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 C and C++:: C and C++ portability pitfalls
266 * Manual Configuration:: Selecting features that can't be guessed
267 * Site Configuration:: Local defaults for @command{configure}
268 * Running configure Scripts:: How to use the Autoconf output
269 * config.status Invocation:: Recreating a configuration
270 * Obsolete Constructs:: Kept for backward compatibility
271 * Using Autotest:: Creating portable test suites
272 * FAQ:: Frequent Autoconf Questions, with answers
273 * History:: History of Autoconf
274 * Copying This Manual:: How to make copies of this manual
275 * Indices:: Indices of symbols, concepts, etc.
278 --- The Detailed Node Listing ---
280 The @acronym{GNU} Build System
282 * Automake:: Escaping Makefile hell
283 * Gnulib:: The @acronym{GNU} portability library
284 * Libtool:: Building libraries portably
285 * Pointers:: More info on the @acronym{GNU} build system
287 Making @command{configure} Scripts
289 * Writing configure.ac:: What to put in an Autoconf input file
290 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
291 * ifnames Invocation:: Listing the conditionals in source code
292 * autoconf Invocation:: How to create configuration scripts
293 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
295 Writing @file{configure.ac}
297 * Shell Script Compiler:: Autoconf as solution of a problem
298 * Autoconf Language:: Programming in Autoconf
299 * configure.ac Layout:: Standard organization of @file{configure.ac}
301 Initialization and Output Files
303 * Initializing configure:: Option processing etc.
304 * Notices:: Copyright, version numbers in @command{configure}
305 * Input:: Where Autoconf should find files
306 * Output:: Outputting results from the configuration
307 * Configuration Actions:: Preparing the output based on results
308 * Configuration Files:: Creating output files
309 * Makefile Substitutions:: Using output variables in @file{Makefile}s
310 * Configuration Headers:: Creating a configuration header file
311 * Configuration Commands:: Running arbitrary instantiation commands
312 * Configuration Links:: Links depending on the configuration
313 * Subdirectories:: Configuring independent packages together
314 * Default Prefix:: Changing the default installation prefix
316 Substitutions in Makefiles
318 * Preset Output Variables:: Output variables that are always set
319 * Installation Directory Variables:: Other preset output variables
320 * Build Directories:: Supporting multiple concurrent compiles
321 * Automatic Remaking:: Makefile rules for configuring
323 Configuration Header Files
325 * Header Templates:: Input for the configuration headers
326 * autoheader Invocation:: How to create configuration templates
327 * Autoheader Macros:: How to specify CPP templates
331 * Common Behavior:: Macros' standard schemes
332 * Alternative Programs:: Selecting between alternative programs
333 * Files:: Checking for the existence of files
334 * Libraries:: Library archives that might be missing
335 * Library Functions:: C library functions that might be missing
336 * Header Files:: Header files that might be missing
337 * Declarations:: Declarations that may be missing
338 * Structures:: Structures or members that might be missing
339 * Types:: Types that might be missing
340 * Compilers and Preprocessors:: Checking for compiling programs
341 * System Services:: Operating system services
342 * Posix Variants:: Special kludges for specific Posix variants
343 * Erlang Libraries:: Checking for the existence of Erlang libraries
347 * Standard Symbols:: Symbols defined by the macros
348 * Default Includes:: Includes used by the generic macros
352 * Particular Programs:: Special handling to find certain programs
353 * Generic Programs:: How to find other programs
357 * Function Portability:: Pitfalls with usual functions
358 * Particular Functions:: Special handling to find certain functions
359 * Generic Functions:: How to find other functions
363 * Header Portability:: Collected knowledge on common headers
364 * Particular Headers:: Special handling to find certain headers
365 * Generic Headers:: How to find other headers
369 * Particular Declarations:: Macros to check for certain declarations
370 * Generic Declarations:: How to find other declarations
374 * Particular Structures:: Macros to check for certain structure members
375 * Generic Structures:: How to find other structure members
379 * Particular Types:: Special handling to find certain types
380 * Generic Types:: How to find other types
382 Compilers and Preprocessors
384 * Specific Compiler Characteristics:: Some portability issues
385 * Generic Compiler Characteristics:: Language independent tests and features
386 * C Compiler:: Checking its characteristics
387 * C++ Compiler:: Likewise
388 * Objective C Compiler:: Likewise
389 * Erlang Compiler and Interpreter:: Likewise
390 * Fortran Compiler:: Likewise
394 * Language Choice:: Selecting which language to use for testing
395 * Writing Test Programs:: Forging source files for compilers
396 * Running the Preprocessor:: Detecting preprocessor symbols
397 * Running the Compiler:: Detecting language or header features
398 * Running the Linker:: Detecting library features
399 * Runtime:: Testing for runtime features
400 * Systemology:: A zoology of operating systems
401 * Multiple Cases:: Tests for several possible values
403 Writing Test Programs
405 * Guidelines:: General rules for writing test programs
406 * Test Functions:: Avoiding pitfalls in test programs
407 * Generating Sources:: Source program boilerplate
411 * Defining Symbols:: Defining C preprocessor symbols
412 * Setting Output Variables:: Replacing variables in output files
413 * Special Chars in Variables:: Characters to beware of in variables
414 * Caching Results:: Speeding up subsequent @command{configure} runs
415 * Printing Messages:: Notifying @command{configure} users
419 * Cache Variable Names:: Shell variables used in caches
420 * Cache Files:: Files @command{configure} uses for caching
421 * Cache Checkpointing:: Loading and saving the cache file
425 * M4 Quotation:: Protecting macros from unwanted expansion
426 * Using autom4te:: The Autoconf executables backbone
427 * Programming in M4sugar:: Convenient pure M4 macros
428 * Programming in M4sh:: Common shell Constructs
429 * File Descriptor Macros:: File descriptor macros for input and output
433 * Active Characters:: Characters that change the behavior of M4
434 * One Macro Call:: Quotation and one macro call
435 * Quotation and Nested Macros:: Macros calling macros
436 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
437 * Quadrigraphs:: Another way to escape special characters
438 * Quotation Rule Of Thumb:: One parenthesis, one quote
440 Using @command{autom4te}
442 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
443 * Customizing autom4te:: Customizing the Autoconf package
445 Programming in M4sugar
447 * Redefined M4 Macros:: M4 builtins changed in M4sugar
448 * Looping constructs:: Iteration in M4
449 * Evaluation Macros:: More quotation and evaluation control
450 * Text processing Macros:: String manipulation in M4
451 * Forbidden Patterns:: Catching unexpanded macros
453 Writing Autoconf Macros
455 * Macro Definitions:: Basic format of an Autoconf macro
456 * Macro Names:: What to call your new macros
457 * Reporting Messages:: Notifying @command{autoconf} users
458 * Dependencies Between Macros:: What to do when macros depend on other macros
459 * Obsoleting Macros:: Warning about old ways of doing things
460 * Coding Style:: Writing Autoconf macros @`a la Autoconf
462 Dependencies Between Macros
464 * Prerequisite Macros:: Ensuring required information
465 * Suggested Ordering:: Warning about possible ordering problems
466 * One-Shot Macros:: Ensuring a macro is called only once
468 Portable Shell Programming
470 * Shellology:: A zoology of shells
471 * Here-Documents:: Quirks and tricks
472 * File Descriptors:: FDs and redirections
473 * File System Conventions:: File names
474 * Shell Substitutions:: Variable and command expansions
475 * Assignments:: Varying side effects of assignments
476 * Parentheses:: Parentheses in shell scripts
477 * Slashes:: Slashes in shell scripts
478 * Special Shell Variables:: Variables you should not change
479 * Limitations of Builtins:: Portable use of not so portable /bin/sh
480 * Limitations of Usual Tools:: Portable use of portable tools
481 * Limitations of Make:: Portable Makefiles
483 Portable C and C++ Programming
485 * Varieties of Unportability:: How to make your programs unportable
486 * Integer Overflow:: When integers get too large
487 * Null Pointers:: Properties of null pointers
488 * Buffer Overruns:: Subscript errors and the like
489 * Floating Point Portability:: Portable floating-point arithmetic
490 * Exiting Portably:: Exiting and the exit status
494 * Specifying Names:: Specifying the system type
495 * Canonicalizing:: Getting the canonical system type
496 * Using System Type:: What to do with the system type
500 * Help Formatting:: Customizing @samp{configure --help}
501 * External Software:: Working with other optional software
502 * Package Options:: Selecting optional features
503 * Pretty Help Strings:: Formatting help string
504 * Site Details:: Configuring site details
505 * Transforming Names:: Changing program names when installing
506 * Site Defaults:: Giving @command{configure} local defaults
508 Transforming Program Names When Installing
510 * Transformation Options:: @command{configure} options to transform names
511 * Transformation Examples:: Sample uses of transforming names
512 * Transformation Rules:: @file{Makefile} uses of transforming names
514 Running @command{configure} Scripts
516 * Basic Installation:: Instructions for typical cases
517 * Compilers and Options:: Selecting compilers and optimization
518 * Multiple Architectures:: Compiling for multiple architectures at once
519 * Installation Names:: Installing in different directories
520 * Optional Features:: Selecting optional features
521 * System Type:: Specifying the system type
522 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
523 * Defining Variables:: Specifying the compiler etc.
524 * configure Invocation:: Changing how @command{configure} runs
528 * Obsolete config.status Use:: Different calling convention
529 * acconfig.h:: Additional entries in @file{config.h.in}
530 * autoupdate Invocation:: Automatic update of @file{configure.ac}
531 * Obsolete Macros:: Backward compatibility macros
532 * Autoconf 1:: Tips for upgrading your files
533 * Autoconf 2.13:: Some fresher tips
535 Upgrading From Version 1
537 * Changed File Names:: Files you might rename
538 * Changed Makefiles:: New things to put in @file{Makefile.in}
539 * Changed Macros:: Macro calls you might replace
540 * Changed Results:: Changes in how to check test results
541 * Changed Macro Writing:: Better ways to write your own macros
543 Upgrading From Version 2.13
545 * Changed Quotation:: Broken code which used to work
546 * New Macros:: Interaction with foreign macros
547 * Hosts and Cross-Compilation:: Bugward compatibility kludges
548 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
549 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
551 Generating Test Suites with Autotest
553 * Using an Autotest Test Suite:: Autotest and the user
554 * Writing testsuite.at:: Autotest macros
555 * testsuite Invocation:: Running @command{testsuite} scripts
556 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
558 Using an Autotest Test Suite
560 * testsuite Scripts:: The concepts of Autotest
561 * Autotest Logs:: Their contents
563 Frequent Autoconf Questions, with answers
565 * Distributing:: Distributing @command{configure} scripts
566 * Why GNU m4:: Why not use the standard M4?
567 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
568 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
569 * Defining Directories:: Passing @code{datadir} to program
570 * autom4te.cache:: What is it? Can I remove it?
571 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
575 * Genesis:: Prehistory and naming of @command{configure}
576 * Exodus:: The plagues of M4 and Perl
577 * Leviticus:: The priestly code of portability arrives
578 * Numbers:: Growth and contributors
579 * Deuteronomy:: Approaching the promises of easy configuration
583 * GNU Free Documentation License:: License for copying this manual
587 * Environment Variable Index:: Index of environment variables used
588 * Output Variable Index:: Index of variables set in output files
589 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
590 * Autoconf Macro Index:: Index of Autoconf macros
591 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
592 * Autotest Macro Index:: Index of Autotest macros
593 * Program & Function Index:: Index of those with portability problems
594 * Concept Index:: General index
599 @c ============================================================= Introduction.
602 @chapter Introduction
606 A physicist, an engineer, and a computer scientist were discussing the
607 nature of God. ``Surely a Physicist,'' said the physicist, ``because
608 early in the Creation, God made Light; and you know, Maxwell's
609 equations, the dual nature of electromagnetic waves, the relativistic
610 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
611 before making Light, God split the Chaos into Land and Water; it takes a
612 hell of an engineer to handle that big amount of mud, and orderly
613 separation of solids from liquids@dots{}'' The computer scientist
614 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
618 @c (via Franc,ois Pinard)
620 Autoconf is a tool for producing shell scripts that automatically
621 configure software source code packages to adapt to many kinds of
622 Posix-like systems. The configuration scripts produced by Autoconf
623 are independent of Autoconf when they are run, so their users do not
624 need to have Autoconf.
626 The configuration scripts produced by Autoconf require no manual user
627 intervention when run; they do not normally even need an argument
628 specifying the system type. Instead, they individually test for the
629 presence of each feature that the software package they are for might need.
630 (Before each check, they print a one-line message stating what they are
631 checking for, so the user doesn't get too bored while waiting for the
632 script to finish.) As a result, they deal well with systems that are
633 hybrids or customized from the more common Posix variants. There is
634 no need to maintain files that list the features supported by each
635 release of each variant of Posix.
637 For each software package that Autoconf is used with, it creates a
638 configuration script from a template file that lists the system features
639 that the package needs or can use. After the shell code to recognize
640 and respond to a system feature has been written, Autoconf allows it to
641 be shared by many software packages that can use (or need) that feature.
642 If it later turns out that the shell code needs adjustment for some
643 reason, it needs to be changed in only one place; all of the
644 configuration scripts can be regenerated automatically to take advantage
647 The Metaconfig package is similar in purpose to Autoconf, but the
648 scripts it produces require manual user intervention, which is quite
649 inconvenient when configuring large source trees. Unlike Metaconfig
650 scripts, Autoconf scripts can support cross-compiling, if some care is
651 taken in writing them.
653 Autoconf does not solve all problems related to making portable
654 software packages---for a more complete solution, it should be used in
655 concert with other @acronym{GNU} build tools like Automake and
656 Libtool. These other tools take on jobs like the creation of a
657 portable, recursive @file{Makefile} with all of the standard targets,
658 linking of shared libraries, and so on. @xref{The GNU Build System},
659 for more information.
661 Autoconf imposes some restrictions on the names of macros used with
662 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
664 Autoconf requires @acronym{GNU} M4 in order to generate the scripts. It uses
665 features that some versions of M4, including @acronym{GNU} M4 1.3,
666 do not have. You should use version 1.4.3 or later of @acronym{GNU} M4.
668 @xref{Autoconf 1}, for information about upgrading from version 1.
669 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
670 for answers to some common questions about Autoconf.
672 See the @uref{http://www.gnu.org/software/autoconf/,
673 Autoconf web page} for up-to-date information, details on the mailing
674 lists, pointers to a list of known bugs, etc.
676 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
677 list}. Past suggestions are
678 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
680 Mail bug reports to @email{bug-autoconf@@gnu.org, the
681 Autoconf Bugs mailing list}. Past bug reports are
682 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
684 If possible, first check that your bug is
685 not already solved in current development versions, and that it has not
686 been reported yet. Be sure to include all the needed information and a
687 short @file{configure.ac} that demonstrates the problem.
689 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
690 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
691 Summary} for details. Patches relative to the
692 current @acronym{CVS} version can be sent for review to the
693 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
695 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
697 Because of its mission, the Autoconf package itself
698 includes only a set of often-used
699 macros that have already demonstrated their usefulness. Nevertheless,
700 if you wish to share your macros, or find existing ones, see the
701 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
702 Archive}, which is kindly run by @email{simons@@cryp.to,
706 @c ================================================= The GNU Build System
708 @node The GNU Build System
709 @chapter The @acronym{GNU} Build System
710 @cindex GNU build system
712 Autoconf solves an important problem---reliable discovery of
713 system-specific build and runtime information---but this is only one
714 piece of the puzzle for the development of portable software. To this
715 end, the @acronym{GNU} project has developed a suite of integrated
716 utilities to finish the job Autoconf started: the @acronym{GNU} build
717 system, whose most important components are Autoconf, Automake, and
718 Libtool. In this chapter, we introduce you to those tools, point you
719 to sources of more information, and try to convince you to use the
720 entire @acronym{GNU} build system for your software.
723 * Automake:: Escaping Makefile hell
724 * Gnulib:: The @acronym{GNU} portability library
725 * Libtool:: Building libraries portably
726 * Pointers:: More info on the @acronym{GNU} build system
732 The ubiquity of @command{make} means that a @file{Makefile} is almost the
733 only viable way to distribute automatic build rules for software, but
734 one quickly runs into @command{make}'s numerous limitations. Its lack of
735 support for automatic dependency tracking, recursive builds in
736 subdirectories, reliable timestamps (e.g., for network file systems), and
737 so on, mean that developers must painfully (and often incorrectly)
738 reinvent the wheel for each project. Portability is non-trivial, thanks
739 to the quirks of @command{make} on many systems. On top of all this is the
740 manual labor required to implement the many standard targets that users
741 have come to expect (@code{make install}, @code{make distclean},
742 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
743 you also have to insert repetitive code in your @code{Makefile.in} to
744 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
745 provided by @command{configure}. Into this mess steps @dfn{Automake}.
748 Automake allows you to specify your build needs in a @code{Makefile.am}
749 file with a vastly simpler and more powerful syntax than that of a plain
750 @code{Makefile}, and then generates a portable @code{Makefile.in} for
751 use with Autoconf. For example, the @code{Makefile.am} to build and
752 install a simple ``Hello world'' program might look like:
756 hello_SOURCES = hello.c
760 The resulting @code{Makefile.in} (~400 lines) automatically supports all
761 the standard targets, the substitutions provided by Autoconf, automatic
762 dependency tracking, @code{VPATH} building, and so on. @command{make} will
763 build the @code{hello} program, and @code{make install} will install it
764 in @file{/usr/local/bin} (or whatever prefix was given to
765 @command{configure}, if not @file{/usr/local}).
767 The benefits of Automake increase for larger packages (especially ones
768 with subdirectories), but even for small programs the added convenience
769 and portability can be substantial. And that's not all@enddots{}
774 @acronym{GNU} software has a well-deserved reputation for running on
775 many different types of systems. While our primary goal is to write
776 software for the @acronym{GNU} system, many users and developers have
777 been introduced to us through the systems that they were already using.
780 Gnulib is a central location for common @acronym{GNU} code, intended to
781 be shared among free software packages. Its components are typically
782 shared at the source level, rather than being a library that gets built,
783 installed, and linked against. The idea is to copy files from Gnulib
784 into your own source tree. There is no distribution tarball; developers
785 should just grab source modules from the repository. The source files
786 are available online, under various licenses, mostly @acronym{GNU}
787 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
789 Gnulib modules typically contain C source code along with Autoconf
790 macros used to configure the source code. For example, the Gnulib
791 @code{stdbool} module implements a @file{stdbool.h} header that nearly
792 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
793 This module contains a source file for the replacement header, along
794 with an Autoconf macro that arranges to use the replacement header on
795 old-fashioned systems.
800 Very often, one wants to build not only programs, but libraries, so that
801 other programs can benefit from the fruits of your labor. Ideally, one
802 would like to produce @emph{shared} (dynamically linked) libraries,
803 which can be used by multiple programs without duplication on disk or in
804 memory and can be updated independently of the linked programs.
805 Producing shared libraries portably, however, is the stuff of
806 nightmares---each system has its own incompatible tools, compiler flags,
807 and magic incantations. Fortunately, @acronym{GNU} provides a solution:
811 Libtool handles all the requirements of building shared libraries for
812 you, and at this time seems to be the @emph{only} way to do so with any
813 portability. It also handles many other headaches, such as: the
814 interaction of @code{Makefile} rules with the variable suffixes of
815 shared libraries, linking reliably with shared libraries before they are
816 installed by the superuser, and supplying a consistent versioning system
817 (so that different versions of a library can be installed or upgraded
818 without breaking binary compatibility). Although Libtool, like
819 Autoconf, can be used without Automake, it is most simply utilized in
820 conjunction with Automake---there, Libtool is used automatically
821 whenever shared libraries are needed, and you need not know its syntax.
826 Developers who are used to the simplicity of @command{make} for small
827 projects on a single system might be daunted at the prospect of
828 learning to use Automake and Autoconf. As your software is
829 distributed to more and more users, however, you will otherwise
830 quickly find yourself putting lots of effort into reinventing the
831 services that the @acronym{GNU} build tools provide, and making the
832 same mistakes that they once made and overcame. (Besides, since
833 you're already learning Autoconf, Automake will be a piece of cake.)
835 There are a number of places that you can go to for more information on
836 the @acronym{GNU} build tools.
843 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
844 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
845 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
846 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
848 @item Automake Manual
850 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
851 information on Automake.
855 The book @cite{@acronym{GNU} Autoconf, Automake and
856 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
857 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
858 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
859 build environment. You can also find
860 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
864 @c ================================================= Making configure Scripts.
866 @node Making configure Scripts
867 @chapter Making @command{configure} Scripts
868 @cindex @file{aclocal.m4}
869 @cindex @command{configure}
871 The configuration scripts that Autoconf produces are by convention
872 called @command{configure}. When run, @command{configure} creates several
873 files, replacing configuration parameters in them with appropriate
874 values. The files that @command{configure} creates are:
878 one or more @file{Makefile} files, usually one in each subdirectory of the
879 package (@pxref{Makefile Substitutions});
882 optionally, a C header file, the name of which is configurable,
883 containing @code{#define} directives (@pxref{Configuration Headers});
886 a shell script called @file{config.status} that, when run, will recreate
887 the files listed above (@pxref{config.status Invocation});
890 an optional shell script normally called @file{config.cache}
891 (created when using @samp{configure --config-cache}) that
892 saves the results of running many of the tests (@pxref{Cache Files});
895 a file called @file{config.log} containing any messages produced by
896 compilers, to help debugging if @command{configure} makes a mistake.
899 @cindex @file{configure.in}
900 @cindex @file{configure.ac}
901 To create a @command{configure} script with Autoconf, you need to write an
902 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
903 @command{autoconf} on it. If you write your own feature tests to
904 supplement those that come with Autoconf, you might also write files
905 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
906 file to contain @code{#define} directives, you might also run
907 @command{autoheader}, and you will distribute the generated file
908 @file{config.h.in} with the package.
910 Here is a diagram showing how the files that can be used in
911 configuration are produced. Programs that are executed are suffixed by
912 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
913 @command{autoconf} and @command{autoheader} also read the installed Autoconf
914 macro files (by reading @file{autoconf.m4}).
917 Files used in preparing a software package for distribution:
919 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
923 | .------> autoconf* -----> configure
925 | `-----> [autoheader*] --> [config.h.in]
929 Makefile.in -------------------------------> Makefile.in
933 Files used in configuring a software package:
936 .-------------> [config.cache]
937 configure* ------------+-------------> config.log
939 [config.h.in] -. v .-> [config.h] -.
940 +--> config.status* -+ +--> make*
941 Makefile.in ---' `-> Makefile ---'
946 * Writing configure.ac:: What to put in an Autoconf input file
947 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
948 * ifnames Invocation:: Listing the conditionals in source code
949 * autoconf Invocation:: How to create configuration scripts
950 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
953 @node Writing configure.ac
954 @section Writing @file{configure.ac}
956 To produce a @command{configure} script for a software package, create a
957 file called @file{configure.ac} that contains invocations of the
958 Autoconf macros that test the system features your package needs or can
959 use. Autoconf macros already exist to check for many features; see
960 @ref{Existing Tests}, for their descriptions. For most other features,
961 you can use Autoconf template macros to produce custom checks; see
962 @ref{Writing Tests}, for information about them. For especially tricky
963 or specialized features, @file{configure.ac} might need to contain some
964 hand-crafted shell commands; see @ref{Portable Shell}. The
965 @command{autoscan} program can give you a good start in writing
966 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
968 Previous versions of Autoconf promoted the name @file{configure.in},
969 which is somewhat ambiguous (the tool needed to process this file is not
970 described by its extension), and introduces a slight confusion with
971 @file{config.h.in} and so on (for which @samp{.in} means ``to be
972 processed by @command{configure}''). Using @file{configure.ac} is now
976 * Shell Script Compiler:: Autoconf as solution of a problem
977 * Autoconf Language:: Programming in Autoconf
978 * configure.ac Layout:: Standard organization of @file{configure.ac}
981 @node Shell Script Compiler
982 @subsection A Shell Script Compiler
984 Just as for any other computer language, in order to properly program
985 @file{configure.ac} in Autoconf you must understand @emph{what} problem
986 the language tries to address and @emph{how} it does so.
988 The problem Autoconf addresses is that the world is a mess. After all,
989 you are using Autoconf in order to have your package compile easily on
990 all sorts of different systems, some of them being extremely hostile.
991 Autoconf itself bears the price for these differences: @command{configure}
992 must run on all those systems, and thus @command{configure} must limit itself
993 to their lowest common denominator of features.
995 Naturally, you might then think of shell scripts; who needs
996 @command{autoconf}? A set of properly written shell functions is enough to
997 make it easy to write @command{configure} scripts by hand. Sigh!
998 Unfortunately, shell functions do not belong to the least common
999 denominator; therefore, where you would like to define a function and
1000 use it ten times, you would instead need to copy its body ten times.
1002 So, what is really needed is some kind of compiler, @command{autoconf},
1003 that takes an Autoconf program, @file{configure.ac}, and transforms it
1004 into a portable shell script, @command{configure}.
1006 How does @command{autoconf} perform this task?
1008 There are two obvious possibilities: creating a brand new language or
1009 extending an existing one. The former option is very attractive: all
1010 sorts of optimizations could easily be implemented in the compiler and
1011 many rigorous checks could be performed on the Autoconf program
1012 (e.g., rejecting any non-portable construct). Alternatively, you can
1013 extend an existing language, such as the @code{sh} (Bourne shell)
1016 Autoconf does the latter: it is a layer on top of @code{sh}. It was
1017 therefore most convenient to implement @command{autoconf} as a macro
1018 expander: a program that repeatedly performs @dfn{macro expansions} on
1019 text input, replacing macro calls with macro bodies and producing a pure
1020 @code{sh} script in the end. Instead of implementing a dedicated
1021 Autoconf macro expander, it is natural to use an existing
1022 general-purpose macro language, such as M4, and implement the extensions
1023 as a set of M4 macros.
1026 @node Autoconf Language
1027 @subsection The Autoconf Language
1030 The Autoconf language is very different from many other computer
1031 languages because it treats actual code the same as plain text. Whereas
1032 in C, for instance, data and instructions have very different syntactic
1033 status, in Autoconf their status is rigorously the same. Therefore, we
1034 need a means to distinguish literal strings from text to be expanded:
1037 When calling macros that take arguments, there must not be any white
1038 space between the macro name and the open parenthesis. Arguments should
1039 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1040 separated by commas. Any leading blanks or newlines in arguments are ignored,
1041 unless they are quoted. You should always quote an argument that
1042 might contain a macro name, comma, parenthesis, or a leading blank or
1043 newline. This rule applies recursively for every macro
1044 call, including macros called from other macros.
1049 AC_CHECK_HEADER([stdio.h],
1050 [AC_DEFINE([HAVE_STDIO_H], [1],
1051 [Define to 1 if you have <stdio.h>.])],
1052 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1056 is quoted properly. You may safely simplify its quotation to:
1059 AC_CHECK_HEADER([stdio.h],
1060 [AC_DEFINE([HAVE_STDIO_H], 1,
1061 [Define to 1 if you have <stdio.h>.])],
1062 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1066 because @samp{1} cannot contain a macro call. Here, the argument of
1067 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1068 interpreted as an argument separator. Also, @samp{AC_CHECK_HEADER}'s
1069 second and third arguments must be quoted, since those arguments contain
1070 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1071 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1072 if you unwisely defined a macro with a name like @samp{Define} or
1073 @samp{stdio} then they would need quoting. Cautious Autoconf users
1074 would keep the quotes, but many Autoconf users find such precautions
1075 annoying, and would rewrite the example as follows:
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 This is safe, so long as you adopt good naming conventions and do not
1086 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1087 @samp{h}. Though it is also safe here to omit the quotes around
1088 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1089 message strings are more likely to inadvertently contain commas.
1091 The following example is wrong and dangerous, as it is underquoted:
1094 AC_CHECK_HEADER(stdio.h,
1095 AC_DEFINE(HAVE_STDIO_H, 1,
1096 Define to 1 if you have <stdio.h>.),
1097 AC_MSG_ERROR([Sorry, can't do anything for you]))
1100 In other cases, you may have to use text that also resembles a macro
1101 call. You must quote that text even when it is not passed as a macro
1105 echo "Hard rock was here! --[AC_DC]"
1109 which will result in
1112 echo "Hard rock was here! --AC_DC"
1116 When you use the same text in a macro argument, you must therefore have
1117 an extra quotation level (since one is stripped away by the macro
1118 substitution). In general, then, it is a good idea to @emph{use double
1119 quoting for all literal string arguments}:
1122 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1125 You are now able to understand one of the constructs of Autoconf that
1126 has been continually misunderstood@dots{} The rule of thumb is that
1127 @emph{whenever you expect macro expansion, expect quote expansion};
1128 i.e., expect one level of quotes to be lost. For instance:
1131 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1135 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1136 @samp{char b[10];} and will be expanded once, which results in
1137 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1138 address this issue via the M4 @code{changequote} primitive, but do not
1139 use it!) Let's take a closer look: the author meant the first argument
1140 to be understood as a literal, and therefore it must be quoted twice:
1143 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1147 Voil@`a, you actually produce @samp{char b[10];} this time!
1149 On the other hand, descriptions (e.g., the last parameter of
1150 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1151 are subject to line breaking, for example---and should not be double quoted.
1152 Even if these descriptions are short and are not actually broken, double
1153 quoting them yields weird results.
1155 Some macros take optional arguments, which this documentation represents
1156 as @ovar{arg} (not to be confused with the quote characters). You may
1157 just leave them empty, or use @samp{[]} to make the emptiness of the
1158 argument explicit, or you may simply omit the trailing commas. The
1159 three lines below are equivalent:
1162 AC_CHECK_HEADERS([stdio.h], [], [], [])
1163 AC_CHECK_HEADERS([stdio.h],,,)
1164 AC_CHECK_HEADERS([stdio.h])
1167 It is best to put each macro call on its own line in
1168 @file{configure.ac}. Most of the macros don't add extra newlines; they
1169 rely on the newline after the macro call to terminate the commands.
1170 This approach makes the generated @command{configure} script a little
1171 easier to read by not inserting lots of blank lines. It is generally
1172 safe to set shell variables on the same line as a macro call, because
1173 the shell allows assignments without intervening newlines.
1175 You can include comments in @file{configure.ac} files by starting them
1176 with the @samp{#}. For example, it is helpful to begin
1177 @file{configure.ac} files with a line like this:
1180 # Process this file with autoconf to produce a configure script.
1183 @node configure.ac Layout
1184 @subsection Standard @file{configure.ac} Layout
1186 The order in which @file{configure.ac} calls the Autoconf macros is not
1187 important, with a few exceptions. Every @file{configure.ac} must
1188 contain a call to @code{AC_INIT} before the checks, and a call to
1189 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1190 rely on other macros having been called first, because they check
1191 previously set values of some variables to decide what to do. These
1192 macros are noted in the individual descriptions (@pxref{Existing
1193 Tests}), and they also warn you when @command{configure} is created if they
1194 are called out of order.
1196 To encourage consistency, here is a suggested order for calling the
1197 Autoconf macros. Generally speaking, the things near the end of this
1198 list are those that could depend on things earlier in it. For example,
1199 library functions could be affected by types and libraries.
1203 Autoconf requirements
1204 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1205 information on the package
1207 checks for libraries
1208 checks for header files
1210 checks for structures
1211 checks for compiler characteristics
1212 checks for library functions
1213 checks for system services
1214 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1220 @node autoscan Invocation
1221 @section Using @command{autoscan} to Create @file{configure.ac}
1222 @cindex @command{autoscan}
1224 The @command{autoscan} program can help you create and/or maintain a
1225 @file{configure.ac} file for a software package. @command{autoscan}
1226 examines source files in the directory tree rooted at a directory given
1227 as a command line argument, or the current directory if none is given.
1228 It searches the source files for common portability problems and creates
1229 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1230 for that package, and checks a possibly existing @file{configure.ac} for
1233 When using @command{autoscan} to create a @file{configure.ac}, you
1234 should manually examine @file{configure.scan} before renaming it to
1235 @file{configure.ac}; it will probably need some adjustments.
1236 Occasionally, @command{autoscan} outputs a macro in the wrong order
1237 relative to another macro, so that @command{autoconf} produces a warning;
1238 you need to move such macros manually. Also, if you want the package to
1239 use a configuration header file, you must add a call to
1240 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1241 also have to change or add some @code{#if} directives to your program in
1242 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1243 information about a program that can help with that job).
1245 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1246 consider adding its suggestions. The file @file{autoscan.log} will
1247 contain detailed information on why a macro is requested.
1249 @command{autoscan} uses several data files (installed along with Autoconf)
1250 to determine which macros to output when it finds particular symbols in
1251 a package's source files. These data files all have the same format:
1252 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1253 output if that symbol is encountered. Lines starting with @samp{#} are
1256 @command{autoscan} accepts the following options:
1261 Print a summary of the command line options and exit.
1265 Print the version number of Autoconf and exit.
1269 Print the names of the files it examines and the potentially interesting
1270 symbols it finds in them. This output can be voluminous.
1272 @item --include=@var{dir}
1274 Append @var{dir} to the include path. Multiple invocations accumulate.
1276 @item --prepend-include=@var{dir}
1278 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1281 @node ifnames Invocation
1282 @section Using @command{ifnames} to List Conditionals
1283 @cindex @command{ifnames}
1285 @command{ifnames} can help you write @file{configure.ac} for a software
1286 package. It prints the identifiers that the package already uses in C
1287 preprocessor conditionals. If a package has already been set up to have
1288 some portability, @command{ifnames} can thus help you figure out what its
1289 @command{configure} needs to check for. It may help fill in some gaps in a
1290 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1293 @command{ifnames} scans all of the C source files named on the command line
1294 (or the standard input, if none are given) and writes to the standard
1295 output a sorted list of all the identifiers that appear in those files
1296 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1297 directives. It prints each identifier on a line, followed by a
1298 space-separated list of the files in which that identifier occurs.
1301 @command{ifnames} accepts the following options:
1306 Print a summary of the command line options and exit.
1310 Print the version number of Autoconf and exit.
1313 @node autoconf Invocation
1314 @section Using @command{autoconf} to Create @command{configure}
1315 @cindex @command{autoconf}
1317 To create @command{configure} from @file{configure.ac}, run the
1318 @command{autoconf} program with no arguments. @command{autoconf} processes
1319 @file{configure.ac} with the M4 macro processor, using the
1320 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1321 file instead of @file{configure.ac} and writes the configuration script
1322 to the standard output instead of to @command{configure}. If you give
1323 @command{autoconf} the argument @option{-}, it reads from the standard
1324 input instead of @file{configure.ac} and writes the configuration script
1325 to the standard output.
1327 The Autoconf macros are defined in several files. Some of the files are
1328 distributed with Autoconf; @command{autoconf} reads them first. Then it
1329 looks for the optional file @file{acsite.m4} in the directory that
1330 contains the distributed Autoconf macro files, and for the optional file
1331 @file{aclocal.m4} in the current directory. Those files can contain
1332 your site's or the package's own Autoconf macro definitions
1333 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1334 defined in more than one of the files that @command{autoconf} reads, the
1335 last definition it reads overrides the earlier ones.
1337 @command{autoconf} accepts the following options:
1342 Print a summary of the command line options and exit.
1346 Print the version number of Autoconf and exit.
1350 Report processing steps.
1354 Don't remove the temporary files.
1358 Remake @file{configure} even if newer than its input files.
1360 @item --include=@var{dir}
1362 Append @var{dir} to the include path. Multiple invocations accumulate.
1364 @item --prepend-include=@var{dir}
1366 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1368 @item --output=@var{file}
1369 @itemx -o @var{file}
1370 Save output (script or trace) to @var{file}. The file @option{-} stands
1371 for the standard output.
1373 @item --warnings=@var{category}
1374 @itemx -W @var{category}
1376 Report the warnings related to @var{category} (which can actually be a
1377 comma separated list). @xref{Reporting Messages}, macro
1378 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1383 report all the warnings
1389 treats warnings as errors
1391 @item no-@var{category}
1392 disable warnings falling into @var{category}
1395 Warnings about @samp{syntax} are enabled by default, and the environment
1396 variable @env{WARNINGS}, a comma separated list of categories, is
1397 honored as well. Passing @option{-W @var{category}} will actually behave as if
1398 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If
1399 you want to disable the defaults and @env{WARNINGS}, but (for example)
1400 enable the warnings about obsolete constructs, you would use @option{-W
1404 @cindex Macro invocation stack
1405 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1406 displays a back trace for errors, but not for warnings; if you want
1407 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1410 @item --trace=@var{macro}[:@var{format}]
1411 @itemx -t @var{macro}[:@var{format}]
1412 Do not create the @command{configure} script, but list the calls to
1413 @var{macro} according to the @var{format}. Multiple @option{--trace}
1414 arguments can be used to list several macros. Multiple @option{--trace}
1415 arguments for a single macro are not cumulative; instead, you should
1416 just make @var{format} as long as needed.
1418 The @var{format} is a regular string, with newlines if desired, and
1419 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1420 @ref{autom4te Invocation}, for details on the @var{format}.
1422 @item --initialization
1424 By default, @option{--trace} does not trace the initialization of the
1425 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1426 results in a noticeable speedup, but can be disabled by this option.
1430 It is often necessary to check the content of a @file{configure.ac}
1431 file, but parsing it yourself is extremely fragile and error-prone. It
1432 is suggested that you rely upon @option{--trace} to scan
1433 @file{configure.ac}. For instance, to find the list of variables that
1434 are substituted, use:
1438 $ @kbd{autoconf -t AC_SUBST}
1439 configure.ac:2:AC_SUBST:ECHO_C
1440 configure.ac:2:AC_SUBST:ECHO_N
1441 configure.ac:2:AC_SUBST:ECHO_T
1442 @i{More traces deleted}
1447 The example below highlights the difference between @samp{$@@},
1448 @samp{$*}, and @samp{$%}.
1452 $ @kbd{cat configure.ac}
1453 AC_DEFINE(This, is, [an
1455 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1462 %: This:is:an [example]
1467 The @var{format} gives you a lot of freedom:
1471 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1472 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1473 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1474 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1475 @i{More traces deleted}
1480 A long @var{separator} can be used to improve the readability of complex
1481 structures, and to ease their parsing (for instance when no single
1482 character is suitable as a separator):
1486 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1487 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1488 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1489 AUTOMAKE|:::::|automake|:::::|$missing_dir
1490 @i{More traces deleted}
1494 @node autoreconf Invocation
1495 @section Using @command{autoreconf} to Update @command{configure} Scripts
1496 @cindex @command{autoreconf}
1498 Installing the various components of the @acronym{GNU} Build System can be
1499 tedious: running @command{autopoint} for Gettext, @command{automake} for
1500 @file{Makefile.in} etc.@: in each directory. It may be needed either
1501 because some tools such as @command{automake} have been updated on your
1502 system, or because some of the sources such as @file{configure.ac} have
1503 been updated, or finally, simply in order to install the @acronym{GNU} Build
1504 System in a fresh tree.
1506 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1507 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1508 @command{autopoint} (when appropriate) repeatedly to update the
1509 @acronym{GNU} Build System in the specified directories and their
1510 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1511 those files that are older than their sources.
1513 If you install a new version of some tool, you can make
1514 @command{autoreconf} remake @emph{all} of the files by giving it the
1515 @option{--force} option.
1517 @xref{Automatic Remaking}, for @file{Makefile} rules to automatically
1518 remake @command{configure} scripts when their source files change. That
1519 method handles the timestamps of configuration header templates
1520 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1521 @option{--localdir=@var{dir}}.
1524 @cindex @command{autopoint}
1525 Gettext supplies the @command{autopoint} command to add translation
1526 infrastructure to a source package. If you use @command{autopoint},
1527 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1528 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
1529 Invocation, , Invoking the @code{autopoint} Program, gettext, GNU
1530 @code{gettext} utilities}, for further details.
1533 @command{autoreconf} accepts the following options:
1538 Print a summary of the command line options and exit.
1542 Print the version number of Autoconf and exit.
1545 Print the name of each directory @command{autoreconf} examines and the
1546 commands it runs. If given two or more times, pass @option{--verbose}
1547 to subordinate tools that support it.
1551 Don't remove the temporary files.
1555 Remake even @file{configure} scripts and configuration headers that are
1556 newer than their input files (@file{configure.ac} and, if present,
1561 Install the missing auxiliary files in the package. By default, files
1562 are copied; this can be changed with @option{--symlink}.
1564 If deemed appropriate, this option triggers calls to
1565 @samp{automake --add-missing},
1566 @samp{libtoolize}, @samp{autopoint}, etc.
1568 @item --no-recursive
1569 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1570 macro @code{AC_CONFIG_SUBDIRS}).
1574 When used with @option{--install}, install symbolic links to the missing
1575 auxiliary files instead of copying them.
1579 When the directories were configured, update the configuration by
1580 running @samp{./config.status --recheck && ./config.status}, and then
1583 @item --include=@var{dir}
1585 Append @var{dir} to the include path. Multiple invocations accumulate.
1586 Passed on to @command{autoconf} and @command{autoheader} internally.
1588 @item --prepend-include=@var{dir}
1590 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1591 Passed on to @command{autoconf} and @command{autoheader} internally.
1593 @item --warnings=@var{category}
1594 @itemx -W @var{category}
1596 Report the warnings related to @var{category} (which can actually be a
1597 comma separated list).
1601 related to cross compilation issues.
1604 report the uses of obsolete constructs.
1610 dubious syntactic constructs.
1613 report all the warnings
1619 treats warnings as errors
1621 @item no-@var{category}
1622 disable warnings falling into @var{category}
1625 Warnings about @samp{syntax} are enabled by default, and the environment
1626 variable @env{WARNINGS}, a comma separated list of categories, is
1627 honored as well. Passing @option{-W @var{category}} will actually behave as if
1628 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If
1629 you want to disable the defaults and @env{WARNINGS}, but (for example)
1630 enable the warnings about obsolete constructs, you would use @option{-W
1634 If you want @command{autoreconf} to pass flags that are not listed here
1635 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your Makefile.am.
1637 @c ========================================= Initialization and Output Files.
1640 @chapter Initialization and Output Files
1642 Autoconf-generated @command{configure} scripts need some information about
1643 how to initialize, such as how to find the package's source files and
1644 about the output files to produce. The following sections describe the
1645 initialization and the creation of output files.
1648 * Initializing configure:: Option processing etc.
1649 * Notices:: Copyright, version numbers in @command{configure}
1650 * Input:: Where Autoconf should find files
1651 * Output:: Outputting results from the configuration
1652 * Configuration Actions:: Preparing the output based on results
1653 * Configuration Files:: Creating output files
1654 * Makefile Substitutions:: Using output variables in @file{Makefile}s
1655 * Configuration Headers:: Creating a configuration header file
1656 * Configuration Commands:: Running arbitrary instantiation commands
1657 * Configuration Links:: Links depending on the configuration
1658 * Subdirectories:: Configuring independent packages together
1659 * Default Prefix:: Changing the default installation prefix
1662 @node Initializing configure
1663 @section Initializing @command{configure}
1665 Every @command{configure} script must call @code{AC_INIT} before doing
1666 anything else. The only other required macro is @code{AC_OUTPUT}
1669 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1671 Process any command-line arguments and perform various initializations
1674 Set the name of the @var{package} and its @var{version}. These are
1675 typically used in @option{--version} support, including that of
1676 @command{configure}. The optional argument @var{bug-report} should be
1677 the email to which users should send bug reports. The package
1678 @var{tarname} differs from @var{package}: the latter designates the full
1679 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1680 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1681 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1682 other than alphanumerics and underscores are changed to @samp{-}.
1684 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1685 there should not be any shell computation, but they can be computed by
1688 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1689 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1690 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1693 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1694 @acindex{PACKAGE_NAME}
1695 @ovindex PACKAGE_NAME
1696 @cvindex PACKAGE_NAME
1697 Exactly @var{package}.
1699 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1700 @acindex{PACKAGE_TARNAME}
1701 @ovindex PACKAGE_TARNAME
1702 @cvindex PACKAGE_TARNAME
1703 Exactly @var{tarname}.
1705 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1706 @acindex{PACKAGE_VERSION}
1707 @ovindex PACKAGE_VERSION
1708 @cvindex PACKAGE_VERSION
1709 Exactly @var{version}.
1711 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1712 @acindex{PACKAGE_STRING}
1713 @ovindex PACKAGE_STRING
1714 @cvindex PACKAGE_STRING
1715 Exactly @samp{@var{package} @var{version}}.
1717 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1718 @acindex{PACKAGE_BUGREPORT}
1719 @ovindex PACKAGE_BUGREPORT
1720 @cvindex PACKAGE_BUGREPORT
1721 Exactly @var{bug-report}.
1727 @section Notices in @command{configure}
1728 @cindex Notices in @command{configure}
1730 The following macros manage version numbers for @command{configure}
1731 scripts. Using them is optional.
1733 @c FIXME: AC_PREREQ should not be here
1734 @defmac AC_PREREQ (@var{version})
1737 Ensure that a recent enough version of Autoconf is being used. If the
1738 version of Autoconf being used to create @command{configure} is
1739 earlier than @var{version}, print an error message to the standard
1740 error output and exit with failure (exit status is 63). For example:
1743 AC_PREREQ([@value{VERSION}])
1746 This macro is the only macro that may be used before @code{AC_INIT}, but
1747 for consistency, you are invited not to do so.
1750 @defmac AC_COPYRIGHT (@var{copyright-notice})
1752 @cindex Copyright Notice
1753 State that, in addition to the Free Software Foundation's copyright on
1754 the Autoconf macros, parts of your @command{configure} are covered by the
1755 @var{copyright-notice}.
1757 The @var{copyright-notice} will show up in both the head of
1758 @command{configure} and in @samp{configure --version}.
1762 @defmac AC_REVISION (@var{revision-info})
1765 Copy revision stamp @var{revision-info} into the @command{configure}
1766 script, with any dollar signs or double-quotes removed. This macro lets
1767 you put a revision stamp from @file{configure.ac} into @command{configure}
1768 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1769 @command{configure}. That way, you can determine easily which revision of
1770 @file{configure.ac} a particular @command{configure} corresponds to.
1772 For example, this line in @file{configure.ac}:
1774 @c The asis prevents RCS from changing the example in the manual.
1776 AC_REVISION([$@asis{Revision: 1.30 }$])
1780 produces this in @command{configure}:
1784 # From configure.ac Revision: 1.30
1790 @section Finding @command{configure} Input
1793 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1794 @acindex{CONFIG_SRCDIR}
1795 @var{unique-file-in-source-dir} is some file that is in the package's
1796 source directory; @command{configure} checks for this file's existence to
1797 make sure that the directory that it is told contains the source code in
1798 fact does. Occasionally people accidentally specify the wrong directory
1799 with @option{--srcdir}; this is a safety check. @xref{configure
1800 Invocation}, for more information.
1804 @c FIXME: Remove definitively once --install explained.
1806 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1807 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1808 @c to split the macros in several files. In this case, Autoconf must be
1809 @c told which files to load, and in which order.
1811 @c @defmac AC_INCLUDE (@var{file}@dots{})
1812 @c @acindex{INCLUDE}
1813 @c @c FIXME: There is no longer shell globbing.
1814 @c Read the macro definitions that appear in the listed files. A list of
1815 @c space-separated file names or shell globbing patterns is expected. The
1816 @c files will be read in the order they're listed.
1818 @c Because the order of definition of macros is important (only the last
1819 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1820 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1821 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1822 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1823 @c the latter case, non-macro lines from included files may end up in the
1824 @c @file{configure} script, whereas in the former case, they'd be discarded
1825 @c just like any text that appear before @code{AC_INIT}.
1828 Packages that do manual configuration or use the @command{install} program
1829 might need to tell @command{configure} where to find some other shell
1830 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1831 it looks are correct for most cases.
1833 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1834 @acindex{CONFIG_AUX_DIR}
1835 Use the auxiliary build tools (e.g., @file{install-sh},
1836 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1837 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1838 These are auxiliary files used in configuration. @var{dir} can be
1839 either absolute or relative to @file{@var{srcdir}}. The default is
1840 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1841 @file{@var{srcdir}/../..}, whichever is the first that contains
1842 @file{install-sh}. The other files are not checked for, so that using
1843 @code{AC_PROG_INSTALL} does not automatically require distributing the
1844 other auxiliary files. It checks for @file{install.sh} also, but that
1845 name is obsolete because some @code{make} have a rule that creates
1846 @file{install} from it if there is no @file{Makefile}.
1848 The auxiliary directory is commonly named @file{build-aux}.
1849 If you need portability to @acronym{DOS} variants, do not name the
1850 auxiliary directory @file{aux}. @xref{File System Conventions}.
1853 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1854 @acindex{REQUIRE_AUX_FILE}
1855 Declares that @var{file} is expected in the directory defined above. In
1856 Autoconf proper, this macro does nothing: its sole purpose is to be
1857 traced by third-party tools to produce a list of expected auxiliary
1858 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
1859 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1860 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1863 Similarly, packages that use @command{aclocal} should declare where
1864 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1866 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1867 @acindex{CONFIG_MACRO_DIR}
1868 Future versions of @command{autopoint}, @command{libtoolize},
1869 @command{aclocal} and @command{autoreconf} will use directory
1870 @var{dir} as the location of additional local Autoconf macros. Be
1871 sure to call this macro directly from @file{configure.ac} so that
1872 tools that install macros for @command{aclocal} can find the
1873 declaration before @option{--trace} can be called safely.
1878 @section Outputting Files
1879 @cindex Outputting files
1881 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1882 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1883 @file{config.status}, which will create the @file{Makefile}s and any
1884 other files resulting from configuration. This is the only required
1885 macro besides @code{AC_INIT} (@pxref{Input}).
1889 @cindex Instantiation
1890 Generate @file{config.status} and launch it. Call this macro once, at
1891 the end of @file{configure.ac}.
1893 @file{config.status} will perform all the configuration actions: all the
1894 output files (see @ref{Configuration Files}, macro
1895 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1896 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1897 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1898 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1899 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1902 The location of your @code{AC_OUTPUT} invocation is the exact point
1903 where configuration actions are taken: any code afterwards will be
1904 executed by @code{configure} once @command{config.status} was run. If
1905 you want to bind actions to @command{config.status} itself
1906 (independently of whether @command{configure} is being run), see
1907 @ref{Configuration Commands, , Running Arbitrary Configuration
1911 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1912 @xref{Obsolete Macros}, for a description of the arguments that
1913 @code{AC_OUTPUT} used to support.
1916 If you run @command{make} in subdirectories, you should run it using the
1917 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1918 @code{MAKE} to the name of the @command{make} program plus any options it
1919 was given. (But many do not include in it the values of any variables
1920 set on the command line, so those are not passed on automatically.)
1921 Some old versions of @command{make} do not set this variable. The
1922 following macro allows you to use it even with those versions.
1924 @defmac AC_PROG_MAKE_SET
1925 @acindex{PROG_MAKE_SET}
1927 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1928 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1929 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1930 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
1934 If you use this macro, place a line like this in each @file{Makefile.in}
1935 that runs @code{MAKE} on other directories:
1943 @node Configuration Actions
1944 @section Performing Configuration Actions
1945 @cindex Configuration actions
1947 @file{configure} is designed so that it appears to do everything itself,
1948 but there is actually a hidden slave: @file{config.status}.
1949 @file{configure} is in charge of examining your system, but it is
1950 @file{config.status} that actually takes the proper actions based on the
1951 results of @file{configure}. The most typical task of
1952 @file{config.status} is to @emph{instantiate} files.
1954 This section describes the common behavior of the four standard
1955 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1956 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
1957 have this prototype:
1959 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1962 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
1966 where the arguments are:
1969 @item @var{tag}@dots{}
1970 A blank-or-newline-separated list of tags, which are typically the names of
1971 the files to instantiate.
1973 You are encouraged to use literals as @var{tags}. In particular, you
1977 @dots{} && my_foos="$my_foos fooo"
1978 @dots{} && my_foos="$my_foos foooo"
1979 AC_CONFIG_FOOS([$my_foos])
1983 and use this instead:
1986 @dots{} && AC_CONFIG_FOOS([fooo])
1987 @dots{} && AC_CONFIG_FOOS([foooo])
1990 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
1991 special @var{tag}s: they may have the form @samp{@var{output}} or
1992 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
1993 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
1995 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
1996 for example, asks for
1997 the creation of @file{Makefile} that will be the expansion of the
1998 output variables in the concatenation of @file{boiler/top.mk} and
1999 @file{boiler/bot.mk}.
2001 The special value @samp{-} might be used to denote the standard output
2002 when used in @var{output}, or the standard input when used in the
2003 @var{inputs}. You most probably don't need to use this in
2004 @file{configure.ac}, but it is convenient when using the command line
2005 interface of @file{./config.status}, see @ref{config.status Invocation},
2008 The @var{inputs} may be absolute or relative file names. In the latter
2009 case they are first looked for in the build tree, and then in the source
2013 Shell commands output literally into @file{config.status}, and
2014 associated with a tag that the user can use to tell @file{config.status}
2015 which the commands to run. The commands are run each time a @var{tag}
2016 request is given to @file{config.status}, typically each time the file
2017 @file{@var{tag}} is created.
2019 The variables set during the execution of @command{configure} are
2020 @emph{not} available here: you first need to set them via the
2021 @var{init-cmds}. Nonetheless the following variables are precomputed:
2025 The name of the top source directory, assuming that the working
2026 directory is the top build directory. This
2027 is what @command{configure}'s option @option{--srcdir} sets.
2030 The name of the top source directory, assuming that the working
2031 directory is the current build directory.
2034 @item ac_top_build_prefix
2035 The name of the top build directory, assuming that the working
2036 directory is the current build directory.
2037 It can be empty, or else ends with a slash, so that you may concatenate
2041 The name of the corresponding source directory, assuming that the
2042 working directory is the current build directory.
2046 The @dfn{current} directory refers to the directory (or
2047 pseudo-directory) containing the input part of @var{tags}. For
2051 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2055 with @option{--srcdir=../package} produces the following values:
2058 # Argument of --srcdir
2060 # Reversing deep/dir
2061 ac_top_build_prefix='../../'
2062 # Concatenation of $ac_top_build_prefix and srcdir
2063 ac_top_srcdir='../../../package'
2064 # Concatenation of $ac_top_srcdir and deep/dir
2065 ac_srcdir='../../../package/deep/dir'
2069 independently of @samp{in/in.in}.
2072 Shell commands output @emph{unquoted} near the beginning of
2073 @file{config.status}, and executed each time @file{config.status} runs
2074 (regardless of the tag). Because they are unquoted, for example,
2075 @samp{$var} will be output as the value of @code{var}. @var{init-cmds}
2076 is typically used by @file{configure} to give @file{config.status} some
2077 variables it needs to run the @var{commands}.
2079 You should be extremely cautious in your variable names: all the
2080 @var{init-cmds} share the same name space and may overwrite each other
2081 in unpredictable ways. Sorry@enddots{}
2084 All these macros can be called multiple times, with different
2085 @var{tag}s, of course!
2088 @node Configuration Files
2089 @section Creating Configuration Files
2090 @cindex Creating configuration files
2091 @cindex Configuration file creation
2093 Be sure to read the previous section, @ref{Configuration Actions}.
2095 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2096 @acindex{CONFIG_FILES}
2097 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2098 file (by default @file{@var{file}.in}), substituting the output variable
2100 @c Before we used to have this feature, which was later rejected
2101 @c because it complicates the write of Makefiles:
2102 @c If the file would be unchanged, it is left untouched, to preserve
2104 This macro is one of the instantiating macros; see @ref{Configuration
2105 Actions}. @xref{Makefile Substitutions}, for more information on using
2106 output variables. @xref{Setting Output Variables}, for more information
2107 on creating them. This macro creates the directory that the file is in
2108 if it doesn't exist. Usually, @file{Makefile}s are created this way,
2109 but other files, such as @file{.gdbinit}, can be specified as well.
2111 Typical calls to @code{AC_CONFIG_FILES} look like this:
2114 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2115 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2118 You can override an input file name by appending to @var{file} a
2119 colon-separated list of input files. Examples:
2122 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2123 [lib/Makefile:boiler/lib.mk])
2127 Doing this allows you to keep your file names acceptable to
2128 @acronym{DOS} variants, or
2129 to prepend and/or append boilerplate to the file.
2134 @node Makefile Substitutions
2135 @section Substitutions in Makefiles
2136 @cindex Substitutions in makefiles
2137 @cindex Makefile substitutions
2139 Each subdirectory in a distribution that contains something to be
2140 compiled or installed should come with a file @file{Makefile.in}, from
2141 which @command{configure} will create a @file{Makefile} in that directory.
2142 To create a @file{Makefile}, @command{configure} performs a simple variable
2143 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2144 @file{Makefile.in} with the value that @command{configure} has determined
2145 for that variable. Variables that are substituted into output files in
2146 this way are called @dfn{output variables}. They are ordinary shell
2147 variables that are set in @command{configure}. To make @command{configure}
2148 substitute a particular variable into the output files, the macro
2149 @code{AC_SUBST} must be called with that variable name as an argument.
2150 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2151 left unchanged. @xref{Setting Output Variables}, for more information
2152 on creating output variables with @code{AC_SUBST}.
2154 A software package that uses a @command{configure} script should be
2155 distributed with a file @file{Makefile.in}, but no @file{Makefile}; that
2156 way, the user has to properly configure the package for the local system
2157 before compiling it.
2159 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2160 @acronym{GNU} Coding Standards}, for more information on what to put in
2164 * Preset Output Variables:: Output variables that are always set
2165 * Installation Directory Variables:: Other preset output variables
2166 * Build Directories:: Supporting multiple concurrent compiles
2167 * Automatic Remaking:: Makefile rules for configuring
2170 @node Preset Output Variables
2171 @subsection Preset Output Variables
2172 @cindex Output variables
2174 Some output variables are preset by the Autoconf macros. Some of the
2175 Autoconf macros set additional output variables, which are mentioned in
2176 the descriptions for those macros. @xref{Output Variable Index}, for a
2177 complete list of output variables. @xref{Installation Directory
2178 Variables}, for the list of the preset ones related to installation
2179 directories. Below are listed the other preset ones. They all are
2180 precious variables (@pxref{Setting Output Variables},
2183 @c Just say no to ASCII sorting! We're humans, not computers.
2184 @c These variables are listed as they would be in a dictionary:
2191 Debugging and optimization options for the C compiler. If it is not set
2192 in the environment when @command{configure} runs, the default value is set
2193 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2194 uses this variable when compiling programs to test for C features.
2197 @defvar configure_input
2198 @ovindex configure_input
2199 A comment saying that the file was generated automatically by
2200 @command{configure} and giving the name of the input file.
2201 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2202 of every @file{Makefile} it creates. For other files, you should
2203 reference this variable in a comment at the top of each input file. For
2204 example, an input shell script should begin like this:
2208 # @@configure_input@@
2212 The presence of that line also reminds people editing the file that it
2213 needs to be processed by @command{configure} in order to be used.
2218 Header file search directory (@option{-I@var{dir}}) and any other
2219 miscellaneous options for the C and C++ preprocessors and compilers. If
2220 it is not set in the environment when @command{configure} runs, the default
2221 value is empty. @command{configure} uses this variable when compiling or
2222 preprocessing programs to test for C and C++ features.
2223 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2229 Debugging and optimization options for the C++ compiler. If it is not
2230 set in the environment when @command{configure} runs, the default value is
2231 set when you call @code{AC_PROG_CXX} (or empty if you don't).
2232 @command{configure} uses this variable when compiling programs to test for
2238 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2239 is called, @command{configure} replaces @samp{@@DEFS@@} with
2240 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2241 variable is not defined while @command{configure} is performing its tests,
2242 only when creating the output files. @xref{Setting Output Variables}, for
2243 how to check the results of previous tests.
2252 How does one suppress the trailing newline from @command{echo} for
2253 question-answer message pairs? These variables provide a way:
2256 echo $ECHO_N "And the winner is... $ECHO_C"
2258 echo "$@{ECHO_T@}dead."
2262 Some old and uncommon @command{echo} implementations offer no means to
2263 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2269 Debugging and optimization options for the Erlang compiler. If it is not set
2270 in the environment when @command{configure} runs, the default value is empty.
2271 @command{configure} uses this variable when compiling programs to test for
2277 Debugging and optimization options for the Fortran compiler. If it
2278 is not set in the environment when @command{configure} runs, the default
2279 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2280 @command{configure} uses this variable when compiling programs to test for
2286 Debugging and optimization options for the Fortran 77 compiler. If it
2287 is not set in the environment when @command{configure} runs, the default
2288 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2289 @command{configure} uses this variable when compiling programs to test for
2290 Fortran 77 features.
2295 Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
2296 options for the linker. Don't use this variable to pass library names
2297 (@option{-l}) to the linker, use @code{LIBS} instead. If it is not set
2298 in the environment when @command{configure} runs, the default value is empty.
2299 @command{configure} uses this variable when linking programs to test for
2300 C, C++, and Fortran features.
2305 @option{-l} options to pass to the linker. The default value is empty,
2306 but some Autoconf macros may prepend extra libraries to this variable if
2307 those libraries are found and provide necessary functions, see
2308 @ref{Libraries}. @command{configure} uses this variable when linking
2309 programs to test for C, C++, and Fortran features.
2314 Debugging and optimization options for the Objective C compiler. If it is
2315 not set in the environment when @command{configure} runs, the default value
2316 is set when you call @code{AC_PROG_OBJC} (or empty if you don't).
2317 @command{configure} uses this variable when compiling programs to test for
2318 Objective C features.
2323 Rigorously equal to @samp{.}. Added for symmetry only.
2326 @defvar abs_builddir
2327 @ovindex abs_builddir
2328 Absolute name of @code{builddir}.
2331 @defvar top_builddir
2332 @ovindex top_builddir
2333 The relative name of the top level of the current build tree. In the
2334 top-level directory, this is the same as @code{builddir}.
2337 @defvar abs_top_builddir
2338 @ovindex abs_top_builddir
2339 Absolute name of @code{top_builddir}.
2344 The relative name of the directory that contains the source code for
2345 that @file{Makefile}.
2350 Absolute name of @code{srcdir}.
2355 The relative name of the top-level source code directory for the
2356 package. In the top-level directory, this is the same as @code{srcdir}.
2359 @defvar abs_top_srcdir
2360 @ovindex abs_top_srcdir
2361 Absolute name of @code{top_srcdir}.
2364 @node Installation Directory Variables
2365 @subsection Installation Directory Variables
2366 @cindex Installation directories
2367 @cindex Directories, installation
2369 The following variables specify the directories where the package will
2370 be installed, see @ref{Directory Variables, , Variables for
2371 Installation Directories, standards, The @acronym{GNU} Coding
2372 Standards}, for more information. See the end of this section for
2373 details on when and how to use these variables.
2377 The directory for installing executables that users run.
2382 The directory for installing idiosyncratic read-only
2383 architecture-independent data.
2387 @ovindex datarootdir
2388 The root of the directory tree for read-only architecture-independent
2394 The directory for installing documentation files (other than Info and
2400 The directory for installing documentation files in DVI format.
2404 @ovindex exec_prefix
2405 The installation prefix for architecture-dependent files. By default
2406 it's the same as @var{prefix}. You should avoid installing anything
2407 directly to @var{exec_prefix}. However, the default value for
2408 directories containing architecture-dependent files should be relative
2409 to @var{exec_prefix}.
2414 The directory for installing HTML documentation.
2419 The directory for installing C header files.
2424 The directory for installing documentation in Info format.
2429 The directory for installing object code libraries.
2434 The directory for installing executables that other programs run.
2439 The directory for installing locale-dependent but
2440 architecture-independent data, such as message catalogs. This directory
2441 usually has a subdirectory per locale.
2444 @defvar localstatedir
2445 @ovindex localstatedir
2446 The directory for installing modifiable single-machine data.
2451 The top-level directory for installing documentation in man format.
2454 @defvar oldincludedir
2455 @ovindex oldincludedir
2456 The directory for installing C header files for non-GCC compilers.
2461 The directory for installing PDF documentation.
2466 The common installation prefix for all files. If @var{exec_prefix}
2467 is defined to a different value, @var{prefix} is used only for
2468 architecture-independent files.
2473 The directory for installing PostScript documentation.
2478 The directory for installing executables that system
2482 @defvar sharedstatedir
2483 @ovindex sharedstatedir
2484 The directory for installing modifiable architecture-independent data.
2489 The directory for installing read-only single-machine data.
2493 Most of these variables have values that rely on @code{prefix} or
2494 @code{exec_prefix}. It is deliberate that the directory output
2495 variables keep them unexpanded: typically @samp{@@datarootdir@@} will be
2496 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2497 @samp{@@datadir@@} will be replaced by @samp{$@{datarootdir@}}.
2499 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2504 she can still specify a different prefix from the one specified to
2505 @command{configure}, in which case, if needed, the package shall hard
2506 code dependencies corresponding to the make-specified prefix.
2509 she can specify a different installation location, in which case the
2510 package @emph{must} still depend on the location which was compiled in
2511 (i.e., never recompile when @samp{make install} is run). This is an
2512 extremely important feature, as many people may decide to install all
2513 the files of a package grouped together, and then install links from
2514 the final locations to there.
2517 In order to support these features, it is essential that
2518 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2519 depend upon the current value of @code{prefix}.
2521 A corollary is that you should not use these variables except in
2522 Makefiles. For instance, instead of trying to evaluate @code{datadir}
2523 in @file{configure} and hard-coding it in Makefiles using
2524 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2526 @option{-DDATADIR='$(datadir)'} to your Makefile's definition of
2527 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2529 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2530 @code{datadir} and friends in your shell scripts and other files, rather
2531 let @command{make} manage their replacement. For instance Autoconf
2532 ships templates of its shell scripts ending with @samp{.in}, and uses a
2533 Makefile snippet similar to:
2538 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2539 -e 's|@@prefix[@@]|$(prefix)|g'
2543 autoconf: Makefile $(srcdir)/autoconf.in
2544 rm -f autoconf autoconf.tmp
2545 $(edit) $(srcdir)/autoconf.in >autoconf.tmp
2546 chmod +x autoconf.tmp
2547 mv autoconf.tmp autoconf
2551 autoheader: Makefile $(srcdir)/autoheader.in
2552 rm -f autoheader autoheader.tmp
2553 $(edit) $(srcdir)/autoconf.in >autoheader.tmp
2554 chmod +x autoheader.tmp
2555 mv autoheader.tmp autoheader
2559 Some details are noteworthy:
2563 The brackets prevent @command{configure} from replacing
2564 @samp{@@datadir@@} in the Sed expression itself.
2565 Brackets are preferable to a backslash here, since
2566 Posix says @samp{\@@} is not portable.
2569 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2573 Don't use @samp{/} in the Sed expression(s) since most likely the
2574 variables you use, such as @samp{$(pkgdatadir)}, will contain
2577 @item Dependency on @file{Makefile}
2578 Since @code{edit} uses values that depend on the configuration specific
2579 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2580 the output depends on @file{Makefile}, not @file{configure.ac}.
2582 @item Separated dependencies and Single Suffix Rules
2583 You can't use them! The above snippet cannot be (portably) rewritten
2587 autoconf autoheader: Makefile
2597 @xref{Limitations of Make}, for details.
2599 @item @samp{$(srcdir)}
2600 Be sure to specify the name of the source directory,
2601 otherwise the package won't support separated builds.
2604 For the more specific installation of Erlang libraries, the following variables
2607 @defvar ERLANG_INSTALL_LIB_DIR
2608 @ovindex ERLANG_INSTALL_LIB_DIR
2609 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2610 The common parent directory of Erlang library installation directories.
2611 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2612 macro in @file{configure.ac}.
2615 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2616 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2617 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2618 The installation directory for Erlang library @var{library}.
2619 This variable is set by calling the
2620 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2621 macro in @file{configure.ac}.
2624 @xref{Erlang Libraries}, for details.
2627 @node Build Directories
2628 @subsection Build Directories
2629 @cindex Build directories
2630 @cindex Directories, build
2632 You can support compiling a software package for several architectures
2633 simultaneously from the same copy of the source code. The object files
2634 for each architecture are kept in their own directory.
2636 To support doing this, @command{make} uses the @code{VPATH} variable to
2637 find the files that are in the source directory. @acronym{GNU} Make
2638 and most other recent @command{make} programs can do this. Older
2639 @command{make} programs do not support @code{VPATH}; when using them, the
2640 source code must be in the same directory as the object files.
2642 To support @code{VPATH}, each @file{Makefile.in} should contain two
2643 lines that look like:
2650 Do not set @code{VPATH} to the value of another variable, for example
2651 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2652 variable substitutions on the value of @code{VPATH}.
2654 @command{configure} substitutes the correct value for @code{srcdir} when
2655 it produces @file{Makefile}.
2657 Do not use the @code{make} variable @code{$<}, which expands to the
2658 file name of the file in the source directory (found with @code{VPATH}),
2659 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2660 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2661 versions of @command{make} do not set @code{$<} in explicit rules; they
2662 expand it to an empty value.
2664 Instead, @file{Makefile} command lines should always refer to source
2665 files by prefixing them with @samp{$(srcdir)/}. For example:
2668 time.info: time.texinfo
2669 $(MAKEINFO) $(srcdir)/time.texinfo
2672 @node Automatic Remaking
2673 @subsection Automatic Remaking
2674 @cindex Automatic remaking
2675 @cindex Remaking automatically
2677 You can put rules like the following in the top-level @file{Makefile.in}
2678 for a package to automatically update the configuration information when
2679 you change the configuration files. This example includes all of the
2680 optional files, such as @file{aclocal.m4} and those related to
2681 configuration header files. Omit from the @file{Makefile.in} rules for
2682 any of these files that your package does not use.
2684 The @samp{$(srcdir)/} prefix is included because of limitations in the
2685 @code{VPATH} mechanism.
2687 The @file{stamp-} files are necessary because the timestamps of
2688 @file{config.h.in} and @file{config.h} will not be changed if remaking
2689 them does not change their contents. This feature avoids unnecessary
2690 recompilation. You should include the file @file{stamp-h.in} your
2691 package's distribution, so @command{make} will consider
2692 @file{config.h.in} up to date. Don't use @command{touch}
2693 (@pxref{Limitations of Usual Tools}), rather use @command{echo} (using
2694 @command{date} would cause needless differences, hence @acronym{CVS}
2699 $(srcdir)/configure: configure.ac aclocal.m4
2700 cd $(srcdir) && autoconf
2702 # autoheader might not change config.h.in, so touch a stamp file.
2703 $(srcdir)/config.h.in: stamp-h.in
2704 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2705 cd $(srcdir) && autoheader
2706 echo timestamp > $(srcdir)/stamp-h.in
2709 stamp-h: config.h.in config.status
2712 Makefile: Makefile.in config.status
2715 config.status: configure
2716 ./config.status --recheck
2721 (Be careful if you copy these lines directly into your Makefile, as you
2722 will need to convert the indented lines to start with the tab character.)
2724 In addition, you should use
2727 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2731 so @file{config.status} will ensure that @file{config.h} is considered up to
2732 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
2734 @xref{config.status Invocation}, for more examples of handling
2735 configuration-related dependencies.
2737 @node Configuration Headers
2738 @section Configuration Header Files
2739 @cindex Configuration Header
2740 @cindex @file{config.h}
2742 When a package contains more than a few tests that define C preprocessor
2743 symbols, the command lines to pass @option{-D} options to the compiler
2744 can get quite long. This causes two problems. One is that the
2745 @command{make} output is hard to visually scan for errors. More
2746 seriously, the command lines can exceed the length limits of some
2747 operating systems. As an alternative to passing @option{-D} options to
2748 the compiler, @command{configure} scripts can create a C header file
2749 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2750 macro selects this kind of output. Though it can be called anywhere
2751 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2752 it right after @code{AC_INIT}.
2754 The package should @samp{#include} the configuration header file before
2755 any other header files, to prevent inconsistencies in declarations (for
2756 example, if it redefines @code{const}).
2758 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2759 option (or @option{-I..}; whichever directory contains @file{config.h}).
2760 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2761 the directory of the currently read file, i.e., the source directory, not
2762 the build directory.
2764 With the appropriate @option{-I} option, you can use
2765 @samp{#include <config.h>}. Actually, it's a good habit to use it,
2766 because in the rare case when the source directory contains another
2767 @file{config.h}, the build directory should be searched first.
2770 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2771 @acindex{CONFIG_HEADERS}
2772 @cvindex HAVE_CONFIG_H
2773 This macro is one of the instantiating macros; see @ref{Configuration
2774 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2775 blank-or-newline-separated list @var{header} containing C preprocessor
2776 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2777 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2778 The usual name for @var{header} is @file{config.h}.
2780 If @var{header} already exists and its contents are identical to what
2781 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2782 making some changes in the configuration without needlessly causing
2783 object files that depend on the header file to be recompiled.
2785 Usually the input file is named @file{@var{header}.in}; however, you can
2786 override the input file name by appending to @var{header} a
2787 colon-separated list of input files. Examples:
2790 AC_CONFIG_HEADERS([config.h:config.hin])
2791 AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
2795 Doing this allows you to keep your file names acceptable to
2796 @acronym{DOS} variants, or
2797 to prepend and/or append boilerplate to the file.
2802 This macro is defined as the name of the first declared config header
2803 and undefined if no config headers have been declared up to this point.
2804 A third-party macro may, for example, require use of a config header
2805 without invoking AC_CONFIG_HEADERS twice, like this:
2808 AC_CONFIG_COMMANDS_PRE(
2809 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2814 @xref{Configuration Actions}, for more details on @var{header}.
2817 * Header Templates:: Input for the configuration headers
2818 * autoheader Invocation:: How to create configuration templates
2819 * Autoheader Macros:: How to specify CPP templates
2822 @node Header Templates
2823 @subsection Configuration Header Templates
2824 @cindex Configuration Header Template
2825 @cindex Header templates
2826 @cindex @file{config.h.in}
2828 Your distribution should contain a template file that looks as you want
2829 the final header file to look, including comments, with @code{#undef}
2830 statements which are used as hooks. For example, suppose your
2831 @file{configure.ac} makes these calls:
2834 AC_CONFIG_HEADERS([conf.h])
2835 AC_CHECK_HEADERS([unistd.h])
2839 Then you could have code like the following in @file{conf.h.in}. On
2840 systems that have @file{unistd.h}, @command{configure} will @samp{#define}
2841 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line will be
2842 commented out (in case the system predefines that symbol).
2846 /* Define as 1 if you have unistd.h. */
2847 #undef HAVE_UNISTD_H
2851 Pay attention that @samp{#undef} is in the first column, and there is
2852 nothing after @samp{HAVE_UNISTD_H}, not even white space. You can
2853 then decode the configuration header using the preprocessor directives:
2860 # include <unistd.h>
2862 /* We are in trouble. */
2867 The use of old form templates, with @samp{#define} instead of
2868 @samp{#undef} is strongly discouraged. Similarly with old templates
2869 with comments on the same line as the @samp{#undef}. Anyway, putting
2870 comments in preprocessor macros has never been a good idea.
2872 Since it is a tedious task to keep a template header up to date, you may
2873 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
2876 @node autoheader Invocation
2877 @subsection Using @command{autoheader} to Create @file{config.h.in}
2878 @cindex @command{autoheader}
2880 The @command{autoheader} program can create a template file of C
2881 @samp{#define} statements for @command{configure} to use. If
2882 @file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
2883 @command{autoheader} creates @file{@var{file}.in}; if multiple file
2884 arguments are given, the first one is used. Otherwise,
2885 @command{autoheader} creates @file{config.h.in}.
2887 In order to do its job, @command{autoheader} needs you to document all
2888 of the symbols that you might use. Typically this is done via an
2889 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
2890 is a literal symbol and whose third argument describes the symbol
2891 (@pxref{Defining Symbols}). Alternatively, you can use
2892 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
2893 suitable input file for a subsequent configuration header file.
2894 Symbols defined by Autoconf's builtin tests are already documented properly;
2895 you need to document only those that you
2898 You might wonder why @command{autoheader} is needed: after all, why
2899 would @command{configure} need to ``patch'' a @file{config.h.in} to
2900 produce a @file{config.h} instead of just creating @file{config.h} from
2901 scratch? Well, when everything rocks, the answer is just that we are
2902 wasting our time maintaining @command{autoheader}: generating
2903 @file{config.h} directly is all that is needed. When things go wrong,
2904 however, you'll be thankful for the existence of @command{autoheader}.
2906 The fact that the symbols are documented is important in order to
2907 @emph{check} that @file{config.h} makes sense. The fact that there is a
2908 well-defined list of symbols that should be @code{#define}'d (or not) is
2909 also important for people who are porting packages to environments where
2910 @command{configure} cannot be run: they just have to @emph{fill in the
2913 But let's come back to the point: @command{autoheader}'s invocation@dots{}
2915 If you give @command{autoheader} an argument, it uses that file instead
2916 of @file{configure.ac} and writes the header file to the standard output
2917 instead of to @file{config.h.in}. If you give @command{autoheader} an
2918 argument of @option{-}, it reads the standard input instead of
2919 @file{configure.ac} and writes the header file to the standard output.
2921 @command{autoheader} accepts the following options:
2926 Print a summary of the command line options and exit.
2930 Print the version number of Autoconf and exit.
2934 Report processing steps.
2938 Don't remove the temporary files.
2942 Remake the template file even if newer than its input files.
2944 @item --include=@var{dir}
2946 Append @var{dir} to the include path. Multiple invocations accumulate.
2948 @item --prepend-include=@var{dir}
2950 Prepend @var{dir} to the include path. Multiple invocations accumulate.
2952 @item --warnings=@var{category}
2953 @itemx -W @var{category}
2955 Report the warnings related to @var{category} (which can actually be a
2956 comma separated list). Current categories include:
2960 report the uses of obsolete constructs
2963 report all the warnings
2969 treats warnings as errors
2971 @item no-@var{category}
2972 disable warnings falling into @var{category}
2979 @node Autoheader Macros
2980 @subsection Autoheader Macros
2981 @cindex Autoheader macros
2983 @command{autoheader} scans @file{configure.ac} and figures out which C
2984 preprocessor symbols it might define. It knows how to generate
2985 templates for symbols defined by @code{AC_CHECK_HEADERS},
2986 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
2987 symbol, you must define a template for it. If there are missing
2988 templates, @command{autoheader} fails with an error message.
2990 The simplest way to create a template for a @var{symbol} is to supply
2991 the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
2992 @ref{Defining Symbols}. You may also use one of the following macros.
2994 @defmac AH_VERBATIM (@var{key}, @var{template})
2996 Tell @command{autoheader} to include the @var{template} as-is in the header
2997 template file. This @var{template} is associated with the @var{key},
2998 which is used to sort all the different templates and guarantee their
2999 uniqueness. It should be a symbol that can be @code{AC_DEFINE}'d.
3004 AH_VERBATIM([_GNU_SOURCE],
3005 [/* Enable GNU extensions on systems that have them. */
3007 # define _GNU_SOURCE
3013 @defmac AH_TEMPLATE (@var{key}, @var{description})
3015 Tell @command{autoheader} to generate a template for @var{key}. This macro
3016 generates standard templates just like @code{AC_DEFINE} when a
3017 @var{description} is given.
3022 AH_TEMPLATE([CRAY_STACKSEG_END],
3023 [Define to one of _getb67, GETB67, getb67
3024 for Cray-2 and Cray-YMP systems. This
3025 function is required for alloca.c support
3030 will generate the following template, with the description properly
3034 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3035 Cray-YMP systems. This function is required for alloca.c
3036 support on those systems. */
3037 #undef CRAY_STACKSEG_END
3042 @defmac AH_TOP (@var{text})
3044 Include @var{text} at the top of the header template file.
3048 @defmac AH_BOTTOM (@var{text})
3050 Include @var{text} at the bottom of the header template file.
3054 @node Configuration Commands
3055 @section Running Arbitrary Configuration Commands
3056 @cindex Configuration commands
3057 @cindex Commands for configuration
3059 You can execute arbitrary commands before, during, and after
3060 @file{config.status} is run. The three following macros accumulate the
3061 commands to run when they are called multiple times.
3062 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3063 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3065 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3066 @acindex{CONFIG_COMMANDS}
3067 Specify additional shell commands to run at the end of
3068 @file{config.status}, and shell commands to initialize any variables
3069 from @command{configure}. Associate the commands with @var{tag}.
3070 Since typically the @var{cmds} create a file, @var{tag} should
3071 naturally be the name of that file. If needed, the directory hosting
3072 @var{tag} is created. This macro is one of the instantiating macros;
3073 see @ref{Configuration Actions}.
3075 Here is an unrealistic example:
3078 AC_CONFIG_COMMANDS([fubar],
3079 [echo this is extra $fubar, and so on.],
3083 Here is a better one:
3085 AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp])
3089 The following two macros look similar, but in fact they are not of the same
3090 breed: they are executed directly by @file{configure}, so you cannot use
3091 @file{config.status} to re-run them.
3093 @c Yet it is good to leave them here. The user sees them together and
3094 @c decides which best fits their needs.
3096 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3097 @acindex{CONFIG_COMMANDS_PRE}
3098 Execute the @var{cmds} right before creating @file{config.status}.
3100 This macro presents the last opportunity to call @code{AC_SUBST},
3101 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3104 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3105 @acindex{CONFIG_COMMANDS_POST}
3106 Execute the @var{cmds} right after creating @file{config.status}.
3112 @node Configuration Links
3113 @section Creating Configuration Links
3114 @cindex Configuration links
3115 @cindex Links for configuration
3117 You may find it convenient to create links whose destinations depend upon
3118 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3119 creation of relative symbolic links can be delicate when the package is
3120 built in a directory different from the source directory.
3122 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3123 @acindex{CONFIG_LINKS}
3125 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3126 the corresponding link name @var{dest}. Makes a symbolic link if
3127 possible, otherwise a hard link if possible, otherwise a copy. The
3128 @var{dest} and @var{source} names should be relative to the top level
3129 source or build directory. This macro is one of the instantiating
3130 macros; see @ref{Configuration Actions}.
3132 For example, this call:
3135 AC_CONFIG_LINKS([host.h:config/$machine.h
3136 object.h:config/$obj_format.h])
3140 creates in the current directory @file{host.h} as a link to
3141 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3142 link to @file{@var{srcdir}/config/$obj_format.h}.
3144 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3145 impossible for @samp{config.status} to guess the links to establish.
3149 ./config.status host.h object.h
3152 to create the links.
3157 @node Subdirectories
3158 @section Configuring Other Packages in Subdirectories
3159 @cindex Configure subdirectories
3160 @cindex Subdirectory configure
3162 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3163 @file{Makefile}s in subdirectories. However, @command{configure} scripts
3164 that control more than one independent package can use
3165 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3166 packages in subdirectories.
3168 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3169 @acindex{CONFIG_SUBDIRS}
3171 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3172 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3173 be a literal, i.e., please do not use:
3176 if test "$package_foo_enabled" = yes; then
3177 $my_subdirs="$my_subdirs foo"
3179 AC_CONFIG_SUBDIRS([$my_subdirs])
3183 because this prevents @samp{./configure --help=recursive} from
3184 displaying the options of the package @code{foo}. Rather, you should
3188 if test "$package_foo_enabled" = yes; then
3189 AC_CONFIG_SUBDIRS([foo])
3193 If a given @var{dir} is not found, an error is reported: if the
3194 subdirectory is optional, write:
3197 if test -d $srcdir/foo; then
3198 AC_CONFIG_SUBDIRS([foo])
3202 @c NB: Yes, below we mean configure.in, not configure.ac.
3203 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3204 of @command{configure}. This is for packages that might use a
3205 non-Autoconf script @command{Configure}, which can't be called through a
3206 wrapper @command{configure} since it would be the same file on
3207 case-insensitive file systems. Likewise, if a @var{dir} contains
3208 @file{configure.in} but no @command{configure}, the Cygnus
3209 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3211 The subdirectory @command{configure} scripts are given the same command
3212 line options that were given to this @command{configure} script, with minor
3213 changes if needed, which include:
3217 adjusting a relative name for the cache file;
3220 adjusting a relative name for the source directory;
3223 propagating the current value of @code{$prefix}, including if it was
3224 defaulted, and if the default values of the top level and of the subdirectory
3225 @file{configure} differ.
3228 This macro also sets the output variable @code{subdirs} to the list of
3229 directories @samp{@var{dir} @dots{}}. @file{Makefile} rules can use
3230 this variable to determine which subdirectories to recurse into.
3232 This macro may be called multiple times.
3235 @node Default Prefix
3236 @section Default Prefix
3237 @cindex Install prefix
3238 @cindex Prefix for install
3240 By default, @command{configure} sets the prefix for files it installs to
3241 @file{/usr/local}. The user of @command{configure} can select a different
3242 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3243 There are two ways to change the default: when creating
3244 @command{configure}, and when running it.
3246 Some software packages might want to install in a directory other than
3247 @file{/usr/local} by default. To accomplish that, use the
3248 @code{AC_PREFIX_DEFAULT} macro.
3250 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3251 @acindex{PREFIX_DEFAULT}
3252 Set the default installation prefix to @var{prefix} instead of
3256 It may be convenient for users to have @command{configure} guess the
3257 installation prefix from the location of a related program that they
3258 have already installed. If you wish to do that, you can call
3259 @code{AC_PREFIX_PROGRAM}.
3261 @defmac AC_PREFIX_PROGRAM (@var{program})
3262 @acindex{PREFIX_PROGRAM}
3263 If the user did not specify an installation prefix (using the
3264 @option{--prefix} option), guess a value for it by looking for
3265 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3266 is found, set the prefix to the parent of the directory containing
3267 @var{program}, else default the prefix as described above
3268 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3269 @var{program} is @code{gcc} and the @env{PATH} contains
3270 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3275 @c ======================================================== Existing tests
3277 @node Existing Tests
3278 @chapter Existing Tests
3280 These macros test for particular system features that packages might
3281 need or want to use. If you need to test for a kind of feature that
3282 none of these macros check for, you can probably do it by calling
3283 primitive test macros with appropriate arguments (@pxref{Writing
3286 These tests print messages telling the user which feature they're
3287 checking for, and what they find. They cache their results for future
3288 @command{configure} runs (@pxref{Caching Results}).
3290 Some of these macros set output variables. @xref{Makefile
3291 Substitutions}, for how to get their values. The phrase ``define
3292 @var{name}'' is used below as a shorthand to mean ``define C
3293 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3294 Symbols}, for how to get those symbol definitions into your program.
3297 * Common Behavior:: Macros' standard schemes
3298 * Alternative Programs:: Selecting between alternative programs
3299 * Files:: Checking for the existence of files
3300 * Libraries:: Library archives that might be missing
3301 * Library Functions:: C library functions that might be missing
3302 * Header Files:: Header files that might be missing
3303 * Declarations:: Declarations that may be missing
3304 * Structures:: Structures or members that might be missing
3305 * Types:: Types that might be missing
3306 * Compilers and Preprocessors:: Checking for compiling programs
3307 * System Services:: Operating system services
3308 * Posix Variants:: Special kludges for specific Posix variants
3309 * Erlang Libraries:: Checking for the existence of Erlang libraries
3312 @node Common Behavior
3313 @section Common Behavior
3314 @cindex Common autoconf behavior
3316 Much effort has been expended to make Autoconf easy to learn. The most
3317 obvious way to reach this goal is simply to enforce standard interfaces
3318 and behaviors, avoiding exceptions as much as possible. Because of
3319 history and inertia, unfortunately, there are still too many exceptions
3320 in Autoconf; nevertheless, this section describes some of the common
3324 * Standard Symbols:: Symbols defined by the macros
3325 * Default Includes:: Includes used by the generic macros
3328 @node Standard Symbols
3329 @subsection Standard Symbols
3330 @cindex Standard symbols
3332 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3333 their test transform their @var{argument}s to a standard alphabet.
3334 First, @var{argument} is converted to upper case and any asterisks
3335 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3336 that are not alphanumeric are converted to underscores.
3341 AC_CHECK_TYPES([struct $Expensive*])
3345 will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3349 @node Default Includes
3350 @subsection Default Includes
3351 @cindex Default includes
3352 @cindex Includes, default
3354 Several tests depend upon a set of header files. Since these headers
3355 are not universally available, tests actually have to provide a set of
3356 protected includes, such as:
3360 #if TIME_WITH_SYS_TIME
3361 # include <sys/time.h>
3364 # if HAVE_SYS_TIME_H
3365 # include <sys/time.h>
3374 Unless you know exactly what you are doing, you should avoid using
3375 unconditional includes, and check the existence of the headers you
3376 include beforehand (@pxref{Header Files}).
3378 Most generic macros use the following macro to provide the default set
3381 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3382 @acindex{INCLUDES_DEFAULT}
3383 Expand to @var{include-directives} if defined, otherwise to:
3388 #if HAVE_SYS_TYPES_H
3389 # include <sys/types.h>
3392 # include <sys/stat.h>
3395 # include <stdlib.h>
3396 # include <stddef.h>
3399 # include <stdlib.h>
3403 # if !STDC_HEADERS && HAVE_MEMORY_H
3404 # include <memory.h>
3406 # include <string.h>
3409 # include <strings.h>
3412 # include <inttypes.h>
3415 # include <stdint.h>
3418 # include <unistd.h>
3423 If the default includes are used, then check for the presence of these
3424 headers and their compatibility, i.e., you don't need to run
3425 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3427 These headers are checked for in the same order as they are included.
3428 For instance, on some systems @file{string.h} and @file{strings.h} both
3429 exist, but conflict. Then @code{HAVE_STRING_H} will be defined, but
3430 @code{HAVE_STRINGS_H} won't.
3433 @node Alternative Programs
3434 @section Alternative Programs
3435 @cindex Programs, checking
3437 These macros check for the presence or behavior of particular programs.
3438 They are used to choose between several alternative programs and to
3439 decide what to do once one has been chosen. If there is no macro
3440 specifically defined to check for a program you need, and you don't need
3441 to check for any special properties of it, then you can use one of the
3442 general program-check macros.
3445 * Particular Programs:: Special handling to find certain programs
3446 * Generic Programs:: How to find other programs
3449 @node Particular Programs
3450 @subsection Particular Program Checks
3452 These macros check for particular programs---whether they exist, and
3453 in some cases whether they support certain features.
3458 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3459 order, and set output variable @code{AWK} to the first one that is found.
3460 It tries @code{gawk} first because that is reported to be the
3461 best implementation.
3464 @defmac AC_PROG_GREP
3467 Look for the best available @code{grep} or @code{ggrep} that accepts the
3468 longest input lines possible, and that supports multiple @option{-e} options.
3469 Set the output variable @code{GREP} to whatever is chosen.
3470 @xref{Limitations of Usual Tools}, for more information about
3471 portability problems with the @command{grep} command family.
3474 @defmac AC_PROG_EGREP
3475 @acindex{PROG_EGREP}
3477 Check whether @code{$GREP -E} works, or else look for the best available
3478 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3479 Set the output variable @code{EGREP} to whatever is chosen.
3482 @defmac AC_PROG_FGREP
3483 @acindex{PROG_FGREP}
3485 Check whether @code{$GREP -F} works, or else look for the best available
3486 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3487 Set the output variable @code{FGREP} to whatever is chosen.
3490 @defmac AC_PROG_INSTALL
3491 @acindex{PROG_INSTALL}
3493 @ovindex INSTALL_PROGRAM
3494 @ovindex INSTALL_DATA
3495 @ovindex INSTALL_SCRIPT
3496 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3497 @command{install} program, if one is found in the current @env{PATH}.
3498 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3499 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3500 default directories) to determine @var{dir} (@pxref{Output}). Also set
3501 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3502 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3504 This macro screens out various instances of @command{install} known not to
3505 work. It prefers to find a C program rather than a shell script, for
3506 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3507 but that name is obsolete because some @command{make} programs have a rule
3508 that creates @file{install} from it if there is no @file{Makefile}.
3510 Autoconf comes with a copy of @file{install-sh} that you can use. If
3511 you use @code{AC_PROG_INSTALL}, you must include either
3512 @file{install-sh} or @file{install.sh} in your distribution, or
3513 @command{configure} will produce an error message saying it can't find
3514 them---even if the system you're on has a good @command{install} program.
3515 This check is a safety measure to prevent you from accidentally leaving
3516 that file out, which would prevent your package from installing on
3517 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3519 If you need to use your own installation program because it has features
3520 not found in standard @command{install} programs, there is no reason to use
3521 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3522 @file{Makefile.in} files.
3525 @defmac AC_PROG_MKDIR_P
3526 @acindex{AC_PROG_MKDIR_P}
3528 Set output variable @code{MKDIR_P} to a program that ensures that for
3529 each argument, a directory named by this argument exists, creating it
3530 and its parent directories if needed, and without race conditions when
3531 two instances of the program attempt to make the same directory at
3532 nearly the same time.
3534 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
3535 falls back on invoking @command{install-sh} with the @option{-d} option,
3536 so your package should
3537 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3538 A @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3539 is vulnerable to race conditions, so if you want to support parallel
3541 different packages into the same directory you need to make sure you
3542 have an up-to-date @file{install-sh}. In particular, be careful about
3543 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3545 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3546 in M4sh}), but it sets an output variable intended for use in other
3547 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3548 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
3549 but @code{MKDIR_P} can use the @option{-m} option, e.g., a makefile might
3550 invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible directory.
3551 Finally, @code{AS_MKDIR_P} does not check for race condition
3552 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3559 @cvindex YYTEXT_POINTER
3560 @ovindex LEX_OUTPUT_ROOT
3561 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3562 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3563 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3566 Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
3567 of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3568 the base of the file name that the lexer generates; usually
3569 @file{lex.yy}, but sometimes something else. These results vary
3570 according to whether @code{lex} or @code{flex} is being used.
3572 You are encouraged to use Flex in your sources, since it is both more
3573 pleasant to use than plain Lex and the C source it produces is portable.
3574 In order to ensure portability, however, you must either provide a
3575 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3576 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3577 statement in the scanner's source. Once this done, the scanner is
3578 portable (unless @emph{you} felt free to use nonportable constructs) and
3579 does not depend on any library. In this case, and in this case only, it
3580 is suggested that you use this Autoconf snippet:
3584 if test "$LEX" != flex; then
3585 LEX="$SHELL $missing_dir/missing flex"
3586 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3587 AC_SUBST([LEXLIB], [''])
3591 The shell script @command{missing} can be found in the Automake
3594 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3595 (indirectly) this macro twice, which will cause an annoying but benign
3596 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3597 of Automake will fix this issue; meanwhile, just ignore this message.
3599 As part of running the test, this macro may delete any file in the
3600 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3603 @defmac AC_PROG_LN_S
3606 If @samp{ln -s} works on the current file system (the operating system
3607 and file system support symbolic links), set the output variable
3608 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3609 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3611 If you make a link in a directory other than the current directory, its
3612 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3613 create links using @samp{$(LN_S)}, either find out which form is used
3614 and adjust the arguments, or always invoke @code{ln} in the directory
3615 where the link is to be created.
3617 In other words, it does not work to do:
3625 (cd /x && $(LN_S) foo bar)
3629 @defmac AC_PROG_RANLIB
3630 @acindex{PROG_RANLIB}
3632 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3633 is found, and otherwise to @samp{:} (do nothing).
3639 Set output variable @code{SED} to a Sed implementation that conforms to
3640 Posix and does not have arbitrary length limits. Report an error if no
3641 acceptable Sed is found. @xref{Limitations of Usual Tools}, for more
3642 information about portability problems with Sed.
3645 @defmac AC_PROG_YACC
3648 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3649 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3650 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3653 @node Generic Programs
3654 @subsection Generic Program and File Checks
3656 These macros are used to find programs not covered by the ``particular''
3657 test macros. If you need to check the behavior of a program as well as
3658 find out whether it is present, you have to write your own test for it
3659 (@pxref{Writing Tests}). By default, these macros use the environment
3660 variable @env{PATH}. If you need to check for a program that might not
3661 be in the user's @env{PATH}, you can pass a modified path to use
3665 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3666 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3669 You are strongly encouraged to declare the @var{variable} passed to
3670 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3671 @code{AC_ARG_VAR}, for more details.
3673 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
3674 @acindex{CHECK_PROG}
3675 Check whether program @var{prog-to-check-for} exists in @env{PATH}. If
3676 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3677 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3678 absolute file name) even if it is the first found in the search path; in
3679 that case, set @var{variable} using the absolute file name of the
3680 @var{prog-to-check-for} found that is not @var{reject}. If
3681 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3685 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3686 @acindex{CHECK_PROGS}
3687 Check for each program in the blank-separated list
3688 @var{progs-to-check-for} existing in the @env{PATH}. If one is found, set
3689 @var{variable} to the name of that program. Otherwise, continue
3690 checking the next program in the list. If none of the programs in the
3691 list are found, set @var{variable} to @var{value-if-not-found}; if
3692 @var{value-if-not-found} is not specified, the value of @var{variable}
3693 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3696 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3697 @acindex{CHECK_TARGET_TOOL}
3698 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3699 with a prefix of the target type as determined by
3700 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3701 If the tool cannot be found with a prefix, and if the build and target
3702 types are equal, then it is also searched for without a prefix.
3704 As noted in @ref{Specifying Names, , Specifying the system type}, the
3705 target is rarely specified, because most of the time it is the same
3706 as the host: it is the type of system for which any compiler tools in
3707 the package will produce code. What this macro will look for is,
3708 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3709 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3710 will use to produce objects, archives or executables}.
3713 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3714 @acindex{CHECK_TOOL}
3715 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3716 with a prefix of the host type as determined by
3717 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3718 For example, if the user runs @samp{configure --host=i386-gnu}, then
3721 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3724 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3725 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3726 @env{PATH}, or to @samp{:} if neither program exists.
3728 In the future, when cross-compiling this macro will @emph{only}
3729 accept program names that are prefixed with the host type.
3730 For more information, see @ref{Specifying Names, , Specifying the
3734 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3735 @acindex{CHECK_TARGET_TOOLS}
3736 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3737 @var{progs-to-check-for} are checked with a prefix of the target type as
3738 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3739 (@pxref{Canonicalizing}). If none of the tools can be found with a
3740 prefix, and if the build and target types are equal, then the first one
3741 without a prefix is used. If a tool is found, set @var{variable} to
3742 the name of that program. If none of the tools in the list are found,
3743 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3744 is not specified, the value of @var{variable} is not changed. Calls
3745 @code{AC_SUBST} for @var{variable}.
3748 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3749 @acindex{CHECK_TOOLS}
3750 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3751 @var{progs-to-check-for} are checked with a prefix of the host type as
3752 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3753 (@pxref{Canonicalizing}). If none of the tools can be found with a
3754 prefix, then the first one without a prefix is used. If a tool is found,
3755 set @var{variable} to the name of that program. If none of the tools in
3756 the list are found, set @var{variable} to @var{value-if-not-found}; if
3757 @var{value-if-not-found} is not specified, the value of @var{variable}
3758 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3760 In the future, when cross-compiling this macro will @emph{not}
3761 accept program names that are not prefixed with the host type.
3764 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3766 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3767 name of @var{prog-to-check-for} if found.
3770 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3771 @acindex{PATH_PROGS}
3772 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3773 are found, set @var{variable} to the absolute name of the program
3777 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3778 @acindex{PATH_TARGET_TOOL}
3779 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3780 name of the program if it is found.
3783 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3785 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3786 name of the program if it is found.
3788 In the future, when cross-compiling this macro will @emph{not}
3789 accept program names that are not prefixed with the host type.
3795 @cindex File, checking
3797 You might also need to check for the existence of files. Before using
3798 these macros, ask yourself whether a runtime test might not be a better
3799 solution. Be aware that, like most Autoconf macros, they test a feature
3800 of the host machine, and therefore, they die when cross-compiling.
3802 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3803 @acindex{CHECK_FILE}
3804 Check whether file @var{file} exists on the native system. If it is
3805 found, execute @var{action-if-found}, otherwise do
3806 @var{action-if-not-found}, if given.
3809 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3810 @acindex{CHECK_FILES}
3811 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3812 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3813 for each file found.
3818 @section Library Files
3819 @cindex Library, checking
3821 The following macros check for the presence of certain C, C++, or Fortran
3822 library archive files.
3824 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3826 Test whether the library @var{library} is available by trying to link
3827 a test program that calls function @var{function} with the library.
3828 @var{function} should be a function provided by the library.
3830 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
3831 the @var{library} argument.
3833 @var{action-if-found} is a list of shell commands to run if the link
3834 with the library succeeds; @var{action-if-not-found} is a list of shell
3835 commands to run if the link fails. If @var{action-if-found} is not
3836 specified, the default action will prepend @option{-l@var{library}} to
3837 @code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all
3838 capitals). This macro is intended to support building @code{LIBS} in
3839 a right-to-left (least-dependent to most-dependent) fashion such that
3840 library dependencies are satisfied as a natural side-effect of
3841 consecutive tests. Some linkers are very sensitive to library ordering
3842 so the order in which @code{LIBS} is generated is important to reliable
3843 detection of libraries.
3845 If linking with @var{library} results in unresolved symbols that would
3846 be resolved by linking with additional libraries, give those libraries
3847 as the @var{other-libraries} argument, separated by spaces:
3848 e.g., @option{-lXt -lX11}. Otherwise, this macro will fail to detect
3849 that @var{library} is present, because linking the test program will
3850 always fail with unresolved symbols. The @var{other-libraries} argument
3851 should be limited to cases where it is desirable to test for one library
3852 in the presence of another that is not already in @code{LIBS}.
3854 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
3855 in some common cases. Many standard functions like @code{gethostbyname}
3856 appear the standard C library on some hosts, and in special libraries
3857 like @code{nsl} on other hosts. On some hosts the special libraries
3858 contain variant implementations that you may not want to use. These
3859 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
3860 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
3864 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3865 @acindex{SEARCH_LIBS}
3866 Search for a library defining @var{function} if it's not already
3867 available. This equates to calling
3868 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
3869 no libraries, then for each library listed in @var{search-libs}.
3871 Add @option{-l@var{library}} to @code{LIBS} for the first library found
3872 to contain @var{function}, and run @var{action-if-found}. If the
3873 function is not found, run @var{action-if-not-found}.
3875 If linking with @var{library} results in unresolved symbols that would
3876 be resolved by linking with additional libraries, give those libraries
3877 as the @var{other-libraries} argument, separated by spaces:
3878 e.g., @option{-lXt -lX11}. Otherwise, this macro will fail to detect
3879 that @var{function} is present, because linking the test program will
3880 always fail with unresolved symbols.
3885 @node Library Functions
3886 @section Library Functions
3888 The following macros check for particular C library functions.
3889 If there is no macro specifically defined to check for a function you need,
3890 and you don't need to check for any special properties of
3891 it, then you can use one of the general function-check macros.
3894 * Function Portability:: Pitfalls with usual functions
3895 * Particular Functions:: Special handling to find certain functions
3896 * Generic Functions:: How to find other functions
3899 @node Function Portability
3900 @subsection Portability of C Functions
3901 @cindex Portability of C functions
3902 @cindex C function portability
3904 Most usual functions can either be missing, or be buggy, or be limited
3905 on some architectures. This section tries to make an inventory of these
3906 portability issues. By definition, this list will always require
3907 additions. Please help us keeping it as complete as possible.
3912 @prindex @code{exit}
3913 On ancient hosts, @code{exit} returned @code{int}.
3914 This is because @code{exit} predates @code{void}, and there was a long
3915 tradition of it returning @code{int}.
3917 On more-modern hosts, the problem more likely is that @code{exit} is not
3918 declared, due to C++ problems of some sort or another. For this reason
3919 we suggest that test programs not invoke @code{exit}, but return from
3920 @code{main} instead.
3924 @prindex @code{free}
3925 The C standard says a call @code{free (NULL)} does nothing, but
3926 some old systems don't support this (e.g., NextStep).
3932 @prindex @code{isinf}
3933 @prindex @code{isnan}
3934 The C99 standard says that @code{isinf} and @code{isnan} are
3935 macros. On some systems just macros are available (e.g., HP-UX), on
3936 some systems both macros and functions (e.g., glibc 2.3.2), and on some
3937 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
3938 these functions are declared in nonstandard headers like
3939 @code{<sunmath.h>} and defined in non-default libraries like
3940 @option{-lm} or @option{-lsunmath}.
3942 The C99 @code{isinf} and @code{isnan} macros work correctly with
3943 @code{long double} arguments, but pre-C99 systems that use functions
3944 typically assume @code{double} arguments. On such a system,
3945 @code{isinf} incorrectly returns true for a finite @code{long double}
3946 argument that is outside the range of @code{double}.
3948 To work around this porting mess, you can use code like the following.
3955 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
3956 : sizeof (x) == sizeof (double) ? isnan_d (x) \
3958 static inline int isnan_f (float x) @{ return x != x; @}
3959 static inline int isnan_d (double x) @{ return x != x; @}
3960 static inline int isnan_ld (long double x) @{ return x != x; @}
3965 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
3966 : sizeof (x) == sizeof (double) ? isinf_d (x) \
3968 static inline int isinf_f (float x) @{ return isnan (x - x); @}
3969 static inline int isinf_d (double x) @{ return isnan (x - x); @}
3970 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
3974 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
3975 compilers that lack the @code{inline} keyword. Some optimizing
3976 compilers mishandle these definitions, but systems with that bug
3977 typically have missing or broken @code{isnan} functions anyway, so it's
3978 probably not worth worrying about.
3982 @prindex @code{malloc}
3983 The C standard says a call @code{malloc (0)} is implementation
3984 dependent. It may either return @code{NULL} (e.g., OSF 4) or
3985 non-@code{NULL} (e.g., @acronym{GNU} C Library). @code{AC_FUNC_MALLOC}
3986 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
3990 @prindex @code{putenv}
3991 Posix prefers @code{setenv} to @code{putenv}; among other things,
3992 @code{putenv} is not required of all Posix implementations, but
3995 Posix specifies that @code{putenv} puts the given string directly in
3996 @code{environ}, but some systems make a copy of it instead (e.g.,
3997 glibc 2.0, or @acronym{BSD}). And when a copy is made, @code{unsetenv} might
3998 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4000 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4001 environment, but this is not standard usage and it dumps core
4002 on some systems (e.g., AIX).
4004 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4005 environment, rather than inserting it with an empty value.
4007 @item @code{realloc}
4009 @prindex @code{realloc}
4010 The C standard says a call @code{realloc (NULL, size)} is equivalent
4011 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4014 @item @code{signal} handler
4016 @prindex @code{signal}
4017 Normally @code{signal} takes a handler function with a return type of
4018 @code{void}, but some old systems required @code{int} instead. Any
4019 actual @code{int} value returned is not used; this is only a
4020 difference in the function prototype demanded.
4022 All systems we know of in current use return @code{void}. The
4023 @code{int} was to support K&R C, where of course @code{void} is not
4024 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4025 used to establish the correct type in all cases.
4027 @item @code{snprintf}
4028 @c @fuindex snprintf
4029 @prindex @code{snprintf}
4030 @c @fuindex vsnprintf
4031 @prindex @code{vsnprintf}
4032 The C99 standard says that if the output array isn't big enough
4033 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4034 truncate the output and return the number of bytes that ought to have
4035 been produced. Some older systems return the truncated length (e.g.,
4036 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4037 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4038 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
4039 older systems ignore the length and overrun the buffer (e.g., 64-bit
4042 @item @code{sprintf}
4044 @prindex @code{sprintf}
4045 @c @fuindex vsprintf
4046 @prindex @code{vsprintf}
4047 The C standard says @code{sprintf} and @code{vsprintf} return the
4048 number of bytes written, but on some ancient systems (SunOS 4 for
4049 instance) they return the buffer pointer instead.
4053 @prindex @code{sscanf}
4054 On various old systems, e.g., HP-UX 9, @code{sscanf} requires that its
4055 input string be writable (though it doesn't actually change it). This
4056 can be a problem when using @command{gcc} since it normally puts
4057 constant strings in read-only memory
4058 (@pxref{Incompatibilities, Incompatibilities of GCC, , gcc, Using and
4059 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
4060 having format strings read-only can be a problem.
4062 @item @code{strerror_r}
4063 @c @fuindex strerror_r
4064 @prindex @code{strerror_r}
4065 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4066 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4067 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
4068 can detect which is in use (@pxref{Particular Functions}).
4070 @item @code{strnlen}
4072 @prindex @code{strnlen}
4073 @acronym{AIX} 4.3 provides a broken version which produces the
4077 strnlen ("foobar", 0) = 0
4078 strnlen ("foobar", 1) = 3
4079 strnlen ("foobar", 2) = 2
4080 strnlen ("foobar", 3) = 1
4081 strnlen ("foobar", 4) = 0
4082 strnlen ("foobar", 5) = 6
4083 strnlen ("foobar", 6) = 6
4084 strnlen ("foobar", 7) = 6
4085 strnlen ("foobar", 8) = 6
4086 strnlen ("foobar", 9) = 6
4089 @item @code{sysconf}
4091 @prindex @code{sysconf}
4092 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX
4093 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
4098 @prindex @code{unlink}
4099 The Posix spec says that @code{unlink} causes the given file to be
4100 removed only after there are no more open file handles for it. Some
4101 non-Posix hosts have trouble with this requirement, though,
4102 and some @acronym{DOS} variants even corrupt the file system.
4104 @item @code{unsetenv}
4105 @c @fuindex unsetenv
4106 @prindex @code{unsetenv}
4107 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4108 can be removed with a call @code{putenv ("FOO=")}, as described under
4109 @code{putenv} above.
4111 @item @code{va_copy}
4113 @prindex @code{va_copy}
4114 The C99 standard provides @code{va_copy} for copying
4115 @code{va_list} variables. It may be available in older environments
4116 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4117 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
4118 @code{memcpy (&dst, &src, sizeof (va_list))} will give maximum
4121 @item @code{va_list}
4123 @prindex @code{va_list}
4124 @code{va_list} is not necessarily just a pointer. It can be a
4125 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4126 not portable. Or it can be an array (e.g., @command{gcc} in some
4127 PowerPC configurations), which means as a function parameter it can be
4128 effectively call-by-reference and library routines might modify the
4129 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4132 @item Signed @code{>>}
4133 Normally the C @code{>>} right shift of a signed type replicates the
4134 high bit, giving a so-called ``arithmetic'' shift. But care should be
4135 taken since Standard C doesn't require that behavior. On those
4136 few processors without a native arithmetic shift (for instance Cray
4137 vector systems) zero bits may be shifted in, the same as a shift of an
4140 @item Integer @code{/}
4141 C divides signed integers by truncating their quotient toward zero,
4142 yielding the same result as Fortran. However, before C99 the standard
4143 allowed C implementations to take the floor or ceiling of the quotient
4144 in some cases. Hardly any implementations took advantage of this
4145 freedom, though, and it's probably not worth worrying about this issue
4150 @node Particular Functions
4151 @subsection Particular Function Checks
4152 @cindex Function, checking
4154 These macros check for particular C functions---whether they exist, and
4155 in some cases how they respond when given certain arguments.
4157 @defmac AC_FUNC_ALLOCA
4158 @acindex{FUNC_ALLOCA}
4160 @cvindex HAVE_ALLOCA_H
4163 @prindex @code{alloca}
4165 Check how to get @code{alloca}. Tries to get a builtin version by
4166 checking for @file{alloca.h} or the predefined C preprocessor macros
4167 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4168 it defines @code{HAVE_ALLOCA_H}.
4170 If those attempts fail, it looks for the function in the standard C
4171 library. If any of those methods succeed, it defines
4172 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4173 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4174 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4175 garbage collect). This variable is separate from @code{LIBOBJS} so
4176 multiple programs can share the value of @code{ALLOCA} without needing
4177 to create an actual library, in case only some of them use the code in
4178 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4179 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4181 This macro does not try to get @code{alloca} from the System V R3
4182 @file{libPW} or the System V R4 @file{libucb} because those libraries
4183 contain some incompatible functions that cause trouble. Some versions
4184 do not even contain @code{alloca} or contain a buggy version. If you
4185 still want to use their @code{alloca}, use @code{ar} to extract
4186 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4188 Source files that use @code{alloca} should start with a piece of code
4189 like the following, to declare it properly.
4194 # include <alloca.h>
4195 #elif defined __GNUC__
4196 # define alloca __builtin_alloca
4198 # define alloca __alloca
4199 #elif defined _MSC_VER
4200 # include <malloc.h>
4201 # define alloca _alloca
4203 # include <stddef.h>
4207 void *alloca (size_t);
4213 @defmac AC_FUNC_CHOWN
4214 @acindex{FUNC_CHOWN}
4216 @prindex @code{chown}
4217 If the @code{chown} function is available and works (in particular, it
4218 should accept @option{-1} for @code{uid} and @code{gid}), define
4223 @defmac AC_FUNC_CLOSEDIR_VOID
4224 @acindex{FUNC_CLOSEDIR_VOID}
4225 @cvindex CLOSEDIR_VOID
4226 @c @fuindex closedir
4227 @prindex @code{closedir}
4228 If the @code{closedir} function does not return a meaningful value,
4229 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4230 return value for an error indicator.
4232 Currently this test is implemented by running a test program. When
4233 cross compiling the pessimistic assumption that @code{closedir} does not
4234 return a meaningful value is made.
4237 @defmac AC_FUNC_ERROR_AT_LINE
4238 @acindex{FUNC_ERROR_AT_LINE}
4239 @c @fuindex error_at_line
4240 @prindex @code{error_at_line}
4241 If the @code{error_at_line} function is not found, require an
4242 @code{AC_LIBOBJ} replacement of @samp{error}.
4245 @defmac AC_FUNC_FNMATCH
4246 @acindex{FUNC_FNMATCH}
4248 @prindex @code{fnmatch}
4249 If the @code{fnmatch} function conforms to Posix, define
4250 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4251 the bugs in Solaris 2.4.
4253 Note that for historical reasons, contrary to the other specific
4254 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4255 broken/missing @code{fnmatch}. See @code{AC_REPLACE_FNMATCH} below.
4258 @defmac AC_FUNC_FNMATCH_GNU
4259 @acindex{FUNC_FNMATCH_GNU}
4261 @prindex @code{fnmatch}
4262 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4263 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
4264 implementation bugs, for example, the bugs in the @acronym{GNU} C
4268 @defmac AC_FUNC_FORK
4270 @cvindex HAVE_VFORK_H
4271 @cvindex HAVE_WORKING_FORK
4272 @cvindex HAVE_WORKING_VFORK
4275 @prindex @code{fork}
4277 @prindex @code{vfork}
4279 This macro checks for the @code{fork} and @code{vfork} functions. If a
4280 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4281 checks whether @code{fork} is just a stub by trying to run it.
4283 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4284 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4285 define @code{vfork} to be @code{fork} for backward compatibility with
4286 previous versions of @command{autoconf}. This macro checks for several known
4287 errors in implementations of @code{vfork} and considers the system to not
4288 have a working @code{vfork} if it detects any of them. It is not considered
4289 to be an implementation error if a child's invocation of @code{signal}
4290 modifies the parent's signal handler, since child processes rarely change
4291 their signal handlers.
4293 Since this macro defines @code{vfork} only for backward compatibility with
4294 previous versions of @command{autoconf} you're encouraged to define it
4295 yourself in new code:
4298 #if !HAVE_WORKING_VFORK
4305 @defmac AC_FUNC_FSEEKO
4306 @acindex{FUNC_FSEEKO}
4307 @cvindex _LARGEFILE_SOURCE
4309 @prindex @code{fseeko}
4310 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4311 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4312 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4313 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4314 largefile-sensitive systems where @code{off_t} does not default to a
4318 @defmac AC_FUNC_GETGROUPS
4319 @acindex{FUNC_GETGROUPS}
4320 @ovindex GETGROUPS_LIBS
4321 @c @fuindex getgroups
4322 @prindex @code{getgroups}
4323 If the @code{getgroups} function is available and works (unlike on
4324 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4325 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4326 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4329 @defmac AC_FUNC_GETLOADAVG
4330 @acindex{FUNC_GETLOADAVG}
4335 @cvindex HAVE_NLIST_H
4336 @cvindex NLIST_NAME_UNION
4337 @cvindex GETLODAVG_PRIVILEGED
4338 @cvindex NEED_SETGID
4339 @cvindex C_GETLOADAVG
4341 @ovindex NEED_SETGID
4343 @ovindex GETLOADAVG_LIBS
4344 @c @fuindex getloadavg
4345 @prindex @code{getloadavg}
4346 Check how to get the system load averages. To perform its tests
4347 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4348 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4349 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4351 If the system has the @code{getloadavg} function, define
4352 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4353 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
4354 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
4355 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4356 possibly define several other C preprocessor macros and output
4361 Define @code{C_GETLOADAVG}.
4364 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4369 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4372 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4373 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
4374 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4377 Programs may need to be installed setgid (or setuid) for
4378 @code{getloadavg} to work. In this case, define
4379 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4380 to @samp{true} (and otherwise to @samp{false}), and set
4381 @code{KMEM_GROUP} to the name of the group that should own the installed
4386 @defmac AC_FUNC_GETMNTENT
4387 @acindex{FUNC_GETMNTENT}
4388 @cvindex HAVE_GETMNTENT
4389 @c @fuindex getmntent
4390 @prindex @code{getmntent}
4391 Check for @code{getmntent} in the standard C library, and then in the
4392 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4393 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if
4394 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4397 @defmac AC_FUNC_GETPGRP
4398 @acindex{FUNC_GETPGRP}
4399 @cvindex GETPGRP_VOID
4402 @prindex @code{getpgid}
4403 @prindex @code{getpgrp}
4404 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4405 @code{getpgrp}; this is the Posix behavior. On older @acronym{BSD}
4406 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4407 behaves like Posix's @code{getpgid}.
4417 This macro does not check whether
4418 @code{getpgrp} exists at all; if you need to work in that situation,
4419 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4422 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4423 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4424 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4426 @prindex @code{lstat}
4427 If @file{link} is a symbolic link, then @code{lstat} should treat
4428 @file{link/} the same as @file{link/.}. However, many older
4429 @code{lstat} implementations incorrectly ignore trailing slashes.
4431 It is safe to assume that if @code{lstat} incorrectly ignores
4432 trailing slashes, then other symbolic-link-aware functions like
4433 @code{unlink} also incorrectly ignore trailing slashes.
4435 If @code{lstat} behaves properly, define
4436 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4437 @code{AC_LIBOBJ} replacement of @code{lstat}.
4440 @defmac AC_FUNC_MALLOC
4441 @acindex{FUNC_MALLOC}
4442 @cvindex HAVE_MALLOC
4445 @prindex @code{malloc}
4446 If the @code{malloc} function is compatible with the @acronym{GNU} C
4447 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4448 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4449 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4450 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4451 native @code{malloc} is not used in the main project.
4453 Typically, the replacement file @file{malloc.c} should look like (note
4454 the @samp{#undef malloc}):
4458 # include <config.h>
4462 #include <sys/types.h>
4466 /* Allocate an N-byte block of memory from the heap.
4467 If N is zero, allocate a 1-byte block. */
4470 rpl_malloc (size_t n)
4479 @defmac AC_FUNC_MEMCMP
4480 @acindex{FUNC_MEMCMP}
4483 @prindex @code{memcmp}
4484 If the @code{memcmp} function is not available, or does not work on
4485 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4486 bytes or more and with at least one buffer not starting on a 4-byte
4487 boundary (such as the one on NeXT x86 OpenStep), require an
4488 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4491 @defmac AC_FUNC_MBRTOWC
4492 @acindex{FUNC_MBRTOWC}
4493 @cvindex HAVE_MBRTOWC
4495 @prindex @code{mbrtowc}
4496 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4497 type @code{mbstate_t} are properly declared.
4500 @defmac AC_FUNC_MKTIME
4501 @acindex{FUNC_MKTIME}
4504 @prindex @code{mktime}
4505 If the @code{mktime} function is not available, or does not work
4506 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4507 For the purposes of this test, @code{mktime} should conform to the
4508 Posix standard and should be the inverse of
4512 @defmac AC_FUNC_MMAP
4516 @prindex @code{mmap}
4517 If the @code{mmap} function exists and works correctly, define
4518 @code{HAVE_MMAP}. Only checks private fixed mapping of already-mapped
4522 @defmac AC_FUNC_OBSTACK
4523 @acindex{FUNC_OBSTACK}
4524 @cvindex HAVE_OBSTACK
4526 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4527 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4530 @defmac AC_FUNC_REALLOC
4531 @acindex{FUNC_REALLOC}
4532 @cvindex HAVE_REALLOC
4535 @prindex @code{realloc}
4536 If the @code{realloc} function is compatible with the @acronym{GNU} C
4537 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4538 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4539 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4540 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4541 the native @code{realloc} is not used in the main project. See
4542 @code{AC_FUNC_MALLOC} for details.
4545 @defmac AC_FUNC_SELECT_ARGTYPES
4546 @acindex{FUNC_SELECT_ARGTYPES}
4547 @cvindex SELECT_TYPE_ARG1
4548 @cvindex SELECT_TYPE_ARG234
4549 @cvindex SELECT_TYPE_ARG5
4551 @prindex @code{select}
4552 Determines the correct type to be passed for each of the
4553 @code{select} function's arguments, and defines those types
4554 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4555 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4556 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4557 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4560 @defmac AC_FUNC_SETPGRP
4561 @acindex{FUNC_SETPGRP}
4562 @cvindex SETPGRP_VOID
4564 @prindex @code{setpgrp}
4565 If @code{setpgrp} takes no argument (the Posix version), define
4566 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4567 two process IDs as arguments. This macro does not check whether
4568 @code{setpgrp} exists at all; if you need to work in that situation,
4569 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4572 @defmac AC_FUNC_STAT
4573 @defmacx AC_FUNC_LSTAT
4575 @acindex{FUNC_LSTAT}
4576 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4577 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4579 @prindex @code{stat}
4581 @prindex @code{lstat}
4582 Determine whether @code{stat} or @code{lstat} have the bug that it
4583 succeeds when given the zero-length file name as argument. The @code{stat}
4584 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4587 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4588 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4592 @defmac AC_FUNC_SETVBUF_REVERSED
4593 @acindex{FUNC_SETVBUF_REVERSED}
4594 @cvindex SETVBUF_REVERSED
4596 @prindex @code{setvbuf}
4597 If @code{setvbuf} takes the buffering type as its second argument and
4598 the buffer pointer as the third, instead of the other way around, define
4599 @code{SETVBUF_REVERSED}.
4602 @defmac AC_FUNC_STRCOLL
4603 @acindex{FUNC_STRCOLL}
4604 @cvindex HAVE_STRCOLL
4606 @prindex @code{strcoll}
4607 If the @code{strcoll} function exists and works correctly, define
4608 @code{HAVE_STRCOLL}. This does a bit more than
4609 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4610 definitions of @code{strcoll} that should not be used.
4613 @defmac AC_FUNC_STRERROR_R
4614 @acindex{FUNC_STRERROR_R}
4615 @cvindex HAVE_STRERROR_R
4616 @cvindex HAVE_DECL_STRERROR_R
4617 @cvindex STRERROR_R_CHAR_P
4618 @c @fuindex strerror_r
4619 @prindex @code{strerror_r}
4620 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4621 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4622 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4623 returns an @code{int} error number. The Thread-Safe Functions option of
4624 Posix requires @code{strerror_r} to return @code{int}, but
4625 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4626 Library) return a @code{char *} value that is not necessarily equal to
4627 the buffer argument.
4630 @defmac AC_FUNC_STRFTIME
4631 @acindex{FUNC_STRFTIME}
4632 @cvindex HAVE_STRFTIME
4633 @c @fuindex strftime
4634 @prindex @code{strftime}
4635 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4636 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4639 @defmac AC_FUNC_STRTOD
4640 @acindex{FUNC_STRTOD}
4643 @prindex @code{strtod}
4644 If the @code{strtod} function does not exist or doesn't work correctly,
4645 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4646 because @file{strtod.c} is likely to need @samp{pow}, set the output
4647 variable @code{POW_LIB} to the extra library needed.
4650 @defmac AC_FUNC_STRTOLD
4651 @acindex{FUNC_STRTOLD}
4652 @prindex @code{strtold}
4653 If the @code{strtold} function exists and conforms to C99, define
4654 @code{HAVE_STRTOLD}.
4657 @defmac AC_FUNC_STRNLEN
4658 @acindex{FUNC_STRNLEN}
4659 @cvindex HAVE_STRNLEN
4661 @prindex @code{strnlen}
4662 If the @code{strnlen} function is not available, or is buggy (like the one
4663 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4666 @defmac AC_FUNC_UTIME_NULL
4667 @acindex{FUNC_UTIME_NULL}
4668 @cvindex HAVE_UTIME_NULL
4670 @prindex @code{utime}
4671 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4672 the present, define @code{HAVE_UTIME_NULL}.
4675 @defmac AC_FUNC_VPRINTF
4676 @acindex{FUNC_VPRINTF}
4677 @cvindex HAVE_VPRINTF
4678 @cvindex HAVE_DOPRNT
4680 @prindex @code{vprintf}
4681 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4682 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
4683 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4684 are also available.)
4687 @defmac AC_REPLACE_FNMATCH
4688 @acindex{REPLACE_FNMATCH}
4690 @prindex @code{fnmatch}
4691 @hdrindex{fnmatch.h}
4692 If the @code{fnmatch} function does not conform to Posix (see
4693 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4695 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4696 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4697 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
4698 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4699 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4700 included in place of the system @code{<fnmatch.h>}.
4705 @node Generic Functions
4706 @subsection Generic Function Checks
4708 These macros are used to find functions not covered by the ``particular''
4709 test macros. If the functions might be in libraries other than the
4710 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4711 If you need to check the behavior of a function as well as find out
4712 whether it is present, you have to write your own test for
4713 it (@pxref{Writing Tests}).
4715 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4716 @acindex{CHECK_FUNC}
4717 If C function @var{function} is available, run shell commands
4718 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
4719 want to define a symbol if the function is available, consider using
4720 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
4721 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4722 standardized than C++. (@pxref{Language Choice}, for more information
4723 about selecting the language for checks.)
4726 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4727 @acindex{CHECK_FUNCS}
4728 @cvindex HAVE_@var{function}
4729 For each @var{function} enumerated in the blank-or-newline-separated argument
4730 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4731 If @var{action-if-found} is given, it is additional shell code to
4732 execute when one of the functions is found. You can give it a value of
4733 @samp{break} to break out of the loop on the first match. If
4734 @var{action-if-not-found} is given, it is executed when one of the
4735 functions is not found.
4738 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
4739 @acindex{CHECK_FUNCS_ONCE}
4740 @cvindex HAVE_@var{function}
4741 For each @var{function} enumerated in the blank-or-newline-separated argument
4742 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4743 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
4744 checking code at most once, so that @command{configure} is smaller and
4745 faster; but the checks cannot be conditionalized and are always done once,
4746 early during the @command{configure} run.
4751 Autoconf follows a philosophy that was formed over the years by those
4752 who have struggled for portability: isolate the portability issues in
4753 specific files, and then program as if you were in a Posix
4754 environment. Some functions may be missing or unfixable, and your
4755 package must be ready to replace them.
4757 Suitable replacements for many such problem functions are available from
4758 Gnulib (@pxref{Gnulib}).
4760 @defmac AC_LIBOBJ (@var{function})
4763 Specify that @samp{@var{function}.c} must be included in the executables
4764 to replace a missing or broken implementation of @var{function}.
4766 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4767 variable @code{LIBOBJS} if it is not already in, and calls
4768 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
4769 directly change @code{LIBOBJS}, since this is not traceable.
4772 @defmac AC_LIBSOURCE (@var{file})
4774 Specify that @var{file} might be needed to compile the project. If you
4775 need to know what files might be needed by a @file{configure.ac}, you
4776 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
4778 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4779 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
4780 that case, since shell variables cannot be traced statically, you must
4781 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4782 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
4783 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4784 @code{"foo"} or @code{"bar"}, you should do:
4787 AC_LIBSOURCE([foo.c])
4788 AC_LIBSOURCE([bar.c])
4789 AC_LIBOBJ([$foo_or_bar])
4793 There is usually a way to avoid this, however, and you are encouraged to
4794 simply call @code{AC_LIBOBJ} with literal arguments.
4796 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
4797 slightly different semantics: the old macro took the function name,
4798 e.g., @code{foo}, as its argument rather than the file name.
4801 @defmac AC_LIBSOURCES (@var{files})
4802 @acindex{LIBSOURCES}
4803 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
4804 comma-separated M4 list. Thus, the above example might be rewritten:
4807 AC_LIBSOURCES([foo.c, bar.c])
4808 AC_LIBOBJ([$foo_or_bar])
4812 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
4813 @acindex{CONFIG_LIBOBJ_DIR}
4814 Specify that @code{AC_LIBOBJ} replacement files are to be found in
4815 @var{directory}, a name relative to the top level of the
4816 source tree. The replacement directory defaults to @file{.}, the top
4817 level directory, and the most typical value is @file{lib}, corresponding
4818 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
4820 @command{configure} might need to know the replacement directory for the
4821 following reasons: (i) some checks use the replacement files, (ii) some
4822 macros bypass broken system headers by installing links to the
4823 replacement headers (iii) when used in conjunction with Automake,
4824 within each @file{Makefile}, @var{directory} is used as a relative path
4825 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
4826 @code{LTLIBOBJS}, etc.
4831 It is common to merely check for the existence of a function, and ask
4832 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
4833 a convenient shorthand.
4835 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
4836 @acindex{REPLACE_FUNCS}
4838 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
4839 @var{action-if-not-found}. You can declare your replacement function by
4840 enclosing the prototype in @samp{#if !HAVE_@var{function}}. If the
4841 system has the function, it probably declares it in a header file you
4842 should be including, so you shouldn't redeclare it lest your declaration
4847 @section Header Files
4848 @cindex Header, checking
4850 The following macros check for the presence of certain C header files.
4851 If there is no macro specifically defined to check for a header file you need,
4852 and you don't need to check for any special properties of
4853 it, then you can use one of the general header-file check macros.
4856 * Header Portability:: Collected knowledge on common headers
4857 * Particular Headers:: Special handling to find certain headers
4858 * Generic Headers:: How to find other headers
4861 @node Header Portability
4862 @subsection Portability of Headers
4863 @cindex Portability of headers
4864 @cindex Header portability
4866 This section tries to collect knowledge about common headers, and the
4867 problems they cause. By definition, this list will always require
4868 additions. Please help us keeping it as complete as possible.
4872 @item @file{limits.h}
4873 C99 says that @file{limits.h} defines @code{LLONG_MIN},
4874 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
4875 environments (e.g., default GCC 4.0.2 + glibc 2.4) do not define them.
4877 @item @file{inttypes.h} vs.@: @file{stdint.h}
4878 @hdrindex{inttypes.h}
4880 The C99 standard says that @file{inttypes.h} includes
4881 @file{stdint.h}, so there's no need to include @file{stdint.h}
4882 separately in a standard environment. Some implementations have
4883 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
4884 know of any implementation that has @file{stdint.h} but not
4887 @item @file{linux/irda.h}
4888 @hdrindex{linux/irda.h}
4889 It requires @file{linux/types.h} and @file{sys/socket.h}.
4891 @item @file{linux/random.h}
4892 @hdrindex{linux/random.h}
4893 It requires @file{linux/types.h}.
4895 @item @file{net/if.h}
4897 On Darwin, this file requires that @file{sys/socket.h} be included
4898 beforehand. One should run:
4901 AC_CHECK_HEADERS([sys/socket.h])
4902 AC_CHECK_HEADERS([net/if.h], [], [],
4905 # include <stdlib.h>
4906 # include <stddef.h>
4909 # include <stdlib.h>
4912 #if HAVE_SYS_SOCKET_H
4913 # include <sys/socket.h>
4918 @item @file{netinet/if_ether.h}
4919 @hdrindex{netinet/if_ether.h}
4920 On Darwin, this file requires that @file{stdio.h} and
4921 @file{sys/socket.h} be included beforehand. One should run:
4924 AC_CHECK_HEADERS([sys/socket.h])
4925 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
4928 # include <stdlib.h>
4929 # include <stddef.h>
4932 # include <stdlib.h>
4935 #if HAVE_SYS_SOCKET_H
4936 # include <sys/socket.h>
4941 @item @file{stdint.h}
4942 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
4944 @item @file{stdlib.h}
4946 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
4948 @item @file{sys/mount.h}
4949 @hdrindex{sys/mount.h}
4950 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
4951 @file{sys/params.h} is a prerequisite.
4953 @item @file{sys/ptem.h}
4954 @hdrindex{sys/ptem.h}
4955 On Solaris 8, @file{sys/stream.h} is a prerequisite.
4957 @item @file{sys/socket.h}
4958 @hdrindex{sys/socket.h}
4959 On Darwin, @file{stdlib.h} is a prerequisite.
4961 @item @file{sys/ucred.h}
4962 @hdrindex{sys/ucred.h}
4963 On HP Tru64 5.1, @file{sys/types.h} is a prerequisite.
4965 @item @file{X11/extensions/scrnsaver.h}
4966 @hdrindex{X11/extensions/scrnsaver.h}
4967 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
4968 so required that you might not even consider looking for it.
4971 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
4972 [[#include <X11/Xlib.h>
4978 @node Particular Headers
4979 @subsection Particular Header Checks
4981 These macros check for particular system header files---whether they
4982 exist, and in some cases whether they declare certain symbols.
4984 @defmac AC_HEADER_ASSERT
4985 @acindex{HEADER_ASSERT}
4988 Check whether to enable assertions in the style of @file{assert.h}.
4989 Assertions are enabled by default, but the user can override this by
4990 invoking @command{configure} with the @option{--disable-assert} option.
4993 @defmac AC_HEADER_DIRENT
4994 @acindex{HEADER_DIRENT}
4995 @cvindex HAVE_DIRENT_H
4996 @cvindex HAVE_NDIR_H
4997 @cvindex HAVE_SYS_DIR_H
4998 @cvindex HAVE_SYS_NDIR_H
5000 @hdrindex{sys/ndir.h}
5001 @hdrindex{sys/dir.h}
5003 Check for the following header files. For the first one that is
5004 found and defines @samp{DIR}, define the listed C preprocessor macro:
5006 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5007 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
5008 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5009 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
5010 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
5013 The directory-library declarations in your source code should look
5014 something like the following:
5018 #include <sys/types.h>
5019 #ifdef HAVE_DIRENT_H
5020 # include <dirent.h>
5021 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5023 # define dirent direct
5024 # define NAMLEN(dirent) ((dirent)->d_namlen)
5025 # if HAVE_SYS_NDIR_H
5026 # include <sys/ndir.h>
5029 # include <sys/dir.h>
5038 Using the above declarations, the program would declare variables to be
5039 of type @code{struct dirent}, not @code{struct direct}, and would access
5040 the length of a directory entry name by passing a pointer to a
5041 @code{struct dirent} to the @code{NAMLEN} macro.
5043 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5045 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5046 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5049 @defmac AC_HEADER_MAJOR
5050 @acindex{HEADER_MAJOR}
5051 @cvindex MAJOR_IN_MKDEV
5052 @cvindex MAJOR_IN_SYSMACROS
5053 @hdrindex{sys/mkdev.h}
5054 @hdrindex{sys/sysmacros.h}
5055 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5056 @code{makedev}, but @file{sys/mkdev.h} does, define
5057 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5058 @code{MAJOR_IN_SYSMACROS}.
5061 @defmac AC_HEADER_RESOLV
5062 @acindex{HEADER_RESOLV}
5063 @cvindex HAVE_RESOLV_H
5065 Checks for header @file{resolv.h}, checking for prerequisites first.
5066 To properly use @file{resolv.h}, your code should contain something like
5070 #if HAVE_SYS_TYPES_H
5071 # include <sys/types.h>
5073 #ifdef HAVE_NETINET_IN_H
5074 # include <netinet/in.h> /* inet_ functions / structs */
5076 #ifdef HAVE_ARPA_NAMESER_H
5077 # include <arpa/nameser.h> /* DNS HEADER struct */
5086 @defmac AC_HEADER_STAT
5087 @acindex{HEADER_STAT}
5088 @cvindex STAT_MACROS_BROKEN
5089 @hdrindex{sys/stat.h}
5090 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5091 @file{sys/stat.h} do not work properly (returning false positives),
5092 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
5093 Amdahl UTS and Motorola System V/88.
5096 @defmac AC_HEADER_STDBOOL
5097 @acindex{HEADER_STDBOOL}
5098 @cvindex HAVE_STDBOOL_H
5100 @hdrindex{stdbool.h}
5102 If @file{stdbool.h} exists and conforms to C99, define
5103 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5104 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
5105 @file{system.h} could contain the following code:
5109 # include <stdbool.h>
5115 # define _Bool signed char
5121 # define __bool_true_false_are_defined 1
5125 Alternatively you can use the @samp{stdbool} package of Gnulib
5126 (@pxref{Gnulib}); it packages the above code into a replacement header
5127 and contains a few other bells and whistles.
5132 @defmac AC_HEADER_STDC
5133 @acindex{HEADER_STDC}
5134 @cvindex STDC_HEADERS
5140 Define @code{STDC_HEADERS} if the system has C header files
5141 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5142 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5143 @file{string.h}, and @file{float.h}; if the system has those, it
5144 probably has the rest of the C89 header files. This macro also
5145 checks whether @file{string.h} declares @code{memchr} (and thus
5146 presumably the other @code{mem} functions), whether @file{stdlib.h}
5147 declare @code{free} (and thus presumably @code{malloc} and other related
5148 functions), and whether the @file{ctype.h} macros work on characters
5149 with the high bit set, as the C standard requires.
5151 Nowadays this macro is becoming obsolete. However, if you use it, your
5152 code can refer to @code{STDC_HEADERS} instead of @code{__STDC__} to
5153 determine whether the system has conforming header files (and probably C
5154 library functions). This is useful if you worry about portability
5155 to ancient systems that lack C89 header files.
5158 @hdrindex{strings.h}
5159 Nowadays @file{string.h} is part of the C standard and declares functions like
5160 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5161 @acronym{BSD} functions like @code{bcopy}; but
5162 historically, string functions were a major sticking point in this area.
5163 If you worry about portability to ancient systems without standard
5164 headers, there is so much variation
5165 that it is probably easier to declare the functions you use than to
5166 figure out exactly what the system header files declare. Some ancient systems
5167 contain a mix of functions from the C standard and from @acronym{BSD}; some are
5168 mostly standard but lack @samp{memmove}; some define the
5169 @acronym{BSD} functions as macros in @file{string.h} or
5170 @file{strings.h}; some have only the @acronym{BSD} functions but
5171 @file{string.h}; some declare the memory functions in @file{memory.h},
5172 some in @file{string.h}; etc. It is probably sufficient to check for
5173 one string function and one memory function; if the library has the
5174 standard versions of those then it probably has most of the others.
5175 If you put the following in @file{configure.ac}:
5179 AC_CHECK_FUNCS([strchr memcpy])
5183 then, in your code, you can use declarations like this:
5188 # include <string.h>
5191 # define strchr index
5192 # define strrchr rindex
5194 char *strchr (), *strrchr ();
5196 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5197 # define memmove(d, s, n) bcopy ((s), (d), (n))
5204 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5205 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros won't
5206 suffice; you must provide an implementation of each function. An easy
5207 way to incorporate your implementations only when needed (since the ones
5208 in system C libraries may be hand optimized) is to, taking @code{memchr}
5209 for example, put it in @file{memchr.c} and use
5210 @samp{AC_REPLACE_FUNCS([memchr])}.
5213 @defmac AC_HEADER_SYS_WAIT
5214 @acindex{HEADER_SYS_WAIT}
5215 @cvindex HAVE_SYS_WAIT_H
5216 @hdrindex{sys/wait.h}
5217 If @file{sys/wait.h} exists and is compatible with Posix, define
5218 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
5219 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5220 of @code{int} to store a status value. If @file{sys/wait.h} is not
5221 Posix compatible, then instead of including it, define the
5222 Posix macros with their usual interpretations. Here is an
5227 #include <sys/types.h>
5229 # include <sys/wait.h>
5232 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5235 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5241 @cvindex _POSIX_VERSION
5243 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5244 Posix systems. If there is no @file{unistd.h}, it is definitely
5245 not a Posix system. However, some non-Posix systems do
5246 have @file{unistd.h}.
5248 The way to check whether the system supports Posix is:
5253 # include <sys/types.h>
5254 # include <unistd.h>
5257 #ifdef _POSIX_VERSION
5258 /* Code for Posix systems. */
5263 @defmac AC_HEADER_TIME
5264 @acindex{HEADER_TIME}
5265 @cvindex TIME_WITH_SYS_TIME
5267 @hdrindex{sys/time.h}
5268 If a program may include both @file{time.h} and @file{sys/time.h},
5269 define @code{TIME_WITH_SYS_TIME}. On some older systems,
5270 @file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
5271 protected against multiple inclusion, so programs should not explicitly
5272 include both files. This macro is useful in programs that use, for
5273 example, @code{struct timeval} as well as
5274 @code{struct tm}. It is best used in conjunction with
5275 @code{HAVE_SYS_TIME_H}, which can be checked for using
5276 @code{AC_CHECK_HEADERS([sys/time.h])}.
5280 #if TIME_WITH_SYS_TIME
5281 # include <sys/time.h>
5284 # if HAVE_SYS_TIME_H
5285 # include <sys/time.h>
5295 @defmac AC_HEADER_TIOCGWINSZ
5296 @acindex{HEADER_TIOCGWINSZ}
5297 @cvindex GWINSZ_IN_SYS_IOCTL
5298 @hdrindex{sys/ioctl.h}
5299 @hdrindex{termios.h}
5300 @c FIXME: I need clarifications from Jim.
5301 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5302 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
5303 found in @file{<termios.h>}.
5310 # include <termios.h>
5313 #if GWINSZ_IN_SYS_IOCTL
5314 # include <sys/ioctl.h>
5320 @node Generic Headers
5321 @subsection Generic Header Checks
5323 These macros are used to find system header files not covered by the
5324 ``particular'' test macros. If you need to check the contents of a header
5325 as well as find out whether it is present, you have to write your own
5326 test for it (@pxref{Writing Tests}).
5328 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5329 @acindex{CHECK_HEADER}
5330 If the system header file @var{header-file} is compilable, execute shell
5331 commands @var{action-if-found}, otherwise execute
5332 @var{action-if-not-found}. If you just want to define a symbol if the
5333 header file is available, consider using @code{AC_CHECK_HEADERS}
5336 For compatibility issues with older versions of Autoconf, please read
5340 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5341 @acindex{CHECK_HEADERS}
5342 @cvindex HAVE_@var{header}
5343 For each given system header file @var{header-file} in the
5344 blank-separated argument list that exists, define
5345 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
5346 is given, it is additional shell code to execute when one of the header
5347 files is found. You can give it a value of @samp{break} to break out of
5348 the loop on the first match. If @var{action-if-not-found} is given, it
5349 is executed when one of the header files is not found.
5351 For compatibility issues with older versions of Autoconf, please read
5355 Previous versions of Autoconf merely checked whether the header was
5356 accepted by the preprocessor. This was changed because the old test was
5357 inappropriate for typical uses. Headers are typically used to compile,
5358 not merely to preprocess, and the old behavior sometimes accepted
5359 headers that clashed at compile-time. If you need to check whether a
5360 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5361 (@pxref{Running the Preprocessor}).
5363 This scheme, which improves the robustness of the test, also requires
5364 that you make sure that headers that must be included before the
5365 @var{header-file} be part of the @var{includes}, (@pxref{Default
5366 Includes}). If looking for @file{bar.h}, which requires that
5367 @file{foo.h} be included before if it exists, we suggest the following
5371 AC_CHECK_HEADERS([foo.h])
5372 AC_CHECK_HEADERS([bar.h], [], [],
5379 The following variant generates smaller, faster @command{configure}
5380 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5382 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5383 @acindex{CHECK_HEADERS_ONCE}
5384 @cvindex HAVE_@var{header}
5385 For each given system header file @var{header-file} in the
5386 blank-separated argument list that exists, define
5387 @code{HAVE_@var{header-file}} (in all capitals).
5388 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
5389 checking code at most once, so that @command{configure} is smaller and
5390 faster; but the checks cannot be conditionalized and are always done once,
5391 early during the @command{configure} run.
5395 @section Declarations
5396 @cindex Declaration, checking
5398 The following macros check for the declaration of variables and
5399 functions. If there is no macro specifically defined to check for a
5400 symbol you need, then you can use the general macros (@pxref{Generic
5401 Declarations}) or, for more complex tests, you may use
5402 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5405 * Particular Declarations:: Macros to check for certain declarations
5406 * Generic Declarations:: How to find other declarations
5409 @node Particular Declarations
5410 @subsection Particular Declaration Checks
5412 There are no specific macros for declarations.
5414 @node Generic Declarations
5415 @subsection Generic Declaration Checks
5417 These macros are used to find declarations not covered by the ``particular''
5420 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5421 @acindex{CHECK_DECL}
5422 If @var{symbol} (a function or a variable) is not declared in
5423 @var{includes} and a declaration is needed, run the shell commands
5424 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
5425 @var{includes} are specified, the default includes are used
5426 (@pxref{Default Includes}).
5428 This macro actually tests whether it is valid to use @var{symbol} as an
5429 r-value, not if it is really declared, because it is much safer to avoid
5430 introducing extra declarations when they are not needed.
5433 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5434 @acindex{CHECK_DECLS}
5435 @cvindex HAVE_DECL_@var{symbol}
5436 For each of the @var{symbols} (@emph{comma}-separated list), define
5437 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5438 @var{symbol} is declared, otherwise to @samp{0}. If
5439 @var{action-if-not-found} is given, it is additional shell code to
5440 execute when one of the function declarations is needed, otherwise
5441 @var{action-if-found} is executed.
5443 This macro uses an m4 list as first argument:
5445 AC_CHECK_DECLS([strdup])
5446 AC_CHECK_DECLS([strlen])
5447 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5450 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5451 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5452 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
5453 @emph{sure} that the check was performed, use
5454 @code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
5457 #if !HAVE_DECL_SYMBOL
5458 extern char *symbol;
5463 If the test may have not been performed, however, because it is safer
5464 @emph{not} to declare a symbol than to use a declaration that conflicts
5465 with the system's one, you should use:
5468 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5469 void *malloc (size_t *s);
5474 You fall into the second category only in extreme situations: either
5475 your files may be used without being configured, or they are used during
5476 the configuration. In most cases the traditional approach is enough.
5479 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5480 @acindex{CHECK_DECLS_ONCE}
5481 @cvindex HAVE_DECL_@var{symbol}
5482 For each of the @var{symbols} (@emph{comma}-separated list), define
5483 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5484 @var{symbol} is declared in the default include files, otherwise to
5485 @samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
5486 generates the checking code at most once, so that @command{configure} is
5487 smaller and faster; but the checks cannot be conditionalized and are
5488 always done once, early during the @command{configure} run.
5494 @cindex Structure, checking
5496 The following macros check for the presence of certain members in C
5497 structures. If there is no macro specifically defined to check for a
5498 member you need, then you can use the general structure-member macros
5499 (@pxref{Generic Structures}) or, for more complex tests, you may use
5500 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5503 * Particular Structures:: Macros to check for certain structure members
5504 * Generic Structures:: How to find other structure members
5507 @node Particular Structures
5508 @subsection Particular Structure Checks
5510 The following macros check for certain structures or structure members.
5512 @defmac AC_STRUCT_DIRENT_D_INO
5513 @acindex{STRUCT_DIRENT_D_INO}
5514 @cvindex HAVE_STRUCT_DIRENT_D_INO
5515 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5516 Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
5517 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5519 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5520 @code{d_ino}, not whether its contents are always reliable.
5521 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5522 though modern systems hide this detail from the user and never return
5523 zero @code{d_ino} values.
5526 @defmac AC_STRUCT_DIRENT_D_TYPE
5527 @acindex{STRUCT_DIRENT_D_TYPE}
5528 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5529 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5530 Headers}). Then, if @code{struct dirent} contains a @code{d_type}
5531 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5534 @defmac AC_STRUCT_ST_BLKSIZE
5535 @acindex{STRUCT_ST_BLKSIZE}
5536 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5537 @cvindex HAVE_ST_BLKSIZE
5538 If @code{struct stat} contains an @code{st_blksize} member, define
5539 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
5540 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5541 the future. This macro is obsoleted, and should be replaced by
5544 AC_CHECK_MEMBERS([struct stat.st_blksize])
5548 @defmac AC_STRUCT_ST_BLOCKS
5549 @acindex{STRUCT_ST_BLOCKS}
5550 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5551 @cvindex HAVE_ST_BLOCKS
5553 If @code{struct stat} contains an @code{st_blocks} member, define
5554 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5555 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5556 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5560 @defmac AC_STRUCT_ST_RDEV
5561 @acindex{STRUCT_ST_RDEV}
5562 @cvindex HAVE_ST_RDEV
5563 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5564 If @code{struct stat} contains an @code{st_rdev} member, define
5565 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
5566 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5567 in the future. Actually, even the new macro is obsolete and should be
5570 AC_CHECK_MEMBERS([struct stat.st_rdev])
5574 @defmac AC_STRUCT_TM
5576 @cvindex TM_IN_SYS_TIME
5578 @hdrindex{sys/time.h}
5579 If @file{time.h} does not define @code{struct tm}, define
5580 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5581 had better define @code{struct tm}.
5584 @defmac AC_STRUCT_TIMEZONE
5585 @acindex{STRUCT_TIMEZONE}
5586 @cvindex HAVE_TM_ZONE
5587 @cvindex HAVE_TZNAME
5588 Figure out how to get the current timezone. If @code{struct tm} has a
5589 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5590 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5591 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5592 define @code{HAVE_DECL_TZNAME}.
5595 @node Generic Structures
5596 @subsection Generic Structure Checks
5598 These macros are used to find structure members not covered by the
5599 ``particular'' test macros.
5601 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5602 @acindex{CHECK_MEMBER}
5603 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5604 If no @var{includes} are specified, the default includes are used
5605 (@pxref{Default Includes}).
5608 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5609 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5613 You can use this macro for sub-members:
5616 AC_CHECK_MEMBER(struct top.middle.bot)
5620 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5621 @acindex{CHECK_MEMBERS}
5622 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5623 @var{members} using the previous macro. When @var{member} belongs to
5624 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5625 capitals, with spaces and dots replaced by underscores). If
5626 @var{action-if-found} is given, it is executed for each of the found
5627 members. If @var{action-if-not-found} is given, it is executed for each
5628 of the members that could not be found.
5630 This macro uses m4 lists:
5632 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5642 The following macros check for C types, either builtin or typedefs. If
5643 there is no macro specifically defined to check for a type you need, and
5644 you don't need to check for any special properties of it, then you can
5645 use a general type-check macro.
5648 * Particular Types:: Special handling to find certain types
5649 * Generic Types:: How to find other types
5652 @node Particular Types
5653 @subsection Particular Type Checks
5655 @hdrindex{sys/types.h}
5658 @hdrindex{inttypes.h}
5659 These macros check for particular C types in @file{sys/types.h},
5660 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
5663 The Gnulib @code{stdint} module is an alternate way to define many of
5664 these symbols; it is useful if you prefer your code to assume a
5665 C99-or-better environment. @xref{Gnulib}.
5667 @defmac AC_TYPE_GETGROUPS
5668 @acindex{TYPE_GETGROUPS}
5669 @cvindex GETGROUPS_T
5670 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5671 is the base type of the array argument to @code{getgroups}.
5674 @defmac AC_TYPE_INT8_T
5675 @acindex{TYPE_INT8_T}
5676 @cvindex HAVE_INT8_T
5678 If @file{stdint.h} or @file{inttypes.h} defines the type @code{int8_t},
5679 define @code{HAVE_INT8_T}. Otherwise, define @code{int8_t} to a signed
5680 integer type that is exactly 8 bits wide and that uses two's complement
5681 representation, if such a type exists.
5684 @defmac AC_TYPE_INT16_T
5685 @acindex{TYPE_INT16_T}
5686 @cvindex HAVE_INT16_T
5688 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
5691 @defmac AC_TYPE_INT32_T
5692 @acindex{TYPE_INT32_T}
5693 @cvindex HAVE_INT32_T
5695 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
5698 @defmac AC_TYPE_INT64_T
5699 @acindex{TYPE_INT64_T}
5700 @cvindex HAVE_INT64_T
5702 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
5705 @defmac AC_TYPE_INTMAX_T
5706 @acindex{TYPE_INTMAX_T}
5707 @cvindex HAVE_INTMAX_T
5709 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
5710 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
5711 widest signed integer type.
5714 @defmac AC_TYPE_INTPTR_T
5715 @acindex{TYPE_INTPTR_T}
5716 @cvindex HAVE_INTPTR_T
5718 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
5719 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
5720 signed integer type wide enough to hold a pointer, if such a type
5724 @defmac AC_TYPE_LONG_DOUBLE
5725 @acindex{TYPE_LONG_DOUBLE}
5726 @cvindex HAVE_LONG_DOUBLE
5727 If the C compiler supports a working @code{long double} type, define
5728 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
5729 same range and precision as @code{double}.
5732 @defmac AC_TYPE_LONG_DOUBLE_WIDER
5733 @acindex{TYPE_LONG_DOUBLE_WIDER}
5734 @cvindex HAVE_LONG_DOUBLE_WIDER
5735 If the C compiler supports a working @code{long double} type with more
5736 range or precision than the @code{double} type, define
5737 @code{HAVE_LONG_DOUBLE_WIDER}.
5740 @defmac AC_TYPE_LONG_LONG_INT
5741 @acindex{TYPE_LONG_LONG_INT}
5742 @cvindex HAVE_LONG_LONG_INT
5743 If the C compiler supports a working @code{long long int} type, define
5744 @code{HAVE_LONG_LONG_INT}.
5747 @defmac AC_TYPE_MBSTATE_T
5748 @acindex{TYPE_MBSTATE_T}
5751 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5752 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
5753 @code{<wchar.h>} does not declare it.
5756 @defmac AC_TYPE_MODE_T
5757 @acindex{TYPE_MODE_T}
5759 Define @code{mode_t} to a suitable type, if standard headers do not
5763 @defmac AC_TYPE_OFF_T
5764 @acindex{TYPE_OFF_T}
5766 Define @code{off_t} to a suitable type, if standard headers do not
5770 @defmac AC_TYPE_PID_T
5771 @acindex{TYPE_PID_T}
5773 Define @code{pid_t} to a suitable type, if standard headers do not
5777 @defmac AC_TYPE_SIGNAL
5778 @acindex{TYPE_SIGNAL}
5781 If @file{signal.h} declares @code{signal} as returning a pointer to a
5782 function returning @code{void}, define @code{RETSIGTYPE} to be
5783 @code{void}; otherwise, define it to be @code{int}.
5785 Define signal handlers as returning type @code{RETSIGTYPE}:
5798 @defmac AC_TYPE_SIZE_T
5799 @acindex{TYPE_SIZE_T}
5801 Define @code{size_t} to a suitable type, if standard headers do not
5805 @defmac AC_TYPE_SSIZE_T
5806 @acindex{TYPE_SSIZE_T}
5808 Define @code{ssize_t} to a suitable type, if standard headers do not
5812 @defmac AC_TYPE_UID_T
5813 @acindex{TYPE_UID_T}
5816 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
5817 headers do not define them.
5820 @defmac AC_TYPE_UINT8_T
5821 @acindex{TYPE_UINT8_T}
5822 @cvindex HAVE_UINT8_T
5824 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uint8_t},
5825 define @code{HAVE_UINT8_T}. Otherwise, define @code{uint8_t} to an
5826 unsigned integer type that is exactly 8 bits wide, if such a type
5830 @defmac AC_TYPE_UINT16_T
5831 @acindex{TYPE_UINT16_T}
5832 @cvindex HAVE_UINT16_T
5834 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit unsigned integers.
5837 @defmac AC_TYPE_UINT32_T
5838 @acindex{TYPE_UINT32_T}
5839 @cvindex HAVE_UINT32_T
5841 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit unsigned integers.
5844 @defmac AC_TYPE_UINT64_T
5845 @acindex{TYPE_UINT64_T}
5846 @cvindex HAVE_UINT64_T
5848 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit unsigned integers.
5851 @defmac AC_TYPE_UINTMAX_T
5852 @acindex{TYPE_UINTMAX_T}
5853 @cvindex HAVE_UINTMAX_T
5855 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
5856 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
5857 widest unsigned integer type.
5860 @defmac AC_TYPE_UINTPTR_T
5861 @acindex{TYPE_UINTPTR_T}
5862 @cvindex HAVE_UINTPTR_T
5864 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
5865 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
5866 unsigned integer type wide enough to hold a pointer, if such a type
5870 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
5871 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
5872 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
5873 If the C compiler supports a working @code{unsigned long long int} type,
5874 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
5878 @subsection Generic Type Checks
5880 These macros are used to check for types not covered by the ``particular''
5883 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5884 @acindex{CHECK_TYPE}
5885 Check whether @var{type} is defined. It may be a compiler builtin type
5886 or defined by the @var{includes} (@pxref{Default Includes}).
5890 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5891 @acindex{CHECK_TYPES}
5892 For each @var{type} of the @var{types} that is defined, define
5893 @code{HAVE_@var{type}} (in all capitals). If no @var{includes} are
5894 specified, the default includes are used (@pxref{Default Includes}). If
5895 @var{action-if-found} is given, it is additional shell code to execute
5896 when one of the types is found. If @var{action-if-not-found} is given,
5897 it is executed when one of the types is not found.
5899 This macro uses m4 lists:
5901 AC_CHECK_TYPES([ptrdiff_t])
5902 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
5907 Autoconf, up to 2.13, used to provide to another version of
5908 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
5909 compatibility, a simple heuristics, quite safe but not totally, is
5910 implemented. In case of doubt, read the documentation of the former
5911 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
5914 @node Compilers and Preprocessors
5915 @section Compilers and Preprocessors
5917 @cindex Preprocessors
5920 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
5921 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
5922 the output of the compiler, typically to the empty string if
5923 Posix and @samp{.exe} if a @acronym{DOS} variant. It can be overridden
5924 by passing the argument @samp{ac_cv_exeext=@var{ext}} to
5925 @command{configure}.
5928 They also define the output variable @code{OBJEXT} based on the
5929 output of the compiler, after @file{.c} files have been excluded, typically
5930 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
5932 If the compiler being used does not produce executables, the tests fail. If
5933 the executables can't be run, and cross-compilation is not enabled, they
5934 fail too. @xref{Manual Configuration}, for more on support for cross
5938 * Specific Compiler Characteristics:: Some portability issues
5939 * Generic Compiler Characteristics:: Language independent tests and features
5940 * C Compiler:: Checking its characteristics
5941 * C++ Compiler:: Likewise
5942 * Objective C Compiler:: Likewise
5943 * Erlang Compiler and Interpreter:: Likewise
5944 * Fortran Compiler:: Likewise
5947 @node Specific Compiler Characteristics
5948 @subsection Specific Compiler Characteristics
5950 Some compilers exhibit different behaviors.
5953 @item Static/Dynamic Expressions
5954 Autoconf relies on a trick to extract one bit of information from the C
5955 compiler: using negative array sizes. For instance the following
5956 excerpt of a C source demonstrates how to test whether @samp{int}s are 4
5963 static int test_array [sizeof (int) == 4 ? 1 : -1];
5970 To our knowledge, there is a single compiler that does not support this
5971 trick: the HP C compilers (the real one, not only the ``bundled'') on
5972 HP-UX 11.00. They incorrectly reject the above program with the diagnostic
5973 ``Variable-length arrays cannot have static storage.''
5974 This bug comes from HP compilers' mishandling of @code{sizeof (int)},
5975 not from the @code{? 1 : -1}, and
5976 Autoconf works around this problem by casting @code{sizeof (int)} to
5977 @code{long int} before comparing it.
5980 @node Generic Compiler Characteristics
5981 @subsection Generic Compiler Characteristics
5983 @defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
5984 @acindex{CHECK_SIZEOF}
5985 Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
5986 size in bytes of @var{type}. If @samp{type} is unknown, it gets a size
5987 of 0. If no @var{includes} are specified, the default includes are used
5988 (@pxref{Default Includes}). If you provide @var{include}, be sure to
5989 include @file{stdio.h} which is required for this macro to run.
5991 This macro now works even when cross-compiling. The @var{unused}
5992 argument was used when cross-compiling.
5994 For example, the call
5997 AC_CHECK_SIZEOF([int *])
6001 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6004 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6005 @acindex{CHECK_ALIGNOF}
6006 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6007 alignment in bytes of @var{type}. If @samp{type} is unknown, it gets a size
6008 of 0. If no @var{includes} are specified, the default includes are used
6009 (@pxref{Default Includes}). If you provide @var{include}, be sure to
6010 include @file{stddef.h} and @file{stdio.h} which are required for this
6011 macro to work correctly.
6014 @defmac AC_LANG_WERROR
6015 @acindex{LANG_WERROR}
6016 Normally Autoconf ignores warnings generated by the compiler, linker, and
6017 preprocessor. If this macro is used, warnings will be treated as fatal
6018 errors instead for the current language. This macro is useful when the
6019 results of configuration will be used where warnings are unacceptable; for
6020 instance, if parts of a program are built with the GCC @option{-Werror}
6021 option. If the whole program will be built using @option{-Werror} it is
6022 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6027 @subsection C Compiler Characteristics
6029 The following macros provide ways to find and exercise a C Compiler.
6030 There are a few constructs that ought to be avoided, but do not deserve
6031 being checked for, since they can easily be worked around.
6034 @item Don't use lines containing solitary backslashes
6035 They tickle a bug in the HP-UX C compiler (checked on HP-UX 10.20,
6036 11.00, and 11i). When given the following source:
6041 * A comment with backslash-newlines in it. %@{ %@} *\
6045 " A string with backslash-newlines in it %@{ %@} \\
6047 char apostrophe = '\\
6055 the compiler incorrectly fails with the diagnostics ``Non-terminating
6056 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6057 Removing the lines with solitary backslashes solves the problem.
6059 @item Don't compile several files at once if output matters to you
6060 Some compilers, such as the HP's, reports the name of the file it is
6061 compiling @emph{when} they are several. For instance:
6070 This can cause problems if you observe the output of the compiler to
6071 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6072 b.o} solves the issue.
6074 @item Don't rely on @code{#error} failing
6075 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6076 simply emits a diagnostic and continues, exiting successfully. So,
6077 instead of an error directive like @code{#error "Unsupported word size"}
6078 it is more portable to use an invalid directive like @code{#Unsupported
6079 word size} in Autoconf tests. In ordinary source code, @code{#error} is
6080 OK, since installers with inadequate compilers like @sc{irix} can simply
6081 examine these compilers' diagnostic output.
6083 @item Don't rely on correct @code{#line} support
6084 On Solaris 8, @command{c89} (Sun WorkShop 6 update 2 C 5.3 Patch
6085 111679-08 2002/05/09)) diagnoses @code{#line} directives whose line
6086 numbers are greater than 32767. In addition, nothing in Posix
6087 makes this invalid. That is why Autoconf stopped issuing
6088 @code{#line} directives.
6091 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6095 Determine a C compiler to use. If @code{CC} is not already set in the
6096 environment, check for @code{gcc} and @code{cc}, then for other C
6097 compilers. Set output variable @code{CC} to the name of the compiler
6100 This macro may, however, be invoked with an optional first argument
6101 which, if specified, must be a blank-separated list of C compilers to
6102 search for. This just gives the user an opportunity to specify an
6103 alternative search list for the C compiler. For example, if you didn't
6104 like the default order, then you could invoke @code{AC_PROG_CC} like
6108 AC_PROG_CC([gcc cl cc])
6111 If the C compiler does not handle function prototypes correctly by
6112 default, try to add an option to output variable @code{CC} to make it
6113 so. This macro tries various options that select standard-conformance
6114 modes on various systems.
6116 After calling this macro you can check whether the C compiler has been
6117 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6119 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
6120 @code{AC_C_PROTOTYPES} below.
6122 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6123 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
6124 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6125 where GCC does not accept @option{-g}), or @option{-g} for other compilers.
6128 @defmac AC_PROG_CC_C_O
6129 @acindex{PROG_CC_C_O}
6130 @cvindex NO_MINUS_C_MINUS_O
6131 If the C compiler does not accept the @option{-c} and @option{-o} options
6132 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
6133 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6134 the first @code{cc} in the path. The test fails if one fails. This
6135 macro was created for @acronym{GNU} Make to choose the default C compilation
6143 Set output variable @code{CPP} to a command that runs the
6144 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6145 It is only portable to run @code{CPP} on files with a @file{.c}
6148 Some preprocessors don't indicate missing include files by the error
6149 status. For such preprocessors an internal variable is set that causes
6150 other macros to check the standard error from the preprocessor and
6151 consider the test failed if any warnings have been reported.
6152 For most preprocessors, though, warnings do not cause include-file
6153 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6156 @defmac AC_PROG_CPP_WERROR
6157 @acindex{PROG_CPP_WERROR}
6159 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6160 preprocessor as errors even if the preprocessor exit status indicates
6161 success. This is useful for avoiding headers that generate mandatory
6162 warnings, such as deprecation notices.
6166 The following macros check for C compiler or machine architecture
6167 features. To check for characteristics not listed here, use
6168 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6169 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6171 @defmac AC_PROG_CC_STDC
6172 @acindex{PROG_CC_STDC}
6173 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6174 C99), try to add an option to output variable @code{CC} to make it work.
6175 If the compiler does not support C99, fall back to supporting
6176 @acronym{ANSI} C89 (@acronym{ISO} C90).
6178 After calling this macro you can check whether the C compiler has been
6179 set to accept Standard C; if not, the shell variable
6180 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6183 @defmac AC_PROG_CC_C89
6184 @acindex{PROG_CC_C89}
6185 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6186 default, try to add an option to output variable @code{CC} to make it
6187 so. This macro tries various options that select @acronym{ANSI} C89 on
6188 some system or another. It considers the compiler to be in
6189 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6191 After calling this macro you can check whether the C compiler has been
6192 set to accept @acronym{ANSI} C89; if not, the shell variable
6193 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6195 This macro is called automatically by @code{AC_PROG_CC}.
6198 @defmac AC_PROG_CC_C99
6199 @acindex{PROG_CC_C99}
6200 If the C compiler is not in C99 mode by default, try to add an
6201 option to output variable @code{CC} to make it so. This macro tries
6202 various options that select C99 on some system or another. It
6203 considers the compiler to be in C99 mode if it handles @code{_Bool},
6204 flexible arrays, @code{inline}, @code{long long int}, mixed code and
6205 declarations, named initialization of structs, @code{restrict}, varargs
6206 macros, variable declarations in @code{for} loops and variable length
6209 After calling this macro you can check whether the C compiler has been
6210 set to accept C99; if not, the shell variable
6211 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6214 @defmac AC_C_BACKSLASH_A
6215 @acindex{HAVE_C_BACKSLASH_A}
6216 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6220 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
6221 @acindex{C_BIGENDIAN}
6222 @cvindex WORDS_BIGENDIAN
6224 If words are stored with the most significant byte first (like Motorola
6225 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
6226 the least significant byte first (like Intel and VAX CPUs), execute
6227 @var{action-if-false}.
6229 This macro runs a test-case if endianness cannot be determined from the
6230 system header files. When cross-compiling, the test-case is not run but
6231 grep'ed for some magic values. @var{action-if-unknown} is executed if
6232 the latter case fails to determine the byte sex of the host system.
6234 The default for @var{action-if-true} is to define
6235 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
6236 nothing. And finally, the default for @var{action-if-unknown} is to
6237 abort configure and tell the installer which variable he should preset
6238 to bypass this test.
6244 If the C compiler does not fully support the @code{const} keyword,
6245 define @code{const} to be empty. Some C compilers that do
6246 not define @code{__STDC__} do support @code{const}; some compilers that
6247 define @code{__STDC__} do not completely support @code{const}. Programs
6248 can simply use @code{const} as if every C compiler supported it; for
6249 those that don't, the @file{Makefile} or configuration header file will
6252 Occasionally installers use a C++ compiler to compile C code, typically
6253 because they lack a C compiler. This causes problems with @code{const},
6254 because C and C++ treat @code{const} differently. For example:
6261 is valid in C but not in C++. These differences unfortunately cannot be
6262 papered over by defining @code{const} to be empty.
6264 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6265 as this generally yields better results in practice. However, using a
6266 C++ compiler to compile C code is not recommended or supported, and
6267 installers who run into trouble in this area should get a C compiler
6268 like GCC to compile their C code.
6271 @defmac AC_C_RESTRICT
6272 @acindex{C_RESTRICT}
6274 If the C compiler recognizes the @code{restrict} keyword, don't do anything.
6275 If it recognizes only a variant spelling (@code{__restrict},
6276 @code{__restrict__}, or @code{_Restrict}), then define
6277 @code{restrict} to that.
6278 Otherwise, define @code{restrict} to be empty.
6279 Thus, programs may simply use @code{restrict} as if every C compiler
6280 supported it; for those that do not, the @file{Makefile}
6281 or configuration header defines it away.
6283 Although support in C++ for the @code{restrict} keyword is not
6284 required, several C++ compilers do accept the keyword.
6285 This macro works for them, too.
6288 @defmac AC_C_VOLATILE
6289 @acindex{C_VOLATILE}
6291 If the C compiler does not understand the keyword @code{volatile},
6292 define @code{volatile} to be empty. Programs can simply use
6293 @code{volatile} as if every C compiler supported it; for those that do
6294 not, the @file{Makefile} or configuration header will define it as
6297 If the correctness of your program depends on the semantics of
6298 @code{volatile}, simply defining it to be empty does, in a sense, break
6299 your code. However, given that the compiler does not support
6300 @code{volatile}, you are at its mercy anyway. At least your
6301 program will compile, when it wouldn't before.
6303 In general, the @code{volatile} keyword is a standard C feature, so
6304 you might expect that @code{volatile} is available only when
6305 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
6306 support volatile, but does not define @code{__STDC__}.
6312 If the C compiler supports the keyword @code{inline}, do nothing.
6313 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6314 if it accepts one of those, otherwise define @code{inline} to be empty.
6317 @defmac AC_C_CHAR_UNSIGNED
6318 @acindex{C_CHAR_UNSIGNED}
6319 @cvindex __CHAR_UNSIGNED__
6320 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6321 unless the C compiler predefines it.
6324 @defmac AC_C_STRINGIZE
6325 @acindex{C_STRINGIZE}
6326 @cvindex HAVE_STRINGIZE
6327 If the C preprocessor supports the stringizing operator, define
6328 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
6329 found in macros such as this:
6338 @cvindex HAVE_TYPEOF
6340 If the C compiler supports GCC's @code{typeof} syntax either directly or
6341 through a different spelling of the keyword (e.g., @code{__typeof__}),
6342 define @code{HAVE_TYPEOF}. If the support is available only through a
6343 different spelling, define @code{typeof} to that spelling.
6346 @defmac AC_C_PROTOTYPES
6347 @acindex{C_PROTOTYPES}
6349 @cvindex __PROTOTYPES
6351 If function prototypes are understood by the compiler (as determined by
6352 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6353 Defining @code{__PROTOTYPES} is for the benefit of
6354 header files that cannot use macros that infringe on user name space.
6357 @defmac AC_PROG_GCC_TRADITIONAL
6358 @acindex{PROG_GCC_TRADITIONAL}
6360 Add @option{-traditional} to output variable @code{CC} if using the
6361 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6362 @option{-traditional}. That usually happens when the fixed header files
6363 have not been installed on an old system. Since recent versions of the
6364 @acronym{GNU} C compiler fix the header files automatically when installed,
6365 this macro is becoming obsolete.
6370 @subsection C++ Compiler Characteristics
6373 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6377 Determine a C++ compiler to use. Check whether the environment variable
6378 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6379 variable @code{CXX} to its value.
6381 Otherwise, if the macro is invoked without an argument, then search for
6382 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6383 then other names). If none of those checks succeed, then as a last
6384 resort set @code{CXX} to @code{g++}.
6386 This macro may, however, be invoked with an optional first argument
6387 which, if specified, must be a blank-separated list of C++ compilers to
6388 search for. This just gives the user an opportunity to specify an
6389 alternative search list for the C++ compiler. For example, if you
6390 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6394 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6397 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6398 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
6399 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6400 systems where G++ does not accept @option{-g}), or @option{-g} for other
6404 @defmac AC_PROG_CXXCPP
6405 @acindex{PROG_CXXCPP}
6407 Set output variable @code{CXXCPP} to a command that runs the C++
6408 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6409 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6410 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6412 Some preprocessors don't indicate missing include files by the error
6413 status. For such preprocessors an internal variable is set that causes
6414 other macros to check the standard error from the preprocessor and
6415 consider the test failed if any warnings have been reported. However,
6416 it is not known whether such broken preprocessors exist for C++.
6419 @defmac AC_PROG_CXX_C_O
6420 @acindex{PROG_CXX_C_O}
6421 @cvindex CXX_NO_MINUS_C_MINUS_O
6422 Test whether the C++ compiler accepts the options @option{-c} and
6423 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6428 @node Objective C Compiler
6429 @subsection Objective C Compiler Characteristics
6432 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6436 Determine an Objective C compiler to use. If @code{OBJC} is not already
6437 set in the environment, check for Objective C compilers. Set output
6438 variable @code{OBJC} to the name of the compiler found.
6440 This macro may, however, be invoked with an optional first argument
6441 which, if specified, must be a blank-separated list of Objective C compilers to
6442 search for. This just gives the user an opportunity to specify an
6443 alternative search list for the Objective C compiler. For example, if you
6444 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6448 AC_PROG_OBJC([gcc objcc objc])
6451 If using the @acronym{GNU} Objective C compiler, set shell variable
6452 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
6453 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6454 compiler (@option{-O2} on systems where @command{gcc} does not accept
6455 @option{-g}), or @option{-g} for other compilers.
6458 @defmac AC_PROG_OBJCCPP
6459 @acindex{PROG_OBJCCPP}
6461 Set output variable @code{OBJCCPP} to a command that runs the Objective C
6462 preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6466 @node Erlang Compiler and Interpreter
6467 @subsection Erlang Compiler and Interpreter Characteristics
6470 Autoconf defines the following macros for determining paths to the essential
6471 Erlang/OTP programs:
6473 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path})
6474 @acindex{ERLANG_PATH_ERLC}
6477 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
6478 environment, check for @command{erlc}. Set output variable @code{ERLC} to the
6479 complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
6480 is not set in the environment, set it to an empty value.
6482 The two optional arguments have the same meaning as the two last arguments of
6483 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For
6484 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
6488 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
6492 @defmac AC_ERLANG_NEED_ERLC (@ovar{path})
6493 @acindex{ERLANG_NEED_ERLC}
6494 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
6495 error message and exits the @command{configure} script if the @command{erlc}
6496 program is not found.
6499 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path})
6500 @acindex{ERLANG_PATH_ERL}
6502 Determine an Erlang interpreter to use. If @code{ERL} is not already set in the
6503 environment, check for @command{erl}. Set output variable @code{ERL} to the
6504 complete path of the interpreter command found.
6506 The two optional arguments have the same meaning as the two last arguments of
6507 macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For
6508 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
6512 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
6516 @defmac AC_ERLANG_NEED_ERL (@ovar{path})
6517 @acindex{ERLANG_NEED_ERL}
6518 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
6519 error message and exits the @command{configure} script if the @command{erl}
6520 program is not found.
6524 @node Fortran Compiler
6525 @subsection Fortran Compiler Characteristics
6529 The Autoconf Fortran support is divided into two categories: legacy
6530 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6531 The former are intended for traditional Fortran 77 code, and have output
6532 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
6533 are for newer programs that can (or must) compile under the newer
6534 Fortran standards, and have output variables like @code{FC},
6535 @code{FCFLAGS}, and @code{FCLIBS}.
6537 Except for two new macros @code{AC_FC_SRCEXT} and
6538 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6539 behave almost identically, and so they are documented together in this
6543 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6547 Determine a Fortran 77 compiler to use. If @code{F77} is not already
6548 set in the environment, then check for @code{g77} and @code{f77}, and
6549 then some other names. Set the output variable @code{F77} to the name
6550 of the compiler found.
6552 This macro may, however, be invoked with an optional first argument
6553 which, if specified, must be a blank-separated list of Fortran 77
6554 compilers to search for. This just gives the user an opportunity to
6555 specify an alternative search list for the Fortran 77 compiler. For
6556 example, if you didn't like the default order, then you could invoke
6557 @code{AC_PROG_F77} like this:
6560 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6563 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6564 @code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}.
6565 If the output variable @code{FFLAGS} was not already set in the
6566 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6567 where @code{g77} does not accept @option{-g}). Otherwise, set
6568 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6571 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6575 Determine a Fortran compiler to use. If @code{FC} is not already set in
6576 the environment, then @code{dialect} is a hint to indicate what Fortran
6577 dialect to search for; the default is to search for the newest available
6578 dialect. Set the output variable @code{FC} to the name of the compiler
6581 By default, newer dialects are preferred over older dialects, but if
6582 @code{dialect} is specified then older dialects are preferred starting
6583 with the specified dialect. @code{dialect} can currently be one of
6584 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
6585 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6586 and no attempt is made to guarantee that a particular language standard
6587 is actually supported. Thus, it is preferable that you avoid the
6588 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6589 the latest Fortran standard.
6591 This macro may, alternatively, be invoked with an optional first argument
6592 which, if specified, must be a blank-separated list of Fortran
6593 compilers to search for, just as in @code{AC_PROG_F77}.
6595 If the output variable @code{FCFLAGS} was not already set in the
6596 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
6597 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
6598 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6601 @defmac AC_PROG_F77_C_O
6602 @defmacx AC_PROG_FC_C_O
6603 @acindex{PROG_F77_C_O}
6604 @acindex{PROG_FC_C_O}
6605 @cvindex F77_NO_MINUS_C_MINUS_O
6606 @cvindex FC_NO_MINUS_C_MINUS_O
6607 Test whether the Fortran compiler accepts the options @option{-c} and
6608 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6609 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6612 The following macros check for Fortran compiler characteristics.
6613 To check for characteristics not listed here, use
6614 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6615 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
6616 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6617 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6620 @defmac AC_F77_LIBRARY_LDFLAGS
6621 @defmacx AC_FC_LIBRARY_LDFLAGS
6622 @acindex{F77_LIBRARY_LDFLAGS}
6624 @acindex{FC_LIBRARY_LDFLAGS}
6626 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
6627 @dfn{Fortran intrinsic and runtime libraries} that are required to
6628 successfully link a Fortran program or shared library. The output
6629 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
6630 should be included after @code{LIBS} when linking).
6632 This macro is intended to be used in those situations when it is
6633 necessary to mix, e.g., C++ and Fortran source code in a single
6634 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
6635 automake, @acronym{GNU} Automake}).
6637 For example, if object files from a C++ and Fortran compiler must be
6638 linked together, then the C++ compiler/linker must be used for linking
6639 (since special C++-ish things need to happen at link time like calling
6640 global constructors, instantiating templates, enabling exception
6643 However, the Fortran intrinsic and runtime libraries must be linked in
6644 as well, but the C++ compiler/linker doesn't know by default how to add
6645 these Fortran 77 libraries. Hence, this macro was created to determine
6646 these Fortran libraries.
6648 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6649 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} will probably also be necessary to
6650 link C/C++ with Fortran; see below.
6653 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6654 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6655 @acindex{F77_DUMMY_MAIN}
6656 @cvindex F77_DUMMY_MAIN
6657 With many compilers, the Fortran libraries detected by
6658 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
6659 their own @code{main} entry function that initializes things like
6660 Fortran I/O, and which then calls a user-provided entry function named
6661 (say) @code{MAIN__} to run the user's program. The
6662 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6663 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
6666 When using Fortran for purely numerical functions (no I/O, etc.)@: often
6667 one prefers to provide one's own @code{main} and skip the Fortran
6668 library initializations. In this case, however, one may still need to
6669 provide a dummy @code{MAIN__} routine in order to prevent linking errors
6670 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
6671 detects whether any such routine is @emph{required} for linking, and
6672 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
6673 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
6674 was found, and @code{none} when no such dummy main is needed.
6676 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
6677 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
6678 @emph{if} it is required. @var{action-if-not-found} defaults to
6679 exiting with an error.
6681 In order to link with Fortran routines, the user's C/C++ program should
6682 then include the following code to define the dummy main if it is
6686 #ifdef F77_DUMMY_MAIN
6690 int F77_DUMMY_MAIN() @{ return 1; @}
6694 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6696 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
6697 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
6698 explicitly unless one wants to change the default actions.
6707 As discussed above, many Fortran libraries allow you to provide an entry
6708 point called (say) @code{MAIN__} instead of the usual @code{main}, which
6709 is then called by a @code{main} function in the Fortran libraries that
6710 initializes things like Fortran I/O@. The
6711 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
6712 @emph{possible} to utilize such an alternate main function, and defines
6713 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
6714 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
6715 simply defined to @code{main}.)
6717 Thus, when calling Fortran routines from C that perform things like I/O,
6718 one should use this macro and name the "main" function
6719 @code{F77_MAIN} or @code{FC_MAIN} instead of @code{main}.
6722 @defmac AC_F77_WRAPPERS
6723 @defmacx AC_FC_WRAPPERS
6724 @acindex{F77_WRAPPERS}
6727 @acindex{FC_WRAPPERS}
6730 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
6731 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
6732 mangle the names of C/C++ identifiers, and identifiers with underscores,
6733 respectively, so that they match the name-mangling scheme used by the
6736 Fortran is case-insensitive, and in order to achieve this the Fortran
6737 compiler converts all identifiers into a canonical case and format. To
6738 call a Fortran subroutine from C or to write a C function that is
6739 callable from Fortran, the C program must explicitly use identifiers in
6740 the format expected by the Fortran compiler. In order to do this, one
6741 simply wraps all C identifiers in one of the macros provided by
6742 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
6743 you have the following Fortran 77 subroutine:
6746 subroutine foobar (x, y)
6747 double precision x, y
6753 You would then declare its prototype in C or C++ as:
6756 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
6758 extern "C" /* prevent C++ name mangling */
6760 void FOOBAR_F77(double *x, double *y);
6763 Note that we pass both the lowercase and uppercase versions of the
6764 function name to @code{F77_FUNC} so that it can select the right one.
6765 Note also that all parameters to Fortran 77 routines are passed as
6766 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
6769 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6771 Although Autoconf tries to be intelligent about detecting the
6772 name-mangling scheme of the Fortran compiler, there may be Fortran
6773 compilers that it doesn't support yet. In this case, the above code
6774 will generate a compile-time error, but some other behavior
6775 (e.g., disabling Fortran-related features) can be induced by checking
6776 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
6778 Now, to call that routine from a C program, we would do something like:
6782 double x = 2.7183, y;
6783 FOOBAR_F77 (&x, &y);
6787 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
6788 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
6789 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
6790 because some Fortran compilers mangle names differently if they contain
6794 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
6795 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
6798 Given an identifier @var{name}, set the shell variable @var{shellvar} to
6799 hold the mangled version @var{name} according to the rules of the
6800 Fortran linker (see also @code{AC_F77_WRAPPERS} or
6801 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
6802 supplied, the shell variable will be simply @var{name}. The purpose of
6803 this macro is to give the caller a way to access the name-mangling
6804 information other than through the C preprocessor as above, for example,
6805 to call Fortran routines from some language other than C/C++.
6808 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
6810 By default, the @code{FC} macros perform their tests using a @file{.f}
6811 extension for source-code files. Some compilers, however, only enable
6812 newer language features for appropriately named files, e.g., Fortran 90
6813 features only for @file{.f90} files. On the other hand, some other
6814 compilers expect all source files to end in @file{.f} and require
6815 special flags to support other file name extensions. The
6816 @code{AC_FC_SRCEXT} macro deals with both of these issues.
6818 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
6819 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
6820 contain the dot). If any special compiler flags are needed for this, it
6821 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
6822 extension and these flags are then used for all subsequent @code{FC} tests
6823 (until @code{AC_FC_SRCEXT} is called again).
6825 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
6826 @file{.f90} extension in future tests, and it would set a
6827 @code{FCFLAGS_f90} output variable with any extra flags that are needed
6828 to compile such files.
6830 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
6831 @code{FCFLAGS}, for two reasons based on the limitations of some
6832 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
6833 time, so files with different extensions must be compiled separately.
6834 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
6835 the source-code file name when compiling. So, continuing the example
6836 above, you might compile a @file{foo.f90} file in your Makefile with the
6841 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) foo.f90
6844 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
6845 extension, it calls @var{action-if-success} (defaults to nothing). If
6846 it fails, and cannot find a way to make the @code{FC} compiler accept such
6847 files, it calls @var{action-if-failure} (defaults to exiting with an
6852 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
6853 @acindex{FC_FREEFORM}
6855 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
6856 (@code{$FC}) allows free-format source code (as opposed to the older
6857 fixed-format style from Fortran 77). If necessary, it may add some
6858 additional flags to @code{FCFLAGS}.
6860 This macro is most important if you are using the default @file{.f}
6861 extension, since many compilers interpret this extension as indicating
6862 fixed-format source unless an additional flag is supplied. If you
6863 specify a different extension with @code{AC_FC_SRCEXT}, such as
6864 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} will ordinarily
6865 succeed without modifying @code{FCFLAGS}.
6867 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
6868 calls @var{action-if-success} (defaults to nothing). If it fails, it
6869 calls @var{action-if-failure} (defaults to exiting with an error
6873 @node System Services
6874 @section System Services
6876 The following macros check for operating system services or capabilities.
6881 @cindex X Window System
6882 Try to locate the X Window System include files and libraries. If the
6883 user gave the command line options @option{--x-includes=@var{dir}} and
6884 @option{--x-libraries=@var{dir}}, use those directories.
6886 If either or both were not given, get the missing values by running
6887 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
6888 environment variable) on a trivial @file{Imakefile} and examining the
6889 @file{Makefile} that it produces. Setting @code{XMKMF} to @samp{false}
6890 will disable this method.
6892 If this method fails to find the X Window System, @command{configure}
6893 will look for the files in several directories where they often reside.
6894 If either method is successful, set the shell variables
6895 @code{x_includes} and @code{x_libraries} to their locations, unless they
6896 are in directories the compiler searches by default.
6898 If both methods fail, or the user gave the command line option
6899 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
6900 otherwise set it to the empty string.
6903 @defmac AC_PATH_XTRA
6907 @ovindex X_EXTRA_LIBS
6909 @cvindex X_DISPLAY_MISSING
6910 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
6911 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
6912 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
6915 This macro also checks for special libraries that some systems need in
6916 order to compile X programs. It adds any that the system needs to
6917 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
6918 libraries that need to be linked with before @option{-lX11}, and adds
6919 any found to the output variable @code{X_PRE_LIBS}.
6921 @c This is an incomplete kludge. Make a real way to do it.
6922 @c If you need to check for other X functions or libraries yourself, then
6923 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
6924 @c @code{LIBS} temporarily, like this: (FIXME - add example)
6927 @defmac AC_SYS_INTERPRETER
6928 @acindex{SYS_INTERPRETER}
6929 Check whether the system supports starting scripts with a line of the
6930 form @samp{#!/bin/sh} to select the interpreter to use for the script.
6931 After running this macro, shell code in @file{configure.ac} can check
6932 the shell variable @code{interpval}; it will be set to @samp{yes}
6933 if the system supports @samp{#!}, @samp{no} if not.
6936 @defmac AC_SYS_LARGEFILE
6937 @acindex{SYS_LARGEFILE}
6938 @cvindex _FILE_OFFSET_BITS
6939 @cvindex _LARGE_FILES
6941 @cindex Large file support
6944 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
6945 large-file support}. On some hosts, one must use special compiler
6946 options to build programs that can access large files. Append any such
6947 options to the output variable @code{CC}. Define
6948 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
6950 Large-file support can be disabled by configuring with the
6951 @option{--disable-largefile} option.
6953 If you use this macro, check that your program works even when
6954 @code{off_t} is wider than @code{long int}, since this is common when
6955 large-file support is enabled. For example, it is not correct to print
6956 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
6959 The LFS introduced the @code{fseeko} and @code{ftello} functions to
6960 replace their C counterparts @code{fseek} and @code{ftell} that do not
6961 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
6962 prototypes available when using them and large-file support is
6966 @defmac AC_SYS_LONG_FILE_NAMES
6967 @acindex{SYS_LONG_FILE_NAMES}
6968 @cvindex HAVE_LONG_FILE_NAMES
6969 If the system supports file names longer than 14 characters, define
6970 @code{HAVE_LONG_FILE_NAMES}.
6973 @defmac AC_SYS_POSIX_TERMIOS
6974 @acindex{SYS_POSIX_TERMIOS}
6975 @cindex Posix termios headers
6976 @cindex termios Posix headers
6977 Check to see if the Posix termios headers and functions are available on the
6978 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
6979 @samp{yes}. If not, set the variable to @samp{no}.
6982 @node Posix Variants
6983 @section Posix Variants
6985 The following macros check for certain operating systems that need
6986 special treatment for some programs, due to exceptional oddities in
6987 their header files or libraries. These macros are warts; they will be
6988 replaced by a more systematic approach, based on the functions they make
6989 available or the environments they provide.
6993 @cvindex _ALL_SOURCE
6994 If on @acronym{AIX}, define @code{_ALL_SOURCE}.
6995 Allows the use of some @acronym{BSD}
6996 functions. Should be called before any macros that run the C compiler.
6999 @defmac AC_GNU_SOURCE
7000 @acindex{GNU_SOURCE}
7001 @cvindex _GNU_SOURCE
7002 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
7003 Allows the use of some @acronym{GNU} functions. Should be called
7004 before any macros that run the C compiler.
7007 @defmac AC_ISC_POSIX
7010 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
7011 variable @code{LIBS} if necessary for Posix facilities. Call this
7012 after @code{AC_PROG_CC} and before any other macros that use Posix
7013 interfaces. @sc{interactive} Unix is no longer sold, and Sun says that
7014 they will drop support for it on 2006-07-23, so this macro is becoming
7021 @cvindex _POSIX_SOURCE
7022 @cvindex _POSIX_1_SOURCE
7023 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
7024 @code{_POSIX_1_SOURCE} to be 2. This allows the use of Posix
7025 facilities. Should be called before any macros that run the C compiler.
7028 @defmac AC_USE_SYSTEM_EXTENSIONS
7029 @acindex{USE_SYSTEM_EXTENSIONS}
7030 @cvindex _ALL_SOURCE
7031 @cvindex _GNU_SOURCE
7033 @cvindex _POSIX_1_SOURCE
7034 @cvindex _POSIX_PTHREAD_SEMANTICS
7035 @cvindex _POSIX_SOURCE
7036 @cvindex __EXTENSIONS__
7037 If possible, enable extensions to Posix on hosts that normally disable
7038 the extensions, typically due to standards-conformance namespace issues.
7039 This may involve defining @code{__EXTENSIONS__} and
7040 @code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris. This
7041 macro also has the combined effects of @code{AC_GNU_SOURCE},
7042 @code{AC_AIX}, and @code{AC_MINIX}.
7046 @node Erlang Libraries
7047 @section Erlang Libraries
7048 @cindex Erlang, Library, checking
7050 The following macros check for an installation of Erlang/OTP, and for the
7051 presence of certain Erlang libraries. All those macros require the
7052 configuration of an Erlang interpreter and an Erlang compiler
7053 (@pxref{Erlang Compiler and Interpreter}).
7055 @defmac AC_ERLANG_SUBST_ROOT_DIR
7056 @acindex{ERLANG_SUBST_ROOT_DIR}
7057 @ovindex ERLANG_ROOT_DIR
7059 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory
7060 in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0}
7061 function). The result of this test is cached if caching is enabled when running
7062 @command{configure}.
7065 @defmac AC_ERLANG_SUBST_LIB_DIR
7066 @acindex{ERLANG_SUBST_LIB_DIR}
7067 @ovindex ERLANG_LIB_DIR
7069 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7070 directory of Erlang/OTP (as returned by Erlang's
7071 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7072 Erlang/OTP library. The result of this test is cached if caching is enabled
7073 when running @command{configure}.
7076 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found})
7077 @acindex{ERLANG_CHECK_LIB}
7078 @ovindex ERLANG_LIB_DIR_@var{library}
7080 Test whether the Erlang/OTP library @var{library} is installed by calling
7081 Erlang's @code{code:lib_dir/1} function. The result of this test is cached if
7082 caching is enabled when running @command{configure}. @var{action-if-found} is a
7083 list of shell commands to run if the library is installed;
7084 @var{action-if-not-found} is a list of shell commands to run if it is not.
7085 Additionally, if the library is installed, the output variable
7086 @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the library
7087 installation directory. For example, to check if library @code{stdlib} is
7091 AC_ERLANG_CHECK_LIB([stdlib],
7092 [echo "stdlib is installed in $ERLANG_LIB_DIR_stdlib"],
7093 [AC_MSG_ERROR([stdlib was not found!])])
7097 In addition to the above macros, which test installed Erlang libraries, the
7098 following macros determine the paths to the directories into which newly built
7099 Erlang libraries are to be installed:
7101 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7102 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7103 @ovindex ERLANG_INSTALL_LIB_DIR
7105 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7106 which every built Erlang library should be installed in a separate subdirectory.
7107 If this variable is not set in the environment when @command{configure} runs,
7108 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7109 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7112 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7113 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7114 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7116 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7117 directory into which the built Erlang library @var{library} version
7118 @var{version} should be installed. If this variable is not set in the
7119 environment when @command{configure} runs, its default value is
7120 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7121 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7122 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7129 @c ========================================================= Writing Tests
7132 @chapter Writing Tests
7134 If the existing feature tests don't do something you need, you have to
7135 write new ones. These macros are the building blocks. They provide
7136 ways for other macros to check whether various kinds of features are
7137 available and report the results.
7139 This chapter contains some suggestions and some of the reasons why the
7140 existing tests are written the way they are. You can also learn a lot
7141 about how to write Autoconf tests by looking at the existing ones. If
7142 something goes wrong in one or more of the Autoconf tests, this
7143 information can help you understand the assumptions behind them, which
7144 might help you figure out how to best solve the problem.
7146 These macros check the output of the compiler system of the current
7147 language (@pxref{Language Choice}). They do not cache the results of
7148 their tests for future use (@pxref{Caching Results}), because they don't
7149 know enough about the information they are checking for to generate a
7150 cache variable name. They also do not print any messages, for the same
7151 reason. The checks for particular kinds of features call these macros
7152 and do cache their results and print messages about what they're
7155 When you write a feature test that could be applicable to more than one
7156 software package, the best thing to do is encapsulate it in a new macro.
7157 @xref{Writing Autoconf Macros}, for how to do that.
7160 * Language Choice:: Selecting which language to use for testing
7161 * Writing Test Programs:: Forging source files for compilers
7162 * Running the Preprocessor:: Detecting preprocessor symbols
7163 * Running the Compiler:: Detecting language or header features
7164 * Running the Linker:: Detecting library features
7165 * Runtime:: Testing for runtime features
7166 * Systemology:: A zoology of operating systems
7167 * Multiple Cases:: Tests for several possible values
7170 @node Language Choice
7171 @section Language Choice
7174 Autoconf-generated @command{configure} scripts check for the C compiler and
7175 its features by default. Packages that use other programming languages
7176 (maybe more than one, e.g., C and C++) need to test features of the
7177 compilers for the respective languages. The following macros determine
7178 which programming language is used in the subsequent tests in
7179 @file{configure.ac}.
7181 @defmac AC_LANG (@var{language})
7182 Do compilation tests using the compiler, preprocessor, and file
7183 extensions for the specified @var{language}.
7185 Supported languages are:
7189 Do compilation tests using @code{CC} and @code{CPP} and use extension
7190 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
7191 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7194 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7195 extension @file{.C} for test programs. Use compilation flags:
7196 @code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and
7197 @code{CXXFLAGS} with @code{CXX}.
7200 Do compilation tests using @code{F77} and use extension @file{.f} for
7201 test programs. Use compilation flags: @code{FFLAGS}.
7204 Do compilation tests using @code{FC} and use extension @file{.f} (or
7205 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
7206 compilation flags: @code{FCFLAGS}.
7212 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7213 @file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
7216 Do compilation tests using @code{OBJC} and @code{OBJCCPP} and use
7217 extension @file{.m} for test programs. Use compilation flags:
7218 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7219 @code{OBJCFLAGS} with @code{OBJC}.
7223 @defmac AC_LANG_PUSH (@var{language})
7225 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7226 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
7227 in macros that need to temporarily switch to a particular language.
7230 @defmac AC_LANG_POP (@ovar{language})
7232 Select the language that is saved on the top of the stack, as set by
7233 @code{AC_LANG_PUSH}, and remove it from the stack.
7235 If given, @var{language} specifies the language we just @emph{quit}. It
7236 is a good idea to specify it when it's known (which should be the
7237 case@dots{}), since Autoconf will detect inconsistencies.
7240 AC_LANG_PUSH([Fortran 77])
7241 # Perform some tests on Fortran 77.
7243 AC_LANG_POP([Fortran 77])
7247 @defmac AC_LANG_ASSERT (@var{language})
7248 @acindex{LANG_ASSERT} Check statically that the current language is
7249 @var{language}. You should use this in your language specific macros
7250 to avoid that they be called with an inappropriate language.
7252 This macro runs only at @command{autoconf} time, and incurs no cost at
7253 @command{configure} time. Sadly enough and because Autoconf is a two
7254 layer language @footnote{Because M4 is not aware of Sh code,
7255 especially conditionals, some optimizations that look nice statically
7256 may produce incorrect results at runtime.}, the macros
7257 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7258 therefore as much as possible you ought to avoid using them to wrap
7259 your code, rather, require from the user to run the macro with a
7260 correct current language, and check it with @code{AC_LANG_ASSERT}.
7261 And anyway, that may help the user understand she is running a Fortran
7262 macro while expecting a result about her Fortran 77 compiler@dots{}
7266 @defmac AC_REQUIRE_CPP
7267 @acindex{REQUIRE_CPP}
7268 Ensure that whichever preprocessor would currently be used for tests has
7269 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7270 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7271 depending on which language is current.
7275 @node Writing Test Programs
7276 @section Writing Test Programs
7278 Autoconf tests follow a common scheme: feed some program with some
7279 input, and most of the time, feed a compiler with some source file.
7280 This section is dedicated to these source samples.
7283 * Guidelines:: General rules for writing test programs
7284 * Test Functions:: Avoiding pitfalls in test programs
7285 * Generating Sources:: Source program boilerplate
7289 @subsection Guidelines for Test Programs
7291 The most important rule to follow when writing testing samples is:
7293 @center @emph{Look for realism.}
7295 This motto means that testing samples must be written with the same
7296 strictness as real programs are written. In particular, you should
7297 avoid ``shortcuts'' and simplifications.
7299 Don't just play with the preprocessor if you want to prepare a
7300 compilation. For instance, using @command{cpp} to check whether a header is
7301 functional might let your @command{configure} accept a header which will
7302 cause some @emph{compiler} error. Do not hesitate checking header with
7303 other headers included before, especially required headers.
7305 Make sure the symbols you use are properly defined, i.e., refrain for
7306 simply declaring a function yourself instead of including the proper
7309 Test programs should not write to standard output. They
7310 should exit with status 0 if the test succeeds, and with status 1
7311 otherwise, so that success
7312 can be distinguished easily from a core dump or other failure;
7313 segmentation violations and other failures produce a nonzero exit
7314 status. Unless you arrange for @code{exit} to be declared, test
7315 programs should @code{return}, not @code{exit}, from @code{main},
7316 because on many systems @code{exit} is not declared by default.
7318 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7319 preprocessor macros defined by tests that have already run. For
7320 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7321 @file{configure.ac} you can have a test program that includes
7322 @file{stdbool.h} conditionally:
7327 # include <stdbool.h>
7332 If a test program needs to use or create a data file, give it a name
7333 that starts with @file{conftest}, such as @file{conftest.data}. The
7334 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7335 after running test programs and if the script is interrupted.
7337 @node Test Functions
7338 @subsection Test Functions
7340 These days it's safe to assume support for function prototypes
7341 (introduced in C89).
7343 Functions that test programs declare should also be conditionalized for
7344 C++, which requires @samp{extern "C"} prototypes. Make sure to not
7345 include any header files containing clashing prototypes.
7351 void *valloc (size_t);
7354 If a test program calls a function with invalid parameters (just to see
7355 whether it exists), organize the program to ensure that it never invokes
7356 that function. You can do this by calling it in another function that is
7357 never invoked. You can't do it by putting it after a call to
7358 @code{exit}, because GCC version 2 knows that @code{exit} never returns
7359 and optimizes out any code that follows it in the same block.
7361 If you include any header files, be sure to call the functions
7362 relevant to them with the correct number of arguments, even if they are
7363 just 0, to avoid compilation errors due to prototypes. GCC version 2
7364 has internal prototypes for several functions that it automatically
7365 inlines; for example, @code{memcpy}. To avoid errors when checking for
7366 them, either pass them the correct number of arguments or redeclare them
7367 with a different return type (such as @code{char}).
7370 @node Generating Sources
7371 @subsection Generating Sources
7373 Autoconf provides a set of macros that can be used to generate test
7374 source files. They are written to be language generic, i.e., they
7375 actually depend on the current language (@pxref{Language Choice}) to
7376 ``format'' the output properly.
7379 @defmac AC_LANG_CONFTEST (@var{source})
7380 @acindex{LANG_CONFTEST}
7381 Save the @var{source} text in the current test source file:
7382 @file{conftest.@var{extension}} where the @var{extension} depends on the
7385 Note that the @var{source} is evaluated exactly once, like regular
7386 Autoconf macro arguments, and therefore (i) you may pass a macro
7387 invocation, (ii) if not, be sure to double quote if needed.
7390 @defmac AC_LANG_SOURCE (@var{source})
7391 @acindex{LANG_SOURCE}
7392 Expands into the @var{source}, with the definition of
7393 all the @code{AC_DEFINE} performed so far.
7396 For instance executing (observe the double quotation!):
7399 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7400 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7401 [Greetings string.])
7404 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7405 gcc -E -dD -o - conftest.c
7415 #define PACKAGE_NAME "Hello"
7416 #define PACKAGE_TARNAME "hello"
7417 #define PACKAGE_VERSION "1.0"
7418 #define PACKAGE_STRING "Hello 1.0"
7419 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7420 #define HELLO_WORLD "Hello, World\n"
7422 const char hw[] = "Hello, World\n";
7425 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7426 are not automatically translated into constants in the source code by this
7429 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7430 @acindex{LANG_PROGRAM}
7431 Expands into a source file which consists of the @var{prologue}, and
7432 then @var{body} as body of the main function (e.g., @code{main} in
7433 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7440 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7441 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7442 [Greetings string.])
7444 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7445 [[fputs (hw, stdout);]])])
7446 gcc -E -dD -o - conftest.c
7456 #define PACKAGE_NAME "Hello"
7457 #define PACKAGE_TARNAME "hello"
7458 #define PACKAGE_VERSION "1.0"
7459 #define PACKAGE_STRING "Hello 1.0"
7460 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7461 #define HELLO_WORLD "Hello, World\n"
7463 const char hw[] = "Hello, World\n";
7473 In Erlang tests, the created source file is that of an Erlang module called
7474 @code{conftest} (@file{conftest.erl}). This module defines and exports at least
7475 one @code{start/0} function, which is called to perform the test. The
7476 @var{prologue} is optional code that is inserted between the module header and
7477 the @code{start/0} function definition. @var{body} is the body of the
7478 @code{start/0} function without the final period (@pxref{Runtime}, about
7479 constraints on this function's behaviour).
7484 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7487 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
7488 [[io:format("~s~n", [?HELLO_WORLD])]])])
7498 -define(HELLO_WORLD, "Hello, world!").
7500 io:format("~s~n", [?HELLO_WORLD])
7504 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
7506 Expands into a source file which consists of the @var{prologue}, and
7507 then a call to the @var{function} as body of the main function (e.g.,
7508 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
7509 of the latter are available.
7511 This function will probably be replaced in the future by a version
7512 which would enable specifying the arguments. The use of this macro is
7513 not encouraged, as it violates strongly the typing system.
7515 This macro cannot be used for Erlang tests.
7518 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
7519 @acindex{LANG_FUNC_LINK_TRY}
7520 Expands into a source file which uses the @var{function} in the body of
7521 the main function (e.g., @code{main} in C). Since it uses
7522 @code{AC_LANG_PROGRAM}, the features of the latter are available.
7524 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
7525 It is considered to be severely broken, and in the future will be
7526 removed in favor of actual function calls (with properly typed
7529 This macro cannot be used for Erlang tests.
7532 @node Running the Preprocessor
7533 @section Running the Preprocessor
7535 Sometimes one might need to run the preprocessor on some source file.
7536 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
7537 your project, not merely run the preprocessor on it; therefore you
7538 certainly want to run the compiler, not the preprocessor. Resist the
7539 temptation of following the easiest path.
7541 Nevertheless, if you need to run the preprocessor, then use
7542 @code{AC_PREPROC_IFELSE}.
7544 The macros described in this section cannot be used for tests in Erlang or
7545 Fortran, since those languages require no preprocessor.
7547 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7548 @acindex{PREPROC_IFELSE}
7549 Run the preprocessor of the current language (@pxref{Language Choice})
7550 on the @var{input}, run the shell commands @var{action-if-true} on
7551 success, @var{action-if-false} otherwise. The @var{input} can be made
7552 by @code{AC_LANG_PROGRAM} and friends.
7554 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
7555 @option{-g}, @option{-O}, etc.@: are not valid options to many C
7558 It is customary to report unexpected failures with
7559 @code{AC_MSG_FAILURE}.
7565 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7566 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7567 [Greetings string.])
7569 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7570 [[fputs (hw, stdout);]])],
7571 [AC_MSG_RESULT([OK])],
7572 [AC_MSG_FAILURE([unexpected preprocessor failure])])
7579 checking for gcc... gcc
7580 checking for C compiler default output file name... a.out
7581 checking whether the C compiler works... yes
7582 checking whether we are cross compiling... no
7583 checking for suffix of executables...
7584 checking for suffix of object files... o
7585 checking whether we are using the GNU C compiler... yes
7586 checking whether gcc accepts -g... yes
7587 checking for gcc option to accept ISO C89... none needed
7588 checking how to run the C preprocessor... gcc -E
7594 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
7595 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
7596 it impossible to use it to elaborate sources. You are encouraged to
7597 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
7598 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
7599 to run the @emph{preprocessor} and not the compiler?
7601 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
7602 @acindex{EGREP_HEADER}
7603 If the output of running the preprocessor on the system header file
7604 @var{header-file} matches the extended regular expression
7605 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
7606 execute @var{action-if-not-found}.
7609 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
7611 @var{program} is the text of a C or C++ program, on which shell
7612 variable, back quote, and backslash substitutions are performed. If the
7613 output of running the preprocessor on @var{program} matches the
7614 extended regular expression @var{pattern}, execute shell commands
7615 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
7620 @node Running the Compiler
7621 @section Running the Compiler
7623 To check for a syntax feature of the current language's (@pxref{Language
7624 Choice}) compiler, such as whether it recognizes a certain keyword, or
7625 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
7626 to compile a small program that uses that feature.
7628 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7629 @acindex{COMPILE_IFELSE}
7630 Run the compiler and compilation flags of the current language
7631 (@pxref{Language Choice}) on the @var{input}, run the shell commands
7632 @var{action-if-true} on success, @var{action-if-false} otherwise. The
7633 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7635 It is customary to report unexpected failures with
7636 @code{AC_MSG_FAILURE}. This macro does not try to link; use
7637 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
7642 For tests in Erlang, the @var{input} must be the source code of a module named
7643 @code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
7644 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
7645 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure
7646 that the Erlang module has the right name.
7648 @node Running the Linker
7649 @section Running the Linker
7651 To check for a library, a function, or a global variable, Autoconf
7652 @command{configure} scripts try to compile and link a small program that
7653 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
7654 @code{ar} on the C library to try to figure out which functions are
7655 available. Trying to link with the function is usually a more reliable
7656 approach because it avoids dealing with the variations in the options
7657 and output formats of @code{nm} and @code{ar} and in the location of the
7658 standard libraries. It also allows configuring for cross-compilation or
7659 checking a function's runtime behavior if needed. On the other hand,
7660 it can be slower than scanning the libraries once, but accuracy is more
7661 important than speed.
7663 @code{AC_LINK_IFELSE} is used to compile test programs to test for
7664 functions and global variables. It is also used by @code{AC_CHECK_LIB}
7665 to check for libraries (@pxref{Libraries}), by adding the library being
7666 checked for to @code{LIBS} temporarily and trying to link a small
7670 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7671 @acindex{LINK_IFELSE}
7672 Run the compiler (and compilation flags) and the linker of the current
7673 language (@pxref{Language Choice}) on the @var{input}, run the shell
7674 commands @var{action-if-true} on success, @var{action-if-false}
7675 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
7678 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7679 current compilation flags.
7681 It is customary to report unexpected failures with
7682 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
7683 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
7686 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
7687 programs are interpreted and do not require linking.
7692 @section Checking Runtime Behavior
7694 Sometimes you need to find out how a system performs at runtime, such
7695 as whether a given function has a certain capability or bug. If you
7696 can, make such checks when your program runs instead of when it is
7697 configured. You can check for things like the machine's endianness when
7698 your program initializes itself.
7700 If you really need to test for a runtime behavior while configuring,
7701 you can write a test program to determine the result, and compile and
7702 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
7703 possible, because this prevents people from configuring your package for
7706 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
7707 @acindex{RUN_IFELSE}
7708 If @var{program} compiles and links successfully and returns an exit
7709 status of 0 when executed, run shell commands @var{action-if-true}.
7710 Otherwise, run shell commands @var{action-if-false}.
7712 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7713 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7714 compilation flags of the current language (@pxref{Language Choice}).
7716 If the compiler being used does not produce executables that run on the
7717 system where @command{configure} is being run, then the test program is
7718 not run. If the optional shell commands @var{action-if-cross-compiling}
7719 are given, they are run instead. Otherwise, @command{configure} prints
7720 an error message and exits.
7722 In the @var{action-if-false} section, the failing exit status is
7723 available in the shell variable @samp{$?}. This exit status might be
7724 that of a failed compilation, or it might be that of a failed program
7727 It is customary to report unexpected failures with
7728 @code{AC_MSG_FAILURE}.
7731 Try to provide a pessimistic default value to use when cross-compiling
7732 makes runtime tests impossible. You do this by passing the optional
7733 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
7734 warning message when creating @command{configure} each time it
7735 encounters a call to @code{AC_RUN_IFELSE} with no
7736 @var{action-if-cross-compiling} argument given. You may ignore the
7737 warning, though users will not be able to configure your package for
7738 cross-compiling. A few of the macros distributed with Autoconf produce
7739 this warning message.
7741 To configure for cross-compiling you can also choose a value for those
7742 parameters based on the canonical system name (@pxref{Manual
7743 Configuration}). Alternatively, set up a test results cache file with
7744 the correct values for the host system (@pxref{Caching Results}).
7746 @ovindex cross_compiling
7747 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
7748 in other macros, including a few of the ones that come with Autoconf,
7749 you can test whether the shell variable @code{cross_compiling} is set to
7750 @samp{yes}, and then use an alternate method to get the results instead
7751 of calling the macros.
7753 A C or C++ runtime test should be portable.
7754 @xref{Portable C and C++}.
7756 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
7757 function: the given status code is used to determine the success of the test
7758 (status is @code{0}) or its failure (status is different than @code{0}), as
7759 explained above. It must be noted that data output through the standard output
7760 (e.g. using @code{io:format/2}) may be truncated when halting the VM.
7761 Therefore, if a test must output configuration information, it is recommended
7762 to create and to output data into the temporary file named @file{conftest.out},
7763 using the functions of module @code{file}. The @code{conftest.out} file is
7764 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
7765 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is:
7768 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
7772 [AC_LANG_PROGRAM([], [dnl
7773 file:write_file("conftest.out", code:lib_dir()),
7775 [echo "code:lib_dir() returned: `cat conftest.out`"],
7776 [AC_MSG_FAILURE([test Erlang program execution failed])])
7781 @section Systemology
7784 This section aims at presenting some systems and pointers to
7785 documentation. It may help you addressing particular problems reported
7788 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
7789 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
7792 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
7793 contains a table correlating the features of various Posix-conforming
7794 systems. @uref{http://www.levenez.com/unix/, Unix History} is a
7795 simplified diagram of how many Unix systems were derived from each
7798 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
7799 provides some variants of traditional implementations of Unix utilities.
7804 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
7805 case-preserving, but case insensitive. This can cause nasty problems,
7806 since for instance the installation attempt for a package having an
7807 @file{INSTALL} file can result in @samp{make install} report that
7808 nothing was to be done!
7810 That's all dependent on whether the file system is a UFS (case
7811 sensitive) or HFS+ (case preserving). By default Apple wants you to
7812 install the OS on HFS+. Unfortunately, there are some pieces of
7813 software which really need to be built on UFS@. We may want to rebuild
7814 Darwin to have both UFS and HFS+ available (and put the /local/build
7817 @item @acronym{QNX} 4.25
7818 @cindex @acronym{QNX} 4.25
7819 @c FIXME: Please, if you feel like writing something more precise,
7820 @c it'd be great. In particular, I can't understand the difference with
7822 @acronym{QNX} is a realtime operating system running on Intel architecture
7823 meant to be scalable from the small embedded systems to the hundred
7824 processor super-computer. It claims to be Posix certified. More
7825 information is available on the
7826 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
7830 @uref{http://h30097.www3.hp.com/@/docs/,
7831 Documentation of several versions of Tru64} is available in different
7834 @item Unix version 7
7835 @cindex Unix version 7
7837 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
7838 time-sharing system'' but we use the more-common name ``Unix version 7''.
7839 Documentation is available in the
7840 @uref{http://plan9.bell-labs.com/7thEdMan/, Unix Seventh Edition Manual}.
7841 Previous versions of Unix are called ``Unix version 6'', etc., but
7842 they were not as widely used.
7846 @node Multiple Cases
7847 @section Multiple Cases
7849 Some operations are accomplished in several possible ways, depending on
7850 the OS variant. Checking for them essentially requires a ``case
7851 statement''. Autoconf does not directly provide one; however, it is
7852 easy to simulate by using a shell variable to keep track of whether a
7853 way to perform the operation has been found yet.
7855 Here is an example that uses the shell variable @code{fstype} to keep
7856 track of whether the remaining cases need to be checked.
7860 AC_MSG_CHECKING([how to get file system type])
7862 # The order of these tests is important.
7863 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
7864 #include <sys/fstyp.h>]])],
7865 [AC_DEFINE([FSTYPE_STATVFS], [1],
7866 [Define if statvfs exists.])
7868 if test $fstype = no; then
7869 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
7870 #include <sys/fstyp.h>]])],
7871 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
7872 [Define if USG statfs.])
7875 if test $fstype = no; then
7876 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
7877 #include <sys/vmount.h>]])]),
7878 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
7879 [Define if AIX statfs.])
7882 # (more cases omitted here)
7883 AC_MSG_RESULT([$fstype])
7887 @c ====================================================== Results of Tests.
7890 @chapter Results of Tests
7892 Once @command{configure} has determined whether a feature exists, what can
7893 it do to record that information? There are four sorts of things it can
7894 do: define a C preprocessor symbol, set a variable in the output files,
7895 save the result in a cache file for future @command{configure} runs, and
7896 print a message letting the user know the result of the test.
7899 * Defining Symbols:: Defining C preprocessor symbols
7900 * Setting Output Variables:: Replacing variables in output files
7901 * Special Chars in Variables:: Characters to beware of in variables
7902 * Caching Results:: Speeding up subsequent @command{configure} runs
7903 * Printing Messages:: Notifying @command{configure} users
7906 @node Defining Symbols
7907 @section Defining C Preprocessor Symbols
7909 A common action to take in response to a feature test is to define a C
7910 preprocessor symbol indicating the results of the test. That is done by
7911 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
7913 By default, @code{AC_OUTPUT} places the symbols defined by these macros
7914 into the output variable @code{DEFS}, which contains an option
7915 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
7916 Autoconf version 1, there is no variable @code{DEFS} defined while
7917 @command{configure} is running. To check whether Autoconf macros have
7918 already defined a certain C preprocessor symbol, test the value of the
7919 appropriate cache variable, as in this example:
7922 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
7923 [Define if vprintf exists.])])
7924 if test "$ac_cv_func_vprintf" != yes; then
7925 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
7926 [Define if _doprnt exists.])])
7930 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
7931 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
7932 correct values into @code{#define} statements in a template file.
7933 @xref{Configuration Headers}, for more information about this kind of
7936 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
7937 @defmacx AC_DEFINE (@var{variable})
7939 Define the C preprocessor variable @var{variable} to @var{value} (verbatim).
7940 @var{value} should not contain literal newlines, and if you are not
7941 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
7942 characters, as @command{make} tends to eat them. To use a shell variable,
7943 use @code{AC_DEFINE_UNQUOTED} instead.
7944 @var{description} is only useful if you are using
7945 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
7946 the generated @file{config.h.in} as the comment before the macro define.
7947 The following example defines the C preprocessor variable
7948 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
7951 AC_DEFINE([EQUATION], ["$a > $b"],
7955 If neither @var{value} nor @var{description} are given, then
7956 @var{value} defaults to 1 instead of to the empty string. This is for
7957 backwards compatibility with older versions of Autoconf, but this usage
7958 is obsolescent and may be withdrawn in future versions of Autoconf.
7960 If the @var{variable} is a literal string, it is passed to
7961 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
7964 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
7965 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
7966 @acindex{DEFINE_UNQUOTED}
7967 Like @code{AC_DEFINE}, but three shell expansions are
7968 performed---once---on @var{variable} and @var{value}: variable expansion
7969 (@samp{$}), command substitution (@samp{`}), and backslash escaping
7970 (@samp{\}). Single and double quote characters in the value have no
7971 special meaning. Use this macro instead of @code{AC_DEFINE} when
7972 @var{variable} or @var{value} is a shell variable. Examples:
7975 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
7976 [Configuration machine file.])
7977 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
7978 [getgroups return type.])
7979 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
7980 [Translated header name.])
7984 Due to a syntactical bizarreness of the Bourne shell, do not use
7985 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
7986 calls from other macro calls or shell code; that can cause syntax errors
7987 in the resulting @command{configure} script. Use either blanks or
7988 newlines. That is, do this:
7991 AC_CHECK_HEADER([elf.h],
7992 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
7999 AC_CHECK_HEADER([elf.h],
8000 [AC_DEFINE([SVR4], [1], [System V Release 4])
8001 LIBS="-lelf $LIBS"])
8008 AC_CHECK_HEADER([elf.h],
8009 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8012 @node Setting Output Variables
8013 @section Setting Output Variables
8014 @cindex Output variables
8016 Another way to record the results of tests is to set @dfn{output
8017 variables}, which are shell variables whose values are substituted into
8018 files that @command{configure} outputs. The two macros below create new
8019 output variables. @xref{Preset Output Variables}, for a list of output
8020 variables that are always available.
8022 @defmac AC_SUBST (@var{variable}, @ovar{value})
8024 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
8025 substitute the variable @var{variable} into output files (typically one
8026 or more @file{Makefile}s). This means that @code{AC_OUTPUT} will
8027 replace instances of @samp{@@@var{variable}@@} in input files with the
8028 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8029 is called. The value can contain newlines.
8030 The substituted value is not rescanned for more output variables;
8031 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8032 literally into the output file. (The algorithm uses the special marker
8033 @code{|#_!!_#|} internally, so the substituted value cannot contain
8036 If @var{value} is given, in addition assign it to @var{variable}.
8038 The string @var{variable} is passed to @code{m4_pattern_allow}
8039 (@pxref{Forbidden Patterns}).
8042 @defmac AC_SUBST_FILE (@var{variable})
8043 @acindex{SUBST_FILE}
8044 Another way to create an output variable from a shell variable. Make
8045 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8046 named by shell variable @var{variable} into output files. This means
8047 that @code{AC_OUTPUT} will replace instances of
8048 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8049 with the contents of the file that the shell variable @var{variable}
8050 names when @code{AC_OUTPUT} is called. Set the variable to
8051 @file{/dev/null} for cases that do not have a file to insert.
8052 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8053 line by itself, optionally surrounded by spaces and tabs. The
8054 substitution replaces the whole line, including the spaces, tabs, and
8055 the terminating newline.
8057 This macro is useful for inserting @file{Makefile} fragments containing
8058 special dependencies or other @code{make} directives for particular host
8059 or target types into @file{Makefile}s. For example, @file{configure.ac}
8063 AC_SUBST_FILE([host_frag])
8064 host_frag=$srcdir/conf/sun4.mh
8068 and then a @file{Makefile.in} could contain:
8074 The string @var{variable} is passed to @code{m4_pattern_allow}
8075 (@pxref{Forbidden Patterns}).
8078 @cindex Previous Variable
8079 @cindex Variable, Precious
8080 Running @command{configure} in varying environments can be extremely
8081 dangerous. If for instance the user runs @samp{CC=bizarre-cc
8082 ./configure}, then the cache, @file{config.h}, and many other output
8083 files will depend upon @command{bizarre-cc} being the C compiler. If
8084 for some reason the user runs @command{./configure} again, or if it is
8085 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8086 and @pxref{config.status Invocation}), then the configuration can be
8087 inconsistent, composed of results depending upon two different
8090 Environment variables that affect this situation, such as @samp{CC}
8091 above, are called @dfn{precious variables}, and can be declared as such
8092 by @code{AC_ARG_VAR}.
8094 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8096 Declare @var{variable} is a precious variable, and include its
8097 @var{description} in the variable section of @samp{./configure --help}.
8099 Being precious means that
8102 @var{variable} is @code{AC_SUBST}'d.
8105 The value of @var{variable} when @command{configure} was launched is
8106 saved in the cache, including if it was not specified on the command
8107 line but via the environment. Indeed, while @command{configure} can
8108 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8109 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8110 which, unfortunately, is what most users do.
8112 We emphasize that it is the @emph{initial} value of @var{variable} which
8113 is saved, not that found during the execution of @command{configure}.
8114 Indeed, specifying @samp{./configure FOO=foo} and letting
8115 @samp{./configure} guess that @code{FOO} is @code{foo} can be two very
8119 @var{variable} is checked for consistency between two
8120 @command{configure} runs. For instance:
8123 $ @kbd{./configure --silent --config-cache}
8124 $ @kbd{CC=cc ./configure --silent --config-cache}
8125 configure: error: `CC' was not set in the previous run
8126 configure: error: changes in the environment can compromise \
8128 configure: error: run `make distclean' and/or \
8129 `rm config.cache' and start over
8133 and similarly if the variable is unset, or if its content is changed.
8137 @var{variable} is kept during automatic reconfiguration
8138 (@pxref{config.status Invocation}) as if it had been passed as a command
8139 line argument, including when no cache is used:
8142 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
8143 $ @kbd{./config.status --recheck}
8144 running /bin/sh ./configure undeclared_var=raboof --silent \
8145 CC=/usr/bin/cc --no-create --no-recursion
8150 @node Special Chars in Variables
8151 @section Special Characters in Output Variables
8152 @cindex Output variables, special characters in
8154 Many output variables are intended to be evaluated both by
8155 @command{make} and by the shell. Some characters are expanded
8156 differently in these two contexts, so to avoid confusion these
8157 variables' values should not contain any of the following characters:
8160 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8163 Also, these variables' values should neither contain newlines, nor start
8164 with @samp{~}, nor contain white space or @samp{:} immediately followed
8165 by @samp{~}. The values can contain nonempty sequences of white space
8166 characters like tabs and spaces, but each such sequence might
8167 arbitrarily be replaced by a single space during substitution.
8169 These restrictions apply both to the values that @command{configure}
8170 computes, and to the values set directly by the user. For example, the
8171 following invocations of @command{configure} are problematic, since they
8172 attempt to use special characters within @code{CPPFLAGS}:
8175 CPPFLAGS='-DOUCH="&\"#$*?"' ./configure
8177 ./configure CPPFLAGS='-DOUCH="&\"#$*?"'
8180 @node Caching Results
8181 @section Caching Results
8184 To avoid checking for the same features repeatedly in various
8185 @command{configure} scripts (or in repeated runs of one script),
8186 @command{configure} can optionally save the results of many checks in a
8187 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
8188 runs with caching enabled and finds a cache file, it reads the results
8189 of previous runs from the cache and avoids rerunning those checks. As a
8190 result, @command{configure} can then run much faster than if it had to
8191 perform all of the checks every time.
8193 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8195 Ensure that the results of the check identified by @var{cache-id} are
8196 available. If the results of the check were in the cache file that was
8197 read, and @command{configure} was not given the @option{--quiet} or
8198 @option{--silent} option, print a message saying that the result was
8199 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
8200 the shell commands are run to determine the value, the value will be
8201 saved in the cache file just before @command{configure} creates its output
8202 files. @xref{Cache Variable Names}, for how to choose the name of the
8203 @var{cache-id} variable.
8205 The @var{commands-to-set-it} @emph{must have no side effects} except for
8206 setting the variable @var{cache-id}, see below.
8209 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
8210 @acindex{CACHE_CHECK}
8211 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8212 messages. This macro provides a convenient shorthand for the most
8213 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
8214 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8215 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8217 The @var{commands-to-set-it} @emph{must have no side effects} except for
8218 setting the variable @var{cache-id}, see below.
8221 It is very common to find buggy macros using @code{AC_CACHE_VAL} or
8222 @code{AC_CACHE_CHECK}, because people are tempted to call
8223 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
8224 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8225 @code{AC_DEFINE}, by examining the value of the cache variable. For
8226 instance, the following macro is broken:
8230 AC_DEFUN([AC_SHELL_TRUE],
8231 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8232 [ac_cv_shell_true_works=no
8233 (true) 2>/dev/null && ac_cv_shell_true_works=yes
8234 if test "$ac_cv_shell_true_works" = yes; then
8235 AC_DEFINE([TRUE_WORKS], [1],
8236 [Define if `true(1)' works properly.])
8243 This fails if the cache is enabled: the second time this macro is run,
8244 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
8249 AC_DEFUN([AC_SHELL_TRUE],
8250 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8251 [ac_cv_shell_true_works=no
8252 (true) 2>/dev/null && ac_cv_shell_true_works=yes])
8253 if test "$ac_cv_shell_true_works" = yes; then
8254 AC_DEFINE([TRUE_WORKS], [1],
8255 [Define if `true(1)' works properly.])
8261 Also, @var{commands-to-set-it} should not print any messages, for
8262 example with @code{AC_MSG_CHECKING}; do that before calling
8263 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8264 the results of the check are retrieved from the cache or determined by
8265 running the shell commands.
8268 * Cache Variable Names:: Shell variables used in caches
8269 * Cache Files:: Files @command{configure} uses for caching
8270 * Cache Checkpointing:: Loading and saving the cache file
8273 @node Cache Variable Names
8274 @subsection Cache Variable Names
8275 @cindex Cache variable
8277 The names of cache variables should have the following format:
8280 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8284 for example, @samp{ac_cv_header_stat_broken} or
8285 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
8288 @item @var{package-prefix}
8289 An abbreviation for your package or organization; the same prefix you
8290 begin local Autoconf macros with, except lowercase by convention.
8291 For cache values used by the distributed Autoconf macros, this value is
8295 Indicates that this shell variable is a cache value. This string
8296 @emph{must} be present in the variable name, including the leading
8299 @item @var{value-type}
8300 A convention for classifying cache values, to produce a rational naming
8301 system. The values used in Autoconf are listed in @ref{Macro Names}.
8303 @item @var{specific-value}
8304 Which member of the class of cache values this test applies to.
8305 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8306 output variable (@samp{INSTALL}).
8308 @item @var{additional-options}
8309 Any particular behavior of the specific member that this test applies to.
8310 For example, @samp{broken} or @samp{set}. This part of the name may
8311 be omitted if it does not apply.
8314 The values assigned to cache variables may not contain newlines.
8315 Usually, their values will be Boolean (@samp{yes} or @samp{no}) or the
8316 names of files or functions; so this is not an important restriction.
8319 @subsection Cache Files
8321 A cache file is a shell script that caches the results of configure
8322 tests run on one system so they can be shared between configure scripts
8323 and configure runs. It is not useful on other systems. If its contents
8324 are invalid for some reason, the user may delete or edit it.
8326 By default, @command{configure} uses no cache file,
8327 to avoid problems caused by accidental
8328 use of stale cache files.
8330 To enable caching, @command{configure} accepts @option{--config-cache} (or
8331 @option{-C}) to cache results in the file @file{config.cache}.
8332 Alternatively, @option{--cache-file=@var{file}} specifies that
8333 @var{file} be the cache file. The cache file is created if it does not
8334 exist already. When @command{configure} calls @command{configure} scripts in
8335 subdirectories, it uses the @option{--cache-file} argument so that they
8336 share the same cache. @xref{Subdirectories}, for information on
8337 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8339 @file{config.status} only pays attention to the cache file if it is
8340 given the @option{--recheck} option, which makes it rerun
8341 @command{configure}.
8343 It is wrong to try to distribute cache files for particular system types.
8344 There is too much room for error in doing that, and too much
8345 administrative overhead in maintaining them. For any features that
8346 can't be guessed automatically, use the standard method of the canonical
8347 system type and linking files (@pxref{Manual Configuration}).
8349 The site initialization script can specify a site-wide cache file to
8350 use, instead of the usual per-program cache. In this case, the cache
8351 file will gradually accumulate information whenever someone runs a new
8352 @command{configure} script. (Running @command{configure} merges the new cache
8353 results with the existing cache file.) This may cause problems,
8354 however, if the system configuration (e.g., the installed libraries or
8355 compilers) changes and the stale cache file is not deleted.
8357 @node Cache Checkpointing
8358 @subsection Cache Checkpointing
8360 If your configure script, or a macro called from @file{configure.ac}, happens
8361 to abort the configure process, it may be useful to checkpoint the cache
8362 a few times at key points using @code{AC_CACHE_SAVE}. Doing so will
8363 reduce the amount of time it takes to re-run the configure script with
8364 (hopefully) the error that caused the previous abort corrected.
8366 @c FIXME: Do we really want to document this guy?
8367 @defmac AC_CACHE_LOAD
8368 @acindex{CACHE_LOAD}
8369 Loads values from existing cache file, or creates a new cache file if a
8370 cache file is not found. Called automatically from @code{AC_INIT}.
8373 @defmac AC_CACHE_SAVE
8374 @acindex{CACHE_SAVE}
8375 Flushes all cached values to the cache file. Called automatically from
8376 @code{AC_OUTPUT}, but it can be quite useful to call
8377 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8383 @r{ @dots{} AC_INIT, etc. @dots{}}
8385 # Checks for programs.
8387 AC_PROG_GCC_TRADITIONAL
8388 @r{ @dots{} more program checks @dots{}}
8393 # Checks for libraries.
8394 AC_CHECK_LIB([nsl], [gethostbyname])
8395 AC_CHECK_LIB([socket], [connect])
8396 @r{ @dots{} more lib checks @dots{}}
8401 # Might abort@dots{}
8402 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8403 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8405 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8408 @node Printing Messages
8409 @section Printing Messages
8410 @cindex Messages, from @command{configure}
8412 @command{configure} scripts need to give users running them several kinds
8413 of information. The following macros print messages in ways appropriate
8414 for each kind. The arguments to all of them get enclosed in shell
8415 double quotes, so the shell performs variable and back-quote
8416 substitution on them.
8418 These macros are all wrappers around the @command{echo} shell command,
8419 and will direct output to the appropriate file descriptor (@pxref{File
8420 Descriptor Macros}).
8421 @command{configure} scripts should rarely need to run @command{echo} directly
8422 to print messages for the user. Using these macros makes it easy to
8423 change how and when each kind of message is printed; such changes need
8424 only be made to the macro definitions and all the callers will change
8427 To diagnose static issues, i.e., when @command{autoconf} is run, see
8428 @ref{Reporting Messages}.
8430 @defmac AC_MSG_CHECKING (@var{feature-description})
8431 @acindex{MSG_CHECKING}
8432 Notify the user that @command{configure} is checking for a particular
8433 feature. This macro prints a message that starts with @samp{checking }
8434 and ends with @samp{...} and no newline. It must be followed by a call
8435 to @code{AC_MSG_RESULT} to print the result of the check and the
8436 newline. The @var{feature-description} should be something like
8437 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
8440 This macro prints nothing if @command{configure} is run with the
8441 @option{--quiet} or @option{--silent} option.
8444 @defmac AC_MSG_RESULT (@var{result-description})
8445 @acindex{MSG_RESULT}
8446 Notify the user of the results of a check. @var{result-description} is
8447 almost always the value of the cache variable for the check, typically
8448 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
8449 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
8450 the completion of the message printed by the call to
8451 @code{AC_MSG_CHECKING}.
8453 This macro prints nothing if @command{configure} is run with the
8454 @option{--quiet} or @option{--silent} option.
8457 @defmac AC_MSG_NOTICE (@var{message})
8458 @acindex{MSG_NOTICE}
8459 Deliver the @var{message} to the user. It is useful mainly to print a
8460 general description of the overall purpose of a group of feature checks,
8464 AC_MSG_NOTICE([checking if stack overflow is detectable])
8467 This macro prints nothing if @command{configure} is run with the
8468 @option{--quiet} or @option{--silent} option.
8471 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
8473 Notify the user of an error that prevents @command{configure} from
8474 completing. This macro prints an error message to the standard error
8475 output and exits @command{configure} with @var{exit-status} (1 by default).
8476 @var{error-description} should be something like @samp{invalid value
8479 The @var{error-description} should start with a lower-case letter, and
8480 ``cannot'' is preferred to ``can't''.
8483 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
8484 @acindex{MSG_FAILURE}
8485 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
8486 prevents @command{configure} from completing @emph{and} that additional
8487 details are provided in @file{config.log}. This is typically used when
8488 abnormal results are found during a compilation.
8491 @defmac AC_MSG_WARN (@var{problem-description})
8493 Notify the @command{configure} user of a possible problem. This macro
8494 prints the message to the standard error output; @command{configure}
8495 continues running afterward, so macros that call @code{AC_MSG_WARN} should
8496 provide a default (back-up) behavior for the situations they warn about.
8497 @var{problem-description} should be something like @samp{ln -s seems to
8503 @c ====================================================== Programming in M4.
8505 @node Programming in M4
8506 @chapter Programming in M4
8509 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
8510 convenient macros for pure M4 programming, and @dfn{M4sh}, which
8511 provides macros dedicated to shell script generation.
8513 As of this version of Autoconf, these two layers are still experimental,
8514 and their interface might change in the future. As a matter of fact,
8515 @emph{anything that is not documented must not be used}.
8518 * M4 Quotation:: Protecting macros from unwanted expansion
8519 * Using autom4te:: The Autoconf executables backbone
8520 * Programming in M4sugar:: Convenient pure M4 macros
8521 * Programming in M4sh:: Common shell Constructs
8522 * File Descriptor Macros:: File descriptor macros for input and output
8526 @section M4 Quotation
8527 @cindex M4 quotation
8530 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
8531 @c prevented `expansion' of $1. Unless it refers to the expansion
8532 @c of the value of $1? Anyway, we need a rewrite here@enddots{}
8534 The most common problem with existing macros is an improper quotation.
8535 This section, which users of Autoconf can skip, but which macro writers
8536 @emph{must} read, first justifies the quotation scheme that was chosen
8537 for Autoconf and then ends with a rule of thumb. Understanding the
8538 former helps one to follow the latter.
8541 * Active Characters:: Characters that change the behavior of M4
8542 * One Macro Call:: Quotation and one macro call
8543 * Quotation and Nested Macros:: Macros calling macros
8544 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
8545 * Quadrigraphs:: Another way to escape special characters
8546 * Quotation Rule Of Thumb:: One parenthesis, one quote
8549 @node Active Characters
8550 @subsection Active Characters
8552 To fully understand where proper quotation is important, you first need
8553 to know what the special characters are in Autoconf: @samp{#} introduces
8554 a comment inside which no macro expansion is performed, @samp{,}
8555 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
8556 and finally @samp{(} and @samp{)} (which M4 tries to match by
8559 In order to understand the delicate case of macro calls, we first have
8560 to present some obvious failures. Below they are ``obvious-ified'',
8561 but when you find them in real life, they are usually in disguise.
8563 Comments, introduced by a hash and running up to the newline, are opaque
8564 tokens to the top level: active characters are turned off, and there is
8568 # define([def], ine)
8569 @result{}# define([def], ine)
8572 Each time there can be a macro expansion, there is a quotation
8573 expansion, i.e., one level of quotes is stripped:
8579 @result{}int tab[10];
8582 Without this in mind, the reader will try hopelessly to use her macro
8586 define([array], [int tab[10];])
8594 How can you correctly output the intended results@footnote{Using
8598 @node One Macro Call
8599 @subsection One Macro Call
8601 Let's proceed on the interaction between active characters and macros
8602 with this small macro, which just returns its first argument:
8609 The two pairs of quotes above are not part of the arguments of
8610 @code{define}; rather, they are understood by the top level when it
8611 tries to find the arguments of @code{define}. Therefore, assuming
8612 @code{car} is not already defined, it is equivalent to write:
8619 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
8620 quotes, it is bad practice for Autoconf macros which must both be more
8621 robust and also advocate perfect style.
8623 At the top level, there are only two possibilities: either you
8629 [car(foo, bar, baz)]
8630 @result{}car(foo, bar, baz)
8633 Let's pay attention to the special characters:
8637 @error{}EOF in argument list
8640 The closing parenthesis is hidden in the comment; with a hypothetical
8641 quoting, the top level understood it this way:
8648 Proper quotation, of course, fixes the problem:
8655 Here are more examples:
8678 With this in mind, we can explore the cases where macros invoke
8682 @node Quotation and Nested Macros
8683 @subsection Quotation and Nested Macros
8685 The examples below use the following macros:
8689 define([active], [ACT, IVE])
8690 define([array], [int tab[10]])
8693 Each additional embedded macro call introduces other possible
8694 interesting quotations:
8705 In the first case, the top level looks for the arguments of @code{car},
8706 and finds @samp{active}. Because M4 evaluates its arguments
8707 before applying the macro, @samp{active} is expanded, which results in:
8715 In the second case, the top level gives @samp{active} as first and only
8716 argument of @code{car}, which results in:
8724 i.e., the argument is evaluated @emph{after} the macro that invokes it.
8725 In the third case, @code{car} receives @samp{[active]}, which results in:
8733 exactly as we already saw above.
8735 The example above, applied to a more realistic example, gives:
8742 car([[int tab[10];]])
8743 @result{}int tab[10];
8747 Huh? The first case is easily understood, but why is the second wrong,
8748 and the third right? To understand that, you must know that after
8749 M4 expands a macro, the resulting text is immediately subjected
8750 to macro expansion and quote removal. This means that the quote removal
8751 occurs twice---first before the argument is passed to the @code{car}
8752 macro, and second after the @code{car} macro expands to the first
8755 As the author of the Autoconf macro @code{car}, you then consider it to
8756 be incorrect that your users have to double-quote the arguments of
8757 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
8761 define([qar], [[$1]])
8765 and check that @code{qar} is properly fixed:
8769 @result{}int tab[10];
8773 Ahhh! That's much better.
8775 But note what you've done: now that the arguments are literal strings,
8776 if the user wants to use the results of expansions as arguments, she has
8777 to use an @emph{unquoted} macro call:
8785 where she wanted to reproduce what she used to do with @code{car}:
8793 Worse yet: she wants to use a macro that produces a set of @code{cpp}
8797 define([my_includes], [#include <stdio.h>])
8799 @result{}#include <stdio.h>
8801 @error{}EOF in argument list
8804 This macro, @code{qar}, because it double quotes its arguments, forces
8805 its users to leave their macro calls unquoted, which is dangerous.
8806 Commas and other active symbols are interpreted by M4 before
8807 they are given to the macro, often not in the way the users expect.
8808 Also, because @code{qar} behaves differently from the other macros,
8809 it's an exception that should be avoided in Autoconf.
8811 @node Changequote is Evil
8812 @subsection @code{changequote} is Evil
8813 @cindex @code{changequote}
8815 The temptation is often high to bypass proper quotation, in particular
8816 when it's late at night. Then, many experienced Autoconf hackers
8817 finally surrender to the dark side of the force and use the ultimate
8818 weapon: @code{changequote}.
8820 The M4 builtin @code{changequote} belongs to a set of primitives that
8821 allow one to adjust the syntax of the language to adjust it to one's
8822 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
8823 quotes, but in the context of shell programming (and actually of most
8824 programming languages), that's about the worst choice one can make:
8825 because of strings and back-quoted expressions in shell code (such as
8826 @samp{'this'} and @samp{`that`}), because of literal characters in usual
8827 programming languages (as in @samp{'0'}), there are many unbalanced
8828 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
8829 not impossible. In order to make M4 useful in such a context, its
8830 designers have equipped it with @code{changequote}, which makes it
8831 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
8832 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
8833 because they are unlikely characters, but @emph{because they are
8834 characters unlikely to be unbalanced}.
8836 There are other magic primitives, such as @code{changecom} to specify
8837 what syntactic forms are comments (it is common to see
8838 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
8839 @code{changeword} and @code{changesyntax} to change other syntactic
8840 details (such as the character to denote the @var{n}th argument, @samp{$} by
8841 default, the parenthesis around arguments, etc.).
8843 These primitives are really meant to make M4 more useful for specific
8844 domains: they should be considered like command line options:
8845 @option{--quotes}, @option{--comments}, @option{--words}, and
8846 @option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
8847 it makes M4 libraries self contained (no need for additional options).
8849 There lies the problem@enddots{}
8853 The problem is that it is then tempting to use them in the middle of an
8854 M4 script, as opposed to its initialization. This, if not carefully
8855 thought out, can lead to disastrous effects: @emph{you are changing the
8856 language in the middle of the execution}. Changing and restoring the
8857 syntax is often not enough: if you happened to invoke macros in between,
8858 these macros will be lost, as the current syntax will probably not be
8859 the one they were implemented with.
8861 @c FIXME: I've been looking for a short, real case example, but I
8866 @subsection Quadrigraphs
8867 @cindex quadrigraphs
8868 @cindex @samp{@@S|@@}
8869 @cindex @samp{@@&t@@}
8870 @c Info cannot handle `:' in index entries.
8871 @c @cindex @samp{@@<:@@}
8872 @c @cindex @samp{@@:>@@}
8873 @c @cindex @samp{@@%:@@}
8875 When writing an Autoconf macro you may occasionally need to generate
8876 special characters that are difficult to express with the standard
8877 Autoconf quoting rules. For example, you may need to output the regular
8878 expression @samp{[^[]}, which matches any character other than @samp{[}.
8879 This expression contains unbalanced brackets so it cannot be put easily
8882 You can work around this problem by using one of the following
8898 Quadrigraphs are replaced at a late stage of the translation process,
8899 after @command{m4} is run, so they do not get in the way of M4 quoting.
8900 For example, the string @samp{^@@<:@@}, independently of its quotation,
8901 will appear as @samp{^[} in the output.
8903 The empty quadrigraph can be used:
8906 @item to mark trailing spaces explicitly
8908 Trailing spaces are smashed by @command{autom4te}. This is a feature.
8910 @item to produce other quadrigraphs
8912 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
8914 @item to escape @emph{occurrences} of forbidden patterns
8916 For instance you might want to mention @code{AC_FOO} in a comment, while
8917 still being sure that @command{autom4te} will still catch unexpanded
8918 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
8921 The name @samp{@@&t@@} was suggested by Paul Eggert:
8924 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
8925 own invention, but the @samp{t} came from the source code of the
8926 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
8927 and which used @samp{mt} to denote the empty string. In C, it would
8928 have looked like something like:
8931 char const mt[] = "";
8935 but of course the source code was written in Algol 68.
8937 I don't know where he got @samp{mt} from: it could have been his own
8938 invention, and I suppose it could have been a common pun around the
8939 Cambridge University computer lab at the time.
8942 @node Quotation Rule Of Thumb
8943 @subsection Quotation Rule Of Thumb
8945 To conclude, the quotation rule of thumb is:
8947 @center @emph{One pair of quotes per pair of parentheses.}
8949 Never over-quote, never under-quote, in particular in the definition of
8950 macros. In the few places where the macros need to use brackets
8951 (usually in C program text or regular expressions), properly quote
8952 @emph{the arguments}!
8954 It is common to read Autoconf programs with snippets like:
8958 changequote(<<, >>)dnl
8960 #ifndef tzname /* For SGI. */
8961 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
8963 changequote([, ])dnl
8964 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
8968 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
8969 double quoting, so you just need:
8974 #ifndef tzname /* For SGI. */
8975 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
8978 [ac_cv_var_tzname=yes],
8979 [ac_cv_var_tzname=no])
8983 The M4-fluent reader will note that these two examples are rigorously
8984 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
8985 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
8986 quotes are not part of the arguments!
8988 Simplified, the example above is just doing this:
8991 changequote(<<, >>)dnl
8993 changequote([, ])dnl
9003 With macros that do not double quote their arguments (which is the
9004 rule), double-quote the (risky) literals:
9007 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9009 #ifndef tzname /* For SGI. */
9010 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9012 [atoi (*tzname);])],
9013 [ac_cv_var_tzname=yes],
9014 [ac_cv_var_tzname=no])
9017 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9018 should be using @code{AC_LINK_IFELSE} instead.
9020 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9021 where quoting does not suffice.
9023 When you create a @command{configure} script using newly written macros,
9024 examine it carefully to check whether you need to add more quotes in
9025 your macros. If one or more words have disappeared in the M4
9026 output, you need more quotes. When in doubt, quote.
9028 However, it's also possible to put on too many layers of quotes. If
9029 this happens, the resulting @command{configure} script may contain
9030 unexpanded macros. The @command{autoconf} program checks for this problem
9031 by looking for the string @samp{AC_} in @file{configure}. However, this
9032 heuristic does not work in general: for example, it does not catch
9033 overquoting in @code{AC_DEFINE} descriptions.
9036 @c ---------------------------------------- Using autom4te
9038 @node Using autom4te
9039 @section Using @command{autom4te}
9041 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9042 to Autoconf per se, heavily rely on M4. All these different uses
9043 revealed common needs factored into a layer over @command{m4}:
9044 @command{autom4te}@footnote{
9046 Yet another great name from Lars J. Aas.
9050 @command{autom4te} is a preprocessor that is like @command{m4}.
9051 It supports M4 extensions designed for use in tools like Autoconf.
9054 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
9055 * Customizing autom4te:: Customizing the Autoconf package
9058 @node autom4te Invocation
9059 @subsection Invoking @command{autom4te}
9061 The command line arguments are modeled after M4's:
9064 autom4te @var{options} @var{files}
9068 where the @var{files} are directly passed to @command{m4}. In addition
9069 to the regular expansion, it handles the replacement of the quadrigraphs
9070 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9071 output. It supports an extended syntax for the @var{files}:
9074 @item @var{file}.m4f
9075 This file is an M4 frozen file. Note that @emph{all the previous files
9076 are ignored}. See the option @option{--melt} for the rationale.
9079 If found in the library path, the @var{file} is included for expansion,
9080 otherwise it is ignored instead of triggering a failure.
9085 Of course, it supports the Autoconf common subset of options:
9090 Print a summary of the command line options and exit.
9094 Print the version number of Autoconf and exit.
9098 Report processing steps.
9102 Don't remove the temporary files and be even more verbose.
9104 @item --include=@var{dir}
9106 Also look for input files in @var{dir}. Multiple invocations
9109 @item --output=@var{file}
9110 @itemx -o @var{file}
9111 Save output (script or trace) to @var{file}. The file @option{-} stands
9112 for the standard output.
9117 As an extension of @command{m4}, it includes the following options:
9120 @item --warnings=@var{category}
9121 @itemx -W @var{category}
9123 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9124 Report the warnings related to @var{category} (which can actually be a
9125 comma separated list). @xref{Reporting Messages}, macro
9126 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
9131 report all the warnings
9137 treats warnings as errors
9139 @item no-@var{category}
9140 disable warnings falling into @var{category}
9143 Warnings about @samp{syntax} are enabled by default, and the environment
9144 variable @env{WARNINGS}, a comma separated list of categories, is
9145 honored. @command{autom4te -W @var{category}} will actually
9146 behave as if you had run:
9149 autom4te --warnings=syntax,$WARNINGS,@var{category}
9153 For example, if you want to disable @command{autom4te}'s defaults and
9154 @env{WARNINGS}, but enable the warnings about obsolete
9155 constructs, you would use @option{-W none,obsolete}.
9158 @cindex Macro invocation stack
9159 @command{autom4te} displays a back trace for errors, but not for
9160 warnings; if you want them, just pass @option{-W error}.
9164 Do not use frozen files. Any argument @code{@var{file}.m4f} will be
9165 replaced with @code{@var{file}.m4}. This helps tracing the macros which
9166 are executed only when the files are frozen, typically
9167 @code{m4_define}. For instance, running:
9170 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9174 is roughly equivalent to running:
9177 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9184 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9191 m4 --reload-state=4.m4f input.m4
9196 Produce a frozen state file. @command{autom4te} freezing is stricter
9197 than M4's: it must produce no warnings, and no output other than empty
9198 lines (a line with white space is @emph{not} empty) and comments
9199 (starting with @samp{#}). Please, note that contrary to @command{m4},
9200 this options takes no argument:
9203 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9210 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9213 @item --mode=@var{octal-mode}
9214 @itemx -m @var{octal-mode}
9215 Set the mode of the non-traces output to @var{octal-mode}; by default
9221 @cindex @file{autom4te.cache}
9222 As another additional feature over @command{m4}, @command{autom4te}
9223 caches its results. @acronym{GNU} M4 is able to produce a regular
9224 output and traces at the same time. Traces are heavily used in the
9225 @acronym{GNU} Build System: @command{autoheader} uses them to build
9226 @file{config.h.in}, @command{autoreconf} to determine what
9227 @acronym{GNU} Build System components are used, @command{automake} to
9228 ``parse'' @file{configure.ac} etc. To save the long runs of
9229 @command{m4}, traces are cached while performing regular expansion,
9230 and conversely. This cache is (actually, the caches are) stored in
9231 the directory @file{autom4te.cache}. @emph{It can safely be removed}
9232 at any moment (especially if for some reason @command{autom4te}
9233 considers it is trashed).
9236 @item --cache=@var{directory}
9237 @itemx -C @var{directory}
9238 Specify the name of the directory where the result should be cached.
9239 Passing an empty value disables caching. Be sure to pass a relative
9240 file name, as for the time being, global caches are not supported.
9243 Don't cache the results.
9247 If a cache is used, consider it obsolete (but update it anyway).
9252 Because traces are so important to the @acronym{GNU} Build System,
9253 @command{autom4te} provides high level tracing features as compared to
9254 M4, and helps exploiting the cache:
9257 @item --trace=@var{macro}[:@var{format}]
9258 @itemx -t @var{macro}[:@var{format}]
9259 Trace the invocations of @var{macro} according to the @var{format}.
9260 Multiple @option{--trace} arguments can be used to list several macros.
9261 Multiple @option{--trace} arguments for a single macro are not
9262 cumulative; instead, you should just make @var{format} as long as
9265 The @var{format} is a regular string, with newlines if desired, and
9266 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
9267 use the following special escapes:
9271 The character @samp{$}.
9274 The file name from which @var{macro} is called.
9277 The line number from which @var{macro} is called.
9280 The depth of the @var{macro} call. This is an M4 technical detail that
9281 you probably don't want to know about.
9284 The name of the @var{macro}.
9287 The @var{num}th argument of the call to @var{macro}.
9291 @itemx $@{@var{separator}@}@@
9292 All the arguments passed to @var{macro}, separated by the character
9293 @var{sep} or the string @var{separator} (@samp{,} by default). Each
9294 argument is quoted, i.e., enclosed in a pair of square brackets.
9298 @itemx $@{@var{separator}@}*
9299 As above, but the arguments are not quoted.
9303 @itemx $@{@var{separator}@}%
9304 As above, but the arguments are not quoted, all new line characters in
9305 the arguments are smashed, and the default separator is @samp{:}.
9307 The escape @samp{$%} produces single-line trace outputs (unless you put
9308 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9312 @xref{autoconf Invocation}, for examples of trace uses.
9314 @item --preselect=@var{macro}
9315 @itemx -p @var{macro}
9316 Cache the traces of @var{macro}, but do not enable traces. This is
9317 especially important to save CPU cycles in the future. For instance,
9318 when invoked, @command{autoconf} preselects all the macros that
9319 @command{autoheader}, @command{automake}, @command{autoreconf} etc.@: will
9320 trace, so that running @command{m4} is not needed to trace them: the
9321 cache suffices. This results in a huge speed-up.
9326 @cindex Autom4te Library
9327 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9328 libraries}. They consists in a powerful yet extremely simple feature:
9329 sets of combined command line arguments:
9332 @item --language=@var{language}
9333 @itemx -l @var{language}
9334 Use the @var{language} Autom4te library. Current languages include:
9338 create M4sugar output.
9341 create M4sh executable shell scripts.
9344 create Autotest executable test suites.
9346 @item Autoconf-without-aclocal-m4
9347 create Autoconf executable configure scripts without
9348 reading @file{aclocal.m4}.
9351 create Autoconf executable configure scripts. This language inherits
9352 all the characteristics of @code{Autoconf-without-aclocal-m4} and will
9353 additionally read @file{aclocal.m4}.
9356 @item --prepend-include=@var{dir}
9358 Prepend directory @var{dir} to the search path. This is used to include
9359 the language-specific files before any third-party macros.
9363 @cindex @file{autom4te.cfg}
9364 As an example, if Autoconf is installed in its default location,
9365 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
9366 strictly equivalent to the command:
9369 autom4te --prepend-include /usr/local/share/autoconf \
9370 m4sugar/m4sugar.m4f --warnings syntax foo.m4
9374 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
9375 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
9379 autom4te --prepend-include /usr/local/share/autoconf \
9380 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
9384 The definition of the languages is stored in @file{autom4te.cfg}.
9386 @node Customizing autom4te
9387 @subsection Customizing @command{autom4te}
9389 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
9390 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
9391 as found in the directory from which @command{autom4te} is run). The
9392 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
9393 then @file{./.autom4te.cfg}, and finally the command line arguments.
9395 In these text files, comments are introduced with @code{#}, and empty
9396 lines are ignored. Customization is performed on a per-language basis,
9397 wrapped in between a @samp{begin-language: "@var{language}"},
9398 @samp{end-language: "@var{language}"} pair.
9400 Customizing a language stands for appending options (@pxref{autom4te
9401 Invocation}) to the current definition of the language. Options, and
9402 more generally arguments, are introduced by @samp{args:
9403 @var{arguments}}. You may use the traditional shell syntax to quote the
9406 As an example, to disable Autoconf caches (@file{autom4te.cache})
9407 globally, include the following lines in @file{~/.autom4te.cfg}:
9410 ## ------------------ ##
9411 ## User Preferences. ##
9412 ## ------------------ ##
9414 begin-language: "Autoconf-without-aclocal-m4"
9416 end-language: "Autoconf-without-aclocal-m4"
9420 @node Programming in M4sugar
9421 @section Programming in M4sugar
9424 M4 by itself provides only a small, but sufficient, set of all-purpose
9425 macros. M4sugar introduces additional generic macros. Its name was
9426 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
9430 * Redefined M4 Macros:: M4 builtins changed in M4sugar
9431 * Looping constructs:: Iteration in M4
9432 * Evaluation Macros:: More quotation and evaluation control
9433 * Text processing Macros:: String manipulation in M4
9434 * Forbidden Patterns:: Catching unexpanded macros
9437 @node Redefined M4 Macros
9438 @subsection Redefined M4 Macros
9461 With a few exceptions, all the M4 native macros are moved in the
9462 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
9463 @code{m4_define} etc.
9465 Some M4 macros are redefined, and are slightly incompatible with their
9470 This macro kept its original name: no @code{m4_dnl} is defined.
9473 @defmac m4_defn (@var{macro})
9475 Contrary to the M4 builtin, this macro fails if @var{macro} is not
9476 defined. See @code{m4_undefine}.
9479 @defmac m4_exit (@var{exit-status})
9481 This macro corresponds to @code{m4exit}.
9484 @defmac m4_if (@var{comment})
9485 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
9486 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
9488 This macro corresponds to @code{ifelse}.
9491 @defmac m4_include (@var{file})
9492 @defmacx m4_sinclude (@var{file})
9495 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
9498 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
9500 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
9501 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9502 provide extended regular expression syntax via @code{epatsubst}.
9505 @defmac m4_popdef (@var{macro})
9507 Contrary to the M4 builtin, this macro fails if @var{macro} is not
9508 defined. See @code{m4_undefine}.
9511 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
9513 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
9514 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9515 provide extended regular expression syntax via @code{eregexp}.
9518 @defmac m4_wrap (@var{text})
9520 This macro corresponds to @code{m4wrap}.
9522 You are encouraged to end @var{text} with @samp{[]}, so that there are
9523 no risks that two consecutive invocations of @code{m4_wrap} result in an
9524 unexpected pasting of tokens, as in
9527 m4_define([foo], [Foo])
9528 m4_define([bar], [Bar])
9529 m4_define([foobar], [FOOBAR])
9536 @defmac m4_undefine (@var{macro})
9538 Contrary to the M4 builtin, this macro fails if @var{macro} is not
9542 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
9546 to recover the behavior of the builtin.
9551 @node Looping constructs
9552 @subsection Looping constructs
9554 The following macros implement loops in M4.
9556 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression})
9558 Loop over the numeric values between @var{first} and @var{last}
9559 including bounds by increments of @var{step}. For each iteration,
9560 expand @var{expression} with the numeric value assigned to @var{var}.
9561 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
9562 on the order of the limits. If given, @var{step} has to match this
9566 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
9568 Loop over the comma-separated m4 list @var{list}, assigning each value
9569 to @var{var}, and expand @var{expression}. The following example will
9573 m4_foreach([myvar], [[foo], [bar, baz]],
9580 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
9582 Loop over the whitespace-separated list @var{list}, assigning each value
9583 to @var{var}, and expand @var{expression}.
9585 The deprecated macro @code{AC_FOREACH} is an alias of
9586 @code{m4_foreach_w}.
9591 @node Evaluation Macros
9592 @subsection Evaluation Macros
9594 The following macros give some control over the order of the evaluation
9595 by adding or removing levels of quotes. They are meant for hard-core M4
9598 @defmac m4_dquote (@var{arg1}, @dots{})
9600 Return the arguments as a quoted list of quoted arguments.
9603 @defmac m4_quote (@var{arg1}, @dots{})
9605 Return the arguments as a single entity, i.e., wrap them into a pair of
9609 The following example aims at emphasizing the difference between (i), not
9610 using these macros, (ii), using @code{m4_quote}, and (iii), using
9614 $ @kbd{cat example.m4}
9615 # Overquote, so that quotes are visible.
9616 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
9619 show(m4_quote(a, b))
9620 show(m4_dquote(a, b))
9621 $ @kbd{autom4te -l m4sugar example.m4}
9622 $1 = a, $@@ = [a],[b]
9623 $1 = a,b, $@@ = [a,b]
9624 $1 = [a],[b], $@@ = [[a],[b]]
9629 @node Text processing Macros
9630 @subsection Text processing Macros
9632 The following macros may be used to manipulate strings in M4.
9633 They are not intended for casual use.
9635 @defmac m4_re_escape (@var{string})
9637 Backslash-escape all characters in @var{string} that are active in
9641 @defmac m4_tolower (@var{string})
9642 @defmacx m4_toupper (@var{string})
9645 Return @var{string} with letters converted to upper or lower case,
9649 @defmac m4_split (@var{string}, @ovar{regexp})
9651 Split @var{string} into an M4 list of elements quoted by @samp{[} and
9652 @samp{]}, while keeping white space at the beginning and at the end.
9653 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
9654 If @var{string} is empty, the result is an empty list.
9657 @defmac m4_normalize (@var{string})
9659 Remove leading and trailing spaces and tabs, sequences of
9660 backslash-then-newline, and replace multiple spaces and tabs with a
9664 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
9665 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
9667 @msindex{append_uniq}
9668 Redefine @var{macro-name} to its former contents with @var{separator}
9669 and @var{string} added at the end. If @var{macro-name} was undefined
9670 before (but not if it was defined but empty), then no @var{separator} is
9671 added. @code{m4_append} can be used to grow strings, and
9672 @code{m4_append_uniq} to grow strings without duplicating substrings.
9677 @node Forbidden Patterns
9678 @subsection Forbidden Patterns
9679 @cindex Forbidden patterns
9680 @cindex Patterns, forbidden
9682 M4sugar provides a means to define suspicious patterns, patterns
9683 describing tokens which should not be found in the output. For
9684 instance, if an Autoconf @file{configure} script includes tokens such as
9685 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
9686 wrong (typically a macro was not evaluated because of overquotation).
9688 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
9690 @defmac m4_pattern_forbid (@var{pattern})
9691 @msindex{pattern_forbid}
9692 Declare that no token matching @var{pattern} must be found in the output.
9693 Comments are not checked; this can be a problem if, for instance, you
9694 have some macro left unexpanded after an @samp{#include}. No consensus
9695 is currently found in the Autoconf community, as some people consider it
9696 should be valid to name macros in comments (which doesn't make sense to
9697 the author of this documentation, as @samp{#}-comments should document
9698 the output, not the input, documented by @samp{dnl} comments).
9701 Of course, you might encounter exceptions to these generic rules, for
9702 instance you might have to refer to @samp{$m4_flags}.
9704 @defmac m4_pattern_allow (@var{pattern})
9705 @msindex{pattern_allow}
9706 Any token matching @var{pattern} is allowed, including if it matches an
9707 @code{m4_pattern_forbid} pattern.
9710 @node Programming in M4sh
9711 @section Programming in M4sh
9713 @c FIXME: Eventually will become a chapter, as it is not related to
9714 @c programming in M4 per se.
9716 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
9717 scripts. This name was coined by Lars J. Aas, who notes that,
9718 according to the Webster's Revised Unabridged Dictionary (1913):
9721 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
9722 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
9726 A mass of mixed ingredients reduced to a soft pulpy state by beating or
9730 A mixture of meal or bran and water fed to animals.
9733 A mess; trouble. [Obs.] --Beau.@: & Fl.
9738 For the time being, it is not mature enough to be widely used.
9740 M4sh provides portable alternatives for some common shell constructs
9741 that unfortunately are not portable in practice.
9743 @c Deprecated, to be replaced by a better API
9745 @defmac AS_BASENAME (@var{file-name})
9747 Output the non-directory portion of @var{file-name}. For example,
9748 if @code{$file} is @samp{/one/two/three}, the command
9749 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
9753 @defmac AS_BOURNE_COMPATIBLE
9754 @asindex{BOURNE_COMPATIBLE}
9755 Set up the shell to be more compatible with the Bourne shell as
9756 standardized by Posix, if possible. This may involve setting
9757 environment variables, or setting options, or similar
9758 implementation-specific actions.
9761 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default})
9763 Expand into a shell @samp{case} statement, where @var{word} is matched
9764 against one or more patterns. @var{if-matched} is run if the
9765 corresponding pattern matched @var{word}, else @var{default} is run.
9768 @defmac AS_DIRNAME (@var{file-name})
9770 Output the directory portion of @var{file-name}. For example,
9771 if @code{$file} is @samp{/one/two/three}, the command
9772 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
9775 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
9777 Run shell code @var{test1}. If @var{test1} exits with a zero status then
9778 run shell code @var{run-if-true1}, else examine further tests. If no test
9779 exits with a zero status, run shell code @var{run-if-false}, with
9780 simplifications if either @var{run-if-true1} or @var{run-if-false1}
9781 is empty. For example,
9784 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
9785 [test "$foo" != no], [HANDLE_FOO([maybe])],
9786 [echo foo not specified])
9790 will make sure any @code{AC_REQUIRE}'s macros of @code{HANDLE_FOO} will
9791 be expanded before the first test.
9794 @defmac AS_MKDIR_P (@var{file-name})
9796 Make the directory @var{file-name}, including intervening directories
9797 as necessary. This is equivalent to @samp{mkdir -p @var{file-name}},
9798 except that it is portable to older versions of @command{mkdir} that
9799 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
9800 succeeds if @var{file-name} is a symbolic link to an existing directory,
9801 even though Posix is unclear whether @samp{mkdir -p} should
9802 succeed in that case. If creation of @var{file-name} fails, exit the
9805 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
9808 @defmac AS_SHELL_SANITIZE
9809 @asindex{SHELL_SANITIZE}
9810 Initialize the shell suitably for @code{configure} scripts. This has
9811 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
9812 environment variables for predictable results from configuration tests.
9813 For example, it sets @env{LC_ALL} to change to the default C locale.
9814 @xref{Special Shell Variables}.
9817 @defmac AS_TR_CPP (@var{expression})
9819 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
9824 $ echo "#define AS_TR_CPP([HAVE_$type]) 1"
9825 #define HAVE_CHAR_P 1
9829 @defmac AS_TR_SH (@var{expression})
9831 Transform @var{expression} into a valid shell variable name. For example:
9834 $ header="sys/some file.h"
9835 $ AS_TR_SH([HAVE_$header])=yes
9836 $ if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
9841 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
9842 @asindex{SET_CATFILE}
9843 Set the shell variable @var{var} to @var{dir}/@var{file}, but
9844 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
9845 @var{file} is absolute, etc.).
9849 @node File Descriptor Macros
9850 @section File Descriptor Macros
9852 @cindex standard input
9853 @cindex file descriptors
9855 @cindex low-level output
9856 @cindex output, low-level
9858 The following macros define file descriptors used to output messages
9859 (or input values) from @file{configure} scripts.
9863 echo "$wombats found" >&AS_MESSAGE_LOG_FD
9864 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
9865 read kangaroos <&AS_ORIGINAL_STDIN_FD`
9869 However doing so is seldom needed, because Autoconf provides higher
9870 level macros as described below.
9872 @defmac AS_MESSAGE_FD
9873 @asindex{MESSAGE_FD}
9874 The file descriptor for @samp{checking for...} messages and results.
9875 Normally this directs messages to the standard output, however when
9876 @command{configure} is run with the @option{-q} option, messages sent to
9877 @code{AS_MESSAGE_FD} will be discarded.
9879 If you want to display some messages, consider using one of the printing
9880 macros (@pxref{Printing Messages}) instead. Copies of messages output
9881 via these macros will additionally be recorded in @file{config.log}.
9884 @defmac AS_MESSAGE_LOG_FD
9885 @asindex{MESSAGE_LOG_FD}
9887 The file descriptor for messages logged to @file{config.log}. Macros
9888 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
9889 Compiler}), redirect all output to this descriptor. You may want to do
9890 so if you develop such a low-level macro.
9893 @defmac AS_ORIGINAL_STDIN_FD
9894 @asindex{ORIGINAL_STDIN_FD}
9895 The file descriptor for the original standard input.
9897 When @command{configure} runs, it may accidentally execute an
9898 interactive command that has the same name as the non-interactive meant
9899 to be used or checked. If the standard input was the terminal, such
9900 interactive programs would cause @command{configure} to stop, pending
9901 some user input. Therefore @command{configure} redirects its standard
9902 input from @file{/dev/null} during its initialization. This is not
9903 normally a problem, since @command{configure} normally does not need
9906 In the extreme case where your @file{configure} script really needs to
9907 obtain some values from the original standard input, you can read them
9908 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
9912 @c =================================================== Writing Autoconf Macros.
9914 @node Writing Autoconf Macros
9915 @chapter Writing Autoconf Macros
9917 When you write a feature test that could be applicable to more than one
9918 software package, the best thing to do is encapsulate it in a new macro.
9919 Here are some instructions and guidelines for writing Autoconf macros.
9922 * Macro Definitions:: Basic format of an Autoconf macro
9923 * Macro Names:: What to call your new macros
9924 * Reporting Messages:: Notifying @command{autoconf} users
9925 * Dependencies Between Macros:: What to do when macros depend on other macros
9926 * Obsoleting Macros:: Warning about old ways of doing things
9927 * Coding Style:: Writing Autoconf macros @`a la Autoconf
9930 @node Macro Definitions
9931 @section Macro Definitions
9934 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
9935 similar to the M4 builtin @code{m4_define} macro. In addition to
9936 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
9937 constrain the order in which macros are called (@pxref{Prerequisite
9940 An Autoconf macro definition looks like this:
9943 AC_DEFUN(@var{macro-name}, @var{macro-body})
9946 You can refer to any arguments passed to the macro as @samp{$1},
9947 @samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
9948 @acronym{GNU} m4}, for more complete information on writing M4 macros.
9950 Be sure to properly quote both the @var{macro-body} @emph{and} the
9951 @var{macro-name} to avoid any problems if the macro happens to have
9952 been previously defined.
9954 Each macro should have a header comment that gives its prototype, and a
9955 brief description. When arguments have default values, display them in
9956 the prototype. For example:
9959 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
9960 # --------------------------------------
9961 m4_define([AC_MSG_ERROR],
9962 [@{ AS_MESSAGE([error: $1], [2])
9963 exit m4_default([$2], [1]); @}])
9966 Comments about the macro should be left in the header comment. Most
9967 other comments will make their way into @file{configure}, so just keep
9968 using @samp{#} to introduce comments.
9971 If you have some very special comments about pure M4 code, comments
9972 that make no sense in @file{configure} and in the header comment, then
9973 use the builtin @code{dnl}: it causes M4 to discard the text
9974 through the next newline.
9976 Keep in mind that @code{dnl} is rarely needed to introduce comments;
9977 @code{dnl} is more useful to get rid of the newlines following macros
9978 that produce no output, such as @code{AC_REQUIRE}.
9982 @section Macro Names
9984 All of the Autoconf macros have all-uppercase names starting with
9985 @samp{AC_} to prevent them from accidentally conflicting with other
9986 text. All shell variables that they use for internal purposes have
9987 mostly-lowercase names starting with @samp{ac_}. To ensure that your
9988 macros don't conflict with present or future Autoconf macros, you should
9989 prefix your own macro names and any shell variables they use with some
9990 other sequence. Possibilities include your initials, or an abbreviation
9991 for the name of your organization or software package.
9993 Most of the Autoconf macros' names follow a structured naming convention
9994 that indicates the kind of feature check by the name. The macro names
9995 consist of several words, separated by underscores, going from most
9996 general to most specific. The names of their cache variables use the
9997 same convention (@pxref{Cache Variable Names}, for more information on
10000 The first word of the name after @samp{AC_} usually tells the category
10001 of the feature being tested. Here are the categories used in Autoconf for
10002 specific test macros, the kind of macro that you are more likely to
10003 write. They are also used for cache variables, in all-lowercase. Use
10004 them where applicable; where they're not, invent your own categories.
10008 C language builtin features.
10010 Declarations of C variables in header files.
10012 Functions in libraries.
10014 Posix group owners of files.
10020 Absolute names of files, including programs.
10022 The base names of programs.
10024 Members of aggregates.
10026 Operating system features.
10028 C builtin or declared types.
10030 C variables in libraries.
10033 After the category comes the name of the particular feature being
10034 tested. Any further words in the macro name indicate particular aspects
10035 of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
10036 behavior of the @code{utime} function when called with a @code{NULL}
10039 An internal macro should have a name that starts with an underscore;
10040 Autoconf internals should therefore start with @samp{_AC_}.
10041 Additionally, a macro that is an internal subroutine of another macro
10042 should have a name that starts with an underscore and the name of that
10043 other macro, followed by one or more words saying what the internal
10044 macro does. For example, @code{AC_PATH_X} has internal macros
10045 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10047 @node Reporting Messages
10048 @section Reporting Messages
10049 @cindex Messages, from @command{autoconf}
10051 When macros statically diagnose abnormal situations, benign or fatal,
10052 they should report them using these macros. For dynamic issues, i.e.,
10053 when @command{configure} is run, see @ref{Printing Messages}.
10055 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10057 Report @var{message} as a warning (or as an error if requested by the
10058 user) if warnings of the @var{category} are turned on. You are
10059 encouraged to use standard categories, which currently include:
10063 messages that don't fall into one of the following categories. Use of an
10064 empty @var{category} is equivalent.
10067 related to cross compilation issues.
10070 use of an obsolete construct.
10073 dubious syntactic constructs, incorrectly ordered macro calls.
10077 @defmac AC_WARNING (@var{message})
10079 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10080 strongly encouraged to use a finer grained category.
10083 @defmac AC_FATAL (@var{message})
10085 Report a severe error @var{message}, and have @command{autoconf} die.
10088 When the user runs @samp{autoconf -W error}, warnings from
10089 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10090 @ref{autoconf Invocation}.
10092 @node Dependencies Between Macros
10093 @section Dependencies Between Macros
10094 @cindex Dependencies between macros
10096 Some Autoconf macros depend on other macros having been called first in
10097 order to work correctly. Autoconf provides a way to ensure that certain
10098 macros are called if needed and a way to warn the user if macros are
10099 called in an order that might cause incorrect operation.
10102 * Prerequisite Macros:: Ensuring required information
10103 * Suggested Ordering:: Warning about possible ordering problems
10104 * One-Shot Macros:: Ensuring a macro is called only once
10107 @node Prerequisite Macros
10108 @subsection Prerequisite Macros
10109 @cindex Prerequisite macros
10110 @cindex Macros, prerequisites
10112 A macro that you write might need to use values that have previously
10113 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
10114 examines the output of @code{flex} or @code{lex}, so it depends on
10115 @code{AC_PROG_LEX} having been called first to set the shell variable
10118 Rather than forcing the user of the macros to keep track of the
10119 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10120 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
10121 called if it is needed, and only called once.
10123 @defmac AC_REQUIRE (@var{macro-name})
10125 If the M4 macro @var{macro-name} has not already been called, call it
10126 (without any arguments). Make sure to quote @var{macro-name} with
10127 square brackets. @var{macro-name} must have been defined using
10128 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10129 that it has been called.
10131 @code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
10132 must not be called from the top level.
10135 @code{AC_REQUIRE} is often misunderstood. It really implements
10136 dependencies between macros in the sense that if one macro depends upon
10137 another, the latter will be expanded @emph{before} the body of the
10138 former. To be more precise, the required macro will be expanded before
10139 the outermost @code{AC_DEFUN}'d macro in the current expansion stack.
10140 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
10141 @code{FOO}. For instance, this definition of macros:
10145 AC_DEFUN([TRAVOLTA],
10146 [test "$body_temperature_in_celsius" -gt "38" &&
10147 dance_floor=occupied])
10148 AC_DEFUN([NEWTON_JOHN],
10149 [test "$hair_style" = "curly" &&
10150 dance_floor=occupied])
10154 AC_DEFUN([RESERVE_DANCE_FLOOR],
10155 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10156 AC_REQUIRE([TRAVOLTA])
10157 AC_REQUIRE([NEWTON_JOHN])
10163 with this @file{configure.ac}
10166 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
10167 RESERVE_DANCE_FLOOR
10168 if test "$dance_floor" = occupied; then
10169 AC_MSG_ERROR([cannot pick up here, let's move])
10174 will not leave you with a better chance to meet a kindred soul at
10175 other times than Saturday night since it expands into:
10179 test "$body_temperature_in_Celsius" -gt "38" &&
10180 dance_floor=occupied
10181 test "$hair_style" = "curly" &&
10182 dance_floor=occupied
10184 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10191 This behavior was chosen on purpose: (i) it prevents messages in
10192 required macros from interrupting the messages in the requiring macros;
10193 (ii) it avoids bad surprises when shell conditionals are used, as in:
10198 AC_REQUIRE([SOME_CHECK])
10205 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
10206 enforce expansion of required macros outside of shell conditional
10207 constructs. You are furthermore encouraged to put all @code{AC_REQUIRE}s
10208 at the beginning of a macro. You can use @code{dnl} to avoid the empty
10211 @node Suggested Ordering
10212 @subsection Suggested Ordering
10213 @cindex Macros, ordering
10214 @cindex Ordering macros
10216 Some macros should be run before another macro if both are called, but
10217 neither @emph{requires} that the other be called. For example, a macro
10218 that changes the behavior of the C compiler should be called before any
10219 macros that run the C compiler. Many of these dependencies are noted in
10222 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
10223 with this kind of dependency appear out of order in a
10224 @file{configure.ac} file. The warning occurs when creating
10225 @command{configure} from @file{configure.ac}, not when running
10226 @command{configure}.
10228 For example, @code{AC_PROG_CPP} checks whether the C compiler
10229 can run the C preprocessor when given the @option{-E} option. It should
10230 therefore be called after any macros that change which C compiler is
10231 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
10234 AC_BEFORE([$0], [AC_PROG_CPP])dnl
10238 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
10239 when @code{AC_PROG_CC} is called.
10241 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
10243 Make M4 print a warning message to the standard error output if
10244 @var{called-macro-name} has already been called. @var{this-macro-name}
10245 should be the name of the macro that is calling @code{AC_BEFORE}. The
10246 macro @var{called-macro-name} must have been defined using
10247 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10248 that it has been called.
10251 @node One-Shot Macros
10252 @subsection One-Shot Macros
10253 @cindex One-shot macros
10254 @cindex Macros, called once
10256 Some macros should be called only once, either because calling them
10257 multiple time is unsafe, or because it is bad style. For instance
10258 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
10259 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
10260 sense to run these expensive checks more than once. Such one-shot
10261 macros can be defined using @code{AC_DEFUN_ONCE}.
10263 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
10264 @acindex{DEFUN_ONCE}
10266 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
10267 Definitions}), and emit a warning any time the macro is called more than
10271 Obviously it is not sensible to evaluate a macro defined by
10272 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}, most of the
10273 times you will want to use @code{AC_REQUIRE} (@pxref{Prerequisite
10276 @node Obsoleting Macros
10277 @section Obsoleting Macros
10278 @cindex Obsoleting macros
10279 @cindex Macros, obsoleting
10281 Configuration and portability technology has evolved over the years.
10282 Often better ways of solving a particular problem are developed, or
10283 ad-hoc approaches are systematized. This process has occurred in many
10284 parts of Autoconf. One result is that some of the macros are now
10285 considered @dfn{obsolete}; they still work, but are no longer considered
10286 the best thing to do, hence they should be replaced with more modern
10287 macros. Ideally, @command{autoupdate} should replace the old macro calls
10288 with their modern implementation.
10290 Autoconf provides a simple means to obsolete a macro.
10292 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
10294 Define @var{old-macro} as @var{implementation}. The only difference
10295 with @code{AC_DEFUN} is that the user will be warned that
10296 @var{old-macro} is now obsolete.
10298 If she then uses @command{autoupdate}, the call to @var{old-macro} will be
10299 replaced by the modern @var{implementation}. @var{message} should
10300 include information on what to do after running @command{autoupdate};
10301 @command{autoupdate} will print it as a warning, and include it
10302 in the updated @file{configure.ac} file.
10304 The details of this macro are hairy: if @command{autoconf} encounters an
10305 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
10306 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
10307 macros will be expanded here, while all other macros are disabled and will
10308 appear literally in the updated @file{configure.ac}.
10311 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
10313 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
10314 with the same parameters. This happens for example if the macro was renamed.
10318 @section Coding Style
10319 @cindex Coding style
10321 The Autoconf macros follow a strict coding style. You are encouraged to
10322 follow this style, especially if you intend to distribute your macro,
10323 either by contributing it to Autoconf itself, or via other means.
10325 The first requirement is to pay great attention to the quotation. For
10326 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
10328 Do not try to invent new interfaces. It is likely that there is a macro
10329 in Autoconf that resembles the macro you are defining: try to stick to
10330 this existing interface (order of arguments, default values, etc.). We
10331 @emph{are} conscious that some of these interfaces are not perfect;
10332 nevertheless, when harmless, homogeneity should be preferred over
10335 Be careful about clashes both between M4 symbols and between shell
10338 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
10339 you are unlikely to generate conflicts. Nevertheless, when you need to
10340 set a special value, @emph{avoid using a regular macro name}; rather,
10341 use an ``impossible'' name. For instance, up to version 2.13, the macro
10342 @code{AC_SUBST} used to remember what @var{symbol}s were already defined
10343 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
10344 But since there is a macro named @code{AC_SUBST_FILE}, it was just
10345 impossible to @samp{AC_SUBST(FILE)}! In this case,
10346 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
10347 have been used (yes, with the parentheses).
10348 @c or better yet, high-level macros such as @code{m4_expand_once}
10350 No Autoconf macro should ever enter the user-variable name space; i.e.,
10351 except for the variables that are the actual result of running the
10352 macro, all shell variables should start with @code{ac_}. In
10353 addition, small macros or any macro that is likely to be embedded in
10354 other macros should be careful not to use obvious names.
10357 Do not use @code{dnl} to introduce comments: most of the comments you
10358 are likely to write are either header comments which are not output
10359 anyway, or comments that should make their way into @file{configure}.
10360 There are exceptional cases where you do want to comment special M4
10361 constructs, in which case @code{dnl} is right, but keep in mind that it
10364 M4 ignores the leading blanks and newlines before each argument.
10365 Use this feature to
10366 indent in such a way that arguments are (more or less) aligned with the
10367 opening parenthesis of the macro being called. For instance, instead of
10370 AC_CACHE_CHECK(for EMX OS/2 environment,
10372 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
10373 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
10380 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10381 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10382 [ac_cv_emxos2=yes],
10383 [ac_cv_emxos2=no])])
10390 AC_CACHE_CHECK([for EMX OS/2 environment],
10392 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
10393 [return __EMX__;])],
10394 [ac_cv_emxos2=yes],
10395 [ac_cv_emxos2=no])])
10398 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
10399 cross-compiling, provide a pessimistic value (typically @samp{no}).
10401 Feel free to use various tricks to prevent auxiliary tools, such as
10402 syntax-highlighting editors, from behaving improperly. For instance,
10406 m4_bpatsubst([$1], [$"])
10413 m4_bpatsubst([$1], [$""])
10417 so that Emacsen do not open an endless ``string'' at the first quote.
10418 For the same reasons, avoid:
10428 test $[@@%:@@] != 0
10432 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
10433 breaking the bracket-matching highlighting from Emacsen. Note the
10434 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
10435 not escape when it is unnecessary. Common examples of useless quotation
10436 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
10437 etc. If you add portability issues to the picture, you'll prefer
10438 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
10439 better than hacking Autoconf @code{:-)}.
10441 When using @command{sed}, don't use @option{-e} except for indenting
10442 purposes. With the @code{s} and @code{y} commands, the preferred
10443 separator is @samp{/} unless @samp{/} itself might appear in the pattern
10444 or replacement, in which case you should use @samp{|}, or optionally
10445 @samp{,} if you know the pattern and replacement cannot contain a file
10446 name. If none of these characters will do, choose a printable character
10447 that cannot appear in the pattern or replacement. Characters from the
10448 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
10449 replacement might contain a file name, since they have special meaning
10450 to the shell and are less likely to occur in file names.
10452 @xref{Macro Definitions}, for details on how to define a macro. If a
10453 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
10454 of an @code{AC_REQUIRE} directive, and macros required by other macros
10455 inside arguments will not need to be expanded before this macro, then
10456 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
10457 All the @code{AC_REQUIRE} statements should be at the beginning of the
10458 macro, @code{dnl}'ed.
10460 You should not rely on the number of arguments: instead of checking
10461 whether an argument is missing, test that it is not empty. It provides
10462 both a simpler and a more predictable interface to the user, and saves
10463 room for further arguments.
10465 Unless the macro is short, try to leave the closing @samp{])} at the
10466 beginning of a line, followed by a comment that repeats the name of the
10467 macro being defined. This introduces an additional newline in
10468 @command{configure}; normally, that is not a problem, but if you want to
10469 remove it you can use @samp{[]dnl} on the last line. You can similarly
10470 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
10471 is recommended instead of @samp{dnl} to ensure that M4 does not
10472 interpret the @samp{dnl} as being attached to the preceding text or
10473 macro output. For example, instead of:
10476 AC_DEFUN([AC_PATH_X],
10477 [AC_MSG_CHECKING([for X])
10479 @r{# @dots{}omitted@dots{}}
10480 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10488 AC_DEFUN([AC_PATH_X],
10489 [AC_REQUIRE_CPP()[]dnl
10490 AC_MSG_CHECKING([for X])
10491 @r{# @dots{}omitted@dots{}}
10492 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10497 If the macro is long, try to split it into logical chunks. Typically,
10498 macros that check for a bug in a function and prepare its
10499 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
10500 this setup. Do not hesitate to introduce auxiliary macros to factor
10503 In order to highlight the recommended coding style, here is a macro
10504 written the old way:
10507 dnl Check for EMX on OS/2.
10509 AC_DEFUN(_AC_EMXOS2,
10510 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
10511 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
10512 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
10513 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
10522 # Check for EMX on OS/2.
10523 m4_define([_AC_EMXOS2],
10524 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10525 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10526 [ac_cv_emxos2=yes],
10527 [ac_cv_emxos2=no])])
10528 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
10535 @c ============================================= Portable Shell Programming
10537 @node Portable Shell
10538 @chapter Portable Shell Programming
10539 @cindex Portable shell programming
10541 When writing your own checks, there are some shell-script programming
10542 techniques you should avoid in order to make your code portable. The
10543 Bourne shell and upward-compatible shells like the Korn shell and Bash
10544 have evolved over the years, but to prevent trouble, do not take
10545 advantage of features that were added after Unix version 7, circa
10546 1977 (@pxref{Systemology}).
10548 You should not use shell functions, aliases, negated character
10549 classes, or other features that are not found in all Bourne-compatible
10550 shells; restrict yourself to the lowest common denominator. Even
10551 @code{unset} is not supported by all shells!
10553 Some old systems have quite
10554 small limits on the length of the @samp{#!} line; for instance, 32
10555 bytes (not including the newline) on SunOS 4.
10556 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
10557 required a single space between the @samp{#!} and the @samp{/}, but
10558 these are no longer of practical concern.
10560 The set of external programs you should run in a @command{configure} script
10561 is fairly small. @xref{Utilities in Makefiles, , Utilities in
10562 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
10563 restriction allows users to start out with a fairly small set of
10564 programs and build the rest, avoiding too many interdependencies between
10567 Some of these external utilities have a portable subset of features; see
10568 @ref{Limitations of Usual Tools}.
10570 There are other sources of documentation about shells. The
10571 specification for the Posix
10572 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
10573 Command Language}, though more generous than the restrictive shell
10574 subset described above, is fairly portable nowadays. Also please see
10575 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
10578 * Shellology:: A zoology of shells
10579 * Here-Documents:: Quirks and tricks
10580 * File Descriptors:: FDs and redirections
10581 * File System Conventions:: File names
10582 * Shell Substitutions:: Variable and command expansions
10583 * Assignments:: Varying side effects of assignments
10584 * Parentheses:: Parentheses in shell scripts
10585 * Slashes:: Slashes in shell scripts
10586 * Special Shell Variables:: Variables you should not change
10587 * Limitations of Builtins:: Portable use of not so portable /bin/sh
10588 * Limitations of Usual Tools:: Portable use of portable tools
10589 * Limitations of Make:: Portable Makefiles
10593 @section Shellology
10596 There are several families of shells, most prominently the Bourne family
10597 and the C shell family which are deeply incompatible. If you want to
10598 write portable shell scripts, avoid members of the C shell family. The
10599 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
10600 Shell difference FAQ} includes a small history of Posix shells, and a
10601 comparison between several of them.
10603 Below we describe some of the members of the Bourne shell family.
10608 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
10609 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
10610 bugs that are fixed in the 0.3.x series, but portable shell scripts
10611 should work around them, since version 0.2 is still shipped with many
10612 @acronym{GNU}/Linux distributions.
10614 To be compatible with Ash 0.2:
10618 don't use @samp{$?} after expanding empty or unset variables,
10619 or at the start of an @command{eval}:
10625 echo "Do not use it: $?"
10627 eval 'echo "Do not use it: $?"'
10631 don't use command substitution within variable expansion:
10638 beware that single builtin substitutions are not performed by a
10639 subshell, hence their effect applies to the current shell! @xref{Shell
10640 Substitutions}, item ``Command Substitution''.
10645 To detect whether you are running Bash, test whether
10646 @code{BASH_VERSION} is set. To require
10647 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
10648 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
10649 Manual}, for details.
10651 @item Bash 2.05 and later
10652 @cindex Bash 2.05 and later
10653 Versions 2.05 and later of Bash use a different format for the
10654 output of the @command{set} builtin, designed to make evaluating its
10655 output easier. However, this output is not compatible with earlier
10656 versions of Bash (or with many other shells, probably). So if
10657 you use Bash 2.05 or higher to execute @command{configure},
10658 you'll need to use Bash 2.05 for all other build tasks as well.
10663 @prindex @samp{ksh}
10664 @prindex @samp{ksh88}
10665 @prindex @samp{ksh93}
10666 The Korn shell is compatible with the Bourne family and it mostly
10667 conforms to Posix. It has two major variants commonly
10668 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
10669 release. It is usually called @command{ksh}, but is called @command{sh}
10670 on some hosts if you set your path appropriately.
10672 Solaris systems have three variants:
10673 @prindex @command{/usr/bin/ksh} on Solaris
10674 @command{/usr/bin/ksh} is @samp{ksh88}; it is
10675 standard on Solaris 2.0 and later.
10676 @prindex @command{/usr/xpg4/bin/sh} on Solaris
10677 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
10678 @samp{ksh88}; it is standard on Solaris 9 and later.
10679 @prindex @command{/usr/dt/bin/dtksh} on Solaris
10680 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
10681 Variants that are not standard may be parts of optional
10682 packages. There is no extra charge for these packages, but they are
10683 not part of a minimal OS install and therefore some installations may
10686 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
10687 is also available as @command{/usr/bin/posix/sh}. If the environment
10688 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
10689 the standard shell conform to Posix.
10692 @prindex @samp{pdksh}
10693 A public-domain clone of the Korn shell called @command{pdksh} is widely
10694 available: it has most of the @samp{ksh88} features along with a few of
10695 its own. It will usually set @code{KSH_VERSION}, except if invoked as
10696 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
10697 Posix compatibility by running @samp{set -o posix}. Unfortunately, with
10698 @command{pdksh} 5.2.14 (the latest stable version as of February 2006)
10699 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
10700 at least one respect:
10703 $ echo "`echo \"hello\"`"
10706 $ echo "`echo \"hello\"`"
10710 The last line of output contains spurious quotes. This is yet another
10711 reason why portable shell code should not contain
10712 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
10717 To detect whether you are running @command{zsh}, test whether
10718 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
10719 compatible with the Bourne shell: you must execute @samp{emulate sh},
10720 and for @command{zsh} versions before 3.1.6-dev-18 you must also
10721 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
10722 zsh, The Z Shell Manual}, for details.
10724 The default Mac OS X @command{sh} was originally Zsh; it was changed to
10725 Bash in Mac OS X 10.2.
10728 The following discussion between Russ Allbery and Robert Lipe is worth
10735 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
10736 leads to a permanent deadlock. Vendors don't want to break users'
10737 existing shell scripts, and there are some corner cases in the Bourne
10738 shell that are not completely compatible with a Posix shell. Thus,
10739 vendors who have taken this route will @emph{never} (OK@dots{}``never say
10740 never'') replace the Bourne shell (as @command{/bin/sh}) with a
10748 This is exactly the problem. While most (at least most System V's) do
10749 have a Bourne shell that accepts shell functions most vendor
10750 @command{/bin/sh} programs are not the Posix shell.
10752 So while most modern systems do have a shell @emph{somewhere} that meets the
10753 Posix standard, the challenge is to find it.
10756 @node Here-Documents
10757 @section Here-Documents
10758 @cindex Here documents
10759 @cindex Shell here documents
10761 Don't rely on @samp{\} being preserved just because it has no special
10762 meaning together with the next symbol. In the native @command{sh}
10763 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
10764 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
10765 use @samp{\\} to get @samp{\}.
10767 With Open@acronym{BSD} 2.7's @command{sh}
10783 bash-2.04$ @kbd{cat <<EOF
10791 Many older shells (including the Bourne shell) implement here-documents
10792 inefficiently. And some shells mishandle large here-documents: for example,
10793 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
10794 derived from Korn shell version M-12/28/93d, mishandle braced variable
10795 expansion @code{$@{var@}} that crosses a 1024- or 4096-byte buffer boundary
10796 within a here-document. If the closing brace does not lie on the boundary,
10797 the failure is silent and the variable expansion will be empty, otherwise
10798 the shell will report a bad substitution. This bug can usually be worked
10799 around by omitting the braces: @code{$var}.
10801 Some shells can be extremely inefficient when there are a lot of
10802 here-documents inside a single statement. For instance if your
10803 @file{configure.ac} includes something like:
10807 if <cross_compiling>; then
10808 assume this and that
10812 check something else
10820 A shell parses the whole @code{if}/@code{fi} construct, creating
10821 temporary files for each here document in it. Some shells create links
10822 for such here-documents on every @code{fork}, so that the clean-up code
10823 they had installed correctly removes them. It is creating the links
10824 that can take the shell forever.
10826 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
10827 @code{if}/@code{fi} constructs, would improve the performance
10828 significantly. Anyway, this kind of construct is not exactly the
10829 typical use of Autoconf. In fact, it's even not recommended, because M4
10830 macros can't look into shell conditionals, so we may fail to expand a
10831 macro when it was expanded before in a conditional path, and the
10832 condition turned out to be false at runtime, and we end up not
10833 executing the macro at all.
10835 @node File Descriptors
10836 @section File Descriptors
10837 @cindex Descriptors
10838 @cindex File descriptors
10839 @cindex Shell file descriptors
10841 Some file descriptors shall not be used, since some systems, admittedly
10842 arcane, use them for special purpose:
10845 3 --- some systems may open it to @samp{/dev/tty}.
10846 4 --- used on the Kubota Titan.
10849 Don't redirect the same file descriptor several times, as you are doomed
10850 to failure under Ultrix.
10853 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
10855 $ @kbd{eval 'echo matter >fullness' >void}
10857 $ @kbd{eval '(echo matter >fullness)' >void}
10859 $ @kbd{(eval '(echo matter >fullness)') >void}
10860 Ambiguous output redirect.
10864 In each case the expected result is of course @file{fullness} containing
10865 @samp{matter} and @file{void} being empty.
10867 Don't try to redirect the standard error of a command substitution: it
10868 must be done @emph{inside} the command substitution: when running
10869 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
10870 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
10872 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
10873 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
10875 Most shells, if not all (including Bash, Zsh, Ash), output traces on
10876 stderr, even for sub-shells. This might result in undesirable content
10877 if you meant to capture the standard-error output of the inner command:
10880 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
10882 + eval echo foo >&2
10885 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
10887 + eval 'echo foo >&2'
10890 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
10891 @i{# Traces on startup files deleted here.}
10893 +zsh:1> eval echo foo >&2
10899 You'll appreciate the various levels of detail@enddots{}
10901 One workaround is to grep out uninteresting lines, hoping not to remove
10902 good ones@enddots{}
10904 Don't try to move/delete open files, such as in @samp{exec >foo; mv foo
10905 bar}; see @ref{Limitations of Builtins}, @command{mv} for more details.
10907 Don't rely on open file descriptors being open in child processes. In
10908 @command{ksh}, file descriptors above 2 which are opened using
10909 @samp{exec n>file} are closed by a subsequent @samp{exec} (such as
10910 that involved in the fork-and-exec which runs a program or script).
10911 Thus, using sh, we have:
10930 Within the process which runs the @samp{descrips} script, file
10931 descriptor number 5 is closed.
10933 @node File System Conventions
10934 @section File System Conventions
10935 @cindex File system conventions
10937 Autoconf uses shell-script processing extensively, so the file names
10938 that it processes should not contain characters that are special to the
10939 shell. Special characters include space, tab, newline, @sc{nul}, and
10943 " # $ & ' ( ) * ; < = > ? [ \ ` |
10946 Also, file names should not begin with @samp{~} or @samp{-}, and should
10947 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
10948 immediately after @samp{:}.
10950 These restrictions apply not only to the files that you distribute, but
10951 also to the absolute file names of your source, build, and destination
10954 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
10955 they should be avoided.
10957 Posix lets implementations treat leading @file{//} specially, but
10958 requires leading @file{///} and beyond to be equivalent to @file{/}.
10959 Most Unix variants treat @file{//} like @file{/}. However, some treat
10960 @file{//} as a ``super-root'' that can provide access to files that are
10961 not otherwise reachable from @file{/}. The super-root tradition began
10962 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
10965 While @command{autoconf} and friends will usually be run on some Posix
10966 variety, it can and will be used on other systems, most notably @acronym{DOS}
10967 variants. This impacts several assumptions regarding file names.
10970 For example, the following code:
10977 foo_dir=$dots$foo_dir ;;
10982 will fail to properly detect absolute file names on those systems, because
10983 they can use a drivespec, and will usually use a backslash as directory
10984 separator. If you want to be portable to @acronym{DOS} variants (at the
10985 price of rejecting valid but oddball Posix file names like @file{a:\b}),
10986 you can check for absolute file names like this:
10990 [\\/]* | ?:[\\/]* ) # Absolute
10993 foo_dir=$dots$foo_dir ;;
10998 Make sure you quote the brackets if appropriate and keep the backslash as
10999 first character (@pxref{Limitations of Builtins}).
11001 Also, because the colon is used as part of a drivespec, these systems don't
11002 use it as path separator. When creating or accessing paths, you can use the
11003 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
11004 to the appropriate value (@samp{:} or @samp{;}) when it starts up.
11006 File names need extra care as well. While @acronym{DOS} variants
11007 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP}) will
11008 usually be able to handle long file names properly, there are still
11009 limitations that can seriously break packages. Several of these issues
11010 can be easily detected by the
11011 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11014 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11015 indicate where they apply: @sc{sfn} means the issues are only relevant to
11016 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11017 variants, while @sc{lfn} identifies problems that exist even under
11018 Microsoft Windows variants.
11021 @item No multiple dots (@sc{sfn})
11022 @acronym{DOS} cannot handle multiple dots in file names. This is an especially
11023 important thing to remember when building a portable configure script,
11024 as @command{autoconf} uses a .in suffix for template files.
11026 This is perfectly OK on Posix variants:
11029 AC_CONFIG_HEADERS([config.h])
11030 AC_CONFIG_FILES([source.c foo.bar])
11035 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11036 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
11037 to @acronym{DOS}-based environments, you should use this instead:
11040 AC_CONFIG_HEADERS([config.h:config.hin])
11041 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11045 @item No leading dot (@sc{sfn})
11046 @acronym{DOS} cannot handle file names that start with a dot. This is usually
11047 not a very important issue for @command{autoconf}.
11049 @item Case insensitivity (@sc{lfn})
11050 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11051 file called @samp{INSTALL} and a directory called @samp{install}. This
11052 also affects @command{make}; if there's a file called @samp{INSTALL} in
11053 the directory, @samp{make install} will do nothing (unless the
11054 @samp{install} target is marked as PHONY).
11056 @item The 8+3 limit (@sc{sfn})
11057 Because the @acronym{DOS} file system only stores the first 8 characters of
11058 the file name and the first 3 of the extension, those must be unique.
11059 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11060 @file{foobar-prettybird.c} all resolve to the same file name
11061 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
11062 @file{foo.bartender}.
11064 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11066 tails in the short version of file names to make them unique. However, a
11067 registry setting can turn this behavior off. While this makes it
11068 possible to share file trees containing long file names between @sc{sfn}
11069 and @sc{lfn} environments, it also means the above problem applies there
11072 @item Invalid characters (@sc{lfn})
11073 Some characters are invalid in @acronym{DOS} file names, and should therefore
11074 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11075 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11076 In a @sc{sfn} environment, other characters are also invalid. These
11077 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11079 @item Invalid names (@sc{lfn})
11080 Some @acronym{DOS} file names are reserved, and cause problems if you
11081 try to use files with those names. These names include @file{CON},
11082 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11083 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11084 File names are case insensitive, so even names like
11085 @file{aux/config.guess} are disallowed.
11089 @node Shell Substitutions
11090 @section Shell Substitutions
11091 @cindex Shell substitutions
11093 Contrary to a persistent urban legend, the Bourne shell does not
11094 systematically split variables and back-quoted expressions, in particular
11095 on the right-hand side of assignments and in the argument of @code{case}.
11096 For instance, the following code:
11099 case "$given_srcdir" in
11100 .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
11101 *) top_srcdir="$dots$given_srcdir" ;;
11106 is more readable when written as:
11109 case $given_srcdir in
11110 .) top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
11111 *) top_srcdir=$dots$given_srcdir ;;
11116 and in fact it is even @emph{more} portable: in the first case of the
11117 first attempt, the computation of @code{top_srcdir} is not portable,
11118 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
11119 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
11120 the same way. There is just no portable way to use double-quoted
11121 strings inside double-quoted back-quoted expressions (pfew!).
11125 @cindex @samp{"$@@"}
11126 One of the most famous shell-portability issues is related to
11127 @samp{"$@@"}. When there are no positional arguments, Posix says
11128 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
11129 original Unix version 7 Bourne shell treated it as equivalent to
11130 @samp{""} instead, and this behavior survives in later implementations
11131 like Digital Unix 5.0.
11133 The traditional way to work around this portability problem is to use
11134 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
11135 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
11136 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
11139 zsh $ @kbd{emulate sh}
11140 zsh $ @kbd{for i in "$@@"; do echo $i; done}
11143 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
11150 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
11151 @samp{"$@@"} because of the portability problems mentioned above.
11152 One workaround relies on Zsh's ``global aliases'' to convert
11153 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
11156 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
11159 A more conservative workaround is to avoid @samp{"$@@"} if it is
11160 possible that there may be no positional arguments. For example,
11164 cat conftest.c "$@@"
11167 you can use this instead:
11171 0) cat conftest.c;;
11172 *) cat conftest.c "$@@";;
11178 @cindex positional parameters
11179 The 10th, 11th, @dots{} positional parameters can be accessed only after
11180 a @code{shift}. The 7th Edition shell reported an error if given
11181 @code{$@{10@}}, and
11182 Solaris 10 @command{/bin/sh} still acts that way:
11185 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
11186 $ @kbd{echo $@{10@}}
11190 @item $@{@var{var}:-@var{value}@}
11191 @c Info cannot handle `:' in index entries.
11192 @c @cindex $@{@var{var}:-@var{value}@}
11193 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
11194 colon for any shell substitution, and complain and die.
11196 @item $@{@var{var}=@var{literal}@}
11197 @cindex $@{@var{var}=@var{literal}@}
11201 : $@{var='Some words'@}
11205 otherwise some shells, such as on Digital Unix V 5.0, will die because
11206 of a ``bad substitution''.
11210 Solaris @command{/bin/sh} has a frightening bug in its interpretation
11211 of this. Imagine you need set a variable to a string containing
11212 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
11213 when the affected variable was already set. This bug can be exercised
11218 $ @kbd{foo=$@{foo='@}'@}}
11221 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
11224 $ @kbd{foo=$@{foo='@}'@}}
11230 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
11231 though it is enclosed in single quotes. The problem doesn't happen
11232 using double quotes.
11234 @item $@{@var{var}=@var{expanded-value}@}
11235 @cindex $@{@var{var}=@var{expanded-value}@}
11241 : $@{var="$default"@}
11245 will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
11246 each char will be set. You won't observe the phenomenon using a simple
11247 @samp{echo $var} since apparently the shell resets the 8th bit when it
11248 expands $var. Here are two means to make this shell confess its sins:
11251 $ @kbd{cat -v <<EOF
11260 $ @kbd{set | grep '^var=' | cat -v}
11263 One classic incarnation of this bug is:
11267 : $@{list="$default"@}
11274 You'll get @samp{a b c} on a single line. Why? Because there are no
11275 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
11276 bit set, hence no IFS splitting is performed!!!
11278 One piece of good news is that Ultrix works fine with @samp{:
11279 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
11280 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
11283 The portable way out consists in using a double assignment, to switch
11284 the 8th bit twice on Ultrix:
11287 list=$@{list="$default"@}
11291 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
11295 test "$@{var+set@}" = set || var=@var{@{value@}}
11299 @item `@var{commands}`
11300 @cindex `@var{commands}`
11301 @cindex Command Substitution
11302 Posix requires shells to trim all trailing newlines from command
11303 output before substituting it, so assignments like
11304 @samp{dir=`echo "$file" | tr a A`} will not work as expected if
11305 @samp{$file} ends in a newline.
11307 While in general it makes no sense, do not substitute a single builtin
11308 with side effects, because Ash 0.2, trying to optimize, does not fork a
11309 subshell to perform the command.
11311 For instance, if you wanted to check that @command{cd} is silent, do not
11312 use @samp{test -z "`cd /`"} because the following can happen:
11317 $ @kbd{test -z "`cd /`" && pwd}
11322 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
11324 The MSYS shell leaves a stray byte in the expansion of a double-quoted
11325 command substitution of a native program, if the end of the substution
11326 is not aligned with the end of the double quote. This may be worked
11327 around by inserting another pair of quotes:
11330 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
11331 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
11332 - broken differ: char 4, line 1
11336 @item $(@var{commands})
11337 @cindex $(@var{commands})
11338 This construct is meant to replace @samp{`@var{commands}`},
11339 and it has most of the problems listed under @code{`@var{commands}`}.
11341 This construct can be
11342 nested while this is impossible to do portably with back quotes.
11343 Unfortunately it is not yet universally supported. Most notably, even recent
11344 releases of Solaris don't support it:
11347 $ @kbd{showrev -c /bin/sh | grep version}
11348 Command version: SunOS 5.10 Generic January 2005
11349 $ @kbd{echo $(echo blah)}
11350 syntax error: `(' unexpected
11354 nor does @sc{irix} 6.5's Bourne shell:
11357 IRIX firebird-image 6.5 07151432 IP22
11358 $ @kbd{echo $(echo blah)}
11362 If you do use @samp{$(@var{commands})}, make sure that the commands
11363 do not start with a parenthesis, as that would cause confusion with
11364 a different notation @samp{$((@var{expression}))} that in modern
11365 shells is an arithmetic expression not a command. To avoid the
11366 confusion, insert a space between the two opening parentheses.
11368 Avoid @var{commands} that contain unbalanced parentheses in
11369 here-documents, comments, or case statement patterns, as many shells
11370 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
11371 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
11374 echo $(case x in x) echo hello;; esac)
11379 Always quote @samp{^}, otherwise traditional shells such as
11380 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
11386 @section Assignments
11387 @cindex Shell assignments
11389 When setting several variables in a row, be aware that the order of the
11390 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
11391 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
11393 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
11395 Don't rely on the following to find @file{subdir/program}:
11398 PATH=subdir$PATH_SEPARATOR$PATH program
11402 as this does not work with Zsh 3.0.6. Use something like this
11406 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
11409 Don't rely on the exit status of an assignment: Ash 0.2 does not change
11410 the status and propagates that of the last statement:
11413 $ @kbd{false || foo=bar; echo $?}
11415 $ @kbd{false || foo=`:`; echo $?}
11420 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
11424 $ @kbd{foo=`exit 1`; echo $?}
11428 To assign default values, follow this algorithm:
11432 If the default value is a literal and does not contain any closing
11436 : $@{var='my literal'@}
11440 If the default value contains no closing brace, has to be expanded, and
11441 the variable being initialized will never be IFS-split (i.e., it's not a
11445 : $@{var="$default"@}
11449 If the default value contains no closing brace, has to be expanded, and
11450 the variable being initialized will be IFS-split (i.e., it's a list),
11454 var=$@{var="$default"@}
11458 If the default value contains a closing brace, then use:
11461 test "$@{var+set@}" = set || var='$@{indirection@}'
11465 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
11466 doubt, just use the latter. @xref{Shell Substitutions}, items
11467 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
11471 @section Parentheses in Shell Scripts
11472 @cindex Shell parentheses
11474 Beware of two opening parentheses in a row, as some shell
11475 implementations mishandle them. For example, @samp{pdksh} 5.2.14
11476 misparses the following code:
11479 if ((true) || false); then
11485 To work around this problem, insert a space between the two opening
11486 parentheses. There is a similar problem and workaround with
11487 @samp{$((}; see @ref{Shell Substitutions}.
11489 Posix requires support for @code{case} patterns with opening
11490 parentheses like this:
11494 (*.c) echo "C source code";;
11499 but the @code{(} in this example is not portable to many older Bourne
11500 shell implementations. It can be omitted safely.
11503 @section Slashes in Shell Scripts
11504 @cindex Shell slashes
11506 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
11507 arguments that contain two trailing slashes:
11510 $ echo / // /// //// .// //.
11516 $ echo abc | tr -t ab //
11522 However, our understanding is that patches are available, so perhaps
11523 it's not worth worrying about working around this horrendous bug.
11525 @node Special Shell Variables
11526 @section Special Shell Variables
11527 @cindex Shell variables
11528 @cindex Special shell variables
11530 Some shell variables should not be used, since they can have a deep
11531 influence on the behavior of the shell. In order to recover a sane
11532 behavior from the shell, some variables should be unset, but
11533 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
11534 fallback value is needed.
11536 As a general rule, shell variable names containing a lower-case letter
11537 are safe; you can define and use these variables without worrying about
11538 their effect on the underlying system, and without worrying about
11539 whether the shell will change them unexpectedly. (The exception is the
11540 shell variable @code{status}, as described below.)
11542 Here is a list of names that are known to cause trouble. This list is
11543 not exhaustive, but you should be safe if you avoid the name
11544 @code{status} and names containing only upper-case letters and
11547 @c Alphabetical order, case insensitive, `A' before `a'.
11550 Many shells reserve @samp{$_} for various purposes, e.g., the name of
11551 the last command executed.
11555 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11556 the standard shell conform to Posix.
11557 Autoconf-generated scripts export this variable when they start up.
11561 When this variable is set it specifies a list of directories to search
11562 when invoking @code{cd} with a relative file name. Posix
11563 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
11564 is used successfully, @code{cd} prints the resulting absolute
11565 file name. Unfortunately this output can break idioms like
11566 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
11567 Also, many shells do not conform to this part of Posix; for
11568 example, @command{zsh} prints the result only if a directory name
11569 other than @file{.} was chosen from @env{CDPATH}.
11571 In practice the shells that have this problem also support
11572 @command{unset}, so you can work around the problem as follows:
11575 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
11578 Autoconf-generated scripts automatically unset @env{CDPATH} if
11579 possible, so you need not worry about this problem in those scripts.
11583 In the MKS shell, case statements and file name generation are
11584 case-insensitive unless @env{DUALCASE} is nonzero.
11585 Autoconf-generated scripts export this variable when they start up.
11599 These variables should not matter for shell scripts, since they are
11600 supposed to affect only interactive shells. However, at least one
11601 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
11602 whether it is interactive, which means that (for example) a @env{PS1}
11603 with a side effect can unexpectedly modify @samp{$?}. To work around
11604 this bug, Autoconf-generated scripts do something like this:
11607 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
11615 Long ago, shell scripts inherited @env{IFS} from the environment,
11616 but this caused many problems so modern shells ignore any environment
11617 settings for @env{IFS}.
11619 Don't set the first character of @code{IFS} to backslash. Indeed,
11620 Bourne shells use the first character (backslash) when joining the
11621 components in @samp{"$@@"} and some shells then re-interpret (!)@: the
11622 backslash escapes, so you can end up with backspace and other strange
11625 The proper value for @code{IFS} (in regular code, not when performing
11626 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
11627 especially important, as it is used to join the arguments in @samp{$*};
11628 however, note that traditional shells, but also bash-2.04, fail to adhere
11629 to this and join with a space anyway.
11641 @evindex LC_COLLATE
11643 @evindex LC_MESSAGES
11644 @evindex LC_MONETARY
11645 @evindex LC_NUMERIC
11648 Autoconf-generated scripts normally set all these variables to
11649 @samp{C} because so much configuration code assumes the C locale and
11650 Posix requires that locale environment variables be set to
11651 @samp{C} if the C locale is desired. However, some older, nonstandard
11652 systems (notably @acronym{SCO}) break if locale environment variables
11653 are set to @samp{C}, so when running on these systems
11654 Autoconf-generated scripts unset the variables instead.
11659 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
11660 extension that overrides @env{LC_ALL} in some cases, so
11661 Autoconf-generated scripts set it too.
11664 @itemx LC_IDENTIFICATION
11665 @itemx LC_MEASUREMENT
11668 @itemx LC_TELEPHONE
11669 @evindex LC_ADDRESS
11670 @evindex LC_IDENTIFICATION
11671 @evindex LC_MEASUREMENT
11674 @evindex LC_TELEPHONE
11676 These locale environment variables are @acronym{GNU} extensions. They
11677 are treated like their Posix brethren (@env{LC_COLLATE},
11678 etc.)@: as described above.
11681 Most modern shells provide the current line number in @code{LINENO}.
11682 Its value is the line number of the beginning of the current command.
11683 Autoconf attempts to execute @command{configure} with a modern shell.
11684 If no such shell is available, it attempts to implement @code{LINENO}
11685 with a Sed prepass that replaces each instance of the string
11686 @code{$LINENO} (not followed by an alphanumeric character) with the
11689 You should not rely on @code{LINENO} within @command{eval}, as the
11690 behavior differs in practice. Also, the possibility of the Sed
11691 prepass means that you should not rely on @code{$LINENO} when quoted,
11692 when in here-documents, or when in long commands that cross line
11693 boundaries. Subshells should be OK, though. In the following
11694 example, lines 1, 6, and 9 are portable, but the other instances of
11695 @code{LINENO} are not:
11705 ( echo 6. $LINENO )
11706 eval 'echo 7. $LINENO'
11712 $ @kbd{bash-2.05 lineno}
11723 $ @kbd{zsh-3.0.6 lineno}
11734 $ @kbd{pdksh-5.2.14 lineno}
11745 $ @kbd{sed '=' <lineno |}
11751 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
11754 > @kbd{ s,^[0-9]*\n,,}
11770 When executing the command @samp{>foo}, @command{zsh} executes
11771 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
11772 compatibility mode and the @command{zsh} version is newer
11773 than 3.1.6-dev-18. If you are using an older @command{zsh}
11774 and forget to set @env{NULLCMD},
11775 your script might be suspended waiting for data on its standard input.
11777 @item PATH_SEPARATOR
11778 @evindex PATH_SEPARATOR
11779 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
11780 variable can be set to either @samp{:} or @samp{;} to control the path
11781 separator Bash uses to set up certain environment variables (such as
11782 @env{PATH}). You can set this variable to @samp{;} if you want
11783 @command{configure} to use @samp{;} as a separator; this might be useful
11784 if you plan to use non-Posix shells to execute files. @xref{File System
11785 Conventions}, for more information about @code{PATH_SEPARATOR}.
11789 Posix 1003.1-2001 requires that @command{cd} and
11790 @command{pwd} must update the @env{PWD} environment variable to point
11791 to the logical name of the current directory, but traditional shells
11792 do not support this. This can cause confusion if one shell instance
11793 maintains @env{PWD} but a subsidiary and different shell does not know
11794 about @env{PWD} and executes @command{cd}; in this case @env{PWD} will
11795 point to the wrong directory. Use @samp{`pwd`} rather than
11799 Many shells provide @code{RANDOM}, a variable that returns a different
11800 integer each time it is used. Most of the time, its value does not
11801 change when it is not used, but on @sc{irix} 6.5 the value changes all
11802 the time. This can be observed by using @command{set}. It is common
11803 practice to use @code{$RANDOM} as part of a file name, but code
11804 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
11807 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
11808 hence read-only. Do not use it.
11811 @node Limitations of Builtins
11812 @section Limitations of Shell Builtins
11813 @cindex Shell builtins
11814 @cindex Limitations of shell builtins
11816 No, no, we are serious: some shells do have limitations! :)
11818 You should always keep in mind that any builtin or command may support
11819 options, and therefore have a very different behavior with arguments
11820 starting with a dash. For instance, the innocent @samp{echo "$word"}
11821 can give unexpected results when @code{word} starts with a dash. It is
11822 often possible to avoid this problem using @samp{echo "x$word"}, taking
11823 the @samp{x} into account later in the pipe.
11827 @prindex @command{.}
11828 Use @command{.} only with regular files (use @samp{test -f}). Bash
11829 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
11830 @command{.} uses @env{PATH} if its argument contains no slashes, so if
11831 you want to use @command{.} on a file @file{foo} in the current
11832 directory, you must use @samp{. ./foo}.
11835 @prindex @command{!}
11836 The Unix version 7 shell did not support
11837 negating the exit status of commands with @command{!}, and this feature
11838 is still absent from more modern shells (e.g., Solaris @command{/bin/sh}).
11839 Shell code like this:
11842 if ! cmp file1 file2 >/dev/null 2>&1; then
11843 echo files differ or trouble
11847 is therefore not portable in practice. Typically it is easy to rewrite
11851 cmp file1 file2 >/dev/null 2>&1 ||
11852 echo files differ or trouble
11855 More generally, one can always rewrite @samp{! @var{command}} as:
11858 if @var{command}; then (exit 1); else :; fi
11861 @item @command{break}
11862 @c ------------------
11863 @prindex @command{break}
11864 The use of @samp{break 2} etc.@: is safe.
11867 @item @command{case}
11868 @c -----------------
11869 @prindex @command{case}
11870 You don't need to quote the argument; no splitting is performed.
11872 You don't need the final @samp{;;}, but you should use it.
11874 Because of a bug in its @code{fnmatch}, Bash fails to properly
11875 handle backslashes in character classes:
11878 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
11883 This is extremely unfortunate, since you are likely to use this code to
11884 handle Posix or @sc{ms-dos} absolute file names. To work around this
11885 bug, always put the backslash first:
11888 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
11890 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
11894 Many Bourne shells cannot handle closing brackets in character classes
11897 Some shells also have problems with backslash escaping in case you do not want
11898 to match the backslash: both a backslash and the escaped character match this
11899 pattern. To work around this, specify the character class in a variable, so
11900 that quote removal does not apply afterwards, and the special characters don't
11901 have to be backslash-escaped:
11904 $ @kbd{case '\' in [\<]) echo OK;; esac}
11906 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
11910 Even with this, Solaris @command{ksh} matches a backslash if the set
11912 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
11914 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
11915 a closing parenthesis if not specified in a character class:
11918 $ @kbd{case foo in *\)*) echo fail ;; esac}
11920 $ @kbd{case foo in *')'*) echo fail ;; esac}
11924 Some shells, such as Ash 0.3.8, are confused by an empty
11925 @code{case}/@code{esac}:
11928 ash-0.3.8 $ @kbd{case foo in esac;}
11929 @error{}Syntax error: ";" unexpected (expecting ")")
11932 Many shells still do not support parenthesized cases, which is a pity
11933 for those of us using tools that rely on balanced parentheses. For
11934 instance, Solaris @command{/bin/sh}:
11937 $ @kbd{case foo in (foo) echo foo;; esac}
11938 @error{}syntax error: `(' unexpected
11944 @prindex @command{cd}
11945 Posix 1003.1-2001 requires that @command{cd} must support
11946 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
11947 with @option{-L} being the default. However, traditional shells do
11948 not support these options, and their @command{cd} command has the
11949 @option{-P} behavior.
11951 Portable scripts should assume neither option is supported, and should
11952 assume neither behavior is the default. This can be a bit tricky,
11953 since the Posix default behavior means that, for example,
11954 @samp{ls ..} and @samp{cd ..} may refer to different directories if
11955 the current logical directory is a symbolic link. It is safe to use
11956 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
11957 Also, Autoconf-generated scripts check for this problem when computing
11958 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
11959 so it is safe to @command{cd} to these variables.
11961 Also please see the discussion of the @command{pwd} command.
11964 @item @command{echo}
11965 @c -----------------
11966 @prindex @command{echo}
11967 The simple @command{echo} is probably the most surprising source of
11968 portability troubles. It is not possible to use @samp{echo} portably
11969 unless both options and escape sequences are omitted. New applications
11970 which are not aiming at portability should use @samp{printf} instead of
11973 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
11974 etc.@: for a means to simulate @option{-n}.
11976 Do not use backslashes in the arguments, as there is no consensus on
11977 their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of
11978 Digital Unix 4.0 and @acronym{MIPS RISC/OS} 4.52, answer 2, but the Solaris
11979 @command{/bin/sh}, Bash, and Zsh (in @command{sh} emulation mode) report 1.
11980 Please note that the problem is truly @command{echo}: all the shells
11981 understand @samp{'\n'} as the string composed of a backslash and an
11984 Because of these problems, do not pass a string containing arbitrary
11985 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
11986 if you know that @var{foo}'s value cannot contain backslashes and cannot
11987 start with @samp{-}, but otherwise you should use a here-document like
11997 @item @command{eval}
11998 @c -----------------
11999 @prindex @command{eval}
12000 The @command{eval} command is useful in limited circumstances, e.g.,
12001 using commands like @samp{eval table_$key=\$value} and @samp{eval
12002 value=table_$key} to simulate a hash table when the key is known to be
12003 alphanumeric. However, @command{eval} is tricky to use on arbitrary
12004 arguments, even when it is implemented correctly.
12006 It is obviously unwise to use @samp{eval $cmd} if the string value of
12007 @samp{cmd} was derived from an untrustworthy source. But even if the
12008 string value is valid, @samp{eval $cmd} might not work as intended,
12009 since it causes field splitting and file name expansion to occur twice,
12010 once for the @command{eval} and once for the command itself. It is
12011 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
12012 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
12013 equivalent of @samp{cat test;.c} if there happens to be a file named
12014 @file{test;.c} in the current directory; and this in turn will
12015 mistakenly attempt to invoke @command{cat} on the file @file{test} and
12016 then execute the command @command{.c}. To avoid this problem, use
12017 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
12019 However, suppose that you want to output the text of the evaluated
12020 command just before executing it. Assuming the previous example,
12021 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
12022 this output doesn't show the user that @samp{test;.c} is the actual name
12023 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"} will
12024 work on this example, but it will fail with @samp{cmd='cat foo >bar'},
12025 since it will mistakenly replace the contents of @file{bar} by the
12026 string @samp{cat foo}. No simple, general, and portable solution to
12027 this problem is known.
12029 You should also be wary of common bugs in @command{eval} implementations.
12030 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
12031 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
12032 4.2.5), the arguments of @samp{eval} are evaluated in a context where
12033 @samp{$?} is 0, so they exhibit behavior like this:
12036 $ false; eval 'echo $?'
12040 The correct behavior here is to output a nonzero value,
12041 but portable scripts should not rely on this.
12043 You should not rely on @code{LINENO} within @command{eval}.
12044 @xref{Special Shell Variables}.
12046 @item @command{exit}
12047 @c -----------------
12048 @prindex @command{exit}
12049 The default value of @command{exit} is supposed to be @code{$?};
12050 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
12051 perform @samp{exit 0}.
12054 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
12056 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
12058 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
12062 Using @samp{exit $?} restores the expected behavior.
12064 Some shell scripts, such as those generated by @command{autoconf}, use a
12065 trap to clean up before exiting. If the last shell command exited with
12066 nonzero status, the trap also exits with nonzero status so that the
12067 invoker can tell that an error occurred.
12069 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
12070 trap ignores the @code{exit} command's argument. In these shells, a trap
12071 cannot determine whether it was invoked by plain @code{exit} or by
12072 @code{exit 1}. Instead of calling @code{exit} directly, use the
12073 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
12076 @item @command{export}
12077 @c -------------------
12078 @prindex @command{export}
12079 The builtin @command{export} dubs a shell variable @dfn{environment
12080 variable}. Each update of exported variables corresponds to an update
12081 of the environment variables. Conversely, each environment variable
12082 received by the shell when it is launched should be imported as a shell
12083 variable marked as exported.
12085 Alas, many shells, such as Solaris @command{/bin/sh},
12086 @sc{irix} 6.3, @sc{irix} 5.2,
12087 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
12088 @command{export} the environment variables they receive. As a result,
12089 two variables coexist: the environment variable and the shell
12090 variable. The following code demonstrates this failure:
12101 when run with @samp{FOO=foo} in the environment, these shells will print
12102 alternately @samp{foo} and @samp{bar}, although it should only print
12103 @samp{foo} and then a sequence of @samp{bar}s.
12105 Therefore you should @command{export} again each environment variable
12109 @item @command{false}
12110 @c ------------------
12111 @prindex @command{false}
12112 Don't expect @command{false} to exit with status 1: in native
12113 Solaris it exits with status 255.
12116 @item @command{for}
12117 @c ----------------
12118 @prindex @command{for}
12119 To loop over positional arguments, use:
12129 You may @emph{not} leave the @code{do} on the same line as @code{for},
12130 since some shells improperly grok:
12138 If you want to explicitly refer to the positional arguments, given the
12139 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
12142 for arg in $@{1+"$@@"@}; do
12148 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
12149 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
12150 item @samp{$@@}, for more.
12155 @prindex @command{if}
12156 Using @samp{!} is not portable. Instead of:
12159 if ! cmp -s file file.new; then
12168 if cmp -s file file.new; then :; else
12173 There are shells that do not reset the exit status from an @command{if}:
12176 $ @kbd{if (exit 42); then true; fi; echo $?}
12181 whereas a proper shell should have printed @samp{0}. This is especially
12182 bad in Makefiles since it produces false failures. This is why properly
12183 written Makefiles, such as Automake's, have such hairy constructs:
12186 if test -f "$file"; then
12187 install "$file" "$dest"
12194 @item @command{printf}
12195 @c ------------------
12196 @prindex @command{printf}
12197 A format string starting with a @samp{-} can cause problems.
12198 Bash (e.g., 2.05b) will interpret it as an options string and
12199 give an error. And @samp{--} to mark the end of options is not good
12200 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which will take that
12201 literally as the format string. Putting the @samp{-} in a @samp{%c}
12202 or @samp{%s} is probably the easiest way to avoid doubt,
12209 @item @command{read}
12210 @c ------------------
12211 @prindex @command{read}
12212 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
12215 @item @command{pwd}
12216 @c ----------------
12217 @prindex @command{pwd}
12218 With modern shells, plain @command{pwd} outputs a ``logical''
12219 directory name, some of whose components may be symbolic links. These
12220 directory names are in contrast to ``physical'' directory names, whose
12221 components are all directories.
12223 Posix 1003.1-2001 requires that @command{pwd} must support
12224 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12225 with @option{-L} being the default. However, traditional shells do
12226 not support these options, and their @command{pwd} command has the
12227 @option{-P} behavior.
12229 Portable scripts should assume neither option is supported, and should
12230 assume neither behavior is the default. Also, on many hosts
12231 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
12232 does not require this behavior and portable scripts should not rely on
12235 Typically it's best to use plain @command{pwd}. On modern hosts this
12236 outputs logical directory names, which have the following advantages:
12240 Logical names are what the user specified.
12242 Physical names may not be portable from one installation
12243 host to another due to network file system gymnastics.
12245 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
12246 some parent directory, but plain @command{pwd} cannot fail for this
12250 Also please see the discussion of the @command{cd} command.
12253 @item @command{set}
12254 @c ----------------
12255 @prindex @command{set}
12256 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
12257 any options) does not sort its output.
12259 The @command{set} builtin faces the usual problem with arguments starting with a
12260 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
12261 the end of the options (any argument after @option{--} is a parameter,
12262 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
12263 10 @command{/bin/sh}) simply stop option
12264 processing as soon as a non-option argument is found. Therefore, use
12265 @samp{dummy} or simply @samp{x} to end the option processing, and use
12266 @command{shift} to pop it out:
12269 set x $my_list; shift
12272 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
12273 longer requires support for this command, and in traditional shells
12274 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
12275 makes scripts harder to debug.
12277 Some nonstandard shells do not recognize more than one option
12278 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
12279 better to combine them:
12285 The @acronym{BSD} shell has had several problems with the @option{-e}
12286 option, partly because @acronym{BSD} @command{make} traditionally used
12287 @option{-e} even though this was incompatible with Posix
12288 (@pxref{Limitations of Make}). Older versions of the @acronym{BSD}
12289 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
12290 @samp{case} when @option{-e} was in effect, causing the shell to exit
12291 unexpectedly in some cases. This was particularly a problem with
12292 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
12293 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
12294 wrapper works around the bug.
12296 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
12297 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
12298 @samp{&&} fails inside a compound statement. For example:
12304 test -n "$foo" && exit 1
12307 test -n "$foo" && exit 1
12313 does not print @samp{two}. One workaround is to use @samp{if test -n
12314 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
12315 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
12318 @item @command{shift}
12319 @c ------------------
12320 @prindex @command{shift}
12321 Not only is @command{shift}ing a bad idea when there is nothing left to
12322 shift, but in addition it is not portable: the shell of @acronym{MIPS
12323 RISC/OS} 4.52 refuses to do it.
12325 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
12326 and it is also absent in many pre-Posix shells.
12329 @item @command{source}
12330 @c -------------------
12331 @prindex @command{source}
12332 This command is not portable, as Posix does not require it; use
12333 @command{.} instead.
12336 @item @command{test}
12337 @c -----------------
12338 @prindex @command{test}
12339 The @code{test} program is the way to perform many file and string
12340 tests. It is often invoked by the alternate name @samp{[}, but using
12341 that name in Autoconf code is asking for trouble since it is an M4 quote
12344 If you need to make multiple checks using @code{test}, combine them with
12345 the shell operators @samp{&&} and @samp{||} instead of using the
12346 @code{test} operators @option{-a} and @option{-o}. On System V, the
12347 precedence of @option{-a} and @option{-o} is wrong relative to the unary
12348 operators; consequently, Posix does not specify them, so using them
12349 is nonportable. If you combine @samp{&&} and @samp{||} in the same
12350 statement, keep in mind that they have equal precedence.
12352 It is safe to use @samp{!} as a @command{test} operator. For example,
12353 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
12354 -d foo; @dots{}} is not.
12357 @item @command{test} (files)
12358 @c -------------------------
12359 To enable @command{configure} scripts to support cross-compilation, they
12360 shouldn't do anything that tests features of the build system instead of
12361 the host system. But occasionally you may find it necessary to check
12362 whether some arbitrary file exists. To do so, use @samp{test -f} or
12363 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
12364 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
12365 lacks it. To test for symbolic links on systems that have them, use
12366 @samp{test -h} rather than @samp{test -L}; either form conforms to
12367 Posix 1003.1-2001, but older shells like Solaris 8
12368 @code{/bin/sh} support only @option{-h}.
12370 @item @command{test} (strings)
12371 @c ---------------------------
12372 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
12373 start with a dash, since @code{test} might interpret its argument as an
12374 option (e.g., @samp{@var{string} = "-n"}).
12376 Contrary to a common belief, @samp{test -n @var{string}} and
12377 @samp{test -z @var{string}} @strong{are} portable. Nevertheless many
12378 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
12379 Digital Unix 4, etc.)@: have bizarre precedence and may be confused if
12380 @var{string} looks like an operator:
12384 test: argument expected
12387 If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
12388 "x@var{string}" != x} instead.
12390 It is common to find variations of the following idiom:
12393 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
12398 to take an action when a token matches a given pattern. Such constructs
12399 should always be avoided by using:
12402 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
12407 Use @code{case} where possible since it is faster, being a shell builtin:
12411 case $ac_feature in
12412 *[!-a-zA-Z0-9_]*) @var{action};;
12416 Alas, negated character classes are probably not portable, although no
12417 shell is known to not support the Posix syntax @samp{[!@dots{}]}
12418 (when in interactive mode, @command{zsh} is confused by the
12419 @samp{[!@dots{}]} syntax and looks for an event in its history because of
12420 @samp{!}). Many shells do not support the alternative syntax
12421 @samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
12423 One solution can be:
12426 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12434 expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12438 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
12439 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
12440 @samp{@var{foo}} contains backslashes.
12443 @item @command{trap}
12444 @c -----------------
12445 @prindex @command{trap}
12446 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
12447 trap 0, i.e., have the @command{trap} run when the script ends (either via an
12448 explicit @command{exit}, or the end of the script).
12450 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
12451 specified signals to their default values, but many common shells (e.g.,
12452 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
12453 ``command'' named @command{-} when the specified conditions arise.
12454 There is no portable workaround, except for @samp{trap - 0}, for which
12455 @samp{trap '' 0} is a portable substitute.
12457 Although Posix is not absolutely clear on this point, it is widely
12458 admitted that when entering the trap @samp{$?} should be set to the exit
12459 status of the last command run before the trap. The ambiguity can be
12460 summarized as: ``when the trap is launched by an @command{exit}, what is
12461 the @emph{last} command run: that before @command{exit}, or
12462 @command{exit} itself?''
12464 Bash considers @command{exit} to be the last command, while Zsh and
12465 Solaris @command{/bin/sh} consider that when the trap is run it is
12466 @emph{still} in the @command{exit}, hence it is the previous exit status
12467 that the trap receives:
12470 $ @kbd{cat trap.sh}
12473 $ @kbd{zsh trap.sh}
12475 $ @kbd{bash trap.sh}
12479 The portable solution is then simple: when you want to @samp{exit 42},
12480 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
12481 set the exit status to 42 for Zsh, and the second to trigger the trap
12482 and pass 42 as exit status for Bash.
12484 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
12485 reset to 0 by empty lines if the code is inside @command{trap}.
12488 $ @kbd{trap 'false}
12496 Fortunately, this bug only affects @command{trap}.
12498 @item @command{true}
12499 @c -----------------
12500 @prindex @command{true}
12501 @c Info cannot handle `:' in index entries.
12502 @c @prindex @command{:}
12503 Don't worry: as far as we know @command{true} is portable.
12504 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
12505 portable shell community tends to prefer using @command{:}. This has a
12506 funny side effect: when asked whether @command{false} is more portable
12507 than @command{true} Alexandre Oliva answered:
12510 In a sense, yes, because if it doesn't exist, the shell will produce an
12511 exit status of failure, which is correct for @command{false}, but not
12512 for @command{true}.
12516 @item @command{unset}
12517 @c ------------------
12518 @prindex @command{unset}
12519 You cannot assume the support of @command{unset}. Nevertheless, because
12520 it is extremely useful to disable embarrassing variables such as
12521 @code{PS1}, you can test for its existence and use
12522 it @emph{provided} you give a neutralizing value when @command{unset} is
12526 if (unset FOO) >/dev/null 2>&1; then
12531 $unset PS1 || PS1='$ '
12534 @xref{Special Shell Variables}, for some neutralizing values. Also, see
12535 @ref{Limitations of Builtins}, documentation of @command{export}, for
12536 the case of environment variables.
12539 @node Limitations of Usual Tools
12540 @section Limitations of Usual Tools
12541 @cindex Limitations of usual tools
12543 The small set of tools you can expect to find on any machine can still
12544 include some limitations you should be aware of.
12548 @c ----------------
12550 Don't leave white space before the opening parenthesis in a user function call.
12551 Posix does not allow this and @acronym{GNU} Awk rejects it:
12554 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
12555 BEGIN @{ die () @}'}
12556 gawk: cmd. line:2: BEGIN @{ die () @}
12557 gawk: cmd. line:2: ^ parse error
12558 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
12559 BEGIN @{ die() @}'}
12563 If you want your program to be deterministic, don't depend on @code{for}
12567 $ @kbd{cat for.awk}
12574 $ @kbd{gawk -f for.awk </dev/null}
12577 $ @kbd{nawk -f for.awk </dev/null}
12582 Some Awk implementations, such as HP-UX 11.0's native one, mishandle anchors:
12585 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
12586 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
12588 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
12590 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
12595 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
12596 or use a simple test to reject such implementations.
12598 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the the
12599 length of regular expressions and literal strings in an Awk program.
12601 Traditional Awk implementations derived from Unix version 7, such as
12602 Solaris @command{/bin/awk}, have many limitations and do not
12603 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
12604 Programs}) will find you an Awk that doesn't have these problems, but if
12605 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
12608 Traditional Awk does not support multidimensional arrays or user-defined
12611 Traditional Awk does not support the @option{-v} option. You can use
12612 assignments after the program instead, e.g., @command{$AWK '@{print v
12613 $1@}' v=x}; however, don't forget that such assignments are not
12614 evaluated until they are encountered (e.g., after any @code{BEGIN}
12617 Traditional Awk does not support the keywords @code{delete} or @code{do}.
12619 Traditional Awk does not support the expressions
12620 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
12621 or @code{@var{a}^=@var{b}}.
12623 Traditional Awk does not support the predefined @code{CONVFMT} variable.
12625 Traditional Awk supports only the predefined functions @code{exp},
12626 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
12627 @code{sqrt}, and @code{substr}.
12629 Traditional Awk @code{getline} is not at all compatible with Posix;
12632 Traditional Awk @code{split} supports only two arguments.
12634 Traditional Awk has a limit of 99
12635 fields in a record. You may be able to circumvent this problem by using
12639 @item @command{basename}
12640 @c ---------------------
12641 @prindex @command{basename}
12642 Not all hosts have a working @command{basename}.
12643 You can use @command{expr} instead.
12645 @c AS_BASENAME is to be replaced by a better API.
12647 Not all hosts have a working @command{basename}, and you should instead
12648 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
12649 @command{expr} if you need to strip a suffix. For example:
12652 a=`basename "$aname"` # This is not portable.
12653 a=`AS_BASENAME(["$aname"])` # This is more portable.
12655 # This is not portable.
12656 c=`basename "$cname" .c`
12658 # This is more portable.
12659 c=`AS_BASENAME(["$cname"])`
12661 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
12667 @item @command{cat}
12668 @c ----------------
12669 @prindex @command{cat}
12670 Don't rely on any option.
12675 @prindex @command{cc}
12676 The command @samp{cc -c foo.c} traditionally produces an object file
12677 named @file{foo.o}. Most compilers allow @option{-c} to be combined
12678 with @option{-o} to specify a different object file name, but
12679 Posix does not require this combination and a few compilers
12680 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
12681 tests for this feature with @code{AC_PROG_CC_C_O}.
12683 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
12684 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
12686 HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and
12687 assemble. @samp{cc -c foo.S} will appear to succeed, but in fact does
12690 The default executable, produced by @samp{cc foo.c}, can be
12693 @item @file{a.out} --- usual Posix convention.
12694 @item @file{b.out} --- i960 compilers (including @command{gcc}).
12695 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
12696 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
12697 @item @file{foo.exe} --- various MS-DOS compilers.
12700 The C compiler's traditional name is @command{cc}, but other names like
12701 @command{gcc} are common. Posix 1003.1-2001 specifies the
12702 name @command{c99}, but older Posix editions specified
12703 @command{c89} and anyway these standard names are rarely used in
12704 practice. Typically the C compiler is invoked from makefiles that use
12705 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
12709 @item @command{chmod}
12710 @c ------------------
12711 @prindex @command{chmod}
12712 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
12713 instead, for two reasons. First, plain @option{-w} does not necessarily
12714 make the file unwritable, since it does not affect mode bits that
12715 correspond to bits in the file mode creation mask. Second,
12716 Posix says that the @option{-w} might be interpreted as an
12717 implementation-specific option, not as a mode; Posix suggests
12718 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
12719 @samp{--} does not work on some older hosts.
12722 @item @command{cmp}
12723 @c ----------------
12724 @prindex @command{cmp}
12725 @command{cmp} performs a raw data comparison of two files, while
12726 @command{diff} compares two text files. Therefore, if you might compare
12727 DOS files, even if only checking whether two files are different, use
12728 @command{diff} to avoid spurious differences due to differences of
12734 @prindex @command{cp}
12735 Avoid the @option{-r} option, since its behavior is not specified by
12736 Posix. Use @option{-R} instead. On @acronym{GNU} hosts the two options
12737 are equivalent, but on Solaris hosts (for example) @command{cp -r}
12738 reads from pipes instead of replicating them.
12740 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
12741 trailing slashes at the end of nonexistent destination directories. To
12742 avoid this problem, omit the trailing slashes. For example, use
12743 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
12744 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
12746 @c This is thanks to Ian.
12747 SunOS 4 @command{cp} does not support @option{-f}, although its
12748 @command{mv} does. It's possible to deduce why @command{mv} and
12749 @command{cp} are different with respect to @option{-f}. @command{mv}
12750 prompts by default before overwriting a read-only file. @command{cp}
12751 does not. Therefore, @command{mv} requires a @option{-f} option, but
12752 @command{cp} does not. @command{mv} and @command{cp} behave differently
12753 with respect to read-only files because the simplest form of
12754 @command{cp} cannot overwrite a read-only file, but the simplest form of
12755 @command{mv} can. This is because @command{cp} opens the target for
12756 write access, whereas @command{mv} simply calls @code{link} (or, in
12757 newer systems, @code{rename}).
12758 @c Ian said: ``I don't think -p or -r are portable''!!! How can you live
12761 @cindex timestamp resolution
12762 Traditionally, file timestamps had 1-second resolution, and @samp{cp
12763 -p} copied the timestamps exactly. However, many modern file systems
12764 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
12765 -p} implementations truncate timestamps when copying files, so this
12766 can result in the destination file appearing to be older than the
12767 source. The exact amount of truncation depends on the resolution of
12768 the system calls that @command{cp} uses; traditionally this was
12769 @code{utime}, which has 1-second resolution, but some newer
12770 @command{cp} implementations use @code{utimes}, which has
12771 1-microsecond resolution. These newer implementations include @acronym{GNU}
12772 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
12773 later. Unfortunately as of January 2006 there is still no system
12774 call to set time stamps to the full nanosecond resolution.
12776 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
12777 ownerships. But whether it actually does copy ownerships or not is a
12778 system dependent policy decision implemented by the kernel. If the
12779 kernel allows it then it happens. If the kernel does not allow it then
12780 it does not happen. It is not something @command{cp} itself has control
12783 In Unix System V any user can chown files to any other user, and System
12784 V also has a non-sticky @file{/tmp}. That probably derives from the
12785 heritage of System V in a business environment without hostile users.
12786 @acronym{BSD} changed this
12787 to be a more secure model where only root can @command{chown} files and
12788 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
12789 of @acronym{BSD} in a campus environment.
12791 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
12792 can be configured to allow a System V style @command{chown}. On the
12793 other hand, @acronym{HP-UX} follows System V, but can
12794 be configured to use the modern security model and disallow
12795 @command{chown}. Since it is an administrator-configurable parameter
12796 you can't use the name of the kernel as an indicator of the behavior.
12800 @item @command{date}
12801 @c -----------------
12802 @prindex @command{date}
12803 Some versions of @command{date} do not recognize special % directives,
12804 and unfortunately, instead of complaining, they just pass them through,
12805 and exit with success:
12809 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
12815 @item @command{diff}
12816 @c -----------------
12817 @prindex @command{diff}
12818 Option @option{-u} is nonportable.
12820 Some implementations, such as Tru64's, fail when comparing to
12821 @file{/dev/null}. Use an empty file instead.
12824 @item @command{dirname}
12825 @c --------------------
12826 @prindex @command{dirname}
12827 Not all hosts have a working @command{dirname}, and you should instead
12828 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
12831 dir=`dirname "$file"` # This is not portable.
12832 dir=`AS_DIRNAME(["$file"])` # This is more portable.
12836 @item @command{egrep}
12837 @c ------------------
12838 @prindex @command{egrep}
12839 Posix 1003.1-2001 no longer requires @command{egrep},
12840 but many older hosts do not yet support the Posix
12841 replacement @code{grep -E}. Also, some traditional implementations do
12842 not work on long input lines. To work around these problems, invoke
12843 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
12845 Portable extended regular expressions should use @samp{\} only to escape
12846 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
12847 is not portable, even though it typically matches @samp{@}}.
12849 The empty alternative is not portable. Use @samp{?} instead. For
12850 instance with Digital Unix v5.0:
12853 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
12855 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
12857 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
12862 @command{$EGREP} also suffers the limitations of @command{grep}.
12864 @item @command{expr}
12865 @c -----------------
12866 @prindex @command{expr}
12867 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
12868 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
12869 misinterpreting @var{word}.
12871 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
12873 @item @command{expr} (@samp{|})
12874 @prindex @command{expr} (@samp{|})
12875 You can use @samp{|}. Although Posix does require that @samp{expr
12876 ''} return the empty string, it does not specify the result when you
12877 @samp{|} together the empty string (or zero) with the empty string. For
12884 Posix 1003.2-1992 returns the empty string
12885 for this case, but traditional Unix returns @samp{0} (Solaris is
12886 one such example). In Posix 1003.1-2001, the specification was
12887 changed to match traditional Unix's behavior (which is
12888 bizarre, but it's too late to fix this). Please note that the same
12889 problem does arise when the empty string results from a computation,
12893 expr bar : foo \| foo : bar
12897 Avoid this portability problem by avoiding the empty string.
12900 @item @command{expr} (@samp{:})
12901 @c ----------------------------
12902 @prindex @command{expr}
12903 Portable @command{expr} regular expressions should use @samp{\} to
12904 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
12905 For example, alternation, @samp{\|}, is common but Posix does not
12906 require its support, so it should be avoided in portable scripts.
12907 Similarly, @samp{\+} and @samp{\?} should be avoided.
12909 Portable @command{expr} regular expressions should not begin with
12910 @samp{^}. Patterns are automatically anchored so leading @samp{^} is
12913 The Posix standard is ambiguous as to whether
12914 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
12915 In practice, it outputs the empty string on most platforms, but portable
12916 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
12917 @command{expr} returns @samp{0}.
12919 One might think that a way to get a uniform behavior would be to use
12920 the empty string as a default value:
12923 expr a : '\(b\)' \| ''
12927 Unfortunately this behaves exactly as the original expression; see the
12928 @samp{@command{expr} (@samp{|})} entry for more information.
12930 Older @command{expr} implementations (e.g., SunOS 4 @command{expr} and
12931 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
12932 @command{expr} to fail if the matched substring is longer than 120
12933 bytes. In this case, you might want to fall back on @samp{echo|sed} if
12934 @command{expr} fails.
12936 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
12937 some cases. For example, the command
12939 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
12943 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
12944 This particular case can be worked around by substituting @samp{[^--]}
12947 Don't leave, there is some more!
12949 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
12950 the empty string, has a funny behavior in its exit status: it's always 1
12951 when parentheses are used!
12954 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
12956 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
12959 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
12961 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
12966 In practice this can be a big problem if you are ready to catch failures
12967 of @command{expr} programs with some other method (such as using
12968 @command{sed}), since you may get twice the result. For instance
12971 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
12975 will output @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
12976 simple workaround consists in testing @command{expr} and use a variable
12977 set to @command{expr} or to @command{false} according to the result.
12979 Tru64 @command{expr} incorrectly treats the result as a number, if it
12980 can be interpreted that way:
12983 $ @kbd{expr 00001 : '.*\(...\)'}
12988 @item @command{fgrep}
12989 @c ------------------
12990 @prindex @command{fgrep}
12991 Posix 1003.1-2001 no longer requires @command{fgrep},
12992 but many older hosts do not yet support the Posix
12993 replacement @code{grep -F}. Also, some traditional implementations do
12994 not work on long input lines. To work around these problems, invoke
12995 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
12998 @item @command{find}
12999 @c -----------------
13000 @prindex @command{find}
13001 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
13002 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
13003 commands do not understand it.
13005 The replacement of @samp{@{@}} is guaranteed only if the argument is
13006 exactly @emph{@{@}}, not if it's only a part of an argument. For
13007 instance on DU, and HP-UX 10.20 and HP-UX 11:
13011 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
13016 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
13019 @item @command{grep}
13020 @c -----------------
13021 @prindex @command{grep}
13022 Portable scripts can rely on the @command{grep} options @option{-c},
13023 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
13024 options. For example, don't use @option{-w}, as Posix does not require
13025 it and Irix 6.5.16m's @command{grep} does not support it. Also,
13026 portable scripts should not combine @option{-c} with @option{-l},
13027 as Posix does not allow this.
13029 Some of the options required by Posix are not portable in practice.
13030 Don't use @samp{grep -q} to suppress output, because many @command{grep}
13031 implementations (e.g., Solaris) do not support @option{-q}.
13032 Don't use @samp{grep -s} to suppress output either, because Posix
13033 says @option{-s} does not suppress output, only some error messages;
13034 also, the @option{-s} option of traditional @command{grep} behaved
13035 like @option{-q} does in most modern implementations. Instead,
13036 redirect the standard output and standard error (in case the file
13037 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
13038 status of @code{grep} to determine whether it found a match.
13040 Some traditional @command{grep} implementations do not work on long
13041 input lines. On AIX the default @code{grep} silently truncates long
13042 lines on the input before matching.
13044 Also, many implementations do not support multiple regexps
13045 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
13046 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT). To
13047 work around these problems, invoke @code{AC_PROG_GREP} and then use
13050 Another possible workaround for the multiple @option{-e} problem is to
13051 separate the patterns by newlines, for example:
13059 except that this will fail with traditional @command{grep}
13060 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
13062 Traditional @command{grep} implementations (e.g., Solaris) do not
13063 support the @option{-E} or @option{-F} options. To work around these
13064 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
13065 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
13066 willing to require support for Posix @command{grep}, your script should
13067 not use both @option{-E} and @option{-F}, since Posix does not allow
13070 Portable @command{grep} regular expressions should use @samp{\} only to
13071 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
13072 alternation, @samp{\|}, is common but Posix does not require its
13073 support in basic regular expressions, so it should be avoided in
13074 portable scripts. Solaris @command{grep} does not support it.
13075 Similarly, @samp{\+} and @samp{\?} should be avoided.
13078 @item @command{join}
13079 @c -----------------
13080 @prindex @command{join}
13081 Solaris 8 @command{join} has bugs when the second operand is standard
13082 input, and when standard input is a pipe. For example, the following
13083 shell script causes Solaris 8 @command{join} to loop forever:
13090 cat file | join file -
13093 Use @samp{join - file} instead.
13098 @prindex @command{ln}
13099 @cindex Symbolic links
13100 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
13101 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
13103 For versions of the @acronym{DJGPP} before 2.04,
13104 @command{ln} emulates symbolic links
13105 to executables by generating a stub that in turn calls the real
13106 program. This feature also works with nonexistent files like in the
13107 Posix spec. So @samp{ln -s file link} will generate @file{link.exe},
13108 which will attempt to call @file{file.exe} if run. But this feature only
13109 works for executables, so @samp{cp -p} is used instead for these
13110 systems. @acronym{DJGPP} versions 2.04 and later have full support
13111 for symbolic links.
13116 @prindex @command{ls}
13117 @cindex Listing directories
13118 The portable options are @option{-acdilrtu}. Modern practice is for
13119 @option{-l} to output both owner and group, but traditional
13120 @command{ls} omits the group.
13122 @c From Bruce Lilly:
13126 @c Unix System V (TWG-TCP/IP) (dim.blilly.com)
13130 @c $ /bin/ls a.exe 2>/dev/null
13134 @c fndcmd:fndcmd.sl 1.68
13136 @c Unix dim SYSTEM5 3.51m mc68k
13138 @c It's an AT&T 3B1. See http://www.faqs.org/faqs/3b1-faq/ or any
13139 @c mirror of the 3B1 FAQ. It's actually SVR2.2.
13140 Modern practice is for all diagnostics to go to standard error, but
13141 traditional @samp{ls foo} prints the message @samp{foo not found} to
13142 standard output if @file{foo} does not exist. Be careful when writing
13143 shell commands like @samp{sources=`ls *.c 2>/dev/null`}, since with
13144 traditional @command{ls} this is equivalent to @samp{sources="*.c not
13145 found"} if there are no @samp{.c} files.
13148 @item @command{mkdir}
13149 @c ------------------
13150 @prindex @command{mkdir}
13151 @cindex Making directories
13152 None of @command{mkdir}'s options are portable to older systems. Instead of
13153 @samp{mkdir -p @var{file-name}}, you should use use
13154 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
13155 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
13157 Posix does not clearly specify whether @samp{mkdir -p foo}
13158 should succeed when @file{foo} is a symbolic link to an already-existing
13159 directory. The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
13160 succeeds, but Solaris @command{mkdir} fails.
13162 Traditional @code{mkdir -p} implementations suffer from race conditions.
13163 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
13164 at the same time, both processes might detect that @file{a} is missing,
13165 one might create @file{a}, then the other might try to create @file{a}
13166 and fail with a @code{File exists} diagnostic. At least Solaris 10,
13167 Net@acronym{BSD} 1.6, and Open@acronym{BSD} 3.4 are vulnerable to race
13168 conditions. The @acronym{GNU} Core Utilities
13169 (since @samp{fileutils}
13170 version 4.1), Free@acronym{BSD} 5.0, and Net@acronym{BSD}-current are
13172 race-free @code{mkdir -p}. This possible race is harmful in parallel
13173 builds when several @file{Makefile} rules call @code{mkdir -p} to
13174 construct directories. You may use
13175 @code{install-sh -d} as a safe replacement, provided this script is
13176 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
13177 OK, but copies from older versions are vulnerable.
13180 @item @command{mktemp}
13181 @c -------------------
13182 @prindex @command{mktemp}
13183 @cindex Creating temporary files
13184 Shell scripts can use temporary files safely with @command{mktemp}, but
13185 it does not exist on all systems. A portable way to create a safe
13186 temporary file name is to create a temporary directory with mode 700 and
13187 use a file inside this directory. Both methods prevent attackers from
13188 gaining control, though @command{mktemp} is far less likely to fail
13189 gratuitously under attack.
13191 Here is sample code to create a new temporary directory safely:
13194 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
13195 # Use mktemp if possible; otherwise fall back on mkdir,
13196 # with $RANDOM to make collisions less likely.
13200 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
13202 test -n "$tmp" && test -d "$tmp"
13204 tmp=$TMPDIR/foo$$-$RANDOM
13205 (umask 077 && mkdir "$tmp")
13212 @prindex @command{mv}
13213 @cindex Moving open files
13214 The only portable options are @option{-f} and @option{-i}.
13216 Moving individual files between file systems is portable (it was in Unix
13218 but it is not always atomic: when doing @samp{mv new existing}, there's
13219 a critical section where neither the old nor the new version of
13220 @file{existing} actually exists.
13222 On some systems moving files from @file{/tmp} can sometimes cause
13223 undesirable (but perfectly valid) warnings, even if you created these
13224 files. This is because @file{/tmp} belongs to a group that ordinary
13225 users are not members of, and files created in @file{/tmp} inherit
13226 @file{/tmp}'s group. When the file is copied, @command{mv} issues
13227 a diagnostic without failing:
13230 $ @kbd{touch /tmp/foo}
13231 $ @kbd{mv /tmp/foo .}
13232 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
13240 This annoying behavior conforms to Posix, unfortunately.
13242 Moving directories across mount points is not portable, use @command{cp}
13245 Moving/Deleting open files isn't portable. The following can't be done
13246 on @acronym{DOS} variants:
13264 @prindex @command{od}
13266 In Mac OS X 10.3, @command{od} does not support the
13267 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
13268 @option{-t}, or the @acronym{XSI} option @option{-s}. The only
13269 supported Posix option is @option{-v}, and the only supported
13270 @acronym{XSI} options are those in @option{-bcdox}. The BSD
13271 @command{hexdump} program can be used instead.
13273 This problem no longer exists in Mac OS X 10.4.3.
13276 @item @command{sed}
13277 @c ----------------
13278 @prindex @command{sed}
13279 Patterns should not include the separator (unless escaped), even as part
13280 of a character class. In conformance with Posix, the Cray
13281 @command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
13283 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
13284 not require support for empty patterns, and Unicos 9 @command{sed} rejects
13287 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
13289 Sed scripts should not use branch labels longer than 8 characters and
13290 should not contain comments. HP-UX sed has a limit of 99 commands
13291 (not counting @samp{:} commands) and
13292 48 labels, which can not be circumvented by using more than one script
13293 file. It can execute up to 19 reads with the @samp{r} command per cycle.
13294 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
13295 about 6000 bytes for the internal representation of commands.
13297 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
13298 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
13299 @samp{;} as a command:
13302 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
13303 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
13306 Input should not have unreasonably long lines, since some @command{sed}
13307 implementations have an input buffer limited to 4000 bytes.
13309 Portable @command{sed} regular expressions should use @samp{\} only to escape
13310 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
13311 alternation, @samp{\|}, is common but Posix does not require its
13312 support, so it should be avoided in portable scripts. Solaris
13313 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
13314 deletes only lines that contain the literal string @samp{a|b}.
13315 Similarly, @samp{\+} and @samp{\?} should be avoided.
13317 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
13319 Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
13320 quite portable to modern hosts, but is not supported by some older
13321 @command{sed} implementations like SVR3.
13323 Some @command{sed} implementations, e.g., Solaris,
13324 restrict the special role of the asterisk to one-character regular expressions.
13325 This may lead to unexpected behavior:
13328 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
13330 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
13334 The @option{-e} option is portable.
13335 Some people prefer to use it:
13338 sed -e '@var{command-1}' \
13339 -e '@var{command-2}'
13343 as opposed to the equivalent:
13353 The following usage is sometimes equivalent:
13356 sed '@var{command-1};@var{command-2}'
13359 but Posix says that this use of a semicolon has undefined effect if
13360 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
13361 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
13362 should use semicolon only with simple scripts that do not use these
13365 Commands inside @{ @} brackets are further restricted. Posix says that
13366 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
13367 each command must be followed immediately by a newline, without any
13368 intervening blanks or semicolons. The closing bracket must be alone on
13369 a line, other than white space preceding or following it.
13371 Contrary to yet another urban legend, you may portably use @samp{&} in
13372 the replacement part of the @code{s} command to mean ``what was
13373 matched''. All descendants of Unix version 7 @command{sed}
13375 don't have first hand experience with older @command{sed}s) have
13378 Posix requires that you must not have any white space between
13379 @samp{!} and the following command. It is OK to have blanks between
13380 the address and the @samp{!}. For instance, on Solaris:
13383 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
13384 @error{}Unrecognized command: /bar/ ! p
13385 $ @kbd{echo "foo" | sed -n '/bar/! p'}
13386 @error{}Unrecognized command: /bar/! p
13387 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
13391 Posix also says that you should not combine @samp{!} and @samp{;}. If
13392 you use @samp{!}, it is best to put it on a command that is delimited by
13393 newlines rather than @samp{;}.
13395 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
13396 @samp{w} commands be followed by exactly one space before their argument.
13397 On the other hand, no white space is allowed between @samp{:} and the
13398 subsequent label name.
13400 @item @command{sed} (@samp{t})
13401 @c ---------------------------
13402 @prindex @command{sed} (@samp{t})
13403 Some old systems have @command{sed} that ``forget'' to reset their
13404 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
13405 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
13406 script (the line numbers are not actual part of the texts):
13409 s/keep me/kept/g # a
13445 Why? When processing line 1, (c) matches, therefore sets the @samp{t}
13446 flag, and the output is produced. When processing
13447 line 2, the @samp{t} flag is still set (this is the bug). Command (a)
13448 fails to match, but @command{sed} is not supposed to clear the @samp{t}
13449 flag when a substitution fails. Command (b) sees that the flag is set,
13450 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
13451 instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
13452 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
13453 Finally, since the flag is clear, line 4 is processed properly.
13455 There are two things one should remember about @samp{t} in @command{sed}.
13456 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
13457 succeeded, not only the immediately preceding substitution. Therefore,
13458 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
13459 line, to reset the @samp{t} flag where needed.
13461 Secondly, you cannot rely on @command{sed} to clear the flag at each new
13464 One portable implementation of the script above is:
13475 @item @command{touch}
13476 @c ------------------
13477 @prindex @command{touch}
13478 @cindex timestamp resolution
13479 If you specify the desired timestamp (e.g., with the @option{-r}
13480 option), @command{touch} typically uses the @code{utime} or
13481 @code{utimes} system call, which can result in the same kind of
13482 timestamp truncation problems that @samp{cp -p} has.
13484 On some old @acronym{BSD} systems, @command{touch} or any command that
13485 results in an empty file does not update the timestamps, so use a
13486 command like @command{echo} as a workaround.
13488 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
13489 fails to work on SunOS 4.1.3 when the empty file is on an
13490 @acronym{NFS}-mounted 4.2 volume.
13495 @node Limitations of Make
13496 @section Limitations of Make
13497 @prindex @command{make}
13498 @cindex Limitations of @command{make}
13500 @command{make} itself suffers a great number of limitations, only a few
13501 of which are listed here. First of all, remember that since commands
13502 are executed by the shell, all its weaknesses are inherited@enddots{}
13507 Posix says that the @samp{$<} construct in makefiles can be
13508 used only in inference rules and in the @samp{.DEFAULT} rule; its
13509 meaning in ordinary rules is unspecified. Solaris @command{make}
13510 for instance will replace it with the empty string. Open@acronym{BSD} (3.0 and
13511 later) @command{make} will diagnose these uses and error out.
13513 @item Command execution
13514 Since 1992 Posix has required that @command{make} must invoke
13515 each command with the equivalent of a @samp{sh -c} subshell. However,
13516 many @command{make} implementations, including @acronym{BSD} make through 2004,
13517 use @samp{sh -e -c} instead, and the @option{-e} option causes the
13518 subshell to exit immediately if a subsidiary simple-command fails. For
13519 example, the command @samp{touch T; rm -f U} will always attempt to
13520 remove @file{U} with Posix make, but incompatible
13521 @command{make} implementations skip the @command{rm} if the
13522 @command{touch} fails. One way to work around this is to reword the
13523 affected simple-commands so that they always succeed, e.g., @samp{touch
13525 However, even this approach can run into common bugs in BSD
13526 implementations of the @option{-e} option of @command{sh} and
13527 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
13528 about porting to buggy BSD shells it may be simpler to migrate
13529 complicated @command{make} actions into separate scripts.
13531 @item Leading underscore in macro names
13532 Some @command{make}s don't support leading underscores in macro names,
13533 such as on NEWS-OS 4.2R.
13536 $ @kbd{cat Makefile}
13539 all:; @@echo this is test
13541 Make: Must be a separator on rules line 2. Stop.
13542 $ @kbd{cat Makefile2}
13545 all:; @@echo this is test
13546 $ @kbd{make -f Makefile2}
13550 @item Trailing backslash in macro
13551 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
13552 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
13553 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
13554 On some versions of HP-UX, @command{make} will read multiple newlines
13555 following a backslash, continuing to the next non-empty line. For
13569 shows @code{FOO} equal to @code{one BAR = two}. Other @command{make}s
13570 sensibly let a backslash continue only to the immediately following
13573 @item Escaped newline in comments
13575 According to Posix, @file{Makefile} comments start with @code{#}
13576 and continue until an unescaped newline is reached.
13579 % @kbd{cat Makefile}
13586 % @kbd{make} # GNU make
13591 However in Real World this is not always the case. Some implementations
13592 discards anything from @code{#} up to the end of line, ignoring any
13593 trailing backslash.
13596 % @kbd{pmake} # BSD make
13597 "Makefile", line 3: Need an operator
13598 Fatal errors encountered -- cannot continue
13602 Therefore, if you want to comment out a multi-line definition, prefix each
13603 line with @code{#}, not only the first.
13613 OSF/1 4.0d's @command{make} cannot process @file{Makefile}s with lines
13614 longer than 38912 bytes. It exits with a @code{Line too long}
13615 diagnostic. A later version, Tru64 5.1's @command{make} has been
13616 reported to crash with lines around 20 kB.
13618 @item @code{make macro=value} and sub-@command{make}s.
13620 A command-line variable definition such as @code{foo=bar} overrides any
13621 definition of @code{foo} in the @file{Makefile}. Some @command{make}
13622 implementations (such as @acronym{GNU} @command{make}) will propagate this
13623 override to sub-invocations of @command{make}. Some other implementation
13624 will not pass the substitution along to sub-@command{make}s.
13627 % @kbd{cat Makefile}
13634 % @kbd{make foo=bar} # GNU make 3.79.1
13637 make[1]: Entering directory `/home/adl'
13639 make[1]: Leaving directory `/home/adl'
13640 % @kbd{pmake foo=bar} # BSD make
13646 You have a few possibilities if you do want the @code{foo=bar} override
13647 to propagate to sub-@command{make}s. One is to use the @option{-e}
13648 option, which causes all environment variables to have precedence over
13649 the @file{Makefile} macro definitions, and declare foo as an environment
13653 % @kbd{env foo=bar make -e}
13656 The @option{-e} option is propagated to sub-@command{make}s automatically,
13657 and since the environment is inherited between @command{make}
13658 invocations, the @code{foo} macro will be overridden in
13659 sub-@code{make}s as expected.
13661 This syntax (@code{foo=bar make -e}) is portable only when used
13662 outside of a @file{Makefile}, for instance from a script or from the
13663 command line. When run inside a @command{make} rule, @acronym{GNU}
13664 @command{make} 3.80 and prior versions forget to propagate the
13665 @option{-e} option to sub-@command{make}s.
13667 Moreover, using @option{-e} could have unexpected side-effects if your
13668 environment contains some other macros usually defined by the
13669 Makefile. (See also the note about @code{make -e} and @code{SHELL}
13672 Another way to propagate overrides to sub-@command{make}s is to do it
13673 manually, from your @file{Makefile}:
13679 $(MAKE) foo=$(foo) two
13684 You need to foresee all macros that a user might want to override if
13687 @item The @code{SHELL} macro
13688 @cindex @code{SHELL} and @command{make}
13689 @cindex @command{make} and @code{SHELL}
13691 Posix-compliant @command{make}s internally use the @code{$(SHELL)}
13692 macro to spawn shell processes and execute @file{Makefile} rules. This
13693 is a builtin macro supplied by @command{make}, but it can be modified
13694 from the @file{Makefile} or a command-line argument.
13696 Not all @command{make}s will define this @code{SHELL} macro. OSF/Tru64
13697 @command{make} is an example; this implementation will always use
13698 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
13699 your @file{Makefile}s. If you use Autoconf, do
13705 Do not force @code{SHELL = /bin/sh} because that is not correct
13706 everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
13707 its @acronym{GNU} @code{make} port sees such a setting it enters a special
13708 emulation mode where features like pipes and redirections are emulated
13709 on top of DOS's @command{command.com}. Unfortunately this emulation is
13710 incomplete; for instance it does not handle command substitutions.
13711 On @acronym{DJGPP} @code{SHELL} should point to Bash.
13713 Posix-compliant @command{make}s should never acquire the value of
13714 $(SHELL) from the environment, even when @code{make -e} is used
13715 (otherwise, think about what would happen to your rules if
13716 @code{SHELL=/bin/tcsh}).
13718 However not all @command{make} implementations will make this exception.
13719 For instance it's not surprising that OSF/Tru64 @command{make} doesn't
13720 protect @code{SHELL}, since it doesn't use it.
13723 % @kbd{cat Makefile}
13729 % @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # OSF1 V4.0 Make
13732 % @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
13737 @item Comments in rules
13738 @cindex Comments in @file{Makefile} rules
13739 @cindex @file{Makefile} rules and comments
13741 Never put comments in a rule.
13743 Some @command{make} treat anything starting with a tab as a command for
13744 the current rule, even if the tab is immediately followed by a @code{#}.
13745 The @command{make} from Tru64 Unix V5.1 is one of them. The following
13746 @file{Makefile} will run @code{# foo} through the shell.
13753 @item The @file{obj/} subdirectory.
13754 @cindex @file{obj/}, subdirectory
13755 @cindex @acronym{BSD} @command{make} and @file{obj/}
13757 Never name one of your subdirectories @file{obj/} if you don't like
13760 If an @file{obj/} directory exists, @acronym{BSD} @command{make} will enter it
13761 before reading @file{Makefile}. Hence the @file{Makefile} in the
13762 current directory will not be read.
13765 % @kbd{cat Makefile}
13768 % @kbd{cat obj/Makefile}
13771 % @kbd{make} # GNU make
13774 % @kbd{pmake} # BSD make
13779 @item @code{make -k}
13780 @cindex @code{make -k}
13782 Do not rely on the exit status of @code{make -k}. Some implementations
13783 reflect whether they encountered an error in their exit status; other
13784 implementations always succeed.
13787 % @kbd{cat Makefile}
13790 % @kbd{make -k; echo exit status: $?} # GNU make
13792 make: *** [all] Error 1
13794 % @kbd{pmake -k; echo exit status: $?} # BSD make
13796 *** Error code 1 (continuing)
13801 @cindex @code{VPATH}
13803 There is no @code{VPATH} support specified in Posix. Many
13804 @command{make}s have a form of @code{VPATH} support, but its
13805 implementation is not consistent amongst @command{make}s.
13807 Maybe the best suggestion to give to people who need the @code{VPATH}
13808 feature is to choose a @command{make} implementation and stick to it.
13809 Since the resulting @file{Makefile}s are not portable anyway, better
13810 choose a portable @command{make} (hint, hint).
13812 Here are a couple of known issues with some @code{VPATH}
13817 @item @code{VPATH} and double-colon rules
13818 @cindex @code{VPATH} and double-colon rules
13819 @cindex double-colon rules and @code{VPATH}
13821 Any assignment to @code{VPATH} causes Sun @command{make} to only execute
13822 the first set of double-colon rules. (This comment has been here since
13823 1994 and the context has been lost. It's probably about SunOS 4. If
13824 you can reproduce this, please send us a test case for illustration.)
13826 @item @code{$<} not supported in explicit rules
13827 @cindex explicit rules, @code{$<}, and @code{VPATH}
13828 @cindex @code{$<}, explicit rules, and @code{VPATH}
13829 @cindex @code{VPATH}, explicit rules, and @code{$<}
13831 As said elsewhere, using @code{$<} in explicit rules is not portable.
13832 The prerequisite file must be named explicitly in the rule. If you want
13833 to find the prerequisite via a @code{VPATH} search, you have to code the
13834 whole thing manually. For instance, using the following pattern:
13839 cp `test -f if.c || echo $(VPATH)/`if.c f.c
13842 @item Automatic rule rewriting
13843 @cindex @code{VPATH} and automatic rule rewriting
13844 @cindex automatic rule rewriting and @code{VPATH}
13846 Some @command{make} implementations, such as SunOS 4 @command{make} or
13847 OSF1/Tru64 @command{make}, will search prerequisites in @code{VPATH} and
13848 rewrite all their occurrences in the rule appropriately.
13859 would execute @code{cp ../pkg/src/if.c f.c} if @file{if.c} was
13860 found in @file{../pkg/src}. That sounds great.
13862 However, for the sake of other @command{make} implementations, we can't
13863 rely on this, and we have to search @code{VPATH} manually:
13868 cp `test -f if.c || echo $(VPATH)/`if.c f.c
13872 However the "prerequisite rewriting" still applies here. So if
13873 @file{if.c} is in @file{../pkg/src}, SunOS 4 @command{make} and OSF1/Tru64
13874 @command{make} will execute
13877 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
13888 and thus fails. Oops.
13890 One workaround is to make sure that @file{if.c} never appears as a plain word
13891 in the rule. For instance these three rules would be safe.
13896 cp `test -f ./if.c || echo $(VPATH)/`if.c f.c
13898 cp `test -f 'ig.c' || echo $(VPATH)/`ig.c g.c
13900 cp `test -f "ih.c" || echo $(VPATH)/`ih.c h.c
13903 Things get worse when your prerequisites are in a macro.
13907 HEADERS = f.h g.h h.h
13908 install-HEADERS: $(HEADERS)
13909 for i in $(HEADERS); do \
13910 $(INSTALL) -m 644 \
13911 `test -f $$i || echo $(VPATH)/`$$i \
13912 $(DESTDIR)$(includedir)/$$i; \
13916 The above @code{install-HEADERS} rule is not SunOS-4-proof because @code{for
13917 i in $(HEADERS);} will be expanded as @code{for i in f.h g.h h.h;}
13918 where @code{f.h} and @code{g.h} are plain words and are hence
13919 subject to @code{VPATH} adjustments.
13921 If the three files are in @file{../pkg/src}, the rule is run as:
13924 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
13926 `test -f $i || echo ../pkg/src/`$i \
13927 /usr/local/include/$i; \
13931 where the two first @command{install} calls will fail. For instance,
13932 consider the @code{f.h} installation:
13936 `test -f ../pkg/src/f.h || \
13939 /usr/local/include/../pkg/src/f.h;
13947 /usr/local/include/../pkg/src/f.h;
13950 Note that the manual @code{VPATH} search did not cause any problems here;
13951 however this command installs @file{f.h} in an incorrect directory.
13953 Trying to quote @code{$(HEADERS)} in some way, as we did for
13954 @code{foo.c} a few @file{Makefile}s ago, does not help:
13957 install-HEADERS: $(HEADERS)
13958 headers='$(HEADERS)'; \
13959 for i in $$headers; do \
13960 $(INSTALL) -m 644 \
13961 `test -f $$i || echo $(VPATH)/`$$i \
13962 $(DESTDIR)$(includedir)/$$i; \
13966 Now, @code{headers='$(HEADERS)'} macroexpands to:
13969 headers='f.h g.h h.h'
13973 but @code{g.h} is still a plain word. (As an aside, the idiom
13974 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
13975 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
13976 syntax error on @code{for i in;}.)
13978 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
13981 HEADERS = f.h g.h h.h
13982 install-HEADERS: $(HEADERS)
13983 headers='$(HEADERS)'; \
13984 for i in $$headers; do \
13985 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
13986 $(INSTALL) -m 644 \
13987 `test -f $$i || echo $(VPATH)/`$$i \
13988 $(DESTDIR)$(includedir)/$$i; \
13992 Automake does something similar. However the above hack works only if
13993 the files listed in @code{HEADERS} are in the current directory or a
13994 subdirectory; they should not be in an enclosing directory. If we had
13995 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
13996 build with OSF1/Tru64 @command{make}. The reason is that not only does
13997 OSF1/Tru64 @command{make} rewrite dependencies, but it also simplifies
13998 them. Hence @code{../f.h} will become @code{../pkg/f.h} instead of
13999 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
14000 a leading @file{../pkg/src/} component.
14002 The following example makes the behavior of OSF1/Tru64 @command{make}
14016 Dependency @file{../foo} was found in @file{sub/../foo}, but OSF1/Tru64
14017 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
14018 directory does not even exist, this just means that the simplification
14019 occurred before the file was checked for.)
14021 For the record here is how SunOS 4 @command{make} behaves on this
14025 make: Fatal error: Don't know how to make target `../foo'
14033 @item OSF/Tru64 @command{make} creates prerequisite directories magically
14034 @cindex @code{VPATH} and prerequisite directories
14035 @cindex prerequisite directories and @code{VPATH}
14037 When a prerequisite is a sub-directory of @code{VPATH}, Tru64
14038 @command{make} will create it in the current directory.
14041 % @kbd{mkdir -p foo/bar build}
14043 % @kbd{cat >Makefile <<END
14052 This can yield unexpected results if a rule uses a manual @code{VPATH}
14053 search as presented before.
14058 command `test -d foo/bar || echo ../`foo/bar
14061 The above @command{command} will be run on the empty @file{foo/bar}
14062 directory that was created in the current directory.
14064 @item target lookup
14065 @cindex @code{VPATH}, resolving target pathnames
14067 @acronym{GNU} @command{make} uses a rather complex algorithm to decide when it
14068 should use files found via a @code{VPATH} search. @xref{Search
14069 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
14072 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
14073 file name found during the @code{VPATH} search for this target, and
14074 builds the file locally using the file name given in the @file{Makefile}.
14075 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
14076 file name found during the @code{VPATH} search.
14078 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
14079 easier to describe: the file name found during the @code{VPATH} search
14080 will be used whether the target needs to be rebuilt or not. Therefore
14081 new files are created locally, but existing files are updated at their
14082 @code{VPATH} location.
14084 Open@acronym{BSD} and Free@acronym{BSD} @command{make}s, however, will
14086 @code{VPATH} search for a dependency which has an explicit rule.
14087 This is extremely annoying.
14089 When attempting a @code{VPATH} build for an autoconfiscated package
14090 (e.g., @code{mkdir build && cd build && ../configure}), this means the
14092 @command{make} will build everything locally in the @file{build}
14093 directory, while @acronym{BSD} @command{make} will build new files locally and
14094 update existing files in the source directory.
14097 % @kbd{cat Makefile}
14100 foo.x bar.x: newer.x
14101 @@echo Building $@@
14102 % @kbd{touch ../bar.x}
14103 % @kbd{touch ../newer.x}
14104 % @kbd{make} # GNU make
14107 % @kbd{pmake} # NetBSD make
14110 % @kbd{fmake} # FreeBSD make, OpenBSD make
14113 % @kbd{tmake} # Tru64 make
14116 % @kbd{touch ../bar.x}
14117 % @kbd{make} # GNU make
14119 % @kbd{pmake} # NetBSD make
14121 % @kbd{fmake} # FreeBSD make, OpenBSD make
14124 % @kbd{tmake} # Tru64 make
14129 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
14130 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
14131 @command{make} always
14132 update @file{bar.x}, even when @file{../bar.x} is up to date.
14134 Another point worth mentioning is that once @acronym{GNU} @command{make} has
14135 decided to ignore a @code{VPATH} file name (e.g., it ignored
14136 @file{../bar.x} in the above example) it will continue to ignore it when
14137 the target occurs as a prerequisite of another rule.
14139 The following example shows that @acronym{GNU} @command{make} does not look up
14140 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
14141 because it ignored the @code{VPATH} result of @file{bar.x} while running
14142 the @code{bar.x: newer.x} rule.
14145 % @kbd{cat Makefile}
14149 @@echo Building $@@
14153 % @kbd{touch ../bar.x}
14154 % @kbd{touch ../newer.x}
14155 % @kbd{make} # GNU make
14158 cp: cannot stat `bar.x': No such file or directory
14159 make: *** [bar.y] Error 1
14160 % @kbd{pmake} # NetBSD make
14164 % @kbd{fmake} # FreeBSD make, OpenBSD make
14165 echo Building bar.x
14167 cp: cannot stat `bar.x': No such file or directory
14169 % @kbd{tmake} # Tru64 make
14171 cp: bar.x: No such file or directory
14175 Note that if you drop away the command from the @code{bar.x: newer.x}
14176 rule, @acronym{GNU} @command{make} will magically start to work: it
14177 knows that @code{bar.x} hasn't been updated, therefore it doesn't
14178 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
14179 uses. Tru64 will also work, but Free@acronym{BSD} and Open@acronym{BSD}
14183 % @kbd{cat Makefile}
14190 % @kbd{touch ../bar.x}
14191 % @kbd{touch ../newer.x}
14192 % @kbd{make} # GNU make
14195 % @kbd{pmake} # NetBSD make
14198 % @kbd{fmake} # FreeBSD make, OpenBSD make
14200 cp: cannot stat `bar.x': No such file or directory
14202 % @kbd{tmake} # Tru64 make
14206 It seems the sole solution that would please every @command{make}
14207 implementation is to never rely on @code{VPATH} searches for targets.
14208 In other words, @code{VPATH} should be reserved to unbuilt sources.
14211 @c end item about VPATH
14213 @item Single Suffix Rules and Separated Dependencies
14214 @cindex Single Suffix Inference Rule
14215 @cindex Rule, Single Suffix Inference
14216 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
14217 (@samp{.from.to:}), but which @emph{destination} suffix is empty
14220 @cindex Separated Dependencies
14221 @dfn{Separated dependencies} simply refers to listing the prerequisite
14222 of a target, without defining a rule. Usually one can list on the one
14223 hand side, the rules, and on the other hand side, the dependencies.
14225 Solaris @command{make} does not support separated dependencies for
14226 targets defined by single suffix rules:
14229 $ @kbd{cat Makefile}
14234 $ @kbd{touch foo.in}
14241 while @acronym{GNU} Make does:
14247 Makefile foo foo.in
14250 Note it works without the @samp{foo: foo.in} dependency.
14253 $ @kbd{cat Makefile}
14262 and it works with double suffix inference rules:
14265 $ @kbd{cat Makefile}
14267 .SUFFIXES: .in .out
14274 As a result, in such a case, you have to write target rules.
14276 @item Timestamp Resolution
14277 @cindex timestamp resolution
14278 Traditionally, file timestamps had 1-second resolution, and
14279 @command{make} used those timestamps to determine whether one file was
14280 newer than the other. However, many modern file systems have
14281 timestamps with 1-nanosecond resolution. Some @command{make}
14282 implementations look at the entire timestamp; others ignore the
14283 fractional part, which can lead to incorrect results. Normally this
14284 is not a problem, but in some extreme cases you may need to use tricks
14285 like @samp{sleep 1} to work around timestamp truncation bugs.
14287 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
14288 file timestamps to their full resolutions (@pxref{Limitations of Usual
14289 Tools}). Hence you should be wary of rules like this:
14296 as @file{dest} will often appear to be older than @file{src} after the
14297 timestamp is truncated, and this can cause @command{make} to do
14298 needless rework the next time it is invoked. To work around this
14299 problem, you can use a timestamp file, e.g.:
14312 @c ======================================== Portable C and C++ Programming
14314 @node Portable C and C++
14315 @chapter Portable C and C++ Programming
14316 @cindex Portable C and C++ programming
14318 C and C++ programs often use low-level features of the underlying
14319 system, and therefore are often more difficult to make portable to other
14322 Several standards have been developed to help make your programs more
14323 portable. If you write programs with these standards in mind, you can
14324 have greater confidence that your programs will work on a wide variety
14325 of systems. @xref{Standards, , Language Standards Supported by GCC,
14326 gcc, Using the GNU Compiler Collection (GCC)}, for a list of C-related
14327 standards. Many programs also assume the
14328 @uref{http://www.opengroup.org/susv3, Posix standard}.
14330 Some old code is written to be portable to K&R C, which predates any C
14331 standard. K&R C compilers are no longer of practical interest, though,
14332 and the rest of section assumes at least C89, the first C standard.
14334 Program portability is a huge topic, and this section can only briefly
14335 introduce common pitfalls. @xref{System Portability, , Portability
14336 between System Types, standards, @acronym{GNU} Coding Standards}, for
14340 * Varieties of Unportability:: How to make your programs unportable
14341 * Integer Overflow:: When integers get too large
14342 * Null Pointers:: Properties of null pointers
14343 * Buffer Overruns:: Subscript errors and the like
14344 * Floating Point Portability:: Portable floating-point arithmetic
14345 * Exiting Portably:: Exiting and the exit status
14348 @node Varieties of Unportability
14349 @section Varieties of Unportability
14350 @cindex portability
14352 Autoconf tests and ordinary programs often need to test what is allowed
14353 on a system, and therefore they may need to deliberately exceed the
14354 boundaries of what the standards allow, if only to see whether an
14355 optional feature is present. When you write such a program, you should
14356 keep in mind the difference between constraints, unspecified behavior,
14357 and undefined behavior.
14359 In C, a @dfn{constraint} is a rule that the compiler must enforce. An
14360 example constraint is that C programs must not declare a bit-field with
14361 negative width. Tests can therefore reliably assume that programs with
14362 negative-width bit-fields will be rejected by a compiler that conforms
14365 @dfn{Unspecified behavior} is valid behavior, where the standard allows
14366 multiple possibilities. For example, the order of evaluation of
14367 function arguments is unspecified. Some unspecified behavior is
14368 @dfn{implementation-defined}, i.e., documented by the implementation,
14369 but since Autoconf tests cannot read the documentation they cannot
14370 distinguish between implementation-defined and other unspecified
14371 behavior. It is common for Autoconf tests to probe implementations to
14372 determine otherwise-unspecified behavior.
14374 @dfn{Undefined behavior} is invalid behavior, where the standard allows
14375 the implementation to do anything it pleases. For example,
14376 dereferencing a null pointer leads to undefined behavior. If possible,
14377 test programs should avoid undefined behavior, since a program with
14378 undefined behavior might succeed on a test that should fail.
14380 The above rules apply to programs that are intended to conform to the
14381 standard. However, strictly-conforming programs are quite rare, since
14382 the standards are so limiting. A major goal of Autoconf is to support
14383 programs that use implementation features not described by the standard,
14384 and it is fairly common for test programs to violate the above rules, if
14385 the programs work well enough in practice.
14387 @node Integer Overflow
14388 @section Integer Overflow
14389 @cindex overflow, arithmetic
14391 In C, signed integer overflow leads to undefined behavior. However,
14392 many programs and Autoconf tests assume that signed integer overflow after
14393 addition, subtraction, or multiplication silently
14394 wraps around modulo a power of two, using two's complement arithmetic,
14395 so long as you cast the resulting value
14396 to an integer type or store it into an integer variable. Such programs
14397 are portable to the vast majority of modern platforms. However, signed
14398 integer division is not always harmless: for example, on CPUs of the
14399 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
14400 which by default terminates the program.
14402 GCC users might consider using the
14403 @option{-ftrapv} option if they are worried about porting their code to
14404 the rare platforms where signed integer overflow does not wrap around
14405 after addition, subtraction, or multiplication.
14407 Unsigned integer overflow reliably wraps around modulo the word size.
14408 This is guaranteed by the C standard and is portable in practice.
14410 @node Null Pointers
14411 @section Properties of Null Pointers
14412 @cindex null pointers
14414 Most modern hosts reliably fail when you attempt to dereference a null
14417 On almost all modern hosts, null pointers use an all-bits-zero internal
14418 representation, so you can reliably use @code{memset} with 0 to set all
14419 the pointers in an array to null values.
14421 If @code{p} is a null pointer to an object type, the C expression
14422 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
14423 the standard says that it has undefined behavior.
14425 @node Buffer Overruns
14426 @section Buffer Overruns and Subscript Errors
14427 @cindex buffer overruns
14429 Buffer overruns and subscript errors are the most common dangerous
14430 errors in C programs. They result in undefined behavior because storing
14431 outside an array typically modifies storage that is used by some other
14432 object, and most modern systems lack runtime checks to catch these
14433 errors. Programs should not rely on buffer overruns being caught.
14435 There is one exception to the usual rule that a portable program cannot
14436 address outside an array. In C, it is valid to compute the address just
14437 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
14438 so long as you do not dereference the resulting pointer. But it is not
14439 valid to compute the address just before an object, e.g., @code{&a[-1]};
14440 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
14441 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
14442 reliable in general, and it is usually easy enough to avoid the
14443 potential portability problem, e.g., by allocating an extra unused array
14444 element at the start or end.
14446 @uref{http://valgrind.org/, Valgrind} can catch many overruns. GCC
14447 users might also consider using the @option{-fmudflap} option to catch
14450 Buffer overruns are usually caused by off-by-one errors, but there are
14451 more subtle ways to get them.
14453 Using @code{int} values to index into an array or compute array sizes
14454 will cause problems on typical 64-bit hosts where an array index might
14455 be @math{2^31} or larger.
14457 If you add or multiply two numbers to calculate an array size, e.g.,
14458 @code{malloc (x * sizeof y + z)}, havoc will ensue if the addition or
14459 multiplication overflows.
14461 Many implementations of the @code{alloca} function silently misbehave
14462 and can generate buffer overflows if given sizes that are too large.
14463 The size limits are implementation dependent, but are at least 4000
14464 bytes on all platforms that we know about.
14466 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
14467 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
14468 portable code should not use them unless the inputs are known to be
14469 within certain limits. The time-related functions can overflow their
14470 buffers if given time stamps out of range (e.g., a year less than -999
14471 or greater than 9999). Time-related buffer overflows cannot happen with
14472 recent-enough versions of the GNU C library, but are possible with other
14473 implementations. The @code{gets} function is the worst, since it almost
14474 invariably overflows its buffer when presented with an input line larger
14477 @node Floating Point Portability
14478 @section Floating Point Portability
14479 @cindex floating point
14481 Almost all modern systems use IEEE-754 floating point, and it is safe to
14482 assume IEEE-754 in most portable code these days. For more information,
14483 please see David Goldberg's classic paper
14484 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
14485 Scientist Should Know About Floating-Point Arithmetic}.
14487 @node Exiting Portably
14488 @section Exiting Portably
14489 @cindex exiting portably
14491 A C or C++ program can exit with status @var{N} by returning
14492 @var{N} from the @code{main} function. Portable programs are supposed
14493 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
14494 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
14495 fail by exiting with status 1, and test programs that assume Posix can
14496 fail by exiting with status values from 1 through 255. Programs on
14497 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
14498 status when @code{main} returned nonzero, but ancient systems like these
14499 are no longer of practical concern.
14501 A program can also exit with status @var{N} by passing @var{N} to the
14502 @code{exit} function, and a program can fail by calling the @code{abort}
14503 function. If a program is specialized to just some platforms, it can fail
14504 by calling functions specific to those platforms, e.g., @code{_exit}
14505 (Posix) and @code{_Exit} (C99). However, like other functions, an exit
14506 function should be declared, typically by including a header. For
14507 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
14508 either directly or via the default includes (@pxref{Default Includes}).
14510 A program can fail due to undefined behavior such as dereferencing a null
14511 pointer, but this is not recommended as undefined behavior allows an
14512 implementation to do whatever it pleases and this includes exiting
14516 @c ================================================== Manual Configuration
14518 @node Manual Configuration
14519 @chapter Manual Configuration
14521 A few kinds of features can't be guessed automatically by running test
14522 programs. For example, the details of the object-file format, or
14523 special options that need to be passed to the compiler or linker. You
14524 can check for such features using ad-hoc means, such as having
14525 @command{configure} check the output of the @code{uname} program, or
14526 looking for libraries that are unique to particular systems. However,
14527 Autoconf provides a uniform method for handling unguessable features.
14530 * Specifying Names:: Specifying the system type
14531 * Canonicalizing:: Getting the canonical system type
14532 * Using System Type:: What to do with the system type
14535 @node Specifying Names
14536 @section Specifying the System Type
14537 @cindex System type
14539 Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated
14540 @command{configure} scripts can make decisions based on a canonical name
14541 for the system type, which has the form:
14542 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
14543 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
14545 @command{configure} can usually guess the canonical name for the type of
14546 system it's running on. To do so it runs a script called
14547 @command{config.guess}, which infers the name using the @code{uname}
14548 command or symbols predefined by the C preprocessor.
14550 Alternately, the user can specify the system type with command line
14551 arguments to @command{configure}. Doing so is necessary when
14552 cross-compiling. In the most complex case of cross-compiling, three
14553 system types are involved. The options to specify them are:
14556 @item --build=@var{build-type}
14557 the type of system on which the package is being configured and
14558 compiled. It defaults to the result of running @command{config.guess}.
14560 @item --host=@var{host-type}
14561 the type of system on which the package will run. By default it is the
14562 same as the build machine. Specifying it enables the cross-compilation
14565 @item --target=@var{target-type}
14566 the type of system for which any compiler tools in the package will
14567 produce code (rarely needed). By default, it is the same as host.
14570 If you mean to override the result of @command{config.guess}, use
14571 @option{--build}, not @option{--host}, since the latter enables
14572 cross-compilation. For historical reasons, passing @option{--host} also
14573 changes the build type. Therefore, whenever you specify @option{--host},
14574 be sure to specify @option{--build} too; this will be fixed in the
14575 future. So, to enter cross-compilation mode, use a command like this
14578 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
14582 Note that if you do not specify @option{--host}, @command{configure} will
14583 fail if it can't run the code generated by the specified compiler. For
14584 example, configuring as follows will fail:
14587 ./configure CC=m68k-coff-gcc
14590 In the future, when cross-compiling Autoconf will @emph{not}
14591 accept tools (compilers, linkers, assemblers) whose name is not
14592 prefixed with the host type. The only case when this may be
14593 useful is when you really are not cross-compiling, but only
14594 building for a least-common-denominator architecture: an example
14595 is building for @code{i386-pc-linux-gnu} while running on an
14596 @code{i686-pc-linux-gnu} architecture. In this case, some particular
14597 pairs might be similar enough to let you get away with the system
14598 compilers, but in general the compiler might make bogus assumptions
14599 on the host: if you know what you are doing, please create symbolic
14600 links from the host compiler to the build compiler.
14602 @cindex @command{config.sub}
14603 @command{configure} recognizes short aliases for many system types; for
14604 example, @samp{decstation} can be used instead of
14605 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
14606 @command{config.sub} to canonicalize system type aliases.
14608 This section deliberately omits the description of the obsolete
14609 interface; see @ref{Hosts and Cross-Compilation}.
14612 @node Canonicalizing
14613 @section Getting the Canonical System Type
14614 @cindex System type
14615 @cindex Canonical system type
14617 The following macros make the system type available to @command{configure}
14620 @ovindex build_alias
14621 @ovindex host_alias
14622 @ovindex target_alias
14624 The variables @samp{build_alias}, @samp{host_alias}, and
14625 @samp{target_alias} are always exactly the arguments of @option{--build},
14626 @option{--host}, and @option{--target}; in particular, they are left empty
14627 if the user did not use them, even if the corresponding
14628 @code{AC_CANONICAL} macro was run. Any configure script may use these
14629 variables anywhere. These are the variables that should be used when in
14630 interaction with the user.
14632 If you need to recognize some special environments based on their system
14633 type, run the following macros to get canonical system names. These
14634 variables are not set before the macro call.
14636 If you use these macros, you must distribute @command{config.guess} and
14637 @command{config.sub} along with your source code. @xref{Output}, for
14638 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
14639 to control in which directory @command{configure} looks for those scripts.
14642 @defmac AC_CANONICAL_BUILD
14643 @acindex{CANONICAL_BUILD}
14646 @ovindex build_vendor
14648 Compute the canonical build-system type variable, @code{build}, and its
14649 three individual parts @code{build_cpu}, @code{build_vendor}, and
14652 If @option{--build} was specified, then @code{build} is the
14653 canonicalization of @code{build_alias} by @command{config.sub},
14654 otherwise it is determined by the shell script @command{config.guess}.
14657 @defmac AC_CANONICAL_HOST
14658 @acindex{CANONICAL_HOST}
14661 @ovindex host_vendor
14663 Compute the canonical host-system type variable, @code{host}, and its
14664 three individual parts @code{host_cpu}, @code{host_vendor}, and
14667 If @option{--host} was specified, then @code{host} is the
14668 canonicalization of @code{host_alias} by @command{config.sub},
14669 otherwise it defaults to @code{build}.
14672 @defmac AC_CANONICAL_TARGET
14673 @acindex{CANONICAL_TARGET}
14675 @ovindex target_cpu
14676 @ovindex target_vendor
14678 Compute the canonical target-system type variable, @code{target}, and its
14679 three individual parts @code{target_cpu}, @code{target_vendor}, and
14682 If @option{--target} was specified, then @code{target} is the
14683 canonicalization of @code{target_alias} by @command{config.sub},
14684 otherwise it defaults to @code{host}.
14687 Note that there can be artifacts due to the backward compatibility
14688 code. See @xref{Hosts and Cross-Compilation}, for more.
14690 @node Using System Type
14691 @section Using the System Type
14693 In @file{configure.ac} the system type is generally used by one or more
14694 @code{case} statements to select system-specifics. Shell wildcards can
14695 be used to match a group of system types.
14697 For example, an extra assembler code object file could be chosen, giving
14698 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
14699 following would be used in a @file{Makefile} to add the object to a
14700 program or library.
14704 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
14705 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
14708 AC_SUBST([CYCLE_OBJ])
14711 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
14712 to select variant source files, for example optimized code for some
14713 CPUs. The configured CPU type doesn't always indicate exact CPU types,
14714 so some runtime capability checks may be necessary too.
14718 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
14719 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
14720 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
14724 The host system type can also be used to find cross-compilation tools
14725 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
14727 The above examples all show @samp{$host}, since this is where the code
14728 is going to run. Only rarely is it necessary to test @samp{$build}
14729 (which is where the build is being done).
14731 Whenever you're tempted to use @samp{$host} it's worth considering
14732 whether some sort of probe would be better. New system types come along
14733 periodically or previously missing features are added. Well-written
14734 probes can adapt themselves to such things, but hard-coded lists of
14735 names won't. Here are some guidelines,
14739 Availability of libraries and library functions should always be checked
14742 Variant behavior of system calls is best identified with runtime tests
14743 if possible, but bug workarounds or obscure difficulties might have to
14744 be driven from @samp{$host}.
14746 Assembler code is inevitably highly CPU-specific and is best selected
14747 according to @samp{$host_cpu}.
14749 Assembler variations like underscore prefix on globals or ELF versus
14750 COFF type directives are however best determined by probing, perhaps
14751 even examining the compiler output.
14754 @samp{$target} is for use by a package creating a compiler or similar.
14755 For ordinary packages it's meaningless and should not be used. It
14756 indicates what the created compiler should generate code for, if it can
14757 cross-compile. @samp{$target} generally selects various hard-coded CPU
14758 and system conventions, since usually the compiler or tools under
14759 construction will themselves determine how the target will work.
14762 @c ===================================================== Site Configuration.
14764 @node Site Configuration
14765 @chapter Site Configuration
14767 @command{configure} scripts support several kinds of local configuration
14768 decisions. There are ways for users to specify where external software
14769 packages are, include or exclude optional features, install programs
14770 under modified names, and set default values for @command{configure}
14774 * Help Formatting:: Customizing @samp{configure --help}
14775 * External Software:: Working with other optional software
14776 * Package Options:: Selecting optional features
14777 * Pretty Help Strings:: Formatting help string
14778 * Site Details:: Configuring site details
14779 * Transforming Names:: Changing program names when installing
14780 * Site Defaults:: Giving @command{configure} local defaults
14783 @node Help Formatting
14784 @section Controlling Help Output
14786 Users will consult @samp{configure --help} to learn of configuration
14787 decisions specific to your package. By default, @command{configure}
14788 breaks this output into sections for each type of option; within each
14789 section, help strings appear in the order @file{configure.ac} defines
14795 --enable-bar include bar
14802 @defmac AC_PRESERVE_HELP_ORDER
14803 @acindex{PRESERVE_HELP_ORDER}
14805 Request an alternate @option{--help} format, in which options of all
14806 types appear together, in the order defined. Call this macro before any
14807 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
14810 Optional Features and Packages:
14812 --enable-bar include bar
14818 @node External Software
14819 @section Working With External Software
14820 @cindex External software
14822 Some packages require, or can optionally use, other software packages
14823 that are already installed. The user can give @command{configure}
14824 command line options to specify which such external software to use.
14825 The options have one of these forms:
14827 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
14830 --with-@var{package}[=@var{arg}]
14831 --without-@var{package}
14834 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
14835 instead of some other linker. @option{--with-x} means work with The X
14838 The user can give an argument by following the package name with
14839 @samp{=} and the argument. Giving an argument of @samp{no} is for
14840 packages that are used by default; it says to @emph{not} use the
14841 package. An argument that is neither @samp{yes} nor @samp{no} could
14842 include a name or number of a version of the other package, to specify
14843 more precisely which other package this program is supposed to work
14844 with. If no argument is given, it defaults to @samp{yes}.
14845 @option{--without-@var{package}} is equivalent to
14846 @option{--with-@var{package}=no}.
14848 @command{configure} scripts do not complain about
14849 @option{--with-@var{package}} options that they do not support. This
14850 behavior permits configuring a source tree containing multiple packages
14851 with a top-level @command{configure} script when the packages support
14852 different options, without spurious error messages about options that
14853 some of the packages support. An unfortunate side effect is that option
14854 spelling errors are not diagnosed. No better approach to this problem
14855 has been suggested so far.
14857 For each external software package that may be used, @file{configure.ac}
14858 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
14859 user asked to use it. Whether each package is used or not by default,
14860 and which arguments are valid, is up to you.
14862 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
14864 If the user gave @command{configure} the option @option{--with-@var{package}}
14865 or @option{--without-@var{package}}, run shell commands
14866 @var{action-if-given}. If neither option was given, run shell commands
14867 @var{action-if-not-given}. The name @var{package} indicates another
14868 software package that this program should work with. It should consist
14869 only of alphanumeric characters and dashes.
14871 The option's argument is available to the shell commands
14872 @var{action-if-given} in the shell variable @code{withval}, which is
14873 actually just the value of the shell variable @code{with_@var{package}},
14874 with any @option{-} characters changed into @samp{_}. You may use that
14875 variable instead, if you wish.
14877 The argument @var{help-string} is a description of the option that
14880 --with-readline support fancy command line editing
14884 @var{help-string} may be more than one line long, if more detail is
14885 needed. Just make sure the columns line up in @samp{configure
14886 --help}. Avoid tabs in the help string. You'll need to enclose the
14887 help string in @samp{[} and @samp{]} in order to produce the leading
14890 You should format your @var{help-string} with the macro
14891 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
14893 The following example shows how to use the @code{AC_ARG_WITH} macro in
14894 a common situation. You want to let the user decide whether to enable
14895 support for an external library (e.g., the readline library); if the user
14896 specified neither @option{--with-readline} nor @option{--without-readline},
14897 you want to enable support for readline only if the library is available
14900 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
14902 AC_ARG_WITH([readline],
14903 [AS_HELP_STRING([--with-readline],
14904 [support fancy command line editing @@<:@@default=check@@:>@@])],
14906 [with_readline=check])
14909 AS_IF([test "x$with_readline" != xno],
14910 [AC_CHECK_LIB([readline], [main],
14911 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
14912 AC_DEFINE([HAVE_LIBREADLINE], [1],
14913 [Define if you have libreadline])
14915 [if test "x$with_readline" != xcheck; then
14917 [--with-readline was given, but test for readline failed])
14922 The next example shows how to use @code{AC_ARG_WITH} to give the user the
14923 possibility to enable support for the readline library, in case it is still
14924 experimental and not well tested, and is therefore disabled by default.
14926 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
14928 AC_ARG_WITH([readline],
14929 [AS_HELP_STRING([--with-readline],
14930 [enable experimental support for readline])],
14932 [with_readline=no])
14935 AS_IF([test "x$with_readline" != xno],
14936 [AC_CHECK_LIB([readline], [main],
14937 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
14938 AC_DEFINE([HAVE_LIBREADLINE], [1],
14939 [Define if you have libreadline])
14942 [--with-readline was given, but test for readline failed])],
14946 The last example shows how to use @code{AC_ARG_WITH} to give the user the
14947 possibility to disable support for the readline library, given that it is
14948 an important feature and that it should be enabled by default.
14950 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
14952 AC_ARG_WITH([readline],
14953 [AS_HELP_STRING([--without-readline],
14954 [disable support for readline])],
14956 [with_readline=yes])
14959 AS_IF([test "x$with_readline" != xno],
14960 [AC_CHECK_LIB([readline], [main],
14961 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
14962 AC_DEFINE([HAVE_LIBREADLINE], [1],
14963 [Define if you have libreadline])
14966 [readline test failed (--without-readline to disable)])],
14970 These three examples can be easily adapted to the case where
14971 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
14972 @ref{Package Options}).
14975 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
14977 This is an obsolete version of @code{AC_ARG_WITH} that does not
14978 support providing a help string.
14981 @node Package Options
14982 @section Choosing Package Options
14983 @cindex Package options
14984 @cindex Options, package
14986 If a software package has optional compile-time features, the user can
14987 give @command{configure} command line options to specify whether to
14988 compile them. The options have one of these forms:
14990 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
14993 --enable-@var{feature}[=@var{arg}]
14994 --disable-@var{feature}
14997 These options allow users to choose which optional features to build and
14998 install. @option{--enable-@var{feature}} options should never make a
14999 feature behave differently or cause one feature to replace another.
15000 They should only cause parts of the program to be built rather than left
15003 The user can give an argument by following the feature name with
15004 @samp{=} and the argument. Giving an argument of @samp{no} requests
15005 that the feature @emph{not} be made available. A feature with an
15006 argument looks like @option{--enable-debug=stabs}. If no argument is
15007 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
15008 equivalent to @option{--enable-@var{feature}=no}.
15010 @command{configure} scripts do not complain about
15011 @option{--enable-@var{feature}} options that they do not support.
15012 This behavior permits configuring a source tree containing multiple
15013 packages with a top-level @command{configure} script when the packages
15014 support different options, without spurious error messages about options
15015 that some of the packages support.
15016 An unfortunate side effect is that option spelling errors are not diagnosed.
15017 No better approach to this problem has been suggested so far.
15019 For each optional feature, @file{configure.ac} should call
15020 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
15021 to include it. Whether each feature is included or not by default, and
15022 which arguments are valid, is up to you.
15024 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15025 @acindex{ARG_ENABLE}
15026 If the user gave @command{configure} the option
15027 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
15028 shell commands @var{action-if-given}. If neither option was given, run
15029 shell commands @var{action-if-not-given}. The name @var{feature}
15030 indicates an optional user-level facility. It should consist only of
15031 alphanumeric characters and dashes.
15033 The option's argument is available to the shell commands
15034 @var{action-if-given} in the shell variable @code{enableval}, which is
15035 actually just the value of the shell variable
15036 @code{enable_@var{feature}}, with any @option{-} characters changed into
15037 @samp{_}. You may use that variable instead, if you wish. The
15038 @var{help-string} argument is like that of @code{AC_ARG_WITH}
15039 (@pxref{External Software}).
15041 You should format your @var{help-string} with the macro
15042 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15044 See the examples suggested with the definition of @code{AC_ARG_WITH}
15045 (@pxref{External Software}) to get an idea of possible applications of
15046 @code{AC_ARG_ENABLE}.
15049 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
15051 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
15052 support providing a help string.
15056 @node Pretty Help Strings
15057 @section Making Your Help Strings Look Pretty
15058 @cindex Help strings
15060 Properly formatting the @samp{help strings} which are used in
15061 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
15062 (@pxref{Package Options}) can be challenging. Specifically, you want
15063 your own @samp{help strings} to line up in the appropriate columns of
15064 @samp{configure --help} just like the standard Autoconf @samp{help
15065 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
15067 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
15068 @acindex{HELP_STRING}
15070 Expands into an help string that looks pretty when the user executes
15071 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
15072 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
15073 Options}). The following example will make this clearer.
15077 [AS_HELP_STRING([--with-foo],
15078 [use foo (default is no)])],
15079 [use_foo=$withval],
15083 The second argument of @code{AS_HELP_STRING} is
15084 not a literal, and should not be double quoted.
15085 @xref{Autoconf Language}, for a more detailed explanation.
15086 Then the last few lines of @samp{configure --help} will appear like
15090 --enable and --with options recognized:
15091 --with-foo use foo (default is no)
15094 The @code{AS_HELP_STRING} macro is particularly helpful when the
15095 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
15096 arguments, as shown in the following example.
15099 AC_DEFUN([MY_ARG_WITH],
15101 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
15102 [use_[]$1=$withval],
15109 @section Configuring Site Details
15110 @cindex Site details
15112 Some software packages require complex site-specific information. Some
15113 examples are host names to use for certain services, company names, and
15114 email addresses to contact. Since some configuration scripts generated
15115 by Metaconfig ask for such information interactively, people sometimes
15116 wonder how to get that information in Autoconf-generated configuration
15117 scripts, which aren't interactive.
15119 Such site configuration information should be put in a file that is
15120 edited @emph{only by users}, not by programs. The location of the file
15121 can either be based on the @code{prefix} variable, or be a standard
15122 location such as the user's home directory. It could even be specified
15123 by an environment variable. The programs should examine that file at
15124 runtime, rather than at compile time. Runtime configuration is more
15125 convenient for users and makes the configuration process simpler than
15126 getting the information while configuring. @xref{Directory Variables, ,
15127 Variables for Installation Directories, standards, @acronym{GNU} Coding
15128 Standards}, for more information on where to put data files.
15130 @node Transforming Names
15131 @section Transforming Program Names When Installing
15132 @cindex Transforming program names
15133 @cindex Program names, transforming
15135 Autoconf supports changing the names of programs when installing them.
15136 In order to use these transformations, @file{configure.ac} must call the
15137 macro @code{AC_ARG_PROGRAM}.
15139 @defmac AC_ARG_PROGRAM
15140 @acindex{ARG_PROGRAM}
15141 @ovindex program_transform_name
15142 Place in output variable @code{program_transform_name} a sequence of
15143 @code{sed} commands for changing the names of installed programs.
15145 If any of the options described below are given to @command{configure},
15146 program names are transformed accordingly. Otherwise, if
15147 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
15148 is given, the target type followed by a dash is used as a prefix.
15149 Otherwise, no program name transformation is done.
15153 * Transformation Options:: @command{configure} options to transform names
15154 * Transformation Examples:: Sample uses of transforming names
15155 * Transformation Rules:: @file{Makefile} uses of transforming names
15158 @node Transformation Options
15159 @subsection Transformation Options
15161 You can specify name transformations by giving @command{configure} these
15162 command line options:
15165 @item --program-prefix=@var{prefix}
15166 prepend @var{prefix} to the names;
15168 @item --program-suffix=@var{suffix}
15169 append @var{suffix} to the names;
15171 @item --program-transform-name=@var{expression}
15172 perform @code{sed} substitution @var{expression} on the names.
15175 @node Transformation Examples
15176 @subsection Transformation Examples
15178 These transformations are useful with programs that can be part of a
15179 cross-compilation development environment. For example, a
15180 cross-assembler running on a Sun 4 configured with
15181 @option{--target=i960-vxworks} is normally installed as
15182 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
15183 with a native Sun 4 assembler.
15185 You can force a program name to begin with @file{g}, if you don't want
15186 @acronym{GNU} programs installed on your system to shadow other programs with
15187 the same name. For example, if you configure @acronym{GNU} @code{diff} with
15188 @option{--program-prefix=g}, then when you run @samp{make install} it is
15189 installed as @file{/usr/local/bin/gdiff}.
15191 As a more sophisticated example, you could use
15194 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
15198 to prepend @samp{g} to most of the program names in a source tree,
15199 excepting those like @code{gdb} that already have one and those like
15200 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
15201 assuming that you have a source tree containing those programs that is
15202 set up to use this feature.)
15204 One way to install multiple versions of some programs simultaneously is
15205 to append a version number to the name of one or both. For example, if
15206 you want to keep Autoconf version 1 around for awhile, you can configure
15207 Autoconf version 2 using @option{--program-suffix=2} to install the
15208 programs as @file{/usr/local/bin/autoconf2},
15209 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
15210 that only the binaries are renamed, therefore you'd have problems with
15211 the library files which might overlap.
15213 @node Transformation Rules
15214 @subsection Transformation Rules
15216 Here is how to use the variable @code{program_transform_name} in a
15217 @file{Makefile.in}:
15220 PROGRAMS = cp ls rm
15221 transform = @@program_transform_name@@
15223 for p in $(PROGRAMS); do \
15224 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
15225 sed '$(transform)'`; \
15229 for p in $(PROGRAMS); do \
15230 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
15234 It is guaranteed that @code{program_transform_name} is never empty, and
15235 that there are no useless separators. Therefore you may safely embed
15236 @code{program_transform_name} within a sed program using @samp{;}:
15239 transform = @@program_transform_name@@
15240 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
15243 Whether to do the transformations on documentation files (Texinfo or
15244 @code{man}) is a tricky question; there seems to be no perfect answer,
15245 due to the several reasons for name transforming. Documentation is not
15246 usually particular to a specific architecture, and Texinfo files do not
15247 conflict with system documentation. But they might conflict with
15248 earlier versions of the same files, and @code{man} pages sometimes do
15249 conflict with system documentation. As a compromise, it is probably
15250 best to do name transformations on @code{man} pages but not on Texinfo
15253 @node Site Defaults
15254 @section Setting Site Defaults
15255 @cindex Site defaults
15257 Autoconf-generated @command{configure} scripts allow your site to provide
15258 default values for some configuration values. You do this by creating
15259 site- and system-wide initialization files.
15261 @evindex CONFIG_SITE
15262 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
15263 uses its value as the name of a shell script to read. Otherwise, it
15264 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
15265 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
15266 settings in machine-specific files override those in machine-independent
15267 ones in case of conflict.
15269 Site files can be arbitrary shell scripts, but only certain kinds of
15270 code are really appropriate to be in them. Because @command{configure}
15271 reads any cache file after it has read any site files, a site file can
15272 define a default cache file to be shared between all Autoconf-generated
15273 @command{configure} scripts run on that system (@pxref{Cache Files}). If
15274 you set a default cache file in a site file, it is a good idea to also
15275 set the output variable @code{CC} in that site file, because the cache
15276 file is only valid for a particular compiler, but many systems have
15279 You can examine or override the value set by a command line option to
15280 @command{configure} in a site file; options set shell variables that have
15281 the same names as the options, with any dashes turned into underscores.
15282 The exceptions are that @option{--without-} and @option{--disable-} options
15283 are like giving the corresponding @option{--with-} or @option{--enable-}
15284 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
15285 sets the variable @code{cache_file} to the value @samp{localcache};
15286 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
15287 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
15288 variable @code{prefix} to the value @samp{/usr}; etc.
15290 Site files are also good places to set default values for other output
15291 variables, such as @code{CFLAGS}, if you need to give them non-default
15292 values: anything you would normally do, repetitively, on the command
15293 line. If you use non-default values for @var{prefix} or
15294 @var{exec_prefix} (wherever you locate the site file), you can set them
15295 in the site file if you specify it with the @code{CONFIG_SITE}
15296 environment variable.
15298 You can set some cache values in the site file itself. Doing this is
15299 useful if you are cross-compiling, where it is impossible to check features
15300 that require running a test program. You could ``prime the cache'' by
15301 setting those values correctly for that system in
15302 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
15303 variables you need to set, look for shell variables with @samp{_cv_} in
15304 their names in the affected @command{configure} scripts, or in the Autoconf
15305 M4 source code for those macros.
15307 The cache file is careful to not override any variables set in the site
15308 files. Similarly, you should not override command-line options in the
15309 site files. Your code should check that variables such as @code{prefix}
15310 and @code{cache_file} have their default values (as set near the top of
15311 @command{configure}) before changing them.
15313 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
15314 command @samp{configure --prefix=/usr/share/local/gnu} would read this
15315 file (if @code{CONFIG_SITE} is not set to a different file).
15318 # config.site for configure
15320 # Change some defaults.
15321 test "$prefix" = NONE && prefix=/usr/share/local/gnu
15322 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
15323 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
15324 test "$localstatedir" = '$prefix/var' && localstatedir=/var
15326 # Give Autoconf 2.x generated configure scripts a shared default
15327 # cache file for feature test results, architecture-specific.
15328 if test "$cache_file" = /dev/null; then
15329 cache_file="$prefix/var/config.cache"
15330 # A cache file is only valid for one C compiler.
15336 @c ============================================== Running configure Scripts.
15338 @node Running configure Scripts
15339 @chapter Running @command{configure} Scripts
15340 @cindex @command{configure}
15342 Below are instructions on how to configure a package that uses a
15343 @command{configure} script, suitable for inclusion as an @file{INSTALL}
15344 file in the package. A plain-text version of @file{INSTALL} which you
15345 may use comes with Autoconf.
15348 * Basic Installation:: Instructions for typical cases
15349 * Compilers and Options:: Selecting compilers and optimization
15350 * Multiple Architectures:: Compiling for multiple architectures at once
15351 * Installation Names:: Installing in different directories
15352 * Optional Features:: Selecting optional features
15353 * System Type:: Specifying the system type
15354 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
15355 * Defining Variables:: Specifying the compiler etc.
15356 * configure Invocation:: Changing how @command{configure} runs
15360 @include install.texi
15363 @c ============================================== Recreating a Configuration
15365 @node config.status Invocation
15366 @chapter Recreating a Configuration
15367 @cindex @command{config.status}
15369 The @command{configure} script creates a file named @file{config.status},
15370 which actually configures, @dfn{instantiates}, the template files. It
15371 also records the configuration options that were specified when the
15372 package was last configured in case reconfiguring is needed.
15376 ./config.status @var{option}@dots{} [@var{file}@dots{}]
15379 It configures the @var{files}; if none are specified, all the templates
15380 are instantiated. The files must be specified without their
15381 dependencies, as in
15384 ./config.status foobar
15391 ./config.status foobar:foo.in:bar.in
15394 The supported @var{option}s are:
15399 Print a summary of the command line options, the list of the template
15404 Print the version number of Autoconf and exit.
15409 Do not print progress messages.
15413 Don't remove the temporary files.
15415 @item --file=@var{file}[:@var{template}]
15416 Require that @var{file} be instantiated as if
15417 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
15418 @var{file} and @var{template} may be @samp{-} in which case the standard
15419 output and/or standard input, respectively, is used. If a
15420 @var{template} file name is relative, it is first looked for in the build
15421 tree, and then in the source tree. @xref{Configuration Actions}, for
15424 This option and the following ones provide one way for separately
15425 distributed packages to share the values computed by @command{configure}.
15426 Doing so can be useful if some of the packages need a superset of the
15427 features that one of them, perhaps a common library, does. These
15428 options allow a @file{config.status} file to create files other than the
15429 ones that its @file{configure.ac} specifies, so it can be used for a
15432 @item --header=@var{file}[:@var{template}]
15433 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
15436 Ask @file{config.status} to update itself and exit (no instantiation).
15437 This option is useful if you change @command{configure}, so that the
15438 results of some tests might be different from the previous run. The
15439 @option{--recheck} option re-runs @command{configure} with the same arguments
15440 you used before, plus the @option{--no-create} option, which prevents
15441 @command{configure} from running @file{config.status} and creating
15442 @file{Makefile} and other files, and the @option{--no-recursion} option,
15443 which prevents @command{configure} from running other @command{configure}
15444 scripts in subdirectories. (This is so other @file{Makefile} rules can
15445 run @file{config.status} when it changes; @pxref{Automatic Remaking},
15449 @file{config.status} checks several optional environment variables that
15450 can alter its behavior:
15452 @defvar CONFIG_SHELL
15453 @evindex CONFIG_SHELL
15454 The shell with which to run @command{configure} for the @option{--recheck}
15455 option. It must be Bourne-compatible. The default is a shell that
15456 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
15457 Invoking @command{configure} by hand bypasses this setting, so you may
15458 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
15459 to insure that the same shell is used everywhere. The absolute name of the
15460 shell should be passed.
15463 @defvar CONFIG_STATUS
15464 @evindex CONFIG_STATUS
15465 The file name to use for the shell script that records the
15466 configuration. The default is @file{./config.status}. This variable is
15467 useful when one package uses parts of another and the @command{configure}
15468 scripts shouldn't be merged because they are maintained separately.
15471 You can use @file{./config.status} in your Makefiles. For example, in
15472 the dependencies given above (@pxref{Automatic Remaking}),
15473 @file{config.status} is run twice when @file{configure.ac} has changed.
15474 If that bothers you, you can make each run only regenerate the files for
15479 stamp-h: config.h.in config.status
15480 ./config.status config.h
15483 Makefile: Makefile.in config.status
15484 ./config.status Makefile
15488 The calling convention of @file{config.status} has changed; see
15489 @ref{Obsolete config.status Use}, for details.
15492 @c =================================================== Obsolete Constructs
15494 @node Obsolete Constructs
15495 @chapter Obsolete Constructs
15496 @cindex Obsolete constructs
15498 Autoconf changes, and throughout the years some constructs have been
15499 obsoleted. Most of the changes involve the macros, but in some cases
15500 the tools themselves, or even some concepts, are now considered
15503 You may completely skip this chapter if you are new to Autoconf. Its
15504 intention is mainly to help maintainers updating their packages by
15505 understanding how to move to more modern constructs.
15508 * Obsolete config.status Use:: Different calling convention
15509 * acconfig.h:: Additional entries in @file{config.h.in}
15510 * autoupdate Invocation:: Automatic update of @file{configure.ac}
15511 * Obsolete Macros:: Backward compatibility macros
15512 * Autoconf 1:: Tips for upgrading your files
15513 * Autoconf 2.13:: Some fresher tips
15516 @node Obsolete config.status Use
15517 @section Obsolete @file{config.status} Invocation
15519 @file{config.status} now supports arguments to specify the files to
15520 instantiate; see @ref{config.status Invocation}, for more details.
15521 Before, environment variables had to be used.
15523 @defvar CONFIG_COMMANDS
15524 @evindex CONFIG_COMMANDS
15525 The tags of the commands to execute. The default is the arguments given
15526 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
15527 @file{configure.ac}.
15530 @defvar CONFIG_FILES
15531 @evindex CONFIG_FILES
15532 The files in which to perform @samp{@@@var{variable}@@} substitutions.
15533 The default is the arguments given to @code{AC_OUTPUT} and
15534 @code{AC_CONFIG_FILES} in @file{configure.ac}.
15537 @defvar CONFIG_HEADERS
15538 @evindex CONFIG_HEADERS
15539 The files in which to substitute C @code{#define} statements. The
15540 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
15541 macro was not called, @file{config.status} ignores this variable.
15544 @defvar CONFIG_LINKS
15545 @evindex CONFIG_LINKS
15546 The symbolic links to establish. The default is the arguments given to
15547 @code{AC_CONFIG_LINKS}; if that macro was not called,
15548 @file{config.status} ignores this variable.
15551 In @ref{config.status Invocation}, using this old interface, the example
15557 stamp-h: config.h.in config.status
15558 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
15559 CONFIG_HEADERS=config.h ./config.status
15562 Makefile: Makefile.in config.status
15563 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
15564 CONFIG_FILES=Makefile ./config.status
15569 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
15570 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
15571 for @code{CONFIG_COMMANDS}, etc.)
15575 @section @file{acconfig.h}
15577 @cindex @file{acconfig.h}
15578 @cindex @file{config.h.top}
15579 @cindex @file{config.h.bot}
15581 In order to produce @file{config.h.in}, @command{autoheader} needs to
15582 build or to find templates for each symbol. Modern releases of Autoconf
15583 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
15584 Macros}), but in older releases a file, @file{acconfig.h}, contained the
15585 list of needed templates. @command{autoheader} copied comments and
15586 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
15587 the current directory, if present. This file used to be mandatory if
15588 you @code{AC_DEFINE} any additional symbols.
15590 Modern releases of Autoconf also provide @code{AH_TOP} and
15591 @code{AH_BOTTOM} if you need to prepend/append some information to
15592 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
15593 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
15594 @command{autoheader} copies the lines before the line containing
15595 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
15596 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
15597 @command{autoheader} copies the lines after that line to the end of the
15598 file it generates. Either or both of those strings may be omitted. An
15599 even older alternate way to produce the same effect in ancient versions
15600 of Autoconf is to create the files @file{@var{file}.top} (typically
15601 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
15602 directory. If they exist, @command{autoheader} copies them to the
15603 beginning and end, respectively, of its output.
15605 In former versions of Autoconf, the files used in preparing a software
15606 package for distribution were:
15609 configure.ac --. .------> autoconf* -----> configure
15611 [aclocal.m4] --+ `---.
15613 +--> [autoheader*] -> [config.h.in]
15614 [acconfig.h] ----. |
15621 Using only the @code{AH_} macros, @file{configure.ac} should be
15622 self-contained, and should not depend upon @file{acconfig.h} etc.
15625 @node autoupdate Invocation
15626 @section Using @command{autoupdate} to Modernize @file{configure.ac}
15627 @cindex @command{autoupdate}
15629 The @command{autoupdate} program updates a @file{configure.ac} file that
15630 calls Autoconf macros by their old names to use the current macro names.
15631 In version 2 of Autoconf, most of the macros were renamed to use a more
15632 uniform and descriptive naming scheme. @xref{Macro Names}, for a
15633 description of the new scheme. Although the old names still work
15634 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
15635 new names), you can make your @file{configure.ac} files more readable
15636 and make it easier to use the current Autoconf documentation if you
15637 update them to use the new macro names.
15639 @evindex SIMPLE_BACKUP_SUFFIX
15640 If given no arguments, @command{autoupdate} updates @file{configure.ac},
15641 backing up the original version with the suffix @file{~} (or the value
15642 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
15643 set). If you give @command{autoupdate} an argument, it reads that file
15644 instead of @file{configure.ac} and writes the updated file to the
15648 @command{autoupdate} accepts the following options:
15653 Print a summary of the command line options and exit.
15657 Print the version number of Autoconf and exit.
15661 Report processing steps.
15665 Don't remove the temporary files.
15669 Force the update even if the file has not changed. Disregard the cache.
15671 @item --include=@var{dir}
15672 @itemx -I @var{dir}
15673 Also look for input files in @var{dir}. Multiple invocations accumulate.
15674 Directories are browsed from last to first.
15677 @node Obsolete Macros
15678 @section Obsolete Macros
15680 Several macros are obsoleted in Autoconf, for various reasons (typically
15681 they failed to quote properly, couldn't be extended for more recent
15682 issues, etc.). They are still supported, but deprecated: their use
15685 During the jump from Autoconf version 1 to version 2, most of the
15686 macros were renamed to use a more uniform and descriptive naming scheme,
15687 but their signature did not change. @xref{Macro Names}, for a
15688 description of the new naming scheme. Below, if there is just the mapping
15689 from old names to new names for these macros, the reader is invited to
15690 refer to the definition of the new macro for the signature and the
15695 @code{AC_FUNC_ALLOCA}
15698 @defmac AC_ARG_ARRAY
15699 @acindex{ARG_ARRAY}
15700 removed because of limited usefulness
15705 This macro is obsolete; it does nothing.
15708 @defmac AC_C_LONG_DOUBLE
15709 @acindex{C_LONG_DOUBLE}
15710 @cvindex HAVE_LONG_DOUBLE
15711 If the C compiler supports a working @code{long double} type with more
15712 range or precision than the @code{double} type, define
15713 @code{HAVE_LONG_DOUBLE}.
15715 You should use @code{AC_TYPE_LONG_DOUBLE} or
15716 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
15719 @defmac AC_CANONICAL_SYSTEM
15720 @acindex{CANONICAL_SYSTEM}
15721 Determine the system type and set output variables to the names of the
15722 canonical system types. @xref{Canonicalizing}, for details about the
15723 variables this macro sets.
15725 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
15726 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
15727 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
15731 @defmac AC_CHAR_UNSIGNED
15732 @acindex{CHAR_UNSIGNED}
15733 @code{AC_C_CHAR_UNSIGNED}
15736 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
15737 @acindex{CHECK_TYPE}
15738 Autoconf, up to 2.13, used to provide this version of
15739 @code{AC_CHECK_TYPE}, deprecated because of its flaws. Firstly, although
15740 it is a member of the @code{CHECK} clan, singular sub-family, it does
15741 more than just checking. Secondly, missing types are not
15742 @code{typedef}'d, they are @code{#define}'d, which can lead to
15743 incompatible code in the case of pointer types.
15745 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
15746 @ref{Generic Types}, for the description of the current macro.
15748 If the type @var{type} is not defined, define it to be the C (or C++)
15749 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
15751 This macro is equivalent to:
15754 AC_CHECK_TYPE([@var{type}], [],
15755 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
15756 [Define to `@var{default}'
15757 if <sys/types.h> does not define.])])
15760 In order to keep backward compatibility, the two versions of
15761 @code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
15765 If there are three or four arguments, the modern version is used.
15768 If the second argument appears to be a C or C++ type, then the
15769 obsolete version is used. This happens if the argument is a C or C++
15770 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
15771 followed by one of @samp{[(* } and then by a string of zero or more
15772 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
15775 If the second argument is spelled with the alphabet of valid C and C++
15776 types, the user is warned and the modern version is used.
15779 Otherwise, the modern version is used.
15783 You are encouraged either to use a valid builtin type, or to use the
15784 equivalent modern code (see above), or better yet, to use
15785 @code{AC_CHECK_TYPES} together with
15789 typedef loff_t off_t;
15793 @c end of AC_CHECK_TYPE
15795 @defmac AC_CHECKING (@var{feature-description})
15797 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
15800 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
15801 @acindex{COMPILE_CHECK}
15802 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
15803 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
15804 addition that it prints @samp{checking for @var{echo-text}} to the
15805 standard output first, if @var{echo-text} is non-empty. Use
15806 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
15807 messages (@pxref{Printing Messages}).
15815 @defmac AC_CROSS_CHECK
15816 @acindex{CROSS_CHECK}
15817 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
15823 Check for the Cygwin environment in which case the shell variable
15824 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
15825 means to check the nature of the host is using
15826 @code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as:
15829 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
15831 *cygwin* ) CYGWIN=yes;;
15836 Beware that the variable @code{CYGWIN} has a very special meaning when
15837 running Cygwin, and should not be changed. That's yet another reason
15838 not to use this macro.
15841 @defmac AC_DECL_SYS_SIGLIST
15842 @acindex{DECL_SYS_SIGLIST}
15843 @cvindex SYS_SIGLIST_DECLARED
15847 AC_CHECK_DECLS([sys_siglist], [], [],
15848 [#include <signal.h>
15849 /* NetBSD declares sys_siglist in unistd.h. */
15851 # include <unistd.h>
15857 @defmac AC_DECL_YYTEXT
15858 @acindex{DECL_YYTEXT}
15859 Does nothing, now integrated in @code{AC_PROG_LEX}.
15862 @defmac AC_DIR_HEADER
15863 @acindex{DIR_HEADER}
15868 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
15869 but defines a different set of C preprocessor macros to indicate which
15870 header file is found:
15872 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
15873 @item Header @tab Old Symbol @tab New Symbol
15874 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
15875 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
15876 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
15877 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
15881 @defmac AC_DYNIX_SEQ
15882 @acindex{DYNIX_SEQ}
15883 If on DYNIX/ptx, add @option{-lseq} to output variable
15884 @code{LIBS}. This macro used to be defined as
15887 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
15891 now it is just @code{AC_FUNC_GETMNTENT}.
15897 Defined the output variable @code{EXEEXT} based on the output of the
15898 compiler, which is now done automatically. Typically set to empty
15899 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
15904 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
15905 and sets @code{EMXOS2}.
15910 @code{AC_MSG_ERROR}
15918 @defmac AC_FIND_XTRA
15919 @acindex{FIND_XTRA}
15920 @code{AC_PATH_XTRA}
15925 @code{m4_foreach_w}
15928 @defmac AC_FUNC_CHECK
15929 @acindex{FUNC_CHECK}
15930 @code{AC_CHECK_FUNC}
15933 @defmac AC_FUNC_WAIT3
15934 @acindex{FUNC_WAIT3}
15935 @cvindex HAVE_WAIT3
15936 If @code{wait3} is found and fills in the contents of its third argument
15937 (a @samp{struct rusage *}), which HP-UX does not do, define
15940 These days portable programs should use @code{waitpid}, not
15941 @code{wait3}, as @code{wait3} has been removed from Posix.
15944 @defmac AC_GCC_TRADITIONAL
15945 @acindex{GCC_TRADITIONAL}
15946 @code{AC_PROG_GCC_TRADITIONAL}
15949 @defmac AC_GETGROUPS_T
15950 @acindex{GETGROUPS_T}
15951 @code{AC_TYPE_GETGROUPS}
15954 @defmac AC_GETLOADAVG
15955 @acindex{GETLOADAVG}
15956 @code{AC_FUNC_GETLOADAVG}
15959 @defmac AC_HAVE_FUNCS
15960 @acindex{HAVE_FUNCS}
15961 @code{AC_CHECK_FUNCS}
15964 @defmac AC_HAVE_HEADERS
15965 @acindex{HAVE_HEADERS}
15966 @code{AC_CHECK_HEADERS}
15969 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
15970 @acindex{HAVE_LIBRARY}
15971 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
15972 @var{function} argument of @code{main}. In addition, @var{library} can
15973 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
15974 all of those cases, the compiler is passed @option{-lfoo}. However,
15975 @var{library} cannot be a shell variable; it must be a literal name.
15978 @defmac AC_HAVE_POUNDBANG
15979 @acindex{HAVE_POUNDBANG}
15980 @code{AC_SYS_INTERPRETER} (different calling convention)
15983 @defmac AC_HEADER_CHECK
15984 @acindex{HEADER_CHECK}
15985 @code{AC_CHECK_HEADER}
15988 @defmac AC_HEADER_EGREP
15989 @acindex{HEADER_EGREP}
15990 @code{AC_EGREP_HEADER}
15993 @defmac AC_HELP_STRING
15994 @acindex{HELP_STRING}
15995 @code{AS_HELP_STRING}
15998 @defmac AC_INIT (@var{unique-file-in-source-dir})
16000 Formerly @code{AC_INIT} used to have a single argument, and was
16005 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
16014 @defmac AC_INT_16_BITS
16015 @acindex{INT_16_BITS}
16016 @cvindex INT_16_BITS
16017 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
16018 Use @samp{AC_CHECK_SIZEOF(int)} instead.
16021 @defmac AC_IRIX_SUN
16023 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
16024 @code{LIBS}. If you were using it to get @code{getmntent}, use
16025 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
16026 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
16027 getpwnam)}. Up to Autoconf 2.13, it used to be
16030 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
16034 now it is defined as
16038 AC_CHECK_LIB([sun], [getpwnam])
16044 Same as @samp{AC_LANG([C])}.
16047 @defmac AC_LANG_CPLUSPLUS
16048 @acindex{LANG_CPLUSPLUS}
16049 Same as @samp{AC_LANG([C++])}.
16052 @defmac AC_LANG_FORTRAN77
16053 @acindex{LANG_FORTRAN77}
16054 Same as @samp{AC_LANG([Fortran 77])}.
16057 @defmac AC_LANG_RESTORE
16058 @acindex{LANG_RESTORE}
16059 Select the @var{language} that is saved on the top of the stack, as set
16060 by @code{AC_LANG_SAVE}, remove it from the stack, and call
16061 @code{AC_LANG(@var{language})}.
16064 @defmac AC_LANG_SAVE
16065 @acindex{LANG_SAVE}
16066 Remember the current language (as set by @code{AC_LANG}) on a stack.
16067 The current language does not change. @code{AC_LANG_PUSH} is preferred.
16070 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
16071 @acindex{LINK_FILES}
16072 This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
16076 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
16084 AC_CONFIG_LINKS([host.h:config/$machine.h
16085 object.h:config/$obj_format.h])
16091 @code{AC_PROG_LN_S}
16094 @defmac AC_LONG_64_BITS
16095 @acindex{LONG_64_BITS}
16096 @cvindex LONG_64_BITS
16097 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
16098 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
16101 @defmac AC_LONG_DOUBLE
16102 @acindex{LONG_DOUBLE}
16103 If the C compiler supports a working @code{long double} type with more
16104 range or precision than the @code{double} type, define
16105 @code{HAVE_LONG_DOUBLE}.
16107 You should use @code{AC_TYPE_LONG_DOUBLE} or
16108 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
16111 @defmac AC_LONG_FILE_NAMES
16112 @acindex{LONG_FILE_NAMES}
16113 @code{AC_SYS_LONG_FILE_NAMES}
16116 @defmac AC_MAJOR_HEADER
16117 @acindex{MAJOR_HEADER}
16118 @code{AC_HEADER_MAJOR}
16121 @defmac AC_MEMORY_H
16123 @cvindex NEED_MEMORY_H
16124 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
16125 defined in @file{memory.h}. Today it is equivalent to
16126 @samp{AC_CHECK_HEADERS([memory.h])}. Adjust your code to depend upon
16127 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
16133 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
16134 environment and sets @code{MINGW32}.
16137 @defmac AC_MINUS_C_MINUS_O
16138 @acindex{MINUS_C_MINUS_O}
16139 @code{AC_PROG_CC_C_O}
16144 @code{AC_FUNC_MMAP}
16149 @code{AC_TYPE_MODE_T}
16155 Defined the output variable @code{OBJEXT} based on the output of the
16156 compiler, after .c files have been excluded. Typically set to @samp{o}
16157 if Posix, @samp{obj} if a @acronym{DOS} variant.
16158 Now the compiler checking macros handle
16159 this automatically.
16162 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
16164 Make M4 print a message to the standard error output warning that
16165 @var{this-macro-name} is obsolete, and giving the file and line number
16166 where it was called. @var{this-macro-name} should be the name of the
16167 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
16168 it is printed at the end of the warning message; for example, it can be
16169 a suggestion for what to use instead of @var{this-macro-name}.
16174 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
16177 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
16178 services to the user.
16183 @code{AC_TYPE_OFF_T}
16186 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
16188 The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted
16189 interface is equivalent to:
16193 AC_CONFIG_FILES(@var{file}@dots{})
16194 AC_CONFIG_COMMANDS([default],
16195 @var{extra-cmds}, @var{init-cmds})
16201 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
16202 @acindex{OUTPUT_COMMANDS}
16203 Specify additional shell commands to run at the end of
16204 @file{config.status}, and shell commands to initialize any variables
16205 from @command{configure}. This macro may be called multiple times. It is
16206 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
16208 Here is an unrealistic example:
16212 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
16214 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
16218 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
16219 additional key, an important difference is that
16220 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
16221 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
16222 can safely be given macro calls as arguments:
16225 AC_CONFIG_COMMANDS(foo, [my_FOO()])
16229 Conversely, where one level of quoting was enough for literal strings
16230 with @code{AC_OUTPUT_COMMANDS}, you need two with
16231 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
16235 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
16236 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
16243 @code{AC_TYPE_PID_T}
16248 @code{AC_PREFIX_PROGRAM}
16251 @defmac AC_PROGRAMS_CHECK
16252 @acindex{PROGRAMS_CHECK}
16253 @code{AC_CHECK_PROGS}
16256 @defmac AC_PROGRAMS_PATH
16257 @acindex{PROGRAMS_PATH}
16258 @code{AC_PATH_PROGS}
16261 @defmac AC_PROGRAM_CHECK
16262 @acindex{PROGRAM_CHECK}
16263 @code{AC_CHECK_PROG}
16266 @defmac AC_PROGRAM_EGREP
16267 @acindex{PROGRAM_EGREP}
16268 @code{AC_EGREP_CPP}
16271 @defmac AC_PROGRAM_PATH
16272 @acindex{PROGRAM_PATH}
16273 @code{AC_PATH_PROG}
16276 @defmac AC_REMOTE_TAPE
16277 @acindex{REMOTE_TAPE}
16278 removed because of limited usefulness
16281 @defmac AC_RESTARTABLE_SYSCALLS
16282 @acindex{RESTARTABLE_SYSCALLS}
16283 @code{AC_SYS_RESTARTABLE_SYSCALLS}
16286 @defmac AC_RETSIGTYPE
16287 @acindex{RETSIGTYPE}
16288 @code{AC_TYPE_SIGNAL}
16293 removed because of limited usefulness
16296 @defmac AC_SCO_INTL
16299 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
16300 macro used to do this:
16303 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
16307 Now it just calls @code{AC_FUNC_STRFTIME} instead.
16310 @defmac AC_SETVBUF_REVERSED
16311 @acindex{SETVBUF_REVERSED}
16312 @code{AC_FUNC_SETVBUF_REVERSED}
16315 @defmac AC_SET_MAKE
16317 @code{AC_PROG_MAKE_SET}
16320 @defmac AC_SIZEOF_TYPE
16321 @acindex{SIZEOF_TYPE}
16322 @code{AC_CHECK_SIZEOF}
16327 @code{AC_TYPE_SIZE_T}
16330 @defmac AC_STAT_MACROS_BROKEN
16331 @acindex{STAT_MACROS_BROKEN}
16332 @code{AC_HEADER_STAT}
16335 @defmac AC_STDC_HEADERS
16336 @acindex{STDC_HEADERS}
16337 @code{AC_HEADER_STDC}
16342 @code{AC_FUNC_STRCOLL}
16345 @defmac AC_ST_BLKSIZE
16346 @acindex{ST_BLKSIZE}
16347 @code{AC_CHECK_MEMBERS}
16350 @defmac AC_ST_BLOCKS
16351 @acindex{ST_BLOCKS}
16352 @code{AC_STRUCT_ST_BLOCKS}
16357 @code{AC_CHECK_MEMBERS}
16360 @defmac AC_SYS_RESTARTABLE_SYSCALLS
16361 @acindex{SYS_RESTARTABLE_SYSCALLS}
16362 @cvindex HAVE_RESTARTABLE_SYSCALLS
16363 If the system automatically restarts a system call that is interrupted
16364 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
16365 not check whether system calls are restarted in general---it checks whether a
16366 signal handler installed with @code{signal} (but not @code{sigaction})
16367 causes system calls to be restarted. It does not check whether system calls
16368 can be restarted when interrupted by signals that have no handler.
16370 These days portable programs should use @code{sigaction} with
16371 @code{SA_RESTART} if they want restartable system calls. They should
16372 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
16373 system call is restartable is a dynamic issue, not a configuration-time
16377 @defmac AC_SYS_SIGLIST_DECLARED
16378 @acindex{SYS_SIGLIST_DECLARED}
16379 @code{AC_DECL_SYS_SIGLIST}
16382 @defmac AC_TEST_CPP
16384 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
16387 @defmac AC_TEST_PROGRAM
16388 @acindex{TEST_PROGRAM}
16389 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
16392 @defmac AC_TIMEZONE
16394 @code{AC_STRUCT_TIMEZONE}
16397 @defmac AC_TIME_WITH_SYS_TIME
16398 @acindex{TIME_WITH_SYS_TIME}
16399 @code{AC_HEADER_TIME}
16402 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
16403 @acindex{TRY_COMPILE}
16408 [AC_LANG_PROGRAM([[@var{includes}]],
16409 [[@var{function-body}]])],
16410 [@var{action-if-true}],
16411 [@var{action-if-false}])
16415 @xref{Running the Compiler}.
16417 This macro double quotes both @var{includes} and @var{function-body}.
16419 For C and C++, @var{includes} is any @code{#include} statements needed
16420 by the code in @var{function-body} (@var{includes} will be ignored if
16421 the currently selected language is Fortran or Fortran 77). The compiler
16422 and compilation flags are determined by the current language
16423 (@pxref{Language Choice}).
16426 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
16432 [AC_LANG_SOURCE([[@var{input}]])],
16433 [@var{action-if-true}],
16434 [@var{action-if-false}])
16438 @xref{Running the Preprocessor}.
16440 This macro double quotes the @var{input}.
16443 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
16449 [AC_LANG_PROGRAM([[@var{includes}]],
16450 [[@var{function-body}]])],
16451 [@var{action-if-true}],
16452 [@var{action-if-false}])
16456 @xref{Running the Compiler}.
16458 This macro double quotes both @var{includes} and @var{function-body}.
16460 Depending on the current language (@pxref{Language Choice}), create a
16461 test program to see whether a function whose body consists of
16462 @var{function-body} can be compiled and linked. If the file compiles
16463 and links successfully, run shell commands @var{action-if-found},
16464 otherwise run @var{action-if-not-found}.
16466 This macro double quotes both @var{includes} and @var{function-body}.
16468 For C and C++, @var{includes} is any @code{#include} statements needed
16469 by the code in @var{function-body} (@var{includes} will be ignored if
16470 the currently selected language is Fortran or Fortran 77). The compiler
16471 and compilation flags are determined by the current language
16472 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
16473 @code{LIBS} are used for linking.
16476 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
16477 @acindex{TRY_LINK_FUNC}
16478 This macro is equivalent to
16479 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
16480 [@var{action-if-found}], [@var{action-if-not-found}])}.
16483 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
16489 [AC_LANG_SOURCE([[@var{program}]])],
16490 [@var{action-if-true}],
16491 [@var{action-if-false}],
16492 [@var{action-if-cross-compiling}])
16501 @code{AC_TYPE_UID_T}
16504 @defmac AC_UNISTD_H
16506 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
16512 Define @code{USG} if the @acronym{BSD} string functions are defined in
16513 @file{strings.h}. You should no longer depend upon @code{USG}, but on
16514 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
16517 @defmac AC_UTIME_NULL
16518 @acindex{UTIME_NULL}
16519 @code{AC_FUNC_UTIME_NULL}
16522 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
16523 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
16524 If the cache file is inconsistent with the current host, target and
16525 build system types, it used to execute @var{cmd} or print a default
16526 error message. This is now handled by default.
16529 @defmac AC_VERBOSE (@var{result-description})
16531 @code{AC_MSG_RESULT}.
16536 @code{AC_FUNC_VFORK}
16541 @code{AC_FUNC_VPRINTF}
16546 @code{AC_FUNC_WAIT3}
16554 @defmac AC_WORDS_BIGENDIAN
16555 @acindex{WORDS_BIGENDIAN}
16556 @code{AC_C_BIGENDIAN}
16559 @defmac AC_XENIX_DIR
16560 @acindex{XENIX_DIR}
16562 This macro used to add @option{-lx} to output variable @code{LIBS} if on
16563 Xenix. Also, if @file{dirent.h} is being checked for, added
16564 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
16565 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
16566 running @sc{xenix} on which you should not depend:
16569 AC_MSG_CHECKING([for Xenix])
16570 AC_EGREP_CPP([yes],
16571 [#if defined M_XENIX && !defined M_UNIX
16574 [AC_MSG_RESULT([yes]); XENIX=yes],
16575 [AC_MSG_RESULT([no]); XENIX=])
16579 @defmac AC_YYTEXT_POINTER
16580 @acindex{YYTEXT_POINTER}
16581 @code{AC_DECL_YYTEXT}
16585 @section Upgrading From Version 1
16586 @cindex Upgrading autoconf
16587 @cindex Autoconf upgrading
16589 Autoconf version 2 is mostly backward compatible with version 1.
16590 However, it introduces better ways to do some things, and doesn't
16591 support some of the ugly things in version 1. So, depending on how
16592 sophisticated your @file{configure.ac} files are, you might have to do
16593 some manual work in order to upgrade to version 2. This chapter points
16594 out some problems to watch for when upgrading. Also, perhaps your
16595 @command{configure} scripts could benefit from some of the new features in
16596 version 2; the changes are summarized in the file @file{NEWS} in the
16597 Autoconf distribution.
16600 * Changed File Names:: Files you might rename
16601 * Changed Makefiles:: New things to put in @file{Makefile.in}
16602 * Changed Macros:: Macro calls you might replace
16603 * Changed Results:: Changes in how to check test results
16604 * Changed Macro Writing:: Better ways to write your own macros
16607 @node Changed File Names
16608 @subsection Changed File Names
16610 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
16611 in a particular package's source directory), you must rename it to
16612 @file{acsite.m4}. @xref{autoconf Invocation}.
16614 If you distribute @file{install.sh} with your package, rename it to
16615 @file{install-sh} so @code{make} builtin rules won't inadvertently
16616 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
16617 looks for the script under both names, but it is best to use the new name.
16619 If you were using @file{config.h.top}, @file{config.h.bot}, or
16620 @file{acconfig.h}, you still can, but you will have less clutter if you
16621 use the @code{AH_} macros. @xref{Autoheader Macros}.
16623 @node Changed Makefiles
16624 @subsection Changed Makefiles
16626 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
16627 your @file{Makefile.in} files, so they can take advantage of the values
16628 of those variables in the environment when @command{configure} is run.
16629 Doing this isn't necessary, but it's a convenience for users.
16631 Also add @samp{@@configure_input@@} in a comment to each input file for
16632 @code{AC_OUTPUT}, so that the output files will contain a comment saying
16633 they were produced by @command{configure}. Automatically selecting the
16634 right comment syntax for all the kinds of files that people call
16635 @code{AC_OUTPUT} on became too much work.
16637 Add @file{config.log} and @file{config.cache} to the list of files you
16638 remove in @code{distclean} targets.
16640 If you have the following in @file{Makefile.in}:
16643 prefix = /usr/local
16644 exec_prefix = $(prefix)
16648 you must change it to:
16651 prefix = @@prefix@@
16652 exec_prefix = @@exec_prefix@@
16656 The old behavior of replacing those variables without @samp{@@}
16657 characters around them has been removed.
16659 @node Changed Macros
16660 @subsection Changed Macros
16662 Many of the macros were renamed in Autoconf version 2. You can still
16663 use the old names, but the new ones are clearer, and it's easier to find
16664 the documentation for them. @xref{Obsolete Macros}, for a table showing the
16665 new names for the old macros. Use the @command{autoupdate} program to
16666 convert your @file{configure.ac} to using the new macro names.
16667 @xref{autoupdate Invocation}.
16669 Some macros have been superseded by similar ones that do the job better,
16670 but are not call-compatible. If you get warnings about calling obsolete
16671 macros while running @command{autoconf}, you may safely ignore them, but
16672 your @command{configure} script will generally work better if you follow
16673 the advice that is printed about what to replace the obsolete macros with. In
16674 particular, the mechanism for reporting the results of tests has
16675 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
16676 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output will
16677 look better if you switch to @code{AC_MSG_CHECKING} and
16678 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
16679 in conjunction with cache variables. @xref{Caching Results}.
16683 @node Changed Results
16684 @subsection Changed Results
16686 If you were checking the results of previous tests by examining the
16687 shell variable @code{DEFS}, you need to switch to checking the values of
16688 the cache variables for those tests. @code{DEFS} no longer exists while
16689 @command{configure} is running; it is only created when generating output
16690 files. This difference from version 1 is because properly quoting the
16691 contents of that variable turned out to be too cumbersome and
16692 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
16695 For example, here is a @file{configure.ac} fragment written for Autoconf
16699 AC_HAVE_FUNCS(syslog)
16701 *-DHAVE_SYSLOG*) ;;
16702 *) # syslog is not in the default libraries. See if it's in some other.
16704 for lib in bsd socket inet; do
16705 AC_CHECKING(for syslog in -l$lib)
16706 LIBS="-l$lib $saved_LIBS"
16707 AC_HAVE_FUNCS(syslog)
16709 *-DHAVE_SYSLOG*) break ;;
16717 Here is a way to write it for version 2:
16720 AC_CHECK_FUNCS([syslog])
16721 if test $ac_cv_func_syslog = no; then
16722 # syslog is not in the default libraries. See if it's in some other.
16723 for lib in bsd socket inet; do
16724 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
16725 LIBS="-l$lib $LIBS"; break])
16730 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
16731 backslashes before quotes, you need to remove them. It now works
16732 predictably, and does not treat quotes (except back quotes) specially.
16733 @xref{Setting Output Variables}.
16735 All of the Boolean shell variables set by Autoconf macros now use
16736 @samp{yes} for the true value. Most of them use @samp{no} for false,
16737 though for backward compatibility some use the empty string instead. If
16738 you were relying on a shell variable being set to something like 1 or
16739 @samp{t} for true, you need to change your tests.
16741 @node Changed Macro Writing
16742 @subsection Changed Macro Writing
16744 When defining your own macros, you should now use @code{AC_DEFUN}
16745 instead of @code{define}. @code{AC_DEFUN} automatically calls
16746 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
16747 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
16748 messages on the screen. There's no actual harm in continuing to use the
16749 older way, but it's less convenient and attractive. @xref{Macro
16752 You probably looked at the macros that came with Autoconf as a guide for
16753 how to do things. It would be a good idea to take a look at the new
16754 versions of them, as the style is somewhat improved and they take
16755 advantage of some new features.
16757 If you were doing tricky things with undocumented Autoconf internals
16758 (macros, variables, diversions), check whether you need to change
16759 anything to account for changes that have been made. Perhaps you can
16760 even use an officially supported technique in version 2 instead of
16761 kludging. Or perhaps not.
16763 To speed up your locally written feature tests, add caching to them.
16764 See whether any of your tests are of general enough usefulness to
16765 encapsulate them into macros that you can share.
16768 @node Autoconf 2.13
16769 @section Upgrading From Version 2.13
16770 @cindex Upgrading autoconf
16771 @cindex Autoconf upgrading
16773 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
16774 suits this section@enddots{}
16777 Autoconf version 2.50 is mostly backward compatible with version 2.13.
16778 However, it introduces better ways to do some things, and doesn't
16779 support some of the ugly things in version 2.13. So, depending on how
16780 sophisticated your @file{configure.ac} files are, you might have to do
16781 some manual work in order to upgrade to version 2.50. This chapter
16782 points out some problems to watch for when upgrading. Also, perhaps
16783 your @command{configure} scripts could benefit from some of the new
16784 features in version 2.50; the changes are summarized in the file
16785 @file{NEWS} in the Autoconf distribution.
16789 * Changed Quotation:: Broken code which used to work
16790 * New Macros:: Interaction with foreign macros
16791 * Hosts and Cross-Compilation:: Bugward compatibility kludges
16792 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
16793 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
16796 @node Changed Quotation
16797 @subsection Changed Quotation
16799 The most important changes are invisible to you: the implementation of
16800 most macros have completely changed. This allowed more factorization of
16801 the code, better error messages, a higher uniformity of the user's
16802 interface etc. Unfortunately, as a side effect, some construct which
16803 used to (miraculously) work might break starting with Autoconf 2.50.
16804 The most common culprit is bad quotation.
16806 For instance, in the following example, the message is not properly
16811 AC_CHECK_HEADERS(foo.h, ,
16812 AC_MSG_ERROR(cannot find foo.h, bailing out))
16817 Autoconf 2.13 simply ignores it:
16820 $ @kbd{autoconf-2.13; ./configure --silent}
16821 creating cache ./config.cache
16822 configure: error: cannot find foo.h
16827 while Autoconf 2.50 will produce a broken @file{configure}:
16830 $ @kbd{autoconf-2.50; ./configure --silent}
16831 configure: error: cannot find foo.h
16832 ./configure: exit: bad non-numeric arg `bailing'
16833 ./configure: exit: bad non-numeric arg `bailing'
16837 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
16841 AC_INIT([Example], [1.0], [bug-example@@example.org])
16842 AC_CHECK_HEADERS([foo.h], [],
16843 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
16847 Many many (and many more) Autoconf macros were lacking proper quotation,
16848 including no less than@dots{} @code{AC_DEFUN} itself!
16851 $ @kbd{cat configure.in}
16852 AC_DEFUN([AC_PROG_INSTALL],
16853 [# My own much better version
16858 $ @kbd{autoconf-2.13}
16859 autoconf: Undefined macros:
16860 ***BUG in Autoconf--please report*** AC_FD_MSG
16861 ***BUG in Autoconf--please report*** AC_EPI
16862 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
16863 configure.in:5:AC_PROG_INSTALL
16864 $ @kbd{autoconf-2.50}
16870 @subsection New Macros
16872 @cindex undefined macro
16873 @cindex @code{_m4_divert_diversion}
16875 While Autoconf was relatively dormant in the late 1990s, Automake
16876 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
16877 in 2001, Autoconf provided
16878 versions of these macros, integrated in the @code{AC_} namespace,
16879 instead of @code{AM_}. But in order to ease the upgrading via
16880 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
16882 Unfortunately older versions of Automake (e.g., Automake 1.4)
16883 did not quote the names of these macros.
16884 Therefore, when @command{m4} finds something like
16885 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
16886 @code{AM_TYPE_PTRDIFF_T} is
16887 expanded, replaced with its Autoconf definition.
16889 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will
16890 complain, in its own words:
16893 $ @kbd{cat configure.ac}
16894 AC_INIT([Example], [1.0], [bug-example@@example.org])
16896 $ @kbd{aclocal-1.4}
16898 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
16899 aclocal.m4:17: the top level
16900 autom4te: m4 failed with exit status: 1
16904 Modern versions of Automake no longer define most of these
16905 macros, and will properly quote the names of the remaining macros.
16906 If you must use an old Automake, do not depend upon macros from Automake
16907 as it is simply not its job
16908 to provide macros (but the one it requires itself):
16911 $ @kbd{cat configure.ac}
16912 AC_INIT([Example], [1.0], [bug-example@@example.org])
16914 $ @kbd{rm aclocal.m4}
16916 autoupdate: `configure.ac' is updated
16917 $ @kbd{cat configure.ac}
16918 AC_INIT([Example], [1.0], [bug-example@@example.org])
16919 AC_CHECK_TYPES([ptrdiff_t])
16920 $ @kbd{aclocal-1.4}
16926 @node Hosts and Cross-Compilation
16927 @subsection Hosts and Cross-Compilation
16928 @cindex Cross compilation
16930 Based on the experience of compiler writers, and after long public
16931 debates, many aspects of the cross-compilation chain have changed:
16935 the relationship between the build, host, and target architecture types,
16938 the command line interface for specifying them to @command{configure},
16941 the variables defined in @command{configure},
16944 the enabling of cross-compilation mode.
16949 The relationship between build, host, and target have been cleaned up:
16950 the chain of default is now simply: target defaults to host, host to
16951 build, and build to the result of @command{config.guess}. Nevertheless,
16952 in order to ease the transition from 2.13 to 2.50, the following
16953 transition scheme is implemented. @emph{Do not rely on it}, as it will
16954 be completely disabled in a couple of releases (we cannot keep it, as it
16955 proves to cause more problems than it cures).
16957 They all default to the result of running @command{config.guess}, unless
16958 you specify either @option{--build} or @option{--host}. In this case,
16959 the default becomes the system type you specified. If you specify both,
16960 and they're different, @command{configure} will enter cross compilation
16961 mode, so it won't run any tests that require execution.
16963 Hint: if you mean to override the result of @command{config.guess},
16964 prefer @option{--build} over @option{--host}. In the future,
16965 @option{--host} will not override the name of the build system type.
16966 Whenever you specify @option{--host}, be sure to specify @option{--build}
16971 For backward compatibility, @command{configure} will accept a system
16972 type as an option by itself. Such an option will override the
16973 defaults for build, host, and target system types. The following
16974 configure statement will configure a cross toolchain that will run on
16975 Net@acronym{BSD}/alpha but generate code for @acronym{GNU} Hurd/sparc, which is
16976 also the build platform.
16979 ./configure --host=alpha-netbsd sparc-gnu
16984 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
16985 and @code{target} had a different semantics before and after the
16986 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
16987 @option{--build} is strictly copied into @code{build_alias}, and is left
16988 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
16989 set to the canonicalized build type. To ease the transition, before,
16990 its contents is the same as that of @code{build_alias}. Do @emph{not}
16991 rely on this broken feature.
16993 For consistency with the backward compatibility scheme exposed above,
16994 when @option{--host} is specified but @option{--build} isn't, the build
16995 system will be assumed to be the same as @option{--host}, and
16996 @samp{build_alias} will be set to that value. Eventually, this
16997 historically incorrect behavior will go away.
17001 The former scheme to enable cross-compilation proved to cause more harm
17002 than good, in particular, it used to be triggered too easily, leaving
17003 regular end users puzzled in front of cryptic error messages.
17004 @command{configure} could even enter cross-compilation mode only
17005 because the compiler was not functional. This is mainly because
17006 @command{configure} used to try to detect cross-compilation, instead of
17007 waiting for an explicit flag from the user.
17009 Now, @command{configure} enters cross-compilation mode if and only if
17010 @option{--host} is passed.
17012 That's the short documentation. To ease the transition between 2.13 and
17013 its successors, a more complicated scheme is implemented. @emph{Do not
17014 rely on the following}, as it will be removed in the near future.
17016 If you specify @option{--host}, but not @option{--build}, when
17017 @command{configure} performs the first compiler test it will try to run
17018 an executable produced by the compiler. If the execution fails, it will
17019 enter cross-compilation mode. This is fragile. Moreover, by the time
17020 the compiler test is performed, it may be too late to modify the
17021 build-system type: other tests may have already been performed.
17022 Therefore, whenever you specify @option{--host}, be sure to specify
17023 @option{--build} too.
17026 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
17030 will enter cross-compilation mode. The former interface, which
17031 consisted in setting the compiler to a cross-compiler without informing
17032 @command{configure} is obsolete. For instance, @command{configure} will
17033 fail if it can't run the code generated by the specified compiler if you
17034 configure as follows:
17037 ./configure CC=m68k-coff-gcc
17041 @node AC_LIBOBJ vs LIBOBJS
17042 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
17044 Up to Autoconf 2.13, the replacement of functions was triggered via the
17045 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
17046 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
17047 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
17049 This change is mandated by the unification of the @acronym{GNU} Build System
17050 components. In particular, the various fragile techniques used to parse
17051 a @file{configure.ac} are all replaced with the use of traces. As a
17052 consequence, any action must be traceable, which obsoletes critical
17053 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
17054 and it can even be handled gracefully (read, ``without your having to
17055 change something'').
17057 There were two typical uses of @code{LIBOBJS}: asking for a replacement
17058 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
17062 As for function replacement, the fix is immediate: use
17063 @code{AC_LIBOBJ}. For instance:
17066 LIBOBJS="$LIBOBJS fnmatch.o"
17067 LIBOBJS="$LIBOBJS malloc.$ac_objext"
17071 should be replaced with:
17074 AC_LIBOBJ([fnmatch])
17075 AC_LIBOBJ([malloc])
17081 When used with Automake 1.10 or newer, a suitable value for
17082 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
17083 can be referenced from any @file{Makefile.am}. Even without Automake,
17084 arranging for @code{LIBOBJDIR} to be set correctly will enable
17085 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
17086 The @code{LIBOJBDIR} feature is experimental.
17089 @node AC_FOO_IFELSE vs AC_TRY_FOO
17090 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
17092 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
17093 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
17094 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
17095 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
17096 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
17097 @code{AC_TRY_RUN}. The motivations where:
17100 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
17101 quoting their arguments;
17104 the combinatoric explosion is solved by decomposing on the one hand the
17105 generation of sources, and on the other hand executing the program;
17108 this scheme helps supporting more languages than plain C and C++.
17111 In addition to the change of syntax, the philosophy has changed too:
17112 while emphasis was put on speed at the expense of accuracy, today's
17113 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
17117 As a perfect example of what is @emph{not} to be done, here is how to
17118 find out whether a header file contains a particular declaration, such
17119 as a typedef, a structure, a structure member, or a function. Use
17120 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
17121 header file; on some systems the symbol might be defined in another
17122 header file that the file you are checking @samp{#include}s.
17124 As a (bad) example, here is how you should not check for C preprocessor
17125 symbols, either defined by header files or predefined by the C
17126 preprocessor: using @code{AC_EGREP_CPP}:
17134 ], is_aix=yes, is_aix=no)
17138 The above example, properly written would (i) use
17139 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
17143 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
17144 [[#if !defined _AIX
17145 error: This isn't AIX!
17154 @c ============================= Generating Test Suites with Autotest
17156 @node Using Autotest
17157 @chapter Generating Test Suites with Autotest
17162 @strong{N.B.: This section describes an experimental feature which will
17163 be part of Autoconf in a forthcoming release. Although we believe
17164 Autotest is stabilizing, this documentation describes an interface which
17165 might change in the future: do not depend upon Autotest without
17166 subscribing to the Autoconf mailing lists.}
17169 It is paradoxical that portable projects depend on nonportable tools
17170 to run their test suite. Autoconf by itself is the paragon of this
17171 problem: although it aims at perfectly portability, up to 2.13 its
17172 test suite was using Deja@acronym{GNU}, a rich and complex testing
17173 framework, but which is far from being standard on Posix systems.
17174 Worse yet, it was likely to be missing on the most fragile platforms,
17175 the very platforms that are most likely to torture Autoconf and
17176 exhibit deficiencies.
17178 To circumvent this problem, many package maintainers have developed their
17179 own testing framework, based on simple shell scripts whose sole outputs
17180 are exit status values describing whether the test succeeded. Most of
17181 these tests share common patterns, and this can result in lots of
17182 duplicated code and tedious maintenance.
17184 Following exactly the same reasoning that yielded to the inception of
17185 Autoconf, Autotest provides a test suite generation framework, based on
17186 M4 macros building a portable shell script. The suite itself is
17187 equipped with automatic logging and tracing facilities which greatly
17188 diminish the interaction with bug reporters, and simple timing reports.
17190 Autoconf itself has been using Autotest for years, and we do attest that
17191 it has considerably improved the strength of the test suite and the
17192 quality of bug reports. Other projects are known to use some generation
17193 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
17194 them with different needs, and this usage has validated Autotest as a general
17197 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
17198 interactive tool testing, which is probably its main limitation.
17201 * Using an Autotest Test Suite:: Autotest and the user
17202 * Writing testsuite.at:: Autotest macros
17203 * testsuite Invocation:: Running @command{testsuite} scripts
17204 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
17207 @node Using an Autotest Test Suite
17208 @section Using an Autotest Test Suite
17211 * testsuite Scripts:: The concepts of Autotest
17212 * Autotest Logs:: Their contents
17215 @node testsuite Scripts
17216 @subsection @command{testsuite} Scripts
17218 @cindex @command{testsuite}
17220 Generating testing or validation suites using Autotest is rather easy.
17221 The whole validation suite is held in a file to be processed through
17222 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
17223 produce a stand-alone Bourne shell script which then gets distributed.
17224 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
17225 the installer's end.
17228 Each test of the validation suite should be part of some test group. A
17229 @dfn{test group} is a sequence of interwoven tests that ought to be
17230 executed together, usually because one test in the group creates data
17231 files than a later test in the same group needs to read. Complex test
17232 groups make later debugging more tedious. It is much better to
17233 keep only a few tests per test group. Ideally there is only one test
17236 For all but the simplest packages, some file such as @file{testsuite.at}
17237 does not fully hold all test sources, as these are often easier to
17238 maintain in separate files. Each of these separate files holds a single
17239 test group, or a sequence of test groups all addressing some common
17240 functionality in the package. In such cases, @file{testsuite.at}
17241 merely initializes the validation suite, and sometimes does elementary
17242 health checking, before listing include statements for all other test
17243 files. The special file @file{package.m4}, containing the
17244 identification of the package, is automatically included if found.
17246 A convenient alternative consists in moving all the global issues
17247 (local Autotest macros, elementary health checking, and @code{AT_INIT}
17248 invocation) into the file @code{local.at}, and making
17249 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
17250 suites. In such case, generating the whole test suite or pieces of it
17251 is only a matter of choosing the @command{autom4te} command line
17254 The validation scripts that Autotest produces are by convention called
17255 @command{testsuite}. When run, @command{testsuite} executes each test
17256 group in turn, producing only one summary line per test to say if that
17257 particular test succeeded or failed. At end of all tests, summarizing
17258 counters get printed. One debugging directory is left for each test
17259 group which failed, if any: such directories are named
17260 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
17261 the test group, and they include:
17264 @item a debugging script named @file{run} which reruns the test in
17265 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
17266 of debugging scripts has the purpose of easing the chase for bugs.
17268 @item all the files created with @code{AT_DATA}
17270 @item a log of the run, named @file{testsuite.log}
17273 In the ideal situation, none of the tests fail, and consequently no
17274 debugging directory is left behind for validation.
17276 It often happens in practice that individual tests in the validation
17277 suite need to get information coming out of the configuration process.
17278 Some of this information, common for all validation suites, is provided
17279 through the file @file{atconfig}, automatically created by
17280 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
17281 testing environment specifically needs, you might prepare an optional
17282 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
17283 The configuration process produces @file{atconfig} and @file{atlocal}
17284 out of these two input files, and these two produced files are
17285 automatically read by the @file{testsuite} script.
17287 Here is a diagram showing the relationship between files.
17290 Files used in preparing a software package for distribution:
17295 subfile-1.at ->. [local.at] ---->+
17297 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
17303 Files used in configuring a software package:
17308 [atlocal.in] --> config.status* --<
17314 Files created during the test suite execution:
17317 atconfig -->. .--> testsuite.log
17321 [atlocal] ->' `--> [testsuite.dir]
17325 @node Autotest Logs
17326 @subsection Autotest Logs
17328 When run, the test suite creates a log file named after itself, e.g., a
17329 test suite named @command{testsuite} creates @file{testsuite.log}. It
17330 contains a lot of information, usually more than maintainers actually
17331 need, but therefore most of the time it contains all that is needed:
17334 @item command line arguments
17335 @c akim s/to consist in/to consist of/
17336 A very bad but unfortunately widespread Posix habit consists of
17337 setting environment variables before the command, such as in
17338 @samp{CC=my-home-grown-cc ./testsuite}. The test suite will not
17339 know this change, hence (i) it cannot report it to you, and (ii)
17340 it cannot preserve the value of @code{CC} for subsequent runs.
17341 Autoconf faced exactly the same problem, and solved it by asking
17342 users to pass the variable definitions as command line arguments.
17343 Autotest requires this rule, too, but has no means to enforce it; the log
17344 then contains a trace of the variables that were changed by the user.
17346 @item @file{ChangeLog} excerpts
17347 The topmost lines of all the @file{ChangeLog}s found in the source
17348 hierarchy. This is especially useful when bugs are reported against
17349 development versions of the package, since the version string does not
17350 provide sufficient information to know the exact state of the sources
17351 the user compiled. Of course, this relies on the use of a
17354 @item build machine
17355 Running a test suite in a cross-compile environment is not an easy task,
17356 since it would mean having the test suite run on a machine @var{build},
17357 while running programs on a machine @var{host}. It is much simpler to
17358 run both the test suite and the programs on @var{host}, but then, from
17359 the point of view of the test suite, there remains a single environment,
17360 @var{host} = @var{build}. The log contains relevant information on the
17361 state of the build machine, including some important environment
17363 @c FIXME: How about having an M4sh macro to say `hey, log the value
17364 @c of `@dots{}'? This would help both Autoconf and Autotest.
17366 @item tested programs
17367 The absolute file name and answers to @option{--version} of the tested
17368 programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}).
17370 @item configuration log
17371 The contents of @file{config.log}, as created by @command{configure},
17372 are appended. It contains the configuration flags and a detailed report
17373 on the configuration itself.
17377 @node Writing testsuite.at
17378 @section Writing @file{testsuite.at}
17380 The @file{testsuite.at} is a Bourne shell script making use of special
17381 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
17382 its beginning followed by one call to @code{m4_include} per source file
17383 for tests. Each such included file, or the remainder of
17384 @file{testsuite.at} if include files are not used, contain a sequence of
17385 test groups. Each test group begins with a call to @code{AT_SETUP},
17386 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
17387 and then completes with a call to @code{AT_CLEANUP}.
17389 @defmac AT_INIT (@ovar{name})
17391 @c FIXME: Not clear, plus duplication of the information.
17392 Initialize Autotest. Giving a @var{name} to the test suite is
17393 encouraged if your package includes several test suites. In any case,
17394 the test suite always displays the package name and version. It also
17395 inherits the package bug report address.
17398 @defmac AT_COPYRIGHT (@var{copyright-notice})
17399 @atindex{COPYRIGHT}
17400 @cindex Copyright Notice
17401 State that, in addition to the Free Software Foundation's copyright on
17402 the Autotest macros, parts of your test suite are covered by
17403 @var{copyright-notice}.
17405 The @var{copyright-notice} will show up in both the head of
17406 @command{testsuite} and in @samp{testsuite --version}.
17409 @defmac AT_TESTED (@var{executables})
17411 Log the file name and answer to @option{--version} of each program in
17412 space-separated list @var{executables}. Several invocations register
17413 new executables, in other words, don't fear registering one program
17417 Autotest test suites rely on @env{PATH} to find the tested program.
17418 This avoids the need to generate absolute names of the various tools, and
17419 makes it possible to test installed programs. Therefore, knowing which
17420 programs are being exercised is crucial to understanding problems in
17421 the test suite itself, or its occasional misuses. It is a good idea to
17422 also subscribe foreign programs you depend upon, to avoid incompatible
17427 @defmac AT_SETUP (@var{test-group-name})
17429 This macro starts a group of related tests, all to be executed in the
17430 same subshell. It accepts a single argument, which holds a few words
17431 (no more than about 30 or 40 characters) quickly describing the purpose
17432 of the test group being started.
17435 @defmac AT_KEYWORDS (@var{keywords})
17437 Associate the space-separated list of @var{keywords} to the enclosing
17438 test group. This makes it possible to run ``slices'' of the test suite.
17439 For instance, if some of your test groups exercise some @samp{foo}
17440 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
17441 @samp{./testsuite -k foo} to run exclusively these test groups. The
17442 @var{title} of the test group is automatically recorded to
17443 @code{AT_KEYWORDS}.
17445 Several invocations within a test group accumulate new keywords. In
17446 other words, don't fear registering the same keyword several times in a
17450 @defmac AT_CAPTURE_FILE (@var{file})
17451 @atindex{CAPTURE_FILE}
17452 If the current test group fails, log the contents of @var{file}.
17453 Several identical calls within one test group have no additional effect.
17456 @defmac AT_XFAIL_IF (@var{shell-condition})
17458 Determine whether the test is expected to fail because it is a known
17459 bug (for unsupported features, you should skip the test).
17460 @var{shell-condition} is a shell expression such as a @code{test}
17461 command; you can instantiate this macro many times from within the
17462 same test group, and one of the conditions will be enough to turn
17463 the test into an expected failure.
17468 End the current test group.
17473 @defmac AT_DATA (@var{file}, @var{contents})
17475 Initialize an input data @var{file} with given @var{contents}. Of
17476 course, the @var{contents} have to be properly quoted between square
17477 brackets to protect against included commas or spurious M4
17478 expansion. The contents ought to end with an end of line.
17481 @defmac AT_CHECK (@var{commands}, @dvar{status, @samp{0}}, @dvar{stdout, @samp{}}, @dvar{stderr, @samp{}}, @ovar{run-if-fail}, @ovar{run-if-pass})
17483 Execute a test by performing given shell @var{commands}. These commands
17484 should normally exit with @var{status}, while producing expected
17485 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
17486 status 77, then the whole test group is skipped. Otherwise, if this test
17487 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
17488 commands @var{run-if-pass}.
17490 The @var{commands} @emph{must not} redirect the standard output, nor the
17493 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
17494 the corresponding value is not checked.
17496 The special value @samp{expout} for @var{stdout} means the expected
17497 output of the @var{commands} is the content of the file @file{expout}.
17498 If @var{stdout} is @samp{stdout}, then the standard output of the
17499 @var{commands} is available for further tests in the file @file{stdout}.
17500 Similarly for @var{stderr} with @samp{expout} and @samp{stderr}.
17504 @node testsuite Invocation
17505 @section Running @command{testsuite} Scripts
17506 @cindex @command{testsuite}
17508 Autotest test suites support the following arguments:
17513 Display the list of options and exit successfully.
17517 Display the version of the test suite and exit successfully.
17521 Remove all the files the test suite might have created and exit. Meant
17522 for @code{clean} Makefile targets.
17526 List all the tests (or only the selection), including their possible
17532 By default all tests are performed (or described with
17533 @option{--list}) in the default environment first silently, then
17534 verbosely, but the environment, set of tests, and verbosity level can be
17538 @item @var{variable}=@var{value}
17539 Set the environment @var{variable} to @var{value}. Use this rather
17540 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
17541 different environment.
17543 @cindex @code{AUTOTEST_PATH}
17544 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
17545 to @env{PATH}. Relative directory names (not starting with
17546 @samp{/}) are considered to be relative to the top level of the
17547 package being built. All directories are made absolute, first
17548 starting from the top level @emph{build} tree, then from the
17549 @emph{source} tree. For instance @samp{./testsuite
17550 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
17551 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
17552 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
17556 @itemx @var{number}-@var{number}
17557 @itemx @var{number}-
17558 @itemx -@var{number}
17559 Add the corresponding test groups, with obvious semantics, to the
17562 @item --keywords=@var{keywords}
17563 @itemx -k @var{keywords}
17564 Add to the selection the test groups with title or keywords (arguments
17565 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
17566 of the comma separated list @var{keywords}, case-insensitively. Use
17567 @samp{!} immediately before the keyword to invert the selection for this
17568 keyword. By default, the keywords match whole words; enclose them in
17569 @samp{.*} to also match parts of words.
17571 For example, running
17574 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
17578 will select all tests tagged @samp{autoupdate} @emph{and} with tags
17579 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_FNMATCH},
17583 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
17587 will select all tests not tagged @samp{autoupdate} @emph{or} with tags
17588 containing @samp{FUNC}.
17592 If any test fails, immediately abort testing. It implies
17593 @option{--debug}: post test group clean up, and top-level logging
17594 are inhibited. This option is meant for the full test
17595 suite, it is not really useful for generated debugging scripts.
17599 Force more verbosity in the detailed output of what is being done. This
17600 is the default for debugging scripts.
17604 Do not remove the files after a test group was performed ---but they are
17605 still removed @emph{before}, therefore using this option is sane when
17606 running several test groups. Create debugging scripts. Do not
17607 overwrite the top-level
17608 log (in order to preserve supposedly existing full log file). This is
17609 the default for debugging scripts, but it can also be useful to debug
17610 the testsuite itself.
17614 Trigger shell tracing of the test groups.
17618 @node Making testsuite Scripts
17619 @section Making @command{testsuite} Scripts
17621 For putting Autotest into movement, you need some configuration and
17622 Makefile machinery. We recommend, at least if your package uses deep or
17623 shallow hierarchies, that you use @file{tests/} as the name of the
17624 directory holding all your tests and their @file{Makefile}. Here is a
17625 check list of things to do.
17630 @cindex @file{package.m4}
17631 Make sure to create the file @file{package.m4}, which defines the
17632 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
17633 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
17634 address to which bug reports should be sent. For sake of completeness,
17635 we suggest that you also define @code{AT_PACKAGE_NAME},
17636 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
17637 @xref{Initializing configure}, for a description of these variables. We
17638 suggest the following Makefile excerpt:
17641 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
17643 echo '# Signature of the current package.'; \
17644 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
17645 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
17646 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
17647 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
17648 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
17649 @} >$(srcdir)/package.m4
17653 Be sure to distribute @file{package.m4} and to put it into the source
17654 hierarchy: the test suite ought to be shipped!
17657 Invoke @code{AC_CONFIG_TESTDIR}.
17659 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, @var{directory}})
17660 @acindex{CONFIG_TESTDIR}
17661 An Autotest test suite is to be configured in @var{directory}. This
17662 macro requires the instantiation of @file{@var{directory}/atconfig} from
17663 @file{@var{directory}/atconfig.in}, and sets the default
17664 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
17668 Still within @file{configure.ac}, as appropriate, ensure that some
17669 @code{AC_CONFIG_FILES} command includes substitution for
17670 @file{tests/atlocal}.
17673 The @file{tests/Makefile.in} should be modified so the validation in
17674 your package is triggered by @samp{make check}. An example is provided
17678 With Automake, here is a minimal example about how to link @samp{make
17679 check} with a validation suite.
17682 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
17683 TESTSUITE = $(srcdir)/testsuite
17685 check-local: atconfig atlocal $(TESTSUITE)
17686 $(SHELL) $(TESTSUITE) $(TESTSUITEFLAGS)
17688 installcheck-local: atconfig atlocal $(TESTSUITE)
17689 $(SHELL) $(TESTSUITE) AUTOTEST_PATH="$(bindir)" \
17692 AUTOTEST = $(AUTOM4TE) --language=autotest
17693 $(TESTSUITE): $(srcdir)/testsuite.at
17694 $(AUTOTEST) -I $(srcdir) -o $@@.tmp $@@.at
17698 You might want to list explicitly the dependencies, i.e., the list of
17699 the files @file{testsuite.at} includes.
17701 With strict Autoconf, you might need to add lines inspired from the
17707 atconfig: $(top_builddir)/config.status
17708 cd $(top_builddir) && \
17709 $(SHELL) ./config.status $(subdir)/$@@
17711 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
17712 cd $(top_builddir) && \
17713 $(SHELL) ./config.status $(subdir)/$@@
17717 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
17720 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
17721 within your Makefile, you can fine-tune test suite execution with this variable,
17725 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
17730 @c =============================== Frequent Autoconf Questions, with answers
17733 @chapter Frequent Autoconf Questions, with answers
17735 Several questions about Autoconf come up occasionally. Here some of them
17739 * Distributing:: Distributing @command{configure} scripts
17740 * Why GNU m4:: Why not use the standard M4?
17741 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
17742 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
17743 * Defining Directories:: Passing @code{datadir} to program
17744 * autom4te.cache:: What is it? Can I remove it?
17745 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
17749 @section Distributing @command{configure} Scripts
17753 What are the restrictions on distributing @command{configure}
17754 scripts that Autoconf generates? How does that affect my
17755 programs that use them?
17758 There are no restrictions on how the configuration scripts that Autoconf
17759 produces may be distributed or used. In Autoconf version 1, they were
17760 covered by the @acronym{GNU} General Public License. We still encourage
17761 software authors to distribute their work under terms like those of the
17762 @acronym{GPL}, but doing so is not required to use Autoconf.
17764 Of the other files that might be used with @command{configure},
17765 @file{config.h.in} is under whatever copyright you use for your
17766 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
17767 exception to the @acronym{GPL} when they are used with an Autoconf-generated
17768 @command{configure} script, which permits you to distribute them under the
17769 same terms as the rest of your package. @file{install-sh} is from the X
17770 Consortium and is not copyrighted.
17773 @section Why Require @acronym{GNU} M4?
17776 Why does Autoconf require @acronym{GNU} M4?
17779 Many M4 implementations have hard-coded limitations on the size and
17780 number of macros that Autoconf exceeds. They also lack several
17781 builtin macros that it would be difficult to get along without in a
17782 sophisticated application like Autoconf, including:
17792 Autoconf requires version 1.4.3 or later of @acronym{GNU} M4.
17794 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
17795 M4 is simple to configure and install, it seems reasonable to require
17796 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
17797 other free software already have most of the @acronym{GNU} utilities
17798 installed, since they prefer them.
17800 @node Bootstrapping
17801 @section How Can I Bootstrap?
17805 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
17806 @command{configure} script, how do I bootstrap? It seems like a chicken
17810 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
17811 @command{configure} script produced by Autoconf, Autoconf is not required
17812 in order to run the script and install @acronym{GNU} M4. Autoconf is only
17813 required if you want to change the M4 @command{configure} script, which few
17814 people have to do (mainly its maintainer).
17816 @node Why Not Imake
17817 @section Why Not Imake?
17821 Why not use Imake instead of @command{configure} scripts?
17824 Several people have written addressing this question, so I include
17825 adaptations of their explanations here.
17827 The following answer is based on one written by Richard Pixley:
17830 Autoconf generated scripts frequently work on machines that it has
17831 never been set up to handle before. That is, it does a good job of
17832 inferring a configuration for a new system. Imake cannot do this.
17834 Imake uses a common database of host specific data. For X11, this makes
17835 sense because the distribution is made as a collection of tools, by one
17836 central authority who has control over the database.
17838 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
17839 maintainer; these maintainers are scattered across the world. Using a
17840 common database would be a maintenance nightmare. Autoconf may appear
17841 to be this kind of database, but in fact it is not. Instead of listing
17842 host dependencies, it lists program requirements.
17844 If you view the @acronym{GNU} suite as a collection of native tools, then the
17845 problems are similar. But the @acronym{GNU} development tools can be
17846 configured as cross tools in almost any host+target permutation. All of
17847 these configurations can be installed concurrently. They can even be
17848 configured to share host independent files across hosts. Imake doesn't
17849 address these issues.
17851 Imake templates are a form of standardization. The @acronym{GNU} coding
17852 standards address the same issues without necessarily imposing the same
17857 Here is some further explanation, written by Per Bothner:
17860 One of the advantages of Imake is that it easy to generate large
17861 Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms.
17862 However, @code{cpp} is not programmable: it has limited conditional
17863 facilities, and no looping. And @code{cpp} cannot inspect its
17866 All of these problems are solved by using @code{sh} instead of
17867 @code{cpp}. The shell is fully programmable, has macro substitution,
17868 can execute (or source) other shell scripts, and can inspect its
17873 Paul Eggert elaborates more:
17876 With Autoconf, installers need not assume that Imake itself is already
17877 installed and working well. This may not seem like much of an advantage
17878 to people who are accustomed to Imake. But on many hosts Imake is not
17879 installed or the default installation is not working well, and requiring
17880 Imake to install a package hinders the acceptance of that package on
17881 those hosts. For example, the Imake template and configuration files
17882 might not be installed properly on a host, or the Imake build procedure
17883 might wrongly assume that all source files are in one big directory
17884 tree, or the Imake configuration might assume one compiler whereas the
17885 package or the installer needs to use another, or there might be a
17886 version mismatch between the Imake expected by the package and the Imake
17887 supported by the host. These problems are much rarer with Autoconf,
17888 where each package comes with its own independent configuration
17891 Also, Imake often suffers from unexpected interactions between
17892 @command{make} and the installer's C preprocessor. The fundamental problem
17893 here is that the C preprocessor was designed to preprocess C programs,
17894 not @file{Makefile}s. This is much less of a problem with Autoconf,
17895 which uses the general-purpose preprocessor M4, and where the
17896 package's author (rather than the installer) does the preprocessing in a
17901 Finally, Mark Eichin notes:
17904 Imake isn't all that extensible, either. In order to add new features to
17905 Imake, you need to provide your own project template, and duplicate most
17906 of the features of the existing one. This means that for a sophisticated
17907 project, using the vendor-provided Imake templates fails to provide any
17908 leverage---since they don't cover anything that your own project needs
17909 (unless it is an X11 program).
17911 On the other side, though:
17913 The one advantage that Imake has over @command{configure}:
17914 @file{Imakefile}s tend to be much shorter (likewise, less redundant)
17915 than @file{Makefile.in}s. There is a fix to this, however---at least
17916 for the Kerberos V5 tree, we've modified things to call in common
17917 @file{post.in} and @file{pre.in} @file{Makefile} fragments for the
17918 entire tree. This means that a lot of common things don't have to be
17919 duplicated, even though they normally are in @command{configure} setups.
17923 @node Defining Directories
17924 @section How Do I @code{#define} Installation Directories?
17927 My program needs library files, installed in @code{datadir} and
17931 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
17932 [Define to the read-only architecture-independent
17940 #define DATADIR "$@{prefix@}/share"
17944 As already explained, this behavior is on purpose, mandated by the
17945 @acronym{GNU} Coding Standards, see @ref{Installation Directory
17946 Variables}. There are several means to achieve a similar goal:
17950 Do not use @code{AC_DEFINE} but use your @file{Makefile} to pass the
17951 actual value of @code{datadir} via compilation flags, see
17952 @ref{Installation Directory Variables}, for the details.
17955 This solution can be simplified when compiling a program: you may either
17956 extend the @code{CPPFLAGS}:
17959 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
17963 or create a dedicated header file:
17966 DISTCLEANFILES = datadir.h
17967 datadir.h: Makefile
17968 echo '#define DATADIR "$(datadir)"' >$@@
17972 Use @code{AC_DEFINE} but have @command{configure} compute the literal
17973 value of @code{datadir} and others. Many people have wrapped macros to
17974 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
17975 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
17978 This solution does not conform to the @acronym{GNU} Coding Standards.
17981 Note that all the previous solutions hard wire the absolute name of
17982 these directories in the executables, which is not a good property. You
17983 may try to compute the names relative to @code{prefix}, and try to
17984 find @code{prefix} at runtime, this way your package is relocatable.
17985 Some macros are already available to address this issue: see
17986 @code{adl_COMPUTE_RELATIVE_PATHS} and
17987 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
17988 @uref{http://autoconf-archive.cryp.to/,
17989 Autoconf Macro Archive}.
17993 @node autom4te.cache
17994 @section What is @file{autom4te.cache}?
17997 What is this directory @file{autom4te.cache}? Can I safely remove it?
18000 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
18001 role and is read by many tools: @command{autoconf} to create
18002 @file{configure}, @command{autoheader} to create @file{config.h.in},
18003 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
18004 check the completeness of @file{configure.ac}, @command{autoreconf} to
18005 check the @acronym{GNU} Build System components that are used. To
18006 ``read @file{configure.ac}'' actually means to compile it with M4,
18007 which can be a very long process for complex @file{configure.ac}.
18009 This is why all these tools, instead of running directly M4, invoke
18010 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
18011 a specific demand, stores additional information in
18012 @file{autom4te.cache} for future runs. For instance, if you run
18013 @command{autoconf}, behind the scenes, @command{autom4te} will also
18014 store information for the other tools, so that when you invoke
18015 @command{autoheader} or @command{automake} etc., re-processing
18016 @file{configure.ac} is not needed. The speed up is frequently of 30%,
18017 and is increasing with the size of @file{configure.ac}.
18019 But it is and remains being simply a cache: you can safely remove it.
18024 Can I permanently get rid of it?
18027 The creation of this cache can be disabled from
18028 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
18029 details. You should be aware that disabling the cache slows down the
18030 Autoconf test suite by 40%. The more @acronym{GNU} Build System
18031 components are used, the more the cache is useful; for instance
18032 running @samp{autoreconf -f} on the Core Utilities is twice slower without
18033 the cache @emph{although @option{--force} implies that the cache is
18034 not fully exploited}, and eight times slower than without
18038 @node Present But Cannot Be Compiled
18039 @section Header Present But Cannot Be Compiled
18041 The most important guideline to bear in mind when checking for
18042 features is to mimic as much as possible the intended use.
18043 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
18044 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
18045 the preprocessor, instead of the compiler, to check for headers. As a
18046 result, incompatibilities between headers went unnoticed during
18047 configuration, and maintainers finally had to deal with this issue
18050 As of Autoconf 2.56 both checks are performed, and @code{configure}
18051 complains loudly if the compiler and the preprocessor do not agree.
18052 For the time being the result used is that of the preprocessor, to give
18053 maintainers time to adjust their @file{configure.ac}, but in the
18054 future, only the compiler will be considered.
18056 Consider the following example:
18059 $ @kbd{cat number.h}
18060 typedef int number;
18062 const number pi = 3;
18063 $ @kbd{cat configure.ac}
18064 AC_INIT([Example], [1.0], [bug-example@@example.org])
18065 AC_CHECK_HEADERS([pi.h])
18066 $ @kbd{autoconf -Wall}
18067 $ @kbd{./configure}
18068 checking for gcc... gcc
18069 checking for C compiler default output file name... a.out
18070 checking whether the C compiler works... yes
18071 checking whether we are cross compiling... no
18072 checking for suffix of executables...
18073 checking for suffix of object files... o
18074 checking whether we are using the GNU C compiler... yes
18075 checking whether gcc accepts -g... yes
18076 checking for gcc option to accept ISO C89... none needed
18077 checking how to run the C preprocessor... gcc -E
18078 checking for grep that handles long lines and -e... grep
18079 checking for egrep... grep -E
18080 checking for ANSI C header files... yes
18081 checking for sys/types.h... yes
18082 checking for sys/stat.h... yes
18083 checking for stdlib.h... yes
18084 checking for string.h... yes
18085 checking for memory.h... yes
18086 checking for strings.h... yes
18087 checking for inttypes.h... yes
18088 checking for stdint.h... yes
18089 checking for unistd.h... yes
18090 checking pi.h usability... no
18091 checking pi.h presence... yes
18092 configure: WARNING: pi.h: present but cannot be compiled
18093 configure: WARNING: pi.h: check for missing prerequisite headers?
18094 configure: WARNING: pi.h: see the Autoconf documentation
18095 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
18096 configure: WARNING: pi.h: proceeding with the preprocessor's result
18097 configure: WARNING: pi.h: in the future, the compiler will take precedence
18098 configure: WARNING: ## -------------------------------------- ##
18099 configure: WARNING: ## Report this to bug-example@@example.org ##
18100 configure: WARNING: ## -------------------------------------- ##
18101 checking for pi.h... yes
18105 The proper way the handle this case is using the fourth argument
18106 (@pxref{Generic Headers}):
18109 $ @kbd{cat configure.ac}
18110 AC_INIT([Example], [1.0], [bug-example@@example.org])
18111 AC_CHECK_HEADERS([number.h pi.h], [], [],
18112 [[#if HAVE_NUMBER_H
18113 # include <number.h>
18116 $ @kbd{autoconf -Wall}
18117 $ @kbd{./configure}
18118 checking for gcc... gcc
18119 checking for C compiler default output... a.out
18120 checking whether the C compiler works... yes
18121 checking whether we are cross compiling... no
18122 checking for suffix of executables...
18123 checking for suffix of object files... o
18124 checking whether we are using the GNU C compiler... yes
18125 checking whether gcc accepts -g... yes
18126 checking for gcc option to accept ANSI C... none needed
18127 checking for number.h... yes
18128 checking for pi.h... yes
18131 See @ref{Particular Headers}, for a list of headers with their
18134 @c ===================================================== History of Autoconf.
18137 @chapter History of Autoconf
18138 @cindex History of autoconf
18140 You may be wondering, Why was Autoconf originally written? How did it
18141 get into its present form? (Why does it look like gorilla spit?) If
18142 you're not wondering, then this chapter contains no information useful
18143 to you, and you might as well skip it. If you @emph{are} wondering,
18144 then let there be light@enddots{}
18147 * Genesis:: Prehistory and naming of @command{configure}
18148 * Exodus:: The plagues of M4 and Perl
18149 * Leviticus:: The priestly code of portability arrives
18150 * Numbers:: Growth and contributors
18151 * Deuteronomy:: Approaching the promises of easy configuration
18157 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
18158 Free Software Foundation. As they were ported to more platforms and
18159 more programs were added, the number of @option{-D} options that users
18160 had to select in the @file{Makefile} (around 20) became burdensome.
18161 Especially for me---I had to test each new release on a bunch of
18162 different systems. So I wrote a little shell script to guess some of
18163 the correct settings for the fileutils package, and released it as part
18164 of fileutils 2.0. That @command{configure} script worked well enough that
18165 the next month I adapted it (by hand) to create similar @command{configure}
18166 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
18167 also adapted one of my scripts for his @acronym{CVS} revision control system.
18169 Later that summer, I learned that Richard Stallman and Richard Pixley
18170 were developing similar scripts to use in the @acronym{GNU} compiler tools;
18171 so I adapted my @command{configure} scripts to support their evolving
18172 interface: using the file name @file{Makefile.in} as the templates;
18173 adding @samp{+srcdir}, the first option (of many); and creating
18174 @file{config.status} files.
18179 As I got feedback from users, I incorporated many improvements, using
18180 Emacs to search and replace, cut and paste, similar changes in each of
18181 the scripts. As I adapted more @acronym{GNU} utilities packages to use
18182 @command{configure} scripts, updating them all by hand became impractical.
18183 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
18184 mail saying that the @command{configure} scripts were great, and asking if
18185 I had a tool for generating them that I could send him. No, I thought,
18186 but I should! So I started to work out how to generate them. And the
18187 journey from the slavery of hand-written @command{configure} scripts to the
18188 abundance and ease of Autoconf began.
18190 Cygnus @command{configure}, which was being developed at around that time,
18191 is table driven; it is meant to deal mainly with a discrete number of
18192 system types with a small number of mainly unguessable features (such as
18193 details of the object file format). The automatic configuration system
18194 that Brian Fox had developed for Bash takes a similar approach. For
18195 general use, it seems to me a hopeless cause to try to maintain an
18196 up-to-date database of which features each variant of each operating
18197 system has. It's easier and more reliable to check for most features on
18198 the fly---especially on hybrid systems that people have hacked on
18199 locally or that have patches from vendors installed.
18201 I considered using an architecture similar to that of Cygnus
18202 @command{configure}, where there is a single @command{configure} script that
18203 reads pieces of @file{configure.in} when run. But I didn't want to have
18204 to distribute all of the feature tests with every package, so I settled
18205 on having a different @command{configure} made from each
18206 @file{configure.in} by a preprocessor. That approach also offered more
18207 control and flexibility.
18209 I looked briefly into using the Metaconfig package, by Larry Wall,
18210 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
18211 reasons. The @command{Configure} scripts it produces are interactive,
18212 which I find quite inconvenient; I didn't like the ways it checked for
18213 some features (such as library functions); I didn't know that it was
18214 still being maintained, and the @command{Configure} scripts I had
18215 seen didn't work on many modern systems (such as System V R4 and NeXT);
18216 it wasn't very flexible in what it could do in response to a feature's
18217 presence or absence; I found it confusing to learn; and it was too big
18218 and complex for my needs (I didn't realize then how much Autoconf would
18219 eventually have to grow).
18221 I considered using Perl to generate my style of @command{configure}
18222 scripts, but decided that M4 was better suited to the job of simple
18223 textual substitutions: it gets in the way less, because output is
18224 implicit. Plus, everyone already has it. (Initially I didn't rely on
18225 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
18226 University of Maryland had recently been putting M4 front ends on
18227 several programs, including @code{tvtwm}, and I was interested in trying
18228 out a new language.
18233 Since my @command{configure} scripts determine the system's capabilities
18234 automatically, with no interactive user intervention, I decided to call
18235 the program that generates them Autoconfig. But with a version number
18236 tacked on, that name would be too long for old Unix file systems,
18237 so I shortened it to Autoconf.
18239 In the fall of 1991 I called together a group of fellow questers after
18240 the Holy Grail of portability (er, that is, alpha testers) to give me
18241 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
18242 and continued to add features and improve the techniques used in the
18243 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
18244 with the idea of making an Autoconf shell script to run M4
18245 and check for unresolved macro calls; Richard Pixley, who suggested
18246 running the compiler instead of searching the file system to find
18247 include files and symbols, for more accurate results; Karl Berry, who
18248 got Autoconf to configure @TeX{} and added the macro index to the
18249 documentation; and Ian Lance Taylor, who added support for creating a C
18250 header file as an alternative to putting @option{-D} options in a
18251 @file{Makefile}, so he could use Autoconf for his @acronym{UUCP} package.
18252 The alpha testers cheerfully adjusted their files again and again as the
18253 names and calling conventions of the Autoconf macros changed from
18254 release to release. They all contributed many specific checks, great
18255 ideas, and bug fixes.
18260 In July 1992, after months of alpha testing, I released Autoconf 1.0,
18261 and converted many @acronym{GNU} packages to use it. I was surprised by how
18262 positive the reaction to it was. More people started using it than I
18263 could keep track of, including people working on software that wasn't
18264 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
18265 Autoconf continued to improve rapidly, as many people using the
18266 @command{configure} scripts reported problems they encountered.
18268 Autoconf turned out to be a good torture test for M4 implementations.
18269 Unix M4 started to dump core because of the length of the
18270 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
18271 M4 as well. Eventually, we realized that we needed to use some
18272 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
18273 particular, has an impoverished set of builtin macros; the System V
18274 version is better, but still doesn't provide everything we need.
18276 More development occurred as people put Autoconf under more stresses
18277 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
18278 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
18279 invalid arguments. Jim Blandy bravely coerced it into configuring
18280 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
18281 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
18282 @command{autoheader} script to automate the creation of C header file
18283 templates, and added a @option{--verbose} option to @command{configure}.
18284 Noah Friedman added the @option{--autoconf-dir} option and
18285 @code{AC_MACRODIR} environment variable. (He also coined the term
18286 @dfn{autoconfiscate} to mean ``adapt a software package to use
18287 Autoconf''.) Roland and Noah improved the quoting protection in
18288 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
18289 dealing with portability problems from February through June, 1993.
18292 @section Deuteronomy
18294 A long wish list for major features had accumulated, and the effect of
18295 several years of patching by various people had left some residual
18296 cruft. In April 1994, while working for Cygnus Support, I began a major
18297 revision of Autoconf. I added most of the features of the Cygnus
18298 @command{configure} that Autoconf had lacked, largely by adapting the
18299 relevant parts of Cygnus @command{configure} with the help of david zuhn
18300 and Ken Raeburn. These features include support for using
18301 @file{config.sub}, @file{config.guess}, @option{--host}, and
18302 @option{--target}; making links to files; and running @command{configure}
18303 scripts in subdirectories. Adding these features enabled Ken to convert
18304 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
18307 I added more features in response to other peoples' requests. Many
18308 people had asked for @command{configure} scripts to share the results of
18309 the checks between runs, because (particularly when configuring a large
18310 source tree, like Cygnus does) they were frustratingly slow. Mike
18311 Haertel suggested adding site-specific initialization scripts. People
18312 distributing software that had to unpack on MS-DOS asked for a way to
18313 override the @file{.in} extension on the file names, which produced file
18314 names like @file{config.h.in} containing two dots. Jim Avera did an
18315 extensive examination of the problems with quoting in @code{AC_DEFINE}
18316 and @code{AC_SUBST}; his insights led to significant improvements.
18317 Richard Stallman asked that compiler output be sent to @file{config.log}
18318 instead of @file{/dev/null}, to help people debug the Emacs
18319 @command{configure} script.
18321 I made some other changes because of my dissatisfaction with the quality
18322 of the program. I made the messages showing results of the checks less
18323 ambiguous, always printing a result. I regularized the names of the
18324 macros and cleaned up coding style inconsistencies. I added some
18325 auxiliary utilities that I had developed to help convert source code
18326 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
18327 the macros not interrupt each others' messages. (That feature revealed
18328 some performance bottlenecks in @acronym{GNU} M4, which he hastily
18329 corrected!) I reorganized the documentation around problems people want
18330 to solve. And I began a test suite, because experience had shown that
18331 Autoconf has a pronounced tendency to regress when we change it.
18333 Again, several alpha testers gave invaluable feedback, especially
18334 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
18337 Finally, version 2.0 was ready. And there was much rejoicing. (And I
18338 have free time again. I think. Yeah, right.)
18341 @c ========================================================== Appendices
18343 @node Copying This Manual
18344 @appendix Copying This Manual
18348 * GNU Free Documentation License:: License for copying this manual
18357 * Environment Variable Index:: Index of environment variables used
18358 * Output Variable Index:: Index of variables set in output files
18359 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
18360 * Autoconf Macro Index:: Index of Autoconf macros
18361 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
18362 * Autotest Macro Index:: Index of Autotest macros
18363 * Program & Function Index:: Index of those with portability problems
18364 * Concept Index:: General index
18367 @node Environment Variable Index
18368 @appendixsec Environment Variable Index
18370 This is an alphabetical list of the environment variables that Autoconf
18375 @node Output Variable Index
18376 @appendixsec Output Variable Index
18378 This is an alphabetical list of the variables that Autoconf can
18379 substitute into files that it creates, typically one or more
18380 @file{Makefile}s. @xref{Setting Output Variables}, for more information
18381 on how this is done.
18385 @node Preprocessor Symbol Index
18386 @appendixsec Preprocessor Symbol Index
18388 This is an alphabetical list of the C preprocessor symbols that the
18389 Autoconf macros define. To work with Autoconf, C source code needs to
18390 use these names in @code{#if} directives.
18394 @node Autoconf Macro Index
18395 @appendixsec Autoconf Macro Index
18397 This is an alphabetical list of the Autoconf macros.
18398 @ifset shortindexflag
18399 To make the list easier to use, the macros are listed without their
18400 preceding @samp{AC_}.
18405 @node M4 Macro Index
18406 @appendixsec M4 Macro Index
18408 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
18409 @ifset shortindexflag
18410 To make the list easier to use, the macros are listed without their
18411 preceding @samp{m4_} or @samp{AS_}.
18416 @node Autotest Macro Index
18417 @appendixsec Autotest Macro Index
18419 This is an alphabetical list of the Autotest macros.
18420 @ifset shortindexflag
18421 To make the list easier to use, the macros are listed without their
18422 preceding @samp{AT_}.
18427 @node Program & Function Index
18428 @appendixsec Program and Function Index
18430 This is an alphabetical list of the programs and functions which
18431 portability is discussed in this document.
18435 @node Concept Index
18436 @appendixsec Concept Index
18438 This is an alphabetical list of the files, tools, and concepts
18439 introduced in this document.
18445 @c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
18446 @c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
18447 @c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
18448 @c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
18449 @c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
18450 @c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
18451 @c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
18452 @c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
18453 @c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
18454 @c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
18455 @c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
18456 @c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
18457 @c LocalWords: distclean uninstall noindent versioning Tromey dir
18458 @c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
18459 @c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
18460 @c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
18461 @c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
18462 @c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
18463 @c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
18464 @c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
18465 @c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
18466 @c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
18467 @c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
18468 @c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
18469 @c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
18470 @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
18471 @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
18472 @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
18473 @c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
18474 @c LocalWords: ld inline malloc OSF putenv setenv FreeBSD realloc SunOS MinGW
18475 @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
18476 @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
18477 @c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
18478 @c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
18479 @c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
18480 @c LocalWords: GETLODAVG SETGID getloadavg nlist setgid setuid GETMNTENT irix
18481 @c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
18482 @c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
18483 @c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
18484 @c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
18485 @c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
18486 @c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
18487 @c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
18488 @c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
18489 @c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS autom GCC's kB
18490 @c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
18491 @c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
18492 @c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
18493 @c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
18494 @c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
18495 @c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae Onolimit conftest AXP str
18496 @c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
18497 @c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
18498 @c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
18499 @c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
18500 @c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
18501 @c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
18502 @c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
18503 @c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
18504 @c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
18505 @c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
18506 @c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
18507 @c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
18508 @c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
18509 @c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
18510 @c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
18511 @c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
18512 @c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
18513 @c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
18514 @c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS unwriteable te VM
18515 @c LocalWords: coreutils sparc Proulx SysV nbar nfoo maxdepth acdilrtu TWG mc
18516 @c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
18517 @c LocalWords: fooXXXXXX Unicos parenthesization utimes hpux hppa unescaped
18518 @c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
18519 @c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc behaviour readline
18520 @c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
18521 @c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
18522 @c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
18523 @c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
18524 @c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
18525 @c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
18526 @c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
18527 @c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
18528 @c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
18529 @c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
18530 @c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
18531 @c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
18532 @c LocalWords: GOBJC OBJCCPP OTP ERLC erl valloc decr dumpdef errprint incr
18533 @c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
18534 @c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN ig
18535 @c LocalWords: Dynix descrips basename aname cname ih macroexpands xno xcheck
18536 @c LocalWords: LIBREADLINE lreadline lncurses libreadline
18538 @c Local Variables:
18540 @c ispell-local-dictionary: "american"