1 \input texinfo @c -*-texinfo-*-
2 @comment ========================================================
3 @comment %**start of header
4 @setfilename autoconf.info
9 @setcontentsaftertitlepage
13 @c @ovar(ARG, DEFAULT)
14 @c -------------------
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{]}
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{]}
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 an Autoconf macro index that @defmac doesn't write to.
57 @c Define an Autotest macro index that @defmac doesn't write to.
59 @c Define an M4sugar macro index that @defmac doesn't write to.
61 @c Define an index for *foreign* programs: `mv' etc. Used for the
62 @c portability sections and so on.
67 @c Shall we factor AC_ out of the Autoconf macro index etc.?
74 @c Registering an AC_\MACRO\.
81 @ifclear shortindexflag
89 @c Registering an AH_\MACRO\.
97 @c Registering an AS_\MACRO\.
104 @ifclear shortindexflag
105 @macro asindex{macro}
112 @c Registering an AT_\MACRO\.
113 @ifset shortindexflag
114 @macro atindex{macro}
119 @ifclear shortindexflag
120 @macro atindex{macro}
127 @c Registering an AU_\MACRO\.
128 @macro auindex{macro}
135 @c Indexing a header.
136 @macro hdrindex{macro}
137 @prindex @file{\macro\}
143 @c Registering an m4_\MACRO\.
144 @ifset shortindexflag
145 @macro msindex{macro}
150 @ifclear shortindexflag
151 @macro msindex{macro}
157 @c Define an index for functions: `alloca' etc. Used for the
158 @c portability sections and so on. We can't use `fn' (aka `fnindex),
159 @c since `@defmac' goes into it => we'd get all the macros too.
161 @c FIXME: Aaarg! It seems there are too many indices for TeX :(
163 @c ! No room for a new @write .
164 @c l.112 @defcodeindex fu
166 @c so don't define yet another one :( Just put some tags before each
167 @c @prindex which is actually a @funindex.
172 @c @c Put the programs and functions into their own index.
173 @c @syncodeindex fu pr
175 @comment %**end of header
176 @comment ========================================================
180 This manual is for @acronym{GNU} Autoconf
181 (version @value{VERSION}, @value{UPDATED}),
182 a package for creating scripts to configure source code packages using
183 templates and an M4 macro package.
185 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
186 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
189 Permission is granted to copy, distribute and/or modify this document
190 under the terms of the @acronym{GNU} Free Documentation License,
191 Version 1.2 or any later version published by the Free Software
192 Foundation; with no Invariant Sections, with the Front-Cover texts
193 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
194 (a) below. A copy of the license is included in the section entitled
195 ``@acronym{GNU} Free Documentation License.''
197 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
198 modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
199 published by the Free Software Foundation raise funds for
200 @acronym{GNU} development.''
206 @dircategory Software development
208 * Autoconf: (autoconf). Create source code configuration scripts.
211 @dircategory Individual utilities
213 * autoscan: (autoconf)autoscan Invocation.
214 Semi-automatic @file{configure.ac} writing
215 * ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
216 * autoconf: (autoconf)autoconf Invocation.
217 How to create configuration scripts
218 * autoreconf: (autoconf)autoreconf Invocation.
219 Remaking multiple @command{configure} scripts
220 * autoheader: (autoconf)autoheader Invocation.
221 How to create configuration templates
222 * autom4te: (autoconf)autom4te Invocation.
223 The Autoconf executables backbone
224 * configure: (autoconf)configure Invocation. Configuring a package.
225 * autoupdate: (autoconf)autoupdate Invocation.
226 Automatic update of @file{configure.ac}
227 * config.status: (autoconf)config.status Invocation. Recreating configurations.
228 * testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
233 @subtitle Creating Automatic Configuration Scripts
234 @subtitle for version @value{VERSION}, @value{UPDATED}
235 @author David MacKenzie
237 @author Akim Demaille
239 @vskip 0pt plus 1filll
252 @c The master menu, created with texinfo-master-menu, goes here.
255 * Introduction:: Autoconf's purpose, strengths, and weaknesses
256 * The GNU Build System:: A set of tools for portable software packages
257 * Making configure Scripts:: How to organize and produce Autoconf scripts
258 * Setup:: Initialization and output
259 * Existing Tests:: Macros that check for particular features
260 * Writing Tests:: How to write new feature checks
261 * Results:: What to do with results from feature checks
262 * Programming in M4:: Layers on top of which Autoconf is written
263 * Writing Autoconf Macros:: Adding new macros to Autoconf
264 * Portable Shell:: Shell script portability pitfalls
265 * Portable Make:: Makefile portability pitfalls
266 * Portable C and C++:: C and C++ portability pitfalls
267 * Manual Configuration:: Selecting features that can't be guessed
268 * Site Configuration:: Local defaults for @command{configure}
269 * Running configure Scripts:: How to use the Autoconf output
270 * config.status Invocation:: Recreating a configuration
271 * Obsolete Constructs:: Kept for backward compatibility
272 * Using Autotest:: Creating portable test suites
273 * FAQ:: Frequent Autoconf Questions, with answers
274 * History:: History of Autoconf
275 * Copying This Manual:: How to make copies of this manual
276 * Indices:: Indices of symbols, concepts, etc.
279 --- The Detailed Node Listing ---
281 The @acronym{GNU} Build System
283 * Automake:: Escaping makefile hell
284 * Gnulib:: The @acronym{GNU} portability library
285 * Libtool:: Building libraries portably
286 * Pointers:: More info on the @acronym{GNU} build system
288 Making @command{configure} Scripts
290 * Writing Autoconf Input:: What to put in an Autoconf input file
291 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
292 * ifnames Invocation:: Listing the conditionals in source code
293 * autoconf Invocation:: How to create configuration scripts
294 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
296 Writing @file{configure.ac}
298 * Shell Script Compiler:: Autoconf as solution of a problem
299 * Autoconf Language:: Programming in Autoconf
300 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
302 Initialization and Output Files
304 * Initializing configure:: Option processing etc.
305 * Notices:: Copyright, version numbers in @command{configure}
306 * Input:: Where Autoconf should find files
307 * Output:: Outputting results from the configuration
308 * Configuration Actions:: Preparing the output based on results
309 * Configuration Files:: Creating output files
310 * Makefile Substitutions:: Using output variables in makefiles
311 * Configuration Headers:: Creating a configuration header file
312 * Configuration Commands:: Running arbitrary instantiation commands
313 * Configuration Links:: Links depending on the configuration
314 * Subdirectories:: Configuring independent packages together
315 * Default Prefix:: Changing the default installation prefix
317 Substitutions in Makefiles
319 * Preset Output Variables:: Output variables that are always set
320 * Installation Directory Variables:: Other preset output variables
321 * Changed Directory Variables:: Warnings about @file{datarootdir}
322 * Build Directories:: Supporting multiple concurrent compiles
323 * Automatic Remaking:: Makefile rules for configuring
325 Configuration Header Files
327 * Header Templates:: Input for the configuration headers
328 * autoheader Invocation:: How to create configuration templates
329 * Autoheader Macros:: How to specify CPP templates
333 * Common Behavior:: Macros' standard schemes
334 * Alternative Programs:: Selecting between alternative programs
335 * Files:: Checking for the existence of files
336 * Libraries:: Library archives that might be missing
337 * Library Functions:: C library functions that might be missing
338 * Header Files:: Header files that might be missing
339 * Declarations:: Declarations that may be missing
340 * Structures:: Structures or members that might be missing
341 * Types:: Types that might be missing
342 * Compilers and Preprocessors:: Checking for compiling programs
343 * System Services:: Operating system services
344 * Posix Variants:: Special kludges for specific Posix variants
345 * Erlang Libraries:: Checking for the existence of Erlang libraries
349 * Standard Symbols:: Symbols defined by the macros
350 * Default Includes:: Includes used by the generic macros
354 * Particular Programs:: Special handling to find certain programs
355 * Generic Programs:: How to find other programs
359 * Function Portability:: Pitfalls with usual functions
360 * Particular Functions:: Special handling to find certain functions
361 * Generic Functions:: How to find other functions
365 * Header Portability:: Collected knowledge on common headers
366 * Particular Headers:: Special handling to find certain headers
367 * Generic Headers:: How to find other headers
371 * Particular Declarations:: Macros to check for certain declarations
372 * Generic Declarations:: How to find other declarations
376 * Particular Structures:: Macros to check for certain structure members
377 * Generic Structures:: How to find other structure members
381 * Particular Types:: Special handling to find certain types
382 * Generic Types:: How to find other types
384 Compilers and Preprocessors
386 * Specific Compiler Characteristics:: Some portability issues
387 * Generic Compiler Characteristics:: Language independent tests and features
388 * C Compiler:: Checking its characteristics
389 * C++ Compiler:: Likewise
390 * Objective C Compiler:: Likewise
391 * Erlang Compiler and Interpreter:: Likewise
392 * Fortran Compiler:: Likewise
396 * Language Choice:: Selecting which language to use for testing
397 * Writing Test Programs:: Forging source files for compilers
398 * Running the Preprocessor:: Detecting preprocessor symbols
399 * Running the Compiler:: Detecting language or header features
400 * Running the Linker:: Detecting library features
401 * Runtime:: Testing for runtime features
402 * Systemology:: A zoology of operating systems
403 * Multiple Cases:: Tests for several possible values
405 Writing Test Programs
407 * Guidelines:: General rules for writing test programs
408 * Test Functions:: Avoiding pitfalls in test programs
409 * Generating Sources:: Source program boilerplate
413 * Defining Symbols:: Defining C preprocessor symbols
414 * Setting Output Variables:: Replacing variables in output files
415 * Special Chars in Variables:: Characters to beware of in variables
416 * Caching Results:: Speeding up subsequent @command{configure} runs
417 * Printing Messages:: Notifying @command{configure} users
421 * Cache Variable Names:: Shell variables used in caches
422 * Cache Files:: Files @command{configure} uses for caching
423 * Cache Checkpointing:: Loading and saving the cache file
427 * M4 Quotation:: Protecting macros from unwanted expansion
428 * Using autom4te:: The Autoconf executables backbone
429 * Programming in M4sugar:: Convenient pure M4 macros
430 * Programming in M4sh:: Common shell Constructs
431 * File Descriptor Macros:: File descriptor macros for input and output
435 * Active Characters:: Characters that change the behavior of M4
436 * One Macro Call:: Quotation and one macro call
437 * Quotation and Nested Macros:: Macros calling macros
438 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
439 * Quadrigraphs:: Another way to escape special characters
440 * Quotation Rule Of Thumb:: One parenthesis, one quote
442 Using @command{autom4te}
444 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
445 * Customizing autom4te:: Customizing the Autoconf package
447 Programming in M4sugar
449 * Redefined M4 Macros:: M4 builtins changed in M4sugar
450 * Looping constructs:: Iteration in M4
451 * Evaluation Macros:: More quotation and evaluation control
452 * Text processing Macros:: String manipulation in M4
453 * Forbidden Patterns:: Catching unexpanded macros
455 Writing Autoconf Macros
457 * Macro Definitions:: Basic format of an Autoconf macro
458 * Macro Names:: What to call your new macros
459 * Reporting Messages:: Notifying @command{autoconf} users
460 * Dependencies Between Macros:: What to do when macros depend on other macros
461 * Obsoleting Macros:: Warning about old ways of doing things
462 * Coding Style:: Writing Autoconf macros @`a la Autoconf
464 Dependencies Between Macros
466 * Prerequisite Macros:: Ensuring required information
467 * Suggested Ordering:: Warning about possible ordering problems
468 * One-Shot Macros:: Ensuring a macro is called only once
470 Portable Shell Programming
472 * Shellology:: A zoology of shells
473 * Here-Documents:: Quirks and tricks
474 * File Descriptors:: FDs and redirections
475 * File System Conventions:: File names
476 * Shell Substitutions:: Variable and command expansions
477 * Assignments:: Varying side effects of assignments
478 * Parentheses:: Parentheses in shell scripts
479 * Slashes:: Slashes in shell scripts
480 * Special Shell Variables:: Variables you should not change
481 * Limitations of Builtins:: Portable use of not so portable /bin/sh
482 * Limitations of Usual Tools:: Portable use of portable tools
484 Portable Make Programming
486 * $< in Ordinary Make Rules:: $< in ordinary rules
487 * Failure in Make Rules:: Failing portably in rules
488 * Special Chars in Names:: Special Characters in Macro Names
489 * Backslash-Newline-Newline:: Empty last lines in macro definitions
490 * Backslash-Newline Comments:: Spanning comments across line boundaries
491 * Long Lines in Makefiles:: Line length limitations
492 * Macros and Submakes:: @code{make macro=value} and submakes
493 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
494 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
495 * Comments in Make Rules:: Other problems with Make comments
496 * obj/ and Make:: Don't name a subdirectory @file{obj}
497 * make -k Status:: Exit status of @samp{make -k}
498 * VPATH and Make:: @code{VPATH} woes
499 * Single Suffix Rules:: Single suffix rules and separated dependencies
500 * Timestamps and Make:: Subsecond timestamp resolution
502 @code{VPATH} and Make
504 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
505 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
506 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
507 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
508 * Make Target Lookup:: More details about @code{VPATH} lookup
510 Portable C and C++ Programming
512 * Varieties of Unportability:: How to make your programs unportable
513 * Integer Overflow:: When integers get too large
514 * Null Pointers:: Properties of null pointers
515 * Buffer Overruns:: Subscript errors and the like
516 * Volatile Objects:: @code{volatile} and signals
517 * Floating Point Portability:: Portable floating-point arithmetic
518 * Exiting Portably:: Exiting and the exit status
522 * Specifying Names:: Specifying the system type
523 * Canonicalizing:: Getting the canonical system type
524 * Using System Type:: What to do with the system type
528 * Help Formatting:: Customizing @samp{configure --help}
529 * External Software:: Working with other optional software
530 * Package Options:: Selecting optional features
531 * Pretty Help Strings:: Formatting help string
532 * Option Checking:: Controlling checking of @command{configure} options
533 * Site Details:: Configuring site details
534 * Transforming Names:: Changing program names when installing
535 * Site Defaults:: Giving @command{configure} local defaults
537 Transforming Program Names When Installing
539 * Transformation Options:: @command{configure} options to transform names
540 * Transformation Examples:: Sample uses of transforming names
541 * Transformation Rules:: Makefile uses of transforming names
543 Running @command{configure} Scripts
545 * Basic Installation:: Instructions for typical cases
546 * Compilers and Options:: Selecting compilers and optimization
547 * Multiple Architectures:: Compiling for multiple architectures at once
548 * Installation Names:: Installing in different directories
549 * Optional Features:: Selecting optional features
550 * System Type:: Specifying the system type
551 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
552 * Defining Variables:: Specifying the compiler etc.
553 * configure Invocation:: Changing how @command{configure} runs
557 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
558 * acconfig Header:: Additional entries in @file{config.h.in}
559 * autoupdate Invocation:: Automatic update of @file{configure.ac}
560 * Obsolete Macros:: Backward compatibility macros
561 * Autoconf 1:: Tips for upgrading your files
562 * Autoconf 2.13:: Some fresher tips
564 Upgrading From Version 1
566 * Changed File Names:: Files you might rename
567 * Changed Makefiles:: New things to put in @file{Makefile.in}
568 * Changed Macros:: Macro calls you might replace
569 * Changed Results:: Changes in how to check test results
570 * Changed Macro Writing:: Better ways to write your own macros
572 Upgrading From Version 2.13
574 * Changed Quotation:: Broken code which used to work
575 * New Macros:: Interaction with foreign macros
576 * Hosts and Cross-Compilation:: Bugward compatibility kludges
577 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
578 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
580 Generating Test Suites with Autotest
582 * Using an Autotest Test Suite:: Autotest and the user
583 * Writing Testsuites:: Autotest macros
584 * testsuite Invocation:: Running @command{testsuite} scripts
585 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
587 Using an Autotest Test Suite
589 * testsuite Scripts:: The concepts of Autotest
590 * Autotest Logs:: Their contents
592 Frequent Autoconf Questions, with answers
594 * Distributing:: Distributing @command{configure} scripts
595 * Why GNU M4:: Why not use the standard M4?
596 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
597 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
598 * Defining Directories:: Passing @code{datadir} to program
599 * Autom4te Cache:: What is it? Can I remove it?
600 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
604 * Genesis:: Prehistory and naming of @command{configure}
605 * Exodus:: The plagues of M4 and Perl
606 * Leviticus:: The priestly code of portability arrives
607 * Numbers:: Growth and contributors
608 * Deuteronomy:: Approaching the promises of easy configuration
612 * GNU Free Documentation License:: License for copying this manual
616 * Environment Variable Index:: Index of environment variables used
617 * Output Variable Index:: Index of variables set in output files
618 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
619 * Autoconf Macro Index:: Index of Autoconf macros
620 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
621 * Autotest Macro Index:: Index of Autotest macros
622 * Program & Function Index:: Index of those with portability problems
623 * Concept Index:: General index
628 @c ============================================================= Introduction.
631 @chapter Introduction
635 A physicist, an engineer, and a computer scientist were discussing the
636 nature of God. ``Surely a Physicist,'' said the physicist, ``because
637 early in the Creation, God made Light; and you know, Maxwell's
638 equations, the dual nature of electromagnetic waves, the relativistic
639 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
640 before making Light, God split the Chaos into Land and Water; it takes a
641 hell of an engineer to handle that big amount of mud, and orderly
642 separation of solids from liquids@dots{}'' The computer scientist
643 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
647 @c (via Franc,ois Pinard)
649 Autoconf is a tool for producing shell scripts that automatically
650 configure software source code packages to adapt to many kinds of
651 Posix-like systems. The configuration scripts produced by Autoconf
652 are independent of Autoconf when they are run, so their users do not
653 need to have Autoconf.
655 The configuration scripts produced by Autoconf require no manual user
656 intervention when run; they do not normally even need an argument
657 specifying the system type. Instead, they individually test for the
658 presence of each feature that the software package they are for might need.
659 (Before each check, they print a one-line message stating what they are
660 checking for, so the user doesn't get too bored while waiting for the
661 script to finish.) As a result, they deal well with systems that are
662 hybrids or customized from the more common Posix variants. There is
663 no need to maintain files that list the features supported by each
664 release of each variant of Posix.
666 For each software package that Autoconf is used with, it creates a
667 configuration script from a template file that lists the system features
668 that the package needs or can use. After the shell code to recognize
669 and respond to a system feature has been written, Autoconf allows it to
670 be shared by many software packages that can use (or need) that feature.
671 If it later turns out that the shell code needs adjustment for some
672 reason, it needs to be changed in only one place; all of the
673 configuration scripts can be regenerated automatically to take advantage
676 The Metaconfig package is similar in purpose to Autoconf, but the
677 scripts it produces require manual user intervention, which is quite
678 inconvenient when configuring large source trees. Unlike Metaconfig
679 scripts, Autoconf scripts can support cross-compiling, if some care is
680 taken in writing them.
682 Autoconf does not solve all problems related to making portable
683 software packages---for a more complete solution, it should be used in
684 concert with other @acronym{GNU} build tools like Automake and
685 Libtool. These other tools take on jobs like the creation of a
686 portable, recursive makefile with all of the standard targets,
687 linking of shared libraries, and so on. @xref{The GNU Build System},
688 for more information.
690 Autoconf imposes some restrictions on the names of macros used with
691 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
693 Autoconf requires @acronym{GNU} M4 in order to generate the scripts. It uses
694 features that some versions of M4, including @acronym{GNU} M4 1.3,
695 do not have. You should use version 1.4.7 or later of @acronym{GNU} M4.
697 @xref{Autoconf 1}, for information about upgrading from version 1.
698 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
699 for answers to some common questions about Autoconf.
701 See the @uref{http://www.gnu.org/software/autoconf/,
702 Autoconf web page} for up-to-date information, details on the mailing
703 lists, pointers to a list of known bugs, etc.
705 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
706 list}. Past suggestions are
707 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
709 Mail bug reports to @email{bug-autoconf@@gnu.org, the
710 Autoconf Bugs mailing list}. Past bug reports are
711 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
713 If possible, first check that your bug is
714 not already solved in current development versions, and that it has not
715 been reported yet. Be sure to include all the needed information and a
716 short @file{configure.ac} that demonstrates the problem.
718 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
719 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
720 Summary} for details. Patches relative to the
721 current @acronym{CVS} version can be sent for review to the
722 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
724 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
726 Because of its mission, the Autoconf package itself
727 includes only a set of often-used
728 macros that have already demonstrated their usefulness. Nevertheless,
729 if you wish to share your macros, or find existing ones, see the
730 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
731 Archive}, which is kindly run by @email{simons@@cryp.to,
735 @c ================================================= The GNU Build System
737 @node The GNU Build System
738 @chapter The @acronym{GNU} Build System
739 @cindex @acronym{GNU} build system
741 Autoconf solves an important problem---reliable discovery of
742 system-specific build and runtime information---but this is only one
743 piece of the puzzle for the development of portable software. To this
744 end, the @acronym{GNU} project has developed a suite of integrated
745 utilities to finish the job Autoconf started: the @acronym{GNU} build
746 system, whose most important components are Autoconf, Automake, and
747 Libtool. In this chapter, we introduce you to those tools, point you
748 to sources of more information, and try to convince you to use the
749 entire @acronym{GNU} build system for your software.
752 * Automake:: Escaping makefile hell
753 * Gnulib:: The @acronym{GNU} portability library
754 * Libtool:: Building libraries portably
755 * Pointers:: More info on the @acronym{GNU} build system
761 The ubiquity of @command{make} means that a makefile is almost the
762 only viable way to distribute automatic build rules for software, but
763 one quickly runs into its numerous limitations. Its lack of
764 support for automatic dependency tracking, recursive builds in
765 subdirectories, reliable timestamps (e.g., for network file systems), and
766 so on, mean that developers must painfully (and often incorrectly)
767 reinvent the wheel for each project. Portability is non-trivial, thanks
768 to the quirks of @command{make} on many systems. On top of all this is the
769 manual labor required to implement the many standard targets that users
770 have come to expect (@code{make install}, @code{make distclean},
771 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
772 you also have to insert repetitive code in your @code{Makefile.in} to
773 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
774 provided by @command{configure}. Into this mess steps @dfn{Automake}.
777 Automake allows you to specify your build needs in a @code{Makefile.am}
778 file with a vastly simpler and more powerful syntax than that of a plain
779 makefile, and then generates a portable @code{Makefile.in} for
780 use with Autoconf. For example, the @code{Makefile.am} to build and
781 install a simple ``Hello world'' program might look like:
785 hello_SOURCES = hello.c
789 The resulting @code{Makefile.in} (~400 lines) automatically supports all
790 the standard targets, the substitutions provided by Autoconf, automatic
791 dependency tracking, @code{VPATH} building, and so on. @command{make}
792 builds the @code{hello} program, and @code{make install} installs it
793 in @file{/usr/local/bin} (or whatever prefix was given to
794 @command{configure}, if not @file{/usr/local}).
796 The benefits of Automake increase for larger packages (especially ones
797 with subdirectories), but even for small programs the added convenience
798 and portability can be substantial. And that's not all@enddots{}
803 @acronym{GNU} software has a well-deserved reputation for running on
804 many different types of systems. While our primary goal is to write
805 software for the @acronym{GNU} system, many users and developers have
806 been introduced to us through the systems that they were already using.
809 Gnulib is a central location for common @acronym{GNU} code, intended to
810 be shared among free software packages. Its components are typically
811 shared at the source level, rather than being a library that gets built,
812 installed, and linked against. The idea is to copy files from Gnulib
813 into your own source tree. There is no distribution tarball; developers
814 should just grab source modules from the repository. The source files
815 are available online, under various licenses, mostly @acronym{GNU}
816 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
818 Gnulib modules typically contain C source code along with Autoconf
819 macros used to configure the source code. For example, the Gnulib
820 @code{stdbool} module implements a @file{stdbool.h} header that nearly
821 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
822 This module contains a source file for the replacement header, along
823 with an Autoconf macro that arranges to use the replacement header on
824 old-fashioned systems.
829 Often, one wants to build not only programs, but libraries, so that
830 other programs can benefit from the fruits of your labor. Ideally, one
831 would like to produce @emph{shared} (dynamically linked) libraries,
832 which can be used by multiple programs without duplication on disk or in
833 memory and can be updated independently of the linked programs.
834 Producing shared libraries portably, however, is the stuff of
835 nightmares---each system has its own incompatible tools, compiler flags,
836 and magic incantations. Fortunately, @acronym{GNU} provides a solution:
840 Libtool handles all the requirements of building shared libraries for
841 you, and at this time seems to be the @emph{only} way to do so with any
842 portability. It also handles many other headaches, such as: the
843 interaction of Make rules with the variable suffixes of
844 shared libraries, linking reliably with shared libraries before they are
845 installed by the superuser, and supplying a consistent versioning system
846 (so that different versions of a library can be installed or upgraded
847 without breaking binary compatibility). Although Libtool, like
848 Autoconf, can be used without Automake, it is most simply utilized in
849 conjunction with Automake---there, Libtool is used automatically
850 whenever shared libraries are needed, and you need not know its syntax.
855 Developers who are used to the simplicity of @command{make} for small
856 projects on a single system might be daunted at the prospect of
857 learning to use Automake and Autoconf. As your software is
858 distributed to more and more users, however, you otherwise
859 quickly find yourself putting lots of effort into reinventing the
860 services that the @acronym{GNU} build tools provide, and making the
861 same mistakes that they once made and overcame. (Besides, since
862 you're already learning Autoconf, Automake is a piece of cake.)
864 There are a number of places that you can go to for more information on
865 the @acronym{GNU} build tools.
872 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
873 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
874 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
875 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
877 @item Automake Manual
879 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
880 information on Automake.
884 The book @cite{@acronym{GNU} Autoconf, Automake and
885 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
886 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
887 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
888 build environment. You can also find
889 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
893 @c ================================================= Making configure Scripts.
895 @node Making configure Scripts
896 @chapter Making @command{configure} Scripts
897 @cindex @file{aclocal.m4}
898 @cindex @command{configure}
900 The configuration scripts that Autoconf produces are by convention
901 called @command{configure}. When run, @command{configure} creates several
902 files, replacing configuration parameters in them with appropriate
903 values. The files that @command{configure} creates are:
907 one or more @file{Makefile} files, usually one in each subdirectory of the
908 package (@pxref{Makefile Substitutions});
911 optionally, a C header file, the name of which is configurable,
912 containing @code{#define} directives (@pxref{Configuration Headers});
915 a shell script called @file{config.status} that, when run, recreates
916 the files listed above (@pxref{config.status Invocation});
919 an optional shell script normally called @file{config.cache}
920 (created when using @samp{configure --config-cache}) that
921 saves the results of running many of the tests (@pxref{Cache Files});
924 a file called @file{config.log} containing any messages produced by
925 compilers, to help debugging if @command{configure} makes a mistake.
928 @cindex @file{configure.in}
929 @cindex @file{configure.ac}
930 To create a @command{configure} script with Autoconf, you need to write an
931 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
932 @command{autoconf} on it. If you write your own feature tests to
933 supplement those that come with Autoconf, you might also write files
934 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
935 file to contain @code{#define} directives, you might also run
936 @command{autoheader}, and you can distribute the generated file
937 @file{config.h.in} with the package.
939 Here is a diagram showing how the files that can be used in
940 configuration are produced. Programs that are executed are suffixed by
941 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
942 @command{autoconf} and @command{autoheader} also read the installed Autoconf
943 macro files (by reading @file{autoconf.m4}).
946 Files used in preparing a software package for distribution:
948 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
952 | .------> autoconf* -----> configure
954 | `-----> [autoheader*] --> [config.h.in]
958 Makefile.in -------------------------------> Makefile.in
962 Files used in configuring a software package:
965 .-------------> [config.cache]
966 configure* ------------+-------------> config.log
968 [config.h.in] -. v .-> [config.h] -.
969 +--> config.status* -+ +--> make*
970 Makefile.in ---' `-> Makefile ---'
975 * Writing Autoconf Input:: What to put in an Autoconf input file
976 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
977 * ifnames Invocation:: Listing the conditionals in source code
978 * autoconf Invocation:: How to create configuration scripts
979 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
982 @node Writing Autoconf Input
983 @section Writing @file{configure.ac}
985 To produce a @command{configure} script for a software package, create a
986 file called @file{configure.ac} that contains invocations of the
987 Autoconf macros that test the system features your package needs or can
988 use. Autoconf macros already exist to check for many features; see
989 @ref{Existing Tests}, for their descriptions. For most other features,
990 you can use Autoconf template macros to produce custom checks; see
991 @ref{Writing Tests}, for information about them. For especially tricky
992 or specialized features, @file{configure.ac} might need to contain some
993 hand-crafted shell commands; see @ref{Portable Shell}. The
994 @command{autoscan} program can give you a good start in writing
995 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
997 Previous versions of Autoconf promoted the name @file{configure.in},
998 which is somewhat ambiguous (the tool needed to process this file is not
999 described by its extension), and introduces a slight confusion with
1000 @file{config.h.in} and so on (for which @samp{.in} means ``to be
1001 processed by @command{configure}''). Using @file{configure.ac} is now
1005 * Shell Script Compiler:: Autoconf as solution of a problem
1006 * Autoconf Language:: Programming in Autoconf
1007 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
1010 @node Shell Script Compiler
1011 @subsection A Shell Script Compiler
1013 Just as for any other computer language, in order to properly program
1014 @file{configure.ac} in Autoconf you must understand @emph{what} problem
1015 the language tries to address and @emph{how} it does so.
1017 The problem Autoconf addresses is that the world is a mess. After all,
1018 you are using Autoconf in order to have your package compile easily on
1019 all sorts of different systems, some of them being extremely hostile.
1020 Autoconf itself bears the price for these differences: @command{configure}
1021 must run on all those systems, and thus @command{configure} must limit itself
1022 to their lowest common denominator of features.
1024 Naturally, you might then think of shell scripts; who needs
1025 @command{autoconf}? A set of properly written shell functions is enough to
1026 make it easy to write @command{configure} scripts by hand. Sigh!
1027 Unfortunately, shell functions do not belong to the least common
1028 denominator; therefore, where you would like to define a function and
1029 use it ten times, you would instead need to copy its body ten times.
1031 So, what is really needed is some kind of compiler, @command{autoconf},
1032 that takes an Autoconf program, @file{configure.ac}, and transforms it
1033 into a portable shell script, @command{configure}.
1035 How does @command{autoconf} perform this task?
1037 There are two obvious possibilities: creating a brand new language or
1038 extending an existing one. The former option is attractive: all
1039 sorts of optimizations could easily be implemented in the compiler and
1040 many rigorous checks could be performed on the Autoconf program
1041 (e.g., rejecting any non-portable construct). Alternatively, you can
1042 extend an existing language, such as the @code{sh} (Bourne shell)
1045 Autoconf does the latter: it is a layer on top of @code{sh}. It was
1046 therefore most convenient to implement @command{autoconf} as a macro
1047 expander: a program that repeatedly performs @dfn{macro expansions} on
1048 text input, replacing macro calls with macro bodies and producing a pure
1049 @code{sh} script in the end. Instead of implementing a dedicated
1050 Autoconf macro expander, it is natural to use an existing
1051 general-purpose macro language, such as M4, and implement the extensions
1052 as a set of M4 macros.
1055 @node Autoconf Language
1056 @subsection The Autoconf Language
1059 The Autoconf language differs from many other computer
1060 languages because it treats actual code the same as plain text. Whereas
1061 in C, for instance, data and instructions have different syntactic
1062 status, in Autoconf their status is rigorously the same. Therefore, we
1063 need a means to distinguish literal strings from text to be expanded:
1066 When calling macros that take arguments, there must not be any white
1067 space between the macro name and the open parenthesis. Arguments should
1068 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1069 separated by commas. Any leading blanks or newlines in arguments are ignored,
1070 unless they are quoted. You should always quote an argument that
1071 might contain a macro name, comma, parenthesis, or a leading blank or
1072 newline. This rule applies recursively for every macro
1073 call, including macros called from other macros.
1078 AC_CHECK_HEADER([stdio.h],
1079 [AC_DEFINE([HAVE_STDIO_H], [1],
1080 [Define to 1 if you have <stdio.h>.])],
1081 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1085 is quoted properly. You may safely simplify its quotation to:
1088 AC_CHECK_HEADER([stdio.h],
1089 [AC_DEFINE([HAVE_STDIO_H], 1,
1090 [Define to 1 if you have <stdio.h>.])],
1091 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1095 because @samp{1} cannot contain a macro call. Here, the argument of
1096 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1097 interpreted as an argument separator. Also, the second and third arguments
1098 of @samp{AC_CHECK_HEADER} must be quoted, since they contain
1099 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1100 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1101 if you unwisely defined a macro with a name like @samp{Define} or
1102 @samp{stdio} then they would need quoting. Cautious Autoconf users
1103 would keep the quotes, but many Autoconf users find such precautions
1104 annoying, and would rewrite the example as follows:
1107 AC_CHECK_HEADER(stdio.h,
1108 [AC_DEFINE(HAVE_STDIO_H, 1,
1109 [Define to 1 if you have <stdio.h>.])],
1110 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1114 This is safe, so long as you adopt good naming conventions and do not
1115 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1116 @samp{h}. Though it is also safe here to omit the quotes around
1117 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1118 message strings are more likely to inadvertently contain commas.
1120 The following example is wrong and dangerous, as it is underquoted:
1123 AC_CHECK_HEADER(stdio.h,
1124 AC_DEFINE(HAVE_STDIO_H, 1,
1125 Define to 1 if you have <stdio.h>.),
1126 AC_MSG_ERROR([Sorry, can't do anything for you]))
1129 In other cases, you may have to use text that also resembles a macro
1130 call. You must quote that text even when it is not passed as a macro
1134 echo "Hard rock was here! --[AC_DC]"
1141 echo "Hard rock was here! --AC_DC"
1145 When you use the same text in a macro argument, you must therefore have
1146 an extra quotation level (since one is stripped away by the macro
1147 substitution). In general, then, it is a good idea to @emph{use double
1148 quoting for all literal string arguments}:
1151 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1154 You are now able to understand one of the constructs of Autoconf that
1155 has been continually misunderstood@dots{} The rule of thumb is that
1156 @emph{whenever you expect macro expansion, expect quote expansion};
1157 i.e., expect one level of quotes to be lost. For instance:
1160 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1164 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1165 @samp{char b[10];} and is expanded once, which results in
1166 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1167 address this issue via the M4 @code{changequote} primitive, but do not
1168 use it!) Let's take a closer look: the author meant the first argument
1169 to be understood as a literal, and therefore it must be quoted twice:
1172 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1176 Voil@`a, you actually produce @samp{char b[10];} this time!
1178 On the other hand, descriptions (e.g., the last parameter of
1179 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1180 are subject to line breaking, for example---and should not be double quoted.
1181 Even if these descriptions are short and are not actually broken, double
1182 quoting them yields weird results.
1184 Some macros take optional arguments, which this documentation represents
1185 as @ovar{arg} (not to be confused with the quote characters). You may
1186 just leave them empty, or use @samp{[]} to make the emptiness of the
1187 argument explicit, or you may simply omit the trailing commas. The
1188 three lines below are equivalent:
1191 AC_CHECK_HEADERS([stdio.h], [], [], [])
1192 AC_CHECK_HEADERS([stdio.h],,,)
1193 AC_CHECK_HEADERS([stdio.h])
1196 It is best to put each macro call on its own line in
1197 @file{configure.ac}. Most of the macros don't add extra newlines; they
1198 rely on the newline after the macro call to terminate the commands.
1199 This approach makes the generated @command{configure} script a little
1200 easier to read by not inserting lots of blank lines. It is generally
1201 safe to set shell variables on the same line as a macro call, because
1202 the shell allows assignments without intervening newlines.
1204 You can include comments in @file{configure.ac} files by starting them
1205 with the @samp{#}. For example, it is helpful to begin
1206 @file{configure.ac} files with a line like this:
1209 # Process this file with autoconf to produce a configure script.
1212 @node Autoconf Input Layout
1213 @subsection Standard @file{configure.ac} Layout
1215 The order in which @file{configure.ac} calls the Autoconf macros is not
1216 important, with a few exceptions. Every @file{configure.ac} must
1217 contain a call to @code{AC_INIT} before the checks, and a call to
1218 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1219 rely on other macros having been called first, because they check
1220 previously set values of some variables to decide what to do. These
1221 macros are noted in the individual descriptions (@pxref{Existing
1222 Tests}), and they also warn you when @command{configure} is created if they
1223 are called out of order.
1225 To encourage consistency, here is a suggested order for calling the
1226 Autoconf macros. Generally speaking, the things near the end of this
1227 list are those that could depend on things earlier in it. For example,
1228 library functions could be affected by types and libraries.
1232 Autoconf requirements
1233 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1234 information on the package
1236 checks for libraries
1237 checks for header files
1239 checks for structures
1240 checks for compiler characteristics
1241 checks for library functions
1242 checks for system services
1243 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1249 @node autoscan Invocation
1250 @section Using @command{autoscan} to Create @file{configure.ac}
1251 @cindex @command{autoscan}
1253 The @command{autoscan} program can help you create and/or maintain a
1254 @file{configure.ac} file for a software package. @command{autoscan}
1255 examines source files in the directory tree rooted at a directory given
1256 as a command line argument, or the current directory if none is given.
1257 It searches the source files for common portability problems and creates
1258 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1259 for that package, and checks a possibly existing @file{configure.ac} for
1262 When using @command{autoscan} to create a @file{configure.ac}, you
1263 should manually examine @file{configure.scan} before renaming it to
1264 @file{configure.ac}; it probably needs some adjustments.
1265 Occasionally, @command{autoscan} outputs a macro in the wrong order
1266 relative to another macro, so that @command{autoconf} produces a warning;
1267 you need to move such macros manually. Also, if you want the package to
1268 use a configuration header file, you must add a call to
1269 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1270 also have to change or add some @code{#if} directives to your program in
1271 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1272 information about a program that can help with that job).
1274 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1275 consider adding its suggestions. The file @file{autoscan.log}
1276 contains detailed information on why a macro is requested.
1278 @command{autoscan} uses several data files (installed along with Autoconf)
1279 to determine which macros to output when it finds particular symbols in
1280 a package's source files. These data files all have the same format:
1281 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1282 output if that symbol is encountered. Lines starting with @samp{#} are
1285 @command{autoscan} accepts the following options:
1290 Print a summary of the command line options and exit.
1294 Print the version number of Autoconf and exit.
1298 Print the names of the files it examines and the potentially interesting
1299 symbols it finds in them. This output can be voluminous.
1301 @item --include=@var{dir}
1303 Append @var{dir} to the include path. Multiple invocations accumulate.
1305 @item --prepend-include=@var{dir}
1307 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1310 @node ifnames Invocation
1311 @section Using @command{ifnames} to List Conditionals
1312 @cindex @command{ifnames}
1314 @command{ifnames} can help you write @file{configure.ac} for a software
1315 package. It prints the identifiers that the package already uses in C
1316 preprocessor conditionals. If a package has already been set up to have
1317 some portability, @command{ifnames} can thus help you figure out what its
1318 @command{configure} needs to check for. It may help fill in some gaps in a
1319 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1322 @command{ifnames} scans all of the C source files named on the command line
1323 (or the standard input, if none are given) and writes to the standard
1324 output a sorted list of all the identifiers that appear in those files
1325 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1326 directives. It prints each identifier on a line, followed by a
1327 space-separated list of the files in which that identifier occurs.
1330 @command{ifnames} accepts the following options:
1335 Print a summary of the command line options and exit.
1339 Print the version number of Autoconf and exit.
1342 @node autoconf Invocation
1343 @section Using @command{autoconf} to Create @command{configure}
1344 @cindex @command{autoconf}
1346 To create @command{configure} from @file{configure.ac}, run the
1347 @command{autoconf} program with no arguments. @command{autoconf} processes
1348 @file{configure.ac} with the M4 macro processor, using the
1349 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1350 file instead of @file{configure.ac} and writes the configuration script
1351 to the standard output instead of to @command{configure}. If you give
1352 @command{autoconf} the argument @option{-}, it reads from the standard
1353 input instead of @file{configure.ac} and writes the configuration script
1354 to the standard output.
1356 The Autoconf macros are defined in several files. Some of the files are
1357 distributed with Autoconf; @command{autoconf} reads them first. Then it
1358 looks for the optional file @file{acsite.m4} in the directory that
1359 contains the distributed Autoconf macro files, and for the optional file
1360 @file{aclocal.m4} in the current directory. Those files can contain
1361 your site's or the package's own Autoconf macro definitions
1362 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1363 defined in more than one of the files that @command{autoconf} reads, the
1364 last definition it reads overrides the earlier ones.
1366 @command{autoconf} accepts the following options:
1371 Print a summary of the command line options and exit.
1375 Print the version number of Autoconf and exit.
1379 Report processing steps.
1383 Don't remove the temporary files.
1387 Remake @file{configure} even if newer than its input files.
1389 @item --include=@var{dir}
1391 Append @var{dir} to the include path. Multiple invocations accumulate.
1393 @item --prepend-include=@var{dir}
1395 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1397 @item --output=@var{file}
1398 @itemx -o @var{file}
1399 Save output (script or trace) to @var{file}. The file @option{-} stands
1400 for the standard output.
1402 @item --warnings=@var{category}
1403 @itemx -W @var{category}
1405 Report the warnings related to @var{category} (which can actually be a
1406 comma separated list). @xref{Reporting Messages}, macro
1407 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1412 report all the warnings
1418 treats warnings as errors
1420 @item no-@var{category}
1421 disable warnings falling into @var{category}
1424 Warnings about @samp{syntax} are enabled by default, and the environment
1425 variable @env{WARNINGS}, a comma separated list of categories, is
1426 honored as well. Passing @option{-W @var{category}} actually behaves as if
1427 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If
1428 you want to disable the defaults and @env{WARNINGS}, but (for example)
1429 enable the warnings about obsolete constructs, you would use @option{-W
1433 @cindex Macro invocation stack
1434 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1435 displays a back trace for errors, but not for warnings; if you want
1436 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1439 @item --trace=@var{macro}[:@var{format}]
1440 @itemx -t @var{macro}[:@var{format}]
1441 Do not create the @command{configure} script, but list the calls to
1442 @var{macro} according to the @var{format}. Multiple @option{--trace}
1443 arguments can be used to list several macros. Multiple @option{--trace}
1444 arguments for a single macro are not cumulative; instead, you should
1445 just make @var{format} as long as needed.
1447 The @var{format} is a regular string, with newlines if desired, and
1448 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1449 @ref{autom4te Invocation}, for details on the @var{format}.
1451 @item --initialization
1453 By default, @option{--trace} does not trace the initialization of the
1454 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1455 results in a noticeable speedup, but can be disabled by this option.
1459 It is often necessary to check the content of a @file{configure.ac}
1460 file, but parsing it yourself is extremely fragile and error-prone. It
1461 is suggested that you rely upon @option{--trace} to scan
1462 @file{configure.ac}. For instance, to find the list of variables that
1463 are substituted, use:
1467 $ @kbd{autoconf -t AC_SUBST}
1468 configure.ac:2:AC_SUBST:ECHO_C
1469 configure.ac:2:AC_SUBST:ECHO_N
1470 configure.ac:2:AC_SUBST:ECHO_T
1471 @i{More traces deleted}
1476 The example below highlights the difference between @samp{$@@},
1477 @samp{$*}, and @samp{$%}.
1481 $ @kbd{cat configure.ac}
1482 AC_DEFINE(This, is, [an
1484 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1491 %: This:is:an [example]
1496 The @var{format} gives you a lot of freedom:
1500 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1501 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1502 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1503 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1504 @i{More traces deleted}
1509 A long @var{separator} can be used to improve the readability of complex
1510 structures, and to ease their parsing (for instance when no single
1511 character is suitable as a separator):
1515 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1516 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1517 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1518 AUTOMAKE|:::::|automake|:::::|$missing_dir
1519 @i{More traces deleted}
1523 @node autoreconf Invocation
1524 @section Using @command{autoreconf} to Update @command{configure} Scripts
1525 @cindex @command{autoreconf}
1527 Installing the various components of the @acronym{GNU} Build System can be
1528 tedious: running @command{autopoint} for Gettext, @command{automake} for
1529 @file{Makefile.in} etc.@: in each directory. It may be needed either
1530 because some tools such as @command{automake} have been updated on your
1531 system, or because some of the sources such as @file{configure.ac} have
1532 been updated, or finally, simply in order to install the @acronym{GNU} Build
1533 System in a fresh tree.
1535 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1536 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1537 @command{autopoint} (when appropriate) repeatedly to update the
1538 @acronym{GNU} Build System in the specified directories and their
1539 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1540 those files that are older than their sources.
1542 If you install a new version of some tool, you can make
1543 @command{autoreconf} remake @emph{all} of the files by giving it the
1544 @option{--force} option.
1546 @xref{Automatic Remaking}, for Make rules to automatically
1547 remake @command{configure} scripts when their source files change. That
1548 method handles the timestamps of configuration header templates
1549 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1550 @option{--localdir=@var{dir}}.
1553 @cindex @command{autopoint}
1554 Gettext supplies the @command{autopoint} command to add translation
1555 infrastructure to a source package. If you use @command{autopoint},
1556 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1557 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
1558 Invocation, , Invoking the @code{autopoint} Program, gettext,
1559 @acronym{GNU} @code{gettext} utilities}, for further details.
1562 @command{autoreconf} accepts the following options:
1567 Print a summary of the command line options and exit.
1571 Print the version number of Autoconf and exit.
1574 Print the name of each directory @command{autoreconf} examines and the
1575 commands it runs. If given two or more times, pass @option{--verbose}
1576 to subordinate tools that support it.
1580 Don't remove the temporary files.
1584 Remake even @file{configure} scripts and configuration headers that are
1585 newer than their input files (@file{configure.ac} and, if present,
1590 Install the missing auxiliary files in the package. By default, files
1591 are copied; this can be changed with @option{--symlink}.
1593 If deemed appropriate, this option triggers calls to
1594 @samp{automake --add-missing},
1595 @samp{libtoolize}, @samp{autopoint}, etc.
1597 @item --no-recursive
1598 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1599 macro @code{AC_CONFIG_SUBDIRS}).
1603 When used with @option{--install}, install symbolic links to the missing
1604 auxiliary files instead of copying them.
1608 When the directories were configured, update the configuration by
1609 running @samp{./config.status --recheck && ./config.status}, and then
1612 @item --include=@var{dir}
1614 Append @var{dir} to the include path. Multiple invocations accumulate.
1615 Passed on to @command{autoconf} and @command{autoheader} internally.
1617 @item --prepend-include=@var{dir}
1619 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1620 Passed on to @command{autoconf} and @command{autoheader} internally.
1622 @item --warnings=@var{category}
1623 @itemx -W @var{category}
1625 Report the warnings related to @var{category} (which can actually be a
1626 comma separated list).
1630 related to cross compilation issues.
1633 report the uses of obsolete constructs.
1639 dubious syntactic constructs.
1642 report all the warnings
1648 treats warnings as errors
1650 @item no-@var{category}
1651 disable warnings falling into @var{category}
1654 Warnings about @samp{syntax} are enabled by default, and the environment
1655 variable @env{WARNINGS}, a comma separated list of categories, is
1656 honored as well. Passing @option{-W @var{category}} actually behaves as if
1657 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If
1658 you want to disable the defaults and @env{WARNINGS}, but (for example)
1659 enable the warnings about obsolete constructs, you would use @option{-W
1663 If you want @command{autoreconf} to pass flags that are not listed here
1664 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
1666 @c ========================================= Initialization and Output Files.
1669 @chapter Initialization and Output Files
1671 Autoconf-generated @command{configure} scripts need some information about
1672 how to initialize, such as how to find the package's source files and
1673 about the output files to produce. The following sections describe the
1674 initialization and the creation of output files.
1677 * Initializing configure:: Option processing etc.
1678 * Notices:: Copyright, version numbers in @command{configure}
1679 * Input:: Where Autoconf should find files
1680 * Output:: Outputting results from the configuration
1681 * Configuration Actions:: Preparing the output based on results
1682 * Configuration Files:: Creating output files
1683 * Makefile Substitutions:: Using output variables in makefiles
1684 * Configuration Headers:: Creating a configuration header file
1685 * Configuration Commands:: Running arbitrary instantiation commands
1686 * Configuration Links:: Links depending on the configuration
1687 * Subdirectories:: Configuring independent packages together
1688 * Default Prefix:: Changing the default installation prefix
1691 @node Initializing configure
1692 @section Initializing @command{configure}
1694 Every @command{configure} script must call @code{AC_INIT} before doing
1695 anything else. The only other required macro is @code{AC_OUTPUT}
1698 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1700 Process any command-line arguments and perform various initializations
1703 Set the name of the @var{package} and its @var{version}. These are
1704 typically used in @option{--version} support, including that of
1705 @command{configure}. The optional argument @var{bug-report} should be
1706 the email to which users should send bug reports. The package
1707 @var{tarname} differs from @var{package}: the latter designates the full
1708 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1709 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1710 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1711 other than alphanumerics and underscores are changed to @samp{-}.
1713 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1714 there should not be any shell computation, but they can be computed by
1717 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1718 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1719 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1722 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1723 @acindex{PACKAGE_NAME}
1724 @ovindex PACKAGE_NAME
1725 @cvindex PACKAGE_NAME
1726 Exactly @var{package}.
1728 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1729 @acindex{PACKAGE_TARNAME}
1730 @ovindex PACKAGE_TARNAME
1731 @cvindex PACKAGE_TARNAME
1732 Exactly @var{tarname}.
1734 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1735 @acindex{PACKAGE_VERSION}
1736 @ovindex PACKAGE_VERSION
1737 @cvindex PACKAGE_VERSION
1738 Exactly @var{version}.
1740 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1741 @acindex{PACKAGE_STRING}
1742 @ovindex PACKAGE_STRING
1743 @cvindex PACKAGE_STRING
1744 Exactly @samp{@var{package} @var{version}}.
1746 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1747 @acindex{PACKAGE_BUGREPORT}
1748 @ovindex PACKAGE_BUGREPORT
1749 @cvindex PACKAGE_BUGREPORT
1750 Exactly @var{bug-report}.
1754 If your @command{configure} script does its own option processing, it
1755 should inspect @samp{$@@} or @samp{$*} immediately after calling
1756 @code{AC_INIT}, because other Autoconf macros liberally use the
1757 @command{set} command to process strings, and this has the side effect
1758 of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
1759 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1760 implement your own option processing. @xref{Site Configuration}.
1764 @section Notices in @command{configure}
1765 @cindex Notices in @command{configure}
1767 The following macros manage version numbers for @command{configure}
1768 scripts. Using them is optional.
1770 @c FIXME: AC_PREREQ should not be here
1771 @defmac AC_PREREQ (@var{version})
1774 Ensure that a recent enough version of Autoconf is being used. If the
1775 version of Autoconf being used to create @command{configure} is
1776 earlier than @var{version}, print an error message to the standard
1777 error output and exit with failure (exit status is 63). For example:
1780 AC_PREREQ([@value{VERSION}])
1783 This macro is the only macro that may be used before @code{AC_INIT}, but
1784 for consistency, you are invited not to do so.
1787 @defmac AC_COPYRIGHT (@var{copyright-notice})
1789 @cindex Copyright Notice
1790 State that, in addition to the Free Software Foundation's copyright on
1791 the Autoconf macros, parts of your @command{configure} are covered by the
1792 @var{copyright-notice}.
1794 The @var{copyright-notice} shows up in both the head of
1795 @command{configure} and in @samp{configure --version}.
1799 @defmac AC_REVISION (@var{revision-info})
1802 Copy revision stamp @var{revision-info} into the @command{configure}
1803 script, with any dollar signs or double-quotes removed. This macro lets
1804 you put a revision stamp from @file{configure.ac} into @command{configure}
1805 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1806 @command{configure}. That way, you can determine easily which revision of
1807 @file{configure.ac} a particular @command{configure} corresponds to.
1809 For example, this line in @file{configure.ac}:
1811 @c The asis prevents RCS from changing the example in the manual.
1813 AC_REVISION([$@asis{Revision: 1.30 }$])
1817 produces this in @command{configure}:
1821 # From configure.ac Revision: 1.30
1827 @section Finding @command{configure} Input
1830 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1831 @acindex{CONFIG_SRCDIR}
1832 @var{unique-file-in-source-dir} is some file that is in the package's
1833 source directory; @command{configure} checks for this file's existence to
1834 make sure that the directory that it is told contains the source code in
1835 fact does. Occasionally people accidentally specify the wrong directory
1836 with @option{--srcdir}; this is a safety check. @xref{configure
1837 Invocation}, for more information.
1841 @c FIXME: Remove definitively once --install explained.
1843 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1844 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1845 @c to split the macros in several files. In this case, Autoconf must be
1846 @c told which files to load, and in which order.
1848 @c @defmac AC_INCLUDE (@var{file}@dots{})
1849 @c @acindex{INCLUDE}
1850 @c @c FIXME: There is no longer shell globbing.
1851 @c Read the macro definitions that appear in the listed files. A list of
1852 @c space-separated file names or shell globbing patterns is expected. The
1853 @c files are read in the order they're listed.
1855 @c Because the order of definition of macros is important (only the last
1856 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1857 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1858 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1859 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1860 @c the latter case, non-macro lines from included files may end up in the
1861 @c @file{configure} script, whereas in the former case, they'd be discarded
1862 @c just like any text that appear before @code{AC_INIT}.
1865 Packages that do manual configuration or use the @command{install} program
1866 might need to tell @command{configure} where to find some other shell
1867 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1868 it looks are correct for most cases.
1870 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1871 @acindex{CONFIG_AUX_DIR}
1872 Use the auxiliary build tools (e.g., @file{install-sh},
1873 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1874 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1875 These are auxiliary files used in configuration. @var{dir} can be
1876 either absolute or relative to @file{@var{srcdir}}. The default is
1877 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1878 @file{@var{srcdir}/../..}, whichever is the first that contains
1879 @file{install-sh}. The other files are not checked for, so that using
1880 @code{AC_PROG_INSTALL} does not automatically require distributing the
1881 other auxiliary files. It checks for @file{install.sh} also, but that
1882 name is obsolete because some @code{make} have a rule that creates
1883 @file{install} from it if there is no makefile.
1885 The auxiliary directory is commonly named @file{build-aux}.
1886 If you need portability to @acronym{DOS} variants, do not name the
1887 auxiliary directory @file{aux}. @xref{File System Conventions}.
1890 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1891 @acindex{REQUIRE_AUX_FILE}
1892 Declares that @var{file} is expected in the directory defined above. In
1893 Autoconf proper, this macro does nothing: its sole purpose is to be
1894 traced by third-party tools to produce a list of expected auxiliary
1895 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
1896 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1897 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1900 Similarly, packages that use @command{aclocal} should declare where
1901 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1903 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1904 @acindex{CONFIG_MACRO_DIR}
1905 Specify @var{dir} as the location of additional local Autoconf macros.
1906 This macro is intended for use by future versions of commands like
1907 @command{autoreconf} that trace macro calls. It should be called
1908 directly from @file{configure.ac} so that tools that install macros for
1909 @command{aclocal} can find the macros' declarations.
1914 @section Outputting Files
1915 @cindex Outputting files
1917 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1918 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1919 @file{config.status}, which in turn creates the makefiles and any
1920 other files resulting from configuration. This is the only required
1921 macro besides @code{AC_INIT} (@pxref{Input}).
1925 @cindex Instantiation
1926 Generate @file{config.status} and launch it. Call this macro once, at
1927 the end of @file{configure.ac}.
1929 @file{config.status} performs all the configuration actions: all the
1930 output files (see @ref{Configuration Files}, macro
1931 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1932 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1933 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1934 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1935 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1938 The location of your @code{AC_OUTPUT} invocation is the exact point
1939 where configuration actions are taken: any code afterwards is
1940 executed by @code{configure} once @command{config.status} was run. If
1941 you want to bind actions to @command{config.status} itself
1942 (independently of whether @command{configure} is being run), see
1943 @ref{Configuration Commands, , Running Arbitrary Configuration
1947 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1948 @xref{Obsolete Macros}, for a description of the arguments that
1949 @code{AC_OUTPUT} used to support.
1952 If you run @command{make} in subdirectories, you should run it using the
1953 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1954 @code{MAKE} to the name of the @command{make} program plus any options it
1955 was given. (But many do not include in it the values of any variables
1956 set on the command line, so those are not passed on automatically.)
1957 Some old versions of @command{make} do not set this variable. The
1958 following macro allows you to use it even with those versions.
1960 @defmac AC_PROG_MAKE_SET
1961 @acindex{PROG_MAKE_SET}
1963 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1964 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1965 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1966 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
1970 If you use this macro, place a line like this in each @file{Makefile.in}
1971 that runs @code{MAKE} on other directories:
1979 @node Configuration Actions
1980 @section Performing Configuration Actions
1981 @cindex Configuration actions
1983 @file{configure} is designed so that it appears to do everything itself,
1984 but there is actually a hidden slave: @file{config.status}.
1985 @file{configure} is in charge of examining your system, but it is
1986 @file{config.status} that actually takes the proper actions based on the
1987 results of @file{configure}. The most typical task of
1988 @file{config.status} is to @emph{instantiate} files.
1990 This section describes the common behavior of the four standard
1991 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1992 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
1993 have this prototype:
1995 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1998 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
2002 where the arguments are:
2006 A blank-or-newline-separated list of tags, which are typically the names of
2007 the files to instantiate.
2009 You are encouraged to use literals as @var{tags}. In particular, you
2013 @dots{} && my_foos="$my_foos fooo"
2014 @dots{} && my_foos="$my_foos foooo"
2015 AC_CONFIG_FOOS([$my_foos])
2019 and use this instead:
2022 @dots{} && AC_CONFIG_FOOS([fooo])
2023 @dots{} && AC_CONFIG_FOOS([foooo])
2026 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2027 special @var{tag} values: they may have the form @samp{@var{output}} or
2028 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
2029 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2031 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2032 for example, asks for
2033 the creation of the file @file{Makefile} that contains the expansion of the
2034 output variables in the concatenation of @file{boiler/top.mk} and
2035 @file{boiler/bot.mk}.
2037 The special value @samp{-} might be used to denote the standard output
2038 when used in @var{output}, or the standard input when used in the
2039 @var{inputs}. You most probably don't need to use this in
2040 @file{configure.ac}, but it is convenient when using the command line
2041 interface of @file{./config.status}, see @ref{config.status Invocation},
2044 The @var{inputs} may be absolute or relative file names. In the latter
2045 case they are first looked for in the build tree, and then in the source
2049 Shell commands output literally into @file{config.status}, and
2050 associated with a tag that the user can use to tell @file{config.status}
2051 which the commands to run. The commands are run each time a @var{tag}
2052 request is given to @file{config.status}, typically each time the file
2053 @file{@var{tag}} is created.
2055 The variables set during the execution of @command{configure} are
2056 @emph{not} available here: you first need to set them via the
2057 @var{init-cmds}. Nonetheless the following variables are precomputed:
2061 The name of the top source directory, assuming that the working
2062 directory is the top build directory. This
2063 is what the @command{configure} option @option{--srcdir} sets.
2066 The name of the top source directory, assuming that the working
2067 directory is the current build directory.
2070 @item ac_top_build_prefix
2071 The name of the top build directory, assuming that the working
2072 directory is the current build directory.
2073 It can be empty, or else ends with a slash, so that you may concatenate
2077 The name of the corresponding source directory, assuming that the
2078 working directory is the current build directory.
2082 The @dfn{current} directory refers to the directory (or
2083 pseudo-directory) containing the input part of @var{tags}. For
2087 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2091 with @option{--srcdir=../package} produces the following values:
2094 # Argument of --srcdir
2096 # Reversing deep/dir
2097 ac_top_build_prefix='../../'
2098 # Concatenation of $ac_top_build_prefix and srcdir
2099 ac_top_srcdir='../../../package'
2100 # Concatenation of $ac_top_srcdir and deep/dir
2101 ac_srcdir='../../../package/deep/dir'
2105 independently of @samp{in/in.in}.
2108 Shell commands output @emph{unquoted} near the beginning of
2109 @file{config.status}, and executed each time @file{config.status} runs
2110 (regardless of the tag). Because they are unquoted, for example,
2111 @samp{$var} is output as the value of @code{var}. @var{init-cmds}
2112 is typically used by @file{configure} to give @file{config.status} some
2113 variables it needs to run the @var{commands}.
2115 You should be extremely cautious in your variable names: all the
2116 @var{init-cmds} share the same name space and may overwrite each other
2117 in unpredictable ways. Sorry@enddots{}
2120 All these macros can be called multiple times, with different
2121 @var{tag} values, of course!
2124 @node Configuration Files
2125 @section Creating Configuration Files
2126 @cindex Creating configuration files
2127 @cindex Configuration file creation
2129 Be sure to read the previous section, @ref{Configuration Actions}.
2131 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2132 @acindex{CONFIG_FILES}
2133 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2134 file (by default @file{@var{file}.in}), substituting the output variable
2136 @c Before we used to have this feature, which was later rejected
2137 @c because it complicates the writing of makefiles:
2138 @c If the file would be unchanged, it is left untouched, to preserve
2140 This macro is one of the instantiating macros; see @ref{Configuration
2141 Actions}. @xref{Makefile Substitutions}, for more information on using
2142 output variables. @xref{Setting Output Variables}, for more information
2143 on creating them. This macro creates the directory that the file is in
2144 if it doesn't exist. Usually, makefiles are created this way,
2145 but other files, such as @file{.gdbinit}, can be specified as well.
2147 Typical calls to @code{AC_CONFIG_FILES} look like this:
2150 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2151 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2154 You can override an input file name by appending to @var{file} a
2155 colon-separated list of input files. Examples:
2158 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2159 [lib/Makefile:boiler/lib.mk])
2163 Doing this allows you to keep your file names acceptable to
2164 @acronym{DOS} variants, or
2165 to prepend and/or append boilerplate to the file.
2170 @node Makefile Substitutions
2171 @section Substitutions in Makefiles
2172 @cindex Substitutions in makefiles
2173 @cindex Makefile substitutions
2175 Each subdirectory in a distribution that contains something to be
2176 compiled or installed should come with a file @file{Makefile.in}, from
2177 which @command{configure} creates a file @file{Makefile} in that directory.
2178 To create @file{Makefile}, @command{configure} performs a simple variable
2179 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2180 @file{Makefile.in} with the value that @command{configure} has determined
2181 for that variable. Variables that are substituted into output files in
2182 this way are called @dfn{output variables}. They are ordinary shell
2183 variables that are set in @command{configure}. To make @command{configure}
2184 substitute a particular variable into the output files, the macro
2185 @code{AC_SUBST} must be called with that variable name as an argument.
2186 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2187 left unchanged. @xref{Setting Output Variables}, for more information
2188 on creating output variables with @code{AC_SUBST}.
2190 A software package that uses a @command{configure} script should be
2191 distributed with a file @file{Makefile.in}, but no makefile; that
2192 way, the user has to properly configure the package for the local system
2193 before compiling it.
2195 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2196 @acronym{GNU} Coding Standards}, for more information on what to put in
2200 * Preset Output Variables:: Output variables that are always set
2201 * Installation Directory Variables:: Other preset output variables
2202 * Changed Directory Variables:: Warnings about @file{datarootdir}
2203 * Build Directories:: Supporting multiple concurrent compiles
2204 * Automatic Remaking:: Makefile rules for configuring
2207 @node Preset Output Variables
2208 @subsection Preset Output Variables
2209 @cindex Output variables
2211 Some output variables are preset by the Autoconf macros. Some of the
2212 Autoconf macros set additional output variables, which are mentioned in
2213 the descriptions for those macros. @xref{Output Variable Index}, for a
2214 complete list of output variables. @xref{Installation Directory
2215 Variables}, for the list of the preset ones related to installation
2216 directories. Below are listed the other preset ones. They all are
2217 precious variables (@pxref{Setting Output Variables},
2220 @c Just say no to ASCII sorting! We're humans, not computers.
2221 @c These variables are listed as they would be in a dictionary:
2228 Debugging and optimization options for the C compiler. If it is not set
2229 in the environment when @command{configure} runs, the default value is set
2230 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2231 uses this variable when compiling or linking programs to test for C features.
2233 If a compiler option affects only the behavior of the preprocessor
2234 (e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS}
2235 instead. If it affects only the linker (e.g., @option{-L
2236 @var{directory}}), it should be put into @code{LDFLAGS} instead. If it
2237 affects only the compiler proper, @code{CFLAGS} is the natural home for
2238 it. If an option affects multiple phases of the compiler, though,
2239 matters get tricky. One approach to put such options directly into
2240 @code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
2241 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2245 @defvar configure_input
2246 @ovindex configure_input
2247 A comment saying that the file was generated automatically by
2248 @command{configure} and giving the name of the input file.
2249 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2250 of every makefile it creates. For other files, you should
2251 reference this variable in a comment at the top of each input file. For
2252 example, an input shell script should begin like this:
2256 # @@configure_input@@
2260 The presence of that line also reminds people editing the file that it
2261 needs to be processed by @command{configure} in order to be used.
2266 Preprocessor options for the C, C++, and Objective C preprocessors and
2268 it is not set in the environment when @command{configure} runs, the default
2269 value is empty. @command{configure} uses this variable when preprocessing
2270 or compiling programs to test for C, C++, and Objective C features.
2272 This variable's contents should contain options like @option{-I},
2273 @option{-D}, and @option{-U} that affect only the behavior of the
2274 preprocessor. Please see the explanation of @code{CFLAGS} for what you
2275 can do if an option affects other phases of the compiler as well.
2277 Currently, @command{configure} always links as part of a single
2278 invocation of the compiler that also preprocesses and compiles, so it
2279 uses this variable also when linking programs. However, it is unwise to
2280 depend on this behavior because the @acronym{GNU} coding standards do
2281 not require it and many packages do not use @code{CPPFLAGS} when linking
2284 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2290 Debugging and optimization options for the C++ compiler. It acts like
2291 @code{CFLAGS}, but for C++ instead of C.
2296 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2297 is called, @command{configure} replaces @samp{@@DEFS@@} with
2298 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2299 variable is not defined while @command{configure} is performing its tests,
2300 only when creating the output files. @xref{Setting Output Variables}, for
2301 how to check the results of previous tests.
2310 How does one suppress the trailing newline from @command{echo} for
2311 question-answer message pairs? These variables provide a way:
2314 echo $ECHO_N "And the winner is... $ECHO_C"
2316 echo "$@{ECHO_T@}dead."
2320 Some old and uncommon @command{echo} implementations offer no means to
2321 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2327 Debugging and optimization options for the Erlang compiler. If it is not set
2328 in the environment when @command{configure} runs, the default value is empty.
2329 @command{configure} uses this variable when compiling
2330 programs to test for Erlang features.
2335 Debugging and optimization options for the Fortran compiler. If it
2336 is not set in the environment when @command{configure} runs, the default
2337 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2338 @command{configure} uses this variable when compiling or linking
2339 programs to test for Fortran features.
2344 Debugging and optimization options for the Fortran 77 compiler. If it
2345 is not set in the environment when @command{configure} runs, the default
2346 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2347 @command{configure} uses this variable when compiling or linking
2348 programs to test for Fortran 77 features.
2353 Options for the linker. If it is not set
2354 in the environment when @command{configure} runs, the default value is empty.
2355 @command{configure} uses this variable when linking programs to test for
2356 C, C++, Objective C, and Fortran features.
2358 This variable's contents should contain options like @option{-s} and
2359 @option{-L} that affect only the behavior of the linker. Please see the
2360 explanation of @code{CFLAGS} for what you can do if an option also
2361 affects other phases of the compiler.
2363 Don't use this variable to pass library names
2364 (@option{-l}) to the linker; use @code{LIBS} instead.
2369 @option{-l} options to pass to the linker. The default value is empty,
2370 but some Autoconf macros may prepend extra libraries to this variable if
2371 those libraries are found and provide necessary functions, see
2372 @ref{Libraries}. @command{configure} uses this variable when linking
2373 programs to test for C, C++, and Fortran features.
2378 Debugging and optimization options for the Objective C compiler. It
2379 acts like @code{CFLAGS}, but for Objective C instead of C.
2384 Rigorously equal to @samp{.}. Added for symmetry only.
2387 @defvar abs_builddir
2388 @ovindex abs_builddir
2389 Absolute name of @code{builddir}.
2392 @defvar top_builddir
2393 @ovindex top_builddir
2394 The relative name of the top level of the current build tree. In the
2395 top-level directory, this is the same as @code{builddir}.
2398 @defvar abs_top_builddir
2399 @ovindex abs_top_builddir
2400 Absolute name of @code{top_builddir}.
2405 The name of the directory that contains the source code for
2411 Absolute name of @code{srcdir}.
2416 The name of the top-level source code directory for the
2417 package. In the top-level directory, this is the same as @code{srcdir}.
2420 @defvar abs_top_srcdir
2421 @ovindex abs_top_srcdir
2422 Absolute name of @code{top_srcdir}.
2425 @node Installation Directory Variables
2426 @subsection Installation Directory Variables
2427 @cindex Installation directories
2428 @cindex Directories, installation
2430 The following variables specify the directories for
2431 package installation, see @ref{Directory Variables, , Variables for
2432 Installation Directories, standards, The @acronym{GNU} Coding
2433 Standards}, for more information. See the end of this section for
2434 details on when and how to use these variables.
2438 The directory for installing executables that users run.
2443 The directory for installing idiosyncratic read-only
2444 architecture-independent data.
2448 @ovindex datarootdir
2449 The root of the directory tree for read-only architecture-independent
2455 The directory for installing documentation files (other than Info and
2461 The directory for installing documentation files in DVI format.
2465 @ovindex exec_prefix
2466 The installation prefix for architecture-dependent files. By default
2467 it's the same as @var{prefix}. You should avoid installing anything
2468 directly to @var{exec_prefix}. However, the default value for
2469 directories containing architecture-dependent files should be relative
2470 to @var{exec_prefix}.
2475 The directory for installing HTML documentation.
2480 The directory for installing C header files.
2485 The directory for installing documentation in Info format.
2490 The directory for installing object code libraries.
2495 The directory for installing executables that other programs run.
2500 The directory for installing locale-dependent but
2501 architecture-independent data, such as message catalogs. This directory
2502 usually has a subdirectory per locale.
2505 @defvar localstatedir
2506 @ovindex localstatedir
2507 The directory for installing modifiable single-machine data.
2512 The top-level directory for installing documentation in man format.
2515 @defvar oldincludedir
2516 @ovindex oldincludedir
2517 The directory for installing C header files for non-@acronym{GCC} compilers.
2522 The directory for installing PDF documentation.
2527 The common installation prefix for all files. If @var{exec_prefix}
2528 is defined to a different value, @var{prefix} is used only for
2529 architecture-independent files.
2534 The directory for installing PostScript documentation.
2539 The directory for installing executables that system
2543 @defvar sharedstatedir
2544 @ovindex sharedstatedir
2545 The directory for installing modifiable architecture-independent data.
2550 The directory for installing read-only single-machine data.
2554 Most of these variables have values that rely on @code{prefix} or
2555 @code{exec_prefix}. It is deliberate that the directory output
2556 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2557 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2558 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2560 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2565 she can still specify a different prefix from the one specified to
2566 @command{configure}, in which case, if needed, the package should hard
2567 code dependencies corresponding to the make-specified prefix.
2570 she can specify a different installation location, in which case the
2571 package @emph{must} still depend on the location which was compiled in
2572 (i.e., never recompile when @samp{make install} is run). This is an
2573 extremely important feature, as many people may decide to install all
2574 the files of a package grouped together, and then install links from
2575 the final locations to there.
2578 In order to support these features, it is essential that
2579 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2580 depend upon the current value of @code{prefix}.
2582 A corollary is that you should not use these variables except in
2583 makefiles. For instance, instead of trying to evaluate @code{datadir}
2584 in @file{configure} and hard-coding it in makefiles using
2585 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2587 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2588 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2590 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2591 @code{datadir} and friends in your shell scripts and other files; instead,
2592 let @command{make} manage their replacement. For instance Autoconf
2593 ships templates of its shell scripts ending with @samp{.in}, and uses a
2594 makefile snippet similar to the following to build scripts like
2595 @command{autoheader} and @command{autom4te}:
2600 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2601 -e 's|@@prefix[@@]|$(prefix)|g'
2605 autoheader autom4te: Makefile
2607 $(edit) '$(srcdir)/$@@.in' >$@@.tmp
2614 autoheader: $(srcdir)/autoheader.in
2615 autom4te: $(srcdir)/autom4te.in
2619 Some details are noteworthy:
2622 @item @samp{@@datadir[@@]}
2623 The brackets prevent @command{configure} from replacing
2624 @samp{@@datadir@@} in the Sed expression itself.
2625 Brackets are preferable to a backslash here, since
2626 Posix says @samp{\@@} is not portable.
2628 @item @samp{$(pkgdatadir)}
2629 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2633 Don't use @samp{/} in the Sed expressions that replace file names since
2635 variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}.
2636 Use a shell metacharacter instead, such as @samp{|}.
2638 @item special characters
2639 File names, file name components, and the value of @code{VPATH} should
2640 not contain shell metacharacters or white
2641 space. @xref{Special Chars in Variables}.
2643 @item dependency on @file{Makefile}
2644 Since @code{edit} uses values that depend on the configuration specific
2645 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2646 the output depends on @file{Makefile}, not @file{configure.ac}.
2649 The main rule is generic, and uses @samp{$@@} extensively to
2650 avoid the need for multiple copies of the rule.
2652 @item Separated dependencies and single suffix rules
2653 You can't use them! The above snippet cannot be (portably) rewritten
2657 autoconf autoheader: Makefile
2667 @xref{Single Suffix Rules}, for details.
2669 @item @samp{$(srcdir)}
2670 Be sure to specify the name of the source directory,
2671 otherwise the package won't support separated builds.
2674 For the more specific installation of Erlang libraries, the following variables
2677 @defvar ERLANG_INSTALL_LIB_DIR
2678 @ovindex ERLANG_INSTALL_LIB_DIR
2679 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2680 The common parent directory of Erlang library installation directories.
2681 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2682 macro in @file{configure.ac}.
2685 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2686 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2687 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2688 The installation directory for Erlang library @var{library}.
2689 This variable is set by calling the
2690 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2691 macro in @file{configure.ac}.
2694 @xref{Erlang Libraries}, for details.
2697 @node Changed Directory Variables
2698 @subsection Changed Directory Variables
2699 @cindex @file{datarootdir}
2701 In Autoconf 2.60, the set of directory variables has changed, and the
2702 defaults of some variables have been adjusted
2703 (@pxref{Installation Directory Variables}) to changes in the
2704 @acronym{GNU} Coding Standards. Notably, @file{datadir}, @file{infodir}, and
2705 @file{mandir} are now expressed in terms of @file{datarootdir}. If you are
2706 upgrading from an earlier Autoconf version, you may need to adjust your files
2707 to ensure that the directory variables are substituted correctly
2708 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2709 in place. For example, in a @file{Makefile.in}, adding
2712 datarootdir = @@datarootdir@@
2716 is usually sufficient. If you use Automake to create @file{Makefile.in},
2717 it will add this for you.
2719 To help with the transition, Autoconf warns about files that seem to use
2720 @code{datarootdir} without defining it. In some cases, it then expands
2721 the value of @code{$datarootdir} in substitutions of the directory
2722 variables. The following example shows such a warning:
2725 $ @kbd{cat configure.ac}
2727 AC_CONFIG_FILES([Makefile])
2729 $ @kbd{cat Makefile.in}
2731 datadir = @@datadir@@
2734 configure: creating ./config.status
2735 config.status: creating Makefile
2736 config.status: WARNING:
2737 Makefile.in seems to ignore the --datarootdir setting
2738 $ @kbd{cat Makefile}
2740 datadir = $@{prefix@}/share
2743 Usually one can easily change the file to accommodate both older and newer
2747 $ @kbd{cat Makefile.in}
2749 datarootdir = @@datarootdir@@
2750 datadir = @@datadir@@
2752 configure: creating ./config.status
2753 config.status: creating Makefile
2754 $ @kbd{cat Makefile}
2756 datarootdir = $@{prefix@}/share
2757 datadir = $@{datarootdir@}
2760 @acindex{DATAROOTDIR_CHECKED}
2761 In some cases, however, the checks may not be able to detect that a suitable
2762 initialization of @code{datarootdir} is in place, or they may fail to detect
2763 that such an initialization is necessary in the output file. If, after
2764 auditing your package, there are still spurious @file{configure} warnings about
2765 @code{datarootdir}, you may add the line
2768 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
2772 to your @file{configure.ac} to disable the warnings. This is an exception
2773 to the usual rule that you should not define a macro whose name begins with
2774 @code{AC_} (@pxref{Macro Names}).
2778 @node Build Directories
2779 @subsection Build Directories
2780 @cindex Build directories
2781 @cindex Directories, build
2783 You can support compiling a software package for several architectures
2784 simultaneously from the same copy of the source code. The object files
2785 for each architecture are kept in their own directory.
2787 To support doing this, @command{make} uses the @code{VPATH} variable to
2788 find the files that are in the source directory. @acronym{GNU} Make
2789 can do this. Most other recent @command{make} programs can do this as
2790 well, though they may have difficulties and it is often simpler to
2791 recommend @acronym{GNU} @command{make} (@pxref{VPATH and Make}). Older
2792 @command{make} programs do not support @code{VPATH}; when using them, the
2793 source code must be in the same directory as the object files.
2795 To support @code{VPATH}, each @file{Makefile.in} should contain two
2796 lines that look like:
2803 Do not set @code{VPATH} to the value of another variable, for example
2804 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2805 variable substitutions on the value of @code{VPATH}.
2807 @command{configure} substitutes the correct value for @code{srcdir} when
2808 it produces @file{Makefile}.
2810 Do not use the @code{make} variable @code{$<}, which expands to the
2811 file name of the file in the source directory (found with @code{VPATH}),
2812 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2813 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2814 versions of @command{make} do not set @code{$<} in explicit rules; they
2815 expand it to an empty value.
2817 Instead, Make command lines should always refer to source
2818 files by prefixing them with @samp{$(srcdir)/}. For example:
2821 time.info: time.texinfo
2822 $(MAKEINFO) '$(srcdir)/time.texinfo'
2825 @node Automatic Remaking
2826 @subsection Automatic Remaking
2827 @cindex Automatic remaking
2828 @cindex Remaking automatically
2830 You can put rules like the following in the top-level @file{Makefile.in}
2831 for a package to automatically update the configuration information when
2832 you change the configuration files. This example includes all of the
2833 optional files, such as @file{aclocal.m4} and those related to
2834 configuration header files. Omit from the @file{Makefile.in} rules for
2835 any of these files that your package does not use.
2837 The @samp{$(srcdir)/} prefix is included because of limitations in the
2838 @code{VPATH} mechanism.
2840 The @file{stamp-} files are necessary because the timestamps of
2841 @file{config.h.in} and @file{config.h} are not changed if remaking
2842 them does not change their contents. This feature avoids unnecessary
2843 recompilation. You should include the file @file{stamp-h.in} your
2844 package's distribution, so that @command{make} considers
2845 @file{config.h.in} up to date. Don't use @command{touch}
2846 (@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
2847 @command{date} would cause needless differences, hence @acronym{CVS}
2852 $(srcdir)/configure: configure.ac aclocal.m4
2853 cd '$(srcdir)' && autoconf
2855 # autoheader might not change config.h.in, so touch a stamp file.
2856 $(srcdir)/config.h.in: stamp-h.in
2857 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2858 cd '$(srcdir)' && autoheader
2859 echo timestamp > '$(srcdir)/stamp-h.in'
2862 stamp-h: config.h.in config.status
2865 Makefile: Makefile.in config.status
2868 config.status: configure
2869 ./config.status --recheck
2874 (Be careful if you copy these lines directly into your makefile, as you
2875 need to convert the indented lines to start with the tab character.)
2877 In addition, you should use
2880 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2884 so @file{config.status} ensures that @file{config.h} is considered up to
2885 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
2887 @xref{config.status Invocation}, for more examples of handling
2888 configuration-related dependencies.
2890 @node Configuration Headers
2891 @section Configuration Header Files
2892 @cindex Configuration Header
2893 @cindex @file{config.h}
2895 When a package contains more than a few tests that define C preprocessor
2896 symbols, the command lines to pass @option{-D} options to the compiler
2897 can get quite long. This causes two problems. One is that the
2898 @command{make} output is hard to visually scan for errors. More
2899 seriously, the command lines can exceed the length limits of some
2900 operating systems. As an alternative to passing @option{-D} options to
2901 the compiler, @command{configure} scripts can create a C header file
2902 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2903 macro selects this kind of output. Though it can be called anywhere
2904 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2905 it right after @code{AC_INIT}.
2907 The package should @samp{#include} the configuration header file before
2908 any other header files, to prevent inconsistencies in declarations (for
2909 example, if it redefines @code{const}).
2911 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2912 option (or @option{-I..}; whichever directory contains @file{config.h}).
2913 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2914 the directory of the currently read file, i.e., the source directory, not
2915 the build directory.
2917 With the appropriate @option{-I} option, you can use
2918 @samp{#include <config.h>}. Actually, it's a good habit to use it,
2919 because in the rare case when the source directory contains another
2920 @file{config.h}, the build directory should be searched first.
2923 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2924 @acindex{CONFIG_HEADERS}
2925 @cvindex HAVE_CONFIG_H
2926 This macro is one of the instantiating macros; see @ref{Configuration
2927 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2928 blank-or-newline-separated list @var{header} containing C preprocessor
2929 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2930 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2931 The usual name for @var{header} is @file{config.h}.
2933 If @var{header} already exists and its contents are identical to what
2934 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2935 making some changes in the configuration without needlessly causing
2936 object files that depend on the header file to be recompiled.
2938 Usually the input file is named @file{@var{header}.in}; however, you can
2939 override the input file name by appending to @var{header} a
2940 colon-separated list of input files. For example, you might need to make
2941 the input file name acceptable to @acronym{DOS} variants:
2944 AC_CONFIG_HEADERS([config.h:config.hin])
2951 This macro is defined as the name of the first declared config header
2952 and undefined if no config headers have been declared up to this point.
2953 A third-party macro may, for example, require use of a config header
2954 without invoking AC_CONFIG_HEADERS twice, like this:
2957 AC_CONFIG_COMMANDS_PRE(
2958 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2963 @xref{Configuration Actions}, for more details on @var{header}.
2966 * Header Templates:: Input for the configuration headers
2967 * autoheader Invocation:: How to create configuration templates
2968 * Autoheader Macros:: How to specify CPP templates
2971 @node Header Templates
2972 @subsection Configuration Header Templates
2973 @cindex Configuration Header Template
2974 @cindex Header templates
2975 @cindex @file{config.h.in}
2977 Your distribution should contain a template file that looks as you want
2978 the final header file to look, including comments, with @code{#undef}
2979 statements which are used as hooks. For example, suppose your
2980 @file{configure.ac} makes these calls:
2983 AC_CONFIG_HEADERS([conf.h])
2984 AC_CHECK_HEADERS([unistd.h])
2988 Then you could have code like the following in @file{conf.h.in}. On
2989 systems that have @file{unistd.h}, @command{configure} defines
2990 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line is
2991 commented out (in case the system predefines that symbol).
2995 /* Define as 1 if you have unistd.h. */
2996 #undef HAVE_UNISTD_H
3000 Pay attention that @samp{#undef} is in the first column, and there is
3001 nothing after @samp{HAVE_UNISTD_H}, not even white space. You can
3002 then decode the configuration header using the preprocessor directives:
3008 #ifdef HAVE_UNISTD_H
3009 # include <unistd.h>
3011 /* We are in trouble. */
3016 The use of old form templates, with @samp{#define} instead of
3017 @samp{#undef} is strongly discouraged. Similarly with old templates
3018 with comments on the same line as the @samp{#undef}. Anyway, putting
3019 comments in preprocessor macros has never been a good idea.
3021 Since it is a tedious task to keep a template header up to date, you may
3022 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3025 @node autoheader Invocation
3026 @subsection Using @command{autoheader} to Create @file{config.h.in}
3027 @cindex @command{autoheader}
3029 The @command{autoheader} program can create a template file of C
3030 @samp{#define} statements for @command{configure} to use.
3031 It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
3032 @file{configure} sources to determine the name of the template.
3033 (If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
3034 input file name, @command{autoheader} uses the first one.)
3036 It is recommended that only one input file is used. If you want to append
3037 a boilerplate code, it is preferable to use
3038 @samp{AH_BOTTOM([#include <conf_post.h>])}.
3039 File @file{conf_post.h} is not processed during the configuration then,
3040 which make things clearer. Analogically, @code{AH_TOP} can be used to
3041 prepend a boilerplate code.
3043 In order to do its job, @command{autoheader} needs you to document all
3044 of the symbols that you might use. Typically this is done via an
3045 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3046 is a literal symbol and whose third argument describes the symbol
3047 (@pxref{Defining Symbols}). Alternatively, you can use
3048 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3049 suitable input file for a subsequent configuration header file.
3050 Symbols defined by Autoconf's builtin tests are already documented properly;
3051 you need to document only those that you
3054 You might wonder why @command{autoheader} is needed: after all, why
3055 would @command{configure} need to ``patch'' a @file{config.h.in} to
3056 produce a @file{config.h} instead of just creating @file{config.h} from
3057 scratch? Well, when everything rocks, the answer is just that we are
3058 wasting our time maintaining @command{autoheader}: generating
3059 @file{config.h} directly is all that is needed. When things go wrong,
3060 however, you'll be thankful for the existence of @command{autoheader}.
3062 The fact that the symbols are documented is important in order to
3063 @emph{check} that @file{config.h} makes sense. The fact that there is a
3064 well-defined list of symbols that should be defined (or not) is
3065 also important for people who are porting packages to environments where
3066 @command{configure} cannot be run: they just have to @emph{fill in the
3069 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3071 If you give @command{autoheader} an argument, it uses that file instead
3072 of @file{configure.ac} and writes the header file to the standard output
3073 instead of to @file{config.h.in}. If you give @command{autoheader} an
3074 argument of @option{-}, it reads the standard input instead of
3075 @file{configure.ac} and writes the header file to the standard output.
3077 @command{autoheader} accepts the following options:
3082 Print a summary of the command line options and exit.
3086 Print the version number of Autoconf and exit.
3090 Report processing steps.
3094 Don't remove the temporary files.
3098 Remake the template file even if newer than its input files.
3100 @item --include=@var{dir}
3102 Append @var{dir} to the include path. Multiple invocations accumulate.
3104 @item --prepend-include=@var{dir}
3106 Prepend @var{dir} to the include path. Multiple invocations accumulate.
3108 @item --warnings=@var{category}
3109 @itemx -W @var{category}
3111 Report the warnings related to @var{category} (which can actually be a
3112 comma separated list). Current categories include:
3116 report the uses of obsolete constructs
3119 report all the warnings
3125 treats warnings as errors
3127 @item no-@var{category}
3128 disable warnings falling into @var{category}
3135 @node Autoheader Macros
3136 @subsection Autoheader Macros
3137 @cindex Autoheader macros
3139 @command{autoheader} scans @file{configure.ac} and figures out which C
3140 preprocessor symbols it might define. It knows how to generate
3141 templates for symbols defined by @code{AC_CHECK_HEADERS},
3142 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3143 symbol, you must define a template for it. If there are missing
3144 templates, @command{autoheader} fails with an error message.
3146 The template for a @var{symbol} is created
3147 by @command{autoheader} from
3148 the @var{description} argument to an @code{AC_DEFINE};
3149 see @ref{Defining Symbols}.
3151 For special needs, you can use the following macros.
3154 @defmac AH_TEMPLATE (@var{key}, @var{description})
3156 Tell @command{autoheader} to generate a template for @var{key}. This macro
3157 generates standard templates just like @code{AC_DEFINE} when a
3158 @var{description} is given.
3163 AH_TEMPLATE([CRAY_STACKSEG_END],
3164 [Define to one of _getb67, GETB67, getb67
3165 for Cray-2 and Cray-YMP systems. This
3166 function is required for alloca.c support
3171 generates the following template, with the description properly
3175 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3176 Cray-YMP systems. This function is required for alloca.c
3177 support on those systems. */
3178 #undef CRAY_STACKSEG_END
3183 @defmac AH_VERBATIM (@var{key}, @var{template})
3185 Tell @command{autoheader} to include the @var{template} as-is in the header
3186 template file. This @var{template} is associated with the @var{key},
3187 which is used to sort all the different templates and guarantee their
3188 uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
3192 @defmac AH_TOP (@var{text})
3194 Include @var{text} at the top of the header template file.
3198 @defmac AH_BOTTOM (@var{text})
3200 Include @var{text} at the bottom of the header template file.
3204 Please note that @var{text} gets included ``verbatim'' to the template file,
3205 not to the resulting config header, so it can easily get mangled when the
3206 template is processed. There is rarely a need for something other than
3209 AH_BOTTOM([#include <custom.h>])
3214 @node Configuration Commands
3215 @section Running Arbitrary Configuration Commands
3216 @cindex Configuration commands
3217 @cindex Commands for configuration
3219 You can execute arbitrary commands before, during, and after
3220 @file{config.status} is run. The three following macros accumulate the
3221 commands to run when they are called multiple times.
3222 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3223 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3225 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3226 @acindex{CONFIG_COMMANDS}
3227 Specify additional shell commands to run at the end of
3228 @file{config.status}, and shell commands to initialize any variables
3229 from @command{configure}. Associate the commands with @var{tag}.
3230 Since typically the @var{cmds} create a file, @var{tag} should
3231 naturally be the name of that file. If needed, the directory hosting
3232 @var{tag} is created. This macro is one of the instantiating macros;
3233 see @ref{Configuration Actions}.
3235 Here is an unrealistic example:
3238 AC_CONFIG_COMMANDS([fubar],
3239 [echo this is extra $fubar, and so on.],
3243 Here is a better one:
3245 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3249 The following two macros look similar, but in fact they are not of the same
3250 breed: they are executed directly by @file{configure}, so you cannot use
3251 @file{config.status} to rerun them.
3253 @c Yet it is good to leave them here. The user sees them together and
3254 @c decides which best fits their needs.
3256 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3257 @acindex{CONFIG_COMMANDS_PRE}
3258 Execute the @var{cmds} right before creating @file{config.status}.
3260 This macro presents the last opportunity to call @code{AC_SUBST},
3261 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3264 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3265 @acindex{CONFIG_COMMANDS_POST}
3266 Execute the @var{cmds} right after creating @file{config.status}.
3272 @node Configuration Links
3273 @section Creating Configuration Links
3274 @cindex Configuration links
3275 @cindex Links for configuration
3277 You may find it convenient to create links whose destinations depend upon
3278 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3279 creation of relative symbolic links can be delicate when the package is
3280 built in a directory different from the source directory.
3282 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3283 @acindex{CONFIG_LINKS}
3285 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3286 the corresponding link name @var{dest}. Makes a symbolic link if
3287 possible, otherwise a hard link if possible, otherwise a copy. The
3288 @var{dest} and @var{source} names should be relative to the top level
3289 source or build directory. This macro is one of the instantiating
3290 macros; see @ref{Configuration Actions}.
3292 For example, this call:
3295 AC_CONFIG_LINKS([host.h:config/$machine.h
3296 object.h:config/$obj_format.h])
3300 creates in the current directory @file{host.h} as a link to
3301 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3302 link to @file{@var{srcdir}/config/$obj_format.h}.
3304 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3305 impossible for @samp{config.status} to guess the links to establish.
3309 ./config.status host.h object.h
3312 to create the links.
3317 @node Subdirectories
3318 @section Configuring Other Packages in Subdirectories
3319 @cindex Configure subdirectories
3320 @cindex Subdirectory configure
3322 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3323 makefiles in subdirectories. However, @command{configure} scripts
3324 that control more than one independent package can use
3325 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3326 packages in subdirectories.
3328 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3329 @acindex{CONFIG_SUBDIRS}
3331 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3332 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3333 be a literal, i.e., please do not use:
3336 if test "$package_foo_enabled" = yes; then
3337 $my_subdirs="$my_subdirs foo"
3339 AC_CONFIG_SUBDIRS([$my_subdirs])
3343 because this prevents @samp{./configure --help=recursive} from
3344 displaying the options of the package @code{foo}. Instead, you should
3348 if test "$package_foo_enabled" = yes; then
3349 AC_CONFIG_SUBDIRS([foo])
3353 If a given @var{dir} is not found, an error is reported: if the
3354 subdirectory is optional, write:
3357 if test -d "$srcdir/foo"; then
3358 AC_CONFIG_SUBDIRS([foo])
3362 @c NB: Yes, below we mean configure.in, not configure.ac.
3363 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3364 of @command{configure}. This is for packages that might use a
3365 non-Autoconf script @command{Configure}, which can't be called through a
3366 wrapper @command{configure} since it would be the same file on
3367 case-insensitive file systems. Likewise, if a @var{dir} contains
3368 @file{configure.in} but no @command{configure}, the Cygnus
3369 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3371 The subdirectory @command{configure} scripts are given the same command
3372 line options that were given to this @command{configure} script, with minor
3373 changes if needed, which include:
3377 adjusting a relative name for the cache file;
3380 adjusting a relative name for the source directory;
3383 propagating the current value of @code{$prefix}, including if it was
3384 defaulted, and if the default values of the top level and of the subdirectory
3385 @file{configure} differ.
3388 This macro also sets the output variable @code{subdirs} to the list of
3389 directories @samp{@var{dir} @dots{}}. Make rules can use
3390 this variable to determine which subdirectories to recurse into.
3392 This macro may be called multiple times.
3395 @node Default Prefix
3396 @section Default Prefix
3397 @cindex Install prefix
3398 @cindex Prefix for install
3400 By default, @command{configure} sets the prefix for files it installs to
3401 @file{/usr/local}. The user of @command{configure} can select a different
3402 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3403 There are two ways to change the default: when creating
3404 @command{configure}, and when running it.
3406 Some software packages might want to install in a directory other than
3407 @file{/usr/local} by default. To accomplish that, use the
3408 @code{AC_PREFIX_DEFAULT} macro.
3410 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3411 @acindex{PREFIX_DEFAULT}
3412 Set the default installation prefix to @var{prefix} instead of
3416 It may be convenient for users to have @command{configure} guess the
3417 installation prefix from the location of a related program that they
3418 have already installed. If you wish to do that, you can call
3419 @code{AC_PREFIX_PROGRAM}.
3421 @defmac AC_PREFIX_PROGRAM (@var{program})
3422 @acindex{PREFIX_PROGRAM}
3423 If the user did not specify an installation prefix (using the
3424 @option{--prefix} option), guess a value for it by looking for
3425 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3426 is found, set the prefix to the parent of the directory containing
3427 @var{program}, else default the prefix as described above
3428 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3429 @var{program} is @code{gcc} and the @env{PATH} contains
3430 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3435 @c ======================================================== Existing tests
3437 @node Existing Tests
3438 @chapter Existing Tests
3440 These macros test for particular system features that packages might
3441 need or want to use. If you need to test for a kind of feature that
3442 none of these macros check for, you can probably do it by calling
3443 primitive test macros with appropriate arguments (@pxref{Writing
3446 These tests print messages telling the user which feature they're
3447 checking for, and what they find. They cache their results for future
3448 @command{configure} runs (@pxref{Caching Results}).
3450 Some of these macros set output variables. @xref{Makefile
3451 Substitutions}, for how to get their values. The phrase ``define
3452 @var{name}'' is used below as a shorthand to mean ``define the C
3453 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3454 Symbols}, for how to get those symbol definitions into your program.
3457 * Common Behavior:: Macros' standard schemes
3458 * Alternative Programs:: Selecting between alternative programs
3459 * Files:: Checking for the existence of files
3460 * Libraries:: Library archives that might be missing
3461 * Library Functions:: C library functions that might be missing
3462 * Header Files:: Header files that might be missing
3463 * Declarations:: Declarations that may be missing
3464 * Structures:: Structures or members that might be missing
3465 * Types:: Types that might be missing
3466 * Compilers and Preprocessors:: Checking for compiling programs
3467 * System Services:: Operating system services
3468 * Posix Variants:: Special kludges for specific Posix variants
3469 * Erlang Libraries:: Checking for the existence of Erlang libraries
3472 @node Common Behavior
3473 @section Common Behavior
3474 @cindex Common autoconf behavior
3476 Much effort has been expended to make Autoconf easy to learn. The most
3477 obvious way to reach this goal is simply to enforce standard interfaces
3478 and behaviors, avoiding exceptions as much as possible. Because of
3479 history and inertia, unfortunately, there are still too many exceptions
3480 in Autoconf; nevertheless, this section describes some of the common
3484 * Standard Symbols:: Symbols defined by the macros
3485 * Default Includes:: Includes used by the generic macros
3488 @node Standard Symbols
3489 @subsection Standard Symbols
3490 @cindex Standard symbols
3492 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3493 their test transform their @var{argument} values to a standard alphabet.
3494 First, @var{argument} is converted to upper case and any asterisks
3495 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3496 that are not alphanumeric are converted to underscores.
3501 AC_CHECK_TYPES([struct $Expensive*])
3505 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3509 @node Default Includes
3510 @subsection Default Includes
3511 @cindex Default includes
3512 @cindex Includes, default
3514 Several tests depend upon a set of header files. Since these headers
3515 are not universally available, tests actually have to provide a set of
3516 protected includes, such as:
3520 #ifdef TIME_WITH_SYS_TIME
3521 # include <sys/time.h>
3524 # ifdef HAVE_SYS_TIME_H
3525 # include <sys/time.h>
3534 Unless you know exactly what you are doing, you should avoid using
3535 unconditional includes, and check the existence of the headers you
3536 include beforehand (@pxref{Header Files}).
3538 Most generic macros use the following macro to provide the default set
3541 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3542 @acindex{INCLUDES_DEFAULT}
3543 Expand to @var{include-directives} if defined, otherwise to:
3548 #ifdef HAVE_SYS_TYPES_H
3549 # include <sys/types.h>
3551 #ifdef HAVE_SYS_STAT_H
3552 # include <sys/stat.h>
3555 # include <stdlib.h>
3556 # include <stddef.h>
3558 # ifdef HAVE_STDLIB_H
3559 # include <stdlib.h>
3562 #ifdef HAVE_STRING_H
3563 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
3564 # include <memory.h>
3566 # include <string.h>
3568 #ifdef HAVE_STRINGS_H
3569 # include <strings.h>
3571 #ifdef HAVE_INTTYPES_H
3572 # include <inttypes.h>
3574 #ifdef HAVE_STDINT_H
3575 # include <stdint.h>
3577 #ifdef HAVE_UNISTD_H
3578 # include <unistd.h>
3583 If the default includes are used, then check for the presence of these
3584 headers and their compatibility, i.e., you don't need to run
3585 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3587 These headers are checked for in the same order as they are included.
3588 For instance, on some systems @file{string.h} and @file{strings.h} both
3589 exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
3590 @code{HAVE_STRINGS_H}.
3593 @node Alternative Programs
3594 @section Alternative Programs
3595 @cindex Programs, checking
3597 These macros check for the presence or behavior of particular programs.
3598 They are used to choose between several alternative programs and to
3599 decide what to do once one has been chosen. If there is no macro
3600 specifically defined to check for a program you need, and you don't need
3601 to check for any special properties of it, then you can use one of the
3602 general program-check macros.
3605 * Particular Programs:: Special handling to find certain programs
3606 * Generic Programs:: How to find other programs
3609 @node Particular Programs
3610 @subsection Particular Program Checks
3612 These macros check for particular programs---whether they exist, and
3613 in some cases whether they support certain features.
3618 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3619 order, and set output variable @code{AWK} to the first one that is found.
3620 It tries @code{gawk} first because that is reported to be the
3621 best implementation.
3624 @defmac AC_PROG_GREP
3627 Look for the best available @code{grep} or @code{ggrep} that accepts the
3628 longest input lines possible, and that supports multiple @option{-e} options.
3629 Set the output variable @code{GREP} to whatever is chosen.
3630 @xref{Limitations of Usual Tools}, for more information about
3631 portability problems with the @command{grep} command family.
3634 @defmac AC_PROG_EGREP
3635 @acindex{PROG_EGREP}
3637 Check whether @code{$GREP -E} works, or else look for the best available
3638 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3639 Set the output variable @code{EGREP} to whatever is chosen.
3642 @defmac AC_PROG_FGREP
3643 @acindex{PROG_FGREP}
3645 Check whether @code{$GREP -F} works, or else look for the best available
3646 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3647 Set the output variable @code{FGREP} to whatever is chosen.
3650 @defmac AC_PROG_INSTALL
3651 @acindex{PROG_INSTALL}
3653 @ovindex INSTALL_PROGRAM
3654 @ovindex INSTALL_DATA
3655 @ovindex INSTALL_SCRIPT
3656 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3657 @command{install} program, if one is found in the current @env{PATH}.
3658 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3659 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3660 default directories) to determine @var{dir} (@pxref{Output}). Also set
3661 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3662 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3664 @samp{@@INSTALL@@} is special, as its value may vary for different
3665 configuration files.
3667 This macro screens out various instances of @command{install} known not to
3668 work. It prefers to find a C program rather than a shell script, for
3669 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3670 but that name is obsolete because some @command{make} programs have a rule
3671 that creates @file{install} from it if there is no makefile.
3673 Autoconf comes with a copy of @file{install-sh} that you can use. If
3674 you use @code{AC_PROG_INSTALL}, you must include either
3675 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3676 @command{configure} produces an error message saying it can't find
3677 them---even if the system you're on has a good @command{install} program.
3678 This check is a safety measure to prevent you from accidentally leaving
3679 that file out, which would prevent your package from installing on
3680 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3682 If you need to use your own installation program because it has features
3683 not found in standard @command{install} programs, there is no reason to use
3684 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3685 @file{Makefile.in} files.
3688 @defmac AC_PROG_MKDIR_P
3689 @acindex{AC_PROG_MKDIR_P}
3691 Set output variable @code{MKDIR_P} to a program that ensures that for
3692 each argument, a directory named by this argument exists, creating it
3693 and its parent directories if needed, and without race conditions when
3694 two instances of the program attempt to make the same directory at
3695 nearly the same time.
3697 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
3698 falls back on invoking @command{install-sh} with the @option{-d} option,
3699 so your package should
3700 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3701 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3702 is vulnerable to race conditions, so if you want to support parallel
3704 different packages into the same directory you need to make sure you
3705 have an up-to-date @file{install-sh}. In particular, be careful about
3706 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3708 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3709 in M4sh}), but it sets an output variable intended for use in other
3710 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3711 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
3712 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
3713 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
3714 directory, and conversely a makefile should use @code{$(MKDIR_P) --
3715 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
3716 Finally, @code{AS_MKDIR_P} does not check for race condition
3717 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3719 @samp{@@MKDIR_P@@} is special, as its value may vary for different
3720 configuration files.
3727 @cvindex YYTEXT_POINTER
3728 @ovindex LEX_OUTPUT_ROOT
3729 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3730 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3731 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3734 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
3735 of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3736 the base of the file name that the lexer generates; usually
3737 @file{lex.yy}, but sometimes something else. These results vary
3738 according to whether @code{lex} or @code{flex} is being used.
3740 You are encouraged to use Flex in your sources, since it is both more
3741 pleasant to use than plain Lex and the C source it produces is portable.
3742 In order to ensure portability, however, you must either provide a
3743 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3744 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3745 statement in the scanner's source. Once this done, the scanner is
3746 portable (unless @emph{you} felt free to use nonportable constructs) and
3747 does not depend on any library. In this case, and in this case only, it
3748 is suggested that you use this Autoconf snippet:
3752 if test "$LEX" != flex; then
3753 LEX="$SHELL $missing_dir/missing flex"
3754 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3755 AC_SUBST([LEXLIB], [''])
3759 The shell script @command{missing} can be found in the Automake
3762 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3763 (indirectly) this macro twice, which causes an annoying but benign
3764 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3765 of Automake will fix this issue; meanwhile, just ignore this message.
3767 As part of running the test, this macro may delete any file in the
3768 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3771 @defmac AC_PROG_LN_S
3774 If @samp{ln -s} works on the current file system (the operating system
3775 and file system support symbolic links), set the output variable
3776 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3777 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3779 If you make a link in a directory other than the current directory, its
3780 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3781 create links using @samp{$(LN_S)}, either find out which form is used
3782 and adjust the arguments, or always invoke @code{ln} in the directory
3783 where the link is to be created.
3785 In other words, it does not work to do:
3793 (cd /x && $(LN_S) foo bar)
3797 @defmac AC_PROG_RANLIB
3798 @acindex{PROG_RANLIB}
3800 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3801 is found, and otherwise to @samp{:} (do nothing).
3807 Set output variable @code{SED} to a Sed implementation that conforms to
3808 Posix and does not have arbitrary length limits. Report an error if no
3809 acceptable Sed is found. @xref{Limitations of Usual Tools}, for more
3810 information about portability problems with Sed.
3813 @defmac AC_PROG_YACC
3816 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3817 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3818 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3821 @node Generic Programs
3822 @subsection Generic Program and File Checks
3824 These macros are used to find programs not covered by the ``particular''
3825 test macros. If you need to check the behavior of a program as well as
3826 find out whether it is present, you have to write your own test for it
3827 (@pxref{Writing Tests}). By default, these macros use the environment
3828 variable @env{PATH}. If you need to check for a program that might not
3829 be in the user's @env{PATH}, you can pass a modified path to use
3833 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3834 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3837 You are strongly encouraged to declare the @var{variable} passed to
3838 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3839 @code{AC_ARG_VAR}, for more details.
3841 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
3842 @acindex{CHECK_PROG}
3843 Check whether program @var{prog-to-check-for} exists in @env{PATH}. If
3844 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3845 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3846 absolute file name) even if it is the first found in the search path; in
3847 that case, set @var{variable} using the absolute file name of the
3848 @var{prog-to-check-for} found that is not @var{reject}. If
3849 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3853 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3854 @acindex{CHECK_PROGS}
3855 Check for each program in the blank-separated list
3856 @var{progs-to-check-for} existing in the @env{PATH}. If one is found, set
3857 @var{variable} to the name of that program. Otherwise, continue
3858 checking the next program in the list. If none of the programs in the
3859 list are found, set @var{variable} to @var{value-if-not-found}; if
3860 @var{value-if-not-found} is not specified, the value of @var{variable}
3861 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3864 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3865 @acindex{CHECK_TARGET_TOOL}
3866 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3867 with a prefix of the target type as determined by
3868 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3869 If the tool cannot be found with a prefix, and if the build and target
3870 types are equal, then it is also searched for without a prefix.
3872 As noted in @ref{Specifying Names, , Specifying the system type}, the
3873 target is rarely specified, because most of the time it is the same
3874 as the host: it is the type of system for which any compiler tool in
3875 the package produces code. What this macro looks for is,
3876 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3877 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3878 uses to produce objects, archives or executables}.
3881 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3882 @acindex{CHECK_TOOL}
3883 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3884 with a prefix of the host type as determined by
3885 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3886 For example, if the user runs @samp{configure --host=i386-gnu}, then
3889 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3892 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3893 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3894 @env{PATH}, or to @samp{:} if neither program exists.
3896 In the future, when cross-compiling this macro will @emph{only}
3897 accept program names that are prefixed with the host type.
3898 For more information, see @ref{Specifying Names, , Specifying the
3902 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3903 @acindex{CHECK_TARGET_TOOLS}
3904 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3905 @var{progs-to-check-for} are checked with a prefix of the target type as
3906 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3907 (@pxref{Canonicalizing}). If none of the tools can be found with a
3908 prefix, and if the build and target types are equal, then the first one
3909 without a prefix is used. If a tool is found, set @var{variable} to
3910 the name of that program. If none of the tools in the list are found,
3911 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3912 is not specified, the value of @var{variable} is not changed. Calls
3913 @code{AC_SUBST} for @var{variable}.
3916 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3917 @acindex{CHECK_TOOLS}
3918 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3919 @var{progs-to-check-for} are checked with a prefix of the host type as
3920 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3921 (@pxref{Canonicalizing}). If none of the tools can be found with a
3922 prefix, then the first one without a prefix is used. If a tool is found,
3923 set @var{variable} to the name of that program. If none of the tools in
3924 the list are found, set @var{variable} to @var{value-if-not-found}; if
3925 @var{value-if-not-found} is not specified, the value of @var{variable}
3926 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3928 In the future, when cross-compiling this macro will @emph{not}
3929 accept program names that are not prefixed with the host type.
3932 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3934 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3935 name of @var{prog-to-check-for} if found.
3938 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3939 @acindex{PATH_PROGS}
3940 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3941 are found, set @var{variable} to the absolute name of the program
3945 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3946 @acindex{PATH_TARGET_TOOL}
3947 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3948 name of the program if it is found.
3951 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3953 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3954 name of the program if it is found.
3956 In the future, when cross-compiling this macro will @emph{not}
3957 accept program names that are not prefixed with the host type.
3963 @cindex File, checking
3965 You might also need to check for the existence of files. Before using
3966 these macros, ask yourself whether a runtime test might not be a better
3967 solution. Be aware that, like most Autoconf macros, they test a feature
3968 of the host machine, and therefore, they die when cross-compiling.
3970 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3971 @acindex{CHECK_FILE}
3972 Check whether file @var{file} exists on the native system. If it is
3973 found, execute @var{action-if-found}, otherwise do
3974 @var{action-if-not-found}, if given.
3977 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3978 @acindex{CHECK_FILES}
3979 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3980 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3981 for each file found.
3986 @section Library Files
3987 @cindex Library, checking
3989 The following macros check for the presence of certain C, C++, or Fortran
3990 library archive files.
3992 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3994 Test whether the library @var{library} is available by trying to link
3995 a test program that calls function @var{function} with the library.
3996 @var{function} should be a function provided by the library.
3998 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
3999 the @var{library} argument.
4001 @var{action-if-found} is a list of shell commands to run if the link
4002 with the library succeeds; @var{action-if-not-found} is a list of shell
4003 commands to run if the link fails. If @var{action-if-found} is not
4004 specified, the default action prepends @option{-l@var{library}} to
4005 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
4006 capitals). This macro is intended to support building @code{LIBS} in
4007 a right-to-left (least-dependent to most-dependent) fashion such that
4008 library dependencies are satisfied as a natural side effect of
4009 consecutive tests. Linkers are sensitive to library ordering
4010 so the order in which @code{LIBS} is generated is important to reliable
4011 detection of libraries.
4013 If linking with @var{library} results in unresolved symbols that would
4014 be resolved by linking with additional libraries, give those libraries
4015 as the @var{other-libraries} argument, separated by spaces:
4016 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4017 that @var{library} is present, because linking the test program
4018 always fails with unresolved symbols. The @var{other-libraries} argument
4019 should be limited to cases where it is desirable to test for one library
4020 in the presence of another that is not already in @code{LIBS}.
4022 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4023 in some common cases. Many standard functions like @code{gethostbyname}
4024 appear the standard C library on some hosts, and in special libraries
4025 like @code{nsl} on other hosts. On some hosts the special libraries
4026 contain variant implementations that you may not want to use. These
4027 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4028 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4032 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4033 @acindex{SEARCH_LIBS}
4034 Search for a library defining @var{function} if it's not already
4035 available. This equates to calling
4036 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4037 no libraries, then for each library listed in @var{search-libs}.
4039 Add @option{-l@var{library}} to @code{LIBS} for the first library found
4040 to contain @var{function}, and run @var{action-if-found}. If the
4041 function is not found, run @var{action-if-not-found}.
4043 If linking with @var{library} results in unresolved symbols that would
4044 be resolved by linking with additional libraries, give those libraries
4045 as the @var{other-libraries} argument, separated by spaces:
4046 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4047 that @var{function} is present, because linking the test program
4048 always fails with unresolved symbols.
4053 @node Library Functions
4054 @section Library Functions
4056 The following macros check for particular C library functions.
4057 If there is no macro specifically defined to check for a function you need,
4058 and you don't need to check for any special properties of
4059 it, then you can use one of the general function-check macros.
4062 * Function Portability:: Pitfalls with usual functions
4063 * Particular Functions:: Special handling to find certain functions
4064 * Generic Functions:: How to find other functions
4067 @node Function Portability
4068 @subsection Portability of C Functions
4069 @cindex Portability of C functions
4070 @cindex C function portability
4072 Most usual functions can either be missing, or be buggy, or be limited
4073 on some architectures. This section tries to make an inventory of these
4074 portability issues. By definition, this list always requires
4075 additions. Please help us keeping it as complete as possible.
4080 @prindex @code{exit}
4081 On ancient hosts, @code{exit} returned @code{int}.
4082 This is because @code{exit} predates @code{void}, and there was a long
4083 tradition of it returning @code{int}.
4085 On current hosts, the problem more likely is that @code{exit} is not
4086 declared, due to C++ problems of some sort or another. For this reason
4087 we suggest that test programs not invoke @code{exit}, but return from
4088 @code{main} instead.
4092 @prindex @code{free}
4093 The C standard says a call @code{free (NULL)} does nothing, but
4094 some old systems don't support this (e.g., NextStep).
4100 @prindex @code{isinf}
4101 @prindex @code{isnan}
4102 The C99 standard says that @code{isinf} and @code{isnan} are
4103 macros. On some systems just macros are available
4104 (e.g., @acronym{HP-UX} and Solaris 10), on
4105 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4106 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
4107 these functions are declared in nonstandard headers like
4108 @code{<sunmath.h>} and defined in non-default libraries like
4109 @option{-lm} or @option{-lsunmath}.
4111 The C99 @code{isinf} and @code{isnan} macros work correctly with
4112 @code{long double} arguments, but pre-C99 systems that use functions
4113 typically assume @code{double} arguments. On such a system,
4114 @code{isinf} incorrectly returns true for a finite @code{long double}
4115 argument that is outside the range of @code{double}.
4117 To work around this porting mess, you can use code like the following.
4124 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4125 : sizeof (x) == sizeof (double) ? isnan_d (x) \
4127 static inline int isnan_f (float x) @{ return x != x; @}
4128 static inline int isnan_d (double x) @{ return x != x; @}
4129 static inline int isnan_ld (long double x) @{ return x != x; @}
4134 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4135 : sizeof (x) == sizeof (double) ? isinf_d (x) \
4137 static inline int isinf_f (float x) @{ return isnan (x - x); @}
4138 static inline int isinf_d (double x) @{ return isnan (x - x); @}
4139 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
4143 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4144 compilers that lack the @code{inline} keyword. Some optimizing
4145 compilers mishandle these definitions, but systems with that bug
4146 typically have missing or broken @code{isnan} functions anyway, so it's
4147 probably not worth worrying about.
4151 @prindex @code{malloc}
4152 The C standard says a call @code{malloc (0)} is implementation
4153 dependent. It can return either @code{NULL} or a new non-null pointer.
4154 The latter is more common (e.g., the @acronym{GNU} C Library) but is by
4155 no means universal. @code{AC_FUNC_MALLOC}
4156 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4160 @prindex @code{putenv}
4161 Posix prefers @code{setenv} to @code{putenv}; among other things,
4162 @code{putenv} is not required of all Posix implementations, but
4165 Posix specifies that @code{putenv} puts the given string directly in
4166 @code{environ}, but some systems make a copy of it instead (e.g.,
4167 glibc 2.0, or @acronym{BSD}). And when a copy is made, @code{unsetenv} might
4168 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4170 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4171 environment, but this is not standard usage and it dumps core
4172 on some systems (e.g., AIX).
4174 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4175 environment, rather than inserting it with an empty value.
4177 @item @code{realloc}
4179 @prindex @code{realloc}
4180 The C standard says a call @code{realloc (NULL, size)} is equivalent
4181 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4184 @item @code{signal} handler
4186 @prindex @code{signal}
4187 Normally @code{signal} takes a handler function with a return type of
4188 @code{void}, but some old systems required @code{int} instead. Any
4189 actual @code{int} value returned is not used; this is only a
4190 difference in the function prototype demanded.
4192 All systems we know of in current use return @code{void}. The
4193 @code{int} was to support K&R C, where of course @code{void} is not
4194 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4195 used to establish the correct type in all cases.
4197 @item @code{snprintf}
4198 @c @fuindex snprintf
4199 @prindex @code{snprintf}
4200 @c @fuindex vsnprintf
4201 @prindex @code{vsnprintf}
4202 The C99 standard says that if the output array isn't big enough
4203 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4204 truncate the output and return the number of bytes that ought to have
4205 been produced. Some older systems return the truncated length (e.g.,
4206 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4207 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4208 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
4209 older systems ignore the length and overrun the buffer (e.g., 64-bit
4212 @item @code{sprintf}
4214 @prindex @code{sprintf}
4215 @c @fuindex vsprintf
4216 @prindex @code{vsprintf}
4217 The C standard says @code{sprintf} and @code{vsprintf} return the
4218 number of bytes written. On some ancient systems (SunOS 4 for
4219 instance) they return the buffer pointer instead, but these no
4220 longer need to be worried about.
4224 @prindex @code{sscanf}
4225 On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires that its
4226 input string be writable (though it doesn't actually change it). This
4227 can be a problem when using @command{gcc} since it normally puts
4228 constant strings in read-only memory (@pxref{Incompatibilities,
4229 Incompatibilities of @acronym{GCC}, , gcc, Using and
4230 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
4231 having format strings read-only can be a problem.
4233 @item @code{strerror_r}
4234 @c @fuindex strerror_r
4235 @prindex @code{strerror_r}
4236 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4237 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4238 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
4239 can detect which is in use (@pxref{Particular Functions}).
4241 @item @code{strnlen}
4243 @prindex @code{strnlen}
4244 @acronym{AIX} 4.3 provides a broken version which produces the
4248 strnlen ("foobar", 0) = 0
4249 strnlen ("foobar", 1) = 3
4250 strnlen ("foobar", 2) = 2
4251 strnlen ("foobar", 3) = 1
4252 strnlen ("foobar", 4) = 0
4253 strnlen ("foobar", 5) = 6
4254 strnlen ("foobar", 6) = 6
4255 strnlen ("foobar", 7) = 6
4256 strnlen ("foobar", 8) = 6
4257 strnlen ("foobar", 9) = 6
4260 @item @code{sysconf}
4262 @prindex @code{sysconf}
4263 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX}
4264 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
4269 @prindex @code{unlink}
4270 The Posix spec says that @code{unlink} causes the given file to be
4271 removed only after there are no more open file handles for it. Some
4272 non-Posix hosts have trouble with this requirement, though,
4273 and some @acronym{DOS} variants even corrupt the file system.
4275 @item @code{unsetenv}
4276 @c @fuindex unsetenv
4277 @prindex @code{unsetenv}
4278 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4279 can be removed with a call @code{putenv ("FOO=")}, as described under
4280 @code{putenv} above.
4282 @item @code{va_copy}
4284 @prindex @code{va_copy}
4285 The C99 standard provides @code{va_copy} for copying
4286 @code{va_list} variables. It may be available in older environments
4287 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4288 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
4289 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4292 @item @code{va_list}
4294 @prindex @code{va_list}
4295 @code{va_list} is not necessarily just a pointer. It can be a
4296 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4297 not portable. Or it can be an array (e.g., @command{gcc} in some
4298 PowerPC configurations), which means as a function parameter it can be
4299 effectively call-by-reference and library routines might modify the
4300 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4303 @item Signed @code{>>}
4304 Normally the C @code{>>} right shift of a signed type replicates the
4305 high bit, giving a so-called ``arithmetic'' shift. But care should be
4306 taken since Standard C doesn't require that behavior. On those
4307 few processors without a native arithmetic shift (for instance Cray
4308 vector systems) zero bits may be shifted in, the same as a shift of an
4311 @item Integer @code{/}
4312 C divides signed integers by truncating their quotient toward zero,
4313 yielding the same result as Fortran. However, before C99 the standard
4314 allowed C implementations to take the floor or ceiling of the quotient
4315 in some cases. Hardly any implementations took advantage of this
4316 freedom, though, and it's probably not worth worrying about this issue
4321 @node Particular Functions
4322 @subsection Particular Function Checks
4323 @cindex Function, checking
4325 These macros check for particular C functions---whether they exist, and
4326 in some cases how they respond when given certain arguments.
4328 @defmac AC_FUNC_ALLOCA
4329 @acindex{FUNC_ALLOCA}
4331 @cvindex HAVE_ALLOCA_H
4334 @prindex @code{alloca}
4336 Check how to get @code{alloca}. Tries to get a builtin version by
4337 checking for @file{alloca.h} or the predefined C preprocessor macros
4338 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4339 it defines @code{HAVE_ALLOCA_H}.
4341 If those attempts fail, it looks for the function in the standard C
4342 library. If any of those methods succeed, it defines
4343 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4344 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4345 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4346 garbage collect). This variable is separate from @code{LIBOBJS} so
4347 multiple programs can share the value of @code{ALLOCA} without needing
4348 to create an actual library, in case only some of them use the code in
4349 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4350 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4352 This macro does not try to get @code{alloca} from the System V R3
4353 @file{libPW} or the System V R4 @file{libucb} because those libraries
4354 contain some incompatible functions that cause trouble. Some versions
4355 do not even contain @code{alloca} or contain a buggy version. If you
4356 still want to use their @code{alloca}, use @code{ar} to extract
4357 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4359 Source files that use @code{alloca} should start with a piece of code
4360 like the following, to declare it properly.
4364 #ifdef HAVE_ALLOCA_H
4365 # include <alloca.h>
4366 #elif defined __GNUC__
4367 # define alloca __builtin_alloca
4369 # define alloca __alloca
4370 #elif defined _MSC_VER
4371 # include <malloc.h>
4372 # define alloca _alloca
4374 # include <stddef.h>
4378 void *alloca (size_t);
4384 @defmac AC_FUNC_CHOWN
4385 @acindex{FUNC_CHOWN}
4387 @prindex @code{chown}
4388 If the @code{chown} function is available and works (in particular, it
4389 should accept @option{-1} for @code{uid} and @code{gid}), define
4394 @defmac AC_FUNC_CLOSEDIR_VOID
4395 @acindex{FUNC_CLOSEDIR_VOID}
4396 @cvindex CLOSEDIR_VOID
4397 @c @fuindex closedir
4398 @prindex @code{closedir}
4399 If the @code{closedir} function does not return a meaningful value,
4400 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4401 return value for an error indicator.
4403 Currently this test is implemented by running a test program. When
4404 cross compiling the pessimistic assumption that @code{closedir} does not
4405 return a meaningful value is made.
4407 This macro is obsolescent, as @code{closedir} returns a meaningful value
4408 on current systems. New programs need not use this macro.
4411 @defmac AC_FUNC_ERROR_AT_LINE
4412 @acindex{FUNC_ERROR_AT_LINE}
4413 @c @fuindex error_at_line
4414 @prindex @code{error_at_line}
4415 If the @code{error_at_line} function is not found, require an
4416 @code{AC_LIBOBJ} replacement of @samp{error}.
4419 @defmac AC_FUNC_FNMATCH
4420 @acindex{FUNC_FNMATCH}
4422 @prindex @code{fnmatch}
4423 If the @code{fnmatch} function conforms to Posix, define
4424 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4425 the bugs in Solaris 2.4.
4427 Unlike the other specific
4428 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4429 broken/missing @code{fnmatch}. This is for historical reasons.
4430 See @code{AC_REPLACE_FNMATCH} below.
4432 This macro is obsolescent. New programs should use Gnulib's
4433 @code{fnmatch-posix} module. @xref{Gnulib}.
4436 @defmac AC_FUNC_FNMATCH_GNU
4437 @acindex{FUNC_FNMATCH_GNU}
4439 @prindex @code{fnmatch}
4440 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4441 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
4442 implementation bugs, for example, the bugs in the @acronym{GNU} C
4445 This macro is obsolescent. New programs should use Gnulib's
4446 @code{fnmatch-gnu} module. @xref{Gnulib}.
4449 @defmac AC_FUNC_FORK
4451 @cvindex HAVE_VFORK_H
4452 @cvindex HAVE_WORKING_FORK
4453 @cvindex HAVE_WORKING_VFORK
4456 @prindex @code{fork}
4458 @prindex @code{vfork}
4460 This macro checks for the @code{fork} and @code{vfork} functions. If a
4461 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4462 checks whether @code{fork} is just a stub by trying to run it.
4464 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4465 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4466 define @code{vfork} to be @code{fork} for backward compatibility with
4467 previous versions of @command{autoconf}. This macro checks for several known
4468 errors in implementations of @code{vfork} and considers the system to not
4469 have a working @code{vfork} if it detects any of them. It is not considered
4470 to be an implementation error if a child's invocation of @code{signal}
4471 modifies the parent's signal handler, since child processes rarely change
4472 their signal handlers.
4474 Since this macro defines @code{vfork} only for backward compatibility with
4475 previous versions of @command{autoconf} you're encouraged to define it
4476 yourself in new code:
4479 #ifndef HAVE_WORKING_VFORK
4486 @defmac AC_FUNC_FSEEKO
4487 @acindex{FUNC_FSEEKO}
4488 @cvindex _LARGEFILE_SOURCE
4490 @prindex @code{fseeko}
4491 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4492 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4493 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4494 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4495 largefile-sensitive systems where @code{off_t} does not default to a
4499 @defmac AC_FUNC_GETGROUPS
4500 @acindex{FUNC_GETGROUPS}
4501 @ovindex GETGROUPS_LIBS
4502 @c @fuindex getgroups
4503 @prindex @code{getgroups}
4504 If the @code{getgroups} function is available and works (unlike on
4505 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4506 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4507 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4510 @defmac AC_FUNC_GETLOADAVG
4511 @acindex{FUNC_GETLOADAVG}
4516 @cvindex HAVE_NLIST_H
4517 @cvindex NLIST_NAME_UNION
4518 @cvindex GETLODAVG_PRIVILEGED
4519 @cvindex NEED_SETGID
4520 @cvindex C_GETLOADAVG
4522 @ovindex NEED_SETGID
4524 @ovindex GETLOADAVG_LIBS
4525 @c @fuindex getloadavg
4526 @prindex @code{getloadavg}
4527 Check how to get the system load averages. To perform its tests
4528 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4529 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4530 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4532 If the system has the @code{getloadavg} function, define
4533 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4534 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
4535 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
4536 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4537 possibly define several other C preprocessor macros and output
4542 Define @code{C_GETLOADAVG}.
4545 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4550 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4553 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4554 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
4555 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4558 Programs may need to be installed set-group-ID (or set-user-ID) for
4559 @code{getloadavg} to work. In this case, define
4560 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4561 to @samp{true} (and otherwise to @samp{false}), and set
4562 @code{KMEM_GROUP} to the name of the group that should own the installed
4566 The @code{AC_FUNC_GETLOADVG} macro is obsolescent. New programs should
4567 use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
4570 @defmac AC_FUNC_GETMNTENT
4571 @acindex{FUNC_GETMNTENT}
4572 @cvindex HAVE_GETMNTENT
4573 @c @fuindex getmntent
4574 @prindex @code{getmntent}
4575 Check for @code{getmntent} in the standard C library, and then in the
4576 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4577 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if
4578 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4581 @defmac AC_FUNC_GETPGRP
4582 @acindex{FUNC_GETPGRP}
4583 @cvindex GETPGRP_VOID
4586 @prindex @code{getpgid}
4587 @prindex @code{getpgrp}
4588 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4589 @code{getpgrp}; this is the Posix behavior. On older @acronym{BSD}
4590 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4591 behaves like Posix's @code{getpgid}.
4601 This macro does not check whether
4602 @code{getpgrp} exists at all; if you need to work in that situation,
4603 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4605 This macro is obsolescent, as current systems have a @code{getpgrp}
4606 whose signature conforms to Posix. New programs need not use this macro.
4609 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4610 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4611 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4613 @prindex @code{lstat}
4614 If @file{link} is a symbolic link, then @code{lstat} should treat
4615 @file{link/} the same as @file{link/.}. However, many older
4616 @code{lstat} implementations incorrectly ignore trailing slashes.
4618 It is safe to assume that if @code{lstat} incorrectly ignores
4619 trailing slashes, then other symbolic-link-aware functions like
4620 @code{unlink} also incorrectly ignore trailing slashes.
4622 If @code{lstat} behaves properly, define
4623 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4624 @code{AC_LIBOBJ} replacement of @code{lstat}.
4627 @defmac AC_FUNC_MALLOC
4628 @acindex{FUNC_MALLOC}
4629 @cvindex HAVE_MALLOC
4632 @prindex @code{malloc}
4633 If the @code{malloc} function is compatible with the @acronym{GNU} C
4634 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4635 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4636 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4637 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4638 native @code{malloc} is not used in the main project.
4640 Typically, the replacement file @file{malloc.c} should look like (note
4641 the @samp{#undef malloc}):
4644 #ifdef HAVE_CONFIG_H
4645 # include <config.h>
4649 #include <sys/types.h>
4653 /* Allocate an N-byte block of memory from the heap.
4654 If N is zero, allocate a 1-byte block. */
4657 rpl_malloc (size_t n)
4666 @defmac AC_FUNC_MEMCMP
4667 @acindex{FUNC_MEMCMP}
4670 @prindex @code{memcmp}
4671 If the @code{memcmp} function is not available, or does not work on
4672 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4673 bytes or more and with at least one buffer not starting on a 4-byte
4674 boundary (such as the one on NeXT x86 OpenStep), require an
4675 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4677 This macro is obsolescent, as current systems have a working
4678 @code{memcmp}. New programs need not use this macro.
4681 @defmac AC_FUNC_MBRTOWC
4682 @acindex{FUNC_MBRTOWC}
4683 @cvindex HAVE_MBRTOWC
4685 @prindex @code{mbrtowc}
4686 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4687 type @code{mbstate_t} are properly declared.
4690 @defmac AC_FUNC_MKTIME
4691 @acindex{FUNC_MKTIME}
4694 @prindex @code{mktime}
4695 If the @code{mktime} function is not available, or does not work
4696 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4697 For the purposes of this test, @code{mktime} should conform to the
4698 Posix standard and should be the inverse of
4702 @defmac AC_FUNC_MMAP
4706 @prindex @code{mmap}
4707 If the @code{mmap} function exists and works correctly, define
4708 @code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
4712 @defmac AC_FUNC_OBSTACK
4713 @acindex{FUNC_OBSTACK}
4714 @cvindex HAVE_OBSTACK
4716 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4717 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4720 @defmac AC_FUNC_REALLOC
4721 @acindex{FUNC_REALLOC}
4722 @cvindex HAVE_REALLOC
4725 @prindex @code{realloc}
4726 If the @code{realloc} function is compatible with the @acronym{GNU} C
4727 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4728 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4729 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4730 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4731 the native @code{realloc} is not used in the main project. See
4732 @code{AC_FUNC_MALLOC} for details.
4735 @defmac AC_FUNC_SELECT_ARGTYPES
4736 @acindex{FUNC_SELECT_ARGTYPES}
4737 @cvindex SELECT_TYPE_ARG1
4738 @cvindex SELECT_TYPE_ARG234
4739 @cvindex SELECT_TYPE_ARG5
4741 @prindex @code{select}
4742 Determines the correct type to be passed for each of the
4743 @code{select} function's arguments, and defines those types
4744 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4745 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4746 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4747 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4749 This macro is obsolescent, as current systems have a @code{select} whose
4750 signature conforms to Posix. New programs need not use this macro.
4753 @defmac AC_FUNC_SETPGRP
4754 @acindex{FUNC_SETPGRP}
4755 @cvindex SETPGRP_VOID
4757 @prindex @code{setpgrp}
4758 If @code{setpgrp} takes no argument (the Posix version), define
4759 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4760 two process IDs as arguments. This macro does not check whether
4761 @code{setpgrp} exists at all; if you need to work in that situation,
4762 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4764 This macro is obsolescent, as current systems have a @code{setpgrp}
4765 whose signature conforms to Posix. New programs need not use this macro.
4768 @defmac AC_FUNC_STAT
4769 @defmacx AC_FUNC_LSTAT
4771 @acindex{FUNC_LSTAT}
4772 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4773 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4775 @prindex @code{stat}
4777 @prindex @code{lstat}
4778 Determine whether @code{stat} or @code{lstat} have the bug that it
4779 succeeds when given the zero-length file name as argument. The @code{stat}
4780 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4783 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4784 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4787 These macros are obsolescent, as no current systems have the bug.
4788 New programs need not use these macros.
4791 @defmac AC_FUNC_STRCOLL
4792 @acindex{FUNC_STRCOLL}
4793 @cvindex HAVE_STRCOLL
4795 @prindex @code{strcoll}
4796 If the @code{strcoll} function exists and works correctly, define
4797 @code{HAVE_STRCOLL}. This does a bit more than
4798 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4799 definitions of @code{strcoll} that should not be used.
4802 @defmac AC_FUNC_STRERROR_R
4803 @acindex{FUNC_STRERROR_R}
4804 @cvindex HAVE_STRERROR_R
4805 @cvindex HAVE_DECL_STRERROR_R
4806 @cvindex STRERROR_R_CHAR_P
4807 @c @fuindex strerror_r
4808 @prindex @code{strerror_r}
4809 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4810 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4811 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4812 returns an @code{int} error number. The Thread-Safe Functions option of
4813 Posix requires @code{strerror_r} to return @code{int}, but
4814 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4815 Library) return a @code{char *} value that is not necessarily equal to
4816 the buffer argument.
4819 @defmac AC_FUNC_STRFTIME
4820 @acindex{FUNC_STRFTIME}
4821 @cvindex HAVE_STRFTIME
4822 @c @fuindex strftime
4823 @prindex @code{strftime}
4824 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4825 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4827 This macro is obsolescent, as no current systems require the @file{intl}
4828 library for @code{strftime}. New programs need not use this macro.
4831 @defmac AC_FUNC_STRTOD
4832 @acindex{FUNC_STRTOD}
4835 @prindex @code{strtod}
4836 If the @code{strtod} function does not exist or doesn't work correctly,
4837 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4838 because @file{strtod.c} is likely to need @samp{pow}, set the output
4839 variable @code{POW_LIB} to the extra library needed.
4842 @defmac AC_FUNC_STRTOLD
4843 @acindex{FUNC_STRTOLD}
4844 @prindex @code{strtold}
4845 If the @code{strtold} function exists and conforms to C99, define
4846 @code{HAVE_STRTOLD}.
4849 @defmac AC_FUNC_STRNLEN
4850 @acindex{FUNC_STRNLEN}
4851 @cvindex HAVE_STRNLEN
4853 @prindex @code{strnlen}
4854 If the @code{strnlen} function is not available, or is buggy (like the one
4855 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4858 @defmac AC_FUNC_UTIME_NULL
4859 @acindex{FUNC_UTIME_NULL}
4860 @cvindex HAVE_UTIME_NULL
4862 @prindex @code{utime}
4863 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4864 the present, define @code{HAVE_UTIME_NULL}.
4866 This macro is obsolescent, as all current systems have a @code{utime}
4867 that behaves this way. New programs need not use this macro.
4870 @defmac AC_FUNC_VPRINTF
4871 @acindex{FUNC_VPRINTF}
4872 @cvindex HAVE_VPRINTF
4873 @cvindex HAVE_DOPRNT
4875 @prindex @code{vprintf}
4876 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4877 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
4878 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4879 are also available.)
4881 This macro is obsolescent, as all current systems have @code{vprintf}.
4882 New programs need not use this macro.
4885 @defmac AC_REPLACE_FNMATCH
4886 @acindex{REPLACE_FNMATCH}
4888 @prindex @code{fnmatch}
4889 @hdrindex{fnmatch.h}
4890 If the @code{fnmatch} function does not conform to Posix (see
4891 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4893 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4894 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4895 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
4896 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4897 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4898 included in place of the system @code{<fnmatch.h>}.
4900 This macro is obsolescent, as it assumes the use of particular source
4901 files. New programs should use Gnulib's @code{fnmatch-posix} module,
4902 which provides this macro along with the source files. @xref{Gnulib}.
4907 @node Generic Functions
4908 @subsection Generic Function Checks
4910 These macros are used to find functions not covered by the ``particular''
4911 test macros. If the functions might be in libraries other than the
4912 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4913 If you need to check the behavior of a function as well as find out
4914 whether it is present, you have to write your own test for
4915 it (@pxref{Writing Tests}).
4917 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4918 @acindex{CHECK_FUNC}
4919 If C function @var{function} is available, run shell commands
4920 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
4921 want to define a symbol if the function is available, consider using
4922 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
4923 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4924 standardized than C++. (@pxref{Language Choice}, for more information
4925 about selecting the language for checks.)
4928 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4929 @acindex{CHECK_FUNCS}
4930 @cvindex HAVE_@var{function}
4931 For each @var{function} enumerated in the blank-or-newline-separated argument
4932 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4933 If @var{action-if-found} is given, it is additional shell code to
4934 execute when one of the functions is found. You can give it a value of
4935 @samp{break} to break out of the loop on the first match. If
4936 @var{action-if-not-found} is given, it is executed when one of the
4937 functions is not found.
4940 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
4941 @acindex{CHECK_FUNCS_ONCE}
4942 @cvindex HAVE_@var{function}
4943 For each @var{function} enumerated in the blank-or-newline-separated argument
4944 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4945 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
4946 checking code at most once, so that @command{configure} is smaller and
4947 faster; but the checks cannot be conditionalized and are always done once,
4948 early during the @command{configure} run.
4953 Autoconf follows a philosophy that was formed over the years by those
4954 who have struggled for portability: isolate the portability issues in
4955 specific files, and then program as if you were in a Posix
4956 environment. Some functions may be missing or unfixable, and your
4957 package must be ready to replace them.
4959 Suitable replacements for many such problem functions are available from
4960 Gnulib (@pxref{Gnulib}).
4962 @defmac AC_LIBOBJ (@var{function})
4965 Specify that @samp{@var{function}.c} must be included in the executables
4966 to replace a missing or broken implementation of @var{function}.
4968 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4969 variable @code{LIBOBJS} if it is not already in, and calls
4970 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
4971 directly change @code{LIBOBJS}, since this is not traceable.
4974 @defmac AC_LIBSOURCE (@var{file})
4976 Specify that @var{file} might be needed to compile the project. If you
4977 need to know what files might be needed by a @file{configure.ac}, you
4978 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
4980 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4981 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
4982 that case, since shell variables cannot be traced statically, you must
4983 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4984 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
4985 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4986 @code{"foo"} or @code{"bar"}, you should do:
4989 AC_LIBSOURCE([foo.c])
4990 AC_LIBSOURCE([bar.c])
4991 AC_LIBOBJ([$foo_or_bar])
4995 There is usually a way to avoid this, however, and you are encouraged to
4996 simply call @code{AC_LIBOBJ} with literal arguments.
4998 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
4999 slightly different semantics: the old macro took the function name,
5000 e.g., @code{foo}, as its argument rather than the file name.
5003 @defmac AC_LIBSOURCES (@var{files})
5004 @acindex{LIBSOURCES}
5005 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
5006 comma-separated M4 list. Thus, the above example might be rewritten:
5009 AC_LIBSOURCES([foo.c, bar.c])
5010 AC_LIBOBJ([$foo_or_bar])
5014 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
5015 @acindex{CONFIG_LIBOBJ_DIR}
5016 Specify that @code{AC_LIBOBJ} replacement files are to be found in
5017 @var{directory}, a name relative to the top level of the
5018 source tree. The replacement directory defaults to @file{.}, the top
5019 level directory, and the most typical value is @file{lib}, corresponding
5020 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
5022 @command{configure} might need to know the replacement directory for the
5023 following reasons: (i) some checks use the replacement files, (ii) some
5024 macros bypass broken system headers by installing links to the
5025 replacement headers (iii) when used in conjunction with Automake,
5026 within each makefile, @var{directory} is used as a relative path
5027 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
5028 @code{LTLIBOBJS}, etc.
5033 It is common to merely check for the existence of a function, and ask
5034 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
5035 a convenient shorthand.
5037 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
5038 @acindex{REPLACE_FUNCS}
5040 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
5041 @var{action-if-not-found}. You can declare your replacement function by
5042 enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the
5043 system has the function, it probably declares it in a header file you
5044 should be including, so you shouldn't redeclare it lest your declaration
5049 @section Header Files
5050 @cindex Header, checking
5052 The following macros check for the presence of certain C header files.
5053 If there is no macro specifically defined to check for a header file you need,
5054 and you don't need to check for any special properties of
5055 it, then you can use one of the general header-file check macros.
5058 * Header Portability:: Collected knowledge on common headers
5059 * Particular Headers:: Special handling to find certain headers
5060 * Generic Headers:: How to find other headers
5063 @node Header Portability
5064 @subsection Portability of Headers
5065 @cindex Portability of headers
5066 @cindex Header portability
5068 This section tries to collect knowledge about common headers, and the
5069 problems they cause. By definition, this list always requires
5070 additions. Please help us keeping it as complete as possible.
5074 @item @file{limits.h}
5075 C99 says that @file{limits.h} defines @code{LLONG_MIN},
5076 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
5077 environments (e.g., default @acronym{GCC} 4.0.2 + glibc 2.4) do not
5080 @item @file{inttypes.h} vs.@: @file{stdint.h}
5081 @hdrindex{inttypes.h}
5083 The C99 standard says that @file{inttypes.h} includes
5084 @file{stdint.h}, so there's no need to include @file{stdint.h}
5085 separately in a standard environment. Some implementations have
5086 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
5087 know of any implementation that has @file{stdint.h} but not
5090 @item @file{linux/irda.h}
5091 @hdrindex{linux/irda.h}
5092 It requires @file{linux/types.h} and @file{sys/socket.h}.
5094 @item @file{linux/random.h}
5095 @hdrindex{linux/random.h}
5096 It requires @file{linux/types.h}.
5098 @item @file{net/if.h}
5100 On Darwin, this file requires that @file{sys/socket.h} be included
5101 beforehand. One should run:
5104 AC_CHECK_HEADERS([sys/socket.h])
5105 AC_CHECK_HEADERS([net/if.h], [], [],
5108 # include <stdlib.h>
5109 # include <stddef.h>
5111 # ifdef HAVE_STDLIB_H
5112 # include <stdlib.h>
5115 #ifdef HAVE_SYS_SOCKET_H
5116 # include <sys/socket.h>
5121 @item @file{netinet/if_ether.h}
5122 @hdrindex{netinet/if_ether.h}
5123 On Darwin, this file requires that @file{stdio.h} and
5124 @file{sys/socket.h} be included beforehand. One should run:
5127 AC_CHECK_HEADERS([sys/socket.h])
5128 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
5131 # include <stdlib.h>
5132 # include <stddef.h>
5134 # ifdef HAVE_STDLIB_H
5135 # include <stdlib.h>
5138 #ifdef HAVE_SYS_SOCKET_H
5139 # include <sys/socket.h>
5144 @item @file{stdint.h}
5145 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
5147 @item @file{stdlib.h}
5149 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
5151 @item @file{sys/mount.h}
5152 @hdrindex{sys/mount.h}
5153 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
5154 @file{sys/params.h} is a prerequisite.
5156 @item @file{sys/ptem.h}
5157 @hdrindex{sys/ptem.h}
5158 On Solaris 8, @file{sys/stream.h} is a prerequisite.
5160 @item @file{sys/socket.h}
5161 @hdrindex{sys/socket.h}
5162 On Darwin, @file{stdlib.h} is a prerequisite.
5164 @item @file{sys/ucred.h}
5165 @hdrindex{sys/ucred.h}
5166 On Tru64 5.1, @file{sys/types.h} is a prerequisite.
5168 @item @file{X11/extensions/scrnsaver.h}
5169 @hdrindex{X11/extensions/scrnsaver.h}
5170 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
5171 so required that you might not even consider looking for it.
5174 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
5175 [[#include <X11/Xlib.h>
5181 @node Particular Headers
5182 @subsection Particular Header Checks
5184 These macros check for particular system header files---whether they
5185 exist, and in some cases whether they declare certain symbols.
5187 @defmac AC_HEADER_ASSERT
5188 @acindex{HEADER_ASSERT}
5191 Check whether to enable assertions in the style of @file{assert.h}.
5192 Assertions are enabled by default, but the user can override this by
5193 invoking @command{configure} with the @option{--disable-assert} option.
5196 @defmac AC_HEADER_DIRENT
5197 @acindex{HEADER_DIRENT}
5198 @cvindex HAVE_DIRENT_H
5199 @cvindex HAVE_NDIR_H
5200 @cvindex HAVE_SYS_DIR_H
5201 @cvindex HAVE_SYS_NDIR_H
5203 @hdrindex{sys/ndir.h}
5204 @hdrindex{sys/dir.h}
5206 Check for the following header files. For the first one that is
5207 found and defines @samp{DIR}, define the listed C preprocessor macro:
5209 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5210 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
5211 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5212 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
5213 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
5216 The directory-library declarations in your source code should look
5217 something like the following:
5221 #include <sys/types.h>
5222 #ifdef HAVE_DIRENT_H
5223 # include <dirent.h>
5224 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5226 # define dirent direct
5227 # define NAMLEN(dirent) ((dirent)->d_namlen)
5228 # ifdef HAVE_SYS_NDIR_H
5229 # include <sys/ndir.h>
5231 # ifdef HAVE_SYS_DIR_H
5232 # include <sys/dir.h>
5241 Using the above declarations, the program would declare variables to be
5242 of type @code{struct dirent}, not @code{struct direct}, and would access
5243 the length of a directory entry name by passing a pointer to a
5244 @code{struct dirent} to the @code{NAMLEN} macro.
5246 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5248 This macro is obsolescent, as all current systems with directory
5249 libraries have @code{<dirent.h>}. New programs need not use this macro.
5251 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5252 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5255 @defmac AC_HEADER_MAJOR
5256 @acindex{HEADER_MAJOR}
5257 @cvindex MAJOR_IN_MKDEV
5258 @cvindex MAJOR_IN_SYSMACROS
5259 @hdrindex{sys/mkdev.h}
5260 @hdrindex{sys/sysmacros.h}
5261 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5262 @code{makedev}, but @file{sys/mkdev.h} does, define
5263 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5264 @code{MAJOR_IN_SYSMACROS}.
5267 @defmac AC_HEADER_RESOLV
5268 @acindex{HEADER_RESOLV}
5269 @cvindex HAVE_RESOLV_H
5271 Checks for header @file{resolv.h}, checking for prerequisites first.
5272 To properly use @file{resolv.h}, your code should contain something like
5276 #ifdef HAVE_SYS_TYPES_H
5277 # include <sys/types.h>
5279 #ifdef HAVE_NETINET_IN_H
5280 # include <netinet/in.h> /* inet_ functions / structs */
5282 #ifdef HAVE_ARPA_NAMESER_H
5283 # include <arpa/nameser.h> /* DNS HEADER struct */
5292 @defmac AC_HEADER_STAT
5293 @acindex{HEADER_STAT}
5294 @cvindex STAT_MACROS_BROKEN
5295 @hdrindex{sys/stat.h}
5296 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5297 @file{sys/stat.h} do not work properly (returning false positives),
5298 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
5299 Amdahl UTS and Motorola System V/88.
5301 This macro is obsolescent, as no current systems have the bug.
5302 New programs need not use this macro.
5305 @defmac AC_HEADER_STDBOOL
5306 @acindex{HEADER_STDBOOL}
5307 @cvindex HAVE_STDBOOL_H
5309 @hdrindex{stdbool.h}
5311 If @file{stdbool.h} exists and conforms to C99, define
5312 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5313 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
5314 @file{system.h} could contain the following code:
5317 #ifdef HAVE_STDBOOL_H
5318 # include <stdbool.h>
5324 # define _Bool signed char
5330 # define __bool_true_false_are_defined 1
5334 Alternatively you can use the @samp{stdbool} package of Gnulib
5335 (@pxref{Gnulib}); it packages the above code into a replacement header
5336 and contains a few other bells and whistles.
5341 @defmac AC_HEADER_STDC
5342 @acindex{HEADER_STDC}
5343 @cvindex STDC_HEADERS
5349 Define @code{STDC_HEADERS} if the system has C header files
5350 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5351 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5352 @file{string.h}, and @file{float.h}; if the system has those, it
5353 probably has the rest of the C89 header files. This macro also
5354 checks whether @file{string.h} declares @code{memchr} (and thus
5355 presumably the other @code{mem} functions), whether @file{stdlib.h}
5356 declare @code{free} (and thus presumably @code{malloc} and other related
5357 functions), and whether the @file{ctype.h} macros work on characters
5358 with the high bit set, as the C standard requires.
5360 If you use this macro, your code can refer to @code{STDC_HEADERS} to
5361 determine whether the system has conforming header files (and probably C
5364 This macro is obsolescent, as current systems have conforming header
5365 files. New programs need not use this macro.
5368 @hdrindex{strings.h}
5369 Nowadays @file{string.h} is part of the C standard and declares functions like
5370 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5371 @acronym{BSD} functions like @code{bcopy}; but
5372 historically, string functions were a major sticking point in this area.
5373 If you still want to worry about portability to ancient systems without
5374 standard headers, there is so much variation
5375 that it is probably easier to declare the functions you use than to
5376 figure out exactly what the system header files declare. Some ancient systems
5377 contained a mix of functions from the C standard and from @acronym{BSD};
5378 some were mostly standard but lacked @samp{memmove}; some defined the
5379 @acronym{BSD} functions as macros in @file{string.h} or
5380 @file{strings.h}; some had only the @acronym{BSD} functions but
5381 @file{string.h}; some declared the memory functions in @file{memory.h},
5382 some in @file{string.h}; etc. It is probably sufficient to check for
5383 one string function and one memory function; if the library had the
5384 standard versions of those then it probably had most of the others.
5385 If you put the following in @file{configure.ac}:
5388 # This example is obsolescent.
5389 # Nowadays you can omit these macro calls.
5391 AC_CHECK_FUNCS([strchr memcpy])
5395 then, in your code, you can use declarations like this:
5399 /* This example is obsolescent.
5400 Nowadays you can just #include <string.h>. */
5402 # include <string.h>
5404 # ifndef HAVE_STRCHR
5405 # define strchr index
5406 # define strrchr rindex
5408 char *strchr (), *strrchr ();
5409 # ifndef HAVE_MEMCPY
5410 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5411 # define memmove(d, s, n) bcopy ((s), (d), (n))
5418 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5419 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros don't
5420 suffice to port to ancient hosts; you must provide an implementation of
5421 each function. An easy
5422 way to incorporate your implementations only when needed (since the ones
5423 in system C libraries may be hand optimized) is to, taking @code{memchr}
5424 for example, put it in @file{memchr.c} and use
5425 @samp{AC_REPLACE_FUNCS([memchr])}.
5428 @defmac AC_HEADER_SYS_WAIT
5429 @acindex{HEADER_SYS_WAIT}
5430 @cvindex HAVE_SYS_WAIT_H
5431 @hdrindex{sys/wait.h}
5432 If @file{sys/wait.h} exists and is compatible with Posix, define
5433 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
5434 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5435 of @code{int} to store a status value. If @file{sys/wait.h} is not
5436 Posix compatible, then instead of including it, define the
5437 Posix macros with their usual interpretations. Here is an
5442 #include <sys/types.h>
5443 #ifdef HAVE_SYS_WAIT_H
5444 # include <sys/wait.h>
5447 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5450 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5456 This macro is obsolescent, as current systems are compatible with Posix.
5457 New programs need not use this macro.
5460 @cvindex _POSIX_VERSION
5462 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5463 Posix systems. If there is no @file{unistd.h}, it is definitely
5464 not a Posix system. However, some non-Posix systems do
5465 have @file{unistd.h}.
5467 The way to check whether the system supports Posix is:
5471 #ifdef HAVE_UNISTD_H
5472 # include <sys/types.h>
5473 # include <unistd.h>
5476 #ifdef _POSIX_VERSION
5477 /* Code for Posix systems. */
5482 @defmac AC_HEADER_TIME
5483 @acindex{HEADER_TIME}
5484 @cvindex TIME_WITH_SYS_TIME
5486 @hdrindex{sys/time.h}
5487 If a program may include both @file{time.h} and @file{sys/time.h},
5488 define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
5489 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not
5490 protected against multiple inclusion, so programs could not explicitly
5491 include both files. This macro is useful in programs that use, for
5492 example, @code{struct timeval} as well as
5493 @code{struct tm}. It is best used in conjunction with
5494 @code{HAVE_SYS_TIME_H}, which can be checked for using
5495 @code{AC_CHECK_HEADERS([sys/time.h])}.
5499 #ifdef TIME_WITH_SYS_TIME
5500 # include <sys/time.h>
5503 # ifdef HAVE_SYS_TIME_H
5504 # include <sys/time.h>
5513 This macro is obsolescent, as current systems can include both files
5514 when they exist. New programs need not use this macro.
5518 @defmac AC_HEADER_TIOCGWINSZ
5519 @acindex{HEADER_TIOCGWINSZ}
5520 @cvindex GWINSZ_IN_SYS_IOCTL
5521 @hdrindex{sys/ioctl.h}
5522 @hdrindex{termios.h}
5523 @c FIXME: I need clarifications from Jim.
5524 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5525 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
5526 found in @file{<termios.h>}.
5532 #ifdef HAVE_TERMIOS_H
5533 # include <termios.h>
5536 #ifdef GWINSZ_IN_SYS_IOCTL
5537 # include <sys/ioctl.h>
5543 @node Generic Headers
5544 @subsection Generic Header Checks
5546 These macros are used to find system header files not covered by the
5547 ``particular'' test macros. If you need to check the contents of a header
5548 as well as find out whether it is present, you have to write your own
5549 test for it (@pxref{Writing Tests}).
5551 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5552 @acindex{CHECK_HEADER}
5553 If the system header file @var{header-file} is compilable, execute shell
5554 commands @var{action-if-found}, otherwise execute
5555 @var{action-if-not-found}. If you just want to define a symbol if the
5556 header file is available, consider using @code{AC_CHECK_HEADERS}
5559 For compatibility issues with older versions of Autoconf, please read
5563 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5564 @acindex{CHECK_HEADERS}
5565 @cvindex HAVE_@var{header}
5566 For each given system header file @var{header-file} in the
5567 blank-separated argument list that exists, define
5568 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
5569 is given, it is additional shell code to execute when one of the header
5570 files is found. You can give it a value of @samp{break} to break out of
5571 the loop on the first match. If @var{action-if-not-found} is given, it
5572 is executed when one of the header files is not found.
5574 For compatibility issues with older versions of Autoconf, please read
5578 Previous versions of Autoconf merely checked whether the header was
5579 accepted by the preprocessor. This was changed because the old test was
5580 inappropriate for typical uses. Headers are typically used to compile,
5581 not merely to preprocess, and the old behavior sometimes accepted
5582 headers that clashed at compile-time. If you need to check whether a
5583 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5584 (@pxref{Running the Preprocessor}).
5586 This scheme, which improves the robustness of the test, also requires
5587 that you make sure that headers that must be included before the
5588 @var{header-file} be part of the @var{includes}, (@pxref{Default
5589 Includes}). If looking for @file{bar.h}, which requires that
5590 @file{foo.h} be included before if it exists, we suggest the following
5594 AC_CHECK_HEADERS([foo.h])
5595 AC_CHECK_HEADERS([bar.h], [], [],
5602 The following variant generates smaller, faster @command{configure}
5603 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5605 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5606 @acindex{CHECK_HEADERS_ONCE}
5607 @cvindex HAVE_@var{header}
5608 For each given system header file @var{header-file} in the
5609 blank-separated argument list that exists, define
5610 @code{HAVE_@var{header-file}} (in all capitals).
5611 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
5612 checking code at most once, so that @command{configure} is smaller and
5613 faster; but the checks cannot be conditionalized and are always done once,
5614 early during the @command{configure} run.
5618 @section Declarations
5619 @cindex Declaration, checking
5621 The following macros check for the declaration of variables and
5622 functions. If there is no macro specifically defined to check for a
5623 symbol you need, then you can use the general macros (@pxref{Generic
5624 Declarations}) or, for more complex tests, you may use
5625 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5628 * Particular Declarations:: Macros to check for certain declarations
5629 * Generic Declarations:: How to find other declarations
5632 @node Particular Declarations
5633 @subsection Particular Declaration Checks
5635 There are no specific macros for declarations.
5637 @node Generic Declarations
5638 @subsection Generic Declaration Checks
5640 These macros are used to find declarations not covered by the ``particular''
5643 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5644 @acindex{CHECK_DECL}
5645 If @var{symbol} (a function, variable, or constant) is not declared in
5646 @var{includes} and a declaration is needed, run the shell commands
5647 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
5648 @var{includes} are specified, the default includes are used
5649 (@pxref{Default Includes}).
5651 This macro actually tests whether @var{symbol} is defined as a macro or
5652 can be used as an r-value, not whether it is really declared, because it
5653 is much safer to avoid
5654 introducing extra declarations when they are not needed.
5657 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5658 @acindex{CHECK_DECLS}
5659 @cvindex HAVE_DECL_@var{symbol}
5660 For each of the @var{symbols} (@emph{comma}-separated list), define
5661 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5662 @var{symbol} is declared, otherwise to @samp{0}. If
5663 @var{action-if-not-found} is given, it is additional shell code to
5664 execute when one of the function declarations is needed, otherwise
5665 @var{action-if-found} is executed.
5667 This macro uses an M4 list as first argument:
5669 AC_CHECK_DECLS([strdup])
5670 AC_CHECK_DECLS([strlen])
5671 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5674 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5675 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5676 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
5677 @emph{sure} that the check was performed, use
5678 @code{HAVE_DECL_@var{symbol}} in @code{#if}:
5681 #if !HAVE_DECL_SYMBOL
5682 extern char *symbol;
5687 If the test may have not been performed, however, because it is safer
5688 @emph{not} to declare a symbol than to use a declaration that conflicts
5689 with the system's one, you should use:
5692 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5693 void *malloc (size_t *s);
5698 You fall into the second category only in extreme situations: either
5699 your files may be used without being configured, or they are used during
5700 the configuration. In most cases the traditional approach is enough.
5703 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5704 @acindex{CHECK_DECLS_ONCE}
5705 @cvindex HAVE_DECL_@var{symbol}
5706 For each of the @var{symbols} (@emph{comma}-separated list), define
5707 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5708 @var{symbol} is declared in the default include files, otherwise to
5709 @samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
5710 generates the checking code at most once, so that @command{configure} is
5711 smaller and faster; but the checks cannot be conditionalized and are
5712 always done once, early during the @command{configure} run.
5718 @cindex Structure, checking
5720 The following macros check for the presence of certain members in C
5721 structures. If there is no macro specifically defined to check for a
5722 member you need, then you can use the general structure-member macros
5723 (@pxref{Generic Structures}) or, for more complex tests, you may use
5724 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5727 * Particular Structures:: Macros to check for certain structure members
5728 * Generic Structures:: How to find other structure members
5731 @node Particular Structures
5732 @subsection Particular Structure Checks
5734 The following macros check for certain structures or structure members.
5736 @defmac AC_STRUCT_DIRENT_D_INO
5737 @acindex{STRUCT_DIRENT_D_INO}
5738 @cvindex HAVE_STRUCT_DIRENT_D_INO
5739 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5740 Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
5741 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5743 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5744 @code{d_ino}, not whether its contents are always reliable.
5745 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5746 though current systems hide this detail from the user and never return
5747 zero @code{d_ino} values.
5748 Many current systems report an incorrect @code{d_ino} for a directory
5749 entry that is a mount point.
5752 @defmac AC_STRUCT_DIRENT_D_TYPE
5753 @acindex{STRUCT_DIRENT_D_TYPE}
5754 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5755 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5756 Headers}). Then, if @code{struct dirent} contains a @code{d_type}
5757 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5760 @defmac AC_STRUCT_ST_BLKSIZE
5761 @acindex{STRUCT_ST_BLKSIZE}
5762 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5763 @cvindex HAVE_ST_BLKSIZE
5764 If @code{struct stat} contains an @code{st_blksize} member, define
5765 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
5766 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5767 the future. This macro is obsoleted, and should be replaced by
5770 AC_CHECK_MEMBERS([struct stat.st_blksize])
5774 @defmac AC_STRUCT_ST_BLOCKS
5775 @acindex{STRUCT_ST_BLOCKS}
5776 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5777 @cvindex HAVE_ST_BLOCKS
5779 If @code{struct stat} contains an @code{st_blocks} member, define
5780 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5781 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5782 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5786 @defmac AC_STRUCT_ST_RDEV
5787 @acindex{STRUCT_ST_RDEV}
5788 @cvindex HAVE_ST_RDEV
5789 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5790 If @code{struct stat} contains an @code{st_rdev} member, define
5791 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
5792 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5793 in the future. Actually, even the new macro is obsolete and should be
5796 AC_CHECK_MEMBERS([struct stat.st_rdev])
5800 @defmac AC_STRUCT_TM
5802 @cvindex TM_IN_SYS_TIME
5804 @hdrindex{sys/time.h}
5805 If @file{time.h} does not define @code{struct tm}, define
5806 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5807 had better define @code{struct tm}.
5809 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
5810 current systems. New programs need not use this macro.
5813 @defmac AC_STRUCT_TIMEZONE
5814 @acindex{STRUCT_TIMEZONE}
5815 @cvindex HAVE_TM_ZONE
5816 @cvindex HAVE_TZNAME
5817 Figure out how to get the current timezone. If @code{struct tm} has a
5818 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5819 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5820 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5821 define @code{HAVE_DECL_TZNAME}.
5824 @node Generic Structures
5825 @subsection Generic Structure Checks
5827 These macros are used to find structure members not covered by the
5828 ``particular'' test macros.
5830 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5831 @acindex{CHECK_MEMBER}
5832 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5833 If no @var{includes} are specified, the default includes are used
5834 (@pxref{Default Includes}).
5837 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5838 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5842 You can use this macro for submembers:
5845 AC_CHECK_MEMBER(struct top.middle.bot)
5849 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5850 @acindex{CHECK_MEMBERS}
5851 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5852 @var{members} using the previous macro. When @var{member} belongs to
5853 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5854 capitals, with spaces and dots replaced by underscores). If
5855 @var{action-if-found} is given, it is executed for each of the found
5856 members. If @var{action-if-not-found} is given, it is executed for each
5857 of the members that could not be found.
5859 This macro uses M4 lists:
5861 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5871 The following macros check for C types, either builtin or typedefs. If
5872 there is no macro specifically defined to check for a type you need, and
5873 you don't need to check for any special properties of it, then you can
5874 use a general type-check macro.
5877 * Particular Types:: Special handling to find certain types
5878 * Generic Types:: How to find other types
5881 @node Particular Types
5882 @subsection Particular Type Checks
5884 @hdrindex{sys/types.h}
5887 @hdrindex{inttypes.h}
5888 These macros check for particular C types in @file{sys/types.h},
5889 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
5892 The Gnulib @code{stdint} module is an alternate way to define many of
5893 these symbols; it is useful if you prefer your code to assume a
5894 C99-or-better environment. @xref{Gnulib}.
5896 @defmac AC_TYPE_GETGROUPS
5897 @acindex{TYPE_GETGROUPS}
5898 @cvindex GETGROUPS_T
5899 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5900 is the base type of the array argument to @code{getgroups}.
5903 @defmac AC_TYPE_INT8_T
5904 @acindex{TYPE_INT8_T}
5905 @cvindex HAVE_INT8_T
5907 If @file{stdint.h} or @file{inttypes.h} defines the type @code{int8_t},
5908 define @code{HAVE_INT8_T}. Otherwise, define @code{int8_t} to a signed
5909 integer type that is exactly 8 bits wide and that uses two's complement
5910 representation, if such a type exists.
5913 @defmac AC_TYPE_INT16_T
5914 @acindex{TYPE_INT16_T}
5915 @cvindex HAVE_INT16_T
5917 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
5920 @defmac AC_TYPE_INT32_T
5921 @acindex{TYPE_INT32_T}
5922 @cvindex HAVE_INT32_T
5924 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
5927 @defmac AC_TYPE_INT64_T
5928 @acindex{TYPE_INT64_T}
5929 @cvindex HAVE_INT64_T
5931 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
5934 @defmac AC_TYPE_INTMAX_T
5935 @acindex{TYPE_INTMAX_T}
5936 @cvindex HAVE_INTMAX_T
5938 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
5939 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
5940 widest signed integer type.
5943 @defmac AC_TYPE_INTPTR_T
5944 @acindex{TYPE_INTPTR_T}
5945 @cvindex HAVE_INTPTR_T
5947 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
5948 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
5949 signed integer type wide enough to hold a pointer, if such a type
5953 @defmac AC_TYPE_LONG_DOUBLE
5954 @acindex{TYPE_LONG_DOUBLE}
5955 @cvindex HAVE_LONG_DOUBLE
5956 If the C compiler supports a working @code{long double} type, define
5957 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
5958 same range and precision as @code{double}.
5961 @defmac AC_TYPE_LONG_DOUBLE_WIDER
5962 @acindex{TYPE_LONG_DOUBLE_WIDER}
5963 @cvindex HAVE_LONG_DOUBLE_WIDER
5964 If the C compiler supports a working @code{long double} type with more
5965 range or precision than the @code{double} type, define
5966 @code{HAVE_LONG_DOUBLE_WIDER}.
5969 @defmac AC_TYPE_LONG_LONG_INT
5970 @acindex{TYPE_LONG_LONG_INT}
5971 @cvindex HAVE_LONG_LONG_INT
5972 If the C compiler supports a working @code{long long int} type, define
5973 @code{HAVE_LONG_LONG_INT}.
5976 @defmac AC_TYPE_MBSTATE_T
5977 @acindex{TYPE_MBSTATE_T}
5980 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5981 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
5982 @code{<wchar.h>} does not declare it.
5985 @defmac AC_TYPE_MODE_T
5986 @acindex{TYPE_MODE_T}
5988 Define @code{mode_t} to a suitable type, if standard headers do not
5992 @defmac AC_TYPE_OFF_T
5993 @acindex{TYPE_OFF_T}
5995 Define @code{off_t} to a suitable type, if standard headers do not
5999 @defmac AC_TYPE_PID_T
6000 @acindex{TYPE_PID_T}
6002 Define @code{pid_t} to a suitable type, if standard headers do not
6006 @defmac AC_TYPE_SIGNAL
6007 @acindex{TYPE_SIGNAL}
6010 If @file{signal.h} declares @code{signal} as returning a pointer to a
6011 function returning @code{void}, define @code{RETSIGTYPE} to be
6012 @code{void}; otherwise, define it to be @code{int}.
6014 Define signal handlers as returning type @code{RETSIGTYPE}:
6027 @defmac AC_TYPE_SIZE_T
6028 @acindex{TYPE_SIZE_T}
6030 Define @code{size_t} to a suitable type, if standard headers do not
6034 @defmac AC_TYPE_SSIZE_T
6035 @acindex{TYPE_SSIZE_T}
6037 Define @code{ssize_t} to a suitable type, if standard headers do not
6041 @defmac AC_TYPE_UID_T
6042 @acindex{TYPE_UID_T}
6045 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6046 headers do not define them.
6049 @defmac AC_TYPE_UINT8_T
6050 @acindex{TYPE_UINT8_T}
6051 @cvindex HAVE_UINT8_T
6053 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uint8_t},
6054 define @code{HAVE_UINT8_T}. Otherwise, define @code{uint8_t} to an
6055 unsigned integer type that is exactly 8 bits wide, if such a type
6059 @defmac AC_TYPE_UINT16_T
6060 @acindex{TYPE_UINT16_T}
6061 @cvindex HAVE_UINT16_T
6063 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit unsigned integers.
6066 @defmac AC_TYPE_UINT32_T
6067 @acindex{TYPE_UINT32_T}
6068 @cvindex HAVE_UINT32_T
6070 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit unsigned integers.
6073 @defmac AC_TYPE_UINT64_T
6074 @acindex{TYPE_UINT64_T}
6075 @cvindex HAVE_UINT64_T
6077 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit unsigned integers.
6080 @defmac AC_TYPE_UINTMAX_T
6081 @acindex{TYPE_UINTMAX_T}
6082 @cvindex HAVE_UINTMAX_T
6084 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6085 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
6086 widest unsigned integer type.
6089 @defmac AC_TYPE_UINTPTR_T
6090 @acindex{TYPE_UINTPTR_T}
6091 @cvindex HAVE_UINTPTR_T
6093 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6094 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
6095 unsigned integer type wide enough to hold a pointer, if such a type
6099 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6100 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6101 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6102 If the C compiler supports a working @code{unsigned long long int} type,
6103 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
6107 @subsection Generic Type Checks
6109 These macros are used to check for types not covered by the ``particular''
6112 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6113 @acindex{CHECK_TYPE}
6114 Check whether @var{type} is defined. It may be a compiler builtin type
6115 or defined by the @var{includes} (@pxref{Default Includes}).
6119 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6120 @acindex{CHECK_TYPES}
6121 For each @var{type} of the @var{types} that is defined, define
6122 @code{HAVE_@var{type}} (in all capitals). If no @var{includes} are
6123 specified, the default includes are used (@pxref{Default Includes}). If
6124 @var{action-if-found} is given, it is additional shell code to execute
6125 when one of the types is found. If @var{action-if-not-found} is given,
6126 it is executed when one of the types is not found.
6128 This macro uses M4 lists:
6130 AC_CHECK_TYPES([ptrdiff_t])
6131 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6136 Autoconf, up to 2.13, used to provide to another version of
6137 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
6138 compatibility, a simple heuristics, quite safe but not totally, is
6139 implemented. In case of doubt, read the documentation of the former
6140 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6143 @node Compilers and Preprocessors
6144 @section Compilers and Preprocessors
6146 @cindex Preprocessors
6149 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6150 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6151 the output of the compiler, typically to the empty string if
6152 Posix and @samp{.exe} if a @acronym{DOS} variant.
6155 They also define the output variable @code{OBJEXT} based on the
6156 output of the compiler, after @file{.c} files have been excluded, typically
6157 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
6159 If the compiler being used does not produce executables, the tests fail. If
6160 the executables can't be run, and cross-compilation is not enabled, they
6161 fail too. @xref{Manual Configuration}, for more on support for cross
6165 * Specific Compiler Characteristics:: Some portability issues
6166 * Generic Compiler Characteristics:: Language independent tests and features
6167 * C Compiler:: Checking its characteristics
6168 * C++ Compiler:: Likewise
6169 * Objective C Compiler:: Likewise
6170 * Erlang Compiler and Interpreter:: Likewise
6171 * Fortran Compiler:: Likewise
6174 @node Specific Compiler Characteristics
6175 @subsection Specific Compiler Characteristics
6177 Some compilers exhibit different behaviors.
6180 @item Static/Dynamic Expressions
6181 Autoconf relies on a trick to extract one bit of information from the C
6182 compiler: using negative array sizes. For instance the following
6183 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6187 static int test_array[sizeof (int) == 4 ? 1 : -1];
6191 To our knowledge, there is a single compiler that does not support this
6192 trick: the @acronym{HP} C compilers (the real ones, not only the ``bundled'') on
6193 @acronym{HP-UX} 11.00.
6194 They incorrectly reject the above program with the diagnostic
6195 ``Variable-length arrays cannot have static storage.''
6196 This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)},
6197 not from the @code{? 1 : -1}, and
6198 Autoconf works around this problem by casting @code{sizeof (int)} to
6199 @code{long int} before comparing it.
6202 @node Generic Compiler Characteristics
6203 @subsection Generic Compiler Characteristics
6205 @defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
6206 @acindex{CHECK_SIZEOF}
6207 Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
6208 size in bytes of @var{type}. If @samp{type} is unknown, it gets a size
6209 of 0. If no @var{includes} are specified, the default includes are used
6210 (@pxref{Default Includes}).
6212 This macro now works even when cross-compiling. The @var{unused}
6213 argument was used when cross-compiling.
6215 For example, the call
6218 AC_CHECK_SIZEOF([int *])
6222 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6225 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6226 @acindex{CHECK_ALIGNOF}
6227 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6228 alignment in bytes of @var{type}. If @samp{type} is unknown, it gets a size
6229 of 0. If no @var{includes} are specified, the default includes are used
6230 (@pxref{Default Includes}).
6233 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @dvar{includes, default-includes}, @ovar{action-if-fails})
6234 @acindex{COMPUTE_INT}
6235 Store into the shell variable @var{var} the value of the integer
6236 @var{expression}. The
6237 value should fit in an initializer in a C variable of type @code{signed
6238 long}. To support cross compilation (in which case, the macro only works on
6239 hosts that use twos-complement arithmetic), it should be possible to evaluate
6240 the expression at compile-time. If no @var{includes} are specified, the default
6241 includes are used (@pxref{Default Includes}).
6243 Execute @var{action-if-fails} if the value cannot be determined correctly.
6246 @defmac AC_LANG_WERROR
6247 @acindex{LANG_WERROR}
6248 Normally Autoconf ignores warnings generated by the compiler, linker, and
6249 preprocessor. If this macro is used, warnings count as fatal
6250 errors for the current language. This macro is useful when the
6251 results of configuration are used where warnings are unacceptable; for
6252 instance, if parts of a program are built with the @acronym{GCC}
6254 option. If the whole program is built using @option{-Werror} it is
6255 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6260 @subsection C Compiler Characteristics
6262 The following macros provide ways to find and exercise a C Compiler.
6263 There are a few constructs that ought to be avoided, but do not deserve
6264 being checked for, since they can easily be worked around.
6267 @item Don't use lines containing solitary backslashes
6268 They tickle a bug in the @acronym{HP-UX} C compiler (checked on
6269 @acronym{HP-UX} 10.20,
6270 11.00, and 11i). When given the following source:
6275 * A comment with backslash-newlines in it. %@{ %@} *\
6279 " A string with backslash-newlines in it %@{ %@} \\
6281 char apostrophe = '\\
6289 the compiler incorrectly fails with the diagnostics ``Non-terminating
6290 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6291 Removing the lines with solitary backslashes solves the problem.
6293 @item Don't compile several files at once if output matters to you
6294 Some compilers, such as @acronym{HP}'s, report names of files being
6295 compiled when given more than one file operand. For instance:
6304 This can cause problems if you observe the output of the compiler to
6305 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6306 b.o} solves the issue.
6308 @item Don't rely on @code{#error} failing
6309 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6310 simply emits a diagnostic and continues, exiting successfully. So,
6311 instead of an error directive like @code{#error "Unsupported word size"}
6312 it is more portable to use an invalid directive like @code{#Unsupported
6313 word size} in Autoconf tests. In ordinary source code, @code{#error} is
6314 OK, since installers with inadequate compilers like @sc{irix} can simply
6315 examine these compilers' diagnostic output.
6317 @item Don't rely on correct @code{#line} support
6318 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
6319 diagnoses @code{#line} directives whose line
6320 numbers are greater than 32767. Nothing in Posix
6321 makes this invalid. That is why Autoconf stopped issuing
6322 @code{#line} directives.
6325 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6329 Determine a C compiler to use. If @code{CC} is not already set in the
6330 environment, check for @code{gcc} and @code{cc}, then for other C
6331 compilers. Set output variable @code{CC} to the name of the compiler
6334 This macro may, however, be invoked with an optional first argument
6335 which, if specified, must be a blank-separated list of C compilers to
6336 search for. This just gives the user an opportunity to specify an
6337 alternative search list for the C compiler. For example, if you didn't
6338 like the default order, then you could invoke @code{AC_PROG_CC} like
6342 AC_PROG_CC([gcc cl cc])
6345 If the C compiler does not handle function prototypes correctly by
6346 default, try to add an option to output variable @code{CC} to make it
6347 so. This macro tries various options that select standard-conformance
6348 modes on various systems.
6350 After calling this macro you can check whether the C compiler has been
6351 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6353 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
6354 @code{AC_C_PROTOTYPES} below.
6356 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6357 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
6358 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6359 where @acronym{GCC} does not accept @option{-g}), or @option{-g} for
6363 @defmac AC_PROG_CC_C_O
6364 @acindex{PROG_CC_C_O}
6365 @cvindex NO_MINUS_C_MINUS_O
6366 If the C compiler does not accept the @option{-c} and @option{-o} options
6367 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
6368 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6369 the first @code{cc} in the path. The test fails if one fails. This
6370 macro was created for @acronym{GNU} Make to choose the default C compilation
6378 Set output variable @code{CPP} to a command that runs the
6379 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6380 It is only portable to run @code{CPP} on files with a @file{.c}
6383 Some preprocessors don't indicate missing include files by the error
6384 status. For such preprocessors an internal variable is set that causes
6385 other macros to check the standard error from the preprocessor and
6386 consider the test failed if any warnings have been reported.
6387 For most preprocessors, though, warnings do not cause include-file
6388 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6391 @defmac AC_PROG_CPP_WERROR
6392 @acindex{PROG_CPP_WERROR}
6394 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6395 preprocessor as errors even if the preprocessor exit status indicates
6396 success. This is useful for avoiding headers that generate mandatory
6397 warnings, such as deprecation notices.
6401 The following macros check for C compiler or machine architecture
6402 features. To check for characteristics not listed here, use
6403 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6404 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6406 @defmac AC_PROG_CC_STDC
6407 @acindex{PROG_CC_STDC}
6408 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6409 C99), try to add an option to output variable @code{CC} to make it work.
6410 If the compiler does not support C99, fall back to supporting
6411 @acronym{ANSI} C89 (@acronym{ISO} C90).
6413 After calling this macro you can check whether the C compiler has been
6414 set to accept Standard C; if not, the shell variable
6415 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6418 @defmac AC_PROG_CC_C89
6419 @acindex{PROG_CC_C89}
6420 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6421 default, try to add an option to output variable @code{CC} to make it
6422 so. This macro tries various options that select @acronym{ANSI} C89 on
6423 some system or another. It considers the compiler to be in
6424 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6426 After calling this macro you can check whether the C compiler has been
6427 set to accept @acronym{ANSI} C89; if not, the shell variable
6428 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6430 This macro is called automatically by @code{AC_PROG_CC}.
6433 @defmac AC_PROG_CC_C99
6434 @acindex{PROG_CC_C99}
6435 If the C compiler is not in C99 mode by default, try to add an
6436 option to output variable @code{CC} to make it so. This macro tries
6437 various options that select C99 on some system or another. It
6438 considers the compiler to be in C99 mode if it handles @code{_Bool},
6439 @code{//} comments, flexible array members, @code{inline}, @code{long
6440 long int}, mixed code and declarations, named initialization of structs,
6441 @code{restrict}, @code{va_copy}, varargs macros, variable declarations
6442 in @code{for} loops, and variable length arrays.
6444 After calling this macro you can check whether the C compiler has been
6445 set to accept C99; if not, the shell variable
6446 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6449 @defmac AC_C_BACKSLASH_A
6450 @acindex{HAVE_C_BACKSLASH_A}
6451 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6454 This macro is obsolescent, as current C compilers understand @samp{\a}.
6455 New programs need not use this macro.
6458 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
6459 @acindex{C_BIGENDIAN}
6460 @cvindex WORDS_BIGENDIAN
6462 If words are stored with the most significant byte first (like Motorola
6463 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
6464 the least significant byte first (like Intel and VAX CPUs), execute
6465 @var{action-if-false}.
6467 This macro runs a test-case if endianness cannot be determined from the
6468 system header files. When cross-compiling, the test-case is not run but
6469 grep'ed for some magic values. @var{action-if-unknown} is executed if
6470 the latter case fails to determine the byte sex of the host system.
6472 The default for @var{action-if-true} is to define
6473 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
6474 nothing. And finally, the default for @var{action-if-unknown} is to
6475 abort configure and tell the installer which variable he should preset
6476 to bypass this test.
6482 If the C compiler does not fully support the @code{const} keyword,
6483 define @code{const} to be empty. Some C compilers that do
6484 not define @code{__STDC__} do support @code{const}; some compilers that
6485 define @code{__STDC__} do not completely support @code{const}. Programs
6486 can simply use @code{const} as if every C compiler supported it; for
6487 those that don't, the makefile or configuration header file
6488 defines it as empty.
6490 Occasionally installers use a C++ compiler to compile C code, typically
6491 because they lack a C compiler. This causes problems with @code{const},
6492 because C and C++ treat @code{const} differently. For example:
6499 is valid in C but not in C++. These differences unfortunately cannot be
6500 papered over by defining @code{const} to be empty.
6502 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6503 as this generally yields better results in practice. However, using a
6504 C++ compiler to compile C code is not recommended or supported, and
6505 installers who run into trouble in this area should get a C compiler
6506 like @acronym{GCC} to compile their C code.
6508 This macro is obsolescent, as current C compilers support @code{const}.
6509 New programs need not use this macro.
6512 @defmac AC_C_RESTRICT
6513 @acindex{C_RESTRICT}
6515 If the C compiler recognizes the @code{restrict} keyword, don't do anything.
6516 If it recognizes only a variant spelling (@code{__restrict},
6517 @code{__restrict__}, or @code{_Restrict}), then define
6518 @code{restrict} to that.
6519 Otherwise, define @code{restrict} to be empty.
6520 Thus, programs may simply use @code{restrict} as if every C compiler
6521 supported it; for those that do not, the makefile
6522 or configuration header defines it away.
6524 Although support in C++ for the @code{restrict} keyword is not
6525 required, several C++ compilers do accept the keyword.
6526 This macro works for them, too.
6529 @defmac AC_C_VOLATILE
6530 @acindex{C_VOLATILE}
6532 If the C compiler does not understand the keyword @code{volatile},
6533 define @code{volatile} to be empty. Programs can simply use
6534 @code{volatile} as if every C compiler supported it; for those that do
6535 not, the makefile or configuration header defines it as
6538 If the correctness of your program depends on the semantics of
6539 @code{volatile}, simply defining it to be empty does, in a sense, break
6540 your code. However, given that the compiler does not support
6541 @code{volatile}, you are at its mercy anyway. At least your
6542 program compiles, when it wouldn't before.
6543 @xref{Volatile Objects}, for more about @code{volatile}.
6545 In general, the @code{volatile} keyword is a standard C feature, so
6546 you might expect that @code{volatile} is available only when
6547 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
6548 support volatile, but does not define @code{__STDC__}.
6550 This macro is obsolescent, as current C compilers support @code{volatile}.
6551 New programs need not use this macro.
6557 If the C compiler supports the keyword @code{inline}, do nothing.
6558 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6559 if it accepts one of those, otherwise define @code{inline} to be empty.
6562 @defmac AC_C_CHAR_UNSIGNED
6563 @acindex{C_CHAR_UNSIGNED}
6564 @cvindex __CHAR_UNSIGNED__
6565 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6566 unless the C compiler predefines it.
6569 @defmac AC_C_STRINGIZE
6570 @acindex{C_STRINGIZE}
6571 @cvindex HAVE_STRINGIZE
6572 If the C preprocessor supports the stringizing operator, define
6573 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
6574 found in macros such as this:
6580 This macro is obsolescent, as current C compilers support the
6581 stringizing operator. New programs need not use this macro.
6584 @defmac AC_C_FLEXIBLE_ARRAY_MEMBER
6585 @acindex{C_FLEXIBLE_ARRAY_MEMBER}
6586 @cvindex FLEXIBLE_ARRAY_MEMBER
6587 If the C compiler supports flexible array members, define
6588 @code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
6589 That way, a declaration like this:
6595 double val[FLEXIBLE_ARRAY_MEMBER];
6600 will let applications use the ``struct hack'' even with compilers that
6601 do not support flexible array members. To allocate and use such an
6602 object, you can use code like this:
6606 size_t n = compute_value_count ();
6608 malloc (offsetof (struct s, val)
6609 + n * sizeof (double));
6611 for (i = 0; i < n; i++)
6612 p->val[i] = compute_value (i);
6616 @defmac AC_C_VARARRAYS
6617 @acindex{C_VARARRAYS}
6618 @cvindex HAVE_C_VARARRAYS
6619 If the C compiler supports variable-length arrays, define
6620 @code{HAVE_C_VARRAYS}. A variable-length array is an array of automatic
6621 storage duration whose length is determined at run time, when the array
6627 @cvindex HAVE_TYPEOF
6629 If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either
6631 through a different spelling of the keyword (e.g., @code{__typeof__}),
6632 define @code{HAVE_TYPEOF}. If the support is available only through a
6633 different spelling, define @code{typeof} to that spelling.
6636 @defmac AC_C_PROTOTYPES
6637 @acindex{C_PROTOTYPES}
6639 @cvindex __PROTOTYPES
6641 If function prototypes are understood by the compiler (as determined by
6642 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6643 Defining @code{__PROTOTYPES} is for the benefit of
6644 header files that cannot use macros that infringe on user name space.
6646 This macro is obsolescent, as current C compilers support prototypes.
6647 New programs need not use this macro.
6650 @defmac AC_PROG_GCC_TRADITIONAL
6651 @acindex{PROG_GCC_TRADITIONAL}
6653 Add @option{-traditional} to output variable @code{CC} if using the
6654 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6655 @option{-traditional}. That usually happens when the fixed header files
6656 have not been installed on an old system.
6658 This macro is obsolescent, since current versions of the @acronym{GNU} C
6659 compiler fix the header files automatically when installed.
6664 @subsection C++ Compiler Characteristics
6667 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6671 Determine a C++ compiler to use. Check whether the environment variable
6672 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6673 variable @code{CXX} to its value.
6675 Otherwise, if the macro is invoked without an argument, then search for
6676 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6677 then other names). If none of those checks succeed, then as a last
6678 resort set @code{CXX} to @code{g++}.
6680 This macro may, however, be invoked with an optional first argument
6681 which, if specified, must be a blank-separated list of C++ compilers to
6682 search for. This just gives the user an opportunity to specify an
6683 alternative search list for the C++ compiler. For example, if you
6684 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6688 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6691 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6692 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
6693 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6694 systems where G++ does not accept @option{-g}), or @option{-g} for other
6698 @defmac AC_PROG_CXXCPP
6699 @acindex{PROG_CXXCPP}
6701 Set output variable @code{CXXCPP} to a command that runs the C++
6702 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6703 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6704 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6706 Some preprocessors don't indicate missing include files by the error
6707 status. For such preprocessors an internal variable is set that causes
6708 other macros to check the standard error from the preprocessor and
6709 consider the test failed if any warnings have been reported. However,
6710 it is not known whether such broken preprocessors exist for C++.
6713 @defmac AC_PROG_CXX_C_O
6714 @acindex{PROG_CXX_C_O}
6715 @cvindex CXX_NO_MINUS_C_MINUS_O
6716 Test whether the C++ compiler accepts the options @option{-c} and
6717 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6722 @node Objective C Compiler
6723 @subsection Objective C Compiler Characteristics
6726 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6730 Determine an Objective C compiler to use. If @code{OBJC} is not already
6731 set in the environment, check for Objective C compilers. Set output
6732 variable @code{OBJC} to the name of the compiler found.
6734 This macro may, however, be invoked with an optional first argument
6735 which, if specified, must be a blank-separated list of Objective C compilers to
6736 search for. This just gives the user an opportunity to specify an
6737 alternative search list for the Objective C compiler. For example, if you
6738 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6742 AC_PROG_OBJC([gcc objcc objc])
6745 If using the @acronym{GNU} Objective C compiler, set shell variable
6746 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
6747 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6748 compiler (@option{-O2} on systems where @command{gcc} does not accept
6749 @option{-g}), or @option{-g} for other compilers.
6752 @defmac AC_PROG_OBJCCPP
6753 @acindex{PROG_OBJCCPP}
6755 Set output variable @code{OBJCCPP} to a command that runs the Objective C
6756 preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6760 @node Erlang Compiler and Interpreter
6761 @subsection Erlang Compiler and Interpreter Characteristics
6764 Autoconf defines the following macros for determining paths to the essential
6765 Erlang/OTP programs:
6767 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path})
6768 @acindex{ERLANG_PATH_ERLC}
6771 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
6772 environment, check for @command{erlc}. Set output variable @code{ERLC} to the
6773 complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
6774 is not set in the environment, set it to an empty value.
6776 The two optional arguments have the same meaning as the two last arguments of
6777 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For
6778 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
6782 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
6786 @defmac AC_ERLANG_NEED_ERLC (@ovar{path})
6787 @acindex{ERLANG_NEED_ERLC}
6788 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
6789 error message and exits the @command{configure} script if the @command{erlc}
6790 program is not found.
6793 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path})
6794 @acindex{ERLANG_PATH_ERL}
6796 Determine an Erlang interpreter to use. If @code{ERL} is not already set in the
6797 environment, check for @command{erl}. Set output variable @code{ERL} to the
6798 complete path of the interpreter command found.
6800 The two optional arguments have the same meaning as the two last arguments of
6801 macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For
6802 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
6806 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
6810 @defmac AC_ERLANG_NEED_ERL (@ovar{path})
6811 @acindex{ERLANG_NEED_ERL}
6812 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
6813 error message and exits the @command{configure} script if the @command{erl}
6814 program is not found.
6818 @node Fortran Compiler
6819 @subsection Fortran Compiler Characteristics
6823 The Autoconf Fortran support is divided into two categories: legacy
6824 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6825 The former are intended for traditional Fortran 77 code, and have output
6826 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
6827 are for newer programs that can (or must) compile under the newer
6828 Fortran standards, and have output variables like @code{FC},
6829 @code{FCFLAGS}, and @code{FCLIBS}.
6831 Except for two new macros @code{AC_FC_SRCEXT} and
6832 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6833 behave almost identically, and so they are documented together in this
6837 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6841 Determine a Fortran 77 compiler to use. If @code{F77} is not already
6842 set in the environment, then check for @code{g77} and @code{f77}, and
6843 then some other names. Set the output variable @code{F77} to the name
6844 of the compiler found.
6846 This macro may, however, be invoked with an optional first argument
6847 which, if specified, must be a blank-separated list of Fortran 77
6848 compilers to search for. This just gives the user an opportunity to
6849 specify an alternative search list for the Fortran 77 compiler. For
6850 example, if you didn't like the default order, then you could invoke
6851 @code{AC_PROG_F77} like this:
6854 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6857 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6858 set the shell variable @code{G77} to @samp{yes}.
6859 If the output variable @code{FFLAGS} was not already set in the
6860 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6861 where @code{g77} does not accept @option{-g}). Otherwise, set
6862 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6865 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6869 Determine a Fortran compiler to use. If @code{FC} is not already set in
6870 the environment, then @code{dialect} is a hint to indicate what Fortran
6871 dialect to search for; the default is to search for the newest available
6872 dialect. Set the output variable @code{FC} to the name of the compiler
6875 By default, newer dialects are preferred over older dialects, but if
6876 @code{dialect} is specified then older dialects are preferred starting
6877 with the specified dialect. @code{dialect} can currently be one of
6878 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
6879 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6880 and no attempt is made to guarantee that a particular language standard
6881 is actually supported. Thus, it is preferable that you avoid the
6882 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6883 the latest Fortran standard.
6885 This macro may, alternatively, be invoked with an optional first argument
6886 which, if specified, must be a blank-separated list of Fortran
6887 compilers to search for, just as in @code{AC_PROG_F77}.
6889 If the output variable @code{FCFLAGS} was not already set in the
6890 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
6891 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
6892 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6895 @defmac AC_PROG_F77_C_O
6896 @defmacx AC_PROG_FC_C_O
6897 @acindex{PROG_F77_C_O}
6898 @acindex{PROG_FC_C_O}
6899 @cvindex F77_NO_MINUS_C_MINUS_O
6900 @cvindex FC_NO_MINUS_C_MINUS_O
6901 Test whether the Fortran compiler accepts the options @option{-c} and
6902 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6903 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6906 The following macros check for Fortran compiler characteristics.
6907 To check for characteristics not listed here, use
6908 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6909 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
6910 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6911 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6914 @defmac AC_F77_LIBRARY_LDFLAGS
6915 @defmacx AC_FC_LIBRARY_LDFLAGS
6916 @acindex{F77_LIBRARY_LDFLAGS}
6918 @acindex{FC_LIBRARY_LDFLAGS}
6920 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
6921 @dfn{Fortran intrinsic and runtime libraries} that are required to
6922 successfully link a Fortran program or shared library. The output
6923 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
6924 should be included after @code{LIBS} when linking).
6926 This macro is intended to be used in those situations when it is
6927 necessary to mix, e.g., C++ and Fortran source code in a single
6928 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
6929 automake, @acronym{GNU} Automake}).
6931 For example, if object files from a C++ and Fortran compiler must be
6932 linked together, then the C++ compiler/linker must be used for linking
6933 (since special C++-ish things need to happen at link time like calling
6934 global constructors, instantiating templates, enabling exception
6937 However, the Fortran intrinsic and runtime libraries must be linked in
6938 as well, but the C++ compiler/linker doesn't know by default how to add
6939 these Fortran 77 libraries. Hence, this macro was created to determine
6940 these Fortran libraries.
6942 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6943 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
6944 link C/C++ with Fortran; see below.
6947 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6948 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6949 @acindex{F77_DUMMY_MAIN}
6950 @cvindex F77_DUMMY_MAIN
6951 With many compilers, the Fortran libraries detected by
6952 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
6953 their own @code{main} entry function that initializes things like
6954 Fortran I/O, and which then calls a user-provided entry function named
6955 (say) @code{MAIN__} to run the user's program. The
6956 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6957 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
6960 When using Fortran for purely numerical functions (no I/O, etc.)@: often
6961 one prefers to provide one's own @code{main} and skip the Fortran
6962 library initializations. In this case, however, one may still need to
6963 provide a dummy @code{MAIN__} routine in order to prevent linking errors
6964 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
6965 detects whether any such routine is @emph{required} for linking, and
6966 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
6967 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
6968 was found, and @code{none} when no such dummy main is needed.
6970 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
6971 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
6972 @emph{if} it is required. @var{action-if-not-found} defaults to
6973 exiting with an error.
6975 In order to link with Fortran routines, the user's C/C++ program should
6976 then include the following code to define the dummy main if it is
6980 #ifdef F77_DUMMY_MAIN
6984 int F77_DUMMY_MAIN() @{ return 1; @}
6988 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6990 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
6991 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
6992 explicitly unless one wants to change the default actions.
7001 As discussed above, many Fortran libraries allow you to provide an entry
7002 point called (say) @code{MAIN__} instead of the usual @code{main}, which
7003 is then called by a @code{main} function in the Fortran libraries that
7004 initializes things like Fortran I/O@. The
7005 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
7006 @emph{possible} to utilize such an alternate main function, and defines
7007 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
7008 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
7009 simply defined to @code{main}.)
7011 Thus, when calling Fortran routines from C that perform things like I/O,
7012 one should use this macro and name the "main" function
7013 @code{F77_MAIN} or @code{FC_MAIN} instead of @code{main}.
7016 @defmac AC_F77_WRAPPERS
7017 @defmacx AC_FC_WRAPPERS
7018 @acindex{F77_WRAPPERS}
7021 @acindex{FC_WRAPPERS}
7024 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
7025 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
7026 mangle the names of C/C++ identifiers, and identifiers with underscores,
7027 respectively, so that they match the name-mangling scheme used by the
7030 Fortran is case-insensitive, and in order to achieve this the Fortran
7031 compiler converts all identifiers into a canonical case and format. To
7032 call a Fortran subroutine from C or to write a C function that is
7033 callable from Fortran, the C program must explicitly use identifiers in
7034 the format expected by the Fortran compiler. In order to do this, one
7035 simply wraps all C identifiers in one of the macros provided by
7036 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
7037 you have the following Fortran 77 subroutine:
7040 subroutine foobar (x, y)
7041 double precision x, y
7047 You would then declare its prototype in C or C++ as:
7050 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
7052 extern "C" /* prevent C++ name mangling */
7054 void FOOBAR_F77(double *x, double *y);
7057 Note that we pass both the lowercase and uppercase versions of the
7058 function name to @code{F77_FUNC} so that it can select the right one.
7059 Note also that all parameters to Fortran 77 routines are passed as
7060 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
7063 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7065 Although Autoconf tries to be intelligent about detecting the
7066 name-mangling scheme of the Fortran compiler, there may be Fortran
7067 compilers that it doesn't support yet. In this case, the above code
7068 generates a compile-time error, but some other behavior
7069 (e.g., disabling Fortran-related features) can be induced by checking
7070 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
7072 Now, to call that routine from a C program, we would do something like:
7076 double x = 2.7183, y;
7077 FOOBAR_F77 (&x, &y);
7081 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
7082 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
7083 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
7084 because some Fortran compilers mangle names differently if they contain
7088 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
7089 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
7092 Given an identifier @var{name}, set the shell variable @var{shellvar} to
7093 hold the mangled version @var{name} according to the rules of the
7094 Fortran linker (see also @code{AC_F77_WRAPPERS} or
7095 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
7096 supplied, the shell variable is simply @var{name}. The purpose of
7097 this macro is to give the caller a way to access the name-mangling
7098 information other than through the C preprocessor as above, for example,
7099 to call Fortran routines from some language other than C/C++.
7102 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
7104 By default, the @code{FC} macros perform their tests using a @file{.f}
7105 extension for source-code files. Some compilers, however, only enable
7106 newer language features for appropriately named files, e.g., Fortran 90
7107 features only for @file{.f90} files. On the other hand, some other
7108 compilers expect all source files to end in @file{.f} and require
7109 special flags to support other file name extensions. The
7110 @code{AC_FC_SRCEXT} macro deals with both of these issues.
7112 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
7113 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
7114 contain the dot). If any special compiler flags are needed for this, it
7115 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
7116 extension and these flags are then used for all subsequent @code{FC} tests
7117 (until @code{AC_FC_SRCEXT} is called again).
7119 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
7120 @file{.f90} extension in future tests, and it would set a
7121 @code{FCFLAGS_f90} output variable with any extra flags that are needed
7122 to compile such files.
7124 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
7125 @code{FCFLAGS}, for two reasons based on the limitations of some
7126 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
7127 time, so files with different extensions must be compiled separately.
7128 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
7129 the source-code file name when compiling. So, continuing the example
7130 above, you might compile a @file{foo.f90} file in your makefile with the
7135 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
7138 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
7139 extension, it calls @var{action-if-success} (defaults to nothing). If
7140 it fails, and cannot find a way to make the @code{FC} compiler accept such
7141 files, it calls @var{action-if-failure} (defaults to exiting with an
7146 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
7147 @acindex{FC_FREEFORM}
7149 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
7150 (@code{$FC}) allows free-format source code (as opposed to the older
7151 fixed-format style from Fortran 77). If necessary, it may add some
7152 additional flags to @code{FCFLAGS}.
7154 This macro is most important if you are using the default @file{.f}
7155 extension, since many compilers interpret this extension as indicating
7156 fixed-format source unless an additional flag is supplied. If you
7157 specify a different extension with @code{AC_FC_SRCEXT}, such as
7158 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily
7159 succeeds without modifying @code{FCFLAGS}.
7161 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
7162 calls @var{action-if-success} (defaults to nothing). If it fails, it
7163 calls @var{action-if-failure} (defaults to exiting with an error
7167 @node System Services
7168 @section System Services
7170 The following macros check for operating system services or capabilities.
7175 @cindex X Window System
7176 Try to locate the X Window System include files and libraries. If the
7177 user gave the command line options @option{--x-includes=@var{dir}} and
7178 @option{--x-libraries=@var{dir}}, use those directories.
7180 If either or both were not given, get the missing values by running
7181 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
7182 environment variable) on a trivial @file{Imakefile} and examining the
7183 makefile that it produces. Setting @code{XMKMF} to @samp{false}
7184 disables this method.
7186 If this method fails to find the X Window System, @command{configure}
7187 looks for the files in several directories where they often reside.
7188 If either method is successful, set the shell variables
7189 @code{x_includes} and @code{x_libraries} to their locations, unless they
7190 are in directories the compiler searches by default.
7192 If both methods fail, or the user gave the command line option
7193 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
7194 otherwise set it to the empty string.
7197 @defmac AC_PATH_XTRA
7201 @ovindex X_EXTRA_LIBS
7203 @cvindex X_DISPLAY_MISSING
7204 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
7205 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
7206 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
7209 This macro also checks for special libraries that some systems need in
7210 order to compile X programs. It adds any that the system needs to
7211 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
7212 libraries that need to be linked with before @option{-lX11}, and adds
7213 any found to the output variable @code{X_PRE_LIBS}.
7215 @c This is an incomplete kludge. Make a real way to do it.
7216 @c If you need to check for other X functions or libraries yourself, then
7217 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
7218 @c @code{LIBS} temporarily, like this: (FIXME - add example)
7221 @defmac AC_SYS_INTERPRETER
7222 @acindex{SYS_INTERPRETER}
7223 Check whether the system supports starting scripts with a line of the
7224 form @samp{#!/bin/sh} to select the interpreter to use for the script.
7225 After running this macro, shell code in @file{configure.ac} can check
7226 the shell variable @code{interpval}; it is set to @samp{yes}
7227 if the system supports @samp{#!}, @samp{no} if not.
7230 @defmac AC_SYS_LARGEFILE
7231 @acindex{SYS_LARGEFILE}
7232 @cvindex _FILE_OFFSET_BITS
7233 @cvindex _LARGE_FILES
7235 @cindex Large file support
7238 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
7239 large-file support}. On some hosts, one must use special compiler
7240 options to build programs that can access large files. Append any such
7241 options to the output variable @code{CC}. Define
7242 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
7244 Large-file support can be disabled by configuring with the
7245 @option{--disable-largefile} option.
7247 If you use this macro, check that your program works even when
7248 @code{off_t} is wider than @code{long int}, since this is common when
7249 large-file support is enabled. For example, it is not correct to print
7250 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
7253 The LFS introduced the @code{fseeko} and @code{ftello} functions to
7254 replace their C counterparts @code{fseek} and @code{ftell} that do not
7255 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
7256 prototypes available when using them and large-file support is
7260 @defmac AC_SYS_LONG_FILE_NAMES
7261 @acindex{SYS_LONG_FILE_NAMES}
7262 @cvindex HAVE_LONG_FILE_NAMES
7263 If the system supports file names longer than 14 characters, define
7264 @code{HAVE_LONG_FILE_NAMES}.
7267 @defmac AC_SYS_POSIX_TERMIOS
7268 @acindex{SYS_POSIX_TERMIOS}
7269 @cindex Posix termios headers
7270 @cindex termios Posix headers
7271 Check to see if the Posix termios headers and functions are available on the
7272 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
7273 @samp{yes}. If not, set the variable to @samp{no}.
7276 @node Posix Variants
7277 @section Posix Variants
7279 The following macros check for certain operating systems that need
7280 special treatment for some programs, due to exceptional oddities in
7281 their header files or libraries. These macros are warts; they will be
7282 replaced by a more systematic approach, based on the functions they make
7283 available or the environments they provide.
7287 @cvindex _ALL_SOURCE
7288 If on @acronym{AIX}, define @code{_ALL_SOURCE}.
7289 Allows the use of some @acronym{BSD}
7290 functions. Should be called before any macros that run the C compiler.
7293 @defmac AC_GNU_SOURCE
7294 @acindex{GNU_SOURCE}
7295 @cvindex _GNU_SOURCE
7296 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
7297 Allows the use of some @acronym{GNU} functions. Should be called
7298 before any macros that run the C compiler.
7301 @defmac AC_ISC_POSIX
7304 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
7305 variable @code{LIBS} if necessary for Posix facilities. Call this
7306 after @code{AC_PROG_CC} and before any other macros that use Posix
7309 This macro is obsolescent, as @sc{interactive} Unix is obsolete, and Sun
7310 dropped support for it on 2006-07-23. New programs need not use this
7317 @cvindex _POSIX_SOURCE
7318 @cvindex _POSIX_1_SOURCE
7319 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
7320 @code{_POSIX_1_SOURCE} to be 2. This allows the use of Posix
7321 facilities. Should be called before any macros that run the C compiler.
7324 @defmac AC_USE_SYSTEM_EXTENSIONS
7325 @acindex{USE_SYSTEM_EXTENSIONS}
7326 @cvindex _ALL_SOURCE
7327 @cvindex _GNU_SOURCE
7329 @cvindex _POSIX_1_SOURCE
7330 @cvindex _POSIX_PTHREAD_SEMANTICS
7331 @cvindex _POSIX_SOURCE
7332 @cvindex _TANDEM_SOURCE
7333 @cvindex __EXTENSIONS__
7334 If possible, enable extensions to Posix on hosts that normally disable
7335 the extensions, typically due to standards-conformance namespace issues.
7336 This may involve defining @code{__EXTENSIONS__} and
7337 @code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris.
7338 It also defines @code{_TANDEM_SOURCE} for the @acronym{HP} NonStop platform.
7339 This macro also has the combined effects of @code{AC_GNU_SOURCE},
7340 @code{AC_AIX}, and @code{AC_MINIX}.
7344 @node Erlang Libraries
7345 @section Erlang Libraries
7346 @cindex Erlang, Library, checking
7348 The following macros check for an installation of Erlang/OTP, and for the
7349 presence of certain Erlang libraries. All those macros require the
7350 configuration of an Erlang interpreter and an Erlang compiler
7351 (@pxref{Erlang Compiler and Interpreter}).
7353 @defmac AC_ERLANG_SUBST_ROOT_DIR
7354 @acindex{ERLANG_SUBST_ROOT_DIR}
7355 @ovindex ERLANG_ROOT_DIR
7357 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory
7358 in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0}
7359 function). The result of this test is cached if caching is enabled when running
7360 @command{configure}.
7363 @defmac AC_ERLANG_SUBST_LIB_DIR
7364 @acindex{ERLANG_SUBST_LIB_DIR}
7365 @ovindex ERLANG_LIB_DIR
7367 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7368 directory of Erlang/OTP (as returned by Erlang's
7369 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7370 Erlang/OTP library. The result of this test is cached if caching is enabled
7371 when running @command{configure}.
7374 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found})
7375 @acindex{ERLANG_CHECK_LIB}
7376 @ovindex ERLANG_LIB_DIR_@var{library}
7377 @ovindex ERLANG_LIB_VER_@var{library}
7379 Test whether the Erlang/OTP library @var{library} is installed by
7380 calling Erlang's @code{code:lib_dir/1} function. The result of this
7381 test is cached if caching is enabled when running @command{configure}.
7382 @var{action-if-found} is a list of shell commands to run if the library
7383 is installed; @var{action-if-not-found} is a list of shell commands to
7384 run if it is not. Additionally, if the library is installed, the output
7385 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
7386 library installation directory, and the output variable
7387 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
7388 part of the subdirectory name, if it is in the standard form
7389 (@code{@var{library}-@var{version}}). If the directory name does not
7390 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
7391 empty string. If the library is not installed,
7392 @samp{ERLANG_LIB_DIR_@var{library}} and
7393 @samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For
7394 example, to check if library @code{stdlib} is installed:
7397 AC_ERLANG_CHECK_LIB([stdlib],
7398 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
7399 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
7400 [AC_MSG_ERROR([stdlib was not found!])])
7404 In addition to the above macros, which test installed Erlang libraries, the
7405 following macros determine the paths to the directories into which newly built
7406 Erlang libraries are to be installed:
7408 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7409 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7410 @ovindex ERLANG_INSTALL_LIB_DIR
7412 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7413 which every built Erlang library should be installed in a separate subdirectory.
7414 If this variable is not set in the environment when @command{configure} runs,
7415 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7416 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7419 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7420 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7421 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7423 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7424 directory into which the built Erlang library @var{library} version
7425 @var{version} should be installed. If this variable is not set in the
7426 environment when @command{configure} runs, its default value is
7427 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7428 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7429 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7436 @c ========================================================= Writing Tests
7439 @chapter Writing Tests
7441 If the existing feature tests don't do something you need, you have to
7442 write new ones. These macros are the building blocks. They provide
7443 ways for other macros to check whether various kinds of features are
7444 available and report the results.
7446 This chapter contains some suggestions and some of the reasons why the
7447 existing tests are written the way they are. You can also learn a lot
7448 about how to write Autoconf tests by looking at the existing ones. If
7449 something goes wrong in one or more of the Autoconf tests, this
7450 information can help you understand the assumptions behind them, which
7451 might help you figure out how to best solve the problem.
7453 These macros check the output of the compiler system of the current
7454 language (@pxref{Language Choice}). They do not cache the results of
7455 their tests for future use (@pxref{Caching Results}), because they don't
7456 know enough about the information they are checking for to generate a
7457 cache variable name. They also do not print any messages, for the same
7458 reason. The checks for particular kinds of features call these macros
7459 and do cache their results and print messages about what they're
7462 When you write a feature test that could be applicable to more than one
7463 software package, the best thing to do is encapsulate it in a new macro.
7464 @xref{Writing Autoconf Macros}, for how to do that.
7467 * Language Choice:: Selecting which language to use for testing
7468 * Writing Test Programs:: Forging source files for compilers
7469 * Running the Preprocessor:: Detecting preprocessor symbols
7470 * Running the Compiler:: Detecting language or header features
7471 * Running the Linker:: Detecting library features
7472 * Runtime:: Testing for runtime features
7473 * Systemology:: A zoology of operating systems
7474 * Multiple Cases:: Tests for several possible values
7477 @node Language Choice
7478 @section Language Choice
7481 Autoconf-generated @command{configure} scripts check for the C compiler and
7482 its features by default. Packages that use other programming languages
7483 (maybe more than one, e.g., C and C++) need to test features of the
7484 compilers for the respective languages. The following macros determine
7485 which programming language is used in the subsequent tests in
7486 @file{configure.ac}.
7488 @defmac AC_LANG (@var{language})
7489 Do compilation tests using the compiler, preprocessor, and file
7490 extensions for the specified @var{language}.
7492 Supported languages are:
7496 Do compilation tests using @code{CC} and @code{CPP} and use extension
7497 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
7498 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7501 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7502 extension @file{.C} for test programs. Use compilation flags:
7503 @code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and
7504 @code{CXXFLAGS} with @code{CXX}.
7507 Do compilation tests using @code{F77} and use extension @file{.f} for
7508 test programs. Use compilation flags: @code{FFLAGS}.
7511 Do compilation tests using @code{FC} and use extension @file{.f} (or
7512 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
7513 compilation flags: @code{FCFLAGS}.
7519 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7520 @file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
7523 Do compilation tests using @code{OBJC} and @code{OBJCCPP} and use
7524 extension @file{.m} for test programs. Use compilation flags:
7525 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7526 @code{OBJCFLAGS} with @code{OBJC}.
7530 @defmac AC_LANG_PUSH (@var{language})
7532 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7533 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
7534 in macros that need to temporarily switch to a particular language.
7537 @defmac AC_LANG_POP (@ovar{language})
7539 Select the language that is saved on the top of the stack, as set by
7540 @code{AC_LANG_PUSH}, and remove it from the stack.
7542 If given, @var{language} specifies the language we just @emph{quit}. It
7543 is a good idea to specify it when it's known (which should be the
7544 case@dots{}), since Autoconf detects inconsistencies.
7547 AC_LANG_PUSH([Fortran 77])
7548 # Perform some tests on Fortran 77.
7550 AC_LANG_POP([Fortran 77])
7554 @defmac AC_LANG_ASSERT (@var{language})
7555 @acindex{LANG_ASSERT} Check statically that the current language is
7556 @var{language}. You should use this in your language specific macros
7557 to avoid that they be called with an inappropriate language.
7559 This macro runs only at @command{autoconf} time, and incurs no cost at
7560 @command{configure} time. Sadly enough and because Autoconf is a two
7561 layer language @footnote{Because M4 is not aware of Sh code,
7562 especially conditionals, some optimizations that look nice statically
7563 may produce incorrect results at runtime.}, the macros
7564 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7565 therefore as much as possible you ought to avoid using them to wrap
7566 your code, rather, require from the user to run the macro with a
7567 correct current language, and check it with @code{AC_LANG_ASSERT}.
7568 And anyway, that may help the user understand she is running a Fortran
7569 macro while expecting a result about her Fortran 77 compiler@dots{}
7573 @defmac AC_REQUIRE_CPP
7574 @acindex{REQUIRE_CPP}
7575 Ensure that whichever preprocessor would currently be used for tests has
7576 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7577 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7578 depending on which language is current.
7582 @node Writing Test Programs
7583 @section Writing Test Programs
7585 Autoconf tests follow a common scheme: feed some program with some
7586 input, and most of the time, feed a compiler with some source file.
7587 This section is dedicated to these source samples.
7590 * Guidelines:: General rules for writing test programs
7591 * Test Functions:: Avoiding pitfalls in test programs
7592 * Generating Sources:: Source program boilerplate
7596 @subsection Guidelines for Test Programs
7598 The most important rule to follow when writing testing samples is:
7600 @center @emph{Look for realism.}
7602 This motto means that testing samples must be written with the same
7603 strictness as real programs are written. In particular, you should
7604 avoid ``shortcuts'' and simplifications.
7606 Don't just play with the preprocessor if you want to prepare a
7607 compilation. For instance, using @command{cpp} to check whether a header is
7608 functional might let your @command{configure} accept a header which
7609 causes some @emph{compiler} error. Do not hesitate to check a header with
7610 other headers included before, especially required headers.
7612 Make sure the symbols you use are properly defined, i.e., refrain for
7613 simply declaring a function yourself instead of including the proper
7616 Test programs should not write to standard output. They
7617 should exit with status 0 if the test succeeds, and with status 1
7618 otherwise, so that success
7619 can be distinguished easily from a core dump or other failure;
7620 segmentation violations and other failures produce a nonzero exit
7621 status. Unless you arrange for @code{exit} to be declared, test
7622 programs should @code{return}, not @code{exit}, from @code{main},
7623 because on many systems @code{exit} is not declared by default.
7625 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7626 preprocessor macros defined by tests that have already run. For
7627 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7628 @file{configure.ac} you can have a test program that includes
7629 @file{stdbool.h} conditionally:
7633 #ifdef HAVE_STDBOOL_H
7634 # include <stdbool.h>
7639 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
7640 work with any standard C compiler. Some developers prefer @code{#if}
7641 because it is easier to read, while others prefer @code{#ifdef} because
7642 it avoids diagnostics with picky compilers like @acronym{GCC} with the
7643 @option{-Wundef} option.
7645 If a test program needs to use or create a data file, give it a name
7646 that starts with @file{conftest}, such as @file{conftest.data}. The
7647 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7648 after running test programs and if the script is interrupted.
7650 @node Test Functions
7651 @subsection Test Functions
7653 These days it's safe to assume support for function prototypes
7654 (introduced in C89).
7656 Functions that test programs declare should also be conditionalized for
7657 C++, which requires @samp{extern "C"} prototypes. Make sure to not
7658 include any header files containing clashing prototypes.
7664 void *valloc (size_t);
7667 If a test program calls a function with invalid parameters (just to see
7668 whether it exists), organize the program to ensure that it never invokes
7669 that function. You can do this by calling it in another function that is
7670 never invoked. You can't do it by putting it after a call to
7671 @code{exit}, because @acronym{GCC} version 2 knows that @code{exit}
7673 and optimizes out any code that follows it in the same block.
7675 If you include any header files, be sure to call the functions
7676 relevant to them with the correct number of arguments, even if they are
7677 just 0, to avoid compilation errors due to prototypes. @acronym{GCC}
7679 has internal prototypes for several functions that it automatically
7680 inlines; for example, @code{memcpy}. To avoid errors when checking for
7681 them, either pass them the correct number of arguments or redeclare them
7682 with a different return type (such as @code{char}).
7685 @node Generating Sources
7686 @subsection Generating Sources
7688 Autoconf provides a set of macros that can be used to generate test
7689 source files. They are written to be language generic, i.e., they
7690 actually depend on the current language (@pxref{Language Choice}) to
7691 ``format'' the output properly.
7694 @defmac AC_LANG_CONFTEST (@var{source})
7695 @acindex{LANG_CONFTEST}
7696 Save the @var{source} text in the current test source file:
7697 @file{conftest.@var{extension}} where the @var{extension} depends on the
7700 Note that the @var{source} is evaluated exactly once, like regular
7701 Autoconf macro arguments, and therefore (i) you may pass a macro
7702 invocation, (ii) if not, be sure to double quote if needed.
7705 @defmac AC_LANG_SOURCE (@var{source})
7706 @acindex{LANG_SOURCE}
7707 Expands into the @var{source}, with the definition of
7708 all the @code{AC_DEFINE} performed so far.
7711 For instance executing (observe the double quotation!):
7714 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7715 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7716 [Greetings string.])
7719 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7720 gcc -E -dD -o - conftest.c
7730 #define PACKAGE_NAME "Hello"
7731 #define PACKAGE_TARNAME "hello"
7732 #define PACKAGE_VERSION "1.0"
7733 #define PACKAGE_STRING "Hello 1.0"
7734 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7735 #define HELLO_WORLD "Hello, World\n"
7737 const char hw[] = "Hello, World\n";
7740 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7741 are not automatically translated into constants in the source code by this
7744 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7745 @acindex{LANG_PROGRAM}
7746 Expands into a source file which consists of the @var{prologue}, and
7747 then @var{body} as body of the main function (e.g., @code{main} in
7748 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7755 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7756 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7757 [Greetings string.])
7759 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7760 [[fputs (hw, stdout);]])])
7761 gcc -E -dD -o - conftest.c
7771 #define PACKAGE_NAME "Hello"
7772 #define PACKAGE_TARNAME "hello"
7773 #define PACKAGE_VERSION "1.0"
7774 #define PACKAGE_STRING "Hello 1.0"
7775 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7776 #define HELLO_WORLD "Hello, World\n"
7778 const char hw[] = "Hello, World\n";
7788 In Erlang tests, the created source file is that of an Erlang module called
7789 @code{conftest} (@file{conftest.erl}). This module defines and exports at least
7790 one @code{start/0} function, which is called to perform the test. The
7791 @var{prologue} is optional code that is inserted between the module header and
7792 the @code{start/0} function definition. @var{body} is the body of the
7793 @code{start/0} function without the final period (@pxref{Runtime}, about
7794 constraints on this function's behavior).
7799 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7802 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
7803 [[io:format("~s~n", [?HELLO_WORLD])]])])
7813 -define(HELLO_WORLD, "Hello, world!").
7815 io:format("~s~n", [?HELLO_WORLD])
7819 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
7821 Expands into a source file which consists of the @var{prologue}, and
7822 then a call to the @var{function} as body of the main function (e.g.,
7823 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
7824 of the latter are available.
7826 This function will probably be replaced in the future by a version
7827 which would enable specifying the arguments. The use of this macro is
7828 not encouraged, as it violates strongly the typing system.
7830 This macro cannot be used for Erlang tests.
7833 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
7834 @acindex{LANG_FUNC_LINK_TRY}
7835 Expands into a source file which uses the @var{function} in the body of
7836 the main function (e.g., @code{main} in C). Since it uses
7837 @code{AC_LANG_PROGRAM}, the features of the latter are available.
7839 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
7840 It is considered to be severely broken, and in the future will be
7841 removed in favor of actual function calls (with properly typed
7844 This macro cannot be used for Erlang tests.
7847 @node Running the Preprocessor
7848 @section Running the Preprocessor
7850 Sometimes one might need to run the preprocessor on some source file.
7851 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
7852 your project, not merely run the preprocessor on it; therefore you
7853 certainly want to run the compiler, not the preprocessor. Resist the
7854 temptation of following the easiest path.
7856 Nevertheless, if you need to run the preprocessor, then use
7857 @code{AC_PREPROC_IFELSE}.
7859 The macros described in this section cannot be used for tests in Erlang or
7860 Fortran, since those languages require no preprocessor.
7862 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7863 @acindex{PREPROC_IFELSE}
7864 Run the preprocessor of the current language (@pxref{Language Choice})
7865 on the @var{input}, run the shell commands @var{action-if-true} on
7866 success, @var{action-if-false} otherwise. The @var{input} can be made
7867 by @code{AC_LANG_PROGRAM} and friends.
7869 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
7870 @option{-g}, @option{-O}, etc.@: are not valid options to many C
7873 It is customary to report unexpected failures with
7874 @code{AC_MSG_FAILURE}.
7880 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7881 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7882 [Greetings string.])
7884 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7885 [[fputs (hw, stdout);]])],
7886 [AC_MSG_RESULT([OK])],
7887 [AC_MSG_FAILURE([unexpected preprocessor failure])])
7894 checking for gcc... gcc
7895 checking for C compiler default output file name... a.out
7896 checking whether the C compiler works... yes
7897 checking whether we are cross compiling... no
7898 checking for suffix of executables...
7899 checking for suffix of object files... o
7900 checking whether we are using the GNU C compiler... yes
7901 checking whether gcc accepts -g... yes
7902 checking for gcc option to accept ISO C89... none needed
7903 checking how to run the C preprocessor... gcc -E
7909 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
7910 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
7911 it impossible to use it to elaborate sources. You are encouraged to
7912 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
7913 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
7914 to run the @emph{preprocessor} and not the compiler?
7916 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
7917 @acindex{EGREP_HEADER}
7918 If the output of running the preprocessor on the system header file
7919 @var{header-file} matches the extended regular expression
7920 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
7921 execute @var{action-if-not-found}.
7924 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
7926 @var{program} is the text of a C or C++ program, on which shell
7927 variable, back quote, and backslash substitutions are performed. If the
7928 output of running the preprocessor on @var{program} matches the
7929 extended regular expression @var{pattern}, execute shell commands
7930 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
7935 @node Running the Compiler
7936 @section Running the Compiler
7938 To check for a syntax feature of the current language's (@pxref{Language
7939 Choice}) compiler, such as whether it recognizes a certain keyword, or
7940 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
7941 to compile a small program that uses that feature.
7943 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7944 @acindex{COMPILE_IFELSE}
7945 Run the compiler and compilation flags of the current language
7946 (@pxref{Language Choice}) on the @var{input}, run the shell commands
7947 @var{action-if-true} on success, @var{action-if-false} otherwise. The
7948 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7950 It is customary to report unexpected failures with
7951 @code{AC_MSG_FAILURE}. This macro does not try to link; use
7952 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
7957 For tests in Erlang, the @var{input} must be the source code of a module named
7958 @code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
7959 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
7960 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure
7961 that the Erlang module has the right name.
7963 @node Running the Linker
7964 @section Running the Linker
7966 To check for a library, a function, or a global variable, Autoconf
7967 @command{configure} scripts try to compile and link a small program that
7968 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
7969 @code{ar} on the C library to try to figure out which functions are
7970 available. Trying to link with the function is usually a more reliable
7971 approach because it avoids dealing with the variations in the options
7972 and output formats of @code{nm} and @code{ar} and in the location of the
7973 standard libraries. It also allows configuring for cross-compilation or
7974 checking a function's runtime behavior if needed. On the other hand,
7975 it can be slower than scanning the libraries once, but accuracy is more
7976 important than speed.
7978 @code{AC_LINK_IFELSE} is used to compile test programs to test for
7979 functions and global variables. It is also used by @code{AC_CHECK_LIB}
7980 to check for libraries (@pxref{Libraries}), by adding the library being
7981 checked for to @code{LIBS} temporarily and trying to link a small
7985 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7986 @acindex{LINK_IFELSE}
7987 Run the compiler (and compilation flags) and the linker of the current
7988 language (@pxref{Language Choice}) on the @var{input}, run the shell
7989 commands @var{action-if-true} on success, @var{action-if-false}
7990 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
7993 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7994 current compilation flags.
7996 It is customary to report unexpected failures with
7997 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
7998 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
8001 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
8002 programs are interpreted and do not require linking.
8007 @section Checking Runtime Behavior
8009 Sometimes you need to find out how a system performs at runtime, such
8010 as whether a given function has a certain capability or bug. If you
8011 can, make such checks when your program runs instead of when it is
8012 configured. You can check for things like the machine's endianness when
8013 your program initializes itself.
8015 If you really need to test for a runtime behavior while configuring,
8016 you can write a test program to determine the result, and compile and
8017 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
8018 possible, because this prevents people from configuring your package for
8021 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
8022 @acindex{RUN_IFELSE}
8023 If @var{program} compiles and links successfully and returns an exit
8024 status of 0 when executed, run shell commands @var{action-if-true}.
8025 Otherwise, run shell commands @var{action-if-false}.
8027 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8028 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8029 compilation flags of the current language (@pxref{Language Choice}).
8031 If the compiler being used does not produce executables that run on the
8032 system where @command{configure} is being run, then the test program is
8033 not run. If the optional shell commands @var{action-if-cross-compiling}
8034 are given, they are run instead. Otherwise, @command{configure} prints
8035 an error message and exits.
8037 In the @var{action-if-false} section, the failing exit status is
8038 available in the shell variable @samp{$?}. This exit status might be
8039 that of a failed compilation, or it might be that of a failed program
8042 It is customary to report unexpected failures with
8043 @code{AC_MSG_FAILURE}.
8046 Try to provide a pessimistic default value to use when cross-compiling
8047 makes runtime tests impossible. You do this by passing the optional
8048 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
8049 warning message when creating @command{configure} each time it
8050 encounters a call to @code{AC_RUN_IFELSE} with no
8051 @var{action-if-cross-compiling} argument given. You may ignore the
8052 warning, though users cannot configure your package for
8053 cross-compiling. A few of the macros distributed with Autoconf produce
8054 this warning message.
8056 To configure for cross-compiling you can also choose a value for those
8057 parameters based on the canonical system name (@pxref{Manual
8058 Configuration}). Alternatively, set up a test results cache file with
8059 the correct values for the host system (@pxref{Caching Results}).
8061 @ovindex cross_compiling
8062 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
8063 in other macros, including a few of the ones that come with Autoconf,
8064 you can test whether the shell variable @code{cross_compiling} is set to
8065 @samp{yes}, and then use an alternate method to get the results instead
8066 of calling the macros.
8068 A C or C++ runtime test should be portable.
8069 @xref{Portable C and C++}.
8071 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
8072 function: the given status code is used to determine the success of the test
8073 (status is @code{0}) or its failure (status is different than @code{0}), as
8074 explained above. It must be noted that data output through the standard output
8075 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
8076 Therefore, if a test must output configuration information, it is recommended
8077 to create and to output data into the temporary file named @file{conftest.out},
8078 using the functions of module @code{file}. The @code{conftest.out} file is
8079 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
8080 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is:
8083 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
8087 [AC_LANG_PROGRAM([], [dnl
8088 file:write_file("conftest.out", code:lib_dir()),
8090 [echo "code:lib_dir() returned: `cat conftest.out`"],
8091 [AC_MSG_FAILURE([test Erlang program execution failed])])
8096 @section Systemology
8099 This section aims at presenting some systems and pointers to
8100 documentation. It may help you addressing particular problems reported
8103 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
8104 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
8107 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
8108 contains a table correlating the features of various Posix-conforming
8109 systems. @uref{http://www.levenez.com/unix/, Unix History} is a
8110 simplified diagram of how many Unix systems were derived from each
8113 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
8114 provides some variants of traditional implementations of Unix utilities.
8119 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
8120 case-preserving, but case insensitive. This can cause nasty problems,
8121 since for instance the installation attempt for a package having an
8122 @file{INSTALL} file can result in @samp{make install} report that
8123 nothing was to be done!
8125 That's all dependent on whether the file system is a UFS (case
8126 sensitive) or HFS+ (case preserving). By default Apple wants you to
8127 install the OS on HFS+. Unfortunately, there are some pieces of
8128 software which really need to be built on UFS@. We may want to rebuild
8129 Darwin to have both UFS and HFS+ available (and put the /local/build
8132 @item @acronym{QNX} 4.25
8133 @cindex @acronym{QNX} 4.25
8134 @c FIXME: Please, if you feel like writing something more precise,
8135 @c it'd be great. In particular, I can't understand the difference with
8137 @acronym{QNX} is a realtime operating system running on Intel architecture
8138 meant to be scalable from the small embedded systems to the hundred
8139 processor super-computer. It claims to be Posix certified. More
8140 information is available on the
8141 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
8145 @uref{http://h30097.www3.hp.com/@/docs/,
8146 Documentation of several versions of Tru64} is available in different
8149 @item Unix version 7
8150 @cindex Unix version 7
8152 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
8153 time-sharing system'' but we use the more-common name ``Unix version 7''.
8154 Documentation is available in the
8155 @uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
8156 Previous versions of Unix are called ``Unix version 6'', etc., but
8157 they were not as widely used.
8161 @node Multiple Cases
8162 @section Multiple Cases
8164 Some operations are accomplished in several possible ways, depending on
8165 the OS variant. Checking for them essentially requires a ``case
8166 statement''. Autoconf does not directly provide one; however, it is
8167 easy to simulate by using a shell variable to keep track of whether a
8168 way to perform the operation has been found yet.
8170 Here is an example that uses the shell variable @code{fstype} to keep
8171 track of whether the remaining cases need to be checked.
8175 AC_MSG_CHECKING([how to get file system type])
8177 # The order of these tests is important.
8178 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
8179 #include <sys/fstyp.h>]])],
8180 [AC_DEFINE([FSTYPE_STATVFS], [1],
8181 [Define if statvfs exists.])
8183 if test $fstype = no; then
8184 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8185 #include <sys/fstyp.h>]])],
8186 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
8187 [Define if USG statfs.])
8190 if test $fstype = no; then
8191 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8192 #include <sys/vmount.h>]])]),
8193 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
8194 [Define if AIX statfs.])
8197 # (more cases omitted here)
8198 AC_MSG_RESULT([$fstype])
8202 @c ====================================================== Results of Tests.
8205 @chapter Results of Tests
8207 Once @command{configure} has determined whether a feature exists, what can
8208 it do to record that information? There are four sorts of things it can
8209 do: define a C preprocessor symbol, set a variable in the output files,
8210 save the result in a cache file for future @command{configure} runs, and
8211 print a message letting the user know the result of the test.
8214 * Defining Symbols:: Defining C preprocessor symbols
8215 * Setting Output Variables:: Replacing variables in output files
8216 * Special Chars in Variables:: Characters to beware of in variables
8217 * Caching Results:: Speeding up subsequent @command{configure} runs
8218 * Printing Messages:: Notifying @command{configure} users
8221 @node Defining Symbols
8222 @section Defining C Preprocessor Symbols
8224 A common action to take in response to a feature test is to define a C
8225 preprocessor symbol indicating the results of the test. That is done by
8226 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
8228 By default, @code{AC_OUTPUT} places the symbols defined by these macros
8229 into the output variable @code{DEFS}, which contains an option
8230 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
8231 Autoconf version 1, there is no variable @code{DEFS} defined while
8232 @command{configure} is running. To check whether Autoconf macros have
8233 already defined a certain C preprocessor symbol, test the value of the
8234 appropriate cache variable, as in this example:
8237 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
8238 [Define if vprintf exists.])])
8239 if test "$ac_cv_func_vprintf" != yes; then
8240 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
8241 [Define if _doprnt exists.])])
8245 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
8246 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
8247 correct values into @code{#define} statements in a template file.
8248 @xref{Configuration Headers}, for more information about this kind of
8251 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
8252 @defmacx AC_DEFINE (@var{variable})
8254 Define @var{variable} to @var{value} (verbatim), by defining a C
8255 preprocessor macro for @var{variable}. @var{variable} should be a C
8256 identifier, optionally suffixed by a parenthesized argument list to
8257 define a C preprocessor macro with arguments. The macro argument list,
8258 if present, should be a comma-separated list of C identifiers, possibly
8259 terminated by an ellipsis @samp{...} if C99 syntax is employed.
8260 @var{variable} should not contain comments, white space, trigraphs,
8261 backslash-newlines, universal character names, or non-@acronym{ASCII}
8264 @var{value} should not contain literal newlines, and if you are not
8265 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
8266 characters, as @command{make} tends to eat them. To use a shell variable,
8267 use @code{AC_DEFINE_UNQUOTED} instead.
8268 @var{description} is only useful if you are using
8269 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
8270 the generated @file{config.h.in} as the comment before the macro define.
8271 The following example defines the C preprocessor variable
8272 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
8275 AC_DEFINE([EQUATION], ["$a > $b"],
8279 If neither @var{value} nor @var{description} are given, then
8280 @var{value} defaults to 1 instead of to the empty string. This is for
8281 backwards compatibility with older versions of Autoconf, but this usage
8282 is obsolescent and may be withdrawn in future versions of Autoconf.
8284 If the @var{variable} is a literal string, it is passed to
8285 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
8287 If multiple @code{AC_DEFINE} statements are executed for the same
8288 @var{variable} name (not counting any parenthesized argument list),
8292 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
8293 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
8294 @acindex{DEFINE_UNQUOTED}
8295 Like @code{AC_DEFINE}, but three shell expansions are
8296 performed---once---on @var{variable} and @var{value}: variable expansion
8297 (@samp{$}), command substitution (@samp{`}), and backslash escaping
8298 (@samp{\}). Single and double quote characters in the value have no
8299 special meaning. Use this macro instead of @code{AC_DEFINE} when
8300 @var{variable} or @var{value} is a shell variable. Examples:
8303 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
8304 [Configuration machine file.])
8305 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
8306 [getgroups return type.])
8307 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
8308 [Translated header name.])
8312 Due to a syntactical bizarreness of the Bourne shell, do not use
8313 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
8314 calls from other macro calls or shell code; that can cause syntax errors
8315 in the resulting @command{configure} script. Use either blanks or
8316 newlines. That is, do this:
8319 AC_CHECK_HEADER([elf.h],
8320 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
8327 AC_CHECK_HEADER([elf.h],
8328 [AC_DEFINE([SVR4], [1], [System V Release 4])
8329 LIBS="-lelf $LIBS"])
8336 AC_CHECK_HEADER([elf.h],
8337 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8340 @node Setting Output Variables
8341 @section Setting Output Variables
8342 @cindex Output variables
8344 Another way to record the results of tests is to set @dfn{output
8345 variables}, which are shell variables whose values are substituted into
8346 files that @command{configure} outputs. The two macros below create new
8347 output variables. @xref{Preset Output Variables}, for a list of output
8348 variables that are always available.
8350 @defmac AC_SUBST (@var{variable}, @ovar{value})
8352 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
8353 substitute the variable @var{variable} into output files (typically one
8354 or more makefiles). This means that @code{AC_OUTPUT}
8355 replaces instances of @samp{@@@var{variable}@@} in input files with the
8356 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8357 is called. The value can contain newlines.
8358 Variable occurrences should not overlap: e.g., an input file should
8359 not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
8361 The substituted value is not rescanned for more output variables;
8362 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8363 literally into the output file. (The algorithm uses the special marker
8364 @code{|#_!!_#|} internally, so neither the substituted value nor the
8365 output file may contain @code{|#_!!_#|}.)
8367 If @var{value} is given, in addition assign it to @var{variable}.
8369 The string @var{variable} is passed to @code{m4_pattern_allow}
8370 (@pxref{Forbidden Patterns}).
8373 @defmac AC_SUBST_FILE (@var{variable})
8374 @acindex{SUBST_FILE}
8375 Another way to create an output variable from a shell variable. Make
8376 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8377 named by shell variable @var{variable} into output files. This means
8378 that @code{AC_OUTPUT} replaces instances of
8379 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8380 with the contents of the file that the shell variable @var{variable}
8381 names when @code{AC_OUTPUT} is called. Set the variable to
8382 @file{/dev/null} for cases that do not have a file to insert.
8383 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8384 line by itself, optionally surrounded by spaces and tabs. The
8385 substitution replaces the whole line, including the spaces, tabs, and
8386 the terminating newline.
8388 This macro is useful for inserting makefile fragments containing
8389 special dependencies or other @code{make} directives for particular host
8390 or target types into makefiles. For example, @file{configure.ac}
8394 AC_SUBST_FILE([host_frag])
8395 host_frag=$srcdir/conf/sun4.mh
8399 and then a @file{Makefile.in} could contain:
8405 The string @var{variable} is passed to @code{m4_pattern_allow}
8406 (@pxref{Forbidden Patterns}).
8409 @cindex Precious Variable
8410 @cindex Variable, Precious
8411 Running @command{configure} in varying environments can be extremely
8412 dangerous. If for instance the user runs @samp{CC=bizarre-cc
8413 ./configure}, then the cache, @file{config.h}, and many other output
8414 files depend upon @command{bizarre-cc} being the C compiler. If
8415 for some reason the user runs @command{./configure} again, or if it is
8416 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8417 and @pxref{config.status Invocation}), then the configuration can be
8418 inconsistent, composed of results depending upon two different
8421 Environment variables that affect this situation, such as @samp{CC}
8422 above, are called @dfn{precious variables}, and can be declared as such
8423 by @code{AC_ARG_VAR}.
8425 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8427 Declare @var{variable} is a precious variable, and include its
8428 @var{description} in the variable section of @samp{./configure --help}.
8430 Being precious means that
8433 @var{variable} is substituted via @code{AC_SUBST}.
8436 The value of @var{variable} when @command{configure} was launched is
8437 saved in the cache, including if it was not specified on the command
8438 line but via the environment. Indeed, while @command{configure} can
8439 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8440 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8441 which, unfortunately, is what most users do.
8443 We emphasize that it is the @emph{initial} value of @var{variable} which
8444 is saved, not that found during the execution of @command{configure}.
8445 Indeed, specifying @samp{./configure FOO=foo} and letting
8446 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
8450 @var{variable} is checked for consistency between two
8451 @command{configure} runs. For instance:
8454 $ @kbd{./configure --silent --config-cache}
8455 $ @kbd{CC=cc ./configure --silent --config-cache}
8456 configure: error: `CC' was not set in the previous run
8457 configure: error: changes in the environment can compromise \
8459 configure: error: run `make distclean' and/or \
8460 `rm config.cache' and start over
8464 and similarly if the variable is unset, or if its content is changed.
8468 @var{variable} is kept during automatic reconfiguration
8469 (@pxref{config.status Invocation}) as if it had been passed as a command
8470 line argument, including when no cache is used:
8473 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
8474 $ @kbd{./config.status --recheck}
8475 running CONFIG_SHELL=/bin/sh /bin/sh ./configure undeclared_var=raboof \
8476 CC=/usr/bin/cc --no-create --no-recursion
8481 @node Special Chars in Variables
8482 @section Special Characters in Output Variables
8483 @cindex Output variables, special characters in
8485 Many output variables are intended to be evaluated both by
8486 @command{make} and by the shell. Some characters are expanded
8487 differently in these two contexts, so to avoid confusion these
8488 variables' values should not contain any of the following characters:
8491 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8494 Also, these variables' values should neither contain newlines, nor start
8495 with @samp{~}, nor contain white space or @samp{:} immediately followed
8496 by @samp{~}. The values can contain nonempty sequences of white space
8497 characters like tabs and spaces, but each such sequence might
8498 arbitrarily be replaced by a single space during substitution.
8500 These restrictions apply both to the values that @command{configure}
8501 computes, and to the values set directly by the user. For example, the
8502 following invocations of @command{configure} are problematic, since they
8503 attempt to use special characters within @code{CPPFLAGS} and white space
8504 within @code{$(srcdir)}:
8507 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
8509 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
8512 @node Caching Results
8513 @section Caching Results
8516 To avoid checking for the same features repeatedly in various
8517 @command{configure} scripts (or in repeated runs of one script),
8518 @command{configure} can optionally save the results of many checks in a
8519 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
8520 runs with caching enabled and finds a cache file, it reads the results
8521 of previous runs from the cache and avoids rerunning those checks. As a
8522 result, @command{configure} can then run much faster than if it had to
8523 perform all of the checks every time.
8525 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8527 Ensure that the results of the check identified by @var{cache-id} are
8528 available. If the results of the check were in the cache file that was
8529 read, and @command{configure} was not given the @option{--quiet} or
8530 @option{--silent} option, print a message saying that the result was
8531 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
8532 the shell commands are run to determine the value, the value is
8533 saved in the cache file just before @command{configure} creates its output
8534 files. @xref{Cache Variable Names}, for how to choose the name of the
8535 @var{cache-id} variable.
8537 The @var{commands-to-set-it} @emph{must have no side effects} except for
8538 setting the variable @var{cache-id}, see below.
8541 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
8542 @acindex{CACHE_CHECK}
8543 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8544 messages. This macro provides a convenient shorthand for the most
8545 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
8546 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8547 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8549 The @var{commands-to-set-it} @emph{must have no side effects} except for
8550 setting the variable @var{cache-id}, see below.
8553 It is common to find buggy macros using @code{AC_CACHE_VAL} or
8554 @code{AC_CACHE_CHECK}, because people are tempted to call
8555 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
8556 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8557 @code{AC_DEFINE}, by examining the value of the cache variable. For
8558 instance, the following macro is broken:
8562 AC_DEFUN([AC_SHELL_TRUE],
8563 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8564 [ac_cv_shell_true_works=no
8565 (true) 2>/dev/null && ac_cv_shell_true_works=yes
8566 if test "$ac_cv_shell_true_works" = yes; then
8567 AC_DEFINE([TRUE_WORKS], [1],
8568 [Define if `true(1)' works properly.])
8575 This fails if the cache is enabled: the second time this macro is run,
8576 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
8581 AC_DEFUN([AC_SHELL_TRUE],
8582 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8583 [ac_cv_shell_true_works=no
8584 (true) 2>/dev/null && ac_cv_shell_true_works=yes])
8585 if test "$ac_cv_shell_true_works" = yes; then
8586 AC_DEFINE([TRUE_WORKS], [1],
8587 [Define if `true(1)' works properly.])
8593 Also, @var{commands-to-set-it} should not print any messages, for
8594 example with @code{AC_MSG_CHECKING}; do that before calling
8595 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8596 the results of the check are retrieved from the cache or determined by
8597 running the shell commands.
8600 * Cache Variable Names:: Shell variables used in caches
8601 * Cache Files:: Files @command{configure} uses for caching
8602 * Cache Checkpointing:: Loading and saving the cache file
8605 @node Cache Variable Names
8606 @subsection Cache Variable Names
8607 @cindex Cache variable
8609 The names of cache variables should have the following format:
8612 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8616 for example, @samp{ac_cv_header_stat_broken} or
8617 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
8620 @item @var{package-prefix}
8621 An abbreviation for your package or organization; the same prefix you
8622 begin local Autoconf macros with, except lowercase by convention.
8623 For cache values used by the distributed Autoconf macros, this value is
8627 Indicates that this shell variable is a cache value. This string
8628 @emph{must} be present in the variable name, including the leading
8631 @item @var{value-type}
8632 A convention for classifying cache values, to produce a rational naming
8633 system. The values used in Autoconf are listed in @ref{Macro Names}.
8635 @item @var{specific-value}
8636 Which member of the class of cache values this test applies to.
8637 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8638 output variable (@samp{INSTALL}).
8640 @item @var{additional-options}
8641 Any particular behavior of the specific member that this test applies to.
8642 For example, @samp{broken} or @samp{set}. This part of the name may
8643 be omitted if it does not apply.
8646 The values assigned to cache variables may not contain newlines.
8647 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
8648 names of files or functions; so this is not an important restriction.
8651 @subsection Cache Files
8653 A cache file is a shell script that caches the results of configure
8654 tests run on one system so they can be shared between configure scripts
8655 and configure runs. It is not useful on other systems. If its contents
8656 are invalid for some reason, the user may delete or edit it.
8658 By default, @command{configure} uses no cache file,
8659 to avoid problems caused by accidental
8660 use of stale cache files.
8662 To enable caching, @command{configure} accepts @option{--config-cache} (or
8663 @option{-C}) to cache results in the file @file{config.cache}.
8664 Alternatively, @option{--cache-file=@var{file}} specifies that
8665 @var{file} be the cache file. The cache file is created if it does not
8666 exist already. When @command{configure} calls @command{configure} scripts in
8667 subdirectories, it uses the @option{--cache-file} argument so that they
8668 share the same cache. @xref{Subdirectories}, for information on
8669 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8671 @file{config.status} only pays attention to the cache file if it is
8672 given the @option{--recheck} option, which makes it rerun
8673 @command{configure}.
8675 It is wrong to try to distribute cache files for particular system types.
8676 There is too much room for error in doing that, and too much
8677 administrative overhead in maintaining them. For any features that
8678 can't be guessed automatically, use the standard method of the canonical
8679 system type and linking files (@pxref{Manual Configuration}).
8681 The site initialization script can specify a site-wide cache file to
8682 use, instead of the usual per-program cache. In this case, the cache
8683 file gradually accumulates information whenever someone runs a new
8684 @command{configure} script. (Running @command{configure} merges the new cache
8685 results with the existing cache file.) This may cause problems,
8686 however, if the system configuration (e.g., the installed libraries or
8687 compilers) changes and the stale cache file is not deleted.
8689 @node Cache Checkpointing
8690 @subsection Cache Checkpointing
8692 If your configure script, or a macro called from @file{configure.ac}, happens
8693 to abort the configure process, it may be useful to checkpoint the cache
8694 a few times at key points using @code{AC_CACHE_SAVE}. Doing so
8695 reduces the amount of time it takes to rerun the configure script with
8696 (hopefully) the error that caused the previous abort corrected.
8698 @c FIXME: Do we really want to document this guy?
8699 @defmac AC_CACHE_LOAD
8700 @acindex{CACHE_LOAD}
8701 Loads values from existing cache file, or creates a new cache file if a
8702 cache file is not found. Called automatically from @code{AC_INIT}.
8705 @defmac AC_CACHE_SAVE
8706 @acindex{CACHE_SAVE}
8707 Flushes all cached values to the cache file. Called automatically from
8708 @code{AC_OUTPUT}, but it can be quite useful to call
8709 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8715 @r{ @dots{} AC_INIT, etc. @dots{}}
8717 # Checks for programs.
8720 @r{ @dots{} more program checks @dots{}}
8725 # Checks for libraries.
8726 AC_CHECK_LIB([nsl], [gethostbyname])
8727 AC_CHECK_LIB([socket], [connect])
8728 @r{ @dots{} more lib checks @dots{}}
8733 # Might abort@dots{}
8734 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8735 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8737 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8740 @node Printing Messages
8741 @section Printing Messages
8742 @cindex Messages, from @command{configure}
8744 @command{configure} scripts need to give users running them several kinds
8745 of information. The following macros print messages in ways appropriate
8746 for each kind. The arguments to all of them get enclosed in shell
8747 double quotes, so the shell performs variable and back-quote
8748 substitution on them.
8750 These macros are all wrappers around the @command{echo} shell command.
8751 They direct output to the appropriate file descriptor (@pxref{File
8752 Descriptor Macros}).
8753 @command{configure} scripts should rarely need to run @command{echo} directly
8754 to print messages for the user. Using these macros makes it easy to
8755 change how and when each kind of message is printed; such changes need
8756 only be made to the macro definitions and all the callers change
8759 To diagnose static issues, i.e., when @command{autoconf} is run, see
8760 @ref{Reporting Messages}.
8762 @defmac AC_MSG_CHECKING (@var{feature-description})
8763 @acindex{MSG_CHECKING}
8764 Notify the user that @command{configure} is checking for a particular
8765 feature. This macro prints a message that starts with @samp{checking }
8766 and ends with @samp{...} and no newline. It must be followed by a call
8767 to @code{AC_MSG_RESULT} to print the result of the check and the
8768 newline. The @var{feature-description} should be something like
8769 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
8772 This macro prints nothing if @command{configure} is run with the
8773 @option{--quiet} or @option{--silent} option.
8776 @defmac AC_MSG_RESULT (@var{result-description})
8777 @acindex{MSG_RESULT}
8778 Notify the user of the results of a check. @var{result-description} is
8779 almost always the value of the cache variable for the check, typically
8780 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
8781 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
8782 the completion of the message printed by the call to
8783 @code{AC_MSG_CHECKING}.
8785 This macro prints nothing if @command{configure} is run with the
8786 @option{--quiet} or @option{--silent} option.
8789 @defmac AC_MSG_NOTICE (@var{message})
8790 @acindex{MSG_NOTICE}
8791 Deliver the @var{message} to the user. It is useful mainly to print a
8792 general description of the overall purpose of a group of feature checks,
8796 AC_MSG_NOTICE([checking if stack overflow is detectable])
8799 This macro prints nothing if @command{configure} is run with the
8800 @option{--quiet} or @option{--silent} option.
8803 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
8805 Notify the user of an error that prevents @command{configure} from
8806 completing. This macro prints an error message to the standard error
8807 output and exits @command{configure} with @var{exit-status} (1 by default).
8808 @var{error-description} should be something like @samp{invalid value
8811 The @var{error-description} should start with a lower-case letter, and
8812 ``cannot'' is preferred to ``can't''.
8815 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
8816 @acindex{MSG_FAILURE}
8817 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
8818 prevents @command{configure} from completing @emph{and} that additional
8819 details are provided in @file{config.log}. This is typically used when
8820 abnormal results are found during a compilation.
8823 @defmac AC_MSG_WARN (@var{problem-description})
8825 Notify the @command{configure} user of a possible problem. This macro
8826 prints the message to the standard error output; @command{configure}
8827 continues running afterward, so macros that call @code{AC_MSG_WARN} should
8828 provide a default (back-up) behavior for the situations they warn about.
8829 @var{problem-description} should be something like @samp{ln -s seems to
8835 @c ====================================================== Programming in M4.
8837 @node Programming in M4
8838 @chapter Programming in M4
8841 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
8842 convenient macros for pure M4 programming, and @dfn{M4sh}, which
8843 provides macros dedicated to shell script generation.
8845 As of this version of Autoconf, these two layers are still experimental,
8846 and their interface might change in the future. As a matter of fact,
8847 @emph{anything that is not documented must not be used}.
8850 * M4 Quotation:: Protecting macros from unwanted expansion
8851 * Using autom4te:: The Autoconf executables backbone
8852 * Programming in M4sugar:: Convenient pure M4 macros
8853 * Programming in M4sh:: Common shell Constructs
8854 * File Descriptor Macros:: File descriptor macros for input and output
8858 @section M4 Quotation
8859 @cindex M4 quotation
8862 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
8863 @c prevented `expansion' of $1. Unless it refers to the expansion
8864 @c of the value of $1? Anyway, we need a rewrite here@enddots{}
8866 The most common problem with existing macros is an improper quotation.
8867 This section, which users of Autoconf can skip, but which macro writers
8868 @emph{must} read, first justifies the quotation scheme that was chosen
8869 for Autoconf and then ends with a rule of thumb. Understanding the
8870 former helps one to follow the latter.
8873 * Active Characters:: Characters that change the behavior of M4
8874 * One Macro Call:: Quotation and one macro call
8875 * Quotation and Nested Macros:: Macros calling macros
8876 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
8877 * Quadrigraphs:: Another way to escape special characters
8878 * Quotation Rule Of Thumb:: One parenthesis, one quote
8881 @node Active Characters
8882 @subsection Active Characters
8884 To fully understand where proper quotation is important, you first need
8885 to know what the special characters are in Autoconf: @samp{#} introduces
8886 a comment inside which no macro expansion is performed, @samp{,}
8887 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
8888 and finally @samp{(} and @samp{)} (which M4 tries to match by
8891 In order to understand the delicate case of macro calls, we first have
8892 to present some obvious failures. Below they are ``obvious-ified'',
8893 but when you find them in real life, they are usually in disguise.
8895 Comments, introduced by a hash and running up to the newline, are opaque
8896 tokens to the top level: active characters are turned off, and there is
8900 # define([def], ine)
8901 @result{}# define([def], ine)
8904 Each time there can be a macro expansion, there is a quotation
8905 expansion, i.e., one level of quotes is stripped:
8911 @result{}int tab[10];
8914 Without this in mind, the reader might try hopelessly to use her macro
8918 define([array], [int tab[10];])
8926 How can you correctly output the intended results@footnote{Using
8930 @node One Macro Call
8931 @subsection One Macro Call
8933 Let's proceed on the interaction between active characters and macros
8934 with this small macro, which just returns its first argument:
8941 The two pairs of quotes above are not part of the arguments of
8942 @code{define}; rather, they are understood by the top level when it
8943 tries to find the arguments of @code{define}. Therefore, assuming
8944 @code{car} is not already defined, it is equivalent to write:
8951 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
8952 quotes, it is bad practice for Autoconf macros which must both be more
8953 robust and also advocate perfect style.
8955 At the top level, there are only two possibilities: either you
8961 [car(foo, bar, baz)]
8962 @result{}car(foo, bar, baz)
8965 Let's pay attention to the special characters:
8969 @error{}EOF in argument list
8972 The closing parenthesis is hidden in the comment; with a hypothetical
8973 quoting, the top level understood it this way:
8980 Proper quotation, of course, fixes the problem:
8987 Here are more examples:
9010 With this in mind, we can explore the cases where macros invoke
9014 @node Quotation and Nested Macros
9015 @subsection Quotation and Nested Macros
9017 The examples below use the following macros:
9021 define([active], [ACT, IVE])
9022 define([array], [int tab[10]])
9025 Each additional embedded macro call introduces other possible
9026 interesting quotations:
9037 In the first case, the top level looks for the arguments of @code{car},
9038 and finds @samp{active}. Because M4 evaluates its arguments
9039 before applying the macro, @samp{active} is expanded, which results in:
9047 In the second case, the top level gives @samp{active} as first and only
9048 argument of @code{car}, which results in:
9056 i.e., the argument is evaluated @emph{after} the macro that invokes it.
9057 In the third case, @code{car} receives @samp{[active]}, which results in:
9065 exactly as we already saw above.
9067 The example above, applied to a more realistic example, gives:
9074 car([[int tab[10];]])
9075 @result{}int tab[10];
9079 Huh? The first case is easily understood, but why is the second wrong,
9080 and the third right? To understand that, you must know that after
9081 M4 expands a macro, the resulting text is immediately subjected
9082 to macro expansion and quote removal. This means that the quote removal
9083 occurs twice---first before the argument is passed to the @code{car}
9084 macro, and second after the @code{car} macro expands to the first
9087 As the author of the Autoconf macro @code{car}, you then consider it to
9088 be incorrect that your users have to double-quote the arguments of
9089 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
9093 define([qar], [[$1]])
9097 and check that @code{qar} is properly fixed:
9101 @result{}int tab[10];
9105 Ahhh! That's much better.
9107 But note what you've done: now that the arguments are literal strings,
9108 if the user wants to use the results of expansions as arguments, she has
9109 to use an @emph{unquoted} macro call:
9117 where she wanted to reproduce what she used to do with @code{car}:
9125 Worse yet: she wants to use a macro that produces a set of @code{cpp}
9129 define([my_includes], [#include <stdio.h>])
9131 @result{}#include <stdio.h>
9133 @error{}EOF in argument list
9136 This macro, @code{qar}, because it double quotes its arguments, forces
9137 its users to leave their macro calls unquoted, which is dangerous.
9138 Commas and other active symbols are interpreted by M4 before
9139 they are given to the macro, often not in the way the users expect.
9140 Also, because @code{qar} behaves differently from the other macros,
9141 it's an exception that should be avoided in Autoconf.
9143 @node Changequote is Evil
9144 @subsection @code{changequote} is Evil
9145 @cindex @code{changequote}
9147 The temptation is often high to bypass proper quotation, in particular
9148 when it's late at night. Then, many experienced Autoconf hackers
9149 finally surrender to the dark side of the force and use the ultimate
9150 weapon: @code{changequote}.
9152 The M4 builtin @code{changequote} belongs to a set of primitives that
9153 allow one to adjust the syntax of the language to adjust it to one's
9154 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
9155 quotes, but in the context of shell programming (and actually of most
9156 programming languages), that's about the worst choice one can make:
9157 because of strings and back-quoted expressions in shell code (such as
9158 @samp{'this'} and @samp{`that`}), because of literal characters in usual
9159 programming languages (as in @samp{'0'}), there are many unbalanced
9160 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
9161 not impossible. In order to make M4 useful in such a context, its
9162 designers have equipped it with @code{changequote}, which makes it
9163 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
9164 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
9165 because they are unlikely characters, but @emph{because they are
9166 characters unlikely to be unbalanced}.
9168 There are other magic primitives, such as @code{changecom} to specify
9169 what syntactic forms are comments (it is common to see
9170 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
9171 @code{changeword} and @code{changesyntax} to change other syntactic
9172 details (such as the character to denote the @var{n}th argument, @samp{$} by
9173 default, the parenthesis around arguments, etc.).
9175 These primitives are really meant to make M4 more useful for specific
9176 domains: they should be considered like command line options:
9177 @option{--quotes}, @option{--comments}, @option{--words}, and
9178 @option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
9179 it makes M4 libraries self contained (no need for additional options).
9181 There lies the problem@enddots{}
9185 The problem is that it is then tempting to use them in the middle of an
9186 M4 script, as opposed to its initialization. This, if not carefully
9187 thought out, can lead to disastrous effects: @emph{you are changing the
9188 language in the middle of the execution}. Changing and restoring the
9189 syntax is often not enough: if you happened to invoke macros in between,
9190 these macros are lost, as the current syntax is probably not
9191 the one they were implemented with.
9193 @c FIXME: I've been looking for a short, real case example, but I
9198 @subsection Quadrigraphs
9199 @cindex quadrigraphs
9200 @cindex @samp{@@S|@@}
9201 @cindex @samp{@@&t@@}
9202 @c Info cannot handle `:' in index entries.
9203 @c @cindex @samp{@@<:@@}
9204 @c @cindex @samp{@@:>@@}
9205 @c @cindex @samp{@@%:@@}
9207 When writing an Autoconf macro you may occasionally need to generate
9208 special characters that are difficult to express with the standard
9209 Autoconf quoting rules. For example, you may need to output the regular
9210 expression @samp{[^[]}, which matches any character other than @samp{[}.
9211 This expression contains unbalanced brackets so it cannot be put easily
9214 You can work around this problem by using one of the following
9230 Quadrigraphs are replaced at a late stage of the translation process,
9231 after @command{m4} is run, so they do not get in the way of M4 quoting.
9232 For example, the string @samp{^@@<:@@}, independently of its quotation,
9233 appears as @samp{^[} in the output.
9235 The empty quadrigraph can be used:
9238 @item to mark trailing spaces explicitly
9240 Trailing spaces are smashed by @command{autom4te}. This is a feature.
9242 @item to produce other quadrigraphs
9244 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
9246 @item to escape @emph{occurrences} of forbidden patterns
9248 For instance you might want to mention @code{AC_FOO} in a comment, while
9249 still being sure that @command{autom4te} still catches unexpanded
9250 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
9253 The name @samp{@@&t@@} was suggested by Paul Eggert:
9256 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
9257 own invention, but the @samp{t} came from the source code of the
9258 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
9259 and which used @samp{mt} to denote the empty string. In C, it would
9260 have looked like something like:
9263 char const mt[] = "";
9267 but of course the source code was written in Algol 68.
9269 I don't know where he got @samp{mt} from: it could have been his own
9270 invention, and I suppose it could have been a common pun around the
9271 Cambridge University computer lab at the time.
9274 @node Quotation Rule Of Thumb
9275 @subsection Quotation Rule Of Thumb
9277 To conclude, the quotation rule of thumb is:
9279 @center @emph{One pair of quotes per pair of parentheses.}
9281 Never over-quote, never under-quote, in particular in the definition of
9282 macros. In the few places where the macros need to use brackets
9283 (usually in C program text or regular expressions), properly quote
9284 @emph{the arguments}!
9286 It is common to read Autoconf programs with snippets like:
9290 changequote(<<, >>)dnl
9292 #ifndef tzname /* For SGI. */
9293 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9295 changequote([, ])dnl
9296 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
9300 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
9301 double quoting, so you just need:
9306 #ifndef tzname /* For SGI. */
9307 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9310 [ac_cv_var_tzname=yes],
9311 [ac_cv_var_tzname=no])
9315 The M4-fluent reader might note that these two examples are rigorously
9316 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
9317 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
9318 quotes are not part of the arguments!
9320 Simplified, the example above is just doing this:
9323 changequote(<<, >>)dnl
9325 changequote([, ])dnl
9335 With macros that do not double quote their arguments (which is the
9336 rule), double-quote the (risky) literals:
9339 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9341 #ifndef tzname /* For SGI. */
9342 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9344 [atoi (*tzname);])],
9345 [ac_cv_var_tzname=yes],
9346 [ac_cv_var_tzname=no])
9349 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9350 should be using @code{AC_LINK_IFELSE} instead.
9352 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9353 where quoting does not suffice.
9355 When you create a @command{configure} script using newly written macros,
9356 examine it carefully to check whether you need to add more quotes in
9357 your macros. If one or more words have disappeared in the M4
9358 output, you need more quotes. When in doubt, quote.
9360 However, it's also possible to put on too many layers of quotes. If
9361 this happens, the resulting @command{configure} script may contain
9362 unexpanded macros. The @command{autoconf} program checks for this problem
9363 by looking for the string @samp{AC_} in @file{configure}. However, this
9364 heuristic does not work in general: for example, it does not catch
9365 overquoting in @code{AC_DEFINE} descriptions.
9368 @c ---------------------------------------- Using autom4te
9370 @node Using autom4te
9371 @section Using @command{autom4te}
9373 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9374 to Autoconf per se, heavily rely on M4. All these different uses
9375 revealed common needs factored into a layer over M4:
9376 @command{autom4te}@footnote{
9378 Yet another great name from Lars J. Aas.
9382 @command{autom4te} is a preprocessor that is like @command{m4}.
9383 It supports M4 extensions designed for use in tools like Autoconf.
9386 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
9387 * Customizing autom4te:: Customizing the Autoconf package
9390 @node autom4te Invocation
9391 @subsection Invoking @command{autom4te}
9393 The command line arguments are modeled after M4's:
9396 autom4te @var{options} @var{files}
9401 where the @var{files} are directly passed to @command{m4}. By default,
9402 @acronym{GNU} M4 is found during configuration, but the environment
9404 @env{M4} can be set to tell @command{autom4te} where to look. In addition
9405 to the regular expansion, it handles the replacement of the quadrigraphs
9406 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9407 output. It supports an extended syntax for the @var{files}:
9410 @item @var{file}.m4f
9411 This file is an M4 frozen file. Note that @emph{all the previous files
9412 are ignored}. See the option @option{--melt} for the rationale.
9415 If found in the library path, the @var{file} is included for expansion,
9416 otherwise it is ignored instead of triggering a failure.
9421 Of course, it supports the Autoconf common subset of options:
9426 Print a summary of the command line options and exit.
9430 Print the version number of Autoconf and exit.
9434 Report processing steps.
9438 Don't remove the temporary files and be even more verbose.
9440 @item --include=@var{dir}
9442 Also look for input files in @var{dir}. Multiple invocations
9445 @item --output=@var{file}
9446 @itemx -o @var{file}
9447 Save output (script or trace) to @var{file}. The file @option{-} stands
9448 for the standard output.
9453 As an extension of @command{m4}, it includes the following options:
9456 @item --warnings=@var{category}
9457 @itemx -W @var{category}
9459 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9460 Report the warnings related to @var{category} (which can actually be a
9461 comma separated list). @xref{Reporting Messages}, macro
9462 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
9467 report all the warnings
9473 treats warnings as errors
9475 @item no-@var{category}
9476 disable warnings falling into @var{category}
9479 Warnings about @samp{syntax} are enabled by default, and the environment
9480 variable @env{WARNINGS}, a comma separated list of categories, is
9481 honored. @samp{autom4te -W @var{category}} actually
9482 behaves as if you had run:
9485 autom4te --warnings=syntax,$WARNINGS,@var{category}
9489 For example, if you want to disable defaults and @env{WARNINGS}
9490 of @command{autom4te}, but enable the warnings about obsolete
9491 constructs, you would use @option{-W none,obsolete}.
9494 @cindex Macro invocation stack
9495 @command{autom4te} displays a back trace for errors, but not for
9496 warnings; if you want them, just pass @option{-W error}.
9500 Do not use frozen files. Any argument @code{@var{file}.m4f} is
9501 replaced by @code{@var{file}.m4}. This helps tracing the macros which
9502 are executed only when the files are frozen, typically
9503 @code{m4_define}. For instance, running:
9506 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9510 is roughly equivalent to running:
9513 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9520 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9527 m4 --reload-state=4.m4f input.m4
9532 Produce a frozen state file. @command{autom4te} freezing is stricter
9533 than M4's: it must produce no warnings, and no output other than empty
9534 lines (a line with white space is @emph{not} empty) and comments
9535 (starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
9536 this option takes no argument:
9539 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9546 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9549 @item --mode=@var{octal-mode}
9550 @itemx -m @var{octal-mode}
9551 Set the mode of the non-traces output to @var{octal-mode}; by default
9557 @cindex @file{autom4te.cache}
9558 As another additional feature over @command{m4}, @command{autom4te}
9559 caches its results. @acronym{GNU} M4 is able to produce a regular
9560 output and traces at the same time. Traces are heavily used in the
9561 @acronym{GNU} Build System: @command{autoheader} uses them to build
9562 @file{config.h.in}, @command{autoreconf} to determine what
9563 @acronym{GNU} Build System components are used, @command{automake} to
9564 ``parse'' @file{configure.ac} etc. To avoid recomputation,
9565 traces are cached while performing regular expansion,
9566 and conversely. This cache is (actually, the caches are) stored in
9567 the directory @file{autom4te.cache}. @emph{It can safely be removed}
9568 at any moment (especially if for some reason @command{autom4te}
9569 considers it is trashed).
9572 @item --cache=@var{directory}
9573 @itemx -C @var{directory}
9574 Specify the name of the directory where the result should be cached.
9575 Passing an empty value disables caching. Be sure to pass a relative
9576 file name, as for the time being, global caches are not supported.
9579 Don't cache the results.
9583 If a cache is used, consider it obsolete (but update it anyway).
9588 Because traces are so important to the @acronym{GNU} Build System,
9589 @command{autom4te} provides high level tracing features as compared to
9590 M4, and helps exploiting the cache:
9593 @item --trace=@var{macro}[:@var{format}]
9594 @itemx -t @var{macro}[:@var{format}]
9595 Trace the invocations of @var{macro} according to the @var{format}.
9596 Multiple @option{--trace} arguments can be used to list several macros.
9597 Multiple @option{--trace} arguments for a single macro are not
9598 cumulative; instead, you should just make @var{format} as long as
9601 The @var{format} is a regular string, with newlines if desired, and
9602 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
9603 use the following special escapes:
9607 The character @samp{$}.
9610 The file name from which @var{macro} is called.
9613 The line number from which @var{macro} is called.
9616 The depth of the @var{macro} call. This is an M4 technical detail that
9617 you probably don't want to know about.
9620 The name of the @var{macro}.
9623 The @var{num}th argument of the call to @var{macro}.
9627 @itemx $@{@var{separator}@}@@
9628 All the arguments passed to @var{macro}, separated by the character
9629 @var{sep} or the string @var{separator} (@samp{,} by default). Each
9630 argument is quoted, i.e., enclosed in a pair of square brackets.
9634 @itemx $@{@var{separator}@}*
9635 As above, but the arguments are not quoted.
9639 @itemx $@{@var{separator}@}%
9640 As above, but the arguments are not quoted, all new line characters in
9641 the arguments are smashed, and the default separator is @samp{:}.
9643 The escape @samp{$%} produces single-line trace outputs (unless you put
9644 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9648 @xref{autoconf Invocation}, for examples of trace uses.
9650 @item --preselect=@var{macro}
9651 @itemx -p @var{macro}
9652 Cache the traces of @var{macro}, but do not enable traces. This is
9653 especially important to save CPU cycles in the future. For instance,
9654 when invoked, @command{autoconf} preselects all the macros that
9655 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
9656 trace, so that running @command{m4} is not needed to trace them: the
9657 cache suffices. This results in a huge speed-up.
9662 @cindex Autom4te Library
9663 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9664 libraries}. They consists in a powerful yet extremely simple feature:
9665 sets of combined command line arguments:
9668 @item --language=@var{language}
9669 @itemx -l @var{language}
9670 Use the @var{language} Autom4te library. Current languages include:
9674 create M4sugar output.
9677 create M4sh executable shell scripts.
9680 create Autotest executable test suites.
9682 @item Autoconf-without-aclocal-m4
9683 create Autoconf executable configure scripts without
9684 reading @file{aclocal.m4}.
9687 create Autoconf executable configure scripts. This language inherits
9688 all the characteristics of @code{Autoconf-without-aclocal-m4} and
9689 additionally reads @file{aclocal.m4}.
9692 @item --prepend-include=@var{dir}
9694 Prepend directory @var{dir} to the search path. This is used to include
9695 the language-specific files before any third-party macros.
9699 @cindex @file{autom4te.cfg}
9700 As an example, if Autoconf is installed in its default location,
9701 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
9702 strictly equivalent to the command:
9705 autom4te --prepend-include /usr/local/share/autoconf \
9706 m4sugar/m4sugar.m4f --warnings syntax foo.m4
9710 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
9711 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
9715 autom4te --prepend-include /usr/local/share/autoconf \
9716 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
9720 The definition of the languages is stored in @file{autom4te.cfg}.
9722 @node Customizing autom4te
9723 @subsection Customizing @command{autom4te}
9725 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
9726 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
9727 as found in the directory from which @command{autom4te} is run). The
9728 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
9729 then @file{./.autom4te.cfg}, and finally the command line arguments.
9731 In these text files, comments are introduced with @code{#}, and empty
9732 lines are ignored. Customization is performed on a per-language basis,
9733 wrapped in between a @samp{begin-language: "@var{language}"},
9734 @samp{end-language: "@var{language}"} pair.
9736 Customizing a language stands for appending options (@pxref{autom4te
9737 Invocation}) to the current definition of the language. Options, and
9738 more generally arguments, are introduced by @samp{args:
9739 @var{arguments}}. You may use the traditional shell syntax to quote the
9742 As an example, to disable Autoconf caches (@file{autom4te.cache})
9743 globally, include the following lines in @file{~/.autom4te.cfg}:
9746 ## ------------------ ##
9747 ## User Preferences. ##
9748 ## ------------------ ##
9750 begin-language: "Autoconf-without-aclocal-m4"
9752 end-language: "Autoconf-without-aclocal-m4"
9756 @node Programming in M4sugar
9757 @section Programming in M4sugar
9760 M4 by itself provides only a small, but sufficient, set of all-purpose
9761 macros. M4sugar introduces additional generic macros. Its name was
9762 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
9766 * Redefined M4 Macros:: M4 builtins changed in M4sugar
9767 * Looping constructs:: Iteration in M4
9768 * Evaluation Macros:: More quotation and evaluation control
9769 * Text processing Macros:: String manipulation in M4
9770 * Forbidden Patterns:: Catching unexpanded macros
9773 @node Redefined M4 Macros
9774 @subsection Redefined M4 Macros
9796 With a few exceptions, all the M4 native macros are moved in the
9797 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
9798 @code{m4_define} etc.
9800 Some M4 macros are redefined, and are slightly incompatible with their
9805 This macro kept its original name: no @code{m4_dnl} is defined.
9808 @defmac m4_defn (@var{macro})
9810 Unlike the M4 builtin, this macro fails if @var{macro} is not
9811 defined. See @code{m4_undefine}.
9814 @defmac m4_exit (@var{exit-status})
9816 This macro corresponds to @code{m4exit}.
9819 @defmac m4_if (@var{comment})
9820 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
9821 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
9823 This macro corresponds to @code{ifelse}.
9826 @defmac m4_include (@var{file})
9827 @defmacx m4_sinclude (@var{file})
9830 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
9833 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
9835 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
9836 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9837 provide extended regular expression syntax via @code{epatsubst}.
9840 @defmac m4_popdef (@var{macro})
9842 Unlike the M4 builtin, this macro fails if @var{macro} is not
9843 defined. See @code{m4_undefine}.
9846 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
9848 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
9849 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9850 provide extended regular expression syntax via @code{eregexp}.
9853 @defmac m4_wrap (@var{text})
9855 This macro corresponds to @code{m4wrap}.
9857 Posix requires arguments of multiple @code{m4wrap} calls to be
9858 reprocessed at @acronym{EOF} in the same order as the original calls.
9859 @acronym{GNU} M4 versions through 1.4.x, however, reprocess them in
9860 reverse order. Your code should not depend on the order.
9862 Also, Posix requires @code{m4wrap} to ignore its second and succeeding
9863 arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the
9864 arguments with intervening spaces. Your code should not pass more than
9867 You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected
9868 token pasting between consecutive invocations of @code{m4_wrap}, as in:
9871 m4_define([foo], [bar])
9872 m4_define([foofoo], [OUCH])
9879 @defmac m4_undefine (@var{macro})
9881 Unlike the M4 builtin, this macro fails if @var{macro} is not
9885 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
9889 to recover the behavior of the builtin.
9892 @defmac m4_maketemp (@var{template})
9893 @defmacx m4_mkstemp (@var{template})
9896 Posix requires @code{maketemp} to replace the trailing @samp{X}
9897 characters in @var{template} with the process id, without regards to the
9898 existence of a file by that name, but this a security hole. When this
9899 was pointed out to the Posix folks, they agreed to invent a new macro
9900 @code{mkstemp} that always creates a uniquely named file, but not all
9901 versions of @acronym{GNU} M4 support the new macro. In M4sugar,
9902 @code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
9903 and both have the secure semantics regardless of which macro the
9904 underlying M4 provides.
9908 @node Looping constructs
9909 @subsection Looping constructs
9911 The following macros implement loops in M4.
9913 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression})
9915 Loop over the numeric values between @var{first} and @var{last}
9916 including bounds by increments of @var{step}. For each iteration,
9917 expand @var{expression} with the numeric value assigned to @var{var}.
9918 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
9919 on the order of the limits. If given, @var{step} has to match this
9923 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
9925 Loop over the comma-separated M4 list @var{list}, assigning each value
9926 to @var{var}, and expand @var{expression}. The following example
9930 m4_foreach([myvar], [[foo], [bar, baz]],
9937 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
9939 Loop over the white-space-separated list @var{list}, assigning each value
9940 to @var{var}, and expand @var{expression}.
9942 The deprecated macro @code{AC_FOREACH} is an alias of
9943 @code{m4_foreach_w}.
9948 @node Evaluation Macros
9949 @subsection Evaluation Macros
9951 The following macros give some control over the order of the evaluation
9952 by adding or removing levels of quotes. They are meant for hard-core M4
9955 @defmac m4_dquote (@var{arg1}, @dots{})
9957 Return the arguments as a quoted list of quoted arguments.
9960 @defmac m4_quote (@var{arg1}, @dots{})
9962 Return the arguments as a single entity, i.e., wrap them into a pair of
9966 The following example aims at emphasizing the difference between (i), not
9967 using these macros, (ii), using @code{m4_quote}, and (iii), using
9971 $ @kbd{cat example.m4}
9972 # Overquote, so that quotes are visible.
9973 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
9974 m4_define([mkargs], [1, 2, 3])
9975 m4_define([arg1], [[$1]])
9978 show(m4_quote(a, b))
9979 show(m4_dquote(a, b))
9982 arg1(m4_defn([mkargs]))
9983 arg1(m4_quote(mkargs))
9984 arg1(m4_dquote(mkargs))
9985 $ @kbd{autom4te -l m4sugar example.m4}
9986 $1 = a, $@@ = [a],[b]
9987 $1 = a,b, $@@ = [a,b]
9988 $1 = [a],[b], $@@ = [[a],[b]]
9998 @node Text processing Macros
9999 @subsection Text processing Macros
10001 The following macros may be used to manipulate strings in M4.
10002 They are not intended for casual use.
10004 @defmac m4_re_escape (@var{string})
10005 @msindex{re_escape}
10006 Backslash-escape all characters in @var{string} that are active in
10010 @defmac m4_tolower (@var{string})
10011 @defmacx m4_toupper (@var{string})
10014 Return @var{string} with letters converted to upper or lower case,
10018 @defmac m4_split (@var{string}, @ovar{regexp})
10020 Split @var{string} into an M4 list of elements quoted by @samp{[} and
10021 @samp{]}, while keeping white space at the beginning and at the end.
10022 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
10023 If @var{string} is empty, the result is an empty list.
10026 @defmac m4_normalize (@var{string})
10027 @msindex{normalize}
10028 Remove leading and trailing spaces and tabs, sequences of
10029 backslash-then-newline, and replace multiple spaces and tabs with a
10033 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
10034 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
10036 @msindex{append_uniq}
10037 Redefine @var{macro-name} to its former contents with @var{separator}
10038 and @var{string} added at the end. If @var{macro-name} was undefined
10039 before (but not if it was defined but empty), then no @var{separator} is
10040 added. @code{m4_append} can be used to grow strings, and
10041 @code{m4_append_uniq} to grow strings without duplicating substrings.
10046 @node Forbidden Patterns
10047 @subsection Forbidden Patterns
10048 @cindex Forbidden patterns
10049 @cindex Patterns, forbidden
10051 M4sugar provides a means to define suspicious patterns, patterns
10052 describing tokens which should not be found in the output. For
10053 instance, if an Autoconf @file{configure} script includes tokens such as
10054 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
10055 wrong (typically a macro was not evaluated because of overquotation).
10057 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
10059 @defmac m4_pattern_forbid (@var{pattern})
10060 @msindex{pattern_forbid}
10061 Declare that no token matching @var{pattern} must be found in the output.
10062 Comments are not checked; this can be a problem if, for instance, you
10063 have some macro left unexpanded after an @samp{#include}. No consensus
10064 is currently found in the Autoconf community, as some people consider it
10065 should be valid to name macros in comments (which doesn't make sense to
10066 the author of this documentation, as @samp{#}-comments should document
10067 the output, not the input, documented by @samp{dnl} comments).
10070 Of course, you might encounter exceptions to these generic rules, for
10071 instance you might have to refer to @samp{$m4_flags}.
10073 @defmac m4_pattern_allow (@var{pattern})
10074 @msindex{pattern_allow}
10075 Any token matching @var{pattern} is allowed, including if it matches an
10076 @code{m4_pattern_forbid} pattern.
10079 @node Programming in M4sh
10080 @section Programming in M4sh
10082 @c FIXME: Eventually will become a chapter, as it is not related to
10083 @c programming in M4 per se.
10085 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
10086 scripts. This name was coined by Lars J. Aas, who notes that,
10087 according to the Webster's Revised Unabridged Dictionary (1913):
10090 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
10091 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
10095 A mass of mixed ingredients reduced to a soft pulpy state by beating or
10099 A mixture of meal or bran and water fed to animals.
10102 A mess; trouble. [Obs.] --Beau.@: & Fl.
10107 For the time being, it is not mature enough to be widely used.
10109 M4sh provides portable alternatives for some common shell constructs
10110 that unfortunately are not portable in practice.
10112 @c Deprecated, to be replaced by a better API
10114 @defmac AS_BASENAME (@var{file-name})
10116 Output the non-directory portion of @var{file-name}. For example,
10117 if @code{$file} is @samp{/one/two/three}, the command
10118 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
10122 @defmac AS_BOURNE_COMPATIBLE
10123 @asindex{BOURNE_COMPATIBLE}
10124 Set up the shell to be more compatible with the Bourne shell as
10125 standardized by Posix, if possible. This may involve setting
10126 environment variables, or setting options, or similar
10127 implementation-specific actions.
10130 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default})
10132 Expand into a shell @samp{case} statement, where @var{word} is matched
10133 against one or more patterns. @var{if-matched} is run if the
10134 corresponding pattern matched @var{word}, else @var{default} is run.
10137 @defmac AS_DIRNAME (@var{file-name})
10139 Output the directory portion of @var{file-name}. For example,
10140 if @code{$file} is @samp{/one/two/three}, the command
10141 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
10144 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
10146 Run shell code @var{test1}. If @var{test1} exits with a zero status then
10147 run shell code @var{run-if-true1}, else examine further tests. If no test
10148 exits with a zero status, run shell code @var{run-if-false}, with
10149 simplifications if either @var{run-if-true1} or @var{run-if-false1}
10150 is empty. For example,
10153 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
10154 [test "$foo" != no], [HANDLE_FOO([maybe])],
10155 [echo foo not specified])
10159 ensures any required macros of @code{HANDLE_FOO}
10160 are expanded before the first test.
10163 @defmac AS_MKDIR_P (@var{file-name})
10165 Make the directory @var{file-name}, including intervening directories
10166 as necessary. This is equivalent to @samp{mkdir -p @var{file-name}},
10167 except that it is portable to older versions of @command{mkdir} that
10168 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
10169 succeeds if @var{file-name} is a symbolic link to an existing directory,
10170 even though Posix is unclear whether @samp{mkdir -p} should
10171 succeed in that case. If creation of @var{file-name} fails, exit the
10174 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
10177 @defmac AS_SHELL_SANITIZE
10178 @asindex{SHELL_SANITIZE}
10179 Initialize the shell suitably for @code{configure} scripts. This has
10180 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
10181 environment variables for predictable results from configuration tests.
10182 For example, it sets @env{LC_ALL} to change to the default C locale.
10183 @xref{Special Shell Variables}.
10186 @defmac AS_TR_CPP (@var{expression})
10188 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
10192 # This outputs "#define HAVE_CHAR_P 1".
10194 echo "#define AS_TR_CPP([HAVE_$type]) 1"
10198 @defmac AS_TR_SH (@var{expression})
10200 Transform @var{expression} into a valid shell variable name. For example:
10203 # This outputs "Have it!".
10204 header="sys/some file.h"
10205 AS_TR_SH([HAVE_$header])=yes
10206 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
10210 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
10211 @asindex{SET_CATFILE}
10212 Set the shell variable @var{var} to @var{dir}/@var{file}, but
10213 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
10214 @var{file} is absolute, etc.).
10218 @node File Descriptor Macros
10219 @section File Descriptor Macros
10221 @cindex standard input
10222 @cindex file descriptors
10223 @cindex descriptors
10224 @cindex low-level output
10225 @cindex output, low-level
10227 The following macros define file descriptors used to output messages
10228 (or input values) from @file{configure} scripts.
10232 echo "$wombats found" >&AS_MESSAGE_LOG_FD
10233 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
10234 read kangaroos <&AS_ORIGINAL_STDIN_FD`
10238 However doing so is seldom needed, because Autoconf provides higher
10239 level macros as described below.
10241 @defmac AS_MESSAGE_FD
10242 @asindex{MESSAGE_FD}
10243 The file descriptor for @samp{checking for...} messages and results.
10244 Normally this directs messages to the standard output, however when
10245 @command{configure} is run with the @option{-q} option, messages sent to
10246 @code{AS_MESSAGE_FD} are discarded.
10248 If you want to display some messages, consider using one of the printing
10249 macros (@pxref{Printing Messages}) instead. Copies of messages output
10250 via these macros are also recorded in @file{config.log}.
10253 @defmac AS_MESSAGE_LOG_FD
10254 @asindex{MESSAGE_LOG_FD}
10256 The file descriptor for messages logged to @file{config.log}. Macros
10257 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
10258 Compiler}), redirect all output to this descriptor. You may want to do
10259 so if you develop such a low-level macro.
10262 @defmac AS_ORIGINAL_STDIN_FD
10263 @asindex{ORIGINAL_STDIN_FD}
10264 The file descriptor for the original standard input.
10266 When @command{configure} runs, it may accidentally execute an
10267 interactive command that has the same name as the non-interactive meant
10268 to be used or checked. If the standard input was the terminal, such
10269 interactive programs would cause @command{configure} to stop, pending
10270 some user input. Therefore @command{configure} redirects its standard
10271 input from @file{/dev/null} during its initialization. This is not
10272 normally a problem, since @command{configure} normally does not need
10275 In the extreme case where your @file{configure} script really needs to
10276 obtain some values from the original standard input, you can read them
10277 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
10281 @c =================================================== Writing Autoconf Macros.
10283 @node Writing Autoconf Macros
10284 @chapter Writing Autoconf Macros
10286 When you write a feature test that could be applicable to more than one
10287 software package, the best thing to do is encapsulate it in a new macro.
10288 Here are some instructions and guidelines for writing Autoconf macros.
10291 * Macro Definitions:: Basic format of an Autoconf macro
10292 * Macro Names:: What to call your new macros
10293 * Reporting Messages:: Notifying @command{autoconf} users
10294 * Dependencies Between Macros:: What to do when macros depend on other macros
10295 * Obsoleting Macros:: Warning about old ways of doing things
10296 * Coding Style:: Writing Autoconf macros @`a la Autoconf
10299 @node Macro Definitions
10300 @section Macro Definitions
10303 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
10304 similar to the M4 builtin @code{m4_define} macro. In addition to
10305 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
10306 constrain the order in which macros are called (@pxref{Prerequisite
10309 An Autoconf macro definition looks like this:
10312 AC_DEFUN(@var{macro-name}, @var{macro-body})
10315 You can refer to any arguments passed to the macro as @samp{$1},
10316 @samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
10317 @acronym{GNU} M4}, for more complete information on writing M4 macros.
10319 Be sure to properly quote both the @var{macro-body} @emph{and} the
10320 @var{macro-name} to avoid any problems if the macro happens to have
10321 been previously defined.
10323 Each macro should have a header comment that gives its prototype, and a
10324 brief description. When arguments have default values, display them in
10325 the prototype. For example:
10328 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
10329 # --------------------------------------
10330 m4_define([AC_MSG_ERROR],
10331 [@{ AS_MESSAGE([error: $1], [2])
10332 exit m4_default([$2], [1]); @}])
10335 Comments about the macro should be left in the header comment. Most
10336 other comments make their way into @file{configure}, so just keep
10337 using @samp{#} to introduce comments.
10340 If you have some special comments about pure M4 code, comments
10341 that make no sense in @file{configure} and in the header comment, then
10342 use the builtin @code{dnl}: it causes M4 to discard the text
10343 through the next newline.
10345 Keep in mind that @code{dnl} is rarely needed to introduce comments;
10346 @code{dnl} is more useful to get rid of the newlines following macros
10347 that produce no output, such as @code{AC_REQUIRE}.
10351 @section Macro Names
10353 All of the Autoconf macros have all-uppercase names starting with
10354 @samp{AC_} to prevent them from accidentally conflicting with other
10355 text. All shell variables that they use for internal purposes have
10356 mostly-lowercase names starting with @samp{ac_}. To ensure that your
10357 macros don't conflict with present or future Autoconf macros, you should
10358 prefix your own macro names and any shell variables they use with some
10359 other sequence. Possibilities include your initials, or an abbreviation
10360 for the name of your organization or software package.
10362 Most of the Autoconf macros' names follow a structured naming convention
10363 that indicates the kind of feature check by the name. The macro names
10364 consist of several words, separated by underscores, going from most
10365 general to most specific. The names of their cache variables use the
10366 same convention (@pxref{Cache Variable Names}, for more information on
10369 The first word of the name after @samp{AC_} usually tells the category
10370 of the feature being tested. Here are the categories used in Autoconf for
10371 specific test macros, the kind of macro that you are more likely to
10372 write. They are also used for cache variables, in all-lowercase. Use
10373 them where applicable; where they're not, invent your own categories.
10377 C language builtin features.
10379 Declarations of C variables in header files.
10381 Functions in libraries.
10383 Posix group owners of files.
10389 Absolute names of files, including programs.
10391 The base names of programs.
10393 Members of aggregates.
10395 Operating system features.
10397 C builtin or declared types.
10399 C variables in libraries.
10402 After the category comes the name of the particular feature being
10403 tested. Any further words in the macro name indicate particular aspects
10404 of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the
10405 C compiler supports @acronym{ISO} Standard C.
10407 An internal macro should have a name that starts with an underscore;
10408 Autoconf internals should therefore start with @samp{_AC_}.
10409 Additionally, a macro that is an internal subroutine of another macro
10410 should have a name that starts with an underscore and the name of that
10411 other macro, followed by one or more words saying what the internal
10412 macro does. For example, @code{AC_PATH_X} has internal macros
10413 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10415 @node Reporting Messages
10416 @section Reporting Messages
10417 @cindex Messages, from @command{autoconf}
10419 When macros statically diagnose abnormal situations, benign or fatal,
10420 they should report them using these macros. For dynamic issues, i.e.,
10421 when @command{configure} is run, see @ref{Printing Messages}.
10423 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10425 Report @var{message} as a warning (or as an error if requested by the
10426 user) if warnings of the @var{category} are turned on. You are
10427 encouraged to use standard categories, which currently include:
10431 messages that don't fall into one of the following categories. Use of an
10432 empty @var{category} is equivalent.
10435 related to cross compilation issues.
10438 use of an obsolete construct.
10441 dubious syntactic constructs, incorrectly ordered macro calls.
10445 @defmac AC_WARNING (@var{message})
10447 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10448 strongly encouraged to use a finer grained category.
10451 @defmac AC_FATAL (@var{message})
10453 Report a severe error @var{message}, and have @command{autoconf} die.
10456 When the user runs @samp{autoconf -W error}, warnings from
10457 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10458 @ref{autoconf Invocation}.
10460 @node Dependencies Between Macros
10461 @section Dependencies Between Macros
10462 @cindex Dependencies between macros
10464 Some Autoconf macros depend on other macros having been called first in
10465 order to work correctly. Autoconf provides a way to ensure that certain
10466 macros are called if needed and a way to warn the user if macros are
10467 called in an order that might cause incorrect operation.
10470 * Prerequisite Macros:: Ensuring required information
10471 * Suggested Ordering:: Warning about possible ordering problems
10472 * One-Shot Macros:: Ensuring a macro is called only once
10475 @node Prerequisite Macros
10476 @subsection Prerequisite Macros
10477 @cindex Prerequisite macros
10478 @cindex Macros, prerequisites
10480 A macro that you write might need to use values that have previously
10481 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
10482 examines the output of @code{flex} or @code{lex}, so it depends on
10483 @code{AC_PROG_LEX} having been called first to set the shell variable
10486 Rather than forcing the user of the macros to keep track of the
10487 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10488 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
10489 called if it is needed, and only called once.
10491 @defmac AC_REQUIRE (@var{macro-name})
10493 If the M4 macro @var{macro-name} has not already been called, call it
10494 (without any arguments). Make sure to quote @var{macro-name} with
10495 square brackets. @var{macro-name} must have been defined using
10496 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10497 that it has been called.
10499 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
10500 must not be called from the top level.
10503 @code{AC_REQUIRE} is often misunderstood. It really implements
10504 dependencies between macros in the sense that if one macro depends upon
10505 another, the latter is expanded @emph{before} the body of the
10506 former. To be more precise, the required macro is expanded before
10507 the outermost defined macro in the current expansion stack.
10508 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
10509 @code{FOO}. For instance, this definition of macros:
10513 AC_DEFUN([TRAVOLTA],
10514 [test "$body_temperature_in_celsius" -gt "38" &&
10515 dance_floor=occupied])
10516 AC_DEFUN([NEWTON_JOHN],
10517 [test "$hair_style" = "curly" &&
10518 dance_floor=occupied])
10522 AC_DEFUN([RESERVE_DANCE_FLOOR],
10523 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10524 AC_REQUIRE([TRAVOLTA])
10525 AC_REQUIRE([NEWTON_JOHN])
10531 with this @file{configure.ac}
10534 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
10535 RESERVE_DANCE_FLOOR
10536 if test "$dance_floor" = occupied; then
10537 AC_MSG_ERROR([cannot pick up here, let's move])
10542 does not leave you with a better chance to meet a kindred soul at
10543 other times than Saturday night since it expands into:
10547 test "$body_temperature_in_Celsius" -gt "38" &&
10548 dance_floor=occupied
10549 test "$hair_style" = "curly" &&
10550 dance_floor=occupied
10552 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10559 This behavior was chosen on purpose: (i) it prevents messages in
10560 required macros from interrupting the messages in the requiring macros;
10561 (ii) it avoids bad surprises when shell conditionals are used, as in:
10566 AC_REQUIRE([SOME_CHECK])
10573 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
10574 enforce expansion of required macros outside of shell conditional
10575 constructs. You are furthermore encouraged to put all @code{AC_REQUIRE} calls
10576 at the beginning of a macro. You can use @code{dnl} to avoid the empty
10579 @node Suggested Ordering
10580 @subsection Suggested Ordering
10581 @cindex Macros, ordering
10582 @cindex Ordering macros
10584 Some macros should be run before another macro if both are called, but
10585 neither @emph{requires} that the other be called. For example, a macro
10586 that changes the behavior of the C compiler should be called before any
10587 macros that run the C compiler. Many of these dependencies are noted in
10590 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
10591 with this kind of dependency appear out of order in a
10592 @file{configure.ac} file. The warning occurs when creating
10593 @command{configure} from @file{configure.ac}, not when running
10594 @command{configure}.
10596 For example, @code{AC_PROG_CPP} checks whether the C compiler
10597 can run the C preprocessor when given the @option{-E} option. It should
10598 therefore be called after any macros that change which C compiler is
10599 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
10602 AC_BEFORE([$0], [AC_PROG_CPP])dnl
10606 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
10607 when @code{AC_PROG_CC} is called.
10609 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
10611 Make M4 print a warning message to the standard error output if
10612 @var{called-macro-name} has already been called. @var{this-macro-name}
10613 should be the name of the macro that is calling @code{AC_BEFORE}. The
10614 macro @var{called-macro-name} must have been defined using
10615 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10616 that it has been called.
10619 @node One-Shot Macros
10620 @subsection One-Shot Macros
10621 @cindex One-shot macros
10622 @cindex Macros, called once
10624 Some macros should be called only once, either because calling them
10625 multiple time is unsafe, or because it is bad style. For instance
10626 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
10627 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
10628 sense to run these expensive checks more than once. Such one-shot
10629 macros can be defined using @code{AC_DEFUN_ONCE}.
10631 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
10632 @acindex{DEFUN_ONCE}
10634 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
10635 Definitions}), and emit a warning any time the macro is called more than
10639 Obviously it is not sensible to evaluate a macro defined by
10640 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}.
10641 Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite
10644 @node Obsoleting Macros
10645 @section Obsoleting Macros
10646 @cindex Obsoleting macros
10647 @cindex Macros, obsoleting
10649 Configuration and portability technology has evolved over the years.
10650 Often better ways of solving a particular problem are developed, or
10651 ad-hoc approaches are systematized. This process has occurred in many
10652 parts of Autoconf. One result is that some of the macros are now
10653 considered @dfn{obsolete}; they still work, but are no longer considered
10654 the best thing to do, hence they should be replaced with more modern
10655 macros. Ideally, @command{autoupdate} should replace the old macro calls
10656 with their modern implementation.
10658 Autoconf provides a simple means to obsolete a macro.
10660 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
10662 Define @var{old-macro} as @var{implementation}. The only difference
10663 with @code{AC_DEFUN} is that the user is warned that
10664 @var{old-macro} is now obsolete.
10666 If she then uses @command{autoupdate}, the call to @var{old-macro} is
10667 replaced by the modern @var{implementation}. @var{message} should
10668 include information on what to do after running @command{autoupdate};
10669 @command{autoupdate} prints it as a warning, and includes it
10670 in the updated @file{configure.ac} file.
10672 The details of this macro are hairy: if @command{autoconf} encounters an
10673 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
10674 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
10675 macros are expanded here, while all other macros are disabled and
10676 appear literally in the updated @file{configure.ac}.
10679 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
10681 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
10682 with the same parameters. This happens for example if the macro was renamed.
10686 @section Coding Style
10687 @cindex Coding style
10689 The Autoconf macros follow a strict coding style. You are encouraged to
10690 follow this style, especially if you intend to distribute your macro,
10691 either by contributing it to Autoconf itself, or via other means.
10693 The first requirement is to pay great attention to the quotation. For
10694 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
10696 Do not try to invent new interfaces. It is likely that there is a macro
10697 in Autoconf that resembles the macro you are defining: try to stick to
10698 this existing interface (order of arguments, default values, etc.). We
10699 @emph{are} conscious that some of these interfaces are not perfect;
10700 nevertheless, when harmless, homogeneity should be preferred over
10703 Be careful about clashes both between M4 symbols and between shell
10706 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
10707 you are unlikely to generate conflicts. Nevertheless, when you need to
10708 set a special value, @emph{avoid using a regular macro name}; rather,
10709 use an ``impossible'' name. For instance, up to version 2.13, the macro
10710 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
10711 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
10712 But since there is a macro named @code{AC_SUBST_FILE}, it was just
10713 impossible to @samp{AC_SUBST(FILE)}! In this case,
10714 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
10715 have been used (yes, with the parentheses).
10716 @c or better yet, high-level macros such as @code{m4_expand_once}
10718 No Autoconf macro should ever enter the user-variable name space; i.e.,
10719 except for the variables that are the actual result of running the
10720 macro, all shell variables should start with @code{ac_}. In
10721 addition, small macros or any macro that is likely to be embedded in
10722 other macros should be careful not to use obvious names.
10725 Do not use @code{dnl} to introduce comments: most of the comments you
10726 are likely to write are either header comments which are not output
10727 anyway, or comments that should make their way into @file{configure}.
10728 There are exceptional cases where you do want to comment special M4
10729 constructs, in which case @code{dnl} is right, but keep in mind that it
10732 M4 ignores the leading blanks and newlines before each argument.
10733 Use this feature to
10734 indent in such a way that arguments are (more or less) aligned with the
10735 opening parenthesis of the macro being called. For instance, instead of
10738 AC_CACHE_CHECK(for EMX OS/2 environment,
10740 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
10741 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
10748 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10749 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10750 [ac_cv_emxos2=yes],
10751 [ac_cv_emxos2=no])])
10758 AC_CACHE_CHECK([for EMX OS/2 environment],
10760 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
10761 [return __EMX__;])],
10762 [ac_cv_emxos2=yes],
10763 [ac_cv_emxos2=no])])
10766 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
10767 cross-compiling, provide a pessimistic value (typically @samp{no}).
10769 Feel free to use various tricks to prevent auxiliary tools, such as
10770 syntax-highlighting editors, from behaving improperly. For instance,
10774 m4_bpatsubst([$1], [$"])
10781 m4_bpatsubst([$1], [$""])
10785 so that Emacsen do not open an endless ``string'' at the first quote.
10786 For the same reasons, avoid:
10796 test $[@@%:@@] != 0
10800 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
10801 breaking the bracket-matching highlighting from Emacsen. Note the
10802 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
10803 not escape when it is unnecessary. Common examples of useless quotation
10804 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
10805 etc. If you add portability issues to the picture, you'll prefer
10806 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
10807 better than hacking Autoconf @code{:-)}.
10809 When using @command{sed}, don't use @option{-e} except for indenting
10810 purposes. With the @code{s} and @code{y} commands, the preferred
10811 separator is @samp{/} unless @samp{/} itself might appear in the pattern
10812 or replacement, in which case you should use @samp{|}, or optionally
10813 @samp{,} if you know the pattern and replacement cannot contain a file
10814 name. If none of these characters will do, choose a printable character
10815 that cannot appear in the pattern or replacement. Characters from the
10816 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
10817 replacement might contain a file name, since they have special meaning
10818 to the shell and are less likely to occur in file names.
10820 @xref{Macro Definitions}, for details on how to define a macro. If a
10821 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
10822 of an @code{AC_REQUIRE} directive, and macros required by other macros
10823 inside arguments do not need to be expanded before this macro, then
10824 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
10825 All the @code{AC_REQUIRE} statements should be at the beginning of the
10826 macro, and each statement should be followed by @code{dnl}.
10828 You should not rely on the number of arguments: instead of checking
10829 whether an argument is missing, test that it is not empty. It provides
10830 both a simpler and a more predictable interface to the user, and saves
10831 room for further arguments.
10833 Unless the macro is short, try to leave the closing @samp{])} at the
10834 beginning of a line, followed by a comment that repeats the name of the
10835 macro being defined. This introduces an additional newline in
10836 @command{configure}; normally, that is not a problem, but if you want to
10837 remove it you can use @samp{[]dnl} on the last line. You can similarly
10838 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
10839 is recommended instead of @samp{dnl} to ensure that M4 does not
10840 interpret the @samp{dnl} as being attached to the preceding text or
10841 macro output. For example, instead of:
10844 AC_DEFUN([AC_PATH_X],
10845 [AC_MSG_CHECKING([for X])
10847 @r{# @dots{}omitted@dots{}}
10848 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10856 AC_DEFUN([AC_PATH_X],
10857 [AC_REQUIRE_CPP()[]dnl
10858 AC_MSG_CHECKING([for X])
10859 @r{# @dots{}omitted@dots{}}
10860 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10865 If the macro is long, try to split it into logical chunks. Typically,
10866 macros that check for a bug in a function and prepare its
10867 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
10868 this setup. Do not hesitate to introduce auxiliary macros to factor
10871 In order to highlight the recommended coding style, here is a macro
10872 written the old way:
10875 dnl Check for EMX on OS/2.
10877 AC_DEFUN(_AC_EMXOS2,
10878 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
10879 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
10880 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
10881 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
10890 # Check for EMX on OS/2.
10891 m4_define([_AC_EMXOS2],
10892 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10893 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10894 [ac_cv_emxos2=yes],
10895 [ac_cv_emxos2=no])])
10896 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
10903 @c ============================================= Portable Shell Programming
10905 @node Portable Shell
10906 @chapter Portable Shell Programming
10907 @cindex Portable shell programming
10909 When writing your own checks, there are some shell-script programming
10910 techniques you should avoid in order to make your code portable. The
10911 Bourne shell and upward-compatible shells like the Korn shell and Bash
10912 have evolved over the years, but to prevent trouble, do not take
10913 advantage of features that were added after Unix version 7, circa
10914 1977 (@pxref{Systemology}).
10916 You should not use shell functions, aliases, negated character
10917 classes, or other features that are not found in all Bourne-compatible
10918 shells; restrict yourself to the lowest common denominator. Even
10919 @code{unset} is not supported by all shells!
10921 Some ancient systems have quite
10922 small limits on the length of the @samp{#!} line; for instance, 32
10923 bytes (not including the newline) on SunOS 4.
10924 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
10925 required a single space between the @samp{#!} and the @samp{/}.
10926 However, these ancient systems are no longer of practical concern.
10928 The set of external programs you should run in a @command{configure} script
10929 is fairly small. @xref{Utilities in Makefiles, , Utilities in
10930 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
10931 restriction allows users to start out with a fairly small set of
10932 programs and build the rest, avoiding too many interdependencies between
10935 Some of these external utilities have a portable subset of features; see
10936 @ref{Limitations of Usual Tools}.
10938 There are other sources of documentation about shells. The
10939 specification for the Posix
10940 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
10941 Command Language}, though more generous than the restrictive shell
10942 subset described above, is fairly portable nowadays. Also please see
10943 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
10946 * Shellology:: A zoology of shells
10947 * Here-Documents:: Quirks and tricks
10948 * File Descriptors:: FDs and redirections
10949 * File System Conventions:: File names
10950 * Shell Substitutions:: Variable and command expansions
10951 * Assignments:: Varying side effects of assignments
10952 * Parentheses:: Parentheses in shell scripts
10953 * Slashes:: Slashes in shell scripts
10954 * Special Shell Variables:: Variables you should not change
10955 * Limitations of Builtins:: Portable use of not so portable /bin/sh
10956 * Limitations of Usual Tools:: Portable use of portable tools
10960 @section Shellology
10963 There are several families of shells, most prominently the Bourne family
10964 and the C shell family which are deeply incompatible. If you want to
10965 write portable shell scripts, avoid members of the C shell family. The
10966 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
10967 Shell difference FAQ} includes a small history of Posix shells, and a
10968 comparison between several of them.
10970 Below we describe some of the members of the Bourne shell family.
10975 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
10976 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
10977 bugs that are fixed in the 0.3.x series, but portable shell scripts
10978 should work around them, since version 0.2 is still shipped with many
10979 @acronym{GNU}/Linux distributions.
10981 To be compatible with Ash 0.2:
10985 don't use @samp{$?} after expanding empty or unset variables,
10986 or at the start of an @command{eval}:
10992 echo "Do not use it: $?"
10994 eval 'echo "Do not use it: $?"'
10998 don't use command substitution within variable expansion:
11005 beware that single builtin substitutions are not performed by a
11006 subshell, hence their effect applies to the current shell! @xref{Shell
11007 Substitutions}, item ``Command Substitution''.
11012 To detect whether you are running Bash, test whether
11013 @code{BASH_VERSION} is set. To require
11014 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
11015 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
11016 Manual}, for details.
11018 @item Bash 2.05 and later
11019 @cindex Bash 2.05 and later
11020 Versions 2.05 and later of Bash use a different format for the
11021 output of the @command{set} builtin, designed to make evaluating its
11022 output easier. However, this output is not compatible with earlier
11023 versions of Bash (or with many other shells, probably). So if
11024 you use Bash 2.05 or higher to execute @command{configure},
11025 you'll need to use Bash 2.05 for all other build tasks as well.
11030 @prindex @samp{ksh}
11031 @prindex @samp{ksh88}
11032 @prindex @samp{ksh93}
11033 The Korn shell is compatible with the Bourne family and it mostly
11034 conforms to Posix. It has two major variants commonly
11035 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
11036 release. It is usually called @command{ksh}, but is called @command{sh}
11037 on some hosts if you set your path appropriately.
11039 Solaris systems have three variants:
11040 @prindex @command{/usr/bin/ksh} on Solaris
11041 @command{/usr/bin/ksh} is @samp{ksh88}; it is
11042 standard on Solaris 2.0 and later.
11043 @prindex @command{/usr/xpg4/bin/sh} on Solaris
11044 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
11045 @samp{ksh88}; it is standard on Solaris 9 and later.
11046 @prindex @command{/usr/dt/bin/dtksh} on Solaris
11047 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
11048 Variants that are not standard may be parts of optional
11049 packages. There is no extra charge for these packages, but they are
11050 not part of a minimal OS install and therefore some installations may
11053 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
11054 is also available as @command{/usr/bin/posix/sh}. If the environment
11055 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11056 the standard shell conform to Posix.
11059 @prindex @samp{pdksh}
11060 A public-domain clone of the Korn shell called @command{pdksh} is widely
11061 available: it has most of the @samp{ksh88} features along with a few of
11062 its own. It usually sets @code{KSH_VERSION}, except if invoked as
11063 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
11064 Posix compatibility by running @samp{set -o posix}. Unfortunately, with
11065 @command{pdksh} 5.2.14 (the latest stable version as of February 2006)
11066 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
11067 at least one respect:
11070 $ @kbd{echo "`echo \"hello\"`"}
11072 $ @kbd{set -o posix}
11073 $ @kbd{echo "`echo \"hello\"`"}
11077 The last line of output contains spurious quotes. This is yet another
11078 reason why portable shell code should not contain
11079 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
11084 To detect whether you are running @command{zsh}, test whether
11085 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
11086 compatible with the Bourne shell: you must execute @samp{emulate sh},
11087 and for @command{zsh} versions before 3.1.6-dev-18 you must also
11088 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
11089 zsh, The Z Shell Manual}, for details.
11091 The default Mac OS X @command{sh} was originally Zsh; it was changed to
11092 Bash in Mac OS X 10.2.
11095 The following discussion between Russ Allbery and Robert Lipe is worth
11102 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
11103 leads to a permanent deadlock. Vendors don't want to break users'
11104 existing shell scripts, and there are some corner cases in the Bourne
11105 shell that are not completely compatible with a Posix shell. Thus,
11106 vendors who have taken this route will @emph{never} (OK@dots{}``never say
11107 never'') replace the Bourne shell (as @command{/bin/sh}) with a
11115 This is exactly the problem. While most (at least most System V's) do
11116 have a Bourne shell that accepts shell functions most vendor
11117 @command{/bin/sh} programs are not the Posix shell.
11119 So while most modern systems do have a shell @emph{somewhere} that meets the
11120 Posix standard, the challenge is to find it.
11123 @node Here-Documents
11124 @section Here-Documents
11125 @cindex Here-documents
11126 @cindex Shell here-documents
11128 Don't rely on @samp{\} being preserved just because it has no special
11129 meaning together with the next symbol. In the native @command{sh}
11130 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
11131 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
11132 use @samp{\\} to get @samp{\}.
11134 With Open@acronym{BSD} 2.7's @command{sh}
11150 bash-2.04$ @kbd{cat <<EOF
11157 Some shells mishandle large here-documents: for example,
11158 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
11159 derived from Korn shell version M-12/28/93d, mishandle braced variable
11160 expansion that crosses a 1024- or 4096-byte buffer boundary
11161 within a here-document. Only the part of the variable name after the boundary
11162 is used. For example, @code{$@{variable@}} could be replaced by the expansion
11163 of @code{$@{ble@}}. If the end of the variable name is aligned with the block
11164 boundary, the shell reports an error, as if you used @code{$@{@}}.
11165 Instead of @code{$@{variable-default@}}, the shell may expand
11166 @code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
11167 be worked around by omitting the braces: @code{$variable}. The bug was fixed in
11168 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
11169 still shipping older versions with the bug.
11171 Many older shells (including the Bourne shell) implement here-documents
11172 inefficiently. In particular, some shells can be extremely inefficient when
11173 a single statement contains many here-documents. For instance if your
11174 @file{configure.ac} includes something like:
11178 if <cross_compiling>; then
11179 assume this and that
11183 check something else
11191 A shell parses the whole @code{if}/@code{fi} construct, creating
11192 temporary files for each here-document in it. Some shells create links
11193 for such here-documents on every @code{fork}, so that the clean-up code
11194 they had installed correctly removes them. It is creating the links
11195 that can take the shell forever.
11197 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
11198 @code{if}/@code{fi} constructs, would improve the performance
11199 significantly. Anyway, this kind of construct is not exactly the
11200 typical use of Autoconf. In fact, it's even not recommended, because M4
11201 macros can't look into shell conditionals, so we may fail to expand a
11202 macro when it was expanded before in a conditional path, and the
11203 condition turned out to be false at runtime, and we end up not
11204 executing the macro at all.
11206 @node File Descriptors
11207 @section File Descriptors
11208 @cindex Descriptors
11209 @cindex File descriptors
11210 @cindex Shell file descriptors
11212 Most shells, if not all (including Bash, Zsh, Ash), output traces on
11213 stderr, even for subshells. This might result in undesirable content
11214 if you meant to capture the standard-error output of the inner command:
11217 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
11219 + eval echo foo >&2
11222 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
11224 + eval 'echo foo >&2'
11227 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
11228 @i{# Traces on startup files deleted here.}
11230 +zsh:1> eval echo foo >&2
11236 One workaround is to grep out uninteresting lines, hoping not to remove
11239 If you intend to redirect both standard error and standard output,
11240 redirect standard output first. This works better with @acronym{HP-UX},
11241 since its shell mishandles tracing if standard error is redirected
11245 $ @kbd{sh -x -c ': 2>err >out'}
11247 + 2> err $ @kbd{cat err}
11251 Don't try to redirect the standard error of a command substitution. It
11252 must be done @emph{inside} the command substitution. When running
11253 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
11254 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
11256 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
11257 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
11259 Don't redirect the same file descriptor several times, as you are doomed
11260 to failure under Ultrix.
11263 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
11265 $ @kbd{eval 'echo matter >fullness' >void}
11267 $ @kbd{eval '(echo matter >fullness)' >void}
11269 $ @kbd{(eval '(echo matter >fullness)') >void}
11270 Ambiguous output redirect.
11274 In each case the expected result is of course @file{fullness} containing
11275 @samp{matter} and @file{void} being empty.
11277 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
11278 subsidiary program. If any of these descriptors is closed, the
11279 operating system may open an unspecified file for the descriptor in the
11280 new process image. Posix says this may be done only if the subsidiary
11281 program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does it even for
11284 Don't rely on open file descriptors being open in child processes. In
11285 @command{ksh}, file descriptors above 2 which are opened using
11286 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
11287 that involved in the fork-and-exec which runs a program or script).
11288 Thus, using @command{sh}, we have:
11291 $ @kbd{cat ./descrips}
11313 Within the process which runs the @samp{descrips} script, file
11314 descriptor 5 is closed.
11316 @acronym{DOS} variants cannot rename or remove open files, such as in
11317 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
11318 perfectly portable among Posix hosts.
11320 A few ancient systems reserved some file descriptors. By convention,
11321 file descriptor 3 was opened to @file{/dev/tty} when you logged into
11322 Eighth Edition (1985) through Tenth Edition Unix (1989). File
11323 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
11324 1990), though we don't now remember what it was. Both these systems are
11325 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
11326 other file descriptors.
11328 @node File System Conventions
11329 @section File System Conventions
11330 @cindex File system conventions
11332 Autoconf uses shell-script processing extensively, so the file names
11333 that it processes should not contain characters that are special to the
11334 shell. Special characters include space, tab, newline, @sc{nul}, and
11338 " # $ & ' ( ) * ; < = > ? [ \ ` |
11341 Also, file names should not begin with @samp{~} or @samp{-}, and should
11342 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
11343 immediately after @samp{:}. On Posix-like platforms, directory names
11344 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
11347 These restrictions apply not only to the files that you distribute, but
11348 also to the absolute file names of your source, build, and destination
11351 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
11352 they should be avoided.
11354 Posix lets implementations treat leading @file{//} specially, but
11355 requires leading @file{///} and beyond to be equivalent to @file{/}.
11356 Most Unix variants treat @file{//} like @file{/}. However, some treat
11357 @file{//} as a ``super-root'' that can provide access to files that are
11358 not otherwise reachable from @file{/}. The super-root tradition began
11359 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
11362 While @command{autoconf} and friends are usually run on some Posix
11363 variety, they can be used on other systems, most notably @acronym{DOS}
11364 variants. This impacts several assumptions regarding file names.
11367 For example, the following code:
11374 foo_dir=$dots$foo_dir ;;
11379 fails to properly detect absolute file names on those systems, because
11380 they can use a drivespec, and usually use a backslash as directory
11381 separator. If you want to be portable to @acronym{DOS} variants (at the
11382 price of rejecting valid but oddball Posix file names like @file{a:\b}),
11383 you can check for absolute file names like this:
11387 [\\/]* | ?:[\\/]* ) # Absolute
11390 foo_dir=$dots$foo_dir ;;
11395 Make sure you quote the brackets if appropriate and keep the backslash as
11396 first character (@pxref{Limitations of Builtins}).
11398 Also, because the colon is used as part of a drivespec, these systems don't
11399 use it as path separator. When creating or accessing paths, you can use the
11400 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
11401 to the appropriate value (@samp{:} or @samp{;}) when it starts up.
11403 File names need extra care as well. While @acronym{DOS} variants
11404 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP})
11405 are usually able to handle long file names properly, there are still
11406 limitations that can seriously break packages. Several of these issues
11407 can be easily detected by the
11408 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11411 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11412 indicate where they apply: @sc{sfn} means the issues are only relevant to
11413 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11414 variants, while @sc{lfn} identifies problems that exist even under
11415 Microsoft Windows variants.
11418 @item No multiple dots (@sc{sfn})
11419 @acronym{DOS} cannot handle multiple dots in file names. This is an especially
11420 important thing to remember when building a portable configure script,
11421 as @command{autoconf} uses a .in suffix for template files.
11423 This is perfectly OK on Posix variants:
11426 AC_CONFIG_HEADERS([config.h])
11427 AC_CONFIG_FILES([source.c foo.bar])
11432 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11433 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
11434 to @acronym{DOS}-based environments, you should use this instead:
11437 AC_CONFIG_HEADERS([config.h:config.hin])
11438 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11442 @item No leading dot (@sc{sfn})
11443 @acronym{DOS} cannot handle file names that start with a dot. This is usually
11444 not important for @command{autoconf}.
11446 @item Case insensitivity (@sc{lfn})
11447 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11448 file called @samp{INSTALL} and a directory called @samp{install}. This
11449 also affects @command{make}; if there's a file called @samp{INSTALL} in
11450 the directory, @samp{make install} does nothing (unless the
11451 @samp{install} target is marked as PHONY).
11453 @item The 8+3 limit (@sc{sfn})
11454 Because the @acronym{DOS} file system only stores the first 8 characters of
11455 the file name and the first 3 of the extension, those must be unique.
11456 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11457 @file{foobar-prettybird.c} all resolve to the same file name
11458 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
11459 @file{foo.bartender}.
11461 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11463 tails in the short version of file names to make them unique. However, a
11464 registry setting can turn this behavior off. While this makes it
11465 possible to share file trees containing long file names between @sc{sfn}
11466 and @sc{lfn} environments, it also means the above problem applies there
11469 @item Invalid characters (@sc{lfn})
11470 Some characters are invalid in @acronym{DOS} file names, and should therefore
11471 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11472 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11473 In a @sc{sfn} environment, other characters are also invalid. These
11474 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11476 @item Invalid names (@sc{lfn})
11477 Some @acronym{DOS} file names are reserved, and cause problems if you
11478 try to use files with those names. These names include @file{CON},
11479 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11480 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11481 File names are case insensitive, so even names like
11482 @file{aux/config.guess} are disallowed.
11486 @node Shell Substitutions
11487 @section Shell Substitutions
11488 @cindex Shell substitutions
11490 Contrary to a persistent urban legend, the Bourne shell does not
11491 systematically split variables and back-quoted expressions, in particular
11492 on the right-hand side of assignments and in the argument of @code{case}.
11493 For instance, the following code:
11496 case "$given_srcdir" in
11497 .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
11498 *) top_srcdir="$dots$given_srcdir" ;;
11503 is more readable when written as:
11506 case $given_srcdir in
11507 .) top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
11508 *) top_srcdir=$dots$given_srcdir ;;
11513 and in fact it is even @emph{more} portable: in the first case of the
11514 first attempt, the computation of @code{top_srcdir} is not portable,
11515 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
11516 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
11517 the same way. There is just no portable way to use double-quoted
11518 strings inside double-quoted back-quoted expressions (pfew!).
11522 @cindex @samp{"$@@"}
11523 One of the most famous shell-portability issues is related to
11524 @samp{"$@@"}. When there are no positional arguments, Posix says
11525 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
11526 original Unix version 7 Bourne shell treated it as equivalent to
11527 @samp{""} instead, and this behavior survives in later implementations
11528 like Digital Unix 5.0.
11530 The traditional way to work around this portability problem is to use
11531 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
11532 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
11533 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
11536 zsh $ @kbd{emulate sh}
11537 zsh $ @kbd{for i in "$@@"; do echo $i; done}
11540 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
11547 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
11548 @samp{"$@@"} because of the portability problems mentioned above.
11549 One workaround relies on Zsh's ``global aliases'' to convert
11550 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
11553 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
11556 A more conservative workaround is to avoid @samp{"$@@"} if it is
11557 possible that there may be no positional arguments. For example,
11561 cat conftest.c "$@@"
11564 you can use this instead:
11568 0) cat conftest.c;;
11569 *) cat conftest.c "$@@";;
11573 Autoconf macros often use the @command{set} command to update
11574 @samp{$@@}, so if you are writing shell code intended for
11575 @command{configure} you should not assume that the value of @samp{$@@}
11576 persists for any length of time.
11580 @cindex positional parameters
11581 The 10th, 11th, @dots{} positional parameters can be accessed only after
11582 a @code{shift}. The 7th Edition shell reported an error if given
11583 @code{$@{10@}}, and
11584 Solaris 10 @command{/bin/sh} still acts that way:
11587 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
11588 $ @kbd{echo $@{10@}}
11592 @item $@{@var{var}:-@var{value}@}
11593 @c Info cannot handle `:' in index entries.
11594 @c @cindex $@{@var{var}:-@var{value}@}
11595 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
11596 colon for any shell substitution, and complain and die.
11598 @item $@{@var{var}=@var{literal}@}
11599 @cindex $@{@var{var}=@var{literal}@}
11603 : $@{var='Some words'@}
11607 otherwise some shells, such as on Digital Unix V 5.0, die because
11608 of a ``bad substitution''.
11612 Solaris @command{/bin/sh} has a frightening bug in its interpretation
11613 of this. Imagine you need set a variable to a string containing
11614 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
11615 when the affected variable was already set. This bug can be exercised
11620 $ @kbd{foo=$@{foo='@}'@}}
11623 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
11626 $ @kbd{foo=$@{foo='@}'@}}
11632 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
11633 though it is enclosed in single quotes. The problem doesn't happen
11634 using double quotes.
11636 @item $@{@var{var}=@var{expanded-value}@}
11637 @cindex $@{@var{var}=@var{expanded-value}@}
11643 : $@{var="$default"@}
11647 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
11648 each char is set. You don't observe the phenomenon using a simple
11649 @samp{echo $var} since apparently the shell resets the 8th bit when it
11650 expands $var. Here are two means to make this shell confess its sins:
11653 $ @kbd{cat -v <<EOF
11662 $ @kbd{set | grep '^var=' | cat -v}
11665 One classic incarnation of this bug is:
11669 : $@{list="$default"@}
11676 You'll get @samp{a b c} on a single line. Why? Because there are no
11677 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
11678 bit set, hence no IFS splitting is performed!!!
11680 One piece of good news is that Ultrix works fine with @samp{:
11681 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
11682 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
11685 The portable way out consists in using a double assignment, to switch
11686 the 8th bit twice on Ultrix:
11689 list=$@{list="$default"@}
11693 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
11697 test "$@{var+set@}" = set || var=@var{@{value@}}
11701 @item `@var{commands}`
11702 @cindex `@var{commands}`
11703 @cindex Command Substitution
11704 Posix requires shells to trim all trailing newlines from command
11705 output before substituting it, so assignments like
11706 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
11707 @samp{$file} ends in a newline.
11709 While in general it makes no sense, do not substitute a single builtin
11710 with side effects, because Ash 0.2, trying to optimize, does not fork a
11711 subshell to perform the command.
11713 For instance, if you wanted to check that @command{cd} is silent, do not
11714 use @samp{test -z "`cd /`"} because the following can happen:
11719 $ @kbd{test -z "`cd /`" && pwd}
11724 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
11726 The MSYS shell leaves a stray byte in the expansion of a double-quoted
11727 command substitution of a native program, if the end of the substution
11728 is not aligned with the end of the double quote. This may be worked
11729 around by inserting another pair of quotes:
11732 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
11733 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
11734 - broken differ: char 4, line 1
11738 @item $(@var{commands})
11739 @cindex $(@var{commands})
11740 This construct is meant to replace @samp{`@var{commands}`},
11741 and it has most of the problems listed under @code{`@var{commands}`}.
11743 This construct can be
11744 nested while this is impossible to do portably with back quotes.
11745 Unfortunately it is not yet universally supported. Most notably, even recent
11746 releases of Solaris don't support it:
11749 $ @kbd{showrev -c /bin/sh | grep version}
11750 Command version: SunOS 5.10 Generic 121004-01 Oct 2005
11751 $ @kbd{echo $(echo blah)}
11752 syntax error: `(' unexpected
11756 nor does @sc{irix} 6.5's Bourne shell:
11759 IRIX firebird-image 6.5 07151432 IP22
11760 $ @kbd{echo $(echo blah)}
11764 If you do use @samp{$(@var{commands})}, make sure that the commands
11765 do not start with a parenthesis, as that would cause confusion with
11766 a different notation @samp{$((@var{expression}))} that in modern
11767 shells is an arithmetic expression not a command. To avoid the
11768 confusion, insert a space between the two opening parentheses.
11770 Avoid @var{commands} that contain unbalanced parentheses in
11771 here-documents, comments, or case statement patterns, as many shells
11772 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
11773 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
11776 echo $(case x in x) echo hello;; esac)
11781 Always quote @samp{^}, otherwise traditional shells such as
11782 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
11788 @section Assignments
11789 @cindex Shell assignments
11791 When setting several variables in a row, be aware that the order of the
11792 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
11793 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
11795 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
11797 Don't rely on the following to find @file{subdir/program}:
11800 PATH=subdir$PATH_SEPARATOR$PATH program
11804 as this does not work with Zsh 3.0.6. Use something like this
11808 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
11811 Don't rely on the exit status of an assignment: Ash 0.2 does not change
11812 the status and propagates that of the last statement:
11815 $ @kbd{false || foo=bar; echo $?}
11817 $ @kbd{false || foo=`:`; echo $?}
11822 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
11826 $ @kbd{foo=`exit 1`; echo $?}
11830 To assign default values, follow this algorithm:
11834 If the default value is a literal and does not contain any closing
11838 : $@{var='my literal'@}
11842 If the default value contains no closing brace, has to be expanded, and
11843 the variable being initialized is not intended to be IFS-split
11844 (i.e., it's not a list), then use:
11847 : $@{var="$default"@}
11851 If the default value contains no closing brace, has to be expanded, and
11852 the variable being initialized is intended to be IFS-split (i.e., it's a list),
11856 var=$@{var="$default"@}
11860 If the default value contains a closing brace, then use:
11863 test "$@{var+set@}" = set || var="has a '@}'"
11867 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
11868 doubt, just use the last form. @xref{Shell Substitutions}, items
11869 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
11873 @section Parentheses in Shell Scripts
11874 @cindex Shell parentheses
11876 Beware of two opening parentheses in a row, as some shell
11877 implementations mishandle them. For example, @samp{pdksh} 5.2.14
11878 misparses the following code:
11881 if ((true) || false); then
11887 To work around this problem, insert a space between the two opening
11888 parentheses. There is a similar problem and workaround with
11889 @samp{$((}; see @ref{Shell Substitutions}.
11891 Posix requires support for @code{case} patterns with opening
11892 parentheses like this:
11896 (*.c) echo "C source code";;
11901 but the @code{(} in this example is not portable to many older Bourne
11902 shell implementations. It can be omitted safely.
11905 @section Slashes in Shell Scripts
11906 @cindex Shell slashes
11908 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
11909 arguments that contain two trailing slashes:
11912 $ @kbd{echo / // /// //// .// //.}
11915 $ @kbd{eval "echo \$x"}
11918 $ @kbd{echo abc | tr -t ab //}
11924 Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
11925 variable is empty and the second double-quote is followed by a word that
11926 begins and ends with slash:
11929 $ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
11935 However, our understanding is that patches are available, so perhaps
11936 it's not worth worrying about working around these horrendous bugs.
11938 @node Special Shell Variables
11939 @section Special Shell Variables
11940 @cindex Shell variables
11941 @cindex Special shell variables
11943 Some shell variables should not be used, since they can have a deep
11944 influence on the behavior of the shell. In order to recover a sane
11945 behavior from the shell, some variables should be unset, but
11946 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
11947 fallback value is needed.
11949 As a general rule, shell variable names containing a lower-case letter
11950 are safe; you can define and use these variables without worrying about
11951 their effect on the underlying system, and without worrying about
11952 whether the shell changes them unexpectedly. (The exception is the
11953 shell variable @code{status}, as described below.)
11955 Here is a list of names that are known to cause trouble. This list is
11956 not exhaustive, but you should be safe if you avoid the name
11957 @code{status} and names containing only upper-case letters and
11960 @c Alphabetical order, case insensitive, `A' before `a'.
11963 Many shells reserve @samp{$_} for various purposes, e.g., the name of
11964 the last command executed.
11968 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11969 the standard shell conform to Posix.
11973 When this variable is set it specifies a list of directories to search
11974 when invoking @code{cd} with a relative file name that did not start
11975 with @samp{./} or @samp{../}. Posix
11976 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
11977 is used successfully, @code{cd} prints the resulting absolute
11978 file name. Unfortunately this output can break idioms like
11979 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
11980 Also, many shells do not conform to this part of Posix; for
11981 example, @command{zsh} prints the result only if a directory name
11982 other than @file{.} was chosen from @env{CDPATH}.
11984 In practice the shells that have this problem also support
11985 @command{unset}, so you can work around the problem as follows:
11988 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
11991 You can also avoid output by ensuring that your directory name is
11992 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
11994 Autoconf-generated scripts automatically unset @env{CDPATH} if
11995 possible, so you need not worry about this problem in those scripts.
11999 In the MKS shell, case statements and file name generation are
12000 case-insensitive unless @env{DUALCASE} is nonzero.
12001 Autoconf-generated scripts export this variable when they start up.
12015 These variables should not matter for shell scripts, since they are
12016 supposed to affect only interactive shells. However, at least one
12017 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
12018 whether it is interactive, which means that (for example) a @env{PS1}
12019 with a side effect can unexpectedly modify @samp{$?}. To work around
12020 this bug, Autoconf-generated scripts do something like this:
12023 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
12031 Long ago, shell scripts inherited @env{IFS} from the environment,
12032 but this caused many problems so modern shells ignore any environment
12033 settings for @env{IFS}.
12035 Don't set the first character of @code{IFS} to backslash. Indeed,
12036 Bourne shells use the first character (backslash) when joining the
12037 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
12038 backslash escapes, so you can end up with backspace and other strange
12041 The proper value for @code{IFS} (in regular code, not when performing
12042 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
12043 especially important, as it is used to join the arguments in @samp{$*};
12044 however, note that traditional shells, but also bash-2.04, fail to adhere
12045 to this and join with a space anyway.
12057 @evindex LC_COLLATE
12059 @evindex LC_MESSAGES
12060 @evindex LC_MONETARY
12061 @evindex LC_NUMERIC
12064 Autoconf-generated scripts normally set all these variables to
12065 @samp{C} because so much configuration code assumes the C locale and
12066 Posix requires that locale environment variables be set to
12067 @samp{C} if the C locale is desired. However, some older, nonstandard
12068 systems (notably @acronym{SCO}) break if locale environment variables
12069 are set to @samp{C}, so when running on these systems
12070 Autoconf-generated scripts unset the variables instead.
12075 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
12076 extension that overrides @env{LC_ALL} in some cases, so
12077 Autoconf-generated scripts set it too.
12080 @itemx LC_IDENTIFICATION
12081 @itemx LC_MEASUREMENT
12084 @itemx LC_TELEPHONE
12085 @evindex LC_ADDRESS
12086 @evindex LC_IDENTIFICATION
12087 @evindex LC_MEASUREMENT
12090 @evindex LC_TELEPHONE
12092 These locale environment variables are @acronym{GNU} extensions. They
12093 are treated like their Posix brethren (@env{LC_COLLATE},
12094 etc.)@: as described above.
12097 Most modern shells provide the current line number in @code{LINENO}.
12098 Its value is the line number of the beginning of the current command.
12099 Autoconf attempts to execute @command{configure} with a shell that
12100 supports @code{LINENO}.
12101 If no such shell is available, it attempts to implement @code{LINENO}
12102 with a Sed prepass that replaces each instance of the string
12103 @code{$LINENO} (not followed by an alphanumeric character) with the
12106 You should not rely on @code{LINENO} within @command{eval}, as the
12107 behavior differs in practice. Also, the possibility of the Sed
12108 prepass means that you should not rely on @code{$LINENO} when quoted,
12109 when in here-documents, or when in long commands that cross line
12110 boundaries. Subshells should be OK, though. In the following
12111 example, lines 1, 6, and 9 are portable, but the other instances of
12112 @code{LINENO} are not:
12122 ( echo 6. $LINENO )
12123 eval 'echo 7. $LINENO'
12129 $ @kbd{bash-2.05 lineno}
12140 $ @kbd{zsh-3.0.6 lineno}
12151 $ @kbd{pdksh-5.2.14 lineno}
12162 $ @kbd{sed '=' <lineno |}
12168 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
12171 > @kbd{ s,^[0-9]*\n,,}
12187 When executing the command @samp{>foo}, @command{zsh} executes
12188 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
12189 compatibility mode and the @command{zsh} version is newer
12190 than 3.1.6-dev-18. If you are using an older @command{zsh}
12191 and forget to set @env{NULLCMD},
12192 your script might be suspended waiting for data on its standard input.
12194 @item PATH_SEPARATOR
12195 @evindex PATH_SEPARATOR
12196 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
12197 variable can be set to either @samp{:} or @samp{;} to control the path
12198 separator Bash uses to set up certain environment variables (such as
12199 @env{PATH}). You can set this variable to @samp{;} if you want
12200 @command{configure} to use @samp{;} as a separator; this might be useful
12201 if you plan to use non-Posix shells to execute files. @xref{File System
12202 Conventions}, for more information about @code{PATH_SEPARATOR}.
12206 Posix 1003.1-2001 requires that @command{cd} and
12207 @command{pwd} must update the @env{PWD} environment variable to point
12208 to the logical name of the current directory, but traditional shells
12209 do not support this. This can cause confusion if one shell instance
12210 maintains @env{PWD} but a subsidiary and different shell does not know
12211 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
12212 points to the wrong directory. Use @samp{`pwd`} rather than
12216 Many shells provide @code{RANDOM}, a variable that returns a different
12217 integer each time it is used. Most of the time, its value does not
12218 change when it is not used, but on @sc{irix} 6.5 the value changes all
12219 the time. This can be observed by using @command{set}. It is common
12220 practice to use @code{$RANDOM} as part of a file name, but code
12221 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
12224 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
12225 hence read-only. Do not use it.
12228 @node Limitations of Builtins
12229 @section Limitations of Shell Builtins
12230 @cindex Shell builtins
12231 @cindex Limitations of shell builtins
12233 No, no, we are serious: some shells do have limitations! :)
12235 You should always keep in mind that any builtin or command may support
12236 options, and therefore differ in behavior with arguments
12237 starting with a dash. For instance, the innocent @samp{echo "$word"}
12238 can give unexpected results when @code{word} starts with a dash. It is
12239 often possible to avoid this problem using @samp{echo "x$word"}, taking
12240 the @samp{x} into account later in the pipe.
12244 @prindex @command{.}
12245 Use @command{.} only with regular files (use @samp{test -f}). Bash
12246 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
12247 @command{.} uses @env{PATH} if its argument contains no slashes, so if
12248 you want to use @command{.} on a file @file{foo} in the current
12249 directory, you must use @samp{. ./foo}.
12252 @prindex @command{!}
12253 The Unix version 7 shell did not support
12254 negating the exit status of commands with @command{!}, and this feature
12255 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
12256 Shell code like this:
12259 if ! cmp file1 file2 >/dev/null 2>&1; then
12260 echo files differ or trouble
12264 is therefore not portable in practice. Typically it is easy to rewrite
12268 cmp file1 file2 >/dev/null 2>&1 ||
12269 echo files differ or trouble
12272 More generally, one can always rewrite @samp{! @var{command}} as:
12275 if @var{command}; then (exit 1); else :; fi
12278 @item @command{break}
12279 @c ------------------
12280 @prindex @command{break}
12281 The use of @samp{break 2} etc.@: is safe.
12284 @item @command{case}
12285 @c -----------------
12286 @prindex @command{case}
12287 You don't need to quote the argument; no splitting is performed.
12289 You don't need the final @samp{;;}, but you should use it.
12291 Because of a bug in its @code{fnmatch}, Bash fails to properly
12292 handle backslashes in character classes:
12295 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
12300 This is extremely unfortunate, since you are likely to use this code to
12301 handle Posix or @sc{ms-dos} absolute file names. To work around this
12302 bug, always put the backslash first:
12305 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
12307 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
12311 Many Bourne shells cannot handle closing brackets in character classes
12314 Some shells also have problems with backslash escaping in case you do not want
12315 to match the backslash: both a backslash and the escaped character match this
12316 pattern. To work around this, specify the character class in a variable, so
12317 that quote removal does not apply afterwards, and the special characters don't
12318 have to be backslash-escaped:
12321 $ @kbd{case '\' in [\<]) echo OK;; esac}
12323 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
12327 Even with this, Solaris @command{ksh} matches a backslash if the set
12329 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
12331 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
12332 a closing parenthesis if not specified in a character class:
12335 $ @kbd{case foo in *\)*) echo fail ;; esac}
12337 $ @kbd{case foo in *')'*) echo fail ;; esac}
12341 Some shells, such as Ash 0.3.8, are confused by an empty
12342 @code{case}/@code{esac}:
12345 ash-0.3.8 $ @kbd{case foo in esac;}
12346 @error{}Syntax error: ";" unexpected (expecting ")")
12349 Many shells still do not support parenthesized cases, which is a pity
12350 for those of us using tools that rely on balanced parentheses. For
12351 instance, Solaris @command{/bin/sh}:
12354 $ @kbd{case foo in (foo) echo foo;; esac}
12355 @error{}syntax error: `(' unexpected
12361 @prindex @command{cd}
12362 Posix 1003.1-2001 requires that @command{cd} must support
12363 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12364 with @option{-L} being the default. However, traditional shells do
12365 not support these options, and their @command{cd} command has the
12366 @option{-P} behavior.
12368 Portable scripts should assume neither option is supported, and should
12369 assume neither behavior is the default. This can be a bit tricky,
12370 since the Posix default behavior means that, for example,
12371 @samp{ls ..} and @samp{cd ..} may refer to different directories if
12372 the current logical directory is a symbolic link. It is safe to use
12373 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
12374 Also, Autoconf-generated scripts check for this problem when computing
12375 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
12376 so it is safe to @command{cd} to these variables.
12378 See @xref{Special Shell Variables}, for portability problems involving
12379 @command{cd} and the @env{CDPATH} environment variable.
12380 Also please see the discussion of the @command{pwd} command.
12383 @item @command{echo}
12384 @c -----------------
12385 @prindex @command{echo}
12386 The simple @command{echo} is probably the most surprising source of
12387 portability troubles. It is not possible to use @samp{echo} portably
12388 unless both options and escape sequences are omitted. New applications
12389 which are not aiming at portability should use @samp{printf} instead of
12392 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
12393 etc.@: for a means to simulate @option{-n}.
12395 Do not use backslashes in the arguments, as there is no consensus on
12396 their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
12397 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
12398 The problem is truly @command{echo}: all the shells
12399 understand @samp{'\n'} as the string composed of a backslash and an
12402 Because of these problems, do not pass a string containing arbitrary
12403 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
12404 if you know that @var{foo}'s value cannot contain backslashes and cannot
12405 start with @samp{-}, but otherwise you should use a here-document like
12415 @item @command{eval}
12416 @c -----------------
12417 @prindex @command{eval}
12418 The @command{eval} command is useful in limited circumstances, e.g.,
12419 using commands like @samp{eval table_$key=\$value} and @samp{eval
12420 value=table_$key} to simulate a hash table when the key is known to be
12421 alphanumeric. However, @command{eval} is tricky to use on arbitrary
12422 arguments, even when it is implemented correctly.
12424 It is obviously unwise to use @samp{eval $cmd} if the string value of
12425 @samp{cmd} was derived from an untrustworthy source. But even if the
12426 string value is valid, @samp{eval $cmd} might not work as intended,
12427 since it causes field splitting and file name expansion to occur twice,
12428 once for the @command{eval} and once for the command itself. It is
12429 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
12430 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
12431 equivalent of @samp{cat test;.c} if there happens to be a file named
12432 @file{test;.c} in the current directory; and this in turn
12433 mistakenly attempts to invoke @command{cat} on the file @file{test} and
12434 then execute the command @command{.c}. To avoid this problem, use
12435 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
12437 However, suppose that you want to output the text of the evaluated
12438 command just before executing it. Assuming the previous example,
12439 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
12440 this output doesn't show the user that @samp{test;.c} is the actual name
12441 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
12442 works on this example, but it fails with @samp{cmd='cat foo >bar'},
12443 since it mistakenly replaces the contents of @file{bar} by the
12444 string @samp{cat foo}. No simple, general, and portable solution to
12445 this problem is known.
12447 You should also be wary of common bugs in @command{eval} implementations.
12448 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
12449 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
12450 4.2.5), the arguments of @samp{eval} are evaluated in a context where
12451 @samp{$?} is 0, so they exhibit behavior like this:
12454 $ @kbd{false; eval 'echo $?'}
12458 The correct behavior here is to output a nonzero value,
12459 but portable scripts should not rely on this.
12461 You should not rely on @code{LINENO} within @command{eval}.
12462 @xref{Special Shell Variables}.
12464 @item @command{exit}
12465 @c -----------------
12466 @prindex @command{exit}
12467 The default value of @command{exit} is supposed to be @code{$?};
12468 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
12469 perform @samp{exit 0}.
12472 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
12474 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
12476 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
12480 Using @samp{exit $?} restores the expected behavior.
12482 Some shell scripts, such as those generated by @command{autoconf}, use a
12483 trap to clean up before exiting. If the last shell command exited with
12484 nonzero status, the trap also exits with nonzero status so that the
12485 invoker can tell that an error occurred.
12487 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
12488 trap ignores the @code{exit} command's argument. In these shells, a trap
12489 cannot determine whether it was invoked by plain @code{exit} or by
12490 @code{exit 1}. Instead of calling @code{exit} directly, use the
12491 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
12494 @item @command{export}
12495 @c -------------------
12496 @prindex @command{export}
12497 The builtin @command{export} dubs a shell variable @dfn{environment
12498 variable}. Each update of exported variables corresponds to an update
12499 of the environment variables. Conversely, each environment variable
12500 received by the shell when it is launched should be imported as a shell
12501 variable marked as exported.
12503 Alas, many shells, such as Solaris @command{/bin/sh},
12504 @sc{irix} 6.3, @sc{irix} 5.2,
12505 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
12506 @command{export} the environment variables they receive. As a result,
12507 two variables coexist: the environment variable and the shell
12508 variable. The following code demonstrates this failure:
12519 when run with @samp{FOO=foo} in the environment, these shells print
12520 alternately @samp{foo} and @samp{bar}, although they should print only
12521 @samp{foo} and then a sequence of @samp{bar}s.
12523 Therefore you should @command{export} again each environment variable
12527 @item @command{false}
12528 @c ------------------
12529 @prindex @command{false}
12530 Don't expect @command{false} to exit with status 1: in native
12531 Solaris @file{/bin/false} exits with status 255.
12534 @item @command{for}
12535 @c ----------------
12536 @prindex @command{for}
12537 To loop over positional arguments, use:
12547 You may @emph{not} leave the @code{do} on the same line as @code{for},
12548 since some shells improperly grok:
12556 If you want to explicitly refer to the positional arguments, given the
12557 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
12560 for arg in $@{1+"$@@"@}; do
12566 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
12567 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
12568 item @samp{$@@}, for more.
12573 @prindex @command{if}
12574 Using @samp{!} is not portable. Instead of:
12577 if ! cmp -s file file.new; then
12586 if cmp -s file file.new; then :; else
12591 There are shells that do not reset the exit status from an @command{if}:
12594 $ @kbd{if (exit 42); then true; fi; echo $?}
12599 whereas a proper shell should have printed @samp{0}. This is especially
12600 bad in makefiles since it produces false failures. This is why properly
12601 written makefiles, such as Automake's, have such hairy constructs:
12604 if test -f "$file"; then
12605 install "$file" "$dest"
12612 @item @command{printf}
12613 @c ------------------
12614 @prindex @command{printf}
12615 A format string starting with a @samp{-} can cause problems.
12616 Bash (e.g., 2.05b) interprets it as an options argument and
12617 gives an error. And @samp{--} to mark the end of options is not good
12618 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that
12619 literally as the format string. Putting the @samp{-} in a @samp{%c}
12620 or @samp{%s} is probably the easiest way to avoid doubt,
12627 @item @command{read}
12628 @c ------------------
12629 @prindex @command{read}
12630 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
12633 @item @command{pwd}
12634 @c ----------------
12635 @prindex @command{pwd}
12636 With modern shells, plain @command{pwd} outputs a ``logical''
12637 directory name, some of whose components may be symbolic links. These
12638 directory names are in contrast to ``physical'' directory names, whose
12639 components are all directories.
12641 Posix 1003.1-2001 requires that @command{pwd} must support
12642 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12643 with @option{-L} being the default. However, traditional shells do
12644 not support these options, and their @command{pwd} command has the
12645 @option{-P} behavior.
12647 Portable scripts should assume neither option is supported, and should
12648 assume neither behavior is the default. Also, on many hosts
12649 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
12650 does not require this behavior and portable scripts should not rely on
12653 Typically it's best to use plain @command{pwd}. On modern hosts this
12654 outputs logical directory names, which have the following advantages:
12658 Logical names are what the user specified.
12660 Physical names may not be portable from one installation
12661 host to another due to network file system gymnastics.
12663 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
12664 some parent directory, but plain @command{pwd} cannot fail for this
12668 Also please see the discussion of the @command{cd} command.
12671 @item @command{set}
12672 @c ----------------
12673 @prindex @command{set}
12674 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
12675 any options) does not sort its output.
12677 The @command{set} builtin faces the usual problem with arguments starting with a
12678 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
12679 the end of the options (any argument after @option{--} is a parameter,
12680 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
12681 10 @command{/bin/sh}) simply stop option
12682 processing as soon as a non-option argument is found. Therefore, use
12683 @samp{dummy} or simply @samp{x} to end the option processing, and use
12684 @command{shift} to pop it out:
12687 set x $my_list; shift
12690 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
12691 longer requires support for this command, and in traditional shells
12692 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
12693 makes scripts harder to debug.
12695 Some nonstandard shells do not recognize more than one option
12696 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
12697 better to combine them:
12703 The @acronym{BSD} shell has had several problems with the @option{-e}
12704 option, partly because @acronym{BSD} @command{make} traditionally used
12705 @option{-e} even though this was incompatible with Posix
12706 (@pxref{Failure in Make Rules}). Older versions of the @acronym{BSD}
12707 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
12708 @samp{case} when @option{-e} was in effect, causing the shell to exit
12709 unexpectedly in some cases. This was particularly a problem with
12710 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
12711 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
12712 wrapper works around the bug.
12714 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
12715 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
12716 @samp{&&} fails inside a compound statement. For example:
12722 test -n "$foo" && exit 1
12725 test -n "$foo" && exit 1
12731 does not print @samp{two}. One workaround is to use @samp{if test -n
12732 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
12733 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
12736 @item @command{shift}
12737 @c ------------------
12738 @prindex @command{shift}
12739 Not only is @command{shift}ing a bad idea when there is nothing left to
12740 shift, but in addition it is not portable: the shell of @acronym{MIPS
12741 RISC/OS} 4.52 refuses to do it.
12743 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
12744 and it is also absent in many pre-Posix shells.
12747 @item @command{source}
12748 @c -------------------
12749 @prindex @command{source}
12750 This command is not portable, as Posix does not require it; use
12751 @command{.} instead.
12754 @item @command{test}
12755 @c -----------------
12756 @prindex @command{test}
12757 The @code{test} program is the way to perform many file and string
12758 tests. It is often invoked by the alternate name @samp{[}, but using
12759 that name in Autoconf code is asking for trouble since it is an M4 quote
12762 If you need to make multiple checks using @code{test}, combine them with
12763 the shell operators @samp{&&} and @samp{||} instead of using the
12764 @code{test} operators @option{-a} and @option{-o}. On System V, the
12765 precedence of @option{-a} and @option{-o} is wrong relative to the unary
12766 operators; consequently, Posix does not specify them, so using them
12767 is nonportable. If you combine @samp{&&} and @samp{||} in the same
12768 statement, keep in mind that they have equal precedence.
12770 It is safe to use @samp{!} as a @command{test} operator. For example,
12771 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
12772 -d foo; @dots{}} is not.
12775 @item @command{test} (files)
12776 @c -------------------------
12777 To enable @command{configure} scripts to support cross-compilation, they
12778 shouldn't do anything that tests features of the build system instead of
12779 the host system. But occasionally you may find it necessary to check
12780 whether some arbitrary file exists. To do so, use @samp{test -f} or
12781 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
12782 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
12783 lacks it. To test for symbolic links on systems that have them, use
12784 @samp{test -h} rather than @samp{test -L}; either form conforms to
12785 Posix 1003.1-2001, but older shells like Solaris 8
12786 @code{/bin/sh} support only @option{-h}.
12788 @item @command{test} (strings)
12789 @c ---------------------------
12790 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
12791 start with a dash, since @code{test} might interpret its argument as an
12792 option (e.g., @samp{@var{string} = "-n"}).
12794 Contrary to a common belief, @samp{test -n @var{string}} and
12795 @samp{test -z @var{string}} @strong{are} portable. Nevertheless many
12796 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
12797 Digital Unix 4, etc.)@: have bizarre precedence and may be confused if
12798 @var{string} looks like an operator:
12802 test: argument expected
12805 If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
12806 "x@var{string}" != x} instead.
12808 It is common to find variations of the following idiom:
12811 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
12816 to take an action when a token matches a given pattern. Such constructs
12817 should always be avoided by using:
12820 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
12825 Use @code{case} where possible since it is faster, being a shell builtin:
12829 case $ac_feature in
12830 *[!-a-zA-Z0-9_]*) @var{action};;
12834 Alas, negated character classes are probably not portable, although no
12835 shell is known to not support the Posix syntax @samp{[!@dots{}]}
12836 (when in interactive mode, @command{zsh} is confused by the
12837 @samp{[!@dots{}]} syntax and looks for an event in its history because of
12838 @samp{!}). Many shells do not support the alternative syntax
12839 @samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
12841 One solution can be:
12844 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12852 expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12856 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
12857 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
12858 @samp{@var{foo}} contains backslashes.
12861 @item @command{trap}
12862 @c -----------------
12863 @prindex @command{trap}
12864 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
12865 trap 0, i.e., have the @command{trap} run when the script ends (either via an
12866 explicit @command{exit}, or the end of the script). The trap for 0 should be
12867 installed outside of a shell function, or @acronym{AIX} 5.3 @command{/bin/sh}
12868 will invoke the trap at the end of this function.
12870 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
12871 specified signals to their default values, but many common shells (e.g.,
12872 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
12873 ``command'' named @command{-} when the specified conditions arise.
12874 There is no portable workaround, except for @samp{trap - 0}, for which
12875 @samp{trap '' 0} is a portable substitute.
12877 Although Posix is not absolutely clear on this point, it is widely
12878 admitted that when entering the trap @samp{$?} should be set to the exit
12879 status of the last command run before the trap. The ambiguity can be
12880 summarized as: ``when the trap is launched by an @command{exit}, what is
12881 the @emph{last} command run: that before @command{exit}, or
12882 @command{exit} itself?''
12884 Bash considers @command{exit} to be the last command, while Zsh and
12885 Solaris @command{/bin/sh} consider that when the trap is run it is
12886 @emph{still} in the @command{exit}, hence it is the previous exit status
12887 that the trap receives:
12890 $ @kbd{cat trap.sh}
12893 $ @kbd{zsh trap.sh}
12895 $ @kbd{bash trap.sh}
12899 The portable solution is then simple: when you want to @samp{exit 42},
12900 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
12901 set the exit status to 42 for Zsh, and the second to trigger the trap
12902 and pass 42 as exit status for Bash.
12904 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
12905 reset to 0 by empty lines if the code is inside @command{trap}.
12908 $ @kbd{trap 'false}
12916 Fortunately, this bug only affects @command{trap}.
12918 @item @command{true}
12919 @c -----------------
12920 @prindex @command{true}
12921 @c Info cannot handle `:' in index entries.
12922 @c @prindex @command{:}
12923 Don't worry: as far as we know @command{true} is portable.
12924 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
12925 portable shell community tends to prefer using @command{:}. This has a
12926 funny side effect: when asked whether @command{false} is more portable
12927 than @command{true} Alexandre Oliva answered:
12930 In a sense, yes, because if it doesn't exist, the shell will produce an
12931 exit status of failure, which is correct for @command{false}, but not
12932 for @command{true}.
12936 @item @command{unset}
12937 @c ------------------
12938 @prindex @command{unset}
12939 In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails
12940 when @code{FOO} is not set. Also, Bash 2.01 mishandles @code{unset
12941 MAIL} in some cases and dumps core.
12943 A few ancient shells lack @command{unset} entirely. Nevertheless, because
12944 it is extremely useful to disable embarrassing variables such as
12945 @code{PS1}, you can test for its existence and use
12946 it @emph{provided} you give a neutralizing value when @command{unset} is
12950 # "|| exit" suppresses any "Segmentation fault" message.
12951 if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then
12956 $unset PS1 || PS1='$ '
12960 @xref{Special Shell Variables}, for some neutralizing values. Also, see
12961 @ref{Limitations of Builtins}, documentation of @command{export}, for
12962 the case of environment variables.
12965 @node Limitations of Usual Tools
12966 @section Limitations of Usual Tools
12967 @cindex Limitations of usual tools
12969 The small set of tools you can expect to find on any machine can still
12970 include some limitations you should be aware of.
12976 Don't leave white space before the opening parenthesis in a user function call.
12977 Posix does not allow this and @acronym{GNU} Awk rejects it:
12980 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
12981 BEGIN @{ die () @}'}
12982 gawk: cmd. line:2: BEGIN @{ die () @}
12983 gawk: cmd. line:2: ^ parse error
12984 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
12985 BEGIN @{ die() @}'}
12989 If you want your program to be deterministic, don't depend on @code{for}
12993 $ @kbd{cat for.awk}
13000 $ @kbd{gawk -f for.awk </dev/null}
13003 $ @kbd{nawk -f for.awk </dev/null}
13008 Some Awk implementations, such as @acronym{HP-UX} 11.0's native one, mishandle anchors:
13011 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
13012 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
13014 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
13016 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
13021 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
13022 or use a simple test to reject such implementations.
13024 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the
13025 length of regular expressions and literal strings in an Awk program.
13027 Traditional Awk implementations derived from Unix version 7, such as
13028 Solaris @command{/bin/awk}, have many limitations and do not
13029 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
13030 Programs}) finds you an Awk that doesn't have these problems, but if
13031 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
13034 Traditional Awk does not support multidimensional arrays or user-defined
13037 Traditional Awk does not support the @option{-v} option. You can use
13038 assignments after the program instead, e.g., @command{$AWK '@{print v
13039 $1@}' v=x}; however, don't forget that such assignments are not
13040 evaluated until they are encountered (e.g., after any @code{BEGIN}
13043 Traditional Awk does not support the keywords @code{delete} or @code{do}.
13045 Traditional Awk does not support the expressions
13046 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
13047 or @code{@var{a}^=@var{b}}.
13049 Traditional Awk does not support the predefined @code{CONVFMT} variable.
13051 Traditional Awk supports only the predefined functions @code{exp},
13052 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
13053 @code{sqrt}, and @code{substr}.
13055 Traditional Awk @code{getline} is not at all compatible with Posix;
13058 Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
13059 @code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}.
13061 In code portable to both traditional and modern Awk, @code{FS} must be a
13062 string containing just one ordinary character, and similarly for the
13063 field-separator argument to @code{split}.
13065 Traditional Awk has a limit of 99
13066 fields in a record. You may be able to circumvent this problem by using
13069 Traditional Awk has a limit of at most 99 bytes in a number formatted by
13070 @code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
13073 The original version of Awk had a limit of at most 99 bytes per
13074 @code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
13075 per run of non-special characters in a @code{printf} format, but these
13076 bugs have been fixed on all practical hosts that we know of.
13078 @item @command{basename}
13079 @c ---------------------
13080 @prindex @command{basename}
13081 Not all hosts have a working @command{basename}.
13082 You can use @command{expr} instead.
13084 @c AS_BASENAME is to be replaced by a better API.
13086 Not all hosts have a working @command{basename}, and you should instead
13087 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
13088 @command{expr} if you need to strip a suffix. For example:
13091 a=`basename "$aname"` # This is not portable.
13092 a=`AS_BASENAME(["$aname"])` # This is more portable.
13094 # This is not portable.
13095 c=`basename "$cname" .c`
13097 # This is more portable.
13098 c=`AS_BASENAME(["$cname"])`
13100 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
13106 @item @command{cat}
13107 @c ----------------
13108 @prindex @command{cat}
13109 Don't rely on any option.
13114 @prindex @command{cc}
13115 The command @samp{cc -c foo.c} traditionally produces an object file
13116 named @file{foo.o}. Most compilers allow @option{-c} to be combined
13117 with @option{-o} to specify a different object file name, but
13118 Posix does not require this combination and a few compilers
13119 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
13120 tests for this feature with @code{AC_PROG_CC_C_O}.
13122 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
13123 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
13125 @acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and
13126 assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
13129 The default executable, produced by @samp{cc foo.c}, can be
13132 @item @file{a.out} --- usual Posix convention.
13133 @item @file{b.out} --- i960 compilers (including @command{gcc}).
13134 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
13135 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
13136 @item @file{foo.exe} --- various MS-DOS compilers.
13139 The C compiler's traditional name is @command{cc}, but other names like
13140 @command{gcc} are common. Posix 1003.1-2001 specifies the
13141 name @command{c99}, but older Posix editions specified
13142 @command{c89} and anyway these standard names are rarely used in
13143 practice. Typically the C compiler is invoked from makefiles that use
13144 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
13148 @item @command{chmod}
13149 @c ------------------
13150 @prindex @command{chmod}
13151 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
13152 instead, for two reasons. First, plain @option{-w} does not necessarily
13153 make the file unwritable, since it does not affect mode bits that
13154 correspond to bits in the file mode creation mask. Second,
13155 Posix says that the @option{-w} might be interpreted as an
13156 implementation-specific option, not as a mode; Posix suggests
13157 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
13158 @samp{--} does not work on some older hosts.
13161 @item @command{cmp}
13162 @c ----------------
13163 @prindex @command{cmp}
13164 @command{cmp} performs a raw data comparison of two files, while
13165 @command{diff} compares two text files. Therefore, if you might compare
13166 DOS files, even if only checking whether two files are different, use
13167 @command{diff} to avoid spurious differences due to differences of
13173 @prindex @command{cp}
13174 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
13175 obsolescent and its behavior on special files is implementation-defined.
13176 Use @option{-R} instead. On @acronym{GNU} hosts the two options
13177 are equivalent, but on Solaris hosts (for example) @command{cp -r}
13178 reads from pipes instead of replicating them.
13180 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
13181 trailing slashes at the end of nonexistent destination directories. To
13182 avoid this problem, omit the trailing slashes. For example, use
13183 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
13184 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
13186 @c This is thanks to Ian.
13187 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
13188 its @command{mv} does.
13190 @cindex timestamp resolution
13191 Traditionally, file timestamps had 1-second resolution, and @samp{cp
13192 -p} copied the timestamps exactly. However, many modern file systems
13193 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
13194 -p} implementations truncate timestamps when copying files, so this
13195 can result in the destination file appearing to be older than the
13196 source. The exact amount of truncation depends on the resolution of
13197 the system calls that @command{cp} uses; traditionally this was
13198 @code{utime}, which has 1-second resolution, but some newer
13199 @command{cp} implementations use @code{utimes}, which has
13200 1-microsecond resolution. These newer implementations include @acronym{GNU}
13201 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
13202 later. Unfortunately as of January 2006 there is still no system
13203 call to set timestamps to the full nanosecond resolution.
13205 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
13206 ownerships. But whether it actually does copy ownerships or not is a
13207 system dependent policy decision implemented by the kernel. If the
13208 kernel allows it then it happens. If the kernel does not allow it then
13209 it does not happen. It is not something @command{cp} itself has control
13212 In Unix System V any user can chown files to any other user, and System
13213 V also has a non-sticky @file{/tmp}. That probably derives from the
13214 heritage of System V in a business environment without hostile users.
13215 @acronym{BSD} changed this
13216 to be a more secure model where only root can @command{chown} files and
13217 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
13218 of @acronym{BSD} in a campus environment.
13220 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
13221 can be configured to allow a System V style @command{chown}. On the
13222 other hand, @acronym{HP-UX} follows System V, but can
13223 be configured to use the modern security model and disallow
13224 @command{chown}. Since it is an administrator-configurable parameter
13225 you can't use the name of the kernel as an indicator of the behavior.
13229 @item @command{date}
13230 @c -----------------
13231 @prindex @command{date}
13232 Some versions of @command{date} do not recognize special @samp{%} directives,
13233 and unfortunately, instead of complaining, they just pass them through,
13234 and exit with success:
13238 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
13244 @item @command{diff}
13245 @c -----------------
13246 @prindex @command{diff}
13247 Option @option{-u} is nonportable.
13249 Some implementations, such as Tru64's, fail when comparing to
13250 @file{/dev/null}. Use an empty file instead.
13253 @item @command{dirname}
13254 @c --------------------
13255 @prindex @command{dirname}
13256 Not all hosts have a working @command{dirname}, and you should instead
13257 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
13260 dir=`dirname "$file"` # This is not portable.
13261 dir=`AS_DIRNAME(["$file"])` # This is more portable.
13265 @item @command{egrep}
13266 @c ------------------
13267 @prindex @command{egrep}
13268 Posix 1003.1-2001 no longer requires @command{egrep},
13269 but many older hosts do not yet support the Posix
13270 replacement @code{grep -E}. Also, some traditional implementations do
13271 not work on long input lines. To work around these problems, invoke
13272 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
13274 Portable extended regular expressions should use @samp{\} only to escape
13275 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
13276 is not portable, even though it typically matches @samp{@}}.
13278 The empty alternative is not portable. Use @samp{?} instead. For
13279 instance with Digital Unix v5.0:
13282 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
13284 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
13286 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
13291 @command{$EGREP} also suffers the limitations of @command{grep}.
13293 @item @command{expr}
13294 @c -----------------
13295 @prindex @command{expr}
13296 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
13297 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
13298 misinterpreting @var{word}.
13300 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
13302 @item @command{expr} (@samp{|})
13303 @prindex @command{expr} (@samp{|})
13304 You can use @samp{|}. Although Posix does require that @samp{expr
13305 ''} return the empty string, it does not specify the result when you
13306 @samp{|} together the empty string (or zero) with the empty string. For
13313 Posix 1003.2-1992 returns the empty string
13314 for this case, but traditional Unix returns @samp{0} (Solaris is
13315 one such example). In Posix 1003.1-2001, the specification was
13316 changed to match traditional Unix's behavior (which is
13317 bizarre, but it's too late to fix this). Please note that the same
13318 problem does arise when the empty string results from a computation,
13322 expr bar : foo \| foo : bar
13326 Avoid this portability problem by avoiding the empty string.
13329 @item @command{expr} (@samp{:})
13330 @c ----------------------------
13331 @prindex @command{expr}
13332 Portable @command{expr} regular expressions should use @samp{\} to
13333 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
13334 For example, alternation, @samp{\|}, is common but Posix does not
13335 require its support, so it should be avoided in portable scripts.
13336 Similarly, @samp{\+} and @samp{\?} should be avoided.
13338 Portable @command{expr} regular expressions should not begin with
13339 @samp{^}. Patterns are automatically anchored so leading @samp{^} is
13342 The Posix standard is ambiguous as to whether
13343 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
13344 In practice, it outputs the empty string on most platforms, but portable
13345 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
13346 @command{expr} returns @samp{0}.
13348 One might think that a way to get a uniform behavior would be to use
13349 the empty string as a default value:
13352 expr a : '\(b\)' \| ''
13356 Unfortunately this behaves exactly as the original expression; see the
13357 @command{expr} (@samp{|}) entry for more information.
13359 Ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
13360 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
13361 @command{expr} to fail if the matched substring is longer than 120
13362 bytes. In this case, you might want to fall back on @samp{echo|sed} if
13363 @command{expr} fails. Nowadays this is of practical importance only for
13364 the rare installer who mistakenly puts @file{/usr/ucb} before
13365 @file{/usr/bin} in @env{PATH}.
13367 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
13368 some cases. For example, the command
13370 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
13374 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
13375 This particular case can be worked around by substituting @samp{[^--]}
13378 Don't leave, there is some more!
13380 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
13381 the empty string, has a funny behavior in its exit status: it's always 1
13382 when parentheses are used!
13385 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
13387 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
13390 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
13392 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
13397 In practice this can be a big problem if you are ready to catch failures
13398 of @command{expr} programs with some other method (such as using
13399 @command{sed}), since you may get twice the result. For instance
13402 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
13406 outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
13407 simple workaround consists of testing @command{expr} and using a variable
13408 set to @command{expr} or to @command{false} according to the result.
13410 Tru64 @command{expr} incorrectly treats the result as a number, if it
13411 can be interpreted that way:
13414 $ @kbd{expr 00001 : '.*\(...\)'}
13419 @item @command{fgrep}
13420 @c ------------------
13421 @prindex @command{fgrep}
13422 Posix 1003.1-2001 no longer requires @command{fgrep},
13423 but many older hosts do not yet support the Posix
13424 replacement @code{grep -F}. Also, some traditional implementations do
13425 not work on long input lines. To work around these problems, invoke
13426 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
13429 @item @command{find}
13430 @c -----------------
13431 @prindex @command{find}
13432 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
13433 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
13434 commands do not understand it.
13436 The replacement of @samp{@{@}} is guaranteed only if the argument is
13437 exactly @emph{@{@}}, not if it's only a part of an argument. For
13438 instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11:
13442 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
13447 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
13450 @item @command{grep}
13451 @c -----------------
13452 @prindex @command{grep}
13453 Portable scripts can rely on the @command{grep} options @option{-c},
13454 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
13455 options. For example, don't use @option{-w}, as Posix does not require
13456 it and Irix 6.5.16m's @command{grep} does not support it. Also,
13457 portable scripts should not combine @option{-c} with @option{-l},
13458 as Posix does not allow this.
13460 Some of the options required by Posix are not portable in practice.
13461 Don't use @samp{grep -q} to suppress output, because many @command{grep}
13462 implementations (e.g., Solaris) do not support @option{-q}.
13463 Don't use @samp{grep -s} to suppress output either, because Posix
13464 says @option{-s} does not suppress output, only some error messages;
13465 also, the @option{-s} option of traditional @command{grep} behaved
13466 like @option{-q} does in most modern implementations. Instead,
13467 redirect the standard output and standard error (in case the file
13468 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
13469 status of @code{grep} to determine whether it found a match.
13471 Some traditional @command{grep} implementations do not work on long
13472 input lines. On AIX the default @code{grep} silently truncates long
13473 lines on the input before matching.
13475 Also, many implementations do not support multiple regexps
13476 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
13477 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT). To
13478 work around these problems, invoke @code{AC_PROG_GREP} and then use
13481 Another possible workaround for the multiple @option{-e} problem is to
13482 separate the patterns by newlines, for example:
13490 except that this fails with traditional @command{grep}
13491 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
13493 Traditional @command{grep} implementations (e.g., Solaris) do not
13494 support the @option{-E} or @option{-F} options. To work around these
13495 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
13496 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
13497 willing to require support for Posix @command{grep}, your script should
13498 not use both @option{-E} and @option{-F}, since Posix does not allow
13501 Portable @command{grep} regular expressions should use @samp{\} only to
13502 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
13503 alternation, @samp{\|}, is common but Posix does not require its
13504 support in basic regular expressions, so it should be avoided in
13505 portable scripts. Solaris @command{grep} does not support it.
13506 Similarly, @samp{\+} and @samp{\?} should be avoided.
13509 @item @command{join}
13510 @c -----------------
13511 @prindex @command{join}
13512 Solaris 8 @command{join} has bugs when the second operand is standard
13513 input, and when standard input is a pipe. For example, the following
13514 shell script causes Solaris 8 @command{join} to loop forever:
13521 cat file | join file -
13524 Use @samp{join - file} instead.
13529 @prindex @command{ln}
13530 @cindex Symbolic links
13531 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
13532 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
13534 For versions of the @acronym{DJGPP} before 2.04,
13535 @command{ln} emulates symbolic links
13536 to executables by generating a stub that in turn calls the real
13537 program. This feature also works with nonexistent files like in the
13538 Posix spec. So @samp{ln -s file link} generates @file{link.exe},
13539 which attempts to call @file{file.exe} if run. But this feature only
13540 works for executables, so @samp{cp -p} is used instead for these
13541 systems. @acronym{DJGPP} versions 2.04 and later have full support
13542 for symbolic links.
13547 @prindex @command{ls}
13548 @cindex Listing directories
13549 The portable options are @option{-acdilrtu}. Current practice is for
13550 @option{-l} to output both owner and group, even though ancient versions
13551 of @command{ls} omitted the group.
13553 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
13554 to standard output if @file{foo} did not exist. Hence a shell command
13555 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
13556 was equivalent to @samp{sources='*.c not found'} in the absence of
13557 @samp{.c} files. This is no longer a practical problem, since current
13558 @command{ls} implementations send diagnostics to standard error.
13560 @item @command{mkdir}
13561 @c ------------------
13562 @prindex @command{mkdir}
13563 @cindex Making directories
13564 No @command{mkdir} option is portable to older systems. Instead of
13565 @samp{mkdir -p @var{file-name}}, you should use
13566 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
13567 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
13569 Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
13570 go-w -p @var{dir}}, often leads to trouble. Free@acronym{BSD}
13571 @command{mkdir} incorrectly attempts to change the permissions of
13572 @var{dir} even if it already exists. @acronym{HP-UX} 11.23 and
13573 @acronym{IRIX} 6.5 @command{mkdir} often assign the wrong permissions to
13574 any newly-created parents of @var{dir}.
13576 Posix does not clearly specify whether @samp{mkdir -p foo}
13577 should succeed when @file{foo} is a symbolic link to an already-existing
13578 directory. The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
13579 succeeds, but Solaris @command{mkdir} fails.
13581 Traditional @code{mkdir -p} implementations suffer from race conditions.
13582 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
13583 at the same time, both processes might detect that @file{a} is missing,
13584 one might create @file{a}, then the other might try to create @file{a}
13585 and fail with a @code{File exists} diagnostic. The @acronym{GNU} Core
13586 Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0,
13587 Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be
13588 race-free when two processes invoke @code{mkdir -p} simultaneously, but
13589 earlier versions are vulnerable. Solaris @command{mkdir} is still
13590 vulnerable as of Solaris 10, and other traditional Unix systems are
13591 probably vulnerable too. This possible race is harmful in parallel
13592 builds when several Make rules call @code{mkdir -p} to
13593 construct directories. You may use
13594 @code{install-sh -d} as a safe replacement, provided this script is
13595 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
13596 OK, but copies from older versions are vulnerable.
13599 @item @command{mktemp}
13600 @c -------------------
13601 @prindex @command{mktemp}
13602 @cindex Creating temporary files
13603 Shell scripts can use temporary files safely with @command{mktemp}, but
13604 it does not exist on all systems. A portable way to create a safe
13605 temporary file name is to create a temporary directory with mode 700 and
13606 use a file inside this directory. Both methods prevent attackers from
13607 gaining control, though @command{mktemp} is far less likely to fail
13608 gratuitously under attack.
13610 Here is sample code to create a new temporary directory safely:
13613 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
13614 # Use mktemp if possible; otherwise fall back on mkdir,
13615 # with $RANDOM to make collisions less likely.
13619 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
13621 test -n "$tmp" && test -d "$tmp"
13623 tmp=$TMPDIR/foo$$-$RANDOM
13624 (umask 077 && mkdir "$tmp")
13631 @prindex @command{mv}
13632 @cindex Moving open files
13633 The only portable options are @option{-f} and @option{-i}.
13635 Moving individual files between file systems is portable (it was in Unix
13637 but it is not always atomic: when doing @samp{mv new existing}, there's
13638 a critical section where neither the old nor the new version of
13639 @file{existing} actually exists.
13641 On some systems moving files from @file{/tmp} can sometimes cause
13642 undesirable (but perfectly valid) warnings, even if you created these
13643 files. This is because @file{/tmp} belongs to a group that ordinary
13644 users are not members of, and files created in @file{/tmp} inherit
13645 the group of @file{/tmp}. When the file is copied, @command{mv} issues
13646 a diagnostic without failing:
13649 $ @kbd{touch /tmp/foo}
13650 $ @kbd{mv /tmp/foo .}
13651 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
13659 This annoying behavior conforms to Posix, unfortunately.
13661 Moving directories across mount points is not portable, use @command{cp}
13664 @acronym{DOS} variants cannot rename or remove open files, and do not
13665 support commands like @samp{mv foo bar >foo}, even though this is
13666 perfectly portable among Posix hosts.
13671 @prindex @command{od}
13673 In Mac OS X 10.3, @command{od} does not support the
13674 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
13675 @option{-t}, or the @acronym{XSI} option @option{-s}. The only
13676 supported Posix option is @option{-v}, and the only supported
13677 @acronym{XSI} options are those in @option{-bcdox}. The @acronym{BSD}
13678 @command{hexdump} program can be used instead.
13680 This problem no longer exists in Mac OS X 10.4.3.
13685 @prindex @command{rm}
13686 The @option{-f} and @option{-r} options are portable.
13688 It is not portable to invoke @command{rm} without operands. For
13689 example, on many systems @samp{rm -f -r} (with no other arguments)
13690 silently succeeds without doing anything, but it fails with a diagnostic
13691 on Net@acronym{BSD} 2.0.2.
13693 A file might not be removed even if its parent directory is writable
13694 and searchable. Many Posix hosts cannot remove a mount point, a named
13695 stream, a working directory, or a last link to a file that is being
13698 @acronym{DOS} variants cannot rename or remove open files, and do not
13699 support commands like @samp{rm foo >foo}, even though this is
13700 perfectly portable among Posix hosts.
13703 @item @command{sed}
13704 @c ----------------
13705 @prindex @command{sed}
13706 Patterns should not include the separator (unless escaped), even as part
13707 of a character class. In conformance with Posix, the Cray
13708 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
13710 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
13711 not require support for empty patterns, and Unicos 9 @command{sed} rejects
13714 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
13716 Sed scripts should not use branch labels longer than 7 characters and
13717 should not contain comments. @acronym{HP-UX} sed has a limit of 99 commands
13718 (not counting @samp{:} commands) and
13719 48 labels, which can not be circumvented by using more than one script
13720 file. It can execute up to 19 reads with the @samp{r} command per cycle.
13721 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
13722 about 6000 bytes for the internal representation of commands.
13724 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
13725 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
13726 @samp{;} as a command:
13729 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
13730 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
13733 Input should not have unreasonably long lines, since some @command{sed}
13734 implementations have an input buffer limited to 4000 bytes.
13736 Portable @command{sed} regular expressions should use @samp{\} only to escape
13737 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
13738 alternation, @samp{\|}, is common but Posix does not require its
13739 support, so it should be avoided in portable scripts. Solaris
13740 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
13741 deletes only lines that contain the literal string @samp{a|b}.
13742 Similarly, @samp{\+} and @samp{\?} should be avoided.
13744 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
13746 Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
13747 quite portable to current hosts, but was not supported by some ancient
13748 @command{sed} implementations like SVR3.
13750 Some @command{sed} implementations, e.g., Solaris,
13751 restrict the special role of the asterisk to one-character regular expressions.
13752 This may lead to unexpected behavior:
13755 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
13757 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
13761 The @option{-e} option is portable, so long as its argument
13762 does not begin with @samp{a}, @samp{c}, or @samp{i}
13763 (as this runs afoul of a Tru64 5.1 bug).
13764 Some people prefer to use @samp{-e}:
13767 sed -e '@var{command-1}' \
13768 -e '@var{command-2}'
13772 as opposed to the equivalent:
13782 The following usage is sometimes equivalent:
13785 sed '@var{command-1};@var{command-2}'
13788 but Posix says that this use of a semicolon has undefined effect if
13789 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
13790 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
13791 should use semicolon only with simple scripts that do not use these
13794 Commands inside @{ @} brackets are further restricted. Posix says that
13795 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
13796 each command must be followed immediately by a newline, without any
13797 intervening blanks or semicolons. The closing bracket must be alone on
13798 a line, other than white space preceding or following it.
13800 Contrary to yet another urban legend, you may portably use @samp{&} in
13801 the replacement part of the @code{s} command to mean ``what was
13802 matched''. All descendants of Unix version 7 @command{sed}
13804 don't have first hand experience with older @command{sed} implementations) have
13807 Posix requires that you must not have any white space between
13808 @samp{!} and the following command. It is OK to have blanks between
13809 the address and the @samp{!}. For instance, on Solaris:
13812 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
13813 @error{}Unrecognized command: /bar/ ! p
13814 $ @kbd{echo "foo" | sed -n '/bar/! p'}
13815 @error{}Unrecognized command: /bar/! p
13816 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
13820 Posix also says that you should not combine @samp{!} and @samp{;}. If
13821 you use @samp{!}, it is best to put it on a command that is delimited by
13822 newlines rather than @samp{;}.
13824 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
13825 @samp{w} commands be followed by exactly one space before their argument.
13826 On the other hand, no white space is allowed between @samp{:} and the
13827 subsequent label name.
13829 If a sed script is specified on the command line and ends in an
13830 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
13831 should be followed by a newline. Otherwise some @command{sed}
13832 implementations (e.g., Open@acronym{BSD} 3.9) do not append a newline to the
13835 Many @command{sed} implementations (e.g., MacOS X 10.4,
13836 Open@acronym{BSD} 3.9, Solaris 10
13837 @command{/usr/ucb/sed}) strip leading white space from the text of
13838 @samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
13839 work around this incompatibility with Posix:
13842 $ @kbd{echo flushleft | sed 'a\}
13847 $ @kbd{echo foo | sed 'a\}
13855 @item @command{sed} (@samp{t})
13856 @c ---------------------------
13857 @prindex @command{sed} (@samp{t})
13858 Some old systems have @command{sed} that ``forget'' to reset their
13859 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
13860 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
13861 script (the line numbers are not actual part of the texts):
13864 s/keep me/kept/g # a
13900 Why? When processing line 1, (c) matches, therefore sets the @samp{t}
13901 flag, and the output is produced. When processing
13902 line 2, the @samp{t} flag is still set (this is the bug). Command (a)
13903 fails to match, but @command{sed} is not supposed to clear the @samp{t}
13904 flag when a substitution fails. Command (b) sees that the flag is set,
13905 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
13906 instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
13907 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
13908 Finally, since the flag is clear, line 4 is processed properly.
13910 There are two things one should remember about @samp{t} in @command{sed}.
13911 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
13912 succeeded, not only the immediately preceding substitution. Therefore,
13913 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
13914 line, to reset the @samp{t} flag where needed.
13916 Secondly, you cannot rely on @command{sed} to clear the flag at each new
13919 One portable implementation of the script above is:
13930 @item @command{touch}
13931 @c ------------------
13932 @prindex @command{touch}
13933 @cindex timestamp resolution
13934 If you specify the desired timestamp (e.g., with the @option{-r}
13935 option), @command{touch} typically uses the @code{utime} or
13936 @code{utimes} system call, which can result in the same kind of
13937 timestamp truncation problems that @samp{cp -p} has.
13939 On ancient @acronym{BSD} systems, @command{touch} or any command that
13940 results in an empty file does not update the timestamps, so use a
13941 command like @command{echo} as a workaround.
13943 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
13944 fails to work on SunOS 4.1.3 when the empty file is on an
13945 @acronym{NFS}-mounted 4.2 volume.
13946 However, these problems are no longer of practical concern.
13951 @node Portable Make
13952 @chapter Portable Make Programming
13953 @prindex @command{make}
13954 @cindex Limitations of @command{make}
13956 Writing portable makefiles is an art. Since a makefile's commands are
13957 executed by the shell, you must consider the shell portability issues
13958 already mentioned. However, other issues are specific to @command{make}
13962 * $< in Ordinary Make Rules:: $< in ordinary rules
13963 * Failure in Make Rules:: Failing portably in rules
13964 * Special Chars in Names:: Special Characters in Macro Names
13965 * Backslash-Newline-Newline:: Empty last lines in macro definitions
13966 * Backslash-Newline Comments:: Spanning comments across line boundaries
13967 * Long Lines in Makefiles:: Line length limitations
13968 * Macros and Submakes:: @code{make macro=value} and submakes
13969 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
13970 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
13971 * Comments in Make Rules:: Other problems with Make comments
13972 * obj/ and Make:: Don't name a subdirectory @file{obj}
13973 * make -k Status:: Exit status of @samp{make -k}
13974 * VPATH and Make:: @code{VPATH} woes
13975 * Single Suffix Rules:: Single suffix rules and separated dependencies
13976 * Timestamps and Make:: Subsecond timestamp resolution
13979 @node $< in Ordinary Make Rules
13980 @section @code{$<} in Ordinary Make Rules
13982 Posix says that the @samp{$<} construct in makefiles can be
13983 used only in inference rules and in the @samp{.DEFAULT} rule; its
13984 meaning in ordinary rules is unspecified. Solaris @command{make}
13985 for instance replaces it with the empty string. Open@acronym{BSD} (3.0 and
13986 later) @command{make} diagnoses these uses and errors out.
13988 @node Failure in Make Rules
13989 @section Failure in Make Rules
13991 Since 1992 Posix has required that @command{make} must invoke
13992 each command with the equivalent of a @samp{sh -c} subshell. However,
13993 many @command{make} implementations, including @acronym{BSD} make through 2004,
13994 use @samp{sh -e -c} instead, and the @option{-e} option causes the
13995 subshell to exit immediately if a subsidiary simple-command fails. For
13996 example, the command @samp{touch T; rm -f U} always attempts to
13997 remove @file{U} with Posix make, but incompatible
13998 @command{make} implementations skip the @command{rm} if the
13999 @command{touch} fails. One way to work around this is to reword the
14000 affected simple-commands so that they always succeed, e.g., @samp{touch
14002 However, even this approach can run into common bugs in @acronym{BSD}
14003 implementations of the @option{-e} option of @command{sh} and
14004 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
14005 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
14006 complicated @command{make} actions into separate scripts.
14008 @node Special Chars in Names
14009 @section Special Characters in Make Macro Names
14011 Posix limits macro names to nonempty strings containing only
14012 @acronym{ASCII} letters and digits, @samp{.}, and @samp{_}. Many
14013 @command{make} implementations allow a wider variety of characters, but
14014 portable makefiles should avoid them. It is portable to start a name
14015 with a special character, e.g., @samp{$(.FOO)}.
14017 Some ancient @command{make} implementations don't support leading
14018 underscores in macro names. An example is @acronym{NEWS-OS} 4.2R.
14021 $ @kbd{cat Makefile}
14024 all:; @@echo this is test
14026 Make: Must be a separator on rules line 2. Stop.
14027 $ @kbd{cat Makefile2}
14030 all:; @@echo this is test
14031 $ @kbd{make -f Makefile2}
14036 However, this problem is no longer of practical concern.
14038 @node Backslash-Newline-Newline
14039 @section Backslash-Newline-Newline in Make Macro Values
14041 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
14042 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
14043 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
14044 On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines
14045 following a backslash, continuing to the next non-empty line. For
14059 shows @code{FOO} equal to @code{one BAR = two}. Other implementations
14060 sensibly let a backslash continue only to the immediately following
14063 @node Backslash-Newline Comments
14064 @section Backslash-Newline in Make Comments
14066 According to Posix, Make comments start with @code{#}
14067 and continue until an unescaped newline is reached.
14070 $ @kbd{cat Makefile}
14077 $ @kbd{make} # GNU make
14082 However this is not always the case. Some implementations
14083 discard everything from @code{#} through the end of the line, ignoring any
14084 trailing backslash.
14087 $ @kbd{pmake} # BSD make
14088 "Makefile", line 3: Need an operator
14089 Fatal errors encountered -- cannot continue
14093 Therefore, if you want to comment out a multi-line definition, prefix each
14094 line with @code{#}, not only the first.
14102 @node Long Lines in Makefiles
14103 @section Long Lines in Makefiles
14105 Tru64 5.1's @command{make} has been reported to crash when given a
14106 makefile with lines longer than around 20 kB. Earlier versions are
14107 reported to exit with @code{Line too long} diagnostics.
14109 @node Macros and Submakes
14110 @section @code{make macro=value} and Submakes
14112 A command-line variable definition such as @code{foo=bar} overrides any
14113 definition of @code{foo} in a makefile. Some @command{make}
14114 implementations (such as @acronym{GNU} @command{make}) propagate this
14115 override to subsidiary invocations of @command{make}. Some other
14116 implementations do not pass the substitution along to submakes.
14119 $ @kbd{cat Makefile}
14126 $ @kbd{make foo=bar} # GNU make 3.79.1
14129 make[1]: Entering directory `/home/adl'
14131 make[1]: Leaving directory `/home/adl'
14132 $ @kbd{pmake foo=bar} # BSD make
14138 You have a few possibilities if you do want the @code{foo=bar} override
14139 to propagate to submakes. One is to use the @option{-e}
14140 option, which causes all environment variables to have precedence over
14141 the makefile macro definitions, and declare foo as an environment
14145 $ @kbd{env foo=bar make -e}
14148 The @option{-e} option is propagated to submakes automatically,
14149 and since the environment is inherited between @command{make}
14150 invocations, the @code{foo} macro is overridden in
14151 submakes as expected.
14153 This syntax (@code{foo=bar make -e}) is portable only when used
14154 outside of a makefile, for instance from a script or from the
14155 command line. When run inside a @command{make} rule, @acronym{GNU}
14156 @command{make} 3.80 and prior versions forget to propagate the
14157 @option{-e} option to submakes.
14159 Moreover, using @option{-e} could have unexpected side effects if your
14160 environment contains some other macros usually defined by the
14161 makefile. (See also the note about @code{make -e} and @code{SHELL}
14164 Another way to propagate overrides to submakes is to do it
14165 manually, from your makefile:
14171 $(MAKE) foo=$(foo) two
14176 You need to foresee all macros that a user might want to override if
14179 @node The Make Macro MAKEFLAGS
14180 @section The Make Macro MAKEFLAGS
14181 @cindex @code{MAKEFLAGS} and @command{make}
14182 @cindex @command{make} and @code{MAKEFLAGS}
14184 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
14185 current and recursive invocations of make, but allows implementations
14186 several formats for the variable. It is tricky to parse
14187 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
14188 or @option{-k} for continued execution are in effect. For example, you
14189 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
14190 contains single-letter options, since in the Cygwin version of
14191 @acronym{GNU} @command{make} it is either @option{--unix} or
14192 @option{--win32} with the second word containing single-letter options.
14195 $ @kbd{cat Makefile}
14197 @@echo MAKEFLAGS = $(MAKEFLAGS)
14201 MAKEFLAGS = --unix -k
14204 @node The Make Macro SHELL
14205 @section The Make Macro @code{SHELL}
14206 @cindex @code{SHELL} and @command{make}
14207 @cindex @command{make} and @code{SHELL}
14209 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
14210 macro to spawn shell processes and execute Make rules. This
14211 is a builtin macro supplied by @command{make}, but it can be modified
14212 by a makefile or by a command-line argument.
14214 Not all @command{make} implementations define this @code{SHELL} macro.
14216 @command{make} is an example; this implementation always uses
14217 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
14218 your makefiles. If you use Autoconf, do
14224 Do not force @code{SHELL = /bin/sh} because that is not correct
14225 everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
14226 its @acronym{GNU} @code{make} port sees such a setting it enters a special
14227 emulation mode where features like pipes and redirections are emulated
14228 on top of DOS's @command{command.com}. Unfortunately this emulation is
14229 incomplete; for instance it does not handle command substitutions.
14230 On @acronym{DJGPP} @code{SHELL} should point to Bash.
14232 Posix-compliant @command{make} should never acquire the value of
14233 $(SHELL) from the environment, even when @code{make -e} is used
14234 (otherwise, think about what would happen to your rules if
14235 @code{SHELL=/bin/tcsh}).
14237 However not all @command{make} implementations have this exception.
14238 For instance it's not surprising that Tru64 @command{make} doesn't
14239 protect @code{SHELL}, since it doesn't use it.
14242 $ @kbd{cat Makefile}
14248 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
14251 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
14256 @node Comments in Make Rules
14257 @section Comments in Make Rules
14258 @cindex Comments in @file{Makefile} rules
14259 @cindex @file{Makefile} rules and comments
14261 Never put comments in a rule.
14263 Some @command{make} treat anything starting with a tab as a command for
14264 the current rule, even if the tab is immediately followed by a @code{#}.
14265 The @command{make} from Tru64 Unix V5.1 is one of them. The following
14266 makefile runs @code{# foo} through the shell.
14273 @node obj/ and Make
14274 @section The @file{obj/} Subdirectory and Make
14275 @cindex @file{obj/}, subdirectory
14276 @cindex @acronym{BSD} @command{make} and @file{obj/}
14278 Never name one of your subdirectories @file{obj/} if you don't like
14281 If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it
14282 before reading the makefile. Hence the makefile in the
14283 current directory is not read.
14286 $ @kbd{cat Makefile}
14289 $ @kbd{cat obj/Makefile}
14292 $ @kbd{make} # GNU make
14295 $ @kbd{pmake} # BSD make
14300 @node make -k Status
14301 @section Exit Status of @code{make -k}
14302 @cindex @code{make -k}
14304 Do not rely on the exit status of @code{make -k}. Some implementations
14305 reflect whether they encountered an error in their exit status; other
14306 implementations always succeed.
14309 $ @kbd{cat Makefile}
14312 $ @kbd{make -k; echo exit status: $?} # GNU make
14314 make: *** [all] Error 1
14316 $ @kbd{pmake -k; echo exit status: $?} # BSD make
14318 *** Error code 1 (continuing)
14322 @node VPATH and Make
14323 @section @code{VPATH} and Make
14324 @cindex @code{VPATH}
14326 Posix does not specify the semantics of @code{VPATH}. Typically,
14327 @command{make} supports @code{VPATH}, but its implementation is not
14330 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
14331 portable to recent-enough popular implementations of @command{make}, but
14332 to keep the resulting makefiles portable, a package's makefile
14333 prototypes must take the following issues into account. These issues
14334 are complicated and are often poorly understood, and installers who use
14335 @code{VPATH} should expect to find many bugs in this area. If you use
14336 @code{VPATH}, the simplest way to avoid these portability bugs is to
14337 stick with @acronym{GNU} @command{make}, since it is the most
14338 commonly-used @command{make} among Autoconf users.
14340 Here are some known issues with some @code{VPATH}
14344 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
14345 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
14346 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
14347 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
14348 * Make Target Lookup:: More details about @code{VPATH} lookup
14351 @node VPATH and Double-colon
14352 @subsection @code{VPATH} and Double-colon Rules
14353 @cindex @code{VPATH} and double-colon rules
14354 @cindex double-colon rules and @code{VPATH}
14356 With ancient versions of Sun @command{make},
14357 any assignment to @code{VPATH} causes @command{make} to execute only
14358 the first set of double-colon rules.
14359 However, this problem is no longer of practical concern.
14361 @node $< in Explicit Rules
14362 @subsection @code{$<} Not Supported in Explicit Rules
14363 @cindex explicit rules, @code{$<}, and @code{VPATH}
14364 @cindex @code{$<}, explicit rules, and @code{VPATH}
14365 @cindex @code{VPATH}, explicit rules, and @code{$<}
14367 Using @code{$<} in explicit rules is not portable.
14368 The prerequisite file must be named explicitly in the rule. If you want
14369 to find the prerequisite via a @code{VPATH} search, you have to code the
14370 whole thing manually. @xref{Build Directories}.
14372 @node Automatic Rule Rewriting
14373 @subsection Automatic Rule Rewriting
14374 @cindex @code{VPATH} and automatic rule rewriting
14375 @cindex automatic rule rewriting and @code{VPATH}
14377 Some @command{make} implementations, such as Solaris and Tru64,
14378 search for prerequisites in @code{VPATH} and
14379 then rewrite each occurrence as a plain word in the rule.
14383 # This isn't portable to GNU make.
14390 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
14391 found in @file{../pkg/src}.
14393 However, this rule leads to real problems in practice. For example, if
14394 the source directory contains an ordinary file named @file{test} that is
14395 used in a dependency, Solaris @command{make} rewrites commands like
14396 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
14397 @dots{}}, which is typically undesirable. To avoid this problem,
14398 portable makefiles should never mention a source file whose name is that
14399 of a shell keyword like @file{until} or a shell command like
14400 @command{cat} or @command{gcc} or @command{test}.
14402 Because of these problems @acronym{GNU} @command{make} and many other
14403 @command{make} implementations do not rewrite commands, so portable
14405 search @code{VPATH} manually. It is tempting to write this:
14408 # This isn't portable to Solaris make.
14411 cp `test -f if.c || echo $(VPATH)/`if.c f.c
14415 However, the ``prerequisite rewriting'' still applies here. So if
14416 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
14420 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
14431 and thus fails. Oops.
14433 A simple workaround, and good practice anyway, is to use @samp{$?} and
14434 @samp{$@@} when possible:
14443 but this does not generalize well to commands with multiple
14444 prerequisites. A more general workaround is to rewrite the rule so that
14445 the prerequisite @file{if.c} never appears as a plain word. For
14446 example, these three rules would be safe, assuming @file{if.c} is in
14447 @file{../pkg/src} and the other files are in the working directory:
14452 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
14454 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
14456 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
14459 Things get worse when your prerequisites are in a macro.
14463 HEADERS = f.h g.h h.h
14464 install-HEADERS: $(HEADERS)
14465 for i in $(HEADERS); do \
14466 $(INSTALL) -m 644 \
14467 `test -f $$i || echo $(VPATH)/`$$i \
14468 $(DESTDIR)$(includedir)/$$i; \
14472 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
14473 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
14474 where @code{f.h} and @code{g.h} are plain words and are hence
14475 subject to @code{VPATH} adjustments.
14477 If the three files are in @file{../pkg/src}, the rule is run as:
14480 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
14482 `test -f $i || echo ../pkg/src/`$i \
14483 /usr/local/include/$i; \
14487 where the two first @command{install} calls fail. For instance,
14488 consider the @code{f.h} installation:
14492 `test -f ../pkg/src/f.h || \
14495 /usr/local/include/../pkg/src/f.h;
14504 /usr/local/include/../pkg/src/f.h;
14507 Note that the manual @code{VPATH} search did not cause any problems here;
14508 however this command installs @file{f.h} in an incorrect directory.
14510 Trying to quote @code{$(HEADERS)} in some way, as we did for
14511 @code{foo.c} a few makefiles ago, does not help:
14514 install-HEADERS: $(HEADERS)
14515 headers='$(HEADERS)'; \
14516 for i in $$headers; do \
14517 $(INSTALL) -m 644 \
14518 `test -f $$i || echo $(VPATH)/`$$i \
14519 $(DESTDIR)$(includedir)/$$i; \
14523 Now, @code{headers='$(HEADERS)'} macroexpands to:
14526 headers='f.h g.h h.h'
14530 but @code{g.h} is still a plain word. (As an aside, the idiom
14531 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
14532 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
14533 syntax error on @code{for i in;}.)
14535 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
14539 HEADERS = f.h g.h h.h
14540 install-HEADERS: $(HEADERS)
14541 headers='$(HEADERS)'; \
14542 for i in $$headers; do \
14543 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
14544 $(INSTALL) -m 644 \
14545 `test -f $$i || echo $(VPATH)/`$$i \
14546 $(DESTDIR)$(includedir)/$$i; \
14550 Automake does something similar. However the above hack works only if
14551 the files listed in @code{HEADERS} are in the current directory or a
14552 subdirectory; they should not be in an enclosing directory. If we had
14553 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
14554 build with Tru64 @command{make}. The reason is that not only does
14555 Tru64 @command{make} rewrite dependencies, but it also simplifies
14556 them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
14557 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
14558 a leading @file{../pkg/src/} component.
14560 The following example makes the behavior of Tru64 @command{make}
14564 $ @kbd{cat Makefile}
14576 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
14577 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
14578 directory does not even exist, this just means that the simplification
14579 occurred before the file was checked for.)
14581 For the record here is how SunOS 4 @command{make} behaves on this
14586 make: Fatal error: Don't know how to make target `../foo'
14594 @node Tru64 Directory Magic
14595 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
14596 @cindex @code{VPATH} and prerequisite directories
14597 @cindex prerequisite directories and @code{VPATH}
14599 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
14600 @command{make} creates it in the current directory.
14603 $ @kbd{mkdir -p foo/bar build}
14605 $ @kbd{cat >Makefile <<END
14614 This can yield unexpected results if a rule uses a manual @code{VPATH}
14615 search as presented before.
14620 command `test -d foo/bar || echo ../`foo/bar
14623 The above @command{command} is run on the empty @file{foo/bar}
14624 directory that was created in the current directory.
14626 @node Make Target Lookup
14627 @subsection Make Target Lookup
14628 @cindex @code{VPATH}, resolving target pathnames
14630 @acronym{GNU} @command{make} uses a complex algorithm to decide when it
14631 should use files found via a @code{VPATH} search. @xref{Search
14632 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
14635 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
14636 file name found during the @code{VPATH} search for this target, and
14637 builds the file locally using the file name given in the makefile.
14638 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
14639 file name found during the @code{VPATH} search.
14641 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
14642 easier to describe: the file name found during the @code{VPATH} search
14643 is used whether the target needs to be rebuilt or not. Therefore
14644 new files are created locally, but existing files are updated at their
14645 @code{VPATH} location.
14647 Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however,
14649 @code{VPATH} search for a dependency that has an explicit rule.
14650 This is extremely annoying.
14652 When attempting a @code{VPATH} build for an autoconfiscated package
14653 (e.g., @code{mkdir build && cd build && ../configure}), this means
14655 @command{make} builds everything locally in the @file{build}
14656 directory, while @acronym{BSD} @command{make} builds new files locally and
14657 updates existing files in the source directory.
14660 $ @kbd{cat Makefile}
14663 foo.x bar.x: newer.x
14664 @@echo Building $@@
14665 $ @kbd{touch ../bar.x}
14666 $ @kbd{touch ../newer.x}
14667 $ @kbd{make} # GNU make
14670 $ @kbd{pmake} # NetBSD make
14673 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14676 $ @kbd{tmake} # Tru64 make
14679 $ @kbd{touch ../bar.x}
14680 $ @kbd{make} # GNU make
14682 $ @kbd{pmake} # NetBSD make
14684 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14687 $ @kbd{tmake} # Tru64 make
14692 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
14693 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
14694 @command{make} always
14695 update @file{bar.x}, even when @file{../bar.x} is up to date.
14697 Another point worth mentioning is that once @acronym{GNU} @command{make} has
14698 decided to ignore a @code{VPATH} file name (e.g., it ignored
14699 @file{../bar.x} in the above example) it continues to ignore it when
14700 the target occurs as a prerequisite of another rule.
14702 The following example shows that @acronym{GNU} @command{make} does not look up
14703 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
14704 because it ignored the @code{VPATH} result of @file{bar.x} while running
14705 the @code{bar.x: newer.x} rule.
14708 $ @kbd{cat Makefile}
14712 @@echo Building $@@
14716 $ @kbd{touch ../bar.x}
14717 $ @kbd{touch ../newer.x}
14718 $ @kbd{make} # GNU make
14721 cp: cannot stat `bar.x': No such file or directory
14722 make: *** [bar.y] Error 1
14723 $ @kbd{pmake} # NetBSD make
14727 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14728 echo Building bar.x
14730 cp: cannot stat `bar.x': No such file or directory
14732 $ @kbd{tmake} # Tru64 make
14734 cp: bar.x: No such file or directory
14738 Note that if you drop away the command from the @code{bar.x: newer.x}
14739 rule, @acronym{GNU} @command{make} magically starts to work: it
14740 knows that @code{bar.x} hasn't been updated, therefore it doesn't
14741 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
14742 uses. Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD}
14746 $ @kbd{cat Makefile}
14753 $ @kbd{touch ../bar.x}
14754 $ @kbd{touch ../newer.x}
14755 $ @kbd{make} # GNU make
14758 $ @kbd{pmake} # NetBSD make
14761 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14763 cp: cannot stat `bar.x': No such file or directory
14765 $ @kbd{tmake} # Tru64 make
14769 It seems the sole solution that would please every @command{make}
14770 implementation is to never rely on @code{VPATH} searches for targets.
14771 In other words, @code{VPATH} should be reserved to unbuilt sources.
14774 @node Single Suffix Rules
14775 @section Single Suffix Rules and Separated Dependencies
14776 @cindex Single Suffix Inference Rule
14777 @cindex Rule, Single Suffix Inference
14778 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
14779 (@samp{.from.to:}), but which @emph{destination} suffix is empty
14782 @cindex Separated Dependencies
14783 @dfn{Separated dependencies} simply refers to listing the prerequisite
14784 of a target, without defining a rule. Usually one can list on the one
14785 hand side, the rules, and on the other hand side, the dependencies.
14787 Solaris @command{make} does not support separated dependencies for
14788 targets defined by single suffix rules:
14791 $ @kbd{cat Makefile}
14796 $ @kbd{touch foo.in}
14803 while @acronym{GNU} Make does:
14809 Makefile foo foo.in
14812 Note it works without the @samp{foo: foo.in} dependency.
14815 $ @kbd{cat Makefile}
14824 and it works with double suffix inference rules:
14827 $ @kbd{cat Makefile}
14829 .SUFFIXES: .in .out
14836 As a result, in such a case, you have to write target rules.
14838 @node Timestamps and Make
14839 @section Timestamp Resolution and Make
14840 @cindex timestamp resolution
14841 Traditionally, file timestamps had 1-second resolution, and
14842 @command{make} used those timestamps to determine whether one file was
14843 newer than the other. However, many modern file systems have
14844 timestamps with 1-nanosecond resolution. Some @command{make}
14845 implementations look at the entire timestamp; others ignore the
14846 fractional part, which can lead to incorrect results. Normally this
14847 is not a problem, but in some extreme cases you may need to use tricks
14848 like @samp{sleep 1} to work around timestamp truncation bugs.
14850 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
14851 file timestamps to their full resolutions (@pxref{Limitations of Usual
14852 Tools}). Hence you should be wary of rules like this:
14859 as @file{dest} often appears to be older than @file{src} after the
14860 timestamp is truncated, and this can cause @command{make} to do
14861 needless rework the next time it is invoked. To work around this
14862 problem, you can use a timestamp file, e.g.:
14873 @c ======================================== Portable C and C++ Programming
14875 @node Portable C and C++
14876 @chapter Portable C and C++ Programming
14877 @cindex Portable C and C++ programming
14879 C and C++ programs often use low-level features of the underlying
14880 system, and therefore are often more difficult to make portable to other
14883 Several standards have been developed to help make your programs more
14884 portable. If you write programs with these standards in mind, you can
14885 have greater confidence that your programs work on a wide variety
14886 of systems. @xref{Standards, , Language Standards Supported by
14887 @acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection
14888 (@acronym{GCC})}, for a list of C-related
14889 standards. Many programs also assume the
14890 @uref{http://www.opengroup.org/susv3, Posix standard}.
14892 Some old code is written to be portable to K&R C, which predates any C
14893 standard. K&R C compilers are no longer of practical interest, though,
14894 and the rest of section assumes at least C89, the first C standard.
14896 Program portability is a huge topic, and this section can only briefly
14897 introduce common pitfalls. @xref{System Portability, , Portability
14898 between System Types, standards, @acronym{GNU} Coding Standards}, for
14902 * Varieties of Unportability:: How to make your programs unportable
14903 * Integer Overflow:: When integers get too large
14904 * Null Pointers:: Properties of null pointers
14905 * Buffer Overruns:: Subscript errors and the like
14906 * Volatile Objects:: @code{volatile} and signals
14907 * Floating Point Portability:: Portable floating-point arithmetic
14908 * Exiting Portably:: Exiting and the exit status
14911 @node Varieties of Unportability
14912 @section Varieties of Unportability
14913 @cindex portability
14915 Autoconf tests and ordinary programs often need to test what is allowed
14916 on a system, and therefore they may need to deliberately exceed the
14917 boundaries of what the standards allow, if only to see whether an
14918 optional feature is present. When you write such a program, you should
14919 keep in mind the difference between constraints, unspecified behavior,
14920 and undefined behavior.
14922 In C, a @dfn{constraint} is a rule that the compiler must enforce. An
14923 example constraint is that C programs must not declare a bit-field with
14924 negative width. Tests can therefore reliably assume that programs with
14925 negative-width bit-fields are rejected by a compiler that conforms
14928 @dfn{Unspecified behavior} is valid behavior, where the standard allows
14929 multiple possibilities. For example, the order of evaluation of
14930 function arguments is unspecified. Some unspecified behavior is
14931 @dfn{implementation-defined}, i.e., documented by the implementation,
14932 but since Autoconf tests cannot read the documentation they cannot
14933 distinguish between implementation-defined and other unspecified
14934 behavior. It is common for Autoconf tests to probe implementations to
14935 determine otherwise-unspecified behavior.
14937 @dfn{Undefined behavior} is invalid behavior, where the standard allows
14938 the implementation to do anything it pleases. For example,
14939 dereferencing a null pointer leads to undefined behavior. If possible,
14940 test programs should avoid undefined behavior, since a program with
14941 undefined behavior might succeed on a test that should fail.
14943 The above rules apply to programs that are intended to conform to the
14944 standard. However, strictly-conforming programs are quite rare, since
14945 the standards are so limiting. A major goal of Autoconf is to support
14946 programs that use implementation features not described by the standard,
14947 and it is fairly common for test programs to violate the above rules, if
14948 the programs work well enough in practice.
14950 @node Integer Overflow
14951 @section Integer Overflow
14952 @cindex overflow, arithmetic
14954 In C, signed integer overflow leads to undefined behavior. However,
14955 many programs and Autoconf tests assume that signed integer overflow after
14956 addition, subtraction, or multiplication silently
14957 wraps around modulo a power of two, using two's complement arithmetic,
14958 so long as you cast the resulting value
14959 to an integer type or store it into an integer variable. Such programs
14960 are portable to the vast majority of modern platforms. However, signed
14961 integer division is not always harmless: for example, on CPUs of the
14962 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
14963 which by default terminates the program. Worse, taking the remainder
14964 of these two values typically yields the same signal on these CPUs,
14965 even though the C standard requires @code{INT_MIN % -1} to yield zero
14966 because the expression does not overflow.
14968 @acronym{GCC} users might consider using the
14969 @option{-ftrapv} option if they are worried about porting their code to
14970 the rare platforms where signed integer overflow does not wrap around
14971 after addition, subtraction, or multiplication.
14973 Unsigned integer overflow reliably wraps around modulo the word size.
14974 This is guaranteed by the C standard and is portable in practice.
14976 @node Null Pointers
14977 @section Properties of Null Pointers
14978 @cindex null pointers
14980 Most modern hosts reliably fail when you attempt to dereference a null
14983 On almost all modern hosts, null pointers use an all-bits-zero internal
14984 representation, so you can reliably use @code{memset} with 0 to set all
14985 the pointers in an array to null values.
14987 If @code{p} is a null pointer to an object type, the C expression
14988 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
14989 the standard says that it has undefined behavior.
14991 @node Buffer Overruns
14992 @section Buffer Overruns and Subscript Errors
14993 @cindex buffer overruns
14995 Buffer overruns and subscript errors are the most common dangerous
14996 errors in C programs. They result in undefined behavior because storing
14997 outside an array typically modifies storage that is used by some other
14998 object, and most modern systems lack runtime checks to catch these
14999 errors. Programs should not rely on buffer overruns being caught.
15001 There is one exception to the usual rule that a portable program cannot
15002 address outside an array. In C, it is valid to compute the address just
15003 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
15004 so long as you do not dereference the resulting pointer. But it is not
15005 valid to compute the address just before an object, e.g., @code{&a[-1]};
15006 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
15007 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
15008 reliable in general, and it is usually easy enough to avoid the
15009 potential portability problem, e.g., by allocating an extra unused array
15010 element at the start or end.
15012 @uref{http://valgrind.org/, Valgrind} can catch many overruns.
15014 users might also consider using the @option{-fmudflap} option to catch
15017 Buffer overruns are usually caused by off-by-one errors, but there are
15018 more subtle ways to get them.
15020 Using @code{int} values to index into an array or compute array sizes
15021 causes problems on typical 64-bit hosts where an array index might
15022 be @math{2^31} or larger. Index values of type @code{size_t} avoid this
15023 problem, but cannot be negative. Index values of type @code{ptrdiff_t}
15024 are signed, and are wide enough in practice.
15026 If you add or multiply two numbers to calculate an array size, e.g.,
15027 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
15028 multiplication overflows.
15030 Many implementations of the @code{alloca} function silently misbehave
15031 and can generate buffer overflows if given sizes that are too large.
15032 The size limits are implementation dependent, but are at least 4000
15033 bytes on all platforms that we know about.
15035 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
15036 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
15037 portable code should not use them unless the inputs are known to be
15038 within certain limits. The time-related functions can overflow their
15039 buffers if given timestamps out of range (e.g., a year less than -999
15040 or greater than 9999). Time-related buffer overflows cannot happen with
15041 recent-enough versions of the @acronym{GNU} C library, but are possible
15043 implementations. The @code{gets} function is the worst, since it almost
15044 invariably overflows its buffer when presented with an input line larger
15047 @node Volatile Objects
15048 @section Volatile Objects
15049 @cindex volatile objects
15051 The keyword @code{volatile} is often misunderstood in portable code.
15052 Its use inhibits some memory-access optimizations, but programmers often
15053 wish that it had a different meaning than it actually does.
15055 @code{volatile} was designed for code that accesses special objects like
15056 memory-mapped device registers whose contents spontaneously change.
15057 Such code is inherently low-level, and it is difficult to specify
15058 portably what @code{volatile} means in these cases. The C standard
15059 says, ``What constitutes an access to an object that has
15060 volatile-qualified type is implementation-defined,'' so in theory each
15061 implementation is supposed to fill in the gap by documenting what
15062 @code{volatile} means for that implementation. In practice, though,
15063 this documentation is usually absent or incomplete.
15065 One area of confusion is the distinction between objects defined with
15066 volatile types, and volatile lvalues. From the C standard's point of
15067 view, an object defined with a volatile type has externally visible
15068 behavior. You can think of such objects as having little oscilloscope
15069 probes attached to them, so that the user can observe some properties of
15070 accesses to them, just as the user can observe data written to output
15071 files. However, the standard does not make it clear whether users can
15072 observe accesses by volatile lvalues to ordinary objects. For example:
15075 /* Declare and access a volatile object.
15076 Accesses to X are "visible" to users. */
15077 static int volatile x;
15080 /* Access two ordinary objects via a volatile lvalue.
15081 It's not clear whether accesses to *P are "visible". */
15083 int *z = malloc (sizeof (int));
15091 Programmers often wish that @code{volatile} meant ``Perform the memory
15092 access here and now, without merging several memory accesses, without
15093 changing the memory word size, and without reordering.'' But the C
15094 standard does not require this. For objects defined with a volatile
15095 type, accesses must be done before the next sequence point; but
15096 otherwise merging, reordering, and word-size change is allowed. Worse,
15097 it is not clear from the standard whether volatile lvalues provide more
15098 guarantees in general than nonvolatile lvalues, if the underlying
15099 objects are ordinary.
15101 Even when accessing objects defined with a volatile type,
15102 the C standard allows only
15103 extremely limited signal handlers: the behavior is undefined if a signal
15104 handler reads any nonlocal object, or writes to any nonlocal object
15105 whose type is not @code{sig_atomic_t volatile}, or calls any standard
15106 library function other than @code{abort}, @code{signal}, and (if C99)
15107 @code{_Exit}. Hence C compilers need not worry about a signal handler
15108 disturbing ordinary computation, unless the computation accesses a
15109 @code{sig_atomic_t volatile} lvalue that is not a local variable.
15110 (There is an obscure exception for accesses via a pointer to a volatile
15111 character, since it may point into part of a @code{sig_atomic_t
15112 volatile} object.) Posix
15113 adds to the list of library functions callable from a portable signal
15114 handler, but otherwise is like the C standard in this area.
15116 Some C implementations allow memory-access optimizations within each
15117 translation unit, such that actual behavior agrees with the behavior
15118 required by the standard only when calling a function in some other
15119 translation unit, and a signal handler acts like it was called from a
15120 different translation unit. The C standard hints that in these
15121 implementations, objects referred to by signal handlers ``would require
15122 explicit specification of @code{volatile} storage, as well as other
15123 implementation-defined restrictions.'' But unfortunately even for this
15124 special case these other restrictions are often not documented well.
15125 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
15126 @acronym{GNU} Compiler Collection (@acronym{GCC})}, for some
15127 restrictions imposed by @acronym{GCC}. @xref{Defining Handlers, ,
15128 Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
15129 restrictions imposed by the @acronym{GNU} C library. Restrictions
15130 differ on other platforms.
15132 If possible, it is best to use a signal handler that fits within the
15133 limits imposed by the C and Posix standards.
15135 If this is not practical, you can try the following rules of thumb. A
15136 signal handler should access only volatile lvalues, preferably lvalues
15137 that refer to objects defined with a volatile type, and should not
15138 assume that the accessed objects have an internally consistent state
15139 if they are larger than a machine word. Furthermore, installers
15140 should employ compilers and compiler options that are commonly used
15141 for building operating system kernels, because kernels often need more
15142 from @code{volatile} than the C Standard requires, and installers who
15143 compile an application in a similar environment can sometimes benefit
15144 from the extra constraints imposed by kernels on compilers.
15145 Admittedly we are handwaving somewhat here, as there are few
15146 guarantees in this area; the rules of thumb may help to fix some bugs
15147 but there is a good chance that they will not fix them all.
15149 For @code{volatile}, C++ has the same problems that C does.
15150 Multithreaded applications have even more problems with @code{volatile},
15151 but they are beyond the scope of this section.
15153 The bottom line is that using @code{volatile} typically hurts
15154 performance but should not hurt correctness. In some cases its use
15155 does help correctness, but these cases are often so poorly understood
15156 that all too often adding @code{volatile} to a data structure merely
15157 alleviates some symptoms of a bug while not fixing the bug in general.
15159 @node Floating Point Portability
15160 @section Floating Point Portability
15161 @cindex floating point
15163 Almost all modern systems use IEEE-754 floating point, and it is safe to
15164 assume IEEE-754 in most portable code these days. For more information,
15165 please see David Goldberg's classic paper
15166 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
15167 Scientist Should Know About Floating-Point Arithmetic}.
15169 @node Exiting Portably
15170 @section Exiting Portably
15171 @cindex exiting portably
15173 A C or C++ program can exit with status @var{N} by returning
15174 @var{N} from the @code{main} function. Portable programs are supposed
15175 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
15176 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
15177 fail by exiting with status 1, and test programs that assume Posix can
15178 fail by exiting with status values from 1 through 255. Programs on
15179 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
15180 status when @code{main} returned nonzero, but ancient systems like these
15181 are no longer of practical concern.
15183 A program can also exit with status @var{N} by passing @var{N} to the
15184 @code{exit} function, and a program can fail by calling the @code{abort}
15185 function. If a program is specialized to just some platforms, it can fail
15186 by calling functions specific to those platforms, e.g., @code{_exit}
15187 (Posix) and @code{_Exit} (C99). However, like other functions, an exit
15188 function should be declared, typically by including a header. For
15189 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
15190 either directly or via the default includes (@pxref{Default Includes}).
15192 A program can fail due to undefined behavior such as dereferencing a null
15193 pointer, but this is not recommended as undefined behavior allows an
15194 implementation to do whatever it pleases and this includes exiting
15198 @c ================================================== Manual Configuration
15200 @node Manual Configuration
15201 @chapter Manual Configuration
15203 A few kinds of features can't be guessed automatically by running test
15204 programs. For example, the details of the object-file format, or
15205 special options that need to be passed to the compiler or linker. You
15206 can check for such features using ad-hoc means, such as having
15207 @command{configure} check the output of the @code{uname} program, or
15208 looking for libraries that are unique to particular systems. However,
15209 Autoconf provides a uniform method for handling unguessable features.
15212 * Specifying Names:: Specifying the system type
15213 * Canonicalizing:: Getting the canonical system type
15214 * Using System Type:: What to do with the system type
15217 @node Specifying Names
15218 @section Specifying the System Type
15219 @cindex System type
15221 Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated
15222 @command{configure} scripts can make decisions based on a canonical name
15223 for the system type, which has the form:
15224 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
15225 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
15227 @command{configure} can usually guess the canonical name for the type of
15228 system it's running on. To do so it runs a script called
15229 @command{config.guess}, which infers the name using the @code{uname}
15230 command or symbols predefined by the C preprocessor.
15232 Alternately, the user can specify the system type with command line
15233 arguments to @command{configure}. Doing so is necessary when
15234 cross-compiling. In the most complex case of cross-compiling, three
15235 system types are involved. The options to specify them are:
15238 @item --build=@var{build-type}
15239 the type of system on which the package is being configured and
15240 compiled. It defaults to the result of running @command{config.guess}.
15242 @item --host=@var{host-type}
15243 the type of system on which the package runs. By default it is the
15244 same as the build machine. Specifying it enables the cross-compilation
15247 @item --target=@var{target-type}
15248 the type of system for which any compiler tools in the package
15249 produce code (rarely needed). By default, it is the same as host.
15252 If you mean to override the result of @command{config.guess}, use
15253 @option{--build}, not @option{--host}, since the latter enables
15254 cross-compilation. For historical reasons, passing @option{--host} also
15255 changes the build type. Therefore, whenever you specify @option{--host},
15256 be sure to specify @option{--build} too; this will be fixed in the
15257 future. So, to enter cross-compilation mode, use a command like this
15260 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
15264 Note that if you do not specify @option{--host}, @command{configure}
15265 fails if it can't run the code generated by the specified compiler. For
15266 example, configuring as follows fails:
15269 ./configure CC=m68k-coff-gcc
15272 In the future, when cross-compiling Autoconf will @emph{not}
15273 accept tools (compilers, linkers, assemblers) whose name is not
15274 prefixed with the host type. The only case when this may be
15275 useful is when you really are not cross-compiling, but only
15276 building for a least-common-denominator architecture: an example
15277 is building for @code{i386-pc-linux-gnu} while running on an
15278 @code{i686-pc-linux-gnu} architecture. In this case, some particular
15279 pairs might be similar enough to let you get away with the system
15280 compilers, but in general the compiler might make bogus assumptions
15281 on the host: if you know what you are doing, please create symbolic
15282 links from the host compiler to the build compiler.
15284 @cindex @command{config.sub}
15285 @command{configure} recognizes short aliases for many system types; for
15286 example, @samp{decstation} can be used instead of
15287 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
15288 @command{config.sub} to canonicalize system type aliases.
15290 This section deliberately omits the description of the obsolete
15291 interface; see @ref{Hosts and Cross-Compilation}.
15294 @node Canonicalizing
15295 @section Getting the Canonical System Type
15296 @cindex System type
15297 @cindex Canonical system type
15299 The following macros make the system type available to @command{configure}
15302 @ovindex build_alias
15303 @ovindex host_alias
15304 @ovindex target_alias
15306 The variables @samp{build_alias}, @samp{host_alias}, and
15307 @samp{target_alias} are always exactly the arguments of @option{--build},
15308 @option{--host}, and @option{--target}; in particular, they are left empty
15309 if the user did not use them, even if the corresponding
15310 @code{AC_CANONICAL} macro was run. Any configure script may use these
15311 variables anywhere. These are the variables that should be used when in
15312 interaction with the user.
15314 If you need to recognize some special environments based on their system
15315 type, run the following macros to get canonical system names. These
15316 variables are not set before the macro call.
15318 If you use these macros, you must distribute @command{config.guess} and
15319 @command{config.sub} along with your source code. @xref{Output}, for
15320 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
15321 to control in which directory @command{configure} looks for those scripts.
15324 @defmac AC_CANONICAL_BUILD
15325 @acindex{CANONICAL_BUILD}
15328 @ovindex build_vendor
15330 Compute the canonical build-system type variable, @code{build}, and its
15331 three individual parts @code{build_cpu}, @code{build_vendor}, and
15334 If @option{--build} was specified, then @code{build} is the
15335 canonicalization of @code{build_alias} by @command{config.sub},
15336 otherwise it is determined by the shell script @command{config.guess}.
15339 @defmac AC_CANONICAL_HOST
15340 @acindex{CANONICAL_HOST}
15343 @ovindex host_vendor
15345 Compute the canonical host-system type variable, @code{host}, and its
15346 three individual parts @code{host_cpu}, @code{host_vendor}, and
15349 If @option{--host} was specified, then @code{host} is the
15350 canonicalization of @code{host_alias} by @command{config.sub},
15351 otherwise it defaults to @code{build}.
15354 @defmac AC_CANONICAL_TARGET
15355 @acindex{CANONICAL_TARGET}
15357 @ovindex target_cpu
15358 @ovindex target_vendor
15360 Compute the canonical target-system type variable, @code{target}, and its
15361 three individual parts @code{target_cpu}, @code{target_vendor}, and
15364 If @option{--target} was specified, then @code{target} is the
15365 canonicalization of @code{target_alias} by @command{config.sub},
15366 otherwise it defaults to @code{host}.
15369 Note that there can be artifacts due to the backward compatibility
15370 code. See @xref{Hosts and Cross-Compilation}, for more.
15372 @node Using System Type
15373 @section Using the System Type
15375 In @file{configure.ac} the system type is generally used by one or more
15376 @code{case} statements to select system-specifics. Shell wildcards can
15377 be used to match a group of system types.
15379 For example, an extra assembler code object file could be chosen, giving
15380 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
15381 following would be used in a makefile to add the object to a
15382 program or library.
15386 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
15387 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
15390 AC_SUBST([CYCLE_OBJ])
15393 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
15394 to select variant source files, for example optimized code for some
15395 CPUs. The configured CPU type doesn't always indicate exact CPU types,
15396 so some runtime capability checks may be necessary too.
15400 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
15401 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
15402 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
15406 The host system type can also be used to find cross-compilation tools
15407 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
15409 The above examples all show @samp{$host}, since this is where the code
15410 is going to run. Only rarely is it necessary to test @samp{$build}
15411 (which is where the build is being done).
15413 Whenever you're tempted to use @samp{$host} it's worth considering
15414 whether some sort of probe would be better. New system types come along
15415 periodically or previously missing features are added. Well-written
15416 probes can adapt themselves to such things, but hard-coded lists of
15417 names can't. Here are some guidelines,
15421 Availability of libraries and library functions should always be checked
15424 Variant behavior of system calls is best identified with runtime tests
15425 if possible, but bug workarounds or obscure difficulties might have to
15426 be driven from @samp{$host}.
15428 Assembler code is inevitably highly CPU-specific and is best selected
15429 according to @samp{$host_cpu}.
15431 Assembler variations like underscore prefix on globals or ELF versus
15432 COFF type directives are however best determined by probing, perhaps
15433 even examining the compiler output.
15436 @samp{$target} is for use by a package creating a compiler or similar.
15437 For ordinary packages it's meaningless and should not be used. It
15438 indicates what the created compiler should generate code for, if it can
15439 cross-compile. @samp{$target} generally selects various hard-coded CPU
15440 and system conventions, since usually the compiler or tools under
15441 construction themselves determine how the target works.
15444 @c ===================================================== Site Configuration.
15446 @node Site Configuration
15447 @chapter Site Configuration
15449 @command{configure} scripts support several kinds of local configuration
15450 decisions. There are ways for users to specify where external software
15451 packages are, include or exclude optional features, install programs
15452 under modified names, and set default values for @command{configure}
15456 * Help Formatting:: Customizing @samp{configure --help}
15457 * External Software:: Working with other optional software
15458 * Package Options:: Selecting optional features
15459 * Pretty Help Strings:: Formatting help string
15460 * Option Checking:: Controlling checking of @command{configure} options
15461 * Site Details:: Configuring site details
15462 * Transforming Names:: Changing program names when installing
15463 * Site Defaults:: Giving @command{configure} local defaults
15466 @node Help Formatting
15467 @section Controlling Help Output
15469 Users consult @samp{configure --help} to learn of configuration
15470 decisions specific to your package. By default, @command{configure}
15471 breaks this output into sections for each type of option; within each
15472 section, help strings appear in the order @file{configure.ac} defines
15478 --enable-bar include bar
15485 @defmac AC_PRESERVE_HELP_ORDER
15486 @acindex{PRESERVE_HELP_ORDER}
15488 Request an alternate @option{--help} format, in which options of all
15489 types appear together, in the order defined. Call this macro before any
15490 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
15493 Optional Features and Packages:
15495 --enable-bar include bar
15501 @node External Software
15502 @section Working With External Software
15503 @cindex External software
15505 Some packages require, or can optionally use, other software packages
15506 that are already installed. The user can give @command{configure}
15507 command line options to specify which such external software to use.
15508 The options have one of these forms:
15510 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15513 --with-@var{package}[=@var{arg}]
15514 --without-@var{package}
15517 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
15518 instead of some other linker. @option{--with-x} means work with The X
15521 The user can give an argument by following the package name with
15522 @samp{=} and the argument. Giving an argument of @samp{no} is for
15523 packages that are used by default; it says to @emph{not} use the
15524 package. An argument that is neither @samp{yes} nor @samp{no} could
15525 include a name or number of a version of the other package, to specify
15526 more precisely which other package this program is supposed to work
15527 with. If no argument is given, it defaults to @samp{yes}.
15528 @option{--without-@var{package}} is equivalent to
15529 @option{--with-@var{package}=no}.
15531 Normally @command{configure} scripts complain about
15532 @option{--with-@var{package}} options that they do not support.
15533 @xref{Option Checking}, for details, and for how to override the
15536 For each external software package that may be used, @file{configure.ac}
15537 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
15538 user asked to use it. Whether each package is used or not by default,
15539 and which arguments are valid, is up to you.
15541 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15543 If the user gave @command{configure} the option @option{--with-@var{package}}
15544 or @option{--without-@var{package}}, run shell commands
15545 @var{action-if-given}. If neither option was given, run shell commands
15546 @var{action-if-not-given}. The name @var{package} indicates another
15547 software package that this program should work with. It should consist
15548 only of alphanumeric characters, dashes, and dots.
15550 The option's argument is available to the shell commands
15551 @var{action-if-given} in the shell variable @code{withval}, which is
15552 actually just the value of the shell variable @code{with_@var{package}},
15553 with any non-alphanumeric characters changed into @samp{_}. You may use that
15554 variable instead, if you wish.
15556 The argument @var{help-string} is a description of the option that
15559 --with-readline support fancy command line editing
15563 @var{help-string} may be more than one line long, if more detail is
15564 needed. Just make sure the columns line up in @samp{configure
15565 --help}. Avoid tabs in the help string. You'll need to enclose the
15566 help string in @samp{[} and @samp{]} in order to produce the leading
15569 You should format your @var{help-string} with the macro
15570 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15572 The following example shows how to use the @code{AC_ARG_WITH} macro in
15573 a common situation. You want to let the user decide whether to enable
15574 support for an external library (e.g., the readline library); if the user
15575 specified neither @option{--with-readline} nor @option{--without-readline},
15576 you want to enable support for readline only if the library is available
15579 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15581 AC_ARG_WITH([readline],
15582 [AS_HELP_STRING([--with-readline],
15583 [support fancy command line editing @@<:@@default=check@@:>@@])],
15585 [with_readline=check])
15588 AS_IF([test "x$with_readline" != xno],
15589 [AC_CHECK_LIB([readline], [main],
15590 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15591 AC_DEFINE([HAVE_LIBREADLINE], [1],
15592 [Define if you have libreadline])
15594 [if test "x$with_readline" != xcheck; then
15596 [--with-readline was given, but test for readline failed])
15601 The next example shows how to use @code{AC_ARG_WITH} to give the user the
15602 possibility to enable support for the readline library, in case it is still
15603 experimental and not well tested, and is therefore disabled by default.
15605 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15607 AC_ARG_WITH([readline],
15608 [AS_HELP_STRING([--with-readline],
15609 [enable experimental support for readline])],
15611 [with_readline=no])
15614 AS_IF([test "x$with_readline" != xno],
15615 [AC_CHECK_LIB([readline], [main],
15616 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15617 AC_DEFINE([HAVE_LIBREADLINE], [1],
15618 [Define if you have libreadline])
15621 [--with-readline was given, but test for readline failed])],
15625 The last example shows how to use @code{AC_ARG_WITH} to give the user the
15626 possibility to disable support for the readline library, given that it is
15627 an important feature and that it should be enabled by default.
15629 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15631 AC_ARG_WITH([readline],
15632 [AS_HELP_STRING([--without-readline],
15633 [disable support for readline])],
15635 [with_readline=yes])
15638 AS_IF([test "x$with_readline" != xno],
15639 [AC_CHECK_LIB([readline], [main],
15640 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15641 AC_DEFINE([HAVE_LIBREADLINE], [1],
15642 [Define if you have libreadline])
15645 [readline test failed (--without-readline to disable)])],
15649 These three examples can be easily adapted to the case where
15650 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
15651 @ref{Package Options}).
15654 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
15656 This is an obsolete version of @code{AC_ARG_WITH} that does not
15657 support providing a help string.
15660 @node Package Options
15661 @section Choosing Package Options
15662 @cindex Package options
15663 @cindex Options, package
15665 If a software package has optional compile-time features, the user can
15666 give @command{configure} command line options to specify whether to
15667 compile them. The options have one of these forms:
15669 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15672 --enable-@var{feature}[=@var{arg}]
15673 --disable-@var{feature}
15676 These options allow users to choose which optional features to build and
15677 install. @option{--enable-@var{feature}} options should never make a
15678 feature behave differently or cause one feature to replace another.
15679 They should only cause parts of the program to be built rather than left
15682 The user can give an argument by following the feature name with
15683 @samp{=} and the argument. Giving an argument of @samp{no} requests
15684 that the feature @emph{not} be made available. A feature with an
15685 argument looks like @option{--enable-debug=stabs}. If no argument is
15686 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
15687 equivalent to @option{--enable-@var{feature}=no}.
15689 Normally @command{configure} scripts complain about
15690 @option{--enable-@var{package}} options that they do not support.
15691 @xref{Option Checking}, for details, and for how to override the
15694 For each optional feature, @file{configure.ac} should call
15695 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
15696 to include it. Whether each feature is included or not by default, and
15697 which arguments are valid, is up to you.
15699 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15700 @acindex{ARG_ENABLE}
15701 If the user gave @command{configure} the option
15702 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
15703 shell commands @var{action-if-given}. If neither option was given, run
15704 shell commands @var{action-if-not-given}. The name @var{feature}
15705 indicates an optional user-level facility. It should consist only of
15706 alphanumeric characters, dashes, and dots.
15708 The option's argument is available to the shell commands
15709 @var{action-if-given} in the shell variable @code{enableval}, which is
15710 actually just the value of the shell variable
15711 @code{enable_@var{feature}}, with any non-alphanumeric characters changed into
15712 @samp{_}. You may use that variable instead, if you wish. The
15713 @var{help-string} argument is like that of @code{AC_ARG_WITH}
15714 (@pxref{External Software}).
15716 You should format your @var{help-string} with the macro
15717 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15719 See the examples suggested with the definition of @code{AC_ARG_WITH}
15720 (@pxref{External Software}) to get an idea of possible applications of
15721 @code{AC_ARG_ENABLE}.
15724 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
15726 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
15727 support providing a help string.
15731 @node Pretty Help Strings
15732 @section Making Your Help Strings Look Pretty
15733 @cindex Help strings
15735 Properly formatting the @samp{help strings} which are used in
15736 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
15737 (@pxref{Package Options}) can be challenging. Specifically, you want
15738 your own @samp{help strings} to line up in the appropriate columns of
15739 @samp{configure --help} just like the standard Autoconf @samp{help
15740 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
15742 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
15743 @acindex{HELP_STRING}
15745 Expands into an help string that looks pretty when the user executes
15746 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
15747 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
15748 Options}). The following example makes this clearer.
15752 [AS_HELP_STRING([--with-foo],
15753 [use foo (default is no)])],
15754 [use_foo=$withval],
15758 The second argument of @code{AS_HELP_STRING} is
15759 not a literal, and should not be double quoted.
15760 @xref{Autoconf Language}, for a more detailed explanation.
15761 Then the last few lines of @samp{configure --help} appear like
15765 --enable and --with options recognized:
15766 --with-foo use foo (default is no)
15769 The @code{AS_HELP_STRING} macro is particularly helpful when the
15770 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
15771 arguments, as shown in the following example.
15774 AC_DEFUN([MY_ARG_WITH],
15776 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
15777 [use_[]$1=$withval],
15783 @node Option Checking
15784 @section Controlling Checking of @command{configure} Options
15785 @cindex Options, Package
15787 The @command{configure} script checks its command-line options against a
15788 list of known options, like @option{--help} or @option{--config-cache}.
15789 An unknown option ordinarily indicates a mistake by the user and
15790 @command{configure} halts with an error. However, by default unknown
15791 @option{--with-@var{package}} and @option{--enable-@var{feature}}
15792 options elicit only a warning, to support configuring entire source
15795 Source trees often contain multiple packages with a top-level
15796 @command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
15797 (@pxref{Subdirectories}). Because the packages generally support
15798 different @option{--with-@var{package}} and
15799 @option{--enable-@var{feature}} options, the @acronym{GNU} Coding
15800 Standards say they must accept unrecognized options without halting.
15801 Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
15802 automatically disables the warnings.
15804 This default behavior may be modified in two ways. First, the installer
15805 can invoke @command{configure} with the
15806 @option{--disable-option-checking} or
15807 @option{--enable-option-checking=fatal} options to disable these
15808 warnings or turn them into fatal errors, respectively. Second, the
15809 maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
15811 @defmac AC_DISABLE_OPTION_CHECKING
15812 @acindex{DISABLE_OPTION_CHECKING}
15814 By default, disable warnings for unrecognized
15815 @option{--with-@var{package}} or @option{--enable-@var{feature}}
15816 options. This is implied by @code{AC_CONFIG_SUBDIRS}.
15818 The installer can override this behavior by passing
15819 @option{--enable-option-checking} (enable warnings) or
15820 @option{--enable-option-checking=fatal} (enable errors) to
15821 @command{configure}.
15826 @section Configuring Site Details
15827 @cindex Site details
15829 Some software packages require complex site-specific information. Some
15830 examples are host names to use for certain services, company names, and
15831 email addresses to contact. Since some configuration scripts generated
15832 by Metaconfig ask for such information interactively, people sometimes
15833 wonder how to get that information in Autoconf-generated configuration
15834 scripts, which aren't interactive.
15836 Such site configuration information should be put in a file that is
15837 edited @emph{only by users}, not by programs. The location of the file
15838 can either be based on the @code{prefix} variable, or be a standard
15839 location such as the user's home directory. It could even be specified
15840 by an environment variable. The programs should examine that file at
15841 runtime, rather than at compile time. Runtime configuration is more
15842 convenient for users and makes the configuration process simpler than
15843 getting the information while configuring. @xref{Directory Variables, ,
15844 Variables for Installation Directories, standards, @acronym{GNU} Coding
15845 Standards}, for more information on where to put data files.
15847 @node Transforming Names
15848 @section Transforming Program Names When Installing
15849 @cindex Transforming program names
15850 @cindex Program names, transforming
15852 Autoconf supports changing the names of programs when installing them.
15853 In order to use these transformations, @file{configure.ac} must call the
15854 macro @code{AC_ARG_PROGRAM}.
15856 @defmac AC_ARG_PROGRAM
15857 @acindex{ARG_PROGRAM}
15858 @ovindex program_transform_name
15859 Place in output variable @code{program_transform_name} a sequence of
15860 @code{sed} commands for changing the names of installed programs.
15862 If any of the options described below are given to @command{configure},
15863 program names are transformed accordingly. Otherwise, if
15864 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
15865 is given, the target type followed by a dash is used as a prefix.
15866 Otherwise, no program name transformation is done.
15870 * Transformation Options:: @command{configure} options to transform names
15871 * Transformation Examples:: Sample uses of transforming names
15872 * Transformation Rules:: Makefile uses of transforming names
15875 @node Transformation Options
15876 @subsection Transformation Options
15878 You can specify name transformations by giving @command{configure} these
15879 command line options:
15882 @item --program-prefix=@var{prefix}
15883 prepend @var{prefix} to the names;
15885 @item --program-suffix=@var{suffix}
15886 append @var{suffix} to the names;
15888 @item --program-transform-name=@var{expression}
15889 perform @code{sed} substitution @var{expression} on the names.
15892 @node Transformation Examples
15893 @subsection Transformation Examples
15895 These transformations are useful with programs that can be part of a
15896 cross-compilation development environment. For example, a
15897 cross-assembler running on a Sun 4 configured with
15898 @option{--target=i960-vxworks} is normally installed as
15899 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
15900 with a native Sun 4 assembler.
15902 You can force a program name to begin with @file{g}, if you don't want
15903 @acronym{GNU} programs installed on your system to shadow other programs with
15904 the same name. For example, if you configure @acronym{GNU} @code{diff} with
15905 @option{--program-prefix=g}, then when you run @samp{make install} it is
15906 installed as @file{/usr/local/bin/gdiff}.
15908 As a more sophisticated example, you could use
15911 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
15915 to prepend @samp{g} to most of the program names in a source tree,
15916 excepting those like @code{gdb} that already have one and those like
15917 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
15918 assuming that you have a source tree containing those programs that is
15919 set up to use this feature.)
15921 One way to install multiple versions of some programs simultaneously is
15922 to append a version number to the name of one or both. For example, if
15923 you want to keep Autoconf version 1 around for awhile, you can configure
15924 Autoconf version 2 using @option{--program-suffix=2} to install the
15925 programs as @file{/usr/local/bin/autoconf2},
15926 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
15927 that only the binaries are renamed, therefore you'd have problems with
15928 the library files which might overlap.
15930 @node Transformation Rules
15931 @subsection Transformation Rules
15933 Here is how to use the variable @code{program_transform_name} in a
15934 @file{Makefile.in}:
15937 PROGRAMS = cp ls rm
15938 transform = @@program_transform_name@@
15940 for p in $(PROGRAMS); do \
15941 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
15942 sed '$(transform)'`; \
15946 for p in $(PROGRAMS); do \
15947 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
15951 It is guaranteed that @code{program_transform_name} is never empty, and
15952 that there are no useless separators. Therefore you may safely embed
15953 @code{program_transform_name} within a sed program using @samp{;}:
15956 transform = @@program_transform_name@@
15957 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
15960 Whether to do the transformations on documentation files (Texinfo or
15961 @code{man}) is a tricky question; there seems to be no perfect answer,
15962 due to the several reasons for name transforming. Documentation is not
15963 usually particular to a specific architecture, and Texinfo files do not
15964 conflict with system documentation. But they might conflict with
15965 earlier versions of the same files, and @code{man} pages sometimes do
15966 conflict with system documentation. As a compromise, it is probably
15967 best to do name transformations on @code{man} pages but not on Texinfo
15970 @node Site Defaults
15971 @section Setting Site Defaults
15972 @cindex Site defaults
15974 Autoconf-generated @command{configure} scripts allow your site to provide
15975 default values for some configuration values. You do this by creating
15976 site- and system-wide initialization files.
15978 @evindex CONFIG_SITE
15979 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
15980 uses its value as the name of a shell script to read. Otherwise, it
15981 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
15982 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
15983 settings in machine-specific files override those in machine-independent
15984 ones in case of conflict.
15986 Site files can be arbitrary shell scripts, but only certain kinds of
15987 code are really appropriate to be in them. Because @command{configure}
15988 reads any cache file after it has read any site files, a site file can
15989 define a default cache file to be shared between all Autoconf-generated
15990 @command{configure} scripts run on that system (@pxref{Cache Files}). If
15991 you set a default cache file in a site file, it is a good idea to also
15992 set the output variable @code{CC} in that site file, because the cache
15993 file is only valid for a particular compiler, but many systems have
15996 You can examine or override the value set by a command line option to
15997 @command{configure} in a site file; options set shell variables that have
15998 the same names as the options, with any dashes turned into underscores.
15999 The exceptions are that @option{--without-} and @option{--disable-} options
16000 are like giving the corresponding @option{--with-} or @option{--enable-}
16001 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
16002 sets the variable @code{cache_file} to the value @samp{localcache};
16003 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
16004 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
16005 variable @code{prefix} to the value @samp{/usr}; etc.
16007 Site files are also good places to set default values for other output
16008 variables, such as @code{CFLAGS}, if you need to give them non-default
16009 values: anything you would normally do, repetitively, on the command
16010 line. If you use non-default values for @var{prefix} or
16011 @var{exec_prefix} (wherever you locate the site file), you can set them
16012 in the site file if you specify it with the @code{CONFIG_SITE}
16013 environment variable.
16015 You can set some cache values in the site file itself. Doing this is
16016 useful if you are cross-compiling, where it is impossible to check features
16017 that require running a test program. You could ``prime the cache'' by
16018 setting those values correctly for that system in
16019 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
16020 variables you need to set, look for shell variables with @samp{_cv_} in
16021 their names in the affected @command{configure} scripts, or in the Autoconf
16022 M4 source code for those macros.
16024 The cache file is careful to not override any variables set in the site
16025 files. Similarly, you should not override command-line options in the
16026 site files. Your code should check that variables such as @code{prefix}
16027 and @code{cache_file} have their default values (as set near the top of
16028 @command{configure}) before changing them.
16030 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
16031 command @samp{configure --prefix=/usr/share/local/gnu} would read this
16032 file (if @code{CONFIG_SITE} is not set to a different file).
16035 # config.site for configure
16037 # Change some defaults.
16038 test "$prefix" = NONE && prefix=/usr/share/local/gnu
16039 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
16040 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
16041 test "$localstatedir" = '$prefix/var' && localstatedir=/var
16043 # Give Autoconf 2.x generated configure scripts a shared default
16044 # cache file for feature test results, architecture-specific.
16045 if test "$cache_file" = /dev/null; then
16046 cache_file="$prefix/var/config.cache"
16047 # A cache file is only valid for one C compiler.
16053 @c ============================================== Running configure Scripts.
16055 @node Running configure Scripts
16056 @chapter Running @command{configure} Scripts
16057 @cindex @command{configure}
16059 Below are instructions on how to configure a package that uses a
16060 @command{configure} script, suitable for inclusion as an @file{INSTALL}
16061 file in the package. A plain-text version of @file{INSTALL} which you
16062 may use comes with Autoconf.
16065 * Basic Installation:: Instructions for typical cases
16066 * Compilers and Options:: Selecting compilers and optimization
16067 * Multiple Architectures:: Compiling for multiple architectures at once
16068 * Installation Names:: Installing in different directories
16069 * Optional Features:: Selecting optional features
16070 * System Type:: Specifying the system type
16071 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
16072 * Defining Variables:: Specifying the compiler etc.
16073 * configure Invocation:: Changing how @command{configure} runs
16077 @include install.texi
16080 @c ============================================== config.status Invocation
16082 @node config.status Invocation
16083 @chapter config.status Invocation
16084 @cindex @command{config.status}
16086 The @command{configure} script creates a file named @file{config.status},
16087 which actually configures, @dfn{instantiates}, the template files. It
16088 also records the configuration options that were specified when the
16089 package was last configured in case reconfiguring is needed.
16093 ./config.status @var{option}@dots{} [@var{file}@dots{}]
16096 It configures the @var{files}; if none are specified, all the templates
16097 are instantiated. The files must be specified without their
16098 dependencies, as in
16101 ./config.status foobar
16108 ./config.status foobar:foo.in:bar.in
16111 The supported options are:
16116 Print a summary of the command line options, the list of the template
16121 Print the version number of Autoconf and the configuration settings,
16127 Do not print progress messages.
16131 Don't remove the temporary files.
16133 @item --file=@var{file}[:@var{template}]
16134 Require that @var{file} be instantiated as if
16135 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
16136 @var{file} and @var{template} may be @samp{-} in which case the standard
16137 output and/or standard input, respectively, is used. If a
16138 @var{template} file name is relative, it is first looked for in the build
16139 tree, and then in the source tree. @xref{Configuration Actions}, for
16142 This option and the following ones provide one way for separately
16143 distributed packages to share the values computed by @command{configure}.
16144 Doing so can be useful if some of the packages need a superset of the
16145 features that one of them, perhaps a common library, does. These
16146 options allow a @file{config.status} file to create files other than the
16147 ones that its @file{configure.ac} specifies, so it can be used for a
16150 @item --header=@var{file}[:@var{template}]
16151 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
16154 Ask @file{config.status} to update itself and exit (no instantiation).
16155 This option is useful if you change @command{configure}, so that the
16156 results of some tests might be different from the previous run. The
16157 @option{--recheck} option reruns @command{configure} with the same arguments
16158 you used before, plus the @option{--no-create} option, which prevents
16159 @command{configure} from running @file{config.status} and creating
16160 @file{Makefile} and other files, and the @option{--no-recursion} option,
16161 which prevents @command{configure} from running other @command{configure}
16162 scripts in subdirectories. (This is so other Make rules can
16163 run @file{config.status} when it changes; @pxref{Automatic Remaking},
16167 @file{config.status} checks several optional environment variables that
16168 can alter its behavior:
16170 @defvar CONFIG_SHELL
16171 @evindex CONFIG_SHELL
16172 The shell with which to run @command{configure} for the @option{--recheck}
16173 option. It must be Bourne-compatible. The default is a shell that
16174 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
16175 Invoking @command{configure} by hand bypasses this setting, so you may
16176 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
16177 to insure that the same shell is used everywhere. The absolute name of the
16178 shell should be passed.
16181 @defvar CONFIG_STATUS
16182 @evindex CONFIG_STATUS
16183 The file name to use for the shell script that records the
16184 configuration. The default is @file{./config.status}. This variable is
16185 useful when one package uses parts of another and the @command{configure}
16186 scripts shouldn't be merged because they are maintained separately.
16189 You can use @file{./config.status} in your makefiles. For example, in
16190 the dependencies given above (@pxref{Automatic Remaking}),
16191 @file{config.status} is run twice when @file{configure.ac} has changed.
16192 If that bothers you, you can make each run only regenerate the files for
16197 stamp-h: config.h.in config.status
16198 ./config.status config.h
16201 Makefile: Makefile.in config.status
16202 ./config.status Makefile
16206 The calling convention of @file{config.status} has changed; see
16207 @ref{Obsolete config.status Use}, for details.
16210 @c =================================================== Obsolete Constructs
16212 @node Obsolete Constructs
16213 @chapter Obsolete Constructs
16214 @cindex Obsolete constructs
16216 Autoconf changes, and throughout the years some constructs have been
16217 obsoleted. Most of the changes involve the macros, but in some cases
16218 the tools themselves, or even some concepts, are now considered
16221 You may completely skip this chapter if you are new to Autoconf. Its
16222 intention is mainly to help maintainers updating their packages by
16223 understanding how to move to more modern constructs.
16226 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
16227 * acconfig Header:: Additional entries in @file{config.h.in}
16228 * autoupdate Invocation:: Automatic update of @file{configure.ac}
16229 * Obsolete Macros:: Backward compatibility macros
16230 * Autoconf 1:: Tips for upgrading your files
16231 * Autoconf 2.13:: Some fresher tips
16234 @node Obsolete config.status Use
16235 @section Obsolete @file{config.status} Invocation
16237 @file{config.status} now supports arguments to specify the files to
16238 instantiate; see @ref{config.status Invocation}, for more details.
16239 Before, environment variables had to be used.
16241 @defvar CONFIG_COMMANDS
16242 @evindex CONFIG_COMMANDS
16243 The tags of the commands to execute. The default is the arguments given
16244 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
16245 @file{configure.ac}.
16248 @defvar CONFIG_FILES
16249 @evindex CONFIG_FILES
16250 The files in which to perform @samp{@@@var{variable}@@} substitutions.
16251 The default is the arguments given to @code{AC_OUTPUT} and
16252 @code{AC_CONFIG_FILES} in @file{configure.ac}.
16255 @defvar CONFIG_HEADERS
16256 @evindex CONFIG_HEADERS
16257 The files in which to substitute C @code{#define} statements. The
16258 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
16259 macro was not called, @file{config.status} ignores this variable.
16262 @defvar CONFIG_LINKS
16263 @evindex CONFIG_LINKS
16264 The symbolic links to establish. The default is the arguments given to
16265 @code{AC_CONFIG_LINKS}; if that macro was not called,
16266 @file{config.status} ignores this variable.
16269 In @ref{config.status Invocation}, using this old interface, the example
16275 stamp-h: config.h.in config.status
16276 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
16277 CONFIG_HEADERS=config.h ./config.status
16280 Makefile: Makefile.in config.status
16281 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
16282 CONFIG_FILES=Makefile ./config.status
16287 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
16288 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
16289 for @code{CONFIG_COMMANDS}, etc.)
16292 @node acconfig Header
16293 @section @file{acconfig.h}
16295 @cindex @file{acconfig.h}
16296 @cindex @file{config.h.top}
16297 @cindex @file{config.h.bot}
16299 In order to produce @file{config.h.in}, @command{autoheader} needs to
16300 build or to find templates for each symbol. Modern releases of Autoconf
16301 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
16302 Macros}), but in older releases a file, @file{acconfig.h}, contained the
16303 list of needed templates. @command{autoheader} copied comments and
16304 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
16305 the current directory, if present. This file used to be mandatory if
16306 you @code{AC_DEFINE} any additional symbols.
16308 Modern releases of Autoconf also provide @code{AH_TOP} and
16309 @code{AH_BOTTOM} if you need to prepend/append some information to
16310 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
16311 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
16312 @command{autoheader} copies the lines before the line containing
16313 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
16314 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
16315 @command{autoheader} copies the lines after that line to the end of the
16316 file it generates. Either or both of those strings may be omitted. An
16317 even older alternate way to produce the same effect in ancient versions
16318 of Autoconf is to create the files @file{@var{file}.top} (typically
16319 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
16320 directory. If they exist, @command{autoheader} copies them to the
16321 beginning and end, respectively, of its output.
16323 In former versions of Autoconf, the files used in preparing a software
16324 package for distribution were:
16327 configure.ac --. .------> autoconf* -----> configure
16329 [aclocal.m4] --+ `---.
16331 +--> [autoheader*] -> [config.h.in]
16332 [acconfig.h] ----. |
16339 Using only the @code{AH_} macros, @file{configure.ac} should be
16340 self-contained, and should not depend upon @file{acconfig.h} etc.
16343 @node autoupdate Invocation
16344 @section Using @command{autoupdate} to Modernize @file{configure.ac}
16345 @cindex @command{autoupdate}
16347 The @command{autoupdate} program updates a @file{configure.ac} file that
16348 calls Autoconf macros by their old names to use the current macro names.
16349 In version 2 of Autoconf, most of the macros were renamed to use a more
16350 uniform and descriptive naming scheme. @xref{Macro Names}, for a
16351 description of the new scheme. Although the old names still work
16352 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
16353 new names), you can make your @file{configure.ac} files more readable
16354 and make it easier to use the current Autoconf documentation if you
16355 update them to use the new macro names.
16357 @evindex SIMPLE_BACKUP_SUFFIX
16358 If given no arguments, @command{autoupdate} updates @file{configure.ac},
16359 backing up the original version with the suffix @file{~} (or the value
16360 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
16361 set). If you give @command{autoupdate} an argument, it reads that file
16362 instead of @file{configure.ac} and writes the updated file to the
16366 @command{autoupdate} accepts the following options:
16371 Print a summary of the command line options and exit.
16375 Print the version number of Autoconf and exit.
16379 Report processing steps.
16383 Don't remove the temporary files.
16387 Force the update even if the file has not changed. Disregard the cache.
16389 @item --include=@var{dir}
16390 @itemx -I @var{dir}
16391 Also look for input files in @var{dir}. Multiple invocations accumulate.
16392 Directories are browsed from last to first.
16395 @node Obsolete Macros
16396 @section Obsolete Macros
16398 Several macros are obsoleted in Autoconf, for various reasons (typically
16399 they failed to quote properly, couldn't be extended for more recent
16400 issues, etc.). They are still supported, but deprecated: their use
16403 During the jump from Autoconf version 1 to version 2, most of the
16404 macros were renamed to use a more uniform and descriptive naming scheme,
16405 but their signature did not change. @xref{Macro Names}, for a
16406 description of the new naming scheme. Below, if there is just the mapping
16407 from old names to new names for these macros, the reader is invited to
16408 refer to the definition of the new macro for the signature and the
16413 @code{AC_FUNC_ALLOCA}
16416 @defmac AC_ARG_ARRAY
16417 @acindex{ARG_ARRAY}
16418 removed because of limited usefulness
16423 This macro is obsolete; it does nothing.
16426 @defmac AC_C_LONG_DOUBLE
16427 @acindex{C_LONG_DOUBLE}
16428 @cvindex HAVE_LONG_DOUBLE
16429 If the C compiler supports a working @code{long double} type with more
16430 range or precision than the @code{double} type, define
16431 @code{HAVE_LONG_DOUBLE}.
16433 You should use @code{AC_TYPE_LONG_DOUBLE} or
16434 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
16437 @defmac AC_CANONICAL_SYSTEM
16438 @acindex{CANONICAL_SYSTEM}
16439 Determine the system type and set output variables to the names of the
16440 canonical system types. @xref{Canonicalizing}, for details about the
16441 variables this macro sets.
16443 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
16444 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
16445 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
16449 @defmac AC_CHAR_UNSIGNED
16450 @acindex{CHAR_UNSIGNED}
16451 @code{AC_C_CHAR_UNSIGNED}
16454 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
16455 @acindex{CHECK_TYPE}
16456 Autoconf, up to 2.13, used to provide this version of
16457 @code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
16458 it is a member of the @code{CHECK} clan, it does
16459 more than just checking. Secondly, missing types are defined
16460 using @code{#define}, not @code{typedef}, and this can lead to
16461 problems in the case of pointer types.
16463 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
16464 @ref{Generic Types}, for the description of the current macro.
16466 If the type @var{type} is not defined, define it to be the C (or C++)
16467 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
16469 This macro is equivalent to:
16472 AC_CHECK_TYPE([@var{type}], [],
16473 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
16474 [Define to `@var{default}'
16475 if <sys/types.h> does not define.])])
16478 In order to keep backward compatibility, the two versions of
16479 @code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
16483 If there are three or four arguments, the modern version is used.
16486 If the second argument appears to be a C or C++ type, then the
16487 obsolete version is used. This happens if the argument is a C or C++
16488 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
16489 followed by one of @samp{[(* } and then by a string of zero or more
16490 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
16493 If the second argument is spelled with the alphabet of valid C and C++
16494 types, the user is warned and the modern version is used.
16497 Otherwise, the modern version is used.
16501 You are encouraged either to use a valid builtin type, or to use the
16502 equivalent modern code (see above), or better yet, to use
16503 @code{AC_CHECK_TYPES} together with
16506 #ifndef HAVE_LOFF_T
16507 typedef loff_t off_t;
16511 @c end of AC_CHECK_TYPE
16513 @defmac AC_CHECKING (@var{feature-description})
16515 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
16518 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
16519 @acindex{COMPILE_CHECK}
16520 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
16521 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
16522 addition that it prints @samp{checking for @var{echo-text}} to the
16523 standard output first, if @var{echo-text} is non-empty. Use
16524 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
16525 messages (@pxref{Printing Messages}).
16533 @defmac AC_CROSS_CHECK
16534 @acindex{CROSS_CHECK}
16535 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
16541 Check for the Cygwin environment in which case the shell variable
16542 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
16543 means to check the nature of the host is using
16544 @code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as:
16547 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
16549 *cygwin* ) CYGWIN=yes;;
16554 Beware that the variable @code{CYGWIN} has a special meaning when
16555 running Cygwin, and should not be changed. That's yet another reason
16556 not to use this macro.
16559 @defmac AC_DECL_SYS_SIGLIST
16560 @acindex{DECL_SYS_SIGLIST}
16561 @cvindex SYS_SIGLIST_DECLARED
16565 AC_CHECK_DECLS([sys_siglist], [], [],
16566 [#include <signal.h>
16567 /* NetBSD declares sys_siglist in unistd.h. */
16568 #ifdef HAVE_UNISTD_H
16569 # include <unistd.h>
16575 @defmac AC_DECL_YYTEXT
16576 @acindex{DECL_YYTEXT}
16577 Does nothing, now integrated in @code{AC_PROG_LEX}.
16580 @defmac AC_DIR_HEADER
16581 @acindex{DIR_HEADER}
16586 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
16587 but defines a different set of C preprocessor macros to indicate which
16588 header file is found:
16590 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
16591 @item Header @tab Old Symbol @tab New Symbol
16592 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
16593 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
16594 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
16595 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
16599 @defmac AC_DYNIX_SEQ
16600 @acindex{DYNIX_SEQ}
16601 If on DYNIX/ptx, add @option{-lseq} to output variable
16602 @code{LIBS}. This macro used to be defined as
16605 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
16609 now it is just @code{AC_FUNC_GETMNTENT}.
16615 Defined the output variable @code{EXEEXT} based on the output of the
16616 compiler, which is now done automatically. Typically set to empty
16617 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
16622 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
16623 and sets @code{EMXOS2}.
16628 @code{AC_MSG_ERROR}
16636 @defmac AC_FIND_XTRA
16637 @acindex{FIND_XTRA}
16638 @code{AC_PATH_XTRA}
16643 @code{m4_foreach_w}
16646 @defmac AC_FUNC_CHECK
16647 @acindex{FUNC_CHECK}
16648 @code{AC_CHECK_FUNC}
16651 @defmac AC_FUNC_SETVBUF_REVERSED
16652 @acindex{FUNC_SETVBUF_REVERSED}
16653 @cvindex SETVBUF_REVERSED
16654 @c @fuindex setvbuf
16655 @prindex @code{setvbuf}
16656 Do nothing. Formerly, this macro checked whether @code{setvbuf} takes
16657 the buffering type as its second argument and the buffer pointer as the
16658 third, instead of the other way around, and defined
16659 @code{SETVBUF_REVERSED}. However, the last systems to have the problem
16660 were those based on SVR2, which became obsolete in 1987, and the macro
16661 is no longer needed.
16664 @defmac AC_FUNC_WAIT3
16665 @acindex{FUNC_WAIT3}
16666 @cvindex HAVE_WAIT3
16667 If @code{wait3} is found and fills in the contents of its third argument
16668 (a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define
16671 These days portable programs should use @code{waitpid}, not
16672 @code{wait3}, as @code{wait3} has been removed from Posix.
16675 @defmac AC_GCC_TRADITIONAL
16676 @acindex{GCC_TRADITIONAL}
16677 @code{AC_PROG_GCC_TRADITIONAL}
16680 @defmac AC_GETGROUPS_T
16681 @acindex{GETGROUPS_T}
16682 @code{AC_TYPE_GETGROUPS}
16685 @defmac AC_GETLOADAVG
16686 @acindex{GETLOADAVG}
16687 @code{AC_FUNC_GETLOADAVG}
16690 @defmac AC_HAVE_FUNCS
16691 @acindex{HAVE_FUNCS}
16692 @code{AC_CHECK_FUNCS}
16695 @defmac AC_HAVE_HEADERS
16696 @acindex{HAVE_HEADERS}
16697 @code{AC_CHECK_HEADERS}
16700 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
16701 @acindex{HAVE_LIBRARY}
16702 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
16703 @var{function} argument of @code{main}. In addition, @var{library} can
16704 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
16705 all of those cases, the compiler is passed @option{-lfoo}. However,
16706 @var{library} cannot be a shell variable; it must be a literal name.
16709 @defmac AC_HAVE_POUNDBANG
16710 @acindex{HAVE_POUNDBANG}
16711 @code{AC_SYS_INTERPRETER} (different calling convention)
16714 @defmac AC_HEADER_CHECK
16715 @acindex{HEADER_CHECK}
16716 @code{AC_CHECK_HEADER}
16719 @defmac AC_HEADER_EGREP
16720 @acindex{HEADER_EGREP}
16721 @code{AC_EGREP_HEADER}
16724 @defmac AC_HELP_STRING
16725 @acindex{HELP_STRING}
16726 @code{AS_HELP_STRING}
16729 @defmac AC_INIT (@var{unique-file-in-source-dir})
16731 Formerly @code{AC_INIT} used to have a single argument, and was
16736 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
16745 @defmac AC_INT_16_BITS
16746 @acindex{INT_16_BITS}
16747 @cvindex INT_16_BITS
16748 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
16749 Use @samp{AC_CHECK_SIZEOF(int)} instead.
16752 @defmac AC_IRIX_SUN
16754 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
16755 @code{LIBS}. If you were using it to get @code{getmntent}, use
16756 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
16757 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
16758 getpwnam)}. Up to Autoconf 2.13, it used to be
16761 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
16765 now it is defined as
16769 AC_CHECK_LIB([sun], [getpwnam])
16775 Same as @samp{AC_LANG([C])}.
16778 @defmac AC_LANG_CPLUSPLUS
16779 @acindex{LANG_CPLUSPLUS}
16780 Same as @samp{AC_LANG([C++])}.
16783 @defmac AC_LANG_FORTRAN77
16784 @acindex{LANG_FORTRAN77}
16785 Same as @samp{AC_LANG([Fortran 77])}.
16788 @defmac AC_LANG_RESTORE
16789 @acindex{LANG_RESTORE}
16790 Select the @var{language} that is saved on the top of the stack, as set
16791 by @code{AC_LANG_SAVE}, remove it from the stack, and call
16792 @code{AC_LANG(@var{language})}.
16795 @defmac AC_LANG_SAVE
16796 @acindex{LANG_SAVE}
16797 Remember the current language (as set by @code{AC_LANG}) on a stack.
16798 The current language does not change. @code{AC_LANG_PUSH} is preferred.
16801 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
16802 @acindex{LINK_FILES}
16803 This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
16807 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
16815 AC_CONFIG_LINKS([host.h:config/$machine.h
16816 object.h:config/$obj_format.h])
16822 @code{AC_PROG_LN_S}
16825 @defmac AC_LONG_64_BITS
16826 @acindex{LONG_64_BITS}
16827 @cvindex LONG_64_BITS
16828 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
16829 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
16832 @defmac AC_LONG_DOUBLE
16833 @acindex{LONG_DOUBLE}
16834 If the C compiler supports a working @code{long double} type with more
16835 range or precision than the @code{double} type, define
16836 @code{HAVE_LONG_DOUBLE}.
16838 You should use @code{AC_TYPE_LONG_DOUBLE} or
16839 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
16842 @defmac AC_LONG_FILE_NAMES
16843 @acindex{LONG_FILE_NAMES}
16844 @code{AC_SYS_LONG_FILE_NAMES}
16847 @defmac AC_MAJOR_HEADER
16848 @acindex{MAJOR_HEADER}
16849 @code{AC_HEADER_MAJOR}
16852 @defmac AC_MEMORY_H
16854 @cvindex NEED_MEMORY_H
16855 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
16856 defined in @file{memory.h}. Today it is equivalent to
16857 @samp{AC_CHECK_HEADERS([memory.h])}. Adjust your code to depend upon
16858 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
16864 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
16865 environment and sets @code{MINGW32}.
16868 @defmac AC_MINUS_C_MINUS_O
16869 @acindex{MINUS_C_MINUS_O}
16870 @code{AC_PROG_CC_C_O}
16875 @code{AC_FUNC_MMAP}
16880 @code{AC_TYPE_MODE_T}
16886 Defined the output variable @code{OBJEXT} based on the output of the
16887 compiler, after .c files have been excluded. Typically set to @samp{o}
16888 if Posix, @samp{obj} if a @acronym{DOS} variant.
16889 Now the compiler checking macros handle
16890 this automatically.
16893 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
16895 Make M4 print a message to the standard error output warning that
16896 @var{this-macro-name} is obsolete, and giving the file and line number
16897 where it was called. @var{this-macro-name} should be the name of the
16898 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
16899 it is printed at the end of the warning message; for example, it can be
16900 a suggestion for what to use instead of @var{this-macro-name}.
16905 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
16908 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
16909 services to the user.
16914 @code{AC_TYPE_OFF_T}
16917 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
16919 The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted
16920 interface is equivalent to:
16924 AC_CONFIG_FILES(@var{file}@dots{})
16925 AC_CONFIG_COMMANDS([default],
16926 @var{extra-cmds}, @var{init-cmds})
16932 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
16933 @acindex{OUTPUT_COMMANDS}
16934 Specify additional shell commands to run at the end of
16935 @file{config.status}, and shell commands to initialize any variables
16936 from @command{configure}. This macro may be called multiple times. It is
16937 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
16939 Here is an unrealistic example:
16943 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
16945 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
16949 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
16950 additional key, an important difference is that
16951 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
16952 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
16953 can safely be given macro calls as arguments:
16956 AC_CONFIG_COMMANDS(foo, [my_FOO()])
16960 Conversely, where one level of quoting was enough for literal strings
16961 with @code{AC_OUTPUT_COMMANDS}, you need two with
16962 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
16966 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
16967 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
16974 @code{AC_TYPE_PID_T}
16979 @code{AC_PREFIX_PROGRAM}
16982 @defmac AC_PROGRAMS_CHECK
16983 @acindex{PROGRAMS_CHECK}
16984 @code{AC_CHECK_PROGS}
16987 @defmac AC_PROGRAMS_PATH
16988 @acindex{PROGRAMS_PATH}
16989 @code{AC_PATH_PROGS}
16992 @defmac AC_PROGRAM_CHECK
16993 @acindex{PROGRAM_CHECK}
16994 @code{AC_CHECK_PROG}
16997 @defmac AC_PROGRAM_EGREP
16998 @acindex{PROGRAM_EGREP}
16999 @code{AC_EGREP_CPP}
17002 @defmac AC_PROGRAM_PATH
17003 @acindex{PROGRAM_PATH}
17004 @code{AC_PATH_PROG}
17007 @defmac AC_REMOTE_TAPE
17008 @acindex{REMOTE_TAPE}
17009 removed because of limited usefulness
17012 @defmac AC_RESTARTABLE_SYSCALLS
17013 @acindex{RESTARTABLE_SYSCALLS}
17014 @code{AC_SYS_RESTARTABLE_SYSCALLS}
17017 @defmac AC_RETSIGTYPE
17018 @acindex{RETSIGTYPE}
17019 @code{AC_TYPE_SIGNAL}
17024 removed because of limited usefulness
17027 @defmac AC_SCO_INTL
17030 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
17031 macro used to do this:
17034 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
17038 Now it just calls @code{AC_FUNC_STRFTIME} instead.
17041 @defmac AC_SETVBUF_REVERSED
17042 @acindex{SETVBUF_REVERSED}
17043 @code{AC_FUNC_SETVBUF_REVERSED}
17046 @defmac AC_SET_MAKE
17048 @code{AC_PROG_MAKE_SET}
17051 @defmac AC_SIZEOF_TYPE
17052 @acindex{SIZEOF_TYPE}
17053 @code{AC_CHECK_SIZEOF}
17058 @code{AC_TYPE_SIZE_T}
17061 @defmac AC_STAT_MACROS_BROKEN
17062 @acindex{STAT_MACROS_BROKEN}
17063 @code{AC_HEADER_STAT}
17066 @defmac AC_STDC_HEADERS
17067 @acindex{STDC_HEADERS}
17068 @code{AC_HEADER_STDC}
17073 @code{AC_FUNC_STRCOLL}
17076 @defmac AC_ST_BLKSIZE
17077 @acindex{ST_BLKSIZE}
17078 @code{AC_CHECK_MEMBERS}
17081 @defmac AC_ST_BLOCKS
17082 @acindex{ST_BLOCKS}
17083 @code{AC_STRUCT_ST_BLOCKS}
17088 @code{AC_CHECK_MEMBERS}
17091 @defmac AC_SYS_RESTARTABLE_SYSCALLS
17092 @acindex{SYS_RESTARTABLE_SYSCALLS}
17093 @cvindex HAVE_RESTARTABLE_SYSCALLS
17094 If the system automatically restarts a system call that is interrupted
17095 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
17096 not check whether system calls are restarted in general---it checks whether a
17097 signal handler installed with @code{signal} (but not @code{sigaction})
17098 causes system calls to be restarted. It does not check whether system calls
17099 can be restarted when interrupted by signals that have no handler.
17101 These days portable programs should use @code{sigaction} with
17102 @code{SA_RESTART} if they want restartable system calls. They should
17103 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
17104 system call is restartable is a dynamic issue, not a configuration-time
17108 @defmac AC_SYS_SIGLIST_DECLARED
17109 @acindex{SYS_SIGLIST_DECLARED}
17110 @code{AC_DECL_SYS_SIGLIST}
17113 @defmac AC_TEST_CPP
17115 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
17118 @defmac AC_TEST_PROGRAM
17119 @acindex{TEST_PROGRAM}
17120 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
17123 @defmac AC_TIMEZONE
17125 @code{AC_STRUCT_TIMEZONE}
17128 @defmac AC_TIME_WITH_SYS_TIME
17129 @acindex{TIME_WITH_SYS_TIME}
17130 @code{AC_HEADER_TIME}
17133 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17134 @acindex{TRY_COMPILE}
17139 [AC_LANG_PROGRAM([[@var{includes}]],
17140 [[@var{function-body}]])],
17141 [@var{action-if-true}],
17142 [@var{action-if-false}])
17146 @xref{Running the Compiler}.
17148 This macro double quotes both @var{includes} and @var{function-body}.
17150 For C and C++, @var{includes} is any @code{#include} statements needed
17151 by the code in @var{function-body} (@var{includes} is ignored if
17152 the currently selected language is Fortran or Fortran 77). The compiler
17153 and compilation flags are determined by the current language
17154 (@pxref{Language Choice}).
17157 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
17163 [AC_LANG_SOURCE([[@var{input}]])],
17164 [@var{action-if-true}],
17165 [@var{action-if-false}])
17169 @xref{Running the Preprocessor}.
17171 This macro double quotes the @var{input}.
17174 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17180 [AC_LANG_PROGRAM([[@var{includes}]],
17181 [[@var{function-body}]])],
17182 [@var{action-if-true}],
17183 [@var{action-if-false}])
17187 @xref{Running the Compiler}.
17189 This macro double quotes both @var{includes} and @var{function-body}.
17191 Depending on the current language (@pxref{Language Choice}), create a
17192 test program to see whether a function whose body consists of
17193 @var{function-body} can be compiled and linked. If the file compiles
17194 and links successfully, run shell commands @var{action-if-found},
17195 otherwise run @var{action-if-not-found}.
17197 This macro double quotes both @var{includes} and @var{function-body}.
17199 For C and C++, @var{includes} is any @code{#include} statements needed
17200 by the code in @var{function-body} (@var{includes} is ignored if
17201 the currently selected language is Fortran or Fortran 77). The compiler
17202 and compilation flags are determined by the current language
17203 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
17204 @code{LIBS} are used for linking.
17207 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
17208 @acindex{TRY_LINK_FUNC}
17209 This macro is equivalent to
17210 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
17211 [@var{action-if-found}], [@var{action-if-not-found}])}.
17214 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
17220 [AC_LANG_SOURCE([[@var{program}]])],
17221 [@var{action-if-true}],
17222 [@var{action-if-false}],
17223 [@var{action-if-cross-compiling}])
17232 @code{AC_TYPE_UID_T}
17235 @defmac AC_UNISTD_H
17237 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
17243 Define @code{USG} if the @acronym{BSD} string functions are defined in
17244 @file{strings.h}. You should no longer depend upon @code{USG}, but on
17245 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
17248 @defmac AC_UTIME_NULL
17249 @acindex{UTIME_NULL}
17250 @code{AC_FUNC_UTIME_NULL}
17253 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
17254 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
17255 If the cache file is inconsistent with the current host, target and
17256 build system types, it used to execute @var{cmd} or print a default
17257 error message. This is now handled by default.
17260 @defmac AC_VERBOSE (@var{result-description})
17262 @code{AC_MSG_RESULT}.
17267 @code{AC_FUNC_VFORK}
17272 @code{AC_FUNC_VPRINTF}
17277 @code{AC_FUNC_WAIT3}
17285 @defmac AC_WORDS_BIGENDIAN
17286 @acindex{WORDS_BIGENDIAN}
17287 @code{AC_C_BIGENDIAN}
17290 @defmac AC_XENIX_DIR
17291 @acindex{XENIX_DIR}
17293 This macro used to add @option{-lx} to output variable @code{LIBS} if on
17294 Xenix. Also, if @file{dirent.h} is being checked for, added
17295 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
17296 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
17297 running @sc{xenix} on which you should not depend:
17300 AC_MSG_CHECKING([for Xenix])
17301 AC_EGREP_CPP([yes],
17302 [#if defined M_XENIX && !defined M_UNIX
17305 [AC_MSG_RESULT([yes]); XENIX=yes],
17306 [AC_MSG_RESULT([no]); XENIX=])
17310 @defmac AC_YYTEXT_POINTER
17311 @acindex{YYTEXT_POINTER}
17312 @code{AC_DECL_YYTEXT}
17316 @section Upgrading From Version 1
17317 @cindex Upgrading autoconf
17318 @cindex Autoconf upgrading
17320 Autoconf version 2 is mostly backward compatible with version 1.
17321 However, it introduces better ways to do some things, and doesn't
17322 support some of the ugly things in version 1. So, depending on how
17323 sophisticated your @file{configure.ac} files are, you might have to do
17324 some manual work in order to upgrade to version 2. This chapter points
17325 out some problems to watch for when upgrading. Also, perhaps your
17326 @command{configure} scripts could benefit from some of the new features in
17327 version 2; the changes are summarized in the file @file{NEWS} in the
17328 Autoconf distribution.
17331 * Changed File Names:: Files you might rename
17332 * Changed Makefiles:: New things to put in @file{Makefile.in}
17333 * Changed Macros:: Macro calls you might replace
17334 * Changed Results:: Changes in how to check test results
17335 * Changed Macro Writing:: Better ways to write your own macros
17338 @node Changed File Names
17339 @subsection Changed File Names
17341 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
17342 in a particular package's source directory), you must rename it to
17343 @file{acsite.m4}. @xref{autoconf Invocation}.
17345 If you distribute @file{install.sh} with your package, rename it to
17346 @file{install-sh} so @code{make} builtin rules don't inadvertently
17347 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
17348 looks for the script under both names, but it is best to use the new name.
17350 If you were using @file{config.h.top}, @file{config.h.bot}, or
17351 @file{acconfig.h}, you still can, but you have less clutter if you
17352 use the @code{AH_} macros. @xref{Autoheader Macros}.
17354 @node Changed Makefiles
17355 @subsection Changed Makefiles
17357 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
17358 your @file{Makefile.in} files, so they can take advantage of the values
17359 of those variables in the environment when @command{configure} is run.
17360 Doing this isn't necessary, but it's a convenience for users.
17362 Also add @samp{@@configure_input@@} in a comment to each input file for
17363 @code{AC_OUTPUT}, so that the output files contain a comment saying
17364 they were produced by @command{configure}. Automatically selecting the
17365 right comment syntax for all the kinds of files that people call
17366 @code{AC_OUTPUT} on became too much work.
17368 Add @file{config.log} and @file{config.cache} to the list of files you
17369 remove in @code{distclean} targets.
17371 If you have the following in @file{Makefile.in}:
17374 prefix = /usr/local
17375 exec_prefix = $(prefix)
17379 you must change it to:
17382 prefix = @@prefix@@
17383 exec_prefix = @@exec_prefix@@
17387 The old behavior of replacing those variables without @samp{@@}
17388 characters around them has been removed.
17390 @node Changed Macros
17391 @subsection Changed Macros
17393 Many of the macros were renamed in Autoconf version 2. You can still
17394 use the old names, but the new ones are clearer, and it's easier to find
17395 the documentation for them. @xref{Obsolete Macros}, for a table showing the
17396 new names for the old macros. Use the @command{autoupdate} program to
17397 convert your @file{configure.ac} to using the new macro names.
17398 @xref{autoupdate Invocation}.
17400 Some macros have been superseded by similar ones that do the job better,
17401 but are not call-compatible. If you get warnings about calling obsolete
17402 macros while running @command{autoconf}, you may safely ignore them, but
17403 your @command{configure} script generally works better if you follow
17404 the advice that is printed about what to replace the obsolete macros with. In
17405 particular, the mechanism for reporting the results of tests has
17406 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
17407 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
17408 looks better if you switch to @code{AC_MSG_CHECKING} and
17409 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
17410 in conjunction with cache variables. @xref{Caching Results}.
17414 @node Changed Results
17415 @subsection Changed Results
17417 If you were checking the results of previous tests by examining the
17418 shell variable @code{DEFS}, you need to switch to checking the values of
17419 the cache variables for those tests. @code{DEFS} no longer exists while
17420 @command{configure} is running; it is only created when generating output
17421 files. This difference from version 1 is because properly quoting the
17422 contents of that variable turned out to be too cumbersome and
17423 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
17426 For example, here is a @file{configure.ac} fragment written for Autoconf
17430 AC_HAVE_FUNCS(syslog)
17432 *-DHAVE_SYSLOG*) ;;
17433 *) # syslog is not in the default libraries. See if it's in some other.
17435 for lib in bsd socket inet; do
17436 AC_CHECKING(for syslog in -l$lib)
17437 LIBS="-l$lib $saved_LIBS"
17438 AC_HAVE_FUNCS(syslog)
17440 *-DHAVE_SYSLOG*) break ;;
17448 Here is a way to write it for version 2:
17451 AC_CHECK_FUNCS([syslog])
17452 if test $ac_cv_func_syslog = no; then
17453 # syslog is not in the default libraries. See if it's in some other.
17454 for lib in bsd socket inet; do
17455 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
17456 LIBS="-l$lib $LIBS"; break])
17461 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
17462 backslashes before quotes, you need to remove them. It now works
17463 predictably, and does not treat quotes (except back quotes) specially.
17464 @xref{Setting Output Variables}.
17466 All of the Boolean shell variables set by Autoconf macros now use
17467 @samp{yes} for the true value. Most of them use @samp{no} for false,
17468 though for backward compatibility some use the empty string instead. If
17469 you were relying on a shell variable being set to something like 1 or
17470 @samp{t} for true, you need to change your tests.
17472 @node Changed Macro Writing
17473 @subsection Changed Macro Writing
17475 When defining your own macros, you should now use @code{AC_DEFUN}
17476 instead of @code{define}. @code{AC_DEFUN} automatically calls
17477 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
17478 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
17479 messages on the screen. There's no actual harm in continuing to use the
17480 older way, but it's less convenient and attractive. @xref{Macro
17483 You probably looked at the macros that came with Autoconf as a guide for
17484 how to do things. It would be a good idea to take a look at the new
17485 versions of them, as the style is somewhat improved and they take
17486 advantage of some new features.
17488 If you were doing tricky things with undocumented Autoconf internals
17489 (macros, variables, diversions), check whether you need to change
17490 anything to account for changes that have been made. Perhaps you can
17491 even use an officially supported technique in version 2 instead of
17492 kludging. Or perhaps not.
17494 To speed up your locally written feature tests, add caching to them.
17495 See whether any of your tests are of general enough usefulness to
17496 encapsulate them into macros that you can share.
17499 @node Autoconf 2.13
17500 @section Upgrading From Version 2.13
17501 @cindex Upgrading autoconf
17502 @cindex Autoconf upgrading
17504 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
17505 suits this section@enddots{}
17508 Autoconf version 2.50 is mostly backward compatible with version 2.13.
17509 However, it introduces better ways to do some things, and doesn't
17510 support some of the ugly things in version 2.13. So, depending on how
17511 sophisticated your @file{configure.ac} files are, you might have to do
17512 some manual work in order to upgrade to version 2.50. This chapter
17513 points out some problems to watch for when upgrading. Also, perhaps
17514 your @command{configure} scripts could benefit from some of the new
17515 features in version 2.50; the changes are summarized in the file
17516 @file{NEWS} in the Autoconf distribution.
17520 * Changed Quotation:: Broken code which used to work
17521 * New Macros:: Interaction with foreign macros
17522 * Hosts and Cross-Compilation:: Bugward compatibility kludges
17523 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
17524 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
17527 @node Changed Quotation
17528 @subsection Changed Quotation
17530 The most important changes are invisible to you: the implementation of
17531 most macros have completely changed. This allowed more factorization of
17532 the code, better error messages, a higher uniformity of the user's
17533 interface etc. Unfortunately, as a side effect, some construct which
17534 used to (miraculously) work might break starting with Autoconf 2.50.
17535 The most common culprit is bad quotation.
17537 For instance, in the following example, the message is not properly
17542 AC_CHECK_HEADERS(foo.h, ,
17543 AC_MSG_ERROR(cannot find foo.h, bailing out))
17548 Autoconf 2.13 simply ignores it:
17551 $ @kbd{autoconf-2.13; ./configure --silent}
17552 creating cache ./config.cache
17553 configure: error: cannot find foo.h
17558 while Autoconf 2.50 produces a broken @file{configure}:
17561 $ @kbd{autoconf-2.50; ./configure --silent}
17562 configure: error: cannot find foo.h
17563 ./configure: exit: bad non-numeric arg `bailing'
17564 ./configure: exit: bad non-numeric arg `bailing'
17568 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
17572 AC_INIT([Example], [1.0], [bug-example@@example.org])
17573 AC_CHECK_HEADERS([foo.h], [],
17574 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
17578 Many many (and many more) Autoconf macros were lacking proper quotation,
17579 including no less than@dots{} @code{AC_DEFUN} itself!
17582 $ @kbd{cat configure.in}
17583 AC_DEFUN([AC_PROG_INSTALL],
17584 [# My own much better version
17589 $ @kbd{autoconf-2.13}
17590 autoconf: Undefined macros:
17591 ***BUG in Autoconf--please report*** AC_FD_MSG
17592 ***BUG in Autoconf--please report*** AC_EPI
17593 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
17594 configure.in:5:AC_PROG_INSTALL
17595 $ @kbd{autoconf-2.50}
17601 @subsection New Macros
17603 @cindex undefined macro
17604 @cindex @code{_m4_divert_diversion}
17606 While Autoconf was relatively dormant in the late 1990s, Automake
17607 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
17608 in 2001, Autoconf provided
17609 versions of these macros, integrated in the @code{AC_} namespace,
17610 instead of @code{AM_}. But in order to ease the upgrading via
17611 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
17613 Unfortunately older versions of Automake (e.g., Automake 1.4)
17614 did not quote the names of these macros.
17615 Therefore, when @command{m4} finds something like
17616 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
17617 @code{AM_TYPE_PTRDIFF_T} is
17618 expanded, replaced with its Autoconf definition.
17620 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
17621 complains, in its own words:
17624 $ @kbd{cat configure.ac}
17625 AC_INIT([Example], [1.0], [bug-example@@example.org])
17627 $ @kbd{aclocal-1.4}
17629 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
17630 aclocal.m4:17: the top level
17631 autom4te: m4 failed with exit status: 1
17635 Modern versions of Automake no longer define most of these
17636 macros, and properly quote the names of the remaining macros.
17637 If you must use an old Automake, do not depend upon macros from Automake
17638 as it is simply not its job
17639 to provide macros (but the one it requires itself):
17642 $ @kbd{cat configure.ac}
17643 AC_INIT([Example], [1.0], [bug-example@@example.org])
17645 $ @kbd{rm aclocal.m4}
17647 autoupdate: `configure.ac' is updated
17648 $ @kbd{cat configure.ac}
17649 AC_INIT([Example], [1.0], [bug-example@@example.org])
17650 AC_CHECK_TYPES([ptrdiff_t])
17651 $ @kbd{aclocal-1.4}
17657 @node Hosts and Cross-Compilation
17658 @subsection Hosts and Cross-Compilation
17659 @cindex Cross compilation
17661 Based on the experience of compiler writers, and after long public
17662 debates, many aspects of the cross-compilation chain have changed:
17666 the relationship between the build, host, and target architecture types,
17669 the command line interface for specifying them to @command{configure},
17672 the variables defined in @command{configure},
17675 the enabling of cross-compilation mode.
17680 The relationship between build, host, and target have been cleaned up:
17681 the chain of default is now simply: target defaults to host, host to
17682 build, and build to the result of @command{config.guess}. Nevertheless,
17683 in order to ease the transition from 2.13 to 2.50, the following
17684 transition scheme is implemented. @emph{Do not rely on it}, as it will
17685 be completely disabled in a couple of releases (we cannot keep it, as it
17686 proves to cause more problems than it cures).
17688 They all default to the result of running @command{config.guess}, unless
17689 you specify either @option{--build} or @option{--host}. In this case,
17690 the default becomes the system type you specified. If you specify both,
17691 and they're different, @command{configure} enters cross compilation
17692 mode, so it doesn't run any tests that require execution.
17694 Hint: if you mean to override the result of @command{config.guess},
17695 prefer @option{--build} over @option{--host}. In the future,
17696 @option{--host} will not override the name of the build system type.
17697 Whenever you specify @option{--host}, be sure to specify @option{--build}
17702 For backward compatibility, @command{configure} accepts a system
17703 type as an option by itself. Such an option overrides the
17704 defaults for build, host, and target system types. The following
17705 configure statement configures a cross toolchain that runs on
17706 Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc,
17707 which is also the build platform.
17710 ./configure --host=alpha-netbsd sparc-gnu
17715 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
17716 and @code{target} had a different semantics before and after the
17717 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
17718 @option{--build} is strictly copied into @code{build_alias}, and is left
17719 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
17720 set to the canonicalized build type. To ease the transition, before,
17721 its contents is the same as that of @code{build_alias}. Do @emph{not}
17722 rely on this broken feature.
17724 For consistency with the backward compatibility scheme exposed above,
17725 when @option{--host} is specified but @option{--build} isn't, the build
17726 system is assumed to be the same as @option{--host}, and
17727 @samp{build_alias} is set to that value. Eventually, this
17728 historically incorrect behavior will go away.
17732 The former scheme to enable cross-compilation proved to cause more harm
17733 than good, in particular, it used to be triggered too easily, leaving
17734 regular end users puzzled in front of cryptic error messages.
17735 @command{configure} could even enter cross-compilation mode only
17736 because the compiler was not functional. This is mainly because
17737 @command{configure} used to try to detect cross-compilation, instead of
17738 waiting for an explicit flag from the user.
17740 Now, @command{configure} enters cross-compilation mode if and only if
17741 @option{--host} is passed.
17743 That's the short documentation. To ease the transition between 2.13 and
17744 its successors, a more complicated scheme is implemented. @emph{Do not
17745 rely on the following}, as it will be removed in the near future.
17747 If you specify @option{--host}, but not @option{--build}, when
17748 @command{configure} performs the first compiler test it tries to run
17749 an executable produced by the compiler. If the execution fails, it
17750 enters cross-compilation mode. This is fragile. Moreover, by the time
17751 the compiler test is performed, it may be too late to modify the
17752 build-system type: other tests may have already been performed.
17753 Therefore, whenever you specify @option{--host}, be sure to specify
17754 @option{--build} too.
17757 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
17761 enters cross-compilation mode. The former interface, which
17762 consisted in setting the compiler to a cross-compiler without informing
17763 @command{configure} is obsolete. For instance, @command{configure}
17764 fails if it can't run the code generated by the specified compiler if you
17765 configure as follows:
17768 ./configure CC=m68k-coff-gcc
17772 @node AC_LIBOBJ vs LIBOBJS
17773 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
17775 Up to Autoconf 2.13, the replacement of functions was triggered via the
17776 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
17777 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
17778 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
17780 This change is mandated by the unification of the @acronym{GNU} Build System
17781 components. In particular, the various fragile techniques used to parse
17782 a @file{configure.ac} are all replaced with the use of traces. As a
17783 consequence, any action must be traceable, which obsoletes critical
17784 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
17785 and it can even be handled gracefully (read, ``without your having to
17786 change something'').
17788 There were two typical uses of @code{LIBOBJS}: asking for a replacement
17789 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
17793 As for function replacement, the fix is immediate: use
17794 @code{AC_LIBOBJ}. For instance:
17797 LIBOBJS="$LIBOBJS fnmatch.o"
17798 LIBOBJS="$LIBOBJS malloc.$ac_objext"
17802 should be replaced with:
17805 AC_LIBOBJ([fnmatch])
17806 AC_LIBOBJ([malloc])
17812 When used with Automake 1.10 or newer, a suitable value for
17813 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
17814 can be referenced from any @file{Makefile.am}. Even without Automake,
17815 arranging for @code{LIBOBJDIR} to be set correctly enables
17816 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
17817 The @code{LIBOJBDIR} feature is experimental.
17820 @node AC_FOO_IFELSE vs AC_TRY_FOO
17821 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
17823 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
17824 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
17825 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
17826 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
17827 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
17828 @code{AC_TRY_RUN}. The motivations where:
17831 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
17832 quoting their arguments;
17835 the combinatoric explosion is solved by decomposing on the one hand the
17836 generation of sources, and on the other hand executing the program;
17839 this scheme helps supporting more languages than plain C and C++.
17842 In addition to the change of syntax, the philosophy has changed too:
17843 while emphasis was put on speed at the expense of accuracy, today's
17844 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
17848 As a perfect example of what is @emph{not} to be done, here is how to
17849 find out whether a header file contains a particular declaration, such
17850 as a typedef, a structure, a structure member, or a function. Use
17851 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
17852 header file; on some systems the symbol might be defined in another
17853 header file that the file you are checking includes.
17855 As a (bad) example, here is how you should not check for C preprocessor
17856 symbols, either defined by header files or predefined by the C
17857 preprocessor: using @code{AC_EGREP_CPP}:
17865 ], is_aix=yes, is_aix=no)
17869 The above example, properly written would (i) use
17870 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
17874 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
17876 error: This isn't AIX!
17885 @c ============================= Generating Test Suites with Autotest
17887 @node Using Autotest
17888 @chapter Generating Test Suites with Autotest
17893 @strong{N.B.: This section describes an experimental feature which will
17894 be part of Autoconf in a forthcoming release. Although we believe
17895 Autotest is stabilizing, this documentation describes an interface which
17896 might change in the future: do not depend upon Autotest without
17897 subscribing to the Autoconf mailing lists.}
17900 It is paradoxical that portable projects depend on nonportable tools
17901 to run their test suite. Autoconf by itself is the paragon of this
17902 problem: although it aims at perfectly portability, up to 2.13 its
17903 test suite was using Deja@acronym{GNU}, a rich and complex testing
17904 framework, but which is far from being standard on Posix systems.
17905 Worse yet, it was likely to be missing on the most fragile platforms,
17906 the very platforms that are most likely to torture Autoconf and
17907 exhibit deficiencies.
17909 To circumvent this problem, many package maintainers have developed their
17910 own testing framework, based on simple shell scripts whose sole outputs
17911 are exit status values describing whether the test succeeded. Most of
17912 these tests share common patterns, and this can result in lots of
17913 duplicated code and tedious maintenance.
17915 Following exactly the same reasoning that yielded to the inception of
17916 Autoconf, Autotest provides a test suite generation framework, based on
17917 M4 macros building a portable shell script. The suite itself is
17918 equipped with automatic logging and tracing facilities which greatly
17919 diminish the interaction with bug reporters, and simple timing reports.
17921 Autoconf itself has been using Autotest for years, and we do attest that
17922 it has considerably improved the strength of the test suite and the
17923 quality of bug reports. Other projects are known to use some generation
17924 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
17925 them with different needs, and this usage has validated Autotest as a general
17928 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
17929 interactive tool testing, which is probably its main limitation.
17932 * Using an Autotest Test Suite:: Autotest and the user
17933 * Writing Testsuites:: Autotest macros
17934 * testsuite Invocation:: Running @command{testsuite} scripts
17935 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
17938 @node Using an Autotest Test Suite
17939 @section Using an Autotest Test Suite
17942 * testsuite Scripts:: The concepts of Autotest
17943 * Autotest Logs:: Their contents
17946 @node testsuite Scripts
17947 @subsection @command{testsuite} Scripts
17949 @cindex @command{testsuite}
17951 Generating testing or validation suites using Autotest is rather easy.
17952 The whole validation suite is held in a file to be processed through
17953 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
17954 produce a stand-alone Bourne shell script which then gets distributed.
17955 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
17956 the installer's end.
17959 Each test of the validation suite should be part of some test group. A
17960 @dfn{test group} is a sequence of interwoven tests that ought to be
17961 executed together, usually because one test in the group creates data
17962 files than a later test in the same group needs to read. Complex test
17963 groups make later debugging more tedious. It is much better to
17964 keep only a few tests per test group. Ideally there is only one test
17967 For all but the simplest packages, some file such as @file{testsuite.at}
17968 does not fully hold all test sources, as these are often easier to
17969 maintain in separate files. Each of these separate files holds a single
17970 test group, or a sequence of test groups all addressing some common
17971 functionality in the package. In such cases, @file{testsuite.at}
17972 merely initializes the validation suite, and sometimes does elementary
17973 health checking, before listing include statements for all other test
17974 files. The special file @file{package.m4}, containing the
17975 identification of the package, is automatically included if found.
17977 A convenient alternative consists in moving all the global issues
17978 (local Autotest macros, elementary health checking, and @code{AT_INIT}
17979 invocation) into the file @code{local.at}, and making
17980 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
17981 suites. In such case, generating the whole test suite or pieces of it
17982 is only a matter of choosing the @command{autom4te} command line
17985 The validation scripts that Autotest produces are by convention called
17986 @command{testsuite}. When run, @command{testsuite} executes each test
17987 group in turn, producing only one summary line per test to say if that
17988 particular test succeeded or failed. At end of all tests, summarizing
17989 counters get printed. One debugging directory is left for each test
17990 group which failed, if any: such directories are named
17991 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
17992 the test group, and they include:
17995 @item a debugging script named @file{run} which reruns the test in
17996 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
17997 of debugging scripts has the purpose of easing the chase for bugs.
17999 @item all the files created with @code{AT_DATA}
18001 @item a log of the run, named @file{testsuite.log}
18004 In the ideal situation, none of the tests fail, and consequently no
18005 debugging directory is left behind for validation.
18007 It often happens in practice that individual tests in the validation
18008 suite need to get information coming out of the configuration process.
18009 Some of this information, common for all validation suites, is provided
18010 through the file @file{atconfig}, automatically created by
18011 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
18012 testing environment specifically needs, you might prepare an optional
18013 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
18014 The configuration process produces @file{atconfig} and @file{atlocal}
18015 out of these two input files, and these two produced files are
18016 automatically read by the @file{testsuite} script.
18018 Here is a diagram showing the relationship between files.
18021 Files used in preparing a software package for distribution:
18026 subfile-1.at ->. [local.at] ---->+
18028 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
18034 Files used in configuring a software package:
18039 [atlocal.in] --> config.status* --<
18045 Files created during the test suite execution:
18048 atconfig -->. .--> testsuite.log
18052 [atlocal] ->' `--> [testsuite.dir]
18056 @node Autotest Logs
18057 @subsection Autotest Logs
18059 When run, the test suite creates a log file named after itself, e.g., a
18060 test suite named @command{testsuite} creates @file{testsuite.log}. It
18061 contains a lot of information, usually more than maintainers actually
18062 need, but therefore most of the time it contains all that is needed:
18065 @item command line arguments
18066 @c akim s/to consist in/to consist of/
18067 A bad but unfortunately widespread habit consists of
18068 setting environment variables before the command, such as in
18069 @samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
18070 know this change, hence (i) it cannot report it to you, and (ii)
18071 it cannot preserve the value of @code{CC} for subsequent runs.
18072 Autoconf faced exactly the same problem, and solved it by asking
18073 users to pass the variable definitions as command line arguments.
18074 Autotest requires this rule, too, but has no means to enforce it; the log
18075 then contains a trace of the variables that were changed by the user.
18077 @item @file{ChangeLog} excerpts
18078 The topmost lines of all the @file{ChangeLog} files found in the source
18079 hierarchy. This is especially useful when bugs are reported against
18080 development versions of the package, since the version string does not
18081 provide sufficient information to know the exact state of the sources
18082 the user compiled. Of course, this relies on the use of a
18085 @item build machine
18086 Running a test suite in a cross-compile environment is not an easy task,
18087 since it would mean having the test suite run on a machine @var{build},
18088 while running programs on a machine @var{host}. It is much simpler to
18089 run both the test suite and the programs on @var{host}, but then, from
18090 the point of view of the test suite, there remains a single environment,
18091 @var{host} = @var{build}. The log contains relevant information on the
18092 state of the build machine, including some important environment
18094 @c FIXME: How about having an M4sh macro to say `hey, log the value
18095 @c of `@dots{}'? This would help both Autoconf and Autotest.
18097 @item tested programs
18098 The absolute file name and answers to @option{--version} of the tested
18099 programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
18101 @item configuration log
18102 The contents of @file{config.log}, as created by @command{configure},
18103 are appended. It contains the configuration flags and a detailed report
18104 on the configuration itself.
18108 @node Writing Testsuites
18109 @section Writing @file{testsuite.at}
18111 The @file{testsuite.at} is a Bourne shell script making use of special
18112 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
18113 its beginning followed by one call to @code{m4_include} per source file
18114 for tests. Each such included file, or the remainder of
18115 @file{testsuite.at} if include files are not used, contain a sequence of
18116 test groups. Each test group begins with a call to @code{AT_SETUP},
18117 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
18118 and then completes with a call to @code{AT_CLEANUP}.
18120 @defmac AT_INIT (@ovar{name})
18122 @c FIXME: Not clear, plus duplication of the information.
18123 Initialize Autotest. Giving a @var{name} to the test suite is
18124 encouraged if your package includes several test suites. In any case,
18125 the test suite always displays the package name and version. It also
18126 inherits the package bug report address.
18129 @defmac AT_COPYRIGHT (@var{copyright-notice})
18130 @atindex{COPYRIGHT}
18131 @cindex Copyright Notice
18132 State that, in addition to the Free Software Foundation's copyright on
18133 the Autotest macros, parts of your test suite are covered by
18134 @var{copyright-notice}.
18136 The @var{copyright-notice} shows up in both the head of
18137 @command{testsuite} and in @samp{testsuite --version}.
18140 @defmac AT_TESTED (@var{executables})
18142 Log the file name and answer to @option{--version} of each program in
18143 space-separated list @var{executables}. Several invocations register
18144 new executables, in other words, don't fear registering one program
18148 Autotest test suites rely on @env{PATH} to find the tested program.
18149 This avoids the need to generate absolute names of the various tools, and
18150 makes it possible to test installed programs. Therefore, knowing which
18151 programs are being exercised is crucial to understanding problems in
18152 the test suite itself, or its occasional misuses. It is a good idea to
18153 also subscribe foreign programs you depend upon, to avoid incompatible
18158 @defmac AT_SETUP (@var{test-group-name})
18160 This macro starts a group of related tests, all to be executed in the
18161 same subshell. It accepts a single argument, which holds a few words
18162 (no more than about 30 or 40 characters) quickly describing the purpose
18163 of the test group being started.
18166 @defmac AT_KEYWORDS (@var{keywords})
18168 Associate the space-separated list of @var{keywords} to the enclosing
18169 test group. This makes it possible to run ``slices'' of the test suite.
18170 For instance, if some of your test groups exercise some @samp{foo}
18171 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
18172 @samp{./testsuite -k foo} to run exclusively these test groups. The
18173 @var{title} of the test group is automatically recorded to
18174 @code{AT_KEYWORDS}.
18176 Several invocations within a test group accumulate new keywords. In
18177 other words, don't fear registering the same keyword several times in a
18181 @defmac AT_CAPTURE_FILE (@var{file})
18182 @atindex{CAPTURE_FILE}
18183 If the current test group fails, log the contents of @var{file}.
18184 Several identical calls within one test group have no additional effect.
18187 @defmac AT_XFAIL_IF (@var{shell-condition})
18189 Determine whether the test is expected to fail because it is a known
18190 bug (for unsupported features, you should skip the test).
18191 @var{shell-condition} is a shell expression such as a @code{test}
18192 command; you can instantiate this macro many times from within the
18193 same test group, and one of the conditions is enough to turn
18194 the test into an expected failure.
18199 End the current test group.
18204 @defmac AT_DATA (@var{file}, @var{contents})
18206 Initialize an input data @var{file} with given @var{contents}. Of
18207 course, the @var{contents} have to be properly quoted between square
18208 brackets to protect against included commas or spurious M4
18209 expansion. The contents ought to end with an end of line.
18212 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass})
18214 Execute a test by performing given shell @var{commands}. These commands
18215 should normally exit with @var{status}, while producing expected
18216 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
18217 status 77, then the whole test group is skipped. Otherwise, if this test
18218 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
18219 commands @var{run-if-pass}.
18221 The @var{commands} @emph{must not} redirect the standard output, nor the
18224 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
18225 the corresponding value is not checked.
18227 The special value @samp{expout} for @var{stdout} means the expected
18228 output of the @var{commands} is the content of the file @file{expout}.
18229 If @var{stdout} is @samp{stdout}, then the standard output of the
18230 @var{commands} is available for further tests in the file @file{stdout}.
18231 Similarly for @var{stderr} with @samp{experr} and @samp{stderr}.
18235 @node testsuite Invocation
18236 @section Running @command{testsuite} Scripts
18237 @cindex @command{testsuite}
18239 Autotest test suites support the following arguments:
18244 Display the list of options and exit successfully.
18248 Display the version of the test suite and exit successfully.
18252 Remove all the files the test suite might have created and exit. Meant
18253 for @code{clean} Make targets.
18257 List all the tests (or only the selection), including their possible
18263 By default all tests are performed (or described with
18264 @option{--list}) in the default environment first silently, then
18265 verbosely, but the environment, set of tests, and verbosity level can be
18269 @item @var{variable}=@var{value}
18270 Set the environment @var{variable} to @var{value}. Use this rather
18271 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
18272 different environment.
18274 @cindex @code{AUTOTEST_PATH}
18275 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
18276 to @env{PATH}. Relative directory names (not starting with
18277 @samp{/}) are considered to be relative to the top level of the
18278 package being built. All directories are made absolute, first
18279 starting from the top level @emph{build} tree, then from the
18280 @emph{source} tree. For instance @samp{./testsuite
18281 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
18282 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
18283 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
18287 @itemx @var{number}-@var{number}
18288 @itemx @var{number}-
18289 @itemx -@var{number}
18290 Add the corresponding test groups, with obvious semantics, to the
18293 @item --keywords=@var{keywords}
18294 @itemx -k @var{keywords}
18295 Add to the selection the test groups with title or keywords (arguments
18296 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
18297 of the comma separated list @var{keywords}, case-insensitively. Use
18298 @samp{!} immediately before the keyword to invert the selection for this
18299 keyword. By default, the keywords match whole words; enclose them in
18300 @samp{.*} to also match parts of words.
18302 For example, running
18305 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
18309 selects all tests tagged @samp{autoupdate} @emph{and} with tags
18310 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
18314 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
18318 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
18319 containing @samp{FUNC}.
18323 If any test fails, immediately abort testing. It implies
18324 @option{--debug}: post test group clean up, and top-level logging
18325 are inhibited. This option is meant for the full test
18326 suite, it is not really useful for generated debugging scripts.
18330 Force more verbosity in the detailed output of what is being done. This
18331 is the default for debugging scripts.
18335 Do not remove the files after a test group was performed ---but they are
18336 still removed @emph{before}, therefore using this option is sane when
18337 running several test groups. Create debugging scripts. Do not
18338 overwrite the top-level
18339 log (in order to preserve supposedly existing full log file). This is
18340 the default for debugging scripts, but it can also be useful to debug
18341 the testsuite itself.
18345 Trigger shell tracing of the test groups.
18349 @node Making testsuite Scripts
18350 @section Making @command{testsuite} Scripts
18352 For putting Autotest into movement, you need some configuration and
18353 makefile machinery. We recommend, at least if your package uses deep or
18354 shallow hierarchies, that you use @file{tests/} as the name of the
18355 directory holding all your tests and their makefile. Here is a
18356 check list of things to do.
18361 @cindex @file{package.m4}
18362 Make sure to create the file @file{package.m4}, which defines the
18363 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
18364 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
18365 address to which bug reports should be sent. For sake of completeness,
18366 we suggest that you also define @code{AT_PACKAGE_NAME},
18367 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
18368 @xref{Initializing configure}, for a description of these variables. We
18369 suggest the following makefile excerpt:
18372 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
18374 echo '# Signature of the current package.'; \
18375 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
18376 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
18377 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
18378 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
18379 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
18380 @} >'$(srcdir)/package.m4'
18384 Be sure to distribute @file{package.m4} and to put it into the source
18385 hierarchy: the test suite ought to be shipped!
18388 Invoke @code{AC_CONFIG_TESTDIR}.
18390 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
18391 @acindex{CONFIG_TESTDIR}
18392 An Autotest test suite is to be configured in @var{directory}. This
18393 macro requires the instantiation of @file{@var{directory}/atconfig} from
18394 @file{@var{directory}/atconfig.in}, and sets the default
18395 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
18399 Still within @file{configure.ac}, as appropriate, ensure that some
18400 @code{AC_CONFIG_FILES} command includes substitution for
18401 @file{tests/atlocal}.
18404 The @file{tests/Makefile.in} should be modified so the validation in
18405 your package is triggered by @samp{make check}. An example is provided
18409 With Automake, here is a minimal example about how to link @samp{make
18410 check} with a validation suite.
18413 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
18414 TESTSUITE = $(srcdir)/testsuite
18416 check-local: atconfig atlocal $(TESTSUITE)
18417 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
18419 installcheck-local: atconfig atlocal $(TESTSUITE)
18420 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
18424 test ! -f '$(TESTSUITE)' || \
18425 $(SHELL) '$(TESTSUITE)' --clean
18427 AUTOTEST = $(AUTOM4TE) --language=autotest
18428 $(TESTSUITE): $(srcdir)/testsuite.at
18429 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
18433 You might want to list explicitly the dependencies, i.e., the list of
18434 the files @file{testsuite.at} includes.
18436 With strict Autoconf, you might need to add lines inspired from the
18442 atconfig: $(top_builddir)/config.status
18443 cd $(top_builddir) && \
18444 $(SHELL) ./config.status $(subdir)/$@@
18446 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
18447 cd $(top_builddir) && \
18448 $(SHELL) ./config.status $(subdir)/$@@
18452 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
18455 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
18456 within your makefile, you can fine-tune test suite execution with this variable,
18460 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
18465 @c =============================== Frequent Autoconf Questions, with answers
18468 @chapter Frequent Autoconf Questions, with answers
18470 Several questions about Autoconf come up occasionally. Here some of them
18474 * Distributing:: Distributing @command{configure} scripts
18475 * Why GNU M4:: Why not use the standard M4?
18476 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
18477 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
18478 * Defining Directories:: Passing @code{datadir} to program
18479 * Autom4te Cache:: What is it? Can I remove it?
18480 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
18484 @section Distributing @command{configure} Scripts
18488 What are the restrictions on distributing @command{configure}
18489 scripts that Autoconf generates? How does that affect my
18490 programs that use them?
18493 There are no restrictions on how the configuration scripts that Autoconf
18494 produces may be distributed or used. In Autoconf version 1, they were
18495 covered by the @acronym{GNU} General Public License. We still encourage
18496 software authors to distribute their work under terms like those of the
18497 @acronym{GPL}, but doing so is not required to use Autoconf.
18499 Of the other files that might be used with @command{configure},
18500 @file{config.h.in} is under whatever copyright you use for your
18501 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
18502 exception to the @acronym{GPL} when they are used with an Autoconf-generated
18503 @command{configure} script, which permits you to distribute them under the
18504 same terms as the rest of your package. @file{install-sh} is from the X
18505 Consortium and is not copyrighted.
18508 @section Why Require @acronym{GNU} M4?
18511 Why does Autoconf require @acronym{GNU} M4?
18514 Many M4 implementations have hard-coded limitations on the size and
18515 number of macros that Autoconf exceeds. They also lack several
18516 builtin macros that it would be difficult to get along without in a
18517 sophisticated application like Autoconf, including:
18527 Autoconf requires version 1.4.7 or later of @acronym{GNU} M4.
18529 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
18530 M4 is simple to configure and install, it seems reasonable to require
18531 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
18532 other free software already have most of the @acronym{GNU} utilities
18533 installed, since they prefer them.
18535 @node Bootstrapping
18536 @section How Can I Bootstrap?
18540 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
18541 @command{configure} script, how do I bootstrap? It seems like a chicken
18545 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
18546 @command{configure} script produced by Autoconf, Autoconf is not required
18547 in order to run the script and install @acronym{GNU} M4. Autoconf is only
18548 required if you want to change the M4 @command{configure} script, which few
18549 people have to do (mainly its maintainer).
18551 @node Why Not Imake
18552 @section Why Not Imake?
18556 Why not use Imake instead of @command{configure} scripts?
18559 Several people have written addressing this question, so I include
18560 adaptations of their explanations here.
18562 The following answer is based on one written by Richard Pixley:
18565 Autoconf generated scripts frequently work on machines that it has
18566 never been set up to handle before. That is, it does a good job of
18567 inferring a configuration for a new system. Imake cannot do this.
18569 Imake uses a common database of host specific data. For X11, this makes
18570 sense because the distribution is made as a collection of tools, by one
18571 central authority who has control over the database.
18573 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
18574 maintainer; these maintainers are scattered across the world. Using a
18575 common database would be a maintenance nightmare. Autoconf may appear
18576 to be this kind of database, but in fact it is not. Instead of listing
18577 host dependencies, it lists program requirements.
18579 If you view the @acronym{GNU} suite as a collection of native tools, then the
18580 problems are similar. But the @acronym{GNU} development tools can be
18581 configured as cross tools in almost any host+target permutation. All of
18582 these configurations can be installed concurrently. They can even be
18583 configured to share host independent files across hosts. Imake doesn't
18584 address these issues.
18586 Imake templates are a form of standardization. The @acronym{GNU} coding
18587 standards address the same issues without necessarily imposing the same
18592 Here is some further explanation, written by Per Bothner:
18595 One of the advantages of Imake is that it easy to generate large
18596 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
18597 However, @code{cpp} is not programmable: it has limited conditional
18598 facilities, and no looping. And @code{cpp} cannot inspect its
18601 All of these problems are solved by using @code{sh} instead of
18602 @code{cpp}. The shell is fully programmable, has macro substitution,
18603 can execute (or source) other shell scripts, and can inspect its
18608 Paul Eggert elaborates more:
18611 With Autoconf, installers need not assume that Imake itself is already
18612 installed and working well. This may not seem like much of an advantage
18613 to people who are accustomed to Imake. But on many hosts Imake is not
18614 installed or the default installation is not working well, and requiring
18615 Imake to install a package hinders the acceptance of that package on
18616 those hosts. For example, the Imake template and configuration files
18617 might not be installed properly on a host, or the Imake build procedure
18618 might wrongly assume that all source files are in one big directory
18619 tree, or the Imake configuration might assume one compiler whereas the
18620 package or the installer needs to use another, or there might be a
18621 version mismatch between the Imake expected by the package and the Imake
18622 supported by the host. These problems are much rarer with Autoconf,
18623 where each package comes with its own independent configuration
18626 Also, Imake often suffers from unexpected interactions between
18627 @command{make} and the installer's C preprocessor. The fundamental problem
18628 here is that the C preprocessor was designed to preprocess C programs,
18629 not makefiles. This is much less of a problem with Autoconf,
18630 which uses the general-purpose preprocessor M4, and where the
18631 package's author (rather than the installer) does the preprocessing in a
18636 Finally, Mark Eichin notes:
18639 Imake isn't all that extensible, either. In order to add new features to
18640 Imake, you need to provide your own project template, and duplicate most
18641 of the features of the existing one. This means that for a sophisticated
18642 project, using the vendor-provided Imake templates fails to provide any
18643 leverage---since they don't cover anything that your own project needs
18644 (unless it is an X11 program).
18646 On the other side, though:
18648 The one advantage that Imake has over @command{configure}:
18649 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
18650 than @file{Makefile.in} files. There is a fix to this, however---at least
18651 for the Kerberos V5 tree, we've modified things to call in common
18652 @file{post.in} and @file{pre.in} makefile fragments for the
18653 entire tree. This means that a lot of common things don't have to be
18654 duplicated, even though they normally are in @command{configure} setups.
18658 @node Defining Directories
18659 @section How Do I @code{#define} Installation Directories?
18662 My program needs library files, installed in @code{datadir} and
18666 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
18667 [Define to the read-only architecture-independent
18675 #define DATADIR "$@{prefix@}/share"
18679 As already explained, this behavior is on purpose, mandated by the
18680 @acronym{GNU} Coding Standards, see @ref{Installation Directory
18681 Variables}. There are several means to achieve a similar goal:
18685 Do not use @code{AC_DEFINE} but use your makefile to pass the
18686 actual value of @code{datadir} via compilation flags.
18687 @xref{Installation Directory Variables}, for the details.
18690 This solution can be simplified when compiling a program: you may either
18691 extend the @code{CPPFLAGS}:
18694 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
18698 or create a dedicated header file:
18701 DISTCLEANFILES = datadir.h
18702 datadir.h: Makefile
18703 echo '#define DATADIR "$(datadir)"' >$@@
18707 Use @code{AC_DEFINE} but have @command{configure} compute the literal
18708 value of @code{datadir} and others. Many people have wrapped macros to
18709 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
18710 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
18713 This solution does not conform to the @acronym{GNU} Coding Standards.
18716 Note that all the previous solutions hard wire the absolute name of
18717 these directories in the executables, which is not a good property. You
18718 may try to compute the names relative to @code{prefix}, and try to
18719 find @code{prefix} at runtime, this way your package is relocatable.
18720 Some macros are already available to address this issue: see
18721 @code{adl_COMPUTE_RELATIVE_PATHS} and
18722 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
18723 @uref{http://autoconf-archive.cryp.to/,
18724 Autoconf Macro Archive}.
18728 @node Autom4te Cache
18729 @section What is @file{autom4te.cache}?
18732 What is this directory @file{autom4te.cache}? Can I safely remove it?
18735 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
18736 role and is read by many tools: @command{autoconf} to create
18737 @file{configure}, @command{autoheader} to create @file{config.h.in},
18738 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
18739 check the completeness of @file{configure.ac}, @command{autoreconf} to
18740 check the @acronym{GNU} Build System components that are used. To
18741 ``read @file{configure.ac}'' actually means to compile it with M4,
18742 which can be a long process for complex @file{configure.ac}.
18744 This is why all these tools, instead of running directly M4, invoke
18745 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
18746 a specific demand, stores additional information in
18747 @file{autom4te.cache} for future runs. For instance, if you run
18748 @command{autoconf}, behind the scenes, @command{autom4te} also
18749 stores information for the other tools, so that when you invoke
18750 @command{autoheader} or @command{automake} etc., reprocessing
18751 @file{configure.ac} is not needed. The speed up is frequently of 30%,
18752 and is increasing with the size of @file{configure.ac}.
18754 But it is and remains being simply a cache: you can safely remove it.
18759 Can I permanently get rid of it?
18762 The creation of this cache can be disabled from
18763 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
18764 details. You should be aware that disabling the cache slows down the
18765 Autoconf test suite by 40%. The more @acronym{GNU} Build System
18766 components are used, the more the cache is useful; for instance
18767 running @samp{autoreconf -f} on the Core Utilities is twice slower without
18768 the cache @emph{although @option{--force} implies that the cache is
18769 not fully exploited}, and eight times slower than without
18773 @node Present But Cannot Be Compiled
18774 @section Header Present But Cannot Be Compiled
18776 The most important guideline to bear in mind when checking for
18777 features is to mimic as much as possible the intended use.
18778 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
18779 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
18780 the preprocessor, instead of the compiler, to check for headers. As a
18781 result, incompatibilities between headers went unnoticed during
18782 configuration, and maintainers finally had to deal with this issue
18785 As of Autoconf 2.56 both checks are performed, and @code{configure}
18786 complains loudly if the compiler and the preprocessor do not agree.
18787 For the time being the result used is that of the preprocessor, to give
18788 maintainers time to adjust their @file{configure.ac}, but in the
18789 future, only the compiler will be considered.
18791 Consider the following example:
18794 $ @kbd{cat number.h}
18795 typedef int number;
18797 const number pi = 3;
18798 $ @kbd{cat configure.ac}
18799 AC_INIT([Example], [1.0], [bug-example@@example.org])
18800 AC_CHECK_HEADERS([pi.h])
18801 $ @kbd{autoconf -Wall}
18802 $ @kbd{./configure}
18803 checking for gcc... gcc
18804 checking for C compiler default output file name... a.out
18805 checking whether the C compiler works... yes
18806 checking whether we are cross compiling... no
18807 checking for suffix of executables...
18808 checking for suffix of object files... o
18809 checking whether we are using the GNU C compiler... yes
18810 checking whether gcc accepts -g... yes
18811 checking for gcc option to accept ISO C89... none needed
18812 checking how to run the C preprocessor... gcc -E
18813 checking for grep that handles long lines and -e... grep
18814 checking for egrep... grep -E
18815 checking for ANSI C header files... yes
18816 checking for sys/types.h... yes
18817 checking for sys/stat.h... yes
18818 checking for stdlib.h... yes
18819 checking for string.h... yes
18820 checking for memory.h... yes
18821 checking for strings.h... yes
18822 checking for inttypes.h... yes
18823 checking for stdint.h... yes
18824 checking for unistd.h... yes
18825 checking pi.h usability... no
18826 checking pi.h presence... yes
18827 configure: WARNING: pi.h: present but cannot be compiled
18828 configure: WARNING: pi.h: check for missing prerequisite headers?
18829 configure: WARNING: pi.h: see the Autoconf documentation
18830 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
18831 configure: WARNING: pi.h: proceeding with the preprocessor's result
18832 configure: WARNING: pi.h: in the future, the compiler will take precedence
18833 configure: WARNING: ## -------------------------------------- ##
18834 configure: WARNING: ## Report this to bug-example@@example.org ##
18835 configure: WARNING: ## -------------------------------------- ##
18836 checking for pi.h... yes
18840 The proper way the handle this case is using the fourth argument
18841 (@pxref{Generic Headers}):
18844 $ @kbd{cat configure.ac}
18845 AC_INIT([Example], [1.0], [bug-example@@example.org])
18846 AC_CHECK_HEADERS([number.h pi.h], [], [],
18847 [[#ifdef HAVE_NUMBER_H
18848 # include <number.h>
18851 $ @kbd{autoconf -Wall}
18852 $ @kbd{./configure}
18853 checking for gcc... gcc
18854 checking for C compiler default output... a.out
18855 checking whether the C compiler works... yes
18856 checking whether we are cross compiling... no
18857 checking for suffix of executables...
18858 checking for suffix of object files... o
18859 checking whether we are using the GNU C compiler... yes
18860 checking whether gcc accepts -g... yes
18861 checking for gcc option to accept ANSI C... none needed
18862 checking for number.h... yes
18863 checking for pi.h... yes
18866 See @ref{Particular Headers}, for a list of headers with their
18869 @c ===================================================== History of Autoconf.
18872 @chapter History of Autoconf
18873 @cindex History of autoconf
18875 You may be wondering, Why was Autoconf originally written? How did it
18876 get into its present form? (Why does it look like gorilla spit?) If
18877 you're not wondering, then this chapter contains no information useful
18878 to you, and you might as well skip it. If you @emph{are} wondering,
18879 then let there be light@enddots{}
18882 * Genesis:: Prehistory and naming of @command{configure}
18883 * Exodus:: The plagues of M4 and Perl
18884 * Leviticus:: The priestly code of portability arrives
18885 * Numbers:: Growth and contributors
18886 * Deuteronomy:: Approaching the promises of easy configuration
18892 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
18893 Free Software Foundation. As they were ported to more platforms and
18894 more programs were added, the number of @option{-D} options that users
18895 had to select in the makefile (around 20) became burdensome.
18896 Especially for me---I had to test each new release on a bunch of
18897 different systems. So I wrote a little shell script to guess some of
18898 the correct settings for the fileutils package, and released it as part
18899 of fileutils 2.0. That @command{configure} script worked well enough that
18900 the next month I adapted it (by hand) to create similar @command{configure}
18901 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
18902 also adapted one of my scripts for his @acronym{CVS} revision control system.
18904 Later that summer, I learned that Richard Stallman and Richard Pixley
18905 were developing similar scripts to use in the @acronym{GNU} compiler tools;
18906 so I adapted my @command{configure} scripts to support their evolving
18907 interface: using the file name @file{Makefile.in} as the templates;
18908 adding @samp{+srcdir}, the first option (of many); and creating
18909 @file{config.status} files.
18914 As I got feedback from users, I incorporated many improvements, using
18915 Emacs to search and replace, cut and paste, similar changes in each of
18916 the scripts. As I adapted more @acronym{GNU} utilities packages to use
18917 @command{configure} scripts, updating them all by hand became impractical.
18918 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
18919 mail saying that the @command{configure} scripts were great, and asking if
18920 I had a tool for generating them that I could send him. No, I thought,
18921 but I should! So I started to work out how to generate them. And the
18922 journey from the slavery of hand-written @command{configure} scripts to the
18923 abundance and ease of Autoconf began.
18925 Cygnus @command{configure}, which was being developed at around that time,
18926 is table driven; it is meant to deal mainly with a discrete number of
18927 system types with a small number of mainly unguessable features (such as
18928 details of the object file format). The automatic configuration system
18929 that Brian Fox had developed for Bash takes a similar approach. For
18930 general use, it seems to me a hopeless cause to try to maintain an
18931 up-to-date database of which features each variant of each operating
18932 system has. It's easier and more reliable to check for most features on
18933 the fly---especially on hybrid systems that people have hacked on
18934 locally or that have patches from vendors installed.
18936 I considered using an architecture similar to that of Cygnus
18937 @command{configure}, where there is a single @command{configure} script that
18938 reads pieces of @file{configure.in} when run. But I didn't want to have
18939 to distribute all of the feature tests with every package, so I settled
18940 on having a different @command{configure} made from each
18941 @file{configure.in} by a preprocessor. That approach also offered more
18942 control and flexibility.
18944 I looked briefly into using the Metaconfig package, by Larry Wall,
18945 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
18946 reasons. The @command{Configure} scripts it produces are interactive,
18947 which I find quite inconvenient; I didn't like the ways it checked for
18948 some features (such as library functions); I didn't know that it was
18949 still being maintained, and the @command{Configure} scripts I had
18950 seen didn't work on many modern systems (such as System V R4 and NeXT);
18951 it wasn't flexible in what it could do in response to a feature's
18952 presence or absence; I found it confusing to learn; and it was too big
18953 and complex for my needs (I didn't realize then how much Autoconf would
18954 eventually have to grow).
18956 I considered using Perl to generate my style of @command{configure}
18957 scripts, but decided that M4 was better suited to the job of simple
18958 textual substitutions: it gets in the way less, because output is
18959 implicit. Plus, everyone already has it. (Initially I didn't rely on
18960 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
18961 University of Maryland had recently been putting M4 front ends on
18962 several programs, including @code{tvtwm}, and I was interested in trying
18963 out a new language.
18968 Since my @command{configure} scripts determine the system's capabilities
18969 automatically, with no interactive user intervention, I decided to call
18970 the program that generates them Autoconfig. But with a version number
18971 tacked on, that name would be too long for old Unix file systems,
18972 so I shortened it to Autoconf.
18974 In the fall of 1991 I called together a group of fellow questers after
18975 the Holy Grail of portability (er, that is, alpha testers) to give me
18976 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
18977 and continued to add features and improve the techniques used in the
18978 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
18979 with the idea of making an Autoconf shell script to run M4
18980 and check for unresolved macro calls; Richard Pixley, who suggested
18981 running the compiler instead of searching the file system to find
18982 include files and symbols, for more accurate results; Karl Berry, who
18983 got Autoconf to configure @TeX{} and added the macro index to the
18984 documentation; and Ian Lance Taylor, who added support for creating a C
18985 header file as an alternative to putting @option{-D} options in a
18986 makefile, so he could use Autoconf for his @acronym{UUCP} package.
18987 The alpha testers cheerfully adjusted their files again and again as the
18988 names and calling conventions of the Autoconf macros changed from
18989 release to release. They all contributed many specific checks, great
18990 ideas, and bug fixes.
18995 In July 1992, after months of alpha testing, I released Autoconf 1.0,
18996 and converted many @acronym{GNU} packages to use it. I was surprised by how
18997 positive the reaction to it was. More people started using it than I
18998 could keep track of, including people working on software that wasn't
18999 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
19000 Autoconf continued to improve rapidly, as many people using the
19001 @command{configure} scripts reported problems they encountered.
19003 Autoconf turned out to be a good torture test for M4 implementations.
19004 Unix M4 started to dump core because of the length of the
19005 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
19006 M4 as well. Eventually, we realized that we needed to use some
19007 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
19008 particular, has an impoverished set of builtin macros; the System V
19009 version is better, but still doesn't provide everything we need.
19011 More development occurred as people put Autoconf under more stresses
19012 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
19013 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
19014 invalid arguments. Jim Blandy bravely coerced it into configuring
19015 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
19016 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
19017 @command{autoheader} script to automate the creation of C header file
19018 templates, and added a @option{--verbose} option to @command{configure}.
19019 Noah Friedman added the @option{--autoconf-dir} option and
19020 @code{AC_MACRODIR} environment variable. (He also coined the term
19021 @dfn{autoconfiscate} to mean ``adapt a software package to use
19022 Autoconf''.) Roland and Noah improved the quoting protection in
19023 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
19024 dealing with portability problems from February through June, 1993.
19027 @section Deuteronomy
19029 A long wish list for major features had accumulated, and the effect of
19030 several years of patching by various people had left some residual
19031 cruft. In April 1994, while working for Cygnus Support, I began a major
19032 revision of Autoconf. I added most of the features of the Cygnus
19033 @command{configure} that Autoconf had lacked, largely by adapting the
19034 relevant parts of Cygnus @command{configure} with the help of david zuhn
19035 and Ken Raeburn. These features include support for using
19036 @file{config.sub}, @file{config.guess}, @option{--host}, and
19037 @option{--target}; making links to files; and running @command{configure}
19038 scripts in subdirectories. Adding these features enabled Ken to convert
19039 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
19042 I added more features in response to other peoples' requests. Many
19043 people had asked for @command{configure} scripts to share the results of
19044 the checks between runs, because (particularly when configuring a large
19045 source tree, like Cygnus does) they were frustratingly slow. Mike
19046 Haertel suggested adding site-specific initialization scripts. People
19047 distributing software that had to unpack on MS-DOS asked for a way to
19048 override the @file{.in} extension on the file names, which produced file
19049 names like @file{config.h.in} containing two dots. Jim Avera did an
19050 extensive examination of the problems with quoting in @code{AC_DEFINE}
19051 and @code{AC_SUBST}; his insights led to significant improvements.
19052 Richard Stallman asked that compiler output be sent to @file{config.log}
19053 instead of @file{/dev/null}, to help people debug the Emacs
19054 @command{configure} script.
19056 I made some other changes because of my dissatisfaction with the quality
19057 of the program. I made the messages showing results of the checks less
19058 ambiguous, always printing a result. I regularized the names of the
19059 macros and cleaned up coding style inconsistencies. I added some
19060 auxiliary utilities that I had developed to help convert source code
19061 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
19062 the macros not interrupt each others' messages. (That feature revealed
19063 some performance bottlenecks in @acronym{GNU} M4, which he hastily
19064 corrected!) I reorganized the documentation around problems people want
19065 to solve. And I began a test suite, because experience had shown that
19066 Autoconf has a pronounced tendency to regress when we change it.
19068 Again, several alpha testers gave invaluable feedback, especially
19069 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
19072 Finally, version 2.0 was ready. And there was much rejoicing. (And I
19073 have free time again. I think. Yeah, right.)
19076 @c ========================================================== Appendices
19078 @node Copying This Manual
19079 @appendix Copying This Manual
19083 * GNU Free Documentation License:: License for copying this manual
19092 * Environment Variable Index:: Index of environment variables used
19093 * Output Variable Index:: Index of variables set in output files
19094 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
19095 * Autoconf Macro Index:: Index of Autoconf macros
19096 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
19097 * Autotest Macro Index:: Index of Autotest macros
19098 * Program & Function Index:: Index of those with portability problems
19099 * Concept Index:: General index
19102 @node Environment Variable Index
19103 @appendixsec Environment Variable Index
19105 This is an alphabetical list of the environment variables that Autoconf
19110 @node Output Variable Index
19111 @appendixsec Output Variable Index
19113 This is an alphabetical list of the variables that Autoconf can
19114 substitute into files that it creates, typically one or more
19115 makefiles. @xref{Setting Output Variables}, for more information
19116 on how this is done.
19120 @node Preprocessor Symbol Index
19121 @appendixsec Preprocessor Symbol Index
19123 This is an alphabetical list of the C preprocessor symbols that the
19124 Autoconf macros define. To work with Autoconf, C source code needs to
19125 use these names in @code{#if} or @code{#ifdef} directives.
19129 @node Autoconf Macro Index
19130 @appendixsec Autoconf Macro Index
19132 This is an alphabetical list of the Autoconf macros.
19133 @ifset shortindexflag
19134 To make the list easier to use, the macros are listed without their
19135 preceding @samp{AC_}.
19140 @node M4 Macro Index
19141 @appendixsec M4 Macro Index
19143 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
19144 @ifset shortindexflag
19145 To make the list easier to use, the macros are listed without their
19146 preceding @samp{m4_} or @samp{AS_}.
19151 @node Autotest Macro Index
19152 @appendixsec Autotest Macro Index
19154 This is an alphabetical list of the Autotest macros.
19155 @ifset shortindexflag
19156 To make the list easier to use, the macros are listed without their
19157 preceding @samp{AT_}.
19162 @node Program & Function Index
19163 @appendixsec Program and Function Index
19165 This is an alphabetical list of the programs and functions which
19166 portability is discussed in this document.
19170 @node Concept Index
19171 @appendixsec Concept Index
19173 This is an alphabetical list of the files, tools, and concepts
19174 introduced in this document.
19180 @c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
19181 @c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
19182 @c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
19183 @c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
19184 @c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
19185 @c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
19186 @c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
19187 @c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
19188 @c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
19189 @c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
19190 @c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
19191 @c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
19192 @c LocalWords: distclean uninstall noindent versioning Tromey dir
19193 @c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
19194 @c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
19195 @c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
19196 @c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
19197 @c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
19198 @c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
19199 @c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
19200 @c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
19201 @c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
19202 @c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
19203 @c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
19204 @c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
19205 @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
19206 @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
19207 @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
19208 @c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
19209 @c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
19210 @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
19211 @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
19212 @c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
19213 @c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
19214 @c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
19215 @c LocalWords: GETLODAVG SETGID getloadavg nlist GETMNTENT irix
19216 @c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
19217 @c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
19218 @c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
19219 @c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
19220 @c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
19221 @c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
19222 @c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
19223 @c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
19224 @c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS autom GCC's kB
19225 @c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
19226 @c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
19227 @c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
19228 @c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
19229 @c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
19230 @c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae Onolimit conftest AXP str
19231 @c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
19232 @c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
19233 @c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
19234 @c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
19235 @c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
19236 @c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
19237 @c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
19238 @c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
19239 @c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
19240 @c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
19241 @c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
19242 @c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
19243 @c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
19244 @c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
19245 @c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
19246 @c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
19247 @c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
19248 @c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
19249 @c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
19250 @c LocalWords: sparc Proulx SysV nbar nfoo maxdepth acdilrtu TWG mc
19251 @c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
19252 @c LocalWords: fooXXXXXX Unicos parenthesization utimes hpux hppa unescaped
19253 @c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
19254 @c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
19255 @c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
19256 @c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
19257 @c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
19258 @c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
19259 @c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
19260 @c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
19261 @c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
19262 @c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
19263 @c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
19264 @c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
19265 @c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
19266 @c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
19267 @c LocalWords: GOBJC OBJCCPP OTP ERLC erl valloc decr dumpdef errprint incr
19268 @c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
19269 @c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
19270 @c LocalWords: Dynix descrips basename aname cname macroexpands xno xcheck
19271 @c LocalWords: LIBREADLINE lreadline lncurses libreadline
19273 @c Local Variables:
19275 @c ispell-local-dictionary: "american"
19276 @c indent-tabs-mode: nil
19277 @c whitespace-check-buffer-indent: nil