1 \input texinfo @c -*-texinfo-*-
2 @comment ========================================================
3 @comment %**start of header
4 @setfilename autoconf.info
8 @setcontentsaftertitlepage
11 @c @ovar(ARG, DEFAULT)
12 @c -------------------
13 @c The ARG is an optional argument. To be used for macro arguments in
14 @c their documentation (@defmac).
16 @r{[}@var{\varname\}@r{]}
19 @c @dvar(ARG, DEFAULT)
20 @c -------------------
21 @c The ARG is an optional argument, defaulting to DEFAULT. To be used
22 @c for macro arguments in their documentation (@defmac).
23 @macro dvar{varname, default}
24 @r{[}@var{\varname\} = @samp{\default\}@r{]}
29 @c A replacement for @uref that puts the URL in the footnotes when
32 @macro href{url, title}
37 @macro href{url, title}
38 \title\@footnote{\title\, @url{\url\}.}
42 @c Handling the indexes with Texinfo yields several different problems.
44 @c Because we want to drop out the AC_ part of the macro names in the
45 @c printed manual, but not in the other outputs, we need a layer above
46 @c the usual @acindex etc. That's why we first define indexes such as
47 @c acx meant to become the macro @acindex. First of all, using ``ac_''
48 @c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
49 @c So use something more regular ``acx''. Then you finish with a printed
50 @c index saying ``index is not existent''. Of course: you ought to use
51 @c two letters :( So you use capitals.
53 @c Second, when defining a macro in the TeX world, following spaces are
54 @c eaten. But then, since we embed @acxindex commands that use the end
55 @c of line as an end marker, the whole things wrecks itself. So make
56 @c sure you do *force* an additional end of line, add a ``@c''.
58 @c Finally, you might want to get rid of TeX expansion, using --expand
59 @c with texi2dvi. But then you wake up an old problem: we use macros
60 @c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
62 @c Define an environment variable index.
64 @c Define an output variable index.
66 @c Define a CPP variable index.
68 @c Define an Autoconf macro index that @defmac doesn't write to.
70 @c Define an Autotest macro index that @defmac doesn't write to.
72 @c Define an M4sugar macro index that @defmac doesn't write to.
74 @c Define an index for *foreign* programs: `mv' etc. Used for the
75 @c portability sections and so on.
80 @c Shall we factor AC_ out of the Autoconf macro index etc.?
87 @c Registering an AC_\MACRO\.
94 @ifclear shortindexflag
102 @c Registering an AH_\MACRO\.
103 @macro ahindex{macro}
110 @c Registering an AS_\MACRO\.
111 @ifset shortindexflag
112 @macro asindex{macro}
117 @ifclear shortindexflag
118 @macro asindex{macro}
125 @c Registering an AT_\MACRO\.
126 @ifset shortindexflag
127 @macro atindex{macro}
132 @ifclear shortindexflag
133 @macro atindex{macro}
140 @c Indexing a header.
141 @macro hdrindex{macro}
142 @prindex @file{\macro\}
148 @c Registering an m4_\MACRO\.
149 @ifset shortindexflag
150 @macro msindex{macro}
155 @ifclear shortindexflag
156 @macro msindex{macro}
162 @c Define an index for functions: `alloca' etc. Used for the
163 @c portability sections and so on. We can't use `fn' (aka `fnindex),
164 @c since `@defmac' goes into it => we'd get all the macros too.
166 @c FIXME: Aaarg! It seems there are too many indices for TeX :(
168 @c ! No room for a new @write .
169 @c l.112 @defcodeindex fu
171 @c so don't define yet another one :( Just put some tags before each
172 @c @prindex which is actually a @funindex.
177 @c @c Put the programs and functions into their own index.
178 @c @syncodeindex fu pr
180 @comment %**end of header
181 @comment ========================================================
185 This manual is for @acronym{GNU} Autoconf
186 (version @value{VERSION}, @value{UPDATED}),
187 a package for creating scripts to configure source code packages using
188 templates and an M4 macro package.
190 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
191 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
194 Permission is granted to copy, distribute and/or modify this document
195 under the terms of the @acronym{GNU} Free Documentation License,
196 Version 1.1 or any later version published by the Free Software
197 Foundation; with no Invariant Sections, with the Front-Cover texts
198 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
199 (a) below. A copy of the license is included in the section entitled
200 ``@acronym{GNU} Free Documentation License.''
202 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
203 modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
204 published by the Free Software Foundation raise funds for
205 @acronym{GNU} development.''
211 @dircategory Software development
213 * Autoconf: (autoconf). Create source code configuration scripts.
216 @dircategory Individual utilities
218 * autoscan: (autoconf)autoscan Invocation.
219 Semi-automatic @file{configure.ac} writing
220 * ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
221 * autoconf: (autoconf)autoconf Invocation.
222 How to create configuration scripts
223 * autoreconf: (autoconf)autoreconf Invocation.
224 Remaking multiple @command{configure} scripts
225 * autoheader: (autoconf)autoheader Invocation.
226 How to create configuration templates
227 * autom4te: (autoconf)autom4te Invocation.
228 The Autoconf executables backbone
229 * configure: (autoconf)configure Invocation. Configuring a package.
230 * autoupdate: (autoconf)autoupdate Invocation.
231 Automatic update of @file{configure.ac}
232 * config.status: (autoconf)config.status Invocation. Recreating configurations.
233 * testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
238 @subtitle Creating Automatic Configuration Scripts
239 @subtitle for version @value{VERSION}, @value{UPDATED}
240 @author David MacKenzie
242 @author Akim Demaille
244 @vskip 0pt plus 1filll
257 @c The master menu, created with texinfo-master-menu, goes here.
260 * Introduction:: Autoconf's purpose, strengths, and weaknesses
261 * The GNU Build System:: A set of tools for portable software packages
262 * Making configure Scripts:: How to organize and produce Autoconf scripts
263 * Setup:: Initialization and output
264 * Existing Tests:: Macros that check for particular features
265 * Writing Tests:: How to write new feature checks
266 * Results:: What to do with results from feature checks
267 * Programming in M4:: Layers on top of which Autoconf is written
268 * Writing Autoconf Macros:: Adding new macros to Autoconf
269 * Portable Shell:: Shell script portability pitfalls
270 * Manual Configuration:: Selecting features that can't be guessed
271 * Site Configuration:: Local defaults for @command{configure}
272 * Running configure Scripts:: How to use the Autoconf output
273 * config.status Invocation:: Recreating a configuration
274 * Obsolete Constructs:: Kept for backward compatibility
275 * Using Autotest:: Creating portable test suites
276 * FAQ:: Frequent Autoconf Questions, with answers
277 * History:: History of Autoconf
278 * Copying This Manual:: How to make copies of this manual
279 * Indices:: Indices of symbols, concepts, etc.
282 --- The Detailed Node Listing ---
284 The @acronym{GNU} Build System
286 * Automake:: Escaping Makefile hell
287 * Libtool:: Building libraries portably
288 * Pointers:: More info on the @acronym{GNU} build system
290 Making @command{configure} Scripts
292 * Writing configure.ac:: What to put in an Autoconf input file
293 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
294 * ifnames Invocation:: Listing the conditionals in source code
295 * autoconf Invocation:: How to create configuration scripts
296 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
298 Writing @file{configure.ac}
300 * Shell Script Compiler:: Autoconf as solution of a problem
301 * Autoconf Language:: Programming in Autoconf
302 * configure.ac Layout:: Standard organization of @file{configure.ac}
304 Initialization and Output Files
306 * Initializing configure:: Option processing etc.
307 * Notices:: Copyright, version numbers in @command{configure}
308 * Input:: Where Autoconf should find files
309 * Output:: Outputting results from the configuration
310 * Configuration Actions:: Preparing the output based on results
311 * Configuration Files:: Creating output files
312 * Makefile Substitutions:: Using output variables in @file{Makefile}s
313 * Configuration Headers:: Creating a configuration header file
314 * Configuration Commands:: Running arbitrary instantiation commands
315 * Configuration Links:: Links depending on the configuration
316 * Subdirectories:: Configuring independent packages together
317 * Default Prefix:: Changing the default installation prefix
319 Substitutions in Makefiles
321 * Preset Output Variables:: Output variables that are always set
322 * Installation Directory Variables:: Other preset output variables
323 * Build Directories:: Supporting multiple concurrent compiles
324 * Automatic Remaking:: Makefile rules for configuring
326 Configuration Header Files
328 * Header Templates:: Input for the configuration headers
329 * autoheader Invocation:: How to create configuration templates
330 * Autoheader Macros:: How to specify CPP templates
334 * Common Behavior:: Macros' standard schemes
335 * Alternative Programs:: Selecting between alternative programs
336 * Files:: Checking for the existence of files
337 * Libraries:: Library archives that might be missing
338 * Library Functions:: C library functions that might be missing
339 * Header Files:: Header files that might be missing
340 * Declarations:: Declarations that may be missing
341 * Structures:: Structures or members that might be missing
342 * Types:: Types that might be missing
343 * Compilers and Preprocessors:: Checking for compiling programs
344 * System Services:: Operating system services
345 * UNIX Variants:: Special kludges for specific UNIX variants
349 * Standard Symbols:: Symbols defined by the macros
350 * Default Includes:: Includes used by the generic macros
354 * Particular Programs:: Special handling to find certain programs
355 * Generic Programs:: How to find other programs
359 * Function Portability:: Pitfalls with usual functions
360 * Particular Functions:: Special handling to find certain functions
361 * Generic Functions:: How to find other functions
365 * Header Portability:: Collected knowledge on common headers
366 * Particular Headers:: Special handling to find certain headers
367 * Generic Headers:: How to find other headers
371 * Particular Declarations:: Macros to check for certain declarations
372 * Generic Declarations:: How to find other declarations
376 * Particular Structures:: Macros to check for certain structure members
377 * Generic Structures:: How to find other structure members
381 * Particular Types:: Special handling to find certain types
382 * Generic Types:: How to find other types
384 Compilers and Preprocessors
386 * Specific Compiler Characteristics:: Some portability issues
387 * Generic Compiler Characteristics:: Language independent tests and features
388 * C Compiler:: Checking its characteristics
389 * C++ Compiler:: Likewise
390 * 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 * Run Time:: Testing for run-time 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 * Caching Results:: Speeding up subsequent @command{configure} runs
414 * Printing Messages:: Notifying @command{configure} users
418 * Cache Variable Names:: Shell variables used in caches
419 * Cache Files:: Files @command{configure} uses for caching
420 * Cache Checkpointing:: Loading and saving the cache file
424 * M4 Quotation:: Protecting macros from unwanted expansion
425 * Using autom4te:: The Autoconf executables backbone
426 * Programming in M4sugar:: Convenient pure M4 macros
427 * Programming in M4sh:: Common shell Constructs
431 * Active Characters:: Characters that change the behavior of M4
432 * One Macro Call:: Quotation and one macro call
433 * Quotation and Nested Macros:: Macros calling macros
434 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
435 * Quadrigraphs:: Another way to escape special characters
436 * Quotation Rule Of Thumb:: One parenthesis, one quote
438 Using @command{autom4te}
440 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
441 * Customizing autom4te:: Customizing the Autoconf package
443 Programming in M4sugar
445 * Redefined M4 Macros:: M4 builtins changed in M4sugar
446 * Evaluation Macros:: More quotation and evaluation control
447 * Forbidden Patterns:: Catching unexpanded macros
449 Writing Autoconf Macros
451 * Macro Definitions:: Basic format of an Autoconf macro
452 * Macro Names:: What to call your new macros
453 * Reporting Messages:: Notifying @command{autoconf} users
454 * Dependencies Between Macros:: What to do when macros depend on other macros
455 * Obsoleting Macros:: Warning about old ways of doing things
456 * Coding Style:: Writing Autoconf macros @`a la Autoconf
458 Dependencies Between Macros
460 * Prerequisite Macros:: Ensuring required information
461 * Suggested Ordering:: Warning about possible ordering problems
463 Portable Shell Programming
465 * Shellology:: A zoology of shells
466 * Here-Documents:: Quirks and tricks
467 * File Descriptors:: FDs and redirections
468 * File System Conventions:: File- and pathnames
469 * Shell Substitutions:: Variable and command expansions
470 * Assignments:: Varying side effects of assignments
471 * Parentheses:: Parentheses in shell scripts
472 * Special Shell Variables:: Variables you should not change
473 * Limitations of Builtins:: Portable use of not so portable /bin/sh
474 * Limitations of Usual Tools:: Portable use of portable tools
475 * Limitations of Make:: Portable Makefiles
479 * Specifying Names:: Specifying the system type
480 * Canonicalizing:: Getting the canonical system type
481 * Using System Type:: What to do with the system type
485 * External Software:: Working with other optional software
486 * Package Options:: Selecting optional features
487 * Pretty Help Strings:: Formatting help string
488 * Site Details:: Configuring site details
489 * Transforming Names:: Changing program names when installing
490 * Site Defaults:: Giving @command{configure} local defaults
492 Transforming Program Names When Installing
494 * Transformation Options:: @command{configure} options to transform names
495 * Transformation Examples:: Sample uses of transforming names
496 * Transformation Rules:: @file{Makefile} uses of transforming names
498 Running @command{configure} Scripts
500 * Basic Installation:: Instructions for typical cases
501 * Compilers and Options:: Selecting compilers and optimization
502 * Multiple Architectures:: Compiling for multiple architectures at once
503 * Installation Names:: Installing in different directories
504 * Optional Features:: Selecting optional features
505 * System Type:: Specifying the system type
506 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
507 * Defining Variables:: Specifying the compiler etc.
508 * configure Invocation:: Changing how @command{configure} runs
512 * Obsolete config.status Use:: Different calling convention
513 * acconfig.h:: Additional entries in @file{config.h.in}
514 * autoupdate Invocation:: Automatic update of @file{configure.ac}
515 * Obsolete Macros:: Backward compatibility macros
516 * Autoconf 1:: Tips for upgrading your files
517 * Autoconf 2.13:: Some fresher tips
519 Upgrading From Version 1
521 * Changed File Names:: Files you might rename
522 * Changed Makefiles:: New things to put in @file{Makefile.in}
523 * Changed Macros:: Macro calls you might replace
524 * Changed Results:: Changes in how to check test results
525 * Changed Macro Writing:: Better ways to write your own macros
527 Upgrading From Version 2.13
529 * Changed Quotation:: Broken code which used to work
530 * New Macros:: Interaction with foreign macros
531 * Hosts and Cross-Compilation:: Bugward compatibility kludges
532 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
533 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
535 Generating Test Suites with Autotest
537 * Using an Autotest Test Suite:: Autotest and the user
538 * Writing testsuite.at:: Autotest macros
539 * testsuite Invocation:: Running @command{testsuite} scripts
540 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
542 Using an Autotest Test Suite
544 * testsuite Scripts:: The concepts of Autotest
545 * Autotest Logs:: Their contents
547 Frequent Autoconf Questions, with answers
549 * Distributing:: Distributing @command{configure} scripts
550 * Why GNU m4:: Why not use the standard M4?
551 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
552 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
553 * Defining Directories:: Passing @code{datadir} to program
554 * autom4te.cache:: What is it? Can I remove it?
555 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
559 * Genesis:: Prehistory and naming of @command{configure}
560 * Exodus:: The plagues of M4 and Perl
561 * Leviticus:: The priestly code of portability arrives
562 * Numbers:: Growth and contributors
563 * Deuteronomy:: Approaching the promises of easy configuration
567 * GNU Free Documentation License:: License for copying this manual
571 * Environment Variable Index:: Index of environment variables used
572 * Output Variable Index:: Index of variables set in output files
573 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
574 * Autoconf Macro Index:: Index of Autoconf macros
575 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
576 * Autotest Macro Index:: Index of Autotest macros
577 * Program & Function Index:: Index of those with portability problems
578 * Concept Index:: General index
583 @c ============================================================= Introduction.
586 @chapter Introduction
590 A physicist, an engineer, and a computer scientist were discussing the
591 nature of God. ``Surely a Physicist,'' said the physicist, ``because
592 early in the Creation, God made Light; and you know, Maxwell's
593 equations, the dual nature of electromagnetic waves, the relativistic
594 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
595 before making Light, God split the Chaos into Land and Water; it takes a
596 hell of an engineer to handle that big amount of mud, and orderly
597 separation of solids from liquids@dots{}'' The computer scientist
598 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
602 @c (via Franc,ois Pinard)
604 Autoconf is a tool for producing shell scripts that automatically
605 configure software source code packages to adapt to many kinds of
606 @sc{unix}-like systems. The configuration scripts produced by Autoconf
607 are independent of Autoconf when they are run, so their users do not
608 need to have Autoconf.
610 The configuration scripts produced by Autoconf require no manual user
611 intervention when run; they do not normally even need an argument
612 specifying the system type. Instead, they individually test for the
613 presence of each feature that the software package they are for might need.
614 (Before each check, they print a one-line message stating what they are
615 checking for, so the user doesn't get too bored while waiting for the
616 script to finish.) As a result, they deal well with systems that are
617 hybrids or customized from the more common @sc{unix} variants. There is
618 no need to maintain files that list the features supported by each
619 release of each variant of @sc{unix}.
621 For each software package that Autoconf is used with, it creates a
622 configuration script from a template file that lists the system features
623 that the package needs or can use. After the shell code to recognize
624 and respond to a system feature has been written, Autoconf allows it to
625 be shared by many software packages that can use (or need) that feature.
626 If it later turns out that the shell code needs adjustment for some
627 reason, it needs to be changed in only one place; all of the
628 configuration scripts can be regenerated automatically to take advantage
631 The Metaconfig package is similar in purpose to Autoconf, but the
632 scripts it produces require manual user intervention, which is quite
633 inconvenient when configuring large source trees. Unlike Metaconfig
634 scripts, Autoconf scripts can support cross-compiling, if some care is
635 taken in writing them.
637 Autoconf does not solve all problems related to making portable
638 software packages---for a more complete solution, it should be used in
639 concert with other @acronym{GNU} build tools like Automake and
640 Libtool. These other tools take on jobs like the creation of a
641 portable, recursive @file{Makefile} with all of the standard targets,
642 linking of shared libraries, and so on. @xref{The GNU Build System},
643 for more information.
645 Autoconf imposes some restrictions on the names of macros used with
646 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
648 Autoconf requires @acronym{GNU} M4 in order to generate the scripts. It uses
649 features that some @sc{unix} versions of M4, including @acronym{GNU} M4 1.3,
650 do not have. You must use version 1.4 or later of @acronym{GNU} M4.
652 @xref{Autoconf 1}, for information about upgrading from version 1.
653 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
654 for answers to some common questions about Autoconf.
657 See the @href{http://www.gnu.org/software/autoconf/autoconf.html,
658 Autoconf web page} for up-to-date information, details on the mailing
659 lists, pointers to a list of known bugs, etc.
661 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
664 Bug reports should be preferably submitted to the
665 @href{http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=autoconf,
666 Autoconf Gnats database}, or sent to @email{bug-autoconf@@gnu.org, the
667 Autoconf Bugs mailing list}. If possible, first check that your bug is
668 not already solved in current development versions, and that it has not
669 been reported yet. Be sure to include all the needed information and a
670 short @file{configure.ac} that demonstrates the problem.
672 Autoconf's development tree is accessible via @acronym{CVS}; see the Autoconf
673 web page for details. There is also a
674 @href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @acronym{CVS}web
675 interface to the Autoconf development tree}. Patches relative to the
676 current @acronym{CVS} version can be sent for review to the
677 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
679 Because of its mission, Autoconf includes only a set of often-used
680 macros that have already demonstrated their usefulness. Nevertheless,
681 if you wish to share your macros, or find existing ones, see the
682 @href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
683 Archive}, which is kindly run by @email{simons@@computer.org,
687 @c ================================================= The GNU Build System
689 @node The GNU Build System
690 @chapter The @acronym{GNU} Build System
691 @cindex GNU build system
693 Autoconf solves an important problem---reliable discovery of
694 system-specific build and run-time information---but this is only one
695 piece of the puzzle for the development of portable software. To this
696 end, the @acronym{GNU} project has developed a suite of integrated
697 utilities to finish the job Autoconf started: the @acronym{GNU} build
698 system, whose most important components are Autoconf, Automake, and
699 Libtool. In this chapter, we introduce you to those tools, point you
700 to sources of more information, and try to convince you to use the
701 entire @acronym{GNU} build system for your software.
704 * Automake:: Escaping Makefile hell
705 * Libtool:: Building libraries portably
706 * Pointers:: More info on the @acronym{GNU} build system
712 The ubiquity of @command{make} means that a @file{Makefile} is almost the
713 only viable way to distribute automatic build rules for software, but
714 one quickly runs into @command{make}'s numerous limitations. Its lack of
715 support for automatic dependency tracking, recursive builds in
716 subdirectories, reliable timestamps (e.g., for network filesystems), and
717 so on, mean that developers must painfully (and often incorrectly)
718 reinvent the wheel for each project. Portability is non-trivial, thanks
719 to the quirks of @command{make} on many systems. On top of all this is the
720 manual labor required to implement the many standard targets that users
721 have come to expect (@code{make install}, @code{make distclean},
722 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
723 you also have to insert repetitive code in your @code{Makefile.in} to
724 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
725 provided by @command{configure}. Into this mess steps @dfn{Automake}.
728 Automake allows you to specify your build needs in a @code{Makefile.am}
729 file with a vastly simpler and more powerful syntax than that of a plain
730 @code{Makefile}, and then generates a portable @code{Makefile.in} for
731 use with Autoconf. For example, the @code{Makefile.am} to build and
732 install a simple ``Hello world'' program might look like:
736 hello_SOURCES = hello.c
740 The resulting @code{Makefile.in} (~400 lines) automatically supports all
741 the standard targets, the substitutions provided by Autoconf, automatic
742 dependency tracking, @code{VPATH} building, and so on. @command{make} will
743 build the @code{hello} program, and @code{make install} will install it
744 in @file{/usr/local/bin} (or whatever prefix was given to
745 @command{configure}, if not @file{/usr/local}).
747 The benefits of Automake increase for larger packages (especially ones
748 with subdirectories), but even for small programs the added convenience
749 and portability can be substantial. And that's not all@enddots{}
754 Very often, one wants to build not only programs, but libraries, so that
755 other programs can benefit from the fruits of your labor. Ideally, one
756 would like to produce @emph{shared} (dynamically linked) libraries,
757 which can be used by multiple programs without duplication on disk or in
758 memory and can be updated independently of the linked programs.
759 Producing shared libraries portably, however, is the stuff of
760 nightmares---each system has its own incompatible tools, compiler flags,
761 and magic incantations. Fortunately, @acronym{GNU} provides a solution:
765 Libtool handles all the requirements of building shared libraries for
766 you, and at this time seems to be the @emph{only} way to do so with any
767 portability. It also handles many other headaches, such as: the
768 interaction of @code{Makefile} rules with the variable suffixes of
769 shared libraries, linking reliably with shared libraries before they are
770 installed by the superuser, and supplying a consistent versioning system
771 (so that different versions of a library can be installed or upgraded
772 without breaking binary compatibility). Although Libtool, like
773 Autoconf, can be used on its own, it is most simply utilized in
774 conjunction with Automake---there, Libtool is used automatically
775 whenever shared libraries are needed, and you need not know its syntax.
780 Developers who are used to the simplicity of @command{make} for small
781 projects on a single system might be daunted at the prospect of
782 learning to use Automake and Autoconf. As your software is
783 distributed to more and more users, however, you will otherwise
784 quickly find yourself putting lots of effort into reinventing the
785 services that the @acronym{GNU} build tools provide, and making the
786 same mistakes that they once made and overcame. (Besides, since
787 you're already learning Autoconf, Automake will be a piece of cake.)
789 There are a number of places that you can go to for more information on
790 the @acronym{GNU} build tools.
797 @href{http://www.gnu.org/software/autoconf/,Autoconf},
798 @href{http://www.gnu.org/software/automake/,Automake}, and
799 @href{http://www.gnu.org/software/libtool/,Libtool}.
801 @item Automake Manual
803 @xref{Top,,Automake,automake,@acronym{GNU} Automake}, for more
804 information on Automake.
808 The book @cite{@acronym{GNU} Autoconf, Automake and
809 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
810 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. New
811 Riders, 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
812 build environment. You can also find the entire book on-line at
813 @href{http://sources.redhat.com/autobook/,``The Goat Book'' home
816 @item Tutorials and Examples
818 The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
819 maintains links to a number of Autoconf/Automake tutorials online, and
820 also links to the @href{http://www.gnu.org/software/ac-archive/,
821 Autoconf Macro Archive}.
825 @c ================================================= Making configure Scripts.
827 @node Making configure Scripts
828 @chapter Making @command{configure} Scripts
829 @cindex @file{aclocal.m4}
830 @cindex @command{configure}
832 The configuration scripts that Autoconf produces are by convention
833 called @command{configure}. When run, @command{configure} creates several
834 files, replacing configuration parameters in them with appropriate
835 values. The files that @command{configure} creates are:
839 one or more @file{Makefile} files, usually one in each subdirectory of the
840 package (@pxref{Makefile Substitutions});
843 optionally, a C header file, the name of which is configurable,
844 containing @code{#define} directives (@pxref{Configuration Headers});
847 a shell script called @file{config.status} that, when run, will recreate
848 the files listed above (@pxref{config.status Invocation});
851 an optional shell script normally called @file{config.cache}
852 (created when using @samp{configure --config-cache}) that
853 saves the results of running many of the tests (@pxref{Cache Files});
856 a file called @file{config.log} containing any messages produced by
857 compilers, to help debugging if @command{configure} makes a mistake.
860 @cindex @file{configure.in}
861 @cindex @file{configure.ac}
862 To create a @command{configure} script with Autoconf, you need to write an
863 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
864 @command{autoconf} on it. If you write your own feature tests to
865 supplement those that come with Autoconf, you might also write files
866 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
867 file to contain @code{#define} directives, you might also run
868 @command{autoheader}, and you will distribute the generated file
869 @file{config.h.in} with the package.
871 Here is a diagram showing how the files that can be used in
872 configuration are produced. Programs that are executed are suffixed by
873 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
874 @command{autoconf} and @command{autoheader} also read the installed Autoconf
875 macro files (by reading @file{autoconf.m4}).
878 Files used in preparing a software package for distribution:
880 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
884 | .------> autoconf* -----> configure
886 | `-----> [autoheader*] --> [config.h.in]
890 Makefile.in -------------------------------> Makefile.in
894 Files used in configuring a software package:
897 .-------------> [config.cache]
898 configure* ------------+-------------> config.log
900 [config.h.in] -. v .-> [config.h] -.
901 +--> config.status* -+ +--> make*
902 Makefile.in ---' `-> Makefile ---'
907 * Writing configure.ac:: What to put in an Autoconf input file
908 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
909 * ifnames Invocation:: Listing the conditionals in source code
910 * autoconf Invocation:: How to create configuration scripts
911 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
914 @node Writing configure.ac
915 @section Writing @file{configure.ac}
917 To produce a @command{configure} script for a software package, create a
918 file called @file{configure.ac} that contains invocations of the
919 Autoconf macros that test the system features your package needs or can
920 use. Autoconf macros already exist to check for many features; see
921 @ref{Existing Tests}, for their descriptions. For most other features,
922 you can use Autoconf template macros to produce custom checks; see
923 @ref{Writing Tests}, for information about them. For especially tricky
924 or specialized features, @file{configure.ac} might need to contain some
925 hand-crafted shell commands; see @ref{Portable Shell}. The
926 @command{autoscan} program can give you a good start in writing
927 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
929 Previous versions of Autoconf promoted the name @file{configure.in},
930 which is somewhat ambiguous (the tool needed to process this file is not
931 described by its extension), and introduces a slight confusion with
932 @file{config.h.in} and so on (for which @samp{.in} means ``to be
933 processed by @command{configure}''). Using @file{configure.ac} is now
937 * Shell Script Compiler:: Autoconf as solution of a problem
938 * Autoconf Language:: Programming in Autoconf
939 * configure.ac Layout:: Standard organization of @file{configure.ac}
942 @node Shell Script Compiler
943 @subsection A Shell Script Compiler
945 Just as for any other computer language, in order to properly program
946 @file{configure.ac} in Autoconf you must understand @emph{what} problem
947 the language tries to address and @emph{how} it does so.
949 The problem Autoconf addresses is that the world is a mess. After all,
950 you are using Autoconf in order to have your package compile easily on
951 all sorts of different systems, some of them being extremely hostile.
952 Autoconf itself bears the price for these differences: @command{configure}
953 must run on all those systems, and thus @command{configure} must limit itself
954 to their lowest common denominator of features.
956 Naturally, you might then think of shell scripts; who needs
957 @command{autoconf}? A set of properly written shell functions is enough to
958 make it easy to write @command{configure} scripts by hand. Sigh!
959 Unfortunately, shell functions do not belong to the least common
960 denominator; therefore, where you would like to define a function and
961 use it ten times, you would instead need to copy its body ten times.
963 So, what is really needed is some kind of compiler, @command{autoconf},
964 that takes an Autoconf program, @file{configure.ac}, and transforms it
965 into a portable shell script, @command{configure}.
967 How does @command{autoconf} perform this task?
969 There are two obvious possibilities: creating a brand new language or
970 extending an existing one. The former option is very attractive: all
971 sorts of optimizations could easily be implemented in the compiler and
972 many rigorous checks could be performed on the Autoconf program
973 (e.g., rejecting any non-portable construct). Alternatively, you can
974 extend an existing language, such as the @code{sh} (Bourne shell)
977 Autoconf does the latter: it is a layer on top of @code{sh}. It was
978 therefore most convenient to implement @command{autoconf} as a macro
979 expander: a program that repeatedly performs @dfn{macro expansions} on
980 text input, replacing macro calls with macro bodies and producing a pure
981 @code{sh} script in the end. Instead of implementing a dedicated
982 Autoconf macro expander, it is natural to use an existing
983 general-purpose macro language, such as M4, and implement the extensions
984 as a set of M4 macros.
987 @node Autoconf Language
988 @subsection The Autoconf Language
991 The Autoconf language is very different from many other computer
992 languages because it treats actual code the same as plain text. Whereas
993 in C, for instance, data and instructions have very different syntactic
994 status, in Autoconf their status is rigorously the same. Therefore, we
995 need a means to distinguish literal strings from text to be expanded:
998 When calling macros that take arguments, there must not be any blank
999 space between the macro name and the open parenthesis. Arguments should
1000 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1001 separated by commas. Any leading spaces in arguments are ignored,
1002 unless they are quoted. You may safely leave out the quotes when the
1003 argument is simple text, but @emph{always} quote complex arguments such
1004 as other macro calls. This rule applies recursively for every macro
1005 call, including macros called from other macros.
1010 AC_CHECK_HEADER([stdio.h],
1011 [AC_DEFINE([HAVE_STDIO_H])],
1012 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1016 is quoted properly. You may safely simplify its quotation to:
1019 AC_CHECK_HEADER(stdio.h,
1020 [AC_DEFINE(HAVE_STDIO_H)],
1021 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1025 Notice that the argument of @code{AC_MSG_ERROR} is still quoted;
1026 otherwise, its comma would have been interpreted as an argument separator.
1028 The following example is wrong and dangerous, as it is underquoted:
1031 AC_CHECK_HEADER(stdio.h,
1032 AC_DEFINE(HAVE_STDIO_H),
1033 AC_MSG_ERROR([Sorry, can't do anything for you]))
1036 In other cases, you may have to use text that also resembles a macro
1037 call. You must quote that text even when it is not passed as a macro
1041 echo "Hard rock was here! --[AC_DC]"
1045 which will result in
1048 echo "Hard rock was here! --AC_DC"
1052 When you use the same text in a macro argument, you must therefore have
1053 an extra quotation level (since one is stripped away by the macro
1054 substitution). In general, then, it is a good idea to @emph{use double
1055 quoting for all literal string arguments}:
1058 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1061 You are now able to understand one of the constructs of Autoconf that
1062 has been continually misunderstood@dots{} The rule of thumb is that
1063 @emph{whenever you expect macro expansion, expect quote expansion};
1064 i.e., expect one level of quotes to be lost. For instance:
1067 AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])
1071 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1072 @samp{char b[10];} and will be expanded once, which results in
1073 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1074 address this issue via the M4 @code{changequote} primitive, but do not
1075 use it!) Let's take a closer look: the author meant the first argument
1076 to be understood as a literal, and therefore it must be quoted twice:
1079 AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])
1083 Voil@`a, you actually produce @samp{char b[10];} this time!
1085 The careful reader will notice that, according to these guidelines, the
1086 ``properly'' quoted @code{AC_CHECK_HEADER} example above is actually
1087 lacking three pairs of quotes! Nevertheless, for the sake of readability,
1088 double quotation of literals is used only where needed in this manual.
1090 Some macros take optional arguments, which this documentation represents
1091 as @ovar{arg} (not to be confused with the quote characters). You may
1092 just leave them empty, or use @samp{[]} to make the emptiness of the
1093 argument explicit, or you may simply omit the trailing commas. The
1094 three lines below are equivalent:
1097 AC_CHECK_HEADERS(stdio.h, [], [], [])
1098 AC_CHECK_HEADERS(stdio.h,,,)
1099 AC_CHECK_HEADERS(stdio.h)
1102 It is best to put each macro call on its own line in
1103 @file{configure.ac}. Most of the macros don't add extra newlines; they
1104 rely on the newline after the macro call to terminate the commands.
1105 This approach makes the generated @command{configure} script a little
1106 easier to read by not inserting lots of blank lines. It is generally
1107 safe to set shell variables on the same line as a macro call, because
1108 the shell allows assignments without intervening newlines.
1110 You can include comments in @file{configure.ac} files by starting them
1111 with the @samp{#}. For example, it is helpful to begin
1112 @file{configure.ac} files with a line like this:
1115 # Process this file with autoconf to produce a configure script.
1118 @node configure.ac Layout
1119 @subsection Standard @file{configure.ac} Layout
1121 The order in which @file{configure.ac} calls the Autoconf macros is not
1122 important, with a few exceptions. Every @file{configure.ac} must
1123 contain a call to @code{AC_INIT} before the checks, and a call to
1124 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1125 rely on other macros having been called first, because they check
1126 previously set values of some variables to decide what to do. These
1127 macros are noted in the individual descriptions (@pxref{Existing
1128 Tests}), and they also warn you when @command{configure} is created if they
1129 are called out of order.
1131 To encourage consistency, here is a suggested order for calling the
1132 Autoconf macros. Generally speaking, the things near the end of this
1133 list are those that could depend on things earlier in it. For example,
1134 library functions could be affected by types and libraries.
1138 Autoconf requirements
1139 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1140 information on the package
1142 checks for libraries
1143 checks for header files
1145 checks for structures
1146 checks for compiler characteristics
1147 checks for library functions
1148 checks for system services
1149 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1155 @node autoscan Invocation
1156 @section Using @command{autoscan} to Create @file{configure.ac}
1157 @cindex @command{autoscan}
1159 The @command{autoscan} program can help you create and/or maintain a
1160 @file{configure.ac} file for a software package. @command{autoscan}
1161 examines source files in the directory tree rooted at a directory given
1162 as a command line argument, or the current directory if none is given.
1163 It searches the source files for common portability problems and creates
1164 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1165 for that package, and checks a possibly existing @file{configure.ac} for
1168 When using @command{autoscan} to create a @file{configure.ac}, you
1169 should manually examine @file{configure.scan} before renaming it to
1170 @file{configure.ac}; it will probably need some adjustments.
1171 Occasionally, @command{autoscan} outputs a macro in the wrong order
1172 relative to another macro, so that @command{autoconf} produces a warning;
1173 you need to move such macros manually. Also, if you want the package to
1174 use a configuration header file, you must add a call to
1175 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1176 also have to change or add some @code{#if} directives to your program in
1177 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1178 information about a program that can help with that job).
1180 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1181 consider adding its suggestions. The file @file{autoscan.log} will
1182 contain detailed information on why a macro is requested.
1184 @command{autoscan} uses several data files (installed along with Autoconf)
1185 to determine which macros to output when it finds particular symbols in
1186 a package's source files. These data files all have the same format:
1187 each line consists of a symbol, whitespace, and the Autoconf macro to
1188 output if that symbol is encountered. Lines starting with @samp{#} are
1191 @command{autoscan} accepts the following options:
1196 Print a summary of the command line options and exit.
1200 Print the version number of Autoconf and exit.
1204 Print the names of the files it examines and the potentially interesting
1205 symbols it finds in them. This output can be voluminous.
1207 @item --include=@var{dir}
1209 Append @var{dir} to the include path. Multiple invocations accumulate.
1211 @item --prepend-include=@var{dir}
1213 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1216 @node ifnames Invocation
1217 @section Using @command{ifnames} to List Conditionals
1218 @cindex @command{ifnames}
1220 @command{ifnames} can help you write @file{configure.ac} for a software
1221 package. It prints the identifiers that the package already uses in C
1222 preprocessor conditionals. If a package has already been set up to have
1223 some portability, @command{ifnames} can thus help you figure out what its
1224 @command{configure} needs to check for. It may help fill in some gaps in a
1225 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1228 @command{ifnames} scans all of the C source files named on the command line
1229 (or the standard input, if none are given) and writes to the standard
1230 output a sorted list of all the identifiers that appear in those files
1231 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1232 directives. It prints each identifier on a line, followed by a
1233 space-separated list of the files in which that identifier occurs.
1236 @command{ifnames} accepts the following options:
1241 Print a summary of the command line options and exit.
1245 Print the version number of Autoconf and exit.
1248 @node autoconf Invocation
1249 @section Using @command{autoconf} to Create @command{configure}
1250 @cindex @command{autoconf}
1252 To create @command{configure} from @file{configure.ac}, run the
1253 @command{autoconf} program with no arguments. @command{autoconf} processes
1254 @file{configure.ac} with the M4 macro processor, using the
1255 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1256 file instead of @file{configure.ac} and writes the configuration script
1257 to the standard output instead of to @command{configure}. If you give
1258 @command{autoconf} the argument @option{-}, it reads from the standard
1259 input instead of @file{configure.ac} and writes the configuration script
1260 to the standard output.
1262 The Autoconf macros are defined in several files. Some of the files are
1263 distributed with Autoconf; @command{autoconf} reads them first. Then it
1264 looks for the optional file @file{acsite.m4} in the directory that
1265 contains the distributed Autoconf macro files, and for the optional file
1266 @file{aclocal.m4} in the current directory. Those files can contain
1267 your site's or the package's own Autoconf macro definitions
1268 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1269 defined in more than one of the files that @command{autoconf} reads, the
1270 last definition it reads overrides the earlier ones.
1272 @command{autoconf} accepts the following options:
1277 Print a summary of the command line options and exit.
1281 Print the version number of Autoconf and exit.
1285 Report processing steps.
1289 Don't remove the temporary files.
1293 Remake @file{configure} even if newer than its input files.
1295 @item --include=@var{dir}
1297 Append @var{dir} to the include path. Multiple invocations accumulate.
1299 @item --prepend-include=@var{dir}
1301 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1303 @item --output=@var{file}
1304 @itemx -o @var{file}
1305 Save output (script or trace) to @var{file}. The file @option{-} stands
1306 for the standard output.
1308 @item --warnings=@var{category}
1309 @itemx -W @var{category}
1311 Report the warnings related to @var{category} (which can actually be a
1312 comma separated list). @xref{Reporting Messages}, macro
1313 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1318 report all the warnings
1324 treats warnings as errors
1326 @item no-@var{category}
1327 disable warnings falling into @var{category}
1330 Warnings about @samp{syntax} are enabled by default, and the environment
1331 variable @code{WARNINGS}, a comma separated list of categories, is
1332 honored. Passing @samp{-W @var{category}} will actually behave as if
1333 you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}. If
1334 you want to disable the defaults and @code{WARNINGS}, but (for example)
1335 enable the warnings about obsolete constructs, you would use @option{-W
1339 @cindex Macro invocation stack
1340 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1341 displays a back trace for errors, but not for warnings; if you want
1342 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1345 @item --trace=@var{macro}[:@var{format}]
1346 @itemx -t @var{macro}[:@var{format}]
1347 Do not create the @command{configure} script, but list the calls to
1348 @var{macro} according to the @var{format}. Multiple @option{--trace}
1349 arguments can be used to list several macros. Multiple @option{--trace}
1350 arguments for a single macro are not cumulative; instead, you should
1351 just make @var{format} as long as needed.
1353 The @var{format} is a regular string, with newlines if desired, and
1354 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1355 @ref{autom4te Invocation}, for details on the @var{format}.
1357 @item --initialization
1359 By default, @option{--trace} does not trace the initialization of the
1360 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1361 results in a noticeable speedup, but can be disabled by this option.
1365 It is often necessary to check the content of a @file{configure.ac}
1366 file, but parsing it yourself is extremely fragile and error-prone. It
1367 is suggested that you rely upon @option{--trace} to scan
1368 @file{configure.ac}. For instance, to find the list of variables that
1369 are substituted, use:
1373 $ @kbd{autoconf -t AC_SUBST}
1374 configure.ac:2:AC_SUBST:ECHO_C
1375 configure.ac:2:AC_SUBST:ECHO_N
1376 configure.ac:2:AC_SUBST:ECHO_T
1377 @i{More traces deleted}
1382 The example below highlights the difference between @samp{$@@},
1383 @samp{$*}, and @strong{$%}.
1387 $ @kbd{cat configure.ac}
1388 AC_DEFINE(This, is, [an
1390 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1397 $: This:is:an [example]
1402 The @var{format} gives you a lot of freedom:
1406 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1407 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1408 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1409 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1410 @i{More traces deleted}
1415 A long @var{separator} can be used to improve the readability of complex
1416 structures, and to ease their parsing (for instance when no single
1417 character is suitable as a separator):
1421 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1422 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1423 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1424 AUTOMAKE|:::::|automake|:::::|$missing_dir
1425 @i{More traces deleted}
1429 @node autoreconf Invocation
1430 @section Using @command{autoreconf} to Update @command{configure} Scripts
1431 @cindex @command{autoreconf}
1433 Installing the various components of the @acronym{GNU} Build System can be
1434 tedious: running @command{autopoint} for Gettext, @command{automake} for
1435 @file{Makefile.in} etc.@: in each directory. It may be needed either
1436 because some tools such as @command{automake} have been updated on your
1437 system, or because some of the sources such as @file{configure.ac} have
1438 been updated, or finally, simply in order to install the @acronym{GNU} Build
1439 System in a fresh tree.
1441 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1442 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1443 @command{autopoint} (when appropriate) repeatedly to update the
1444 @acronym{GNU} Build System in the specified directories and their
1445 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1446 those files that are older than their sources.
1448 If you install a new version of some tool, you can make
1449 @command{autoreconf} remake @emph{all} of the files by giving it the
1450 @option{--force} option.
1452 @xref{Automatic Remaking}, for @file{Makefile} rules to automatically
1453 remake @command{configure} scripts when their source files change. That
1454 method handles the timestamps of configuration header templates
1455 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1456 @option{--localdir=@var{dir}}.
1459 @command{autoreconf} accepts the following options:
1464 Print a summary of the command line options and exit.
1468 Print the version number of Autoconf and exit.
1471 Print the name of each directory where @command{autoreconf} runs
1472 @command{autoconf} (and @command{autoheader}, if appropriate).
1476 Don't remove the temporary files.
1480 Remake even @file{configure} scripts and configuration headers that are
1481 newer than their input files (@file{configure.ac} and, if present,
1486 Install the missing auxiliary files in the package. By default, files
1487 are copied; this can be changed with @option{--symlink}.
1489 This option triggers calls to @samp{automake --add-missing},
1490 @samp{libtoolize}, @samp{autopoint}, etc.
1494 When used with @option{--install}, install symbolic links to the missing
1495 auxiliary files instead of copying them.
1499 When the directories were configured, update the configuration by
1500 running @samp{./config.status --recheck && ./config.status}, and then
1503 @item --include=@var{dir}
1505 Append @var{dir} to the include path. Multiple invocations accumulate.
1507 @item --prepend-include=@var{dir}
1509 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1511 @item --warnings=@var{category}
1512 @itemx -W @var{category}
1514 Report the warnings related to @var{category} (which can actually be a
1515 comma separated list).
1519 related to cross compilation issues.
1522 report the uses of obsolete constructs.
1528 dubious syntactic constructs.
1531 report all the warnings
1537 treats warnings as errors
1539 @item no-@var{category}
1540 disable warnings falling into @var{category}
1543 Warnings about @samp{syntax} are enabled by default, and the environment
1544 variable @code{WARNINGS}, a comma separated list of categories, is
1545 honored. Passing @samp{-W @var{category}} will actually behave as if
1546 you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}. If
1547 you want to disable the defaults and @code{WARNINGS}, but (for example)
1548 enable the warnings about obsolete constructs, you would use @option{-W
1553 @c ========================================= Initialization and Output Files.
1556 @chapter Initialization and Output Files
1558 Autoconf-generated @command{configure} scripts need some information about
1559 how to initialize, such as how to find the package's source files and
1560 about the output files to produce. The following sections describe the
1561 initialization and the creation of output files.
1564 * Initializing configure:: Option processing etc.
1565 * Notices:: Copyright, version numbers in @command{configure}
1566 * Input:: Where Autoconf should find files
1567 * Output:: Outputting results from the configuration
1568 * Configuration Actions:: Preparing the output based on results
1569 * Configuration Files:: Creating output files
1570 * Makefile Substitutions:: Using output variables in @file{Makefile}s
1571 * Configuration Headers:: Creating a configuration header file
1572 * Configuration Commands:: Running arbitrary instantiation commands
1573 * Configuration Links:: Links depending on the configuration
1574 * Subdirectories:: Configuring independent packages together
1575 * Default Prefix:: Changing the default installation prefix
1578 @node Initializing configure
1579 @section Initializing @command{configure}
1581 Every @command{configure} script must call @code{AC_INIT} before doing
1582 anything else. The only other required macro is @code{AC_OUTPUT}
1585 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1587 Process any command-line arguments and perform various initializations
1590 Set the name of the @var{package} and its @var{version}. These are
1591 typically used in @option{--version} support, including that of
1592 @command{configure}. The optional argument @var{bug-report} should be
1593 the email to which users should send bug reports. The package
1594 @var{tarname} differs from @var{package}: the latter designates the full
1595 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1596 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1597 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1598 other than alphanumerics and underscores are changed to @samp{-}.
1600 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1601 there should not be any shell computation, but they can be computed by
1604 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1605 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1606 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1609 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1610 @acindex{PACKAGE_NAME}
1611 @ovindex PACKAGE_NAME
1612 @cvindex PACKAGE_NAME
1613 Exactly @var{package}.
1615 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1616 @acindex{PACKAGE_TARNAME}
1617 @ovindex PACKAGE_TARNAME
1618 @cvindex PACKAGE_TARNAME
1619 Exactly @var{tarname}.
1621 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1622 @acindex{PACKAGE_VERSION}
1623 @ovindex PACKAGE_VERSION
1624 @cvindex PACKAGE_VERSION
1625 Exactly @var{version}.
1627 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1628 @acindex{PACKAGE_STRING}
1629 @ovindex PACKAGE_STRING
1630 @cvindex PACKAGE_STRING
1631 Exactly @samp{@var{package} @var{version}}.
1633 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1634 @acindex{PACKAGE_BUGREPORT}
1635 @ovindex PACKAGE_BUGREPORT
1636 @cvindex PACKAGE_BUGREPORT
1637 Exactly @var{bug-report}.
1643 @section Notices in @command{configure}
1644 @cindex Notices in @command{configure}
1646 The following macros manage version numbers for @command{configure}
1647 scripts. Using them is optional.
1649 @c FIXME: AC_PREREQ should not be here
1650 @defmac AC_PREREQ (@var{version})
1653 Ensure that a recent enough version of Autoconf is being used. If the
1654 version of Autoconf being used to create @command{configure} is
1655 earlier than @var{version}, print an error message to the standard
1656 error output and exit with failure (exit status is 63). For example:
1659 AC_PREREQ(@value{VERSION})
1662 This macro is the only macro that may be used before @code{AC_INIT}, but
1663 for consistency, you are invited not to do so.
1666 @defmac AC_COPYRIGHT (@var{copyright-notice})
1668 @cindex Copyright Notice
1669 State that, in addition to the Free Software Foundation's copyright on
1670 the Autoconf macros, parts of your @command{configure} are covered by the
1671 @var{copyright-notice}.
1673 The @var{copyright-notice} will show up in both the head of
1674 @command{configure} and in @samp{configure --version}.
1678 @defmac AC_REVISION (@var{revision-info})
1681 Copy revision stamp @var{revision-info} into the @command{configure}
1682 script, with any dollar signs or double-quotes removed. This macro lets
1683 you put a revision stamp from @file{configure.ac} into @command{configure}
1684 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1685 @command{configure}. That way, you can determine easily which revision of
1686 @file{configure.ac} a particular @command{configure} corresponds to.
1688 For example, this line in @file{configure.ac}:
1690 @c The asis prevents RCS from changing the example in the manual.
1692 AC_REVISION($@asis{Revision: 1.30 }$)
1696 produces this in @command{configure}:
1700 # From configure.ac Revision: 1.30
1706 @section Finding @command{configure} Input
1709 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1710 @acindex{CONFIG_SRCDIR}
1711 @var{unique-file-in-source-dir} is some file that is in the package's
1712 source directory; @command{configure} checks for this file's existence to
1713 make sure that the directory that it is told contains the source code in
1714 fact does. Occasionally people accidentally specify the wrong directory
1715 with @option{--srcdir}; this is a safety check. @xref{configure
1716 Invocation}, for more information.
1720 @c FIXME: Remove definitively once --install explained.
1722 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1723 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1724 @c to split the macros in several files. In this case, Autoconf must be
1725 @c told which files to load, and in which order.
1727 @c @defmac AC_INCLUDE (@var{file}@dots{})
1728 @c @acindex{INCLUDE}
1729 @c @c FIXME: There is no longer shell globbing.
1730 @c Read the macro definitions that appear in the listed files. A list of
1731 @c space-separated filenames or shell globbing patterns is expected. The
1732 @c files will be read in the order they're listed.
1734 @c Because the order of definition of macros is important (only the last
1735 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1736 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1737 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1738 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1739 @c the latter case, non-macro lines from included files may end up in the
1740 @c @file{configure} script, whereas in the former case, they'd be discarded
1741 @c just like any text that appear before @code{AC_INIT}.
1744 Packages that do manual configuration or use the @code{install} program
1745 might need to tell @command{configure} where to find some other shell
1746 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1747 it looks are correct for most cases.
1749 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1750 @acindex{CONFIG_AUX_DIR}
1751 Use the auxiliary build tools (e.g., @file{install-sh},
1752 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1753 Automake and Libtool scripts etc.) that are in directory @var{dir}.
1754 These are auxiliary files used in configuration. @var{dir} can be
1755 either absolute or relative to @file{@var{srcdir}}. The default is
1756 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1757 @file{@var{srcdir}/../..}, whichever is the first that contains
1758 @file{install-sh}. The other files are not checked for, so that using
1759 @code{AC_PROG_INSTALL} does not automatically require distributing the
1760 other auxiliary files. It checks for @file{install.sh} also, but that
1761 name is obsolete because some @code{make} have a rule that creates
1762 @file{install} from it if there is no @file{Makefile}.
1764 The auxiliary directory should not be named @file{aux} for portability
1765 to MS-DOS, because the filename @file{aux} is reserved under MS-DOS.
1768 Similarly, packages that use @command{aclocal} should declare where
1769 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1771 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1772 @acindex{CONFIG_MACRO_DIR}
1773 Future versions of @command{autopoint}, @command{libtoolize},
1774 @command{aclocal} and @command{autoreconf} will use directory
1775 @var{dir} as the location of additional local Autoconf macros. Be
1776 sure to call this macro directly from @file{configure.ac} so that
1777 tools that install macros for @command{aclocal} can find the
1778 declaration before @option{--trace} can be called safely.
1783 @section Outputting Files
1784 @cindex Outputting files
1786 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1787 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1788 @file{config.status}, which will create the @file{Makefile}s and any
1789 other files resulting from configuration. This is the only required
1790 macro besides @code{AC_INIT} (@pxref{Input}).
1794 @cindex Instantiation
1795 Generate @file{config.status} and launch it. Call this macro once, at
1796 the end of @file{configure.ac}.
1798 @file{config.status} will perform all the configuration actions: all the
1799 output files (see @ref{Configuration Files}, macro
1800 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1801 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1802 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1803 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1804 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1807 The location of your @code{AC_OUTPUT} invocation is the exact point
1808 where configuration actions are taken: any code afterwards will be
1809 executed by @code{configure} once @command{config.status} was run. If
1810 you want to bind actions to @command{config.status} itself
1811 (independently of whether @command{configure} is being run), see
1812 @ref{Configuration Commands, , Running Arbitrary Configuration
1816 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1817 @xref{Obsolete Macros}, for a description of the arguments that
1818 @code{AC_OUTPUT} used to support.
1821 If you run @command{make} in subdirectories, you should run it using the
1822 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1823 @code{MAKE} to the name of the @command{make} program plus any options it
1824 was given. (But many do not include in it the values of any variables
1825 set on the command line, so those are not passed on automatically.)
1826 Some old versions of @command{make} do not set this variable. The
1827 following macro allows you to use it even with those versions.
1829 @defmac AC_PROG_MAKE_SET
1830 @acindex{PROG_MAKE_SET}
1832 If @command{make} predefines the Make variable @code{MAKE}, define
1833 output variable @code{SET_MAKE} to be empty. Otherwise, define
1834 @code{SET_MAKE} to contain @samp{MAKE=make}. Calls @code{AC_SUBST} for
1838 If you use this macro, place a line like this in each @file{Makefile.in}
1839 that runs @code{MAKE} on other directories:
1847 @node Configuration Actions
1848 @section Performing Configuration Actions
1849 @cindex Configuration actions
1851 @file{configure} is designed so that it appears to do everything itself,
1852 but there is actually a hidden slave: @file{config.status}.
1853 @file{configure} is in charge of examining your system, but it is
1854 @file{config.status} that actually takes the proper actions based on the
1855 results of @file{configure}. The most typical task of
1856 @file{config.status} is to @emph{instantiate} files.
1858 This section describes the common behavior of the four standard
1859 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1860 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
1861 have this prototype:
1863 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1866 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
1870 where the arguments are:
1873 @item @var{tag}@dots{}
1874 A whitespace-separated list of tags, which are typically the names of
1875 the files to instantiate.
1877 You are encouraged to use literals as @var{tags}. In particular, you
1881 @dots{} && my_foos="$my_foos fooo"
1882 @dots{} && my_foos="$my_foos foooo"
1883 AC_CONFIG_FOOS($my_foos)
1887 and use this instead:
1890 @dots{} && AC_CONFIG_FOOS(fooo)
1891 @dots{} && AC_CONFIG_FOOS(foooo)
1894 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
1895 special @var{tag}s: they may have the form @samp{@var{output}} or
1896 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
1897 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
1900 @samp{AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)} asks for
1901 the creation of @file{Makefile} that will be the expansion of the
1902 output variables in the concatenation of @file{boiler/top.mk} and
1903 @file{boiler/bot.mk}.
1905 The special value @samp{-} might be used to denote the standard output
1906 when used in @var{output}, or the standard input when used in the
1907 @var{inputs}. You most probably don't need to use this in
1908 @file{configure.ac}, but it is convenient when using the command line
1909 interface of @file{./config.status}, see @ref{config.status Invocation},
1912 The @var{inputs} may be absolute or relative filenames. In the latter
1913 case they are first looked for in the build tree, and then in the source
1917 Shell commands output literally into @file{config.status}, and
1918 associated with a tag that the user can use to tell @file{config.status}
1919 which the commands to run. The commands are run each time a @var{tag}
1920 request is given to @file{config.status}, typically each time the file
1921 @file{@var{tag}} is created.
1923 The variables set during the execution of @command{configure} are
1924 @emph{not} available here: you first need to set them via the
1925 @var{init-cmds}. Nonetheless the following variables are precomputed:
1929 The path from the top build directory to the top source directory. This
1930 is what @command{configure}'s option @option{--srcdir} sets.
1933 The path from the current build directory to the top source directory.
1936 @item ac_top_builddir
1937 The path from the current build directory to the top build directory.
1938 It can be empty, or else ends with a slash, so that you may concatenate
1942 The path from the current build directory to the corresponding source
1947 The @dfn{current} directory refers to the directory (or
1948 pseudo-directory) containing the input part of @var{tags}. For
1952 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
1956 with @option{--srcdir=../package} produces the following values:
1959 # Argument of --srcdir
1961 # Reversing deep/dir
1962 ac_top_builddir='../../'
1963 # Concatenation of $ac_top_builddir and srcdir
1964 ac_top_srcdir='../../../package'
1965 # Concatenation of $ac_top_srcdir and deep/dir
1966 ac_srcdir='../../../package/deep/dir'
1970 independently of @samp{in/in.in}.
1973 Shell commands output @emph{unquoted} near the beginning of
1974 @file{config.status}, and executed each time @file{config.status} runs
1975 (regardless of the tag). Because they are unquoted, for example,
1976 @samp{$var} will be output as the value of @code{var}. @var{init-cmds}
1977 is typically used by @file{configure} to give @file{config.status} some
1978 variables it needs to run the @var{commands}.
1980 You should be extremely cautious in your variable names: all the
1981 @var{init-cmds} share the same name space and may overwrite each other
1982 in unpredictable ways. Sorry@enddots{}
1985 All these macros can be called multiple times, with different
1986 @var{tag}s, of course!
1989 @node Configuration Files
1990 @section Creating Configuration Files
1991 @cindex Creating configuration files
1992 @cindex Configuration file creation
1994 Be sure to read the previous section, @ref{Configuration Actions}.
1996 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
1997 @acindex{CONFIG_FILES}
1998 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
1999 file (by default @file{@var{file}.in}), substituting the output variable
2001 @c Before we used to have this feature, which was later rejected
2002 @c because it complicates the write of Makefiles:
2003 @c If the file would be unchanged, it is left untouched, to preserve
2005 This macro is one of the instantiating macros; see @ref{Configuration
2006 Actions}. @xref{Makefile Substitutions}, for more information on using
2007 output variables. @xref{Setting Output Variables}, for more information
2008 on creating them. This macro creates the directory that the file is in
2009 if it doesn't exist. Usually, @file{Makefile}s are created this way,
2010 but other files, such as @file{.gdbinit}, can be specified as well.
2012 Typical calls to @code{AC_CONFIG_FILES} look like this:
2015 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2016 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2019 You can override an input file name by appending to @var{file} a
2020 colon-separated list of input files. Examples:
2023 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2024 [lib/Makefile:boiler/lib.mk])
2028 Doing this allows you to keep your file names acceptable to MS-DOS, or
2029 to prepend and/or append boilerplate to the file.
2034 @node Makefile Substitutions
2035 @section Substitutions in Makefiles
2036 @cindex Substitutions in makefiles
2037 @cindex Makefile substitutions
2039 Each subdirectory in a distribution that contains something to be
2040 compiled or installed should come with a file @file{Makefile.in}, from
2041 which @command{configure} will create a @file{Makefile} in that directory.
2042 To create a @file{Makefile}, @command{configure} performs a simple variable
2043 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2044 @file{Makefile.in} with the value that @command{configure} has determined
2045 for that variable. Variables that are substituted into output files in
2046 this way are called @dfn{output variables}. They are ordinary shell
2047 variables that are set in @command{configure}. To make @command{configure}
2048 substitute a particular variable into the output files, the macro
2049 @code{AC_SUBST} must be called with that variable name as an argument.
2050 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2051 left unchanged. @xref{Setting Output Variables}, for more information
2052 on creating output variables with @code{AC_SUBST}.
2054 A software package that uses a @command{configure} script should be
2055 distributed with a file @file{Makefile.in}, but no @file{Makefile}; that
2056 way, the user has to properly configure the package for the local system
2057 before compiling it.
2059 @xref{Makefile Conventions,, Makefile Conventions, standards, The
2060 @acronym{GNU} Coding Standards}, for more information on what to put in
2064 * Preset Output Variables:: Output variables that are always set
2065 * Installation Directory Variables:: Other preset output variables
2066 * Build Directories:: Supporting multiple concurrent compiles
2067 * Automatic Remaking:: Makefile rules for configuring
2070 @node Preset Output Variables
2071 @subsection Preset Output Variables
2072 @cindex Output variables
2074 Some output variables are preset by the Autoconf macros. Some of the
2075 Autoconf macros set additional output variables, which are mentioned in
2076 the descriptions for those macros. @xref{Output Variable Index}, for a
2077 complete list of output variables. @xref{Installation Directory
2078 Variables}, for the list of the preset ones related to installation
2079 directories. Below are listed the other preset ones. They all are
2080 precious variables (@pxref{Setting Output Variables},
2083 @c Just say no to ASCII sorting! We're humans, not computers.
2084 @c These variables are listed as they would be in a dictionary:
2091 Debugging and optimization options for the C compiler. If it is not set
2092 in the environment when @command{configure} runs, the default value is set
2093 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2094 uses this variable when compiling programs to test for C features.
2097 @defvar configure_input
2098 @ovindex configure_input
2099 A comment saying that the file was generated automatically by
2100 @command{configure} and giving the name of the input file.
2101 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2102 of every @file{Makefile} it creates. For other files, you should
2103 reference this variable in a comment at the top of each input file. For
2104 example, an input shell script should begin like this:
2108 # @@configure_input@@
2112 The presence of that line also reminds people editing the file that it
2113 needs to be processed by @command{configure} in order to be used.
2118 Header file search directory (@option{-I@var{dir}}) and any other
2119 miscellaneous options for the C and C++ preprocessors and compilers. If
2120 it is not set in the environment when @command{configure} runs, the default
2121 value is empty. @command{configure} uses this variable when compiling or
2122 preprocessing programs to test for C and C++ features.
2127 Debugging and optimization options for the C++ compiler. If it is not
2128 set in the environment when @command{configure} runs, the default value is
2129 set when you call @code{AC_PROG_CXX} (or empty if you don't).
2130 @command{configure} uses this variable when compiling programs to test for
2136 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2137 is called, @command{configure} replaces @samp{@@DEFS@@} with
2138 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2139 variable is not defined while @command{configure} is performing its tests,
2140 only when creating the output files. @xref{Setting Output Variables}, for
2141 how to check the results of previous tests.
2150 How does one suppress the trailing newline from @code{echo} for
2151 question-answer message pairs? These variables provide a way:
2154 echo $ECHO_N "And the winner is... $ECHO_C"
2156 echo "$@{ECHO_T@}dead."
2160 Some old and uncommon @code{echo} implementations offer no means to
2161 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2167 Debugging and optimization options for the Fortran compiler. If it
2168 is not set in the environment when @command{configure} runs, the default
2169 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2170 @command{configure} uses this variable when compiling programs to test for
2176 Debugging and optimization options for the Fortran 77 compiler. If it
2177 is not set in the environment when @command{configure} runs, the default
2178 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2179 @command{configure} uses this variable when compiling programs to test for
2180 Fortran 77 features.
2185 Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
2186 options for the linker. Don't use this variable to pass library names
2187 (@option{-l}) to the linker, use @code{LIBS} instead. If it is not set
2188 in the environment when @command{configure} runs, the default value is empty.
2189 @command{configure} uses this variable when linking programs to test for
2190 C, C++, and Fortran features.
2195 @option{-l} options to pass to the linker. The default value is empty,
2196 but some Autoconf macros may prepend extra libraries to this variable if
2197 those libraries are found and provide necessary functions, see
2198 @ref{Libraries}. @command{configure} uses this variable when linking
2199 programs to test for C, C++, and Fortran features.
2204 Rigorously equal to @samp{.}. Added for symmetry only.
2207 @defvar abs_builddir
2208 @ovindex abs_builddir
2209 Absolute path of @code{builddir}.
2212 @defvar top_builddir
2213 @ovindex top_builddir
2214 The relative path to the top-level of the current build tree. In the
2215 top-level directory, this is the same as @code{builddir}.
2218 @defvar abs_top_builddir
2219 @ovindex abs_top_builddir
2220 Absolute path of @code{top_builddir}.
2225 The relative path to the directory that contains the source code for
2226 that @file{Makefile}.
2231 Absolute path of @code{srcdir}.
2236 The relative path to the top-level source code directory for the
2237 package. In the top-level directory, this is the same as @code{srcdir}.
2240 @defvar abs_top_srcdir
2241 @ovindex abs_top_srcdir
2242 Absolute path of @code{top_srcdir}.
2245 @node Installation Directory Variables
2246 @subsection Installation Directory Variables
2247 @cindex Installation directories
2248 @cindex Directories, installation
2250 The following variables specify the directories where the package will
2251 be installed, see @ref{Directory Variables,, Variables for
2252 Installation Directories, standards, The @acronym{GNU} Coding
2253 Standards}, for more information. See the end of this section for
2254 details on when and how to use these variables.
2258 The directory for installing executables that users run.
2263 The directory for installing read-only architecture-independent data.
2267 @ovindex exec_prefix
2268 The installation prefix for architecture-dependent files. By default
2269 it's the same as @var{prefix}. You should avoid installing anything
2270 directly to @var{exec_prefix}. However, the default value for
2271 directories containing architecture-dependent files should be relative
2272 to @var{exec_prefix}.
2277 The directory for installing C header files.
2282 The directory for installing documentation in Info format.
2287 The directory for installing object code libraries.
2292 The directory for installing executables that other programs run.
2295 @defvar localstatedir
2296 @ovindex localstatedir
2297 The directory for installing modifiable single-machine data.
2302 The top-level directory for installing documentation in man format.
2305 @defvar oldincludedir
2306 @ovindex oldincludedir
2307 The directory for installing C header files for non-GCC compilers.
2312 The common installation prefix for all files. If @var{exec_prefix}
2313 is defined to a different value, @var{prefix} is used only for
2314 architecture-independent files.
2319 The directory for installing executables that system
2323 @defvar sharedstatedir
2324 @ovindex sharedstatedir
2325 The directory for installing modifiable architecture-independent data.
2330 The directory for installing read-only single-machine data.
2334 Most of these variables have values that rely on @code{prefix} or
2335 @code{exec_prefix}. It is deliberate that the directory output
2336 variables keep them unexpanded: typically @samp{@@datadir@@} will be
2337 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}.
2339 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2344 she can still specify a different prefix from the one specified to
2345 @command{configure}, in which case, if needed, the package shall hard
2346 code dependencies corresponding to the make-specified prefix.
2349 she can specify a different installation location, in which case the
2350 package @emph{must} still depend on the location which was compiled in
2351 (i.e., never recompile when @samp{make install} is run). This is an
2352 extremely important feature, as many people may decide to install all
2353 the files of a package grouped together, and then install links from
2354 the final locations to there.
2357 In order to support these features, it is essential that @code{datadir}
2358 remains being defined as @samp{$@{prefix@}/share} to depend upon the
2359 current value of @code{prefix}.
2361 A corollary is that you should not use these variables except in
2362 Makefiles. For instance, instead of trying to evaluate @code{datadir}
2363 in @file{configure} and hard-coding it in Makefiles using
2364 e.g., @samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir")}, you should add
2365 @samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}.
2367 Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace
2368 @code{datadir} and friends in your shell scripts and other files, rather
2369 let @command{make} manage their replacement. For instance Autoconf
2370 ships templates of its shell scripts ending with @samp{.in}, and uses a
2371 Makefile snippet similar to:
2376 -e 's,@@datadir\@@,$(pkgdatadir),g' \
2377 -e 's,@@prefix\@@,$(prefix),g'
2381 autoconf: Makefile $(srcdir)/autoconf.in
2382 rm -f autoconf autoconf.tmp
2383 $(edit) $(srcdir)/autoconf.in >autoconf.tmp
2384 chmod +x autoconf.tmp
2385 mv autoconf.tmp autoconf
2389 autoheader: Makefile $(srcdir)/autoheader.in
2390 rm -f autoheader autoheader.tmp
2391 $(edit) $(srcdir)/autoconf.in >autoheader.tmp
2392 chmod +x autoheader.tmp
2393 mv autoheader.tmp autoheader
2397 Some details are noteworthy:
2401 The backslash prevents @command{configure} from replacing
2402 @samp{@@datadir@@} in the sed expression itself.
2405 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2409 Don't use @samp{/} in the sed expression(s) since most likely the
2410 variables you use, such as @samp{$(pkgdatadir)}, will contain
2413 @item Dependency on @file{Makefile}
2414 Since @code{edit} uses values that depend on the configuration specific
2415 values (@code{prefix} etc.) and not only on @code{VERSION} and so forth,
2416 the output depends on @file{Makefile}, not @file{configure.ac}.
2418 @item Separated dependencies and Single Suffix Rules
2419 You can't use them! The above snippet cannot be (portably) rewritten
2423 autoconf autoheader: Makefile
2433 @xref{Limitations of Make}, for details.
2435 @item @samp{$(srcdir)}
2436 Be sure to specify the path to the sources, otherwise the package won't
2437 support separated builds.
2441 @node Build Directories
2442 @subsection Build Directories
2443 @cindex Build directories
2444 @cindex Directories, build
2446 You can support compiling a software package for several architectures
2447 simultaneously from the same copy of the source code. The object files
2448 for each architecture are kept in their own directory.
2450 To support doing this, @command{make} uses the @code{VPATH} variable to
2451 find the files that are in the source directory. @acronym{GNU} Make
2452 and most other recent @command{make} programs can do this. Older
2453 @command{make} programs do not support @code{VPATH}; when using them, the
2454 source code must be in the same directory as the object files.
2456 To support @code{VPATH}, each @file{Makefile.in} should contain two
2457 lines that look like:
2464 Do not set @code{VPATH} to the value of another variable, for example
2465 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2466 variable substitutions on the value of @code{VPATH}.
2468 @command{configure} substitutes the correct value for @code{srcdir} when
2469 it produces @file{Makefile}.
2471 Do not use the @code{make} variable @code{$<}, which expands to the
2472 file name of the file in the source directory (found with @code{VPATH}),
2473 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2474 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2475 versions of @command{make} do not set @code{$<} in explicit rules; they
2476 expand it to an empty value.
2478 Instead, @file{Makefile} command lines should always refer to source
2479 files by prefixing them with @samp{$(srcdir)/}. For example:
2482 time.info: time.texinfo
2483 $(MAKEINFO) $(srcdir)/time.texinfo
2486 @node Automatic Remaking
2487 @subsection Automatic Remaking
2488 @cindex Automatic remaking
2489 @cindex Remaking automatically
2491 You can put rules like the following in the top-level @file{Makefile.in}
2492 for a package to automatically update the configuration information when
2493 you change the configuration files. This example includes all of the
2494 optional files, such as @file{aclocal.m4} and those related to
2495 configuration header files. Omit from the @file{Makefile.in} rules for
2496 any of these files that your package does not use.
2498 The @samp{$(srcdir)/} prefix is included because of limitations in the
2499 @code{VPATH} mechanism.
2501 The @file{stamp-} files are necessary because the timestamps of
2502 @file{config.h.in} and @file{config.h} will not be changed if remaking
2503 them does not change their contents. This feature avoids unnecessary
2504 recompilation. You should include the file @file{stamp-h.in} your
2505 package's distribution, so @command{make} will consider
2506 @file{config.h.in} up to date. Don't use @command{touch}
2507 (@pxref{Limitations of Usual Tools}), rather use @command{echo} (using
2508 @command{date} would cause needless differences, hence @acronym{CVS}
2513 $(srcdir)/configure: configure.ac aclocal.m4
2514 cd $(srcdir) && autoconf
2516 # autoheader might not change config.h.in, so touch a stamp file.
2517 $(srcdir)/config.h.in: stamp-h.in
2518 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2519 cd $(srcdir) && autoheader
2520 echo timestamp > $(srcdir)/stamp-h.in
2523 stamp-h: config.h.in config.status
2526 Makefile: Makefile.in config.status
2529 config.status: configure
2530 ./config.status --recheck
2535 (Be careful if you copy these lines directly into your Makefile, as you
2536 will need to convert the indented lines to start with the tab character.)
2538 In addition, you should use @samp{AC_CONFIG_FILES([stamp-h], [echo
2539 timestamp > stamp-h])} so @file{config.status} will ensure that
2540 @file{config.h} is considered up to date. @xref{Output}, for more
2541 information about @code{AC_OUTPUT}.
2543 @xref{config.status Invocation}, for more examples of handling
2544 configuration-related dependencies.
2546 @node Configuration Headers
2547 @section Configuration Header Files
2548 @cindex Configuration Header
2549 @cindex @file{config.h}
2551 When a package contains more than a few tests that define C preprocessor
2552 symbols, the command lines to pass @option{-D} options to the compiler
2553 can get quite long. This causes two problems. One is that the
2554 @command{make} output is hard to visually scan for errors. More
2555 seriously, the command lines can exceed the length limits of some
2556 operating systems. As an alternative to passing @option{-D} options to
2557 the compiler, @command{configure} scripts can create a C header file
2558 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2559 macro selects this kind of output. It should be called right after
2562 The package should @samp{#include} the configuration header file before
2563 any other header files, to prevent inconsistencies in declarations (for
2564 example, if it redefines @code{const}). Use @samp{#include <config.h>}
2565 instead of @samp{#include "config.h"}, and pass the C compiler a
2566 @option{-I.} option (or @option{-I..}; whichever directory contains
2567 @file{config.h}). That way, even if the source directory is configured
2568 itself (perhaps to make a distribution), other build directories can
2569 also be configured without finding the @file{config.h} from the source
2572 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2573 @acindex{CONFIG_HEADERS}
2574 @cvindex HAVE_CONFIG_H
2575 This macro is one of the instantiating macros; see @ref{Configuration
2576 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2577 whitespace-separated list @var{header} containing C preprocessor
2578 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2579 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2580 The usual name for @var{header} is @file{config.h}.
2582 If @var{header} already exists and its contents are identical to what
2583 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2584 making some changes in the configuration without needlessly causing
2585 object files that depend on the header file to be recompiled.
2587 Usually the input file is named @file{@var{header}.in}; however, you can
2588 override the input file name by appending to @var{header} a
2589 colon-separated list of input files. Examples:
2592 AC_CONFIG_HEADERS([config.h:config.hin])
2593 AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
2597 Doing this allows you to keep your file names acceptable to MS-DOS, or
2598 to prepend and/or append boilerplate to the file.
2601 @xref{Configuration Actions}, for more details on @var{header}.
2604 * Header Templates:: Input for the configuration headers
2605 * autoheader Invocation:: How to create configuration templates
2606 * Autoheader Macros:: How to specify CPP templates
2609 @node Header Templates
2610 @subsection Configuration Header Templates
2611 @cindex Configuration Header Template
2612 @cindex Header templates
2613 @cindex @file{config.h.in}
2615 Your distribution should contain a template file that looks as you want
2616 the final header file to look, including comments, with @code{#undef}
2617 statements which are used as hooks. For example, suppose your
2618 @file{configure.ac} makes these calls:
2621 AC_CONFIG_HEADERS([conf.h])
2622 AC_CHECK_HEADERS([unistd.h])
2626 Then you could have code like the following in @file{conf.h.in}. On
2627 systems that have @file{unistd.h}, @command{configure} will @samp{#define}
2628 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line will be
2629 commented out (in case the system predefines that symbol).
2633 /* Define as 1 if you have unistd.h. */
2634 #undef HAVE_UNISTD_H
2638 Pay attention that @samp{#undef} is in the first column, and there is
2639 nothing behind @samp{HAVE_UNISTD_H}, not even white spaces. You can
2640 then decode the configuration header using the preprocessor directives:
2647 # include <unistd.h>
2649 /* We are in trouble. */
2654 The use of old form templates, with @samp{#define} instead of
2655 @samp{#undef} is strongly discouraged. Similarly with old templates
2656 with comments on the same line as the @samp{#undef}. Anyway, putting
2657 comments in preprocessor macros has never been a good idea.
2659 Since it is a tedious task to keep a template header up to date, you may
2660 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
2663 @node autoheader Invocation
2664 @subsection Using @command{autoheader} to Create @file{config.h.in}
2665 @cindex @command{autoheader}
2667 The @command{autoheader} program can create a template file of C
2668 @samp{#define} statements for @command{configure} to use. If
2669 @file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
2670 @command{autoheader} creates @file{@var{file}.in}; if multiple file
2671 arguments are given, the first one is used. Otherwise,
2672 @command{autoheader} creates @file{config.h.in}.
2674 In order to do its job, @command{autoheader} needs you to document all
2675 of the symbols that you might use; i.e., there must be at least one
2676 @code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} call with a third
2677 argument for each symbol (@pxref{Defining Symbols}). An additional
2678 constraint is that the first argument of @code{AC_DEFINE} must be a
2679 literal. Note that all symbols defined by Autoconf's builtin tests are
2680 already documented properly; you only need to document those that you
2683 You might wonder why @command{autoheader} is needed: after all, why
2684 would @command{configure} need to ``patch'' a @file{config.h.in} to
2685 produce a @file{config.h} instead of just creating @file{config.h} from
2686 scratch? Well, when everything rocks, the answer is just that we are
2687 wasting our time maintaining @command{autoheader}: generating
2688 @file{config.h} directly is all that is needed. When things go wrong,
2689 however, you'll be thankful for the existence of @command{autoheader}.
2691 The fact that the symbols are documented is important in order to
2692 @emph{check} that @file{config.h} makes sense. The fact that there is a
2693 well-defined list of symbols that should be @code{#define}'d (or not) is
2694 also important for people who are porting packages to environments where
2695 @command{configure} cannot be run: they just have to @emph{fill in the
2698 But let's come back to the point: @command{autoheader}'s invocation@dots{}
2700 If you give @command{autoheader} an argument, it uses that file instead
2701 of @file{configure.ac} and writes the header file to the standard output
2702 instead of to @file{config.h.in}. If you give @command{autoheader} an
2703 argument of @option{-}, it reads the standard input instead of
2704 @file{configure.ac} and writes the header file to the standard output.
2706 @command{autoheader} accepts the following options:
2711 Print a summary of the command line options and exit.
2715 Print the version number of Autoconf and exit.
2719 Report processing steps.
2723 Don't remove the temporary files.
2727 Remake the template file even if newer than its input files.
2729 @item --include=@var{dir}
2731 Append @var{dir} to include path. Multiple invocations accumulate.
2733 @item --prepend-include=@var{dir}
2735 Prepend @var{dir} to include path. Multiple invocations accumulate.
2737 @item --warnings=@var{category}
2738 @itemx -W @var{category}
2740 Report the warnings related to @var{category} (which can actually be a
2741 comma separated list). Current categories include:
2745 report the uses of obsolete constructs
2748 report all the warnings
2754 treats warnings as errors
2756 @item no-@var{category}
2757 disable warnings falling into @var{category}
2764 @node Autoheader Macros
2765 @subsection Autoheader Macros
2766 @cindex Autoheader macros
2768 @command{autoheader} scans @file{configure.ac} and figures out which C
2769 preprocessor symbols it might define. It knows how to generate
2770 templates for symbols defined by @code{AC_CHECK_HEADERS},
2771 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
2772 symbol, you must define a template for it. If there are missing
2773 templates, @command{autoheader} fails with an error message.
2775 The simplest way to create a template for a @var{symbol} is to supply
2776 the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
2777 @ref{Defining Symbols}. You may also use one of the following macros.
2779 @defmac AH_VERBATIM (@var{key}, @var{template})
2781 Tell @command{autoheader} to include the @var{template} as-is in the header
2782 template file. This @var{template} is associated with the @var{key},
2783 which is used to sort all the different templates and guarantee their
2784 uniqueness. It should be a symbol that can be @code{AC_DEFINE}'d.
2789 AH_VERBATIM([_GNU_SOURCE],
2790 [/* Enable GNU extensions on systems that have them. */
2792 # define _GNU_SOURCE
2798 @defmac AH_TEMPLATE (@var{key}, @var{description})
2800 Tell @command{autoheader} to generate a template for @var{key}. This macro
2801 generates standard templates just like @code{AC_DEFINE} when a
2802 @var{description} is given.
2807 AH_TEMPLATE([CRAY_STACKSEG_END],
2808 [Define to one of _getb67, GETB67, getb67
2809 for Cray-2 and Cray-YMP systems. This
2810 function is required for alloca.c support
2815 will generate the following template, with the description properly
2819 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
2820 Cray-YMP systems. This function is required for alloca.c
2821 support on those systems. */
2822 #undef CRAY_STACKSEG_END
2827 @defmac AH_TOP (@var{text})
2829 Include @var{text} at the top of the header template file.
2833 @defmac AH_BOTTOM (@var{text})
2835 Include @var{text} at the bottom of the header template file.
2839 @node Configuration Commands
2840 @section Running Arbitrary Configuration Commands
2841 @cindex Configuration commands
2842 @cindex Commands for configuration
2844 You can execute arbitrary commands before, during, and after
2845 @file{config.status} is run. The three following macros accumulate the
2846 commands to run when they are called multiple times.
2847 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
2848 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
2850 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2851 @acindex{CONFIG_COMMANDS}
2852 Specify additional shell commands to run at the end of
2853 @file{config.status}, and shell commands to initialize any variables
2854 from @command{configure}. Associate the commands with @var{tag}.
2855 Since typically the @var{cmds} create a file, @var{tag} should
2856 naturally be the name of that file. If needed, the directory hosting
2857 @var{tag} is created. This macro is one of the instantiating macros;
2858 see @ref{Configuration Actions}.
2860 Here is an unrealistic example:
2863 AC_CONFIG_COMMANDS([fubar],
2864 [echo this is extra $fubar, and so on.],
2868 Here is a better one:
2870 AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp])
2874 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
2875 @acindex{OUTPUT_COMMANDS_PRE}
2876 Execute the @var{cmds} right before creating @file{config.status}.
2879 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
2880 @acindex{OUTPUT_COMMANDS_POST}
2881 Execute the @var{cmds} right after creating @file{config.status}.
2887 @node Configuration Links
2888 @section Creating Configuration Links
2889 @cindex Configuration links
2890 @cindex Links for configuration
2892 You may find it convenient to create links whose destinations depend upon
2893 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
2894 creation of relative symbolic links can be delicate when the package is
2895 built in a directory different from the source directory.
2897 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2898 @acindex{CONFIG_LINKS}
2900 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
2901 the corresponding link name @var{dest}. Makes a symbolic link if
2902 possible, otherwise a hard link if possible, otherwise a copy. The
2903 @var{dest} and @var{source} names should be relative to the top level
2904 source or build directory. This macro is one of the instantiating
2905 macros; see @ref{Configuration Actions}.
2907 For example, this call:
2910 AC_CONFIG_LINKS(host.h:config/$machine.h
2911 object.h:config/$obj_format.h)
2915 creates in the current directory @file{host.h} as a link to
2916 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
2917 link to @file{@var{srcdir}/config/$obj_format.h}.
2919 The tempting value @samp{.} for @var{dest} is invalid: it makes it
2920 impossible for @samp{config.status} to guess the links to establish.
2924 ./config.status host.h object.h
2927 to create the links.
2932 @node Subdirectories
2933 @section Configuring Other Packages in Subdirectories
2934 @section Configure subdirectories
2935 @section Subdirectory configure
2937 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
2938 @file{Makefile}s in subdirectories. However, @command{configure} scripts
2939 that control more than one independent package can use
2940 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
2941 packages in subdirectories.
2943 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
2944 @acindex{CONFIG_SUBDIRS}
2946 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
2947 @var{dir} in the given whitespace-separated list. Each @var{dir} should
2948 be a literal, i.e., please do not use:
2951 if test "$package_foo_enabled" = yes; then
2952 $my_subdirs="$my_subdirs foo"
2954 AC_CONFIG_SUBDIRS($my_subdirs)
2958 because this prevents @samp{./configure --help=recursive} from
2959 displaying the options of the package @code{foo}. Rather, you should
2963 if test "$package_foo_enabled" = yes; then
2964 AC_CONFIG_SUBDIRS(foo)
2968 If a given @var{dir} is not found, an error is reported: if the
2969 subdirectory is optional, write:
2972 if test -d $srcdir/foo; then
2973 AC_CONFIG_SUBDIRS(foo)
2977 @c NB: Yes, below we mean configure.in, not configure.ac.
2978 If a given @var{dir} contains @command{configure.gnu}, it is run instead
2979 of @command{configure}. This is for packages that might use a
2980 non-Autoconf script @command{Configure}, which can't be called through a
2981 wrapper @command{configure} since it would be the same file on
2982 case-insensitive filesystems. Likewise, if a @var{dir} contains
2983 @file{configure.in} but no @command{configure}, the Cygnus
2984 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
2986 The subdirectory @command{configure} scripts are given the same command
2987 line options that were given to this @command{configure} script, with minor
2988 changes if needed, which include:
2992 adjusting a relative path for the cache file;
2995 adjusting a relative path for the source directory;
2998 propagating the current value of @code{$prefix}, including if it was
2999 defaulted, and if the default values of the top level and of the subdirectory
3000 @file{configure} differ.
3003 This macro also sets the output variable @code{subdirs} to the list of
3004 directories @samp{@var{dir} @dots{}}. @file{Makefile} rules can use
3005 this variable to determine which subdirectories to recurse into.
3007 This macro may be called multiple times.
3010 @node Default Prefix
3011 @section Default Prefix
3012 @cindex Install prefix
3013 @cindex Prefix for install
3015 By default, @command{configure} sets the prefix for files it installs to
3016 @file{/usr/local}. The user of @command{configure} can select a different
3017 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3018 There are two ways to change the default: when creating
3019 @command{configure}, and when running it.
3021 Some software packages might want to install in a directory other than
3022 @file{/usr/local} by default. To accomplish that, use the
3023 @code{AC_PREFIX_DEFAULT} macro.
3025 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3026 @acindex{PREFIX_DEFAULT}
3027 Set the default installation prefix to @var{prefix} instead of
3031 It may be convenient for users to have @command{configure} guess the
3032 installation prefix from the location of a related program that they
3033 have already installed. If you wish to do that, you can call
3034 @code{AC_PREFIX_PROGRAM}.
3036 @defmac AC_PREFIX_PROGRAM (@var{program})
3037 @acindex{PREFIX_PROGRAM}
3038 If the user did not specify an installation prefix (using the
3039 @option{--prefix} option), guess a value for it by looking for
3040 @var{program} in @code{PATH}, the way the shell does. If @var{program}
3041 is found, set the prefix to the parent of the directory containing
3042 @var{program}, else default the prefix as described above
3043 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3044 @var{program} is @code{gcc} and the @code{PATH} contains
3045 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3050 @c ======================================================== Existing tests
3052 @node Existing Tests
3053 @chapter Existing Tests
3055 These macros test for particular system features that packages might
3056 need or want to use. If you need to test for a kind of feature that
3057 none of these macros check for, you can probably do it by calling
3058 primitive test macros with appropriate arguments (@pxref{Writing
3061 These tests print messages telling the user which feature they're
3062 checking for, and what they find. They cache their results for future
3063 @command{configure} runs (@pxref{Caching Results}).
3065 Some of these macros set output variables. @xref{Makefile
3066 Substitutions}, for how to get their values. The phrase ``define
3067 @var{name}'' is used below as a shorthand to mean ``define C
3068 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3069 Symbols}, for how to get those symbol definitions into your program.
3072 * Common Behavior:: Macros' standard schemes
3073 * Alternative Programs:: Selecting between alternative programs
3074 * Files:: Checking for the existence of files
3075 * Libraries:: Library archives that might be missing
3076 * Library Functions:: C library functions that might be missing
3077 * Header Files:: Header files that might be missing
3078 * Declarations:: Declarations that may be missing
3079 * Structures:: Structures or members that might be missing
3080 * Types:: Types that might be missing
3081 * Compilers and Preprocessors:: Checking for compiling programs
3082 * System Services:: Operating system services
3083 * UNIX Variants:: Special kludges for specific UNIX variants
3086 @node Common Behavior
3087 @section Common Behavior
3088 @cindex Common autoconf behavior
3090 Much effort has been expended to make Autoconf easy to learn. The most
3091 obvious way to reach this goal is simply to enforce standard interfaces
3092 and behaviors, avoiding exceptions as much as possible. Because of
3093 history and inertia, unfortunately, there are still too many exceptions
3094 in Autoconf; nevertheless, this section describes some of the common
3098 * Standard Symbols:: Symbols defined by the macros
3099 * Default Includes:: Includes used by the generic macros
3102 @node Standard Symbols
3103 @subsection Standard Symbols
3104 @cindex Standard symbols
3106 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3107 their test transform their @var{argument}s to a standard alphabet.
3108 First, @var{argument} is converted to upper case and any asterisks
3109 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3110 that are not alphanumeric are converted to underscores.
3115 AC_CHECK_TYPES(struct $Expensive*)
3119 will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3123 @node Default Includes
3124 @subsection Default Includes
3125 @cindex Default includes
3126 @cindex Includes, default
3128 Several tests depend upon a set of header files. Since these headers
3129 are not universally available, tests actually have to provide a set of
3130 protected includes, such as:
3134 #if TIME_WITH_SYS_TIME
3135 # include <sys/time.h>
3138 # if HAVE_SYS_TIME_H
3139 # include <sys/time.h>
3148 Unless you know exactly what you are doing, you should avoid using
3149 unconditional includes, and check the existence of the headers you
3150 include beforehand (@pxref{Header Files}).
3152 Most generic macros use the following macro to provide the default set
3155 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3156 @acindex{INCLUDES_DEFAULT}
3157 Expand to @var{include-directives} if defined, otherwise to:
3162 #if HAVE_SYS_TYPES_H
3163 # include <sys/types.h>
3166 # include <sys/stat.h>
3169 # include <stdlib.h>
3170 # include <stddef.h>
3173 # include <stdlib.h>
3177 # if !STDC_HEADERS && HAVE_MEMORY_H
3178 # include <memory.h>
3180 # include <string.h>
3183 # include <strings.h>
3186 # include <inttypes.h>
3189 # include <stdint.h>
3192 # include <unistd.h>
3197 If the default includes are used, then check for the presence of these
3198 headers and their compatibility, i.e., you don't need to run
3199 @code{AC_HEADERS_STDC}, nor check for @file{stdlib.h} etc.
3201 These headers are checked for in the same order as they are included.
3202 For instance, on some systems @file{string.h} and @file{strings.h} both
3203 exist, but conflict. Then @code{HAVE_STRING_H} will be defined, but
3204 @code{HAVE_STRINGS_H} won't.
3207 @node Alternative Programs
3208 @section Alternative Programs
3209 @cindex Programs, checking
3211 These macros check for the presence or behavior of particular programs.
3212 They are used to choose between several alternative programs and to
3213 decide what to do once one has been chosen. If there is no macro
3214 specifically defined to check for a program you need, and you don't need
3215 to check for any special properties of it, then you can use one of the
3216 general program-check macros.
3219 * Particular Programs:: Special handling to find certain programs
3220 * Generic Programs:: How to find other programs
3223 @node Particular Programs
3224 @subsection Particular Program Checks
3226 These macros check for particular programs---whether they exist, and
3227 in some cases whether they support certain features.
3232 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3233 order, and set output variable @code{AWK} to the first one that is found.
3234 It tries @code{gawk} first because that is reported to be the
3235 best implementation.
3238 @defmac AC_PROG_GREP
3241 On AIX the default @code{grep} silently truncates long lines on the
3242 input before matching. This macro looks for @sc{gnu} Grep or
3243 else the best available @code{grep} or @code{ggrep} in the user's
3244 @code{$PATH}, which accepts the longest input lines possible. Set the
3245 output variable @code{GREP} to whatever is chosen.
3248 @defmac AC_PROG_EGREP
3249 @acindex{PROG_EGREP}
3251 Check whether @code{$GREP -E} works, or else search the user's
3252 @code{$PATH} for @code{egrep}, and @code{gegrep}, in that order, and set
3253 output variable @code{EGREP} to the one which accepts the longest input
3257 @defmac AC_PROG_FGREP
3258 @acindex{PROG_FGREP}
3260 Check whether @code{$GREP -F} works, or else search the user's
3261 @code{$PATH} for @code{fgrep}, and @code{gfgrep}, in that order, and set
3262 output variable @code{FGREP} to the one which accepts the longest input
3266 @defmac AC_PROG_INSTALL
3267 @acindex{PROG_INSTALL}
3269 @ovindex INSTALL_PROGRAM
3270 @ovindex INSTALL_DATA
3271 @ovindex INSTALL_SCRIPT
3272 Set output variable @code{INSTALL} to the path of a @acronym{BSD}-compatible
3273 @code{install} program, if one is found in the current @code{PATH}.
3274 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3275 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3276 default directories) to determine @var{dir} (@pxref{Output}). Also set
3277 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3278 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3280 This macro screens out various instances of @code{install} known not to
3281 work. It prefers to find a C program rather than a shell script, for
3282 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3283 but that name is obsolete because some @command{make} programs have a rule
3284 that creates @file{install} from it if there is no @file{Makefile}.
3286 Autoconf comes with a copy of @file{install-sh} that you can use. If
3287 you use @code{AC_PROG_INSTALL}, you must include either
3288 @file{install-sh} or @file{install.sh} in your distribution, or
3289 @command{configure} will produce an error message saying it can't find
3290 them---even if the system you're on has a good @code{install} program.
3291 This check is a safety measure to prevent you from accidentally leaving
3292 that file out, which would prevent your package from installing on
3293 systems that don't have a @acronym{BSD}-compatible @code{install} program.
3295 If you need to use your own installation program because it has features
3296 not found in standard @code{install} programs, there is no reason to use
3297 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3298 @file{Makefile.in} files.
3305 @cvindex YYTEXT_POINTER
3306 @ovindex LEX_OUTPUT_ROOT
3307 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3308 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3309 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3312 Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
3313 of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3314 the base of the file name that the lexer generates; usually
3315 @file{lex.yy}, but sometimes something else. These results vary
3316 according to whether @code{lex} or @code{flex} is being used.
3318 You are encouraged to use Flex in your sources, since it is both more
3319 pleasant to use than plain Lex and the C source it produces is portable.
3320 In order to ensure portability, however, you must either provide a
3321 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3322 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3323 statement in the scanner's source. Once this done, the scanner is
3324 portable (unless @emph{you} felt free to use nonportable constructs) and
3325 does not depend on any library. In this case, and in this case only, it
3326 is suggested that you use this Autoconf snippet:
3330 if test "$LEX" != flex; then
3331 LEX="$SHELL $missing_dir/missing flex"
3332 AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
3333 AC_SUBST(LEXLIB, '')
3337 The shell script @command{missing} can be found in the Automake
3340 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3341 (indirectly) this macro twice, which will cause an annoying but benign
3342 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3343 of Automake will fix this issue; meanwhile, just ignore this message.
3345 As part of running the test, this macro may delete any file in the
3346 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3349 @defmac AC_PROG_LN_S
3352 If @samp{ln -s} works on the current file system (the operating system
3353 and file system support symbolic links), set the output variable
3354 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3355 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3357 If you make a link in a directory other than the current directory, its
3358 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3359 create links using @samp{$(LN_S)}, either find out which form is used
3360 and adjust the arguments, or always invoke @code{ln} in the directory
3361 where the link is to be created.
3363 In other words, it does not work to do:
3371 (cd /x && $(LN_S) foo bar)
3375 @defmac AC_PROG_RANLIB
3376 @acindex{PROG_RANLIB}
3378 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3379 is found, and otherwise to @samp{:} (do nothing).
3385 Set output variable @code{SED} to a @code{sed} on @samp{PATH} that
3386 truncates as few characters as possible. If @sc{gnu} Sed is found,
3390 @defmac AC_PROG_YACC
3393 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3394 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3395 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3398 @node Generic Programs
3399 @subsection Generic Program and File Checks
3401 These macros are used to find programs not covered by the ``particular''
3402 test macros. If you need to check the behavior of a program as well as
3403 find out whether it is present, you have to write your own test for it
3404 (@pxref{Writing Tests}). By default, these macros use the environment
3405 variable @code{PATH}. If you need to check for a program that might not
3406 be in the user's @code{PATH}, you can pass a modified path to use
3410 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3411 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:etc])
3414 You are strongly encouraged to declare the @var{variable} passed to
3415 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3416 @code{AC_ARG_VAR}, for more details.
3418 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
3419 @acindex{CHECK_PROG}
3420 Check whether program @var{prog-to-check-for} exists in @code{PATH}. If
3421 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3422 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3423 absolute file name) even if it is the first found in the search path; in
3424 that case, set @var{variable} using the absolute file name of the
3425 @var{prog-to-check-for} found that is not @var{reject}. If
3426 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3430 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3431 @acindex{CHECK_PROGS}
3432 Check for each program in the whitespace-separated list
3433 @var{progs-to-check-for} existing in the @code{PATH}. If one is found, set
3434 @var{variable} to the name of that program. Otherwise, continue
3435 checking the next program in the list. If none of the programs in the
3436 list are found, set @var{variable} to @var{value-if-not-found}; if
3437 @var{value-if-not-found} is not specified, the value of @var{variable}
3438 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3441 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3442 @acindex{CHECK_TOOL}
3443 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3444 with a prefix of the host type as determined by
3445 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3446 For example, if the user runs @samp{configure --host=i386-gnu}, then
3449 AC_CHECK_TOOL(RANLIB, ranlib, :)
3452 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3453 @code{PATH}, or otherwise to @samp{ranlib} if that program exists in
3454 @code{PATH}, or to @samp{:} if neither program exists.
3457 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3458 @acindex{CHECK_TOOLS}
3459 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3460 @var{progs-to-check-for} are checked with a prefix of the host type as
3461 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3462 (@pxref{Canonicalizing}). If none of the tools can be found with a
3463 prefix, then the first one without a prefix is used. If a tool is found,
3464 set @var{variable} to the name of that program. If none of the tools in
3465 the list are found, set @var{variable} to @var{value-if-not-found}; if
3466 @var{value-if-not-found} is not specified, the value of @var{variable}
3467 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3470 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3472 Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire
3473 path of @var{prog-to-check-for} if found.
3476 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3477 @acindex{PATH_PROGS}
3478 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3479 are found, set @var{variable} to the entire path of the program
3483 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3485 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the entire
3486 path of the program if it is found.
3492 @cindex File, checking
3494 You might also need to check for the existence of files. Before using
3495 these macros, ask yourself whether a run-time test might not be a better
3496 solution. Be aware that, like most Autoconf macros, they test a feature
3497 of the host machine, and therefore, they die when cross-compiling.
3499 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3500 @acindex{CHECK_FILE}
3501 Check whether file @var{file} exists on the native system. If it is
3502 found, execute @var{action-if-found}, otherwise do
3503 @var{action-if-not-found}, if given.
3506 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3507 @acindex{CHECK_FILES}
3508 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3509 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3510 for each file found.
3515 @section Library Files
3516 @cindex Library, checking
3518 The following macros check for the presence of certain C, C++, or Fortran
3519 library archive files.
3521 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3523 Depending on the current language(@pxref{Language Choice}), try to
3524 ensure that the C, C++, or Fortran function @var{function} is
3525 available by checking whether a test program can be linked with the
3526 library @var{library} to get the function. @var{library} is the base
3527 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
3528 the @var{library} argument.
3530 @var{action-if-found} is a list of shell commands to run if the link
3531 with the library succeeds; @var{action-if-not-found} is a list of shell
3532 commands to run if the link fails. If @var{action-if-found} is not
3533 specified, the default action will prepend @option{-l@var{library}} to
3534 @code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all
3535 capitals). This macro is intended to support building @code{LIBS} in
3536 a right-to-left (least-dependent to most-dependent) fashion such that
3537 library dependencies are satisfied as a natural side-effect of
3538 consecutive tests. Some linkers are very sensitive to library ordering
3539 so the order in which @code{LIBS} is generated is important to reliable
3540 detection of libraries.
3542 If linking with @var{library} results in unresolved symbols that would
3543 be resolved by linking with additional libraries, give those libraries
3544 as the @var{other-libraries} argument, separated by spaces:
3545 e.g., @option{-lXt -lX11}. Otherwise, this macro will fail to detect
3546 that @var{library} is present, because linking the test program will
3547 always fail with unresolved symbols. The @var{other-libraries} argument
3548 should be limited to cases where it is desirable to test for one library
3549 in the presence of another that is not already in @code{LIBS}.
3553 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3554 @acindex{SEARCH_LIBS}
3555 Search for a library defining @var{function} if it's not already
3556 available. This equates to calling
3557 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
3558 no libraries, then for each library listed in @var{search-libs}.
3560 Add @option{-l@var{library}} to @code{LIBS} for the first library found
3561 to contain @var{function}, and run @var{action-if-found}. If the
3562 function is not found, run @var{action-if-not-found}.
3564 If linking with @var{library} results in unresolved symbols that would
3565 be resolved by linking with additional libraries, give those libraries
3566 as the @var{other-libraries} argument, separated by spaces:
3567 e.g., @option{-lXt -lX11}. Otherwise, this macro will fail to detect
3568 that @var{function} is present, because linking the test program will
3569 always fail with unresolved symbols.
3574 @node Library Functions
3575 @section Library Functions
3577 The following macros check for particular C library functions.
3578 If there is no macro specifically defined to check for a function you need,
3579 and you don't need to check for any special properties of
3580 it, then you can use one of the general function-check macros.
3583 * Function Portability:: Pitfalls with usual functions
3584 * Particular Functions:: Special handling to find certain functions
3585 * Generic Functions:: How to find other functions
3588 @node Function Portability
3589 @subsection Portability of C Functions
3590 @cindex Portability of C functions
3591 @cindex C function portability
3593 Most usual functions can either be missing, or be buggy, or be limited
3594 on some architectures. This section tries to make an inventory of these
3595 portability issues. By definition, this list will always require
3596 additions. Please help us keeping it as complete as possible.
3601 @prindex @code{exit}
3602 Did you know that, on some older hosts, @code{exit} returns @code{int}?
3603 This is because @code{exit} predates @code{void}, and there was a long
3604 tradition of it returning @code{int}.
3608 @prindex @code{putenv}
3609 POSIX specifies that @code{putenv} puts the given string directly in
3610 @code{environ}, but some systems make a copy of it instead (eg.@:
3611 glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might
3612 not free it, causing a memory leak (eg.@: FreeBSD 4).
3614 POSIX specifies that @code{putenv("FOO")} removes @samp{FOO} from the
3615 environment, but on some systems (eg.@: FreeBSD 4) this is not the
3616 case and instead @code{unsetenv} must be used.
3618 On MINGW, a call @code{putenv("FOO=")} removes @samp{FOO} from the
3619 environment, rather than inserting it with an empty value.
3621 @item @code{signal} handler
3623 @prindex @code{signal}
3624 Normally @code{signal} takes a handler function with a return type of
3625 @code{void}, but some old systems required @code{int} instead. Any
3626 actual @code{int} value returned is not used, this is only a
3627 difference in the function prototype demanded.
3629 All systems we know of in current use take @code{void}. Presumably
3630 @code{int} was to support K&R C, where of course @code{void} is not
3631 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
3632 used to establish the correct type in all cases.
3634 @item @code{snprintf}
3635 @c @fuindex snprintf
3636 @prindex @code{snprintf}
3637 @c @fuindex vsnprintf
3638 @prindex @code{vsnprintf}
3639 The ISO C99 standard says that if the output array isn't big enough
3640 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
3641 truncate the output and return the number of bytes that ought to have
3642 been produced. Some older systems return the truncated length (e.g.,
3643 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
3644 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
3645 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
3646 older systems ignore the length and overrun the buffer (e.g., 64-bit
3649 @item @code{sprintf}
3651 @prindex @code{sprintf}
3652 @c @fuindex vsprintf
3653 @prindex @code{vsprintf}
3654 The ISO C standard says @code{sprintf} and @code{vsprintf} return the
3655 number of bytes written, but on some old systems (SunOS 4 for
3656 instance) they return the buffer pointer instead.
3660 @prindex @code{sscanf}
3661 On various old systems, e.g., HP-UX 9, @code{sscanf} requires that its
3662 input string be writable (though it doesn't actually change it). This
3663 can be a problem when using @command{gcc} since it normally puts
3664 constant strings in read-only memory
3665 (@pxref{Incompatibilities,Incompatibilities of GCC,,gcc,Using and
3666 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
3667 having format strings read-only can be a problem.
3669 @item @code{strnlen}
3671 @prindex @code{strnlen}
3672 @acronym{AIX} 4.3 provides a broken version which produces the
3676 strnlen ("foobar", 0) = 0
3677 strnlen ("foobar", 1) = 3
3678 strnlen ("foobar", 2) = 2
3679 strnlen ("foobar", 3) = 1
3680 strnlen ("foobar", 4) = 0
3681 strnlen ("foobar", 5) = 6
3682 strnlen ("foobar", 6) = 6
3683 strnlen ("foobar", 7) = 6
3684 strnlen ("foobar", 8) = 6
3685 strnlen ("foobar", 9) = 6
3688 @item @code{sysconf}
3690 @prindex @code{sysconf}
3691 @code{_SC_PAGESIZE} is standard, but some older systems (eg.@: HP-UX
3692 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
3697 @prindex @code{unlink}
3698 The @acronym{POSIX} spec says that @code{unlink} causes the given file to be
3699 removed only after there are no more open file handles for it. Not all
3700 OS's support this behavior though. So even on systems that provide
3701 @code{unlink}, you cannot portably assume it is OK to call it on files
3702 that are open. For example, on Windows 9x and ME, such a call would fail;
3703 on DOS it could even lead to file system corruption, as the file might end
3704 up being written to after the OS has removed it.
3706 @item @code{unsetenv}
3707 @c @fuindex unsetenv
3708 @prindex @code{unsetenv}
3709 On MINGW, @code{unsetenv} is not available, but a variable @samp{FOO}
3710 can be removed with a call @code{putenv("FOO=")}, as described under
3711 @code{putenv} above.
3713 @item @code{va_copy}
3715 @prindex @code{va_copy}
3716 The ISO C99 standard provides @code{va_copy} for copying
3717 @code{va_list} variables. It may be available in older environments
3718 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
3719 C89 mode). These can be tested with @code{#ifdef}. A fallback to
3720 @code{memcpy (&dst, &src, sizeof(va_list))} will give maximum
3723 @item @code{va_list}
3725 @prindex @code{va_list}
3726 @code{va_list} is not necessarily just a pointer. It can be a
3727 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
3728 not portable. Or it can be an array (e.g., @command{gcc} in some
3729 PowerPC configurations), which means as a function parameter it can be
3730 effectively call-by-reference and library routines might modify the
3731 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
3734 @item Signed @code{>>}
3735 Normally the C @code{>>} right shift of a signed type replicates the
3736 high bit, giving a so-called ``arithmetic'' shift. But care should be
3737 taken since the ISO C standard doesn't require that behavior. On those
3738 few processors without a native arithmetic shift (for instance Cray
3739 vector systems) zero bits may be shifted in, the same as a shift of an
3744 @node Particular Functions
3745 @subsection Particular Function Checks
3746 @cindex Function, checking
3748 These macros check for particular C functions---whether they exist, and
3749 in some cases how they respond when given certain arguments.
3751 @defmac AC_FUNC_ALLOCA
3752 @acindex{FUNC_ALLOCA}
3754 @cvindex HAVE_ALLOCA_H
3757 @prindex @code{alloca}
3759 Check how to get @code{alloca}. Tries to get a builtin version by
3760 checking for @file{alloca.h} or the predefined C preprocessor macros
3761 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
3762 it defines @code{HAVE_ALLOCA_H}.
3764 If those attempts fail, it looks for the function in the standard C
3765 library. If any of those methods succeed, it defines
3766 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
3767 @code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} (so
3768 programs can periodically call @samp{alloca(0)} to garbage collect).
3769 This variable is separate from @code{LIBOBJS} so multiple programs can
3770 share the value of @code{ALLOCA} without needing to create an actual
3771 library, in case only some of them use the code in @code{LIBOBJS}.
3773 This macro does not try to get @code{alloca} from the System V R3
3774 @file{libPW} or the System V R4 @file{libucb} because those libraries
3775 contain some incompatible functions that cause trouble. Some versions
3776 do not even contain @code{alloca} or contain a buggy version. If you
3777 still want to use their @code{alloca}, use @code{ar} to extract
3778 @file{alloca.o} from them instead of compiling @file{alloca.c}.
3780 Source files that use @code{alloca} should start with a piece of code
3781 like the following, to declare it properly. In some versions of @acronym{AIX},
3782 the declaration of @code{alloca} must precede everything else except for
3783 comments and preprocessor directives. The @code{#pragma} directive is
3784 indented so that pre-@acronym{ANSI} C compilers will ignore it, rather than
3789 /* AIX requires this to be the first thing in the file. */
3792 # include <alloca.h>
3797 # ifndef alloca /* predefined by HP cc +Olibcalls */
3807 @defmac AC_FUNC_CHOWN
3808 @acindex{FUNC_CHOWN}
3810 @prindex @code{chown}
3811 If the @code{chown} function is available and works (in particular, it
3812 should accept @option{-1} for @code{uid} and @code{gid}), define
3817 @defmac AC_FUNC_CLOSEDIR_VOID
3818 @acindex{FUNC_CLOSEDIR_VOID}
3819 @cvindex CLOSEDIR_VOID
3820 @c @fuindex closedir
3821 @prindex @code{closedir}
3822 If the @code{closedir} function does not return a meaningful value,
3823 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
3824 return value for an error indicator.
3827 @defmac AC_FUNC_ERROR_AT_LINE
3828 @acindex{FUNC_ERROR_AT_LINE}
3829 @c @fuindex error_at_line
3830 @prindex @code{error_at_line}
3831 If the @code{error_at_line} function is not found, require an
3832 @code{AC_LIBOBJ} replacement of @samp{error}.
3835 @defmac AC_FUNC_FNMATCH
3836 @acindex{FUNC_FNMATCH}
3838 @prindex @code{fnmatch}
3839 If the @code{fnmatch} function conforms to @acronym{POSIX}, define
3840 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
3841 the bugs in Solaris 2.4.
3843 Note that for historical reasons, contrary to the other specific
3844 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
3845 broken/missing @code{fnmatch}. See @code{AC_REPLACE_FNMATCH} below.
3848 @defmac AC_FUNC_FNMATCH_GNU
3849 @acindex{FUNC_FNMATCH_GNU}
3851 @prindex @code{fnmatch}
3852 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
3853 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
3854 implementation bugs, for example, the bugs in the @acronym{GNU} C
3858 @defmac AC_FUNC_FORK
3860 @cvindex HAVE_VFORK_H
3861 @cvindex HAVE_WORKING_FORK
3862 @cvindex HAVE_WORKING_VFORK
3865 @prindex @code{fork}
3867 @prindex @code{vfork}
3869 This macro checks for the @code{fork} and @code{vfork} functions. If a
3870 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
3871 checks whether @code{fork} is just a stub by trying to run it.
3873 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
3874 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
3875 define @code{vfork} to be @code{fork} for backward compatibility with
3876 previous versions of @command{autoconf}. This macro checks for several known
3877 errors in implementations of @code{vfork} and considers the system to not
3878 have a working @code{vfork} if it detects any of them. It is not considered
3879 to be an implementation error if a child's invocation of @code{signal}
3880 modifies the parent's signal handler, since child processes rarely change
3881 their signal handlers.
3883 Since this macro defines @code{vfork} only for backward compatibility with
3884 previous versions of @command{autoconf} you're encouraged to define it
3885 yourself in new code:
3888 #if !HAVE_WORKING_VFORK
3895 @defmac AC_FUNC_FSEEKO
3896 @acindex{FUNC_FSEEKO}
3897 @cvindex _LARGEFILE_SOURCE
3899 @prindex @code{fseeko}
3900 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
3901 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
3902 visible on some systems (e.g. glibc 2.2). Otherwise linkage problems
3903 may occur when compiling with @code{AC_SYS_LARGEFILE} on
3904 largefile-sensitive systems where @code{off_t} does not default to a
3908 @defmac AC_FUNC_GETGROUPS
3909 @acindex{FUNC_GETGROUPS}
3910 @ovindex GETGROUPS_LIBS
3911 @c @fuindex getgroups
3912 @prindex @code{getgroups}
3913 If the @code{getgroups} function is available and works (unlike on
3914 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
3915 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
3916 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
3919 @defmac AC_FUNC_GETLOADAVG
3920 @acindex{FUNC_GETLOADAVG}
3925 @cvindex HAVE_NLIST_H
3926 @cvindex NLIST_NAME_UNION
3927 @cvindex GETLODAVG_PRIVILEGED
3928 @cvindex NEED_SETGID
3929 @cvindex C_GETLOADAVG
3931 @ovindex NEED_SETGID
3933 @ovindex GETLOADAVG_LIBS
3934 @c @fuindex getloadavg
3935 @prindex @code{getloadavg}
3936 Check how to get the system load averages. To perform its tests
3937 properly, this macro needs the file @file{getloadavg.c}; therefore, be
3938 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
3939 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
3941 If the system has the @code{getloadavg} function, define
3942 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
3943 needed to get that function. Also add @code{GETLOADAVG_LIBS} to
3944 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
3945 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
3946 possibly define several other C preprocessor macros and output
3951 Define @code{C_GETLOADAVG}.
3954 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
3959 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
3962 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
3963 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
3964 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
3967 Programs may need to be installed setgid (or setuid) for
3968 @code{getloadavg} to work. In this case, define
3969 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
3970 to @samp{true} (and otherwise to @samp{false}), and set
3971 @code{KMEM_GROUP} to the name of the group that should own the installed
3976 @defmac AC_FUNC_GETMNTENT
3977 @acindex{FUNC_GETMNTENT}
3978 @cvindex HAVE_GETMNTENT
3979 @c @fuindex getmntent
3980 @prindex @code{getmntent}
3981 Check for @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen}
3982 libraries, for @sc{irix} 4, PTX, and Unixware, respectively. Then, if
3983 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
3986 @defmac AC_FUNC_GETPGRP
3987 @acindex{FUNC_GETPGRP}
3988 @cvindex GETPGRP_VOID
3991 @prindex @code{getpgid}
3992 @prindex @code{getpgrp}
3993 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
3994 @code{getpgrp}; this is the @acronym{POSIX} behavior. On older BSD
3995 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
3996 behaves like @acronym{POSIX}'s @code{getpgid}.
4006 This macro does not check whether
4007 @code{getpgrp} exists at all; if you need to work in that situation,
4008 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4011 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4012 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4013 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4015 @prindex @code{lstat}
4016 If @file{link} is a symbolic link, then @code{lstat} should treat
4017 @file{link/} the same as @file{link/.}. However, many older
4018 @code{lstat} implementations incorrectly ignore trailing slashes.
4020 It is safe to assume that if @code{lstat} incorrectly ignores
4021 trailing slashes, then other symbolic-link-aware functions like
4022 @code{unlink} also incorrectly ignore trailing slashes.
4024 If @code{lstat} behaves properly, define
4025 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4026 @code{AC_LIBOBJ} replacement of @code{lstat}.
4029 @defmac AC_FUNC_MALLOC
4030 @acindex{FUNC_MALLOC}
4031 @cvindex HAVE_MALLOC
4034 @prindex @code{malloc}
4035 If the @code{malloc} function is compatible with the @acronym{GNU} C
4036 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4037 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4038 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4039 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4040 native @code{malloc} is not used in the main project.
4042 Typically, the replacement file @file{malloc.c} should look like (note
4043 the @samp{#undef malloc}):
4047 # include <config.h>
4051 #include <sys/types.h>
4055 /* Allocate an N-byte block of memory from the heap.
4056 If N is zero, allocate a 1-byte block. */
4059 rpl_malloc (size_t n)
4068 @defmac AC_FUNC_MEMCMP
4069 @acindex{FUNC_MEMCMP}
4072 @prindex @code{memcmp}
4073 If the @code{memcmp} function is not available, or does not work on
4074 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4075 bytes or more and with at least one buffer not starting on a 4-byte
4076 boundary (such as the one on NeXT x86 OpenStep), require an
4077 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4080 @defmac AC_FUNC_MBRTOWC
4081 @acindex{FUNC_MBRTOWC}
4082 @cvindex HAVE_MBRTOWC
4084 @prindex @code{mbrtowc}
4085 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4086 type @code{mbstate_t} are properly declared.
4089 @defmac AC_FUNC_MKTIME
4090 @acindex{FUNC_MKTIME}
4093 @prindex @code{mktime}
4094 If the @code{mktime} function is not available, or does not work
4095 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4096 For the purposes of this test, @code{mktime} should conform to the
4097 @acronym{POSIX} standard and should be the inverse of
4101 @defmac AC_FUNC_MMAP
4105 @prindex @code{mmap}
4106 If the @code{mmap} function exists and works correctly, define
4107 @code{HAVE_MMAP}. Only checks private fixed mapping of already-mapped
4111 @defmac AC_FUNC_OBSTACK
4112 @acindex{FUNC_OBSTACK}
4113 @cvindex HAVE_OBSTACK
4115 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4116 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4119 @defmac AC_FUNC_REALLOC
4120 @acindex{FUNC_REALLOC}
4121 @cvindex HAVE_REALLOC
4124 @prindex @code{realloc}
4125 If the @code{realloc} function is compatible with the @acronym{GNU} C
4126 library @code{realloc} (i.e., @samp{realloc (0, 0)} returns a
4127 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4128 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4129 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4130 the native @code{realloc} is not used in the main project. See
4131 @code{AC_FUNC_MALLOC} for details.
4134 @defmac AC_FUNC_SELECT_ARGTYPES
4135 @acindex{FUNC_SELECT_ARGTYPES}
4136 @cvindex SELECT_TYPE_ARG1
4137 @cvindex SELECT_TYPE_ARG234
4138 @cvindex SELECT_TYPE_ARG5
4140 @prindex @code{select}
4141 Determines the correct type to be passed for each of the
4142 @code{select} function's arguments, and defines those types
4143 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4144 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4145 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4146 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4149 @defmac AC_FUNC_SETPGRP
4150 @acindex{FUNC_SETPGRP}
4151 @cvindex SETPGRP_VOID
4153 @prindex @code{setpgrp}
4154 If @code{setpgrp} takes no argument (the @acronym{POSIX} version), define
4155 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4156 two process IDs as arguments. This macro does not check whether
4157 @code{setpgrp} exists at all; if you need to work in that situation,
4158 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4161 @defmac AC_FUNC_STAT
4162 @defmacx AC_FUNC_LSTAT
4164 @acindex{FUNC_LSTAT}
4165 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4166 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4168 @prindex @code{stat}
4170 @prindex @code{lstat}
4171 Determine whether @code{stat} or @code{lstat} have the bug that it
4172 succeeds when given the zero-length file name as argument. The @code{stat}
4173 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4176 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4177 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4181 @defmac AC_FUNC_SETVBUF_REVERSED
4182 @acindex{FUNC_SETVBUF_REVERSED}
4183 @cvindex SETVBUF_REVERSED
4185 @prindex @code{setvbuf}
4186 If @code{setvbuf} takes the buffering type as its second argument and
4187 the buffer pointer as the third, instead of the other way around, define
4188 @code{SETVBUF_REVERSED}.
4191 @defmac AC_FUNC_STRCOLL
4192 @acindex{FUNC_STRCOLL}
4193 @cvindex HAVE_STRCOLL
4195 @prindex @code{strcoll}
4196 If the @code{strcoll} function exists and works correctly, define
4197 @code{HAVE_STRCOLL}. This does a bit more than
4198 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4199 definitions of @code{strcoll} that should not be used.
4202 @defmac AC_FUNC_STRTOD
4203 @acindex{FUNC_STRTOD}
4206 @prindex @code{strtod}
4207 If the @code{strtod} function does not exist or doesn't work correctly,
4208 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4209 because @file{strtod.c} is likely to need @samp{pow}, set the output
4210 variable @code{POW_LIB} to the extra library needed.
4213 @defmac AC_FUNC_STRERROR_R
4214 @acindex{FUNC_STRERROR_R}
4215 @cvindex HAVE_STRERROR_R
4216 @cvindex HAVE_DECL_STRERROR_R
4217 @cvindex STRERROR_R_CHAR_P
4218 @c @fuindex strerror_r
4219 @prindex @code{strerror_r}
4220 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4221 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4222 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4223 returns an @code{int} error number. The Thread-Safe Functions option of
4224 @acronym{POSIX} requires @code{strerror_r} to return @code{int}, but
4225 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4226 Library) return a @code{char *} value that is not necessarily equal to
4227 the buffer argument.
4230 @defmac AC_FUNC_STRFTIME
4231 @acindex{FUNC_STRFTIME}
4232 @cvindex HAVE_STRFTIME
4233 @c @fuindex strftime
4234 @prindex @code{strftime}
4235 Check for @code{strftime} in the @file{intl} library, for SCO @sc{unix}.
4236 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4239 @defmac AC_FUNC_STRNLEN
4240 @acindex{FUNC_STRNLEN}
4241 @cvindex HAVE_STRNLEN
4243 @prindex @code{strnlen}
4244 If the @code{strnlen} function is not available, or is buggy (like the one
4245 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4248 @defmac AC_FUNC_UTIME_NULL
4249 @acindex{FUNC_UTIME_NULL}
4250 @cvindex HAVE_UTIME_NULL
4252 @prindex @code{utime}
4253 If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to
4254 the present, define @code{HAVE_UTIME_NULL}.
4257 @defmac AC_FUNC_VPRINTF
4258 @acindex{FUNC_VPRINTF}
4259 @cvindex HAVE_VPRINTF
4260 @cvindex HAVE_DOPRNT
4262 @prindex @code{vprintf}
4263 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4264 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
4265 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4266 are also available.)
4269 @defmac AC_REPLACE_FNMATCH
4270 @acindex{REPLACE_FNMATCH}
4272 @prindex @code{fnmatch}
4274 If the @code{fnmatch} function does not conform to @acronym{POSIX} (see
4275 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4277 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4278 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4279 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
4280 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4281 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4282 included in place of the system @code{<fnmatch.h>}.
4287 @node Generic Functions
4288 @subsection Generic Function Checks
4290 These macros are used to find functions not covered by the ``particular''
4291 test macros. If the functions might be in libraries other than the
4292 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4293 If you need to check the behavior of a function as well as find out
4294 whether it is present, you have to write your own test for
4295 it (@pxref{Writing Tests}).
4297 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4298 @acindex{CHECK_FUNC}
4299 If C function @var{function} is available, run shell commands
4300 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
4301 want to define a symbol if the function is available, consider using
4302 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
4303 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4304 standardized than C++. (@pxref{Language Choice}, for more information
4305 about selecting the language for checks.)
4308 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4309 @acindex{CHECK_FUNCS}
4310 @cvindex HAVE_@var{function}
4311 For each @var{function} in the whitespace-separated argument list,
4312 define @code{HAVE_@var{function}} (in all capitals) if it is available.
4313 If @var{action-if-found} is given, it is additional shell code to
4314 execute when one of the functions is found. You can give it a value of
4315 @samp{break} to break out of the loop on the first match. If
4316 @var{action-if-not-found} is given, it is executed when one of the
4317 functions is not found.
4322 Autoconf follows a philosophy that was formed over the years by those
4323 who have struggled for portability: isolate the portability issues in
4324 specific files, and then program as if you were in a @acronym{POSIX}
4325 environment. Some functions may be missing or unfixable, and your
4326 package must be ready to replace them.
4328 @defmac AC_LIBOBJ (@var{function})
4331 Specify that @samp{@var{function}.c} must be included in the executables
4332 to replace a missing or broken implementation of @var{function}.
4334 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4335 variable @code{LIBOBJS} if it is not already in, and calls
4336 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
4337 directly change @code{LIBOBJS}, since this is not traceable.
4340 @defmac AC_LIBSOURCE (@var{file})
4342 Specify that @var{file} might be needed to compile the project. If you
4343 need to know what files might be needed by a @file{configure.ac}, you
4344 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
4346 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4347 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
4348 that case, since shell variables cannot be traced statically, you must
4349 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4350 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
4351 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4352 @code{"foo"} or @code{"bar"}, you should do:
4357 AC_LIBOBJ($foo_or_bar)
4361 There is usually a way to avoid this, however, and you are encouraged to
4362 simply call @code{AC_LIBOBJ} with literal arguments.
4364 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
4365 slightly different semantics: the old macro took the function name,
4366 e.g., @code{foo}, as its argument rather than the file name.
4369 @defmac AC_LIBSOURCES (@var{files})
4370 @acindex{LIBSOURCES}
4371 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
4372 comma-separated M4 list. Thus, the above example might be rewritten:
4375 AC_LIBSOURCES([foo.c, bar.c])
4376 AC_LIBOBJ($foo_or_bar)
4380 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
4381 @acindex{CONFIG_LIBOBJ_DIR}
4382 Specify that @code{AC_LIBOBJ} replacement files are to be found in
4383 @var{directory}, a relative path starting from the top level of the
4384 source tree. The replacement directory defaults to @file{.}, the top
4385 level directory, and the most typical value is @file{lib}, corresponding
4386 to @samp{AC_CONFIG_LIBOBJ_DIR(lib)}.
4388 @command{configure} might need to know the replacement directory for the
4389 following reasons: (i) some checks use the replacement files, (ii) some
4390 macros bypass broken system headers by installing links to the
4391 replacement headers, etc.
4396 It is common to merely check for the existence of a function, and ask
4397 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
4398 a convenient shorthand.
4400 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
4401 @acindex{REPLACE_FUNCS}
4403 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
4404 @var{action-if-not-found}. You can declare your replacement function by
4405 enclosing the prototype in @samp{#if !HAVE_@var{function}}. If the
4406 system has the function, it probably declares it in a header file you
4407 should be including, so you shouldn't redeclare it lest your declaration
4412 @section Header Files
4413 @cindex Header, checking
4415 The following macros check for the presence of certain C header files.
4416 If there is no macro specifically defined to check for a header file you need,
4417 and you don't need to check for any special properties of
4418 it, then you can use one of the general header-file check macros.
4421 * Header Portability:: Collected knowledge on common headers
4422 * Particular Headers:: Special handling to find certain headers
4423 * Generic Headers:: How to find other headers
4426 @node Header Portability
4427 @subsection Portability of Headers
4428 @cindex Portability of headers
4429 @cindex Header portability
4431 This section tries to collect knowledge about common headers, and the
4432 problems they cause. By definition, this list will always require
4433 additions. Please help us keeping it as complete as possible.
4436 @item @file{inttypes.h} vs.@: @file{stdint.h}
4437 @hdrindex inttypes.h
4439 Paul Eggert notes that: ISO C 1999 says that @file{inttypes.h} includes
4440 @file{stdint.h}, so there's no need to include @file{stdint.h}
4441 separately in a standard environment. Many implementations have
4442 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but I don't
4443 know of any implementation that has @file{stdint.h} but not
4444 @file{inttypes.h}. Nor do I know of any free software that includes
4445 @file{stdint.h}; @file{stdint.h} seems to be a creation of the committee.
4447 @item @file{linux/irda.h}
4448 @hdrindex linux/irda.h
4449 It requires @file{linux/types.h} and @file{sys/socket.h}.
4451 @item @file{linux/random.h}
4452 @hdrindex linux/random.h
4453 It requires @file{linux/types.h}.
4455 @item @file{net/if.h}
4457 On Darwin, this file requires that @file{sys/socket.h} be included
4458 beforehand. One should run:
4461 AC_CHECK_HEADERS([sys/socket.h])
4462 AC_CHECK_HEADERS([net/if.h], [], [],
4465 # include <stdlib.h>
4466 # include <stddef.h>
4469 # include <stdlib.h>
4472 #if HAVE_SYS_SOCKET_H
4473 # include <sys/socket.h>
4478 @item @file{netinet/if_ether.h}
4479 @hdrindex netinet/if_ether.h
4480 On Darwin, this file requires that @file{stdio.h} and
4481 @file{sys/socket.h} be included beforehand. One should run:
4484 AC_CHECK_HEADERS([sys/socket.h])
4485 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
4488 # include <stdlib.h>
4489 # include <stddef.h>
4492 # include <stdlib.h>
4495 #if HAVE_SYS_SOCKET_H
4496 # include <sys/socket.h>
4501 @item @file{stdint.h}
4502 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
4504 @item @file{stdlib.h}
4506 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
4508 @item @file{sys/mount.h}
4509 @hdrindex sys/mount.h
4510 On FreeBSD 4.8 on ia32 and using gcc version 2.95.4,
4511 @file{sys/params.h} is a prerequisite.
4513 @item @file{sys/socket.h}
4514 @hdrindex sys/socket.h
4515 On Darwin, @file{stdlib.h} is a prerequisite.
4517 @item @file{sys/ucred.h}
4518 @hdrindex sys/ucred.h
4519 On HP Tru64 5.1, @file{sys/types.h} is a prerequisite.
4521 @item @file{X11/extensions/scrnsaver.h}
4522 @hdrindex X11/extensions/scrnsaver.h
4523 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
4524 so required that you might not even consider looking for it.
4527 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
4528 [[#include <X11/Xlib.h>
4534 @node Particular Headers
4535 @subsection Particular Header Checks
4537 These macros check for particular system header files---whether they
4538 exist, and in some cases whether they declare certain symbols.
4540 @defmac AC_HEADER_DIRENT
4541 @acindex{HEADER_DIRENT}
4542 @cvindex HAVE_DIRENT_H
4543 @cvindex HAVE_NDIR_H
4544 @cvindex HAVE_SYS_DIR_H
4545 @cvindex HAVE_SYS_NDIR_H
4547 @hdrindex sys/ndir.h
4550 Check for the following header files. For the first one that is
4551 found and defines @samp{DIR}, define the listed C preprocessor macro:
4553 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
4554 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
4555 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
4556 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
4557 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
4560 The directory-library declarations in your source code should look
4561 something like the following:
4566 # include <dirent.h>
4567 # define NAMLEN(dirent) strlen((dirent)->d_name)
4569 # define dirent direct
4570 # define NAMLEN(dirent) (dirent)->d_namlen
4571 # if HAVE_SYS_NDIR_H
4572 # include <sys/ndir.h>
4575 # include <sys/dir.h>
4584 Using the above declarations, the program would declare variables to be
4585 of type @code{struct dirent}, not @code{struct direct}, and would access
4586 the length of a directory entry name by passing a pointer to a
4587 @code{struct dirent} to the @code{NAMLEN} macro.
4589 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
4592 @defmac AC_HEADER_MAJOR
4593 @acindex{HEADER_MAJOR}
4594 @cvindex MAJOR_IN_MKDEV
4595 @cvindex MAJOR_IN_SYSMACROS
4596 @hdrindex sys/mkdev.h
4597 @hdrindex sys/sysmacros.h
4598 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
4599 @code{makedev}, but @file{sys/mkdev.h} does, define
4600 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
4601 @code{MAJOR_IN_SYSMACROS}.
4605 @defmac AC_HEADER_STAT
4606 @acindex{HEADER_STAT}
4607 @acindex{STAT_MACROS_BROKEN}
4608 @hdrindex sys/stat.h
4609 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
4610 @file{sys/stat.h} do not work properly (returning false positives),
4611 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
4612 Amdahl UTS and Motorola System V/88.
4615 @defmac AC_HEADER_STDBOOL
4616 @acindex{HEADER_STDBOOL}
4617 @cvindex HAVE_STDBOOL_H
4621 If @file{stdbool.h} exists and is conformant to C99, define
4622 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
4623 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
4624 @file{system.h} should contain the following code:
4628 # include <stdbool.h>
4634 typedef unsigned char _Bool;
4640 # define __bool_true_false_are_defined 1
4646 @defmac AC_HEADER_STDC
4647 @acindex{HEADER_STDC}
4648 @cvindex STDC_HEADERS
4654 Define @code{STDC_HEADERS} if the system has @acronym{ANSI} C header files.
4655 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
4656 @file{string.h}, and @file{float.h}; if the system has those, it
4657 probably has the rest of the @acronym{ANSI} C header files. This macro also
4658 checks whether @file{string.h} declares @code{memchr} (and thus
4659 presumably the other @code{mem} functions), whether @file{stdlib.h}
4660 declare @code{free} (and thus presumably @code{malloc} and other related
4661 functions), and whether the @file{ctype.h} macros work on characters
4662 with the high bit set, as @acronym{ANSI} C requires.
4664 Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether
4665 the system has @acronym{ANSI}-compliant header files (and probably C library
4666 functions) because many systems that have GCC do not have @acronym{ANSI} C
4671 On systems without @acronym{ANSI} C headers, there is so much variation
4672 that it is probably easier to declare the functions you use than to
4673 figure out exactly what the system header files declare. Some systems
4674 contain a mix of functions from @acronym{ANSI} and @acronym{BSD}; some are
4675 mostly @acronym{ANSI} but lack @samp{memmove}; some define the
4676 @acronym{BSD} functions as macros in @file{string.h} or
4677 @file{strings.h}; some have only the @acronym{BSD} functions but
4678 @file{string.h}; some declare the memory functions in @file{memory.h},
4679 some in @file{string.h}; etc. It is probably sufficient to check for
4680 one string function and one memory function; if the library has the
4681 @acronym{ANSI} versions of those then it probably has most of the others.
4682 If you put the following in @file{configure.ac}:
4686 AC_CHECK_FUNCS(strchr memcpy)
4690 then, in your code, you can use declarations like this:
4695 # include <string.h>
4698 # define strchr index
4699 # define strrchr rindex
4701 char *strchr (), *strrchr ();
4703 # define memcpy(d, s, n) bcopy ((s), (d), (n))
4704 # define memmove(d, s, n) bcopy ((s), (d), (n))
4711 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
4712 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros won't
4713 suffice; you must provide an implementation of each function. An easy
4714 way to incorporate your implementations only when needed (since the ones
4715 in system C libraries may be hand optimized) is to, taking @code{memchr}
4716 for example, put it in @file{memchr.c} and use
4717 @samp{AC_REPLACE_FUNCS(memchr)}.
4720 @defmac AC_HEADER_SYS_WAIT
4721 @acindex{HEADER_SYS_WAIT}
4722 @cvindex HAVE_SYS_WAIT_H
4723 @hdrindex sys/wait.h
4724 If @file{sys/wait.h} exists and is compatible with @acronym{POSIX}, define
4725 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
4726 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
4727 of @code{int} to store a status value. If @file{sys/wait.h} is not
4728 @acronym{POSIX} compatible, then instead of including it, define the
4729 @acronym{POSIX} macros with their usual interpretations. Here is an
4734 #include <sys/types.h>
4736 # include <sys/wait.h>
4739 # define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8)
4742 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
4748 @cvindex _POSIX_VERSION
4750 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
4751 @acronym{POSIX} systems. If there is no @file{unistd.h}, it is definitely
4752 not a @acronym{POSIX} system. However, some non-@acronym{POSIX} systems do
4753 have @file{unistd.h}.
4755 The way to check if the system supports @acronym{POSIX} is:
4760 # include <sys/types.h>
4761 # include <unistd.h>
4764 #ifdef _POSIX_VERSION
4765 /* Code for POSIX systems. */
4770 @defmac AC_HEADER_TIME
4771 @acindex{HEADER_TIME}
4772 @cvindex TIME_WITH_SYS_TIME
4774 @hdrindex sys/time.h
4775 If a program may include both @file{time.h} and @file{sys/time.h},
4776 define @code{TIME_WITH_SYS_TIME}. On some older systems,
4777 @file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
4778 protected against multiple inclusion, so programs should not explicitly
4779 include both files. This macro is useful in programs that use, for
4780 example, @code{struct timeval} as well as
4781 @code{struct tm}. It is best used in conjunction with
4782 @code{HAVE_SYS_TIME_H}, which can be checked for using
4783 @code{AC_CHECK_HEADERS(sys/time.h)}.
4787 #if TIME_WITH_SYS_TIME
4788 # include <sys/time.h>
4791 # if HAVE_SYS_TIME_H
4792 # include <sys/time.h>
4802 @defmac AC_HEADER_TIOCGWINSZ
4803 @acindex{HEADER_TIOCGWINSZ}
4804 @cvindex GWINSZ_IN_SYS_IOCTL
4805 @hdrindex sys/ioctl.h
4807 @c FIXME: I need clarifications from Jim.
4808 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
4809 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
4810 found in @file{<termios.h>}.
4817 # include <termios.h>
4820 #if GWINSZ_IN_SYS_IOCTL
4821 # include <sys/ioctl.h>
4827 @node Generic Headers
4828 @subsection Generic Header Checks
4830 These macros are used to find system header files not covered by the
4831 ``particular'' test macros. If you need to check the contents of a header
4832 as well as find out whether it is present, you have to write your own
4833 test for it (@pxref{Writing Tests}).
4835 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4836 @acindex{CHECK_HEADER}
4837 If the system header file @var{header-file} is compilable, execute shell
4838 commands @var{action-if-found}, otherwise execute
4839 @var{action-if-not-found}. If you just want to define a symbol if the
4840 header file is available, consider using @code{AC_CHECK_HEADERS}
4843 For compatibility issues with older versions of Autoconf, please read
4847 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4848 @acindex{CHECK_HEADERS}
4849 @cvindex HAVE_@var{header}
4850 For each given system header file @var{header-file} in the
4851 whitespace-separated argument list that exists, define
4852 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
4853 is given, it is additional shell code to execute when one of the header
4854 files is found. You can give it a value of @samp{break} to break out of
4855 the loop on the first match. If @var{action-if-not-found} is given, it
4856 is executed when one of the header files is not found.
4858 For compatibility issues with older versions of Autoconf, please read
4862 Previous versions of Autoconf merely checked whether the header was
4863 accepted by the preprocessor. This was changed because the old test was
4864 inappropriate for typical uses. Headers are typically used to compile,
4865 not merely to preprocess, and the old behavior sometimes accepted
4866 headers that clashed at compile-time. If you need to check whether a
4867 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
4868 (@pxref{Running the Preprocessor}).
4870 This scheme, which improves the robustness of the test, also requires
4871 that you make sure that headers that must be included before the
4872 @var{header-file} be part of the @var{includes}, (@pxref{Default
4873 Includes}). If looking for @file{bar.h}, which requires that
4874 @file{foo.h} be included before if it exists, we suggest the following
4878 AC_CHECK_HEADERS([foo.h])
4879 AC_CHECK_HEADERS([bar.h], [], [],
4887 @section Declarations
4888 @cindex Declaration, checking
4890 The following macros check for the declaration of variables and
4891 functions. If there is no macro specifically defined to check for a
4892 symbol you need, then you can use the general macros (@pxref{Generic
4893 Declarations}) or, for more complex tests, you may use
4894 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
4897 * Particular Declarations:: Macros to check for certain declarations
4898 * Generic Declarations:: How to find other declarations
4901 @node Particular Declarations
4902 @subsection Particular Declaration Checks
4904 There are no specific macros for declarations.
4906 @node Generic Declarations
4907 @subsection Generic Declaration Checks
4909 These macros are used to find declarations not covered by the ``particular''
4912 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4913 @acindex{CHECK_DECL}
4914 If @var{symbol} (a function or a variable) is not declared in
4915 @var{includes} and a declaration is needed, run the shell commands
4916 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
4917 @var{includes} are specified, the default includes are used
4918 (@pxref{Default Includes}).
4920 This macro actually tests whether it is valid to use @var{symbol} as an
4921 r-value, not if it is really declared, because it is much safer to avoid
4922 introducing extra declarations when they are not needed.
4925 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4926 @acindex{CHECK_DECLS}
4927 @cvindex HAVE_DECL_@var{symbol}
4928 For each of the @var{symbols} (@emph{comma}-separated list), define
4929 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
4930 @var{symbol} is declared, otherwise to @samp{0}. If
4931 @var{action-if-not-found} is given, it is additional shell code to
4932 execute when one of the function declarations is needed, otherwise
4933 @var{action-if-found} is executed.
4935 This macro uses an m4 list as first argument:
4937 AC_CHECK_DECLS(strdup)
4938 AC_CHECK_DECLS([strlen])
4939 AC_CHECK_DECLS([malloc, realloc, calloc, free])
4942 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
4943 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
4944 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
4945 @emph{sure} that the check was performed, use
4946 @code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
4949 #if !HAVE_DECL_SYMBOL
4950 extern char *symbol;
4955 If the test may have not been performed, however, because it is safer
4956 @emph{not} to declare a symbol than to use a declaration that conflicts
4957 with the system's one, you should use:
4960 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
4961 void *malloc (size_t *s);
4966 You fall into the second category only in extreme situations: either
4967 your files may be used without being configured, or they are used during
4968 the configuration. In most cases the traditional approach is enough.
4974 @cindex Structure, checking
4976 The following macros check for the presence of certain members in C
4977 structures. If there is no macro specifically defined to check for a
4978 member you need, then you can use the general structure-member macros
4979 (@pxref{Generic Structures}) or, for more complex tests, you may use
4980 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
4983 * Particular Structures:: Macros to check for certain structure members
4984 * Generic Structures:: How to find other structure members
4987 @node Particular Structures
4988 @subsection Particular Structure Checks
4990 The following macros check for certain structures or structure members.
4992 @defmac AC_STRUCT_ST_BLKSIZE
4993 @acindex{STRUCT_ST_BLKSIZE}
4994 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
4995 @cvindex HAVE_ST_BLKSIZE
4996 If @code{struct stat} contains an @code{st_blksize} member, define
4997 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
4998 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
4999 the future. This macro is obsoleted, and should be replaced by
5002 AC_CHECK_MEMBERS([struct stat.st_blksize])
5006 @defmac AC_STRUCT_ST_BLOCKS
5007 @acindex{STRUCT_ST_BLOCKS}
5008 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5009 @cvindex HAVE_ST_BLOCKS
5011 If @code{struct stat} contains an @code{st_blocks} member, define
5012 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5013 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5014 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5018 @defmac AC_STRUCT_ST_RDEV
5019 @acindex{STRUCT_ST_RDEV}
5020 @cvindex HAVE_ST_RDEV
5021 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5022 If @code{struct stat} contains an @code{st_rdev} member, define
5023 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
5024 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5025 in the future. Actually, even the new macro is obsolete and should be
5028 AC_CHECK_MEMBERS([struct stat.st_rdev])
5032 @defmac AC_STRUCT_TM
5034 @cvindex TM_IN_SYS_TIME
5036 @hdrindex sys/time.h
5037 If @file{time.h} does not define @code{struct tm}, define
5038 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5039 had better define @code{struct tm}.
5042 @defmac AC_STRUCT_TIMEZONE
5043 @acindex{STRUCT_TIMEZONE}
5044 @cvindex HAVE_TM_ZONE
5045 @cvindex HAVE_TZNAME
5046 Figure out how to get the current timezone. If @code{struct tm} has a
5047 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5048 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5049 @code{tzname} is found, define @code{HAVE_TZNAME}.
5052 @node Generic Structures
5053 @subsection Generic Structure Checks
5055 These macros are used to find structure members not covered by the
5056 ``particular'' test macros.
5058 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5059 @acindex{CHECK_MEMBER}
5060 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5061 If no @var{includes} are specified, the default includes are used
5062 (@pxref{Default Includes}).
5065 AC_CHECK_MEMBER(struct passwd.pw_gecos,,
5066 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5070 You can use this macro for sub-members:
5073 AC_CHECK_MEMBER(struct top.middle.bot)
5077 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5078 @acindex{CHECK_MEMBERS}
5079 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5080 @var{members} using the previous macro. When @var{member} belongs to
5081 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5082 capitals, with spaces and dots replaced by underscores). If
5083 @var{action-if-found} is given, it is executed for each of the found
5084 members. If @var{action-if-not-found} is given, it is executed for each
5085 of the members that could not be found.
5087 This macro uses m4 lists:
5089 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5099 The following macros check for C types, either builtin or typedefs. If
5100 there is no macro specifically defined to check for a type you need, and
5101 you don't need to check for any special properties of it, then you can
5102 use a general type-check macro.
5105 * Particular Types:: Special handling to find certain types
5106 * Generic Types:: How to find other types
5109 @node Particular Types
5110 @subsection Particular Type Checks
5112 @hdrindex sys/types.h
5114 These macros check for particular C types in @file{sys/types.h},
5115 @file{stdlib.h} and others, if they exist.
5117 @defmac AC_TYPE_GETGROUPS
5118 @acindex{TYPE_GETGROUPS}
5119 @cvindex GETGROUPS_T
5120 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5121 is the base type of the array argument to @code{getgroups}.
5124 @defmac AC_TYPE_MBSTATE_T
5125 @acindex{TYPE_MBSTATE_T}
5128 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5129 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
5130 @code{<wchar.h>} does not declare it.
5133 @defmac AC_TYPE_MODE_T
5134 @acindex{TYPE_MODE_T}
5136 Equivalent to @samp{AC_CHECK_TYPE(mode_t, int)}.
5139 @defmac AC_TYPE_OFF_T
5140 @acindex{TYPE_OFF_T}
5142 Equivalent to @samp{AC_CHECK_TYPE(off_t, long)}.
5145 @defmac AC_TYPE_PID_T
5146 @acindex{TYPE_PID_T}
5148 Equivalent to @samp{AC_CHECK_TYPE(pid_t, int)}.
5151 @defmac AC_TYPE_SIGNAL
5152 @acindex{TYPE_SIGNAL}
5155 If @file{signal.h} declares @code{signal} as returning a pointer to a
5156 function returning @code{void}, define @code{RETSIGTYPE} to be
5157 @code{void}; otherwise, define it to be @code{int}.
5159 Define signal handlers as returning type @code{RETSIGTYPE}:
5172 @defmac AC_TYPE_SIZE_T
5173 @acindex{TYPE_SIZE_T}
5175 Equivalent to @samp{AC_CHECK_TYPE(size_t, unsigned)}.
5178 @defmac AC_TYPE_UID_T
5179 @acindex{TYPE_UID_T}
5182 If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and
5183 @code{gid_t} to be @code{int}.
5187 @subsection Generic Type Checks
5189 These macros are used to check for types not covered by the ``particular''
5192 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5193 @acindex{CHECK_TYPE}
5194 Check whether @var{type} is defined. It may be a compiler builtin type
5195 or defined by the @var{includes} (@pxref{Default Includes}).
5199 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5200 @acindex{CHECK_TYPES}
5201 For each @var{type} of the @var{types} that is defined, define
5202 @code{HAVE_@var{type}} (in all capitals). If no @var{includes} are
5203 specified, the default includes are used (@pxref{Default Includes}). If
5204 @var{action-if-found} is given, it is additional shell code to execute
5205 when one of the types is found. If @var{action-if-not-found} is given,
5206 it is executed when one of the types is not found.
5208 This macro uses m4 lists:
5210 AC_CHECK_TYPES(ptrdiff_t)
5211 AC_CHECK_TYPES([unsigned long long, uintmax_t])
5216 Autoconf, up to 2.13, used to provide to another version of
5217 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
5218 compatibility, a simple heuristics, quite safe but not totally, is
5219 implemented. In case of doubt, read the documentation of the former
5220 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
5223 @node Compilers and Preprocessors
5224 @section Compilers and Preprocessors
5226 @cindex Preprocessors
5229 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
5230 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
5231 the output of the compiler, typically to the empty string if Unix and
5232 @samp{.exe} if Win32 or OS/2.
5235 They also define the output variable @code{OBJEXT} based on the
5236 output of the compiler, after @file{.c} files have been excluded, typically
5237 to @samp{o} if Unix, @samp{obj} if Win32.
5239 If the compiler being used does not produce executables, the tests fail. If
5240 the executables can't be run, and cross-compilation is not enabled, they
5241 fail too. @xref{Manual Configuration}, for more on support for cross
5245 * Specific Compiler Characteristics:: Some portability issues
5246 * Generic Compiler Characteristics:: Language independent tests and features
5247 * C Compiler:: Checking its characteristics
5248 * C++ Compiler:: Likewise
5249 * Fortran Compiler:: Likewise
5252 @node Specific Compiler Characteristics
5253 @subsection Specific Compiler Characteristics
5255 Some compilers exhibit different behaviors.
5258 @item Static/Dynamic Expressions
5259 Autoconf relies on a trick to extract one bit of information from the C
5260 compiler: using negative array sizes. For instance the following
5261 excerpt of a C source demonstrates how to test whether @samp{int}s are 4
5268 static int test_array [sizeof (int) == 4 ? 1 : -1];
5275 To our knowledge, there is a single compiler that does not support this
5276 trick: the HP C compilers (the real one, not only the ``bundled'') on
5280 $ @kbd{cc -c -Ae +O2 +Onolimit conftest.c}
5281 cc: "conftest.c": error 1879: Variable-length arrays cannot \
5282 have static storage.
5285 Autoconf works around this problem by casting @code{sizeof (int)} to
5286 @code{long} before comparing it.
5289 @node Generic Compiler Characteristics
5290 @subsection Generic Compiler Characteristics
5292 @defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
5293 @acindex{CHECK_SIZEOF}
5294 Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
5295 size in bytes of @var{type}. If @samp{type} is unknown, it gets a size
5296 of 0. If no @var{includes} are specified, the default includes are used
5297 (@pxref{Default Includes}). If you provide @var{include}, be sure to
5298 include @file{stdio.h} which is required for this macro to run.
5300 This macro now works even when cross-compiling. The @var{unused}
5301 argument was used when cross-compiling.
5303 For example, the call
5306 AC_CHECK_SIZEOF(int *)
5310 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
5313 @defmac AC_LANG_WERROR
5314 @acindex{LANG_WERROR}
5315 Normally Autoconf ignores warnings generated by the compiler, linker, and
5316 preprocessor. If this macro is used, warnings will be treated as fatal
5317 errors instead for the current language. This macro is useful when the
5318 results of configuration will be used where warnings are unacceptable; for
5319 instance, if parts of a program are built with the GCC @samp{-Werror}
5320 option. If the whole program will be built using @samp{-Werror} it is
5321 often simpler to put @samp{-Werror} in the compiler flags (@code{CFLAGS}
5326 @subsection C Compiler Characteristics
5328 The following macros provide ways to find and exercise a C Compiler.
5329 There are a few constructs that ought to be avoided, but do not deserve
5330 being checked for, since they can easily be worked around.
5333 @item Don't use lines containing solitary backslashes
5334 They tickle a bug in the HP-UX C compiler (checked on HP-UX 10.20,
5335 11.00, and 11i). Running the compiler on the following source,
5340 * A comment with backslash-newlines in it. %@{ %@} *\
5344 " A string with backslash-newlines in it %@{ %@} \\
5346 char apostrophe = '\\
5357 @error{}cpp: "foo.c", line 13: error 4048: Non-terminating comment at end of file.
5358 @error{}cpp: "foo.c", line 13: error 4033: Missing #endif at end of file.
5362 Removing the lines with solitary backslashes solves the problem.
5364 @item Don't compile several files at once if output matters to you
5365 Some compilers, such as the HP's, reports the name of the file it is
5366 compiling @emph{when} they are several. For instance:
5375 This can cause problems if you observe the output of the compiler to
5376 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
5377 b.o} solves the issue.
5379 @item Don't rely on correct @code{#line} support
5380 On Solaris 8, @command{c89} (Sun WorkShop 6 update 2 C 5.3 Patch
5381 111679-08 2002/05/09)) rejects @code{#line} directives whose line
5382 numbers are greater than 32767. In addition, nothing in @sc{posix}
5383 makes this invalid. That is the reason why Autoconf stopped issuing
5384 @code{#line} directives.
5387 @defmac AC_PROG_CC (@ovar{compiler-search-list})
5391 Determine a C compiler to use. If @code{CC} is not already set in the
5392 environment, check for @code{gcc} and @code{cc}, then for other C
5393 compilers. Set output variable @code{CC} to the name of the compiler
5396 This macro may, however, be invoked with an optional first argument
5397 which, if specified, must be a space separated list of C compilers to
5398 search for. This just gives the user an opportunity to specify an
5399 alternative search list for the C compiler. For example, if you didn't
5400 like the default order, then you could invoke @code{AC_PROG_CC} like
5404 AC_PROG_CC(cl egcs gcc cc)
5407 If the C compiler is not in @acronym{ANSI} C mode by default, try to add an
5408 option to output variable @code{CC} to make it so. This macro tries
5409 various options that select @acronym{ANSI} C on some system or another. It
5410 considers the compiler to be in @acronym{ANSI} C mode if it handles function
5411 prototypes correctly.
5413 After calling this macro you can check whether the C compiler has been
5414 set to accept @acronym{ANSI} C; if not, the shell variable
5415 @code{ac_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
5416 code in @acronym{ANSI} C, you can make an un-@acronym{ANSI}fied copy of it by
5417 using the program @code{ansi2knr}, which comes with Automake. See also
5418 under @code{AC_C_PROTOTYPES} below.
5420 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
5421 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
5422 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
5423 where GCC does not accept @option{-g}), or @option{-g} for other compilers.
5426 @defmac AC_PROG_CC_C_O
5427 @acindex{PROG_CC_C_O}
5428 @cvindex NO_MINUS_C_MINUS_O
5429 If the C compiler does not accept the @option{-c} and @option{-o} options
5430 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
5431 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
5432 the first @code{cc} in the path. The test fails if one fails. This
5433 macro was created for @acronym{GNU} Make to choose the default C compilation
5441 Set output variable @code{CPP} to a command that runs the
5442 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
5443 It is only portable to run @code{CPP} on files with a @file{.c}
5446 Some preprocessors don't indicate missing include files by the error
5447 status. For such preprocessors an internal variable is set that causes
5448 other macros to check the standard error from the preprocessor and
5449 consider the test failed if any warnings have been reported.
5450 For most preprocessors, though, warnings do not cause include-file
5451 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
5454 @defmac AC_PROG_CPP_WERROR
5455 @acindex{PROG_CPP_WERROR}
5457 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
5458 preprocessor as errors even if the preprocessor exit status indicates
5459 success. This is useful for avoiding headers that generate mandatory
5460 warnings, such as deprecation notices.
5464 The following macros check for C compiler or machine architecture
5465 features. To check for characteristics not listed here, use
5466 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
5467 @code{AC_RUN_IFELSE} (@pxref{Run Time}).
5469 @defmac AC_C_BACKSLASH_A
5470 @acindex{HAVE_C_BACKSLASH_A}
5471 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
5475 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
5476 @acindex{C_BIGENDIAN}
5477 @cvindex WORDS_BIGENDIAN
5479 If words are stored with the most significant byte first (like Motorola
5480 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
5481 the least significant byte first (like Intel and VAX CPUs), execute
5482 @var{action-if-false}.
5484 This macro runs a test-case if endianness cannot be determined from the
5485 system header files. When cross-compiling, the test-case is not run but
5486 grep'ed for some magic values. @var{action-if-unknown} is executed if
5487 the latter case fails to determine the byte sex of the host system.
5489 The default for @var{action-if-true} is to define
5490 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
5491 nothing. And finally, the default for @var{action-if-unknown} is to
5492 abort configure and tell the installer which variable he should preset
5493 to bypass this test.
5499 If the C compiler does not fully support the @acronym{ANSI} C qualifier
5500 @code{const}, define @code{const} to be empty. Some C compilers that do
5501 not define @code{__STDC__} do support @code{const}; some compilers that
5502 define @code{__STDC__} do not completely support @code{const}. Programs
5503 can simply use @code{const} as if every C compiler supported it; for
5504 those that don't, the @file{Makefile} or configuration header file will
5507 Occasionally installers use a C++ compiler to compile C code, typically
5508 because they lack a C compiler. This causes problems with @code{const},
5509 because C and C++ treat @code{const} differently. For example:
5516 is valid in C but not in C++. These differences unfortunately cannot be
5517 papered over by defining @code{const} to be empty.
5519 If @command{autoconf} detects this situation, it leaves @code{const} alone,
5520 as this generally yields better results in practice. However, using a
5521 C++ compiler to compile C code is not recommended or supported, and
5522 installers who run into trouble in this area should get a C compiler
5523 like GCC to compile their C code.
5526 @defmac AC_C_RESTRICT
5529 If the C compiler recognizes the @code{restrict} keyword, don't do anything.
5530 If it recognizes only a variant spelling (@code{__restrict},
5531 @code{__restrict__}, or @code{_Restrict}), then define
5532 @code{restrict} to that.
5533 Otherwise, define @code{restrict} to be empty.
5534 Thus, programs may simply use @code{restrict} as if every C compiler
5535 supported it; for those that do not, the @file{Makefile}
5536 or configuration header defines it away.
5538 Although support in C++ for the @code{restrict} keyword is not
5539 required, several C++ compilers do accept the keyword.
5540 This macro works for them, too.
5543 @defmac AC_C_VOLATILE
5544 @acindex{C_VOLATILE}
5546 If the C compiler does not understand the keyword @code{volatile},
5547 define @code{volatile} to be empty. Programs can simply use
5548 @code{volatile} as if every C compiler supported it; for those that do
5549 not, the @file{Makefile} or configuration header will define it as
5552 If the correctness of your program depends on the semantics of
5553 @code{volatile}, simply defining it to be empty does, in a sense, break
5554 your code. However, given that the compiler does not support
5555 @code{volatile}, you are at its mercy anyway. At least your
5556 program will compile, when it wouldn't before.
5558 In general, the @code{volatile} keyword is a feature of @acronym{ANSI} C, so
5559 you might expect that @code{volatile} is available only when
5560 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
5561 support volatile, but does not define @code{__STDC__}.
5567 If the C compiler supports the keyword @code{inline}, do nothing.
5568 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
5569 if it accepts one of those, otherwise define @code{inline} to be empty.
5572 @defmac AC_C_CHAR_UNSIGNED
5573 @acindex{C_CHAR_UNSIGNED}
5574 @cvindex __CHAR_UNSIGNED__
5575 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
5576 unless the C compiler predefines it.
5579 @defmac AC_C_LONG_DOUBLE
5580 @acindex{C_LONG_DOUBLE}
5581 @cvindex HAVE_LONG_DOUBLE
5582 If the C compiler supports a working @code{long double} type with more
5583 range or precision than the @code{double} type, define
5584 @code{HAVE_LONG_DOUBLE}.
5587 @defmac AC_C_STRINGIZE
5588 @acindex{C_STRINGIZE}
5589 @cvindex HAVE_STRINGIZE
5590 If the C preprocessor supports the stringizing operator, define
5591 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
5592 found in macros such as this:
5599 @defmac AC_C_PROTOTYPES
5600 @acindex{C_PROTOTYPES}
5602 @cvindex __PROTOTYPES
5604 If function prototypes are understood by the compiler (as determined by
5605 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
5606 In the case the compiler does not handle
5607 prototypes, you should use @code{ansi2knr}, which comes with the
5608 Automake distribution, to unprotoize function definitions. For
5609 function prototypes, you should first define @code{PARAMS}:
5614 # define PARAMS(protos) protos
5615 # else /* no PROTOTYPES */
5616 # define PARAMS(protos) ()
5617 # endif /* no PROTOTYPES */
5622 then use it this way:
5625 size_t my_strlen PARAMS ((const char *));
5629 This macro also defines @code{__PROTOTYPES}; this is for the benefit of
5630 header files that cannot use macros that infringe on user name space.
5632 @defmac AC_PROG_GCC_TRADITIONAL
5633 @acindex{PROG_GCC_TRADITIONAL}
5635 Add @option{-traditional} to output variable @code{CC} if using the
5636 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
5637 @option{-traditional}. That usually happens when the fixed header files
5638 have not been installed on an old system. Since recent versions of the
5639 @acronym{GNU} C compiler fix the header files automatically when installed,
5640 this is becoming a less prevalent problem.
5645 @subsection C++ Compiler Characteristics
5648 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
5652 Determine a C++ compiler to use. Check if the environment variable
5653 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
5654 variable @code{CXX} to its value.
5656 Otherwise, if the macro is invoked without an argument, then search for
5657 a C++ compiler under the likely names (first @code{g++} and @code{c++}
5658 then other names). If none of those checks succeed, then as a last
5659 resort set @code{CXX} to @code{g++}.
5661 This macro may, however, be invoked with an optional first argument
5662 which, if specified, must be a space separated list of C++ compilers to
5663 search for. This just gives the user an opportunity to specify an
5664 alternative search list for the C++ compiler. For example, if you
5665 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
5669 AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)
5672 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
5673 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
5674 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
5675 systems where G++ does not accept @option{-g}), or @option{-g} for other
5679 @defmac AC_PROG_CXXCPP
5680 @acindex{PROG_CXXCPP}
5682 Set output variable @code{CXXCPP} to a command that runs the C++
5683 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
5684 It is only portable to run @code{CXXCPP} on files with a @file{.c},
5685 @file{.C}, or @file{.cc} extension.
5687 Some preprocessors don't indicate missing include files by the error
5688 status. For such preprocessors an internal variable is set that causes
5689 other macros to check the standard error from the preprocessor and
5690 consider the test failed if any warnings have been reported. However,
5691 it is not known whether such broken preprocessors exist for C++.
5696 @node Fortran Compiler
5697 @subsection Fortran Compiler Characteristics
5701 The Autoconf Fortran support is divided into two categories: legacy
5702 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
5703 The former are intended for traditional Fortran 77 code, and have output
5704 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
5705 are for newer programs that can (or must) compile under the newer
5706 Fortran standards, and have output variables like @code{FC},
5707 @code{FCFLAGS}, and @code{FCLIBS}.
5709 Except for two new macros @code{AC_FC_SRCEXT} and
5710 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
5711 behave almost identically, and so they are documented together in this
5715 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
5719 Determine a Fortran 77 compiler to use. If @code{F77} is not already
5720 set in the environment, then check for @code{g77} and @code{f77}, and
5721 then some other names. Set the output variable @code{F77} to the name
5722 of the compiler found.
5724 This macro may, however, be invoked with an optional first argument
5725 which, if specified, must be a space separated list of Fortran 77
5726 compilers to search for. This just gives the user an opportunity to
5727 specify an alternative search list for the Fortran 77 compiler. For
5728 example, if you didn't like the default order, then you could invoke
5729 @code{AC_PROG_F77} like this:
5732 AC_PROG_F77(fl32 f77 fort77 xlf g77 f90 xlf90)
5735 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
5736 @code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}.
5737 If the output variable @code{FFLAGS} was not already set in the
5738 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
5739 where @code{g77} does not accept @option{-g}). Otherwise, set
5740 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
5743 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
5747 Determine a Fortran compiler to use. If @code{FC} is not already set in
5748 the environment, then @code{dialect} is a hint to indicate what Fortran
5749 dialect to search for; the default is to search for the newest available
5750 dialect. Set the output variable @code{FC} to the name of the compiler
5753 By default, newer dialects are preferred over older dialects, but if
5754 @code{dialect} is specified then older dialects are preferred starting
5755 with the specified dialect. @code{dialect} can currently be one of
5756 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
5757 which compiler @emph{name} to prefer (e.g. @code{f90} or @code{f95}),
5758 and no attempt is made to guarantee that a particular language standard
5759 is actually supported. Thus, it is preferable that you avoid the
5760 @code{dialect} option, and use AC_PROG_FC only for code compatible with
5761 the latest Fortran standard.
5763 This macro may, alternatively, be invoked with an optional first argument
5764 which, if specified, must be a space separated list of Fortran
5765 compilers to search for, just as in @code{AC_PROG_F77}.
5767 If the output variable @code{FCFLAGS} was not already set in the
5768 environment, then set it to @option{-g -02} for GNU @code{g77} (or
5769 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
5770 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
5773 @defmac AC_PROG_F77_C_O
5774 @defmacx AC_PROG_FC_C_O
5775 @acindex{PROG_F77_C_O}
5776 @acindex{PROG_FC_C_O}
5777 @cvindex F77_NO_MINUS_C_MINUS_O
5778 @cvindex FC_NO_MINUS_C_MINUS_O
5779 Test if the Fortran compiler accepts the options @option{-c} and
5780 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
5781 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
5784 The following macros check for Fortran compiler characteristics.
5785 To check for characteristics not listed here, use
5786 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
5787 @code{AC_RUN_IFELSE} (@pxref{Run Time}), making sure to first set the
5788 current language to Fortran 77 or Fortran via @code{AC_LANG(Fortran 77)}
5789 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
5792 @defmac AC_F77_LIBRARY_LDFLAGS
5793 @defmacx AC_FC_LIBRARY_LDFLAGS
5794 @acindex{F77_LIBRARY_LDFLAGS}
5796 @acindex{FC_LIBRARY_LDFLAGS}
5798 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
5799 @dfn{Fortran intrinsic and run-time libraries} that are required to
5800 successfully link a Fortran program or shared library. The output
5801 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
5802 should be include after @code{LIBS} when linking).
5804 This macro is intended to be used in those situations when it is
5805 necessary to mix, e.g., C++ and Fortran source code in a single
5806 program or shared library (@pxref{Mixing Fortran 77 With C and C++,,,
5807 automake, @acronym{GNU} Automake}).
5809 For example, if object files from a C++ and Fortran compiler must be
5810 linked together, then the C++ compiler/linker must be used for linking
5811 (since special C++-ish things need to happen at link time like calling
5812 global constructors, instantiating templates, enabling exception
5815 However, the Fortran intrinsic and run-time libraries must be linked in
5816 as well, but the C++ compiler/linker doesn't know by default how to add
5817 these Fortran 77 libraries. Hence, this macro was created to determine
5818 these Fortran libraries.
5820 The macros @code{AC_F77_DUMMY_MAIN}/@code{AC_FC_DUMMY_MAIN} or
5821 @code{AC_F77_MAIN}/@code{AC_FC_MAIN} will probably also be necessary to
5822 link C/C++ with Fortran; see below.
5825 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
5826 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
5827 @acindex{F77_DUMMY_MAIN}
5828 @cvindex F77_DUMMY_MAIN
5829 With many compilers, the Fortran libraries detected by
5830 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
5831 their own @code{main} entry function that initializes things like
5832 Fortran I/O, and which then calls a user-provided entry function named
5833 (say) @code{MAIN__} to run the user's program. The
5834 @code{AC_F77_DUMMY_MAIN}/@code{AC_FC_DUMMY_MAIN} or
5835 @code{AC_F77_MAIN}/@code{AC_FC_MAIN} macro figures out how to deal with
5838 When using Fortran for purely numerical functions (no I/O, etc.)@: often
5839 one prefers to provide one's own @code{main} and skip the Fortran
5840 library initializations. In this case, however, one may still need to
5841 provide a dummy @code{MAIN__} routine in order to prevent linking errors
5842 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
5843 detects whether any such routine is @emph{required} for linking, and
5844 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
5845 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
5846 was found, and @code{none} when no such dummy main is needed.
5848 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
5849 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
5850 @emph{if} it is required. @ovar{action-if-not-found} defaults to
5851 exiting with an error.
5853 In order to link with Fortran routines, the user's C/C++ program should
5854 then include the following code to define the dummy main if it is
5858 #ifdef F77_DUMMY_MAIN
5862 int F77_DUMMY_MAIN() @{ return 1; @}
5866 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
5868 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
5869 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
5870 explicitly unless one wants to change the default actions.
5879 As discussed above, many Fortran libraries allow you to provide an entry
5880 point called (say) @code{MAIN__} instead of the usual @code{main}, which
5881 is then called by a @code{main} function in the Fortran libraries that
5882 initializes things like Fortran I/O@. The
5883 @code{AC_F77_MAIN}/@code{AC_FC_MAIN} macro detects whether it is
5884 @emph{possible} to utilize such an alternate main function, and defines
5885 @code{F77_MAIN}/@code{FC_MAIN} to the name of the function. (If no
5886 alternate main function name is found, @code{F77_MAIN}/@code{FC_MAIN} is
5887 simply defined to @code{main}.)
5889 Thus, when calling Fortran routines from C that perform things like I/O,
5890 one should use this macro and name the "main" function
5891 @code{F77_MAIN}/@code{FC_MAIN} instead of @code{main}.
5894 @defmac AC_F77_WRAPPERS
5895 @defmacx AC_FC_WRAPPERS
5896 @acindex{F77_WRAPPERS}
5899 @acindex{FC_WRAPPERS}
5902 Defines C macros @code{F77_FUNC(name,NAME)}/@code{FC_FUNC(name,NAME)}
5903 and @code{F77_FUNC_(name,NAME)}/@code{FC_FUNC_(name,NAME)} to properly
5904 mangle the names of C/C++ identifiers, and identifiers with underscores,
5905 respectively, so that they match the name-mangling scheme used by the
5908 Fortran is case-insensitive, and in order to achieve this the Fortran
5909 compiler converts all identifiers into a canonical case and format. To
5910 call a Fortran subroutine from C or to write a C function that is
5911 callable from Fortran, the C program must explicitly use identifiers in
5912 the format expected by the Fortran compiler. In order to do this, one
5913 simply wraps all C identifiers in one of the macros provided by
5914 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
5915 you have the following Fortran 77 subroutine:
5918 subroutine foobar(x,y)
5919 double precision x, y
5925 You would then declare its prototype in C or C++ as:
5928 #define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
5930 extern "C" /* prevent C++ name mangling */
5932 void FOOBAR_F77(double *x, double *y);
5935 Note that we pass both the lowercase and uppercase versions of the
5936 function name to @code{F77_FUNC} so that it can select the right one.
5937 Note also that all parameters to Fortran 77 routines are passed as
5938 pointers (@pxref{Mixing Fortran 77 With C and C++,,, automake, @acronym{GNU}
5941 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
5943 Although Autoconf tries to be intelligent about detecting the
5944 name-mangling scheme of the Fortran compiler, there may be Fortran
5945 compilers that it doesn't support yet. In this case, the above code
5946 will generate a compile-time error, but some other behavior
5947 (e.g., disabling Fortran-related features) can be induced by checking
5948 whether the @code{F77_FUNC}/@code{FC_FUNC} macro is defined.
5950 Now, to call that routine from a C program, we would do something like:
5954 double x = 2.7183, y;
5959 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
5960 you should use @code{F77_FUNC_}/@code{FC_FUNC_} instead of
5961 @code{F77_FUNC}/@code{FC_FUNC} (with the same arguments). This is
5962 because some Fortran compilers mangle names differently if they contain
5966 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
5967 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
5970 Given an identifier @var{name}, set the shell variable @var{shellvar} to
5971 hold the mangled version @var{name} according to the rules of the
5972 Fortran linker (see also @code{AC_F77_WRAPPERS} or
5973 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
5974 supplied, the shell variable will be simply @var{name}. The purpose of
5975 this macro is to give the caller a way to access the name-mangling
5976 information other than through the C preprocessor as above, for example,
5977 to call Fortran routines from some language other than C/C++.
5980 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
5982 By default, the @code{FC} macros perform their tests using a @file{.f}
5983 extension for source-code files. Some compilers, however, only enable
5984 newer language features for appropriately named files, e.g. Fortran 90
5985 features only for @file{.f90} files. On the other hand, some other
5986 compilers expect all source files to end in @file{.f} and require
5987 special flags to support other filename extensions. The
5988 @code{AC_FC_SRCEXT} macro deals with both of these issues.
5990 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
5991 ending with the extension .@var{ext} (i.e. @var{ext} does @emph{not}
5992 contain the dot). If any special compiler flags are needed for this, it
5993 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
5994 extension and these flags are then used for all subsequent @code{FC} tests
5995 (until @code{AC_FC_SRCEXT} is called again).
5997 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
5998 @file{.f90} extension in future tests, and it would set a
5999 @code{FCFLAGS_f90} output variable with any extra flags that are needed
6000 to compile such files.
6002 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
6003 @code{FCFLAGS}, for two reasons based on the limitations of some
6004 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
6005 time, so files with different extensions must be compiled separately.
6006 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
6007 the source-code filename when compiling. So, continuing the example
6008 above, you might compile a @file{foo.f90} file in your Makefile with the
6013 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) foo.f90
6016 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
6017 extension, it calls @ovar{action-if-success} (defaults to nothing). If
6018 it fails, and cannot find a way to make the @code{FC} compiler accept such
6019 files, it calls @ovar{action-if-failure} (defaults to exiting with an
6024 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
6025 @acindex{FC_FREEFORM}
6027 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
6028 (@code{$FC}) allows free-format source code (as opposed to the older
6029 fixed-format style from Fortran 77). If necessary, it may add some
6030 additional flags to @code{FCFLAGS}.
6032 This macro is most important if you are using the default @file{.f}
6033 extension, since many compilers interpret this extension as indicating
6034 fixed-format source unless an additional flag is supplied. If you
6035 specify a different extension with @code{AC_FC_SRCEXT}, such as
6036 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} will ordinarily
6037 succeed without modifying @code{FCFLAGS}.
6039 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
6040 calls @ovar{action-if-success} (defaults to nothing). If it fails, it
6041 calls @ovar{action-if-failure} (defaults to exiting with an error
6045 @node System Services
6046 @section System Services
6048 The following macros check for operating system services or capabilities.
6052 @cindex X Window System
6053 Try to locate the X Window System include files and libraries. If the
6054 user gave the command line options @option{--x-includes=@var{dir}} and
6055 @option{--x-libraries=@var{dir}}, use those directories. If either or
6056 both were not given, get the missing values by running @code{xmkmf} on a
6057 trivial @file{Imakefile} and examining the @file{Makefile} that it
6058 produces. If that fails (such as if @code{xmkmf} is not present), look
6059 for the files in several directories where they often reside. If either
6060 method is successful, set the shell variables @code{x_includes} and
6061 @code{x_libraries} to their locations, unless they are in directories
6062 the compiler searches by default.
6064 If both methods fail, or the user gave the command line option
6065 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
6066 otherwise set it to the empty string.
6069 @defmac AC_PATH_XTRA
6073 @ovindex X_EXTRA_LIBS
6075 @cvindex X_DISPLAY_MISSING
6076 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
6077 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
6078 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
6081 This macro also checks for special libraries that some systems need in
6082 order to compile X programs. It adds any that the system needs to
6083 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
6084 libraries that need to be linked with before @option{-lX11}, and adds
6085 any found to the output variable @code{X_PRE_LIBS}.
6087 @c This is an incomplete kludge. Make a real way to do it.
6088 @c If you need to check for other X functions or libraries yourself, then
6089 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
6090 @c @code{LIBS} temporarily, like this: (FIXME - add example)
6093 @defmac AC_SYS_INTERPRETER
6094 @acindex{SYS_INTERPRETER}
6095 Check whether the system supports starting scripts with a line of the
6096 form @samp{#! /bin/csh} to select the interpreter to use for the script.
6097 After running this macro, shell code in @file{configure.ac} can check
6098 the shell variable @code{interpval}; it will be set to @samp{yes}
6099 if the system supports @samp{#!}, @samp{no} if not.
6102 @defmac AC_SYS_LARGEFILE
6103 @acindex{SYS_LARGEFILE}
6104 @cvindex _FILE_OFFSET_BITS
6105 @cvindex _LARGE_FILES
6107 @cindex Large file support
6110 @href{http://www.unix-systems.org/version2/whatsnew/lfs20mar.html,
6111 large-file support}. On some hosts, one must use special compiler
6112 options to build programs that can access large files. Append any such
6113 options to the output variable @code{CC}. Define
6114 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
6116 Large-file support can be disabled by configuring with the
6117 @option{--disable-largefile} option.
6119 If you use this macro, check that your program works even when
6120 @code{off_t} is longer than @code{long}, since this is common when
6121 large-file support is enabled. For example, it is not correct to print
6122 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
6125 The LFS introduced the @code{fseeko} and @code{ftello} functions to
6126 replace their C counterparts @code{fseek} and @code{ftell} that do not
6127 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
6128 prototypes available when using them and large-file support is
6132 @defmac AC_SYS_LONG_FILE_NAMES
6133 @acindex{SYS_LONG_FILE_NAMES}
6134 @cvindex HAVE_LONG_FILE_NAMES
6135 If the system supports file names longer than 14 characters, define
6136 @code{HAVE_LONG_FILE_NAMES}.
6139 @defmac AC_SYS_POSIX_TERMIOS
6140 @acindex{SYS_POSIX_TERMIOS}
6141 @cindex POSIX termios headers
6142 @cindex termios POSIX headers
6143 Check to see if the POSIX termios headers and functions are available on the
6144 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
6145 @samp{yes}. If not, set the variable to @samp{no}.
6149 @section UNIX Variants
6151 The following macros check for certain operating systems that need
6152 special treatment for some programs, due to exceptional oddities in
6153 their header files or libraries. These macros are warts; they will be
6154 replaced by a more systematic approach, based on the functions they make
6155 available or the environments they provide.
6159 @cvindex _ALL_SOURCE
6160 If on @acronym{AIX}, define @code{_ALL_SOURCE}. Allows the use of some @acronym{BSD}
6161 functions. Should be called before any macros that run the C compiler.
6164 @defmac AC_GNU_SOURCE
6165 @acindex{GNU_SOURCE}
6166 @cvindex _GNU_SOURCE
6167 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
6168 Allows the use of some @acronym{GNU} functions. Should be called
6169 before any macros that run the C compiler.
6172 @defmac AC_ISC_POSIX
6175 For @sc{interactive unix} (@acronym{ISC}), add @option{-lcposix} to output
6176 variable @code{LIBS} if necessary for @acronym{POSIX} facilities. Call this
6177 after @code{AC_PROG_CC} and before any other macros that use @acronym{POSIX}
6178 interfaces. @sc{interactive unix} is no longer sold, and Sun says that
6179 they will drop support for it on 2006-07-23, so this macro is becoming
6186 @cvindex _POSIX_SOURCE
6187 @cvindex _POSIX_1_SOURCE
6188 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
6189 @code{_POSIX_1_SOURCE} to be 2. This allows the use of @acronym{POSIX}
6190 facilities. Should be called before any macros that run the C compiler.
6196 @c ========================================================= Writing Tests
6199 @chapter Writing Tests
6201 If the existing feature tests don't do something you need, you have to
6202 write new ones. These macros are the building blocks. They provide
6203 ways for other macros to check whether various kinds of features are
6204 available and report the results.
6206 This chapter contains some suggestions and some of the reasons why the
6207 existing tests are written the way they are. You can also learn a lot
6208 about how to write Autoconf tests by looking at the existing ones. If
6209 something goes wrong in one or more of the Autoconf tests, this
6210 information can help you understand the assumptions behind them, which
6211 might help you figure out how to best solve the problem.
6213 These macros check the output of the compiler system of the current
6214 language (@pxref{Language Choice}). They do not cache the results of
6215 their tests for future use (@pxref{Caching Results}), because they don't
6216 know enough about the information they are checking for to generate a
6217 cache variable name. They also do not print any messages, for the same
6218 reason. The checks for particular kinds of features call these macros
6219 and do cache their results and print messages about what they're
6222 When you write a feature test that could be applicable to more than one
6223 software package, the best thing to do is encapsulate it in a new macro.
6224 @xref{Writing Autoconf Macros}, for how to do that.
6227 * Language Choice:: Selecting which language to use for testing
6228 * Writing Test Programs:: Forging source files for compilers
6229 * Running the Preprocessor:: Detecting preprocessor symbols
6230 * Running the Compiler:: Detecting language or header features
6231 * Running the Linker:: Detecting library features
6232 * Run Time:: Testing for run-time features
6233 * Systemology:: A zoology of operating systems
6234 * Multiple Cases:: Tests for several possible values
6237 @node Language Choice
6238 @section Language Choice
6241 Autoconf-generated @command{configure} scripts check for the C compiler and
6242 its features by default. Packages that use other programming languages
6243 (maybe more than one, e.g., C and C++) need to test features of the
6244 compilers for the respective languages. The following macros determine
6245 which programming language is used in the subsequent tests in
6246 @file{configure.ac}.
6248 @defmac AC_LANG (@var{language})
6249 Do compilation tests using the compiler, preprocessor, and file
6250 extensions for the specified @var{language}.
6252 Supported languages are:
6256 Do compilation tests using @code{CC} and @code{CPP} and use extension
6257 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
6258 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
6261 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
6262 extension @file{.C} for test programs. Use compilation flags:
6263 @code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and
6264 @code{CXXFLAGS} with @code{CXX}.
6267 Do compilation tests using @code{F77} and use extension @file{.f} for
6268 test programs. Use compilation flags: @code{FFLAGS}.
6271 Do compilation tests using @code{FC} and use extension @file{.f} (or
6272 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
6273 compilation flags: @code{FCFLAGS}.
6277 @defmac AC_LANG_PUSH (@var{language})
6279 Remember the current language (as set by @code{AC_LANG}) on a stack, and
6280 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
6281 in macros that need to temporarily switch to a particular language.
6284 @defmac AC_LANG_POP (@ovar{language})
6286 Select the language that is saved on the top of the stack, as set by
6287 @code{AC_LANG_PUSH}, and remove it from the stack.
6289 If given, @var{language} specifies the language we just @emph{quit}. It
6290 is a good idea to specify it when it's known (which should be the
6291 case@dots{}), since Autoconf will detect inconsistencies.
6294 AC_LANG_PUSH(Fortran 77)
6295 # Perform some tests on Fortran 77.
6297 AC_LANG_POP(Fortran 77)
6301 @defmac AC_LANG_ASSERT (@var{language})
6302 @acindex{LANG_ASSERT} Check statically that the current language is
6303 @var{language}. You should use this in your language specific macros
6304 to avoid that they be called with an inappropriate language.
6306 This macro runs only at @command{autoconf} time, and incurs no cost at
6307 @command{configure} time. Sadly enough and because Autoconf is a two
6308 layer language @footnote{Because M4 is not aware of Sh code,
6309 especially conditionals, some optimizations that look nice statically
6310 may produce incorrect results at runtime.}, the macros
6311 @code{AC_LANG_PUSH}/@code{AC_LANG_POP} cannot be ``optimizing'',
6312 therefore as much as possible you ought to avoid using them to wrap
6313 your code, rather, require from the user to run the macro with a
6314 correct current language, and check it with @code{AC_LANG_ASSERT}.
6315 And anyway, that may help the user understand she is running a Fortran
6316 macro while expecting a result about her Fortran 77 compiler...
6320 @defmac AC_REQUIRE_CPP
6321 @acindex{REQUIRE_CPP}
6322 Ensure that whichever preprocessor would currently be used for tests has
6323 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
6324 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
6325 depending on which language is current.
6329 @node Writing Test Programs
6330 @section Writing Test Programs
6332 Autoconf tests follow is common scheme: feeding some program with some
6333 input, and most of the time, feeding a compiler with some source file.
6334 This section is dedicated to these source samples.
6337 * Guidelines:: General rules for writing test programs
6338 * Test Functions:: Avoiding pitfalls in test programs
6339 * Generating Sources:: Source program boilerplate
6343 @subsection Guidelines for Test Programs
6345 The most important rule to follow when writing testing samples is:
6347 @center @emph{Look for realism.}
6349 This motto means that testing samples must be written with the same
6350 strictness as real programs are written. In particular, you should
6351 avoid ``shortcuts'' and simplifications.
6353 Don't just play with the preprocessor if you want to prepare a
6354 compilation. For instance, using @command{cpp} to check if a header is
6355 functional might let your @command{configure} accept a header which will
6356 cause some @emph{compiler} error. Do not hesitate checking header with
6357 other headers included before, especially required headers.
6359 Make sure the symbols you use are properly defined, i.e., refrain for
6360 simply declaring a function yourself instead of including the proper
6363 Test programs should not write anything to the standard output. They
6364 should return 0 if the test succeeds, nonzero otherwise, so that success
6365 can be distinguished easily from a core dump or other failure;
6366 segmentation violations and other failures produce a nonzero exit
6367 status. Test programs should @code{exit}, not @code{return}, from
6368 @code{main}, because on some systems (old Suns, at least) the argument
6369 to @code{return} in @code{main} is ignored.
6371 Test programs can use @code{#if} or @code{#ifdef} to check the values of
6372 preprocessor macros defined by tests that have already run. For
6373 example, if you call @code{AC_HEADER_STDC}, then later on in
6374 @file{configure.ac} you can have a test program that includes an
6375 @acronym{ANSI} C header file conditionally:
6380 # include <stdlib.h>
6385 If a test program needs to use or create a data file, give it a name
6386 that starts with @file{conftest}, such as @file{conftest.data}. The
6387 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
6388 after running test programs and if the script is interrupted.
6390 @node Test Functions
6391 @subsection Test Functions
6393 Function declarations in test programs should have a prototype
6394 conditionalized for C++. In practice, though, test programs rarely need
6395 functions that take arguments.
6405 Functions that test programs declare should also be conditionalized for
6406 C++, which requires @samp{extern "C"} prototypes. Make sure to not
6407 include any header files containing clashing prototypes.
6411 extern "C" void *malloc (size_t);
6417 If a test program calls a function with invalid parameters (just to see
6418 whether it exists), organize the program to ensure that it never invokes
6419 that function. You can do this by calling it in another function that is
6420 never invoked. You can't do it by putting it after a call to
6421 @code{exit}, because GCC version 2 knows that @code{exit} never returns
6422 and optimizes out any code that follows it in the same block.
6424 If you include any header files, be sure to call the functions
6425 relevant to them with the correct number of arguments, even if they are
6426 just 0, to avoid compilation errors due to prototypes. GCC version 2
6427 has internal prototypes for several functions that it automatically
6428 inlines; for example, @code{memcpy}. To avoid errors when checking for
6429 them, either pass them the correct number of arguments or redeclare them
6430 with a different return type (such as @code{char}).
6433 @node Generating Sources
6434 @subsection Generating Sources
6436 Autoconf provides a set of macros that can be used to generate test
6437 source files. They are written to be language generic, i.e., they
6438 actually depend on the current language (@pxref{Language Choice}) to
6439 ``format'' the output properly.
6442 @defmac AC_LANG_CONFTEST (@var{source})
6443 @acindex{LANG_CONFTEST}
6444 Save the @var{source} text in the current test source file:
6445 @file{conftest.@var{extension}} where the @var{extension} depends on the
6448 Note that the @var{source} is evaluated exactly once, like regular
6449 Autoconf macro arguments, and therefore (i) you may pass a macro
6450 invocation, (ii) if not, be sure to double quote if needed.
6453 @defmac AC_LANG_SOURCE (@var{source})
6454 @acindex{LANG_SOURCE}
6455 Expands into the @var{source}, with the definition of
6456 all the @code{AC_DEFINE} performed so far.
6459 For instance executing (observe the double quotation!):
6462 AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
6463 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
6465 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
6466 gcc -E -dD -o - conftest.c
6478 #define PACKAGE_NAME "Autoconf Documentation"
6479 #define PACKAGE_TARNAME "autoconf-documentation"
6480 #define PACKAGE_VERSION "@value{VERSION}"
6481 #define PACKAGE_STRING "Autoconf Documentation @value{VERSION}"
6482 #define PACKAGE_BUGREPORT "bug-autoconf@@gnu.org"
6483 #define HELLO_WORLD "Hello, World\n"
6484 # 1170 "configure" 2
6486 const char hw[] = "Hello, World\n";
6489 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
6490 @acindex{LANG_PROGRAM}
6491 Expands into a source file which consists of the @var{prologue}, and
6492 then @var{body} as body of the main function (e.g., @code{main} in
6493 C). Since it uses @code{AC_LANG_SOURCE}, the feature of the latter are
6500 AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
6501 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
6503 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
6504 [[fputs (hw, stdout);]])])
6505 gcc -E -dD -o - conftest.c
6517 #define PACKAGE_NAME "Autoconf Documentation"
6518 #define PACKAGE_TARNAME "autoconf-documentation"
6519 #define PACKAGE_VERSION "@value{VERSION}"
6520 #define PACKAGE_STRING "Autoconf Documentation @value{VERSION}"
6521 #define PACKAGE_BUGREPORT "bug-autoconf@@gnu.org"
6522 #define HELLO_WORLD "Hello, World\n"
6523 # 1170 "configure" 2
6525 const char hw[] = "Hello, World\n";
6536 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
6538 Expands into a source file which consists of the @var{prologue}, and
6539 then a call to the @var{function} as body of the main function (e.g.,
6540 @code{main} in C). Since it uses @code{AC_LANG_PROGRAMS}, the feature
6541 of the latter are available.
6543 This function will probably be replaced in the future by a version
6544 which would enable specifying the arguments. The use of this macro is
6545 not encouraged, as it violates strongly the typing system.
6549 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
6550 @acindex{LANG_FUNC_LINK_TRY}
6551 Expands into a source file which consists of a pseudo use of the
6552 @var{function} as body of the main function (e.g., @code{main} in C): a
6553 simple (function pointer) assignment. Since it uses
6554 @code{AC_LANG_PROGRAMS}, the feature of the latter are available.
6556 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
6557 It is considered to be severely broken, and in the future will be
6558 removed in favor of actual function calls (with properly typed
6562 @node Running the Preprocessor
6563 @section Running the Preprocessor
6565 Sometimes one might need to run the preprocessor on some source file.
6566 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
6567 your project, not merely run the preprocessor on it; therefore you
6568 certainly want to run the compiler, not the preprocessor. Resist the
6569 temptation of following the easiest path.
6571 Nevertheless, if you need to run the preprocessor, then use
6572 @code{AC_PREPROC_IFELSE}.
6574 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
6575 @acindex{PREPROC_IFELSE}
6576 Run the preprocessor of the current language (@pxref{Language Choice})
6577 on the @var{input}, run the shell commands @var{action-if-true} on
6578 success, @var{action-if-false} otherwise. The @var{input} can be made
6579 by @code{AC_LANG_PROGRAM} and friends.
6581 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
6582 @option{-g}, @option{-O}, etc.@: are not valid options to many C
6585 It is customary to report unexpected failures with
6586 @code{AC_MSG_FAILURE}.
6592 AC_INIT(Autoconf Documentation, @value{VERSION}, bug-autoconf@@gnu.org)
6593 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"])
6595 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
6596 [[fputs (hw, stdout);]])],
6597 [AC_MSG_RESULT([OK])],
6598 [AC_MSG_FAILURE([unexpected preprocessor failure])])
6605 checking for gcc... gcc
6606 checking for C compiler default output... a.out
6607 checking whether the C compiler works... yes
6608 checking whether we are cross compiling... no
6609 checking for suffix of executables...
6610 checking for suffix of object files... o
6611 checking whether we are using the GNU C compiler... yes
6612 checking whether gcc accepts -g... yes
6613 checking for gcc option to accept ANSI C... none needed
6614 checking how to run the C preprocessor... gcc -E
6620 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
6621 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
6622 it impossible to use it to elaborate sources. You are encouraged to
6623 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
6624 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
6625 to run the @emph{preprocessor} and not the compiler?
6627 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
6628 @acindex{EGREP_HEADER}
6629 If the output of running the preprocessor on the system header file
6630 @var{header-file} matches the extended regular expression
6631 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
6632 execute @var{action-if-not-found}.
6635 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
6637 @var{program} is the text of a C or C++ program, on which shell
6638 variable, back quote, and backslash substitutions are performed. If the
6639 output of running the preprocessor on @var{program} matches the
6640 extended regular expression @var{pattern}, execute shell commands
6641 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
6646 @node Running the Compiler
6647 @section Running the Compiler
6649 To check for a syntax feature of the current language's (@pxref{Language
6650 Choice}) compiler, such as whether it recognizes a certain keyword, or
6651 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
6652 to compile a small program that uses that feature.
6654 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found})
6655 @acindex{COMPILE_IFELSE}
6656 Run the compiler and compilation flags of the current language
6657 (@pxref{Language Choice}) on the @var{input}, run the shell commands
6658 @var{action-if-true} on success, @var{action-if-false} otherwise. The
6659 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
6661 It is customary to report unexpected failures with
6662 @code{AC_MSG_FAILURE}. This macro does not try to link; use
6663 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
6667 @node Running the Linker
6668 @section Running the Linker
6670 To check for a library, a function, or a global variable, Autoconf
6671 @command{configure} scripts try to compile and link a small program that
6672 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
6673 @code{ar} on the C library to try to figure out which functions are
6674 available. Trying to link with the function is usually a more reliable
6675 approach because it avoids dealing with the variations in the options
6676 and output formats of @code{nm} and @code{ar} and in the location of the
6677 standard libraries. It also allows configuring for cross-compilation or
6678 checking a function's run-time behavior if needed. On the other hand,
6679 it can be slower than scanning the libraries once, but accuracy is more
6680 important than speed.
6682 @code{AC_LINK_IFELSE} is used to compile test programs to test for
6683 functions and global variables. It is also used by @code{AC_CHECK_LIB}
6684 to check for libraries (@pxref{Libraries}), by adding the library being
6685 checked for to @code{LIBS} temporarily and trying to link a small
6689 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found})
6690 @acindex{LINK_IFELSE}
6691 Run the compiler (and compilation flags) and the linker of the current
6692 language (@pxref{Language Choice}) on the @var{input}, run the shell
6693 commands @var{action-if-true} on success, @var{action-if-false}
6694 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
6697 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
6698 current compilation flags.
6700 It is customary to report unexpected failures with
6701 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
6702 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Run Time}).
6708 @section Checking Run Time Behavior
6710 Sometimes you need to find out how a system performs at run time, such
6711 as whether a given function has a certain capability or bug. If you
6712 can, make such checks when your program runs instead of when it is
6713 configured. You can check for things like the machine's endianness when
6714 your program initializes itself.
6716 If you really need to test for a run-time behavior while configuring,
6717 you can write a test program to determine the result, and compile and
6718 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
6719 possible, because this prevents people from configuring your package for
6722 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{action-if-cross-compiling})
6723 @acindex{RUN_IFELSE}
6724 If @var{program} compiles and links successfully and returns an exit
6725 status of 0 when executed, run shell commands @var{action-if-true}.
6726 Otherwise, run shell commands @var{action-if-false}.
6728 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
6729 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
6730 compilation flags of the current language (@pxref{Language Choice}).
6732 If the compiler being used does not produce executables that run on the
6733 system where @command{configure} is being run, then the test program is
6734 not run. If the optional shell commands @var{action-if-cross-compiling}
6735 are given, they are run instead. Otherwise, @command{configure} prints
6736 an error message and exits.
6738 In the @var{action-if-false} section, the exit status of the program is
6739 available in the shell variable @samp{$?}, but be very careful to limit
6740 yourself to positive values smaller than 127; bigger values should be
6741 saved into a file by the @var{program}. Note also that you have simply
6742 no guarantee that this exit status is issued by the @var{program}, or by
6743 the failure of its compilation. In other words, use this feature if
6744 sadist only, it was reestablished because the Autoconf maintainers grew
6745 tired of receiving ``bug reports''.
6747 It is customary to report unexpected failures with
6748 @code{AC_MSG_FAILURE}.
6751 Try to provide a pessimistic default value to use when cross-compiling
6752 makes run-time tests impossible. You do this by passing the optional
6753 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
6754 warning message when creating @command{configure} each time it
6755 encounters a call to @code{AC_RUN_IFELSE} with no
6756 @var{action-if-cross-compiling} argument given. You may ignore the
6757 warning, though users will not be able to configure your package for
6758 cross-compiling. A few of the macros distributed with Autoconf produce
6759 this warning message.
6761 To configure for cross-compiling you can also choose a value for those
6762 parameters based on the canonical system name (@pxref{Manual
6763 Configuration}). Alternatively, set up a test results cache file with
6764 the correct values for the host system (@pxref{Caching Results}).
6766 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
6767 in other macros, including a few of the ones that come with Autoconf,
6768 you can test whether the shell variable @code{cross_compiling} is set to
6769 @samp{yes}, and then use an alternate method to get the results instead
6770 of calling the macros.
6774 @section Systemology
6777 This section aims at presenting some systems and pointers to
6778 documentation. It may help you addressing particular problems reported
6781 The @href{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
6782 contains a lot of interesting crossed information on various Unices.
6787 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
6788 case-preserving, but case insensitive. This can cause nasty problems,
6789 since for instance the installation attempt for a package having an
6790 @file{INSTALL} file can result in @samp{make install} report that
6791 nothing was to be done!
6793 That's all dependent on whether the file system is a UFS (case
6794 sensitive) or HFS+ (case preserving). By default Apple wants you to
6795 install the OS on HFS+. Unfortunately, there are some pieces of
6796 software which really need to be built on UFS@. We may want to rebuild
6797 Darwin to have both UFS and HFS+ available (and put the /local/build
6800 @item @acronym{QNX} 4.25
6801 @cindex @acronym{QNX} 4.25
6802 @c FIXME: Please, if you feel like writing something more precise,
6803 @c it'd be great. In particular, I can't understand the difference with
6805 @acronym{QNX} is a realtime operating system running on Intel architecture
6806 meant to be scalable from the small embedded systems to the hundred
6807 processor super-computer. It claims to be @acronym{POSIX} certified. More
6808 information is available on the @href{www.qnx.com, @acronym{QNX} home page},
6809 including the @href{http://support.qnx.com/support/docs/qnx4/, @acronym{QNX}
6814 The @href{http://www.tru64unix.compaq.com/docs/base_doc/DOCUMENTATION/,
6815 documentation of several versions of Tru64} is available in different
6818 @item Unix version 7
6819 @cindex Unix version 7
6821 Documentation is available in the
6822 @href{http://plan9.bell-labs.com/7thEdMan/index.html, V7 Manual}.
6826 @node Multiple Cases
6827 @section Multiple Cases
6829 Some operations are accomplished in several possible ways, depending on
6830 the @sc{unix} variant. Checking for them essentially requires a ``case
6831 statement''. Autoconf does not directly provide one; however, it is
6832 easy to simulate by using a shell variable to keep track of whether a
6833 way to perform the operation has been found yet.
6835 Here is an example that uses the shell variable @code{fstype} to keep
6836 track of whether the remaining cases need to be checked.
6840 AC_MSG_CHECKING([how to get file system type])
6842 # The order of these tests is important.
6843 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
6844 #include <sys/fstyp.h>]])],
6845 [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
6846 if test $fstype = no; then
6847 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
6848 #include <sys/fstyp.h>]])],
6849 [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
6851 if test $fstype = no; then
6852 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
6853 #include <sys/vmount.h>]])]),
6854 [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
6856 # (more cases omitted here)
6857 AC_MSG_RESULT([$fstype])
6861 @c ====================================================== Results of Tests.
6864 @chapter Results of Tests
6866 Once @command{configure} has determined whether a feature exists, what can
6867 it do to record that information? There are four sorts of things it can
6868 do: define a C preprocessor symbol, set a variable in the output files,
6869 save the result in a cache file for future @command{configure} runs, and
6870 print a message letting the user know the result of the test.
6873 * Defining Symbols:: Defining C preprocessor symbols
6874 * Setting Output Variables:: Replacing variables in output files
6875 * Caching Results:: Speeding up subsequent @command{configure} runs
6876 * Printing Messages:: Notifying @command{configure} users
6879 @node Defining Symbols
6880 @section Defining C Preprocessor Symbols
6882 A common action to take in response to a feature test is to define a C
6883 preprocessor symbol indicating the results of the test. That is done by
6884 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
6886 By default, @code{AC_OUTPUT} places the symbols defined by these macros
6887 into the output variable @code{DEFS}, which contains an option
6888 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
6889 Autoconf version 1, there is no variable @code{DEFS} defined while
6890 @command{configure} is running. To check whether Autoconf macros have
6891 already defined a certain C preprocessor symbol, test the value of the
6892 appropriate cache variable, as in this example:
6895 AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
6896 if test "$ac_cv_func_vprintf" != yes; then
6897 AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
6901 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
6902 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
6903 correct values into @code{#define} statements in a template file.
6904 @xref{Configuration Headers}, for more information about this kind of
6907 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
6908 @defmacx AC_DEFINE (@var{variable})
6910 Define the C preprocessor variable @var{variable} to @var{value} (verbatim).
6911 @var{value} should not contain literal newlines, and if you are not
6912 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
6913 characters, as @command{make} tends to eat them. To use a shell variable
6914 (which you need to do in order to define a value containing the M4 quote
6915 characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead.
6916 @var{description} is only useful if you are using
6917 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
6918 the generated @file{config.h.in} as the comment before the macro define.
6919 The following example defines the C preprocessor variable
6920 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
6923 AC_DEFINE(EQUATION, "$a > $b")
6926 If neither @var{value} nor @var{description} are given, then
6927 @var{value} defaults to 1 instead of to the empty string. This is for
6928 backwards compatibility with older versions of Autoconf, but this usage
6929 is obsolescent and may be withdrawn in future versions of Autoconf.
6932 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
6933 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
6934 @acindex{DEFINE_UNQUOTED}
6935 Like @code{AC_DEFINE}, but three shell expansions are
6936 performed---once---on @var{variable} and @var{value}: variable expansion
6937 (@samp{$}), command substitution (@samp{`}), and backslash escaping
6938 (@samp{\}). Single and double quote characters in the value have no
6939 special meaning. Use this macro instead of @code{AC_DEFINE} when
6940 @var{variable} or @var{value} is a shell variable. Examples:
6943 AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
6944 AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
6945 AC_DEFINE_UNQUOTED($ac_tr_hdr)
6949 Due to a syntactical bizarreness of the Bourne shell, do not use
6950 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
6951 calls from other macro calls or shell code; that can cause syntax errors
6952 in the resulting @command{configure} script. Use either spaces or
6953 newlines. That is, do this:
6956 AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
6963 AC_CHECK_HEADER(elf.h,
6965 LIBS="$LIBS -lelf"])
6972 AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])
6975 @node Setting Output Variables
6976 @section Setting Output Variables
6977 @cindex Output variables
6979 Another way to record the results of tests is to set @dfn{output
6980 variables}, which are shell variables whose values are substituted into
6981 files that @command{configure} outputs. The two macros below create new
6982 output variables. @xref{Preset Output Variables}, for a list of output
6983 variables that are always available.
6985 @defmac AC_SUBST (@var{variable}, @ovar{value})
6987 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
6988 substitute the variable @var{variable} into output files (typically one
6989 or more @file{Makefile}s). This means that @code{AC_OUTPUT} will
6990 replace instances of @samp{@@@var{variable}@@} in input files with the
6991 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
6992 is called. This value of @var{variable} should not contain literal
6995 If @var{value} is given, in addition assign it to @var{variable}.
6998 @defmac AC_SUBST_FILE (@var{variable})
6999 @acindex{SUBST_FILE}
7000 Another way to create an output variable from a shell variable. Make
7001 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
7002 named by shell variable @var{variable} into output files. This means
7003 that @code{AC_OUTPUT} will replace instances of
7004 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
7005 with the contents of the file that the shell variable @var{variable}
7006 names when @code{AC_OUTPUT} is called. Set the variable to
7007 @file{/dev/null} for cases that do not have a file to insert.
7009 This macro is useful for inserting @file{Makefile} fragments containing
7010 special dependencies or other @code{make} directives for particular host
7011 or target types into @file{Makefile}s. For example, @file{configure.ac}
7015 AC_SUBST_FILE(host_frag)
7016 host_frag=$srcdir/conf/sun4.mh
7020 and then a @file{Makefile.in} could contain:
7027 @cindex Previous Variable
7028 @cindex Variable, Precious
7029 Running @command{configure} in varying environments can be extremely
7030 dangerous. If for instance the user runs @samp{CC=bizarre-cc
7031 ./configure}, then the cache, @file{config.h}, and many other output
7032 files will depend upon @command{bizarre-cc} being the C compiler. If
7033 for some reason the user runs @command{./configure} again, or if it is
7034 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
7035 and @pxref{config.status Invocation}), then the configuration can be
7036 inconsistent, composed of results depending upon two different
7039 Environment variables that affect this situation, such as @samp{CC}
7040 above, are called @dfn{precious variables}, and can be declared as such
7041 by @code{AC_ARG_VAR}.
7043 @defmac AC_ARG_VAR (@var{variable}, @var{description})
7045 Declare @var{variable} is a precious variable, and include its
7046 @var{description} in the variable section of @samp{./configure --help}.
7048 Being precious means that
7051 @var{variable} is @code{AC_SUBST}'d.
7054 The value of @var{variable} when @command{configure} was launched is
7055 saved in the cache, including if it was not specified on the command
7056 line but via the environment. Indeed, while @command{configure} can
7057 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
7058 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
7059 which, unfortunately, is what most users do.
7061 We emphasize that it is the @emph{initial} value of @var{variable} which
7062 is saved, not that found during the execution of @command{configure}.
7063 Indeed, specifying @samp{./configure FOO=foo} and letting
7064 @samp{./configure} guess that @code{FOO} is @code{foo} can be two very
7068 @var{variable} is checked for consistency between two
7069 @command{configure} runs. For instance:
7072 $ @kbd{./configure --silent --config-cache}
7073 $ @kbd{CC=cc ./configure --silent --config-cache}
7074 configure: error: `CC' was not set in the previous run
7075 configure: error: changes in the environment can compromise \
7077 configure: error: run `make distclean' and/or \
7078 `rm config.cache' and start over
7082 and similarly if the variable is unset, or if its content is changed.
7086 @var{variable} is kept during automatic reconfiguration
7087 (@pxref{config.status Invocation}) as if it had been passed as a command
7088 line argument, including when no cache is used:
7091 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
7092 $ @kbd{./config.status --recheck}
7093 running /bin/sh ./configure undeclared_var=raboof --silent \
7094 CC=/usr/bin/cc --no-create --no-recursion
7100 @node Caching Results
7101 @section Caching Results
7104 To avoid checking for the same features repeatedly in various
7105 @command{configure} scripts (or in repeated runs of one script),
7106 @command{configure} can optionally save the results of many checks in a
7107 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
7108 runs with caching enabled and finds a cache file, it reads the results
7109 of previous runs from the cache and avoids rerunning those checks. As a
7110 result, @command{configure} can then run much faster than if it had to
7111 perform all of the checks every time.
7113 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
7115 Ensure that the results of the check identified by @var{cache-id} are
7116 available. If the results of the check were in the cache file that was
7117 read, and @command{configure} was not given the @option{--quiet} or
7118 @option{--silent} option, print a message saying that the result was
7119 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
7120 the shell commands are run to determine the value, the value will be
7121 saved in the cache file just before @command{configure} creates its output
7122 files. @xref{Cache Variable Names}, for how to choose the name of the
7123 @var{cache-id} variable.
7125 The @var{commands-to-set-it} @emph{must have no side effects} except for
7126 setting the variable @var{cache-id}, see below.
7129 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
7130 @acindex{CACHE_CHECK}
7131 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
7132 messages. This macro provides a convenient shorthand for the most
7133 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
7134 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
7135 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
7137 The @var{commands-to-set-it} @emph{must have no side effects} except for
7138 setting the variable @var{cache-id}, see below.
7141 It is very common to find buggy macros using @code{AC_CACHE_VAL} or
7142 @code{AC_CACHE_CHECK}, because people are tempted to call
7143 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
7144 @emph{follows} the call to @code{AC_CACHE_VAL} should call
7145 @code{AC_DEFINE}, by examining the value of the cache variable. For
7146 instance, the following macro is broken:
7150 AC_DEFUN([AC_SHELL_TRUE],
7151 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
7152 [ac_cv_shell_true_works=no
7153 true && ac_cv_shell_true_works=yes
7154 if test $ac_cv_shell_true_works = yes; then
7155 AC_DEFINE([TRUE_WORKS], 1
7156 [Define if `true(1)' works properly.])
7163 This fails if the cache is enabled: the second time this macro is run,
7164 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
7169 AC_DEFUN([AC_SHELL_TRUE],
7170 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
7171 [ac_cv_shell_true_works=no
7172 true && ac_cv_shell_true_works=yes])
7173 if test $ac_cv_shell_true_works = yes; then
7174 AC_DEFINE([TRUE_WORKS], 1
7175 [Define if `true(1)' works properly.])
7181 Also, @var{commands-to-set-it} should not print any messages, for
7182 example with @code{AC_MSG_CHECKING}; do that before calling
7183 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
7184 the results of the check are retrieved from the cache or determined by
7185 running the shell commands.
7188 * Cache Variable Names:: Shell variables used in caches
7189 * Cache Files:: Files @command{configure} uses for caching
7190 * Cache Checkpointing:: Loading and saving the cache file
7193 @node Cache Variable Names
7194 @subsection Cache Variable Names
7195 @cindex Cache variable
7197 The names of cache variables should have the following format:
7200 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
7204 for example, @samp{ac_cv_header_stat_broken} or
7205 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
7208 @item @var{package-prefix}
7209 An abbreviation for your package or organization; the same prefix you
7210 begin local Autoconf macros with, except lowercase by convention.
7211 For cache values used by the distributed Autoconf macros, this value is
7215 Indicates that this shell variable is a cache value. This string
7216 @emph{must} be present in the variable name, including the leading
7219 @item @var{value-type}
7220 A convention for classifying cache values, to produce a rational naming
7221 system. The values used in Autoconf are listed in @ref{Macro Names}.
7223 @item @var{specific-value}
7224 Which member of the class of cache values this test applies to.
7225 For example, which function (@samp{alloca}), program (@samp{gcc}), or
7226 output variable (@samp{INSTALL}).
7228 @item @var{additional-options}
7229 Any particular behavior of the specific member that this test applies to.
7230 For example, @samp{broken} or @samp{set}. This part of the name may
7231 be omitted if it does not apply.
7234 The values assigned to cache variables may not contain newlines.
7235 Usually, their values will be Boolean (@samp{yes} or @samp{no}) or the
7236 names of files or functions; so this is not an important restriction.
7239 @subsection Cache Files
7241 A cache file is a shell script that caches the results of configure
7242 tests run on one system so they can be shared between configure scripts
7243 and configure runs. It is not useful on other systems. If its contents
7244 are invalid for some reason, the user may delete or edit it.
7246 By default, @command{configure} uses no cache file (technically, it uses
7247 @option{--cache-file=/dev/null}), to avoid problems caused by accidental
7248 use of stale cache files.
7250 To enable caching, @command{configure} accepts @option{--config-cache} (or
7251 @option{-C}) to cache results in the file @file{config.cache}.
7252 Alternatively, @option{--cache-file=@var{file}} specifies that
7253 @var{file} be the cache file. The cache file is created if it does not
7254 exist already. When @command{configure} calls @command{configure} scripts in
7255 subdirectories, it uses the @option{--cache-file} argument so that they
7256 share the same cache. @xref{Subdirectories}, for information on
7257 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
7259 @file{config.status} only pays attention to the cache file if it is
7260 given the @option{--recheck} option, which makes it rerun
7261 @command{configure}.
7263 It is wrong to try to distribute cache files for particular system types.
7264 There is too much room for error in doing that, and too much
7265 administrative overhead in maintaining them. For any features that
7266 can't be guessed automatically, use the standard method of the canonical
7267 system type and linking files (@pxref{Manual Configuration}).
7269 The site initialization script can specify a site-wide cache file to
7270 use, instead of the usual per-program cache. In this case, the cache
7271 file will gradually accumulate information whenever someone runs a new
7272 @command{configure} script. (Running @command{configure} merges the new cache
7273 results with the existing cache file.) This may cause problems,
7274 however, if the system configuration (e.g., the installed libraries or
7275 compilers) changes and the stale cache file is not deleted.
7277 @node Cache Checkpointing
7278 @subsection Cache Checkpointing
7280 If your configure script, or a macro called from @file{configure.ac}, happens
7281 to abort the configure process, it may be useful to checkpoint the cache
7282 a few times at key points using @code{AC_CACHE_SAVE}. Doing so will
7283 reduce the amount of time it takes to re-run the configure script with
7284 (hopefully) the error that caused the previous abort corrected.
7286 @c FIXME: Do we really want to document this guy?
7287 @defmac AC_CACHE_LOAD
7288 @acindex{CACHE_LOAD}
7289 Loads values from existing cache file, or creates a new cache file if a
7290 cache file is not found. Called automatically from @code{AC_INIT}.
7293 @defmac AC_CACHE_SAVE
7294 @acindex{CACHE_SAVE}
7295 Flushes all cached values to the cache file. Called automatically from
7296 @code{AC_OUTPUT}, but it can be quite useful to call
7297 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
7303 @r{ @dots{} AC_INIT, etc. @dots{}}
7305 # Checks for programs.
7307 AC_PROG_GCC_TRADITIONAL
7308 @r{ @dots{} more program checks @dots{}}
7313 # Checks for libraries.
7314 AC_CHECK_LIB(nsl, gethostbyname)
7315 AC_CHECK_LIB(socket, connect)
7316 @r{ @dots{} more lib checks @dots{}}
7321 # Might abort@dots{}
7322 AM_PATH_GTK(1.0.2,, [AC_MSG_ERROR([GTK not in path])])
7323 AM_PATH_GTKMM(0.9.5,, [AC_MSG_ERROR([GTK not in path])])
7325 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
7328 @node Printing Messages
7329 @section Printing Messages
7330 @cindex Messages, from @command{configure}
7332 @command{configure} scripts need to give users running them several kinds
7333 of information. The following macros print messages in ways appropriate
7334 for each kind. The arguments to all of them get enclosed in shell
7335 double quotes, so the shell performs variable and back-quote
7336 substitution on them.
7338 These macros are all wrappers around the @code{echo} shell command.
7339 @command{configure} scripts should rarely need to run @code{echo} directly
7340 to print messages for the user. Using these macros makes it easy to
7341 change how and when each kind of message is printed; such changes need
7342 only be made to the macro definitions and all of the callers will change
7345 To diagnose static issues, i.e., when @command{autoconf} is run, see
7346 @ref{Reporting Messages}.
7348 @defmac AC_MSG_CHECKING (@var{feature-description})
7349 @acindex{MSG_CHECKING}
7350 Notify the user that @command{configure} is checking for a particular
7351 feature. This macro prints a message that starts with @samp{checking }
7352 and ends with @samp{...} and no newline. It must be followed by a call
7353 to @code{AC_MSG_RESULT} to print the result of the check and the
7354 newline. The @var{feature-description} should be something like
7355 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
7358 This macro prints nothing if @command{configure} is run with the
7359 @option{--quiet} or @option{--silent} option.
7362 @defmac AC_MSG_RESULT (@var{result-description})
7363 @acindex{MSG_RESULT}
7364 Notify the user of the results of a check. @var{result-description} is
7365 almost always the value of the cache variable for the check, typically
7366 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
7367 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
7368 the completion of the message printed by the call to
7369 @code{AC_MSG_CHECKING}.
7371 This macro prints nothing if @command{configure} is run with the
7372 @option{--quiet} or @option{--silent} option.
7375 @defmac AC_MSG_NOTICE (@var{message})
7376 @acindex{MSG_NOTICE}
7377 Deliver the @var{message} to the user. It is useful mainly to print a
7378 general description of the overall purpose of a group of feature checks,
7382 AC_MSG_NOTICE([checking if stack overflow is detectable])
7385 This macro prints nothing if @command{configure} is run with the
7386 @option{--quiet} or @option{--silent} option.
7389 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
7391 Notify the user of an error that prevents @command{configure} from
7392 completing. This macro prints an error message to the standard error
7393 output and exits @command{configure} with @var{exit-status} (1 by default).
7394 @var{error-description} should be something like @samp{invalid value
7397 The @var{error-description} should start with a lower-case letter, and
7398 ``cannot'' is preferred to ``can't''.
7401 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
7402 @acindex{MSG_FAILURE}
7403 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
7404 prevents @command{configure} from completing @emph{and} that additional
7405 details are provided in @file{config.log}. This is typically used when
7406 abnormal results are found during a compilation.
7409 @defmac AC_MSG_WARN (@var{problem-description})
7411 Notify the @command{configure} user of a possible problem. This macro
7412 prints the message to the standard error output; @command{configure}
7413 continues running afterward, so macros that call @code{AC_MSG_WARN} should
7414 provide a default (back-up) behavior for the situations they warn about.
7415 @var{problem-description} should be something like @samp{ln -s seems to
7421 @c ====================================================== Programming in M4.
7423 @node Programming in M4
7424 @chapter Programming in M4
7427 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
7428 convenient macros for pure M4 programming, and @dfn{M4sh}, which
7429 provides macros dedicated to shell script generation.
7431 As of this version of Autoconf, these two layers are still experimental,
7432 and their interface might change in the future. As a matter of fact,
7433 @emph{anything that is not documented must not be used}.
7436 * M4 Quotation:: Protecting macros from unwanted expansion
7437 * Using autom4te:: The Autoconf executables backbone
7438 * Programming in M4sugar:: Convenient pure M4 macros
7439 * Programming in M4sh:: Common shell Constructs
7443 @section M4 Quotation
7444 @cindex M4 quotation
7447 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
7448 @c prevented `expansion' of $1. Unless it refers to the expansion
7449 @c of the value of $1? Anyway, we need a rewrite here@enddots{}
7451 The most common problem with existing macros is an improper quotation.
7452 This section, which users of Autoconf can skip, but which macro writers
7453 @emph{must} read, first justifies the quotation scheme that was chosen
7454 for Autoconf and then ends with a rule of thumb. Understanding the
7455 former helps one to follow the latter.
7458 * Active Characters:: Characters that change the behavior of M4
7459 * One Macro Call:: Quotation and one macro call
7460 * Quotation and Nested Macros:: Macros calling macros
7461 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
7462 * Quadrigraphs:: Another way to escape special characters
7463 * Quotation Rule Of Thumb:: One parenthesis, one quote
7466 @node Active Characters
7467 @subsection Active Characters
7469 To fully understand where proper quotation is important, you first need
7470 to know what the special characters are in Autoconf: @samp{#} introduces
7471 a comment inside which no macro expansion is performed, @samp{,}
7472 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
7473 and finally @samp{(} and @samp{)} (which M4 tries to match by
7476 In order to understand the delicate case of macro calls, we first have
7477 to present some obvious failures. Below they are ``obvious-ified'',
7478 but when you find them in real life, they are usually in disguise.
7480 Comments, introduced by a hash and running up to the newline, are opaque
7481 tokens to the top level: active characters are turned off, and there is
7485 # define([def], ine)
7486 @result{}# define([def], ine)
7489 Each time there can be a macro expansion, there is a quotation
7490 expansion, i.e., one level of quotes is stripped:
7496 @result{}int tab[10];
7499 Without this in mind, the reader will try hopelessly to use her macro
7503 define([array], [int tab[10];])
7511 How can you correctly output the intended results@footnote{Using
7515 @node One Macro Call
7516 @subsection One Macro Call
7518 Let's proceed on the interaction between active characters and macros
7519 with this small macro, which just returns its first argument:
7526 The two pairs of quotes above are not part of the arguments of
7527 @code{define}; rather, they are understood by the top level when it
7528 tries to find the arguments of @code{define}. Therefore, assuming
7529 @code{car} is not already defined, it is equivalent to write:
7536 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
7537 quotes, it is bad practice for Autoconf macros which must both be more
7538 robust and also advocate perfect style.
7540 At the top level, there are only two possibilities: either you
7546 [car(foo, bar, baz)]
7547 @result{}car(foo, bar, baz)
7550 Let's pay attention to the special characters:
7554 @error{}EOF in argument list
7557 The closing parenthesis is hidden in the comment; with a hypothetical
7558 quoting, the top level understood it this way:
7565 Proper quotation, of course, fixes the problem:
7572 Here are more examples:
7595 With this in mind, we can explore the cases where macros invoke
7599 @node Quotation and Nested Macros
7600 @subsection Quotation and Nested Macros
7602 The examples below use the following macros:
7606 define([active], [ACT, IVE])
7607 define([array], [int tab[10]])
7610 Each additional embedded macro call introduces other possible
7611 interesting quotations:
7622 In the first case, the top level looks for the arguments of @code{car},
7623 and finds @samp{active}. Because M4 evaluates its arguments
7624 before applying the macro, @samp{active} is expanded, which results in:
7632 In the second case, the top level gives @samp{active} as first and only
7633 argument of @code{car}, which results in:
7641 i.e., the argument is evaluated @emph{after} the macro that invokes it.
7642 In the third case, @code{car} receives @samp{[active]}, which results in:
7650 exactly as we already saw above.
7652 The example above, applied to a more realistic example, gives:
7659 car([[int tab[10];]])
7660 @result{}int tab[10];
7664 Huh? The first case is easily understood, but why is the second wrong,
7665 and the third right? To understand that, you must know that after
7666 M4 expands a macro, the resulting text is immediately subjected
7667 to macro expansion and quote removal. This means that the quote removal
7668 occurs twice---first before the argument is passed to the @code{car}
7669 macro, and second after the @code{car} macro expands to the first
7672 As the author of the Autoconf macro @code{car}, you then consider it to
7673 be incorrect that your users have to double-quote the arguments of
7674 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
7678 define([qar], [[$1]])
7682 and check that @code{qar} is properly fixed:
7686 @result{}int tab[10];
7690 Ahhh! That's much better.
7692 But note what you've done: now that the arguments are literal strings,
7693 if the user wants to use the results of expansions as arguments, she has
7694 to use an @emph{unquoted} macro call:
7702 where she wanted to reproduce what she used to do with @code{car}:
7710 Worse yet: she wants to use a macro that produces a set of @code{cpp}
7714 define([my_includes], [#include <stdio.h>])
7716 @result{}#include <stdio.h>
7718 @error{}EOF in argument list
7721 This macro, @code{qar}, because it double quotes its arguments, forces
7722 its users to leave their macro calls unquoted, which is dangerous.
7723 Commas and other active symbols are interpreted by M4 before
7724 they are given to the macro, often not in the way the users expect.
7725 Also, because @code{qar} behaves differently from the other macros,
7726 it's an exception that should be avoided in Autoconf.
7728 @node Changequote is Evil
7729 @subsection @code{changequote} is Evil
7730 @cindex @code{changequote}
7732 The temptation is often high to bypass proper quotation, in particular
7733 when it's late at night. Then, many experienced Autoconf hackers
7734 finally surrender to the dark side of the force and use the ultimate
7735 weapon: @code{changequote}.
7737 The M4 builtin @code{changequote} belongs to a set of primitives that
7738 allow one to adjust the syntax of the language to adjust it to one's
7739 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
7740 quotes, but in the context of shell programming (and actually of most
7741 programming languages), that's about the worst choice one can make:
7742 because of strings and back-quoted expressions in shell code (such as
7743 @samp{'this'} and @samp{`that`}), because of literal characters in usual
7744 programming languages (as in @samp{'0'}), there are many unbalanced
7745 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
7746 not impossible. In order to make M4 useful in such a context, its
7747 designers have equipped it with @code{changequote}, which makes it
7748 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
7749 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
7750 because they are unlikely characters, but @emph{because they are
7751 characters unlikely to be unbalanced}.
7753 There are other magic primitives, such as @code{changecom} to specify
7754 what syntactic forms are comments (it is common to see
7755 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
7756 @code{changeword} and @code{changesyntax} to change other syntactic
7757 details (such as the character to denote the n-th argument, @samp{$} by
7758 default, the parenthesis around arguments etc.).
7760 These primitives are really meant to make M4 more useful for specific
7761 domains: they should be considered like command line options:
7762 @option{--quotes}, @option{--comments}, @option{--words}, and
7763 @code{--syntax}. Nevertheless, they are implemented as M4 builtins, as
7764 it makes M4 libraries self contained (no need for additional options).
7766 There lies the problem@enddots{}
7770 The problem is that it is then tempting to use them in the middle of an
7771 M4 script, as opposed to its initialization. This, if not carefully
7772 thought out, can lead to disastrous effects: @emph{you are changing the
7773 language in the middle of the execution}. Changing and restoring the
7774 syntax is often not enough: if you happened to invoke macros in between,
7775 these macros will be lost, as the current syntax will probably not be
7776 the one they were implemented with.
7778 @c FIXME: I've been looking for a short, real case example, but I
7783 @subsection Quadrigraphs
7784 @cindex quadrigraphs
7785 @cindex @samp{@@S|@@}
7786 @cindex @samp{@@&t@@}
7787 @c Info cannot handle `:' in index entries.
7788 @c @cindex @samp{@@<:@@}
7789 @c @cindex @samp{@@:>@@}
7790 @c @cindex @samp{@@%:@@}
7792 When writing an Autoconf macro you may occasionally need to generate
7793 special characters that are difficult to express with the standard
7794 Autoconf quoting rules. For example, you may need to output the regular
7795 expression @samp{[^[]}, which matches any character other than @samp{[}.
7796 This expression contains unbalanced brackets so it cannot be put easily
7799 You can work around this problem by using one of the following
7815 Quadrigraphs are replaced at a late stage of the translation process,
7816 after @command{m4} is run, so they do not get in the way of M4 quoting.
7817 For example, the string @samp{^@@<:@@}, independently of its quotation,
7818 will appear as @samp{^[} in the output.
7820 The empty quadrigraph can be used:
7823 @item to mark trailing spaces explicitly
7825 Trailing spaces are smashed by @command{autom4te}. This is a feature.
7827 @item to produce other quadrigraphs
7829 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
7831 @item to escape @emph{occurrences} of forbidden patterns
7833 For instance you might want to mention @code{AC_FOO} in a comment, while
7834 still being sure that @command{autom4te} will still catch unexpanded
7835 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
7838 The name @samp{@@&t@@} was suggested by Paul Eggert:
7841 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
7842 own invention, but the @samp{t} came from the source code of the
7843 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
7844 and which used @samp{mt} to denote the empty string. In C, it would
7845 have looked like something like:
7848 char const mt[] = "";
7852 but of course the source code was written in Algol 68.
7854 I don't know where he got @samp{mt} from: it could have been his own
7855 invention, and I suppose it could have been a common pun around the
7856 Cambridge University computer lab at the time.
7859 @node Quotation Rule Of Thumb
7860 @subsection Quotation Rule Of Thumb
7862 To conclude, the quotation rule of thumb is:
7864 @center @emph{One pair of quotes per pair of parentheses.}
7866 Never over-quote, never under-quote, in particular in the definition of
7867 macros. In the few places where the macros need to use brackets
7868 (usually in C program text or regular expressions), properly quote
7869 @emph{the arguments}!
7871 It is common to read Autoconf programs with snippets like:
7875 changequote(<<, >>)dnl
7877 #ifndef tzname /* For SGI. */
7878 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
7880 changequote([, ])dnl
7881 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
7885 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
7886 double quoting, so you just need:
7891 #ifndef tzname /* For SGI. */
7892 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
7895 [ac_cv_var_tzname=yes],
7896 [ac_cv_var_tzname=no])
7900 The M4-fluent reader will note that these two examples are rigorously
7901 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
7902 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
7903 quotes are not part of the arguments!
7905 Simplified, the example above is just doing this:
7908 changequote(<<, >>)dnl
7910 changequote([, ])dnl
7921 With macros that do not double quote their arguments (which is the
7922 rule), double-quote the (risky) literals:
7925 AC_LINK_IFELSE([AC_LANG_PROGRAM(
7927 #ifndef tzname /* For SGI. */
7928 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
7930 [atoi (*tzname);])],
7931 [ac_cv_var_tzname=yes],
7932 [ac_cv_var_tzname=no])
7935 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
7936 where quoting does not suffice.
7938 When you create a @command{configure} script using newly written macros,
7939 examine it carefully to check whether you need to add more quotes in
7940 your macros. If one or more words have disappeared in the M4
7941 output, you need more quotes. When in doubt, quote.
7943 However, it's also possible to put on too many layers of quotes. If
7944 this happens, the resulting @command{configure} script will contain
7945 unexpanded macros. The @command{autoconf} program checks for this problem
7946 by doing @samp{grep AC_ configure}.
7949 @c ---------------------------------------- Using autom4te
7951 @node Using autom4te
7952 @section Using @command{autom4te}
7954 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
7955 to Autoconf per se, heavily rely on M4. All these different uses
7956 revealed common needs factored into a layer over @command{m4}:
7957 @command{autom4te}@footnote{
7959 Yet another great name from Lars J. Aas.
7963 @command{autom4te} is a preprocessor that is like @command{m4}.
7964 It supports M4 extensions designed for use in tools like Autoconf.
7967 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
7968 * Customizing autom4te:: Customizing the Autoconf package
7971 @node autom4te Invocation
7972 @subsection Invoking @command{autom4te}
7974 The command line arguments are modeled after M4's:
7977 autom4te @var{options} @var{files}
7981 where the @var{files} are directly passed to @command{m4}. In addition
7982 to the regular expansion, it handles the replacement of the quadrigraphs
7983 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
7984 output. It supports an extended syntax for the @var{files}:
7987 @item @var{file}.m4f
7988 This file is an M4 frozen file. Note that @emph{all the previous files
7989 are ignored}. See the option @option{--melt} for the rationale.
7992 If found in the library path, the @var{file} is included for expansion,
7993 otherwise it is ignored instead of triggering a failure.
7998 Of course, it supports the Autoconf common subset of options:
8003 Print a summary of the command line options and exit.
8007 Print the version number of Autoconf and exit.
8011 Report processing steps.
8015 Don't remove the temporary files and be even more verbose.
8017 @item --include=@var{dir}
8019 Also look for input files in @var{dir}. Multiple invocations
8022 @item --output=@var{file}
8023 @itemx -o @var{file}
8024 Save output (script or trace) to @var{file}. The file @option{-} stands
8025 for the standard output.
8030 As an extension of @command{m4}, it includes the following options:
8033 @item --warnings=@var{category}
8034 @itemx -W @var{category}
8036 @c FIXME: Point to the M4sugar macros, not Autoconf's.
8037 Report the warnings related to @var{category} (which can actually be a
8038 comma separated list). @xref{Reporting Messages}, macro
8039 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
8044 report all the warnings
8050 treats warnings as errors
8052 @item no-@var{category}
8053 disable warnings falling into @var{category}
8056 Warnings about @samp{syntax} are enabled by default, and the environment
8057 variable @code{WARNINGS}, a comma separated list of categories, is
8058 honored. @command{autom4te -W @var{category}} will actually
8059 behave as if you had run:
8062 autom4te --warnings=syntax,$WARNINGS,@var{category}
8066 If you want to disable @command{autom4te}'s defaults and
8067 @code{WARNINGS}, but (for example) enable the warnings about obsolete
8068 constructs, you would use @option{-W none,obsolete}.
8071 @cindex Macro invocation stack
8072 @command{autom4te} displays a back trace for errors, but not for
8073 warnings; if you want them, just pass @option{-W error}. For instance,
8074 on this @file{configure.ac}:
8078 [AC_RUN_IFELSE([AC_LANG_PROGRAM([exit (0)])])])
8091 $ @kbd{autom4te -l autoconf -Wcross}
8092 configure.ac:8: warning: AC_RUN_IFELSE called without default \
8093 to allow cross compiling
8094 $ @kbd{autom4te -l autoconf -Wcross,error -f}
8095 configure.ac:8: error: AC_RUN_IFELSE called without default \
8096 to allow cross compiling
8097 acgeneral.m4:3044: AC_RUN_IFELSE is expanded from...
8098 configure.ac:2: INNER is expanded from...
8099 configure.ac:5: OUTER is expanded from...
8100 configure.ac:8: the top level
8106 Do not use frozen files. Any argument @code{@var{file}.m4f} will be
8107 replaced with @code{@var{file}.m4}. This helps tracing the macros which
8108 are executed only when the files are frozen, typically
8109 @code{m4_define}. For instance, running:
8112 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
8116 is roughly equivalent to running:
8119 m4 1.m4 2.m4 3.m4 4.m4 input.m4
8126 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
8133 m4 --reload-state=4.m4f input.m4
8138 Produce a frozen state file. @command{autom4te} freezing is stricter
8139 than M4's: it must produce no warnings, and no output other than empty
8140 lines (a line with whitespace is @emph{not} empty) and comments
8141 (starting with @samp{#}). Please, note that contrary to @command{m4},
8142 this options takes no argument:
8145 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
8152 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
8155 @item --mode=@var{octal-mode}
8156 @itemx -m @var{octal-mode}
8157 Set the mode of the non-traces output to @var{octal-mode}; by default
8163 @cindex @file{autom4te.cache}
8164 As another additional feature over @command{m4}, @command{autom4te}
8165 caches its results. @acronym{GNU} M4 is able to produce a regular
8166 output and traces at the same time. Traces are heavily used in the
8167 @acronym{GNU} Build System: @command{autoheader} uses them to build
8168 @file{config.h.in}, @command{autoreconf} to determine what
8169 @acronym{GNU} Build System components are used, @command{automake} to
8170 ``parse'' @file{configure.ac} etc. To save the long runs of
8171 @command{m4}, traces are cached while performing regular expansion,
8172 and conversely. This cache is (actually, the caches are) stored in
8173 the directory @file{autom4te.cache}. @emph{It can safely be removed}
8174 at any moment (especially if for some reason @command{autom4te}
8175 considers it is trashed).
8178 @item --cache=@var{directory}
8179 @itemx -C @var{directory}
8180 Specify the name of the directory where the result should be cached.
8181 Passing an empty value disables caching. Be sure to pass a relative
8182 path name, as for the time being, global caches are not supported.
8185 Don't cache the results.
8189 If a cache is used, consider it obsolete (but update it anyway).
8194 Because traces are so important to the @acronym{GNU} Build System,
8195 @command{autom4te} provides high level tracing features as compared to
8196 M4, and helps exploiting the cache:
8199 @item --trace=@var{macro}[:@var{format}]
8200 @itemx -t @var{macro}[:@var{format}]
8201 Trace the invocations of @var{macro} according to the @var{format}.
8202 Multiple @option{--trace} arguments can be used to list several macros.
8203 Multiple @option{--trace} arguments for a single macro are not
8204 cumulative; instead, you should just make @var{format} as long as
8207 The @var{format} is a regular string, with newlines if desired, and
8208 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
8209 use the following special escapes:
8213 The character @samp{$}.
8216 The filename from which @var{macro} is called.
8219 The line number from which @var{macro} is called.
8222 The depth of the @var{macro} call. This is an M4 technical detail that
8223 you probably don't want to know about.
8226 The name of the @var{macro}.
8229 The @var{num}th argument of the call to @var{macro}.
8233 @itemx $@{@var{separator}@}@@
8234 All the arguments passed to @var{macro}, separated by the character
8235 @var{sep} or the string @var{separator} (@samp{,} by default). Each
8236 argument is quoted, i.e., enclosed in a pair of square brackets.
8240 @itemx $@{@var{separator}@}*
8241 As above, but the arguments are not quoted.
8245 @itemx $@{@var{separator}@}%
8246 As above, but the arguments are not quoted, all new line characters in
8247 the arguments are smashed, and the default separator is @samp{:}.
8249 The escape @samp{$%} produces single-line trace outputs (unless you put
8250 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
8254 @xref{autoconf Invocation}, for examples of trace uses.
8256 @item --preselect=@var{macro}
8257 @itemx -p @var{macro}
8258 Cache the traces of @var{macro}, but do not enable traces. This is
8259 especially important to save CPU cycles in the future. For instance,
8260 when invoked, @command{autoconf} preselects all the macros that
8261 @command{autoheader}, @command{automake}, @command{autoreconf} etc.@: will
8262 trace, so that running @command{m4} is not needed to trace them: the
8263 cache suffices. This results in a huge speed-up.
8268 @cindex Autom4te Library
8269 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
8270 libraries}. They consists in a powerful yet extremely simple feature:
8271 sets of combined command line arguments:
8274 @item --language=@var{language}
8275 @itemx -l =@var{language}
8276 Use the @var{language} Autom4te library. Current languages include:
8280 create M4sugar output.
8283 create M4sh executable shell scripts.
8286 create Autotest executable test suites.
8289 create Autoconf executable configure scripts.
8291 @item Autoconf-without-aclocal-m4
8292 create Autoconf executable configure scripts without
8293 reading @file{aclocal.m4}.
8296 @item --prepend-include=@var{dir}
8298 Prepend directory @var{dir} to the search path. This is used to include
8299 the language-specific files before any third-party macros.
8303 @cindex @file{autom4te.cfg}
8304 As an example, if Autoconf is installed in its default location,
8305 @file{/usr/local}, running @samp{autom4te -l m4sugar foo.m4} is
8306 strictly equivalent to running @samp{autom4te --prepend-include
8307 /usr/local/share/autoconf m4sugar/m4sugar.m4f --warnings syntax foo.m4}.
8308 Recursive expansion applies: running @samp{autom4te -l m4sh foo.m4}
8309 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
8310 foo.m4}, i.e., @samp{autom4te --prepend-include /usr/local/share/autoconf
8311 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4}. The definition
8312 of the languages is stored in @file{autom4te.cfg}.
8314 @node Customizing autom4te
8315 @subsection Customizing @command{autom4te}
8317 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
8318 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
8319 as found in the directory from which @command{autom4te} is run). The
8320 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
8321 then @file{./.autom4te.cfg}, and finally the command line arguments.
8323 In these text files, comments are introduced with @code{#}, and empty
8324 lines are ignored. Customization is performed on a per-language basis,
8325 wrapped in between a @samp{begin-language: "@var{language}"},
8326 @samp{end-language: "@var{language}"} pair.
8328 Customizing a language stands for appending options (@pxref{autom4te
8329 Invocation}) to the current definition of the language. Options, and
8330 more generally arguments, are introduced by @samp{args:
8331 @var{arguments}}. You may use the traditional shell syntax to quote the
8334 As an example, to disable Autoconf caches (@file{autom4te.cache})
8335 globally, include the following lines in @file{~/.autom4te.cfg}:
8338 ## ------------------ ##
8339 ## User Preferences. ##
8340 ## ------------------ ##
8342 begin-language: "Autoconf"
8344 end-language: "Autoconf"
8348 @node Programming in M4sugar
8349 @section Programming in M4sugar
8352 M4 by itself provides only a small, but sufficient, set of all-purpose
8353 macros. M4sugar introduces additional generic macros. Its name was
8354 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
8358 * Redefined M4 Macros:: M4 builtins changed in M4sugar
8359 * Evaluation Macros:: More quotation and evaluation control
8360 * Forbidden Patterns:: Catching unexpanded macros
8363 @node Redefined M4 Macros
8364 @subsection Redefined M4 Macros
8366 With a few exceptions, all the M4 native macros are moved in the
8367 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
8368 @code{m4_define} etc.
8370 Some M4 macros are redefined, and are slightly incompatible with their
8375 This macro kept its original name: no @code{m4_dnl} is defined.
8378 @defmac m4_defn (@var{macro})
8380 Contrary to the M4 builtin, this macro fails if @var{macro} is not
8381 defined. See @code{m4_undefine}.
8384 @defmac m4_exit (@var{exit-status})
8386 This macro corresponds to @code{m4exit}.
8389 @defmac m4_if (@var{comment})
8390 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
8391 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
8393 This macro corresponds to @code{ifelse}.
8396 @defmac m4_undefine (@var{macro})
8398 Contrary to the M4 builtin, this macro fails if @var{macro} is not
8402 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
8406 to recover the behavior of the builtin.
8409 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
8411 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
8412 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
8413 provide extended regular expression syntax via @code{epatsubst}.
8416 @defmac m4_popdef (@var{macro})
8418 Contrary to the M4 builtin, this macro fails if @var{macro} is not
8419 defined. See @code{m4_undefine}.
8422 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
8424 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
8425 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
8426 provide extended regular expression syntax via @code{eregexp}.
8429 @defmac m4_wrap (@var{text})
8431 This macro corresponds to @code{m4wrap}.
8433 You are encouraged to end @var{text} with @samp{[]}, so that there are
8434 no risks that two consecutive invocations of @code{m4_wrap} result in an
8435 unexpected pasting of tokens, as in
8438 m4_define([foo], [Foo])
8439 m4_define([bar], [Bar])
8440 m4_define([foobar], [FOOBAR])
8447 @node Evaluation Macros
8448 @subsection Evaluation Macros
8450 The following macros give some control over the order of the evaluation
8451 by adding or removing levels of quotes. They are meant for hard-core M4
8454 @defmac m4_dquote (@var{arg1}, @dots{})
8456 Return the arguments as a quoted list of quoted arguments.
8459 @defmac m4_quote (@var{arg1}, @dots{})
8461 Return the arguments as a single entity, i.e., wrap them into a pair of
8465 The following example aims at emphasizing the difference between (i), not
8466 using these macros, (ii), using @code{m4_quote}, and (iii), using
8470 $ @kbd{cat example.m4}
8471 # Overquote, so that quotes are visible.
8472 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
8475 show(m4_quote(a, b))
8476 show(m4_dquote(a, b))
8477 $ @kbd{autom4te -l m4sugar example.m4}
8478 $1 = a, $@@ = [a],[b]
8479 $1 = a,b, $@@ = [a,b]
8480 $1 = [a],[b], $@@ = [[a],[b]]
8485 @node Forbidden Patterns
8486 @subsection Forbidden Patterns
8487 @cindex Forbidden patterns
8488 @cindex Patterns, forbidden
8490 M4sugar provides a means to define suspicious patterns, patterns
8491 describing tokens which should not be found in the output. For
8492 instance, if an Autoconf @file{configure} script includes tokens such as
8493 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
8494 wrong (typically a macro was not evaluated because of overquotation).
8496 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
8498 @defmac m4_pattern_forbid (@var{pattern})
8499 @msindex{pattern_forbid}
8500 Declare that no token matching @var{pattern} must be found in the output.
8501 Comments are not checked; this can be a problem if, for instance, you
8502 have some macro left unexpanded after an @samp{#include}. No consensus
8503 is currently found in the Autoconf community, as some people consider it
8504 should be valid to name macros in comments (which doesn't makes sense to
8505 the author of this documentation, as @samp{#}-comments should document
8506 the output, not the input, documented by @samp{dnl} comments).
8509 Of course, you might encounter exceptions to these generic rules, for
8510 instance you might have to refer to @samp{$m4_flags}.
8512 @defmac m4_pattern_allow (@var{pattern})
8513 @msindex{pattern_allow}
8514 Any token matching @var{pattern} is allowed, including if it matches an
8515 @code{m4_pattern_forbid} pattern.
8518 @node Programming in M4sh
8519 @section Programming in M4sh
8521 @c FIXME: Eventually will become a chapter, as it is not related to
8522 @c programming in M4 per se.
8524 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
8525 scripts. This name was coined by Lars J. Aas, who notes that,
8526 according to the Webster's Revised Unabridged Dictionary (1913):
8529 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
8530 wash, and prob.@: to AS.@: miscian to mix. See ``Mix''.]
8534 A mass of mixed ingredients reduced to a soft pulpy state by beating or
8538 A mixture of meal or bran and water fed to animals.
8541 A mess; trouble. [Obs.] --Beau.@: & Fl.
8546 For the time being, it is not mature enough to be widely used.
8548 M4sh provides portable alternatives for some common shell constructs
8549 that unfortunately are not portable in practice.
8551 @defmac AS_DIRNAME (@var{pathname})
8553 Return the directory portion of @var{pathname}, using the algorithm
8554 required by @acronym{POSIX}. @xref{Limitations of Usual Tools}, for more
8555 details about what this returns and why it is more portable than the
8556 @command{dirname} command.
8559 @defmac AS_IF (@var{test}, @ovar{RUN-IF-TRUE}, @ovar{RUN-IF-FALSE})
8561 Run shell code TEST. If TEST exits with a zero status then run shell code
8562 RUN-IF-TRUE, else run shell code RUN-IF-FALSE, with simplifications if either
8563 RUN-IF-TRUE or RUN-IF-FALSE is empty.
8566 @defmac AS_MKDIR_P (@var{filename})
8568 Make the directory @var{filename}, including intervening directories
8569 as necessary. This is equivalent to @samp{mkdir -p @var{filename}},
8570 except that it is portable to older versions of @command{mkdir} that
8571 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
8572 succeeds if @var{filename} is a symbolic link to an existing directory,
8573 even though @acronym{POSIX} is unclear whether @samp{mkdir -p} should
8574 succeed in that case.
8577 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
8578 @asindex{SET_CATFILE}
8579 Set the shell variable @var{var} to @var{dir}/@var{file}, but
8580 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
8581 @var{file} is absolute etc.).
8586 @c=================================================== Writing Autoconf Macros.
8588 @node Writing Autoconf Macros
8589 @chapter Writing Autoconf Macros
8591 When you write a feature test that could be applicable to more than one
8592 software package, the best thing to do is encapsulate it in a new macro.
8593 Here are some instructions and guidelines for writing Autoconf macros.
8596 * Macro Definitions:: Basic format of an Autoconf macro
8597 * Macro Names:: What to call your new macros
8598 * Reporting Messages:: Notifying @command{autoconf} users
8599 * Dependencies Between Macros:: What to do when macros depend on other macros
8600 * Obsoleting Macros:: Warning about old ways of doing things
8601 * Coding Style:: Writing Autoconf macros @`a la Autoconf
8604 @node Macro Definitions
8605 @section Macro Definitions
8608 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
8609 similar to the M4 builtin @code{m4_define} macro. In addition to
8610 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
8611 constrain the order in which macros are called (@pxref{Prerequisite
8614 An Autoconf macro definition looks like this:
8617 AC_DEFUN(@var{macro-name}, @var{macro-body})
8620 You can refer to any arguments passed to the macro as @samp{$1},
8621 @samp{$2}, etc. @xref{Definitions,, How to define new macros, m4.info,
8622 @acronym{GNU} m4}, for more complete information on writing M4 macros.
8624 Be sure to properly quote both the @var{macro-body} @emph{and} the
8625 @var{macro-name} to avoid any problems if the macro happens to have
8626 been previously defined.
8628 Each macro should have a header comment that gives its prototype, and a
8629 brief description. When arguments have default values, display them in
8630 the prototype. For example:
8633 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
8634 # --------------------------------------
8635 m4_define([AC_MSG_ERROR],
8636 [@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}])
8639 Comments about the macro should be left in the header comment. Most
8640 other comments will make their way into @file{configure}, so just keep
8641 using @samp{#} to introduce comments.
8644 If you have some very special comments about pure M4 code, comments
8645 that make no sense in @file{configure} and in the header comment, then
8646 use the builtin @code{dnl}: it causes M4 to discard the text
8647 through the next newline.
8649 Keep in mind that @code{dnl} is rarely needed to introduce comments;
8650 @code{dnl} is more useful to get rid of the newlines following macros
8651 that produce no output, such as @code{AC_REQUIRE}.
8655 @section Macro Names
8657 All of the Autoconf macros have all-uppercase names starting with
8658 @samp{AC_} to prevent them from accidentally conflicting with other
8659 text. All shell variables that they use for internal purposes have
8660 mostly-lowercase names starting with @samp{ac_}. To ensure that your
8661 macros don't conflict with present or future Autoconf macros, you should
8662 prefix your own macro names and any shell variables they use with some
8663 other sequence. Possibilities include your initials, or an abbreviation
8664 for the name of your organization or software package.
8666 Most of the Autoconf macros' names follow a structured naming convention
8667 that indicates the kind of feature check by the name. The macro names
8668 consist of several words, separated by underscores, going from most
8669 general to most specific. The names of their cache variables use the
8670 same convention (@pxref{Cache Variable Names}, for more information on
8673 The first word of the name after @samp{AC_} usually tells the category
8674 of the feature being tested. Here are the categories used in Autoconf for
8675 specific test macros, the kind of macro that you are more likely to
8676 write. They are also used for cache variables, in all-lowercase. Use
8677 them where applicable; where they're not, invent your own categories.
8681 C language builtin features.
8683 Declarations of C variables in header files.
8685 Functions in libraries.
8687 @sc{unix} group owners of files.
8693 The full path names to files, including programs.
8695 The base names of programs.
8697 Members of aggregates.
8699 Operating system features.
8701 C builtin or declared types.
8703 C variables in libraries.
8706 After the category comes the name of the particular feature being
8707 tested. Any further words in the macro name indicate particular aspects
8708 of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
8709 behavior of the @code{utime} function when called with a @code{NULL}
8712 An internal macro should have a name that starts with an underscore;
8713 Autoconf internals should therefore start with @samp{_AC_}.
8714 Additionally, a macro that is an internal subroutine of another macro
8715 should have a name that starts with an underscore and the name of that
8716 other macro, followed by one or more words saying what the internal
8717 macro does. For example, @code{AC_PATH_X} has internal macros
8718 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
8720 @node Reporting Messages
8721 @section Reporting Messages
8722 @cindex Messages, from @command{autoconf}
8724 When macros statically diagnose abnormal situations, benign or fatal,
8725 they should report them using these macros. For dynamic issues, i.e.,
8726 when @command{configure} is run, see @ref{Printing Messages}.
8728 @defmac AC_DIAGNOSE (@var{category}, @var{message})
8730 Report @var{message} as a warning (or as an error if requested by the
8731 user) if warnings of the @var{category} are turned on. You are
8732 encouraged to use standard categories, which currently include:
8736 messages that don't fall into one of the following categories. Use of an
8737 empty @var{category} is equivalent.
8740 related to cross compilation issues.
8743 use of an obsolete construct.
8746 dubious syntactic constructs, incorrectly ordered macro calls.
8750 @defmac AC_WARNING (@var{message})
8752 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
8753 strongly encouraged to use a finer grained category.
8756 @defmac AC_FATAL (@var{message})
8758 Report a severe error @var{message}, and have @command{autoconf} die.
8761 When the user runs @samp{autoconf -W error}, warnings from
8762 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
8763 @ref{autoconf Invocation}.
8765 @node Dependencies Between Macros
8766 @section Dependencies Between Macros
8767 @cindex Dependencies between macros
8769 Some Autoconf macros depend on other macros having been called first in
8770 order to work correctly. Autoconf provides a way to ensure that certain
8771 macros are called if needed and a way to warn the user if macros are
8772 called in an order that might cause incorrect operation.
8775 * Prerequisite Macros:: Ensuring required information
8776 * Suggested Ordering:: Warning about possible ordering problems
8779 @node Prerequisite Macros
8780 @subsection Prerequisite Macros
8781 @cindex Prerequisite macros
8782 @cindex Macros, prerequisites
8784 A macro that you write might need to use values that have previously
8785 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
8786 examines the output of @code{flex} or @code{lex}, so it depends on
8787 @code{AC_PROG_LEX} having been called first to set the shell variable
8790 Rather than forcing the user of the macros to keep track of the
8791 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
8792 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
8793 called if it is needed, and only called once.
8795 @defmac AC_REQUIRE (@var{macro-name})
8797 If the M4 macro @var{macro-name} has not already been called, call it
8798 (without any arguments). Make sure to quote @var{macro-name} with
8799 square brackets. @var{macro-name} must have been defined using
8800 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
8801 that it has been called.
8803 @code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
8804 must not be called from the top level.
8807 @code{AC_REQUIRE} is often misunderstood. It really implements
8808 dependencies between macros in the sense that if one macro depends upon
8809 another, the latter will be expanded @emph{before} the body of the
8810 former. In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the
8811 body of @code{FOO}. For instance, this definition of macros:
8815 AC_DEFUN([TRAVOLTA],
8816 [test "$body_temperature_in_celsius" -gt "38" &&
8817 dance_floor=occupied])
8818 AC_DEFUN([NEWTON_JOHN],
8819 [test "$hair_style" = "curly" &&
8820 dance_floor=occupied])
8824 AC_DEFUN([RESERVE_DANCE_FLOOR],
8825 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
8826 AC_REQUIRE([TRAVOLTA])
8827 AC_REQUIRE([NEWTON_JOHN])
8833 with this @file{configure.ac}
8838 if test "$dance_floor" = occupied; then
8839 AC_MSG_ERROR([cannot pick up here, let's move])
8844 will not leave you with a better chance to meet a kindred soul at
8845 other times than Saturday night since it expands into:
8849 test "$body_temperature_in_Celsius" -gt "38" &&
8850 dance_floor=occupied
8851 test "$hair_style" = "curly" &&
8852 dance_floor=occupied
8854 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
8861 This behavior was chosen on purpose: (i) it prevents messages in
8862 required macros from interrupting the messages in the requiring macros;
8863 (ii) it avoids bad surprises when shell conditionals are used, as in:
8868 AC_REQUIRE([SOME_CHECK])
8876 You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a
8877 macro. You can use @code{dnl} to avoid the empty lines they leave.
8879 @node Suggested Ordering
8880 @subsection Suggested Ordering
8881 @cindex Macros, ordering
8882 @cindex Ordering macros
8884 Some macros should be run before another macro if both are called, but
8885 neither @emph{requires} that the other be called. For example, a macro
8886 that changes the behavior of the C compiler should be called before any
8887 macros that run the C compiler. Many of these dependencies are noted in
8890 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
8891 with this kind of dependency appear out of order in a
8892 @file{configure.ac} file. The warning occurs when creating
8893 @command{configure} from @file{configure.ac}, not when running
8894 @command{configure}.
8896 For example, @code{AC_PROG_CPP} checks whether the C compiler
8897 can run the C preprocessor when given the @option{-E} option. It should
8898 therefore be called after any macros that change which C compiler is
8899 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
8902 AC_BEFORE([$0], [AC_PROG_CPP])dnl
8906 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
8907 when @code{AC_PROG_CC} is called.
8909 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
8911 Make M4 print a warning message to the standard error output if
8912 @var{called-macro-name} has already been called. @var{this-macro-name}
8913 should be the name of the macro that is calling @code{AC_BEFORE}. The
8914 macro @var{called-macro-name} must have been defined using
8915 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
8916 that it has been called.
8919 @node Obsoleting Macros
8920 @section Obsoleting Macros
8921 @cindex Obsoleting macros
8922 @cindex Macros, obsoleting
8924 Configuration and portability technology has evolved over the years.
8925 Often better ways of solving a particular problem are developed, or
8926 ad-hoc approaches are systematized. This process has occurred in many
8927 parts of Autoconf. One result is that some of the macros are now
8928 considered @dfn{obsolete}; they still work, but are no longer considered
8929 the best thing to do, hence they should be replaced with more modern
8930 macros. Ideally, @command{autoupdate} should replace the old macro calls
8931 with their modern implementation.
8933 Autoconf provides a simple means to obsolete a macro.
8935 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
8938 Define @var{old-macro} as @var{implementation}. The only difference
8939 with @code{AC_DEFUN} is that the user will be warned that
8940 @var{old-macro} is now obsolete.
8942 If she then uses @command{autoupdate}, the call to @var{old-macro} will be
8943 replaced by the modern @var{implementation}. @command{autoupdate} will
8944 then print the additional @var{message}.
8948 @section Coding Style
8949 @cindex Coding style
8951 The Autoconf macros follow a strict coding style. You are encouraged to
8952 follow this style, especially if you intend to distribute your macro,
8953 either by contributing it to Autoconf itself, or via other means.
8955 The first requirement is to pay great attention to the quotation. For
8956 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
8958 Do not try to invent new interfaces. It is likely that there is a macro
8959 in Autoconf that resembles the macro you are defining: try to stick to
8960 this existing interface (order of arguments, default values, etc.). We
8961 @emph{are} conscious that some of these interfaces are not perfect;
8962 nevertheless, when harmless, homogeneity should be preferred over
8965 Be careful about clashes both between M4 symbols and between shell
8968 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
8969 you are unlikely to generate conflicts. Nevertheless, when you need to
8970 set a special value, @emph{avoid using a regular macro name}; rather,
8971 use an ``impossible'' name. For instance, up to version 2.13, the macro
8972 @code{AC_SUBST} used to remember what @var{symbol}s were already defined
8973 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
8974 But since there is a macro named @code{AC_SUBST_FILE}, it was just
8975 impossible to @samp{AC_SUBST(FILE)}! In this case,
8976 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
8977 have been used (yes, with the parentheses)@dots{}or better yet, high-level
8978 macros such as @code{AC_EXPAND_ONCE}.
8980 No Autoconf macro should ever enter the user-variable name space; i.e.,
8981 except for the variables that are the actual result of running the
8982 macro, all shell variables should start with @code{ac_}. In
8983 addition, small macros or any macro that is likely to be embedded in
8984 other macros should be careful not to use obvious names.
8987 Do not use @code{dnl} to introduce comments: most of the comments you
8988 are likely to write are either header comments which are not output
8989 anyway, or comments that should make their way into @file{configure}.
8990 There are exceptional cases where you do want to comment special M4
8991 constructs, in which case @code{dnl} is right, but keep in mind that it
8994 M4 ignores the leading spaces before each argument, use this feature to
8995 indent in such a way that arguments are (more or less) aligned with the
8996 opening parenthesis of the macro being called. For instance, instead of
8999 AC_CACHE_CHECK(for EMX OS/2 environment,
9001 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
9002 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
9009 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
9010 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
9012 [ac_cv_emxos2=no])])
9019 AC_CACHE_CHECK([for EMX OS/2 environment],
9021 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
9022 [return __EMX__;])],
9024 [ac_cv_emxos2=no])])
9027 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
9028 cross-compiling, provide a pessimistic value (typically @samp{no}).
9030 Feel free to use various tricks to prevent auxiliary tools, such as
9031 syntax-highlighting editors, from behaving improperly. For instance,
9035 m4_bpatsubst([$1], [$"])
9042 m4_bpatsubst([$1], [$""])
9046 so that Emacsen do not open an endless ``string'' at the first quote.
9047 For the same reasons, avoid:
9061 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
9062 breaking the bracket-matching highlighting from Emacsen. Note the
9063 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
9064 not escape when it is unnecessary. Common examples of useless quotation
9065 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
9066 etc. If you add portability issues to the picture, you'll prefer
9067 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
9068 better than hacking Autoconf @code{:-)}.
9070 When using @command{sed}, don't use @option{-e} except for indenting
9071 purpose. With the @code{s} command, the preferred separator is @samp{/}
9072 unless @samp{/} itself is used in the command, in which case you should
9075 @xref{Macro Definitions}, for details on how to define a macro. If a
9076 macro doesn't use @code{AC_REQUIRE} and it is expected to never be the
9077 object of an @code{AC_REQUIRE} directive, then use @code{m4_define}. In
9078 case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE}
9079 statements should be at the beginning of the macro, @code{dnl}'ed.
9081 You should not rely on the number of arguments: instead of checking
9082 whether an argument is missing, test that it is not empty. It provides
9083 both a simpler and a more predictable interface to the user, and saves
9084 room for further arguments.
9086 Unless the macro is short, try to leave the closing @samp{])} at the
9087 beginning of a line, followed by a comment that repeats the name of the
9088 macro being defined. This introduces an additional newline in
9089 @command{configure}; normally, that is not a problem, but if you want to
9090 remove it you can use @samp{[]dnl} on the last line. You can similarly
9091 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
9092 is recommended instead of @samp{dnl} to ensure that M4 does not
9093 interpret the @samp{dnl} as being attached to the preceding text or
9094 macro output. For example, instead of:
9097 AC_DEFUN([AC_PATH_X],
9098 [AC_MSG_CHECKING([for X])
9100 @r{# @dots{}omitted@dots{}}
9101 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
9109 AC_DEFUN([AC_PATH_X],
9110 [AC_REQUIRE_CPP()[]dnl
9111 AC_MSG_CHECKING([for X])
9112 @r{# @dots{}omitted@dots{}}
9113 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
9118 If the macro is long, try to split it into logical chunks. Typically,
9119 macros that check for a bug in a function and prepare its
9120 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
9121 this setup. Do not hesitate to introduce auxiliary macros to factor
9124 In order to highlight the recommended coding style, here is a macro
9125 written the old way:
9128 dnl Check for EMX on OS/2.
9130 AC_DEFUN(_AC_EMXOS2,
9131 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
9132 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
9133 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
9134 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
9143 # Check for EMX on OS/2.
9144 m4_define([_AC_EMXOS2],
9145 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
9146 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
9148 [ac_cv_emxos2=no])])
9149 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
9156 @c ============================================= Portable Shell Programming
9158 @node Portable Shell
9159 @chapter Portable Shell Programming
9160 @cindex Portable shell programming
9162 When writing your own checks, there are some shell-script programming
9163 techniques you should avoid in order to make your code portable. The
9164 Bourne shell and upward-compatible shells like the Korn shell and Bash
9165 have evolved over the years, but to prevent trouble, do not take
9166 advantage of features that were added after @sc{unix} version 7, circa
9167 1977 (@pxref{Systemology}).
9169 You should not use shell functions, aliases, negated character
9170 classes, or other features that are not found in all Bourne-compatible
9171 shells; restrict yourself to the lowest common denominator. Even
9172 @code{unset} is not supported by all shells! Also, include a space
9173 after the exclamation point in interpreter specifications, like this:
9180 If you omit the space before the path, then 4.2@acronym{BSD} based systems
9181 (such as DYNIX) will ignore the line, because they interpret
9182 @samp{#! /} as a 4-byte magic number. Some old systems have quite
9183 small limits on the length of the @samp{#!} line too, for instance 32
9184 bytes (not including the newline) on SunOS 4.
9186 The set of external programs you should run in a @command{configure} script
9187 is fairly small. @xref{Utilities in Makefiles,, Utilities in
9188 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
9189 restriction allows users to start out with a fairly small set of
9190 programs and build the rest, avoiding too many interdependencies between
9193 Some of these external utilities have a portable subset of features; see
9194 @ref{Limitations of Usual Tools}.
9196 There are other sources of documentation about shells. See for instance
9197 @href{http://www.faqs.org/faqs/unix-faq/shell/, the Shell FAQs}.
9200 * Shellology:: A zoology of shells
9201 * Here-Documents:: Quirks and tricks
9202 * File Descriptors:: FDs and redirections
9203 * File System Conventions:: File- and pathnames
9204 * Shell Substitutions:: Variable and command expansions
9205 * Assignments:: Varying side effects of assignments
9206 * Parentheses:: Parentheses in shell scripts
9207 * Special Shell Variables:: Variables you should not change
9208 * Limitations of Builtins:: Portable use of not so portable /bin/sh
9209 * Limitations of Usual Tools:: Portable use of portable tools
9210 * Limitations of Make:: Portable Makefiles
9217 There are several families of shells, most prominently the Bourne family
9218 and the C shell family which are deeply incompatible. If you want to
9219 write portable shell scripts, avoid members of the C shell family. The
9220 @href{http://www.faqs.org/faqs/unix-faq/shell/shell-differences/, the
9221 Shell difference FAQ} includes a small history of Unix shells, and a
9222 comparison between several of them.
9224 Below we describe some of the members of the Bourne shell family.
9229 @command{ash} is often used on @acronym{GNU}/Linux and @acronym{BSD}
9230 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
9231 bugs that are fixed in the 0.3.x series, but portable shell scripts
9232 should work around them, since version 0.2 is still shipped with many
9233 @acronym{GNU}/Linux distributions.
9235 To be compatible with Ash 0.2:
9239 don't use @samp{$?} after expanding empty or unset variables:
9245 echo "Don't use it: $?"
9249 don't use command substitution within variable expansion:
9256 beware that single builtin substitutions are not performed by a
9257 subshell, hence their effect applies to the current shell! @xref{Shell
9258 Substitutions}, item ``Command Substitution''.
9263 To detect whether you are running @command{bash}, test if
9264 @code{BASH_VERSION} is set. To disable its extensions and require
9265 @acronym{POSIX} compatibility, run @samp{set -o posix}. @xref{Bash POSIX
9266 Mode,, Bash @acronym{POSIX} Mode, bash, The @acronym{GNU} Bash Reference
9267 Manual}, for details.
9269 @item Bash 2.05 and later
9270 @cindex Bash 2.05 and later
9271 Versions 2.05 and later of @command{bash} use a different format for the
9272 output of the @command{set} builtin, designed to make evaluating its
9273 output easier. However, this output is not compatible with earlier
9274 versions of @command{bash} (or with many other shells, probably). So if
9275 you use @command{bash} 2.05 or higher to execute @command{configure},
9276 you'll need to use @command{bash} 2.05 for all other build tasks as well.
9282 @prindex @samp{ksh88}
9283 @prindex @samp{ksh93}
9284 The Korn shell is compatible with the Bourne family and it mostly
9285 conforms to @acronym{POSIX}. It has two major variants commonly
9286 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
9287 release. It is usually called @command{ksh}, but Solaris systems have
9289 @prindex @command{/usr/bin/ksh} on Solaris
9290 @command{/usr/bin/ksh} is @samp{ksh88},
9291 @prindex @command{/usr/xpg4/bin/sh} on Solaris
9292 @command{/usr/xpg4/bin/sh} is a @acronym{POSIX}-compliant variant of
9294 @prindex @command{/usr/dt/bin/dtksh} on Solaris
9295 @command{/usr/dt/bin/dtksh} is @samp{ksh93}. @command{/usr/bin/ksh}
9296 is standard on Solaris; the other variants are parts of optional
9297 packages. There is no extra charge for these packages, but they are
9298 not part of a minimal OS install and therefore some installations may
9300 @prindex @samp{pdksh}
9301 A public-domain clone of the Korn shell called @samp{pdksh} is also
9302 widely available: it has most of the @samp{ksh88} features along with
9307 To detect whether you are running @command{zsh}, test if
9308 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
9309 compatible with the Bourne shell: you have to run @samp{emulate sh} and
9310 set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility,
9311 zsh, The Z Shell Manual}, for details.
9313 Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3.
9316 The following discussion between Russ Allbery and Robert Lipe is worth
9323 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
9324 leads to a permanent deadlock. Vendors don't want to break users'
9325 existing shell scripts, and there are some corner cases in the Bourne
9326 shell that are not completely compatible with a @acronym{POSIX} shell. Thus,
9327 vendors who have taken this route will @emph{never} (OK@dots{}``never say
9328 never'') replace the Bourne shell (as @command{/bin/sh}) with a
9329 @acronym{POSIX} shell.
9336 This is exactly the problem. While most (at least most System V's) do
9337 have a Bourne shell that accepts shell functions most vendor
9338 @command{/bin/sh} programs are not the @acronym{POSIX} shell.
9340 So while most modern systems do have a shell @emph{somewhere} that meets the
9341 @acronym{POSIX} standard, the challenge is to find it.
9344 @node Here-Documents
9345 @section Here-Documents
9346 @cindex Here documents
9347 @cindex Shell here documents
9349 Don't rely on @samp{\} being preserved just because it has no special
9350 meaning together with the next symbol. In the native @command{/bin/sh}
9351 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
9352 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
9353 use @samp{\\} to get @samp{\}.
9355 With Open@acronym{BSD} 2.7's @command{/bin/sh}
9371 bash-2.04$ @kbd{cat <<EOF
9379 Many older shells (including the Bourne shell) implement here-documents
9380 inefficiently. And some shells mishandle large here-documents: for
9381 example, Solaris 8 @command{dtksh}, which is derived from
9382 @command{ksh} M-12/28/93d, mishandles variable expansion that occurs
9383 on 1024-byte buffer boundaries within a here-document. Users can
9384 generally fix these problems by using a faster or more reliable
9385 shell, e.g., by using the command @samp{bash ./configure} rather than
9386 plain @samp{./configure}.
9388 Some shells can be extremely inefficient when there are a lot of
9389 here-documents inside a single statement. For instance if your
9390 @file{configure.ac} includes something like:
9394 if <cross_compiling>; then
9395 assume this and that
9399 check something else
9407 A shell parses the whole @code{if}/@code{fi} construct, creating
9408 temporary files for each here document in it. Some shells create links
9409 for such here-documents on every @code{fork}, so that the clean-up code
9410 they had installed correctly removes them. It is creating the links
9411 that can take the shell forever.
9413 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
9414 @code{if}/@code{fi} constructs, would improve the performance
9415 significantly. Anyway, this kind of construct is not exactly the
9416 typical use of Autoconf. In fact, it's even not recommended, because M4
9417 macros can't look into shell conditionals, so we may fail to expand a
9418 macro when it was expanded before in a conditional path, and the
9419 condition turned out to be false at run-time, and we end up not
9420 executing the macro at all.
9422 @node File Descriptors
9423 @section File Descriptors
9425 @cindex File descriptors
9426 @cindex Shell file descriptors
9428 Some file descriptors shall not be used, since some systems, admittedly
9429 arcane, use them for special purpose:
9432 3 --- some systems may open it to @samp{/dev/tty}.
9433 4 --- used on the Kubota Titan.
9436 Don't redirect the same file descriptor several times, as you are doomed
9437 to failure under Ultrix.
9440 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
9442 $ @kbd{eval 'echo matter >fullness' >void}
9444 $ @kbd{eval '(echo matter >fullness)' >void}
9446 $ @kbd{(eval '(echo matter >fullness)') >void}
9447 Ambiguous output redirect.
9451 In each case the expected result is of course @file{fullness} containing
9452 @samp{matter} and @file{void} being empty.
9454 Don't try to redirect the standard error of a command substitution: it
9455 must be done @emph{inside} the command substitution: when running
9456 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
9457 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
9459 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
9460 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
9462 Most shells, if not all (including Bash, Zsh, Ash), output traces on
9463 stderr, even for sub-shells. This might result in undesirable content
9464 if you meant to capture the standard-error output of the inner command:
9467 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
9472 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
9474 + eval 'echo foo >&2'
9477 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
9478 @i{# Traces on startup files deleted here.}
9480 +zsh:1> eval echo foo >&2
9486 You'll appreciate the various levels of detail@enddots{}
9488 One workaround is to grep out uninteresting lines, hoping not to remove
9491 Don't try to move/delete open files, such as in @samp{exec >foo; mv foo
9492 bar}; see @ref{Limitations of Builtins}, @command{mv} for more details.
9494 @node File System Conventions
9495 @section File System Conventions
9496 @cindex File system conventions
9498 While @command{autoconf} and friends will usually be run on some Unix
9499 variety, it can and will be used on other systems, most notably @acronym{DOS}
9500 variants. This impacts several assumptions regarding file and
9504 For example, the following code:
9511 foo_dir=$dots$foo_dir ;;
9516 will fail to properly detect absolute paths on those systems, because
9517 they can use a drivespec, and will usually use a backslash as directory
9518 separator. The canonical way to check for absolute paths is:
9522 [\\/]* | ?:[\\/]* ) # Absolute
9525 foo_dir=$dots$foo_dir ;;
9530 Make sure you quote the brackets if appropriate and keep the backslash as
9531 first character (@pxref{Limitations of Builtins}).
9533 Also, because the colon is used as part of a drivespec, these systems don't
9534 use it as path separator. When creating or accessing paths, use the
9535 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
9536 to the appropriate value (@samp{:} or @samp{;}) when it starts up.
9538 File names need extra care as well. While @acronym{DOS}-based environments
9539 that are Unixy enough to run @command{autoconf} (such as DJGPP) will
9540 usually be able to handle long file names properly, there are still
9541 limitations that can seriously break packages. Several of these issues
9542 can be easily detected by the
9543 @href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
9546 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
9547 indicate where they apply: @sc{sfn} means the issues are only relevant to
9548 plain @acronym{DOS}, not to @acronym{DOS} boxes under Windows, while @sc{lfn}
9549 identifies problems that exist even under Windows.
9552 @item No multiple dots (@sc{sfn})
9553 @acronym{DOS} cannot handle multiple dots in filenames. This is an especially
9554 important thing to remember when building a portable configure script,
9555 as @command{autoconf} uses a .in suffix for template files.
9557 This is perfectly OK on Unices:
9560 AC_CONFIG_HEADERS([config.h])
9561 AC_CONFIG_FILES([source.c foo.bar])
9566 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
9567 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
9568 to @acronym{DOS}-based environments, you should use this instead:
9571 AC_CONFIG_HEADERS([config.h:config.hin])
9572 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
9576 @item No leading dot (@sc{sfn})
9577 @acronym{DOS} cannot handle filenames that start with a dot. This is usually
9578 not a very important issue for @command{autoconf}.
9580 @item Case insensitivity (@sc{lfn})
9581 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
9582 file called @samp{INSTALL} and a directory called @samp{install}. This
9583 also affects @command{make}; if there's a file called @samp{INSTALL} in
9584 the directory, @samp{make install} will do nothing (unless the
9585 @samp{install} target is marked as PHONY).
9587 @item The 8+3 limit (@sc{sfn})
9588 Because the @acronym{DOS} file system only stores the first 8 characters of
9589 the filename and the first 3 of the extension, those must be unique.
9590 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
9591 @file{foobar-prettybird.c} all resolve to the same filename
9592 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
9593 @file{foo.bartender}.
9595 Note: This is not usually a problem under Windows, as it uses numeric
9596 tails in the short version of filenames to make them unique. However, a
9597 registry setting can turn this behavior off. While this makes it
9598 possible to share file trees containing long file names between @sc{sfn}
9599 and @sc{lfn} environments, it also means the above problem applies there
9602 @item Invalid characters
9603 Some characters are invalid in @acronym{DOS} filenames, and should therefore
9604 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
9605 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
9606 In a @sc{sfn} environment, other characters are also invalid. These
9607 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
9610 @node Shell Substitutions
9611 @section Shell Substitutions
9612 @cindex Shell substitutions
9614 Contrary to a persistent urban legend, the Bourne shell does not
9615 systematically split variables and back-quoted expressions, in particular
9616 on the right-hand side of assignments and in the argument of @code{case}.
9617 For instance, the following code:
9620 case "$given_srcdir" in
9621 .) top_srcdir="`echo "$dots" | sed 's,/$,,'`"
9622 *) top_srcdir="$dots$given_srcdir" ;;
9627 is more readable when written as:
9630 case $given_srcdir in
9631 .) top_srcdir=`echo "$dots" | sed 's,/$,,'`
9632 *) top_srcdir=$dots$given_srcdir ;;
9637 and in fact it is even @emph{more} portable: in the first case of the
9638 first attempt, the computation of @code{top_srcdir} is not portable,
9639 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
9640 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
9641 the same way. There is just no portable way to use double-quoted
9642 strings inside double-quoted back-quoted expressions (pfew!).
9646 @cindex @samp{"$@@"}
9647 One of the most famous shell-portability issues is related to
9648 @samp{"$@@"}. When there are no positional arguments, @acronym{POSIX} says
9649 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
9650 original Unix Version 7 Bourne shell treated it as equivalent to
9651 @samp{""} instead, and this behavior survives in later implementations
9652 like Digital Unix 5.0.
9654 The traditional way to work around this portability problem is to use
9655 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
9656 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
9657 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
9660 zsh $ @kbd{emulate sh}
9661 zsh $ @kbd{for i in "$@@"; do echo $i; done}
9664 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
9671 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
9672 @samp{"$@@"} because of the portability problems mentioned above.
9673 One workaround relies on Zsh's ``global aliases'' to convert
9674 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
9677 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
9680 A more conservative workaround is to avoid @samp{"$@@"} if it is
9681 possible that there may be no positional arguments. For example,
9685 cat conftest.c "$@@"
9688 you can use this instead:
9693 *) cat conftest.c "$@@";;
9697 @item $@{@var{var}:-@var{value}@}
9698 @c Info cannot handle `:' in index entries.
9699 @c @cindex $@{@var{var}:-@var{value}@}
9700 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
9701 colon for any shell substitution, and complain and die.
9703 @item $@{@var{var}=@var{literal}@}
9704 @cindex $@{@var{var}=@var{literal}@}
9708 : $@{var='Some words'@}
9712 otherwise some shells, such as on Digital Unix V 5.0, will die because
9713 of a ``bad substitution''.
9717 Solaris' @command{/bin/sh} has a frightening bug in its interpretation
9718 of this. Imagine you need set a variable to a string containing
9719 @samp{@}}. This @samp{@}} character confuses Solaris' @command{/bin/sh}
9720 when the affected variable was already set. This bug can be exercised
9725 $ @kbd{foo=$@{foo='@}'@}}
9728 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
9731 $ @kbd{foo=$@{foo='@}'@}}
9737 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
9738 though it is enclosed in single quotes. The problem doesn't happen
9739 using double quotes.
9741 @item $@{@var{var}=@var{expanded-value}@}
9742 @cindex $@{@var{var}=@var{expanded-value}@}
9748 : $@{var="$default"@}
9752 will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
9753 each char will be set. You won't observe the phenomenon using a simple
9754 @samp{echo $var} since apparently the shell resets the 8th bit when it
9755 expands $var. Here are two means to make this shell confess its sins:
9767 $ @kbd{set | grep '^var=' | cat -v}
9770 One classic incarnation of this bug is:
9774 : $@{list="$default"@}
9781 You'll get @samp{a b c} on a single line. Why? Because there are no
9782 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
9783 bit set, hence no IFS splitting is performed!!!
9785 One piece of good news is that Ultrix works fine with @samp{:
9786 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
9787 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
9790 The portable way out consists in using a double assignment, to switch
9791 the 8th bit twice on Ultrix:
9794 list=$@{list="$default"@}
9798 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
9802 test "$@{var+set@}" = set || var=@var{@{value@}}
9806 @item `@var{commands}`
9807 @cindex `@var{commands}`
9808 @cindex Command Substitution
9809 While in general it makes no sense, do not substitute a single builtin
9810 with side effects, becauase Ash 0.2, trying to optimize, does not fork a
9811 subshell to perform the command.
9813 For instance, if you wanted to check that @command{cd} is silent, do not
9814 use @samp{test -z "`cd /`"} because the following can happen:
9819 $ @kbd{test -z "`cd /`" && pwd}
9824 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
9827 @item $(@var{commands})
9828 @cindex $(@var{commands})
9829 This construct is meant to replace @samp{`@var{commands}`}; they can be
9830 nested while this is impossible to do portably with back quotes.
9831 Unfortunately it is not yet widely supported. Most notably, even recent
9832 releases of Solaris don't support it:
9835 $ @kbd{showrev -c /bin/sh | grep version}
9836 Command version: SunOS 5.8 Generic 109324-02 February 2001
9837 $ @kbd{echo $(echo blah)}
9838 syntax error: `(' unexpected
9842 nor does @sc{irix} 6.5's Bourne shell:
9845 IRIX firebird-image 6.5 07151432 IP22
9846 $ @kbd{echo $(echo blah)}
9850 If you do use @samp{$(@var{commands})}, make sure that the commands
9851 do not start with a parenthesis, as that would cause confusion with
9852 a different notation @samp{$((@var{expression}))} that in modern
9853 shells is an arithmetic expression not a command. To avoid the
9854 confusion, insert a space between the two opening parentheses.
9860 @section Assignments
9861 @cindex Shell assignments
9863 When setting several variables in a row, be aware that the order of the
9864 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
9865 gives @samp{1} with sh on Solaris, but @samp{2} with Bash. You must use
9866 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
9868 Don't rely on the following to find @file{subdir/program}:
9871 PATH=subdir$PATH_SEPARATOR$PATH program
9875 as this does not work with Zsh 3.0.6. Use something like this
9879 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
9882 Don't rely on the exit status of an assignment: Ash 0.2 does not change
9883 the status and propagates that of the last statement:
9886 $ @kbd{false || foo=bar; echo $?}
9888 $ @kbd{false || foo=`:`; echo $?}
9893 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
9897 $ @kbd{foo=`exit 1`; echo $?}
9901 To assign default values, follow this algorithm:
9905 If the default value is a literal and does not contain any closing
9909 : $@{var='my literal'@}
9913 If the default value contains no closing brace, has to be expanded, and
9914 the variable being initialized will never be IFS-split (i.e., it's not a
9918 : $@{var="$default"@}
9922 If the default value contains no closing brace, has to be expanded, and
9923 the variable being initialized will be IFS-split (i.e., it's a list),
9927 var=$@{var="$default"@}
9931 If the default value contains a closing brace, then use:
9934 test "$@{var+set@}" = set || var='$@{indirection@}'
9938 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
9939 doubt, just use the latter. @xref{Shell Substitutions}, items
9940 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
9944 @section Parentheses in Shell Scripts
9945 @cindex Shell parentheses
9947 Beware of two opening parentheses in a row, as some shell
9948 implementations mishandle them. For example, @samp{pdksh} 5.2.14
9949 misparses the following code:
9952 if ((true) || false); then
9958 To work around this problem, insert a space between the two opening
9959 parentheses. There is a similar problem and workaround with
9960 @samp{$((}; see @ref{Shell Substitutions}.
9962 @acronym{POSIX} requires support for @code{case} patterns with opening
9963 parentheses like this:
9967 (*.c) echo "C source code";;
9972 but the @code{(} in this example is not portable to many older Bourne
9973 shell implementations. It can be omitted safely.
9975 @node Special Shell Variables
9976 @section Special Shell Variables
9977 @cindex Shell variables
9978 @cindex Special shell variables
9980 Some shell variables should not be used, since they can have a deep
9981 influence on the behavior of the shell. In order to recover a sane
9982 behavior from the shell, some variables should be unset, but
9983 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
9984 fallback value is needed. We list these values below.
9986 @c Alphabetical order, case insensitive, `A' before `a'.
9990 When this variable is set it specifies a list of directories to search
9991 when invoking @code{cd} with a relative filename. @acronym{POSIX}
9992 1003.1-2001 says that if a nonempty directory name from @code{CDPATH}
9993 is used successfully, @code{cd} prints the resulting absolute
9994 filename. Unfortunately this output can break idioms like
9995 @samp{abs=`cd src && pwd`} because @code{abs} receives the path twice.
9996 Also, many shells do not conform to this part of @acronym{POSIX}; for
9997 example, @command{zsh} prints the result only if a directory name
9998 other than @file{.} was chosen from @code{CDPATH}.
10000 In practice the shells that have this problem also support
10001 @command{unset}, so you can work around the problem as follows:
10004 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
10007 Autoconf-generated scripts automatically unset @code{CDPATH} if
10008 possible, so you need not worry about this problem in those scripts.
10012 Don't set the first character of @code{IFS} to backslash. Indeed,
10013 Bourne shells use the first character (backslash) when joining the
10014 components in @samp{"$@@"} and some shells then re-interpret (!) the
10015 backslash escapes, so you can end up with backspace and other strange
10018 The proper value for @code{IFS} (in regular code, not when performing
10019 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
10020 especially important, as it is used to join the arguments in @samp{@@*}.
10032 @evindex LC_COLLATE
10034 @evindex LC_MESSAGES
10035 @evindex LC_MONETARY
10036 @evindex LC_NUMERIC
10039 Autoconf-generated scripts normally set all these variables to
10040 @samp{C} because so much configuration code assumes the C locale and
10041 @acronym{POSIX} requires that locale environment variables be set to
10042 @samp{C} if the C locale is desired. However, some older, nonstandard
10043 systems (notably @acronym{SCO}) break if locale environment variables
10044 are set to @samp{C}, so when running on these systems
10045 Autoconf-generated scripts unset the variables instead.
10050 @env{LANGUAGE} is not specified by @acronym{POSIX}, but it is a @acronym{GNU}
10051 extension that overrides @env{LC_ALL} in some cases, so
10052 Autoconf-generated scripts set it too.
10055 @itemx LC_IDENTIFICATION
10056 @itemx LC_MEASUREMENT
10059 @itemx LC_TELEPHONE
10060 @evindex LC_ADDRESS
10061 @evindex LC_IDENTIFICATION
10062 @evindex LC_MEASUREMENT
10065 @evindex LC_TELEPHONE
10067 These locale environment variables are @acronym{GNU} extensions. They
10068 are treated like their @acronym{POSIX} brethren (@env{LC_COLLATE},
10069 etc.)@: as described above.
10073 Most modern shells provide the current line number in @code{LINENO}.
10074 Its value is the line number of the beginning of the current command.
10075 Autoconf attempts to execute @command{configure} with a modern shell.
10076 If no such shell is available, it attempts to implement @code{LINENO}
10077 with a Sed prepass that replaces each instance of the string
10078 @code{$LINENO} (not followed by an alphanumeric character) with the
10081 You should not rely on @code{LINENO} within @command{eval}, as the
10082 behavior differs in practice. Also, the possibility of the Sed
10083 prepass means that you should not rely on @code{$LINENO} when quoted,
10084 when in here-documents, or when in long commands that cross line
10085 boundaries. Subshells should be OK, though. In the following
10086 example, lines 1, 6, and 9 are portable, but the other instances of
10087 @code{LINENO} are not:
10097 ( echo 6. $LINENO )
10098 eval 'echo 7. $LINENO'
10104 $ @kbd{bash-2.05 lineno}
10115 $ @kbd{zsh-3.0.6 lineno}
10126 $ @kbd{pdksh-5.2.14 lineno}
10137 $ @kbd{sed '=' <lineno |}
10142 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
10145 > @kbd{ s,^[0-9]*\n,,}
10162 When executing the command @samp{>foo}, @command{zsh} executes
10163 @samp{$NULLCMD >foo}. The Bourne shell considers @code{NULLCMD} to be
10164 @samp{:}, while @command{zsh}, even in Bourne shell compatibility mode,
10165 sets @code{NULLCMD} to @samp{cat}. If you forgot to set @code{NULLCMD},
10166 your script might be suspended waiting for data on its standard input.
10180 These variables should not matter for shell scripts, since they are
10181 supposed to affect only interactive shells. However, at least one
10182 shell (the pre-3.0 @sc{uwin} @command{ksh}) gets confused about
10183 whether it is interactive, which means that (for example) a @env{PS1}
10184 with a side effect can unexpectedly modify @samp{$?}. To work around
10185 this bug, Autoconf-generated scripts do something like this:
10188 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
10196 @acronym{POSIX} 1003.1-2001 requires that @command{cd} and
10197 @command{pwd} must update the @env{PWD} environment variable to point
10198 to the logical path to the current directory, but traditional shells
10199 do not support this. This can cause confusion if one shell instance
10200 maintains @env{PWD} but a subsidiary and different shell does not know
10201 about @env{PWD} and executes @command{cd}; in this case @env{PWD} will
10202 point to the wrong directory. Use @samp{`pwd`} rather than
10207 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
10208 hence read-only. Do not use it.
10210 @item PATH_SEPARATOR
10211 @evindex PATH_SEPARATOR
10212 If it is not set, @command{configure} will detect the appropriate path
10213 separator for the build system and set the @code{PATH_SEPARATOR} output
10214 variable accordingly.
10216 On DJGPP systems, the @code{PATH_SEPARATOR} environment variable can be
10217 set to either @samp{:} or @samp{;} to control the path separator
10218 @command{bash} uses to set up certain environment variables (such as
10219 @code{PATH}). Since this only works inside @command{bash}, you want
10220 @command{configure} to detect the regular @acronym{DOS} path separator
10221 (@samp{;}), so it can be safely substituted in files that may not support
10222 @samp{;} as path separator. So it is recommended to either unset this
10223 variable or set it to @samp{;}.
10227 Many shells provide @code{RANDOM}, a variable that returns a different
10228 integer each time it is used. Most of the time, its value does not
10229 change when it is not used, but on @sc{irix} 6.5 the value changes all
10230 the time. This can be observed by using @command{set}.
10234 @node Limitations of Builtins
10235 @section Limitations of Shell Builtins
10236 @cindex Shell builtins
10237 @cindex Limitations of shell builtins
10239 No, no, we are serious: some shells do have limitations! :)
10241 You should always keep in mind that any builtin or command may support
10242 options, and therefore have a very different behavior with arguments
10243 starting with a dash. For instance, the innocent @samp{echo "$word"}
10244 can give unexpected results when @code{word} starts with a dash. It is
10245 often possible to avoid this problem using @samp{echo "x$word"}, taking
10246 the @samp{x} into account later in the pipe.
10250 @prindex @command{.}
10251 Use @command{.} only with regular files (use @samp{test -f}). Bash
10252 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
10253 @command{.} uses @env{PATH} if its argument contains no slashes, so if
10254 you want to use @command{.} on a file @file{foo} in the current
10255 directory, you must use @samp{. ./foo}.
10258 @prindex @command{!}
10259 You can't use @command{!}; you'll have to rewrite your code.
10262 @item @command{break}
10263 @c ------------------
10264 @prindex @command{break}
10265 The use of @samp{break 2} etc.@: is safe.
10269 @c ---------------------------------
10270 @prindex @command{cd}
10271 @acronym{POSIX} 1003.1-2001 requires that @command{cd} must support
10272 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
10273 with @option{-L} being the default. However, traditional shells do
10274 not support these options, and their @command{cd} command has the
10275 @option{-P} behavior.
10277 Portable scripts should assume neither option is supported, and should
10278 assume neither behavior is the default. This can be a bit tricky,
10279 since the @acronym{POSIX} default behavior means that, for example,
10280 @samp{ls ..} and @samp{cd ..} may refer to different directories if
10281 the current logical directory is a symbolic link. It is safe to use
10282 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
10283 Also, Autoconf-generated scripts check for this problem when computing
10284 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
10285 so it is safe to @command{cd} to these variables.
10287 Also please see the discussion of the @command{pwd} command.
10290 @item @command{case}
10291 @c -----------------
10292 @prindex @command{case}
10293 You don't need to quote the argument; no splitting is performed.
10295 You don't need the final @samp{;;}, but you should use it.
10297 Because of a bug in its @code{fnmatch}, @command{bash} fails to properly
10298 handle backslashes in character classes:
10301 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
10306 This is extremely unfortunate, since you are likely to use this code to
10307 handle @sc{unix} or @sc{ms-dos} absolute paths. To work around this
10308 bug, always put the backslash first:
10311 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
10313 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
10317 Some shells, such as Ash 0.3.8, are confused by an empty
10318 @code{case}/@code{esac}:
10321 ash-0.3.8 $ @kbd{case foo in esac;}
10322 @error{}Syntax error: ";" unexpected (expecting ")")
10325 Many shells still do not support parenthesized cases, which is a pity
10326 for those of us using tools that rely on balanced parentheses. For
10327 instance, Solaris 8's Bourne shell:
10330 $ @kbd{case foo in (foo) echo foo;; esac}
10331 @error{}syntax error: `(' unexpected
10335 @item @command{echo}
10336 @c -----------------
10337 @prindex @command{echo}
10338 The simple @code{echo} is probably the most surprising source of
10339 portability troubles. It is not possible to use @samp{echo} portably
10340 unless both options and escape sequences are omitted. New applications
10341 which are not aiming at portability should use @samp{printf} instead of
10344 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
10345 etc.@: for a means to simulate @option{-n}.
10347 Do not use backslashes in the arguments, as there is no consensus on
10348 their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of
10349 Digital Unix 4.0 and @acronym{MIPS RISC/OS} 4.52, answer 2, but the Solaris'
10350 @command{sh}, Bash, and Zsh (in @command{sh} emulation mode) report 1.
10351 Please note that the problem is truly @command{echo}: all the shells
10352 understand @samp{'\n'} as the string composed of a backslash and an
10355 Because of these problems, do not pass a string containing arbitrary
10356 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
10357 if you know that @var{foo}'s value cannot contain backslashes and cannot
10358 start with @samp{-}, but otherwise you should use a here-document like
10368 @item @command{exit}
10369 @c -----------------
10370 @prindex @command{exit}
10371 The default value of @command{exit} is supposed to be @code{$?};
10372 unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
10373 perform @samp{exit 0}.
10376 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
10378 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
10380 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
10384 Using @samp{exit $?} restores the expected behavior.
10386 Some shell scripts, such as those generated by @command{autoconf}, use a
10387 trap to clean up before exiting. If the last shell command exited with
10388 nonzero status, the trap also exits with nonzero status so that the
10389 invoker can tell that an error occurred.
10391 Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit
10392 trap ignores the @code{exit} command's argument. In these shells, a trap
10393 cannot determine whether it was invoked by plain @code{exit} or by
10394 @code{exit 1}. Instead of calling @code{exit} directly, use the
10395 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
10398 @item @command{export}
10399 @c -------------------
10400 @prindex @command{export}
10401 The builtin @command{export} dubs a shell variable @dfn{environment
10402 variable}. Each update of exported variables corresponds to an update
10403 of the environment variables. Conversely, each environment variable
10404 received by the shell when it is launched should be imported as a shell
10405 variable marked as exported.
10407 Alas, many shells, such as Solaris 2.5, @sc{irix} 6.3, @sc{irix} 5.2,
10408 @acronym{AIX} 4.1.5, and Digital @sc{unix} 4.0, forget to
10409 @command{export} the environment variables they receive. As a result,
10410 two variables coexist: the environment variable and the shell
10411 variable. The following code demonstrates this failure:
10422 when run with @samp{FOO=foo} in the environment, these shells will print
10423 alternately @samp{foo} and @samp{bar}, although it should only print
10424 @samp{foo} and then a sequence of @samp{bar}s.
10426 Therefore you should @command{export} again each environment variable
10430 @item @command{false}
10431 @c ------------------
10432 @prindex @command{false}
10433 Don't expect @command{false} to exit with status 1: in the native Bourne
10434 shell of Solaris 8 it exits with status 255.
10437 @item @command{for}
10438 @c ----------------
10439 @prindex @command{for}
10440 To loop over positional arguments, use:
10450 You may @emph{not} leave the @code{do} on the same line as @code{for},
10451 since some shells improperly grok:
10459 If you want to explicitly refer to the positional arguments, given the
10460 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
10463 for arg in $@{1+"$@@"@}; do
10469 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
10470 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
10471 item @samp{$@@}, for more.
10476 @prindex @command{if}
10477 Using @samp{!} is not portable. Instead of:
10480 if ! cmp -s file file.new; then
10489 if cmp -s file file.new; then :; else
10494 There are shells that do not reset the exit status from an @command{if}:
10497 $ @kbd{if (exit 42); then true; fi; echo $?}
10502 whereas a proper shell should have printed @samp{0}. This is especially
10503 bad in Makefiles since it produces false failures. This is why properly
10504 written Makefiles, such as Automake's, have such hairy constructs:
10507 if test -f "$file"; then
10508 install "$file" "$dest"
10515 @item @command{printf}
10516 @c ------------------
10517 @prindex @command{printf}
10518 A format string starting with a @samp{-} can cause problems.
10519 @command{bash} (eg. 2.05b) will interpret it as an options string and
10520 give an error. And @samp{--} to mark the end of options is not good
10521 in the NetBSD Almquist shell (eg. 0.4.6) which will take that
10522 literally as the format string. Putting the @samp{-} in a @samp{%c}
10523 or @samp{%s} is probably the easiest way to avoid doubt,
10530 @item @command{pwd}
10531 @c ----------------
10532 @prindex @command{pwd}
10533 With modern shells, plain @command{pwd} outputs a ``logical''
10534 directory name, some of whose components may be symbolic links. These
10535 directory names are in contrast to ``physical'' directory names, whose
10536 components are all directories.
10538 @acronym{POSIX} 1003.1-2001 requires that @command{pwd} must support
10539 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
10540 with @option{-L} being the default. However, traditional shells do
10541 not support these options, and their @command{pwd} command has the
10542 @option{-P} behavior.
10544 Portable scripts should assume neither option is supported, and should
10545 assume neither behavior is the default. Also, on many hosts
10546 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but @acronym{POSIX}
10547 does not require this behavior and portable scripts should not rely on
10550 Typically it's best to use plain @command{pwd}. On modern hosts this
10551 outputs logical directory names, which have the following advantages:
10555 Logical names are what the user specified.
10557 Physical names may not be portable from one installation
10558 host to another due to network filesystem gymnastics.
10560 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
10561 some parent directory, but plain @command{pwd} cannot fail for this
10565 Also please see the discussion of the @command{cd} command.
10568 @item @command{set}
10569 @c ----------------
10570 @prindex @command{set}
10571 This builtin faces the usual problem with arguments starting with a
10572 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
10573 the end of the options (any argument after @option{--} is a parameter,
10574 even @samp{-x} for instance), but most shells simply stop the option
10575 processing as soon as a non-option argument is found. Therefore, use
10576 @samp{dummy} or simply @samp{x} to end the option processing, and use
10577 @command{shift} to pop it out:
10580 set x $my_list; shift
10583 Some shells have the "opposite" problem of not recognizing all options
10584 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
10585 better to elide these:
10592 @item @command{shift}
10593 @c ------------------
10594 @prindex @command{shift}
10595 Not only is @command{shift}ing a bad idea when there is nothing left to
10596 shift, but in addition it is not portable: the shell of @acronym{MIPS
10597 RISC/OS} 4.52 refuses to do it.
10600 @item @command{source}
10601 @c -------------------
10602 @prindex @command{source}
10603 This command is not portable, as @acronym{POSIX} does not require it; use
10604 @command{.} instead.
10607 @item @command{test}
10608 @c -----------------
10609 @prindex @command{test}
10610 The @code{test} program is the way to perform many file and string
10611 tests. It is often invoked by the alternate name @samp{[}, but using
10612 that name in Autoconf code is asking for trouble since it is an M4 quote
10615 If you need to make multiple checks using @code{test}, combine them with
10616 the shell operators @samp{&&} and @samp{||} instead of using the
10617 @code{test} operators @option{-a} and @option{-o}. On System V, the
10618 precedence of @option{-a} and @option{-o} is wrong relative to the unary
10619 operators; consequently, @acronym{POSIX} does not specify them, so using them
10620 is nonportable. If you combine @samp{&&} and @samp{||} in the same
10621 statement, keep in mind that they have equal precedence.
10623 You may use @samp{!} with @command{test}, but not with @command{if}:
10624 @samp{test ! -r foo || exit 1}.
10627 @item @command{test} (files)
10628 @c -------------------------
10629 To enable @command{configure} scripts to support cross-compilation, they
10630 shouldn't do anything that tests features of the build system instead of
10631 the host system. But occasionally you may find it necessary to check
10632 whether some arbitrary file exists. To do so, use @samp{test -f} or
10633 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
10634 have it. Do not use @samp{test -e} either, because Solaris 2.5 does not
10635 have it. To test for symbolic links on systems that have them, use
10636 @samp{test -h} rather than @samp{test -L}; either form conforms to
10637 @acronym{POSIX} 1003.1-2001, but older shells like Solaris 8
10638 @code{/bin/sh} support only @option{-h}.
10640 @item @command{test} (strings)
10641 @c ---------------------------
10642 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
10643 start with a dash, since @code{test} might interpret its argument as an
10644 option (e.g., @samp{@var{string} = "-n"}).
10646 Contrary to a common belief, @samp{test -n @var{string}} and
10647 @samp{test -z @var{string}} @strong{are} portable. Nevertheless many
10648 shells (such as Solaris 2.5, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
10649 Digital Unix 4 etc.) have bizarre precedence and may be confused if
10650 @var{string} looks like an operator:
10654 test: argument expected
10657 If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
10658 "x@var{string}" != x} instead.
10660 It is common to find variations of the following idiom:
10663 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
10668 to take an action when a token matches a given pattern. Such constructs
10669 should always be avoided by using:
10672 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
10677 Use @code{case} where possible since it is faster, being a shell builtin:
10681 case $ac_feature in
10682 *[!-a-zA-Z0-9_]*) @var{action};;
10686 Alas, negated character classes are probably not portable, although no
10687 shell is known to not support the @acronym{POSIX} syntax @samp{[!@dots{}]}
10688 (when in interactive mode, @command{zsh} is confused by the
10689 @samp{[!@dots{}]} syntax and looks for an event in its history because of
10690 @samp{!}). Many shells do not support the alternative syntax
10691 @samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
10693 One solution can be:
10696 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
10704 expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
10708 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
10709 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
10710 @samp{@var{foo}} contains backslashes.
10713 @item @command{trap}
10714 @c -----------------
10715 @prindex @command{trap}
10716 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
10717 trap 0, i.e., have the @command{trap} run when the script ends (either via an
10718 explicit @command{exit}, or the end of the script).
10720 Although @acronym{POSIX} is not absolutely clear on this point, it is widely
10721 admitted that when entering the trap @samp{$?} should be set to the exit
10722 status of the last command run before the trap. The ambiguity can be
10723 summarized as: ``when the trap is launched by an @command{exit}, what is
10724 the @emph{last} command run: that before @command{exit}, or
10725 @command{exit} itself?''
10727 Bash considers @command{exit} to be the last command, while Zsh and
10728 Solaris 8 @command{sh} consider that when the trap is run it is
10729 @emph{still} in the @command{exit}, hence it is the previous exit status
10730 that the trap receives:
10733 $ @kbd{cat trap.sh}
10736 $ @kbd{zsh trap.sh}
10738 $ @kbd{bash trap.sh}
10742 The portable solution is then simple: when you want to @samp{exit 42},
10743 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
10744 set the exit status to 42 for Zsh, and the second to trigger the trap
10745 and pass 42 as exit status for Bash.
10747 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
10748 reset to 0 by empty lines if the code is inside @command{trap}.
10751 $ @kbd{trap 'false}
10759 Fortunately, this bug only affects @command{trap}.
10761 @item @command{true}
10762 @c -----------------
10763 @prindex @command{true}
10764 @c Info cannot handle `:' in index entries.
10765 @c @prindex @command{:}
10766 Don't worry: as far as we know @command{true} is portable.
10767 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
10768 portable shell community tends to prefer using @command{:}. This has a
10769 funny side effect: when asked whether @command{false} is more portable
10770 than @command{true} Alexandre Oliva answered:
10773 In a sense, yes, because if it doesn't exist, the shell will produce an
10774 exit status of failure, which is correct for @command{false}, but not
10775 for @command{true}.
10779 @item @command{unset}
10780 @c ------------------
10781 @prindex @command{unset}
10782 You cannot assume the support of @command{unset}. Nevertheless, because
10783 it is extremely useful to disable embarrassing variables such as
10784 @code{PS1}, you can test for its existence and use
10785 it @emph{provided} you give a neutralizing value when @command{unset} is
10789 if (unset FOO) >/dev/null 2>&1; then
10794 $unset PS1 || PS1='$ '
10797 @xref{Special Shell Variables}, for some neutralizing values. Also, see
10798 @ref{Limitations of Builtins}, documentation of @command{export}, for
10799 the case of environment variables.
10802 @node Limitations of Usual Tools
10803 @section Limitations of Usual Tools
10804 @cindex Limitations of usual tools
10806 The small set of tools you can expect to find on any machine can still
10807 include some limitations you should be aware of.
10810 @item @command{awk}
10811 @c ----------------
10812 @prindex @command{awk}
10813 Don't leave white spaces before the parentheses in user functions calls;
10814 @acronym{GNU} awk will reject it:
10817 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
10818 BEGIN @{ die () @}'}
10819 gawk: cmd. line:2: BEGIN @{ die () @}
10820 gawk: cmd. line:2: ^ parse error
10821 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
10822 BEGIN @{ die() @}'}
10826 If you want your program to be deterministic, don't depend on @code{for}
10830 $ @kbd{cat for.awk}
10837 $ @kbd{gawk -f for.awk </dev/null}
10840 $ @kbd{nawk -f for.awk </dev/null}
10845 Some AWK, such as HPUX 11.0's native one, have regex engines fragile to
10849 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
10850 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
10852 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
10854 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
10859 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
10860 or use a simple test to reject such AWK@.
10863 @item @command{cat}
10864 @c ----------------
10865 @prindex @command{cat}
10866 Don't rely on any option. The option @option{-v}, which displays
10867 non-printing characters, @emph{seems} portable, though.
10872 @prindex @command{cc}
10873 The command @samp{cc -c foo.c} traditionally produces an object file
10874 named @file{foo.o}. Most compilers allow @option{-c} to be combined
10875 with @option{-o} to specify a different object file name, but
10876 @acronym{POSIX} does not require this combination and a few compilers
10877 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
10878 tests for this feature with @code{AC_PROG_CC_C_O}.
10880 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
10881 (such as @sc{cds} on Reliant @sc{unix}) leave a @file{foo.o}.
10883 HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and
10884 assemble. @samp{cc -c foo.S} will appear to succeed, but in fact does
10887 The default executable, produced by @samp{cc foo.c}, can be
10890 @item @file{a.out} --- usual Unix convention.
10891 @item @file{b.out} --- i960 compilers (including @command{gcc}).
10892 @item @file{a.exe} --- DJGPP port of @command{gcc}.
10893 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
10894 @item @file{foo.exe} --- various MS-DOS compilers.
10897 The C compiler's traditional name is @command{cc}, but other names like
10898 @command{gcc} are common. @acronym{POSIX} 1003.1-2001 specifies the
10899 name @command{c99}, but older @acronym{POSIX} editions specified
10900 @command{c89} and anyway these standard names are rarely used in
10901 practice. Typically the C compiler is invoked from makefiles that use
10902 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
10906 @item @command{chmod}
10907 @c ------------------
10908 @prindex @command{chmod}
10909 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
10910 instead, for two reasons. First, plain @samp{-w} does not necessarily
10911 make the file unwriteable, since it does not affect mode bits that
10912 correspond to bits in the file mode creation mask. Second,
10913 @acronym{POSIX} says that the @samp{-w} might be interpreted as an
10914 implementation-specific option, not as a mode; @acronym{POSIX} suggests
10915 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
10916 @samp{--} does not work on some older hosts.
10919 @item @command{cmp}
10920 @c ----------------
10921 @prindex @command{cmp}
10922 @command{cmp} performs a raw data comparison of two files, while
10923 @command{diff} compares two text files. Therefore, if you might compare
10924 DOS files, even if only checking whether two files are different, use
10925 @command{diff} to avoid spurious differences due to differences of
10931 @prindex @command{cp}
10932 @cindex timestamp resolution
10933 Traditionally, file timestamps had 1-second resolution, and @samp{cp
10934 -p} copied the timestamps exactly. However, many modern filesystems
10935 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
10936 -p} implementations truncate timestamps when copying files, so this
10937 can result in the destination file appearing to be older than the
10938 source. The exact amount of truncation depends on the resolution of
10939 the system calls that @command{cp} uses; traditionally this was
10940 @code{utime}, which has 1-second resolution, but some newer
10941 @command{cp} implementations use @code{utimes}, which has
10942 1-microsecond resolution. These newer implementations include GNU
10943 coreutils 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
10944 later. Unfortunately as of September 2003 there is still no system
10945 call to set time stamps to the full nanosecond resolution.
10947 @c This is thanks to Ian.
10948 SunOS @command{cp} does not support @option{-f}, although its
10949 @command{mv} does. It's possible to deduce why @command{mv} and
10950 @command{cp} are different with respect to @option{-f}. @command{mv}
10951 prompts by default before overwriting a read-only file. @command{cp}
10952 does not. Therefore, @command{mv} requires a @option{-f} option, but
10953 @command{cp} does not. @command{mv} and @command{cp} behave differently
10954 with respect to read-only files because the simplest form of
10955 @command{cp} cannot overwrite a read-only file, but the simplest form of
10956 @command{mv} can. This is because @command{cp} opens the target for
10957 write access, whereas @command{mv} simply calls @code{link} (or, in
10958 newer systems, @code{rename}).
10959 @c Ian said: ``I don't think -p or -r are portable''!!! How can you live
10962 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
10963 ownerships. But whether it actually does copy ownerships or not is a
10964 system dependent policy decision implemented by the kernel. If the
10965 kernel allows it then it happens. If the kernel does not allow it then
10966 it does not happen. It is not something @command{cp} itself has control
10969 In SysV any user can chown files to any other user, and SysV also had a
10970 non-sticky @file{/tmp}. That undoubtedly derives from the heritage of
10971 SysV in a business environment without hostile users. BSD changed this
10972 to be a more secure model where only root can @command{chown} files and
10973 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
10974 of BSD in a campus environment.
10976 Linux by default follows BSD, but it can be configured to allow
10977 @command{chown}. HP-UX as an alternate example follows SysV, but it can
10978 be configured to use the modern security model and disallow
10979 @command{chown}. Since it is an administrator configurable parameter
10980 you can't use the name of the kernel as an indicator of the behavior.
10984 @item @command{date}
10985 @c -----------------
10986 @prindex @command{date}
10987 Some versions of @command{date} do not recognize special % directives,
10988 and unfortunately, instead of complaining, they just pass them through,
10989 and exit with success:
10993 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
10999 @item @command{diff}
11000 @c -----------------
11001 @prindex @command{diff}
11002 Option @option{-u} is nonportable.
11004 Some implementations, such as Tru64's, fail when comparing to
11005 @file{/dev/null}. Use an empty file instead.
11008 @item @command{dirname}
11009 @c --------------------
11010 @prindex @command{dirname}
11011 Not all hosts have a working @command{dirname}, and you should instead
11012 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
11015 dir=`dirname "$file"` # This is not portable.
11016 dir=`AS_DIRNAME(["$file"])` # This is more portable.
11020 This handles a few subtleties in the standard way required by
11021 @acronym{POSIX}. For example, under UN*X, should @samp{dirname //1} give
11022 @samp{/}? Paul Eggert answers:
11025 No, under some older flavors of Unix, leading @samp{//} is a special
11026 path name: it refers to a ``super-root'' and is used to access other
11027 machines' files. Leading @samp{///}, @samp{////}, etc.@: are equivalent
11028 to @samp{/}; but leading @samp{//} is special. I think this tradition
11029 started with Apollo Domain/OS, an OS that is still in use on some older
11032 @acronym{POSIX} allows but does not require the special treatment for
11033 @samp{//}. It says that the behavior of dirname on path names of the
11034 form @samp{//([^/]+/*)?} is implementation defined. In these cases,
11035 @acronym{GNU} @command{dirname} returns @samp{/}, but it's more
11036 portable to return @samp{//} as this works even on those older flavors
11041 @item @command{egrep}
11042 @c ------------------
11043 @prindex @command{egrep}
11044 @acronym{POSIX} 1003.1-2001 no longer requires @command{egrep},
11045 but many older hosts do not yet support the @acronym{POSIX}
11046 replacement @code{grep -E}. To work around this problem, invoke
11047 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
11049 The empty alternative is not portable, use @samp{?} instead. For
11050 instance with Digital Unix v5.0:
11053 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
11055 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
11057 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
11062 @command{$EGREP} also suffers the limitations of @command{grep}.
11064 @item @command{expr}
11065 @c -----------------
11066 @prindex @command{expr}
11067 No @command{expr} keyword starts with @samp{x}, so use @samp{expr
11068 x"@var{word}" : 'x@var{regex}'} to keep @command{expr} from
11069 misinterpreting @var{word}.
11071 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
11073 @item @command{expr} (@samp{|})
11074 @prindex @command{expr} (@samp{|})
11075 You can use @samp{|}. Although @acronym{POSIX} does require that @samp{expr
11076 ''} return the empty string, it does not specify the result when you
11077 @samp{|} together the empty string (or zero) with the empty string. For
11084 @acronym{GNU}/Linux and @acronym{POSIX}.2-1992 return the empty string
11085 for this case, but traditional @sc{unix} returns @samp{0} (Solaris is
11086 one such example). In @acronym{POSIX}.1-2001, the specification has
11087 been changed to match traditional @sc{unix}'s behavior (which is
11088 bizarre, but it's too late to fix this). Please note that the same
11089 problem does arise when the empty string results from a computation,
11093 expr bar : foo \| foo : bar
11097 Avoid this portability problem by avoiding the empty string.
11100 @item @command{expr} (@samp{:})
11101 @c ----------------------------
11102 @prindex @command{expr}
11103 Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, as they are
11104 not supported on Solaris.
11106 The @acronym{POSIX} standard is ambiguous as to whether
11107 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
11108 In practice, it outputs the empty string on most platforms, but portable
11109 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
11110 @command{expr} returns @samp{0}.
11112 One might think that a way to get a uniform behavior would be to use
11113 the empty string as a default value:
11116 expr a : '\(b\)' \| ''
11120 Unfortunately this behaves exactly as the original expression; see the
11121 @samp{@command{expr} (@samp{:})} entry for more information.
11123 Older @command{expr} implementations (e.g., SunOS 4 @command{expr} and
11124 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
11125 @command{expr} to fail if the matched substring is longer than 120
11126 bytes. In this case, you might want to fall back on @samp{echo|sed} if
11127 @command{expr} fails.
11129 Don't leave, there is some more!
11131 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
11132 the empty string, has a funny behavior in its exit status: it's always 1
11133 when parentheses are used!
11136 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
11138 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
11141 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
11143 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
11148 In practice this can be a big problem if you are ready to catch failures
11149 of @command{expr} programs with some other method (such as using
11150 @command{sed}), since you may get twice the result. For instance
11153 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
11157 will output @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
11158 simple workaround consists in testing @command{expr} and use a variable
11159 set to @command{expr} or to @command{false} according to the result.
11162 @item @command{fgrep}
11163 @c ------------------
11164 @prindex @command{fgrep}
11165 @acronym{POSIX} 1003.1-2001 no longer requires @command{fgrep},
11166 but many older hosts do not yet support the @acronym{POSIX}
11167 replacement @code{grep -F}. To work around this problem, invoke
11168 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
11171 @item @command{find}
11172 @c -----------------
11173 @prindex @command{find}
11174 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
11175 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris 2.5 @command{find}
11176 commands do not understand it.
11178 The replacement of @samp{@{@}} is guaranteed only if the argument is
11179 exactly @emph{@{@}}, not if it's only a part of an argument. For
11180 instance on DU, and HP-UX 10.20 and HP-UX 11:
11184 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
11189 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
11192 @item @command{grep}
11193 @c -----------------
11194 @prindex @command{grep}
11195 Don't use @samp{grep -s} to suppress output, because @samp{grep -s} on
11196 System V does not suppress output, only error messages. Instead,
11197 redirect the standard output and standard error (in case the file
11198 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
11199 status of @code{grep} to determine whether it found a match.
11201 Don't use multiple regexps with @option{-e}, as some @code{grep} will only
11202 honor the last pattern (e.g., @sc{irix} 6.5 and Solaris 2.5.1). Anyway,
11203 Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{} Instead, use
11204 extended regular expressions and alternation.
11206 Don't rely on @option{-w}, as Irix 6.5.16m's @command{grep} does not
11212 @prindex @command{ln}
11213 @cindex Symbolic links
11214 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
11215 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
11217 For versions of the DJGPP before 2.04, @command{ln} emulates soft links
11218 to executables by generating a stub that in turn calls the real
11219 program. This feature also works with nonexistent files like in the
11220 Unix spec. So @samp{ln -s file link} will generate @file{link.exe},
11221 which will attempt to call @file{file.exe} if run. But this feature only
11222 works for executables, so @samp{cp -p} is used instead for these
11223 systems. DJGPP versions 2.04 and later have full symlink support.
11228 @prindex @command{ls}
11229 @cindex Listing directories
11230 The portable options are @option{-acdilrtu}. Modern practice is for
11231 @option{-l} to output both owner and group, but traditional
11232 @command{ls} omits the group.
11234 @c From Bruce Lilly:
11238 @c UNIX System V (TWG-TCP/IP) (dim.blilly.com)
11242 @c $ /bin/ls a.exe 2>/dev/null
11246 @c fndcmd:fndcmd.sl 1.68
11248 @c UNIX dim SYSTEM5 3.51m mc68k
11250 @c It's an AT&T 3B1. See http://www.faqs.org/faqs/3b1-faq/ or any
11251 @c mirror of the 3B1 FAQ. It's actually SVR2.2.
11252 Modern practice is for all diagnostics to go to standard error, but
11253 traditional @samp{ls foo} prints the message @samp{foo not found} to
11254 standard output if @file{foo} does not exist. Be careful when writing
11255 shell commands like @samp{sources=`ls *.c 2>/dev/null`}, since with
11256 traditional @command{ls} this is equivalent to @samp{sources="*.c not
11257 found"} if there are no @samp{.c} files.
11260 @item @command{mkdir}
11261 @c ------------------
11262 @prindex @command{mkdir}
11263 @cindex Making directories
11264 None of @command{mkdir}'s options are portable to older systems. Instead of
11265 @samp{mkdir -p @var{filename}}, you should use use
11266 @code{AS_MKDIR_P(@var{filename})} (@pxref{Programming in M4sh}).
11268 @acronym{POSIX} does not clearly specify whether @samp{mkdir -p foo}
11269 should succeed when @file{foo} is a symbolic link to an already-existing
11270 directory. GNU Coreutils 5.1.0 @command{mkdir} succeeds, but Solaris 9
11271 @command{mkdir} fails.
11275 @prindex @command{mv}
11276 @cindex Moving open files
11277 The only portable options are @option{-f} and @option{-i}.
11279 Moving individual files between file systems is portable (it was in V6),
11280 but it is not always atomic: when doing @samp{mv new existing}, there's
11281 a critical section where neither the old nor the new version of
11282 @file{existing} actually exists.
11284 Be aware that moving files from @file{/tmp} can sometimes cause
11285 undesirable (but perfectly valid) warnings, even if you created these
11286 files. On some systems, creating the file in @file{/tmp} is setting a
11287 guid @code{wheel} which you may not be part of. So the file is copied,
11288 and then the @code{chgrp} fails:
11291 $ @kbd{touch /tmp/foo}
11292 $ @kbd{mv /tmp/foo .}
11293 @error{}mv: ./foo: set owner/group (was: 3830/0): Operation not permitted
11301 This behavior conforms to @acronym{POSIX}:
11304 If the duplication of the file characteristics fails for any reason, mv
11305 shall write a diagnostic message to standard error, but this failure
11306 shall not cause mv to modify its exit status.''
11309 Moving directories across mount points is not portable, use @command{cp}
11312 Moving/Deleting open files isn't portable. The following can't be done
11328 @item @command{sed}
11329 @c ----------------
11330 @prindex @command{sed}
11331 Patterns should not include the separator (unless escaped), even as part
11332 of a character class. In conformance with @acronym{POSIX}, the Cray
11333 @command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
11335 Sed scripts should not use branch labels longer than 8 characters and
11336 should not contain comments.
11338 Don't include extra @samp{;}, as some @command{sed}, such as Net@acronym{BSD}
11339 1.4.2's, try to interpret the second as a command:
11342 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
11343 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
11346 Input should have reasonably long lines, since some @command{sed} have
11347 an input buffer limited to 4000 bytes.
11349 Alternation, @samp{\|}, is common but @acronym{POSIX} does not require its
11350 support, so it should be avoided in portable scripts. Solaris 8
11351 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
11352 deletes only lines that contain the literal string @samp{a|b}.
11354 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
11356 Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
11357 quite portable to modern hosts, but is not supported by some older
11358 @command{sed} implementations like SVR3.
11360 Of course the option @option{-e} is portable, but it is not needed. No
11361 valid Sed program can start with a dash, so it does not help
11362 disambiguating. Its sole usefulness is to help enforcing indentation as
11366 sed -e @var{instruction-1} \
11367 -e @var{instruction-2}
11374 sed @var{instruction-1};@var{instruction-2}
11377 Contrary to yet another urban legend, you may portably use @samp{&} in
11378 the replacement part of the @code{s} command to mean ``what was
11379 matched''. All descendants of Bell Lab's V7 @command{sed} (at least; we
11380 don't have first hand experience with older @command{sed}s) have
11383 @acronym{POSIX} requires that you must not have any white space between
11384 @samp{!} and the following command. It is OK to have blanks between
11385 the address and the @samp{!}. For instance, on Solaris 8:
11388 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
11389 @error{}Unrecognized command: /bar/ ! p
11390 $ @kbd{echo "foo" | sed -n '/bar/! p'}
11391 @error{}Unrecognized command: /bar/! p
11392 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
11396 @item @command{sed} (@samp{t})
11397 @c ---------------------------
11398 @prindex @command{sed} (@samp{t})
11399 Some old systems have @command{sed} that ``forget'' to reset their
11400 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
11401 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
11402 script (the line numbers are not actual part of the texts):
11405 s/keep me/kept/g # a
11441 Why? When processing 1, a matches, therefore sets the t flag, b jumps to
11442 d, and the output is produced. When processing line 2, the t flag is
11443 still set (this is the bug). Line a fails to match, but @command{sed}
11444 is not supposed to clear the t flag when a substitution fails. Line b
11445 sees that the flag is set, therefore it clears it, and jumps to d, hence
11446 you get @samp{delete me} instead of @samp{deleted}. When processing 3, t
11447 is clear, a matches, so the flag is set, hence b clears the flags and
11448 jumps. Finally, since the flag is clear, 4 is processed properly.
11450 There are two things one should remember about @samp{t} in @command{sed}.
11451 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
11452 succeeded, not only the immediately preceding substitution. Therefore,
11453 always use a fake @samp{t clear; : clear} to reset the t flag where
11456 Secondly, you cannot rely on @command{sed} to clear the flag at each new
11459 One portable implementation of the script above is:
11470 @item @command{touch}
11471 @c ------------------
11472 @prindex @command{touch}
11473 @cindex timestamp resolution
11474 If you specify the desired timestamp (e.g., with the @option{-r}
11475 option), @command{touch} typically uses the @code{utime} or
11476 @code{utimes} system call, which can result in the same kind of
11477 timestamp truncation problems that @samp{cp -p} has.
11479 On some old @acronym{BSD} systems, @command{touch} or any command that
11480 results in an empty file does not update the timestamps, so use a
11481 command like @code{echo} as a workaround.
11483 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
11484 fails to work on SunOS 4.1.3 when the empty file is on an
11485 @acronym{NFS}-mounted 4.2 volume.
11490 @node Limitations of Make
11491 @section Limitations of Make
11492 @prindex @command{make}
11493 @cindex Limitations of @command{make}
11495 @command{make} itself suffers a great number of limitations, only a few
11496 of which are listed here. First of all, remember that since commands
11497 are executed by the shell, all its weaknesses are inherited@enddots{}
11501 @acronym{POSIX} says that the @samp{$<} construct in makefiles can be used
11502 only in inference rules and in the @samp{.DEFAULT} rule; its meaning in
11503 ordinary rules is unspecified. Solaris 8's @command{make} for instance
11504 will replace it with the argument.
11506 @item Leading underscore in macro names
11507 Some @command{make}s don't support leading underscores in macro names,
11508 such as on NEWS-OS 4.2R.
11511 $ @kbd{cat Makefile}
11514 all:; @@echo this is test
11516 Make: Must be a separator on rules line 2. Stop.
11517 $ @kbd{cat Makefile2}
11520 all:; @@echo this is test
11521 $ @kbd{make -f Makefile2}
11525 @item Trailing backslash in macro
11526 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
11527 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
11528 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
11529 On some versions of HP-UX, @command{make} will read multiple newlines
11530 following a backslash, continuing to the next non-empty line. For
11544 shows @code{FOO} equal to @code{one BAR = two}. Other @command{make}s
11545 sensibly let a backslash continue only to the immediately following
11548 @item Escaped newline in comments
11550 According to @acronym{POSIX}, @file{Makefile} comments start with @code{#}
11551 and continue until an unescaped newline is reached.
11554 % @kbd{cat Makefile}
11561 % @kbd{make} # GNU make
11566 However in Real World this is not always the case. Some implementations
11567 discards anything from @code{#} up to the end of line, ignoring any
11568 trailing backslash.
11571 % @kbd{pmake} # BSD make
11572 "Makefile", line 3: Need an operator
11573 Fatal errors encountered -- cannot continue
11577 Therefore, if you want to comment out a multi-line definition, prefix each
11578 line with @code{#}, not only the first.
11586 @item @code{make macro=value} and sub-@command{make}s.
11588 A command-line variable definition such as @code{foo=bar} overrides any
11589 definition of @code{foo} in the @file{Makefile}. Some @command{make}
11590 implementations (such as @acronym{GNU} @command{make}) will propagate this
11591 override to sub-invocations of @command{make}. Some other implementation
11592 will not pass the substitution along to sub-@command{make}s.
11595 % @kbd{cat Makefile}
11602 % @kbd{make foo=bar} # GNU make 3.79.1
11605 make[1]: Entering directory `/home/adl'
11607 make[1]: Leaving directory `/home/adl'
11608 % @kbd{pmake foo=bar} # BSD make
11614 You have a few possibilities if you do want the @code{foo=bar} override
11615 to propagate to sub-@command{make}s. One is to use the @code{-e}
11616 option, which causes all environment variables to have precedence over
11617 the @file{Makefile} macro definitions, and declare foo as an environment
11621 % @kbd{env foo=bar make -e}
11624 The @code{-e} option is propagated to sub-@command{make}s automatically,
11625 and since the environment is inherited between @command{make}
11626 invocations, the @code{foo} macro will be overridden in
11627 sub-@code{make}s as expected.
11629 This syntax (@code{foo=bar make -e}) is portable only when used
11630 outside a @file{Makefile}, for instance from a script or from the
11631 command line. When run inside a @command{make} rule, GNU
11632 @command{make} 3.80 and prior versions forget to propagate the
11633 @code{-e} option to sub-@command{make}s.
11635 Moreover, using @code{-e} could have unexpected side-effects if your
11636 environment contains some other macros usually defined by the
11637 Makefile. (See also the note about @code{make -e} and @code{SHELL}
11640 Another way to propagate overrides to sub-@command{make}s is to do it
11641 manually, from your @file{Makefile}:
11647 $(MAKE) foo=$(foo) two
11652 You need to foresee all macros that a user might want to override if
11655 @item The @code{SHELL} macro
11656 @cindex @code{SHELL} and @command{make}
11657 @cindex @command{make} and @code{SHELL}
11659 @acronym{POSIX}-compliant @command{make}s internally use the @code{$(SHELL)}
11660 macro to spawn shell processes and execute @file{Makefile} rules. This
11661 is a builtin macro supplied by @command{make}, but it can be modified
11662 from the @file{Makefile} or a command-line argument.
11664 Not all @command{make}s will define this @code{SHELL} macro. OSF/Tru64
11665 @command{make} is an example; this implementation will always use
11666 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
11667 your @file{Makefile}s. If you use Autoconf, do
11673 @acronym{POSIX}-compliant @command{make}s should never acquire the value of
11674 $(SHELL) from the environment, even when @code{make -e} is used
11675 (otherwise, think about what would happen to your rules if
11676 @code{SHELL=/bin/tcsh}).
11678 However not all @command{make} implementations will make this exception.
11679 For instance it's not surprising that OSF/Tru64 @command{make} doesn't
11680 protect @code{SHELL}, since it doesn't use it.
11683 % @kbd{cat Makefile}
11689 % @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # OSF1 V4.0 Make
11692 % @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
11697 @item Comments in rules
11698 @cindex Comments in @file{Makefile} rules
11699 @cindex @file{Makefile} rules and comments
11701 Never put comments in a rule.
11703 Some @command{make} treat anything starting with a tab as a command for
11704 the current rule, even if the tab is immediately followed by a @code{#}.
11705 The @command{make} from Tru64 Unix V5.1 is one of them. The following
11706 @file{Makefile} will run @code{# foo} through the shell.
11713 @item The @file{obj/} subdirectory.
11714 @cindex @file{obj/}, subdirectory
11715 @cindex BSD @command{make} and @file{obj/}
11717 Never name one of your subdirectories @file{obj/} if you don't like
11720 If an @file{obj/} directory exists, BSD @command{make} will enter it
11721 before reading @file{Makefile}. Hence the @file{Makefile} in the
11722 current directory will not be read.
11725 % @kbd{cat Makefile}
11728 % @kbd{cat obj/Makefile}
11731 % @kbd{make} # GNU make
11734 % @kbd{pmake} # BSD make
11739 @item @code{make -k}
11740 @cindex @code{make -k}
11742 Do not rely on the exit status of @code{make -k}. Some implementations
11743 reflect whether they encountered an error in their exit status; other
11744 implementations always succeed.
11747 % @kbd{cat Makefile}
11750 % @kbd{make -k; echo exit status: $?} # GNU make
11752 make: *** [all] Error 1
11754 % @kbd{pmake -k; echo exit status: $?} # BSD make
11756 *** Error code 1 (continuing)
11761 @cindex @code{VPATH}
11763 There is no @code{VPATH} support specified in @acronym{POSIX}. Many
11764 @command{make}s have a form of @code{VPATH} support, but its
11765 implementation is not consistent amongst @command{make}s.
11767 Maybe the best suggestion to give to people who need the @code{VPATH}
11768 feature is to choose a @command{make} implementation and stick to it.
11769 Since the resulting @file{Makefile}s are not portable anyway, better
11770 choose a portable @command{make} (hint, hint).
11772 Here are a couple of known issues with some @code{VPATH}
11777 @item @code{VPATH} and double-colon rules
11778 @cindex @code{VPATH} and double-colon rules
11779 @cindex double-colon rules and @code{VPATH}
11781 Any assignment to @code{VPATH} causes Sun @command{make} to only execute
11782 the first set of double-colon rules. (This comment has been here since
11783 1994 and the context has been lost. It's probably about SunOS 4. If
11784 you can reproduce this, please send us a test case for illustration.)
11786 @item @code{$<} not supported in explicit rules
11787 @cindex explicit rules, @code{$<}, and @code{VPATH}
11788 @cindex @code{$<}, explicit rules, and @code{VPATH}
11789 @cindex @code{VPATH}, explicit rules, and @code{$<}
11791 As said elsewhere, using @code{$<} in explicit rules is not portable.
11792 The prerequisite file must be named explicitly in the rule. If you want
11793 to find the prerequisite via a @code{VPATH} search, you have to code the
11794 whole thing manually. For instance, using the following pattern:
11799 cp `test -f ifoo.c || echo ../pkg/src/`ifoo.c foo.c
11802 @item Automatic rule rewriting
11803 @cindex @code{VPATH} and automatic rule rewriting
11804 @cindex automatic rule rewriting and @code{VPATH}
11806 Some @command{make} implementations, such as SunOS @command{make} or
11807 OSF1/Tru64 @command{make}, will search prerequisites in @code{VPATH} and
11808 rewrite all their occurrences in the rule appropriately.
11819 would execute @code{cp ../pkg/src/ifoo.c foo.c} if @file{ifoo.c} was
11820 found in @file{../pkg/src}. That sounds great.
11822 However, for the sake of other @command{make} implementations, we can't
11823 rely on this, and we have to search @code{VPATH} manually:
11828 cp `test -f ifoo.c || echo ../pkg/src/`ifoo.c foo.c
11832 However the "prerequisite rewriting" still applies here. So if
11833 @file{ifoo.c} is in @file{../pkg/src}, SunOS @command{make} and OSF1/Tru64
11834 @command{make} will execute
11837 @code{cp `test -f ../pkg/src/ifoo.c || echo ../pkg/src/`ifoo.c foo.c}
11848 and thus fails. Oops.
11850 One workaround is to make sure that ifoo.c never appears as a plain word
11851 in the rule. For instance these three rules would be safe.
11856 cp `test -f ./ifoo.c || echo ../pkg/src/`ifoo.c foo.c
11858 cp `test -f 'ifoo2.c' || echo ../pkg/src/`ifoo2.c foo2.c
11860 cp `test -f "ifoo3.c" || echo ../pkg/src/`ifoo3.c foo3.c
11863 Things get worse when your prerequisites are in a macro.
11867 HEADERS = foo.h foo2.h foo3.h
11868 install-HEADERS: $(HEADERS)
11869 for i in $(HEADERS); do \
11870 $(INSTALL) -m 644 `test -f $$i || echo ../pkg/src/`$$i \
11871 $(DESTDIR)$(includedir)/$$i; \
11875 The above @code{install-HEADERS} rule is not SunOS-proof because @code{for
11876 i in $(HEADERS);} will be expanded as @code{for i in foo.h foo2.h foo3.h;}
11877 where @code{foo.h} and @code{foo2.h} are plain words and are hence
11878 subject to @code{VPATH} adjustments.
11880 If the three files are in @file{../pkg/src}, the rule is run as:
11883 for i in ../pkg/src/foo.h ../pkg/src/foo2.h foo3.h; do \
11884 install -m 644 `test -f $i || echo ../pkg/src/`$i \
11885 /usr/local/include/$i; \
11889 where the two first @command{install} calls will fail. For instance,
11890 consider the @code{foo.h} installation:
11893 install -m 644 `test -f ../pkg/src/foo.h || echo ../pkg/src/`../pkg/src/foo.h \
11894 /usr/local/include/../pkg/src/foo.h;
11900 install -m 644 ../pkg/src/foo.h /usr/local/include/../pkg/src/foo.h;
11903 Note that the manual @code{VPATH} search did not cause any problems here;
11904 however this command installs @file{foo.h} in an incorrect directory.
11906 Trying to quote @code{$(HEADERS)} in some way, as we did for
11907 @code{foo.c} a few @file{Makefile}s ago, does not help:
11910 install-HEADERS: $(HEADERS)
11911 headers='$(HEADERS)'; for i in $$headers; do \
11912 $(INSTALL) -m 644 `test -f $$i || echo ../pkg/src/`$$i \
11913 $(DESTDIR)$(includedir)/$$i; \
11917 Indeed, @code{headers='$(HEADERS)'} expands to @code{headers='foo.h
11918 foo2.h foo3.h'} where @code{foo2.h} is still a plain word. (Aside: the
11919 @code{headers='$(HEADERS)'; for i in $$headers;} idiom is a good
11920 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
11921 syntax error on @code{for i in;}.)
11923 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
11926 HEADERS = foo.h foo2.h foo3.h
11927 install-HEADERS: $(HEADERS)
11928 headers='$(HEADERS)'; for i in $$headers; do \
11929 i=`expr "$$i" : '../pkg/src/\(.*\)'`;
11930 $(INSTALL) -m 644 `test -f $$i || echo ../pkg/src/`$$i \
11931 $(DESTDIR)$(includedir)/$$i; \
11935 Automake does something similar. However the above hack works only if
11936 the files listed in @code{HEADERS} are in the current directory or a
11937 subdirectory; they should not be in an enclosing directory. If we had
11938 @code{HEADERS = ../foo.h}, the above fragment would fail in a VPATH
11939 build with OSF1/Tru64 @command{make}. The reason is that not only does
11940 OSF1/Tru64 @command{make} rewrite dependencies, but it also simplifies
11941 them. Hence @code{../foo.h} will become @code{../pkg/foo.h} instead of
11942 @code{../pkg/src/../foo.h}. This obviously defeats any attempt to strip
11943 a leading @file{../pkg/src/} component.
11945 The following example makes the behavior of OSF1/Tru64 @command{make}
11959 Dependency @file{../foo} was found in @file{sub/../foo}, but OSF1/Tru64
11960 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
11961 directory does not even exist, this just means that the simplification
11962 occurred before the file was checked for.)
11964 For the records here is how SunOS @command{make} behaves on this
11968 make: Fatal error: Don't know how to make target `../foo'
11976 @item OSF/Tru64 @command{make} creates prerequisite directories magically
11977 @cindex @code{VPATH} and prerequisite directories
11978 @cindex prerequisite directories and @code{VPATH}
11980 When a prerequisite is a sub-directory of @code{VPATH}, Tru64
11981 @command{make} will create it in the current directory.
11984 % @kbd{mkdir -p foo/bar build}
11986 % @kbd{cat >Makefile <<END
11995 This can yield unexpected results if a rule uses a manual @code{VPATH}
11996 search as presented before.
12001 command `test -d foo/bar || echo ../`foo/bar
12004 The above @command{command} will be run on the empty @file{foo/bar}
12005 directory that was created in the current directory.
12007 @item target lookup
12008 @cindex @code{VPATH}, resolving target pathnames
12010 @acronym{GNU} @command{make} uses a rather complex algorithm to decide when it
12011 should use files found via a @code{VPATH} search. @xref{Search
12012 Algorithm,, How Directory Searches are Performed, make, The @acronym{GNU} Make
12015 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
12016 filename found during the @code{VPATH} search for this target, and
12017 builds the file locally using the filename given in the @file{Makefile}.
12018 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
12019 filename found during the @code{VPATH} search.
12021 Other @command{make} implementations, like NetBSD @command{make}, are
12022 easier to describe: the filename found during the @code{VPATH} search
12023 will be used whether the target needs to be rebuilt or not. Therefore
12024 new files are created locally, but existing files are updated at their
12025 @code{VPATH} location.
12027 OpenBSD and FreeBSD @command{make}s, however, will never perform a
12028 @code{VPATH} search for a dependency which has an explicit rule.
12029 This is extremely annoying.
12031 When attempting a @code{VPATH} build for an autoconfiscated package
12032 (e.g,, @code{mkdir build && cd build && ../configure}), this means the
12034 @command{make} will build everything locally in the @file{build}
12035 directory, while BSD @command{make} will build new files locally and
12036 update existing files in the source directory.
12039 % @kbd{cat Makefile}
12042 foo.x bar.x: newer.x
12043 @@echo Building $@@
12044 % @kbd{touch ../bar.x}
12045 % @kbd{touch ../newer.x}
12046 % @kbd{make} # GNU make
12049 % @kbd{pmake} # NetBSD make
12052 % @kbd{fmake} # FreeBSD make, OpenBSD make
12055 % @kbd{tmake} # Tru64 make
12058 % @kbd{touch ../bar.x}
12059 % @kbd{make} # GNU make
12061 % @kbd{pmake} # NetBSD make
12063 % @kbd{fmake} # FreeBSD make, OpenBSD make
12066 % @kbd{tmake} # Tru64 make
12071 Note how NetBSD @command{make} updates @file{../bar.x} in its VPATH
12072 location, and how FreeBSD, OpenBSD, and Tru64 @command{make} always
12073 update @file{bar.x}, even when @file{../bar.x} is up to date.
12075 Another point worth mentioning is that once @acronym{GNU} @command{make} has
12076 decided to ignore a @code{VPATH} filename (e.g., it ignored
12077 @file{../bar.x} in the above example) it will continue to ignore it when
12078 the target occurs as a prerequisite of another rule.
12080 The following example shows that @acronym{GNU} @command{make} does not look up
12081 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
12082 because it ignored the @code{VPATH} result of @file{bar.x} while running
12083 the @code{bar.x: newer.x} rule.
12086 % @kbd{cat Makefile}
12090 @@echo Building $@@
12094 % @kbd{touch ../bar.x}
12095 % @kbd{touch ../newer.x}
12096 % @kbd{make} # GNU make
12099 cp: cannot stat `bar.x': No such file or directory
12100 make: *** [bar.y] Error 1
12101 % @kbd{pmake} # NetBSD make
12105 % @kbd{fmake} # FreeBSD make, OpenBSD make
12106 echo Building bar.x
12108 cp: cannot stat `bar.x': No such file or directory
12110 % @kbd{tmake} # Tru64 make
12112 cp: bar.x: No such file or directory
12116 Note that if you drop away the command from the @code{bar.x: newer.x}
12117 rule, @acronym{GNU} @command{make} will magically start to work: it
12118 knows that @code{bar.x} hasn't been updated, therefore it doesn't
12119 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
12120 uses. Tru64 will also work, but FreeBSD and OpenBSD still don't.
12123 % @kbd{cat Makefile}
12130 % @kbd{touch ../bar.x}
12131 % @kbd{touch ../newer.x}
12132 % @kbd{make} # GNU make
12135 % @kbd{pmake} # NetBSD make
12138 % @kbd{fmake} # FreeBSD make, OpenBSD make
12140 cp: cannot stat `bar.x': No such file or directory
12142 % @kbd{tmake} # True64 make
12146 It seems the sole solution that would please every @command{make}
12147 implementation is to never rely on @code{VPATH} searches for targets.
12148 In other words, @code{VPATH} should be reserved to unbuilt sources.
12151 @c end item about VPATH
12153 @item Single Suffix Rules and Separated Dependencies
12154 @cindex Single Suffix Inference Rule
12155 @cindex Rule, Single Suffix Inference
12156 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
12157 (@samp{.from.to:}), but which @emph{destination} suffix is empty
12160 @cindex Separated Dependencies
12161 @dfn{Separated dependencies} simply refers to listing the prerequisite
12162 of a target, without defining a rule. Usually one can list on the one
12163 hand side, the rules, and on the other hand side, the dependencies.
12165 Solaris @command{make} does not support separated dependencies for
12166 targets defined by single suffix rules:
12169 $ @kbd{cat Makefile}
12174 $ @kbd{touch foo.in}
12181 while @acronym{GNU} Make does:
12187 Makefile foo foo.in
12190 Note it works without the @samp{foo: foo.in} dependency.
12193 $ @kbd{cat Makefile}
12202 and it works with double suffix inference rules:
12205 $ @kbd{cat Makefile}
12207 .SUFFIXES: .in .out
12214 As a result, in such a case, you have to write target rules.
12216 @item Timestamp Resolution
12217 @cindex timestamp resolution
12218 Traditionally, file timestamps had 1-second resolution, and
12219 @command{make} used those timestamps to determine whether one file was
12220 newer than the other. However, many modern filesystems have
12221 timestamps with 1-nanosecond resolution. Some @command{make}
12222 implementations look at the entire timestamp; others ignore the
12223 fractional part, which can lead to incorrect results. Normally this
12224 is not a problem, but in some extreme cases you may need to use tricks
12225 like @samp{sleep 1} to work around timestamp truncation bugs.
12227 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
12228 file timestamps to their full resolutions (@pxref{Limitations of Usual
12229 Tools}). Hence you should be wary of rules like this:
12236 as @file{dest} will often appear to be older than @file{src} after the
12237 timestamp is truncated, and this can cause @command{make} to do
12238 needless rework the next time it is invoked. To work around this
12239 problem, you can use a timestamp file, e.g.:
12252 @c ================================================== Manual Configuration
12254 @node Manual Configuration
12255 @chapter Manual Configuration
12257 A few kinds of features can't be guessed automatically by running test
12258 programs. For example, the details of the object-file format, or
12259 special options that need to be passed to the compiler or linker. You
12260 can check for such features using ad-hoc means, such as having
12261 @command{configure} check the output of the @code{uname} program, or
12262 looking for libraries that are unique to particular systems. However,
12263 Autoconf provides a uniform method for handling unguessable features.
12266 * Specifying Names:: Specifying the system type
12267 * Canonicalizing:: Getting the canonical system type
12268 * Using System Type:: What to do with the system type
12271 @node Specifying Names
12272 @section Specifying the System Type
12273 @cindex System type
12275 Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated
12276 @command{configure} scripts can make decisions based on a canonical name
12277 for the system type, which has the form:
12278 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
12279 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
12281 @command{configure} can usually guess the canonical name for the type of
12282 system it's running on. To do so it runs a script called
12283 @command{config.guess}, which infers the name using the @code{uname}
12284 command or symbols predefined by the C preprocessor.
12286 Alternately, the user can specify the system type with command line
12287 arguments to @command{configure}. Doing so is necessary when
12288 cross-compiling. In the most complex case of cross-compiling, three
12289 system types are involved. The options to specify them are:
12292 @item --build=@var{build-type}
12293 the type of system on which the package is being configured and
12294 compiled. It defaults to the result of running @command{config.guess}.
12296 @item --host=@var{host-type}
12297 @ovindex cross_compiling
12298 the type of system on which the package will run. By default it is the
12299 same as the build machine. Specifying it enables the cross-compilation
12302 @item --target=@var{target-type}
12303 the type of system for which any compiler tools in the package will
12304 produce code (rarely needed). By default, it is the same as host.
12307 If you mean to override the result of @command{config.guess}, use
12308 @option{--build}, not @option{--host}, since the latter enables
12309 cross-compilation. For historical reasons, passing @option{--host} also
12310 changes the build type. Therefore, whenever you specify @code{--host},
12311 be sure to specify @code{--build} too. This will be fixed in the
12315 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
12319 will enter cross-compilation mode, but @command{configure} will fail if it
12320 can't run the code generated by the specified compiler if you configure
12324 ./configure CC=m68k-coff-gcc
12327 @cindex @command{config.sub}
12328 @command{configure} recognizes short aliases for many system types; for
12329 example, @samp{decstation} can be used instead of
12330 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
12331 @command{config.sub} to canonicalize system type aliases.
12333 This section deliberately omits the description of the obsolete
12334 interface; see @ref{Hosts and Cross-Compilation}.
12337 @node Canonicalizing
12338 @section Getting the Canonical System Type
12339 @cindex System type
12340 @cindex Canonical system type
12342 The following macros make the system type available to @command{configure}
12345 @ovindex build_alias
12346 @ovindex host_alias
12347 @ovindex target_alias
12349 The variables @samp{build_alias}, @samp{host_alias}, and
12350 @samp{target_alias} are always exactly the arguments of @option{--build},
12351 @option{--host}, and @option{--target}; in particular, they are left empty
12352 if the user did not use them, even if the corresponding
12353 @code{AC_CANONICAL} macro was run. Any configure script may use these
12354 variables anywhere. These are the variables that should be used when in
12355 interaction with the user.
12357 If you need to recognize some special environments based on their system
12358 type, run the following macros to get canonical system names. These
12359 variables are not set before the macro call.
12361 If you use these macros, you must distribute @command{config.guess} and
12362 @command{config.sub} along with your source code. @xref{Output}, for
12363 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
12364 to control in which directory @command{configure} looks for those scripts.
12367 @defmac AC_CANONICAL_BUILD
12368 @acindex{CANONICAL_BUILD}
12371 @ovindex build_vendor
12373 Compute the canonical build-system type variable, @code{build}, and its
12374 three individual parts @code{build_cpu}, @code{build_vendor}, and
12377 If @option{--build} was specified, then @code{build} is the
12378 canonicalization of @code{build_alias} by @command{config.sub},
12379 otherwise it is determined by the shell script @command{config.guess}.
12382 @defmac AC_CANONICAL_HOST
12383 @acindex{CANONICAL_HOST}
12386 @ovindex host_vendor
12388 Compute the canonical host-system type variable, @code{host}, and its
12389 three individual parts @code{host_cpu}, @code{host_vendor}, and
12392 If @option{--host} was specified, then @code{host} is the
12393 canonicalization of @code{host_alias} by @command{config.sub},
12394 otherwise it defaults to @code{build}.
12397 @defmac AC_CANONICAL_TARGET
12398 @acindex{CANONICAL_TARGET}
12400 @ovindex target_cpu
12401 @ovindex target_vendor
12403 Compute the canonical target-system type variable, @code{target}, and its
12404 three individual parts @code{target_cpu}, @code{target_vendor}, and
12407 If @option{--target} was specified, then @code{target} is the
12408 canonicalization of @code{target_alias} by @command{config.sub},
12409 otherwise it defaults to @code{host}.
12412 Note that there can be artifacts due to the backward compatibility
12413 code. See @xref{Hosts and Cross-Compilation}, for more.
12415 @node Using System Type
12416 @section Using the System Type
12418 In @file{configure.ac} the system type is generally used by one or more
12419 @code{case} statements to select system-specifics. Shell wildcards can
12420 be used to match a group of system types.
12422 For example, an extra assembler code object file could be chosen, giving
12423 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
12424 following would be used in a @file{Makefile} to add the object to a
12425 program or library.
12429 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
12430 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
12433 AC_SUBST(CYCLE_OBJ)
12436 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
12437 to select variant source files, for example optimized code for some
12438 CPUs. The configured CPU type doesn't always indicate exact CPU types,
12439 so some run-time capability checks may be necessary too.
12443 alpha*-*-*) AC_CONFIG_LINKS(dither.c:alpha/dither.c) ;;
12444 powerpc*-*-*) AC_CONFIG_LINKS(dither.c:powerpc/dither.c) ;;
12445 *-*-*) AC_CONFIG_LINKS(dither.c:generic/dither.c) ;;
12449 Another example is filenames made to vary according to system
12450 conventions. On Unix-like systems ``dot'' files are usual but on DOS
12451 systems @file{ini} files are usual. It may be worth allowing the user
12452 to override such things though, if it's a matter of personal preference,
12453 or in case a new DOS-like system comes along.
12457 *-*-msdos* | *-*-go32* | *-*-mingw32* | *-*-cygwin* | *-*-windows*)
12458 MUMBLE_INIT="mumble.ini"
12461 MUMBLE_INIT=".mumbleinit"
12464 AC_SUBST(MUMBLE_INIT)
12467 The host system type can also be used to find cross-compilation tools
12468 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
12470 The above examples all show @samp{$host}, since this is where the code
12471 is going to run. Only rarely is it necessary to test @samp{$build}
12472 (which is where the build is being done).
12474 Whenever you're tempted to use @samp{$host} it's worth considering
12475 whether some sort of probe would be better. New system types come along
12476 periodically or previously missing features are added. Well-written
12477 probes can adapt themselves to such things, but hard-coded lists of
12478 names won't. Here are some guidelines,
12482 Availability of libraries and library functions should always be checked
12485 Variant behaviour of system calls is best identified with runtime tests
12486 if possible, but bug workarounds or obscure difficulties might have to
12487 be driven from @samp{$host}.
12489 Assembler code is inevitably highly CPU-specific and is best selected
12490 according to @samp{$host_cpu}.
12492 Assembler variations like underscore prefix on globals or ELF versus
12493 COFF type directives are however best determined by probing, perhaps
12494 even examining the compiler output.
12497 @samp{$target} is for use by a package creating a compiler or similar.
12498 For ordinary packages it's meaningless and should not be used. It
12499 indicates what the created compiler should generate code for, if it can
12500 cross-compile. @samp{$target} generally selects various hard-coded CPU
12501 and system conventions, since usually the compiler or tools under
12502 construction will themselves determine how the target will work.
12505 @c ===================================================== Site Configuration.
12507 @node Site Configuration
12508 @chapter Site Configuration
12510 @command{configure} scripts support several kinds of local configuration
12511 decisions. There are ways for users to specify where external software
12512 packages are, include or exclude optional features, install programs
12513 under modified names, and set default values for @command{configure}
12517 * External Software:: Working with other optional software
12518 * Package Options:: Selecting optional features
12519 * Pretty Help Strings:: Formatting help string
12520 * Site Details:: Configuring site details
12521 * Transforming Names:: Changing program names when installing
12522 * Site Defaults:: Giving @command{configure} local defaults
12525 @node External Software
12526 @section Working With External Software
12527 @cindex External software
12529 Some packages require, or can optionally use, other software packages
12530 that are already installed. The user can give @command{configure}
12531 command line options to specify which such external software to use.
12532 The options have one of these forms:
12534 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
12537 --with-@var{package}[=@var{arg}]
12538 --without-@var{package}
12541 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
12542 instead of some other linker. @option{--with-x} means work with The X
12545 The user can give an argument by following the package name with
12546 @samp{=} and the argument. Giving an argument of @samp{no} is for
12547 packages that are used by default; it says to @emph{not} use the
12548 package. An argument that is neither @samp{yes} nor @samp{no} could
12549 include a name or number of a version of the other package, to specify
12550 more precisely which other package this program is supposed to work
12551 with. If no argument is given, it defaults to @samp{yes}.
12552 @option{--without-@var{package}} is equivalent to
12553 @option{--with-@var{package}=no}.
12555 @command{configure} scripts do not complain about
12556 @option{--with-@var{package}} options that they do not support. This
12557 behavior permits configuring a source tree containing multiple packages
12558 with a top-level @command{configure} script when the packages support
12559 different options, without spurious error messages about options that
12560 some of the packages support. An unfortunate side effect is that option
12561 spelling errors are not diagnosed. No better approach to this problem
12562 has been suggested so far.
12564 For each external software package that may be used, @file{configure.ac}
12565 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
12566 user asked to use it. Whether each package is used or not by default,
12567 and which arguments are valid, is up to you.
12569 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
12571 If the user gave @command{configure} the option @option{--with-@var{package}}
12572 or @option{--without-@var{package}}, run shell commands
12573 @var{action-if-given}. If neither option was given, run shell commands
12574 @var{action-if-not-given}. The name @var{package} indicates another
12575 software package that this program should work with. It should consist
12576 only of alphanumeric characters and dashes.
12578 The option's argument is available to the shell commands
12579 @var{action-if-given} in the shell variable @code{withval}, which is
12580 actually just the value of the shell variable @code{with_@var{package}},
12581 with any @option{-} characters changed into @samp{_}. You may use that
12582 variable instead, if you wish.
12584 The argument @var{help-string} is a description of the option that
12587 --with-readline support fancy command line editing
12591 @var{help-string} may be more than one line long, if more detail is
12592 needed. Just make sure the columns line up in @samp{configure
12593 --help}. Avoid tabs in the help string. You'll need to enclose the
12594 help string in @samp{[} and @samp{]} in order to produce the leading
12597 You should format your @var{help-string} with the macro
12598 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
12601 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
12603 This is an obsolete version of @code{AC_ARG_WITH} that does not
12604 support providing a help string.
12607 @node Package Options
12608 @section Choosing Package Options
12609 @cindex Package options
12610 @cindex Options, package
12612 If a software package has optional compile-time features, the user can
12613 give @command{configure} command line options to specify whether to
12614 compile them. The options have one of these forms:
12616 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
12619 --enable-@var{feature}[=@var{arg}]
12620 --disable-@var{feature}
12623 These options allow users to choose which optional features to build and
12624 install. @option{--enable-@var{feature}} options should never make a
12625 feature behave differently or cause one feature to replace another.
12626 They should only cause parts of the program to be built rather than left
12629 The user can give an argument by following the feature name with
12630 @samp{=} and the argument. Giving an argument of @samp{no} requests
12631 that the feature @emph{not} be made available. A feature with an
12632 argument looks like @option{--enable-debug=stabs}. If no argument is
12633 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
12634 equivalent to @option{--enable-@var{feature}=no}.
12636 @command{configure} scripts do not complain about
12637 @option{--enable-@var{feature}} options that they do not support.
12638 This behavior permits configuring a source tree containing multiple
12639 packages with a top-level @command{configure} script when the packages
12640 support different options, without spurious error messages about options
12641 that some of the packages support.
12642 An unfortunate side effect is that option spelling errors are not diagnosed.
12643 No better approach to this problem has been suggested so far.
12645 For each optional feature, @file{configure.ac} should call
12646 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
12647 to include it. Whether each feature is included or not by default, and
12648 which arguments are valid, is up to you.
12650 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
12651 @acindex{ARG_ENABLE}
12652 If the user gave @command{configure} the option
12653 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
12654 shell commands @var{action-if-given}. If neither option was given, run
12655 shell commands @var{action-if-not-given}. The name @var{feature}
12656 indicates an optional user-level facility. It should consist only of
12657 alphanumeric characters and dashes.
12659 The option's argument is available to the shell commands
12660 @var{action-if-given} in the shell variable @code{enableval}, which is
12661 actually just the value of the shell variable
12662 @code{enable_@var{feature}}, with any @option{-} characters changed into
12663 @samp{_}. You may use that variable instead, if you wish. The
12664 @var{help-string} argument is like that of @code{AC_ARG_WITH}
12665 (@pxref{External Software}).
12667 You should format your @var{help-string} with the macro
12668 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
12671 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
12673 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
12674 support providing a help string.
12678 @node Pretty Help Strings
12679 @section Making Your Help Strings Look Pretty
12680 @cindex Help strings
12682 Properly formatting the @samp{help strings} which are used in
12683 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
12684 (@pxref{Package Options}) can be challenging. Specifically, you want
12685 your own @samp{help strings} to line up in the appropriate columns of
12686 @samp{configure --help} just like the standard Autoconf @samp{help
12687 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
12689 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
12690 @acindex{HELP_STRING}
12692 Expands into an help string that looks pretty when the user executes
12693 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
12694 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
12695 Options}). The following example will make this clearer.
12698 AC_DEFUN([TEST_MACRO],
12699 [AC_ARG_WITH([foo],
12700 AS_HELP_STRING([--with-foo],
12701 [use foo (default is NO)]),
12702 [ac_cv_use_foo=$withval], [ac_cv_use_foo=no])
12703 AC_CACHE_CHECK([whether to use foo],
12704 [ac_cv_use_foo], [ac_cv_use_foo=no])])
12707 Please note that the call to @code{AS_HELP_STRING} is @strong{unquoted}.
12708 Then the last few lines of @samp{configure --help} will appear like
12712 --enable and --with options recognized:
12713 --with-foo use foo (default is NO)
12716 The @code{AS_HELP_STRING} macro is particularly helpful when the
12717 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
12718 arguments, as shown in the following example.
12721 AC_DEFUN(MY_ARG_WITH,
12723 AS_HELP_STRING([--with-$1], [use $1 (default is $2)]),
12724 ac_cv_use_$1=$withval, ac_cv_use_$1=no),
12725 AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])
12731 @section Configuring Site Details
12732 @cindex Site details
12734 Some software packages require complex site-specific information. Some
12735 examples are host names to use for certain services, company names, and
12736 email addresses to contact. Since some configuration scripts generated
12737 by Metaconfig ask for such information interactively, people sometimes
12738 wonder how to get that information in Autoconf-generated configuration
12739 scripts, which aren't interactive.
12741 Such site configuration information should be put in a file that is
12742 edited @emph{only by users}, not by programs. The location of the file
12743 can either be based on the @code{prefix} variable, or be a standard
12744 location such as the user's home directory. It could even be specified
12745 by an environment variable. The programs should examine that file at
12746 run time, rather than at compile time. Run-time configuration is more
12747 convenient for users and makes the configuration process simpler than
12748 getting the information while configuring. @xref{Directory Variables,,
12749 Variables for Installation Directories, standards, @acronym{GNU} Coding
12750 Standards}, for more information on where to put data files.
12752 @node Transforming Names
12753 @section Transforming Program Names When Installing
12754 @cindex Transforming program names
12755 @cindex Program names, transforming
12757 Autoconf supports changing the names of programs when installing them.
12758 In order to use these transformations, @file{configure.ac} must call the
12759 macro @code{AC_ARG_PROGRAM}.
12761 @defmac AC_ARG_PROGRAM
12762 @acindex{ARG_PROGRAM}
12763 @ovindex program_transform_name
12764 Place in output variable @code{program_transform_name} a sequence of
12765 @code{sed} commands for changing the names of installed programs.
12767 If any of the options described below are given to @command{configure},
12768 program names are transformed accordingly. Otherwise, if
12769 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
12770 is given, the target type followed by a dash is used as a prefix.
12771 Otherwise, no program name transformation is done.
12775 * Transformation Options:: @command{configure} options to transform names
12776 * Transformation Examples:: Sample uses of transforming names
12777 * Transformation Rules:: @file{Makefile} uses of transforming names
12780 @node Transformation Options
12781 @subsection Transformation Options
12783 You can specify name transformations by giving @command{configure} these
12784 command line options:
12787 @item --program-prefix=@var{prefix}
12788 prepend @var{prefix} to the names;
12790 @item --program-suffix=@var{suffix}
12791 append @var{suffix} to the names;
12793 @item --program-transform-name=@var{expression}
12794 perform @code{sed} substitution @var{expression} on the names.
12797 @node Transformation Examples
12798 @subsection Transformation Examples
12800 These transformations are useful with programs that can be part of a
12801 cross-compilation development environment. For example, a
12802 cross-assembler running on a Sun 4 configured with
12803 @option{--target=i960-vxworks} is normally installed as
12804 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
12805 with a native Sun 4 assembler.
12807 You can force a program name to begin with @file{g}, if you don't want
12808 @acronym{GNU} programs installed on your system to shadow other programs with
12809 the same name. For example, if you configure @acronym{GNU} @code{diff} with
12810 @option{--program-prefix=g}, then when you run @samp{make install} it is
12811 installed as @file{/usr/local/bin/gdiff}.
12813 As a more sophisticated example, you could use
12816 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
12820 to prepend @samp{g} to most of the program names in a source tree,
12821 excepting those like @code{gdb} that already have one and those like
12822 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
12823 assuming that you have a source tree containing those programs that is
12824 set up to use this feature.)
12826 One way to install multiple versions of some programs simultaneously is
12827 to append a version number to the name of one or both. For example, if
12828 you want to keep Autoconf version 1 around for awhile, you can configure
12829 Autoconf version 2 using @option{--program-suffix=2} to install the
12830 programs as @file{/usr/local/bin/autoconf2},
12831 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
12832 that only the binaries are renamed, therefore you'd have problems with
12833 the library files which might overlap.
12835 @node Transformation Rules
12836 @subsection Transformation Rules
12838 Here is how to use the variable @code{program_transform_name} in a
12839 @file{Makefile.in}:
12842 PROGRAMS = cp ls rm
12843 transform = @@program_transform_name@@
12845 for p in $(PROGRAMS); do \
12846 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
12847 sed '$(transform)'`; \
12851 for p in $(PROGRAMS); do \
12852 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
12856 It is guaranteed that @code{program_transform_name} is never empty, and
12857 that there are no useless separators. Therefore you may safely embed
12858 @code{program_transform_name} within a sed program using @samp{;}:
12861 transform = @@program_transform_name@@
12862 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
12865 Whether to do the transformations on documentation files (Texinfo or
12866 @code{man}) is a tricky question; there seems to be no perfect answer,
12867 due to the several reasons for name transforming. Documentation is not
12868 usually particular to a specific architecture, and Texinfo files do not
12869 conflict with system documentation. But they might conflict with
12870 earlier versions of the same files, and @code{man} pages sometimes do
12871 conflict with system documentation. As a compromise, it is probably
12872 best to do name transformations on @code{man} pages but not on Texinfo
12875 @node Site Defaults
12876 @section Setting Site Defaults
12877 @cindex Site defaults
12879 Autoconf-generated @command{configure} scripts allow your site to provide
12880 default values for some configuration values. You do this by creating
12881 site- and system-wide initialization files.
12883 @evindex CONFIG_SITE
12884 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
12885 uses its value as the name of a shell script to read. Otherwise, it
12886 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
12887 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
12888 settings in machine-specific files override those in machine-independent
12889 ones in case of conflict.
12891 Site files can be arbitrary shell scripts, but only certain kinds of
12892 code are really appropriate to be in them. Because @command{configure}
12893 reads any cache file after it has read any site files, a site file can
12894 define a default cache file to be shared between all Autoconf-generated
12895 @command{configure} scripts run on that system (@pxref{Cache Files}). If
12896 you set a default cache file in a site file, it is a good idea to also
12897 set the output variable @code{CC} in that site file, because the cache
12898 file is only valid for a particular compiler, but many systems have
12901 You can examine or override the value set by a command line option to
12902 @command{configure} in a site file; options set shell variables that have
12903 the same names as the options, with any dashes turned into underscores.
12904 The exceptions are that @option{--without-} and @option{--disable-} options
12905 are like giving the corresponding @option{--with-} or @option{--enable-}
12906 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
12907 sets the variable @code{cache_file} to the value @samp{localcache};
12908 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
12909 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
12910 variable @code{prefix} to the value @samp{/usr}; etc.
12912 Site files are also good places to set default values for other output
12913 variables, such as @code{CFLAGS}, if you need to give them non-default
12914 values: anything you would normally do, repetitively, on the command
12915 line. If you use non-default values for @var{prefix} or
12916 @var{exec_prefix} (wherever you locate the site file), you can set them
12917 in the site file if you specify it with the @code{CONFIG_SITE}
12918 environment variable.
12920 You can set some cache values in the site file itself. Doing this is
12921 useful if you are cross-compiling, where it is impossible to check features
12922 that require running a test program. You could ``prime the cache'' by
12923 setting those values correctly for that system in
12924 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
12925 variables you need to set, look for shell variables with @samp{_cv_} in
12926 their names in the affected @command{configure} scripts, or in the Autoconf
12927 M4 source code for those macros.
12929 The cache file is careful to not override any variables set in the site
12930 files. Similarly, you should not override command-line options in the
12931 site files. Your code should check that variables such as @code{prefix}
12932 and @code{cache_file} have their default values (as set near the top of
12933 @command{configure}) before changing them.
12935 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
12936 command @samp{configure --prefix=/usr/share/local/gnu} would read this
12937 file (if @code{CONFIG_SITE} is not set to a different file).
12940 # config.site for configure
12942 # Change some defaults.
12943 test "$prefix" = NONE && prefix=/usr/share/local/gnu
12944 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
12945 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
12946 test "$localstatedir" = '$prefix/var' && localstatedir=/var
12948 # Give Autoconf 2.x generated configure scripts a shared default
12949 # cache file for feature test results, architecture-specific.
12950 if test "$cache_file" = /dev/null; then
12951 cache_file="$prefix/var/config.cache"
12952 # A cache file is only valid for one C compiler.
12958 @c ============================================== Running configure Scripts.
12960 @node Running configure Scripts
12961 @chapter Running @command{configure} Scripts
12962 @cindex @command{configure}
12964 Below are instructions on how to configure a package that uses a
12965 @command{configure} script, suitable for inclusion as an @file{INSTALL}
12966 file in the package. A plain-text version of @file{INSTALL} which you
12967 may use comes with Autoconf.
12970 * Basic Installation:: Instructions for typical cases
12971 * Compilers and Options:: Selecting compilers and optimization
12972 * Multiple Architectures:: Compiling for multiple architectures at once
12973 * Installation Names:: Installing in different directories
12974 * Optional Features:: Selecting optional features
12975 * System Type:: Specifying the system type
12976 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
12977 * Defining Variables:: Specifying the compiler etc.
12978 * configure Invocation:: Changing how @command{configure} runs
12982 @include install.texi
12985 @c ============================================== Recreating a Configuration
12987 @node config.status Invocation
12988 @chapter Recreating a Configuration
12989 @cindex @command{config.status}
12991 The @command{configure} script creates a file named @file{config.status},
12992 which actually configures, @dfn{instantiates}, the template files. It
12993 also records the configuration options that were specified when the
12994 package was last configured in case reconfiguring is needed.
12998 ./config.status @var{option}@dots{} [@var{file}@dots{}]
13001 It configures the @var{files}; if none are specified, all the templates
13002 are instantiated. The files must be specified without their
13003 dependencies, as in
13006 ./config.status foobar
13013 ./config.status foobar:foo.in:bar.in
13016 The supported @var{option}s are:
13021 Print a summary of the command line options, the list of the template
13026 Print the version number of Autoconf and exit.
13031 Do not print progress messages.
13035 Don't remove the temporary files.
13037 @item --file=@var{file}[:@var{template}]
13038 Require that @var{file} be instantiated as if
13039 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
13040 @var{file} and @var{template} may be @samp{-} in which case the standard
13041 output and/or standard input, respectively, is used. If a
13042 @var{template} filename is relative, it is first looked for in the build
13043 tree, and then in the source tree. @xref{Configuration Actions}, for
13046 This option and the following ones provide one way for separately
13047 distributed packages to share the values computed by @command{configure}.
13048 Doing so can be useful if some of the packages need a superset of the
13049 features that one of them, perhaps a common library, does. These
13050 options allow a @file{config.status} file to create files other than the
13051 ones that its @file{configure.ac} specifies, so it can be used for a
13054 @item --header=@var{file}[:@var{template}]
13055 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
13058 Ask @file{config.status} to update itself and exit (no instantiation).
13059 This option is useful if you change @command{configure}, so that the
13060 results of some tests might be different from the previous run. The
13061 @option{--recheck} option re-runs @command{configure} with the same arguments
13062 you used before, plus the @option{--no-create} option, which prevents
13063 @command{configure} from running @file{config.status} and creating
13064 @file{Makefile} and other files, and the @option{--no-recursion} option,
13065 which prevents @command{configure} from running other @command{configure}
13066 scripts in subdirectories. (This is so other @file{Makefile} rules can
13067 run @file{config.status} when it changes; @pxref{Automatic Remaking},
13071 @file{config.status} checks several optional environment variables that
13072 can alter its behavior:
13074 @defvar CONFIG_SHELL
13075 @evindex CONFIG_SHELL
13076 The shell with which to run @command{configure} for the @option{--recheck}
13077 option. It must be Bourne-compatible. The default is a shell that
13078 supports @env{LINENO} if available, and @file{/bin/sh} otherwise.
13081 @defvar CONFIG_STATUS
13082 @evindex CONFIG_STATUS
13083 The file name to use for the shell script that records the
13084 configuration. The default is @file{./config.status}. This variable is
13085 useful when one package uses parts of another and the @command{configure}
13086 scripts shouldn't be merged because they are maintained separately.
13089 You can use @file{./config.status} in your Makefiles. For example, in
13090 the dependencies given above (@pxref{Automatic Remaking}),
13091 @file{config.status} is run twice when @file{configure.ac} has changed.
13092 If that bothers you, you can make each run only regenerate the files for
13097 stamp-h: config.h.in config.status
13098 ./config.status config.h
13101 Makefile: Makefile.in config.status
13102 ./config.status Makefile
13106 The calling convention of @file{config.status} has changed; see
13107 @ref{Obsolete config.status Use}, for details.
13110 @c =================================================== Obsolete Constructs
13112 @node Obsolete Constructs
13113 @chapter Obsolete Constructs
13114 @cindex Obsolete constructs
13116 Autoconf changes, and throughout the years some constructs have been
13117 obsoleted. Most of the changes involve the macros, but in some cases
13118 the tools themselves, or even some concepts, are now considered
13121 You may completely skip this chapter if you are new to Autoconf. Its
13122 intention is mainly to help maintainers updating their packages by
13123 understanding how to move to more modern constructs.
13126 * Obsolete config.status Use:: Different calling convention
13127 * acconfig.h:: Additional entries in @file{config.h.in}
13128 * autoupdate Invocation:: Automatic update of @file{configure.ac}
13129 * Obsolete Macros:: Backward compatibility macros
13130 * Autoconf 1:: Tips for upgrading your files
13131 * Autoconf 2.13:: Some fresher tips
13134 @node Obsolete config.status Use
13135 @section Obsolete @file{config.status} Invocation
13137 @file{config.status} now supports arguments to specify the files to
13138 instantiate; see @ref{config.status Invocation}, for more details.
13139 Before, environment variables had to be used.
13141 @defvar CONFIG_COMMANDS
13142 @evindex CONFIG_COMMANDS
13143 The tags of the commands to execute. The default is the arguments given
13144 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
13145 @file{configure.ac}.
13148 @defvar CONFIG_FILES
13149 @evindex CONFIG_FILES
13150 The files in which to perform @samp{@@@var{variable}@@} substitutions.
13151 The default is the arguments given to @code{AC_OUTPUT} and
13152 @code{AC_CONFIG_FILES} in @file{configure.ac}.
13155 @defvar CONFIG_HEADERS
13156 @evindex CONFIG_HEADERS
13157 The files in which to substitute C @code{#define} statements. The
13158 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
13159 macro was not called, @file{config.status} ignores this variable.
13162 @defvar CONFIG_LINKS
13163 @evindex CONFIG_LINKS
13164 The symbolic links to establish. The default is the arguments given to
13165 @code{AC_CONFIG_LINKS}; if that macro was not called,
13166 @file{config.status} ignores this variable.
13169 In @ref{config.status Invocation}, using this old interface, the example
13175 stamp-h: config.h.in config.status
13176 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
13177 CONFIG_HEADERS=config.h ./config.status
13180 Makefile: Makefile.in config.status
13181 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
13182 CONFIG_FILES=Makefile ./config.status
13187 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
13188 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
13189 for @code{CONFIG_COMMANDS} etc.)
13193 @section @file{acconfig.h}
13195 @cindex @file{acconfig.h}
13196 @cindex @file{config.h.top}
13197 @cindex @file{config.h.bot}
13199 In order to produce @file{config.h.in}, @command{autoheader} needs to
13200 build or to find templates for each symbol. Modern releases of Autoconf
13201 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
13202 Macros}), but in older releases a file, @file{acconfig.h}, contained the
13203 list of needed templates. @command{autoheader} copied comments and
13204 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
13205 the current directory, if present. This file used to be mandatory if
13206 you @code{AC_DEFINE} any additional symbols.
13208 Modern releases of Autoconf also provide @code{AH_TOP} and
13209 @code{AH_BOTTOM} if you need to prepend/append some information to
13210 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
13211 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
13212 @command{autoheader} copies the lines before the line containing
13213 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
13214 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
13215 @command{autoheader} copies the lines after that line to the end of the
13216 file it generates. Either or both of those strings may be omitted. An
13217 even older alternate way to produce the same effect in ancient versions
13218 of Autoconf is to create the files @file{@var{file}.top} (typically
13219 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
13220 directory. If they exist, @command{autoheader} copies them to the
13221 beginning and end, respectively, of its output.
13223 In former versions of Autoconf, the files used in preparing a software
13224 package for distribution were:
13227 configure.ac --. .------> autoconf* -----> configure
13229 [aclocal.m4] --+ `---.
13231 +--> [autoheader*] -> [config.h.in]
13232 [acconfig.h] ----. |
13239 Using only the @code{AH_} macros, @file{configure.ac} should be
13240 self-contained, and should not depend upon @file{acconfig.h} etc.
13243 @node autoupdate Invocation
13244 @section Using @command{autoupdate} to Modernize @file{configure.ac}
13245 @cindex @command{autoupdate}
13247 The @command{autoupdate} program updates a @file{configure.ac} file that
13248 calls Autoconf macros by their old names to use the current macro names.
13249 In version 2 of Autoconf, most of the macros were renamed to use a more
13250 uniform and descriptive naming scheme. @xref{Macro Names}, for a
13251 description of the new scheme. Although the old names still work
13252 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
13253 new names), you can make your @file{configure.ac} files more readable
13254 and make it easier to use the current Autoconf documentation if you
13255 update them to use the new macro names.
13257 @evindex SIMPLE_BACKUP_SUFFIX
13258 If given no arguments, @command{autoupdate} updates @file{configure.ac},
13259 backing up the original version with the suffix @file{~} (or the value
13260 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
13261 set). If you give @command{autoupdate} an argument, it reads that file
13262 instead of @file{configure.ac} and writes the updated file to the
13266 @command{autoupdate} accepts the following options:
13271 Print a summary of the command line options and exit.
13275 Print the version number of Autoconf and exit.
13279 Report processing steps.
13283 Don't remove the temporary files.
13287 Force the update even if the file has not changed. Disregard the cache.
13289 @item --include=@var{dir}
13290 @itemx -I @var{dir}
13291 Also look for input files in @var{dir}. Multiple invocations accumulate.
13292 Directories are browsed from last to first.
13295 @node Obsolete Macros
13296 @section Obsolete Macros
13298 Several macros are obsoleted in Autoconf, for various reasons (typically
13299 they failed to quote properly, couldn't be extended for more recent
13300 issues etc.). They are still supported, but deprecated: their use
13303 During the jump from Autoconf version 1 to version 2, most of the
13304 macros were renamed to use a more uniform and descriptive naming scheme,
13305 but their signature did not change. @xref{Macro Names}, for a
13306 description of the new naming scheme. Below, if there is just the mapping
13307 from old names to new names for these macros, the reader is invited to
13308 refer to the definition of the new macro for the signature and the
13313 @code{AC_FUNC_ALLOCA}
13316 @defmac AC_ARG_ARRAY
13317 @acindex{ARG_ARRAY}
13318 removed because of limited usefulness
13323 This macro is obsolete; it does nothing.
13326 @defmac AC_CANONICAL_SYSTEM
13327 @acindex{CANONICAL_SYSTEM}
13328 Determine the system type and set output variables to the names of the
13329 canonical system types. @xref{Canonicalizing}, for details about the
13330 variables this macro sets.
13332 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
13333 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
13334 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
13338 @defmac AC_CHAR_UNSIGNED
13339 @acindex{CHAR_UNSIGNED}
13340 @code{AC_C_CHAR_UNSIGNED}
13343 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
13344 @acindex{CHECK_TYPE}
13345 Autoconf, up to 2.13, used to provide this version of
13346 @code{AC_CHECK_TYPE}, deprecated because of its flaws. Firstly, although
13347 it is a member of the @code{CHECK} clan, singular sub-family, it does
13348 more than just checking. Secondly, missing types are not
13349 @code{typedef}'d, they are @code{#define}'d, which can lead to
13350 incompatible code in the case of pointer types.
13352 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
13353 @ref{Generic Types}, for the description of the current macro.
13355 If the type @var{type} is not defined, define it to be the C (or C++)
13356 builtin type @var{default}, e.g., @samp{short} or @samp{unsigned}.
13358 This macro is equivalent to:
13361 AC_CHECK_TYPE([@var{type}],,
13362 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
13363 [Define to `@var{default}' if
13364 <sys/types.h> does not define.])])
13367 In order to keep backward compatibility, the two versions of
13368 @code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
13372 If there are three or four arguments, the modern version is used.
13375 If the second argument appears to be a C or C++ type, then the
13376 obsolete version is used. This happens if the argument is a C or C++
13377 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
13378 followed by one of @samp{[(* } and then by a string of zero or more
13379 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
13382 If the second argument is spelled with the alphabet of valid C and C++
13383 types, the user is warned and the modern version is used.
13386 Otherwise, the modern version is used.
13390 You are encouraged either to use a valid builtin type, or to use the
13391 equivalent modern code (see above), or better yet, to use
13392 @code{AC_CHECK_TYPES} together with
13396 typedef loff_t off_t;
13400 @c end of AC_CHECK_TYPE
13402 @defmac AC_CHECKING (@var{feature-description})
13404 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
13407 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found})
13408 @acindex{COMPILE_CHECK}
13409 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
13410 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
13411 addition that it prints @samp{checking for @var{echo-text}} to the
13412 standard output first, if @var{echo-text} is non-empty. Use
13413 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
13414 messages (@pxref{Printing Messages}).
13422 @defmac AC_CROSS_CHECK
13423 @acindex{CROSS_CHECK}
13424 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
13430 Check for the Cygwin environment in which case the shell variable
13431 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
13432 means to check the nature of the host is using
13433 @code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as:
13436 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
13438 *cygwin* ) CYGWIN=yes;;
13443 Beware that the variable @code{CYGWIN} has a very special meaning when
13444 running CygWin32, and should not be changed. That's yet another reason
13445 not to use this macro.
13448 @defmac AC_DECL_SYS_SIGLIST
13449 @acindex{DECL_SYS_SIGLIST}
13450 @cvindex SYS_SIGLIST_DECLARED
13454 AC_CHECK_DECLS([sys_siglist],,,
13455 [#include <signal.h>
13456 /* NetBSD declares sys_siglist in unistd.h. */
13458 # include <unistd.h>
13464 @defmac AC_DECL_YYTEXT
13465 @acindex{DECL_YYTEXT}
13466 Does nothing, now integrated in @code{AC_PROG_LEX}.
13469 @defmac AC_DIR_HEADER
13470 @acindex{DIR_HEADER}
13475 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
13476 but defines a different set of C preprocessor macros to indicate which
13477 header file is found:
13479 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
13480 @item Header @tab Old Symbol @tab New Symbol
13481 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
13482 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
13483 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
13484 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
13488 @defmac AC_DYNIX_SEQ
13489 @acindex{DYNIX_SEQ}
13490 If on DYNIX/ptx, add @option{-lseq} to output variable
13491 @code{LIBS}. This macro used to be defined as
13494 AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS")
13498 now it is just @code{AC_FUNC_GETMNTENT}.
13504 Defined the output variable @code{EXEEXT} based on the output of the
13505 compiler, which is now done automatically. Typically set to empty
13506 string if Unix and @samp{.exe} if Win32 or OS/2.
13511 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
13512 and sets @code{EMXOS2}.
13517 @code{AC_MSG_ERROR}
13525 @defmac AC_FIND_XTRA
13526 @acindex{FIND_XTRA}
13527 @code{AC_PATH_XTRA}
13530 @defmac AC_FUNC_CHECK
13531 @acindex{FUNC_CHECK}
13532 @code{AC_CHECK_FUNC}
13535 @defmac AC_FUNC_WAIT3
13536 @acindex{FUNC_WAIT3}
13537 @cvindex HAVE_WAIT3
13538 If @code{wait3} is found and fills in the contents of its third argument
13539 (a @samp{struct rusage *}), which HP-UX does not do, define
13542 These days portable programs should use @code{waitpid}, not
13543 @code{wait3}, as @code{wait3} is being removed from the Open Group
13544 standards, and will not appear in the next revision of POSIX@.
13547 @defmac AC_GCC_TRADITIONAL
13548 @acindex{GCC_TRADITIONAL}
13549 @code{AC_PROG_GCC_TRADITIONAL}
13552 @defmac AC_GETGROUPS_T
13553 @acindex{GETGROUPS_T}
13554 @code{AC_TYPE_GETGROUPS}
13557 @defmac AC_GETLOADAVG
13558 @acindex{GETLOADAVG}
13559 @code{AC_FUNC_GETLOADAVG}
13562 @defmac AC_HAVE_FUNCS
13563 @acindex{HAVE_FUNCS}
13564 @code{AC_CHECK_FUNCS}
13567 @defmac AC_HAVE_HEADERS
13568 @acindex{HAVE_HEADERS}
13569 @code{AC_CHECK_HEADERS}
13572 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
13573 @acindex{HAVE_LIBRARY}
13574 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
13575 @var{function} argument of @code{main}. In addition, @var{library} can
13576 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
13577 all of those cases, the compiler is passed @option{-lfoo}. However,
13578 @var{library} cannot be a shell variable; it must be a literal name.
13581 @defmac AC_HAVE_POUNDBANG
13582 @acindex{HAVE_POUNDBANG}
13583 @code{AC_SYS_INTERPRETER} (different calling convention)
13586 @defmac AC_HEADER_CHECK
13587 @acindex{HEADER_CHECK}
13588 @code{AC_CHECK_HEADER}
13591 @defmac AC_HEADER_EGREP
13592 @acindex{HEADER_EGREP}
13593 @code{AC_EGREP_HEADER}
13596 @defmac AC_HELP_STRING
13597 @acindex{HELP_STRING}
13598 @code{AS_HELP_STRING}
13601 @defmac AC_INIT (@var{unique-file-in-source-dir})
13603 Formerly @code{AC_INIT} used to have a single argument, and was
13608 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
13617 @defmac AC_INT_16_BITS
13618 @acindex{INT_16_BITS}
13619 @cvindex INT_16_BITS
13620 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
13621 Use @samp{AC_CHECK_SIZEOF(int)} instead.
13624 @defmac AC_IRIX_SUN
13626 If on @sc{irix} (Silicon Graphics @sc{unix}), add @option{-lsun} to output
13627 @code{LIBS}. If you were using it to get @code{getmntent}, use
13628 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
13629 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
13630 getpwnam)}. Up to Autoconf 2.13, it used to be
13633 AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS")
13637 now it is defined as
13641 AC_CHECK_LIB(sun, getpwnam)
13647 Same as @samp{AC_LANG(C)}.
13650 @defmac AC_LANG_CPLUSPLUS
13651 @acindex{LANG_CPLUSPLUS}
13652 Same as @samp{AC_LANG(C++)}.
13655 @defmac AC_LANG_FORTRAN77
13656 @acindex{LANG_FORTRAN77}
13657 Same as @samp{AC_LANG(Fortran 77)}.
13660 @defmac AC_LANG_RESTORE
13661 @acindex{LANG_RESTORE}
13662 Select the @var{language} that is saved on the top of the stack, as set
13663 by @code{AC_LANG_SAVE}, remove it from the stack, and call
13664 @code{AC_LANG(@var{language})}.
13667 @defmac AC_LANG_SAVE
13668 @acindex{LANG_SAVE}
13669 Remember the current language (as set by @code{AC_LANG}) on a stack.
13670 The current language does not change. @code{AC_LANG_PUSH} is preferred.
13673 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
13674 @acindex{LINK_FILES}
13675 This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
13679 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
13687 AC_CONFIG_LINKS(host.h:config/$machine.h
13688 object.h:config/$obj_format.h)
13694 @code{AC_PROG_LN_S}
13697 @defmac AC_LONG_64_BITS
13698 @acindex{LONG_64_BITS}
13699 @cvindex LONG_64_BITS
13700 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
13701 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
13704 @defmac AC_LONG_DOUBLE
13705 @acindex{LONG_DOUBLE}
13706 @code{AC_C_LONG_DOUBLE}
13709 @defmac AC_LONG_FILE_NAMES
13710 @acindex{LONG_FILE_NAMES}
13711 @code{AC_SYS_LONG_FILE_NAMES}
13714 @defmac AC_MAJOR_HEADER
13715 @acindex{MAJOR_HEADER}
13716 @code{AC_HEADER_MAJOR}
13719 @defmac AC_MEMORY_H
13721 @cvindex NEED_MEMORY_H
13722 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
13723 defined in @file{memory.h}. Today it is equivalent to
13724 @samp{AC_CHECK_HEADERS(memory.h)}. Adjust your code to depend upon
13725 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
13731 Similar to @code{AC_CYGWIN} but checks for the MingW32 compiler
13732 environment and sets @code{MINGW32}.
13735 @defmac AC_MINUS_C_MINUS_O
13736 @acindex{MINUS_C_MINUS_O}
13737 @code{AC_PROG_CC_C_O}
13742 @code{AC_FUNC_MMAP}
13747 @code{AC_TYPE_MODE_T}
13753 Defined the output variable @code{OBJEXT} based on the output of the
13754 compiler, after .c files have been excluded. Typically set to @samp{o}
13755 if Unix, @samp{obj} if Win32. Now the compiler checking macros handle
13756 this automatically.
13759 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
13761 Make M4 print a message to the standard error output warning that
13762 @var{this-macro-name} is obsolete, and giving the file and line number
13763 where it was called. @var{this-macro-name} should be the name of the
13764 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
13765 it is printed at the end of the warning message; for example, it can be
13766 a suggestion for what to use instead of @var{this-macro-name}.
13771 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
13774 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
13775 services to the user.
13780 @code{AC_TYPE_OFF_T}
13783 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
13785 The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted
13786 interface is equivalent to:
13790 AC_CONFIG_FILES(@var{file}@dots{})
13791 AC_CONFIG_COMMANDS([default],
13792 @var{extra-cmds}, @var{init-cmds})
13798 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
13799 @acindex{OUTPUT_COMMANDS}
13800 Specify additional shell commands to run at the end of
13801 @file{config.status}, and shell commands to initialize any variables
13802 from @command{configure}. This macro may be called multiple times. It is
13803 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
13805 Here is an unrealistic example:
13809 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
13811 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
13815 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
13816 additional key, an important difference is that
13817 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
13818 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
13819 can safely be given macro calls as arguments:
13822 AC_CONFIG_COMMANDS(foo, [my_FOO()])
13826 Conversely, where one level of quoting was enough for literal strings
13827 with @code{AC_OUTPUT_COMMANDS}, you need two with
13828 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
13832 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
13833 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
13840 @code{AC_TYPE_PID_T}
13845 @code{AC_PREFIX_PROGRAM}
13848 @defmac AC_PROG_CC_STDC
13849 @acindex{PROG_CC_STDC}
13850 This macro has been integrated into @code{AC_PROG_CC}.
13853 @defmac AC_PROGRAMS_CHECK
13854 @acindex{PROGRAMS_CHECK}
13855 @code{AC_CHECK_PROGS}
13858 @defmac AC_PROGRAMS_PATH
13859 @acindex{PROGRAMS_PATH}
13860 @code{AC_PATH_PROGS}
13863 @defmac AC_PROGRAM_CHECK
13864 @acindex{PROGRAM_CHECK}
13865 @code{AC_CHECK_PROG}
13868 @defmac AC_PROGRAM_EGREP
13869 @acindex{PROGRAM_EGREP}
13870 @code{AC_EGREP_CPP}
13873 @defmac AC_PROGRAM_PATH
13874 @acindex{PROGRAM_PATH}
13875 @code{AC_PATH_PROG}
13878 @defmac AC_REMOTE_TAPE
13879 @acindex{REMOTE_TAPE}
13880 removed because of limited usefulness
13883 @defmac AC_RESTARTABLE_SYSCALLS
13884 @acindex{RESTARTABLE_SYSCALLS}
13885 @code{AC_SYS_RESTARTABLE_SYSCALLS}
13888 @defmac AC_RETSIGTYPE
13889 @acindex{RETSIGTYPE}
13890 @code{AC_TYPE_SIGNAL}
13895 removed because of limited usefulness
13898 @defmac AC_SCO_INTL
13901 If on SCO UNIX, add @option{-lintl} to output variable @code{LIBS}. This
13905 AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS")
13909 Now it just calls @code{AC_FUNC_STRFTIME} instead.
13912 @defmac AC_SETVBUF_REVERSED
13913 @acindex{SETVBUF_REVERSED}
13914 @code{AC_FUNC_SETVBUF_REVERSED}
13917 @defmac AC_SET_MAKE
13919 @code{AC_PROG_MAKE_SET}
13922 @defmac AC_SIZEOF_TYPE
13923 @acindex{SIZEOF_TYPE}
13924 @code{AC_CHECK_SIZEOF}
13929 @code{AC_TYPE_SIZE_T}
13932 @defmac AC_STAT_MACROS_BROKEN
13933 @acindex{STAT_MACROS_BROKEN}
13934 @code{AC_HEADER_STAT}
13937 @defmac AC_STDC_HEADERS
13938 @acindex{STDC_HEADERS}
13939 @code{AC_HEADER_STDC}
13944 @code{AC_FUNC_STRCOLL}
13947 @defmac AC_ST_BLKSIZE
13948 @acindex{ST_BLKSIZE}
13949 @code{AC_CHECK_MEMBERS}
13952 @defmac AC_ST_BLOCKS
13953 @acindex{ST_BLOCKS}
13954 @code{AC_STRUCT_ST_BLOCKS}
13959 @code{AC_CHECK_MEMBERS}
13962 @defmac AC_SYS_RESTARTABLE_SYSCALLS
13963 @acindex{SYS_RESTARTABLE_SYSCALLS}
13964 @cvindex HAVE_RESTARTABLE_SYSCALLS
13965 If the system automatically restarts a system call that is interrupted
13966 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
13967 not check if system calls are restarted in general--it tests whether a
13968 signal handler installed with @code{signal} (but not @code{sigaction})
13969 causes system calls to be restarted. It does not test if system calls
13970 can be restarted when interrupted by signals that have no handler.
13972 These days portable programs should use @code{sigaction} with
13973 @code{SA_RESTART} if they want restartable system calls. They should
13974 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
13975 system call is restartable is a dynamic issue, not a configuration-time
13979 @defmac AC_SYS_SIGLIST_DECLARED
13980 @acindex{SYS_SIGLIST_DECLARED}
13981 @code{AC_DECL_SYS_SIGLIST}
13984 @defmac AC_TEST_CPP
13986 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
13989 @defmac AC_TEST_PROGRAM
13990 @acindex{TEST_PROGRAM}
13991 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
13994 @defmac AC_TIMEZONE
13996 @code{AC_STRUCT_TIMEZONE}
13999 @defmac AC_TIME_WITH_SYS_TIME
14000 @acindex{TIME_WITH_SYS_TIME}
14001 @code{AC_HEADER_TIME}
14004 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
14005 @acindex{TRY_COMPILE}
14006 Same as @samp{AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[@var{includes}]],
14007 [[@var{function-body}]])], [@var{action-if-true}],
14008 [@var{action-if-false}])} (@pxref{Running the Compiler}).
14010 This macro double quotes both @var{includes} and @var{function-body}.
14012 For C and C++, @var{includes} is any @code{#include} statements needed
14013 by the code in @var{function-body} (@var{includes} will be ignored if
14014 the currently selected language is Fortran or Fortran 77). The compiler
14015 and compilation flags are determined by the current language
14016 (@pxref{Language Choice}).
14019 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
14021 Same as @samp{AC_PREPROC_IFELSE([AC_LANG_SOURCE([[@var{input}]])],
14022 [@var{action-if-true}], [@var{action-if-false}])} (@pxref{Running the
14025 This macro double quotes the @var{input}.
14028 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
14030 Same as @samp{AC_LINK_IFELSE([AC_LANG_PROGRAM([[@var{includes}]],
14031 [[@var{function-body}]])], [@var{action-if-true}],
14032 [@var{action-if-false}])} (@pxref{Running the Compiler}).
14034 This macro double quotes both @var{includes} and @var{function-body}.
14036 Depending on the current language (@pxref{Language Choice}), create a
14037 test program to see whether a function whose body consists of
14038 @var{function-body} can be compiled and linked. If the file compiles
14039 and links successfully, run shell commands @var{action-if-found},
14040 otherwise run @var{action-if-not-found}.
14042 This macro double quotes both @var{includes} and @var{function-body}.
14044 For C and C++, @var{includes} is any @code{#include} statements needed
14045 by the code in @var{function-body} (@var{includes} will be ignored if
14046 the currently selected language is Fortran or Fortran 77). The compiler
14047 and compilation flags are determined by the current language
14048 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
14049 @code{LIBS} are used for linking.
14052 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
14053 @acindex{TRY_LINK_FUNC}
14054 This macro is equivalent to
14055 @samp{AC_LINK_IFELSE([AC_LANG_CALL([[@var{includes}]],
14056 [[@var{function-body}]])], [@var{action-if-true}],
14057 [@var{action-if-false}])}.
14060 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
14062 Same as @samp{AC_RUN_IFELSE([AC_LANG_SOURCE([[@var{program}]],
14063 [@var{action-if-true}], [@var{action-if-false}],
14064 [@var{action-if-cross-compiling}])} (@pxref{Run Time}).
14070 @code{AC_TYPE_UID_T}
14073 @defmac AC_UNISTD_H
14075 Same as @samp{AC_CHECK_HEADERS(unistd.h)}.
14081 Define @code{USG} if the @acronym{BSD} string functions are defined in
14082 @file{strings.h}. You should no longer depend upon @code{USG}, but on
14083 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
14086 @defmac AC_UTIME_NULL
14087 @acindex{UTIME_NULL}
14088 @code{AC_FUNC_UTIME_NULL}
14091 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
14092 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
14093 If the cache file is inconsistent with the current host, target and
14094 build system types, it used to execute @var{cmd} or print a default
14095 error message. This is now handled by default.
14098 @defmac AC_VERBOSE (@var{result-description})
14100 @code{AC_MSG_RESULT}.
14105 @code{AC_FUNC_VFORK}
14110 @code{AC_FUNC_VPRINTF}
14115 @code{AC_FUNC_WAIT3}
14123 @defmac AC_WORDS_BIGENDIAN
14124 @acindex{WORDS_BIGENDIAN}
14125 @code{AC_C_BIGENDIAN}
14128 @defmac AC_XENIX_DIR
14129 @acindex{XENIX_DIR}
14131 This macro used to add @option{-lx} to output variable @code{LIBS} if on
14132 Xenix. Also, if @file{dirent.h} is being checked for, added
14133 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
14134 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
14135 running @sc{xenix} on which you should not depend:
14138 AC_MSG_CHECKING([for Xenix])
14140 [#if defined M_XENIX && !defined M_UNIX
14143 [AC_MSG_RESULT([yes]); XENIX=yes],
14144 [AC_MSG_RESULT([no]); XENIX=])
14148 @defmac AC_YYTEXT_POINTER
14149 @acindex{YYTEXT_POINTER}
14150 @code{AC_DECL_YYTEXT}
14154 @section Upgrading From Version 1
14155 @cindex Upgrading autoconf
14156 @cindex Autoconf upgrading
14158 Autoconf version 2 is mostly backward compatible with version 1.
14159 However, it introduces better ways to do some things, and doesn't
14160 support some of the ugly things in version 1. So, depending on how
14161 sophisticated your @file{configure.ac} files are, you might have to do
14162 some manual work in order to upgrade to version 2. This chapter points
14163 out some problems to watch for when upgrading. Also, perhaps your
14164 @command{configure} scripts could benefit from some of the new features in
14165 version 2; the changes are summarized in the file @file{NEWS} in the
14166 Autoconf distribution.
14169 * Changed File Names:: Files you might rename
14170 * Changed Makefiles:: New things to put in @file{Makefile.in}
14171 * Changed Macros:: Macro calls you might replace
14172 * Changed Results:: Changes in how to check test results
14173 * Changed Macro Writing:: Better ways to write your own macros
14176 @node Changed File Names
14177 @subsection Changed File Names
14179 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
14180 in a particular package's source directory), you must rename it to
14181 @file{acsite.m4}. @xref{autoconf Invocation}.
14183 If you distribute @file{install.sh} with your package, rename it to
14184 @file{install-sh} so @code{make} builtin rules won't inadvertently
14185 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
14186 looks for the script under both names, but it is best to use the new name.
14188 If you were using @file{config.h.top}, @file{config.h.bot}, or
14189 @file{acconfig.h}, you still can, but you will have less clutter if you
14190 use the @code{AH_} macros. @xref{Autoheader Macros}.
14192 @node Changed Makefiles
14193 @subsection Changed Makefiles
14195 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
14196 your @file{Makefile.in} files, so they can take advantage of the values
14197 of those variables in the environment when @command{configure} is run.
14198 Doing this isn't necessary, but it's a convenience for users.
14200 Also add @samp{@@configure_input@@} in a comment to each input file for
14201 @code{AC_OUTPUT}, so that the output files will contain a comment saying
14202 they were produced by @command{configure}. Automatically selecting the
14203 right comment syntax for all the kinds of files that people call
14204 @code{AC_OUTPUT} on became too much work.
14206 Add @file{config.log} and @file{config.cache} to the list of files you
14207 remove in @code{distclean} targets.
14209 If you have the following in @file{Makefile.in}:
14212 prefix = /usr/local
14213 exec_prefix = $(prefix)
14217 you must change it to:
14220 prefix = @@prefix@@
14221 exec_prefix = @@exec_prefix@@
14225 The old behavior of replacing those variables without @samp{@@}
14226 characters around them has been removed.
14228 @node Changed Macros
14229 @subsection Changed Macros
14231 Many of the macros were renamed in Autoconf version 2. You can still
14232 use the old names, but the new ones are clearer, and it's easier to find
14233 the documentation for them. @xref{Obsolete Macros}, for a table showing the
14234 new names for the old macros. Use the @command{autoupdate} program to
14235 convert your @file{configure.ac} to using the new macro names.
14236 @xref{autoupdate Invocation}.
14238 Some macros have been superseded by similar ones that do the job better,
14239 but are not call-compatible. If you get warnings about calling obsolete
14240 macros while running @command{autoconf}, you may safely ignore them, but
14241 your @command{configure} script will generally work better if you follow
14242 the advice that is printed about what to replace the obsolete macros with. In
14243 particular, the mechanism for reporting the results of tests has
14244 changed. If you were using @code{echo} or @code{AC_VERBOSE} (perhaps
14245 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output will
14246 look better if you switch to @code{AC_MSG_CHECKING} and
14247 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
14248 in conjunction with cache variables. @xref{Caching Results}.
14252 @node Changed Results
14253 @subsection Changed Results
14255 If you were checking the results of previous tests by examining the
14256 shell variable @code{DEFS}, you need to switch to checking the values of
14257 the cache variables for those tests. @code{DEFS} no longer exists while
14258 @command{configure} is running; it is only created when generating output
14259 files. This difference from version 1 is because properly quoting the
14260 contents of that variable turned out to be too cumbersome and
14261 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
14264 For example, here is a @file{configure.ac} fragment written for Autoconf
14268 AC_HAVE_FUNCS(syslog)
14270 *-DHAVE_SYSLOG*) ;;
14271 *) # syslog is not in the default libraries. See if it's in some other.
14273 for lib in bsd socket inet; do
14274 AC_CHECKING(for syslog in -l$lib)
14275 LIBS="$saved_LIBS -l$lib"
14276 AC_HAVE_FUNCS(syslog)
14278 *-DHAVE_SYSLOG*) break ;;
14286 Here is a way to write it for version 2:
14289 AC_CHECK_FUNCS(syslog)
14290 if test $ac_cv_func_syslog = no; then
14291 # syslog is not in the default libraries. See if it's in some other.
14292 for lib in bsd socket inet; do
14293 AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
14294 LIBS="$LIBS -l$lib"; break])
14299 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
14300 backslashes before quotes, you need to remove them. It now works
14301 predictably, and does not treat quotes (except back quotes) specially.
14302 @xref{Setting Output Variables}.
14304 All of the Boolean shell variables set by Autoconf macros now use
14305 @samp{yes} for the true value. Most of them use @samp{no} for false,
14306 though for backward compatibility some use the empty string instead. If
14307 you were relying on a shell variable being set to something like 1 or
14308 @samp{t} for true, you need to change your tests.
14310 @node Changed Macro Writing
14311 @subsection Changed Macro Writing
14313 When defining your own macros, you should now use @code{AC_DEFUN}
14314 instead of @code{define}. @code{AC_DEFUN} automatically calls
14315 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
14316 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
14317 messages on the screen. There's no actual harm in continuing to use the
14318 older way, but it's less convenient and attractive. @xref{Macro
14321 You probably looked at the macros that came with Autoconf as a guide for
14322 how to do things. It would be a good idea to take a look at the new
14323 versions of them, as the style is somewhat improved and they take
14324 advantage of some new features.
14326 If you were doing tricky things with undocumented Autoconf internals
14327 (macros, variables, diversions), check whether you need to change
14328 anything to account for changes that have been made. Perhaps you can
14329 even use an officially supported technique in version 2 instead of
14330 kludging. Or perhaps not.
14332 To speed up your locally written feature tests, add caching to them.
14333 See whether any of your tests are of general enough usefulness to
14334 encapsulate them into macros that you can share.
14337 @node Autoconf 2.13
14338 @section Upgrading From Version 2.13
14339 @cindex Upgrading autoconf
14340 @cindex Autoconf upgrading
14342 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
14343 suits this section@enddots{}
14346 Autoconf version 2.50 is mostly backward compatible with version 2.13.
14347 However, it introduces better ways to do some things, and doesn't
14348 support some of the ugly things in version 2.13. So, depending on how
14349 sophisticated your @file{configure.ac} files are, you might have to do
14350 some manual work in order to upgrade to version 2.50. This chapter
14351 points out some problems to watch for when upgrading. Also, perhaps
14352 your @command{configure} scripts could benefit from some of the new
14353 features in version 2.50; the changes are summarized in the file
14354 @file{NEWS} in the Autoconf distribution.
14358 * Changed Quotation:: Broken code which used to work
14359 * New Macros:: Interaction with foreign macros
14360 * Hosts and Cross-Compilation:: Bugward compatibility kludges
14361 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
14362 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
14365 @node Changed Quotation
14366 @subsection Changed Quotation
14368 The most important changes are invisible to you: the implementation of
14369 most macros have completely changed. This allowed more factorization of
14370 the code, better error messages, a higher uniformity of the user's
14371 interface etc. Unfortunately, as a side effect, some construct which
14372 used to (miraculously) work might break starting with Autoconf 2.50.
14373 The most common culprit is bad quotation.
14375 For instance, in the following example, the message is not properly
14380 AC_CHECK_HEADERS(foo.h,,
14381 AC_MSG_ERROR(cannot find foo.h, bailing out))
14386 Autoconf 2.13 simply ignores it:
14389 $ @kbd{autoconf-2.13; ./configure --silent}
14390 creating cache ./config.cache
14391 configure: error: cannot find foo.h
14396 while Autoconf 2.50 will produce a broken @file{configure}:
14399 $ @kbd{autoconf-2.50; ./configure --silent}
14400 configure: error: cannot find foo.h
14401 ./configure: exit: bad non-numeric arg `bailing'
14402 ./configure: exit: bad non-numeric arg `bailing'
14406 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
14411 AC_CHECK_HEADERS(foo.h,,
14412 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
14416 Many many (and many more) Autoconf macros were lacking proper quotation,
14417 including no less than@dots{} @code{AC_DEFUN} itself!
14420 $ @kbd{cat configure.in}
14421 AC_DEFUN([AC_PROG_INSTALL],
14422 [# My own much better version
14427 $ @kbd{autoconf-2.13}
14428 autoconf: Undefined macros:
14429 ***BUG in Autoconf--please report*** AC_FD_MSG
14430 ***BUG in Autoconf--please report*** AC_EPI
14431 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
14432 configure.in:5:AC_PROG_INSTALL
14433 $ @kbd{autoconf-2.50}
14439 @subsection New Macros
14441 @cindex undefined macro
14442 @cindex @code{_m4_divert_diversion}
14444 Because Autoconf has been dormant for years, Automake provided
14445 Autoconf-like macros for a while. Autoconf 2.50 now provides better
14446 versions of these macros, integrated in the @code{AC_} namespace,
14447 instead of @code{AM_}. But in order to ease the upgrading via
14448 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
14450 Unfortunately Automake did not quote the names of these macros!
14451 Therefore, when @command{m4} finds something like
14452 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
14453 @code{AM_TYPE_PTRDIFF_T} is
14454 expanded, replaced with its Autoconf definition.
14456 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will
14457 complain, in its own words:
14460 $ @kbd{cat configure.in}
14463 $ @kbd{aclocal-1.4}
14465 ./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
14466 actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from...
14467 ./aclocal.m4:17: the top level
14471 Future versions of Automake will simply no longer define most of these
14472 macros, and will properly quote the names of the remaining macros.
14473 But you don't have to wait for it to happen to do the right thing right
14474 now: do not depend upon macros from Automake as it is simply not its job
14475 to provide macros (but the one it requires itself):
14478 $ @kbd{cat configure.in}
14481 $ @kbd{rm aclocal.m4}
14483 autoupdate: `configure.in' is updated
14484 $ @kbd{cat configure.in}
14486 AC_CHECK_TYPES([ptrdiff_t])
14487 $ @kbd{aclocal-1.4}
14493 @node Hosts and Cross-Compilation
14494 @subsection Hosts and Cross-Compilation
14495 @cindex Cross compilation
14497 Based on the experience of compiler writers, and after long public
14498 debates, many aspects of the cross-compilation chain have changed:
14502 the relationship between the build, host, and target architecture types,
14505 the command line interface for specifying them to @command{configure},
14508 the variables defined in @command{configure},
14511 the enabling of cross-compilation mode.
14516 The relationship between build, host, and target have been cleaned up:
14517 the chain of default is now simply: target defaults to host, host to
14518 build, and build to the result of @command{config.guess}. Nevertheless,
14519 in order to ease the transition from 2.13 to 2.50, the following
14520 transition scheme is implemented. @emph{Do not rely on it}, as it will
14521 be completely disabled in a couple of releases (we cannot keep it, as it
14522 proves to cause more problems than it cures).
14524 They all default to the result of running @command{config.guess}, unless
14525 you specify either @option{--build} or @option{--host}. In this case,
14526 the default becomes the system type you specified. If you specify both,
14527 and they're different, @command{configure} will enter cross compilation
14528 mode, so it won't run any tests that require execution.
14530 Hint: if you mean to override the result of @command{config.guess},
14531 prefer @option{--build} over @option{--host}. In the future,
14532 @option{--host} will not override the name of the build system type.
14533 Whenever you specify @code{--host}, be sure to specify @code{--build}
14538 For backward compatibility, @command{configure} will accept a system
14539 type as an option by itself. Such an option will override the
14540 defaults for build, host, and target system types. The following
14541 configure statement will configure a cross toolchain that will run on
14542 Net@acronym{BSD}/alpha but generate code for @acronym{GNU} Hurd/sparc, which is
14543 also the build platform.
14546 ./configure --host=alpha-netbsd sparc-gnu
14551 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
14552 and @code{target} had a different semantics before and after the
14553 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
14554 @option{--build} is strictly copied into @code{build_alias}, and is left
14555 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
14556 set to the canonicalized build type. To ease the transition, before,
14557 its contents is the same as that of @code{build_alias}. Do @emph{not}
14558 rely on this broken feature.
14560 For consistency with the backward compatibility scheme exposed above,
14561 when @option{--host} is specified but @option{--build} isn't, the build
14562 system will be assumed to be the same as @option{--host}, and
14563 @samp{build_alias} will be set to that value. Eventually, this
14564 historically incorrect behavior will go away.
14568 The former scheme to enable cross-compilation proved to cause more harm
14569 than good, in particular, it used to be triggered too easily, leaving
14570 regular end users puzzled in front of cryptic error messages.
14571 @command{configure} could even enter cross-compilation mode only
14572 because the compiler was not functional. This is mainly because
14573 @command{configure} used to try to detect cross-compilation, instead of
14574 waiting for an explicit flag from the user.
14576 Now, @command{configure} enters cross-compilation mode if and only if
14577 @option{--host} is passed.
14579 That's the short documentation. To ease the transition between 2.13 and
14580 its successors, a more complicated scheme is implemented. @emph{Do not
14581 rely on the following}, as it will be removed in the near future.
14583 If you specify @option{--host}, but not @option{--build}, when
14584 @command{configure} performs the first compiler test it will try to run
14585 an executable produced by the compiler. If the execution fails, it will
14586 enter cross-compilation mode. This is fragile. Moreover, by the time
14587 the compiler test is performed, it may be too late to modify the
14588 build-system type: other tests may have already been performed.
14589 Therefore, whenever you specify @code{--host}, be sure to specify
14590 @code{--build} too.
14593 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
14597 will enter cross-compilation mode. The former interface, which
14598 consisted in setting the compiler to a cross-compiler without informing
14599 @command{configure} is obsolete. For instance, @command{configure} will
14600 fail if it can't run the code generated by the specified compiler if you
14601 configure as follows:
14604 ./configure CC=m68k-coff-gcc
14608 @node AC_LIBOBJ vs LIBOBJS
14609 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
14611 Up to Autoconf 2.13, the replacement of functions was triggered via the
14612 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
14613 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
14614 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
14616 This change is mandated by the unification of the @acronym{GNU} Build System
14617 components. In particular, the various fragile techniques used to parse
14618 a @file{configure.ac} are all replaced with the use of traces. As a
14619 consequence, any action must be traceable, which obsoletes critical
14620 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
14621 and it can even be handled gracefully (read, ``without your having to
14622 change something'').
14624 There were two typical uses of @code{LIBOBJS}: asking for a replacement
14625 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
14629 As for function replacement, the fix is immediate: use
14630 @code{AC_LIBOBJ}. For instance:
14633 LIBOBJS="$LIBOBJS fnmatch.o"
14634 LIBOBJS="$LIBOBJS malloc.$ac_objext"
14638 should be replaced with:
14641 AC_LIBOBJ([fnmatch])
14642 AC_LIBOBJ([malloc])
14649 When asked for automatic de-ANSI-fication, Automake needs
14650 @code{LIBOBJS}'ed filenames to have @samp{$U} appended to the base
14651 names. Libtool requires the definition of @code{LTLIBOBJS}, whose
14652 suffixes are mapped to @samp{.lo}. People used to run snippets such as:
14655 # This is necessary so that .o files in LIBOBJS are also built via
14656 # the ANSI2KNR-filtering rules.
14657 LIBOBJS=`echo "$LIBOBJS" | sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
14658 LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.o/\.lo/g'`
14659 AC_SUBST(LTLIBOBJS)
14663 Note that this code is @emph{wrong}, because @samp{.o} is not the only
14664 possible extension@footnote{
14666 Yet another reason why assigning @code{LIBOBJS} directly is discouraged.
14668 }! It should have read:
14671 # This is necessary so that .o files in LIBOBJS are also built via
14672 # the ANSI2KNR-filtering rules.
14673 LIB@@&t@@OBJS=`echo "$LIB@@&t@@OBJS" |
14674 sed 's,\.[[^.]]* ,$U&,g;s,\.[[^.]]*$,$U&,'`
14675 LTLIBOBJS=`echo "$LIB@@&t@@OBJS" |
14676 sed 's,\.[[^.]]* ,.lo ,g;s,\.[[^.]]*$,.lo,'`
14677 AC_SUBST(LTLIBOBJS)
14682 You no longer have to use this: @code{AC_OUTPUT} normalizes
14683 @code{LIBOBJS} and @code{LTLIBOBJS} (hence it works with any version of
14684 Automake and Libtool). Just remove these lines (@command{autoupdate}
14685 cannot handle this task, since this is not a macro).
14687 Note that @code{U} must not be used in your Makefiles.
14690 @node AC_FOO_IFELSE vs AC_TRY_FOO
14691 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
14693 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
14694 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
14695 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
14696 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
14697 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
14698 @code{AC_TRY_RUN}. The motivations where:
14701 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
14702 quoting their arguments;
14705 the combinatoric explosion is solved by decomposing on the one hand the
14706 generation of sources, and on the other hand executing the program;
14709 this scheme helps supporting more languages than plain C and C++.
14712 In addition to the change of syntax, the philosphy has changed too:
14713 while emphasis was put on speed at the expense of accuracy, today's
14714 Autoconf promotes accuracy of the testing framework at, ahem..., the
14718 As a perfect example of what is @emph{not} to be done, here is how to
14719 find out whether a header file contains a particular declaration, such
14720 as a typedef, a structure, a structure member, or a function. Use
14721 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
14722 header file; on some systems the symbol might be defined in another
14723 header file that the file you are checking @samp{#include}s.
14725 As a (bad) example, here is how you should not check for C preprocessor
14726 symbols, either defined by header files or predefined by the C
14727 preprocessor: using @code{AC_EGREP_CPP}:
14735 ], is_aix=yes, is_aix=no)
14739 The above example, properly written would (i) use
14740 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
14744 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
14745 [[#if !defined _AIX
14746 # error _AIX not defined
14755 @c ============================= Generating Test Suites with Autotest
14757 @node Using Autotest
14758 @chapter Generating Test Suites with Autotest
14763 @strong{N.B.: This section describes an experimental feature which will
14764 be part of Autoconf in a forthcoming release. Although we believe
14765 Autotest is stabilizing, this documentation describes an interface which
14766 might change in the future: do not depend upon Autotest without
14767 subscribing to the Autoconf mailing lists.}
14770 It is paradoxical that portable projects depend on nonportable tools
14771 to run their test suite. Autoconf by itself is the paragon of this
14772 problem: although it aims at perfectly portability, up to 2.13, its
14773 test suite was using Deja@acronym{GNU}, a rich and complex testing
14774 framework, but which is far from being standard on Unix systems.
14775 Worse yet, it was likely to be missing on the most fragile platforms,
14776 the very platforms that are most likely to torture Autoconf and
14777 exhibit deficiencies.
14779 To circumvent this problem many package maintainers have developed their
14780 own testing framework, based on simple shell scripts whose sole output
14781 are their exit status: the test succeeded, or failed. In addition, most
14782 of these tests share some common patterns, what results in lots of
14783 duplicated code, tedious maintenance etc.
14785 Following exactly the same reasoning that yielded to the inception of
14786 Autoconf, Autotest provides a test suite generation frame work, based on
14787 M4 macros, building a portable shell script. The suite itself is
14788 equipped with automatic logging and tracing facilities which greatly
14789 diminish the interaction with bug reporters, and simple timing reports.
14791 Autoconf itself has been using Autotest for years, and we do attest that
14792 it has considerably improved the strength of the test suite, and the
14793 quality of bug reports. Other projects are known to use some generation
14794 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
14795 them having different needs, what slowly polishes Autotest as a general
14798 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
14799 interactive tool testing, which is probably its main limitation.
14802 * Using an Autotest Test Suite:: Autotest and the user
14803 * Writing testsuite.at:: Autotest macros
14804 * testsuite Invocation:: Running @command{testsuite} scripts
14805 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
14808 @node Using an Autotest Test Suite
14809 @section Using an Autotest Test Suite
14812 * testsuite Scripts:: The concepts of Autotest
14813 * Autotest Logs:: Their contents
14816 @node testsuite Scripts
14817 @subsection @command{testsuite} Scripts
14819 @cindex @command{testsuite}
14821 Generating testing or validation suites using Autotest is rather easy.
14822 The whole validation suite is held in a file to be processed through
14823 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
14824 produce a stand-alone Bourne shell script which then gets distributed.
14825 Neither @command{autom4te} nor @acronym{GNU} M4 are not needed anymore at
14829 Each test of the validation suite should be part of some test group. A
14830 @dfn{test group} is a sequence of interwoven tests that ought to be
14831 executed together, usually because one test in the group creates data
14832 files than a later test in the same group needs to read. Complex test
14833 groups make later debugging more tedious. It is much better keeping
14834 keep only a few tests per test group, and if you can put only one test
14835 per test group, this is just ideal.
14837 For all but the simplest packages, some file such as @file{testsuite.at}
14838 does not fully hold all test sources, as these are often easier to
14839 maintain in separate files. Each of these separate files holds a single
14840 test group, or a sequence of test groups all addressing some common
14841 functionality in the package. In such cases, file @file{testsuite.at}
14842 only initializes the whole validation suite, and sometimes do elementary
14843 health checking, before listing include statements for all other test
14844 files. The special file @file{package.m4}, containing the
14845 identification of the package, is automatically included if found.
14847 A convenient alternative consists in moving all the global issues
14848 (local Autotest macros, elementary health checking, and @code{AT_INIT}
14849 invocation) into the file @code{local.at}, and making
14850 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
14851 suites. In such case, generating the whole test suite or pieces of it
14852 is only a matter of choosing the @command{autom4te} command line
14855 The validation scripts that Autotest produces are by convention called
14856 @command{testsuite}. When run, @command{testsuite} executes each test
14857 group in turn, producing only one summary line per test to say if that
14858 particular test succeeded or failed. At end of all tests, summarizing
14859 counters get printed. One debugging directory is left for each test
14860 group which failed, if any: such directories are named
14861 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
14862 the test group, and they include:
14865 @item a debugging script named @file{run} which reruns the test in
14866 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
14867 of debugging scripts has the purpose of easing the chase for bugs.
14869 @item all the files created with @code{AT_DATA}
14871 @item a log of the run, named @file{testsuite.log}
14874 In the ideal situation, none of the tests fail, and consequently, no
14875 debugging directory is left out of validation.
14877 It often happens in practice that individual tests in the validation
14878 suite need to get information coming out of the configuration process.
14879 Some of this information, common for all validation suites, is provided
14880 through the file @file{atconfig}, automatically created by
14881 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
14882 testing environment specifically needs, you might prepare an optional
14883 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
14884 The configuration process produces @file{atconfig} and @file{atlocal}
14885 out of these two input files, and these two produced files are
14886 automatically read by the @file{testsuite} script.
14888 Here is a diagram showing the relationship between files.
14891 Files used in preparing a software package for distribution:
14896 subfile-1.at ->. [local.at] ---->+
14898 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
14904 Files used in configuring a software package:
14909 [atlocal.in] --> config.status* --<
14915 Files created during the test suite execution:
14918 atconfig -->. .--> testsuite.log
14922 [atlocal] ->' `--> [testsuite.dir]
14926 @node Autotest Logs
14927 @subsection Autotest Logs
14929 When run, the test suite creates a log file named after itself, e.g., a
14930 test suite named @command{testsuite} creates @file{testsuite.log}. It
14931 contains a lot of information, usually more than maintainers actually
14932 need, but therefore most of the time it contains all that is needed:
14935 @item command line arguments
14936 @c akim s/to consist in/to consist of/
14937 A very bad Unix habit which is unfortunately wide spread consists of
14938 setting environment variables before the command, such as in
14939 @samp{CC=my-home-grown-cc ./testsuite}. This results in the test suite
14940 not knowing this change, hence (i) it can't report it to you, and (ii)
14941 it cannot preserve the value of @code{CC} for subsequent runs.
14942 Autoconf faced exactly the same problem, and solved it by asking
14943 users to pass the variable definitions as command line arguments.
14944 Autotest requires this rule too, but has no means to enforce it; the log
14945 then contains a trace of the variables the user changed.
14947 @item @file{ChangeLog} excerpts
14948 The topmost lines of all the @file{ChangeLog}s found in the source
14949 hierarchy. This is especially useful when bugs are reported against
14950 development versions of the package, since the version string does not
14951 provide sufficient information to know the exact state of the sources
14952 the user compiled. Of course this relies on the use of a
14955 @item build machine
14956 Running a test suite in a cross-compile environment is not an easy task,
14957 since it would mean having the test suite run on a machine @var{build},
14958 while running programs on a machine @var{host}. It is much simpler to
14959 run both the test suite and the programs on @var{host}, but then, from
14960 the point of view of the test suite, there remains a single environment,
14961 @var{host} = @var{build}. The log contains relevant information on the
14962 state of the build machine, including some important environment
14964 @c FIXME: How about having an M4sh macro to say `hey, log the value
14965 @c of `@dots{}'? This would help both Autoconf and Autotest.
14967 @item tested programs
14968 The absolute path and answers to @option{--version} of the tested
14969 programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}).
14971 @item configuration log
14972 The contents of @file{config.log}, as created by @command{configure},
14973 are appended. It contains the configuration flags and a detailed report
14974 on the configuration itself.
14978 @node Writing testsuite.at
14979 @section Writing @file{testsuite.at}
14981 The @file{testsuite.at} is a Bourne shell script making use of special
14982 Autotest M4 macros. It often contains a call to @code{AT_INIT} nears
14983 its beginning followed by one call to @code{m4_include} per source file
14984 for tests. Each such included file, or the remainder of
14985 @file{testsuite.at} if include files are not used, contain a sequence of
14986 test groups. Each test group begins with one call to @code{AT_SETUP},
14987 it contains an arbitrary number of shell commands or calls to
14988 @code{AT_CHECK}, and it completes with one call to @code{AT_CLEANUP}.
14990 @defmac AT_INIT (@ovar{name})
14992 @c FIXME: Not clear, plus duplication of the information.
14993 Initialize Autotest. Giving a @var{name} to the test suite is
14994 encouraged if your package includes several test suites. In any case,
14995 the test suite always displays the package name and version. It also
14996 inherits the package bug report address.
14999 @defmac AT_TESTED (@var{executables})
15001 Log the path and answer to @option{--version} of each program in
15002 space-separated list @var{executables}. Several invocations register
15003 new executables, in other words, don't fear registering one program
15007 Autotest test suites rely on the @code{PATH} to find the tested program.
15008 This saves from generating the absolute paths to the various tools, and
15009 makes it possible to test installed programs. Therefore, knowing what
15010 programs are being exercised is crucial to understand some problems in
15011 the test suite itself, or its occasional misuses. It is a good idea to
15012 also subscribe foreign programs you depend upon, to ease incompatibility
15017 @defmac AT_SETUP (@var{test-group-name})
15019 This macro starts a group of related tests, all to be executed in the
15020 same subshell. It accepts a single argument, which holds a few words
15021 (no more than about 30 or 40 characters) quickly describing the purpose
15022 of the test group being started.
15025 @defmac AT_KEYWORDS (@var{keywords})
15027 Associate the space-separated list of @var{keywords} to the enclosing
15028 test group. This makes it possible to run ``slices'' of the test suite.
15029 For instance if some of your test groups exercise some @samp{foo}
15030 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
15031 @samp{./testsuite -k foo} to run exclusively these test groups. The
15032 @var{title} of the test group is automatically recorded to
15033 @code{AT_KEYWORDS}.
15035 Several invocations within a test group accumulate new keywords. In
15036 other words, don't fear registering several times the same keyword in a
15040 @defmac AT_XFAIL_IF (@var{shell-condition})
15042 Determine whether the test is expected to fail because it is a known
15043 bug (for unsupported features, you should skip the test).
15044 @var{shell-condition} is a shell expression such as a @code{test}
15045 command; you can instantiate this macro many times from within the
15046 same test group, and one of the conditions will be enough to turn
15047 the test into an expected failure.
15052 End the current test group.
15057 @defmac AT_DATA (@var{file}, @var{contents})
15059 Initialize an input data @var{file} with given @var{contents}. Of
15060 course, the @var{contents} have to be properly quoted between square
15061 brackets to protect against included commas or spurious M4
15062 expansion. The contents ought to end with an end of line.
15065 @defmac AT_CHECK (@var{commands}, @dvar{status, @samp{0}}, @dvar{stdout, @samp{}}, @dvar{stderr, @samp{}}, @ovar{run-if-fail}, @ovar{run-if-pass})
15067 Execute a test by performing given shell @var{commands}. These commands
15068 should normally exit with @var{status}, while producing expected
15069 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
15070 status 77, then the whole test group is skipped. Otherwise, if this test
15071 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
15072 commands @var{run-if-pass}.
15074 The @var{commands} @emph{must not} redirect the standard output, nor the
15077 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
15078 the corresponding value is not checked.
15080 The special value @samp{expout} for @var{stdout} means the expected
15081 output of the @var{commands} is the content of the file @file{expout}.
15082 If @var{stdout} is @samp{stdout}, then the standard output of the
15083 @var{commands} is available for further tests in the file @file{stdout}.
15084 Similarly for @var{stderr} with @samp{expout} and @samp{stderr}.
15088 @node testsuite Invocation
15089 @section Running @command{testsuite} Scripts
15090 @cindex @command{testsuite}
15092 Autotest test suites support the following arguments:
15097 Display the list of options and exit successfully.
15101 Display the version of the test suite and exit successfully.
15105 Remove all the files the test suite might have created and exit. Meant
15106 for @code{clean} Makefile targets.
15110 List all the tests (or only the selection), including their possible
15116 By default all the tests are performed (or described with
15117 @option{--list}) in the default environment first silently, then
15118 verbosely, but the environment, set of tests, and verbosity level can be
15122 @item @var{variable}=@var{value}
15123 Set the environment @var{variable} to @var{value}. Do not run
15124 @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
15125 different environment.
15127 @cindex @code{AUTOTEST_PATH}
15128 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
15129 to @code{PATH}. It handles specially relative paths (not starting with
15130 @samp{/}): they are considered to be relative to the top level of the
15131 package being built. All the directories are made absolute, first
15132 starting from the top level @emph{build} tree, then from the
15133 @emph{source} tree. For instance @samp{./testsuite
15134 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
15135 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
15136 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
15140 @itemx @var{number}-@var{number}
15141 @itemx @var{number}-
15142 @itemx -@var{number}
15143 Add the corresponding test groups, with obvious semantics, to the
15146 @item --keywords=@var{keywords}
15147 @itemx -k @var{keywords}
15148 Add to the selection the test groups which title or keywords (arguments
15149 to @code{AT_SETUP} or @code{AT_KEYWORDS}) match @emph{all} the keywords
15150 of the comma separated list @var{keywords}.
15152 Running @samp{./testsuite -k autoupdate,FUNC} will select all the tests
15153 tagged with @samp{autoupdate} @emph{and} @samp{FUNC} (as in
15154 @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_FNMATCH} etc.) while
15155 @samp{./testsuite -k autoupdate -k FUNC} runs all the tests tagged with
15156 @samp{autoupdate} @emph{or} @samp{FUNC}.
15160 If any test fails, immediately abort testing. It implies
15161 @option{--debug}: post test group clean up, debugging script generation,
15162 and logging are inhibited. This option is meant for the full test
15163 suite, it is not really useful for generated debugging scripts.
15167 Force more verbosity in the detailed output of what is being done. This
15168 is the default for debugging scripts.
15172 Do not remove the files after a test group was performed ---but they are
15173 still removed @emph{before}, therefore using this option is sane when
15174 running several test groups. Do not create debugging scripts. Do not
15175 log (in order to preserve supposedly existing full log file). This is
15176 the default for debugging scripts, but it can also be useful to debug
15177 the testsuite itself.
15181 Trigger shell tracing of the test groups.
15185 @node Making testsuite Scripts
15186 @section Making @command{testsuite} Scripts
15188 For putting Autotest into movement, you need some configuration and
15189 Makefile machinery. We recommend, at least if your package uses deep or
15190 shallow hierarchies, that you use @file{tests/} as the name of the
15191 directory holding all your tests and their @file{Makefile}. Here is a
15192 check list of things to do.
15197 @cindex @file{package.m4}
15198 Make sure to create the file @file{package.m4}, which defines the
15199 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
15200 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
15201 address to which bug reports should be sent. For sake of completeness,
15202 we suggest that you also define @code{AT_PACKAGE_NAME},
15203 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
15204 @xref{Initializing configure}, for a description of these variables. We
15205 suggest the following Makefile excerpt:
15208 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
15210 echo '# Signature of the current package.'; \
15211 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
15212 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
15213 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
15214 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
15215 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
15216 @} >$(srcdir)/package.m4
15220 Be sure to distribute @file{package.m4} and to put it into the source
15221 hierarchy: the test suite ought to be shipped!
15224 Invoke @code{AC_CONFIG_TESTDIR}.
15226 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, @var{directory}})
15227 @acindex{CONFIG_TESTDIR}
15228 An Autotest test suite is to be configured in @var{directory}. This
15229 macro requires the instantiation of @file{@var{directory}/atconfig} from
15230 @file{@var{directory}/atconfig.in}, and sets the default
15231 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
15235 Still within @file{configure.ac}, as appropriate, ensure that some
15236 @code{AC_CONFIG_FILES} command includes substitution for
15237 @file{tests/atlocal}.
15240 The @file{tests/Makefile.in} should be modified so the validation in
15241 your package is triggered by @samp{make check}. An example is provided
15245 With Automake, here is a minimal example about how to link @samp{make
15246 check} with a validation suite.
15249 EXTRA_DIST = testsuite.at testsuite
15250 TESTSUITE = $(srcdir)/testsuite
15251 check-local: atconfig atlocal $(TESTSUITE)
15252 $(SHELL) $(TESTSUITE)
15254 AUTOTEST = $(AUTOM4TE) --language=autotest
15255 $(TESTSUITE): $(srcdir)/testsuite.at
15256 $(AUTOTEST) -I $(srcdir) -o $@@.tmp $@@.at
15260 You might want to list explicitly the dependencies, i.e., the list of
15261 the files @file{testsuite.at} includes.
15263 With strict Autoconf, you might need to add lines inspired from the
15269 atconfig: $(top_builddir)/config.status
15270 cd $(top_builddir) && \
15271 $(SHELL) ./config.status $(subdir)/$@@
15273 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
15274 cd $(top_builddir) && \
15275 $(SHELL) ./config.status $(subdir)/$@@
15279 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
15284 @c =============================== Frequent Autoconf Questions, with answers
15287 @chapter Frequent Autoconf Questions, with answers
15289 Several questions about Autoconf come up occasionally. Here some of them
15293 * Distributing:: Distributing @command{configure} scripts
15294 * Why GNU m4:: Why not use the standard M4?
15295 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
15296 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
15297 * Defining Directories:: Passing @code{datadir} to program
15298 * autom4te.cache:: What is it? Can I remove it?
15299 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
15303 @section Distributing @command{configure} Scripts
15307 What are the restrictions on distributing @command{configure}
15308 scripts that Autoconf generates? How does that affect my
15309 programs that use them?
15312 There are no restrictions on how the configuration scripts that Autoconf
15313 produces may be distributed or used. In Autoconf version 1, they were
15314 covered by the @acronym{GNU} General Public License. We still encourage
15315 software authors to distribute their work under terms like those of the
15316 GPL, but doing so is not required to use Autoconf.
15318 Of the other files that might be used with @command{configure},
15319 @file{config.h.in} is under whatever copyright you use for your
15320 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
15321 exception to the GPL when they are used with an Autoconf-generated
15322 @command{configure} script, which permits you to distribute them under the
15323 same terms as the rest of your package. @file{install-sh} is from the X
15324 Consortium and is not copyrighted.
15327 @section Why Require @acronym{GNU} M4?
15330 Why does Autoconf require @acronym{GNU} M4?
15333 Many M4 implementations have hard-coded limitations on the size and
15334 number of macros that Autoconf exceeds. They also lack several
15335 builtin macros that it would be difficult to get along without in a
15336 sophisticated application like Autoconf, including:
15346 Autoconf requires version 1.4 or above of @acronym{GNU} M4 because it uses
15347 frozen state files.
15349 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
15350 M4 is simple to configure and install, it seems reasonable to require
15351 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
15352 other free software already have most of the @acronym{GNU} utilities
15353 installed, since they prefer them.
15355 @node Bootstrapping
15356 @section How Can I Bootstrap?
15360 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
15361 @command{configure} script, how do I bootstrap? It seems like a chicken
15365 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
15366 @command{configure} script produced by Autoconf, Autoconf is not required
15367 in order to run the script and install @acronym{GNU} M4. Autoconf is only
15368 required if you want to change the M4 @command{configure} script, which few
15369 people have to do (mainly its maintainer).
15371 @node Why Not Imake
15372 @section Why Not Imake?
15376 Why not use Imake instead of @command{configure} scripts?
15379 Several people have written addressing this question, so I include
15380 adaptations of their explanations here.
15382 The following answer is based on one written by Richard Pixley:
15385 Autoconf generated scripts frequently work on machines that it has
15386 never been set up to handle before. That is, it does a good job of
15387 inferring a configuration for a new system. Imake cannot do this.
15389 Imake uses a common database of host specific data. For X11, this makes
15390 sense because the distribution is made as a collection of tools, by one
15391 central authority who has control over the database.
15393 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
15394 maintainer; these maintainers are scattered across the world. Using a
15395 common database would be a maintenance nightmare. Autoconf may appear
15396 to be this kind of database, but in fact it is not. Instead of listing
15397 host dependencies, it lists program requirements.
15399 If you view the @acronym{GNU} suite as a collection of native tools, then the
15400 problems are similar. But the @acronym{GNU} development tools can be
15401 configured as cross tools in almost any host+target permutation. All of
15402 these configurations can be installed concurrently. They can even be
15403 configured to share host independent files across hosts. Imake doesn't
15404 address these issues.
15406 Imake templates are a form of standardization. The @acronym{GNU} coding
15407 standards address the same issues without necessarily imposing the same
15412 Here is some further explanation, written by Per Bothner:
15415 One of the advantages of Imake is that it easy to generate large
15416 Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms.
15417 However, @code{cpp} is not programmable: it has limited conditional
15418 facilities, and no looping. And @code{cpp} cannot inspect its
15421 All of these problems are solved by using @code{sh} instead of
15422 @code{cpp}. The shell is fully programmable, has macro substitution,
15423 can execute (or source) other shell scripts, and can inspect its
15428 Paul Eggert elaborates more:
15431 With Autoconf, installers need not assume that Imake itself is already
15432 installed and working well. This may not seem like much of an advantage
15433 to people who are accustomed to Imake. But on many hosts Imake is not
15434 installed or the default installation is not working well, and requiring
15435 Imake to install a package hinders the acceptance of that package on
15436 those hosts. For example, the Imake template and configuration files
15437 might not be installed properly on a host, or the Imake build procedure
15438 might wrongly assume that all source files are in one big directory
15439 tree, or the Imake configuration might assume one compiler whereas the
15440 package or the installer needs to use another, or there might be a
15441 version mismatch between the Imake expected by the package and the Imake
15442 supported by the host. These problems are much rarer with Autoconf,
15443 where each package comes with its own independent configuration
15446 Also, Imake often suffers from unexpected interactions between
15447 @command{make} and the installer's C preprocessor. The fundamental problem
15448 here is that the C preprocessor was designed to preprocess C programs,
15449 not @file{Makefile}s. This is much less of a problem with Autoconf,
15450 which uses the general-purpose preprocessor M4, and where the
15451 package's author (rather than the installer) does the preprocessing in a
15456 Finally, Mark Eichin notes:
15459 Imake isn't all that extensible, either. In order to add new features to
15460 Imake, you need to provide your own project template, and duplicate most
15461 of the features of the existing one. This means that for a sophisticated
15462 project, using the vendor-provided Imake templates fails to provide any
15463 leverage---since they don't cover anything that your own project needs
15464 (unless it is an X11 program).
15466 On the other side, though:
15468 The one advantage that Imake has over @command{configure}:
15469 @file{Imakefile}s tend to be much shorter (likewise, less redundant)
15470 than @file{Makefile.in}s. There is a fix to this, however---at least
15471 for the Kerberos V5 tree, we've modified things to call in common
15472 @file{post.in} and @file{pre.in} @file{Makefile} fragments for the
15473 entire tree. This means that a lot of common things don't have to be
15474 duplicated, even though they normally are in @command{configure} setups.
15478 @node Defining Directories
15479 @section How Do I @code{#define} Installation Directories?
15482 My program needs library files, installed in @code{datadir} and
15486 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
15487 [Define to the read-only architecture-independent
15495 #define DATADIR "$@{prefix@}/share"
15499 As already explained, this behavior is on purpose, mandated by the
15500 @acronym{GNU} Coding Standards, see @ref{Installation Directory
15501 Variables}. There are several means to achieve a similar goal:
15505 Do not use @code{AC_DEFINE} but use your @file{Makefile} to pass the
15506 actual value of @code{datadir} via compilation flags, see
15507 @ref{Installation Directory Variables}, for the details.
15510 This solution can be simplified when compiling a program: you may either
15511 extend the @code{CPPFLAGS}:
15514 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
15518 or create a dedicated header file:
15521 DISTCLEANFILES = datadir.h
15522 datadir.h: Makefile
15523 echo '#define DATADIR "$(datadir)"' >$@@
15527 Use @code{AC_DEFINE} but have @command{configure} compute the literal
15528 value of @code{datadir} and others. Many people have wrapped macros to
15529 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
15530 the @href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
15533 This solution does not conform to the @acronym{GNU} Coding Standards.
15536 Note that all the previous solutions hard wire the absolute path to
15537 these directories in the executables, which is not a good property. You
15538 may try to compute the paths relatively to @code{prefix}, and try to
15539 find @code{prefix} at runtime, this way your package is relocatable.
15540 Some macros are already available to address this issue: see
15541 @code{adl_COMPUTE_RELATIVE_PATHS} and
15542 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
15543 @href{http://www.gnu.org/software/ac-archive/, Autoconf Macro Archive}.
15547 @node autom4te.cache
15548 @section What is @file{autom4te.cache}?
15551 What is this directory @file{autom4te.cache}? Can I safely remove it?
15554 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
15555 role and is read by many tools: @command{autoconf} to create
15556 @file{configure}, @command{autoheader} to create @file{config.h.in},
15557 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
15558 check the completeness of @file{configure.ac}, @command{autoreconf} to
15559 check the @acronym{GNU} Build System components that are used. To
15560 ``read @file{configure.ac}'' actually means to compile it with M4,
15561 which can be a very long process for complex @file{configure.ac}.
15563 This is why all these tools, instead of running directly M4, invoke
15564 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
15565 a specific demand, stores additional information in
15566 @file{autom4te.cache} for future runs. For instance, if you run
15567 @command{autoconf}, behind the scenes, @command{autom4te} will also
15568 store information for the other tools, so that when you invoke
15569 @command{autoheader} or @command{automake} etc., re-processing
15570 @file{configure.ac} is not needed. The speed up is frequently of 30,
15571 and is increasing with the size of @file{configure.ac}.
15573 But it is and remains being simply a cache: you can safely remove it.
15578 Can I permanently get rid of it?
15581 The creation of this cache can be disabled from
15582 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
15583 details. You should be aware that disabling the cache slows down the
15584 Autoconf test suite by 40%. The more @acronym{GNU} Build System
15585 components are used, the more the cache is useful; for instance
15586 running @samp{autoreconf -f} on the Coreutils is twice slower without
15587 the cache @emph{although @option{--force} implies that the cache is
15588 not fully exploited}, and eight times slower than without
15592 @node Present But Cannot Be Compiled
15593 @section Header Present But Cannot Be Compiled
15595 The most important guideline to bear in mind when checking for
15596 features is to mimic as much as possible the intended use.
15597 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
15598 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
15599 the preprocessor, instead of the compiler, to check for headers. As a
15600 result, incompatibilities between headers went unnoticed during
15601 configuration, and maintainers finally had to deal with this issue
15604 As of Autoconf 2.56 both checks are performed, and @code{configure}
15605 complains loudly if the compiler and the preprocessor do not agree.
15606 For the time being the result used is that of the preprocessor, to give
15607 maintainers time to adjust their @file{configure.ac}, but in the near
15608 future, only the compiler will be considered.
15610 Consider the following example:
15613 $ @kbd{cat number.h}
15614 typedef int number;
15616 const number pi = 3;
15617 $ @kbd{cat configure.ac}
15619 AC_CHECK_HEADERS(pi.h)
15620 $ @kbd{autoconf -Wall}
15621 $ @kbd{./configure}
15622 checking for gcc... gcc
15623 checking for C compiler default output... a.out
15624 checking whether the C compiler works... yes
15625 checking whether we are cross compiling... no
15626 checking for suffix of executables...
15627 checking for suffix of object files... o
15628 checking whether we are using the GNU C compiler... yes
15629 checking whether gcc accepts -g... yes
15630 checking for gcc option to accept ANSI C... none needed
15631 checking how to run the C preprocessor... gcc -E
15632 checking for egrep... grep -E
15633 checking for ANSI C header files... yes
15634 checking for sys/types.h... yes
15635 checking for sys/stat.h... yes
15636 checking for stdlib.h... yes
15637 checking for string.h... yes
15638 checking for memory.h... yes
15639 checking for strings.h... yes
15640 checking for inttypes.h... yes
15641 checking for stdint.h... yes
15642 checking for unistd.h... yes
15643 checking pi.h usability... no
15644 checking pi.h presence... yes
15645 configure: WARNING: pi.h: present but cannot be compiled
15646 configure: WARNING: pi.h: check for missing prerequisite headers?
15647 configure: WARNING: pi.h: proceeding with the preprocessor's result
15648 configure: WARNING: ## ------------------------------------ ##
15649 configure: WARNING: ## Report this to bug-autoconf@@gnu.org. ##
15650 configure: WARNING: ## ------------------------------------ ##
15651 checking for pi.h... yes
15655 The proper way the handle this case is using the fourth argument
15656 (@pxref{Generic Headers}):
15659 $ @kbd{cat configure.ac}
15661 AC_CHECK_HEADERS(number.h pi.h,,,
15662 [[#if HAVE_NUMBER_H
15663 # include <number.h>
15666 $ @kbd{autoconf -Wall}
15667 $ @kbd{./configure}
15668 checking for gcc... gcc
15669 checking for C compiler default output... a.out
15670 checking whether the C compiler works... yes
15671 checking whether we are cross compiling... no
15672 checking for suffix of executables...
15673 checking for suffix of object files... o
15674 checking whether we are using the GNU C compiler... yes
15675 checking whether gcc accepts -g... yes
15676 checking for gcc option to accept ANSI C... none needed
15677 checking for number.h... yes
15678 checking for pi.h... yes
15681 See @ref{Particular Headers}, for a list of headers with their
15684 @c ===================================================== History of Autoconf.
15687 @chapter History of Autoconf
15688 @cindex History of autoconf
15690 You may be wondering, Why was Autoconf originally written? How did it
15691 get into its present form? (Why does it look like gorilla spit?) If
15692 you're not wondering, then this chapter contains no information useful
15693 to you, and you might as well skip it. If you @emph{are} wondering,
15694 then let there be light@enddots{}
15697 * Genesis:: Prehistory and naming of @command{configure}
15698 * Exodus:: The plagues of M4 and Perl
15699 * Leviticus:: The priestly code of portability arrives
15700 * Numbers:: Growth and contributors
15701 * Deuteronomy:: Approaching the promises of easy configuration
15707 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
15708 Free Software Foundation. As they were ported to more platforms and
15709 more programs were added, the number of @option{-D} options that users
15710 had to select in the @file{Makefile} (around 20) became burdensome.
15711 Especially for me---I had to test each new release on a bunch of
15712 different systems. So I wrote a little shell script to guess some of
15713 the correct settings for the fileutils package, and released it as part
15714 of fileutils 2.0. That @command{configure} script worked well enough that
15715 the next month I adapted it (by hand) to create similar @command{configure}
15716 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
15717 also adapted one of my scripts for his @acronym{CVS} revision control system.
15719 Later that summer, I learned that Richard Stallman and Richard Pixley
15720 were developing similar scripts to use in the @acronym{GNU} compiler tools;
15721 so I adapted my @command{configure} scripts to support their evolving
15722 interface: using the file name @file{Makefile.in} as the templates;
15723 adding @samp{+srcdir}, the first option (of many); and creating
15724 @file{config.status} files.
15729 As I got feedback from users, I incorporated many improvements, using
15730 Emacs to search and replace, cut and paste, similar changes in each of
15731 the scripts. As I adapted more @acronym{GNU} utilities packages to use
15732 @command{configure} scripts, updating them all by hand became impractical.
15733 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
15734 mail saying that the @command{configure} scripts were great, and asking if
15735 I had a tool for generating them that I could send him. No, I thought,
15736 but I should! So I started to work out how to generate them. And the
15737 journey from the slavery of hand-written @command{configure} scripts to the
15738 abundance and ease of Autoconf began.
15740 Cygnus @command{configure}, which was being developed at around that time,
15741 is table driven; it is meant to deal mainly with a discrete number of
15742 system types with a small number of mainly unguessable features (such as
15743 details of the object file format). The automatic configuration system
15744 that Brian Fox had developed for Bash takes a similar approach. For
15745 general use, it seems to me a hopeless cause to try to maintain an
15746 up-to-date database of which features each variant of each operating
15747 system has. It's easier and more reliable to check for most features on
15748 the fly---especially on hybrid systems that people have hacked on
15749 locally or that have patches from vendors installed.
15751 I considered using an architecture similar to that of Cygnus
15752 @command{configure}, where there is a single @command{configure} script that
15753 reads pieces of @file{configure.in} when run. But I didn't want to have
15754 to distribute all of the feature tests with every package, so I settled
15755 on having a different @command{configure} made from each
15756 @file{configure.in} by a preprocessor. That approach also offered more
15757 control and flexibility.
15759 I looked briefly into using the Metaconfig package, by Larry Wall,
15760 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
15761 reasons. The @command{Configure} scripts it produces are interactive,
15762 which I find quite inconvenient; I didn't like the ways it checked for
15763 some features (such as library functions); I didn't know that it was
15764 still being maintained, and the @command{Configure} scripts I had
15765 seen didn't work on many modern systems (such as System V R4 and NeXT);
15766 it wasn't very flexible in what it could do in response to a feature's
15767 presence or absence; I found it confusing to learn; and it was too big
15768 and complex for my needs (I didn't realize then how much Autoconf would
15769 eventually have to grow).
15771 I considered using Perl to generate my style of @command{configure}
15772 scripts, but decided that M4 was better suited to the job of simple
15773 textual substitutions: it gets in the way less, because output is
15774 implicit. Plus, everyone already has it. (Initially I didn't rely on
15775 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
15776 University of Maryland had recently been putting M4 front ends on
15777 several programs, including @code{tvtwm}, and I was interested in trying
15778 out a new language.
15783 Since my @command{configure} scripts determine the system's capabilities
15784 automatically, with no interactive user intervention, I decided to call
15785 the program that generates them Autoconfig. But with a version number
15786 tacked on, that name would be too long for old @sc{unix} file systems,
15787 so I shortened it to Autoconf.
15789 In the fall of 1991 I called together a group of fellow questers after
15790 the Holy Grail of portability (er, that is, alpha testers) to give me
15791 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
15792 and continued to add features and improve the techniques used in the
15793 checks. Prominent among the testers were Fran@,cois Pinard, who came up
15794 with the idea of making an Autoconf shell script to run M4
15795 and check for unresolved macro calls; Richard Pixley, who suggested
15796 running the compiler instead of searching the file system to find
15797 include files and symbols, for more accurate results; Karl Berry, who
15798 got Autoconf to configure @TeX{} and added the macro index to the
15799 documentation; and Ian Lance Taylor, who added support for creating a C
15800 header file as an alternative to putting @option{-D} options in a
15801 @file{Makefile}, so he could use Autoconf for his @acronym{UUCP} package.
15802 The alpha testers cheerfully adjusted their files again and again as the
15803 names and calling conventions of the Autoconf macros changed from
15804 release to release. They all contributed many specific checks, great
15805 ideas, and bug fixes.
15810 In July 1992, after months of alpha testing, I released Autoconf 1.0,
15811 and converted many @acronym{GNU} packages to use it. I was surprised by how
15812 positive the reaction to it was. More people started using it than I
15813 could keep track of, including people working on software that wasn't
15814 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
15815 Autoconf continued to improve rapidly, as many people using the
15816 @command{configure} scripts reported problems they encountered.
15818 Autoconf turned out to be a good torture test for M4 implementations.
15819 @sc{unix} M4 started to dump core because of the length of the
15820 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
15821 M4 as well. Eventually, we realized that we needed to use some
15822 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
15823 particular, has an impoverished set of builtin macros; the System V
15824 version is better, but still doesn't provide everything we need.
15826 More development occurred as people put Autoconf under more stresses
15827 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
15828 david zuhn contributed C++ support. Fran@,cois Pinard made it diagnose
15829 invalid arguments. Jim Blandy bravely coerced it into configuring
15830 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
15831 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
15832 @command{autoheader} script to automate the creation of C header file
15833 templates, and added a @option{--verbose} option to @command{configure}.
15834 Noah Friedman added the @option{--autoconf-dir} option and
15835 @code{AC_MACRODIR} environment variable. (He also coined the term
15836 @dfn{autoconfiscate} to mean ``adapt a software package to use
15837 Autoconf''.) Roland and Noah improved the quoting protection in
15838 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
15839 dealing with portability problems from February through June, 1993.
15842 @section Deuteronomy
15844 A long wish list for major features had accumulated, and the effect of
15845 several years of patching by various people had left some residual
15846 cruft. In April 1994, while working for Cygnus Support, I began a major
15847 revision of Autoconf. I added most of the features of the Cygnus
15848 @command{configure} that Autoconf had lacked, largely by adapting the
15849 relevant parts of Cygnus @command{configure} with the help of david zuhn
15850 and Ken Raeburn. These features include support for using
15851 @file{config.sub}, @file{config.guess}, @option{--host}, and
15852 @option{--target}; making links to files; and running @command{configure}
15853 scripts in subdirectories. Adding these features enabled Ken to convert
15854 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
15857 I added more features in response to other peoples' requests. Many
15858 people had asked for @command{configure} scripts to share the results of
15859 the checks between runs, because (particularly when configuring a large
15860 source tree, like Cygnus does) they were frustratingly slow. Mike
15861 Haertel suggested adding site-specific initialization scripts. People
15862 distributing software that had to unpack on MS-DOS asked for a way to
15863 override the @file{.in} extension on the file names, which produced file
15864 names like @file{config.h.in} containing two dots. Jim Avera did an
15865 extensive examination of the problems with quoting in @code{AC_DEFINE}
15866 and @code{AC_SUBST}; his insights led to significant improvements.
15867 Richard Stallman asked that compiler output be sent to @file{config.log}
15868 instead of @file{/dev/null}, to help people debug the Emacs
15869 @command{configure} script.
15871 I made some other changes because of my dissatisfaction with the quality
15872 of the program. I made the messages showing results of the checks less
15873 ambiguous, always printing a result. I regularized the names of the
15874 macros and cleaned up coding style inconsistencies. I added some
15875 auxiliary utilities that I had developed to help convert source code
15876 packages to use Autoconf. With the help of Fran@,cois Pinard, I made
15877 the macros not interrupt each others' messages. (That feature revealed
15878 some performance bottlenecks in @acronym{GNU} M4, which he hastily
15879 corrected!) I reorganized the documentation around problems people want
15880 to solve. And I began a test suite, because experience had shown that
15881 Autoconf has a pronounced tendency to regress when we change it.
15883 Again, several alpha testers gave invaluable feedback, especially
15884 Fran@,cois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
15887 Finally, version 2.0 was ready. And there was much rejoicing. (And I
15888 have free time again. I think. Yeah, right.)
15891 @c ========================================================== Appendices
15893 @node Copying This Manual
15894 @appendix Copying This Manual
15898 * GNU Free Documentation License:: License for copying this manual
15907 * Environment Variable Index:: Index of environment variables used
15908 * Output Variable Index:: Index of variables set in output files
15909 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
15910 * Autoconf Macro Index:: Index of Autoconf macros
15911 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
15912 * Autotest Macro Index:: Index of Autotest macros
15913 * Program & Function Index:: Index of those with portability problems
15914 * Concept Index:: General index
15917 @node Environment Variable Index
15918 @appendixsec Environment Variable Index
15920 This is an alphabetical list of the environment variables that Autoconf
15925 @node Output Variable Index
15926 @appendixsec Output Variable Index
15928 This is an alphabetical list of the variables that Autoconf can
15929 substitute into files that it creates, typically one or more
15930 @file{Makefile}s. @xref{Setting Output Variables}, for more information
15931 on how this is done.
15935 @node Preprocessor Symbol Index
15936 @appendixsec Preprocessor Symbol Index
15938 This is an alphabetical list of the C preprocessor symbols that the
15939 Autoconf macros define. To work with Autoconf, C source code needs to
15940 use these names in @code{#if} directives.
15944 @node Autoconf Macro Index
15945 @appendixsec Autoconf Macro Index
15947 This is an alphabetical list of the Autoconf macros.
15948 @ifset shortindexflag
15949 To make the list easier to use, the macros are listed without their
15950 preceding @samp{AC_}.
15955 @node M4 Macro Index
15956 @appendixsec M4 Macro Index
15958 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
15959 @ifset shortindexflag
15960 To make the list easier to use, the macros are listed without their
15961 preceding @samp{m4_} or @samp{AS_}.
15966 @node Autotest Macro Index
15967 @appendixsec Autotest Macro Index
15969 This is an alphabetical list of the Autotest macros.
15970 @ifset shortindexflag
15971 To make the list easier to use, the macros are listed without their
15972 preceding @samp{AT_}.
15977 @node Program & Function Index
15978 @appendixsec Program and Function Index
15980 This is an alphabetical list of the programs and functions which
15981 portability is discussed in this document.
15985 @node Concept Index
15986 @appendixsec Concept Index
15988 This is an alphabetical list of the files, tools, and concepts
15989 introduced in this document.
15995 @c Local Variables:
15997 @c ispell-local-dictionary: "american"