diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/Makefile.in | 341 | ||||
| -rw-r--r-- | doc/autoconf.info | 10852 | ||||
| -rw-r--r-- | doc/autoconf.texi | 11346 | ||||
| -rw-r--r-- | doc/install.texi | 258 | ||||
| -rw-r--r-- | doc/make-stds.texi | 944 | ||||
| -rwxr-xr-x | doc/rename.sh | 21 | ||||
| -rw-r--r-- | doc/stamp-vti | 4 | ||||
| -rw-r--r-- | doc/standards.info | 4454 | ||||
| -rw-r--r-- | doc/standards.texi | 3656 | ||||
| -rw-r--r-- | doc/version.texi | 4 |
10 files changed, 31880 insertions, 0 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..db3130e --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,341 @@ +# Copyright 2010-2012,2023 Thomas E. Dickey +# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 +# Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +SHELL = @SHELL@ + +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +bindir = @bindir@ +sbindir = @sbindir@ +libexecdir = @libexecdir@ +datarootdir = @datarootdir@ +datadir = @datadir@ +sysconfdir = @sysconfdir@ +sharedstatedir = @sharedstatedir@ +localstatedir = @localstatedir@ +libdir = @libdir@ +infodir = @infodir@ +mandir = @mandir@ +includedir = @includedir@ +oldincludedir = /usr/include +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +top_builddir = .. + +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ + +INSTALL_INFO = @INSTALL_INFO@ + +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_HEADER = $(INSTALL_DATA) +transform = @program_transform_name@ +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +AWK = @AWK@ +EXPR = @EXPR@ +HELP2MAN = @HELP2MAN@ +M4 = @M4@ +PACKAGE = @PACKAGE@ +PACKAGE_NAME = @PACKAGE_NAME@ +PERL = @PERL@ +PERLSCRIPTS = @PERLSCRIPTS@ +VERSION = @VERSION@ + +MAKEINFO = @MAKEINFO@ --no-split +TEXI2HTML = texi2html + +info_TEXINFOS = autoconf.texi standards.texi +autoconf_TEXINFOS = install.texi +standards_TEXINFOS = make-stds.texi + +# Files from texi2dvi that should be removed, but which Automake does +# not know. +CLEANFILES = autoconf.cvs autoconf.ev autoconf.evs autoconf.ma autoconf.mas \ + autoconf.ov autoconf.ovs autoconf.ms autoconf.mss autoconf.tmp + +subdir = doc +CONFIG_CLEAN_FILES = +DIST_SOURCES = +TEXINFO_TEX = $(top_srcdir)/config/texinfo.tex +INFO_DEPS = autoconf.info standards.info +DVIS = autoconf.dvi standards.dvi +TEXINFOS = autoconf.texi standards.texi +DIST_COMMON = $(autoconf_TEXINFOS) $(standards_TEXINFOS) Makefile.am \ + Makefile.in stamp-vti version.texi +all: all-am + +.SUFFIXES: +.SUFFIXES: .dvi .info .ps .texi + +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + cd $(top_builddir) && \ + CONFIG_HEADERS= CONFIG_LINKS= \ + CONFIG_FILES=$(subdir)/$@ $(SHELL) ./config.status + +$(srcdir)/version.texi: $(srcdir)/stamp-vti + @: +$(srcdir)/stamp-vti: autoconf.texi $(top_srcdir)/configure.ac + @(set `$(SHELL) $(top_srcdir)/config/mdate-sh $(srcdir)/autoconf.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp + @cmp -s vti.tmp $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi"; \ + cp vti.tmp $(srcdir)/version.texi) + -@rm -f vti.tmp + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp + +maintainer-clean-vti: + -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi + +autoconf.info: autoconf.texi $(srcdir)/version.texi $(autoconf_TEXINFOS) +autoconf.dvi: autoconf.texi $(srcdir)/version.texi $(autoconf_TEXINFOS) + +standards.info: standards.texi $(standards_TEXINFOS) +standards.dvi: standards.texi $(standards_TEXINFOS) + +.texi.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \ + `echo $< | sed 's,.*/,,'` + +.texi.dvi: + TEXINPUTS=$(top_srcdir)/config:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texi: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \ + `echo $< | sed 's,.*/,,'` +TEXI2DVI = texi2dvi +DVIPS = dvips +.dvi.ps: + $(DVIPS) $< -o $@ + +uninstall-info-am: + $(PRE_UNINSTALL) + @if test $(INSTALL_INFO) != no; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + name=`basename "$$file" .info | sed -e '$(transform)'`; \ + FILE=$$name.info; \ + echo " $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$FILE"; \ + $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$FILE; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + name=`basename "$$file" .info | sed -e '$(transform)'`; \ + FILE=$$name.info; \ + (if cd $(DESTDIR)$(infodir); then \ + echo " rm -f $$FILE $$FILE-[0-9] $$FILE-[0-9][0-9])"; \ + rm -f $$file $$file-[0-9] $$file-[0-9][0-9]; \ + else :; fi); \ + done + +dist-info: $(INFO_DEPS) + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + d=$(srcdir); \ + for file in `CDPATH=: && cd $$d && eval echo $$base*`; do \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file; \ + done; \ + done + +mostlyclean-aminfo: + -rm -f autoconf.aux autoconf.cp autoconf.cps autoconf.cv autoconf.dvi \ + autoconf.ev autoconf.fn autoconf.fns autoconf.ky autoconf.log \ + autoconf.ma autoconf.ms autoconf.ov autoconf.pg autoconf.ps \ + autoconf.toc autoconf.tp autoconf.vr autoconf.vrs \ + standards.aux standards.cp standards.cps standards.dvi \ + standards.fn standards.ky standards.log standards.pg \ + standards.ps standards.toc standards.tp standards.vr + +maintainer-clean-aminfo: + cd $(srcdir) && \ + for i in $(INFO_DEPS); do \ + rm -f $$i; \ + if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \ + rm -f $$i-[0-9]*; \ + fi; \ + done +tags: TAGS +TAGS: + + +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) + +top_distdir = .. +distdir = $(top_distdir)/$(PACKAGE)-$(VERSION) + +distdir: $(DISTFILES) + @for file in $(DISTFILES); do \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test "$$dir" != "$$file" && test "$$dir" != "."; then \ + mkdir -p "$(distdir)/$$dir"; \ + fi; \ + if test -d $$d/$$file; then \ + cp -pR $$d/$$file $(distdir) \ + || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="${top_distdir}" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) + +installdirs: + mkdir -p $(DESTDIR)$(infodir) + +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -rm -f Makefile $(CONFIG_CLEAN_FILES) stamp-h stamp-h[0-9]* + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic mostlyclean-am + +distclean: distclean-am + +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + +install-exec-am: + +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + mkdir -p $(DESTDIR)$(infodir) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + name=`basename "$$file" .info | sed -e '$(transform)'`; \ + FILE=$$name.info; \ + d=$(srcdir); \ + for ifile in `CDPATH=: && cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \ + if test -f $$d/$$ifile; then \ + $(SHELL) $$d/rename.sh $$d/$$ifile $$FILE; \ + echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$FILE"; \ + $(INSTALL_DATA) $$FILE $(DESTDIR)$(infodir)/$$FILE; \ + test "$$file" != "$$FILE" && rm -f "$$FILE"; \ + break; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if test $(INSTALL_INFO) != no; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + name=`basename "$$file" .info | sed -e '$(transform)'`; \ + FILE=$$name.info; \ + echo " $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$FILE";\ + $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$FILE || :;\ + done; \ + else : ; fi +install-man: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic mostlyclean-vti + +uninstall-am: uninstall-info-am + +.PHONY: all all-am check check-am clean clean-generic dist-info \ + distclean distclean-generic distdir dvi dvi-am info info-am \ + install install-am install-data install-data-am install-exec \ + install-exec-am install-info install-info-am install-man \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti mostlyclean \ + mostlyclean-aminfo mostlyclean-generic mostlyclean-vti \ + uninstall uninstall-am uninstall-info-am + + +# The documentation + +html: autoconf_1.html standards_1.html + +autoconf_1.html: autoconf.texi install.texi + $(TEXI2HTML) -split_chapter $(srcdir)/autoconf.texi + +standards_1.html: standards.texi make-stds.texi + $(TEXI2HTML) -split_chapter $(srcdir)/standards.texi +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/autoconf.info b/doc/autoconf.info new file mode 100644 index 0000000..d64dd17 --- /dev/null +++ b/doc/autoconf.info @@ -0,0 +1,10852 @@ +This is autoconf.info, produced by makeinfo version 6.7 from +autoconf.texi. + +INFO-DIR-SECTION GNU admin +START-INFO-DIR-ENTRY +* Autoconf: (autoconf). Create source code configuration scripts +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* autoscan: (autoconf)autoscan Invocation. + Semi-automatic 'configure.ac' writing +* ifnames: (autoconf)ifnames Invocation. + Listing the conditionals in source code +* autoconf: (autoconf)autoconf Invocation. + How to create configuration scripts +* autoreconf: (autoconf)autoreconf Invocation. + Remaking multiple 'configure' scripts +* configure: (autoconf)configure Invocation. + Configuring a package +* config.status: (autoconf)config.status Invocation. + Recreating a configuration +END-INFO-DIR-ENTRY + +Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie. + + This file documents the GNU Autoconf package for creating scripts to +configure source code packages using templates and an 'm4' macro +package. + + Copyright 2003-2022,2023 Thomas E. Dickey +Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001 Free +Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + +File: autoconf.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +This file documents the GNU Autoconf package for creating scripts to +configure source code packages using templates and the GNU M4 macro +package. This is edition 2.52.20231210, for Autoconf version +2.52.20231210. + +* Menu: + +* Introduction:: Autoconf's purpose, strengths, and weaknesses +* The GNU build system:: A set of tools for portable software packages +* Making configure Scripts:: How to organize and produce Autoconf scripts +* Setup:: Initialization and output +* Existing Tests:: Macros that check for particular features +* Writing Tests:: How to write new feature checks +* Results:: What to do with results from feature checks +* Programming in M4:: Layers on top of which Autoconf is written +* Writing Autoconf Macros:: Adding new macros to Autoconf +* Portable Shell:: Shell script portability pitfalls +* Manual Configuration:: Selecting features that can't be guessed +* Site Configuration:: Local defaults for 'configure' +* Running configure scripts:: How to use the Autoconf output +* config.status Invocation:: Recreating a configuration +* Obsolete Constructs:: Kept for backward compatibility +* Questions:: Questions about Autoconf, with answers +* History:: History of Autoconf +* Environment Variable Index:: Index of environment variables used +* Output Variable Index:: Index of variables set in output files +* Preprocessor Symbol Index:: Index of C preprocessor symbols defined +* Autoconf Macro Index:: Index of Autoconf macros +* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros +* Concept Index:: General index + + +The GNU build system + +* Automake:: Escaping Makefile hell +* Libtool:: Building libraries portably +* Pointers:: More info on the GNU build system + +Making 'configure' Scripts + +* Writing configure.ac:: What to put in an Autoconf input file +* autoscan Invocation:: Semi-automatic 'configure.ac' writing +* ifnames Invocation:: Listing the conditionals in source code +* autoconf Invocation:: How to create configuration scripts +* autoreconf Invocation:: Remaking multiple 'configure' scripts + +Writing 'configure.ac' + +* Shell Script Compiler:: Autoconf as solution of a problem +* Autoconf Language:: Programming in Autoconf +* configure.ac Layout:: Standard organization of configure.ac + +Initialization and Output Files + +* Notices:: Copyright, version numbers in 'configure' +* Input:: Where Autoconf should find files +* Output:: Outputting results from the configuration +* Configuration Actions:: Preparing the output based on results +* Configuration Files:: Creating output files +* Makefile Substitutions:: Using output variables in 'Makefile's +* Configuration Headers:: Creating a configuration header file +* Configuration Commands:: Running arbitrary instantiation commands +* Configuration Links:: Links depending from the configuration +* Subdirectories:: Configuring independent packages together +* Default Prefix:: Changing the default installation prefix + +Substitutions in Makefiles + +* Preset Output Variables:: Output variables that are always set +* Installation Directory Variables:: Other preset output variables +* Build Directories:: Supporting multiple concurrent compiles +* Automatic Remaking:: Makefile rules for configuring + +Configuration Header Files + +* Header Templates:: Input for the configuration headers +* autoheader Invocation:: How to create configuration templates +* Autoheader Macros:: How to specify CPP templates + +Existing Tests + +* Common Behavior:: Macros' standard schemes +* Alternative Programs:: Selecting between alternative programs +* Files:: Checking for the existence of files +* Libraries:: Library archives that might be missing +* Library Functions:: C library functions that might be missing +* Header Files:: Header files that might be missing +* Declarations:: Declarations that may be missing +* Structures:: Structures or members that might be missing +* Types:: Types that might be missing +* Compilers and Preprocessors:: Checking for compiling programs +* System Services:: Operating system services +* UNIX Variants:: Special kludges for specific UNIX variants + +Common Behavior + +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros + +Alternative Programs + +* Particular Programs:: Special handling to find certain programs +* Generic Programs:: How to find other programs + +Library Functions + +* Function Portability:: Pitfalls with usual functions +* Particular Functions:: Special handling to find certain functions +* Generic Functions:: How to find other functions + +Header Files + +* Particular Headers:: Special handling to find certain headers +* Generic Headers:: How to find other headers + +Declarations + +* Particular Declarations:: Macros to check for certain declarations +* Generic Declarations:: How to find other declarations + +Structures + +* Particular Structures:: Macros to check for certain structure members +* Generic Structures:: How to find other structure members + +Types + +* Particular Types:: Special handling to find certain types +* Generic Types:: How to find other types + +Compilers and Preprocessors + +* Generic Compiler Characteristics:: Language independent tests +* C Compiler:: Checking its characteristics +* C++ Compiler:: Likewise +* Fortran 77 Compiler:: Likewise + +Writing Tests + +* Examining Declarations:: Detecting header files and declarations +* Examining Syntax:: Detecting language syntax features +* Examining Libraries:: Detecting functions and global variables +* Run Time:: Testing for run-time features +* Systemology:: A zoology of operating systems +* Multiple Cases:: Tests for several possible values +* Language Choice:: Selecting which language to use for testing + +Checking Run Time Behavior + +* Test Programs:: Running test programs +* Guidelines:: General rules for writing test programs +* Test Functions:: Avoiding pitfalls in test programs + +Results of Tests + +* Defining Symbols:: Defining C preprocessor symbols +* Setting Output Variables:: Replacing variables in output files +* Caching Results:: Speeding up subsequent 'configure' runs +* Printing Messages:: Notifying 'configure' users + +Caching Results + +* Cache Variable Names:: Shell variables used in caches +* Cache Files:: Files 'configure' uses for caching +* Cache Checkpointing:: Loading and saving the cache file + +Programming in M4 + +* M4 Quotation:: Protecting macros from unwanted expansion +* Programming in M4sugar:: Convenient pure M4 macros + +M4 Quotation + +* Active Characters:: Characters that change the behavior of m4 +* One Macro Call:: Quotation and one macro call +* Quotation and Nested Macros:: Macros calling macros +* Quadrigraphs:: Another way to escape special characters +* Quotation Rule Of Thumb:: One parenthesis, one quote + +Programming in M4sugar + +* Redefined M4 Macros:: M4 builtins changed in M4sugar +* Forbidden Patterns:: Catching unexpanded macros + +Writing Autoconf Macros + +* Macro Definitions:: Basic format of an Autoconf macro +* Macro Names:: What to call your new macros +* Reporting Messages:: Notifying 'autoconf' users +* Dependencies Between Macros:: What to do when macros depend on other macros +* Obsoleting Macros:: Warning about old ways of doing things +* Coding Style:: Writing Autoconf macros à la Autoconf + +Dependencies Between Macros + +* Prerequisite Macros:: Ensuring required information +* Suggested Ordering:: Warning about possible ordering problems + +Portable Shell Programming + +* Shellology:: A zoology of shells +* Here-Documents:: Quirks and tricks +* File Descriptors:: FDs and redirections +* File System Conventions:: File- and pathnames +* Shell Substitutions:: Variable and command expansions +* Assignments:: Varying side effects of assignments +* Special Shell Variables:: Variables you should not change +* Limitations of Builtins:: Portable use of not so portable /bin/sh +* Limitations of Usual Tools:: Portable use of portable tools +* Limitations of Make:: Portable Makefiles + +Manual Configuration + +* Specifying Names:: Specifying the system type +* Canonicalizing:: Getting the canonical system type +* Using System Type:: What to do with the system type + +Site Configuration + +* External Software:: Working with other optional software +* Package Options:: Selecting optional features +* Pretty Help Strings:: Formatting help string +* Site Details:: Configuring site details +* Transforming Names:: Changing program names when installing +* Site Defaults:: Giving 'configure' local defaults + +Transforming Program Names When Installing + +* Transformation Options:: 'configure' options to transform names +* Transformation Examples:: Sample uses of transforming names +* Transformation Rules:: 'Makefile' uses of transforming names + +Running 'configure' Scripts + +* Basic Installation:: Instructions for typical cases +* Compilers and Options:: Selecting compilers and optimization +* Multiple Architectures:: Compiling for multiple architectures at once +* Installation Names:: Installing in different directories +* Optional Features:: Selecting optional features +* System Type:: Specifying the system type +* Sharing Defaults:: Setting site-wide defaults for 'configure' +* Environment Variables:: Defining environment variables. +* configure Invocation:: Changing how 'configure' runs + +Obsolete Constructs + +* Obsolete config.status Use:: Different calling convention +* acconfig.h:: Additional entries in 'config.h.in' +* autoupdate Invocation:: Automatic update of 'configure.ac' +* Obsolete Macros:: Backward compatibility macros +* Autoconf 1:: Tips for upgrading your files +* Autoconf 2.13:: Some fresher tips + +Upgrading From Version 1 + +* Changed File Names:: Files you might rename +* Changed Makefiles:: New things to put in 'Makefile.in' +* Changed Macros:: Macro calls you might replace +* Changed Results:: Changes in how to check test results +* Changed Macro Writing:: Better ways to write your own macros + +Upgrading From Version 2.13 + +* Changed Quotation:: Broken code which used to work +* New Macros:: Interaction with foreign macros + +Questions About Autoconf + +* Distributing:: Distributing 'configure' scripts +* Why GNU m4:: Why not use the standard M4? +* Bootstrapping:: Autoconf and GNU M4 require each other? +* Why Not Imake:: Why GNU uses 'configure' instead of Imake + +History of Autoconf + +* Genesis:: Prehistory and naming of 'configure' +* Exodus:: The plagues of M4 and Perl +* Leviticus:: The priestly code of portability arrives +* Numbers:: Growth and contributors +* Deuteronomy:: Approaching the promises of easy configuration + + + +File: autoconf.info, Node: Introduction, Next: The GNU build system, Prev: Top, Up: Top + +1 Introduction +************** + + A physicist, an engineer, and a computer scientist were discussing the + nature of God. "Surely a Physicist," said the physicist, "because + early in the Creation, God made Light; and you know, Maxwell's + equations, the dual nature of electromagnetic waves, the relativistic + consequences..." "An Engineer!," said the engineer, "because +before making Light, God split the Chaos into Land and Water; it takes a + hell of an engineer to handle that big amount of mud, and orderly + separation of solids from liquids..." The computer scientist + shouted: "And the Chaos, where do you think it was coming from, hmm?" + + --Anonymous + + Autoconf is a tool for producing shell scripts that automatically +configure software source code packages to adapt to many kinds of +UNIX-like systems. The configuration scripts produced by Autoconf are +independent of Autoconf when they are run, so their users do not need to +have Autoconf. + + The configuration scripts produced by Autoconf require no manual user +intervention when run; they do not normally even need an argument +specifying the system type. Instead, they individually test for the +presence of each feature that the software package they are for might +need. (Before each check, they print a one-line message stating what +they are checking for, so the user doesn't get too bored while waiting +for the script to finish.) As a result, they deal well with systems +that are hybrids or customized from the more common UNIX variants. +There is no need to maintain files that list the features supported by +each release of each variant of UNIX. + + For each software package that Autoconf is used with, it creates a +configuration script from a template file that lists the system features +that the package needs or can use. After the shell code to recognize +and respond to a system feature has been written, Autoconf allows it to +be shared by many software packages that can use (or need) that feature. +If it later turns out that the shell code needs adjustment for some +reason, it needs to be changed in only one place; all of the +configuration scripts can be regenerated automatically to take advantage +of the updated code. + + The Metaconfig package is similar in purpose to Autoconf, but the +scripts it produces require manual user intervention, which is quite +inconvenient when configuring large source trees. Unlike Metaconfig +scripts, Autoconf scripts can support cross-compiling, if some care is +taken in writing them. + + Autoconf does not solve all problems related to making portable +software packages--for a more complete solution, it should be used in +concert with other GNU build tools like Automake and Libtool. These +other tools take on jobs like the creation of a portable, recursive +'Makefile' with all of the standard targets, linking of shared +libraries, and so on. *Note The GNU build system::, for more +information. + + Autoconf imposes some restrictions on the names of macros used with +'#if' in C programs (*note Preprocessor Symbol Index::). + + Autoconf requires GNU M4 in order to generate the scripts. It uses +features that some UNIX versions of M4, including GNU M4 1.3, do not +have. You must use version 1.4 or later of GNU M4. + + *Note Autoconf 1::, for information about upgrading from version 1. +*Note History::, for the story of Autoconf's development. *Note +Questions::, for answers to some common questions about Autoconf. + + See the Autoconf web page(1) for up-to-date information, details on +the mailing lists, pointers to a list of known bugs, etc. + + Mail suggestions to the Autoconf mailing list <autoconf@gnu.org>. + + Bug reports should be preferably submitted to the Autoconf Gnats +database(2), or sent to the Autoconf Bugs mailing list +<bug-autoconf@gnu.org>. If possible, first check that your bug is not +already solved in current development versions, and that it has not been +reported yet. Be sure to include all the needed information and a short +'configure.ac' that demonstrates the problem. + + Autoconf's development tree is accessible via CVS; see the Autoconf +web page for details. There is also a CVSweb interface to the Autoconf +development tree(3). Patches relative to the current CVS version can be +sent for review to the Autoconf Patches mailing list +<autoconf-patches@gnu.org>. + + Because of its mission, Autoconf includes only a set of often-used +macros that have already demonstrated their usefulness. Nevertheless, +if you wish to share your macros, or find existing ones, see the +Autoconf Macro Archive(4), which is kindly run by Peter Simons +<simons@computer.org>. + + ---------- Footnotes ---------- + + (1) Autoconf web page, +<http://www.gnu.org/software/autoconf/autoconf.html>. + + (2) Autoconf Gnats database, +<http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf>. + + (3) CVSweb interface to the Autoconf development tree, +<http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/>. + + (4) Autoconf Macro Archive, +<http://www.gnu.org/software/ac-archive/>. + + +File: autoconf.info, Node: The GNU build system, Next: Making configure Scripts, Prev: Introduction, Up: Top + +2 The GNU build system +********************** + +Autoconf solves an important problem--reliable discovery of +system-specific build and runtime information--but this is only one +piece of the puzzle for the development of portable software. To this +end, the GNU project has developed a suite of integrated utilities to +finish the job Autoconf started: the GNU build system, whose most +important components are Autoconf, Automake, and Libtool. In this +chapter, we introduce you to those tools, point you to sources of more +information, and try to convince you to use the entire GNU build system +for your software. + +* Menu: + +* Automake:: Escaping Makefile hell +* Libtool:: Building libraries portably +* Pointers:: More info on the GNU build system + + +File: autoconf.info, Node: Automake, Next: Libtool, Prev: The GNU build system, Up: The GNU build system + +2.1 Automake +============ + +The ubiquity of 'make' means that a 'Makefile' is almost the only viable +way to distribute automatic build rules for software, but one quickly +runs into 'make''s numerous limitations. Its lack of support for +automatic dependency tracking, recursive builds in subdirectories, +reliable timestamps (e.g. for network filesystems), and so on, mean +that developers must painfully (and often incorrectly) reinvent the +wheel for each project. Portability is non-trivial, thanks to the +quirks of 'make' on many systems. On top of all this is the manual +labor required to implement the many standard targets that users have +come to expect ('make install', 'make distclean', 'make uninstall', +etc.). Since you are, of course, using Autoconf, you also have to +insert repetitive code in your 'Makefile.in' to recognize '@CC@', +'@CFLAGS@', and other substitutions provided by 'configure'. Into this +mess steps "Automake". + + Automake allows you to specify your build needs in a 'Makefile.am' +file with a vastly simpler and more powerful syntax than that of a plain +'Makefile', and then generates a portable 'Makefile.in' for use with +Autoconf. For example, the 'Makefile.am' to build and install a simple +"Hello world" program might look like: + + bin_PROGRAMS = hello + hello_SOURCES = hello.c + +The resulting 'Makefile.in' (~400 lines) automatically supports all the +standard targets, the substitutions provided by Autoconf, automatic +dependency tracking, 'VPATH' building, and so on. 'make' will build the +'hello' program, and 'make install' will install it in '/usr/local/bin' +(or whatever prefix was given to 'configure', if not '/usr/local'). + + Automake may require that additional tools be present on the +_developer's_ machine. For example, the 'Makefile.in' that the +developer works with may not be portable (e.g. it might use special +features of your compiler to automatically generate dependency +information). Running 'make dist', however, produces a +'hello-1.0.tar.gz' package (or whatever the program/version is) with a +'Makefile.in' that will work on any system. + + The benefits of Automake increase for larger packages (especially +ones with subdirectories), but even for small programs the added +convenience and portability can be substantial. And that's not all... + + +File: autoconf.info, Node: Libtool, Next: Pointers, Prev: Automake, Up: The GNU build system + +2.2 Libtool +=========== + +Very often, one wants to build not only programs, but libraries, so that +other programs can benefit from the fruits of your labor. Ideally, one +would like to produce _shared_ (dynamically-linked) libraries, which can +be used by multiple programs without duplication on disk or in memory +and can be updated independently of the linked programs. Producing +shared libraries portably, however, is the stuff of nightmares--each +system has its own incompatible tools, compiler flags, and magic +incantations. Fortunately, GNU provides a solution: "Libtool". + + Libtool handles all the requirements of building shared libraries for +you, and at this time seems to be the _only_ way to do so with any +portability. It also handles many other headaches, such as: the +interaction of 'Makefile' rules with the variable suffixes of shared +libraries, linking reliably to shared libraries before they are +installed by the superuser, and supplying a consistent versioning system +(so that different versions of a library can be installed or upgraded +without breaking binary compatibility). Although Libtool, like +Autoconf, can be used on its own, it is most simply utilized in +conjunction with Automake--there, Libtool is used automatically whenever +shared libraries are needed, and you need not know its syntax. + + +File: autoconf.info, Node: Pointers, Prev: Libtool, Up: The GNU build system + +2.3 Pointers +============ + +Developers who are used to the simplicity of 'make' for small projects +on a single system might be daunted at the prospect of learning to use +Automake and Autoconf. As your software is distributed to more and more +users, however, you will otherwise quickly find yourself putting lots of +effort into reinventing the services that the GNU build tools provide, +and making the same mistakes that they once made and overcame. +(Besides, since you're already learning Autoconf, Automake will be a +piece of cake.) + + There are a number of places that you can go to for more information +on the GNU build tools. + + - Web + + The home pages for Autoconf(1), and Libtool(2). + + - Books + + The book 'GNU Autoconf, Automake and Libtool'(3) describes the + complete GNU build environment. You can also find the entire book + on-line at "The Goat Book" home page(4). + + - Tutorials and Examples + + The Autoconf Developer Page(5) maintains links to a number of + Autoconf/Automake tutorials online, and also links to the Autoconf + Macro Archive(6). + + ---------- Footnotes ---------- + + (1) Autoconf, <http://www.gnu.org/software/autoconf/>. + + (2) Libtool, <http://www.gnu.org/software/libtool/>. + + (3) 'GNU Autoconf, Automake and Libtool', by G. V. Vaughan, B. +Elliston, T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN +1578701902. + + (4) "The Goat Book" home page, <http://sources.redhat.com/autobook/>. + + (5) Autoconf Developer Page, <http://sources.redhat.com/autoconf/>. + + (6) Autoconf Macro Archive, +<http://www.gnu.org/software/ac-archive/>. + + +File: autoconf.info, Node: Making configure Scripts, Next: Setup, Prev: The GNU build system, Up: Top + +3 Making 'configure' Scripts +**************************** + +The configuration scripts that Autoconf produces are by convention +called 'configure'. When run, 'configure' creates several files, +replacing configuration parameters in them with appropriate values. The +files that 'configure' creates are: + + - one or more 'Makefile' files, one in each subdirectory of the + package (*note Makefile Substitutions::); + + - optionally, a C header file, the name of which is configurable, + containing '#define' directives (*note Configuration Headers::); + + - a shell script called 'config.status' that, when run, will recreate + the files listed above (*note config.status Invocation::); + + - an optional shell script normally called 'config.cache' (created + when using 'configure --config-cache') that saves the results of + running many of the tests (*note Cache Files::); + + - a file called 'config.log' containing any messages produced by + compilers, to help debugging if 'configure' makes a mistake. + + To create a 'configure' script with Autoconf, you need to write an +Autoconf input file 'configure.ac' (or 'configure.in') and run +'autoconf' on it. If you write your own feature tests to supplement +those that come with Autoconf, you might also write files called +'aclocal.m4' and 'acsite.m4'. If you use a C header file to contain +'#define' directives, you might also run 'autoheader', and you will +distribute the generated file 'config.h.in' with the package. + + Here is a diagram showing how the files that can be used in +configuration are produced. Programs that are executed are suffixed by +'*'. Optional files are enclosed in square brackets ('[]'). 'autoconf' +and 'autoheader' also read the installed Autoconf macro files (by +reading 'autoconf.m4'). + +Files used in preparing a software package for distribution: + your source files --> [autoscan*] --> [configure.scan] --> configure.ac + + configure.ac --. + | .------> autoconf* -----> configure + [aclocal.m4] --+---+ + | `-----> [autoheader*] --> [config.h.in] + [acsite.m4] ---' + + Makefile.in -------------------------------> Makefile.in + +Files used in configuring a software package: + .-------------> [config.cache] + configure* ------------+-------------> config.log + | + [config.h.in] -. v .-> [config.h] -. + +--> config.status* -+ +--> make* + Makefile.in ---' `-> Makefile ---' + +* Menu: + +* Writing configure.ac:: What to put in an Autoconf input file +* autoscan Invocation:: Semi-automatic 'configure.ac' writing +* ifnames Invocation:: Listing the conditionals in source code +* autoconf Invocation:: How to create configuration scripts +* autoreconf Invocation:: Remaking multiple 'configure' scripts + + +File: autoconf.info, Node: Writing configure.ac, Next: autoscan Invocation, Prev: Making configure Scripts, Up: Making configure Scripts + +3.1 Writing 'configure.ac' +========================== + +To produce a 'configure' script for a software package, create a file +called 'configure.ac' that contains invocations of the Autoconf macros +that test the system features your package needs or can use. Autoconf +macros already exist to check for many features; see *note Existing +Tests::, for their descriptions. For most other features, you can use +Autoconf template macros to produce custom checks; see *note Writing +Tests::, for information about them. For especially tricky or +specialized features, 'configure.ac' might need to contain some +hand-crafted shell commands; see *note Portable Shell::. The 'autoscan' +program can give you a good start in writing 'configure.ac' (*note +autoscan Invocation::, for more information). + + Previous versions of Autoconf promoted the name 'configure.in', which +is somewhat ambiguous (the tool needed to produce this file is not +described by its extension), and introduces a slight confusion with +'config.h.in' and so on (for which '.in' means "to be processed by +'configure'"). Using 'configure.ac' is now preferred. + +* Menu: + +* Shell Script Compiler:: Autoconf as solution of a problem +* Autoconf Language:: Programming in Autoconf +* configure.ac Layout:: Standard organization of configure.ac + + +File: autoconf.info, Node: Shell Script Compiler, Next: Autoconf Language, Prev: Writing configure.ac, Up: Writing configure.ac + +3.1.1 A Shell Script Compiler +----------------------------- + +Just as for any other computer language, in order to properly program +'configure.ac' in Autoconf you must understand _what_ problem the +language tries to address and _how_ it does so. + + The problem Autoconf addresses is that the world is a mess. After +all, you are using Autoconf in order to have your package compile easily +on all sorts of different systems, some of them being extremely hostile. +Autoconf itself bears the price for these differences: 'configure' must +run on all those systems, and thus 'configure' must limit itself to +their lowest common denominator of features. + + Naturally, you might then think of shell scripts; who needs +'autoconf'? A set of properly written shell functions is enough to make +it easy to write 'configure' scripts by hand. Sigh! Unfortunately, +shell functions do not belong to the least common denominator; +therefore, where you would like to define a function and use it ten +times, you would instead need to copy its body ten times. + + So, what is really needed is some kind of compiler, 'autoconf', that +takes an Autoconf program, 'configure.ac', and transforms it into a +portable shell script, 'configure'. + + How does 'autoconf' perform this task? + + There are two obvious possibilities: creating a brand new language or +extending an existing one. The former option is very attractive: all +sorts of optimizations could easily be implemented in the compiler and +many rigorous checks could be performed on the Autoconf program (e.g. +rejecting any non-portable construct). Alternatively, you can extend an +existing language, such as the 'sh' (Bourne shell) language. + + Autoconf does the latter: it is a layer on top of 'sh'. It was +therefore most convenient to implement 'autoconf' as a macro expander: a +program that repeatedly performs "macro expansions" on text input, +replacing macro calls with macro bodies and producing a pure 'sh' script +in the end. Instead of implementing a dedicated Autoconf macro +expander, it is natural to use an existing general-purpose macro +language, such as M4, and implement the extensions as a set of M4 +macros. + + +File: autoconf.info, Node: Autoconf Language, Next: configure.ac Layout, Prev: Shell Script Compiler, Up: Writing configure.ac + +3.1.2 The Autoconf Language +--------------------------- + +The Autoconf language is very different from many other computer +languages because it treats actual code the same as plain text. Whereas +in C, for instance, data and instructions have very different syntactic +status, in Autoconf their status is rigorously the same. Therefore, we +need a means to distinguish literal strings from text to be expanded: +quotation. + + When calling macros that take arguments, there must not be any blank +space between the macro name and the open parenthesis. Arguments should +be enclosed within the M4 quote characters '[' and ']', and be separated +by commas. Any leading spaces in arguments are ignored, unless they are +quoted. You may safely leave out the quotes when the argument is simple +text, but _always_ quote complex arguments such as other macro calls. +This rule applies recursively for every macro call, including macros +called from other macros. + + For instance: + + AC_CHECK_HEADER([stdio.h], + [AC_DEFINE([HAVE_STDIO_H])], + [AC_MSG_ERROR([Sorry, can't do anything for you])]) + +is quoted properly. You may safely simplify its quotation to: + + AC_CHECK_HEADER(stdio.h, + [AC_DEFINE(HAVE_STDIO_H)], + [AC_MSG_ERROR([Sorry, can't do anything for you])]) + +Notice that the argument of 'AC_MSG_ERROR' is still quoted; otherwise, +its comma would have been interpreted as an argument separator. + + The following example is wrong and dangerous, as it is underquoted: + + AC_CHECK_HEADER(stdio.h, + AC_DEFINE(HAVE_STDIO_H), + AC_MSG_ERROR([Sorry, can't do anything for you])) + + In other cases, you may have to use text that also resembles a macro +call. You must quote that text even when it is not passed as a macro +argument: + + echo "Hard rock was here! --[AC_DC]" + +which will result in + + echo "Hard rock was here! --AC_DC" + +When you use the same text in a macro argument, you must therefore have +an extra quotation level (since one is stripped away by the macro +substitution). In general, then, it is a good idea to _use double +quoting for all literal string arguments_: + + AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) + + You are now able to understand one of the constructs of Autoconf that +has been continually misunderstood... The rule of thumb is that +_whenever you expect macro expansion, expect quote expansion_; i.e., +expect one level of quotes to be lost. For instance: + + AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])]) + +is incorrect: here, the first argument of 'AC_COMPILE_IFELSE' is 'char +b[10];' and will be expanded once, which results in 'char b10;'. (There +was an idiom common in Autoconf's past to address this issue via the M4 +'changequote' primitive, but do not use it!) Let's take a closer look: +the author meant the first argument to be understood as a literal, and +therefore it must be quoted twice: + + AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])]) + +Voilà, you actually produce 'char b[10];' this time! + + The careful reader will notice that, according to these guidelines, +the "properly" quoted 'AC_CHECK_HEADER' example above is actually +lacking three pairs of quotes! Nevertheless, for the sake of +readability, double quotation of literals is used only where needed in +this manual. + + Some macros take optional arguments, which this documentation +represents as [ARG] (not to be confused with the quote characters). You +may just leave them empty, or use '[]' to make the emptiness of the +argument explicit, or you may simply omit the trailing commas. The +three lines below are equivalent: + + AC_CHECK_HEADERS(stdio.h, [], [], []) + AC_CHECK_HEADERS(stdio.h,,,) + AC_CHECK_HEADERS(stdio.h) + + It is best to put each macro call on its own line in 'configure.ac'. +Most of the macros don't add extra newlines; they rely on the newline +after the macro call to terminate the commands. This approach makes the +generated 'configure' script a little easier to read by not inserting +lots of blank lines. It is generally safe to set shell variables on the +same line as a macro call, because the shell allows assignments without +intervening newlines. + + You can include comments in 'configure.ac' files by starting them +with the '#'. For example, it is helpful to begin 'configure.ac' files +with a line like this: + + # Process this file with autoconf to produce a configure script. + + +File: autoconf.info, Node: configure.ac Layout, Prev: Autoconf Language, Up: Writing configure.ac + +3.1.3 Standard 'configure.ac' Layout +------------------------------------ + +The order in which 'configure.ac' calls the Autoconf macros is not +important, with a few exceptions. Every 'configure.ac' must contain a +call to 'AC_INIT' before the checks, and a call to 'AC_OUTPUT' at the +end (*note Output::). Additionally, some macros rely on other macros +having been called first, because they check previously set values of +some variables to decide what to do. These macros are noted in the +individual descriptions (*note Existing Tests::), and they also warn you +when 'configure' is created if they are called out of order. + + To encourage consistency, here is a suggested order for calling the +Autoconf macros. Generally speaking, the things near the end of this +list are those that could depend on things earlier in it. For example, +library functions could be affected by types and libraries. + + Autoconf requirements + 'AC_INIT(PACKAGE, VERSION, BUG-REPORT-ADDRESS)' + information on the package + checks for programs + checks for libraries + checks for header files + checks for types + checks for structures + checks for compiler characteristics + checks for library functions + checks for system services + 'AC_CONFIG_FILES([FILE...])' + 'AC_OUTPUT' + + +File: autoconf.info, Node: autoscan Invocation, Next: ifnames Invocation, Prev: Writing configure.ac, Up: Making configure Scripts + +3.2 Using 'autoscan' to Create 'configure.ac' +============================================= + +The 'autoscan' program can help you create and/or maintain a +'configure.ac' file for a software package. 'autoscan' examines source +files in the directory tree rooted at a directory given as a command +line argument, or the current directory if none is given. It searches +the source files for common portability problems and creates a file +'configure.scan' which is a preliminary 'configure.ac' for that package, +and checks a possibly existing 'configure.ac' for completeness. + + When using 'autoscan' to create a 'configure.ac', you should manually +examine 'configure.scan' before renaming it to 'configure.ac'; it will +probably need some adjustments. Occasionally, 'autoscan' outputs a +macro in the wrong order relative to another macro, so that 'autoconf' +produces a warning; you need to move such macros manually. Also, if you +want the package to use a configuration header file, you must add a call +to 'AC_CONFIG_HEADERS' (*note Configuration Headers::). You might also +have to change or add some '#if' directives to your program in order to +make it work with Autoconf (*note ifnames Invocation::, for information +about a program that can help with that job). + + When using 'autoscan' to maintain a 'configure.ac', simply consider +adding its suggestions. The file 'autoscan.log' will contain detailed +information on why a macro is requested. + + 'autoscan' uses several data files (installed along with Autoconf) to +determine which macros to output when it finds particular symbols in a +package's source files. These data files all have the same format: each +line consists of a symbol, whitespace, and the Autoconf macro to output +if that symbol is encountered. Lines starting with '#' are comments. + + 'autoscan' is only installed if you already have Perl installed. +'autoscan' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--verbose' +'-v' + Print the names of the files it examines and the potentially + interesting symbols it finds in them. This output can be + voluminous. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the 'AC_MACRODIR' environment + variable to a directory; this option overrides the environment + variable. + + This option is rarely needed and dangerous; it is only used when + one plays with different versions of Autoconf simultaneously. + + +File: autoconf.info, Node: ifnames Invocation, Next: autoconf Invocation, Prev: autoscan Invocation, Up: Making configure Scripts + +3.3 Using 'ifnames' to List Conditionals +======================================== + +'ifnames' can help you write 'configure.ac' for a software package. It +prints the identifiers that the package already uses in C preprocessor +conditionals. If a package has already been set up to have some +portability, 'ifnames' can thus help you figure out what its 'configure' +needs to check for. It may help fill in some gaps in a 'configure.ac' +generated by 'autoscan' (*note autoscan Invocation::). + + 'ifnames' scans all of the C source files named on the command line +(or the standard input, if none are given) and writes to the standard +output a sorted list of all the identifiers that appear in those files +in '#if', '#elif', '#ifdef', or '#ifndef' directives. It prints each +identifier on a line, followed by a space-separated list of the files in +which that identifier occurs. + +'ifnames' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + + +File: autoconf.info, Node: autoconf Invocation, Next: autoreconf Invocation, Prev: ifnames Invocation, Up: Making configure Scripts + +3.4 Using 'autoconf' to Create 'configure' +========================================== + +To create 'configure' from 'configure.ac', run the 'autoconf' program +with no arguments. 'autoconf' processes 'configure.ac' with the 'm4' +macro processor, using the Autoconf macros. If you give 'autoconf' an +argument, it reads that file instead of 'configure.ac' and writes the +configuration script to the standard output instead of to 'configure'. +If you give 'autoconf' the argument '-', it reads from the standard +input instead of 'configure.ac' and writes the configuration script to +the standard output. + + The Autoconf macros are defined in several files. Some of the files +are distributed with Autoconf; 'autoconf' reads them first. Then it +looks for the optional file 'acsite.m4' in the directory that contains +the distributed Autoconf macro files, and for the optional file +'aclocal.m4' in the current directory. Those files can contain your +site's or the package's own Autoconf macro definitions (*note Writing +Autoconf Macros::, for more information). If a macro is defined in more +than one of the files that 'autoconf' reads, the last definition it +reads overrides the earlier ones. + + 'autoconf' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--verbose' +'-v' + Report processing steps. + +'--debug' +'-d' + Don't remove the temporary files. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the 'AC_MACRODIR' environment + variable to a directory; this option overrides the environment + variable. + + This option is rarely needed and dangerous; it is only used when + one plays with different versions of Autoconf simultaneously. + +'--localdir=DIR' +'-l DIR' + Look for the package file 'aclocal.m4' in directory DIR instead of + in the current directory. + +'--output=FILE' +'-o FILE' + Save output (script or trace) to FILE. The file '-' stands for the + standard output. + +'--warnings=CATEGORY' +'-W CATEGORY' + Report the warnings related to CATEGORY (which can actually be a + comma separated list). *Note Reporting Messages::, macro + 'AC_DIAGNOSE', for a comprehensive list of categories. Special + values include: + + 'all' + report all the warnings + + 'none' + report none + + 'error' + treats warnings as errors + + 'no-CATEGORY' + disable warnings falling into CATEGORY + + Warnings about 'syntax' are enabled by default, and the environment + variable 'WARNINGS', a comma separated list of categories, is + honored. 'autoconf -W CATEGORY' will actually behave as if you had + run: + + autoconf --warnings=syntax,$WARNINGS,CATEGORY + + If you want to disable 'autoconf''s defaults and 'WARNINGS', but + (for example) enable the warnings about obsolete constructs, you + would use '-W none,obsolete'. + + 'autoconf' displays a back trace for errors, but not for warnings; + if you want them, just pass '-W error'. For instance, on this + 'configure.ac': + + AC_DEFUN([INNER], + [AC_TRY_RUN([true])]) + + AC_DEFUN([OUTER], + [INNER]) + + AC_INIT + OUTER + + you get: + + $ autoconf -Wcross + configure.ac:8: warning: AC_TRY_RUN called without default \ + to allow cross compiling + $ autoconf -Wcross,error + configure.ac:8: error: AC_TRY_RUN called without default \ + to allow cross compiling + acgeneral.m4:3044: AC_TRY_RUN is expanded from... + configure.ac:2: INNER is expanded from... + configure.ac:5: OUTER is expanded from... + configure.ac:8: the top level + +'--trace=MACRO[:FORMAT]' +'-t MACRO[:FORMAT]' + Do not create the 'configure' script, but list the calls to MACRO + according to the FORMAT. Multiple '--trace' arguments can be used + to list several macros. Multiple '--trace' arguments for a single + macro are not cumulative; instead, you should just make FORMAT as + long as needed. + + The FORMAT is a regular string, with newlines if desired, and + several special escape codes. It defaults to '$f:$l:$n:$%'; see + below for details on the FORMAT. + +'--initialization' +'-i' + By default, '--trace' does not trace the initialization of the + Autoconf macros (typically the 'AC_DEFUN' definitions). This + results in a noticeable speedup, but can be disabled by this + option. + + It is often necessary to check the content of a 'configure.ac' file, +but parsing it yourself is extremely fragile and error-prone. It is +suggested that you rely upon '--trace' to scan 'configure.ac'. + + The FORMAT of '--trace' can use the following special escapes: + +'$$' + The character '$'. + +'$f' + The filename from which MACRO is called. + +'$l' + The line number from which MACRO is called. + +'$d' + The depth of the MACRO call. This is an M4 technical detail that + you probably don't want to know about. + +'$n' + The name of the MACRO. + +'$NUM' + The NUMth argument of the call to MACRO. + +'$@' +'$SEP@' +'${SEPARATOR}@' + All the arguments passed to MACRO, separated by the character SEP + or the string SEPARATOR (',' by default). Each argument is quoted, + i.e. enclosed in a pair of square brackets. + +'$*' +'$SEP*' +'${SEPARATOR}*' + As above, but the arguments are not quoted. + +'$%' +'$SEP%' +'${SEPARATOR}%' + As above, but the arguments are not quoted, all new line characters + in the arguments are smashed, and the default separator is ':'. + + The escape '$%' produces single-line trace outputs (unless you put + newlines in the 'separator'), while '$@' and '$*' do not. + + For instance, to find the list of variables that are substituted, +use: + + $ autoconf -t AC_SUBST + configure.ac:2:AC_SUBST:ECHO_C + configure.ac:2:AC_SUBST:ECHO_N + configure.ac:2:AC_SUBST:ECHO_T + More traces deleted + +The example below highlights the difference between '$@', '$*', and +*$%*. + + $ cat configure.ac + AC_DEFINE(This, is, [an + [example]]) + $ autoconf -t 'AC_DEFINE:@: $@ + *: $* + $: $%' + @: [This],[is],[an + [example]] + *: This,is,an + [example] + $: This:is:an [example] + +The FORMAT gives you a lot of freedom: + + $ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";' + $ac_subst{"ECHO_C"} = "configure.ac:2"; + $ac_subst{"ECHO_N"} = "configure.ac:2"; + $ac_subst{"ECHO_T"} = "configure.ac:2"; + More traces deleted + +A long SEPARATOR can be used to improve the readability of complex +structures, and to ease its parsing (for instance when no single +character is suitable as a separator)): + + $ autoconf -t 'AM_MISSING_PROG:${|:::::|}*' + AUTOCONF|:::::|autoconf|:::::|$missing_dir + More traces deleted + + +File: autoconf.info, Node: autoreconf Invocation, Prev: autoconf Invocation, Up: Making configure Scripts + +3.5 Using 'autoreconf' to Update 'configure' Scripts +==================================================== + +If you have a lot of Autoconf-generated 'configure' scripts, the +'autoreconf' program can save you some work. It runs 'autoconf' (and +'autoheader', where appropriate) repeatedly to remake the Autoconf +'configure' scripts and configuration header templates in the directory +tree rooted at the current directory. By default, it only remakes those +files that are older than their 'configure.ac' or (if present) +'aclocal.m4'. Since 'autoheader' does not change the timestamp of its +output file if the file wouldn't be changing, this is not necessarily +the minimum amount of work. If you install a new version of Autoconf, +you can make 'autoreconf' remake _all_ of the files by giving it the +'--force' option. + + If you give 'autoreconf' the '--autoconf-dir=DIR' or '--localdir=DIR' +options, it passes them down to 'autoconf' and 'autoheader' (with +relative paths adjusted properly). + + 'autoreconf' does not support having, in the same directory tree, +both directories that are parts of a larger package (sharing +'aclocal.m4' and 'acconfig.h') and directories that are independent +packages (each with their own 'aclocal.m4' and 'acconfig.h'). It +assumes that they are all part of the same package if you use +'--localdir', or that each directory is a separate package if you don't +use it. This restriction may be removed in the future. + + *Note Automatic Remaking::, for 'Makefile' rules to automatically +remake 'configure' scripts when their source files change. That method +handles the timestamps of configuration header templates properly, but +does not pass '--autoconf-dir=DIR' or '--localdir=DIR'. + +'autoreconf' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--verbose' + Print the name of each directory where 'autoreconf' runs 'autoconf' + (and 'autoheader', if appropriate). + +'--debug' +'-d' + Don't remove the temporary files. + +'--force' +'-f' + Remake even 'configure' scripts and configuration headers that are + newer than their input files ('configure.ac' and, if present, + 'aclocal.m4'). + +'--install' +'-i' + Copy missing auxiliary files. This option is similar to the option + '--add-missing' in other tools. + +'--symlink' +'-s' + Instead of copying missing auxiliary files, install symbolic links. + +'--localdir=DIR' +'-l DIR' + Have 'autoconf' and 'autoheader' look for the package files + 'aclocal.m4' and ('autoheader' only) 'acconfig.h' (but not + 'FILE.top' and 'FILE.bot') in directory DIR instead of in the + directory containing each 'configure.ac'. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the 'AC_MACRODIR' environment + variable to a directory; this option overrides the environment + variable. + + This option is rarely needed and dangerous; it is only used when + one plays with different versions of Autoconf simultaneously. + +'--m4dir=DIR' +'-M DIR' + Specify location of additional macro files ('m4' by default). + + +File: autoconf.info, Node: Setup, Next: Existing Tests, Prev: Making configure Scripts, Up: Top + +4 Initialization and Output Files +********************************* + +Autoconf-generated 'configure' scripts need some information about how +to initialize, such as how to find the package's source files; and about +the output files to produce. The following sections describe +initialization and the creation of output files. + +* Menu: + +* Notices:: Copyright, version numbers in 'configure' +* Input:: Where Autoconf should find files +* Output:: Outputting results from the configuration +* Configuration Actions:: Preparing the output based on results +* Configuration Files:: Creating output files +* Makefile Substitutions:: Using output variables in 'Makefile's +* Configuration Headers:: Creating a configuration header file +* Configuration Commands:: Running arbitrary instantiation commands +* Configuration Links:: Links depending from the configuration +* Subdirectories:: Configuring independent packages together +* Default Prefix:: Changing the default installation prefix + + +File: autoconf.info, Node: Notices, Next: Input, Prev: Setup, Up: Setup + +4.1 Notices in 'configure' +========================== + +The following macros manage version numbers for 'configure' scripts. +Using them is optional. + + -- Macro: AC_PREREQ (VERSION) + Ensure that a recent enough version of Autoconf is being used. If + the version of Autoconf being used to create 'configure' is earlier + than VERSION, print an error message to the standard error output + and do not create 'configure'. For example: + + AC_PREREQ(2.52.20231210) + + This macro is the only macro that may be used before 'AC_INIT', but + for consistency, you are invited not to do so. + + -- Macro: AC_COPYRIGHT (COPYRIGHT-NOTICE) + State that, in addition to the Free Software Foundation's copyright + on the Autoconf macros, parts of your 'configure' are covered by + the COPYRIGHT-NOTICE. + + The COPYRIGHT-NOTICE will show up in both the head of 'configure' + and in 'configure --version'. + + -- Macro: AC_REVISION (REVISION-INFO) + Copy revision stamp REVISION-INFO into the 'configure' script, with + any dollar signs or double-quotes removed. This macro lets you put + a revision stamp from 'configure.ac' into 'configure' without RCS + or 'cvs' changing it when you check in 'configure'. That way, you + can determine easily which revision of 'configure.ac' a particular + 'configure' corresponds to. + + For example, this line in 'configure.ac': + + AC_REVISION($Revision: 1.77 $) + + produces this in 'configure': + + #! /bin/sh + # From configure.ac Revision: 1.30 + + +File: autoconf.info, Node: Input, Next: Output, Prev: Notices, Up: Setup + +4.2 Finding 'configure' Input +============================= + +Every 'configure' script must call 'AC_INIT' before doing anything else. +The only other required macro is 'AC_OUTPUT' (*note Output::). + + -- Macro: AC_INIT (PACKAGE, VERSION, [BUG-REPORT-ADDRESS]) + Process any command-line arguments and perform various + initializations and verifications. Set the name of the PACKAGE and + its VERSION. The optional argument BUG-REPORT-ADDRESS should be + the email to which users should send bug reports. + + -- Macro: AC_CONFIG_SRCDIR (UNIQUE-FILE-IN-SOURCE-DIR) + UNIQUE-FILE-IN-SOURCE-DIR is some file that is in the package's + source directory; 'configure' checks for this file's existence to + make sure that the directory that it is told contains the source + code in fact does. Occasionally people accidentally specify the + wrong directory with '--srcdir'; this is a safety check. *Note + configure Invocation::, for more information. + + Packages that do manual configuration or use the 'install' program +might need to tell 'configure' where to find some other shell scripts by +calling 'AC_CONFIG_AUX_DIR', though the default places it looks are +correct for most cases. + + -- Macro: AC_CONFIG_AUX_DIR (DIR) + Use the auxiliary build tools (e.g., 'install-sh', 'config.sub', + 'config.guess', Cygnus 'configure', Automake and Libtool scripts + etc.) that are in directory DIR. These are auxiliary files used + in configuration. DIR can be either absolute or relative to + 'SRCDIR'. The default is 'SRCDIR' or 'SRCDIR/..' or + 'SRCDIR/../..', whichever is the first that contains 'install-sh'. + The other files are not checked for, so that using + 'AC_PROG_INSTALL' does not automatically require distributing the + other auxiliary files. It checks for 'install.sh' also, but that + name is obsolete because some 'make' have a rule that creates + 'install' from it if there is no 'Makefile'. + + +File: autoconf.info, Node: Output, Next: Configuration Actions, Prev: Input, Up: Setup + +4.3 Outputting Files +==================== + +Every Autoconf-generated 'configure' script must finish by calling +'AC_OUTPUT'. It is the macro that generates 'config.status', which will +create the 'Makefile's and any other files resulting from configuration. +The only other required macro is 'AC_INIT' (*note Input::). + + -- Macro: AC_OUTPUT + Generate 'config.status' and launch it. Call this macro once, at + the end of 'configure.ac'. + + 'config.status' will take all the configuration actions: all the + output files (see *note Configuration Files::, macro + 'AC_CONFIG_FILES'), header files (see *note Configuration + Headers::, macro 'AC_CONFIG_HEADERS'), commands (see *note + Configuration Commands::, macro 'AC_CONFIG_COMMANDS'), links (see + *note Configuration Links::, macro 'AC_CONFIG_LINKS'), + subdirectories to configure (see *note Subdirectories::, macro + 'AC_CONFIG_SUBDIRS') are honored. + + Historically, the usage of 'AC_OUTPUT' was somewhat different. *Note +Obsolete Macros::, for a description of the arguments that 'AC_OUTPUT' +used to support. + + If you run 'make' on subdirectories, you should run it using the +'make' variable 'MAKE'. Most versions of 'make' set 'MAKE' to the name +of the 'make' program plus any options it was given. (But many do not +include in it the values of any variables set on the command line, so +those are not passed on automatically.) Some old versions of 'make' do +not set this variable. The following macro allows you to use it even +with those versions. + + -- Macro: AC_PROG_MAKE_SET + If 'make' predefines the variable 'MAKE', define output variable + 'SET_MAKE' to be empty. Otherwise, define 'SET_MAKE' to contain + 'MAKE=make'. Calls 'AC_SUBST' for 'SET_MAKE'. + + To use this macro, place a line like this in each 'Makefile.in' that +runs 'MAKE' on other directories: + + @SET_MAKE@ + + +File: autoconf.info, Node: Configuration Actions, Next: Configuration Files, Prev: Output, Up: Setup + +4.4 Taking Configuration Actions +================================ + +'configure' is designed so that it appears to do everything itself, but +there is actually a hidden slave: 'config.status'. 'configure' is in +charge of examining your system, but it is 'config.status' that actually +takes the proper actions based on the results of 'configure'. The most +typical task of 'config.status' is to _instantiate_ files. + + This section describes the common behavior of the four standard +instantiating macros: 'AC_CONFIG_FILES', 'AC_CONFIG_HEADERS', +'AC_CONFIG_COMMANDS' and 'AC_CONFIG_LINKS'. They all have this +prototype: + + AC_CONFIG_FOOS(TAG..., [COMMANDS], [INIT-CMDS]) + +where the arguments are: + +TAG... + A whitespace-separated list of tags, which are typically the names + of the files to instantiate. + +COMMANDS + Shell commands output literally into 'config.status', and + associated with a tag that the user can use to tell 'config.status' + which the commands to run. The commands are run each time a TAG + request is given to 'config.status'; typically, each time the file + 'TAG' is created. + +INIT-CMDS + Shell commands output _unquoted_ near the beginning of + 'config.status', and executed each time 'config.status' runs + (regardless of the tag). Because they are unquoted, for example, + '$var' will be output as the value of 'var'. INIT-CMDS is + typically used by 'configure' to give 'config.status' some + variables it needs to run the COMMANDS. + + All these macros can be called multiple times, with different TAGs, +of course! + + You are encouraged to use literals as TAGS. In particular, you +should avoid + + ... && my_foos="$my_foos fooo" + ... && my_foos="$my_foos foooo" + AC_CONFIG_FOOS($my_foos) + +and use this instead: + + ... && AC_CONFIG_FOOS(fooo) + ... && AC_CONFIG_FOOS(foooo) + + The macro 'AC_CONFIG_FILES' and 'AC_CONFIG_HEADERS' use specials +TAGs: they may have the form 'OUTPUT' or 'OUTPUT:INPUTS'. The file +OUTPUT is instantiated from its templates, INPUTS if specified, +defaulting to 'OUTPUT.in'. + + For instance 'AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)' +asks for the creation of 'Makefile' that will be the expansion of the +output variables in the concatenation of 'boiler/top.mk' and +'boiler/bot.mk'. + + The special value '-' might be used to denote the standard output +when used in OUTPUT, or the standard input when used in the INPUTS. You +most probably don't need to use this in 'configure.ac', but it is +convenient when using the command line interface of './config.status', +see *note config.status Invocation::, for more details. + + The INPUTS may be absolute or relative filenames. In the latter case +they are first looked for in the build tree, and then in the source +tree. + + +File: autoconf.info, Node: Configuration Files, Next: Makefile Substitutions, Prev: Configuration Actions, Up: Setup + +4.5 Creating Configuration Files +================================ + +Be sure to read the previous section, *note Configuration Actions::. + + -- Macro: AC_CONFIG_FILES (FILE..., [CMDS], [INIT-CMDS]) + Make 'AC_OUTPUT' create each 'FILE' by copying an input file (by + default 'FILE.in'), substituting the output variable values. This + macro is one of the instantiating macros, see *note Configuration + Actions::. *Note Makefile Substitutions::, for more information on + using output variables. *Note Setting Output Variables::, for more + information on creating them. This macro creates the directory + that the file is in if it doesn't exist. Usually, 'Makefile's are + created this way, but other files, such as '.gdbinit', can be + specified as well. + + Typical calls to 'AC_CONFIG_FILES' look like this: + + AC_CONFIG_FILES(Makefile src/Makefile man/Makefile X/Imakefile) + AC_CONFIG_FILES(autoconf, chmod +x autoconf) + + You can override an input file name by appending to FILE a + colon-separated list of input files. Examples: + + AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk + lib/Makefile:boiler/lib.mk) + + Doing this allows you to keep your file names acceptable to MS-DOS, + or to prepend and/or append boilerplate to the file. + + +File: autoconf.info, Node: Makefile Substitutions, Next: Configuration Headers, Prev: Configuration Files, Up: Setup + +4.6 Substitutions in Makefiles +============================== + +Each subdirectory in a distribution that contains something to be +compiled or installed should come with a file 'Makefile.in', from which +'configure' will create a 'Makefile' in that directory. To create a +'Makefile', 'configure' performs a simple variable substitution, +replacing occurrences of '@VARIABLE@' in 'Makefile.in' with the value +that 'configure' has determined for that variable. Variables that are +substituted into output files in this way are called "output variables". +They are ordinary shell variables that are set in 'configure'. To make +'configure' substitute a particular variable into the output files, the +macro 'AC_SUBST' must be called with that variable name as an argument. +Any occurrences of '@VARIABLE@' for other variables are left unchanged. +*Note Setting Output Variables::, for more information on creating +output variables with 'AC_SUBST'. + + A software package that uses a 'configure' script should be +distributed with a file 'Makefile.in', but no 'Makefile'; that way, the +user has to properly configure the package for the local system before +compiling it. + + *Note Makefile Conventions: (standards)Makefile Conventions, for more +information on what to put in 'Makefile's. + +* Menu: + +* Preset Output Variables:: Output variables that are always set +* Installation Directory Variables:: Other preset output variables +* Build Directories:: Supporting multiple concurrent compiles +* Automatic Remaking:: Makefile rules for configuring + + +File: autoconf.info, Node: Preset Output Variables, Next: Installation Directory Variables, Prev: Makefile Substitutions, Up: Makefile Substitutions + +4.6.1 Preset Output Variables +----------------------------- + +Some output variables are preset by the Autoconf macros. Some of the +Autoconf macros set additional output variables, which are mentioned in +the descriptions for those macros. *Note Output Variable Index::, for a +complete list of output variables. *Note Installation Directory +Variables::, for the list of the preset ones related to installation +directories. Below are listed the other preset ones. They all are +precious variables (*note Setting Output Variables::, 'AC_ARG_VAR'). + + -- Variable: CFLAGS + Debugging and optimization options for the C compiler. If it is + not set in the environment when 'configure' runs, the default value + is set when you call 'AC_PROG_CC' (or empty if you don't). + 'configure' uses this variable when compiling programs to test for + C features. + + -- Variable: configure_input + A comment saying that the file was generated automatically by + 'configure' and giving the name of the input file. 'AC_OUTPUT' + adds a comment line containing this variable to the top of every + 'Makefile' it creates. For other files, you should reference this + variable in a comment at the top of each input file. For example, + an input shell script should begin like this: + + #! /bin/sh + # @configure_input@ + + The presence of that line also reminds people editing the file that + it needs to be processed by 'configure' in order to be used. + + -- Variable: CPPFLAGS + Header file search directory ('-IDIR') and any other miscellaneous + options for the C and C++ preprocessors and compilers. If it is + not set in the environment when 'configure' runs, the default value + is empty. 'configure' uses this variable when compiling or + preprocessing programs to test for C and C++ features. + + -- Variable: CXXFLAGS + Debugging and optimization options for the C++ compiler. If it is + not set in the environment when 'configure' runs, the default value + is set when you call 'AC_PROG_CXX' (or empty if you don't). + 'configure' uses this variable when compiling programs to test for + C++ features. + + -- Variable: DEFS + '-D' options to pass to the C compiler. If 'AC_CONFIG_HEADERS' is + called, 'configure' replaces '@DEFS@' with '-DHAVE_CONFIG_H' + instead (*note Configuration Headers::). This variable is not + defined while 'configure' is performing its tests, only when + creating the output files. *Note Setting Output Variables::, for + how to check the results of previous tests. + + -- Variable: ECHO_C + -- Variable: ECHO_N + -- Variable: ECHO_T + How does one suppress the trailing newline from 'echo' for + question-answer message pairs? These variables provide a way: + + echo $ECHO_N "And the winner is... $ECHO_C" + sleep 100000000000 + echo "${ECHO_T}dead." + + Some old and uncommon 'echo' implementations offer no means to + achieve this, in which case 'ECHO_T' is set to tab. You might not + want to use it. + + -- Variable: FFLAGS + Debugging and optimization options for the Fortran 77 compiler. If + it is not set in the environment when 'configure' runs, the default + value is set when you call 'AC_PROG_F77' (or empty if you don't). + 'configure' uses this variable when compiling programs to test for + Fortran 77 features. + + -- Variable: LDFLAGS + Stripping ('-s'), path ('-L'), and any other miscellaneous options + for the linker. Don't use this variable to pass library names + ('-l') to the linker, use 'LIBS' instead. If it is not set in the + environment when 'configure' runs, the default value is empty. + 'configure' uses this variable when linking programs to test for C, + C++ and Fortran 77 features. + + -- Variable: LIBS + '-l' options to pass to the linker. The default value is empty, + but some Autoconf macros may prepend extra libraries to this + variable if those libraries are found and provide necessary + functions, see *note Libraries::. 'configure' uses this variable + when linking programs to test for C, C++ and Fortran 77 features. + + -- Variable: srcdir + The directory that contains the source code for that 'Makefile'. + + -- Variable: top_srcdir + The top-level source code directory for the package. In the + top-level directory, this is the same as 'srcdir'. + + +File: autoconf.info, Node: Installation Directory Variables, Next: Build Directories, Prev: Preset Output Variables, Up: Makefile Substitutions + +4.6.2 Installation Directory Variables +-------------------------------------- + +The following variables specify the directories where the package will +be installed, see *note Variables for Installation Directories: +(standards)Directory Variables, for more information. See the end of +this section for details on when and how to use these variables. + + -- Variable: bindir + The directory for installing executables that users run. + + -- Variable: datadir + The directory for installing read-only architecture-independent + data. + + -- Variable: exec_prefix + The installation prefix for architecture-dependent files. By + default it's the same as PREFIX. You should avoid installing + anything directly to EXEC_PREFIX. However, the default value for + directories containing architecture-dependent files should be + relative to EXEC_PREFIX. + + -- Variable: includedir + The directory for installing C header files. + + -- Variable: infodir + The directory for installing documentation in Info format. + + -- Variable: libdir + The directory for installing object code libraries. + + -- Variable: libexecdir + The directory for installing executables that other programs run. + + -- Variable: localstatedir + The directory for installing modifiable single-machine data. + + -- Variable: mandir + The top-level directory for installing documentation in man format. + + -- Variable: oldincludedir + The directory for installing C header files for non-gcc compilers. + + -- Variable: prefix + The common installation prefix for all files. If EXEC_PREFIX is + defined to a different value, PREFIX is used only for + architecture-independent files. + + -- Variable: sbindir + The directory for installing executables that system administrators + run. + + -- Variable: sharedstatedir + The directory for installing modifiable architecture-independent + data. + + -- Variable: sysconfdir + The directory for installing read-only single-machine data. + + Most of these variables have values that rely on 'prefix' or +'exec_prefix'. It is on purpose that the directory output variables +keep them unexpanded: typically '@datadir@' will be replaced by +'${prefix}/share', not '/usr/local/share'. + + This behavior is mandated by the GNU coding standards, so that when +the user runs: + +'make' + she can still specify a different prefix from the one specified to + 'configure', in which case, if needed, the package shall hard code + dependencies to her late desires. + +'make install' + she can specify a different installation location, in which case + the package _must_ still depend on the location which was compiled + in (i.e., never recompile when 'make install' is run). This is an + extremely important feature, as many people may decide to install + all the files of a package grouped together, and then install links + from the final locations to there. + + In order to support these features, it is essential that 'datadir' +remains being defined as '${prefix}/share' to depend upon the current +value of 'prefix'. + + A corollary is that you should not use these variables but in +Makefiles. For instance, instead of trying to evaluate 'datadir' in +'configure' and hardcoding it in Makefiles using e.g. +'AC_DEFINE_UNQUOTED(DATADIR, "$datadir")', you should add +'-DDATADIR="$(datadir)"' to your 'CPPFLAGS'. + + Similarly you should not rely on 'AC_OUTPUT_FILES' to replace +'datadir' and friends in your shell scripts and other files, rather let +'make' manage their replacement. For instance Autoconf ships templates +of its shell scripts ending with '.sh', and uses this Makefile snippet: + + .sh: + rm -f $@ $@.tmp + sed 's,@datadir\@,$(pkgdatadir),g' $< >$@.tmp + chmod +x $@.tmp + mv $@.tmp $@ + + Three things are noteworthy: + +'@datadir\@' + The backslash prevents 'configure' from replacing '@datadir@' in + the sed expression itself. + +'$(pkgdatadir)' + Don't use '@pkgdatadir@'! Use the matching makefile variable + instead. + +',' + Don't use '/' in the sed expression(s) since most probably the + variables you use, such as '$(pkgdatadir)', will contain some. + + +File: autoconf.info, Node: Build Directories, Next: Automatic Remaking, Prev: Installation Directory Variables, Up: Makefile Substitutions + +4.6.3 Build Directories +----------------------- + +You can support compiling a software package for several architectures +simultaneously from the same copy of the source code. The object files +for each architecture are kept in their own directory. + + To support doing this, 'make' uses the 'VPATH' variable to find the +files that are in the source directory. GNU 'make' and most other +recent 'make' programs can do this. Older 'make' programs do not +support 'VPATH'; when using them, the source code must be in the same +directory as the object files. + + To support 'VPATH', each 'Makefile.in' should contain two lines that +look like: + + srcdir = @srcdir@ + VPATH = @srcdir@ + + Do not set 'VPATH' to the value of another variable, for example +'VPATH = $(srcdir)', because some versions of 'make' do not do variable +substitutions on the value of 'VPATH'. + + 'configure' substitutes in the correct value for 'srcdir' when it +produces 'Makefile'. + + Do not use the 'make' variable '$<', which expands to the file name +of the file in the source directory (found with 'VPATH'), except in +implicit rules. (An implicit rule is one such as '.c.o', which tells +how to create a '.o' file from a '.c' file.) Some versions of 'make' do +not set '$<' in explicit rules; they expand it to an empty value. + + Instead, 'Makefile' command lines should always refer to source files +by prefixing them with '$(srcdir)/'. For example: + + time.info: time.texinfo + $(MAKEINFO) $(srcdir)/time.texinfo + + +File: autoconf.info, Node: Automatic Remaking, Prev: Build Directories, Up: Makefile Substitutions + +4.6.4 Automatic Remaking +------------------------ + +You can put rules like the following in the top-level 'Makefile.in' for +a package to automatically update the configuration information when you +change the configuration files. This example includes all of the +optional files, such as 'aclocal.m4' and those related to configuration +header files. Omit from the 'Makefile.in' rules for any of these files +that your package does not use. + + The '$(srcdir)/' prefix is included because of limitations in the +'VPATH' mechanism. + + The 'stamp-' files are necessary because the timestamps of +'config.h.in' and 'config.h' will not be changed if remaking them does +not change their contents. This feature avoids unnecessary +recompilation. You should include the file 'stamp-h.in' your package's +distribution, so 'make' will consider 'config.h.in' up to date. Don't +use 'touch' (*note Limitations of Usual Tools::), rather use 'echo' +(using 'date' would cause needless differences, hence CVS conflicts +etc.). + + $(srcdir)/configure: configure.ac aclocal.m4 + cd $(srcdir) && autoconf + + # autoheader might not change config.h.in, so touch a stamp file. + $(srcdir)/config.h.in: stamp-h.in + $(srcdir)/stamp-h.in: configure.ac aclocal.m4 + cd $(srcdir) && autoheader + echo timestamp > $(srcdir)/stamp-h.in + + config.h: stamp-h + stamp-h: config.h.in config.status + ./config.status + + Makefile: Makefile.in config.status + ./config.status + + config.status: configure + ./config.status --recheck + +(Be careful if you copy these lines directly into your Makefile, as you +will need to convert the indented lines to start with the tab +character.) + + In addition, you should use 'AC_CONFIG_FILES(stamp-h, echo timestamp +> stamp-h)' so 'config.status' will ensure that 'config.h' is considered +up to date. *Note Output::, for more information about 'AC_OUTPUT'. + + *Note config.status Invocation::, for more examples of handling +configuration-related dependencies. + + +File: autoconf.info, Node: Configuration Headers, Next: Configuration Commands, Prev: Makefile Substitutions, Up: Setup + +4.7 Configuration Header Files +============================== + +When a package tests more than a few C preprocessor symbols, the command +lines to pass '-D' options to the compiler can get quite long. This +causes two problems. One is that the 'make' output is hard to visually +scan for errors. More seriously, the command lines can exceed the +length limits of some operating systems. As an alternative to passing +'-D' options to the compiler, 'configure' scripts can create a C header +file containing '#define' directives. The 'AC_CONFIG_HEADERS' macro +selects this kind of output. It should be called right after 'AC_INIT'. + + The package should '#include' the configuration header file before +any other header files, to prevent inconsistencies in declarations (for +example, if it redefines 'const'). Use '#include <config.h>' instead of +'#include "config.h"', and pass the C compiler a '-I.' option (or +'-I..'; whichever directory contains 'config.h'). That way, even if the +source directory is configured itself (perhaps to make a distribution), +other build directories can also be configured without finding the +'config.h' from the source directory. + + -- Macro: AC_CONFIG_HEADERS (HEADER ..., [CMDS], [INIT-CMDS]) + This macro is one of the instantiating macros, see *note + Configuration Actions::. Make 'AC_OUTPUT' create the file(s) in + the whitespace-separated list HEADER containing C preprocessor + '#define' statements, and replace '@DEFS@' in generated files with + '-DHAVE_CONFIG_H' instead of the value of 'DEFS'. The usual name + for HEADER is 'config.h'. + + If HEADER already exists and its contents are identical to what + 'AC_OUTPUT' would put in it, it is left alone. Doing this allows + some changes in configuration without needlessly causing object + files that depend on the header file to be recompiled. + + Usually the input file is named 'HEADER.in'; however, you can + override the input file name by appending to HEADER, a + colon-separated list of input files. Examples: + + AC_CONFIG_HEADERS(config.h:config.hin) + AC_CONFIG_HEADERS(defines.h:defs.pre:defines.h.in:defs.post) + + Doing this allows you to keep your file names acceptable to MS-DOS, + or to prepend and/or append boilerplate to the file. + + *Note Configuration Actions::, for more details on HEADER. + +* Menu: + +* Header Templates:: Input for the configuration headers +* autoheader Invocation:: How to create configuration templates +* Autoheader Macros:: How to specify CPP templates + + +File: autoconf.info, Node: Header Templates, Next: autoheader Invocation, Prev: Configuration Headers, Up: Configuration Headers + +4.7.1 Configuration Header Templates +------------------------------------ + +Your distribution should contain a template file that looks as you want +the final header file to look, including comments, with '#undef' +statements which are used as hooks. For example, suppose your +'configure.ac' makes these calls: + + AC_CONFIG_HEADERS(conf.h) + AC_CHECK_HEADERS(unistd.h) + +Then you could have code like the following in 'conf.h.in'. On systems +that have 'unistd.h', 'configure' will '#define' 'HAVE_UNISTD_H' to 1. +On other systems, the whole line will be commented out (in case the +system predefines that symbol). + + /* Define as 1 if you have unistd.h. */ + #undef HAVE_UNISTD_H + + You can then decode the configuration header using the preprocessor +directives: + + #include <conf.h> + + #if HAVE_UNISTD_H + # include <unistd.h> + #else + /* We are in trouble. */ + #endif + + The use of old form templates, with '#define' instead of '#undef' is +strongly discouraged. + + Since it is a tedious task to keep a template header up to date, you +may use 'autoheader' to generate it, see *note autoheader Invocation::. + + +File: autoconf.info, Node: autoheader Invocation, Next: Autoheader Macros, Prev: Header Templates, Up: Configuration Headers + +4.7.2 Using 'autoheader' to Create 'config.h.in' +------------------------------------------------ + +The 'autoheader' program can create a template file of C '#define' +statements for 'configure' to use. If 'configure.ac' invokes +'AC_CONFIG_HEADERS(FILE)', 'autoheader' creates 'FILE.in'; if multiple +file arguments are given, the first one is used. Otherwise, +'autoheader' creates 'config.h.in'. + + In order to do its job, 'autoheader' needs you to document all of the +symbols that you might use; i.e., there must be at least one 'AC_DEFINE' +or one 'AC_DEFINE_UNQUOTED' using its third argument for each symbol +(*note Defining Symbols::). An additional constraint is that the first +argument of 'AC_DEFINE' must be a literal. Note that all symbols +defined by Autoconf's built-in tests are already documented properly; +you only need to document those that you define yourself. + + You might wonder why 'autoheader' is needed: after all, why would +'configure' need to "patch" a 'config.h.in' to produce a 'config.h' +instead of just creating 'config.h' from scratch? Well, when everything +rocks, the answer is just that we are wasting our time maintaining +'autoheader': generating 'config.h' directly is all that is needed. +When things go wrong, however, you'll be thankful for the existence of +'autoheader'. + + The fact that the symbols are documented is important in order to +_check_ that 'config.h' makes sense. The fact that there is a well +defined list of symbols that should be '#define''d (or not) is also +important for people who are porting packages to environments where +'configure' cannot be run: they just have to _fill in the blanks_. + + But let's come back to the point: 'autoheader''s invocation... + + If you give 'autoheader' an argument, it uses that file instead of +'configure.ac' and writes the header file to the standard output instead +of to 'config.h.in'. If you give 'autoheader' an argument of '-', it +reads the standard input instead of 'configure.ac' and writes the header +file to the standard output. + + 'autoheader' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--debug' +'-d' + Don't remove the temporary files. + +'--verbose' +'-v' + Report processing steps. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the 'AC_MACRODIR' environment + variable to a directory; this option overrides the environment + variable. + + This option is rarely needed and dangerous; it is only used when + one plays with different versions of Autoconf simultaneously. + +'--localdir=DIR' +'-l DIR' + Look for the package files 'aclocal.m4' and 'acconfig.h' (but not + 'FILE.top' and 'FILE.bot') in directory DIR instead of in the + current directory. + +'--warnings=CATEGORY' +'-W CATEGORY' + Report the warnings related to CATEGORY (which can actually be a + comma separated list). Current categories include: + + 'obsolete' + report the uses of obsolete constructs + + 'all' + report all the warnings + + 'none' + report none + + 'error' + treats warnings as errors + + 'no-CATEGORY' + disable warnings falling into CATEGORY + + +File: autoconf.info, Node: Autoheader Macros, Prev: autoheader Invocation, Up: Configuration Headers + +4.7.3 Autoheader Macros +----------------------- + +'autoheader' scans 'configure.ac' and figures out which C preprocessor +symbols it might define. It knows how to generate templates for symbols +defined by 'AC_CHECK_HEADERS', 'AC_CHECK_FUNCS' etc., but if you +'AC_DEFINE' any additional symbol, you must define a template for it. +If there are missing templates, 'autoheader' fails with an error +message. + + The simplest way to create a template for a SYMBOL is to supply the +DESCRIPTION argument to an 'AC_DEFINE(SYMBOL)'; see *note Defining +Symbols::. You may also use one of the following macros. + + -- Macro: AH_VERBATIM (KEY, TEMPLATE) + Tell 'autoheader' to include the TEMPLATE as-is in the header + template file. This TEMPLATE is associated with the KEY, which is + used to sort all the different templates and guarantee their + uniqueness. It should be the symbol that can be 'AC_DEFINE''d. + + For example: + + AH_VERBATIM([_GNU_SOURCE], + [/* Enable GNU extensions on systems that have them. */ + #ifndef _GNU_SOURCE + # define _GNU_SOURCE + #endif]) + + -- Macro: AH_TEMPLATE (KEY, DESCRIPTION) + Tell 'autoheader' to generate a template for KEY. This macro + generates standard templates just like 'AC_DEFINE' when a + DESCRIPTION is given. + + For example: + + AH_TEMPLATE([CRAY_STACKSEG_END], + [Define to one of _getb67, GETB67, getb67 + for Cray-2 and Cray-YMP systems. This + function is required for alloca.c support + on those systems.]) + + will generate the following template, with the description properly + justified. + + /* Define to one of _getb67, GETB67, getb67 for Cray-2 and + Cray-YMP systems. This function is required for alloca.c + support on those systems. */ + #undef CRAY_STACKSEG_END + + -- Macro: AH_TOP (TEXT) + Include TEXT at the top of the header template file. + + -- Macro: AH_BOTTOM (TEXT) + Include TEXT at the bottom of the header template file. + + +File: autoconf.info, Node: Configuration Commands, Next: Configuration Links, Prev: Configuration Headers, Up: Setup + +4.8 Running Arbitrary Configuration Commands +============================================ + +You execute arbitrary commands either before, during and after +'config.status' is run. The three following macros accumulate the +commands to run when they are called multiple times. +'AC_CONFIG_COMMANDS' replaces the obsolete macro 'AC_OUTPUT_COMMANDS', +see *note Obsolete Macros::, for details. + + -- Macro: AC_CONFIG_COMMANDS (TAG..., [CMDS], [INIT-CMDS]) + Specify additional shell commands to run at the end of + 'config.status', and shell commands to initialize any variables + from 'configure'. Associate the commands to the TAG. Since + typically the CMDS create a file, TAG should naturally be the name + of that file. This macro is one of the instantiating macros, see + *note Configuration Actions::. + + Here is an unrealistic example: + fubar=42 + AC_CONFIG_COMMANDS(fubar, + [echo this is extra $fubar, and so on.], + [fubar=$fubar]) + + Here is a better one: + AC_CONFIG_COMMANDS(time-stamp, [date >time-stamp]) + + -- Macro: AC_CONFIG_COMMANDS_PRE (CMDS) + Execute the CMDS right before creating 'config.status'. A typical + use is computing values derived from variables built during the + execution of 'configure': + + AC_CONFIG_COMMANDS_PRE( + [LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'` + AC_SUBST(LTLIBOBJS)]) + + -- Macro: AC_CONFIG_COMMANDS_POST (CMDS) + Execute the CMDS right after creating 'config.status'. + + +File: autoconf.info, Node: Configuration Links, Next: Subdirectories, Prev: Configuration Commands, Up: Setup + +4.9 Creating Configuration Links +================================ + +You may find it convenient to create links whose destinations depend +upon results of tests. One can use 'AC_CONFIG_COMMANDS' but the +creation of relative symbolic links can be delicate when the package is +built in another directory than its sources. + + -- Macro: AC_CONFIG_LINKS (DEST:SOURCE..., [CMDS], [INIT-CMDS]) + Make 'AC_OUTPUT' link each of the existing files SOURCE to the + corresponding link name DEST. Makes a symbolic link if possible, + otherwise a hard link. The DEST and SOURCE names should be + relative to the top level source or build directory. This macro is + one of the instantiating macros, see *note Configuration Actions::. + + For example, this call: + + AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) + + creates in the current directory 'host.h' as a link to + 'SRCDIR/config/$machine.h', and 'object.h' as a link to + 'SRCDIR/config/$obj_format.h'. + + The tempting value '.' for DEST is invalid: it makes it impossible + for 'config.status' to guess the links to establish. + + One can then run: + ./config.status host.h object.h + to create the links. + + +File: autoconf.info, Node: Subdirectories, Next: Default Prefix, Prev: Configuration Links, Up: Setup + +4.10 Configuring Other Packages in Subdirectories +================================================= + +In most situations, calling 'AC_OUTPUT' is sufficient to produce +'Makefile's in subdirectories. However, 'configure' scripts that +control more than one independent package can use 'AC_CONFIG_SUBDIRS' to +run 'configure' scripts for other packages in subdirectories. + + -- Macro: AC_CONFIG_SUBDIRS (DIR ...) + Make 'AC_OUTPUT' run 'configure' in each subdirectory DIR in the + given whitespace-separated list. Each DIR should be a literal, + i.e., please do not use: + + if test "$package_foo_enabled" = yes; then + $my_subdirs="$my_subdirs foo" + fi + AC_CONFIG_SUBDIRS($my_subdirs) + + because this prevents './configure --help=recursive' from + displaying the options of the package 'foo'. Rather, you should + write: + + if test "$package_foo_enabled" = yes then; + AC_CONFIG_SUBDIRS(foo) + fi + + If a given DIR is not found, no error is reported, so a 'configure' + script can configure whichever parts of a large source tree are + present. If a given DIR contains 'configure.gnu', it is run + instead of 'configure'. This is for packages that might use a + non-autoconf script 'Configure', which can't be called through a + wrapper 'configure' since it would be the same file on + case-insensitive filesystems. Likewise, if a DIR contains + 'configure.ac' but no 'configure', the Cygnus 'configure' script + found by 'AC_CONFIG_AUX_DIR' is used. + + The subdirectory 'configure' scripts are given the same command + line options that were given to this 'configure' script, with minor + changes if needed (e.g., to adjust a relative path for the cache + file or source directory). This macro also sets the output + variable 'subdirs' to the list of directories 'DIR ...'. + 'Makefile' rules can use this variable to determine which + subdirectories to recurse into. This macro may be called multiple + times. + + +File: autoconf.info, Node: Default Prefix, Prev: Subdirectories, Up: Setup + +4.11 Default Prefix +=================== + +By default, 'configure' sets the prefix for files it installs to +'/usr/local'. The user of 'configure' can select a different prefix +using the '--prefix' and '--exec-prefix' options. There are two ways to +change the default: when creating 'configure', and when running it. + + Some software packages might want to install in a directory besides +'/usr/local' by default. To accomplish that, use the +'AC_PREFIX_DEFAULT' macro. + + -- Macro: AC_PREFIX_DEFAULT (PREFIX) + Set the default installation prefix to PREFIX instead of + '/usr/local'. + + It may be convenient for users to have 'configure' guess the +installation prefix from the location of a related program that they +have already installed. If you wish to do that, you can call +'AC_PREFIX_PROGRAM'. + + -- Macro: AC_PREFIX_PROGRAM (PROGRAM) + If the user did not specify an installation prefix (using the + '--prefix' option), guess a value for it by looking for PROGRAM in + 'PATH', the way the shell does. If PROGRAM is found, set the + prefix to the parent of the directory containing PROGRAM; otherwise + leave the prefix specified in 'Makefile.in' unchanged. For + example, if PROGRAM is 'gcc' and the 'PATH' contains + '/usr/local/gnu/bin/gcc', set the prefix to '/usr/local/gnu'. + + +File: autoconf.info, Node: Existing Tests, Next: Writing Tests, Prev: Setup, Up: Top + +5 Existing Tests +**************** + +These macros test for particular system features that packages might +need or want to use. If you need to test for a kind of feature that +none of these macros check for, you can probably do it by calling +primitive test macros with appropriate arguments (*note Writing +Tests::). + + These tests print messages telling the user which feature they're +checking for, and what they find. They cache their results for future +'configure' runs (*note Caching Results::). + + Some of these macros set output variables. *Note Makefile +Substitutions::, for how to get their values. The phrase "define NAME" +is used below as a shorthand to mean "define C preprocessor symbol NAME +to the value 1". *Note Defining Symbols::, for how to get those symbol +definitions into your program. + +* Menu: + +* Common Behavior:: Macros' standard schemes +* Alternative Programs:: Selecting between alternative programs +* Files:: Checking for the existence of files +* Libraries:: Library archives that might be missing +* Library Functions:: C library functions that might be missing +* Header Files:: Header files that might be missing +* Declarations:: Declarations that may be missing +* Structures:: Structures or members that might be missing +* Types:: Types that might be missing +* Compilers and Preprocessors:: Checking for compiling programs +* System Services:: Operating system services +* UNIX Variants:: Special kludges for specific UNIX variants + + +File: autoconf.info, Node: Common Behavior, Next: Alternative Programs, Prev: Existing Tests, Up: Existing Tests + +5.1 Common Behavior +=================== + +Much effort has been expended to make Autoconf easy to learn. The most +obvious way to reach this goal is simply to enforce standard interfaces +and behaviors, avoiding exceptions as much as possible. Because of +history and inertia, unfortunately, there are still too many exceptions +in Autoconf; nevertheless, this section describes some of the common +rules. + +* Menu: + +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros + + +File: autoconf.info, Node: Standard Symbols, Next: Default Includes, Prev: Common Behavior, Up: Common Behavior + +5.1.1 Standard Symbols +---------------------- + +All the generic macros that 'AC_DEFINE' a symbol as a result of their +test transform their ARGUMENTs to a standard alphabet. First, ARGUMENT +is converted to upper case and any asterisks ('*') are each converted to +'P'. Any remaining characters that are not alphanumeric are converted +to underscores. + + For instance, + + AC_CHECK_TYPES(struct $Expensive*) + +will define the symbol 'HAVE_STRUCT__EXPENSIVEP' if the check succeeds. + + +File: autoconf.info, Node: Default Includes, Prev: Standard Symbols, Up: Common Behavior + +5.1.2 Default Includes +---------------------- + +Several tests depend upon a set of header files. Since these headers +are not universally available, tests actually have to provide a set of +protected includes, such as: + + #if TIME_WITH_SYS_TIME + # include <sys/time.h> + # include <time.h> + #else + # if HAVE_SYS_TIME_H + # include <sys/time.h> + # else + # include <time.h> + # endif + #endif + +Unless you know exactly what you are doing, you should avoid using +unconditional includes, and check the existence of the headers you +include beforehand (*note Header Files::). + + Most generic macros provide the following default set of includes: + + #include <stdio.h> + #if HAVE_SYS_TYPES_H + # include <sys/types.h> + #endif + #if HAVE_SYS_STAT_H + # include <sys/stat.h> + #endif + #if STDC_HEADERS + # include <stdlib.h> + # include <stddef.h> + #else + # if HAVE_STDLIB_H + # include <stdlib.h> + # endif + #endif + #if HAVE_STRING_H + # if !STDC_HEADERS && HAVE_MEMORY_H + # include <memory.h> + # endif + # include <string.h> + #endif + #if HAVE_STRINGS_H + # include <strings.h> + #endif + #if HAVE_INTTYPES_H + # include <inttypes.h> + #else + # if HAVE_STDINT_H + # include <stdint.h> + # endif + #endif + #if HAVE_UNISTD_H + # include <unistd.h> + #endif + + If the default includes are used, then Autoconf will automatically +check for the presence of these headers and their compatibility, i.e., +you don't need to run 'AC_HEADERS_STDC', nor check for 'stdlib.h' etc. + + These headers are checked for in the same order as they are included. +For instance, on some systems 'string.h' and 'strings.h' both exist, but +conflict. Then 'HAVE_STRING_H' will be defined, but 'HAVE_STRINGS_H' +won't. + + +File: autoconf.info, Node: Alternative Programs, Next: Files, Prev: Common Behavior, Up: Existing Tests + +5.2 Alternative Programs +======================== + +These macros check for the presence or behavior of particular programs. +They are used to choose between several alternative programs and to +decide what to do once one has been chosen. If there is no macro +specifically defined to check for a program you need, and you don't need +to check for any special properties of it, then you can use one of the +general program-check macros. + +* Menu: + +* Particular Programs:: Special handling to find certain programs +* Generic Programs:: How to find other programs + + +File: autoconf.info, Node: Particular Programs, Next: Generic Programs, Prev: Alternative Programs, Up: Alternative Programs + +5.2.1 Particular Program Checks +------------------------------- + +These macros check for particular programs--whether they exist, and in +some cases whether they support certain features. + + -- Macro: AC_PROG_AWK + Check for 'mawk', 'gawk', 'nawk', and 'awk', in that order, and set + output variable 'AWK' to the first one that is found. It tries + 'mawk' first because that is reported to be the fastest + implementation. + + -- Macro: AC_PROG_EGREP + Check for 'grep -E', 'egrep' in that order, and set output variable + 'EGREP' to the first one that is found. + + -- Macro: AC_PROG_FGREP + Check for 'grep -F', 'fgrep' in that order, and set output variable + 'FGREP' to the first one that is found. + + -- Macro: AC_PROG_GREP + Check for 'grep', 'ggrep' in that order, and set output variable + 'GREP' to the first one that is found. + + -- Macro: AC_PROG_INSTALL + Set output variable 'INSTALL' to the path of a BSD compatible + 'install' program, if one is found in the current 'PATH'. + Otherwise, set 'INSTALL' to 'DIR/install-sh -c', checking the + directories specified to 'AC_CONFIG_AUX_DIR' (or its default + directories) to determine DIR (*note Output::). Also set the + variables 'INSTALL_PROGRAM' and 'INSTALL_SCRIPT' to '${INSTALL}' + and 'INSTALL_DATA' to '${INSTALL} -m 644'. + + This macro screens out various instances of 'install' known not to + work. It prefers to find a C program rather than a shell script, + for speed. Instead of 'install-sh', it can also use 'install.sh', + but that name is obsolete because some 'make' programs have a rule + that creates 'install' from it if there is no 'Makefile'. + + Autoconf comes with a copy of 'install-sh' that you can use. If + you use 'AC_PROG_INSTALL', you must include either 'install-sh' or + 'install.sh' in your distribution, or 'configure' will produce an + error message saying it can't find them--even if the system you're + on has a good 'install' program. This check is a safety measure to + prevent you from accidentally leaving that file out, which would + prevent your package from installing on systems that don't have a + BSD-compatible 'install' program. + + If you need to use your own installation program because it has + features not found in standard 'install' programs, there is no + reason to use 'AC_PROG_INSTALL'; just put the file name of your + program into your 'Makefile.in' files. + + -- Macro: AC_PROG_LEX + If 'flex' is found, set output variable 'LEX' to 'flex' and + 'LEXLIB' to '-lfl', if that library is in a standard place. + Otherwise set 'LEX' to 'lex' and 'LEXLIB' to '-ll'. + + Define 'YYTEXT_POINTER' if 'yytext' is a 'char *' instead of a + 'char []'. Also set output variable 'LEX_OUTPUT_ROOT' to the base + of the file name that the lexer generates; usually 'lex.yy', but + sometimes something else. These results vary according to whether + 'lex' or 'flex' is being used. + + You are encouraged to use Flex in your sources, since it is both + more pleasant to use than plain Lex and the C source it produces is + portable. In order to ensure portability, however, you must either + provide a function 'yywrap' or, if you don't use it (e.g., your + scanner has no '#include'-like feature), simply include a + '%noyywrap' statement in the scanner's source. Once this done, the + scanner is portable (unless _you_ felt free to use nonportable + constructs) and does not depend on any library. In this case, and + in this case only, it is suggested that you use this Autoconf + snippet: + + AC_PROG_LEX + if test "$LEX" != flex; then + LEX="$SHELL $missing_dir/missing flex" + AC_SUBST(LEX_OUTPUT_ROOT, lex.yy) + AC_SUBST(LEXLIB, '') + fi + + The shell script 'missing' can be found in the Automake + distribution. + + To ensure backward compatibility, Automake's 'AM_PROG_LEX' invokes + (indirectly) this macro twice, which will cause an annoying but + benign "'AC_PROG_LEX' invoked multiple times" warning. Future + versions of Automake will fix this issue, meanwhile, just ignore + this message. + + -- Macro: AC_PROG_LN_S + If 'ln -s' works on the current file system (the operating system + and file system support symbolic links), set the output variable + 'LN_S' to 'ln -s'; otherwise, if 'ln' works, set 'LN_S' to 'ln' and + otherwise set it to 'cp -p'. + + If you make a link a directory other than the current directory, + its meaning depends on whether 'ln' or 'ln -s' is used. To safely + create links using '$(LN_S)', either find out which form is used + and adjust the arguments, or always invoke 'ln' in the directory + where the link is to be created. + + In other words, it does not work to do: + $(LN_S) foo /x/bar + + Instead, do: + + (cd /x && $(LN_S) foo bar) + + -- Macro: AC_PROG_RANLIB + Set output variable 'RANLIB' to 'ranlib' if 'ranlib' is found, and + otherwise to ':' (do nothing). + + -- Macro: AC_PROG_YACC + If 'byacc' is found, set 'YACC' to 'byacc'. Otherwise, if 'bison' + is found, set output variable 'YACC' to 'bison -y'. Finally, if + neither 'byacc' or 'bison' is found, set 'YACC' to 'yacc'. + + +File: autoconf.info, Node: Generic Programs, Prev: Particular Programs, Up: Alternative Programs + +5.2.2 Generic Program and File Checks +------------------------------------- + +These macros are used to find programs not covered by the "particular" +test macros. If you need to check the behavior of a program as well as +find out whether it is present, you have to write your own test for it +(*note Writing Tests::). By default, these macros use the environment +variable 'PATH'. If you need to check for a program that might not be +in the user's 'PATH', you can pass a modified path to use instead, like +this: + + AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd, + $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc) + + You are strongly encouraged to declare the VARIABLE passed to +'AC_CHECK_PROG' etc. as precious, *Note Setting Output Variables::, +'AC_ARG_VAR', for more details. + + -- Macro: AC_CHECK_PROG (VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND, + [VALUE-IF-NOT-FOUND], [PATH], [REJECT]) + Check whether program PROG-TO-CHECK-FOR exists in 'PATH'. If it is + found, set VARIABLE to VALUE-IF-FOUND, otherwise to + VALUE-IF-NOT-FOUND, if given. Always pass over REJECT (an absolute + file name) even if it is the first found in the search path; in + that case, set VARIABLE using the absolute file name of the + PROG-TO-CHECK-FOR found that is not REJECT. If VARIABLE was + already set, do nothing. Calls 'AC_SUBST' for VARIABLE. + + -- Macro: AC_CHECK_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Check for each program in the whitespace-separated list + PROGS-TO-CHECK-FOR exists on the 'PATH'. If it is found, set + VARIABLE to the name of that program. Otherwise, continue checking + the next program in the list. If none of the programs in the list + are found, set VARIABLE to VALUE-IF-NOT-FOUND; if + VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not + changed. Calls 'AC_SUBST' for VARIABLE. + + -- Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a + prefix of the host type as determined by 'AC_CANONICAL_HOST', + followed by a dash (*note Canonicalizing::). For example, if the + user runs 'configure --host=i386-gnu', then this call: + AC_CHECK_TOOL(RANLIB, ranlib, :) + sets 'RANLIB' to 'i386-gnu-ranlib' if that program exists in + 'PATH', or otherwise to 'ranlib' if that program exists in 'PATH', + or to ':' if neither program exists. + + -- Macro: AC_CHECK_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_TOOL', each of the tools in the list + PROGS-TO-CHECK-FOR are checked with a prefix of the host type as + determined by 'AC_CANONICAL_HOST', followed by a dash (*note + Canonicalizing::). If none of the tools can be found with a + prefix, then the first one without a prefix is used. If a tool is + found, set VARIABLE to the name of that program. If none of the + tools in the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if + VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not + changed. Calls 'AC_SUBST' for VARIABLE. + + -- Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_PROG', but set VARIABLE to the entire path of + PROG-TO-CHECK-FOR if found. + + -- Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found, + set VARIABLE to the entire path of the program found. + + -- Macro: AC_PATH_TOOL (VARIABLE, PROG-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_TOOL', but set VARIABLE to the entire path of the + program if it is found. + + +File: autoconf.info, Node: Files, Next: Libraries, Prev: Alternative Programs, Up: Existing Tests + +5.3 Files +========= + +You might also need to check for the existence of files. Before using +these macros, ask yourself whether a run time test might not be a better +solution. Be aware that, like most Autoconf macros, they test a feature +of the host machine, and therefore, they die when cross-compiling. + + -- Macro: AC_CHECK_FILE (FILE, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Check whether file FILE exists on the native system. If it is + found, execute ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, + if given. + + -- Macro: AC_CHECK_FILES (FILES, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Executes 'AC_CHECK_FILE' once for each file listed in FILES. + Additionally, defines 'HAVE_FILE' (*note Standard Symbols::) for + each file found. + + +File: autoconf.info, Node: Libraries, Next: Library Functions, Prev: Files, Up: Existing Tests + +5.4 Library Files +================= + +The following macros check for the presence of certain C, C++ or Fortran +77 library archive files. + + -- Macro: AC_CHECK_LIB (LIBRARY, FUNCTION, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) + Depending on the current language(*note Language Choice::), try to + ensure that the C, C++, or Fortran 77 function FUNCTION is + available by checking whether a test program can be linked with the + library LIBRARY to get the function. LIBRARY is the base name of + the library; e.g., to check for '-lmp', use 'mp' as the LIBRARY + argument. + + ACTION-IF-FOUND is a list of shell commands to run if the link with + the library succeeds; ACTION-IF-NOT-FOUND is a list of shell + commands to run if the link fails. If ACTION-IF-FOUND is not + specified, the default action will prepend '-lLIBRARY' to 'LIBS' + and define 'HAVE_LIBLIBRARY' (in all capitals). This macro is + intended to support building of 'LIBS' in a right-to-left + (least-dependent to most-dependent) fashion such that library + dependencies are satisfied as a natural side-effect of consecutive + tests. Some linkers are very sensitive to library ordering so the + order in which 'LIBS' is generated is important to reliable + detection of libraries. + + If linking with LIBRARY results in unresolved symbols that would be + resolved by linking with additional libraries, give those libraries + as the OTHER-LIBRARIES argument, separated by spaces: e.g. '-lXt + -lX11'. Otherwise, this macro will fail to detect that LIBRARY is + present, because linking the test program will always fail with + unresolved symbols. The OTHER-LIBRARIES argument should be limited + to cases where it is desirable to test for one library in the + presence of another that is not already in 'LIBS'. + + -- Macro: AC_SEARCH_LIBS (FUNCTION, SEARCH-LIBS, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) + Search for a library defining FUNCTION if it's not already + available. This equates to calling 'AC_TRY_LINK_FUNC' first with + no libraries, then for each library listed in SEARCH-LIBS. + + Add '-lLIBRARY' to 'LIBS' for the first library found to contain + FUNCTION, and run ACTION-IF-FOUND. If the function is not found, + run ACTION-IF-NOT-FOUND. + + If linking with LIBRARY results in unresolved symbols that would be + resolved by linking with additional libraries, give those libraries + as the OTHER-LIBRARIES argument, separated by spaces: e.g. '-lXt + -lX11'. Otherwise, this macro will fail to detect that FUNCTION is + present, because linking the test program will always fail with + unresolved symbols. + + +File: autoconf.info, Node: Library Functions, Next: Header Files, Prev: Libraries, Up: Existing Tests + +5.5 Library Functions +===================== + +The following macros check for particular C library functions. If there +is no macro specifically defined to check for a function you need, and +you don't need to check for any special properties of it, then you can +use one of the general function-check macros. + +* Menu: + +* Function Portability:: Pitfalls with usual functions +* Particular Functions:: Special handling to find certain functions +* Generic Functions:: How to find other functions + + +File: autoconf.info, Node: Function Portability, Next: Particular Functions, Prev: Library Functions, Up: Library Functions + +5.5.1 Portability of Classical Functions +---------------------------------------- + +Most usual functions can either be missing, or be buggy, or be limited +on some architectures. This section tries to make an inventory of these +portability issues. By definition, this list will always require +additions, please help us keeping it as complete as possible + +'unlink' + The POSIX spec says that 'unlink' causes the given files to be + removed only after there are no more open file handles for it. Not + all OS's support this behaviour though. So even on systems that + provide 'unlink', you cannot portably assume it is OK to call it on + files that are open. For example, on Windows 9x and ME, such a + call would fail; on DOS it could even lead to file system + corruption, as the file might end up being written to after the OS + has removed it. + + +File: autoconf.info, Node: Particular Functions, Next: Generic Functions, Prev: Function Portability, Up: Library Functions + +5.5.2 Particular Function Checks +-------------------------------- + +These macros check for particular C functions--whether they exist, and +in some cases how they respond when given certain arguments. + + -- Macro: AC_FUNC_ALLOCA + Check how to get 'alloca'. Tries to get a builtin version by + checking for 'alloca.h' or the predefined C preprocessor macros + '__GNUC__' and '_AIX'. If this macro finds 'alloca.h', it defines + 'HAVE_ALLOCA_H'. + + If those attempts fail, it looks for the function in the standard C + library. If any of those methods succeed, it defines + 'HAVE_ALLOCA'. Otherwise, it sets the output variable 'ALLOCA' to + 'alloca.o' and defines 'C_ALLOCA' (so programs can periodically + call 'alloca(0)' to garbage collect). This variable is separate + from 'LIBOBJS' so multiple programs can share the value of 'ALLOCA' + without needing to create an actual library, in case only some of + them use the code in 'LIBOBJS'. + + This macro does not try to get 'alloca' from the System V R3 + 'libPW' or the System V R4 'libucb' because those libraries contain + some incompatible functions that cause trouble. Some versions do + not even contain 'alloca' or contain a buggy version. If you still + want to use their 'alloca', use 'ar' to extract 'alloca.o' from + them instead of compiling 'alloca.c'. + + Source files that use 'alloca' should start with a piece of code + like the following, to declare it properly. In some versions of + AIX, the declaration of 'alloca' must precede everything else + except for comments and preprocessor directives. The '#pragma' + directive is indented so that pre-ANSI C compilers will ignore it, + rather than choke on it. + + /* AIX requires this to be the first thing in the file. */ + #ifndef __GNUC__ + # if HAVE_ALLOCA_H + # include <alloca.h> + # else + # ifdef _AIX + #pragma alloca + # else + # ifndef alloca /* predefined by HP cc +Olibcalls */ + char *alloca (); + # endif + # endif + # endif + #endif + + -- Macro: AC_FUNC_CHOWN + If the 'chown' function is available and works (in particular, it + should accept '-1' for 'uid' and 'gid'), define 'HAVE_CHOWN'. + + -- Macro: AC_FUNC_CLOSEDIR_VOID + If the 'closedir' function does not return a meaningful value, + define 'CLOSEDIR_VOID'. Otherwise, callers ought to check its + return value for an error indicator. + + -- Macro: AC_FUNC_ERROR_AT_LINE + If the 'error_at_line' function is not found, require an + 'AC_LIBOBJ' replacement of 'error'. + + -- Macro: AC_FUNC_FNMATCH + If the 'fnmatch' function is available and works (unlike the one on + Solaris 2.4), define 'HAVE_FNMATCH'. + + -- Macro: AC_FUNC_FORK + This macro checks for the 'fork' and 'vfork' functions. If a + working 'fork' is found, define 'HAVE_WORKING_FORK'. This macro + checks whether 'fork' is just a stub by trying to run it. + + If 'vfork.h' is found, define 'HAVE_VFORK_H'. If a working 'vfork' + is found, define 'HAVE_WORKING_VFORK'. Otherwise, define 'vfork' + to be 'fork' for backward compatibility with previous versions of + 'autoconf'. This macro checks for several known errors in + implementations of 'vfork' and considers the system to not have a + working 'vfork' if it detects any of them. It is not considered to + be an implementation error if a child's invocation of 'signal' + modifies the parent's signal handler, since child processes rarely + change their signal handlers. + + Since this macro defines 'vfork' only for backward compatibility + with previous versions of 'autoconf' you're encouraged to define it + yourself in new code: + #if !HAVE_WORKING_VFORK + # define vfork fork + #endif + + -- Macro: AC_FUNC_FSEEKO + If the 'fseeko' function is available, define 'HAVE_FSEEKO'. + Define '_LARGEFILE_SOURCE' if necessary. + + -- Macro: AC_FUNC_GETGROUPS + If the 'getgroups' function is available and works (unlike on + Ultrix 4.3, where 'getgroups (0, 0)' always fails), define + 'HAVE_GETGROUPS'. Set 'GETGROUPS_LIBS' to any libraries needed to + get that function. This macro runs 'AC_TYPE_GETGROUPS'. + + -- Macro: AC_FUNC_GETLOADAVG + Check how to get the system load averages. If the system has the + 'getloadavg' function, define 'HAVE_GETLOADAVG', and set + 'GETLOADAVG_LIBS' to any libraries needed to get that function. + Also add 'GETLOADAVG_LIBS' to 'LIBS'. + + Otherwise, require an 'AC_LIBOBJ' replacement ('getloadavg.c') of + 'getloadavg', and possibly define several other C preprocessor + macros and output variables: + + 1. Define 'C_GETLOADAVG'. + + 2. Define 'SVR4', 'DGUX', 'UMAX', or 'UMAX4_3' if on those + systems. + + 3. If 'nlist.h' is found, define 'NLIST_STRUCT'. + + 4. If 'struct nlist' has an 'n_un.n_name' member, define + 'HAVE_STRUCT_NLIST_N_UN_N_NAME'. The obsolete symbol + 'NLIST_NAME_UNION' is still defined, but do not depend upon + it. + + 5. Programs may need to be installed setgid (or setuid) for + 'getloadavg' to work. In this case, define + 'GETLOADAVG_PRIVILEGED', set the output variable 'NEED_SETGID' + to 'true' (and otherwise to 'false'), and set 'KMEM_GROUP' to + the name of the group that should own the installed program. + + -- Macro: AC_FUNC_GETMNTENT + Check for 'getmntent' in the 'sun', 'seq', and 'gen' libraries, for + Irix 4, PTX, and Unixware, respectively. Then, if 'getmntent' is + available, define 'HAVE_GETMNTENT'. + + -- Macro: AC_FUNC_GETPGRP + If 'getpgrp' takes no argument (the POSIX.1 version), define + 'GETPGRP_VOID'. Otherwise, it is the BSD version, which takes a + process ID as an argument. This macro does not check whether + 'getpgrp' exists at all; if you need to work in that situation, + first call 'AC_CHECK_FUNC' for 'getpgrp'. + + -- Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK + If 'link' is a symbolic link, then 'lstat' should treat 'link/' the + same as 'link/.'. However, many older 'lstat' implementations + incorrectly ignore trailing slashes. + + It is safe to assume that if 'lstat' incorrectly ignores trailing + slashes, then other symbolic-link-aware functions like 'unlink' and + 'unlink' also incorrectly ignore trailing slashes. + + If 'lstat' behaves properly, define + 'LSTAT_FOLLOWS_SLASHED_SYMLINK', otherwise require an 'AC_LIBOBJ' + replacement of 'lstat'. + + -- Macro: AC_FUNC_MALLOC + If the 'malloc' works correctly ('malloc (0)' returns a valid + pointer), define 'HAVE_MALLOC'. + + -- Macro: AC_FUNC_MEMCMP + If the 'memcmp' function is not available, or does not work on + 8-bit data (like the one on SunOS 4.1.3), or fails when comparing + 16 bytes or more and with at least one buffer not starting on a + 4-byte boundary (such as the one on NeXT x86 OpenStep), require an + 'AC_LIBOBJ' replacement for 'memcmp'. + + -- Macro: AC_FUNC_MKTIME + If the 'mktime' function is not available, or does not work + correctly, require an 'AC_LIBOBJ' replacement for 'mktime'. + + -- Macro: AC_FUNC_MMAP + If the 'mmap' function exists and works correctly, define + 'HAVE_MMAP'. Only checks private fixed mapping of already-mapped + memory. + + -- Macro: AC_FUNC_OBSTACK + If the obstacks are found, define 'HAVE_OBSTACK', else require an + 'AC_LIBOBJ' replacement for 'obstack'. + + -- Macro: AC_FUNC_SELECT_ARGTYPES + Determines the correct type to be passed for each of the 'select' + function's arguments, and defines those types in + 'SELECT_TYPE_ARG1', 'SELECT_TYPE_ARG234', and 'SELECT_TYPE_ARG5' + respectively. 'SELECT_TYPE_ARG1' defaults to 'int', + 'SELECT_TYPE_ARG234' defaults to 'int *', and 'SELECT_TYPE_ARG5' + defaults to 'struct timeval *'. + + -- Macro: AC_FUNC_SETPGRP + If 'setpgrp' takes no argument (the POSIX.1 version), define + 'SETPGRP_VOID'. Otherwise, it is the BSD version, which takes two + process IDs as arguments. This macro does not check whether + 'setpgrp' exists at all; if you need to work in that situation, + first call 'AC_CHECK_FUNC' for 'setpgrp'. + + -- Macro: AC_FUNC_STAT + -- Macro: AC_FUNC_LSTAT + Determine whether 'stat' or 'lstat' have the bug that it succeeds + when given the zero-length file name argument. The 'stat' and + 'lstat' from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do this. + + If it does, then define 'HAVE_STAT_EMPTY_STRING_BUG' (or + 'HAVE_LSTAT_EMPTY_STRING_BUG') and ask for an 'AC_LIBOBJ' + replacement of it. + + -- Macro: AC_FUNC_SETVBUF_REVERSED + If 'setvbuf' takes the buffering type as its second argument and + the buffer pointer as the third, instead of the other way around, + define 'SETVBUF_REVERSED'. + + -- Macro: AC_FUNC_STRCOLL + If the 'strcoll' function exists and works correctly, define + 'HAVE_STRCOLL'. This does a bit more than + 'AC_CHECK_FUNCS(strcoll)', because some systems have incorrect + definitions of 'strcoll' that should not be used. + + -- Macro: AC_FUNC_STRTOD + If the 'strtod' function does not exist or doesn't work correctly, + ask for an 'AC_LIBOBJ' replacement of 'strtod'. In this case, + because 'strtod.c' is likely to need 'pow', set the output variable + 'POW_LIB' to the extra library needed. + + -- Macro: AC_FUNC_STRERROR_R + If 'strerror_r' is available, define 'HAVE_STRERROR_R'. If its + implementation correctly returns a 'char *', define + 'HAVE_WORKING_STRERROR_R'. On at least DEC UNIX 4.0[A-D] and HP-UX + B.10.20, 'strerror_r' returns 'int'. Actually, this tests only + whether it returns a scalar or an array, but that should be enough. + This is used by the common 'error.c'. + + -- Macro: AC_FUNC_STRFTIME + Check for 'strftime' in the 'intl' library, for SCO UNIX. Then, if + 'strftime' is available, define 'HAVE_STRFTIME'. + + -- Macro: AC_FUNC_UTIME_NULL + If 'utime(FILE, NULL)' sets FILE's timestamp to the present, define + 'HAVE_UTIME_NULL'. + + -- Macro: AC_FUNC_VPRINTF + If 'vprintf' is found, define 'HAVE_VPRINTF'. Otherwise, if + '_doprnt' is found, define 'HAVE_DOPRNT'. (If 'vprintf' is + available, you may assume that 'vfprintf' and 'vsprintf' are also + available.) + + +File: autoconf.info, Node: Generic Functions, Prev: Particular Functions, Up: Library Functions + +5.5.3 Generic Function Checks +----------------------------- + +These macros are used to find functions not covered by the "particular" +test macros. If the functions might be in libraries other than the +default C library, first call 'AC_CHECK_LIB' for those libraries. If +you need to check the behavior of a function as well as find out whether +it is present, you have to write your own test for it (*note Writing +Tests::). + + -- Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + If C function FUNCTION is available, run shell commands + ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND. If you just want + to define a symbol if the function is available, consider using + 'AC_CHECK_FUNCS' instead. This macro checks for functions with C + linkage even when 'AC_LANG(C++)' has been called, since C is more + standardized than C++. (*note Language Choice::, for more + information about selecting the language for checks.) + + -- Macro: AC_CHECK_FUNCS (FUNCTION..., [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + For each FUNCTION in the whitespace-separated argument list, define + 'HAVE_FUNCTION' (in all capitals) if it is available. If + ACTION-IF-FOUND is given, it is additional shell code to execute + when one of the functions is found. You can give it a value of + 'break' to break out of the loop on the first match. If + ACTION-IF-NOT-FOUND is given, it is executed when one of the + functions is not found. + + Autoconf follows a philosophy that was formed over the years by those +who have struggled for portability: isolate the portability issues in +specific files, and then program as if you were in a POSIX environment. +Some functions may be missing or unfixable, and your package must be +ready to replace them. + + Use the first three of the following macros to specify a function to +be replaced, and the last one ('AC_REPLACE_FUNCS') to check for and +replace the function if needed. + + -- Macro: AC_LIBOBJ (FUNCTION) + Specify that 'FUNCTION.c' must be included in the executables to + replace a missing or broken implementation of FUNCTION. + + Technically, it adds 'FUNCTION.$ac_objext' to the output variable + 'LIBOBJS' and calls 'AC_LIBSOURCE' for 'FUNCTION.c'. You should + not directly change 'LIBOBJS', since this is not traceable. + + -- Macro: AC_LIBSOURCE (FILE) + Specify that FILE might be needed to compile the project. If you + need to know what files might be needed by a 'configure.ac', you + should trace 'AC_LIBSOURCE'. FILE must be a literal. + + This macro is called automatically from 'AC_LIBOBJ', but you must + call it explicitly if you pass a shell variable to 'AC_LIBOBJ'. In + that case, since shell variables cannot be traced statically, you + must pass to 'AC_LIBSOURCE' any possible files that the shell + variable might cause 'AC_LIBOBJ' to need. For example, if you want + to pass a variable '$foo_or_bar' to 'AC_LIBOBJ' that holds either + '"foo"' or '"bar"', you should do: + + AC_LIBSOURCE(foo.c) + AC_LIBSOURCE(bar.c) + AC_LIBOBJ($foo_or_bar) + + There is usually a way to avoid this, however, and you are + encouraged to simply call 'AC_LIBOBJ' with literal arguments. + + Note that this macro replaces the obsolete 'AC_LIBOBJ_DECL', with + slightly different semantics: the old macro took the function name, + e.g. 'foo', as its argument rather than the file name. + + -- Macro: AC_LIBSOURCES (FILES) + Like 'AC_LIBSOURCE', but accepts one or more FILES in a + comma-separated M4 list. Thus, the above example might be + rewritten: + + AC_LIBSOURCES([foo.c, bar.c]) + AC_LIBOBJ($foo_or_bar) + + -- Macro: AC_REPLACE_FUNCS (FUNCTION...) + Like 'AC_CHECK_FUNCS', but uses 'AC_LIBOBJ(FUNCTION)' as + ACTION-IF-NOT-FOUND. You can declare your replacement function by + enclosing the prototype in '#if !HAVE_FUNCTION'. If the system has + the function, it probably declares it in a header file you should + be including, so you shouldn't redeclare it lest your declaration + conflict. + + +File: autoconf.info, Node: Header Files, Next: Declarations, Prev: Library Functions, Up: Existing Tests + +5.6 Header Files +================ + +The following macros check for the presence of certain C header files. +If there is no macro specifically defined to check for a header file you +need, and you don't need to check for any special properties of it, then +you can use one of the general header-file check macros. + +* Menu: + +* Particular Headers:: Special handling to find certain headers +* Generic Headers:: How to find other headers + + +File: autoconf.info, Node: Particular Headers, Next: Generic Headers, Prev: Header Files, Up: Header Files + +5.6.1 Particular Header Checks +------------------------------ + +These macros check for particular system header files--whether they +exist, and in some cases whether they declare certain symbols. + + -- Macro: AC_HEADER_DIRENT + Check for the following header files. For the first one that is + found and defines 'DIR', define the listed C preprocessor macro: + + 'dirent.h' 'HAVE_DIRENT_H' + 'sys/ndir.h' 'HAVE_SYS_NDIR_H' + 'sys/dir.h' 'HAVE_SYS_DIR_H' + 'ndir.h' 'HAVE_NDIR_H' + + The directory-library declarations in your source code should look + something like the following: + + #if HAVE_DIRENT_H + # include <dirent.h> + # define NAMLEN(dirent) strlen((dirent)->d_name) + #else + # define dirent direct + # define NAMLEN(dirent) (dirent)->d_namlen + # if HAVE_SYS_NDIR_H + # include <sys/ndir.h> + # endif + # if HAVE_SYS_DIR_H + # include <sys/dir.h> + # endif + # if HAVE_NDIR_H + # include <ndir.h> + # endif + #endif + + Using the above declarations, the program would declare variables + to be of type 'struct dirent', not 'struct direct', and would + access the length of a directory entry name by passing a pointer to + a 'struct dirent' to the 'NAMLEN' macro. + + This macro also checks for the SCO Xenix 'dir' and 'x' libraries. + + -- Macro: AC_HEADER_MAJOR + If 'sys/types.h' does not define 'major', 'minor', and 'makedev', + but 'sys/mkdev.h' does, define 'MAJOR_IN_MKDEV'; otherwise, if + 'sys/sysmacros.h' does, define 'MAJOR_IN_SYSMACROS'. + + -- Macro: AC_HEADER_STAT + If the macros 'S_ISDIR', 'S_ISREG' et al. defined in 'sys/stat.h' + do not work properly (returning false positives), define + 'STAT_MACROS_BROKEN'. This is the case on Tektronix UTekV, Amdahl + UTS and Motorola System V/88. + + -- Macro: AC_HEADER_STDC + Define 'STDC_HEADERS' if the system has ANSI C header files. + Specifically, this macro checks for 'stdlib.h', 'stdarg.h', + 'string.h', and 'float.h'; if the system has those, it probably has + the rest of the ANSI C header files. This macro also checks + whether 'string.h' declares 'memchr' (and thus presumably the other + 'mem' functions), whether 'stdlib.h' declare 'free' (and thus + presumably 'malloc' and other related functions), and whether the + 'ctype.h' macros work on characters with the high bit set, as ANSI + C requires. + + Use 'STDC_HEADERS' instead of '__STDC__' to determine whether the + system has ANSI-compliant header files (and probably C library + functions) because many systems that have GCC do not have ANSI C + header files. + + On systems without ANSI C headers, there is so much variation that + it is probably easier to declare the functions you use than to + figure out exactly what the system header files declare. Some + systems contain a mix of functions ANSI and BSD; some are mostly + ANSI but lack 'memmove'; some define the BSD functions as macros in + 'string.h' or 'strings.h'; some have only the BSD functions but + 'string.h'; some declare the memory functions in 'memory.h', some + in 'string.h'; etc. It is probably sufficient to check for one + string function and one memory function; if the library has the + ANSI versions of those then it probably has most of the others. If + you put the following in 'configure.ac': + + AC_HEADER_STDC + AC_CHECK_FUNCS(strchr memcpy) + + then, in your code, you can put declarations like this: + + #if STDC_HEADERS + # include <string.h> + #else + # if !HAVE_STRCHR + # define strchr index + # define strrchr rindex + # endif + char *strchr (), *strrchr (); + # if !HAVE_MEMCPY + # define memcpy(d, s, n) bcopy ((s), (d), (n)) + # define memmove(d, s, n) bcopy ((s), (d), (n)) + # endif + #endif + + If you use a function like 'memchr', 'memset', 'strtok', or + 'strspn', which have no BSD equivalent, then macros won't suffice; + you must provide an implementation of each function. An easy way + to incorporate your implementations only when needed (since the + ones in system C libraries may be hand optimized) is to, taking + 'memchr' for example, put it in 'memchr.c' and use + 'AC_REPLACE_FUNCS(memchr)'. + + -- Macro: AC_HEADER_SYS_WAIT + If 'sys/wait.h' exists and is compatible with POSIX.1, define + 'HAVE_SYS_WAIT_H'. Incompatibility can occur if 'sys/wait.h' does + not exist, or if it uses the old BSD 'union wait' instead of 'int' + to store a status value. If 'sys/wait.h' is not POSIX.1 + compatible, then instead of including it, define the POSIX.1 macros + with their usual interpretations. Here is an example: + + #include <sys/types.h> + #if HAVE_SYS_WAIT_H + # include <sys/wait.h> + #endif + #ifndef WEXITSTATUS + # define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8) + #endif + #ifndef WIFEXITED + # define WIFEXITED(stat_val) (((stat_val) & 255) == 0) + #endif + + '_POSIX_VERSION' is defined when 'unistd.h' is included on POSIX.1 +systems. If there is no 'unistd.h', it is definitely not a POSIX.1 +system. However, some non-POSIX.1 systems do have 'unistd.h'. + + The way to check if the system supports POSIX.1 is: + + #if HAVE_UNISTD_H + # include <sys/types.h> + # include <unistd.h> + #endif + + #ifdef _POSIX_VERSION + /* Code for POSIX.1 systems. */ + #endif + + -- Macro: AC_HEADER_TIME + If a program may include both 'time.h' and 'sys/time.h', define + 'TIME_WITH_SYS_TIME'. On some older systems, 'sys/time.h' includes + 'time.h', but 'time.h' is not protected against multiple inclusion, + so programs should not explicitly include both files. This macro + is useful in programs that use, for example, 'struct timeval' or + 'struct timezone' as well as 'struct tm'. It is best used in + conjunction with 'HAVE_SYS_TIME_H', which can be checked for using + 'AC_CHECK_HEADERS(sys/time.h)'. + + #if TIME_WITH_SYS_TIME + # include <sys/time.h> + # include <time.h> + #else + # if HAVE_SYS_TIME_H + # include <sys/time.h> + # else + # include <time.h> + # endif + #endif + + -- Macro: AC_HEADER_TIOCGWINSZ + If the use of 'TIOCGWINSZ' requires '<sys/ioctl.h>', then define + 'GWINSZ_IN_SYS_IOCTL'. Otherwise 'TIOCGWINSZ' can be found in + '<termios.h>'. + + Use: + + #if HAVE_TERMIOS_H + # include <termios.h> + #endif + + #if GWINSZ_IN_SYS_IOCTL + # include <sys/ioctl.h> + #endif + + +File: autoconf.info, Node: Generic Headers, Prev: Particular Headers, Up: Header Files + +5.6.2 Generic Header Checks +--------------------------- + +These macros are used to find system header files not covered by the +"particular" test macros. If you need to check the contents of a header +as well as find out whether it is present, you have to write your own +test for it (*note Writing Tests::). + + -- Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + If the system header file HEADER-FILE is usable, execute shell + commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. + If you just want to define a symbol if the header file is + available, consider using 'AC_CHECK_HEADERS' instead. + + The meaning of "usable" depends upon the content of INCLUDES: + + if INCLUDES is empty + check whether + + HEADER-FILE + + can be _preprocessed_ without error. + + if INCLUDE is set + Check whether + + INCLUDES + #include <HEADER-FILE> + + can be _compiled_ without error. You may use + 'AC_CHECK_HEADER' (and 'AC_CHECK_HEADERS') to check whether + two headers are compatible. + + You may pass any kind of dummy content for INCLUDES, such as a + single space, a comment, to check whether HEADER-FILE compiles with + success. + + -- Macro: AC_CHECK_HEADERS (HEADER-FILE..., [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + For each given system header file HEADER-FILE in the + whitespace-separated argument list that exists, define + 'HAVE_HEADER-FILE' (in all capitals). If ACTION-IF-FOUND is given, + it is additional shell code to execute when one of the header files + is found. You can give it a value of 'break' to break out of the + loop on the first match. If ACTION-IF-NOT-FOUND is given, it is + executed when one of the header files is not found. + + Be sure to read the documentation of 'AC_CHECK_HEADER' to + understand the influence of INCLUDES. + + +File: autoconf.info, Node: Declarations, Next: Structures, Prev: Header Files, Up: Existing Tests + +5.7 Declarations +================ + +The following macros check for the declaration of variables and +functions. If there is no macro specifically defined to check for a +symbol you need, then you can use the general macros (*note Generic +Declarations::) or, for more complex tests, you may use 'AC_TRY_COMPILE' +(*note Examining Syntax::). + +* Menu: + +* Particular Declarations:: Macros to check for certain declarations +* Generic Declarations:: How to find other declarations + + +File: autoconf.info, Node: Particular Declarations, Next: Generic Declarations, Prev: Declarations, Up: Declarations + +5.7.1 Particular Declaration Checks +----------------------------------- + +The following macros check for certain declarations. + + -- Macro: AC_DECL_SYS_SIGLIST + Define 'SYS_SIGLIST_DECLARED' if the variable 'sys_siglist' is + declared in a system header file, either 'signal.h' or 'unistd.h'. + + +File: autoconf.info, Node: Generic Declarations, Prev: Particular Declarations, Up: Declarations + +5.7.2 Generic Declaration Checks +-------------------------------- + +These macros are used to find declarations not covered by the +"particular" test macros. + + -- Macro: AC_CHECK_DECL (SYMBOL, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + If SYMBOL (a function or a variable) is not declared in INCLUDES + and a declaration is needed, run the shell commands + ACTION-IF-NOT-FOUND, otherwise ACTION-IF-FOUND. If no INCLUDES are + specified, the default includes are used (*note Default + Includes::). + + This macro actually tests whether it is valid to use SYMBOL as an + r-value, not if it is really declared, because it is much safer to + avoid introducing extra declarations when they are not needed. + + -- Macro: AC_CHECK_DECLS (SYMBOLS, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + For each of the SYMBOLS (_comma_-separated list), define + 'HAVE_DECL_SYMBOL' (in all capitals) to '1' if SYMBOL is declared, + otherwise to '0'. If ACTION-IF-NOT-FOUND is given, it is + additional shell code to execute when one of the function + declarations is needed, otherwise ACTION-IF-FOUND is executed. + + This macro uses an m4 list as first argument: + AC_CHECK_DECLS(strdup) + AC_CHECK_DECLS([strlen]) + AC_CHECK_DECLS([malloc, realloc, calloc, free]) + + Unlike the other 'AC_CHECK_*S' macros, when a SYMBOL is not + declared, 'HAVE_DECL_SYMBOL' is defined to '0' instead of leaving + 'HAVE_DECL_SYMBOL' undeclared. When you are _sure_ that the check + was performed, use 'HAVE_DECL_SYMBOL' just like any other result of + Autoconf: + + #if !HAVE_DECL_SYMBOL + extern char *symbol; + #endif + + If the test may have not been performed, however, because it is + safer _not_ to declare a symbol than to use a declaration that + conflicts with the system's one, you should use: + + #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC + char *malloc (size_t *s); + #endif + + You fall into the second category only in extreme situations: + either your files may be used without being configured, or they are + used during the configuration. In most cases the traditional + approach is enough. + + +File: autoconf.info, Node: Structures, Next: Types, Prev: Declarations, Up: Existing Tests + +5.8 Structures +============== + +The following macros check for the presence of certain members in C +structures. If there is no macro specifically defined to check for a +member you need, then you can use the general structure-member macro +(*note Generic Structures::) or, for more complex tests, you may use +'AC_TRY_COMPILE' (*note Examining Syntax::). + +* Menu: + +* Particular Structures:: Macros to check for certain structure members +* Generic Structures:: How to find other structure members + + +File: autoconf.info, Node: Particular Structures, Next: Generic Structures, Prev: Structures, Up: Structures + +5.8.1 Particular Structure Checks +--------------------------------- + +The following macros check for certain structures or structure members. + + -- Macro: AC_STRUCT_ST_BLKSIZE + If 'struct stat' contains an 'st_blksize' member, define + 'HAVE_STRUCT_STAT_ST_BLKSIZE'. The former name, 'HAVE_ST_BLKSIZE' + is to be avoided, as its support will cease in the future. This + macro is obsoleted, and should be replaced by + + AC_CHECK_MEMBERS([struct stat.st_blksize]) + + -- Macro: AC_STRUCT_ST_BLOCKS + If 'struct stat' contains an 'st_blocks' member, define + 'HAVE_STRUCT STAT_ST_BLOCKS'. Otherwise, require an 'AC_LIBOBJ' + replacement of 'fileblocks'. The former name, 'HAVE_ST_BLOCKS' is + to be avoided, as its support will cease in the future. + + -- Macro: AC_STRUCT_ST_RDEV + If 'struct stat' contains an 'st_rdev' member, define + 'HAVE_STRUCT_STAT_ST_RDEV'. The former name for this macro, + 'HAVE_ST_RDEV', is to be avoided as it will cease to be supported + in the future. Actually, even the new macro is obsolete, and + should be replaced by: + AC_CHECK_MEMBERS([struct stat.st_rdev]) + + -- Macro: AC_STRUCT_TM + If 'time.h' does not define 'struct tm', define 'TM_IN_SYS_TIME', + which means that including 'sys/time.h' had better define 'struct + tm'. + + -- Macro: AC_STRUCT_TIMEZONE + Figure out how to get the current timezone. If 'struct tm' has a + 'tm_zone' member, define 'HAVE_STRUCT_TM_TM_ZONE' (and the + obsoleted 'HAVE_TM_ZONE'). Otherwise, if the external array + 'tzname' is found, define 'HAVE_TZNAME'. + + +File: autoconf.info, Node: Generic Structures, Prev: Particular Structures, Up: Structures + +5.8.2 Generic Structure Checks +------------------------------ + +These macros are used to find structure members not covered by the +"particular" test macros. + + -- Macro: AC_CHECK_MEMBER (AGGREGATE.MEMBER, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + Check whether MEMBER is a member of the aggregate AGGREGATE. If no + INCLUDES are specified, the default includes are used (*note + Default Includes::). + + AC_CHECK_MEMBER(struct passwd.pw_gecos,, + [AC_MSG_ERROR([We need `passwd.pw_gecos'!])], + [#include <pwd.h>]) + + You can use this macro for sub-members: + + AC_CHECK_MEMBER(struct top.middle.bot) + + -- Macro: AC_CHECK_MEMBERS (MEMBERS, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + Check for the existence of each 'AGGREGATE.MEMBER' of MEMBERS using + the previous macro. When MEMBER belongs to AGGREGATE, define + 'HAVE_AGGREGATE_MEMBER' (in all capitals, with spaces and dots + replaced by underscores). + + This macro uses m4 lists: + AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) + + +File: autoconf.info, Node: Types, Next: Compilers and Preprocessors, Prev: Structures, Up: Existing Tests + +5.9 Types +========= + +The following macros check for C types, either builtin or typedefs. If +there is no macro specifically defined to check for a type you need, and +you don't need to check for any special properties of it, then you can +use a general type-check macro. + +* Menu: + +* Particular Types:: Special handling to find certain types +* Generic Types:: How to find other types + + +File: autoconf.info, Node: Particular Types, Next: Generic Types, Prev: Types, Up: Types + +5.9.1 Particular Type Checks +---------------------------- + +These macros check for particular C types in 'sys/types.h', 'stdlib.h' +and others, if they exist. + + -- Macro: AC_TYPE_GETGROUPS + Define 'GETGROUPS_T' to be whichever of 'gid_t' or 'int' is the + base type of the array argument to 'getgroups'. + + -- Macro: AC_TYPE_MODE_T + Equivalent to 'AC_CHECK_TYPE(mode_t, int)'. + + -- Macro: AC_TYPE_OFF_T + Equivalent to 'AC_CHECK_TYPE(off_t, long)'. + + -- Macro: AC_TYPE_PID_T + Equivalent to 'AC_CHECK_TYPE(pid_t, int)'. + + -- Macro: AC_TYPE_SIGNAL + If 'signal.h' declares 'signal' as returning a pointer to a + function returning 'void', define 'RETSIGTYPE' to be 'void'; + otherwise, define it to be 'int'. + + Define signal handlers as returning type 'RETSIGTYPE': + + RETSIGTYPE + hup_handler () + { + ... + } + + -- Macro: AC_TYPE_SIZE_T + Equivalent to 'AC_CHECK_TYPE(size_t, unsigned)'. + + -- Macro: AC_TYPE_UID_T + If 'uid_t' is not defined, define 'uid_t' to be 'int' and 'gid_t' + to be 'int'. + + +File: autoconf.info, Node: Generic Types, Prev: Particular Types, Up: Types + +5.9.2 Generic Type Checks +------------------------- + +These macros are used to check for types not covered by the "particular" +test macros. + + -- Macro: AC_CHECK_TYPE (TYPE, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + Check whether TYPE is defined. It may be a compiler builtin type + or defined by the [INCLUDES] (*note Default Includes::). + + -- Macro: AC_CHECK_TYPES (TYPES, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + For each TYPE of the TYPES that is defined, define 'HAVE_TYPE' (in + all capitals). If no INCLUDES are specified, the default includes + are used (*note Default Includes::). If ACTION-IF-FOUND is given, + it is additional shell code to execute when one of the types is + found. If ACTION-IF-NOT-FOUND is given, it is executed when one of + the types is not found. + + This macro uses m4 lists: + AC_CHECK_TYPES(ptrdiff_t) + AC_CHECK_TYPES([unsigned long long, uintmax_t]) + + Autoconf, up to 2.13, used to provide to another version of +'AC_CHECK_TYPE', broken by design. In order to keep backward +compatibility, a simple heuristics, quite safe but not totally, is +implemented. In case of doubt, read the documentation of the former +'AC_CHECK_TYPE', see *note Obsolete Macros::. + + +File: autoconf.info, Node: Compilers and Preprocessors, Next: System Services, Prev: Types, Up: Existing Tests + +5.10 Compilers and Preprocessors +================================ + +All the tests for compilers ('AC_PROG_CC', 'AC_PROG_CXX', 'AC_PROG_F77') +define the output variable 'EXEEXT' based on the output of the compiler, +typically to the empty string if Unix and '.exe' if Win32 or OS/2. + + They also define the output variable 'OBJEXT' based on the output of +the compiler, after .c files have been excluded, typically to 'o' if +Unix, 'obj' if Win32. + + If the compiler being used does not produce executables, they fail. +If the executables can't be run, and cross-compilation is not enabled, +they fail too. *Note Manual Configuration::, for more on support for +cross compiling. + +* Menu: + +* Generic Compiler Characteristics:: Language independent tests +* C Compiler:: Checking its characteristics +* C++ Compiler:: Likewise +* Fortran 77 Compiler:: Likewise + + +File: autoconf.info, Node: Generic Compiler Characteristics, Next: C Compiler, Prev: Compilers and Preprocessors, Up: Compilers and Preprocessors + +5.10.1 Generic Compiler Characteristics +--------------------------------------- + + -- Macro: AC_CHECK_SIZEOF (TYPE, [UNUSED], [INCLUDES]) + Define 'SIZEOF_TYPE' (*note Standard Symbols::) to be the size in + bytes of TYPE. If 'type' is unknown, it gets a size of 0. If no + INCLUDES are specified, the default includes are used (*note + Default Includes::). If you provide INCLUDE, make sure to include + 'stdio.h' which is required for this macro to run. + + This macro now works even when cross-compiling. The UNUSED + argument was used when cross-compiling. + + For example, the call + + AC_CHECK_SIZEOF(int *) + + defines 'SIZEOF_INT_P' to be 8 on DEC Alpha AXP systems. + + +File: autoconf.info, Node: C Compiler, Next: C++ Compiler, Prev: Generic Compiler Characteristics, Up: Compilers and Preprocessors + +5.10.2 C Compiler Characteristics +--------------------------------- + + -- Macro: AC_PROG_CC ([COMPILER-SEARCH-LIST]) + Determine a C compiler to use. If 'CC' is not already set in the + environment, check for 'gcc' and 'cc', then for other C compilers. + Set output variable 'CC' to the name of the compiler found. + + This macro may, however, be invoked with an optional first argument + which, if specified, must be a space separated list of C compilers + to search for. This just gives the user an opportunity to specify + an alternative search list for the C compiler. For example, if you + didn't like the default order, then you could invoke 'AC_PROG_CC' + like this: + + AC_PROG_CC(cl egcs gcc cc) + + If using the GNU C compiler, set shell variable 'GCC' to 'yes'. If + output variable 'CFLAGS' was not already set, set it to '-g -O2' + for the GNU C compiler ('-O2' on systems where GCC does not accept + '-g'), or '-g' for other compilers. + + -- Macro: AC_PROG_CC_C_O + If the C compiler does not accept the '-c' and '-o' options + simultaneously, define 'NO_MINUS_C_MINUS_O'. This macro actually + tests both the compiler found by 'AC_PROG_CC', and, if different, + the first 'cc' in the path. The test fails if one fails. This + macro was created for GNU Make to choose the default C compilation + rule. + + -- Macro: AC_PROG_CC_STDC + If the C compiler is not in ANSI C mode by default, try to add an + option to output variable 'CC' to make it so. This macro tries + various options that select ANSI C on some system or another. It + considers the compiler to be in ANSI C mode if it handles function + prototypes correctly. + + If you use this macro, you should check after calling it whether + the C compiler has been set to accept ANSI C; if not, the shell + variable 'ac_cv_prog_cc_stdc' is set to 'no'. If you wrote your + source code in ANSI C, you can make an un-ANSIfied copy of it by + using the program 'ansi2knr', which comes with Automake. + + -- Macro: AC_PROG_CPP + Set output variable 'CPP' to a command that runs the C + preprocessor. If '$CC -E' doesn't work, '/lib/cpp' is used. It is + only portable to run 'CPP' on files with a '.c' extension. + + If the current language is C (*note Language Choice::), many of the + specific test macros use the value of 'CPP' indirectly by calling + 'AC_TRY_CPP', 'AC_CHECK_HEADER', 'AC_EGREP_HEADER', or + 'AC_EGREP_CPP'. + + Some preprocessors don't indicate missing include files by the + error status. For such preprocessors an internal variable is set + that causes other macros to check the standard error from the + preprocessor and consider the test failed if any warnings have been + reported. + + The following macros check for C compiler or machine architecture +features. To check for characteristics not listed here, use +'AC_TRY_COMPILE' (*note Examining Syntax::) or 'AC_TRY_RUN' (*note Run +Time::) + + -- Macro: AC_C_BIGENDIAN + If words are stored with the most significant byte first (like + Motorola and SPARC, but not Intel and VAX, CPUs), define + 'WORDS_BIGENDIAN'. + + -- Macro: AC_C_CONST + If the C compiler does not fully support the ANSI C qualifier + 'const', define 'const' to be empty. Some C compilers that do not + define '__STDC__' do support 'const'; some compilers that define + '__STDC__' do not completely support 'const'. Programs can simply + use 'const' as if every C compiler supported it; for those that + don't, the 'Makefile' or configuration header file will define it + as empty. + + Occasionally installers use a C++ compiler to compile C code, + typically because they lack a C compiler. This causes problems + with 'const', because C and C++ treat 'const' differently. For + example: + + const int foo; + + is valid in C but not in C++. These differences unfortunately + cannot be papered over by defining 'const' to be empty. + + If 'autoconf' detects this situation, it leaves 'const' alone, as + this generally yields better results in practice. However, using a + C++ compiler to compile C code is not recommended or supported, and + installers who run into trouble in this area should get a C + compiler like GCC to compile their C code. + + -- Macro: AC_C_VOLATILE + If the C compiler does not understand the keyword 'volatile', + define 'volatile' to be empty. Programs can simply use 'volatile' + as if every C compiler supported it; for those that do not, the + 'Makefile' or configuration header will define it as empty. + + If the correctness of your program depends on the semantics of + 'volatile', simply defining it to be empty does, in a sense, break + your code. However, given that the compiler does not support + 'volatile', you are at its mercy anyway. At least your program + will compile, when it wouldn't before. + + In general, the 'volatile' keyword is a feature of ANSI C, so you + might expect that 'volatile' is available only when '__STDC__' is + defined. However, Ultrix 4.3's native compiler does support + volatile, but does not defined '__STDC__'. + + -- Macro: AC_C_INLINE + If the C compiler supports the keyword 'inline', do nothing. + Otherwise define 'inline' to '__inline__' or '__inline' if it + accepts one of those, otherwise define 'inline' to be empty. + + -- Macro: AC_C_CHAR_UNSIGNED + If the C type 'char' is unsigned, define '__CHAR_UNSIGNED__', + unless the C compiler predefines it. + + -- Macro: AC_C_LONG_DOUBLE + If the C compiler supports the 'long double' type, define + 'HAVE_LONG_DOUBLE'. Some C compilers that do not define '__STDC__' + do support the 'long double' type; some compilers that define + '__STDC__' do not support 'long double'. + + -- Macro: AC_C_STRINGIZE + If the C preprocessor supports the stringizing operator, define + 'HAVE_STRINGIZE'. The stringizing operator is '#' and is found in + macros such as this: + + #define x(y) #y + + -- Macro: AC_C_PROTOTYPES + Check to see if function prototypes are understood by the compiler. + If so, define 'PROTOTYPES'. In the case the compiler does not + handle prototypes, you should use 'ansi2knr', which comes with the + Automake distribution, to unprotoize function definitions. For + function prototypes, you should first define 'PARAMS': + + #ifndef PARAMS + # if PROTOTYPES + # define PARAMS(protos) protos + # else /* no PROTOTYPES */ + # define PARAMS(protos) () + # endif /* no PROTOTYPES */ + #endif + + then use it this way: + + size_t my_strlen PARAMS ((const char *)); + + -- Macro: AC_PROG_GCC_TRADITIONAL + Add '-traditional' to output variable 'CC' if using the GNU C + compiler and 'ioctl' does not work properly without '-traditional'. + That usually happens when the fixed header files have not been + installed on an old system. Since recent versions of the GNU C + compiler fix the header files automatically when installed, this is + becoming a less prevalent problem. + + +File: autoconf.info, Node: C++ Compiler, Next: Fortran 77 Compiler, Prev: C Compiler, Up: Compilers and Preprocessors + +5.10.3 C++ Compiler Characteristics +----------------------------------- + + -- Macro: AC_PROG_CXX ([COMPILER-SEARCH-LIST]) + Determine a C++ compiler to use. Check if the environment variable + 'CXX' or 'CCC' (in that order) is set; if so, then set output + variable 'CXX' to its value. + + Otherwise, if the macro is invoked without an argument, then search + for a C++ compiler under the likely names (first 'g++' and 'c++' + then other names). If none of those checks succeed, then as a last + resort set 'CXX' to 'g++'. + + This macro may, however, be invoked with an optional first argument + which, if specified, must be a space separated list of C++ + compilers to search for. This just gives the user an opportunity + to specify an alternative search list for the C++ compiler. For + example, if you didn't like the default order, then you could + invoke 'AC_PROG_CXX' like this: + + AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc) + + If using the GNU C++ compiler, set shell variable 'GXX' to 'yes'. + If output variable 'CXXFLAGS' was not already set, set it to '-g + -O2' for the GNU C++ compiler ('-O2' on systems where G++ does not + accept '-g'), or '-g' for other compilers. + + -- Macro: AC_PROG_CXXCPP + Set output variable 'CXXCPP' to a command that runs the C++ + preprocessor. If '$CXX -E' doesn't work, '/lib/cpp' is used. It + is only portable to run 'CXXCPP' on files with a '.c', '.C', or + '.cc' extension. + + If the current language is C++ (*note Language Choice::), many of + the specific test macros use the value of 'CXXCPP' indirectly by + calling 'AC_TRY_CPP', 'AC_CHECK_HEADER', 'AC_EGREP_HEADER', or + 'AC_EGREP_CPP'. + + Some preprocessors don't indicate missing include files by the + error status. For such preprocessors an internal variable is set + that causes other macros to check the standard error from the + preprocessor and consider the test failed if any warnings have been + reported. However, it is not known whether such broken + preprocessors exist for C++. + + +File: autoconf.info, Node: Fortran 77 Compiler, Prev: C++ Compiler, Up: Compilers and Preprocessors + +5.10.4 Fortran 77 Compiler Characteristics +------------------------------------------ + + -- Macro: AC_PROG_F77 ([COMPILER-SEARCH-LIST]) + Determine a Fortran 77 compiler to use. If 'F77' is not already + set in the environment, then check for 'g77' and 'f77', and then + some other names. Set the output variable 'F77' to the name of the + compiler found. + + This macro may, however, be invoked with an optional first argument + which, if specified, must be a space separated list of Fortran 77 + compilers to search for. This just gives the user an opportunity + to specify an alternative search list for the Fortran 77 compiler. + For example, if you didn't like the default order, then you could + invoke 'AC_PROG_F77' like this: + + AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90) + + If using 'g77' (the GNU Fortran 77 compiler), then 'AC_PROG_F77' + will set the shell variable 'G77' to 'yes'. If the output variable + 'FFLAGS' was not already set in the environment, then set it to '-g + -02' for 'g77' (or '-O2' where 'g77' does not accept '-g'). + Otherwise, set 'FFLAGS' to '-g' for all other Fortran 77 compilers. + + -- Macro: AC_PROG_F77_C_O + Test if the Fortran 77 compiler accepts the options '-c' and '-o' + simultaneously, and define 'F77_NO_MINUS_C_MINUS_O' if it does not. + + The following macros check for Fortran 77 compiler characteristics. +To check for characteristics not listed here, use 'AC_TRY_COMPILE' +(*note Examining Syntax::) or 'AC_TRY_RUN' (*note Run Time::), making +sure to first set the current language to Fortran 77 'AC_LANG(Fortran +77)' (*note Language Choice::). + + -- Macro: AC_F77_LIBRARY_LDFLAGS + Determine the linker flags (e.g. '-L' and '-l') for the "Fortran + 77 intrinsic and run-time libraries" that are required to + successfully link a Fortran 77 program or shared library. The + output variable 'FLIBS' is set to these flags. + + This macro is intended to be used in those situations when it is + necessary to mix, e.g. C++ and Fortran 77 source code into a + single program or shared library (*note (automake)Mixing Fortran 77 + With C and C++::). + + For example, if object files from a C++ and Fortran 77 compiler + must be linked together, then the C++ compiler/linker must be used + for linking (since special C++-ish things need to happen at link + time like calling global constructors, instantiating templates, + enabling exception support, etc.). + + However, the Fortran 77 intrinsic and run-time libraries must be + linked in as well, but the C++ compiler/linker doesn't know by + default how to add these Fortran 77 libraries. Hence, the macro + 'AC_F77_LIBRARY_LDFLAGS' was created to determine these Fortran 77 + libraries. + + The macro 'AC_F77_DUMMY_MAIN' or 'AC_F77_MAIN' will probably also + be necessary to link C/C++ with Fortran; see below. + + -- Macro: AC_F77_DUMMY_MAIN ([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) + With many compilers, the Fortran libraries detected by + 'AC_F77_LIBRARY_LDFLAGS' provide their own 'main' entry function + that initializes things like Fortran I/O, and which then calls a + user-provided entry function named e.g. 'MAIN__' to run the user's + program. The 'AC_F77_DUMMY_MAIN' or 'AC_F77_MAIN' macro figures + out how to deal with this interaction. + + When using Fortran for purely numerical functions (no I/O, + etcetera), users often prefer to provide their own 'main' and skip + the Fortran library initializations. In this case, however, one + may still need to provide a dummy 'MAIN__' routine in order to + prevent linking errors on some systems. 'AC_F77_DUMMY_MAIN' + detects whether any such routine is _required_ for linking, and + what its name is; the shell variable 'F77_DUMMY_MAIN' holds this + name, 'unknown' when no solution was found, and 'none' when no such + dummy main is needed. + + By default, ACTION-IF-FOUND defines 'F77_DUMMY_MAIN' to the name of + this routine (e.g. 'MAIN__') _if_ it is required. + [ACTION-IF-NOT-FOUND] defaults to exiting with an error. + + In order to link with Fortran routines, the user's C/C++ program + should then include the following code to define the dummy main if + it is needed: + + #ifdef F77_DUMMY_MAIN + # ifdef __cplusplus + extern "C" + # endif + int F77_DUMMY_MAIN() { return 1; } + #endif + + Note that 'AC_F77_DUMMY_MAIN' is called automatically from + 'AC_F77_WRAPPERS'; there is generally no need to call it explicitly + unless one wants to change the default actions. + + -- Macro: AC_F77_MAIN + As discussed above for 'AC_F77_DUMMY_MAIN', many Fortran libraries + allow you to provide an entry point called e.g. 'MAIN__' instead + of the usual 'main', which is then called by a 'main' function in + the Fortran libraries that initializes things like Fortran I/O. The + 'AC_F77_MAIN' macro detects whether it is _possible_ to utilize + such an alternate main function, and defines 'F77_MAIN' to the name + of the function. (If no alternate main function name is found, + 'F77_MAIN' is simply defined to 'main'.) + + Thus, when calling Fortran routines from C that perform things like + I/O, one should use this macro and name the "main" function + 'F77_MAIN' instead of 'main'. + + -- Macro: AC_F77_WRAPPERS + Defines C macros 'F77_FUNC(name,NAME)' and 'F77_FUNC_(name,NAME)' + to properly mangle the names of C/C++ identifiers, and identifiers + with underscores, respectively, so that they match the + name-mangling scheme used by the Fortran 77 compiler. + + Fortran 77 is case-insensitive, and in order to achieve this the + Fortran 77 compiler converts all identifiers into a canonical case + and format. To call a Fortran 77 subroutine from C or to write a C + function that is callable from Fortran 77, the C program must + explicitly use identifiers in the format expected by the Fortran 77 + compiler. In order to do this, one simply wraps all C identifiers + in one of the macros provided by 'AC_F77_WRAPPERS'. For example, + suppose you have the following Fortran 77 subroutine: + + subroutine foobar(x,y) + double precision x, y + y = 3.14159 * x + return + end + + You would then declare its prototype in C or C++ as: + + #define FOOBAR_F77 F77_FUNC(foobar,FOOBAR) + #ifdef __cplusplus + extern "C" /* prevent C++ name mangling */ + #endif + void FOOBAR_F77(double *x, double *y); + + Note that we pass both the lowercase and uppercase versions of the + function name to 'F77_FUNC' so that it can select the right one. + Note also that all parameters to Fortran 77 routines are passed as + pointers (*note (automake)Mixing Fortran 77 With C and C++::). + + Although Autoconf tries to be intelligent about detecting the + name-mangling scheme of the Fortran 77 compiler, there may be + Fortran 77 compilers that it doesn't support yet. In this case, + the above code will generate a compile-time error, but some other + behavior (e.g. disabling Fortran-related features) can be induced + by checking whether the 'F77_FUNC' macro is defined. + + Now, to call that routine from a C program, we would do something + like: + + { + double x = 2.7183, y; + FOOBAR_F77(&x, &y); + } + + If the Fortran 77 identifier contains an underscore (e.g. + 'foo_bar'), you should use 'F77_FUNC_' instead of 'F77_FUNC' (with + the same arguments). This is because some Fortran 77 compilers + mangle names differently if they contain an underscore. + + -- Macro: AC_F77_FUNC (NAME, [SHELLVAR]) + Given an identifier NAME, set the shell variable SHELLVAR to hold + the mangled version NAME according to the rules of the Fortran 77 + linker (see also 'AC_F77_WRAPPERS'). SHELLVAR is optional; if it + is not supplied, the shell variable will be simply NAME. The + purpose of this macro is to give the caller a way to access the + name-mangling information other than through the C preprocessor as + above; for example, to call Fortran routines from some language + other than C/C++. + + +File: autoconf.info, Node: System Services, Next: UNIX Variants, Prev: Compilers and Preprocessors, Up: Existing Tests + +5.11 System Services +==================== + +The following macros check for operating system services or +capabilities. + + -- Macro: AC_PATH_X + Try to locate the X Window System include files and libraries. If + the user gave the command line options '--x-includes=DIR' and + '--x-libraries=DIR', use those directories. If either or both were + not given, get the missing values by running 'xmkmf' on a trivial + 'Imakefile' and examining the 'Makefile' that it produces. If that + fails (such as if 'xmkmf' is not present), look for them in several + directories where they often reside. If either method is + successful, set the shell variables 'x_includes' and 'x_libraries' + to their locations, unless they are in directories the compiler + searches by default. + + If both methods fail, or the user gave the command line option + '--without-x', set the shell variable 'no_x' to 'yes'; otherwise + set it to the empty string. + + -- Macro: AC_PATH_XTRA + An enhanced version of 'AC_PATH_X'. It adds the C compiler flags + that X needs to output variable 'X_CFLAGS', and the X linker flags + to 'X_LIBS'. Define 'X_DISPLAY_MISSING' if X is not available. + + This macro also checks for special libraries that some systems need + in order to compile X programs. It adds any that the system needs + to output variable 'X_EXTRA_LIBS'. And it checks for special X11R6 + libraries that need to be linked with before '-lX11', and adds any + found to the output variable 'X_PRE_LIBS'. + + -- Macro: AC_SYS_INTERPRETER + Check whether the system supports starting scripts with a line of + the form '#! /bin/csh' to select the interpreter to use for the + script. After running this macro, shell code in 'configure.ac' can + check the shell variable 'interpval'; it will be set to 'yes' if + the system supports '#!', 'no' if not. + + -- Macro: AC_SYS_LARGEFILE + Arrange for large-file support(1). On some hosts, one must use + special compiler options to build programs that can access large + files. Append any such options to the output variable 'CC'. + Define '_FILE_OFFSET_BITS' and '_LARGE_FILES' if necessary. + + Large-file support can be disabled by configuring with the + '--disable-largefile' option. + + If you use this macro, check that your program works even when + 'off_t' is longer than 'long', since this is common when large-file + support is enabled. For example, it is not correct to print an + arbitrary 'off_t' value 'X' with 'printf ("%ld", (long) X)'. + + -- Macro: AC_SYS_LONG_FILE_NAMES + If the system supports file names longer than 14 characters, define + 'HAVE_LONG_FILE_NAMES'. + + -- Macro: AC_SYS_POSIX_TERMIOS + Check to see if POSIX termios headers and functions are available + on the system. If so, set the shell variable + 'am_cv_sys_posix_termios' to 'yes'. If not, set the variable to + 'no'. + + ---------- Footnotes ---------- + + (1) large-file support, +<http://www.sas.com/standards/large.file/x_open.20Mar96.html>. + + +File: autoconf.info, Node: UNIX Variants, Prev: System Services, Up: Existing Tests + +5.12 UNIX Variants +================== + +The following macros check for certain operating systems that need +special treatment for some programs, due to exceptional oddities in +their header files or libraries. These macros are warts; they will be +replaced by a more systematic approach, based on the functions they make +available or the environments they provide. + + -- Macro: AC_AIX + If on AIX, define '_ALL_SOURCE'. Allows the use of some BSD + functions. Should be called before any macros that run the C + compiler. + + -- Macro: AC_ISC_POSIX + If on a POSIXized ISC UNIX, define '_POSIX_SOURCE' and add '-posix' + (for the GNU C compiler) or '-Xp' (for other C compilers) to output + variable 'CC'. This allows the use of POSIX facilities. Must be + called after 'AC_PROG_CC' and before any other macros that run the + C compiler. + + -- Macro: AC_MINIX + If on Minix, define '_MINIX' and '_POSIX_SOURCE' and define + '_POSIX_1_SOURCE' to be 2. This allows the use of POSIX + facilities. Should be called before any macros that run the C + compiler. + + +File: autoconf.info, Node: Writing Tests, Next: Results, Prev: Existing Tests, Up: Top + +6 Writing Tests +*************** + +If the existing feature tests don't do something you need, you have to +write new ones. These macros are the building blocks. They provide +ways for other macros to check whether various kinds of features are +available and report the results. + + This chapter contains some suggestions and some of the reasons why +the existing tests are written the way they are. You can also learn a +lot about how to write Autoconf tests by looking at the existing ones. +If something goes wrong in one or more of the Autoconf tests, this +information can help you understand the assumptions behind them, which +might help you figure out how to best solve the problem. + + These macros check the output of the C compiler system. They do not +cache the results of their tests for future use (*note Caching +Results::), because they don't know enough about the information they +are checking for to generate a cache variable name. They also do not +print any messages, for the same reason. The checks for particular +kinds of C features call these macros and do cache their results and +print messages about what they're checking for. + + When you write a feature test that could be applicable to more than +one software package, the best thing to do is encapsulate it in a new +macro. *Note Writing Autoconf Macros::, for how to do that. + +* Menu: + +* Examining Declarations:: Detecting header files and declarations +* Examining Syntax:: Detecting language syntax features +* Examining Libraries:: Detecting functions and global variables +* Run Time:: Testing for run-time features +* Systemology:: A zoology of operating systems +* Multiple Cases:: Tests for several possible values +* Language Choice:: Selecting which language to use for testing + + +File: autoconf.info, Node: Examining Declarations, Next: Examining Syntax, Prev: Writing Tests, Up: Writing Tests + +6.1 Examining Declarations +========================== + +The macro 'AC_TRY_CPP' is used to check whether particular header files +exist. You can check for one at a time, or more than one if you need +several header files to all exist for some purpose. + + -- Macro: AC_TRY_CPP (INCLUDES, [ACTION-IF-TRUE], [ACTION-IF-FALSE]) + INCLUDES is C or C++ '#include' statements and declarations, on + which shell variable, back quote, and backslash substitutions are + performed. (Actually, it can be any C program, but other + statements are probably not useful.) If the preprocessor produces + no error messages while processing it, run shell commands + ACTION-IF-TRUE. Otherwise run shell commands ACTION-IF-FALSE. + + This macro uses 'CPPFLAGS', but not 'CFLAGS', because '-g', '-O', + etc. are not valid options to many C preprocessors. + + Here is how to find out whether a header file contains a particular +declaration, such as a typedef, a structure, a structure member, or a +function. Use 'AC_EGREP_HEADER' instead of running 'grep' directly on +the header file; on some systems the symbol might be defined in another +header file that the file you are checking '#include's. + + -- Macro: AC_EGREP_HEADER (PATTERN, HEADER-FILE, ACTION-IF-FOUND, + [ACTION-IF-NOT-FOUND]) + If the output of running the preprocessor on the system header file + HEADER-FILE matches the 'egrep' regular expression PATTERN, execute + shell commands ACTION-IF-FOUND, otherwise execute + ACTION-IF-NOT-FOUND. + + To check for C preprocessor symbols, either defined by header files +or predefined by the C preprocessor, use 'AC_EGREP_CPP'. Here is an +example of the latter: + + AC_EGREP_CPP(yes, + [#ifdef _AIX + yes + #endif + ], is_aix=yes, is_aix=no) + + -- Macro: AC_EGREP_CPP (PATTERN, PROGRAM, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + PROGRAM is the text of a C or C++ program, on which shell variable, + back quote, and backslash substitutions are performed. If the + output of running the preprocessor on PROGRAM matches the 'egrep' + regular expression PATTERN, execute shell commands ACTION-IF-FOUND, + otherwise execute ACTION-IF-NOT-FOUND. + + This macro calls 'AC_PROG_CPP' or 'AC_PROG_CXXCPP' (depending on + which language is current, *note Language Choice::), if it hasn't + been called already. + + +File: autoconf.info, Node: Examining Syntax, Next: Examining Libraries, Prev: Examining Declarations, Up: Writing Tests + +6.2 Examining Syntax +==================== + +To check for a syntax feature of the C, C++ or Fortran 77 compiler, such +as whether it recognizes a certain keyword, use 'AC_TRY_COMPILE' to try +to compile a small program that uses that feature. You can also use it +to check for structures and structure members that are not present on +all systems. + + -- Macro: AC_TRY_COMPILE (INCLUDES, FUNCTION-BODY, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Create a C, C++ or Fortran 77 test program (depending on which + language is current, *note Language Choice::), to see whether a + function whose body consists of FUNCTION-BODY can be compiled. + + For C and C++, INCLUDES is any '#include' statements needed by the + code in FUNCTION-BODY (INCLUDES will be ignored if the currently + selected language is Fortran 77). This macro also uses 'CFLAGS' or + 'CXXFLAGS' if either C or C++ is the currently selected language, + as well as 'CPPFLAGS', when compiling. If Fortran 77 is the + currently selected language then 'FFLAGS' will be used when + compiling. + + If the file compiles successfully, run shell commands + ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. + + This macro does not try to link; use 'AC_TRY_LINK' if you need to + do that (*note Examining Libraries::). + + +File: autoconf.info, Node: Examining Libraries, Next: Run Time, Prev: Examining Syntax, Up: Writing Tests + +6.3 Examining Libraries +======================= + +To check for a library, a function, or a global variable, Autoconf +'configure' scripts try to compile and link a small program that uses +it. This is unlike Metaconfig, which by default uses 'nm' or 'ar' on +the C library to try to figure out which functions are available. +Trying to link with the function is usually a more reliable approach +because it avoids dealing with the variations in the options and output +formats of 'nm' and 'ar' and in the location of the standard libraries. +It also allows configuring for cross-compilation or checking a +function's runtime behavior if needed. On the other hand, it can be +slower than scanning the libraries once. + + A few systems have linkers that do not return a failure exit status +when there are unresolved functions in the link. This bug makes the +configuration scripts produced by Autoconf unusable on those systems. +However, some of them can be given options that make the exit status +correct. This is a problem that Autoconf does not currently handle +automatically. If users encounter this problem, they might be able to +solve it by setting 'LDFLAGS' in the environment to pass whatever +options the linker needs (for example, '-Wl,-dn' on MIPS RISC/OS). + + 'AC_TRY_LINK' is used to compile test programs to test for functions +and global variables. It is also used by 'AC_CHECK_LIB' to check for +libraries (*note Libraries::), by adding the library being checked for +to 'LIBS' temporarily and trying to link a small program. + + -- Macro: AC_TRY_LINK (INCLUDES, FUNCTION-BODY, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Depending on the current language (*note Language Choice::), create + a test program to see whether a function whose body consists of + FUNCTION-BODY can be compiled and linked. + + For C and C++, INCLUDES is any '#include' statements needed by the + code in FUNCTION-BODY (INCLUDES will be ignored if the currently + selected language is Fortran 77). This macro also uses 'CFLAGS' or + 'CXXFLAGS' if either C or C++ is the currently selected language, + as well as 'CPPFLAGS', when compiling. If Fortran 77 is the + currently selected language then 'FFLAGS' will be used when + compiling. However, both 'LDFLAGS' and 'LIBS' will be used during + linking in all cases. + + If the file compiles and links successfully, run shell commands + ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. + + -- Macro: AC_TRY_LINK_FUNC (FUNCTION, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Depending on the current language (*note Language Choice::), create + a test program to see whether a program whose body consists of a + prototype of and a call to FUNCTION can be compiled and linked. + + If the file compiles and links successfully, run shell commands + ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. + + +File: autoconf.info, Node: Run Time, Next: Systemology, Prev: Examining Libraries, Up: Writing Tests + +6.4 Checking Run Time Behavior +============================== + +Sometimes you need to find out how a system performs at run time, such +as whether a given function has a certain capability or bug. If you +can, make such checks when your program runs instead of when it is +configured. You can check for things like the machine's endianness when +your program initializes itself. + + If you really need to test for a run-time behavior while configuring, +you can write a test program to determine the result, and compile and +run it using 'AC_TRY_RUN'. Avoid running test programs if possible, +because this prevents people from configuring your package for +cross-compiling. + +* Menu: + +* Test Programs:: Running test programs +* Guidelines:: General rules for writing test programs +* Test Functions:: Avoiding pitfalls in test programs + + +File: autoconf.info, Node: Test Programs, Next: Guidelines, Prev: Run Time, Up: Run Time + +6.4.1 Running Test Programs +--------------------------- + +Use the following macro if you need to test run-time behavior of the +system while configuring. + + -- Macro: AC_TRY_RUN (PROGRAM, [ACTION-IF-TRUE], [ACTION-IF-FALSE], + [ACTION-IF-CROSS-COMPILING]) + PROGRAM is the text of a C program, on which shell variable and + back quote substitutions are performed. If it compiles and links + successfully and returns an exit status of 0 when executed, run + shell commands ACTION-IF-TRUE. Otherwise, run shell commands + ACTION-IF-FALSE; the exit status of the program is available in the + shell variable '$?'. This macro uses 'CFLAGS' or 'CXXFLAGS', + 'CPPFLAGS', 'LDFLAGS', and 'LIBS' when compiling. + + If the C compiler being used does not produce executables that run + on the system where 'configure' is being run, then the test program + is not run. If the optional shell commands + ACTION-IF-CROSS-COMPILING are given, they are run instead. + Otherwise, 'configure' prints an error message and exits. + + Try to provide a pessimistic default value to use when +cross-compiling makes run-time tests impossible. You do this by passing +the optional last argument to 'AC_TRY_RUN'. 'autoconf' prints a warning +message when creating 'configure' each time it encounters a call to +'AC_TRY_RUN' with no ACTION-IF-CROSS-COMPILING argument given. You may +ignore the warning, though users will not be able to configure your +package for cross-compiling. A few of the macros distributed with +Autoconf produce this warning message. + + To configure for cross-compiling you can also choose a value for +those parameters based on the canonical system name (*note Manual +Configuration::). Alternatively, set up a test results cache file with +the correct values for the host system (*note Caching Results::). + + To provide a default for calls of 'AC_TRY_RUN' that are embedded in +other macros, including a few of the ones that come with Autoconf, you +can call 'AC_PROG_CC' before running them. Then, if the shell variable +'cross_compiling' is set to 'yes', use an alternate method to get the +results instead of calling the macros. + + +File: autoconf.info, Node: Guidelines, Next: Test Functions, Prev: Test Programs, Up: Run Time + +6.4.2 Guidelines for Test Programs +---------------------------------- + +Test programs should not write anything to the standard output. They +should return 0 if the test succeeds, nonzero otherwise, so that success +can be distinguished easily from a core dump or other failure; +segmentation violations and other failures produce a nonzero exit +status. Test programs should 'exit', not 'return', from 'main', because +on some systems (old Suns, at least) the argument to 'return' in 'main' +is ignored. + + Test programs can use '#if' or '#ifdef' to check the values of +preprocessor macros defined by tests that have already run. For +example, if you call 'AC_HEADER_STDC', then later on in 'configure.ac' +you can have a test program that includes an ANSI C header file +conditionally: + + #if STDC_HEADERS + # include <stdlib.h> + #endif + + If a test program needs to use or create a data file, give it a name +that starts with 'conftest', such as 'conftest.data'. The 'configure' +script cleans up by running 'rm -rf conftest*' after running test +programs and if the script is interrupted. + + +File: autoconf.info, Node: Test Functions, Prev: Guidelines, Up: Run Time + +6.4.3 Test Functions +-------------------- + +Function declarations in test programs should have a prototype +conditionalized for C++. In practice, though, test programs rarely need +functions that take arguments. + + #ifdef __cplusplus + foo (int i) + #else + foo (i) int i; + #endif + + Functions that test programs declare should also be conditionalized +for C++, which requires 'extern "C"' prototypes. Make sure to not +include any header files containing clashing prototypes. + + #ifdef __cplusplus + extern "C" void *malloc (size_t); + #else + char *malloc (); + #endif + + If a test program calls a function with invalid parameters (just to +see whether it exists), organize the program to ensure that it never +invokes that function. You can do this by calling it in another +function that is never invoked. You can't do it by putting it after a +call to 'exit', because GCC version 2 knows that 'exit' never returns +and optimizes out any code that follows it in the same block. + + If you include any header files, make sure to call the functions +relevant to them with the correct number of arguments, even if they are +just 0, to avoid compilation errors due to prototypes. GCC version 2 +has internal prototypes for several functions that it automatically +inlines; for example, 'memcpy'. To avoid errors when checking for them, +either pass them the correct number of arguments or redeclare them with +a different return type (such as 'char'). + + +File: autoconf.info, Node: Systemology, Next: Multiple Cases, Prev: Run Time, Up: Writing Tests + +6.5 Systemology +=============== + +This section aims at presenting some systems and pointers to +documentation. It may help you addressing particular problems reported +by users. + +QNX 4.25 + QNX is a realtime operating system running on Intel architecture + meant to be scalable from the small embedded systems to hundred + processor super-computer. It claims to be POSIX certified. More + information is available on the QNX home page(1), including the QNX + man pages(2). + + ---------- Footnotes ---------- + + (1) QNX home page, <www.qnx.com>. + + (2) QNX man pages, <http://support.qnx.com/support/docs/qnx4/>. + + +File: autoconf.info, Node: Multiple Cases, Next: Language Choice, Prev: Systemology, Up: Writing Tests + +6.6 Multiple Cases +================== + +Some operations are accomplished in several possible ways, depending on +the UNIX variant. Checking for them essentially requires a "case +statement". Autoconf does not directly provide one; however, it is easy +to simulate by using a shell variable to keep track of whether a way to +perform the operation has been found yet. + + Here is an example that uses the shell variable 'fstype' to keep +track of whether the remaining cases need to be checked. + + AC_MSG_CHECKING([how to get file system type]) + fstype=no + # The order of these tests is important. + AC_TRY_CPP([#include <sys/statvfs.h> + #include <sys/fstyp.h>], + [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4]) + if test $fstype = no; then + AC_TRY_CPP([#include <sys/statfs.h> + #include <sys/fstyp.h>], + [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3]) + fi + if test $fstype = no; then + AC_TRY_CPP([#include <sys/statfs.h> + #include <sys/vmount.h>], + [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX]) + fi + # (more cases omitted here) + AC_MSG_RESULT([$fstype]) + + +File: autoconf.info, Node: Language Choice, Prev: Multiple Cases, Up: Writing Tests + +6.7 Language Choice +=================== + +Autoconf-generated 'configure' scripts check for the C compiler and its +features by default. Packages that use other programming languages +(maybe more than one, e.g. C and C++) need to test features of the +compilers for the respective languages. The following macros determine +which programming language is used in the subsequent tests in +'configure.ac'. + + -- Macro: AC_LANG (LANGUAGE) + Do compilation tests using the compiler, preprocessor and file + extensions for the specified LANGUAGE. + + Supported languages are: + + 'C' + Do compilation tests using 'CC' and 'CPP' and use extension + '.c' for test programs. + + 'C++' + Do compilation tests using 'CXX' and 'CXXCPP' and use + extension '.C' for test programs. + + 'Fortran 77' + Do compilation tests using 'F77' and use extension '.f' for + test programs. + + -- Macro: AC_LANG_PUSH (LANGUAGE) + Remember the current language (as set by 'AC_LANG') on a stack, and + then select the LANGUAGE. Use this macro and 'AC_LANG_POP' in + macros that need to temporarily switch to a particular language. + + -- Macro: AC_LANG_POP ([LANGUAGE]) + Select the language that is saved on the top of the stack, as set + by 'AC_LANG_PUSH', and remove it from the stack. + + If given, LANGUAGE specifies the language we just _quit_. It is a + good idea to specify it when it's known (which should be the + case...), since Autoconf will detect inconsistencies. + + AC_LANG_PUSH(Fortran 77) + # Perform some tests on Fortran 77. + # ... + AC_LANG_POP(Fortran 77) + + -- Macro: AC_REQUIRE_CPP + Ensure that whichever preprocessor would currently be used for + tests has been found. Calls 'AC_REQUIRE' (*note Prerequisite + Macros::) with an argument of either 'AC_PROG_CPP' or + 'AC_PROG_CXXCPP', depending on which language is current. + + +File: autoconf.info, Node: Results, Next: Programming in M4, Prev: Writing Tests, Up: Top + +7 Results of Tests +****************** + +Once 'configure' has determined whether a feature exists, what can it do +to record that information? There are four sorts of things it can do: +define a C preprocessor symbol, set a variable in the output files, save +the result in a cache file for future 'configure' runs, and print a +message letting the user know the result of the test. + +* Menu: + +* Defining Symbols:: Defining C preprocessor symbols +* Setting Output Variables:: Replacing variables in output files +* Caching Results:: Speeding up subsequent 'configure' runs +* Printing Messages:: Notifying 'configure' users + + +File: autoconf.info, Node: Defining Symbols, Next: Setting Output Variables, Prev: Results, Up: Results + +7.1 Defining C Preprocessor Symbols +=================================== + +A common action to take in response to a feature test is to define a C +preprocessor symbol indicating the results of the test. That is done by +calling 'AC_DEFINE' or 'AC_DEFINE_UNQUOTED'. + + By default, 'AC_OUTPUT' places the symbols defined by these macros +into the output variable 'DEFS', which contains an option +'-DSYMBOL=VALUE' for each symbol defined. Unlike in Autoconf version 1, +there is no variable 'DEFS' defined while 'configure' is running. To +check whether Autoconf macros have already defined a certain C +preprocessor symbol, test the value of the appropriate cache variable, +as in this example: + + AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)]) + if test "$ac_cv_func_vprintf" != yes; then + AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)]) + fi + + If 'AC_CONFIG_HEADERS' has been called, then instead of creating +'DEFS', 'AC_OUTPUT' creates a header file by substituting the correct +values into '#define' statements in a template file. *Note +Configuration Headers::, for more information about this kind of output. + + -- Macro: AC_DEFINE (VARIABLE, [VALUE], [DESCRIPTION]) + Define C preprocessor variable VARIABLE. If VALUE is given, set + VARIABLE to that value (verbatim), otherwise set it to 1. VALUE + should not contain literal newlines, and if you are not using + 'AC_CONFIG_HEADERS' it should not contain any '#' characters, as + 'make' tends to eat them. To use a shell variable (which you need + to do in order to define a value containing the M4 quote characters + '[' or ']'), use 'AC_DEFINE_UNQUOTED' instead. DESCRIPTION is only + useful if you are using 'AC_CONFIG_HEADERS'. In this case, + DESCRIPTION is put into the generated 'config.h.in' as the comment + before the macro define. The following example defines the C + preprocessor variable 'EQUATION' to be the string constant '"$a > + $b"': + + AC_DEFINE(EQUATION, "$a > $b") + + -- Macro: AC_DEFINE_UNQUOTED (VARIABLE, [VALUE], [DESCRIPTION]) + Like 'AC_DEFINE', but three shell expansions are + performed--once--on VARIABLE and VALUE: variable expansion ('$'), + command substitution ('`'), and backslash escaping ('\'). Single + and double quote characters in the value have no special meaning. + Use this macro instead of 'AC_DEFINE' when VARIABLE or VALUE is a + shell variable. Examples: + + AC_DEFINE_UNQUOTED(config_machfile, "$machfile") + AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups) + AC_DEFINE_UNQUOTED($ac_tr_hdr) + + Due to the syntactical bizarreness of the Bourne shell, do not use +semicolons to separate 'AC_DEFINE' or 'AC_DEFINE_UNQUOTED' calls from +other macro calls or shell code; that can cause syntax errors in the +resulting 'configure' script. Use either spaces or newlines. That is, +do this: + + AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"]) + +or this: + + AC_CHECK_HEADER(elf.h, + [AC_DEFINE(SVR4) + LIBS="$LIBS -lelf"]) + +instead of this: + + AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"]) + + +File: autoconf.info, Node: Setting Output Variables, Next: Caching Results, Prev: Defining Symbols, Up: Results + +7.2 Setting Output Variables +============================ + +Another way to record the results of tests is to set "output variables", +which are shell variables whose values are substituted into files that +'configure' outputs. The two macros below create new output variables. +*Note Preset Output Variables::, for a list of output variables that are +always available. + + -- Macro: AC_SUBST (VARIABLE, [VALUE]) + Create an output variable from a shell variable. Make 'AC_OUTPUT' + substitute the variable VARIABLE into output files (typically one + or more 'Makefile's). This means that 'AC_OUTPUT' will replace + instances of '@VARIABLE@' in input files with the value that the + shell variable VARIABLE has when 'AC_OUTPUT' is called. This value + of VARIABLE should not contain literal newlines. + + If VALUE is given, in addition assign it to 'variable'. + + -- Macro: AC_SUBST_FILE (VARIABLE) + Another way to create an output variable from a shell variable. + Make 'AC_OUTPUT' insert (without substitutions) the contents of the + file named by shell variable VARIABLE into output files. This + means that 'AC_OUTPUT' will replace instances of '@VARIABLE@' in + output files (such as 'Makefile.in') with the contents of the file + that the shell variable VARIABLE names when 'AC_OUTPUT' is called. + Set the variable to '/dev/null' for cases that do not have a file + to insert. + + This macro is useful for inserting 'Makefile' fragments containing + special dependencies or other 'make' directives for particular host + or target types into 'Makefile's. For example, 'configure.ac' + could contain: + + AC_SUBST_FILE(host_frag) + host_frag=$srcdir/conf/sun4.mh + + and then a 'Makefile.in' could contain: + + @host_frag@ + + Running 'configure' in different environments can be extremely +dangerous. If for instance the user runs 'CC=bizarre-cc ./configure', +then the cache, 'config.h' and many other output files will depend upon +'bizarre-cc' being the C compiler. If for some reason the user runs +'/configure' again, or if it is run via './config.status --recheck', +(*Note Automatic Remaking::, and *note config.status Invocation::), then +the configuration can be inconsistent, composed of results depending +upon two different compilers. + + Such variables are named "precious variables", and can be declared as +such by 'AC_ARG_VAR'. + + -- Macro: AC_ARG_VAR (VARIABLE, DESCRIPTION) + Declare VARIABLE is a precious variable, and include its + DESCRIPTION in the variable section of './configure --help'. + + Being precious means that + - VARIABLE is 'AC_SUBST''d. + + - VARIABLE is kept in the cache including if it was not + specified on the './configure' command line. Indeed, while + 'configure' can notice the definition of 'CC' in './configure + CC=bizarre-cc', it is impossible to notice it in + 'CC=bizarre-cc ./configure', which, unfortunately, is what + most users do. + + - VARIABLE is checked for consistency between two 'configure' + runs. For instance: + + $ ./configure --silent --config-cache + $ CC=cc ./configure --silent --config-cache + configure: error: `CC' was not set in the previous run + configure: error: changes in the environment can compromise \ + the build + configure: error: run `make distclean' and/or \ + `rm config.cache' and start over + + and similarly if the variable is unset, or if its content is + changed. + + - VARIABLE is kept during automatic reconfiguration (*note + config.status Invocation::) as if it had been passed as a + command line argument, including when no cache is used: + + $ CC=/usr/bin/cc ./configure undeclared_var=raboof --silent + $ ./config.status --recheck + running /bin/sh ./configure undeclared_var=raboof --silent \ + CC=/usr/bin/cc --no-create --no-recursion + + +File: autoconf.info, Node: Caching Results, Next: Printing Messages, Prev: Setting Output Variables, Up: Results + +7.3 Caching Results +=================== + +To avoid checking for the same features repeatedly in various +'configure' scripts (or in repeated runs of one script), 'configure' can +optionally save the results of many checks in a "cache file" (*note +Cache Files::). If a 'configure' script runs with caching enabled and +finds a cache file, it reads the results of previous runs from the cache +and avoids rerunning those checks. As a result, 'configure' can then +run much faster than if it had to perform all of the checks every time. + + -- Macro: AC_CACHE_VAL (CACHE-ID, COMMANDS-TO-SET-IT) + Ensure that the results of the check identified by CACHE-ID are + available. If the results of the check were in the cache file that + was read, and 'configure' was not given the '--quiet' or '--silent' + option, print a message saying that the result was cached; + otherwise, run the shell commands COMMANDS-TO-SET-IT. If the shell + commands are run to determine the value, the value will be saved in + the cache file just before 'configure' creates its output files. + *Note Cache Variable Names::, for how to choose the name of the + CACHE-ID variable. + + The COMMANDS-TO-SET-IT _must have no side effects_ except for + setting the variable CACHE-ID, see below. + + -- Macro: AC_CACHE_CHECK (MESSAGE, CACHE-ID, COMMANDS-TO-SET-IT) + A wrapper for 'AC_CACHE_VAL' that takes care of printing the + messages. This macro provides a convenient shorthand for the most + common way to use these macros. It calls 'AC_MSG_CHECKING' for + MESSAGE, then 'AC_CACHE_VAL' with the CACHE-ID and COMMANDS + arguments, and 'AC_MSG_RESULT' with CACHE-ID. + + The COMMANDS-TO-SET-IT _must have no side effects_ except for + setting the variable CACHE-ID, see below. + + It is very common to find buggy macros using 'AC_CACHE_VAL' or +'AC_CACHE_CHECK', because people are tempted to call 'AC_DEFINE' in the +COMMANDS-TO-SET-IT. Instead, the code that _follows_ the call to +'AC_CACHE_VAL' should call 'AC_DEFINE', by examining the value of the +cache variable. For instance, the following macro is broken: + + AC_DEFUN([AC_SHELL_TRUE], + [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], + [ac_cv_shell_true_works=no + true && ac_cv_shell_true_works=yes + if test $ac_cv_shell_true_works = yes; then + AC_DEFINE([TRUE_WORKS], 1 + [Define if `true(1)' works properly.]) + fi]) + ]) + +This fails if the cache is enabled: the second time this macro is run, +'TRUE_WORKS' _will not be defined_. The proper implementation is: + + AC_DEFUN([AC_SHELL_TRUE], + [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], + [ac_cv_shell_true_works=no + true && ac_cv_shell_true_works=yes]) + if test $ac_cv_shell_true_works = yes; then + AC_DEFINE([TRUE_WORKS], 1 + [Define if `true(1)' works properly.]) + fi + ]) + + Also, COMMANDS-TO-SET-IT should not print any messages, for example +with 'AC_MSG_CHECKING'; do that before calling 'AC_CACHE_VAL', so the +messages are printed regardless of whether the results of the check are +retrieved from the cache or determined by running the shell commands. + +* Menu: + +* Cache Variable Names:: Shell variables used in caches +* Cache Files:: Files 'configure' uses for caching +* Cache Checkpointing:: Loading and saving the cache file + + +File: autoconf.info, Node: Cache Variable Names, Next: Cache Files, Prev: Caching Results, Up: Caching Results + +7.3.1 Cache Variable Names +-------------------------- + +The names of cache variables should have the following format: + + PACKAGE-PREFIX_cv_VALUE-TYPE_SPECIFIC-VALUE_[ADDITIONAL-OPTIONS] + +for example, 'ac_cv_header_stat_broken' or 'ac_cv_prog_gcc_traditional'. +The parts of the variable name are: + +PACKAGE-PREFIX + An abbreviation for your package or organization; the same prefix + you begin local Autoconf macros with, except lowercase by + convention. For cache values used by the distributed Autoconf + macros, this value is 'ac'. + +'_cv_' + Indicates that this shell variable is a cache value. This string + _must_ be present in the variable name, including the leading + underscore. + +VALUE-TYPE + A convention for classifying cache values, to produce a rational + naming system. The values used in Autoconf are listed in *note + Macro Names::. + +SPECIFIC-VALUE + Which member of the class of cache values this test applies to. + For example, which function ('alloca'), program ('gcc'), or output + variable ('INSTALL'). + +ADDITIONAL-OPTIONS + Any particular behavior of the specific member that this test + applies to. For example, 'broken' or 'set'. This part of the name + may be omitted if it does not apply. + + The values assigned to cache variables may not contain newlines. +Usually, their values will be boolean ('yes' or 'no') or the names of +files or functions; so this is not an important restriction. + + +File: autoconf.info, Node: Cache Files, Next: Cache Checkpointing, Prev: Cache Variable Names, Up: Caching Results + +7.3.2 Cache Files +----------------- + +A cache file is a shell script that caches the results of configure +tests run on one system so they can be shared between configure scripts +and configure runs. It is not useful on other systems. If its contents +are invalid for some reason, the user may delete or edit it. + + By default, 'configure' uses no cache file (technically, it uses +'--cache-file=/dev/null'), to avoid problems caused by accidental use of +stale cache files. + + To enable caching, 'configure' accepts '--config-cache' (or '-C') to +cache results in the file 'config.cache'. Alternatively, +'--cache-file=FILE' specifies that FILE be the cache file. The cache +file is created if it does not exist already. When 'configure' calls +'configure' scripts in subdirectories, it uses the '--cache-file' +argument so that they share the same cache. *Note Subdirectories::, for +information on configuring subdirectories with the 'AC_CONFIG_SUBDIRS' +macro. + + 'config.status' only pays attention to the cache file if it is given +the '--recheck' option, which makes it rerun 'configure'. + + It is wrong to try to distribute cache files for particular system +types. There is too much room for error in doing that, and too much +administrative overhead in maintaining them. For any features that +can't be guessed automatically, use the standard method of the canonical +system type and linking files (*note Manual Configuration::). + + The site initialization script can specify a site-wide cache file to +use, instead of the usual per-program cache. In this case, the cache +file will gradually accumulate information whenever someone runs a new +'configure' script. (Running 'configure' merges the new cache results +with the existing cache file.) This may cause problems, however, if the +system configuration (e.g. the installed libraries or compilers) +changes and the stale cache file is not deleted. + + +File: autoconf.info, Node: Cache Checkpointing, Prev: Cache Files, Up: Caching Results + +7.3.3 Cache Checkpointing +------------------------- + +If your configure script, or a macro called from configure.ac, happens +to abort the configure process, it may be useful to checkpoint the cache +a few times at key points using 'AC_CACHE_SAVE'. Doing so will reduce +the amount of time it takes to re-run the configure script with +(hopefully) the error that caused the previous abort corrected. + + -- Macro: AC_CACHE_LOAD + Loads values from existing cache file, or creates a new cache file + if a cache file is not found. Called automatically from 'AC_INIT'. + + -- Macro: AC_CACHE_SAVE + Flushes all cached values to the cache file. Called automatically + from 'AC_OUTPUT', but it can be quite useful to call + 'AC_CACHE_SAVE' at key points in configure.ac. + + For instance: + + ... AC_INIT, etc. ... + # Checks for programs. + AC_PROG_CC + AC_PROG_GCC_TRADITIONAL + ... more program checks ... + AC_CACHE_SAVE + + # Checks for libraries. + AC_CHECK_LIB(nsl, gethostbyname) + AC_CHECK_LIB(socket, connect) + ... more lib checks ... + AC_CACHE_SAVE + + # Might abort... + AM_PATH_GTK(1.0.2,, (exit 1); exit) + AM_PATH_GTKMM(0.9.5,, (exit 1); exit) + ... AC_OUTPUT, etc. ... + + +File: autoconf.info, Node: Printing Messages, Prev: Caching Results, Up: Results + +7.4 Printing Messages +===================== + +'configure' scripts need to give users running them several kinds of +information. The following macros print messages in ways appropriate +for each kind. The arguments to all of them get enclosed in shell +double quotes, so the shell performs variable and back-quote +substitution on them. + + These macros are all wrappers around the 'echo' shell command. +'configure' scripts should rarely need to run 'echo' directly to print +messages for the user. Using these macros makes it easy to change how +and when each kind of message is printed; such changes need only be made +to the macro definitions and all of the callers will change +automatically. + + To diagnose static issues, i.e., when 'autoconf' is run, see *note +Reporting Messages::. + + -- Macro: AC_MSG_CHECKING (FEATURE-DESCRIPTION) + Notify the user that 'configure' is checking for a particular + feature. This macro prints a message that starts with 'checking ' + and ends with '...' and no newline. It must be followed by a call + to 'AC_MSG_RESULT' to print the result of the check and the + newline. The FEATURE-DESCRIPTION should be something like 'whether + the Fortran compiler accepts C++ comments' or 'for c89'. + + This macro prints nothing if 'configure' is run with the '--quiet' + or '--silent' option. + + -- Macro: AC_MSG_RESULT (RESULT-DESCRIPTION) + Notify the user of the results of a check. RESULT-DESCRIPTION is + almost always the value of the cache variable for the check, + typically 'yes', 'no', or a file name. This macro should follow a + call to 'AC_MSG_CHECKING', and the RESULT-DESCRIPTION should be the + completion of the message printed by the call to 'AC_MSG_CHECKING'. + + This macro prints nothing if 'configure' is run with the '--quiet' + or '--silent' option. + + -- Macro: AC_MSG_NOTICE (MESSAGE) + Deliver the MESSAGE to the user. It is useful mainly to print a + general description of the overall purpose of a group of feature + checks, e.g., + + AC_MSG_NOTICE([checking if stack overflow is detectable]) + + This macro prints nothing if 'configure' is run with the '--quiet' + or '--silent' option. + + -- Macro: AC_MSG_ERROR (ERROR-DESCRIPTION, [EXIT-STATUS]) + Notify the user of an error that prevents 'configure' from + completing. This macro prints an error message to the standard + error output and exits 'configure' with EXIT-STATUS (1 by default). + ERROR-DESCRIPTION should be something like 'invalid value $HOME for + \$HOME'. + + The ERROR-DESCRIPTION should start with a lower-case letter, and + "cannot" is preferred to "can't". + + -- Macro: AC_MSG_WARN (PROBLEM-DESCRIPTION) + Notify the 'configure' user of a possible problem. This macro + prints the message to the standard error output; 'configure' + continues running afterward, so macros that call 'AC_MSG_WARN' + should provide a default (back-up) behavior for the situations they + warn about. PROBLEM-DESCRIPTION should be something like 'ln -s + seems to make hard links'. + + +File: autoconf.info, Node: Programming in M4, Next: Writing Autoconf Macros, Prev: Results, Up: Top + +8 Programming in M4 +******************* + +Autoconf is written on top of two layers: "M4sugar", which provides +convenient macros for pure M4 programming, and "M4sh", which provides +macros dedicated to shell script generation. + + As of this version of Autoconf, these two layers are still +experimental, and their interface might change in the future. As a +matter of fact, _anything that is not documented must not be used_. + +* Menu: + +* M4 Quotation:: Protecting macros from unwanted expansion +* Programming in M4sugar:: Convenient pure M4 macros + + +File: autoconf.info, Node: M4 Quotation, Next: Programming in M4sugar, Prev: Programming in M4, Up: Programming in M4 + +8.1 M4 Quotation +================ + +The most common brokenness of existing macros is an improper quotation. +This section, which users of Autoconf can skip, but which macro writers +_must_ read, first justifies the quotation scheme that was chosen for +Autoconf and then ends with a rule of thumb. Understanding the former +helps one to follow the latter. + +* Menu: + +* Active Characters:: Characters that change the behavior of m4 +* One Macro Call:: Quotation and one macro call +* Quotation and Nested Macros:: Macros calling macros +* Quadrigraphs:: Another way to escape special characters +* Quotation Rule Of Thumb:: One parenthesis, one quote + + +File: autoconf.info, Node: Active Characters, Next: One Macro Call, Prev: M4 Quotation, Up: M4 Quotation + +8.1.1 Active Characters +----------------------- + +To fully understand where proper quotation is important, you first need +to know what are the special characters in Autoconf: '#' introduces a +comment inside which no macro expansion is performed, ',' separates +arguments, '[' and ']' are the quotes themselves, and finally '(' and +')' (which 'm4' tries to match by pairs). + + In order to understand the delicate case of macro calls, we first +have to present some obvious failures. Below they are "obvious-ified", +although you find them in real life, they are usually in disguise. + + Comments, introduced by a hash and running up to the newline, are +opaque tokens to the top level: active characters are turned off, and +there is no macro expansion: + + # define([def], ine) + =># define([def], ine) + + Each time there can be a macro expansion, there is a quotation +expansion; i.e., one level of quotes is stripped: + + int tab[10]; + =>int tab10; + [int tab[10];] + =>int tab[10]; + + Without this in mind, the reader will try hopelessly to use her macro +'array': + + define([array], [int tab[10];]) + array + =>int tab10; + [array] + =>array + +How can you correctly output the intended results(1)? + + ---------- Footnotes ---------- + + (1) Using 'defn'. + + +File: autoconf.info, Node: One Macro Call, Next: Quotation and Nested Macros, Prev: Active Characters, Up: M4 Quotation + +8.1.2 One Macro Call +-------------------- + +Let's proceed on the interaction between active characters and macros +with this small macro, which just returns its first argument: + + define([car], [$1]) + +The two pairs of quotes above are not part of the arguments of 'define'; +rather, they are understood by the top level when it tries to find the +arguments of 'define'. Therefore, it is equivalent to write: + + define(car, $1) + +But, while it is acceptable for a 'configure.ac' to avoid unneeded +quotes, it is bad practice for Autoconf macros which must both be more +robust and also advocate perfect style. + + At the top level, there are only two possible quotings: either you +quote or you don't: + + car(foo, bar, baz) + =>foo + [car(foo, bar, baz)] + =>car(foo, bar, baz) + + Let's pay attention to the special characters: + + car(#) + error->EOF in argument list + + The closing parenthesis is hidden in the comment; with a hypothetical +quoting, the top level understood it this way: + + car([#)] + +Proper quotation, of course, fixes the problem: + + car([#]) + =># + + The reader will easily understand the following examples: + + car(foo, bar) + =>foo + car([foo, bar]) + =>foo, bar + car((foo, bar)) + =>(foo, bar) + car([(foo], [bar)]) + =>(foo + car([], []) + => + car([[]], [[]]) + =>[] + + With this in mind, we can explore the cases where macros invoke +macros... + + +File: autoconf.info, Node: Quotation and Nested Macros, Next: Quadrigraphs, Prev: One Macro Call, Up: M4 Quotation + +8.1.3 Quotation and Nested Macros +--------------------------------- + +The examples below use the following macros: + + define([car], [$1]) + define([active], [ACT, IVE]) + define([array], [int tab[10]]) + + Each additional embedded macro call introduces other possible +interesting quotations: + + car(active) + =>ACT + car([active]) + =>ACT, IVE + car([[active]]) + =>active + + In the first case, the top level looks for the arguments of 'car', +and finds 'active'. Because 'm4' evaluates its arguments before +applying the macro, 'active' is expanded, which results in: + + car(ACT, IVE) + =>ACT + +In the second case, the top level gives 'active' as first and only +argument of 'car', which results in: + + active + =>ACT, IVE + +i.e., the argument is evaluated _after_ the macro that invokes it. In +the third case, 'car' receives '[active]', which results in: + + [active] + =>active + +exactly as we already saw above. + + The example above, applied to a more realistic example, gives: + + car(int tab[10];) + =>int tab10; + car([int tab[10];]) + =>int tab10; + car([[int tab[10];]]) + =>int tab[10]; + +Huh? The first case is easily understood, but why is the second wrong, +and the third right? To understand that, you must know that after 'm4' +expands a macro, the resulting text is immediately subjected to macro +expansion and quote removal. This means that the quote removal occurs +twice--first before the argument is passed to the 'car' macro, and +second after the 'car' macro expands to the first argument. + + As the author of the Autoconf macro 'car', you then consider it to be +incorrect that your users have to double-quote the arguments of 'car', +so you "fix" your macro. Let's call it 'qar' for quoted car: + + define([qar], [[$1]]) + +and check that 'qar' is properly fixed: + + qar([int tab[10];]) + =>int tab[10]; + +Ahhh! That's much better. + + But note what you've done: now that the arguments are literal +strings, if the user wants to use the results of expansions as +arguments, she has to use an _unquoted_ macro call: + + qar(active) + =>ACT + +where she wanted to reproduce what she used to do with 'car': + + car([active]) + =>ACT, IVE + +Worse yet: she wants to use a macro that produces a set of 'cpp' macros: + + define([my_includes], [#include <stdio.h>]) + car([my_includes]) + =>#include <stdio.h> + qar(my_includes) + error->EOF in argument list + + This macro, 'qar', because it double quotes its arguments, forces its +users to leave their macro calls unquoted, which is dangerous. Commas +and other active symbols are interpreted by 'm4' before they are given +to the macro, often not in the way the users expect. Also, because +'qar' behaves differently from the other macros, it's an exception that +should be avoided in Autoconf. + + +File: autoconf.info, Node: Quadrigraphs, Next: Quotation Rule Of Thumb, Prev: Quotation and Nested Macros, Up: M4 Quotation + +8.1.4 Quadrigraphs +------------------ + +When writing an autoconf macro you may occasionally need to generate +special characters that are difficult to express with the standard +autoconf quoting rules. For example, you may need to output the regular +expression '[^[]', which matches any character other than '['. This +expression contains unbalanced brackets so it cannot be put easily into +an M4 macro. + + You can work around this problem by using one of the following +"quadrigraphs": + +'@<:@' + '[' +'@:>@' + ']' +'@S|@' + '$' +'@%:@' + '#' + + Quadrigraphs are replaced at a late stage of the translation process, +after 'm4' is run, so they do not get in the way of M4 quoting. For +example, the string '[^@<:@]', if properly quoted, will appear as '[^[]' +in the 'configure' script. + + +File: autoconf.info, Node: Quotation Rule Of Thumb, Prev: Quadrigraphs, Up: M4 Quotation + +8.1.5 Quotation Rule Of Thumb +----------------------------- + +To conclude, the quotation rule of thumb is: + + _One pair of quotes per pair of parentheses._ + + Never over-quote, never under-quote, in particular in the definition +of macros. In the few places where the macros need to use brackets +(usually in C program text or regular expressions), properly quote _the +arguments_! + + It is common to read Autoconf programs with snippets like: + + AC_TRY_LINK( + changequote(<<, >>)dnl + <<#include <time.h> + #ifndef tzname /* For SGI. */ + extern char *tzname[]; /* RS6000 and others reject char **tzname. */ + #endif>>, + changequote([, ])dnl + [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) + +which is incredibly useless since 'AC_TRY_LINK' is _already_ double +quoting, so you just need: + + AC_TRY_LINK( + [#include <time.h> + #ifndef tzname /* For SGI. */ + extern char *tzname[]; /* RS6000 and others reject char **tzname. */ + #endif], + [atoi (*tzname);], + [ac_cv_var_tzname=yes], + [ac_cv_var_tzname=no]) + +The M4-fluent reader will note that these two examples are rigorously +equivalent, since 'm4' swallows both the 'changequote(<<, >>)' and '<<' +'>>' when it "collects" the arguments: these quotes are not part of the +arguments! + + Simplified, the example above is just doing this: + + changequote(<<, >>)dnl + <<[]>> + changequote([, ])dnl + +instead of simply: + + [[]] + + With macros that do not double quote their arguments (which is the +rule), double-quote the (risky) literals: + + AC_LINK_IFELSE([AC_LANG_PROGRAM( + [[#include <time.h> + #ifndef tzname /* For SGI. */ + extern char *tzname[]; /* RS6000 and others reject char **tzname. */ + #endif]], + [atoi (*tzname);])], + [ac_cv_var_tzname=yes], + [ac_cv_var_tzname=no]) + + See *Note Quadrigraphs::, for what to do if you run into a hopeless +case where quoting does not suffice. + + When you create a 'configure' script using newly written macros, +examine it carefully to check whether you need to add more quotes in +your macros. If one or more words have disappeared in the 'm4' output, +you need more quotes. When in doubt, quote. + + However, it's also possible to put on too many layers of quotes. If +this happens, the resulting 'configure' script will contain unexpanded +macros. The 'autoconf' program checks for this problem by doing 'grep +AC_ configure'. + + +File: autoconf.info, Node: Programming in M4sugar, Prev: M4 Quotation, Up: Programming in M4 + +8.2 Programming in M4sugar +========================== + +M4 by itself provides only a small, but sufficient, set of all-purpose +macros. M4sugar introduces additional generic macros. Its name was +coined by Lars J. Aas: "Readability And Greater Understanding Stands 4 +M4sugar". + +* Menu: + +* Redefined M4 Macros:: M4 builtins changed in M4sugar +* Forbidden Patterns:: Catching unexpanded macros + + +File: autoconf.info, Node: Redefined M4 Macros, Next: Forbidden Patterns, Prev: Programming in M4sugar, Up: Programming in M4sugar + +8.2.1 Redefined M4 Macros +------------------------- + +All the M4 native macros are moved in the 'm4_' pseudo-namespace, e.g., +M4sugar renames 'define' as 'm4_define' etc. There is one exception: +'dnl' kept its original name, and no 'm4_dnl' is defined. + + M4sugar redefines some M4 macros, and made them slightly incompatible +with their native equivalent. + + -- Macro: m4_defn (MACRO) + Contrary to the M4 builtin, this macro fails if MACRO is not + defined. See 'm4_undefine'. + + -- Macro: m4_undefine (MACRO) + Contrary to the M4 builtin, this macro fails if MACRO is not + defined. Use + + m4_ifdef([MACRO], [m4_undefine([MACRO])]) + + to recover the behavior of the builtin. + + -- Macro: m4_popdef (MACRO) + Contrary to the M4 builtin, this macro fails if MACRO is not + defined. See 'm4_undefine'. + + +File: autoconf.info, Node: Forbidden Patterns, Prev: Redefined M4 Macros, Up: Programming in M4sugar + +8.2.2 Forbidden Patterns +------------------------ + +M4sugar provides a means to define suspicious patterns, patterns +describing tokens which should not be found in the output. For +instance, if an Autoconf 'configure' script includes tokens such as +'AC_DEFINE', or 'dnl', then most probably something went wrong +(typically a macro was not evaluated because of over quotation). + + M4sugar forbids all the tokens matching '^m4_' and '^dnl$'. + + -- Macro: m4_pattern_forbid (PATTERN) + Declare no token matching PATTERN must be found in the output. + Comments are not checked; this can be a problem if, for instance, + you have some macro left unexpanded after an '#include'. No + consensus is currently found in the Autoconf community, as some + people consider it should be valid to name macros in comments + (which doesn't makes sense to the author of this documentation, as + '#'-comments should document the output, not the input, documented + vy 'dnl'-comments). + + Of course, you might encounter exceptions to these generic rules, for +instance you might have to refer to '$m4_flags'. + + -- Macro: m4_pattern_allow (PATTERN) + Any token matching PATTERN is allowed, including if it matches an + 'm4_pattern_forbid' pattern. + + +File: autoconf.info, Node: Writing Autoconf Macros, Next: Portable Shell, Prev: Programming in M4, Up: Top + +9 Writing Autoconf Macros +************************* + +When you write a feature test that could be applicable to more than one +software package, the best thing to do is encapsulate it in a new macro. +Here are some instructions and guidelines for writing Autoconf macros. + +* Menu: + +* Macro Definitions:: Basic format of an Autoconf macro +* Macro Names:: What to call your new macros +* Reporting Messages:: Notifying 'autoconf' users +* Dependencies Between Macros:: What to do when macros depend on other macros +* Obsoleting Macros:: Warning about old ways of doing things +* Coding Style:: Writing Autoconf macros à la Autoconf + + +File: autoconf.info, Node: Macro Definitions, Next: Macro Names, Prev: Writing Autoconf Macros, Up: Writing Autoconf Macros + +9.1 Macro Definitions +===================== + +Autoconf macros are defined using the 'AC_DEFUN' macro, which is similar +to the M4 builtin 'define' macro. In addition to defining a macro, +'AC_DEFUN' adds to it some code that is used to constrain the order in +which macros are called (*note Prerequisite Macros::). + + An Autoconf macro definition looks like this: + + AC_DEFUN(MACRO-NAME, MACRO-BODY) + + You can refer to any arguments passed to the macro as '$1', '$2', +etc. *Note How to define new macros: (m4.info)Definitions, for more +complete information on writing M4 macros. + + Be sure to properly quote both the MACRO-BODY _and_ the MACRO-NAME to +avoid any problems if the macro happens to have been previously defined. + + Each macro should have a header comment that gives its prototype, and +a brief description. When arguments have default values, display them +in the prototype. For example: + + # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) + # -------------------------------------- + define([AC_MSG_ERROR], + [{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); }]) + + Comments about the macro should be left in the header comment. Most +other comments will make their way into 'configure', so just keep using +'#' to introduce comments. + + If you have some very special comments about pure M4 code, comments +that make no sense in 'configure' and in the header comment, then use +the builtin 'dnl': it causes 'm4' to discard the text through the next +newline. + + Keep in mind that 'dnl' is rarely needed to introduce comments; 'dnl' +is more useful to get rid of the newlines following macros that produce +no output, such as 'AC_REQUIRE'. + + +File: autoconf.info, Node: Macro Names, Next: Reporting Messages, Prev: Macro Definitions, Up: Writing Autoconf Macros + +9.2 Macro Names +=============== + +All of the Autoconf macros have all-uppercase names starting with 'AC_' +to prevent them from accidentally conflicting with other text. All +shell variables that they use for internal purposes have +mostly-lowercase names starting with 'ac_'. To ensure that your macros +don't conflict with present or future Autoconf macros, you should prefix +your own macro names and any shell variables they use with some other +sequence. Possibilities include your initials, or an abbreviation for +the name of your organization or software package. + + Most of the Autoconf macros' names follow a structured naming +convention that indicates the kind of feature check by the name. The +macro names consist of several words, separated by underscores, going +from most general to most specific. The names of their cache variables +use the same convention (*note Cache Variable Names::, for more +information on them). + + The first word of the name after 'AC_' usually tells the category of +feature being tested. Here are the categories used in Autoconf for +specific test macros, the kind of macro that you are more likely to +write. They are also used for cache variables, in all-lowercase. Use +them where applicable; where they're not, invent your own categories. + +'C' + C language builtin features. +'DECL' + Declarations of C variables in header files. +'FUNC' + Functions in libraries. +'GROUP' + UNIX group owners of files. +'HEADER' + Header files. +'LIB' + C libraries. +'PATH' + The full path names to files, including programs. +'PROG' + The base names of programs. +'MEMBER' + Members of aggregates. +'SYS' + Operating system features. +'TYPE' + C builtin or declared types. +'VAR' + C variables in libraries. + + After the category comes the name of the particular feature being +tested. Any further words in the macro name indicate particular aspects +of the feature. For example, 'AC_FUNC_UTIME_NULL' checks the behavior +of the 'utime' function when called with a 'NULL' pointer. + + An internal macro should have a name that starts with an underscore; +Autoconf internals should therefore start with '_AC_'. Additionally, a +macro that is an internal subroutine of another macro should have a name +that starts with an underscore and the name of that other macro, +followed by one or more words saying what the internal macro does. For +example, 'AC_PATH_X' has internal macros '_AC_PATH_X_XMKMF' and +'_AC_PATH_X_DIRECT'. + + +File: autoconf.info, Node: Reporting Messages, Next: Dependencies Between Macros, Prev: Macro Names, Up: Writing Autoconf Macros + +9.3 Reporting Messages +====================== + +When macros statically diagnose abnormal situations, benign or fatal, +they should report them using these macros. For dynamic issues, i.e., +when 'configure' is run, see *note Printing Messages::. + + -- Macro: AC_DIAGNOSE (CATEGORY, MESSAGE) + Report MESSAGE as a warning (or as an error if requested by the + user) if it falls into the CATEGORY. You are encouraged to use + standard categories, which currently include: + + 'all' + messages that don't fall into one of the following category. + Use of an empty CATEGORY is equivalent. + + 'cross' + related to cross compilation issues. + + 'obsolete' + use of an obsolete construct. + + 'syntax' + dubious syntactic constructs, incorrectly ordered macro calls. + + -- Macro: AC_WARNING (MESSAGE) + Equivalent to 'AC_DIAGNOSE([syntax], MESSAGE)', but you are + strongly encouraged to use a finer grained category. + + -- Macro: AC_FATAL (MESSAGE) + Report a severe error MESSAGE, and have 'autoconf' die. + + When the user runs 'autoconf -W error', warnings from 'AC_DIAGNOSE' +and 'AC_WARNING' are reported as error, see *note autoconf Invocation::. + + +File: autoconf.info, Node: Dependencies Between Macros, Next: Obsoleting Macros, Prev: Reporting Messages, Up: Writing Autoconf Macros + +9.4 Dependencies Between Macros +=============================== + +Some Autoconf macros depend on other macros having been called first in +order to work correctly. Autoconf provides a way to ensure that certain +macros are called if needed and a way to warn the user if macros are +called in an order that might cause incorrect operation. + +* Menu: + +* Prerequisite Macros:: Ensuring required information +* Suggested Ordering:: Warning about possible ordering problems + + +File: autoconf.info, Node: Prerequisite Macros, Next: Suggested Ordering, Prev: Dependencies Between Macros, Up: Dependencies Between Macros + +9.4.1 Prerequisite Macros +------------------------- + +A macro that you write might need to use values that have previously +been computed by other macros. For example, 'AC_DECL_YYTEXT' examines +the output of 'flex' or 'lex', so it depends on 'AC_PROG_LEX' having +been called first to set the shell variable 'LEX'. + + Rather than forcing the user of the macros to keep track of the +dependencies between them, you can use the 'AC_REQUIRE' macro to do it +automatically. 'AC_REQUIRE' can ensure that a macro is only called if +it is needed, and only called once. + + -- Macro: AC_REQUIRE (MACRO-NAME) + If the M4 macro MACRO-NAME has not already been called, call it + (without any arguments). Make sure to quote MACRO-NAME with square + brackets. MACRO-NAME must have been defined using 'AC_DEFUN' or + else contain a call to 'AC_PROVIDE' to indicate that it has been + called. + + 'AC_REQUIRE' must be used inside an 'AC_DEFUN''d macro; it must not + be called from the top level. + + 'AC_REQUIRE' is often misunderstood. It really implements +dependencies between macros in the sense that if one macro depends upon +another, the latter will be expanded _before_ the body of the former. +In particular, 'AC_REQUIRE(FOO)' is not replaced with the body of 'FOO'. +For instance, this definition of macros: + + AC_DEFUN([TRAVOLTA], + [test "$body_temparature_in_celsius" -gt "38" && + dance_floor=occupied]) + AC_DEFUN([NEWTON_JOHN], + [test "$hair_style" = "curly" && + dance_floor=occupied]) + + AC_DEFUN([RESERVE_DANCE_FLOOR], + [if date | grep '^Sat.*pm' >/dev/null 2>&1; then + AC_REQUIRE([TRAVOLTA]) + AC_REQUIRE([NEWTON_JOHN]) + fi]) + +with this 'configure.ac' + + AC_INIT + RESERVE_DANCE_FLOOR + if test "$dance_floor" = occupied; then + AC_MSG_ERROR([cannot pick up here, let's move]) + fi + +will not leave you with a better chance to meet a kindred soul at other +times than Saturday night since it expands into: + + test "$body_temperature_in_Celsius" -gt "38" && + dance_floor=occupied + test "$hair_style" = "curly" && + dance_floor=occupied + fi + if date | grep '^Sat.*pm' >/dev/null 2>&1; then + + + fi + + This behavior was chosen on purpose: (i) it prevents messages in +required macros from interrupting the messages in the requiring macros; +(ii) it avoids bad surprises when shell conditionals are used, as in: + + if ...; then + AC_REQUIRE([SOME_CHECK]) + fi + ... + SOME_CHECK + + You are encouraged to put all 'AC_REQUIRE's at the beginning of a +macro. You can use 'dnl' to avoid the empty lines they leave. + + +File: autoconf.info, Node: Suggested Ordering, Prev: Prerequisite Macros, Up: Dependencies Between Macros + +9.4.2 Suggested Ordering +------------------------ + +Some macros should be run before another macro if both are called, but +neither _requires_ that the other be called. For example, a macro that +changes the behavior of the C compiler should be called before any +macros that run the C compiler. Many of these dependencies are noted in +the documentation. + + Autoconf provides the 'AC_BEFORE' macro to warn users when macros +with this kind of dependency appear out of order in a 'configure.ac' +file. The warning occurs when creating 'configure' from 'configure.ac', +not when running 'configure'. + + For example, 'AC_PROG_CPP' checks whether the C compiler can run the +C preprocessor when given the '-E' option. It should therefore be +called after any macros that change which C compiler is being used, such +as 'AC_PROG_CC'. So 'AC_PROG_CC' contains: + + AC_BEFORE([$0], [AC_PROG_CPP])dnl + +This warns the user if a call to 'AC_PROG_CPP' has already occurred when +'AC_PROG_CC' is called. + + -- Macro: AC_BEFORE (THIS-MACRO-NAME, CALLED-MACRO-NAME) + Make 'm4' print a warning message to the standard error output if + CALLED-MACRO-NAME has already been called. THIS-MACRO-NAME should + be the name of the macro that is calling 'AC_BEFORE'. The macro + CALLED-MACRO-NAME must have been defined using 'AC_DEFUN' or else + contain a call to 'AC_PROVIDE' to indicate that it has been called. + + +File: autoconf.info, Node: Obsoleting Macros, Next: Coding Style, Prev: Dependencies Between Macros, Up: Writing Autoconf Macros + +9.5 Obsoleting Macros +===================== + +Configuration and portability technology has evolved over the years. +Often better ways of solving a particular problem are developed, or +ad-hoc approaches are systematized. This process has occurred in many +parts of Autoconf. One result is that some of the macros are now +considered "obsolete"; they still work, but are no longer considered the +best thing to do, hence they should be replaced with more modern macros. +Ideally, 'autoupdate' should substitute the old macro calls with their +modern implementation. + + Autoconf provides a simple means to obsolete a macro. + + -- Macro: AU_DEFUN (OLD-MACRO, IMPLEMENTATION, [MESSAGE]) + Define OLD-MACRO as IMPLEMENTATION. The only difference with + 'AC_DEFUN' is that the user will be warned that OLD-MACRO is now + obsolete. + + If she then uses 'autoupdate', the call to OLD-MACRO will be + replaced by the modern IMPLEMENTATION. The additional MESSAGE is + then printed. + + +File: autoconf.info, Node: Coding Style, Prev: Obsoleting Macros, Up: Writing Autoconf Macros + +9.6 Coding Style +================ + +The Autoconf macros follow a strict coding style. You are encouraged to +follow this style, especially if you intend to distribute your macro, +either by contributing it to Autoconf itself, or via other means. + + The first requirement is to pay great attention to the quotation, for +more details, see *note Autoconf Language::, and *note M4 Quotation::. + + Do not try to invent new interfaces. It is likely that there is a +macro in Autoconf that resembles the macro you are defining: try to +stick to this existing interface (order of arguments, default values, +etc.). We _are_ conscious that some of these interfaces are not +perfect; nevertheless, when harmless, homogeneity should be preferred +over creativity. + + Be careful about clashes both between M4 symbols and between shell +variables. + + If you stick to the suggested M4 naming scheme (*note Macro Names::), +you are unlikely to generate conflicts. Nevertheless, when you need to +set a special value, _avoid using a regular macro name_; rather, use an +"impossible" name. For instance, up to version 2.13, the macro +'AC_SUBST' used to remember what SYMBOLs were already defined by setting +'AC_SUBST_SYMBOL', which is a regular macro name. But since there is a +macro named 'AC_SUBST_FILE', it was just impossible to 'AC_SUBST(FILE)'! +In this case, 'AC_SUBST(SYMBOL)' or '_AC_SUBST(SYMBOL)' should have been +used (yes, with the parentheses)...or better yet, high-level macros such +as 'AC_EXPAND_ONCE'. + + No Autoconf macro should ever enter the user-variable name space; +i.e., except for the variables that are the actual result of running the +macro, all shell variables should start with 'ac_'. In addition, small +macros or any macro that is likely to be embedded in other macros should +be careful not to use obvious names. + + Do not use 'dnl' to introduce comments: most of the comments you are +likely to write are either header comments which are not output anyway, +or comments that should make their way into 'configure'. There are +exceptional cases where you do want to comment special M4 constructs, in +which case 'dnl' is right, but keep in mind that it is unlikely. + + M4 ignores the leading spaces before each argument, use this feature +to indent in such a way that arguments are (more or less) aligned with +the opening parenthesis of the macro being called. For instance, +instead of + + AC_CACHE_CHECK(for EMX OS/2 environment, + ac_cv_emxos2, + [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])], + [ac_cv_emxos2=yes], [ac_cv_emxos2=no])]) + +write + + AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], + [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) + +or even + + AC_CACHE_CHECK([for EMX OS/2 environment], + [ac_cv_emxos2], + [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], + [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) + + When using 'AC_TRY_RUN' or any macro that cannot work when +cross-compiling, provide a pessimistic value (typically 'no'). + + Feel free to use various tricks to prevent auxiliary tools, such as +syntax-highlighting editors, from behaving improperly. For instance, +instead of: + + patsubst([$1], [$"]) + +use + + patsubst([$1], [$""]) + +so that Emacsen do not open a endless "string" at the first quote. For +the same reasons, avoid: + + test $[#] != 0 + +and use: + + test $[@%:@] != 0 + +Otherwise, the closing bracket would be hidden inside a '#'-comment, +breaking the bracket-matching highlighting from Emacsen. Note the +preferred style to escape from M4: '$[1]', '$[@]', etc. Do not escape +when it is unneeded. Common examples of useless quotation are '[$]$1' +(write '$$1'), '[$]var' (use '$var'), etc. If you add portability +issues to the picture, you'll prefer '${1+"$[@]"}' to '"[$]@"', and +you'll prefer do something better than hacking Autoconf ':-)'. + + When using 'sed', don't use '-e' except for indenting purpose. With +the 's' command, the preferred separator is '/' unless '/' itself is +used in the command, in which case you should use ','. + + *Note Macro Definitions::, for details on how to define a macro. If +a macro doesn't use 'AC_REQUIRE' and it is expected to never be the +object of an 'AC_REQUIRE' directive, then use 'define'. In case of +doubt, use 'AC_DEFUN'. All the 'AC_REQUIRE' statements should be at the +beginning of the macro, 'dnl''ed. + + You should not rely on the number of arguments: instead of checking +whether an argument is missing, test that it is not empty. It provides +both a simpler and a more predictable interface to the user, and saves +room for further arguments. + + Unless the macro is short, try to leave the closing '])' at the +beginning of a line, followed by a comment that repeats the name of the +macro being defined. This introduces an additional newline in +'configure'; normally, that is not a problem, but if you want to remove +it you can use '[]dnl' on the last line. You can similarly use '[]dnl' +after a macro call to remove its newline. '[]dnl' is recommended +instead of 'dnl' to ensure that M4 does not interpret the 'dnl' as being +attached to the preceding text or macro output. For example, instead +of: + + AC_DEFUN([AC_PATH_X], + [AC_MSG_CHECKING([for X]) + AC_REQUIRE_CPP() + # ...omitted... + AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) + fi]) + +you would write: + + AC_DEFUN([AC_PATH_X], + [AC_REQUIRE_CPP()[]dnl + AC_MSG_CHECKING([for X]) + # ...omitted... + AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) + fi[]dnl + ])# AC_PATH_X + + If the macro is long, try to split it into logical chunks. +Typically, macros that check for a bug in a function and prepare its +'AC_LIBOBJ' replacement should have an auxiliary macro to perform this +setup. Do not hesitate to introduce auxiliary macros to factor your +code. + + In order to highlight the recommended coding style, here is a macro +written the old way: + + dnl Check for EMX on OS/2. + dnl _AC_EMXOS2 + AC_DEFUN(_AC_EMXOS2, + [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, + [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], + ac_cv_emxos2=yes, ac_cv_emxos2=no)]) + test "$ac_cv_emxos2" = yes && EMXOS2=yes]) + +and the new way: + + # _AC_EMXOS2 + # ---------- + # Check for EMX on OS/2. + define([_AC_EMXOS2], + [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], + [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) + test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl + ])# _AC_EMXOS2 + + +File: autoconf.info, Node: Portable Shell, Next: Manual Configuration, Prev: Writing Autoconf Macros, Up: Top + +10 Portable Shell Programming +***************************** + +When writing your own checks, there are some shell-script programming +techniques you should avoid in order to make your code portable. The +Bourne shell and upward-compatible shells like the Korn shell and Bash +have evolved over the years, but to prevent trouble, do not take +advantage of features that were added after UNIX version 7, circa 1977. +You should not use shell functions, aliases, negated character classes, +or other features that are not found in all Bourne-compatible shells; +restrict yourself to the lowest common denominator. Even 'unset' is not +supported by all shells! Also, include a space after the exclamation +point in interpreter specifications, like this: + + #! /usr/bin/perl + +If you omit the space before the path, then 4.2BSD based systems (such +as Sequent DYNIX) will ignore the line, because they interpret '#! /' as +a 4-byte magic number. + + The set of external programs you should run in a 'configure' script +is fairly small. *Note Utilities in Makefiles: (standards)Utilities in +Makefiles, for the list. This restriction allows users to start out +with a fairly small set of programs and build the rest, avoiding too +many interdependencies between packages. + + Some of these external utilities have a portable subset of features; +see *note Limitations of Usual Tools::. + +* Menu: + +* Shellology:: A zoology of shells +* Here-Documents:: Quirks and tricks +* File Descriptors:: FDs and redirections +* File System Conventions:: File- and pathnames +* Shell Substitutions:: Variable and command expansions +* Assignments:: Varying side effects of assignments +* Special Shell Variables:: Variables you should not change +* Limitations of Builtins:: Portable use of not so portable /bin/sh +* Limitations of Usual Tools:: Portable use of portable tools +* Limitations of Make:: Portable Makefiles + + +File: autoconf.info, Node: Shellology, Next: Here-Documents, Prev: Portable Shell, Up: Portable Shell + +10.1 Shellology +=============== + +There are several families of shells, most prominently the Bourne family +and the C shell family which are deeply incompatible. If you want to +write portable shell scripts, avoid members of the C shell family. + + Below we describe some of the members of the Bourne shell family. + +Ash + 'ash' is often used on GNU/Linux and BSD systems as a light-weight + Bourne-compatible shell. Ash 0.2 has some bugs that are fixed in + the 0.3.x series, but portable shell scripts should workaround + them, since version 0.2 is still shipped with many GNU/Linux + distributions. + + To be compatible with Ash 0.2: + + - don't use '$?' after expanding empty or unset variables: + + foo= + false + $foo + echo "Don't use it: $?" + + - don't use command substitution within variable expansion: + + cat ${FOO=`bar`} + + - beware that single builtin substitutions are not performed by + a sub shell, hence their effect applies to the current shell! + *Note Shell Substitutions::, item "Command Substitution". + +Bash + To detect whether you are running 'bash', test if 'BASH_VERSION' is + set. To disable its extensions and require POSIX compatibility, + run 'set -o posix'. *Note Bash POSIX Mode: (bash)Bash POSIX Mode, + for details. + +'/usr/xpg4/bin/sh' on Solaris + The POSIX-compliant Bourne shell on a Solaris system is + '/usr/xpg4/bin/sh' and is part of an extra optional package. There + is no extra charge for this package, but it is also not part of a + minimal OS install and therefore some folks may not have it. + +Zsh + To detect whether you are running 'zsh', test if 'ZSH_VERSION' is + set. By default 'zsh' is _not_ compatible with the Bourne shell: + you have to run 'emulate sh' and set 'NULLCMD' to ':'. *Note + Compatibility: (zsh)Compatibility, for details. + + Zsh 3.0.8 is the native '/bin/sh' on Mac OS X 10.0.3. + + The following discussion between Russ Allbery and Robert Lipe is +worth reading: + +Russ Allbery: + + The GNU assumption that '/bin/sh' is the one and only shell leads + to a permanent deadlock. Vendors don't want to break user's + existent shell scripts, and there are some corner cases in the + Bourne shell that are not completely compatible with a POSIX shell. + Thus, vendors who have taken this route will _never_ (OK..."never + say never") replace the Bourne shell (as '/bin/sh') with a POSIX + shell. + +Robert Lipe: + + This is exactly the problem. While most (at least most System V's) + do have a bourne shell that accepts shell functions most vendor + '/bin/sh' programs are not the POSIX shell. + + So while most modern systems do have a shell _somewhere_ that meets + the POSIX standard, the challenge is to find it. + + +File: autoconf.info, Node: Here-Documents, Next: File Descriptors, Prev: Shellology, Up: Portable Shell + +10.2 Here-Documents +=================== + +Don't rely on '\' being preserved just because it has no special meaning +together with the next symbol. in the native '/bin/sh' on OpenBSD 2.7 +'\"' expands to '"' in here-documents with unquoted delimiter. As a +general rule, if '\\' expands to '\' use '\\' to get '\'. + + With OpenBSD 2.7's '/bin/sh' + + $ cat <<EOF + > \" \\ + > EOF + " \ + +and with Bash: + + bash-2.04$ cat <<EOF + > \" \\ + > EOF + \" \ + + Many older shells (including the Bourne shell) implement +here-documents inefficiently. Users can generally speed things up by +using a faster shell, e.g., by using the command 'bash ./configure' +rather than plain './configure'. + + Some shells can be extremely inefficient when there are a lot of +here-documents inside a single statement. For instance if your +'configure.ac' includes something like: + + if <cross_compiling>; then + assume this and that + else + check this + check that + check something else + ... + on and on forever + ... + fi + + A shell parses the whole 'if'/'fi' construct, creating temporary +files for each here document in it. Some shells create links for such +here-documents on every 'fork', so that the clean-up code they had +installed correctly removes them. It is creating the links that the +shell can take forever. + + Moving the tests out of the 'if'/'fi', or creating multiple 'if'/'fi' +constructs, would improve the performance significantly. Anyway, this +kind of construct is not exactly the typical use of Autoconf. In fact, +it's even not recommended, because M4 macros can't look into shell +conditionals, so we may fail to expand a macro when it was expanded +before in a conditional path, and the condition turned out to be false +at run-time, and we end up not executing the macro at all. + + +File: autoconf.info, Node: File Descriptors, Next: File System Conventions, Prev: Here-Documents, Up: Portable Shell + +10.3 File Descriptors +===================== + +Some file descriptors shall not be used, since some systems, admittedly +arcane, use them for special purpose: + +3 + some systems may open it to '/dev/tty'. + +4 + used on the Kubota Titan. + + Don't redirect several times the same file descriptor, as you are +doomed to failure under Ultrix. + + ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 + UWS V4.4 (Rev. 11) + $ eval 'echo matter >fullness' >void + illegal io + $ eval '(echo matter >fullness)' >void + illegal io + $ (eval '(echo matter >fullness)') >void + Ambiguous output redirect. + +In each case the expected result is of course 'fullness' containing +'matter' and 'void' being empty. + + Don't try to redirect the standard error of a command substitution: +it must be done _inside_ the command substitution: when running ': `cd +/zorglub` 2>/dev/null' expect the error message to escape, while ': `cd +/zorglub 2>/dev/null`' works properly. + + It is worth noting that Zsh (but not Ash nor Bash) makes it possible +in assignments though: 'foo=`cd /zorglub` 2>/dev/null'. + + Most shells, if not all (including Bash, Zsh, Ash), output traces on +stderr, even for sub-shells. This might result in undesired content if +you meant to capture the standard-error output of the inner command: + + $ ash -x -c '(eval "echo foo >&2") 2>stderr' + $ cat stderr + + eval echo foo >&2 + + echo foo + foo + $ bash -x -c '(eval "echo foo >&2") 2>stderr' + $ cat stderr + + eval 'echo foo >&2' + ++ echo foo + foo + $ zsh -x -c '(eval "echo foo >&2") 2>stderr' + # Traces on startup files deleted here. + $ cat stderr + +zsh:1> eval echo foo >&2 + +zsh:1> echo foo + foo + +You'll appreciate the various levels of detail... + + One workaround is to grep out uninteresting lines, hoping not to +remove good ones... + + +File: autoconf.info, Node: File System Conventions, Next: Shell Substitutions, Prev: File Descriptors, Up: Portable Shell + +10.4 File System Conventions +============================ + +While 'autoconf' and friends will usually be run on some Unix variety, +it can and will be used on other systems, most notably DOS variants. +This impacts several assumptions regarding file and path names. + +For example, the following code: + + case $foo_dir in + /*) # Absolute + ;; + *) + foo_dir=$dots$foo_dir ;; + esac + +will fail to properly detect absolute paths on those systems, because +they can use a drivespec, and will usually use a backslash as directory +separator. The canonical way to check for absolute paths is: + + case $foo_dir in + [\\/]* | ?:[\\/]* ) # Absolute + ;; + *) + foo_dir=$dots$foo_dir ;; + esac + +Make sure you quote the brackets if appropriate and keep the backslash +as first character (*note Limitations of Builtins::). + + Also, because the colon is used as part of a drivespec, these systems +don't use it as path separator. When creating or accessing paths, use +'$ac_path_separator' instead (or the 'PATH_SEPARATOR' output variable). +'autoconf' sets this to the appropriate value (':' or ';') when it +starts up. + + File names need extra care as well. While DOS-based environments +that are Unixy enough to run 'autoconf' (such as DJGPP) will usually be +able to handle long file names properly, there are still limitations +that can seriously break packages. Several of these issues can be +easily detected by the doschk(1) package. + + A short overview follows; problems are marked with SFN/LFN to +indicate where they apply: SFN means the issues are only relevant to +plain DOS, not to DOS boxes under Windows, while LFN identifies problems +that exist even under Windows. + +No multiple dots (SFN) + DOS cannot handle multiple dots in filenames. This is an + especially important thing to remember when building a portable + configure script, as 'autoconf' uses a .in suffix for template + files. + + This is perfectly OK on Unices: + + AC_CONFIG_HEADER(config.h) + AC_CONFIG_FILES([source.c foo.bar]) + AC_OUTPUT + + but it causes problems on DOS, as it requires 'config.h.in', + 'source.c.in' and 'foo.bar.in'. To make your package more portable + to DOS-based environments, you should use this instead: + + AC_CONFIG_HEADER(config.h:config.hin) + AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) + AC_OUTPUT + +No leading dot (SFN) + DOS cannot handle filenames that start with a dot. This is usually + not a very important issue for 'autoconf'. + +Case insensitivity (LFN) + DOS is case insensitive, so you cannot, for example, have both a + file called 'INSTALL' and a directory called 'install'. This also + affects 'make'; if there's a file called 'INSTALL' in the + directory, 'make install' will do nothing (unless the 'install' + target is marked as PHONY). + +The 8+3 limit (SFN) + Because the DOS file system only stores the first 8 characters of + the filename and the first 3 of the extension, those must be + unique. That means that 'foobar-part1.c', 'foobar-part2.c' and + 'foobar-prettybird.c' all resolve to the same filename + ('FOOBAR-P.C'). The same goes for 'foo.bar' and 'foo.bartender'. + + Note: This is not usually a problem under Windows, as it uses + numeric tails in the short version of filenames to make them + unique. However, a registry setting can turn this behaviour off. + While this makes it possible to share file trees containing long + file names between SFN and LFN environments, it also means the + above problem applies there as well. + +Invalid characters + Some characters are invalid in DOS filenames, and should therefore + be avoided. In a LFN environment, these are '/', '\', '?', '*', + ':', '<', '>', '|' and '"'. In a SFN environment, other characters + are also invalid. These include '+', ',', '[' and ']'. + + ---------- Footnotes ---------- + + (1) doschk, <ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz>. + + +File: autoconf.info, Node: Shell Substitutions, Next: Assignments, Prev: File System Conventions, Up: Portable Shell + +10.5 Shell Substitutions +======================== + +Contrary to a persistent urban legend, the Bourne shell does not +systematically split variables and backquoted expressions, in particular +on the right-hand side of assignments and in the argument of 'case'. +For instance, the following code: + + case "$given_srcdir" in + .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" + *) top_srcdir="$dots$given_srcdir" ;; + esac + +is more readable when written as: + + case $given_srcdir in + .) top_srcdir=`echo "$dots" | sed 's,/$,,'` + *) top_srcdir=$dots$given_srcdir ;; + esac + +and in fact it is even _more_ portable: in the first case of the first +attempt, the computation of 'top_srcdir' is not portable, since not all +shells properly understand '"`..."..."...`"'. Worse yet, not all shells +understand '"`...\"...\"...`"' the same way. There is just no portable +way to use double-quoted strings inside double-quoted backquoted +expressions (pfew!). + +'$@' + One of the most famous shell-portability issues is related to + '"$@"': when there are no positional arguments, it is supposed to + be equivalent to nothing. But some shells, for instance under + Digital Unix 4.0 and 5.0, will then replace it with an empty + argument. To be portable, use '${1+"$@"}'. + +'${VAR:-VALUE}' + Old BSD shells, including the Ultrix 'sh', don't accept the colon + for any shell substitution, and complain and die. + +'${VAR=LITERAL}' + Be sure to quote: + + : ${var='Some words'} + + otherwise some shells, such as on Digital Unix V 5.0, will die + because of a "bad substitution". + + Solaris' '/bin/sh' has a frightening bug in its interpretation of + this. Imagine you need set a variable to a string containing '}'. + This '}' character confuses Solaris' '/bin/sh' when the affected + variable was already set. This bug can be exercised by running: + + $ unset foo + $ foo=${foo='}'} + $ echo $foo + } + $ foo=${foo='}' # no error; this hints to what the bug is + $ echo $foo + } + $ foo=${foo='}'} + $ echo $foo + }} + ^ ugh! + + It seems that '}' is interpreted as matching '${', even though it + is enclosed in single quotes. The problem doesn't happen using + double quotes. + +'${VAR=EXPANDED-VALUE}' + On Ultrix, running + + default="yu,yaa" + : ${var="$default"} + + will set VAR to 'M-yM-uM-,M-yM-aM-a', i.e., the 8th bit of each + char will be set. You won't observe the phenomenon using a simple + 'echo $var' since apparently the shell resets the 8th bit when it + expands $var. Here are two means to make this shell confess its + sins: + + $ cat -v <<EOF + $var + EOF + + and + + $ set | grep '^var=' | cat -v + + One classic incarnation of this bug is: + + default="a b c" + : ${list="$default"} + for c in $list; do + echo $c + done + + You'll get 'a b c' on a single line. Why? Because there are no + spaces in '$list': there are 'M- ', i.e., spaces with the 8th bit + set, hence no IFS splitting is performed!!! + + One piece of good news is that Ultrix works fine with ': + ${list=$default}'; i.e., if you _don't_ quote. The bad news is + then that QNX 4.25 then sets LIST to the _last_ item of DEFAULT! + + The portable way out consists in using a double assignment, to + switch the 8th bit twice on Ultrix: + + list=${list="$default"} + + ...but beware of the '}' bug from Solaris (see above). For safety, + use: + + test "${var+set}" = set || var={VALUE} + +'`COMMANDS`' + While in general it makes no sense, do not substitute a single + builtin with side effects as Ash 0.2, trying to optimize, does not + fork a sub-shell to perform the command. + + For instance, if you wanted to check that 'cd' is silent, do not + use 'test -z "`cd /`"' because the following can happen: + + $ pwd + /tmp + $ test -n "`cd /`" && pwd + / + + The result of 'foo=`exit 1`' is left as an exercise to the reader. + +'$(COMMANDS)' + This construct is meant to replace '`COMMANDS`'; they can be nested + while this is impossible to do portably with back quotes. + Unfortunately it is not yet widely supported. Most notably, even + recent releases of Solaris don't support it: + + $ showrev -c /bin/sh | grep version + Command version: SunOS 5.8 Generic 109324-02 February 2001 + $ echo $(echo blah) + syntax error: `(' unexpected + + nor does IRIX 6.5's Bourne shell: + $ uname -a + IRIX firebird-image 6.5 07151432 IP22 + $ echo $(echo blah) + $(echo blah) + + +File: autoconf.info, Node: Assignments, Next: Special Shell Variables, Prev: Shell Substitutions, Up: Portable Shell + +10.6 Assignments +================ + +When setting several variables in a row, be aware that the order of the +evaluation is undefined. For instance 'foo=1 foo=2; echo $foo' gives +'1' with sh on Solaris, but '2' with Bash. You must use ';' to enforce +the order: 'foo=1; foo=2; echo $foo'. + + Don't rely on the exit status of an assignment: Ash 0.2 does not +change the status and propagates that of the last statement: + + $ false || foo=bar; echo $? + 1 + $ false || foo=`:`; echo $? + 0 + +and to make things even worse, QNX 4.25 just sets the exit status to 0 +in any case: + + $ foo=`exit 1`; echo $? + 0 + + To assign default values, follow this algorithm: + + 1. If the default value is a literal and does not contain any closing + brace, use: + + : ${var='my literal'} + + 2. If the default value contains no closing brace, has to be expanded, + and the variable being initialized will never be IFS-split (i.e., + it's not a list), then use: + + : ${var="$default"} + + 3. If the default value contains no closing brace, has to be expanded, + and the variable being initialized will be IFS-split (i.e., it's a + list), then use: + + var=${var="$default"} + + 4. If the default value contains a closing brace, then use: + + test "${var+set}" = set || var='${indirection}' + + In most cases 'var=${var="$default"}' is fine, but in case of doubt, +just use the latter. *Note Shell Substitutions::, items '${VAR:-VALUE}' +and '${VAR=VALUE}' for the rationale. + + +File: autoconf.info, Node: Special Shell Variables, Next: Limitations of Builtins, Prev: Assignments, Up: Portable Shell + +10.7 Special Shell Variables +============================ + +Some shell variables should not be used, since they can have a deep +influence on the behavior of the shell. In order to recover a sane +behavior from the shell, some variables should be unset, but 'unset' is +not portable (*note Limitations of Builtins::) and a fallback value is +needed. We list these values below. + +'CDPATH' + When this variable is set 'cd' is verbose, so idioms such as + 'abs=`cd $rel && pwd`' break because 'abs' receives the path twice. + + Setting 'CDPATH' to the empty value is not enough for most shells. + A simple colon is enough except for 'zsh', which prefers a leading + dot: + + zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo) + /tmp/foo + zsh-3.1.6 % (CDPATH=:. cd foo) + /tmp/foo + zsh-3.1.6 % (CDPATH=.: cd foo) + zsh-3.1.6 % + + (of course we could just 'unset' 'CDPATH', since it also behaves + properly if set to the empty string). + + Life wouldn't be so much fun if 'bash' and 'zsh' had the same + behavior: + + bash-2.02 % (CDPATH=:. cd foo) + bash-2.02 % (CDPATH=.: cd foo) + /tmp/foo + + Therefore, a portable solution to neutralize 'CDPATH' is + + CDPATH=${ZSH_VERSION+.}: + + Note that since 'zsh' supports 'unset', you may unset 'CDPATH' + using ':' as a fallback, see *note Limitations of Builtins::. + +'IFS' + Don't set the first character of 'IFS' to backslash. Indeed, + Bourne shells use the first character (backslash) when joining the + components in '"$@"' and some shells then re-interpret (!) the + backslash escapes, so you can end up with backspace and other + strange characters. + +'LANG' +'LC_ALL' +'LC_TIME' +'LC_CTYPE' +'LANGUAGE' +'LC_COLLATE' +'LC_NUMERIC' +'LC_MESSAGES' + + These must not be set unconditionally because not all systems + understand e.g. 'LANG=C' (notably SCO). Fixing 'LC_MESSAGES' + prevents Solaris 'sh' from translating var values in 'set'! Non-C + 'LC_CTYPE' values break the ctype check. Fixing 'LC_COLLATE' makes + scripts more portable in some cases. For example, it causes the + regular expression '[a-z]' to match only lower-case letters on + ASCII platforms. However, '[a-z]' does not work in general even + when 'LC_COLLATE' is fixed; for example, it does not work for + EBCDIC platforms. For maximum portability, you should use regular + expressions like '[abcdefghijklmnopqrstuvwxyz]' that list + characters explicitly instead of relying on ranges. + + _If_ one of these variables is set, you should try to unset it, + using 'C' as a fall back value. see *note Limitations of + Builtins::, builtin 'unset', for more details. + +'NULLCMD' + When executing the command '>foo', 'zsh' executes '$NULLCMD >foo'. + The Bourne shell considers 'NULLCMD' is ':', while 'zsh', even in + Bourne shell compatibility mode, sets 'NULLCMD' to 'cat'. If you + forgot to set 'NULLCMD', your script might be suspended waiting for + data on its standard input. + +'status' + This variable is an alias to '$?' for 'zsh' (at least 3.1.6), hence + read-only. Do not use it. + +'PATH_SEPARATOR' + On DJGPP systems, the 'PATH_SEPARATOR' variable can be set to + either ':' or ';' to control the path separator 'bash' uses to set + up certain environment variables (such as 'PATH'). Since this only + works inside bash, you want autoconf to detect the regular DOS path + separator ';', so it can be safely substituted in files that may + not support ';' as path separator. So either unset this variable + or set it to ';'. + +'RANDOM' + Many shells provide 'RANDOM', a variable that returns a different + integer when used. Most of the time, its value does not change + when it is not used, but on IRIX 6.5 the value changes all the + time. This can be observed by using 'set'. + + +File: autoconf.info, Node: Limitations of Builtins, Next: Limitations of Usual Tools, Prev: Special Shell Variables, Up: Portable Shell + +10.8 Limitations of Shell Builtins +================================== + +No, no, we are serious: some shells do have limitations! :) + + You should always keep in mind that any built-in or command may +support options, and therefore have a very different behavior with +arguments starting with a dash. For instance, the innocent 'echo +"$word"' can give unexpected results when 'word' starts with a dash. It +is often possible to avoid this problem using 'echo "x$word"', taking +the 'x' into account later in the pipe. + +'!' + You can't use '!', you'll have to rewrite your code. + +'break' + The use of 'break 2', etcetera, is safe. + +'case' + You don't need to quote the argument; no splitting is performed. + + You don't need the final ';;', but you should use it. + + Because of a bug in its 'fnmatch', 'bash' fails to properly handle + backslashes in character classes: + + bash-2.02$ case /tmp in [/\\]*) echo OK;; esac + bash-2.02$ + + This is extremely unfortunate, since you are likely to use this + code to handle UNIX or MS-DOS absolute paths. To work around this + bug, always put the backslash first: + + bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac + OK + bash-2.02$ case /tmp in [\\/]*) echo OK;; esac + OK + +'echo' + The simple 'echo' is probably the most surprising source of + portability troubles. It is not possible to use 'echo' portably + unless both options and escape sequences are omitted. New + applications which are not aiming at portability should use + 'printf' instead of 'echo'. + + Don't expect any option. *Note Preset Output Variables::, 'ECHO_N' + etc. for a means to simulate '-c'. + + Do not use backslashes in the arguments, as there is no consensus + on their handling. On 'echo '\n' | wc -l', the 'sh' of Digital + Unix 4.0, MIPS RISC/OS 4.52, answer 2, but the Solaris' 'sh', Bash + and Zsh (in 'sh' emulation mode) report 1. Please note that the + problem is truly 'echo': all the shells understand ''\n'' as the + string composed of a backslash and an 'n'. + + Because of these problems, do not pass a string containing + arbitrary characters to 'echo'. For example, 'echo "$foo"' is safe + if you know that FOO's value cannot contain backslashes and cannot + start with '-', but otherwise you should use a here-document like + this: + + cat <<EOF + $foo + EOF + +'exit' + The default value of 'exit' is supposed to be '$?'; unfortunately, + some shells, such as the DJGPP port of Bash 2.04, just perform + 'exit 0'. + + bash-2.04$ foo=`exit 1` || echo fail + fail + bash-2.04$ foo=`(exit 1)` || echo fail + fail + bash-2.04$ foo=`(exit 1); exit` || echo fail + bash-2.04$ + + Using 'exit $?' restores the expected behavior. + + Some shell scripts, such as those generated by 'autoconf', use a + trap to clean up before exiting. If the last shell command exited + with nonzero status, the trap also exits with nonzero status so + that the invoker can tell that an error occurred. + + Unfortunately, in some shells, such as Solaris 8 'sh', an exit trap + ignores the 'exit' command's status. In these shells, a trap + cannot determine whether it was invoked by plain 'exit' or by 'exit + 1'. Instead of calling 'exit' directly, use the 'AC_MSG_ERROR' + macro that has a workaround for this problem. + +'export' + The builtin 'export' dubs "environment variable" a shell variable. + Each update of exported variables corresponds to an update of the + environment variables. Conversely, each environment variable + received by the shell when it is launched should be imported as a + shell variable marked as exported. + + Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX + 4.1.5 and DU 4.0, forget to 'export' the environment variables they + receive. As a result, two variables are coexisting: the + environment variable and the shell variable. The following code + demonstrates this failure: + + #! /bin/sh + echo $FOO + FOO=bar + echo $FOO + exec /bin/sh $0 + + when run with 'FOO=foo' in the environment, these shells will print + alternately 'foo' and 'bar', although it should only print 'foo' + and then a sequence of 'bar's. + + Therefore you should 'export' again each environment variable that + you update. + +'false' + Don't expect 'false' to exit with status 1: in the native Bourne + shell of Solaris 8, it exits with status 255. + +'for' + To loop over positional arguments, use: + + for arg + do + echo "$arg" + done + + You may _not_ leave the 'do' on the same line as 'for', since some + shells improperly grok: + + for arg; do + echo "$arg" + done + + If you want to explicitly refer to the positional arguments, given + the '$@' bug (*note Shell Substitutions::), use: + + for arg in ${1+"$@"}; do + echo "$arg" + done + +'if' + Using '!' is not portable. Instead of: + + if ! cmp -s file file.new; then + mv file.new file + fi + + use: + + if cmp -s file file.new; then :; else + mv file.new file + fi + + There are shells that do not reset the exit status from an 'if': + + $ if (exit 42); then true; fi; echo $? + 42 + + whereas a proper shell should have printed '0'. This is especially + bad in Makefiles since it produces false failures. This is why + properly written Makefiles, such as Automake's, have such hairy + constructs: + + if test -f "$file"; then + install "$file" "$dest" + else + : + fi + +'set' + This builtin faces the usual problem with arguments starting with a + dash. Modern shells such as Bash or Zsh understand '--' to specify + the end of the options (any argument after '--' is a parameters, + even '-x' for instance), but most shells simply stop the option + processing as soon as a non-option argument is found. Therefore, + use 'dummy' or simply 'x' to end the option processing, and use + 'shift' to pop it out: + + set x $my_list; shift + +'shift' + Not only is 'shift'ing a bad idea when there is nothing left to + shift, but in addition it is not portable: the shell of MIPS + RISC/OS 4.52 refuses to do it. + +'test' + The 'test' program is the way to perform many file and string + tests. It is often invoked by the alternate name '[', but using + that name in Autoconf code is asking for trouble since it is an M4 + quote character. + + If you need to make multiple checks using 'test', combine them with + the shell operators '&&' and '||' instead of using the 'test' + operators '-a' and '-o'. On System V, the precedence of '-a' and + '-o' is wrong relative to the unary operators; consequently, POSIX + does not specify them, so using them is nonportable. If you + combine '&&' and '||' in the same statement, keep in mind that they + have equal precedence. + + You may use '!' with 'test', but not with 'if': 'test ! -r foo || + exit 1'. + +'test' (files) + To enable 'configure' scripts to support cross-compilation, they + shouldn't do anything that tests features of the build system + instead of the host system. But occasionally you may find it + necessary to check whether some arbitrary file exists. To do so, + use 'test -f' or 'test -r'. Do not use 'test -x', because 4.3BSD + does not have it. Do not use 'test -e' either, because Solaris 2.5 + does not have it. + +'test' (strings) + Avoid 'test "STRING"', in particular if STRING might start with a + dash, since 'test' might interpret its argument as an option (e.g., + 'STRING = "-n"'). + + Contrary to a common belief, 'test -n STRING' and 'test -z STRING' + *are* portable, nevertheless many shells (such as Solaris 2.5, AIX + 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have bizarre precedence + and may be confused if STRING looks like an operator: + + $ test -n = + test: argument expected + + If there are risks, use 'test "xSTRING" = x' or 'test "xSTRING" != + x' instead. + + It is frequent to find variations of the following idiom: + + test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && + ACTION + + to take an action when a token matches a given pattern. Such + constructs should always be avoided by using: + + echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 && + ACTION + + Use 'case' where possible since it is faster, being a shell + builtin: + + case $ac_feature in + *[!-a-zA-Z0-9_]*) ACTION;; + esac + + Alas, negated character classes are probably not portable, although + no shell is known to not support the POSIX.2 syntax '[!...]' (when + in interactive mode, 'zsh' is confused by the '[!...]' syntax and + looks for an event in its history because of '!'). Many shells do + not support the alternative syntax '[^...]' (Solaris, Digital Unix, + etc.). + + One solution can be: + + expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && + ACTION + + or better yet + + expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && + ACTION + + 'expr "XFOO" : "XBAR"' is more robust than 'echo "XFOO" | grep + "^XBAR"', because it avoids problems when 'FOO' contains + backslashes. + +'trap' + It is safe to trap at least the signals 1, 2, 13 and 15. You can + also trap 0, i.e., have the 'trap' run when the script ends (either + via an explicit 'exit', or the end of the script). + + Although POSIX is not absolutely clear on this point, it is widely + admitted that when entering the trap '$?' should be set to the exit + status of the last command run before the trap. The ambiguity can + be summarized as: "when the trap is launched by an 'exit', what is + the _last_ command run: that before 'exit', or 'exit' itself?" + + Bash considers 'exit' to be the last command, while Zsh and Solaris + 8 'sh' consider that when the trap is run it is _still_ in the + 'exit', hence it is the previous exit status that the trap + receives: + + $ cat trap.sh + trap 'echo $?' 0 + (exit 42); exit 0 + $ zsh trap.sh + 42 + $ bash trap.sh + 0 + + The portable solution is then simple: when you want to 'exit 42', + run '(exit 42); exit 42', the first 'exit' being used to set the + exit status to 42 for Zsh, and the second to trigger the trap and + pass 42 as exit status for Bash. + + The shell in FreeBSD 4.0 has the following bug: '$?' is reset to 0 + by empty lines if the code is inside 'trap'. + + $ trap 'false + + echo $?' 0 + $ exit + 0 + + Fortunately, this bug only affects 'trap'. + +'true' + Don't worry: as far as we know 'true' is portable. Nevertheless, + it's not always a builtin (e.g., Bash 1.x), and the portable shell + community tends to prefer using ':'. This has a funny side effect: + when asked whether 'false' is more portable than 'true' Alexandre + Oliva answered: + + In a sense, yes, because if it doesn't exist, the shell will + produce an exit status of failure, which is correct for + 'false', but not for 'true'. + +'unset' + You cannot assume the support of 'unset', nevertheless, because it + is extremely useful to disable embarrassing variables such as + 'CDPATH' or 'LANG', you can test for its existence and use it + _provided_ you give a neutralizing value when 'unset' is not + supported: + + if (unset FOO) >/dev/null 2>&1; then + unset=unset + else + unset=false + fi + $unset CDPATH || CDPATH=: + + *Note Special Shell Variables::, for some neutralizing values. + Also, see *note Limitations of Builtins::, documentation of + 'export', for the case of environment variables. + + +File: autoconf.info, Node: Limitations of Usual Tools, Next: Limitations of Make, Prev: Limitations of Builtins, Up: Portable Shell + +10.9 Limitations of Usual Tools +=============================== + +The small set of tools you can expect to find on any machine can still +include some limitations you should be aware of. + +'awk' + Don't leave white spaces before the parentheses in user functions + calls, GNU awk will reject it: + + $ gawk 'function die () { print "Aaaaarg!" } + BEGIN { die () }' + gawk: cmd. line:2: BEGIN { die () } + gawk: cmd. line:2: ^ parse error + $ gawk 'function die () { print "Aaaaarg!" } + BEGIN { die() }' + Aaaaarg! + + If you want your program to be deterministic, don't depend on 'for' + on arrays: + + $ cat for.awk + END { + arr["foo"] = 1 + arr["bar"] = 1 + for (i in arr) + print i + } + $ gawk -f for.awk </dev/null + foo + bar + $ nawk -f for.awk </dev/null + bar + foo + + Some AWK, such as HPUX 11.0's native one, have regex engines + fragile to inner anchors: + + $ echo xfoo | $AWK '/foo|^bar/ { print }' + $ echo bar | $AWK '/foo|^bar/ { print }' + bar + $ echo xfoo | $AWK '/^bar|foo/ { print }' + xfoo + $ echo bar | $AWK '/^bar|foo/ { print }' + bar + + Either do not depend on such patterns (i.e., use '/^(.*foo|bar)/', + or use a simple test to reject such AWK. + +'cat' + Don't rely on any option. The option '-v', which displays + non-printing characters, _seems_ portable, though. + +'cc' + When a compilation such as 'cc foo.c -o foo' fails, some compilers + (such as CDS on Reliant UNIX) leave a 'foo.o'. + +'cmp' + 'cmp' performs a raw data comparison of two files, while 'diff' + compares two text files. Therefore, if you might compare DOS + files, even if only checking whether two files are different, use + 'diff' to avoid spurious differences due to differences of newline + encoding. + +'cp' + SunOS 'cp' does not support '-f', although its 'mv' does. It's + possible to deduce why 'mv' and 'cp' are different with respect to + '-f'. 'mv' prompts by default before overwriting a read-only file. + 'cp' does not. Therefore, 'mv' requires a '-f' option, but 'cp' + does not. 'mv' and 'cp' behave differently with respect to + read-only files because the simplest form of 'cp' cannot overwrite + a read-only file, but the simplest form of 'mv' can. This is + because 'cp' opens the target for write access, whereas 'mv' simply + calls 'link' (or, in newer systems, 'rename'). + +'diff' + Option '-u' is nonportable. + + Some implementations, such as Tru64's, fail when comparing to + '/dev/null'. Use an empty file instead. + +'dirname' + Not all hosts have 'dirname', but it is reasonably easy to emulate, + e.g.: + + dir=`expr "x$file" : 'x\(.*\)/[^/]*' \| + '.' : '.' + + But there are a few subtilities, e.g., under UN*X, should '//1' + give '/'? Paul Eggert answers: + + No, under some older flavors of Unix, leading '//' is a + special path name: it refers to a "super-root" and is used to + access other machines' files. Leading '///', '////', etc. + are equivalent to '/'; but leading '//' is special. I think + this tradition started with Apollo Domain/OS, an OS that is + still in use on some older hosts. + + POSIX.2 allows but does not require the special treatment for + '//'. It says that the behavior of dirname on path names of + the form '//([^/]+/*)?' is implementation defined. In these + cases, GNU 'dirname' returns '/', but it's more portable to + return '//' as this works even on those older flavors of Unix. + + I have heard rumors that this special treatment of '//' may be + dropped in future versions of POSIX, but for now it's still + the standard. + +'egrep' + The empty alternative is not portable, use '?' instead. For + instance with Digital Unix v5.0: + + > printf "foo\n|foo\n" | egrep '^(|foo|bar)$' + |foo + > printf "bar\nbar|\n" | egrep '^(foo|bar|)$' + bar| + > printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$' + foo + |bar + + 'egrep' also suffers the limitations of 'grep'. + +'expr' + No 'expr' keyword starts with 'x', so use 'expr x"WORD" : 'xREGEX'' + to keep 'expr' from misinterpreting WORD. + + Don't use 'length', 'substr', 'match' and 'index'. + +'expr' ('|') + You can use '|'. Although POSIX does require that 'expr ''' return + the empty string, it does not specify the result when you '|' + together the empty string (or zero) with the empty string. For + example: + + expr '' \| '' + + GNU/Linux and POSIX.2-1992 return the empty string for this case, + but traditional Unix returns '0' (Solaris is one such example). In + the latest POSIX draft, the specification has been changed to match + traditional Unix's behavior (which is bizarre, but it's too late to + fix this). Please note that the same problem does arise when the + empty string results from a computation, as in: + + expr bar : foo \| foo : bar + + Avoid this portability problem by avoiding the empty string. + +'expr' (':') + Don't use '\?', '\+' and '\|' in patterns, they are not supported + on Solaris. + + The POSIX.2-1992 standard is ambiguous as to whether 'expr a : b' + (and 'expr 'a' : '\(b\)'') output '0' or the empty string. In + practice, it outputs the empty string on most platforms, but + portable scripts should not assume this. For instance, the QNX + 4.25 native 'expr' returns '0'. + + You may believe that one means to get a uniform behavior would be + to use the empty string as a default value: + + expr a : b \| '' + + unfortunately this behaves exactly as the original expression, see + the ''expr' (':')' entry for more information. + + Older 'expr' implementations (e.g. SunOS 4 'expr' and Solaris 8 + '/usr/ucb/expr') have a silly length limit that causes 'expr' to + fail if the matched substring is longer than 120 bytes. In this + case, you might want to fall back on 'echo|sed' if 'expr' fails. + + Don't leave, there is some more! + + The QNX 4.25 'expr', in addition of preferring '0' to the empty + string, has a funny behavior in its exit status: it's always 1 when + parentheses are used! + + $ val=`expr 'a' : 'a'`; echo "$?: $val" + 0: 1 + $ val=`expr 'a' : 'b'`; echo "$?: $val" + 1: 0 + + $ val=`expr 'a' : '\(a\)'`; echo "?: $val" + 1: a + $ val=`expr 'a' : '\(b\)'`; echo "?: $val" + 1: 0 + + In practice this can be a big problem if you are ready to catch + failures of 'expr' programs with some other method (such as using + 'sed'), since you may get twice the result. For instance + + $ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/' + + will output 'a' on most hosts, but 'aa' on QNX 4.25. A simple work + around consists in testing 'expr' and use a variable set to 'expr' + or to 'false' according to the result. + +'find' + The option '-maxdepth' seems to be GNU specific. Tru64 v5.1, + NetBSD 1.5 and Solaris 2.5 'find' commands do not understand it. + +'grep' + Don't use 'grep -s' to suppress output, because 'grep -s' on System + V does not suppress output, only error messages. Instead, redirect + the standard output and standard error (in case the file doesn't + exist) of 'grep' to '/dev/null'. Check the exit status of 'grep' + to determine whether it found a match. + + Don't use multiple regexps with '-e', as some 'grep' will only + honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway, + Stardent Vistra SVR4 'grep' lacks '-e'... Instead, use alternation + and 'egrep'. + +'ln' + Don't rely on 'ln' having a '-f' option. Symbolic links are not + available on old systems, use 'ln' as a fall back. + + For versions of the DJGPP before 2.04, 'ln' emulates soft links for + executables by generating a stub that in turn calls the real + program. This feature also works with nonexistent files like in + the Unix spec. So 'ln -s file link' will generate 'link.exe', + which will attempt to call 'file.exe' if run. But this feature + only works for executables, so 'cp -p' is used instead for these + systems. DJGPP versions 2.04 and later have full symlink support. + +'mv' + The only portable options are '-f' and '-i'. + + Moving individual files between file systems is portable (it was in + V6), but it is not always atomic: when doing 'mv new existing', + there's a critical section where neither the old nor the new + version of 'existing' actually exists. + + Moving directories across mount points is not portable, use 'cp' + and 'rm'. + +'sed' + Patterns should not include the separator (unless escaped), even as + part of a character class. In conformance with POSIX, the Cray + 'sed' will reject 's/[^/]*$//': use 's,[^/]*$,,'. + + Sed scripts should not use branch labels longer than 8 characters + and should not contain comments. + + Don't include extra ';', as some 'sed', such as NetBSD 1.4.2's, try + to interpret the second as a command: + + $ echo a | sed 's/x/x/;;s/x/x/' + sed: 1: "s/x/x/;;s/x/x/": invalid command code ; + + Input should have reasonably long lines, since some 'sed' have an + input buffer limited to 4000 bytes. + + Alternation, '\|', is common but not portable. Anchors ('^' and + '$') inside groups are not portable. + + Nested groups are extremely portable, but there is at least one + 'sed' (System V/68 Base Operating System R3V7.1) that does not + support it. + + Of course the option '-e' is portable, but it is not needed. No + valid Sed program can start with a dash, so it does not help + disambiguating. Its sole usefulness is helping enforcing indenting + as in: + + sed -e INSTRUCTION-1 \ + -e INSTRUCTION-2 + + as opposed to + + sed INSTRUCTION-1;INSTRUCTION-2 + + Contrary to yet another urban legend, you may portably use '&' in + the replacement part of the 's' command to mean "what was matched". + +'sed' ('t') + Some old systems have 'sed' that "forget" to reset their 't' flag + when starting a new cycle. For instance on MIPS RISC/OS, and on + IRIX 5.3, if you run the following 'sed' script (the line numbers + are not actual part of the texts): + + s/keep me/kept/g # a + t end # b + s/.*/deleted/g # c + : end # d + + on + + delete me # 1 + delete me # 2 + keep me # 3 + delete me # 4 + + you get + + deleted + delete me + kept + deleted + + instead of + + deleted + deleted + kept + deleted + + Why? When processing 1, a matches, therefore sets the t flag, b + jumps to d, and the output is produced. When processing line 2, + the t flag is still set (this is the bug). Line a fails to match, + but 'sed' is not supposed to clear the t flag when a substitution + fails. Line b sees that the flag is set, therefore it clears it, + and jumps to d, hence you get 'delete me' instead of 'deleted'. + When processing 3 t is clear, a matches, so the flag is set, hence + b clears the flags and jumps. Finally, since the flag is clear, 4 + is processed properly. + + There are two things one should remind about 't' in 'sed'. + Firstly, always remember that 't' jumps if _some_ substitution + succeeded, not only the immediately preceding substitution, + therefore, always use a fake 't clear; : clear' to reset the t flag + where indeed. + + Secondly, you cannot rely on 'sed' to clear the flag at each new + cycle. + + One portable implementation of the script above is: + + t clear + : clear + s/keep me/kept/g + t end + s/.*/deleted/g + : end + +'touch' + On some old BSD systems, 'touch' or any command that results in an + empty file does not update the timestamps, so use a command like + 'echo' as a workaround. + + GNU 'touch' 3.16r (and presumably all before that) fails to work on + SunOS 4.1.3 when the empty file is on an NFS-mounted 4.2 volume. + + +File: autoconf.info, Node: Limitations of Make, Prev: Limitations of Usual Tools, Up: Portable Shell + +10.10 Limitations of Make +========================= + +Make itself suffers a great number of limitations, only a few of which +being listed here. First of all, remember that since commands are +executed by the shell, all its weaknesses are inherited... + +Leading underscore in macro names + Some Make don't support leading underscores in macro names, such as + on NEWS-OS 4.2R. + + $ cat Makefile + _am_include = # + _am_quote = + all:; @echo this is test + + % make + Make: Must be a separator on rules line 2. Stop. + + $ cat Makefile2 + am_include = # + am_quote = + all:; @echo this is test + + $ make -f Makefile2 + this is test + +'VPATH' + Don't use it! For instance any assignment to 'VPATH' causes Sun + 'make' to only execute the first set of double-colon rules. + + +File: autoconf.info, Node: Manual Configuration, Next: Site Configuration, Prev: Portable Shell, Up: Top + +11 Manual Configuration +*********************** + +A few kinds of features can't be guessed automatically by running test +programs. For example, the details of the object-file format, or +special options that need to be passed to the compiler or linker. You +can check for such features using ad-hoc means, such as having +'configure' check the output of the 'uname' program, or looking for +libraries that are unique to particular systems. However, Autoconf +provides a uniform method for handling unguessable features. + +* Menu: + +* Specifying Names:: Specifying the system type +* Canonicalizing:: Getting the canonical system type +* Using System Type:: What to do with the system type + + +File: autoconf.info, Node: Specifying Names, Next: Canonicalizing, Prev: Manual Configuration, Up: Manual Configuration + +11.1 Specifying the System Type +=============================== + +Like other GNU 'configure' scripts, Autoconf-generated 'configure' +scripts can make decisions based on a canonical name for the system +type, which has the form: 'CPU-VENDOR-OS', where OS can be 'SYSTEM' or +'KERNEL-SYSTEM' + + 'configure' can usually guess the canonical name for the type of +system it's running on. To do so it runs a script called +'config.guess', which infers the name using the 'uname' command or +symbols predefined by the C preprocessor. + + Alternately, the user can specify the system type with command line +arguments to 'configure'. Doing so is necessary when cross-compiling. +In the most complex case of cross-compiling, three system types are +involved. The options to specify them are(1): + +'--build=BUILD-TYPE' + the type of system on which the package is being configured and + compiled. + +'--host=HOST-TYPE' + the type of system on which the package will run. + +'--target=TARGET-TYPE' + the type of system for which any compiler tools in the package will + produce code (rarely needed). By default, it is the same as host. + + They all default to the result of running 'config.guess', unless you +specify either '--build' or '--host'. In this case, the default becomes +the system type you specified. If you specify both, and they're +different, 'configure' will enter cross compilation mode, so it won't +run any tests that require execution. + + Hint: if you mean to override the result of 'config.guess', prefer +'--build' over '--host'. In the future, '--host' will not override the +name of the build system type. Also, if you specify '--host', but not +'--build', when 'configure' performs the first compiler test it will try +to run an executable produced by the compiler. If the execution fails, +it will enter cross-compilation mode. Note, however, that it won't +guess the build-system type, since this may require running test +programs. Moreover, by the time the compiler test is performed, it may +be too late to modify the build-system type: other tests may have +already been performed. Therefore, whenever you specify '--host', be +sure to specify '--build' too. + + ./configure --build=i686-pc-linux-gnu --host=m68k-coff + +will enter cross-compilation mode, but 'configure' will fail if it can't +run the code generated by the specified compiler if you configure as +follows: + + ./configure CC=m68k-coff-gcc + + 'configure' recognizes short aliases for many system types; for +example, 'decstation' can be used instead of 'mips-dec-ultrix4.2'. +'configure' runs a script called 'config.sub' to canonicalize system +type aliases. + + ---------- Footnotes ---------- + + (1) For backward compatibility, 'configure' will accept a system type +as an option by itself. Such an option will override the defaults for +build, host and target system types. The following configure statement +will configure a cross toolchain that will run on NetBSD/alpha but +generate code for GNU Hurd/sparc, which is also the build platform. + + ./configure --host=alpha-netbsd sparc-gnu + + +File: autoconf.info, Node: Canonicalizing, Next: Using System Type, Prev: Specifying Names, Up: Manual Configuration + +11.2 Getting the Canonical System Type +====================================== + +The following macros make the system type available to 'configure' +scripts. + + The variables 'build_alias', 'host_alias', and 'target_alias' are +always exactly the arguments of '--build', '--host', and '--target'; in +particular, they are left empty if the user did not use them, even if +the corresponding 'AC_CANONICAL' macro was run. Any configure script +may use these variables anywhere. These are the variables that should +be used when in interaction with the user. + + If you need to recognize some special environments based on their +system type, run the following macros to get canonical system names. +These variables are not set before the macro call. + + If you use these macros, you must distribute 'config.guess' and +'config.sub' along with your source code. *Note Output::, for +information about the 'AC_CONFIG_AUX_DIR' macro which you can use to +control in which directory 'configure' looks for those scripts. + + -- Macro: AC_CANONICAL_BUILD + Compute the canonical build-system type variable, 'build', and its + three individual parts 'build_cpu', 'build_vendor', and 'build_os'. + + If '--build' was specified, then 'build' is the canonicalization of + 'build_alias' by 'config.sub', otherwise it is determined by the + shell script 'config.guess'. + + -- Macro: AC_CANONICAL_HOST + Compute the canonical host-system type variable, 'host', and its + three individual parts 'host_cpu', 'host_vendor', and 'host_os'. + + If '--host' was specified, then 'host' is the canonicalization of + 'host_alias' by 'config.sub', otherwise it defaults to 'build'. + + For temporary backward-compatibility, when '--host' is specified by + '--build' isn't, the build system will be assumed to be the same as + '--host', and 'build_alias' will be set to that value. Eventually, + this historically incorrect behavior will go away. + + -- Macro: AC_CANONICAL_TARGET + Compute the canonical target-system type variable, 'target', and + its three individual parts 'target_cpu', 'target_vendor', and + 'target_os'. + + If '--target' was specified, then 'target' is the canonicalization + of 'target_alias' by 'config.sub', otherwise it defaults to 'host'. + + +File: autoconf.info, Node: Using System Type, Prev: Canonicalizing, Up: Manual Configuration + +11.3 Using the System Type +========================== + +How do you use a canonical system type? Usually, you use it in one or +more 'case' statements in 'configure.ac' to select system-specific C +files. Then, using 'AC_CONFIG_LINKS', link those files which have names +based on the system name, to generic names, such as 'host.h' or +'target.c' (*note Configuration Links::). The 'case' statement patterns +can use shell wild cards to group several cases together, like in this +fragment: + + case "$target" in + i386-*-mach* | i386-*-gnu*) + obj_format=aout emulation=mach bfd_gas=yes ;; + i960-*-bout) obj_format=bout ;; + esac + +and in 'configure.ac', use: + + AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) + + You can also use the host system type to find cross-compilation +tools. *Note Generic Programs::, for information about the +'AC_CHECK_TOOL' macro which does that. + + +File: autoconf.info, Node: Site Configuration, Next: Running configure scripts, Prev: Manual Configuration, Up: Top + +12 Site Configuration +********************* + +'configure' scripts support several kinds of local configuration +decisions. There are ways for users to specify where external software +packages are, include or exclude optional features, install programs +under modified names, and set default values for 'configure' options. + +* Menu: + +* External Software:: Working with other optional software +* Package Options:: Selecting optional features +* Pretty Help Strings:: Formatting help string +* Site Details:: Configuring site details +* Transforming Names:: Changing program names when installing +* Site Defaults:: Giving 'configure' local defaults + + +File: autoconf.info, Node: External Software, Next: Package Options, Prev: Site Configuration, Up: Site Configuration + +12.1 Working With External Software +=================================== + +Some packages require, or can optionally use, other software packages +that are already installed. The user can give 'configure' command line +options to specify which such external software to use. The options +have one of these forms: + + --with-PACKAGE=[ARG] + --without-PACKAGE + + For example, '--with-gnu-ld' means work with the GNU linker instead +of some other linker. '--with-x' means work with The X Window System. + + The user can give an argument by following the package name with '=' +and the argument. Giving an argument of 'no' is for packages that are +used by default; it says to _not_ use the package. An argument that is +neither 'yes' nor 'no' could include a name or number of a version of +the other package, to specify more precisely which other package this +program is supposed to work with. If no argument is given, it defaults +to 'yes'. '--without-PACKAGE' is equivalent to '--with-PACKAGE=no'. + + 'configure' scripts do not complain about '--with-PACKAGE' options +that they do not support. This behavior permits configuring a source +tree containing multiple packages with a top-level 'configure' script +when the packages support different options, without spurious error +messages about options that some of the packages support. An +unfortunate side effect is that option spelling errors are not +diagnosed. No better approach to this problem has been suggested so +far. + + For each external software package that may be used, 'configure.ac' +should call 'AC_ARG_WITH' to detect whether the 'configure' user asked +to use it. Whether each package is used or not by default, and which +arguments are valid, is up to you. + + -- Macro: AC_ARG_WITH (PACKAGE, HELP-STRING, [ACTION-IF-GIVEN], + [ACTION-IF-NOT-GIVEN]) + If the user gave 'configure' the option '--with-PACKAGE' or + '--without-PACKAGE', run shell commands ACTION-IF-GIVEN. If + neither option was given, run shell commands ACTION-IF-NOT-GIVEN. + The name PACKAGE indicates another software package that this + program should work with. It should consist only of alphanumeric + characters and dashes. + + The option's argument is available to the shell commands + ACTION-IF-GIVEN in the shell variable 'withval', which is actually + just the value of the shell variable 'with_PACKAGE', with any '-' + characters changed into '_'. You may use that variable instead, if + you wish. + + The argument HELP-STRING is a description of the option that looks + like this: + --with-readline support fancy command line editing + + HELP-STRING may be more than one line long, if more detail is + needed. Just make sure the columns line up in 'configure --help'. + Avoid tabs in the help string. You'll need to enclose it in '[' + and ']' in order to produce the leading spaces. + + You should format your HELP-STRING with the macro 'AC_HELP_STRING' + (*note Pretty Help Strings::). + + -- Macro: AC_WITH (PACKAGE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN]) + This is an obsolete version of 'AC_ARG_WITH' that does not support + providing a help string. + + +File: autoconf.info, Node: Package Options, Next: Pretty Help Strings, Prev: External Software, Up: Site Configuration + +12.2 Choosing Package Options +============================= + +If a software package has optional compile-time features, the user can +give 'configure' command line options to specify whether to compile +them. The options have one of these forms: + + --enable-FEATURE=[ARG] + --disable-FEATURE + + These options allow users to choose which optional features to build +and install. '--enable-FEATURE' options should never make a feature +behave differently or cause one feature to replace another. They should +only cause parts of the program to be built rather than left out. + + The user can give an argument by following the feature name with '=' +and the argument. Giving an argument of 'no' requests that the feature +_not_ be made available. A feature with an argument looks like +'--enable-debug=stabs'. If no argument is given, it defaults to 'yes'. +'--disable-FEATURE' is equivalent to '--enable-FEATURE=no'. + + 'configure' scripts do not complain about '--enable-FEATURE' options +that they do not support. This behavior permits configuring a source +tree containing multiple packages with a top-level 'configure' script +when the packages support different options, without spurious error +messages about options that some of the packages support. An +unfortunate side effect is that option spelling errors are not +diagnosed. No better approach to this problem has been suggested so +far. + + For each optional feature, 'configure.ac' should call 'AC_ARG_ENABLE' +to detect whether the 'configure' user asked to include it. Whether +each feature is included or not by default, and which arguments are +valid, is up to you. + + -- Macro: AC_ARG_ENABLE (FEATURE, HELP-STRING, [ACTION-IF-GIVEN], + [ACTION-IF-NOT-GIVEN]) + If the user gave 'configure' the option '--enable-FEATURE' or + '--disable-FEATURE', run shell commands ACTION-IF-GIVEN. If + neither option was given, run shell commands ACTION-IF-NOT-GIVEN. + The name FEATURE indicates an optional user-level facility. It + should consist only of alphanumeric characters and dashes. + + The option's argument is available to the shell commands + ACTION-IF-GIVEN in the shell variable 'enableval', which is + actually just the value of the shell variable 'enable_FEATURE', + with any '-' characters changed into '_'. You may use that + variable instead, if you wish. The HELP-STRING argument is like + that of 'AC_ARG_WITH' (*note External Software::). + + You should format your HELP-STRING with the macro 'AC_HELP_STRING' + (*note Pretty Help Strings::). + + -- Macro: AC_ENABLE (FEATURE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN]) + This is an obsolete version of 'AC_ARG_ENABLE' that does not + support providing a help string. + + +File: autoconf.info, Node: Pretty Help Strings, Next: Site Details, Prev: Package Options, Up: Site Configuration + +12.3 Making Your Help Strings Look Pretty +========================================= + +Properly formatting the 'help strings' which are used in 'AC_ARG_WITH' +(*note External Software::) and 'AC_ARG_ENABLE' (*note Package +Options::) can be challenging. Specifically, you want your own 'help +strings' to line up in the appropriate columns of 'configure --help' +just like the standard Autoconf 'help strings' do. This is the purpose +of the 'AC_HELP_STRING' macro. + + -- Macro: AC_HELP_STRING (LEFT-HAND-SIDE, RIGHT-HAND-SIDE) + + Expands into an help string that looks pretty when the user + executes 'configure --help'. It is typically used in 'AC_ARG_WITH' + (*note External Software::) or 'AC_ARG_ENABLE' (*note Package + Options::). The following example will make this clearer. + + AC_DEFUN(TEST_MACRO, + [AC_ARG_WITH(foo, + AC_HELP_STRING([--with-foo], + [use foo (default is NO)]), + ac_cv_use_foo=$withval, ac_cv_use_foo=no), + AC_CACHE_CHECK(whether to use foo, + ac_cv_use_foo, ac_cv_use_foo=no)]) + + Please note that the call to 'AC_HELP_STRING' is *unquoted*. Then + the last few lines of 'configure --help' will appear like this: + + --enable and --with options recognized: + --with-foo use foo (default is NO) + + The 'AC_HELP_STRING' macro is particularly helpful when the + LEFT-HAND-SIDE and/or RIGHT-HAND-SIDE are composed of macro + arguments, as shown in the following example. + + AC_DEFUN(MY_ARG_WITH, + [AC_ARG_WITH([$1], + AC_HELP_STRING([--with-$1], [use $1 (default is $2)]), + ac_cv_use_$1=$withval, ac_cv_use_$1=no), + AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)]) + + +File: autoconf.info, Node: Site Details, Next: Transforming Names, Prev: Pretty Help Strings, Up: Site Configuration + +12.4 Configuring Site Details +============================= + +Some software packages require complex site-specific information. Some +examples are host names to use for certain services, company names, and +email addresses to contact. Since some configuration scripts generated +by Metaconfig ask for such information interactively, people sometimes +wonder how to get that information in Autoconf-generated configuration +scripts, which aren't interactive. + + Such site configuration information should be put in a file that is +edited _only by users_, not by programs. The location of the file can +either be based on the 'prefix' variable, or be a standard location such +as the user's home directory. It could even be specified by an +environment variable. The programs should examine that file at run +time, rather than at compile time. Run time configuration is more +convenient for users and makes the configuration process simpler than +getting the information while configuring. *Note Variables for +Installation Directories: (standards)Directory Variables, for more +information on where to put data files. + + +File: autoconf.info, Node: Transforming Names, Next: Site Defaults, Prev: Site Details, Up: Site Configuration + +12.5 Transforming Program Names When Installing +=============================================== + +Autoconf supports changing the names of programs when installing them. +In order to use these transformations, 'configure.ac' must call the +macro 'AC_ARG_PROGRAM'. + + -- Macro: AC_ARG_PROGRAM + Place in output variable 'program_transform_name' a sequence of + 'sed' commands for changing the names of installed programs. + + If any of the options described below are given to 'configure', + program names are transformed accordingly. Otherwise, if + 'AC_CANONICAL_TARGET' has been called and a '--target' value is + given that differs from the host type (specified with '--host'), + the target type followed by a dash is used as a prefix. Otherwise, + no program name transformation is done. + +* Menu: + +* Transformation Options:: 'configure' options to transform names +* Transformation Examples:: Sample uses of transforming names +* Transformation Rules:: 'Makefile' uses of transforming names + + +File: autoconf.info, Node: Transformation Options, Next: Transformation Examples, Prev: Transforming Names, Up: Transforming Names + +12.5.1 Transformation Options +----------------------------- + +You can specify name transformations by giving 'configure' these command +line options: + +'--program-prefix=PREFIX' + prepend PREFIX to the names; + +'--program-suffix=SUFFIX' + append SUFFIX to the names; + +'--program-transform-name=EXPRESSION' + perform 'sed' substitution EXPRESSION on the names. + + +File: autoconf.info, Node: Transformation Examples, Next: Transformation Rules, Prev: Transformation Options, Up: Transforming Names + +12.5.2 Transformation Examples +------------------------------ + +These transformations are useful with programs that can be part of a +cross-compilation development environment. For example, a +cross-assembler running on a Sun 4 configured with +'--target=i960-vxworks' is normally installed as 'i960-vxworks-as', +rather than 'as', which could be confused with a native Sun 4 assembler. + + You can force a program name to begin with 'g', if you don't want GNU +programs installed on your system to shadow other programs with the same +name. For example, if you configure GNU 'diff' with +'--program-prefix=g', then when you run 'make install' it is installed +as '/usr/local/bin/gdiff'. + + As a more sophisticated example, you could use + + --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' + + to prepend 'g' to most of the program names in a source tree, +excepting those like 'gdb' that already have one and those like 'less' +and 'lesskey' that aren't GNU programs. (That is assuming that you have +a source tree containing those programs that is set up to use this +feature.) + + One way to install multiple versions of some programs simultaneously +is to append a version number to the name of one or both. For example, +if you want to keep Autoconf version 1 around for awhile, you can +configure Autoconf version 2 using '--program-suffix=2' to install the +programs as '/usr/local/bin/autoconf2', '/usr/local/bin/autoheader2', +etc. Nevertheless, pay attention that only the binaries are renamed, +therefore you'd have problems with the library files which might +overlap. + + +File: autoconf.info, Node: Transformation Rules, Prev: Transformation Examples, Up: Transforming Names + +12.5.3 Transformation Rules +--------------------------- + +Here is how to use the variable 'program_transform_name' in a +'Makefile.in': + + transform = @program_transform_name@ + install: all + $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog | \ + sed '$(transform)'` + + uninstall: + rm -f $(bindir)/`echo myprog | sed '$(transform)'` + +If you have more than one program to install, you can do it in a loop: + + PROGRAMS = cp ls rm + install: + for p in $(PROGRAMS); do \ + $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p | \ + sed '$(transform)'`; \ + done + + uninstall: + for p in $(PROGRAMS); do \ + rm -f $(bindir)/`echo $$p | sed '$(transform)'`; \ + done + + It is guaranteed that 'program_transform_name' is never empty, and +that there are no useless separators. Therefore you may safely embed +'program_transform_name' within a sed program using ';': + + transform = @program_transform_name@ + transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ + + Whether to do the transformations on documentation files (Texinfo or +'man') is a tricky question; there seems to be no perfect answer, due to +the several reasons for name transforming. Documentation is not usually +particular to a specific architecture, and Texinfo files do not conflict +with system documentation. But they might conflict with earlier +versions of the same files, and 'man' pages sometimes do conflict with +system documentation. As a compromise, it is probably best to do name +transformations on 'man' pages but not on Texinfo manuals. + + +File: autoconf.info, Node: Site Defaults, Prev: Transforming Names, Up: Site Configuration + +12.6 Setting Site Defaults +========================== + +Autoconf-generated 'configure' scripts allow your site to provide +default values for some configuration values. You do this by creating +site- and system-wide initialization files. + + If the environment variable 'CONFIG_SITE' is set, 'configure' uses +its value as the name of a shell script to read. Otherwise, it reads +the shell script 'PREFIX/share/config.site' if it exists, then +'PREFIX/etc/config.site' if it exists. Thus, settings in +machine-specific files override those in machine-independent ones in +case of conflict. + + Site files can be arbitrary shell scripts, but only certain kinds of +code are really appropriate to be in them. Because 'configure' reads +any cache file after it has read any site files, a site file can define +a default cache file to be shared between all Autoconf-generated +'configure' scripts run on that system (*note Cache Files::). If you +set a default cache file in a site file, it is a good idea to also set +the output variable 'CC' in that site file, because the cache file is +only valid for a particular compiler, but many systems have several +available. + + You can examine or override the value set by a command line option to +'configure' in a site file; options set shell variables that have the +same names as the options, with any dashes turned into underscores. The +exceptions are that '--without-' and '--disable-' options are like +giving the corresponding '--with-' or '--enable-' option and the value +'no'. Thus, '--cache-file=localcache' sets the variable 'cache_file' to +the value 'localcache'; '--enable-warnings=no' or '--disable-warnings' +sets the variable 'enable_warnings' to the value 'no'; '--prefix=/usr' +sets the variable 'prefix' to the value '/usr'; etc. + + Site files are also good places to set default values for other +output variables, such as 'CFLAGS', if you need to give them non-default +values: anything you would normally do, repetitively, on the command +line. If you use non-default values for PREFIX or EXEC_PREFIX (wherever +you locate the site file), you can set them in the site file if you +specify it with the 'CONFIG_SITE' environment variable. + + You can set some cache values in the site file itself. Doing this is +useful if you are cross-compiling, so it is impossible to check features +that require running a test program. You could "prime the cache" by +setting those values correctly for that system in +'PREFIX/etc/config.site'. To find out the names of the cache variables +you need to set, look for shell variables with '_cv_' in their names in +the affected 'configure' scripts, or in the Autoconf M4 source code for +those macros. + + The cache file is careful to not override any variables set in the +site files. Similarly, you should not override command-line options in +the site files. Your code should check that variables such as 'prefix' +and 'cache_file' have their default values (as set near the top of +'configure') before changing them. + + Here is a sample file '/usr/share/local/gnu/share/config.site'. The +command 'configure --prefix=/usr/share/local/gnu' would read this file +(if 'CONFIG_SITE' is not set to a different file). + + # config.site for configure + # + # Change some defaults. + test "$prefix" = NONE && prefix=/usr/share/local/gnu + test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu + test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var + test "$localstatedir" = '$prefix/var' && localstatedir=/var + + # Give Autoconf 2.x generated configure scripts a shared default + # cache file for feature test results, architecture-specific. + if test "$cache_file" = /dev/null; then + cache_file="$prefix/var/config.cache" + # A cache file is only valid for one C compiler. + CC=gcc + fi + + +File: autoconf.info, Node: Running configure scripts, Next: config.status Invocation, Prev: Site Configuration, Up: Top + +13 Running 'configure' Scripts +****************************** + +Below are instructions on how to configure a package that uses a +'configure' script, suitable for inclusion as an 'INSTALL' file in the +package. A plain-text version of 'INSTALL' which you may use comes with +Autoconf. + +* Menu: + +* Basic Installation:: Instructions for typical cases +* Compilers and Options:: Selecting compilers and optimization +* Multiple Architectures:: Compiling for multiple architectures at once +* Installation Names:: Installing in different directories +* Optional Features:: Selecting optional features +* System Type:: Specifying the system type +* Sharing Defaults:: Setting site-wide defaults for 'configure' +* Environment Variables:: Defining environment variables. +* configure Invocation:: Changing how 'configure' runs + + +File: autoconf.info, Node: Basic Installation, Next: Compilers and Options, Up: Running configure scripts + +13.1 Basic Installation +======================= + +These are generic installation instructions. + + The 'configure' shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a 'Makefile' in each directory of the package. +It may also create one or more '.h' files containing system-dependent +definitions. Finally, it creates a shell script 'config.status' that +you can run in the future to recreate the current configuration, and a +file 'config.log' containing compiler output (useful mainly for +debugging 'configure'). + + It can also use an optional file (typically called 'config.cache' and +enabled with '--cache-file=config.cache' or simply '-C') that saves the +results of its tests to speed up reconfiguring. (Caching is disabled by +default to prevent problems with accidental use of stale cache files.) + + If you need to do unusual things to compile the package, please try +to figure out how 'configure' could check whether to do them, and mail +diffs or instructions to the address given in the 'README' so they can +be considered for the next release. If you are using the cache, and at +some point 'config.cache' contains results you don't want to keep, you +may remove or edit it. + + The file 'configure.ac' (or 'configure.in') is used to create +'configure' by a program called 'autoconf'. You only need +'configure.ac' if you want to change it or regenerate 'configure' using +a newer version of 'autoconf'. + +The simplest way to compile this package is: + + 1. 'cd' to the directory containing the package's source code and type + './configure' to configure the package for your system. If you're + using 'csh' on an old version of System V, you might need to type + 'sh ./configure' instead to prevent 'csh' from trying to execute + 'configure' itself. + + Running 'configure' takes awhile. While running, it prints some + messages telling which features it is checking for. + + 2. Type 'make' to compile the package. + + 3. Optionally, type 'make check' to run any self-tests that come with + the package. + + 4. Type 'make install' to install the programs and any data files and + documentation. + + 5. You can remove the program binaries and object files from the + source code directory by typing 'make clean'. To also remove the + files that 'configure' created (so you can compile the package for + a different kind of computer), type 'make distclean'. There is + also a 'make maintainer-clean' target, but that is intended mainly + for the package's developers. If you use it, you may have to get + all sorts of other programs in order to regenerate files that came + with the distribution. + + +File: autoconf.info, Node: Compilers and Options, Next: Multiple Architectures, Prev: Basic Installation, Up: Running configure scripts + +13.2 Compilers and Options +========================== + +Some systems require unusual options for compilation or linking that the +'configure' script does not know about. Run './configure --help' for +details on some of the pertinent environment variables. + + You can give 'configure' initial values for variables by setting them +in the environment. You can do that on the command line like this: + + ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix + + *Note Environment Variables::, for more details. + + +File: autoconf.info, Node: Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Running configure scripts + +13.3 Compiling For Multiple Architectures +========================================= + +You can compile the package for more than one kind of computer at the +same time, by placing the object files for each architecture in their +own directory. To do this, you must use a version of 'make' that +supports the 'VPATH' variable, such as GNU 'make'. 'cd' to the +directory where you want the object files and executables to go and run +the 'configure' script. 'configure' automatically checks for the source +code in the directory that 'configure' is in and in '..'. + + If you have to use a 'make' that does not support the 'VPATH' +variable, you have to compile the package for one architecture at a time +in the source code directory. After you have installed the package for +one architecture, use 'make distclean' before reconfiguring for another +architecture. + + +File: autoconf.info, Node: Installation Names, Next: Optional Features, Prev: Multiple Architectures, Up: Running configure scripts + +13.4 Installation Names +======================= + +By default, 'make install' will install the package's files in +'/usr/local/bin', '/usr/local/man', etc. You can specify an +installation prefix other than '/usr/local' by giving 'configure' the +option '--prefix=PATH'. + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +give 'configure' the option '--exec-prefix=PATH', the package will use +PATH as the prefix for installing programs and libraries. Documentation +and other data files will still use the regular prefix. + + In addition, if you use an unusual directory layout you can give +options like '--bindir=PATH' to specify different values for particular +kinds of files. Run 'configure --help' for a list of the directories +you can set and what kinds of files go in them. + + If the package supports it, you can cause programs to be installed +with an extra prefix or suffix on their names by giving 'configure' the +option '--program-prefix=PREFIX' or '--program-suffix=SUFFIX'. + + +File: autoconf.info, Node: Optional Features, Next: System Type, Prev: Installation Names, Up: Running configure scripts + +13.5 Optional Features +====================== + +Some packages pay attention to '--enable-FEATURE' options to +'configure', where FEATURE indicates an optional part of the package. +They may also pay attention to '--with-PACKAGE' options, where PACKAGE +is something like 'gnu-as' or 'x' (for the X Window System). The +'README' should mention any '--enable-' and '--with-' options that the +package recognizes. + + For packages that use the X Window System, 'configure' can usually +find the X include and library files automatically, but if it doesn't, +you can use the 'configure' options '--x-includes=DIR' and +'--x-libraries=DIR' to specify their locations. + + +File: autoconf.info, Node: System Type, Next: Sharing Defaults, Prev: Optional Features, Up: Running configure scripts + +13.6 Specifying the System Type +=============================== + +There may be some features 'configure' cannot figure out automatically, +but needs to determine by the type of host the package will run on. +Usually 'configure' can figure that out, but if it prints a message +saying it cannot guess the host type, give it the '--build=TYPE' option. +TYPE can either be a short name for the system type, such as 'sun4', or +a canonical name which has the form: + + CPU-COMPANY-SYSTEM + +where SYSTEM can have one of these forms: + + OS + KERNEL-OS + + See the file 'config.sub' for the possible values of each field. If +'config.sub' isn't included in this package, then this package doesn't +need to know the host type. + + If you are _building_ compiler tools for cross-compiling, you should +use the '--target=TYPE' option to select the type of system they will +produce code for. + + If you want to _use_ a cross compiler, that generates code for a +platform different from the build platform, you should specify the host +platform (i.e., that on which the generated programs will eventually be +run) with '--host=TYPE'. In this case, you should also specify the +build platform with '--build=TYPE', because, in this case, it may not be +possible to guess the build platform (it sometimes involves compiling +and running simple test programs, and this can't be done if the compiler +is a cross compiler). + + +File: autoconf.info, Node: Sharing Defaults, Next: Environment Variables, Prev: System Type, Up: Running configure scripts + +13.7 Sharing Defaults +===================== + +If you want to set default values for 'configure' scripts to share, you +can create a site shell script called 'config.site' that gives default +values for variables like 'CC', 'cache_file', and 'prefix'. 'configure' +looks for 'PREFIX/share/config.site' if it exists, then +'PREFIX/etc/config.site' if it exists. Or, you can set the +'CONFIG_SITE' environment variable to the location of the site script. +A warning: not all 'configure' scripts look for a site script. + + +File: autoconf.info, Node: Environment Variables, Next: configure Invocation, Prev: Sharing Defaults, Up: Running configure scripts + +13.8 Environment Variables +========================== + +Variables not defined in a site shell script can be set in the +environment passed to configure. However, some packages may run +configure again during the build, and the customized values of these +variables may be lost. In order to avoid this problem, you should set +them in the 'configure' command line, using 'VAR=value'. For example: + + ./configure CC=/usr/local2/bin/gcc + +will cause the specified gcc to be used as the C compiler (unless it is +overridden in the site shell script). + + +File: autoconf.info, Node: configure Invocation, Prev: Environment Variables, Up: Running configure scripts + +13.9 'configure' Invocation +=========================== + +'configure' recognizes the following options to control how it operates. + +'--help' +'-h' + Print a summary of the options to 'configure', and exit. + +'--version' +'-V' + Print the version of Autoconf used to generate the 'configure' + script, and exit. + +'--cache-file=FILE' + Enable the cache: use and save the results of the tests in FILE, + traditionally 'config.cache'. FILE defaults to '/dev/null' to + disable caching. + +'--config-cache' +'-C' + Alias for '--cache-file=config.cache'. + +'--quiet' +'--silent' +'-q' + Do not print messages saying which checks are being made. To + suppress all normal output, redirect it to '/dev/null' (any error + messages will still be shown). + +'--srcdir=DIR' + Look for the package's source code in directory DIR. Usually + 'configure' can determine that directory automatically. + +'configure' also accepts some other, not widely useful, options. Run +'configure --help' for more details. + + +File: autoconf.info, Node: config.status Invocation, Next: Obsolete Constructs, Prev: Running configure scripts, Up: Top + +14 Recreating a Configuration +***************************** + +The 'configure' script creates a file named 'config.status', which +actually configures, "instantiates", the template files. It also +records the configuration options that were specified when the package +was last configured in case reconfiguring is needed. + + Synopsis: + ./config.status OPTION... [FILE...] + + It configures the FILES, if none are specified, all the templates are +instantiated. The files must be specified without their dependencies, +as in + + ./config.status foobar + +not + + ./config.status foobar:foo.in:bar.in + + The supported OPTIONs are: + +'--help' +'-h' + Print a summary of the command line options, the list of the + template files and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--debug' +'-d' + Don't remove the temporary files. + +'--file=FILE[:TEMPLATE]' + Require that FILE be instantiated as if + 'AC_CONFIG_FILES(FILE:TEMPLATE)' was used. Both FILE and TEMPLATE + may be '-' in which case the standard output and/or standard input, + respectively, is used. If a TEMPLATE filename is relative, it is + first looked for in the build tree, and then in the source tree. + *Note Configuration Actions::, for more details. + + This option and the following ones provide one way for separately + distributed packages to share the values computed by 'configure'. + Doing so can be useful if some of the packages need a superset of + the features that one of them, perhaps a common library, does. + These options allow a 'config.status' file to create files other + than the ones that its 'configure.ac' specifies, so it can be used + for a different package. + +'--header=FILE[:TEMPLATE]' + Same as '--file' above, but with 'AC_CONFIG_HEADERS'. + +'--recheck' + Ask 'config.status' to update itself and exit (no instantiation). + This option is useful if you change 'configure', so that the + results of some tests might be different from the previous run. + The '--recheck' option re-runs 'configure' with the same arguments + you used before, plus the '--no-create' option, which prevents + 'configure' from running 'config.status' and creating 'Makefile' + and other files, and the '--no-recursion' option, which prevents + 'configure' from running other 'configure' scripts in + subdirectories. (This is so other 'Makefile' rules can run + 'config.status' when it changes; *note Automatic Remaking::, for an + example). + + 'config.status' checks several optional environment variables that +can alter its behavior: + + -- Variable: CONFIG_SHELL + The shell with which to run 'configure' for the '--recheck' option. + It must be Bourne-compatible. The default is '/bin/sh'. + + -- Variable: CONFIG_STATUS + The file name to use for the shell script that records the + configuration. The default is './config.status'. This variable is + useful when one package uses parts of another and the 'configure' + scripts shouldn't be merged because they are maintained separately. + + You can use './config.status' in your Makefiles. For example, in the +dependencies given above (*note Automatic Remaking::), 'config.status' +is run twice when 'configure.ac' has changed. If that bothers you, you +can make each run only regenerate the files for that rule: + config.h: stamp-h + stamp-h: config.h.in config.status + ./config.status config.h + echo > stamp-h + + Makefile: Makefile.in config.status + ./config.status Makefile + + The calling convention of 'config.status' has changed, see *note +Obsolete config.status Use::, for details. + + +File: autoconf.info, Node: Obsolete Constructs, Next: Questions, Prev: config.status Invocation, Up: Top + +15 Obsolete Constructs +********************** + +Autoconf changes, and throughout the years some constructs are +obsoleted. Most of the changes involve the macros, but the tools +themselves, or even some concepts, are now considered obsolete. + + You may completely skip this chapter if you are new to Autoconf, its +intention is mainly to help maintainers updating their packages by +understanding how to move to more modern constructs. + +* Menu: + +* Obsolete config.status Use:: Different calling convention +* acconfig.h:: Additional entries in 'config.h.in' +* autoupdate Invocation:: Automatic update of 'configure.ac' +* Obsolete Macros:: Backward compatibility macros +* Autoconf 1:: Tips for upgrading your files +* Autoconf 2.13:: Some fresher tips + + +File: autoconf.info, Node: Obsolete config.status Use, Next: acconfig.h, Prev: Obsolete Constructs, Up: Obsolete Constructs + +15.1 Obsolete 'config.status' Invocation +======================================== + +'config.status' now supports arguments to specify the files to +instantiate, see *note config.status Invocation::, for more details. +Before, environment variables had to be used. + + -- Variable: CONFIG_COMMANDS + The tags of the commands to execute. The default is the arguments + given to 'AC_OUTPUT' and 'AC_CONFIG_COMMANDS' in 'configure.ac'. + + -- Variable: CONFIG_FILES + The files in which to perform '@VARIABLE@' substitutions. The + default is the arguments given to 'AC_OUTPUT' and 'AC_CONFIG_FILES' + in 'configure.ac'. + + -- Variable: CONFIG_HEADERS + The files in which to substitute C '#define' statements. The + default is the arguments given to 'AC_CONFIG_HEADERS'; if that + macro was not called, 'config.status' ignores this variable. + + -- Variable: CONFIG_LINKS + The symbolic links to establish. The default is the arguments + given to 'AC_CONFIG_LINKS'; if that macro was not called, + 'config.status' ignores this variable. + + In *note config.status Invocation::, using this old interface, the +example would be: + + config.h: stamp-h + stamp-h: config.h.in config.status + CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ + CONFIG_HEADERS=config.h ./config.status + echo > stamp-h + + Makefile: Makefile.in config.status + CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ + CONFIG_FILES=Makefile ./config.status + +(If 'configure.ac' does not call 'AC_CONFIG_HEADERS', there is no need +to set 'CONFIG_HEADERS' in the 'make' rules, equally for +'CONFIG_COMMANDS' etc.) + + +File: autoconf.info, Node: acconfig.h, Next: autoupdate Invocation, Prev: Obsolete config.status Use, Up: Obsolete Constructs + +15.2 'acconfig.h' +================= + +In order to produce 'config.h.in', 'autoheader' needs to build or to +find templates for each symbol. Modern releases of Autoconf use +'AH_VERBATIM' and 'AH_TEMPLATE' (*note Autoheader Macros::), but in +older releases a file, 'acconfig.h', contained the list of needed +templates. 'autoheader' copies comments and '#define' and '#undef' +statements from 'acconfig.h' in the current directory, if present. This +file used to be mandatory if you 'AC_DEFINE' any additional symbols. + + Modern releases of Autoconf also provide 'AH_TOP' and 'AH_BOTTOM' if +you need to prepend/append some information to 'config.h.in'. Ancient +versions of Autoconf had a similar feature: if './acconfig.h' contains +the string '@TOP@', 'autoheader' copies the lines before the line +containing '@TOP@' into the top of the file that it generates. +Similarly, if './acconfig.h' contains the string '@BOTTOM@', +'autoheader' copies the lines after that line to the end of the file it +generates. Either or both of those strings may be omitted. An even +older alternate way to produce the same effect in jurasik versions of +Autoconf is to create the files 'FILE.top' (typically 'config.h.top') +and/or 'FILE.bot' in the current directory. If they exist, 'autoheader' +copies them to the beginning and end, respectively, of its output. + + In former versions of Autoconf, the files used in preparing a +software package for distribution were: + configure.ac --. .------> autoconf* -----> configure + +---+ + [aclocal.m4] --+ `---. + [acsite.m4] ---' | + +--> [autoheader*] -> [config.h.in] + [acconfig.h] ----. | + +-----' + [config.h.top] --+ + [config.h.bot] --' + + Use only the 'AH_' macros, 'configure.ac' should be self-contained, +and should not depend upon 'acconfig.h' etc. + + +File: autoconf.info, Node: autoupdate Invocation, Next: Obsolete Macros, Prev: acconfig.h, Up: Obsolete Constructs + +15.3 Using 'autoupdate' to Modernize 'configure.ac' +=================================================== + +The 'autoupdate' program updates a 'configure.ac' file that calls +Autoconf macros by their old names to use the current macro names. In +version 2 of Autoconf, most of the macros were renamed to use a more +uniform and descriptive naming scheme. *Note Macro Names::, for a +description of the new scheme. Although the old names still work (*note +Obsolete Macros::, for a list of the old macros and the corresponding +new names), you can make your 'configure.ac' files more readable and +make it easier to use the current Autoconf documentation if you update +them to use the new macro names. + + If given no arguments, 'autoupdate' updates 'configure.ac', backing +up the original version with the suffix '~' (or the value of the +environment variable 'SIMPLE_BACKUP_SUFFIX', if that is set). If you +give 'autoupdate' an argument, it reads that file instead of +'configure.ac' and writes the updated file to the standard output. + +'autoupdate' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--verbose' +'-v' + Report processing steps. + +'--debug' +'-d' + Don't remove the temporary files. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the 'AC_MACRODIR' environment + variable to a directory; this option overrides the environment + variable. + + This option is rarely needed and dangerous; it is only used when + one plays with different versions of Autoconf simultaneously. + +'--localdir=DIR' +'-l DIR' + Look for the package file 'aclocal.m4' in directory DIR instead of + in the current directory. + + +File: autoconf.info, Node: Obsolete Macros, Next: Autoconf 1, Prev: autoupdate Invocation, Up: Obsolete Constructs + +15.4 Obsolete Macros +==================== + +Several macros are obsoleted in Autoconf, for various reasons (typically +they failed to quote properly, couldn't be extended for more recent +issues etc.). They are still supported, but deprecated: their use +should be avoided. + + During the jump from Autoconf version 1 to version 2, most of the +macros were renamed to use a more uniform and descriptive naming scheme, +but their signature did not change. *Note Macro Names::, for a +description of the new naming scheme. Below, there is just the mapping +from old names to new names for these macros, the reader is invited to +refer to the definition of the new macro for the signature and the +description. + + -- Macro: AC_ALLOCA + 'AC_FUNC_ALLOCA' + + -- Macro: AC_ARG_ARRAY + removed because of limited usefulness + + -- Macro: AC_C_CROSS + This macro is obsolete; it does nothing. + + -- Macro: AC_CANONICAL_SYSTEM + Determine the system type and set output variables to the names of + the canonical system types. *Note Canonicalizing::, for details + about the variables this macro sets. + + The user is encouraged to use either 'AC_CANONICAL_BUILD', or + 'AC_CANONICAL_HOST', or 'AC_CANONICAL_TARGET', depending on the + needs. Using 'AC_CANONICAL_TARGET' is enough to run the two other + macros. + + -- Macro: AC_CHAR_UNSIGNED + 'AC_C_CHAR_UNSIGNED' + + -- Macro: AC_CHECK_TYPE (TYPE, DEFAULT) + Autoconf, up to 2.13, used to provide this version of + 'AC_CHECK_TYPE', deprecated because of its flaws. Firstly, + although it is a member of the 'CHECK' clan, singular sub-family, + it does more than just checking. Second, missing types are not + 'typedef''d, they are '#define''d, which can lead to incompatible + code in the case of pointer types. + + This use of 'AC_CHECK_TYPE' is obsolete and discouraged, see *note + Generic Types::, for the description of the current macro. + + If the type TYPE is not defined, define it to be the C (or C++) + builtin type DEFAULT; e.g., 'short' or 'unsigned'. + + This macro is equivalent to: + + AC_CHECK_TYPE([TYPE], + [AC_DEFINE([TYPE], [DEFAULT], + [Define to `DEFAULT' if <sys/types.h> + does not define.])]) + + In order to keep backward compatibility, the two versions of + 'AC_CHECK_TYPE' are implemented, selected by a simple heuristics: + + 1. If there are three or four arguments, the modern version is + used. + + 2. If the second argument appears to be a C or C++ type, then the + obsolete version is used. This happens if the argument is a C + or C++ _builtin_ type or a C identifier ending in '_t', + optionally followed by one of '[(* ' and then by a string of + zero or more characters taken from the set '[]()* _a-zA-Z0-9'. + + 3. If the second argument is spelled with the alphabet of valid C + and C++ types, the user is warned and the modern version is + used. + + 4. Otherwise, the modern version is used. + + You are encouraged either to use a valid builtin type, or to use + the equivalent modern code (see above), or better yet, to use + 'AC_CHECK_TYPES' together with + + #if !HAVE_LOFF_T + typedef loff_t off_t; + #endif + + -- Macro: AC_CHECKING (FEATURE-DESCRIPTION) + Same as 'AC_MSG_NOTICE([checking FEATURE-DESCRIPTION...]'. + + -- Macro: AC_COMPILE_CHECK (ECHO-TEXT, INCLUDES, FUNCTION-BODY, + ACTION-IF-FOUND, [ACTION-IF-NOT-FOUND]) + This is an obsolete version of 'AC_TRY_LINK' (*note Examining + Libraries::), with the addition that it prints 'checking for + ECHO-TEXT' to the standard output first, if ECHO-TEXT is non-empty. + Use 'AC_MSG_CHECKING' and 'AC_MSG_RESULT' instead to print messages + (*note Printing Messages::). + + -- Macro: AC_CONST + 'AC_C_CONST' + + -- Macro: AC_CROSS_CHECK + Same as 'AC_C_CROSS', which is obsolete too, and does nothing + ':-)'. + + -- Macro: AC_CYGWIN + Check for the Cygwin environment in which case the shell variable + 'CYGWIN' is set to 'yes'. Don't use this macro, the dignified + means to check the nature of the host is using 'AC_CANONICAL_HOST'. + As a matter of fact this macro is defined as: + + AC_REQUIRE([AC_CANONICAL_HOST])[]dnl + case $host_os in + *cygwin* ) CYGWIN=yes;; + * ) CYGWIN=no;; + esac + + Beware that the variable 'CYGWIN' has a very special meaning when + running CygWin32, and should not be changed. That's yet another + reason not to use this macro. + + -- Macro: AC_DECL_YYTEXT + Does nothing, now integrated in 'AC_PROG_LEX'. + + -- Macro: AC_DIR_HEADER + Like calling 'AC_FUNC_CLOSEDIR_VOID' and'AC_HEADER_DIRENT', but + defines a different set of C preprocessor macros to indicate which + header file is found: + + Header Old Symbol New Symbol + 'dirent.h' 'DIRENT' 'HAVE_DIRENT_H' + 'sys/ndir.h' 'SYSNDIR' 'HAVE_SYS_NDIR_H' + 'sys/dir.h' 'SYSDIR' 'HAVE_SYS_DIR_H' + 'ndir.h' 'NDIR' 'HAVE_NDIR_H' + + -- Macro: AC_DYNIX_SEQ + If on Dynix/PTX (Sequent UNIX), add '-lseq' to output variable + 'LIBS'. This macro used to be defined as + + AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS") + + now it is just 'AC_FUNC_GETMNTENT'. + + -- Macro: AC_EXEEXT + Defined the output variable 'EXEEXT' based on the output of the + compiler, which is now done automatically. Typically set to empty + string if Unix and '.exe' if Win32 or OS/2. + + -- Macro: AC_EMXOS2 + Similar to 'AC_CYGWIN' but checks for the EMX environment on OS/2 + and sets 'EMXOS2'. + + -- Macro: AC_ERROR + 'AC_MSG_ERROR' + + -- Macro: AC_FIND_X + 'AC_PATH_X' + + -- Macro: AC_FIND_XTRA + 'AC_PATH_XTRA' + + -- Macro: AC_FUNC_CHECK + 'AC_CHECK_FUNC' + + -- Macro: AC_FUNC_WAIT3 + If 'wait3' is found and fills in the contents of its third argument + (a 'struct rusage *'), which HP-UX does not do, define + 'HAVE_WAIT3'. + + These days portable programs should use 'waitpid', not 'wait3', as + 'wait3' is being removed from the Open Group standards, and will + not appear in the next revision of POSIX. + + -- Macro: AC_GCC_TRADITIONAL + 'AC_PROG_GCC_TRADITIONAL' + + -- Macro: AC_GETGROUPS_T + 'AC_TYPE_GETGROUPS' + + -- Macro: AC_GETLOADAVG + 'AC_FUNC_GETLOADAVG' + + -- Macro: AC_HAVE_FUNCS + 'AC_CHECK_FUNCS' + + -- Macro: AC_HAVE_HEADERS + 'AC_CHECK_HEADERS' + + -- Macro: AC_HAVE_LIBRARY (LIBRARY, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) + This macro is equivalent to calling 'AC_CHECK_LIB' with a FUNCTION + argument of 'main'. In addition, LIBRARY can be written as any of + 'foo', '-lfoo', or 'libfoo.a'. In all of those cases, the compiler + is passed '-lfoo'. However, LIBRARY cannot be a shell variable; it + must be a literal name. + + -- Macro: AC_HAVE_POUNDBANG + 'AC_SYS_INTERPRETER' (different calling convention) + + -- Macro: AC_HEADER_CHECK + 'AC_CHECK_HEADER' + + -- Macro: AC_HEADER_EGREP + 'AC_EGREP_HEADER' + + -- Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR) + Formerly 'AC_INIT' used to have a single argument, and was + equivalent to: + + AC_INIT + AC_CONFIG_SRCDIR(UNIQUE-FILE-IN-SOURCE-DIR) + + -- Macro: AC_INLINE + 'AC_C_INLINE' + + -- Macro: AC_INT_16_BITS + If the C type 'int' is 16 bits wide, define 'INT_16_BITS'. Use + 'AC_CHECK_SIZEOF(int)' instead. + + -- Macro: AC_IRIX_SUN + If on IRIX (Silicon Graphics UNIX), add '-lsun' to output 'LIBS'. + If you were using it to get 'getmntent', use 'AC_FUNC_GETMNTENT' + instead. If you used it for the NIS versions of the password and + group functions, use 'AC_CHECK_LIB(sun, getpwnam)'. Up to Autoconf + 2.13, it used to be + + AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS") + + now it is defined as + + AC_FUNC_GETMNTENT + AC_CHECK_LIB(sun, getpwnam) + + -- Macro: AC_LANG_C + Same as 'AC_LANG(C)'. + + -- Macro: AC_LANG_CPLUSPLUS + Same as 'AC_LANG(C++)'. + + -- Macro: AC_LANG_FORTRAN77 + Same as 'AC_LANG(Fortran 77)'. + + -- Macro: AC_LANG_RESTORE + Select the LANGUAGE that is saved on the top of the stack, as set + by 'AC_LANG_SAVE', remove it from the stack, and call + 'AC_LANG(LANGUAGE)'. + + -- Macro: AC_LANG_SAVE + Remember the current language (as set by 'AC_LANG') on a stack. + The current language does not change. 'AC_LANG_PUSH' is preferred. + + -- Macro: AC_LINK_FILES (SOURCE..., DEST...) + This is an obsolete version of 'AC_CONFIG_LINKS'. An updated + version of: + + AC_LINK_FILES(config/$machine.h config/$obj_format.h, + host.h object.h) + + is: + + AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) + + -- Macro: AC_LN_S + 'AC_PROG_LN_S' + + -- Macro: AC_LONG_64_BITS + Define 'LONG_64_BITS' if the C type 'long int' is 64 bits wide. + Use the generic macro 'AC_CHECK_SIZEOF([long int])' instead. + + -- Macro: AC_LONG_DOUBLE + 'AC_C_LONG_DOUBLE' + + -- Macro: AC_LONG_FILE_NAMES + 'AC_SYS_LONG_FILE_NAMES' + + -- Macro: AC_MAJOR_HEADER + 'AC_HEADER_MAJOR' + + -- Macro: AC_MEMORY_H + Used to define 'NEED_MEMORY_H' if the 'mem' functions were defined + in 'memory.h'. Today it is equivalent to + 'AC_CHECK_HEADERS(memory.h)'. Adjust your code to depend upon + 'HAVE_MEMORY_H', not 'NEED_MEMORY_H', see *Note Standard Symbols::. + + -- Macro: AC_MINGW32 + Similar to 'AC_CYGWIN' but checks for the MingW32 compiler + environment and sets 'MINGW32'. + + -- Macro: AC_MINUS_C_MINUS_O + 'AC_PROG_CC_C_O' + + -- Macro: AC_MMAP + 'AC_FUNC_MMAP' + + -- Macro: AC_MODE_T + 'AC_TYPE_MODE_T' + + -- Macro: AC_OBJEXT + Defined the output variable 'OBJEXT' based on the output of the + compiler, after .c files have been excluded. Typically set to 'o' + if Unix, 'obj' if Win32. Now the compiler checking macros handle + this automatically. + + -- Macro: AC_OBSOLETE (THIS-MACRO-NAME, [SUGGESTION]) + Make 'm4' print a message to the standard error output warning that + THIS-MACRO-NAME is obsolete, and giving the file and line number + where it was called. THIS-MACRO-NAME should be the name of the + macro that is calling 'AC_OBSOLETE'. If SUGGESTION is given, it is + printed at the end of the warning message; for example, it can be a + suggestion for what to use instead of THIS-MACRO-NAME. + + For instance + + AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl + + You are encouraged to use 'AU_DEFUN' instead, since it gives better + services to the user. + + -- Macro: AC_OFF_T + 'AC_TYPE_OFF_T' + + -- Macro: AC_OUTPUT ([FILE]..., [EXTRA-CMDS], [INIT-CMDS], [SAVE-DEFS]) + The use of 'AC_OUTPUT' with argument is deprecated, this obsoleted + interface is equivalent to: + + AC_CONFIG_FILES(FILE...) + AC_CONFIG_COMMANDS([default], + EXTRA-CMDS, INIT-CMDS) + AC_SETUP_DEFS(SAVE-DEFS) + AC_OUTPUT + + If you specify SAVE-DEFS, autoconf will save the '#define's in a + different form, for use in the files specified in + 'AC_CONFIG_HEADERS'. In this case, autoconf substitutes the + C-style '#define's where it finds '@DEFS@'. This runs faster, and + is simpler to maintain than building a file of '#undef's, since + autoconf will automatically generate a '#define' for each + 'AC_DEFINE' that you execute in the 'configure' script. The value + for SAVE-DEFS should be either 'cat', or 'sort'; this value is used + to filter the list of '#define's before editing. Sorted lists are + easier to read, but you may wish to see the definitions in the + order that they were processed. + + -- Macro: AC_OUTPUT_COMMANDS (EXTRA-CMDS, [INIT-CMDS]) + Specify additional shell commands to run at the end of + 'config.status', and shell commands to initialize any variables + from 'configure'. This macro may be called multiple times. It is + obsolete, replaced by 'AC_CONFIG_COMMANDS'. + + Here is an unrealistic example: + + fubar=27 + AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], + fubar=$fubar) + AC_OUTPUT_COMMANDS([echo this is another, extra, bit], + [echo init bit]) + + Aside from the fact that 'AC_CONFIG_COMMANDS' requires an + additional key, an important difference is that + 'AC_OUTPUT_COMMANDS' is quoting its arguments twice, while + 'AC_CONFIG_COMMANDS'. This means that 'AC_CONFIG_COMMANDS' can + safely be given macro calls as arguments: + + AC_CONFIG_COMMANDS(foo, [my_FOO()]) + + conversely, where one level of quoting was enough for literal + strings with 'AC_OUTPUT_COMMANDS', you need two with + 'AC_CONFIG_COMMANDS'. The following lines are equivalent: + + AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) + AC_CONFIG_COMMANDS(default, [[echo "Square brackets: []"]]) + + -- Macro: AC_PID_T + 'AC_TYPE_PID_T' + + -- Macro: AC_PREFIX + 'AC_PREFIX_PROGRAM' + + -- Macro: AC_PROGRAMS_CHECK + 'AC_CHECK_PROGS' + + -- Macro: AC_PROGRAMS_PATH + 'AC_PATH_PROGS' + + -- Macro: AC_PROGRAM_CHECK + 'AC_CHECK_PROG' + + -- Macro: AC_PROGRAM_EGREP + 'AC_EGREP_CPP' + + -- Macro: AC_PROGRAM_PATH + 'AC_PATH_PROG' + + -- Macro: AC_REMOTE_TAPE + removed because of limited usefulness + + -- Macro: AC_RESTARTABLE_SYSCALLS + 'AC_SYS_RESTARTABLE_SYSCALLS' + + -- Macro: AC_RETSIGTYPE + 'AC_TYPE_SIGNAL' + + -- Macro: AC_RSH + Removed because of limited usefulness. + + -- Macro: AC_SCO_INTL + If on SCO UNIX, add '-lintl' to output variable 'LIBS'. This macro + used to + + AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS") + + now it just calls 'AC_FUNC_STRFTIME' instead. + + -- Macro: AC_SETVBUF_REVERSED + 'AC_FUNC_SETVBUF_REVERSED' + + -- Macro: AC_SET_MAKE + 'AC_PROG_MAKE_SET' + + -- Macro: AC_SIZEOF_TYPE + 'AC_CHECK_SIZEOF' + + -- Macro: AC_SIZE_T + 'AC_TYPE_SIZE_T' + + -- Macro: AC_STAT_MACROS_BROKEN + 'AC_HEADER_STAT' + + -- Macro: AC_STDC_HEADERS + 'AC_HEADER_STDC' + + -- Macro: AC_STRCOLL + 'AC_FUNC_STRCOLL' + + -- Macro: AC_ST_BLKSIZE + 'AC_STRUCT_ST_BLKSIZE' + + -- Macro: AC_ST_BLOCKS + 'AC_STRUCT_ST_BLOCKS' + + -- Macro: AC_ST_RDEV + 'AC_STRUCT_ST_RDEV' + + -- Macro: AC_SYS_RESTARTABLE_SYSCALLS + If the system automatically restarts a system call that is + interrupted by a signal, define 'HAVE_RESTARTABLE_SYSCALLS'. This + macro does not check if system calls are restarted in general-it + tests whether a signal handler installed with 'signal' (but not + 'sigaction') causes system calls to be restarted. It does not test + if system calls can be restarted when interrupted by signals that + have no handler. + + These days portable programs should use 'sigaction' with + 'SA_RESTART' if they want restartable system calls. They should + not rely on 'HAVE_RESTARTABLE_SYSCALLS', since nowadays whether a + system call is restartable is a dynamic issue, not a + configuration-time issue. + + -- Macro: AC_SYS_SIGLIST_DECLARED + 'AC_DECL_SYS_SIGLIST' + + -- Macro: AC_TEST_CPP + 'AC_TRY_CPP' + + -- Macro: AC_TEST_PROGRAM + 'AC_TRY_RUN' + + -- Macro: AC_TIMEZONE + 'AC_STRUCT_TIMEZONE' + + -- Macro: AC_TIME_WITH_SYS_TIME + 'AC_HEADER_TIME' + + -- Macro: AC_UID_T + 'AC_TYPE_UID_T' + + -- Macro: AC_UNISTD_H + Same as 'AC_CHECK_HEADERS(unistd.h)'. + + -- Macro: AC_USG + Define 'USG' if the BSD string functions are defined in + 'strings.h'. You should no longer depend upon 'USG', but on + 'HAVE_STRING_H', see *Note Standard Symbols::. + + -- Macro: AC_UTIME_NULL + 'AC_FUNC_UTIME_NULL' + + -- Macro: AC_VALIDATE_CACHED_SYSTEM_TUPLE ([CMD]) + If the cache file is inconsistent with the current host, target and + build system types, it used to execute CMD or print a default error + message. + + This is now handled by default. + + -- Macro: AC_VERBOSE (RESULT-DESCRIPTION) + 'AC_MSG_RESULT'. + + -- Macro: AC_VFORK + 'AC_FUNC_VFORK' + + -- Macro: AC_VPRINTF + 'AC_FUNC_VPRINTF' + + -- Macro: AC_WAIT3 + 'AC_FUNC_WAIT3' + + -- Macro: AC_WARN + 'AC_MSG_WARN' + + -- Macro: AC_WORDS_BIGENDIAN + 'AC_C_BIGENDIAN' + + -- Macro: AC_XENIX_DIR + This macro used to add '-lx' to output variable 'LIBS' if on Xenix. + Also, if 'dirent.h' is being checked for, added '-ldir' to 'LIBS'. + Now it is merely an alias of 'AC_HEADER_DIRENT' instead, plus some + code to detect whether running XENIX on which you should not + depend: + + AC_MSG_CHECKING([for Xenix]) + AC_EGREP_CPP(yes, + [#if defined M_XENIX && !defined M_UNIX + yes + #endif], + [AC_MSG_RESULT([yes]); XENIX=yes], + [AC_MSG_RESULT([no]); XENIX=]) + + -- Macro: AC_YYTEXT_POINTER + 'AC_DECL_YYTEXT' + + +File: autoconf.info, Node: Autoconf 1, Next: Autoconf 2.13, Prev: Obsolete Macros, Up: Obsolete Constructs + +15.5 Upgrading From Version 1 +============================= + +Autoconf version 2 is mostly backward compatible with version 1. +However, it introduces better ways to do some things, and doesn't +support some of the ugly things in version 1. So, depending on how +sophisticated your 'configure.ac' files are, you might have to do some +manual work in order to upgrade to version 2. This chapter points out +some problems to watch for when upgrading. Also, perhaps your +'configure' scripts could benefit from some of the new features in +version 2; the changes are summarized in the file 'NEWS' in the Autoconf +distribution. + +* Menu: + +* Changed File Names:: Files you might rename +* Changed Makefiles:: New things to put in 'Makefile.in' +* Changed Macros:: Macro calls you might replace +* Changed Results:: Changes in how to check test results +* Changed Macro Writing:: Better ways to write your own macros + + +File: autoconf.info, Node: Changed File Names, Next: Changed Makefiles, Prev: Autoconf 1, Up: Autoconf 1 + +15.5.1 Changed File Names +------------------------- + +If you have an 'aclocal.m4' installed with Autoconf (as opposed to in a +particular package's source directory), you must rename it to +'acsite.m4'. *Note autoconf Invocation::. + + If you distribute 'install.sh' with your package, rename it to +'install-sh' so 'make' builtin rules won't inadvertently create a file +called 'install' from it. 'AC_PROG_INSTALL' looks for the script under +both names, but it is best to use the new name. + + If you were using 'config.h.top', 'config.h.bot', or 'acconfig.h', +you still can, but you will have less clutter if you use the 'AH_' +macros. *Note Autoheader Macros::. + + +File: autoconf.info, Node: Changed Makefiles, Next: Changed Macros, Prev: Changed File Names, Up: Autoconf 1 + +15.5.2 Changed Makefiles +------------------------ + +Add '@CFLAGS@', '@CPPFLAGS@', and '@LDFLAGS@' in your 'Makefile.in' +files, so they can take advantage of the values of those variables in +the environment when 'configure' is run. Doing this isn't necessary, +but it's a convenience for users. + + Also add '@configure_input@' in a comment to each input file for +'AC_OUTPUT', so that the output files will contain a comment saying they +were produced by 'configure'. Automatically selecting the right comment +syntax for all the kinds of files that people call 'AC_OUTPUT' on became +too much work. + + Add 'config.log' and 'config.cache' to the list of files you remove +in 'distclean' targets. + + If you have the following in 'Makefile.in': + + prefix = /usr/local + exec_prefix = $(prefix) + +you must change it to: + + prefix = @prefix@ + exec_prefix = @exec_prefix@ + +The old behavior of replacing those variables without '@' characters +around them has been removed. + + +File: autoconf.info, Node: Changed Macros, Next: Changed Results, Prev: Changed Makefiles, Up: Autoconf 1 + +15.5.3 Changed Macros +--------------------- + +Many of the macros were renamed in Autoconf version 2. You can still +use the old names, but the new ones are clearer, and it's easier to find +the documentation for them. *Note Obsolete Macros::, for a table +showing the new names for the old macros. Use the 'autoupdate' program +to convert your 'configure.ac' to using the new macro names. *Note +autoupdate Invocation::. + + Some macros have been superseded by similar ones that do the job +better, but are not call-compatible. If you get warnings about calling +obsolete macros while running 'autoconf', you may safely ignore them, +but your 'configure' script will generally work better if you follow the +advice it prints about what to replace the obsolete macros with. In +particular, the mechanism for reporting the results of tests has +changed. If you were using 'echo' or 'AC_VERBOSE' (perhaps via +'AC_COMPILE_CHECK'), your 'configure' script's output will look better +if you switch to 'AC_MSG_CHECKING' and 'AC_MSG_RESULT'. *Note Printing +Messages::. Those macros work best in conjunction with cache variables. +*Note Caching Results::. + + +File: autoconf.info, Node: Changed Results, Next: Changed Macro Writing, Prev: Changed Macros, Up: Autoconf 1 + +15.5.4 Changed Results +---------------------- + +If you were checking the results of previous tests by examining the +shell variable 'DEFS', you need to switch to checking the values of the +cache variables for those tests. 'DEFS' no longer exists while +'configure' is running; it is only created when generating output files. +This difference from version 1 is because properly quoting the contents +of that variable turned out to be too cumbersome and inefficient to do +every time 'AC_DEFINE' is called. *Note Cache Variable Names::. + + For example, here is a 'configure.ac' fragment written for Autoconf +version 1: + + AC_HAVE_FUNCS(syslog) + case "$DEFS" in + *-DHAVE_SYSLOG*) ;; + *) # syslog is not in the default libraries. See if it's in some other. + saved_LIBS="$LIBS" + for lib in bsd socket inet; do + AC_CHECKING(for syslog in -l$lib) + LIBS="$saved_LIBS -l$lib" + AC_HAVE_FUNCS(syslog) + case "$DEFS" in + *-DHAVE_SYSLOG*) break ;; + *) ;; + esac + LIBS="$saved_LIBS" + done ;; + esac + + Here is a way to write it for version 2: + + AC_CHECK_FUNCS(syslog) + if test $ac_cv_func_syslog = no; then + # syslog is not in the default libraries. See if it's in some other. + for lib in bsd socket inet; do + AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG) + LIBS="$LIBS -l$lib"; break]) + done + fi + + If you were working around bugs in 'AC_DEFINE_UNQUOTED' by adding +backslashes before quotes, you need to remove them. It now works +predictably, and does not treat quotes (except back quotes) specially. +*Note Setting Output Variables::. + + All of the boolean shell variables set by Autoconf macros now use +'yes' for the true value. Most of them use 'no' for false, though for +backward compatibility some use the empty string instead. If you were +relying on a shell variable being set to something like 1 or 't' for +true, you need to change your tests. + + +File: autoconf.info, Node: Changed Macro Writing, Prev: Changed Results, Up: Autoconf 1 + +15.5.5 Changed Macro Writing +---------------------------- + +When defining your own macros, you should now use 'AC_DEFUN' instead of +'define'. 'AC_DEFUN' automatically calls 'AC_PROVIDE' and ensures that +macros called via 'AC_REQUIRE' do not interrupt other macros, to prevent +nested 'checking...' messages on the screen. There's no actual harm in +continuing to use the older way, but it's less convenient and +attractive. *Note Macro Definitions::. + + You probably looked at the macros that came with Autoconf as a guide +for how to do things. It would be a good idea to take a look at the new +versions of them, as the style is somewhat improved and they take +advantage of some new features. + + If you were doing tricky things with undocumented Autoconf internals +(macros, variables, diversions), check whether you need to change +anything to account for changes that have been made. Perhaps you can +even use an officially supported technique in version 2 instead of +kludging. Or perhaps not. + + To speed up your locally written feature tests, add caching to them. +See whether any of your tests are of general enough usefulness to +encapsulate into macros that you can share. + + +File: autoconf.info, Node: Autoconf 2.13, Prev: Autoconf 1, Up: Obsolete Constructs + +15.6 Upgrading From Version 2.13 +================================ + +The introduction of the previous section (*note Autoconf 1::) perfectly +suits this section... + + Autoconf version 2.50 is mostly backward compatible with version + 2.13. However, it introduces better ways to do some things, and + doesn't support some of the ugly things in version 2.13. So, + depending on how sophisticated your 'configure.ac' files are, you + might have to do some manual work in order to upgrade to version + 2.50. This chapter points out some problems to watch for when + upgrading. Also, perhaps your 'configure' scripts could benefit + from some of the new features in version 2.50; the changes are + summarized in the file 'NEWS' in the Autoconf distribution. + +* Menu: + +* Changed Quotation:: Broken code which used to work +* New Macros:: Interaction with foreign macros + + +File: autoconf.info, Node: Changed Quotation, Next: New Macros, Prev: Autoconf 2.13, Up: Autoconf 2.13 + +15.6.1 Changed Quotation +------------------------ + +The most important changes are invisible to you: the implementation of +most macros have completely changed. This allowed more factorization of +the code, better error messages, a higher uniformity of the user's +interface etc. Unfortunately, as a side effect, some construct which +used to (miraculously) work might break starting with Autoconf 2.50. +The most common culprit is bad quotation. + + For instance, in the following example, the message is not properly +quoted: + + AC_INIT + AC_CHECK_HEADERS(foo.h,, + AC_MSG_ERROR(cannot find foo.h, bailing out)) + AC_OUTPUT + +Autoconf 2.13 simply ignores it: + + $ autoconf-2.13; ./configure --silent + creating cache ./config.cache + configure: error: cannot find foo.h + $ + +while Autoconf 2.50 will produce a broken 'configure': + + $ autoconf-2.50; ./configure --silent + configure: error: cannot find foo.h + ./configure: exit: bad non-numeric arg `bailing' + ./configure: exit: bad non-numeric arg `bailing' + $ + + The message needs to be quoted, and the 'AC_MSG_ERROR' invocation +too! + + AC_INIT + AC_CHECK_HEADERS(foo.h,, + [AC_MSG_ERROR([cannot find foo.h, bailing out])]) + AC_OUTPUT + + Many many (and many more) Autoconf macros were lacking proper +quotation, including no less than... 'AC_DEFUN' itself! + + $ cat configure.in + AC_DEFUN([AC_PROG_INSTALL], + [# My own much better version + ]) + AC_INIT + AC_PROG_INSTALL + AC_OUTPUT + $ autoconf-2.13 + autoconf: Undefined macros: + ***BUG in Autoconf--please report*** AC_FD_MSG + ***BUG in Autoconf--please report*** AC_EPI + configure.in:1:AC_DEFUN([AC_PROG_INSTALL], + configure.in:5:AC_PROG_INSTALL + $ autoconf-2.50 + $ + + +File: autoconf.info, Node: New Macros, Prev: Changed Quotation, Up: Autoconf 2.13 + +15.6.2 New Macros +----------------- + +Because Autoconf has been dormant for years, Automake provided +Autoconf-like macros for a while. Autoconf 2.50 now provides better +versions of these macros, integrated in the 'AC_' namespace, instead of +'AM_'. But in order to ease the upgrading via 'autoupdate', bindings to +such 'AM_' macros are provided. + + Unfortunately Automake did not quote the name of these macros! +Therefore, when 'm4' find in 'aclocal.m4' something like +'AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)', 'AM_TYPE_PTRDIFF_T' is expanded, +replaced with its Autoconf definition. + + Fortunately Autoconf catches pre-'AC_INIT' expansions, and will +complain, in its own words: + + $ cat configure.in + AC_INIT + AM_TYPE_PTRDIFF_T + $ aclocal-1.4 + $ autoconf + ./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion + actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from... + ./aclocal.m4:17: the top level + $ + + Future versions of Automake will simply no longer define most of +these macros, and will properly quote the names of the remaining macros. +But you don't have to wait for it to happen to do the right thing right +now: do not depend upon macros from Automake as it is simply not its job +to provide macros (but the one it requires by itself): + + $ cat configure.in + AC_INIT + AM_TYPE_PTRDIFF_T + $ rm aclocal.m4 + $ autoupdate + autoupdate: `configure.in' is updated + $ cat configure.in + AC_INIT + AC_CHECK_TYPES([ptrdiff_t]) + $ aclocal-1.4 + $ autoconf + $ + + +File: autoconf.info, Node: Questions, Next: History, Prev: Obsolete Constructs, Up: Top + +16 Questions About Autoconf +*************************** + +Several questions about Autoconf come up occasionally. Here some of +them are addressed. + +* Menu: + +* Distributing:: Distributing 'configure' scripts +* Why GNU m4:: Why not use the standard M4? +* Bootstrapping:: Autoconf and GNU M4 require each other? +* Why Not Imake:: Why GNU uses 'configure' instead of Imake + + +File: autoconf.info, Node: Distributing, Next: Why GNU m4, Prev: Questions, Up: Questions + +16.1 Distributing 'configure' Scripts +===================================== + + What are the restrictions on distributing 'configure' + scripts that Autoconf generates? How does that affect my + programs that use them? + + There are no restrictions on how the configuration scripts that +Autoconf produces may be distributed or used. In Autoconf version 1, +they were covered by the GNU General Public License. We still encourage +software authors to distribute their work under terms like those of the +GPL, but doing so is not required to use Autoconf. + + Of the other files that might be used with 'configure', 'config.h.in' +is under whatever copyright you use for your 'configure.ac'. +'config.sub' and 'config.guess' have an exception to the GPL when they +are used with an Autoconf-generated 'configure' script, which permits +you to distribute them under the same terms as the rest of your package. +'install-sh' is from the X Consortium and is not copyrighted. + + +File: autoconf.info, Node: Why GNU m4, Next: Bootstrapping, Prev: Distributing, Up: Questions + +16.2 Why Require GNU M4? +======================== + + Why does Autoconf require GNU M4? + + Many M4 implementations have hard-coded limitations on the size and +number of macros that Autoconf exceeds. They also lack several builtin +macros that it would be difficult to get along without in a +sophisticated application like Autoconf, including: + + builtin + indir + patsubst + __file__ + __line__ + + Autoconf requires version 1.4 or above of GNU M4 because it uses +frozen state files. + + Since only software maintainers need to use Autoconf, and since GNU +M4 is simple to configure and install, it seems reasonable to require +GNU M4 to be installed also. Many maintainers of GNU and other free +software already have most of the GNU utilities installed, since they +prefer them. + + +File: autoconf.info, Node: Bootstrapping, Next: Why Not Imake, Prev: Why GNU m4, Up: Questions + +16.3 How Can I Bootstrap? +========================= + + If Autoconf requires GNU M4 and GNU M4 has an Autoconf + 'configure' script, how do I bootstrap? It seems like a chicken + and egg problem! + + This is a misunderstanding. Although GNU M4 does come with a +'configure' script produced by Autoconf, Autoconf is not required in +order to run the script and install GNU M4. Autoconf is only required +if you want to change the M4 'configure' script, which few people have +to do (mainly its maintainer). + + +File: autoconf.info, Node: Why Not Imake, Prev: Bootstrapping, Up: Questions + +16.4 Why Not Imake? +=================== + + Why not use Imake instead of 'configure' scripts? + + Several people have written addressing this question, so I include +adaptations of their explanations here. + + The following answer is based on one written by Richard Pixley: + + Autoconf generated scripts frequently work on machines that it has + never been set up to handle before. That is, it does a good job of + inferring a configuration for a new system. Imake cannot do this. + + Imake uses a common database of host specific data. For X11, this + makes sense because the distribution is made as a collection of + tools, by one central authority who has control over the database. + + GNU tools are not released this way. Each GNU tool has a + maintainer; these maintainers are scattered across the world. + Using a common database would be a maintenance nightmare. Autoconf + may appear to be this kind of database, but in fact it is not. + Instead of listing host dependencies, it lists program + requirements. + + If you view the GNU suite as a collection of native tools, then the + problems are similar. But the GNU development tools can be + configured as cross tools in almost any host+target permutation. + All of these configurations can be installed concurrently. They + can even be configured to share host independent files across + hosts. Imake doesn't address these issues. + + Imake templates are a form of standardization. The GNU coding + standards address the same issues without necessarily imposing the + same restrictions. + + Here is some further explanation, written by Per Bothner: + + One of the advantages of Imake is that it easy to generate large + Makefiles using 'cpp''s '#include' and macro mechanisms. However, + 'cpp' is not programmable: it has limited conditional facilities, + and no looping. And 'cpp' cannot inspect its environment. + + All of these problems are solved by using 'sh' instead of 'cpp'. + The shell is fully programmable, has macro substitution, can + execute (or source) other shell scripts, and can inspect its + environment. + + Paul Eggert elaborates more: + + With Autoconf, installers need not assume that Imake itself is + already installed and working well. This may not seem like much of + an advantage to people who are accustomed to Imake. But on many + hosts Imake is not installed or the default installation is not + working well, and requiring Imake to install a package hinders the + acceptance of that package on those hosts. For example, the Imake + template and configuration files might not be installed properly on + a host, or the Imake build procedure might wrongly assume that all + source files are in one big directory tree, or the Imake + configuration might assume one compiler whereas the package or the + installer needs to use another, or there might be a version + mismatch between the Imake expected by the package and the Imake + supported by the host. These problems are much rarer with + Autoconf, where each package comes with its own independent + configuration processor. + + Also, Imake often suffers from unexpected interactions between + 'make' and the installer's C preprocessor. The fundamental problem + here is that the C preprocessor was designed to preprocess C + programs, not 'Makefile's. This is much less of a problem with + Autoconf, which uses the general-purpose preprocessor 'm4', and + where the package's author (rather than the installer) does the + preprocessing in a standard way. + + Finally, Mark Eichin notes: + + Imake isn't all that extensible, either. In order to add new + features to Imake, you need to provide your own project template, + and duplicate most of the features of the existing one. This means + that for a sophisticated project, using the vendor-provided Imake + templates fails to provide any leverage--since they don't cover + anything that your own project needs (unless it is an X11 program). + + On the other side, though: + + The one advantage that Imake has over 'configure': 'Imakefile's + tend to be much shorter (likewise, less redundant) than + 'Makefile.in's. There is a fix to this, however--at least for the + Kerberos V5 tree, we've modified things to call in common 'post.in' + and 'pre.in' 'Makefile' fragments for the entire tree. This means + that a lot of common things don't have to be duplicated, even + though they normally are in 'configure' setups. + + +File: autoconf.info, Node: History, Next: Environment Variable Index, Prev: Questions, Up: Top + +17 History of Autoconf +********************** + +You may be wondering, Why was Autoconf originally written? How did it +get into its present form? (Why does it look like gorilla spit?) If +you're not wondering, then this chapter contains no information useful +to you, and you might as well skip it. If you _are_ wondering, then let +there be light... + +* Menu: + +* Genesis:: Prehistory and naming of 'configure' +* Exodus:: The plagues of M4 and Perl +* Leviticus:: The priestly code of portability arrives +* Numbers:: Growth and contributors +* Deuteronomy:: Approaching the promises of easy configuration + + +File: autoconf.info, Node: Genesis, Next: Exodus, Prev: History, Up: History + +17.1 Genesis +============ + +In June 1991 I was maintaining many of the GNU utilities for the Free +Software Foundation. As they were ported to more platforms and more +programs were added, the number of '-D' options that users had to select +in the 'Makefile' (around 20) became burdensome. Especially for me--I +had to test each new release on a bunch of different systems. So I +wrote a little shell script to guess some of the correct settings for +the fileutils package, and released it as part of fileutils 2.0. That +'configure' script worked well enough that the next month I adapted it +(by hand) to create similar 'configure' scripts for several other GNU +utilities packages. Brian Berliner also adapted one of my scripts for +his CVS revision control system. + + Later that summer, I learned that Richard Stallman and Richard Pixley +were developing similar scripts to use in the GNU compiler tools; so I +adapted my 'configure' scripts to support their evolving interface: +using the file name 'Makefile.in' as the templates; adding '+srcdir', +the first option (of many); and creating 'config.status' files. + + +File: autoconf.info, Node: Exodus, Next: Leviticus, Prev: Genesis, Up: History + +17.2 Exodus +=========== + +As I got feedback from users, I incorporated many improvements, using +Emacs to search and replace, cut and paste, similar changes in each of +the scripts. As I adapted more GNU utilities packages to use +'configure' scripts, updating them all by hand became impractical. Rich +Murphey, the maintainer of the GNU graphics utilities, sent me mail +saying that the 'configure' scripts were great, and asking if I had a +tool for generating them that I could send him. No, I thought, but I +should! So I started to work out how to generate them. And the journey +from the slavery of hand-written 'configure' scripts to the abundance +and ease of Autoconf began. + + Cygnus 'configure', which was being developed at around that time, is +table driven; it is meant to deal mainly with a discrete number of +system types with a small number of mainly unguessable features (such as +details of the object file format). The automatic configuration system +that Brian Fox had developed for Bash takes a similar approach. For +general use, it seems to me a hopeless cause to try to maintain an +up-to-date database of which features each variant of each operating +system has. It's easier and more reliable to check for most features on +the fly--especially on hybrid systems that people have hacked on locally +or that have patches from vendors installed. + + I considered using an architecture similar to that of Cygnus +'configure', where there is a single 'configure' script that reads +pieces of 'configure.in' when run. But I didn't want to have to +distribute all of the feature tests with every package, so I settled on +having a different 'configure' made from each 'configure.in' by a +preprocessor. That approach also offered more control and flexibility. + + I looked briefly into using the Metaconfig package, by Larry Wall, +Harlan Stenn, and Raphael Manfredi, but I decided not to for several +reasons. The 'Configure' scripts it produces are interactive, which I +find quite inconvenient; I didn't like the ways it checked for some +features (such as library functions); I didn't know that it was still +being maintained, and the 'Configure' scripts I had seen didn't work on +many modern systems (such as System V R4 and NeXT); it wasn't very +flexible in what it could do in response to a feature's presence or +absence; I found it confusing to learn; and it was too big and complex +for my needs (I didn't realize then how much Autoconf would eventually +have to grow). + + I considered using Perl to generate my style of 'configure' scripts, +but decided that M4 was better suited to the job of simple textual +substitutions: it gets in the way less, because output is implicit. +Plus, everyone already has it. (Initially I didn't rely on the GNU +extensions to M4.) Also, some of my friends at the University of +Maryland had recently been putting M4 front ends on several programs, +including 'tvtwm', and I was interested in trying out a new language. + + +File: autoconf.info, Node: Leviticus, Next: Numbers, Prev: Exodus, Up: History + +17.3 Leviticus +============== + +Since my 'configure' scripts determine the system's capabilities +automatically, with no interactive user intervention, I decided to call +the program that generates them Autoconfig. But with a version number +tacked on, that name would be too long for old UNIX file systems, so I +shortened it to Autoconf. + + In the fall of 1991 I called together a group of fellow questers +after the Holy Grail of portability (er, that is, alpha testers) to give +me feedback as I encapsulated pieces of my handwritten scripts in M4 +macros and continued to add features and improve the techniques used in +the checks. Prominent among the testers were François Pinard, who came +up with the idea of making an 'autoconf' shell script to run 'm4' and +check for unresolved macro calls; Richard Pixley, who suggested running +the compiler instead of searching the file system to find include files +and symbols, for more accurate results; Karl Berry, who got Autoconf to +configure TeX and added the macro index to the documentation; and Ian +Lance Taylor, who added support for creating a C header file as an +alternative to putting '-D' options in a 'Makefile', so he could use +Autoconf for his UUCP package. The alpha testers cheerfully adjusted +their files again and again as the names and calling conventions of the +Autoconf macros changed from release to release. They all contributed +many specific checks, great ideas, and bug fixes. + + +File: autoconf.info, Node: Numbers, Next: Deuteronomy, Prev: Leviticus, Up: History + +17.4 Numbers +============ + +In July 1992, after months of alpha testing, I released Autoconf 1.0, +and converted many GNU packages to use it. I was surprised by how +positive the reaction to it was. More people started using it than I +could keep track of, including people working on software that wasn't +part of the GNU Project (such as TCL, FSP, and Kerberos V5). Autoconf +continued to improve rapidly, as many people using the 'configure' +scripts reported problems they encountered. + + Autoconf turned out to be a good torture test for M4 implementations. +UNIX 'm4' started to dump core because of the length of the macros that +Autoconf defined, and several bugs showed up in GNU 'm4' as well. +Eventually, we realized that we needed to use some features that only +GNU M4 has. 4.3BSD 'm4', in particular, has an impoverished set of +builtin macros; the System V version is better, but still doesn't +provide everything we need. + + More development occurred as people put Autoconf under more stresses +(and to uses I hadn't anticipated). Karl Berry added checks for X11. +david zuhn contributed C++ support. François Pinard made it diagnose +invalid arguments. Jim Blandy bravely coerced it into configuring GNU +Emacs, laying the groundwork for several later improvements. Roland +McGrath got it to configure the GNU C Library, wrote the 'autoheader' +script to automate the creation of C header file templates, and added a +'--verbose' option to 'configure'. Noah Friedman added the +'--autoconf-dir' option and 'AC_MACRODIR' environment variable. (He +also coined the term "autoconfiscate" to mean "adapt a software package +to use Autoconf".) Roland and Noah improved the quoting protection in +'AC_DEFINE' and fixed many bugs, especially when I got sick of dealing +with portability problems from February through June, 1993. + + +File: autoconf.info, Node: Deuteronomy, Prev: Numbers, Up: History + +17.5 Deuteronomy +================ + +A long wish list for major features had accumulated, and the effect of +several years of patching by various people had left some residual +cruft. In April 1994, while working for Cygnus Support, I began a major +revision of Autoconf. I added most of the features of the Cygnus +'configure' that Autoconf had lacked, largely by adapting the relevant +parts of Cygnus 'configure' with the help of david zuhn and Ken Raeburn. +These features include support for using 'config.sub', 'config.guess', +'--host', and '--target'; making links to files; and running 'configure' +scripts in subdirectories. Adding these features enabled Ken to convert +GNU 'as', and Rob Savoye to convert DejaGNU, to using Autoconf. + + I added more features in response to other peoples' requests. Many +people had asked for 'configure' scripts to share the results of the +checks between runs, because (particularly when configuring a large +source tree, like Cygnus does) they were frustratingly slow. Mike +Haertel suggested adding site-specific initialization scripts. People +distributing software that had to unpack on MS-DOS asked for a way to +override the '.in' extension on the file names, which produced file +names like 'config.h.in' containing two dots. Jim Avera did an +extensive examination of the problems with quoting in 'AC_DEFINE' and +'AC_SUBST'; his insights led to significant improvements. Richard +Stallman asked that compiler output be sent to 'config.log' instead of +'/dev/null', to help people debug the Emacs 'configure' script. + + I made some other changes because of my dissatisfaction with the +quality of the program. I made the messages showing results of the +checks less ambiguous, always printing a result. I regularized the +names of the macros and cleaned up coding style inconsistencies. I +added some auxiliary utilities that I had developed to help convert +source code packages to use Autoconf. With the help of François Pinard, +I made the macros not interrupt each others' messages. (That feature +revealed some performance bottlenecks in GNU 'm4', which he hastily +corrected!) I reorganized the documentation around problems people want +to solve. And I began a test suite, because experience had shown that +Autoconf has a pronounced tendency to regress when we change it. + + Again, several alpha testers gave invaluable feedback, especially +François Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, and +Mark Eichin. + + Finally, version 2.0 was ready. And there was much rejoicing. (And +I have free time again. I think. Yeah, right.) + + +File: autoconf.info, Node: Environment Variable Index, Next: Output Variable Index, Prev: History, Up: Top + +Environment Variable Index +************************** + +This is an alphabetical list of the environment variables that Autoconf +checks. + + +* Menu: + +* AC_MACRODIR: autoscan Invocation. (line 54) +* AC_MACRODIR <1>: autoconf Invocation. (line 45) +* AC_MACRODIR <2>: autoreconf Invocation. + (line 77) +* AC_MACRODIR <3>: autoheader Invocation. + (line 62) +* AC_MACRODIR <4>: autoupdate Invocation. + (line 42) +* CDPATH: Special Shell Variables. + (line 13) +* CONFIG_COMMANDS: Obsolete config.status Use. + (line 11) +* CONFIG_FILES: Obsolete config.status Use. + (line 15) +* CONFIG_HEADERS: Obsolete config.status Use. + (line 20) +* CONFIG_LINKS: Obsolete config.status Use. + (line 25) +* CONFIG_SHELL: config.status Invocation. + (line 75) +* CONFIG_SITE: Site Defaults. (line 10) +* CONFIG_STATUS: config.status Invocation. + (line 79) +* IFS: Special Shell Variables. + (line 45) +* LANG: Special Shell Variables. + (line 59) +* LANGUAGE: Special Shell Variables. + (line 59) +* LC_ALL: Special Shell Variables. + (line 59) +* LC_COLLATE: Special Shell Variables. + (line 59) +* LC_CTYPE: Special Shell Variables. + (line 59) +* LC_MESSAGES: Special Shell Variables. + (line 59) +* LC_NUMERIC: Special Shell Variables. + (line 59) +* LC_TIME: Special Shell Variables. + (line 59) +* NULLCMD: Special Shell Variables. + (line 77) +* PATH_SEPARATOR: Special Shell Variables. + (line 88) +* RANDOM: Special Shell Variables. + (line 97) +* SIMPLE_BACKUP_SUFFIX: autoupdate Invocation. + (line 16) +* status: Special Shell Variables. + (line 84) +* WARNINGS: autoconf Invocation. (line 65) +* WARNINGS <1>: autoheader Invocation. + (line 78) + + +File: autoconf.info, Node: Output Variable Index, Next: Preprocessor Symbol Index, Prev: Environment Variable Index, Up: Top + +Output Variable Index +********************* + +This is an alphabetical list of the variables that Autoconf can +substitute into files that it creates, typically one or more +'Makefile's. *Note Setting Output Variables::, for more information on +how this is done. + + +* Menu: + +* ALLOCA: Particular Functions. + (line 10) +* AWK: Particular Programs. (line 10) +* bindir: Installation Directory Variables. + (line 12) +* build: Canonicalizing. (line 26) +* build_alias: Canonicalizing. (line 9) +* build_cpu: Canonicalizing. (line 26) +* build_os: Canonicalizing. (line 26) +* build_vendor: Canonicalizing. (line 26) +* CC: C Compiler. (line 7) +* CC <1>: C Compiler. (line 34) +* CC <2>: C Compiler. (line 156) +* CC <3>: System Services. (line 44) +* CC <4>: UNIX Variants. (line 18) +* CFLAGS: Preset Output Variables. + (line 15) +* CFLAGS <1>: C Compiler. (line 7) +* configure_input: Preset Output Variables. + (line 22) +* CPP: C Compiler. (line 47) +* CPPFLAGS: Preset Output Variables. + (line 36) +* cross_compiling: Specifying Names. (line 26) +* CXX: C++ Compiler. (line 7) +* CXXCPP: C++ Compiler. (line 31) +* CXXFLAGS: Preset Output Variables. + (line 43) +* CXXFLAGS <1>: C++ Compiler. (line 7) +* datadir: Installation Directory Variables. + (line 15) +* DEFS: Preset Output Variables. + (line 50) +* ECHO_C: Preset Output Variables. + (line 60) +* ECHO_N: Preset Output Variables. + (line 60) +* ECHO_T: Preset Output Variables. + (line 60) +* EGREP: Particular Programs. (line 16) +* exec_prefix: Installation Directory Variables. + (line 19) +* EXEEXT: Compilers and Preprocessors. + (line 6) +* EXEEXT <1>: Obsolete Macros. (line 145) +* F77: Fortran 77 Compiler. (line 7) +* FFLAGS: Preset Output Variables. + (line 72) +* FFLAGS <1>: Fortran 77 Compiler. (line 7) +* FGREP: Particular Programs. (line 20) +* FLIBS: Fortran 77 Compiler. (line 38) +* GETGROUPS_LIBS: Particular Functions. + (line 97) +* GETLOADAVG_LIBS: Particular Functions. + (line 103) +* GREP: Particular Programs. (line 24) +* host: Canonicalizing. (line 34) +* host_alias: Canonicalizing. (line 9) +* host_cpu: Canonicalizing. (line 34) +* host_os: Canonicalizing. (line 34) +* host_vendor: Canonicalizing. (line 34) +* includedir: Installation Directory Variables. + (line 26) +* infodir: Installation Directory Variables. + (line 29) +* INSTALL: Particular Programs. (line 28) +* INSTALL_DATA: Particular Programs. (line 28) +* INSTALL_PROGRAM: Particular Programs. (line 28) +* INSTALL_SCRIPT: Particular Programs. (line 28) +* KMEM_GROUP: Particular Functions. + (line 103) +* LDFLAGS: Preset Output Variables. + (line 79) +* LEX: Particular Programs. (line 57) +* LEXLIB: Particular Programs. (line 57) +* LEX_OUTPUT_ROOT: Particular Programs. (line 57) +* libdir: Installation Directory Variables. + (line 32) +* libexecdir: Installation Directory Variables. + (line 35) +* LIBOBJS: Particular Functions. + (line 103) +* LIBOBJS <1>: Particular Functions. + (line 160) +* LIBOBJS <2>: Particular Functions. + (line 167) +* LIBOBJS <3>: Generic Functions. (line 44) +* LIBOBJS <4>: Generic Functions. (line 84) +* LIBOBJS <5>: Particular Structures. + (line 17) +* LIBS: Preset Output Variables. + (line 87) +* LIBS <1>: Obsolete Macros. (line 408) +* LIBS <2>: Obsolete Macros. (line 515) +* LN_S: Particular Programs. (line 95) +* localstatedir: Installation Directory Variables. + (line 38) +* mandir: Installation Directory Variables. + (line 41) +* NEED_SETGID: Particular Functions. + (line 103) +* OBJEXT: Compilers and Preprocessors. + (line 10) +* OBJEXT <1>: Obsolete Macros. (line 300) +* oldincludedir: Installation Directory Variables. + (line 44) +* POW_LIB: Particular Functions. + (line 216) +* prefix: Installation Directory Variables. + (line 47) +* program_transform_name: Transforming Names. (line 11) +* RANLIB: Particular Programs. (line 114) +* sbindir: Installation Directory Variables. + (line 52) +* SET_MAKE: Output. (line 37) +* sharedstatedir: Installation Directory Variables. + (line 56) +* srcdir: Preset Output Variables. + (line 94) +* subdirs: Subdirectories. (line 12) +* sysconfdir: Installation Directory Variables. + (line 60) +* target: Canonicalizing. (line 46) +* target_alias: Canonicalizing. (line 9) +* target_cpu: Canonicalizing. (line 46) +* target_os: Canonicalizing. (line 46) +* target_vendor: Canonicalizing. (line 46) +* top_srcdir: Preset Output Variables. + (line 97) +* X_CFLAGS: System Services. (line 26) +* X_EXTRA_LIBS: System Services. (line 26) +* X_LIBS: System Services. (line 26) +* X_PRE_LIBS: System Services. (line 26) +* YACC: Particular Programs. (line 118) + + +File: autoconf.info, Node: Preprocessor Symbol Index, Next: Autoconf Macro Index, Prev: Output Variable Index, Up: Top + +Preprocessor Symbol Index +************************* + +This is an alphabetical list of the C preprocessor symbols that the +Autoconf macros define. To work with Autoconf, C source code needs to +use these names in '#if' directives. + + +* Menu: + +* _ALL_SOURCE: UNIX Variants. (line 13) +* _FILE_OFFSET_BITS: System Services. (line 44) +* _LARGEFILE_SOURCE: Particular Functions. + (line 93) +* _LARGE_FILES: System Services. (line 44) +* _MINIX: UNIX Variants. (line 25) +* _POSIX_1_SOURCE: UNIX Variants. (line 25) +* _POSIX_SOURCE: UNIX Variants. (line 18) +* _POSIX_SOURCE <1>: UNIX Variants. (line 25) +* _POSIX_VERSION: Particular Headers. (line 130) +* __CHAR_UNSIGNED__: C Compiler. (line 120) +* CLOSEDIR_VOID: Particular Functions. + (line 58) +* const: C Compiler. (line 73) +* C_ALLOCA: Particular Functions. + (line 10) +* C_GETLOADAVG: Particular Functions. + (line 103) +* DGUX: Particular Functions. + (line 103) +* DIRENT: Obsolete Macros. (line 126) +* F77_DUMMY_MAIN: Fortran 77 Compiler. (line 64) +* F77_FUNC: Fortran 77 Compiler. (line 115) +* F77_FUNC_: Fortran 77 Compiler. (line 115) +* F77_MAIN: Fortran 77 Compiler. (line 101) +* F77_NO_MINUS_C_MINUS_O: Fortran 77 Compiler. (line 28) +* GETGROUPS_T: Particular Types. (line 10) +* GETLODAVG_PRIVILEGED: Particular Functions. + (line 103) +* GETPGRP_VOID: Particular Functions. + (line 136) +* gid_t: Particular Types. (line 39) +* GWINSZ_IN_SYS_IOCTL: Particular Headers. (line 167) +* HAVE_ALLOCA_H: Particular Functions. + (line 10) +* HAVE_CONFIG_H: Configuration Headers. + (line 25) +* HAVE_DECL_SYMBOL: Generic Declarations. + (line 23) +* HAVE_DIRENT_H: Particular Headers. (line 10) +* HAVE_DOPRNT: Particular Functions. + (line 238) +* HAVE_FUNCTION: Generic Functions. (line 25) +* HAVE_GETMNTENT: Particular Functions. + (line 131) +* HAVE_HEADER: Generic Headers. (line 43) +* HAVE_LONG_DOUBLE: C Compiler. (line 124) +* HAVE_LONG_FILE_NAMES: System Services. (line 58) +* HAVE_LSTAT_EMPTY_STRING_BUG: Particular Functions. + (line 196) +* HAVE_MMAP: Particular Functions. + (line 171) +* HAVE_NDIR_H: Particular Headers. (line 10) +* HAVE_OBSTACK: Particular Functions. + (line 176) +* HAVE_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 446) +* HAVE_STAT_EMPTY_STRING_BUG: Particular Functions. + (line 196) +* HAVE_STRCOLL: Particular Functions. + (line 210) +* HAVE_STRERROR_R: Particular Functions. + (line 222) +* HAVE_STRFTIME: Particular Functions. + (line 230) +* HAVE_STRINGIZE: C Compiler. (line 130) +* HAVE_STRUCT_STAT_ST_BLKSIZE: Particular Structures. + (line 9) +* HAVE_STRUCT_STAT_ST_BLOCKS: Particular Structures. + (line 17) +* HAVE_STRUCT_STAT_ST_RDEV: Particular Structures. + (line 23) +* HAVE_ST_BLKSIZE: Particular Structures. + (line 9) +* HAVE_ST_BLOCKS: Particular Structures. + (line 17) +* HAVE_ST_RDEV: Particular Structures. + (line 23) +* HAVE_SYS_DIR_H: Particular Headers. (line 10) +* HAVE_SYS_NDIR_H: Particular Headers. (line 10) +* HAVE_SYS_WAIT_H: Particular Headers. (line 112) +* HAVE_TM_ZONE: Particular Structures. + (line 36) +* HAVE_TZNAME: Particular Structures. + (line 36) +* HAVE_UTIME_NULL: Particular Functions. + (line 234) +* HAVE_VFORK_H: Particular Functions. + (line 71) +* HAVE_VPRINTF: Particular Functions. + (line 238) +* HAVE_WAIT3: Obsolete Macros. (line 166) +* HAVE_WORKING_FORK: Particular Functions. + (line 71) +* HAVE_WORKING_STRERROR_R: Particular Functions. + (line 222) +* HAVE_WORKING_VFORK: Particular Functions. + (line 71) +* inline: C Compiler. (line 115) +* INT_16_BITS: Obsolete Macros. (line 217) +* LONG_64_BITS: Obsolete Macros. (line 268) +* LSTAT_FOLLOWS_SLASHED_SYMLINK: Particular Functions. + (line 143) +* MAJOR_IN_MKDEV: Particular Headers. (line 46) +* MAJOR_IN_SYSMACROS: Particular Headers. (line 46) +* mode_t: Particular Types. (line 14) +* NDIR: Obsolete Macros. (line 126) +* NEED_MEMORY_H: Obsolete Macros. (line 281) +* NEED_SETGID: Particular Functions. + (line 103) +* NLIST_NAME_UNION: Particular Functions. + (line 103) +* NLIST_STRUCT: Particular Functions. + (line 103) +* NO_MINUS_C_MINUS_O: C Compiler. (line 26) +* off_t: Particular Types. (line 17) +* PARAMS: C Compiler. (line 137) +* pid_t: Particular Types. (line 20) +* PROTOTYPES: C Compiler. (line 137) +* RETSIGTYPE: Particular Types. (line 23) +* SELECT_TYPE_ARG1: Particular Functions. + (line 180) +* SELECT_TYPE_ARG234: Particular Functions. + (line 180) +* SELECT_TYPE_ARG5: Particular Functions. + (line 180) +* SETPGRP_VOID: Particular Functions. + (line 188) +* SETVBUF_REVERSED: Particular Functions. + (line 205) +* size_t: Particular Types. (line 36) +* STDC_HEADERS: Particular Headers. (line 57) +* SVR4: Particular Functions. + (line 103) +* SYSDIR: Obsolete Macros. (line 126) +* SYSNDIR: Obsolete Macros. (line 126) +* SYS_SIGLIST_DECLARED: Particular Declarations. + (line 9) +* TIME_WITH_SYS_TIME: Particular Headers. (line 146) +* TM_IN_SYS_TIME: Particular Structures. + (line 31) +* uid_t: Particular Types. (line 39) +* UMAX: Particular Functions. + (line 103) +* UMAX4_3: Particular Functions. + (line 103) +* USG: Obsolete Macros. (line 482) +* vfork: Particular Functions. + (line 71) +* volatile: C Compiler. (line 98) +* WORDS_BIGENDIAN: C Compiler. (line 68) +* X_DISPLAY_MISSING: System Services. (line 26) +* YYTEXT_POINTER: Particular Programs. (line 57) + + +File: autoconf.info, Node: Autoconf Macro Index, Next: M4 Macro Index, Prev: Preprocessor Symbol Index, Up: Top + +Autoconf Macro Index +******************** + +This is an alphabetical list of the Autoconf macros. To make the list +easier to use, the macros are listed without their preceding 'AC_'. + + +* Menu: + +* AH_BOTTOM: Autoheader Macros. (line 56) +* AH_TEMPLATE: Autoheader Macros. (line 32) +* AH_TOP: Autoheader Macros. (line 53) +* AH_VERBATIM: Autoheader Macros. (line 18) +* AIX: UNIX Variants. (line 13) +* ALLOCA: Obsolete Macros. (line 20) +* ARG_ARRAY: Obsolete Macros. (line 23) +* ARG_ENABLE: Package Options. (line 40) +* ARG_PROGRAM: Transforming Names. (line 11) +* ARG_VAR: Setting Output Variables. + (line 57) +* ARG_WITH: External Software. (line 41) +* AU_DEFUN: Obsoleting Macros. (line 18) +* BEFORE: Suggested Ordering. (line 28) +* BOTTOM: Autoheader Macros. (line 56) +* CACHE_CHECK: Caching Results. (line 29) +* CACHE_LOAD: Cache Checkpointing. (line 13) +* CACHE_SAVE: Cache Checkpointing. (line 17) +* CACHE_VAL: Caching Results. (line 15) +* CANONICAL_BUILD: Canonicalizing. (line 26) +* CANONICAL_HOST: Canonicalizing. (line 34) +* CANONICAL_SYSTEM: Obsolete Macros. (line 29) +* CANONICAL_TARGET: Canonicalizing. (line 46) +* CHAR_UNSIGNED: Obsolete Macros. (line 39) +* CHECKING: Obsolete Macros. (line 89) +* CHECK_DECL: Generic Declarations. + (line 11) +* CHECK_DECLS: Generic Declarations. + (line 23) +* CHECK_FILE: Files. (line 13) +* CHECK_FILES: Files. (line 19) +* CHECK_FUNC: Generic Functions. (line 15) +* CHECK_FUNCS: Generic Functions. (line 25) +* CHECK_HEADER: Generic Headers. (line 13) +* CHECK_HEADERS: Generic Headers. (line 43) +* CHECK_LIB: Libraries. (line 11) +* CHECK_MEMBER: Generic Structures. (line 11) +* CHECK_MEMBERS: Generic Structures. (line 25) +* CHECK_PROG: Generic Programs. (line 23) +* CHECK_PROGS: Generic Programs. (line 33) +* CHECK_SIZEOF: Generic Compiler Characteristics. + (line 7) +* CHECK_TOOL: Generic Programs. (line 43) +* CHECK_TOOLS: Generic Programs. (line 54) +* CHECK_TYPE: Generic Types. (line 11) +* CHECK_TYPE <1>: Obsolete Macros. (line 42) +* CHECK_TYPES: Generic Types. (line 16) +* COMPILE_CHECK: Obsolete Macros. (line 93) +* CONFIG_AUX_DIR: Input. (line 29) +* CONFIG_COMMANDS: Configuration Commands. + (line 13) +* CONFIG_FILES: Configuration Files. (line 9) +* CONFIG_HEADERS: Configuration Headers. + (line 25) +* CONFIG_LINKS: Configuration Links. (line 12) +* CONFIG_SRCDIR: Input. (line 16) +* CONFIG_SUBDIRS: Subdirectories. (line 12) +* CONST: Obsolete Macros. (line 100) +* COPYRIGHT: Notices. (line 21) +* CROSS_CHECK: Obsolete Macros. (line 103) +* CYGWIN: Obsolete Macros. (line 107) +* C_BIGENDIAN: C Compiler. (line 68) +* C_CHAR_UNSIGNED: C Compiler. (line 120) +* C_CONST: C Compiler. (line 73) +* C_CROSS: Obsolete Macros. (line 26) +* C_INLINE: C Compiler. (line 115) +* C_LONG_DOUBLE: C Compiler. (line 124) +* C_PROTOTYPES: C Compiler. (line 137) +* C_STRINGIZE: C Compiler. (line 130) +* C_VOLATILE: C Compiler. (line 98) +* DECL_SYS_SIGLIST: Particular Declarations. + (line 9) +* DECL_YYTEXT: Obsolete Macros. (line 123) +* DEFINE: Defining Symbols. (line 29) +* DEFINE_UNQUOTED: Defining Symbols. (line 45) +* DEFUN: Macro Definitions. (line 6) +* DEFUN <1>: Obsoleting Macros. (line 18) +* DIAGNOSE: Reporting Messages. (line 11) +* DIR_HEADER: Obsolete Macros. (line 126) +* DYNIX_SEQ: Obsolete Macros. (line 137) +* EGREP_CPP: Examining Declarations. + (line 46) +* EGREP_HEADER: Examining Declarations. + (line 29) +* EMXOS2: Obsolete Macros. (line 150) +* ENABLE: Package Options. (line 57) +* ERROR: Obsolete Macros. (line 154) +* EXEEXT: Obsolete Macros. (line 145) +* F77_DUMMY_MAIN: Fortran 77 Compiler. (line 64) +* F77_FUNC: Fortran 77 Compiler. (line 169) +* F77_LIBRARY_LDFLAGS: Fortran 77 Compiler. (line 38) +* F77_MAIN: Fortran 77 Compiler. (line 101) +* F77_WRAPPERS: Fortran 77 Compiler. (line 115) +* FATAL: Reporting Messages. (line 33) +* FIND_X: Obsolete Macros. (line 157) +* FIND_XTRA: Obsolete Macros. (line 160) +* FUNC_ALLOCA: Particular Functions. + (line 10) +* FUNC_CHECK: Obsolete Macros. (line 163) +* FUNC_CHOWN: Particular Functions. + (line 54) +* FUNC_CLOSEDIR_VOID: Particular Functions. + (line 58) +* FUNC_ERROR_AT_LINE: Particular Functions. + (line 63) +* FUNC_FNMATCH: Particular Functions. + (line 67) +* FUNC_FORK: Particular Functions. + (line 71) +* FUNC_FSEEKO: Particular Functions. + (line 93) +* FUNC_GETGROUPS: Particular Functions. + (line 97) +* FUNC_GETLOADAVG: Particular Functions. + (line 103) +* FUNC_GETMNTENT: Particular Functions. + (line 131) +* FUNC_GETPGRP: Particular Functions. + (line 136) +* FUNC_LSTAT: Particular Functions. + (line 196) +* FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK: Particular Functions. + (line 143) +* FUNC_MALLOC: Particular Functions. + (line 156) +* FUNC_MEMCMP: Particular Functions. + (line 160) +* FUNC_MKTIME: Particular Functions. + (line 167) +* FUNC_MMAP: Particular Functions. + (line 171) +* FUNC_OBSTACK: Particular Functions. + (line 176) +* FUNC_SELECT_ARGTYPES: Particular Functions. + (line 180) +* FUNC_SETPGRP: Particular Functions. + (line 188) +* FUNC_SETVBUF_REVERSED: Particular Functions. + (line 205) +* FUNC_STAT: Particular Functions. + (line 196) +* FUNC_STRCOLL: Particular Functions. + (line 210) +* FUNC_STRERROR_R: Particular Functions. + (line 222) +* FUNC_STRFTIME: Particular Functions. + (line 230) +* FUNC_STRTOD: Particular Functions. + (line 216) +* FUNC_UTIME_NULL: Particular Functions. + (line 234) +* FUNC_VPRINTF: Particular Functions. + (line 238) +* FUNC_WAIT3: Obsolete Macros. (line 166) +* GCC_TRADITIONAL: Obsolete Macros. (line 175) +* GETGROUPS_T: Obsolete Macros. (line 178) +* GETLOADAVG: Obsolete Macros. (line 181) +* HAVE_FUNCS: Obsolete Macros. (line 184) +* HAVE_HEADERS: Obsolete Macros. (line 187) +* HAVE_LIBRARY: Obsolete Macros. (line 191) +* HAVE_POUNDBANG: Obsolete Macros. (line 198) +* HEADER_CHECK: Obsolete Macros. (line 201) +* HEADER_DIRENT: Particular Headers. (line 10) +* HEADER_EGREP: Obsolete Macros. (line 204) +* HEADER_MAJOR: Particular Headers. (line 46) +* HEADER_STAT: Particular Headers. (line 51) +* HEADER_STDC: Particular Headers. (line 57) +* HEADER_SYS_WAIT: Particular Headers. (line 112) +* HEADER_TIME: Particular Headers. (line 146) +* HEADER_TIOCGWINSZ: Particular Headers. (line 167) +* HELP_STRING: Pretty Help Strings. (line 14) +* INIT: Input. (line 10) +* INIT <1>: Obsolete Macros. (line 207) +* INLINE: Obsolete Macros. (line 214) +* INT_16_BITS: Obsolete Macros. (line 217) +* IRIX_SUN: Obsolete Macros. (line 221) +* ISC_POSIX: UNIX Variants. (line 18) +* LANG_C: Obsolete Macros. (line 235) +* LANG_CPLUSPLUS: Obsolete Macros. (line 238) +* LANG_FORTRAN77: Obsolete Macros. (line 241) +* LANG_POP: Language Choice. (line 37) +* LANG_PUSH: Language Choice. (line 32) +* LANG_RESTORE: Obsolete Macros. (line 244) +* LANG_SAVE: Obsolete Macros. (line 249) +* LIBOBJ: Generic Functions. (line 44) +* LIBSOURCE: Generic Functions. (line 52) +* LIBSOURCES: Generic Functions. (line 76) +* LINK_FILES: Obsolete Macros. (line 253) +* LN_S: Obsolete Macros. (line 265) +* LONG_64_BITS: Obsolete Macros. (line 268) +* LONG_DOUBLE: Obsolete Macros. (line 272) +* LONG_FILE_NAMES: Obsolete Macros. (line 275) +* MAJOR_HEADER: Obsolete Macros. (line 278) +* MEMORY_H: Obsolete Macros. (line 281) +* MINGW32: Obsolete Macros. (line 287) +* MINIX: UNIX Variants. (line 25) +* MINUS_C_MINUS_O: Obsolete Macros. (line 291) +* MMAP: Obsolete Macros. (line 294) +* MODE_T: Obsolete Macros. (line 297) +* MSG_CHECKING: Printing Messages. (line 23) +* MSG_ERROR: Printing Messages. (line 54) +* MSG_NOTICE: Printing Messages. (line 44) +* MSG_RESULT: Printing Messages. (line 34) +* MSG_WARN: Printing Messages. (line 64) +* OBJEXT: Obsolete Macros. (line 300) +* OBSOLETE: Obsolete Macros. (line 306) +* OFF_T: Obsolete Macros. (line 321) +* OUTPUT: Output. (line 12) +* OUTPUT <1>: Obsolete Macros. (line 324) +* OUTPUT_COMMANDS: Obsolete Macros. (line 346) +* OUTPUT_COMMANDS_POST: Configuration Commands. + (line 39) +* OUTPUT_COMMANDS_PRE: Configuration Commands. + (line 30) +* PATH_PROG: Generic Programs. (line 66) +* PATH_PROGS: Generic Programs. (line 71) +* PATH_TOOL: Generic Programs. (line 76) +* PATH_X: System Services. (line 10) +* PATH_XTRA: System Services. (line 26) +* PID_T: Obsolete Macros. (line 375) +* PREFIX: Obsolete Macros. (line 378) +* PREFIX_DEFAULT: Default Prefix. (line 16) +* PREFIX_PROGRAM: Default Prefix. (line 25) +* PREREQ: Notices. (line 10) +* PROGRAMS_CHECK: Obsolete Macros. (line 381) +* PROGRAMS_PATH: Obsolete Macros. (line 384) +* PROGRAM_CHECK: Obsolete Macros. (line 387) +* PROGRAM_EGREP: Obsolete Macros. (line 390) +* PROGRAM_PATH: Obsolete Macros. (line 393) +* PROG_AWK: Particular Programs. (line 10) +* PROG_CC: C Compiler. (line 7) +* PROG_CC_C_O: C Compiler. (line 26) +* PROG_CC_STDC: C Compiler. (line 34) +* PROG_CPP: C Compiler. (line 47) +* PROG_CXX: C++ Compiler. (line 7) +* PROG_CXXCPP: C++ Compiler. (line 31) +* PROG_F77_C_O: Fortran 77 Compiler. (line 28) +* PROG_FORTRAN: Fortran 77 Compiler. (line 7) +* PROG_GCC_TRADITIONAL: C Compiler. (line 156) +* PROG_INSTALL: Particular Programs. (line 28) +* PROG_LEX: Particular Programs. (line 57) +* PROG_LN_S: Particular Programs. (line 95) +* PROG_MAKE_SET: Output. (line 37) +* PROG_RANLIB: Particular Programs. (line 114) +* PROG_YACC: Particular Programs. (line 118) +* REMOTE_TAPE: Obsolete Macros. (line 396) +* REPLACE_FUNCS: Generic Functions. (line 84) +* REQUIRE: Prerequisite Macros. (line 17) +* REQUIRE_CPP: Language Choice. (line 50) +* RESTARTABLE_SYSCALLS: Obsolete Macros. (line 399) +* RETSIGTYPE: Obsolete Macros. (line 402) +* REVISION: Notices. (line 29) +* RSH: Obsolete Macros. (line 405) +* SCO_INTL: Obsolete Macros. (line 408) +* SEARCH_LIBS: Libraries. (line 41) +* SETVBUF_REVERSED: Obsolete Macros. (line 416) +* SET_MAKE: Obsolete Macros. (line 419) +* SIZEOF_TYPE: Obsolete Macros. (line 422) +* SIZE_T: Obsolete Macros. (line 425) +* STAT_MACROS_BROKEN: Particular Headers. (line 51) +* STAT_MACROS_BROKEN <1>: Obsolete Macros. (line 428) +* STDC_HEADERS: Obsolete Macros. (line 431) +* STRCOLL: Obsolete Macros. (line 434) +* STRUCT_ST_BLKSIZE: Particular Structures. + (line 9) +* STRUCT_ST_BLOCKS: Particular Structures. + (line 17) +* STRUCT_ST_RDEV: Particular Structures. + (line 23) +* STRUCT_TIMEZONE: Particular Structures. + (line 36) +* STRUCT_TM: Particular Structures. + (line 31) +* ST_BLKSIZE: Obsolete Macros. (line 437) +* ST_BLOCKS: Obsolete Macros. (line 440) +* ST_RDEV: Obsolete Macros. (line 443) +* SUBST: Setting Output Variables. + (line 13) +* SUBST_FILE: Setting Output Variables. + (line 23) +* SYS_INTERPRETER: System Services. (line 37) +* SYS_LARGEFILE: System Services. (line 44) +* SYS_LONG_FILE_NAMES: System Services. (line 58) +* SYS_POSIX_TERMIOS: System Services. (line 62) +* SYS_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 446) +* SYS_SIGLIST_DECLARED: Obsolete Macros. (line 461) +* TEMPLATE: Autoheader Macros. (line 32) +* TEST_CPP: Obsolete Macros. (line 464) +* TEST_PROGRAM: Obsolete Macros. (line 467) +* TIMEZONE: Obsolete Macros. (line 470) +* TIME_WITH_SYS_TIME: Obsolete Macros. (line 473) +* TOP: Autoheader Macros. (line 53) +* TRY_COMPILE: Examining Syntax. (line 14) +* TRY_CPP: Examining Declarations. + (line 11) +* TRY_LINK: Examining Libraries. (line 33) +* TRY_LINK_FUNC: Examining Libraries. (line 51) +* TRY_RUN: Test Programs. (line 11) +* TYPE_GETGROUPS: Particular Types. (line 10) +* TYPE_MODE_T: Particular Types. (line 14) +* TYPE_OFF_T: Particular Types. (line 17) +* TYPE_PID_T: Particular Types. (line 20) +* TYPE_SIGNAL: Particular Types. (line 23) +* TYPE_SIZE_T: Particular Types. (line 36) +* TYPE_UID_T: Particular Types. (line 39) +* UID_T: Obsolete Macros. (line 476) +* UNISTD_H: Obsolete Macros. (line 479) +* USG: Obsolete Macros. (line 482) +* UTIME_NULL: Obsolete Macros. (line 487) +* VALIDATE_CACHED_SYSTEM_TUPLE: Obsolete Macros. (line 490) +* VERBATIM: Autoheader Macros. (line 18) +* VERBOSE: Obsolete Macros. (line 497) +* VFORK: Obsolete Macros. (line 500) +* VPRINTF: Obsolete Macros. (line 503) +* WAIT3: Obsolete Macros. (line 506) +* WARN: Obsolete Macros. (line 509) +* WARNING: Reporting Messages. (line 29) +* WITH: External Software. (line 67) +* WORDS_BIGENDIAN: Obsolete Macros. (line 512) +* XENIX_DIR: Obsolete Macros. (line 515) +* YYTEXT_POINTER: Obsolete Macros. (line 530) + + +File: autoconf.info, Node: M4 Macro Index, Next: Concept Index, Prev: Autoconf Macro Index, Up: Top + +M4 Macro Index +************** + +This is an alphabetical list of the M4, M4sugar, and M4sh macros. To +make the list easier to use, the macros are listed without their +preceding 'm4_' or 'AS_'. + + +* Menu: + +* defn: Redefined M4 Macros. (line 14) +* defn <1>: Redefined M4 Macros. (line 26) +* pattern_allow: Forbidden Patterns. (line 28) +* pattern_forbid: Forbidden Patterns. (line 15) +* undefine: Redefined M4 Macros. (line 18) + + +File: autoconf.info, Node: Concept Index, Prev: M4 Macro Index, Up: Top + +Concept Index +************* + +This is an alphabetical list of the files, tools, and concepts +introduced in this document. + + +* Menu: + +* !: Limitations of Builtins. + (line 16) +* "$@": Shell Substitutions. (line 31) +* $(COMMANDS): Shell Substitutions. (line 132) +* ${VAR:-VALUE}: Shell Substitutions. (line 38) +* ${VAR=EXPANDED-VALUE}: Shell Substitutions. (line 71) +* ${VAR=LITERAL}: Shell Substitutions. (line 42) +* /usr/xpg4/bin/sh on Solaris: Shellology. (line 43) +* :: Limitations of Builtins. + (line 312) +* @%:@: Quadrigraphs. (line 6) +* @:>@: Quadrigraphs. (line 6) +* @<:@: Quadrigraphs. (line 6) +* @S|@: Quadrigraphs. (line 6) +* 'COMMANDS': Shell Substitutions. (line 117) +* acconfig.h: acconfig.h. (line 6) +* aclocal.m4: Making configure Scripts. + (line 6) +* Ash: Shellology. (line 13) +* autoconf: autoconf Invocation. (line 6) +* autoheader: autoheader Invocation. + (line 6) +* Automake: Automake. (line 19) +* autoreconf: autoreconf Invocation. + (line 6) +* autoscan: autoscan Invocation. (line 6) +* autoupdate: autoupdate Invocation. + (line 6) +* awk: Limitations of Usual Tools. + (line 10) +* Back trace: autoconf Invocation. (line 93) +* Bash: Shellology. (line 37) +* break: Limitations of Builtins. + (line 19) +* Cache: Caching Results. (line 6) +* Cache variable: Cache Variable Names. + (line 6) +* Cache, enabling: configure Invocation. + (line 18) +* case: Limitations of Builtins. + (line 22) +* cat: Limitations of Usual Tools. + (line 53) +* cmp: Limitations of Usual Tools. + (line 61) +* Command Substitution: Shell Substitutions. (line 117) +* config.h: Configuration Headers. + (line 6) +* config.h.bot: acconfig.h. (line 6) +* config.h.in: Header Templates. (line 6) +* config.h.top: acconfig.h. (line 6) +* config.status: config.status Invocation. + (line 6) +* Configuration Header: Configuration Headers. + (line 6) +* Configuration Header Template: Header Templates. (line 6) +* configure: Making configure Scripts. + (line 6) +* configure <1>: Running configure scripts. + (line 6) +* configure.ac: Making configure Scripts. + (line 27) +* configure.in: Making configure Scripts. + (line 27) +* Copyright Notice: Notices. (line 21) +* cp: Limitations of Usual Tools. + (line 68) +* Declaration, checking: Declarations. (line 6) +* diff: Limitations of Usual Tools. + (line 79) +* dirname: Limitations of Usual Tools. + (line 85) +* dnl: Macro Definitions. (line 35) +* dnl <1>: Coding Style. (line 40) +* echo: Limitations of Builtins. + (line 42) +* egrep: Limitations of Usual Tools. + (line 112) +* Endianness: C Compiler. (line 68) +* exit: Limitations of Builtins. + (line 69) +* export: Limitations of Builtins. + (line 94) +* expr: Limitations of Usual Tools. + (line 126) +* expr <1>: Limitations of Usual Tools. + (line 151) +* expr (|): Limitations of Usual Tools. + (line 132) +* false: Limitations of Builtins. + (line 120) +* File, checking: Files. (line 6) +* for: Limitations of Builtins. + (line 124) +* Function, checking: Particular Functions. + (line 6) +* grep: Limitations of Usual Tools. + (line 204) +* Header, checking: Header Files. (line 6) +* if: Limitations of Builtins. + (line 146) +* ifnames: ifnames Invocation. (line 6) +* Includes, default: Default Includes. (line 6) +* Instantiation: Output. (line 12) +* Language: Language Choice. (line 6) +* Library, checking: Libraries. (line 6) +* Libtool: Libtool. (line 13) +* Links: Configuration Links. (line 12) +* ln: Limitations of Usual Tools. + (line 216) +* M4sugar: Programming in M4sugar. + (line 6) +* Macro invocation stack: autoconf Invocation. (line 93) +* Messages, from autoconf: Reporting Messages. (line 6) +* Messages, from configure: Printing Messages. (line 6) +* mv: Limitations of Usual Tools. + (line 228) +* obstack: Particular Functions. + (line 176) +* POSIX termios headers: System Services. (line 62) +* Previous Variable: Setting Output Variables. + (line 44) +* Programs, checking: Alternative Programs. + (line 6) +* QNX 4.25: Systemology. (line 11) +* quadrigraphs: Quadrigraphs. (line 6) +* quotation: Autoconf Language. (line 6) +* quotation <1>: M4 Quotation. (line 6) +* Revision: Notices. (line 29) +* sed: Limitations of Usual Tools. + (line 239) +* sed (t): Limitations of Usual Tools. + (line 278) +* set: Limitations of Builtins. + (line 175) +* shift: Limitations of Builtins. + (line 186) +* Structure, checking: Structures. (line 6) +* Symbolic links: Limitations of Usual Tools. + (line 216) +* termios POSIX headers: System Services. (line 62) +* test: Limitations of Builtins. + (line 191) +* touch: Limitations of Usual Tools. + (line 338) +* trap: Limitations of Builtins. + (line 272) +* true: Limitations of Builtins. + (line 312) +* undefined macro: _m4_divert_diversion: New Macros. (line 6) +* unset: Limitations of Builtins. + (line 323) +* Variable, Precious: Setting Output Variables. + (line 44) +* Version: Notices. (line 10) +* VPATH: Limitations of Make. (line 31) +* Zsh: Shellology. (line 49) + + + +Tag Table: +Node: Top1982 +Node: Introduction14243 +Ref: Introduction-Footnote-119088 +Ref: Introduction-Footnote-219169 +Ref: Introduction-Footnote-319269 +Ref: Introduction-Footnote-419383 +Node: The GNU build system19458 +Node: Automake20377 +Node: Libtool22803 +Node: Pointers24229 +Ref: Pointers-Footnote-125435 +Ref: Pointers-Footnote-225494 +Ref: Pointers-Footnote-325551 +Ref: Pointers-Footnote-425693 +Ref: Pointers-Footnote-525767 +Ref: Pointers-Footnote-625839 +Node: Making configure Scripts25914 +Node: Writing configure.ac28948 +Node: Shell Script Compiler30414 +Node: Autoconf Language32715 +Node: configure.ac Layout37347 +Node: autoscan Invocation38751 +Node: ifnames Invocation41504 +Node: autoconf Invocation42704 +Node: autoreconf Invocation49781 +Node: Setup53123 +Node: Notices54328 +Node: Input55964 +Node: Output58012 +Node: Configuration Actions59994 +Node: Configuration Files62899 +Node: Makefile Substitutions64365 +Node: Preset Output Variables66048 +Node: Installation Directory Variables70619 +Node: Build Directories74971 +Node: Automatic Remaking76624 +Node: Configuration Headers78779 +Node: Header Templates81482 +Node: autoheader Invocation82760 +Node: Autoheader Macros86228 +Node: Configuration Commands88431 +Node: Configuration Links90117 +Node: Subdirectories91489 +Node: Default Prefix93644 +Node: Existing Tests95041 +Node: Common Behavior96759 +Node: Standard Symbols97421 +Node: Default Includes98022 +Node: Alternative Programs99954 +Node: Particular Programs100640 +Node: Generic Programs106101 +Node: Files110010 +Node: Libraries110905 +Node: Library Functions113770 +Node: Function Portability114393 +Node: Particular Functions115398 +Node: Generic Functions125990 +Node: Header Files130235 +Node: Particular Headers130798 +Node: Generic Headers137767 +Node: Declarations139839 +Node: Particular Declarations140428 +Node: Generic Declarations140851 +Node: Structures143224 +Node: Particular Structures143831 +Node: Generic Structures145553 +Node: Types146797 +Node: Particular Types147317 +Node: Generic Types148487 +Node: Compilers and Preprocessors149859 +Node: Generic Compiler Characteristics150870 +Node: C Compiler151733 +Node: C++ Compiler159074 +Node: Fortran 77 Compiler161317 +Node: System Services169814 +Ref: System Services-Footnote-1172930 +Node: UNIX Variants173021 +Node: Writing Tests174203 +Node: Examining Declarations176135 +Node: Examining Syntax178635 +Node: Examining Libraries180083 +Node: Run Time183095 +Node: Test Programs184076 +Node: Guidelines186343 +Node: Test Functions187542 +Node: Systemology189098 +Ref: Systemology-Footnote-1189726 +Ref: Systemology-Footnote-2189764 +Node: Multiple Cases189832 +Node: Language Choice191089 +Node: Results193124 +Node: Defining Symbols193874 +Node: Setting Output Variables197130 +Node: Caching Results201321 +Node: Cache Variable Names205004 +Node: Cache Files206593 +Node: Cache Checkpointing208623 +Node: Printing Messages209954 +Node: Programming in M4213139 +Node: M4 Quotation213812 +Node: Active Characters214622 +Ref: Active Characters-Footnote-1216000 +Node: One Macro Call216022 +Node: Quotation and Nested Macros217584 +Node: Quadrigraphs220550 +Node: Quotation Rule Of Thumb221475 +Node: Programming in M4sugar224118 +Node: Redefined M4 Macros224626 +Node: Forbidden Patterns225596 +Node: Writing Autoconf Macros226961 +Node: Macro Definitions227762 +Node: Macro Names229570 +Node: Reporting Messages232171 +Node: Dependencies Between Macros233517 +Node: Prerequisite Macros234141 +Node: Suggested Ordering236922 +Node: Obsoleting Macros238441 +Node: Coding Style239564 +Node: Portable Shell246570 +Node: Shellology248656 +Node: Here-Documents251635 +Node: File Descriptors253597 +Node: File System Conventions255605 +Ref: File System Conventions-Footnote-1259725 +Node: Shell Substitutions259799 +Node: Assignments264708 +Node: Special Shell Variables266345 +Node: Limitations of Builtins270391 +Node: Limitations of Usual Tools282719 +Node: Limitations of Make295462 +Node: Manual Configuration296443 +Node: Specifying Names297272 +Ref: Specifying Names-Footnote-1300083 +Node: Canonicalizing300483 +Node: Using System Type302887 +Node: Site Configuration303936 +Node: External Software304769 +Node: Package Options308085 +Node: Pretty Help Strings310953 +Node: Site Details312932 +Node: Transforming Names314167 +Node: Transformation Options315315 +Node: Transformation Examples315819 +Node: Transformation Rules317541 +Node: Site Defaults319377 +Node: Running configure scripts323296 +Node: Basic Installation324313 +Node: Compilers and Options327161 +Node: Multiple Architectures327803 +Node: Installation Names328802 +Node: Optional Features330001 +Node: System Type330785 +Node: Sharing Defaults332311 +Node: Environment Variables332953 +Node: configure Invocation333639 +Node: config.status Invocation334771 +Node: Obsolete Constructs338596 +Node: Obsolete config.status Use339522 +Node: acconfig.h341321 +Node: autoupdate Invocation343337 +Node: Obsolete Macros345299 +Node: Autoconf 1362452 +Node: Changed File Names363518 +Node: Changed Makefiles364293 +Node: Changed Macros365386 +Node: Changed Results366642 +Node: Changed Macro Writing368753 +Node: Autoconf 2.13370028 +Node: Changed Quotation371037 +Node: New Macros372944 +Node: Questions374578 +Node: Distributing375102 +Node: Why GNU m4376173 +Node: Bootstrapping377071 +Node: Why Not Imake377687 +Node: History382392 +Node: Genesis383191 +Node: Exodus384387 +Node: Leviticus387438 +Node: Numbers388972 +Node: Deuteronomy390893 +Node: Environment Variable Index393565 +Node: Output Variable Index397608 +Node: Preprocessor Symbol Index407637 +Node: Autoconf Macro Index418644 +Node: M4 Macro Index441976 +Node: Concept Index442663 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/doc/autoconf.texi b/doc/autoconf.texi new file mode 100644 index 0000000..2728b2f --- /dev/null +++ b/doc/autoconf.texi @@ -0,0 +1,11346 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename autoconf.info +@settitle Autoconf + +@finalout +@setchapternewpage odd +@setcontentsaftertitlepage + +@include version.texi + +@c A simple macro for optional variables. +@macro ovar{varname} +@r{[}@var{\varname\}@r{]} +@end macro + +@c I don't like the way URL are displayed in TeX with @uref. +@ifhtml +@macro href{url, title} +@uref{\url\, \title\} +@end macro +@end ifhtml +@ifnothtml +@macro href{url, title} +\title\@footnote{\title\, @url{\url\}.} +@end macro +@end ifnothtml + + +@dircategory GNU admin +@direntry +* Autoconf: (autoconf). Create source code configuration scripts +@end direntry + +@dircategory Individual utilities +@direntry +* autoscan: (autoconf)autoscan Invocation. + Semi-automatic @file{configure.ac} writing +* ifnames: (autoconf)ifnames Invocation. + Listing the conditionals in source code +* autoconf: (autoconf)autoconf Invocation. + How to create configuration scripts +* autoreconf: (autoconf)autoreconf Invocation. + Remaking multiple @code{configure} scripts +* configure: (autoconf)configure Invocation. + Configuring a package +* config.status: (autoconf)config.status Invocation. + Recreating a configuration +@end direntry + +@ifinfo +Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie. + +This file documents the GNU Autoconf package for creating scripts to +configure source code packages using templates and an @code{m4} macro +package. + +Copyright 2003-2022,2023 Thomas E. Dickey@* +Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001 Free +Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the Foundation. +@end ifinfo + +@titlepage +@title Autoconf +@subtitle Creating Automatic Configuration Scripts +@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION} +@subtitle @value{UPDATED} +@author David MacKenzie and Ben Elliston +@c I think I've rewritten all of Noah and Roland's contributions by now. + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, +2001 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the Foundation. +@end titlepage + +@c Define an environment variable index. +@defcodeindex ev +@c Define an output variable index. +@defcodeindex ov +@c Define a CPP variable index. +@defcodeindex cv +@c Define an Autoconf macro index that @defmac doesn't write to. +@defcodeindex ma +@c Define an M4sugar macro index that @defmac doesn't write to. +@defcodeindex ms + +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up + +@ifinfo +This file documents the GNU Autoconf package for creating scripts to +configure source code packages using templates and the GNU M4 macro +package. This is edition @value{EDITION}, for Autoconf version +@value{VERSION}. + +@end ifinfo + +@c The master menu, created with texinfo-master-menu, goes here. + +@menu +* Introduction:: Autoconf's purpose, strengths, and weaknesses +* The GNU build system:: A set of tools for portable software packages +* Making configure Scripts:: How to organize and produce Autoconf scripts +* Setup:: Initialization and output +* Existing Tests:: Macros that check for particular features +* Writing Tests:: How to write new feature checks +* Results:: What to do with results from feature checks +* Programming in M4:: Layers on top of which Autoconf is written +* Writing Autoconf Macros:: Adding new macros to Autoconf +* Portable Shell:: Shell script portability pitfalls +* Manual Configuration:: Selecting features that can't be guessed +* Site Configuration:: Local defaults for @code{configure} +* Running configure scripts:: How to use the Autoconf output +* config.status Invocation:: Recreating a configuration +* Obsolete Constructs:: Kept for backward compatibility +* Questions:: Questions about Autoconf, with answers +* History:: History of Autoconf +* Environment Variable Index:: Index of environment variables used +* Output Variable Index:: Index of variables set in output files +* Preprocessor Symbol Index:: Index of C preprocessor symbols defined +* Autoconf Macro Index:: Index of Autoconf macros +* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros +* Concept Index:: General index + +@detailmenu --- The Detailed Node Listing --- + +The GNU build system + +* Automake:: Escaping Makefile hell +* Libtool:: Building libraries portably +* Pointers:: More info on the GNU build system + +Making @code{configure} Scripts + +* Writing configure.ac:: What to put in an Autoconf input file +* autoscan Invocation:: Semi-automatic @file{configure.ac} writing +* ifnames Invocation:: Listing the conditionals in source code +* autoconf Invocation:: How to create configuration scripts +* autoreconf Invocation:: Remaking multiple @code{configure} scripts + +Writing @file{configure.ac} + +* Shell Script Compiler:: Autoconf as solution of a problem +* Autoconf Language:: Programming in Autoconf +* configure.ac Layout:: Standard organization of configure.ac + +Initialization and Output Files + +* Notices:: Copyright, version numbers in @code{configure} +* Input:: Where Autoconf should find files +* Output:: Outputting results from the configuration +* Configuration Actions:: Preparing the output based on results +* Configuration Files:: Creating output files +* Makefile Substitutions:: Using output variables in @file{Makefile}s +* Configuration Headers:: Creating a configuration header file +* Configuration Commands:: Running arbitrary instantiation commands +* Configuration Links:: Links depending from the configuration +* Subdirectories:: Configuring independent packages together +* Default Prefix:: Changing the default installation prefix + +Substitutions in Makefiles + +* Preset Output Variables:: Output variables that are always set +* Installation Directory Variables:: Other preset output variables +* Build Directories:: Supporting multiple concurrent compiles +* Automatic Remaking:: Makefile rules for configuring + +Configuration Header Files + +* Header Templates:: Input for the configuration headers +* autoheader Invocation:: How to create configuration templates +* Autoheader Macros:: How to specify CPP templates + +Existing Tests + +* Common Behavior:: Macros' standard schemes +* Alternative Programs:: Selecting between alternative programs +* Files:: Checking for the existence of files +* Libraries:: Library archives that might be missing +* Library Functions:: C library functions that might be missing +* Header Files:: Header files that might be missing +* Declarations:: Declarations that may be missing +* Structures:: Structures or members that might be missing +* Types:: Types that might be missing +* Compilers and Preprocessors:: Checking for compiling programs +* System Services:: Operating system services +* UNIX Variants:: Special kludges for specific UNIX variants + +Common Behavior + +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros + +Alternative Programs + +* Particular Programs:: Special handling to find certain programs +* Generic Programs:: How to find other programs + +Library Functions + +* Function Portability:: Pitfalls with usual functions +* Particular Functions:: Special handling to find certain functions +* Generic Functions:: How to find other functions + +Header Files + +* Particular Headers:: Special handling to find certain headers +* Generic Headers:: How to find other headers + +Declarations + +* Particular Declarations:: Macros to check for certain declarations +* Generic Declarations:: How to find other declarations + +Structures + +* Particular Structures:: Macros to check for certain structure members +* Generic Structures:: How to find other structure members + +Types + +* Particular Types:: Special handling to find certain types +* Generic Types:: How to find other types + +Compilers and Preprocessors + +* Generic Compiler Characteristics:: Language independent tests +* C Compiler:: Checking its characteristics +* C++ Compiler:: Likewise +* Fortran 77 Compiler:: Likewise + +Writing Tests + +* Examining Declarations:: Detecting header files and declarations +* Examining Syntax:: Detecting language syntax features +* Examining Libraries:: Detecting functions and global variables +* Run Time:: Testing for run-time features +* Systemology:: A zoology of operating systems +* Multiple Cases:: Tests for several possible values +* Language Choice:: Selecting which language to use for testing + +Checking Run Time Behavior + +* Test Programs:: Running test programs +* Guidelines:: General rules for writing test programs +* Test Functions:: Avoiding pitfalls in test programs + +Results of Tests + +* Defining Symbols:: Defining C preprocessor symbols +* Setting Output Variables:: Replacing variables in output files +* Caching Results:: Speeding up subsequent @code{configure} runs +* Printing Messages:: Notifying @code{configure} users + +Caching Results + +* Cache Variable Names:: Shell variables used in caches +* Cache Files:: Files @code{configure} uses for caching +* Cache Checkpointing:: Loading and saving the cache file + +Programming in M4 + +* M4 Quotation:: Protecting macros from unwanted expansion +* Programming in M4sugar:: Convenient pure M4 macros + +M4 Quotation + +* Active Characters:: Characters that change the behavior of m4 +* One Macro Call:: Quotation and one macro call +* Quotation and Nested Macros:: Macros calling macros +* Quadrigraphs:: Another way to escape special characters +* Quotation Rule Of Thumb:: One parenthesis, one quote + +Programming in M4sugar + +* Redefined M4 Macros:: M4 builtins changed in M4sugar +* Forbidden Patterns:: Catching unexpanded macros + +Writing Autoconf Macros + +* Macro Definitions:: Basic format of an Autoconf macro +* Macro Names:: What to call your new macros +* Reporting Messages:: Notifying @code{autoconf} users +* Dependencies Between Macros:: What to do when macros depend on other macros +* Obsoleting Macros:: Warning about old ways of doing things +* Coding Style:: Writing Autoconf macros @`a la Autoconf + +Dependencies Between Macros + +* Prerequisite Macros:: Ensuring required information +* Suggested Ordering:: Warning about possible ordering problems + +Portable Shell Programming + +* Shellology:: A zoology of shells +* Here-Documents:: Quirks and tricks +* File Descriptors:: FDs and redirections +* File System Conventions:: File- and pathnames +* Shell Substitutions:: Variable and command expansions +* Assignments:: Varying side effects of assignments +* Special Shell Variables:: Variables you should not change +* Limitations of Builtins:: Portable use of not so portable /bin/sh +* Limitations of Usual Tools:: Portable use of portable tools +* Limitations of Make:: Portable Makefiles + +Manual Configuration + +* Specifying Names:: Specifying the system type +* Canonicalizing:: Getting the canonical system type +* Using System Type:: What to do with the system type + +Site Configuration + +* External Software:: Working with other optional software +* Package Options:: Selecting optional features +* Pretty Help Strings:: Formatting help string +* Site Details:: Configuring site details +* Transforming Names:: Changing program names when installing +* Site Defaults:: Giving @code{configure} local defaults + +Transforming Program Names When Installing + +* Transformation Options:: @code{configure} options to transform names +* Transformation Examples:: Sample uses of transforming names +* Transformation Rules:: @file{Makefile} uses of transforming names + +Running @code{configure} Scripts + +* Basic Installation:: Instructions for typical cases +* Compilers and Options:: Selecting compilers and optimization +* Multiple Architectures:: Compiling for multiple architectures at once +* Installation Names:: Installing in different directories +* Optional Features:: Selecting optional features +* System Type:: Specifying the system type +* Sharing Defaults:: Setting site-wide defaults for @code{configure} +* Environment Variables:: Defining environment variables. +* configure Invocation:: Changing how @code{configure} runs + +Obsolete Constructs + +* Obsolete config.status Use:: Different calling convention +* acconfig.h:: Additional entries in @file{config.h.in} +* autoupdate Invocation:: Automatic update of @file{configure.ac} +* Obsolete Macros:: Backward compatibility macros +* Autoconf 1:: Tips for upgrading your files +* Autoconf 2.13:: Some fresher tips + +Upgrading From Version 1 + +* Changed File Names:: Files you might rename +* Changed Makefiles:: New things to put in @file{Makefile.in} +* Changed Macros:: Macro calls you might replace +* Changed Results:: Changes in how to check test results +* Changed Macro Writing:: Better ways to write your own macros + +Upgrading From Version 2.13 + +* Changed Quotation:: Broken code which used to work +* New Macros:: Interaction with foreign macros + +Questions About Autoconf + +* Distributing:: Distributing @code{configure} scripts +* Why GNU m4:: Why not use the standard M4? +* Bootstrapping:: Autoconf and GNU M4 require each other? +* Why Not Imake:: Why GNU uses @code{configure} instead of Imake + +History of Autoconf + +* Genesis:: Prehistory and naming of @code{configure} +* Exodus:: The plagues of M4 and Perl +* Leviticus:: The priestly code of portability arrives +* Numbers:: Growth and contributors +* Deuteronomy:: Approaching the promises of easy configuration + +@end detailmenu +@end menu + +@c ============================================================= Introduction. + +@node Introduction, The GNU build system, Top, Top +@chapter Introduction + +@flushright +A physicist, an engineer, and a computer scientist were discussing the +nature of God. ``Surely a Physicist,'' said the physicist, ``because +early in the Creation, God made Light; and you know, Maxwell's +equations, the dual nature of electromagnetic waves, the relativistic +consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because +before making Light, God split the Chaos into Land and Water; it takes a +hell of an engineer to handle that big amount of mud, and orderly +separation of solids from liquids@dots{}'' The computer scientist +shouted: ``And the Chaos, where do you think it was coming from, hmm?'' + +---Anonymous +@end flushright +@c (via Franc,ois Pinard) + +Autoconf is a tool for producing shell scripts that automatically +configure software source code packages to adapt to many kinds of +@sc{unix}-like systems. The configuration scripts produced by Autoconf +are independent of Autoconf when they are run, so their users do not +need to have Autoconf. + +The configuration scripts produced by Autoconf require no manual user +intervention when run; they do not normally even need an argument +specifying the system type. Instead, they individually test for the +presence of each feature that the software package they are for might need. +(Before each check, they print a one-line message stating what they are +checking for, so the user doesn't get too bored while waiting for the +script to finish.) As a result, they deal well with systems that are +hybrids or customized from the more common @sc{unix} variants. There is +no need to maintain files that list the features supported by each +release of each variant of @sc{unix}. + +For each software package that Autoconf is used with, it creates a +configuration script from a template file that lists the system features +that the package needs or can use. After the shell code to recognize +and respond to a system feature has been written, Autoconf allows it to +be shared by many software packages that can use (or need) that feature. +If it later turns out that the shell code needs adjustment for some +reason, it needs to be changed in only one place; all of the +configuration scripts can be regenerated automatically to take advantage +of the updated code. + +The Metaconfig package is similar in purpose to Autoconf, but the +scripts it produces require manual user intervention, which is quite +inconvenient when configuring large source trees. Unlike Metaconfig +scripts, Autoconf scripts can support cross-compiling, if some care is +taken in writing them. + +Autoconf does not solve all problems related to making portable software +packages---for a more complete solution, it should be used in concert +with other GNU build tools like Automake and Libtool. These other tools +take on jobs like the creation of a portable, recursive @file{Makefile} +with all of the standard targets, linking of shared libraries, and so +on. @xref{The GNU build system}, for more information. + +Autoconf imposes some restrictions on the names of macros used with +@code{#if} in C programs (@pxref{Preprocessor Symbol Index}). + +Autoconf requires @sc{gnu} M4 in order to generate the scripts. It uses +features that some @sc{unix} versions of M4, including @sc{gnu} M4 1.3, +do not have. You must use version 1.4 or later of @sc{gnu} M4. + +@xref{Autoconf 1}, for information about upgrading from version 1. +@xref{History}, for the story of Autoconf's development. +@xref{Questions}, for answers to some common questions about Autoconf. + + +See the @href{http://www.gnu.org/software/autoconf/autoconf.html, +Autoconf web page} for up-to-date information, details on the mailing +lists, pointers to a list of known bugs, etc. + +Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing +list}. + +Bug reports should be preferably submitted to the +@href{http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf, +Autoconf Gnats database}, or sent to @email{bug-autoconf@@gnu.org, the +Autoconf Bugs mailing list}. If possible, first check that your bug is +not already solved in current development versions, and that it has not +been reported yet. Be sure to include all the needed information and a +short @file{configure.ac} that demonstrates the problem. + +Autoconf's development tree is accessible via @sc{cvs}; see the Autoconf +web page for details. There is also a +@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @sc{cvs}web +interface to the Autoconf development tree}. Patches relative to the +current @sc{cvs} version can be sent for review to the +@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}. + +Because of its mission, Autoconf includes only a set of often-used +macros that have already demonstrated their usefulness. Nevertheless, +if you wish to share your macros, or find existing ones, see the +@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro +Archive}, which is kindly run by @email{simons@@computer.org, +Peter Simons}. + + +@c ================================================= The GNU build system + +@node The GNU build system, Making configure Scripts, Introduction, Top +@chapter The GNU build system + +Autoconf solves an important problem---reliable discovery of +system-specific build and runtime information---but this is only one +piece of the puzzle for the development of portable software. To this +end, the GNU project has developed a suite of integrated utilities to +finish the job Autoconf started: the GNU build system, whose most +important components are Autoconf, Automake, and Libtool. In this +chapter, we introduce you to those tools, point you to sources of more +information, and try to convince you to use the entire GNU build system +for your software. + +@menu +* Automake:: Escaping Makefile hell +* Libtool:: Building libraries portably +* Pointers:: More info on the GNU build system +@end menu + +@node Automake, Libtool, The GNU build system, The GNU build system +@section Automake + +The ubiquity of @code{make} means that a @code{Makefile} is almost the +only viable way to distribute automatic build rules for software, but +one quickly runs into @code{make}'s numerous limitations. Its lack of +support for automatic dependency tracking, recursive builds in +subdirectories, reliable timestamps (e.g. for network filesystems), and +so on, mean that developers must painfully (and often incorrectly) +reinvent the wheel for each project. Portability is non-trivial, thanks +to the quirks of @code{make} on many systems. On top of all this is the +manual labor required to implement the many standard targets that users +have come to expect (@code{make install}, @code{make distclean}, +@code{make uninstall}, etc.). Since you are, of course, using Autoconf, +you also have to insert repetitive code in your @code{Makefile.in} to +recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions +provided by @code{configure}. Into this mess steps @dfn{Automake}. +@cindex Automake + +Automake allows you to specify your build needs in a @code{Makefile.am} +file with a vastly simpler and more powerful syntax than that of a plain +@code{Makefile}, and then generates a portable @code{Makefile.in} for +use with Autoconf. For example, the @code{Makefile.am} to build and +install a simple ``Hello world'' program might look like: + +@example +bin_PROGRAMS = hello +hello_SOURCES = hello.c +@end example + +@noindent +The resulting @code{Makefile.in} (~400 lines) automatically supports all +the standard targets, the substitutions provided by Autoconf, automatic +dependency tracking, @code{VPATH} building, and so on. @code{make} will +build the @code{hello} program, and @code{make install} will install it +in @file{/usr/local/bin} (or whatever prefix was given to +@code{configure}, if not @file{/usr/local}). + +Automake may require that additional tools be present on the +@emph{developer's} machine. For example, the @code{Makefile.in} that +the developer works with may not be portable (e.g. it might use special +features of your compiler to automatically generate dependency +information). Running @code{make dist}, however, produces a +@file{hello-1.0.tar.gz} package (or whatever the program/version is) +with a @code{Makefile.in} that will work on any system. + +The benefits of Automake increase for larger packages (especially ones +with subdirectories), but even for small programs the added convenience +and portability can be substantial. And that's not all@dots{} + +@node Libtool, Pointers, Automake, The GNU build system +@section Libtool + +Very often, one wants to build not only programs, but libraries, so that +other programs can benefit from the fruits of your labor. Ideally, one +would like to produce @emph{shared} (dynamically-linked) libraries, +which can be used by multiple programs without duplication on disk or in +memory and can be updated independently of the linked programs. +Producing shared libraries portably, however, is the stuff of +nightmares---each system has its own incompatible tools, compiler flags, +and magic incantations. Fortunately, GNU provides a solution: +@dfn{Libtool}. +@cindex Libtool + +Libtool handles all the requirements of building shared libraries for +you, and at this time seems to be the @emph{only} way to do so with any +portability. It also handles many other headaches, such as: the +interaction of @code{Makefile} rules with the variable suffixes of +shared libraries, linking reliably to shared libraries before they are +installed by the superuser, and supplying a consistent versioning system +(so that different versions of a library can be installed or upgraded +without breaking binary compatibility). Although Libtool, like +Autoconf, can be used on its own, it is most simply utilized in +conjunction with Automake---there, Libtool is used automatically +whenever shared libraries are needed, and you need not know its syntax. + +@node Pointers, , Libtool, The GNU build system +@section Pointers + +Developers who are used to the simplicity of @code{make} for small +projects on a single system might be daunted at the prospect of learning +to use Automake and Autoconf. As your software is distributed to more +and more users, however, you will otherwise quickly find yourself +putting lots of effort into reinventing the services that the GNU build +tools provide, and making the same mistakes that they once made and +overcame. (Besides, since you're already learning Autoconf, Automake +will be a piece of cake.) + +There are a number of places that you can go to for more information on +the GNU build tools. + +@itemize @minus + +@item Web + +The home pages for +@href{http://www.gnu.org/software/autoconf/,Autoconf}, and +@href{http://www.gnu.org/software/libtool/,Libtool}. + +@item Books + +The book @cite{GNU Autoconf, Automake and Libtool}@footnote{@cite{GNU +Autoconf, Automake and Libtool}, by G. V. Vaughan, B. Elliston, +T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN 1578701902.} +describes the complete GNU build environment. You can also find the +entire book on-line at @href{http://sources.redhat.com/autobook/,``The +Goat Book'' home page}. + +@item Tutorials and Examples + +The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page} +maintains links to a number of Autoconf/Automake tutorials online, and +also links to the @href{http://www.gnu.org/software/ac-archive/, +Autoconf Macro Archive}. + +@end itemize + +@c ================================================= Making configure Scripts. + +@node Making configure Scripts, Setup, The GNU build system, Top +@chapter Making @code{configure} Scripts +@cindex @file{aclocal.m4} +@cindex @code{configure} + +The configuration scripts that Autoconf produces are by convention +called @code{configure}. When run, @code{configure} creates several +files, replacing configuration parameters in them with appropriate +values. The files that @code{configure} creates are: + +@itemize @minus +@item +one or more @file{Makefile} files, one in each subdirectory of the +package (@pxref{Makefile Substitutions}); + +@item +optionally, a C header file, the name of which is configurable, +containing @code{#define} directives (@pxref{Configuration Headers}); + +@item +a shell script called @file{config.status} that, when run, will recreate +the files listed above (@pxref{config.status Invocation}); + +@item +an optional shell script normally called @file{config.cache} +(created when using @samp{configure --config-cache}) that +saves the results of running many of the tests (@pxref{Cache Files}); + +@item +a file called @file{config.log} containing any messages produced by +compilers, to help debugging if @code{configure} makes a mistake. +@end itemize + +@cindex @file{configure.in} +@cindex @file{configure.ac} +To create a @code{configure} script with Autoconf, you need to write an +Autoconf input file @file{configure.ac} (or @file{configure.in}) and run +@code{autoconf} on it. If you write your own feature tests to +supplement those that come with Autoconf, you might also write files +called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header +file to contain @code{#define} directives, you might also run +@code{autoheader}, and you will distribute the generated file +@file{config.h.in} with the package. + +Here is a diagram showing how the files that can be used in +configuration are produced. Programs that are executed are suffixed by +@samp{*}. Optional files are enclosed in square brackets (@samp{[]}). +@code{autoconf} and @code{autoheader} also read the installed Autoconf +macro files (by reading @file{autoconf.m4}). + +@noindent +Files used in preparing a software package for distribution: +@example +your source files --> [autoscan*] --> [configure.scan] --> configure.ac + +@group +configure.ac --. + | .------> autoconf* -----> configure +[aclocal.m4] --+---+ + | `-----> [autoheader*] --> [config.h.in] +[acsite.m4] ---' +@end group + +Makefile.in -------------------------------> Makefile.in +@end example + +@noindent +Files used in configuring a software package: +@example +@group + .-------------> [config.cache] +configure* ------------+-------------> config.log + | +[config.h.in] -. v .-> [config.h] -. + +--> config.status* -+ +--> make* +Makefile.in ---' `-> Makefile ---' +@end group +@end example + +@menu +* Writing configure.ac:: What to put in an Autoconf input file +* autoscan Invocation:: Semi-automatic @file{configure.ac} writing +* ifnames Invocation:: Listing the conditionals in source code +* autoconf Invocation:: How to create configuration scripts +* autoreconf Invocation:: Remaking multiple @code{configure} scripts +@end menu + +@node Writing configure.ac, autoscan Invocation, Making configure Scripts, Making configure Scripts +@section Writing @file{configure.ac} + +To produce a @code{configure} script for a software package, create a +file called @file{configure.ac} that contains invocations of the +Autoconf macros that test the system features your package needs or can +use. Autoconf macros already exist to check for many features; see +@ref{Existing Tests}, for their descriptions. For most other features, +you can use Autoconf template macros to produce custom checks; see +@ref{Writing Tests}, for information about them. For especially tricky +or specialized features, @file{configure.ac} might need to contain some +hand-crafted shell commands; see @ref{Portable Shell}. The +@code{autoscan} program can give you a good start in writing +@file{configure.ac} (@pxref{autoscan Invocation}, for more information). + +Previous versions of Autoconf promoted the name @file{configure.in}, +which is somewhat ambiguous (the tool needed to produce this file is not +described by its extension), and introduces a slight confusion with +@file{config.h.in} and so on (for which @samp{.in} means ``to be +processed by @code{configure}''). Using @file{configure.ac} is now +preferred. + +@menu +* Shell Script Compiler:: Autoconf as solution of a problem +* Autoconf Language:: Programming in Autoconf +* configure.ac Layout:: Standard organization of configure.ac +@end menu + +@node Shell Script Compiler, Autoconf Language, Writing configure.ac, Writing configure.ac +@subsection A Shell Script Compiler + +Just as for any other computer language, in order to properly program +@file{configure.ac} in Autoconf you must understand @emph{what} problem +the language tries to address and @emph{how} it does so. + +The problem Autoconf addresses is that the world is a mess. After all, +you are using Autoconf in order to have your package compile easily on +all sorts of different systems, some of them being extremely hostile. +Autoconf itself bears the price for these differences: @code{configure} +must run on all those systems, and thus @code{configure} must limit itself +to their lowest common denominator of features. + +Naturally, you might then think of shell scripts; who needs +@code{autoconf}? A set of properly written shell functions is enough to +make it easy to write @code{configure} scripts by hand. Sigh! +Unfortunately, shell functions do not belong to the least common +denominator; therefore, where you would like to define a function and +use it ten times, you would instead need to copy its body ten times. + +So, what is really needed is some kind of compiler, @code{autoconf}, +that takes an Autoconf program, @file{configure.ac}, and transforms it +into a portable shell script, @code{configure}. + +How does @code{autoconf} perform this task? + +There are two obvious possibilities: creating a brand new language or +extending an existing one. The former option is very attractive: all +sorts of optimizations could easily be implemented in the compiler and +many rigorous checks could be performed on the Autoconf program +(e.g. rejecting any non-portable construct). Alternatively, you can +extend an existing language, such as the @code{sh} (Bourne shell) +language. + +Autoconf does the latter: it is a layer on top of @code{sh}. It was +therefore most convenient to implement @code{autoconf} as a macro +expander: a program that repeatedly performs @dfn{macro expansions} on +text input, replacing macro calls with macro bodies and producing a pure +@code{sh} script in the end. Instead of implementing a dedicated +Autoconf macro expander, it is natural to use an existing +general-purpose macro language, such as M4, and implement the extensions +as a set of M4 macros. + + +@node Autoconf Language, configure.ac Layout, Shell Script Compiler, Writing configure.ac +@subsection The Autoconf Language +@cindex quotation + +The Autoconf language is very different from many other computer +languages because it treats actual code the same as plain text. Whereas +in C, for instance, data and instructions have very different syntactic +status, in Autoconf their status is rigorously the same. Therefore, we +need a means to distinguish literal strings from text to be expanded: +quotation. + +When calling macros that take arguments, there must not be any blank +space between the macro name and the open parenthesis. Arguments should +be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be +separated by commas. Any leading spaces in arguments are ignored, +unless they are quoted. You may safely leave out the quotes when the +argument is simple text, but @emph{always} quote complex arguments such +as other macro calls. This rule applies recursively for every macro +call, including macros called from other macros. + +For instance: + +@example +AC_CHECK_HEADER([stdio.h], + [AC_DEFINE([HAVE_STDIO_H])], + [AC_MSG_ERROR([Sorry, can't do anything for you])]) +@end example + +@noindent +is quoted properly. You may safely simplify its quotation to: + +@example +AC_CHECK_HEADER(stdio.h, + [AC_DEFINE(HAVE_STDIO_H)], + [AC_MSG_ERROR([Sorry, can't do anything for you])]) +@end example + +@noindent +Notice that the argument of @code{AC_MSG_ERROR} is still quoted; +otherwise, its comma would have been interpreted as an argument separator. + +The following example is wrong and dangerous, as it is underquoted: + +@example +AC_CHECK_HEADER(stdio.h, + AC_DEFINE(HAVE_STDIO_H), + AC_MSG_ERROR([Sorry, can't do anything for you])) +@end example + +In other cases, you may have to use text that also resembles a macro +call. You must quote that text even when it is not passed as a macro +argument: + +@example +echo "Hard rock was here! --[AC_DC]" +@end example + +@noindent +which will result in + +@example +echo "Hard rock was here! --AC_DC" +@end example + +@noindent +When you use the same text in a macro argument, you must therefore have +an extra quotation level (since one is stripped away by the macro +substitution). In general, then, it is a good idea to @emph{use double +quoting for all literal string arguments}: + +@example +AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) +@end example + +You are now able to understand one of the constructs of Autoconf that +has been continually misunderstood@dots{} The rule of thumb is that +@emph{whenever you expect macro expansion, expect quote expansion}; +i.e., expect one level of quotes to be lost. For instance: + +@example +AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])]) +@end example + +@noindent +is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is +@samp{char b[10];} and will be expanded once, which results in +@samp{char b10;}. (There was an idiom common in Autoconf's past to +address this issue via the M4 @code{changequote} primitive, but do not +use it!) Let's take a closer look: the author meant the first argument +to be understood as a literal, and therefore it must be quoted twice: + +@example +AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])]) +@end example + +@noindent +Voil@`a, you actually produce @samp{char b[10];} this time! + +The careful reader will notice that, according to these guidelines, the +``properly'' quoted @code{AC_CHECK_HEADER} example above is actually +lacking three pairs of quotes! Nevertheless, for the sake of readability, +double quotation of literals is used only where needed in this manual. + +Some macros take optional arguments, which this documentation represents +as @ovar{arg} (not to be confused with the quote characters). You may +just leave them empty, or use @samp{[]} to make the emptiness of the +argument explicit, or you may simply omit the trailing commas. The +three lines below are equivalent: + +@example +AC_CHECK_HEADERS(stdio.h, [], [], []) +AC_CHECK_HEADERS(stdio.h,,,) +AC_CHECK_HEADERS(stdio.h) +@end example + +It is best to put each macro call on its own line in +@file{configure.ac}. Most of the macros don't add extra newlines; they +rely on the newline after the macro call to terminate the commands. +This approach makes the generated @code{configure} script a little +easier to read by not inserting lots of blank lines. It is generally +safe to set shell variables on the same line as a macro call, because +the shell allows assignments without intervening newlines. + +You can include comments in @file{configure.ac} files by starting them +with the @samp{#}. For example, it is helpful to begin +@file{configure.ac} files with a line like this: + +@example +# Process this file with autoconf to produce a configure script. +@end example + +@node configure.ac Layout, , Autoconf Language, Writing configure.ac +@subsection Standard @file{configure.ac} Layout + +The order in which @file{configure.ac} calls the Autoconf macros is not +important, with a few exceptions. Every @file{configure.ac} must +contain a call to @code{AC_INIT} before the checks, and a call to +@code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros +rely on other macros having been called first, because they check +previously set values of some variables to decide what to do. These +macros are noted in the individual descriptions (@pxref{Existing +Tests}), and they also warn you when @code{configure} is created if they +are called out of order. + +To encourage consistency, here is a suggested order for calling the +Autoconf macros. Generally speaking, the things near the end of this +list are those that could depend on things earlier in it. For example, +library functions could be affected by types and libraries. + +@display +@group +Autoconf requirements +@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})} +information on the package +checks for programs +checks for libraries +checks for header files +checks for types +checks for structures +checks for compiler characteristics +checks for library functions +checks for system services +@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})} +@code{AC_OUTPUT} +@end group +@end display + + +@node autoscan Invocation, ifnames Invocation, Writing configure.ac, Making configure Scripts +@section Using @code{autoscan} to Create @file{configure.ac} +@cindex @code{autoscan} + +The @code{autoscan} program can help you create and/or maintain a +@file{configure.ac} file for a software package. @code{autoscan} +examines source files in the directory tree rooted at a directory given +as a command line argument, or the current directory if none is given. +It searches the source files for common portability problems and creates +a file @file{configure.scan} which is a preliminary @file{configure.ac} +for that package, and checks a possibly existing @file{configure.ac} for +completeness. + +When using @command{autoscan} to create a @file{configure.ac}, you +should manually examine @file{configure.scan} before renaming it to +@file{configure.ac}; it will probably need some adjustments. +Occasionally, @code{autoscan} outputs a macro in the wrong order +relative to another macro, so that @code{autoconf} produces a warning; +you need to move such macros manually. Also, if you want the package to +use a configuration header file, you must add a call to +@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might +also have to change or add some @code{#if} directives to your program in +order to make it work with Autoconf (@pxref{ifnames Invocation}, for +information about a program that can help with that job). + +When using @command{autoscan} to maintain a @file{configure.ac}, simply +consider adding its suggestions. The file @file{autoscan.log} will +contain detailed information on why a macro is requested. + +@code{autoscan} uses several data files (installed along with Autoconf) +to determine which macros to output when it finds particular symbols in +a package's source files. These data files all have the same format: +each line consists of a symbol, whitespace, and the Autoconf macro to +output if that symbol is encountered. Lines starting with @samp{#} are +comments. + +@code{autoscan} is only installed if you already have Perl installed. +@code{autoscan} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --verbose +@itemx -v +Print the names of the files it examines and the potentially interesting +symbols it finds in them. This output can be voluminous. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. +@end table + +@node ifnames Invocation, autoconf Invocation, autoscan Invocation, Making configure Scripts +@section Using @code{ifnames} to List Conditionals +@cindex @code{ifnames} + +@code{ifnames} can help you write @file{configure.ac} for a software +package. It prints the identifiers that the package already uses in C +preprocessor conditionals. If a package has already been set up to have +some portability, @code{ifnames} can thus help you figure out what its +@code{configure} needs to check for. It may help fill in some gaps in a +@file{configure.ac} generated by @code{autoscan} (@pxref{autoscan +Invocation}). + +@code{ifnames} scans all of the C source files named on the command line +(or the standard input, if none are given) and writes to the standard +output a sorted list of all the identifiers that appear in those files +in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef} +directives. It prints each identifier on a line, followed by a +space-separated list of the files in which that identifier occurs. + +@noindent +@code{ifnames} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. +@end table + +@node autoconf Invocation, autoreconf Invocation, ifnames Invocation, Making configure Scripts +@section Using @code{autoconf} to Create @code{configure} +@cindex @code{autoconf} + +To create @code{configure} from @file{configure.ac}, run the +@code{autoconf} program with no arguments. @code{autoconf} processes +@file{configure.ac} with the @code{m4} macro processor, using the +Autoconf macros. If you give @code{autoconf} an argument, it reads that +file instead of @file{configure.ac} and writes the configuration script +to the standard output instead of to @code{configure}. If you give +@code{autoconf} the argument @option{-}, it reads from the standard +input instead of @file{configure.ac} and writes the configuration script +to the standard output. + +The Autoconf macros are defined in several files. Some of the files are +distributed with Autoconf; @code{autoconf} reads them first. Then it +looks for the optional file @file{acsite.m4} in the directory that +contains the distributed Autoconf macro files, and for the optional file +@file{aclocal.m4} in the current directory. Those files can contain +your site's or the package's own Autoconf macro definitions +(@pxref{Writing Autoconf Macros}, for more information). If a macro is defined +in more than one of the files that @code{autoconf} reads, the last +definition it reads overrides the earlier ones. + +@code{autoconf} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --verbose +@itemx -v +Report processing steps. + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. + +@item --localdir=@var{dir} +@itemx -l @var{dir} +Look for the package file @file{aclocal.m4} in directory @var{dir} +instead of in the current directory. + +@item --output=@var{file} +@itemx -o @var{file} +Save output (script or trace) to @var{file}. The file @option{-} stands +for the standard output. + +@item --warnings=@var{category} +@itemx -W @var{category} +@evindex WARNINGS +Report the warnings related to @var{category} (which can actually be a +comma separated list). @xref{Reporting Messages}, macro +@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special +values include: + +@table @samp +@item all +report all the warnings + +@item none +report none + +@item error +treats warnings as errors + +@item no-@var{category} +disable warnings falling into @var{category} +@end table + +Warnings about @samp{syntax} are enabled by default, and the environment +variable @code{WARNINGS}, a comma separated list of categories, is +honored. @command{autoconf -W @var{category}} will actually +behave as if you had run: + +@example +autoconf --warnings=syntax,$WARNINGS,@var{category} +@end example + +@noindent +If you want to disable @command{autoconf}'s defaults and @code{WARNINGS}, +but (for example) enable the warnings about obsolete constructs, you +would use @option{-W none,obsolete}. + +@cindex Back trace +@cindex Macro invocation stack +@command{autoconf} displays a back trace for errors, but not for +warnings; if you want them, just pass @option{-W error}. For instance, +on this @file{configure.ac}: + +@example +AC_DEFUN([INNER], +[AC_TRY_RUN([true])]) + +AC_DEFUN([OUTER], +[INNER]) + +AC_INIT +OUTER +@end example + +@noindent +you get: + +@example +$ autoconf -Wcross +configure.ac:8: warning: AC_TRY_RUN called without default \ +to allow cross compiling +$ autoconf -Wcross,error +configure.ac:8: error: AC_TRY_RUN called without default \ +to allow cross compiling +acgeneral.m4:3044: AC_TRY_RUN is expanded from... +configure.ac:2: INNER is expanded from... +configure.ac:5: OUTER is expanded from... +configure.ac:8: the top level +@end example + +@item --trace=@var{macro}[:@var{format}] +@itemx -t @var{macro}[:@var{format}] +Do not create the @code{configure} script, but list the calls to +@var{macro} according to the @var{format}. Multiple @option{--trace} +arguments can be used to list several macros. Multiple @option{--trace} +arguments for a single macro are not cumulative; instead, you should +just make @var{format} as long as needed. + +The @var{format} is a regular string, with newlines if desired, and +several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see +below for details on the @var{format}. + +@item --initialization +@itemx -i +By default, @option{--trace} does not trace the initialization of the +Autoconf macros (typically the @code{AC_DEFUN} definitions). This +results in a noticeable speedup, but can be disabled by this option. +@end table + + +It is often necessary to check the content of a @file{configure.ac} +file, but parsing it yourself is extremely fragile and error-prone. It +is suggested that you rely upon @option{--trace} to scan +@file{configure.ac}. + +The @var{format} of @option{--trace} can use the following special +escapes: + +@table @samp +@item $$ +The character @samp{$}. + +@item $f +The filename from which @var{macro} is called. + +@item $l +The line number from which @var{macro} is called. + +@item $d +The depth of the @var{macro} call. This is an M4 technical detail that +you probably don't want to know about. + +@item $n +The name of the @var{macro}. + +@item $@var{num} +The @var{num}th argument of the call to @var{macro}. + +@item $@@ +@itemx $@var{sep}@@ +@itemx $@{@var{separator}@}@@ +All the arguments passed to @var{macro}, separated by the character +@var{sep} or the string @var{separator} (@samp{,} by default). Each +argument is quoted, i.e. enclosed in a pair of square brackets. + +@item $* +@itemx $@var{sep}* +@itemx $@{@var{separator}@}* +As above, but the arguments are not quoted. + +@item $% +@itemx $@var{sep}% +@itemx $@{@var{separator}@}% +As above, but the arguments are not quoted, all new line characters in +the arguments are smashed, and the default separator is @samp{:}. + +The escape @samp{$%} produces single-line trace outputs (unless you put +newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do +not. +@end table + +For instance, to find the list of variables that are substituted, use: + +@example +@group +$ autoconf -t AC_SUBST +configure.ac:2:AC_SUBST:ECHO_C +configure.ac:2:AC_SUBST:ECHO_N +configure.ac:2:AC_SUBST:ECHO_T +@i{More traces deleted} +@end group +@end example + +@noindent +The example below highlights the difference between @samp{$@@}, +@samp{$*}, and @strong{$%}. + +@example +@group +$ cat configure.ac +AC_DEFINE(This, is, [an +[example]]) +$ autoconf -t 'AC_DEFINE:@@: $@@ +*: $* +$: $%' +@@: [This],[is],[an +[example]] +*: This,is,an +[example] +$: This:is:an [example] +@end group +@end example + +@noindent +The @var{format} gives you a lot of freedom: + +@example +@group +$ autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";' +$ac_subst@{"ECHO_C"@} = "configure.ac:2"; +$ac_subst@{"ECHO_N"@} = "configure.ac:2"; +$ac_subst@{"ECHO_T"@} = "configure.ac:2"; +@i{More traces deleted} +@end group +@end example + +@noindent +A long @var{separator} can be used to improve the readability of complex +structures, and to ease its parsing (for instance when no single +character is suitable as a separator)): + +@example +@group +$ autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*' +AUTOCONF|:::::|autoconf|:::::|$missing_dir +@i{More traces deleted} +@end group +@end example + +@node autoreconf Invocation, , autoconf Invocation, Making configure Scripts +@section Using @code{autoreconf} to Update @code{configure} Scripts +@cindex @code{autoreconf} + +If you have a lot of Autoconf-generated @code{configure} scripts, the +@code{autoreconf} program can save you some work. It runs +@code{autoconf} (and @code{autoheader}, where appropriate) repeatedly to +remake the Autoconf @code{configure} scripts and configuration header +templates in the directory tree rooted at the current directory. By +default, it only remakes those files that are older than their +@file{configure.ac} or (if present) @file{aclocal.m4}. Since +@code{autoheader} does not change the timestamp of its output file if +the file wouldn't be changing, this is not necessarily the minimum +amount of work. If you install a new version of Autoconf, you can make +@code{autoreconf} remake @emph{all} of the files by giving it the +@option{--force} option. + +If you give @code{autoreconf} the @option{--autoconf-dir=@var{dir}} or +@option{--localdir=@var{dir}} options, it passes them down to +@code{autoconf} and @code{autoheader} (with relative paths adjusted +properly). + +@code{autoreconf} does not support having, in the same directory tree, +both directories that are parts of a larger package (sharing +@file{aclocal.m4} and @file{acconfig.h}) and directories that are +independent packages (each with their own @file{aclocal.m4} and +@file{acconfig.h}). It assumes that they are all part of the same +package if you use @option{--localdir}, or that each directory is a +separate package if you don't use it. This restriction may be removed +in the future. + +@xref{Automatic Remaking}, for @file{Makefile} rules to automatically +remake @code{configure} scripts when their source files change. That +method handles the timestamps of configuration header templates +properly, but does not pass @option{--autoconf-dir=@var{dir}} or +@option{--localdir=@var{dir}}. + +@noindent +@code{autoreconf} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --verbose +Print the name of each directory where @code{autoreconf} runs +@code{autoconf} (and @code{autoheader}, if appropriate). + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --force +@itemx -f +Remake even @file{configure} scripts and configuration headers that are +newer than their input files (@file{configure.ac} and, if present, +@file{aclocal.m4}). + +@item --install +@itemx -i +Copy missing auxiliary files. This option is similar to the option +@code{--add-missing} in other tools. + +@item --symlink +@itemx -s +Instead of copying missing auxiliary files, install symbolic links. + +@item --localdir=@var{dir} +@itemx -l @var{dir} +Have @code{autoconf} and @code{autoheader} look for the package files +@file{aclocal.m4} and (@code{autoheader} only) @file{acconfig.h} (but +not @file{@var{file}.top} and @file{@var{file}.bot}) in directory +@var{dir} instead of in the directory containing each @file{configure.ac}. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. + +@item --m4dir=@var{dir} +@itemx -M @var{dir} +Specify location of additional macro files (@file{m4} by default). +@end table + + +@c ========================================= Initialization and Output Files. + +@node Setup, Existing Tests, Making configure Scripts, Top +@chapter Initialization and Output Files + +Autoconf-generated @code{configure} scripts need some information about +how to initialize, such as how to find the package's source files; and +about the output files to produce. The following sections describe +initialization and the creation of output files. + +@menu +* Notices:: Copyright, version numbers in @code{configure} +* Input:: Where Autoconf should find files +* Output:: Outputting results from the configuration +* Configuration Actions:: Preparing the output based on results +* Configuration Files:: Creating output files +* Makefile Substitutions:: Using output variables in @file{Makefile}s +* Configuration Headers:: Creating a configuration header file +* Configuration Commands:: Running arbitrary instantiation commands +* Configuration Links:: Links depending from the configuration +* Subdirectories:: Configuring independent packages together +* Default Prefix:: Changing the default installation prefix +@end menu + +@node Notices, Input, Setup, Setup +@section Notices in @code{configure} + +The following macros manage version numbers for @code{configure} +scripts. Using them is optional. + +@c FIXME: AC_PREREQ should not be here, but where should it go? +@defmac AC_PREREQ (@var{version}) +@maindex PREREQ +@cindex Version +Ensure that a recent enough version of Autoconf is being used. If the +version of Autoconf being used to create @code{configure} is earlier +than @var{version}, print an error message to the standard error output +and do not create @code{configure}. For example: + +@example +AC_PREREQ(@value{VERSION}) +@end example + +This macro is the only macro that may be used before @code{AC_INIT}, but +for consistency, you are invited not to do so. +@end defmac + +@defmac AC_COPYRIGHT (@var{copyright-notice}) +@maindex COPYRIGHT +@cindex Copyright Notice +State that, in addition to the Free Software Foundation's copyright on +the Autoconf macros, parts of your @code{configure} are covered by the +@var{copyright-notice}. + +The @var{copyright-notice} will show up in both the head of +@code{configure} and in @samp{configure --version}. +@end defmac + + +@defmac AC_REVISION (@var{revision-info}) +@maindex REVISION +@cindex Revision +Copy revision stamp @var{revision-info} into the @code{configure} +script, with any dollar signs or double-quotes removed. This macro lets +you put a revision stamp from @file{configure.ac} into @code{configure} +without @sc{rcs} or @code{cvs} changing it when you check in +@code{configure}. That way, you can determine easily which revision of +@file{configure.ac} a particular @code{configure} corresponds to. + +For example, this line in @file{configure.ac}: + +@c The asis prevents RCS from changing the example in the manual. +@example +AC_REVISION($@asis{Revision: 1.30 }$) +@end example + +@noindent +produces this in @code{configure}: + +@example +#! /bin/sh +# From configure.ac Revision: 1.30 +@end example +@end defmac + + +@node Input, Output, Notices, Setup +@section Finding @code{configure} Input + +Every @code{configure} script must call @code{AC_INIT} before doing +anything else. The only other required macro is @code{AC_OUTPUT} +(@pxref{Output}). + +@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report-address}) +@maindex INIT +Process any command-line arguments and perform various initializations +and verifications. Set the name of the @var{package} and its +@var{version}. The optional argument @var{bug-report-address} should be +the email to which users should send bug reports. +@end defmac + +@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir}) +@maindex CONFIG_SRCDIR +@var{unique-file-in-source-dir} is some file that is in the package's +source directory; @code{configure} checks for this file's existence to +make sure that the directory that it is told contains the source code in +fact does. Occasionally people accidentally specify the wrong directory +with @option{--srcdir}; this is a safety check. @xref{configure +Invocation}, for more information. +@end defmac + + +@c FIXME: Remove definitively once --install explained. +@c +@c Small packages may store all their macros in @code{aclocal.m4}. As the +@c set of macros grows, or for maintenance reasons, a maintainer may prefer +@c to split the macros in several files. In this case, Autoconf must be +@c told which files to load, and in which order. +@c +@c @defmac AC_INCLUDE (@var{file}@dots{}) +@c @maindex INCLUDE +@c @c FIXME: There is no longer shell globbing. +@c Read the macro definitions that appear in the listed files. A list of +@c space-separated filenames or shell globbing patterns is expected. The +@c files will be read in the order they're listed. +@c +@c Because the order of definition of macros is important (only the last +@c definition of a macro is used), beware that it is @code{AC_INIT} that +@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that +@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within +@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in +@c the latter case, non-macro lines from included files may end up in the +@c @file{configure} script, whereas in the former case, they'd be discarded +@c just like any text that appear before @code{AC_INIT}. +@c @end defmac + +Packages that do manual configuration or use the @code{install} program +might need to tell @code{configure} where to find some other shell +scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places +it looks are correct for most cases. + +@defmac AC_CONFIG_AUX_DIR (@var{dir}) +@maindex CONFIG_AUX_DIR +Use the auxiliary build tools (e.g., @file{install-sh}, +@file{config.sub}, @file{config.guess}, Cygnus @code{configure}, +Automake and Libtool scripts etc.) that are in directory @var{dir}. +These are auxiliary files used in configuration. @var{dir} can be +either absolute or relative to @file{@var{srcdir}}. The default is +@file{@var{srcdir}} or @file{@var{srcdir}/..} or +@file{@var{srcdir}/../..}, whichever is the first that contains +@file{install-sh}. The other files are not checked for, so that using +@code{AC_PROG_INSTALL} does not automatically require distributing the +other auxiliary files. It checks for @file{install.sh} also, but that +name is obsolete because some @command{make} have a rule that creates +@file{install} from it if there is no @file{Makefile}. +@end defmac + + +@node Output, Configuration Actions, Input, Setup +@section Outputting Files + +Every Autoconf-generated @code{configure} script must finish by calling +@code{AC_OUTPUT}. It is the macro that generates @file{config.status}, +which will create the @file{Makefile}s and any other files resulting +from configuration. The only other required macro is @code{AC_INIT} +(@pxref{Input}). + +@defmac AC_OUTPUT +@maindex OUTPUT +@cindex Instantiation +Generate @file{config.status} and launch it. Call this macro once, at +the end of @file{configure.ac}. + +@file{config.status} will take all the configuration actions: all the +output files (see @ref{Configuration Files}, macro +@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers}, +macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration +Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see +@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories +to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS}) +are honored. +@end defmac + +Historically, the usage of @code{AC_OUTPUT} was somewhat different. +@xref{Obsolete Macros}, for a description of the arguments that +@code{AC_OUTPUT} used to support. + + +If you run @code{make} on subdirectories, you should run it using the +@code{make} variable @code{MAKE}. Most versions of @code{make} set +@code{MAKE} to the name of the @code{make} program plus any options it +was given. (But many do not include in it the values of any variables +set on the command line, so those are not passed on automatically.) +Some old versions of @code{make} do not set this variable. The +following macro allows you to use it even with those versions. + +@defmac AC_PROG_MAKE_SET +@maindex PROG_MAKE_SET +@ovindex SET_MAKE +If @code{make} predefines the variable @code{MAKE}, define output +variable @code{SET_MAKE} to be empty. Otherwise, define @code{SET_MAKE} +to contain @samp{MAKE=make}. Calls @code{AC_SUBST} for @code{SET_MAKE}. +@end defmac + +To use this macro, place a line like this in each @file{Makefile.in} +that runs @code{MAKE} on other directories: + +@example +@@SET_MAKE@@ +@end example + + + +@node Configuration Actions, Configuration Files, Output, Setup +@section Taking Configuration Actions + +@file{configure} is designed so that it appears to do everything itself, +but there is actually a hidden slave: @file{config.status}. +@file{configure} is in charge of examining your system, but it is +@file{config.status} that actually takes the proper actions based on the +results of @file{configure}. The most typical task of +@file{config.status} is to @emph{instantiate} files. + +This section describes the common behavior of the four standard +instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS}, +@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all +have this prototype: + +@c Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something +@c awful. +@example +AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}]) +@end example + +@noindent +where the arguments are: + +@table @var +@item @var{tag}@dots{} +A whitespace-separated list of tags, which are typically the names of +the files to instantiate. + +@item commands +Shell commands output literally into @file{config.status}, and +associated with a tag that the user can use to tell @file{config.status} +which the commands to run. The commands are run each time a @var{tag} +request is given to @file{config.status}; typically, each time the file +@file{@var{tag}} is created. + +@item init-cmds +Shell commands output @emph{unquoted} near the beginning of +@file{config.status}, and executed each time @file{config.status} runs +(regardless of the tag). Because they are unquoted, for example, +@samp{$var} will be output as the value of @code{var}. @var{init-cmds} +is typically used by @file{configure} to give @file{config.status} some +variables it needs to run the @var{commands}. +@end table + +All these macros can be called multiple times, with different +@var{tag}s, of course! + +You are encouraged to use literals as @var{tags}. In particular, you +should avoid + +@example +@dots{} && my_foos="$my_foos fooo" +@dots{} && my_foos="$my_foos foooo" +AC_CONFIG_FOOS($my_foos) +@end example + +@noindent +and use this instead: + +@example +@dots{} && AC_CONFIG_FOOS(fooo) +@dots{} && AC_CONFIG_FOOS(foooo) +@end example + +The macro @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use +specials @var{tag}s: they may have the form @samp{@var{output}} or +@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated +from its templates, @var{inputs} if specified, defaulting to +@samp{@var{output}.in}. + +For instance +@samp{AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)} asks for +the creation of @file{Makefile} that will be the expansion of the +output variables in the concatenation of @file{boiler/top.mk} and +@file{boiler/bot.mk}. + +The special value @samp{-} might be used to denote the standard output +when used in @var{output}, or the standard input when used in the +@var{inputs}. You most probably don't need to use this in +@file{configure.ac}, but it is convenient when using the command line +interface of @file{./config.status}, see @ref{config.status Invocation}, +for more details. + +The @var{inputs} may be absolute or relative filenames. In the latter +case they are first looked for in the build tree, and then in the source +tree. + + +@node Configuration Files, Makefile Substitutions, Configuration Actions, Setup +@section Creating Configuration Files + +Be sure to read the previous section, @ref{Configuration Actions}. + +@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds}) +@maindex CONFIG_FILES +Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input +file (by default @file{@var{file}.in}), substituting the output variable +values. +@c Before we used to have this feature, which was later rejected +@c because it complicates the write of Makefiles: +@c If the file would be unchanged, it is left untouched, to preserve +@c timestamp. +This macro is one of the instantiating macros, see @ref{Configuration +Actions}. @xref{Makefile Substitutions}, for more information on using +output variables. @xref{Setting Output Variables}, for more information +on creating them. This macro creates the directory that the file is in +if it doesn't exist. Usually, @file{Makefile}s are created this way, +but other files, such as @file{.gdbinit}, can be specified as well. + +Typical calls to @code{AC_CONFIG_FILES} look like this: + +@example +AC_CONFIG_FILES(Makefile src/Makefile man/Makefile X/Imakefile) +AC_CONFIG_FILES(autoconf, chmod +x autoconf) +@end example + +You can override an input file name by appending to @var{file} a +colon-separated list of input files. Examples: + +@example +AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk + lib/Makefile:boiler/lib.mk) +@end example + +@noindent +Doing this allows you to keep your file names acceptable to MS-DOS, or +to prepend and/or append boilerplate to the file. +@end defmac + + + +@node Makefile Substitutions, Configuration Headers, Configuration Files, Setup +@section Substitutions in Makefiles + +Each subdirectory in a distribution that contains something to be +compiled or installed should come with a file @file{Makefile.in}, from +which @code{configure} will create a @file{Makefile} in that directory. +To create a @file{Makefile}, @code{configure} performs a simple variable +substitution, replacing occurrences of @samp{@@@var{variable}@@} in +@file{Makefile.in} with the value that @code{configure} has determined +for that variable. Variables that are substituted into output files in +this way are called @dfn{output variables}. They are ordinary shell +variables that are set in @code{configure}. To make @code{configure} +substitute a particular variable into the output files, the macro +@code{AC_SUBST} must be called with that variable name as an argument. +Any occurrences of @samp{@@@var{variable}@@} for other variables are +left unchanged. @xref{Setting Output Variables}, for more information +on creating output variables with @code{AC_SUBST}. + +A software package that uses a @code{configure} script should be +distributed with a file @file{Makefile.in}, but no @file{Makefile}; that +way, the user has to properly configure the package for the local system +before compiling it. + +@xref{Makefile Conventions,, Makefile Conventions, standards, The +GNU Coding Standards}, for more information on what to put in +@file{Makefile}s. + +@menu +* Preset Output Variables:: Output variables that are always set +* Installation Directory Variables:: Other preset output variables +* Build Directories:: Supporting multiple concurrent compiles +* Automatic Remaking:: Makefile rules for configuring +@end menu + +@node Preset Output Variables, Installation Directory Variables, Makefile Substitutions, Makefile Substitutions +@subsection Preset Output Variables + +Some output variables are preset by the Autoconf macros. Some of the +Autoconf macros set additional output variables, which are mentioned in +the descriptions for those macros. @xref{Output Variable Index}, for a +complete list of output variables. @xref{Installation Directory +Variables}, for the list of the preset ones related to installation +directories. Below are listed the other preset ones. They all are +precious variables (@pxref{Setting Output Variables}, +@code{AC_ARG_VAR}). + +@c Just say no to ASCII sorting! We're humans, not computers. +@c These variables are listed as they would be in a dictionary: +@c actor +@c Actress +@c actress + +@defvar CFLAGS +@ovindex CFLAGS +Debugging and optimization options for the C compiler. If it is not set +in the environment when @code{configure} runs, the default value is set +when you call @code{AC_PROG_CC} (or empty if you don't). @code{configure} +uses this variable when compiling programs to test for C features. +@end defvar + +@defvar configure_input +@ovindex configure_input +A comment saying that the file was generated automatically by +@code{configure} and giving the name of the input file. +@code{AC_OUTPUT} adds a comment line containing this variable to the top +of every @file{Makefile} it creates. For other files, you should +reference this variable in a comment at the top of each input file. For +example, an input shell script should begin like this: + +@example +#! /bin/sh +# @@configure_input@@ +@end example + +@noindent +The presence of that line also reminds people editing the file that it +needs to be processed by @code{configure} in order to be used. +@end defvar + +@defvar CPPFLAGS +@ovindex CPPFLAGS +Header file search directory (@option{-I@var{dir}}) and any other +miscellaneous options for the C and C++ preprocessors and compilers. If +it is not set in the environment when @code{configure} runs, the default +value is empty. @code{configure} uses this variable when compiling or +preprocessing programs to test for C and C++ features. +@end defvar + +@defvar CXXFLAGS +@ovindex CXXFLAGS +Debugging and optimization options for the C++ compiler. If it is not +set in the environment when @code{configure} runs, the default value is +set when you call @code{AC_PROG_CXX} (or empty if you don't). +@code{configure} uses this variable when compiling programs to test for +C++ features. +@end defvar + +@defvar DEFS +@ovindex DEFS +@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS} +is called, @code{configure} replaces @samp{@@DEFS@@} with +@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This +variable is not defined while @code{configure} is performing its tests, +only when creating the output files. @xref{Setting Output Variables}, for +how to check the results of previous tests. +@end defvar + +@defvar ECHO_C +@defvarx ECHO_N +@defvarx ECHO_T +@ovindex ECHO_C +@ovindex ECHO_N +@ovindex ECHO_T +How does one suppress the trailing newline from @code{echo} for +question-answer message pairs? These variables provide a way: + +@example +echo $ECHO_N "And the winner is... $ECHO_C" +sleep 100000000000 +echo "$@{ECHO_T@}dead." +@end example + +@noindent +Some old and uncommon @code{echo} implementations offer no means to +achieve this, in which case @code{ECHO_T} is set to tab. You might not +want to use it. +@end defvar + +@defvar FFLAGS +@ovindex FFLAGS +Debugging and optimization options for the Fortran 77 compiler. If it +is not set in the environment when @code{configure} runs, the default +value is set when you call @code{AC_PROG_F77} (or empty if you don't). +@code{configure} uses this variable when compiling programs to test for +Fortran 77 features. +@end defvar + +@defvar LDFLAGS +@ovindex LDFLAGS +Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous +options for the linker. Don't use this variable to pass library names +(@option{-l}) to the linker, use @code{LIBS} instead. If it is not set +in the environment when @code{configure} runs, the default value is empty. +@code{configure} uses this variable when linking programs to test for +C, C++ and Fortran 77 features. +@end defvar + +@defvar LIBS +@ovindex LIBS +@option{-l} options to pass to the linker. The default value is empty, +but some Autoconf macros may prepend extra libraries to this variable if +those libraries are found and provide necessary functions, see +@ref{Libraries}. @code{configure} uses this variable when linking +programs to test for C, C++ and Fortran 77 features. +@end defvar + +@defvar srcdir +@ovindex srcdir +The directory that contains the source code for that @file{Makefile}. +@end defvar + +@defvar top_srcdir +@ovindex top_srcdir +The top-level source code directory for the package. In the top-level +directory, this is the same as @code{srcdir}. +@end defvar + +@node Installation Directory Variables, Build Directories, Preset Output Variables, Makefile Substitutions +@subsection Installation Directory Variables + +The following variables specify the directories where the package will +be installed, see @ref{Directory Variables,, Variables for Installation +Directories, standards, The GNU Coding Standards}, for more information. +See the end of this section for details on when and how to use these +variables. + +@defvar bindir +@ovindex bindir +The directory for installing executables that users run. +@end defvar + +@defvar datadir +@ovindex datadir +The directory for installing read-only architecture-independent data. +@end defvar + +@defvar exec_prefix +@ovindex exec_prefix +The installation prefix for architecture-dependent files. By default +it's the same as @var{prefix}. You should avoid installing anything +directly to @var{exec_prefix}. However, the default value for +directories containing architecture-dependent files should be relative +to @var{exec_prefix}. +@end defvar + +@defvar includedir +@ovindex includedir +The directory for installing C header files. +@end defvar + +@defvar infodir +@ovindex infodir +The directory for installing documentation in Info format. +@end defvar + +@defvar libdir +@ovindex libdir +The directory for installing object code libraries. +@end defvar + +@defvar libexecdir +@ovindex libexecdir +The directory for installing executables that other programs run. +@end defvar + +@defvar localstatedir +@ovindex localstatedir +The directory for installing modifiable single-machine data. +@end defvar + +@defvar mandir +@ovindex mandir +The top-level directory for installing documentation in man format. +@end defvar + +@defvar oldincludedir +@ovindex oldincludedir +The directory for installing C header files for non-gcc compilers. +@end defvar + +@defvar prefix +@ovindex prefix +The common installation prefix for all files. If @var{exec_prefix} +is defined to a different value, @var{prefix} is used only for +architecture-independent files. +@end defvar + +@defvar sbindir +@ovindex sbindir +The directory for installing executables that system +administrators run. +@end defvar + +@defvar sharedstatedir +@ovindex sharedstatedir +The directory for installing modifiable architecture-independent data. +@end defvar + +@defvar sysconfdir +@ovindex sysconfdir +The directory for installing read-only single-machine data. +@end defvar + + +Most of these variables have values that rely on @code{prefix} or +@code{exec_prefix}. It is on purpose that the directory output +variables keep them unexpanded: typically @samp{@@datadir@@} will be +replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}. + +This behavior is mandated by the @sc{gnu} coding standards, so that when +the user runs: + +@table @samp +@item make +she can still specify a different prefix from the one specified to +@command{configure}, in which case, if needed, the package shall hard +code dependencies to her late desires. + +@item make install +she can specify a different installation location, in which case the +package @emph{must} still depend on the location which was compiled in +(i.e., never recompile when @samp{make install} is run). This is an +extremely important feature, as many people may decide to install all +the files of a package grouped together, and then install links from +the final locations to there. +@end table + +In order to support these features, it is essential that @code{datadir} +remains being defined as @samp{$@{prefix@}/share} to depend upon the +current value of @code{prefix}. + +A corollary is that you should not use these variables but in Makefiles. +For instance, instead of trying to evaluate @code{datadir} in +@file{configure} and hardcoding it in Makefiles using +e.g. @samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir")}, you should add +@samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}. + +Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace +@code{datadir} and friends in your shell scripts and other files, rather +let @command{make} manage their replacement. For instance Autoconf +ships templates of its shell scripts ending with @samp{.sh}, and uses +this Makefile snippet: + +@example +.sh: + rm -f $@@ $@@.tmp + sed 's,@@datadir\@@,$(pkgdatadir),g' $< >$@@.tmp + chmod +x $@@.tmp + mv $@@.tmp $@@ +@end example + +Three things are noteworthy: + +@table @samp +@item @@datadir\@@ +The backslash prevents @command{configure} from replacing +@samp{@@datadir@@} in the sed expression itself. + +@item $(pkgdatadir) +Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable +instead. + +@item , +Don't use @samp{/} in the sed expression(s) since most probably the +variables you use, such as @samp{$(pkgdatadir)}, will contain +some. +@end table + + +@node Build Directories, Automatic Remaking, Installation Directory Variables, Makefile Substitutions +@subsection Build Directories + +You can support compiling a software package for several architectures +simultaneously from the same copy of the source code. The object files +for each architecture are kept in their own directory. + +To support doing this, @code{make} uses the @code{VPATH} variable to +find the files that are in the source directory. @sc{gnu} @code{make} +and most other recent @code{make} programs can do this. Older +@code{make} programs do not support @code{VPATH}; when using them, the +source code must be in the same directory as the object files. + +To support @code{VPATH}, each @file{Makefile.in} should contain two +lines that look like: + +@example +srcdir = @@srcdir@@ +VPATH = @@srcdir@@ +@end example + +Do not set @code{VPATH} to the value of another variable, for example +@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do +variable substitutions on the value of @code{VPATH}. + +@code{configure} substitutes in the correct value for @code{srcdir} when +it produces @file{Makefile}. + +Do not use the @code{make} variable @code{$<}, which expands to the +file name of the file in the source directory (found with @code{VPATH}), +except in implicit rules. (An implicit rule is one such as @samp{.c.o}, +which tells how to create a @file{.o} file from a @file{.c} file.) Some +versions of @code{make} do not set @code{$<} in explicit rules; they +expand it to an empty value. + +Instead, @file{Makefile} command lines should always refer to source +files by prefixing them with @samp{$(srcdir)/}. For example: + +@example +time.info: time.texinfo + $(MAKEINFO) $(srcdir)/time.texinfo +@end example + +@node Automatic Remaking, , Build Directories, Makefile Substitutions +@subsection Automatic Remaking + +You can put rules like the following in the top-level @file{Makefile.in} +for a package to automatically update the configuration information when +you change the configuration files. This example includes all of the +optional files, such as @file{aclocal.m4} and those related to +configuration header files. Omit from the @file{Makefile.in} rules for +any of these files that your package does not use. + +The @samp{$(srcdir)/} prefix is included because of limitations in the +@code{VPATH} mechanism. + +The @file{stamp-} files are necessary because the timestamps of +@file{config.h.in} and @file{config.h} will not be changed if remaking +them does not change their contents. This feature avoids unnecessary +recompilation. You should include the file @file{stamp-h.in} your +package's distribution, so @command{make} will consider +@file{config.h.in} up to date. Don't use @command{touch} +(@pxref{Limitations of Usual Tools}), rather use @command{echo} (using +@command{date} would cause needless differences, hence @sc{cvs} +conflicts etc.). + +@example +@group +$(srcdir)/configure: configure.ac aclocal.m4 + cd $(srcdir) && autoconf + +# autoheader might not change config.h.in, so touch a stamp file. +$(srcdir)/config.h.in: stamp-h.in +$(srcdir)/stamp-h.in: configure.ac aclocal.m4 + cd $(srcdir) && autoheader + echo timestamp > $(srcdir)/stamp-h.in + +config.h: stamp-h +stamp-h: config.h.in config.status + ./config.status + +Makefile: Makefile.in config.status + ./config.status + +config.status: configure + ./config.status --recheck +@end group +@end example + +@noindent +(Be careful if you copy these lines directly into your Makefile, as you +will need to convert the indented lines to start with the tab character.) + +In addition, you should use @samp{AC_CONFIG_FILES(stamp-h, echo +timestamp > stamp-h)} so @file{config.status} will ensure that +@file{config.h} is considered up to date. @xref{Output}, for more +information about @code{AC_OUTPUT}. + +@xref{config.status Invocation}, for more examples of handling +configuration-related dependencies. + +@node Configuration Headers, Configuration Commands, Makefile Substitutions, Setup +@section Configuration Header Files +@cindex Configuration Header +@cindex @file{config.h} + +When a package tests more than a few C preprocessor symbols, the command +lines to pass @option{-D} options to the compiler can get quite long. +This causes two problems. One is that the @code{make} output is hard to +visually scan for errors. More seriously, the command lines can exceed +the length limits of some operating systems. As an alternative to +passing @option{-D} options to the compiler, @code{configure} scripts can +create a C header file containing @samp{#define} directives. The +@code{AC_CONFIG_HEADERS} macro selects this kind of output. It should +be called right after @code{AC_INIT}. + +The package should @samp{#include} the configuration header file before +any other header files, to prevent inconsistencies in declarations (for +example, if it redefines @code{const}). Use @samp{#include <config.h>} +instead of @samp{#include "config.h"}, and pass the C compiler a +@option{-I.} option (or @option{-I..}; whichever directory contains +@file{config.h}). That way, even if the source directory is configured +itself (perhaps to make a distribution), other build directories can +also be configured without finding the @file{config.h} from the source +directory. + +@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds}) +@maindex CONFIG_HEADERS +@cvindex HAVE_CONFIG_H +This macro is one of the instantiating macros, see @ref{Configuration +Actions}. Make @code{AC_OUTPUT} create the file(s) in the +whitespace-separated list @var{header} containing C preprocessor +@code{#define} statements, and replace @samp{@@DEFS@@} in generated +files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. +The usual name for @var{header} is @file{config.h}. + +If @var{header} already exists and its contents are identical to what +@code{AC_OUTPUT} would put in it, it is left alone. Doing this allows +some changes in configuration without needlessly causing object files +that depend on the header file to be recompiled. + +Usually the input file is named @file{@var{header}.in}; however, you can +override the input file name by appending to @var{header}, a +colon-separated list of input files. Examples: + +@example +AC_CONFIG_HEADERS(config.h:config.hin) +AC_CONFIG_HEADERS(defines.h:defs.pre:defines.h.in:defs.post) +@end example + +@noindent +Doing this allows you to keep your file names acceptable to MS-DOS, or +to prepend and/or append boilerplate to the file. +@end defmac + +@xref{Configuration Actions}, for more details on @var{header}. + +@menu +* Header Templates:: Input for the configuration headers +* autoheader Invocation:: How to create configuration templates +* Autoheader Macros:: How to specify CPP templates +@end menu + +@node Header Templates, autoheader Invocation, Configuration Headers, Configuration Headers +@subsection Configuration Header Templates +@cindex Configuration Header Template +@cindex @file{config.h.in} + +Your distribution should contain a template file that looks as you want +the final header file to look, including comments, with @code{#undef} +statements which are used as hooks. For example, suppose your +@file{configure.ac} makes these calls: + +@example +AC_CONFIG_HEADERS(conf.h) +AC_CHECK_HEADERS(unistd.h) +@end example + +@noindent +Then you could have code like the following in @file{conf.h.in}. On +systems that have @file{unistd.h}, @code{configure} will @samp{#define} +@samp{HAVE_UNISTD_H} to 1. On other systems, the whole line will be +commented out (in case the system predefines that symbol). + +@example +@group +/* Define as 1 if you have unistd.h. */ +#undef HAVE_UNISTD_H +@end group +@end example + +You can then decode the configuration header using the preprocessor +directives: + +@example +@group +#include <conf.h> + +#if HAVE_UNISTD_H +# include <unistd.h> +#else +/* We are in trouble. */ +#endif +@end group +@end example + +The use of old form templates, with @samp{#define} instead of +@samp{#undef} is strongly discouraged. + +Since it is a tedious task to keep a template header up to date, you may +use @code{autoheader} to generate it, see @ref{autoheader Invocation}. + + +@node autoheader Invocation, Autoheader Macros, Header Templates, Configuration Headers +@subsection Using @code{autoheader} to Create @file{config.h.in} +@cindex @code{autoheader} + +The @command{autoheader} program can create a template file of C +@samp{#define} statements for @code{configure} to use. If +@file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})}, +@command{autoheader} creates @file{@var{file}.in}; if multiple file +arguments are given, the first one is used. Otherwise, +@command{autoheader} creates @file{config.h.in}. + +In order to do its job, @command{autoheader} needs you to document all +of the symbols that you might use; i.e., there must be at least one +@code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} using its third +argument for each symbol (@pxref{Defining Symbols}). An additional +constraint is that the first argument of @code{AC_DEFINE} must be a +literal. Note that all symbols defined by Autoconf's built-in tests are +already documented properly; you only need to document those that you +define yourself. + +You might wonder why @command{autoheader} is needed: after all, why +would @command{configure} need to ``patch'' a @file{config.h.in} to +produce a @file{config.h} instead of just creating @file{config.h} from +scratch? Well, when everything rocks, the answer is just that we are +wasting our time maintaining @command{autoheader}: generating +@file{config.h} directly is all that is needed. When things go wrong, +however, you'll be thankful for the existence of @command{autoheader}. + +The fact that the symbols are documented is important in order to +@emph{check} that @file{config.h} makes sense. The fact that there is a +well defined list of symbols that should be @code{#define}'d (or not) is +also important for people who are porting packages to environments where +@command{configure} cannot be run: they just have to @emph{fill in the +blanks}. + +But let's come back to the point: @command{autoheader}'s invocation@dots{} + +If you give @command{autoheader} an argument, it uses that file instead +of @file{configure.ac} and writes the header file to the standard output +instead of to @file{config.h.in}. If you give @command{autoheader} an +argument of @option{-}, it reads the standard input instead of +@file{configure.ac} and writes the header file to the standard output. + +@code{autoheader} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --verbose +@itemx -v +Report processing steps. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. + +@item --localdir=@var{dir} +@itemx -l @var{dir} +Look for the package files @file{aclocal.m4} and @file{acconfig.h} (but +not @file{@var{file}.top} and @file{@var{file}.bot}) in directory +@var{dir} instead of in the current directory. + +@item --warnings=@var{category} +@itemx -W @var{category} +@evindex WARNINGS +Report the warnings related to @var{category} (which can actually be a +comma separated list). Current categories include: + +@table @samp +@item obsolete +report the uses of obsolete constructs + +@item all +report all the warnings + +@item none +report none + +@item error +treats warnings as errors + +@item no-@var{category} +disable warnings falling into @var{category} +@end table + +@end table + + + +@node Autoheader Macros, , autoheader Invocation, Configuration Headers +@subsection Autoheader Macros + +@code{autoheader} scans @file{configure.ac} and figures out which C +preprocessor symbols it might define. It knows how to generate +templates for symbols defined by @code{AC_CHECK_HEADERS}, +@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional +symbol, you must define a template for it. If there are missing +templates, @code{autoheader} fails with an error message. + +The simplest way to create a template for a @var{symbol} is to supply +the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see +@ref{Defining Symbols}. You may also use one of the following macros. + +@defmac AH_VERBATIM (@var{key}, @var{template}) +@maindex AH_VERBATIM +@maindex VERBATIM +Tell @code{autoheader} to include the @var{template} as-is in the header +template file. This @var{template} is associated with the @var{key}, +which is used to sort all the different templates and guarantee their +uniqueness. It should be the symbol that can be @code{AC_DEFINE}'d. + +For example: + +@example +AH_VERBATIM([_GNU_SOURCE], +[/* Enable GNU extensions on systems that have them. */ +#ifndef _GNU_SOURCE +# define _GNU_SOURCE +#endif]) +@end example +@end defmac + + +@defmac AH_TEMPLATE (@var{key}, @var{description}) +@maindex AH_TEMPLATE +@maindex TEMPLATE +Tell @code{autoheader} to generate a template for @var{key}. This macro +generates standard templates just like @code{AC_DEFINE} when a +@var{description} is given. + +For example: + +@example +AH_TEMPLATE([CRAY_STACKSEG_END], + [Define to one of _getb67, GETB67, getb67 + for Cray-2 and Cray-YMP systems. This + function is required for alloca.c support + on those systems.]) +@end example + +@noindent +will generate the following template, with the description properly +justified. + +@example +/* Define to one of _getb67, GETB67, getb67 for Cray-2 and + Cray-YMP systems. This function is required for alloca.c + support on those systems. */ +#undef CRAY_STACKSEG_END +@end example +@end defmac + + +@defmac AH_TOP (@var{text}) +@maindex AH_TOP +@maindex TOP +Include @var{text} at the top of the header template file. +@end defmac + + +@defmac AH_BOTTOM (@var{text}) +@maindex AH_BOTTOM +@maindex BOTTOM +Include @var{text} at the bottom of the header template file. +@end defmac + + +@node Configuration Commands, Configuration Links, Configuration Headers, Setup +@section Running Arbitrary Configuration Commands + +You execute arbitrary commands either before, during and after +@file{config.status} is run. The three following macros accumulate the +commands to run when they are called multiple times. +@code{AC_CONFIG_COMMANDS} replaces the obsolete macro +@code{AC_OUTPUT_COMMANDS}, see @ref{Obsolete Macros}, for details. + +@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds}) +@maindex CONFIG_COMMANDS +Specify additional shell commands to run at the end of +@file{config.status}, and shell commands to initialize any variables +from @code{configure}. Associate the commands to the @var{tag}. Since +typically the @var{cmds} create a file, @var{tag} should naturally be +the name of that file. This macro is one of the instantiating macros, +see @ref{Configuration Actions}. + +Here is an unrealistic example: +@example +fubar=42 +AC_CONFIG_COMMANDS(fubar, + [echo this is extra $fubar, and so on.], + [fubar=$fubar]) +@end example + +Here is a better one: +@example +AC_CONFIG_COMMANDS(time-stamp, [date >time-stamp]) +@end example +@end defmac + +@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds}) +@maindex OUTPUT_COMMANDS_PRE +Execute the @var{cmds} right before creating @file{config.status}. A +typical use is computing values derived from variables built during the +execution of @code{configure}: + +@example +AC_CONFIG_COMMANDS_PRE( +[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'` +AC_SUBST(LTLIBOBJS)]) +@end example +@end defmac + +@defmac AC_CONFIG_COMMANDS_POST (@var{cmds}) +@maindex OUTPUT_COMMANDS_POST +Execute the @var{cmds} right after creating @file{config.status}. +@end defmac + + + + +@node Configuration Links, Subdirectories, Configuration Commands, Setup +@section Creating Configuration Links + +You may find it convenient to create links whose destinations depend upon +results of tests. One can use @code{AC_CONFIG_COMMANDS} but the +creation of relative symbolic links can be delicate when the package is +built in another directory than its sources. + +@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds}) +@maindex CONFIG_LINKS +@cindex Links +Make @code{AC_OUTPUT} link each of the existing files @var{source} to +the corresponding link name @var{dest}. Makes a symbolic link if +possible, otherwise a hard link. The @var{dest} and @var{source} names +should be relative to the top level source or build directory. This +macro is one of the instantiating macros, see @ref{Configuration +Actions}. + +For example, this call: + +@example +AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) +@end example + +@noindent +creates in the current directory @file{host.h} as a link to +@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a +link to @file{@var{srcdir}/config/$obj_format.h}. + +The tempting value @samp{.} for @var{dest} is invalid: it makes it +impossible for @samp{config.status} to guess the links to establish. + +One can then run: +@example +./config.status host.h object.h +@end example +@noindent +to create the links. +@end defmac + + + +@node Subdirectories, Default Prefix, Configuration Links, Setup +@section Configuring Other Packages in Subdirectories + +In most situations, calling @code{AC_OUTPUT} is sufficient to produce +@file{Makefile}s in subdirectories. However, @code{configure} scripts +that control more than one independent package can use +@code{AC_CONFIG_SUBDIRS} to run @code{configure} scripts for other +packages in subdirectories. + +@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{}) +@maindex CONFIG_SUBDIRS +@ovindex subdirs +Make @code{AC_OUTPUT} run @code{configure} in each subdirectory +@var{dir} in the given whitespace-separated list. Each @var{dir} should +be a literal, i.e., please do not use: + +@example +if test "$package_foo_enabled" = yes; then + $my_subdirs="$my_subdirs foo" +fi +AC_CONFIG_SUBDIRS($my_subdirs) +@end example + +@noindent +because this prevents @samp{./configure --help=recursive} from +displaying the options of the package @code{foo}. Rather, you should +write: + +@example +if test "$package_foo_enabled" = yes then; + AC_CONFIG_SUBDIRS(foo) +fi +@end example + +If a given @var{dir} is not found, no error is reported, so a +@code{configure} script can configure whichever parts of a large source +tree are present. If a given @var{dir} contains @code{configure.gnu}, +it is run instead of @code{configure}. This is for packages that might +use a non-autoconf script @code{Configure}, which can't be called +through a wrapper @code{configure} since it would be the same file on +case-insensitive filesystems. Likewise, if a @var{dir} contains +@file{configure.ac} but no @code{configure}, the Cygnus @code{configure} +script found by @code{AC_CONFIG_AUX_DIR} is used. + +The subdirectory @code{configure} scripts are given the same command +line options that were given to this @code{configure} script, with minor +changes if needed (e.g., to adjust a relative path for the cache file or +source directory). This macro also sets the output variable +@code{subdirs} to the list of directories @samp{@var{dir} @dots{}}. +@file{Makefile} rules can use this variable to determine which +subdirectories to recurse into. This macro may be called multiple +times. +@end defmac + +@node Default Prefix, , Subdirectories, Setup +@section Default Prefix + +By default, @code{configure} sets the prefix for files it installs to +@file{/usr/local}. The user of @code{configure} can select a different +prefix using the @option{--prefix} and @option{--exec-prefix} options. +There are two ways to change the default: when creating +@code{configure}, and when running it. + +Some software packages might want to install in a directory besides +@file{/usr/local} by default. To accomplish that, use the +@code{AC_PREFIX_DEFAULT} macro. + +@defmac AC_PREFIX_DEFAULT (@var{prefix}) +@maindex PREFIX_DEFAULT +Set the default installation prefix to @var{prefix} instead of +@file{/usr/local}. +@end defmac + +It may be convenient for users to have @code{configure} guess the +installation prefix from the location of a related program that they +have already installed. If you wish to do that, you can call +@code{AC_PREFIX_PROGRAM}. + +@defmac AC_PREFIX_PROGRAM (@var{program}) +@maindex PREFIX_PROGRAM +If the user did not specify an installation prefix (using the +@option{--prefix} option), guess a value for it by looking for +@var{program} in @code{PATH}, the way the shell does. If @var{program} +is found, set the prefix to the parent of the directory containing +@var{program}; otherwise leave the prefix specified in +@file{Makefile.in} unchanged. For example, if @var{program} is +@code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc}, +set the prefix to @file{/usr/local/gnu}. +@end defmac + + + +@c ======================================================== Existing tests + +@node Existing Tests, Writing Tests, Setup, Top +@chapter Existing Tests + +These macros test for particular system features that packages might +need or want to use. If you need to test for a kind of feature that +none of these macros check for, you can probably do it by calling +primitive test macros with appropriate arguments (@pxref{Writing +Tests}). + +These tests print messages telling the user which feature they're +checking for, and what they find. They cache their results for future +@code{configure} runs (@pxref{Caching Results}). + +Some of these macros set output variables. @xref{Makefile +Substitutions}, for how to get their values. The phrase ``define +@var{name}'' is used below as a shorthand to mean ``define C +preprocessor symbol @var{name} to the value 1''. @xref{Defining +Symbols}, for how to get those symbol definitions into your program. + +@menu +* Common Behavior:: Macros' standard schemes +* Alternative Programs:: Selecting between alternative programs +* Files:: Checking for the existence of files +* Libraries:: Library archives that might be missing +* Library Functions:: C library functions that might be missing +* Header Files:: Header files that might be missing +* Declarations:: Declarations that may be missing +* Structures:: Structures or members that might be missing +* Types:: Types that might be missing +* Compilers and Preprocessors:: Checking for compiling programs +* System Services:: Operating system services +* UNIX Variants:: Special kludges for specific UNIX variants +@end menu + +@node Common Behavior, Alternative Programs, Existing Tests, Existing Tests +@section Common Behavior + +Much effort has been expended to make Autoconf easy to learn. The most +obvious way to reach this goal is simply to enforce standard interfaces +and behaviors, avoiding exceptions as much as possible. Because of +history and inertia, unfortunately, there are still too many exceptions +in Autoconf; nevertheless, this section describes some of the common +rules. + +@menu +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros +@end menu + +@node Standard Symbols, Default Includes, Common Behavior, Common Behavior +@subsection Standard Symbols + +All the generic macros that @code{AC_DEFINE} a symbol as a result of +their test transform their @var{argument}s to a standard alphabet. +First, @var{argument} is converted to upper case and any asterisks +(@samp{*}) are each converted to @samp{P}. Any remaining characters +that are not alphanumeric are converted to underscores. + +For instance, + +@example +AC_CHECK_TYPES(struct $Expensive*) +@end example + +@noindent +will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check succeeds. + + +@node Default Includes, , Standard Symbols, Common Behavior +@subsection Default Includes +@cindex Includes, default + +Several tests depend upon a set of header files. Since these headers +are not universally available, tests actually have to provide a set of +protected includes, such as: + +@example +@group +#if TIME_WITH_SYS_TIME +# include <sys/time.h> +# include <time.h> +#else +# if HAVE_SYS_TIME_H +# include <sys/time.h> +# else +# include <time.h> +# endif +#endif +@end group +@end example + +@noindent +Unless you know exactly what you are doing, you should avoid using +unconditional includes, and check the existence of the headers you +include beforehand (@pxref{Header Files}). + +Most generic macros provide the following default set of includes: + +@example +@group +#include <stdio.h> +#if HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#if HAVE_SYS_STAT_H +# include <sys/stat.h> +#endif +#if STDC_HEADERS +# include <stdlib.h> +# include <stddef.h> +#else +# if HAVE_STDLIB_H +# include <stdlib.h> +# endif +#endif +#if HAVE_STRING_H +# if !STDC_HEADERS && HAVE_MEMORY_H +# include <memory.h> +# endif +# include <string.h> +#endif +#if HAVE_STRINGS_H +# include <strings.h> +#endif +#if HAVE_INTTYPES_H +# include <inttypes.h> +#else +# if HAVE_STDINT_H +# include <stdint.h> +# endif +#endif +#if HAVE_UNISTD_H +# include <unistd.h> +#endif +@end group +@end example + +If the default includes are used, then Autoconf will automatically check +for the presence of these headers and their compatibility, i.e., you +don't need to run @code{AC_HEADERS_STDC}, nor check for @file{stdlib.h} +etc. + +These headers are checked for in the same order as they are included. +For instance, on some systems @file{string.h} and @file{strings.h} both +exist, but conflict. Then @code{HAVE_STRING_H} will be defined, but +@code{HAVE_STRINGS_H} won't. + +@node Alternative Programs, Files, Common Behavior, Existing Tests +@section Alternative Programs +@cindex Programs, checking + +These macros check for the presence or behavior of particular programs. +They are used to choose between several alternative programs and to +decide what to do once one has been chosen. If there is no macro +specifically defined to check for a program you need, and you don't need +to check for any special properties of it, then you can use one of the +general program-check macros. + +@menu +* Particular Programs:: Special handling to find certain programs +* Generic Programs:: How to find other programs +@end menu + +@node Particular Programs, Generic Programs, Alternative Programs, Alternative Programs +@subsection Particular Program Checks + +These macros check for particular programs---whether they exist, and +in some cases whether they support certain features. + +@defmac AC_PROG_AWK +@maindex PROG_AWK +@ovindex AWK +Check for @code{mawk}, @code{gawk}, @code{nawk}, and @code{awk}, in that +order, and set output variable @code{AWK} to the first one that is found. +It tries @code{mawk} first because that is reported to be the +fastest implementation. +@end defmac + + +@defmac AC_PROG_EGREP +@ovindex EGREP +Check for @code{grep -E}, @code{egrep} in that +order, and set output variable @code{EGREP} to the first one that is found. +@end defmac + + +@defmac AC_PROG_FGREP +@ovindex FGREP +Check for @code{grep -F}, @code{fgrep} in that +order, and set output variable @code{FGREP} to the first one that is found. +@end defmac + + +@defmac AC_PROG_GREP +@ovindex GREP +Check for @code{grep}, @code{ggrep} in that +order, and set output variable @code{GREP} to the first one that is found. +@end defmac + + +@defmac AC_PROG_INSTALL +@maindex PROG_INSTALL +@ovindex INSTALL +@ovindex INSTALL_PROGRAM +@ovindex INSTALL_DATA +@ovindex INSTALL_SCRIPT +Set output variable @code{INSTALL} to the path of a @sc{bsd} compatible +@code{install} program, if one is found in the current @code{PATH}. +Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c}, +checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its +default directories) to determine @var{dir} (@pxref{Output}). Also set +the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to +@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}. + +This macro screens out various instances of @code{install} known not to +work. It prefers to find a C program rather than a shell script, for +speed. Instead of @file{install-sh}, it can also use @file{install.sh}, +but that name is obsolete because some @code{make} programs have a rule +that creates @file{install} from it if there is no @file{Makefile}. + +Autoconf comes with a copy of @file{install-sh} that you can use. If +you use @code{AC_PROG_INSTALL}, you must include either +@file{install-sh} or @file{install.sh} in your distribution, or +@code{configure} will produce an error message saying it can't find +them---even if the system you're on has a good @code{install} program. +This check is a safety measure to prevent you from accidentally leaving +that file out, which would prevent your package from installing on +systems that don't have a @sc{bsd}-compatible @code{install} program. + +If you need to use your own installation program because it has features +not found in standard @code{install} programs, there is no reason to use +@code{AC_PROG_INSTALL}; just put the file name of your program into your +@file{Makefile.in} files. +@end defmac + +@defmac AC_PROG_LEX +@maindex PROG_LEX +@ovindex LEX +@ovindex LEXLIB +@cvindex YYTEXT_POINTER +@ovindex LEX_OUTPUT_ROOT +If @code{flex} is found, set output variable @code{LEX} to @samp{flex} +and @code{LEXLIB} to @option{-lfl}, if that library is in a standard +place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to +@option{-ll}. + +Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead +of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to +the base of the file name that the lexer generates; usually +@file{lex.yy}, but sometimes something else. These results vary +according to whether @code{lex} or @code{flex} is being used. + +You are encouraged to use Flex in your sources, since it is both more +pleasant to use than plain Lex and the C source it produces is portable. +In order to ensure portability, however, you must either provide a +function @code{yywrap} or, if you don't use it (e.g., your scanner has +no @samp{#include}-like feature), simply include a @samp{%noyywrap} +statement in the scanner's source. Once this done, the scanner is +portable (unless @emph{you} felt free to use nonportable constructs) and +does not depend on any library. In this case, and in this case only, it +is suggested that you use this Autoconf snippet: + +@example +AC_PROG_LEX +if test "$LEX" != flex; then + LEX="$SHELL $missing_dir/missing flex" + AC_SUBST(LEX_OUTPUT_ROOT, lex.yy) + AC_SUBST(LEXLIB, '') +fi +@end example + +The shell script @command{missing} can be found in the Automake +distribution. + +To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes +(indirectly) this macro twice, which will cause an annoying but benign +``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions +of Automake will fix this issue, meanwhile, just ignore this message. +@end defmac + +@defmac AC_PROG_LN_S +@maindex PROG_LN_S +@ovindex LN_S +If @samp{ln -s} works on the current file system (the operating system +and file system support symbolic links), set the output variable +@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set +@code{LN_S} to @samp{ln} and otherwise set it to @samp{cp -p}. + +If you make a link a directory other than the current directory, its +meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely +create links using @samp{$(LN_S)}, either find out which form is used +and adjust the arguments, or always invoke @code{ln} in the directory +where the link is to be created. + +In other words, it does not work to do: +@example +$(LN_S) foo /x/bar +@end example + +Instead, do: + +@example +(cd /x && $(LN_S) foo bar) +@end example +@end defmac + +@defmac AC_PROG_RANLIB +@maindex PROG_RANLIB +@ovindex RANLIB +Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} +is found, and otherwise to @samp{:} (do nothing). +@end defmac + +@defmac AC_PROG_YACC +@maindex PROG_YACC +@ovindex YACC +If @code{byacc} is found, set @code{YACC} to @samp{byacc}. +Otherwise, if @code{bison} is found, +set output variable @code{YACC} to @samp{bison -y}. +Finally, if neither @code{byacc} or @code{bison} is found, +set @code{YACC} to @samp{yacc}. +@end defmac + +@node Generic Programs, , Particular Programs, Alternative Programs +@subsection Generic Program and File Checks + +These macros are used to find programs not covered by the ``particular'' +test macros. If you need to check the behavior of a program as well as +find out whether it is present, you have to write your own test for it +(@pxref{Writing Tests}). By default, these macros use the environment +variable @code{PATH}. If you need to check for a program that might not +be in the user's @code{PATH}, you can pass a modified path to use +instead, like this: + +@example +AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd, + $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc) +@end example + +You are strongly encouraged to declare the @var{variable} passed to +@code{AC_CHECK_PROG} etc. as precious, @xref{Setting Output Variables}, +@code{AC_ARG_VAR}, for more details. + +@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject}) +@maindex CHECK_PROG +Check whether program @var{prog-to-check-for} exists in @code{PATH}. If +it is found, set @var{variable} to @var{value-if-found}, otherwise to +@var{value-if-not-found}, if given. Always pass over @var{reject} (an +absolute file name) even if it is the first found in the search path; in +that case, set @var{variable} using the absolute file name of the +@var{prog-to-check-for} found that is not @var{reject}. If +@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for +@var{variable}. +@end defmac + +@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex CHECK_PROGS +Check for each program in the whitespace-separated list +@var{progs-to-check-for} exists on the @code{PATH}. If it is found, set +@var{variable} to the name of that program. Otherwise, continue +checking the next program in the list. If none of the programs in the +list are found, set @var{variable} to @var{value-if-not-found}; if +@var{value-if-not-found} is not specified, the value of @var{variable} +is not changed. Calls @code{AC_SUBST} for @var{variable}. +@end defmac + +@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex CHECK_TOOL +Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} +with a prefix of the host type as determined by +@code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}). +For example, if the user runs @samp{configure --host=i386-gnu}, then +this call: +@example +AC_CHECK_TOOL(RANLIB, ranlib, :) +@end example +@noindent +sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in +@code{PATH}, or otherwise to @samp{ranlib} if that program exists in +@code{PATH}, or to @samp{:} if neither program exists. +@end defmac + +@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex CHECK_TOOLS +Like @code{AC_CHECK_TOOL}, each of the tools in the list @var{progs-to-check-for} are +checked with a prefix of the host type as determined by @code{AC_CANONICAL_HOST}, +followed by a dash (@pxref{Canonicalizing}). If none of the tools can be found with a +prefix, then the first one without a prefix is used. If a tool is found, set +@var{variable} to the name of that program. If none of the tools in the +list are found, set @var{variable} to @var{value-if-not-found}; if +@var{value-if-not-found} is not specified, the value of @var{variable} +is not changed. Calls @code{AC_SUBST} for @var{variable}. +@end defmac + +@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex PATH_PROG +Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire +path of @var{prog-to-check-for} if found. +@end defmac + +@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex PATH_PROGS +Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for} +are found, set @var{variable} to the entire path of the program +found. +@end defmac + +@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex PATH_TOOL +Like @code{AC_CHECK_TOOL}, but set @var{variable} to the entire +path of the program if it is found. +@end defmac + + +@node Files, Libraries, Alternative Programs, Existing Tests +@section Files +@cindex File, checking + +You might also need to check for the existence of files. Before using +these macros, ask yourself whether a run time test might not be a better +solution. Be aware that, like most Autoconf macros, they test a feature +of the host machine, and therefore, they die when cross-compiling. + +@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex CHECK_FILE +Check whether file @var{file} exists on the native system. If it is +found, execute @var{action-if-found}, otherwise do +@var{action-if-not-found}, if given. +@end defmac + +@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex CHECK_FILES +Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}. +Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols}) +for each file found. +@end defmac + + +@node Libraries, Library Functions, Files, Existing Tests +@section Library Files +@cindex Library, checking + +The following macros check for the presence of certain C, C++ or Fortran +77 library archive files. + +@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) +@maindex CHECK_LIB +Depending on the current language(@pxref{Language Choice}), try to +ensure that the C, C++, or Fortran 77 function @var{function} is +available by checking whether a test program can be linked with the +library @var{library} to get the function. @var{library} is the base +name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as +the @var{library} argument. + +@var{action-if-found} is a list of shell commands to run if the link +with the library succeeds; @var{action-if-not-found} is a list of shell +commands to run if the link fails. If @var{action-if-found} is not +specified, the default action will prepend @option{-l@var{library}} to +@code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all +capitals). This macro is intended to support building of @code{LIBS} in +a right-to-left (least-dependent to most-dependent) fashion such that +library dependencies are satisfied as a natural side-effect of +consecutive tests. Some linkers are very sensitive to library ordering +so the order in which @code{LIBS} is generated is important to reliable +detection of libraries. + +If linking with @var{library} results in unresolved symbols that would +be resolved by linking with additional libraries, give those libraries +as the @var{other-libraries} argument, separated by spaces: +e.g. @option{-lXt -lX11}. Otherwise, this macro will fail to detect +that @var{library} is present, because linking the test program will +always fail with unresolved symbols. The @var{other-libraries} argument +should be limited to cases where it is desirable to test for one library +in the presence of another that is not already in @code{LIBS}. +@end defmac + + +@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) +@maindex SEARCH_LIBS +Search for a library defining @var{function} if it's not already +available. This equates to calling @code{AC_TRY_LINK_FUNC} first +with no libraries, then for each library listed in @var{search-libs}. + +Add @option{-l@var{library}} to @code{LIBS} for the first library found +to contain @var{function}, and run @var{action-if-found}. If the +function is not found, run @var{action-if-not-found}. + +If linking with @var{library} results in unresolved symbols that would +be resolved by linking with additional libraries, give those libraries +as the @var{other-libraries} argument, separated by spaces: +e.g. @option{-lXt -lX11}. Otherwise, this macro will fail to detect +that @var{function} is present, because linking the test program will +always fail with unresolved symbols. +@end defmac + + + +@node Library Functions, Header Files, Libraries, Existing Tests +@section Library Functions + +The following macros check for particular C library functions. +If there is no macro specifically defined to check for a function you need, +and you don't need to check for any special properties of +it, then you can use one of the general function-check macros. + +@menu +* Function Portability:: Pitfalls with usual functions +* Particular Functions:: Special handling to find certain functions +* Generic Functions:: How to find other functions +@end menu + +@node Function Portability, Particular Functions, Library Functions, Library Functions +@subsection Portability of Classical Functions + +Most usual functions can either be missing, or be buggy, or be limited +on some architectures. This section tries to make an inventory of these +portability issues. By definition, this list will always require +additions, please help us keeping it as complete as possible + +@table @code + +@item unlink +The @sc{posix} spec says that @code{unlink} causes the given files to be +removed only after there are no more open file handles for it. Not all +OS's support this behaviour though. So even on systems that provide +@code{unlink}, you cannot portably assume it is OK to call it on files +that are open. For example, on Windows 9x and ME, such a call would fail; +on DOS it could even lead to file system corruption, as the file might end +up being written to after the OS has removed it. + +@end table + + +@node Particular Functions, Generic Functions, Function Portability, Library Functions +@subsection Particular Function Checks +@cindex Function, checking + +These macros check for particular C functions---whether they exist, and +in some cases how they respond when given certain arguments. + +@defmac AC_FUNC_ALLOCA +@maindex FUNC_ALLOCA +@cvindex C_ALLOCA +@cvindex HAVE_ALLOCA_H +@ovindex ALLOCA +Check how to get @code{alloca}. Tries to get a builtin version by +checking for @file{alloca.h} or the predefined C preprocessor macros +@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h}, +it defines @code{HAVE_ALLOCA_H}. + +If those attempts fail, it looks for the function in the standard C +library. If any of those methods succeed, it defines +@code{HAVE_ALLOCA}. Otherwise, it sets the output variable +@code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} (so +programs can periodically call @samp{alloca(0)} to garbage collect). +This variable is separate from @code{LIBOBJS} so multiple programs can +share the value of @code{ALLOCA} without needing to create an actual +library, in case only some of them use the code in @code{LIBOBJS}. + +This macro does not try to get @code{alloca} from the System V R3 +@file{libPW} or the System V R4 @file{libucb} because those libraries +contain some incompatible functions that cause trouble. Some versions +do not even contain @code{alloca} or contain a buggy version. If you +still want to use their @code{alloca}, use @code{ar} to extract +@file{alloca.o} from them instead of compiling @file{alloca.c}. + +Source files that use @code{alloca} should start with a piece of code +like the following, to declare it properly. In some versions of AIX, +the declaration of @code{alloca} must precede everything else except for +comments and preprocessor directives. The @code{#pragma} directive is +indented so that pre-@sc{ansi} C compilers will ignore it, rather than +choke on it. + +@example +@group +/* AIX requires this to be the first thing in the file. */ +#ifndef __GNUC__ +# if HAVE_ALLOCA_H +# include <alloca.h> +# else +# ifdef _AIX + #pragma alloca +# else +# ifndef alloca /* predefined by HP cc +Olibcalls */ +char *alloca (); +# endif +# endif +# endif +#endif +@end group +@end example +@end defmac + +@defmac AC_FUNC_CHOWN +@maindex FUNC_CHOWN +If the @code{chown} function is available and works (in particular, it +should accept @option{-1} for @code{uid} and @code{gid}), define +@code{HAVE_CHOWN}. +@end defmac + + +@defmac AC_FUNC_CLOSEDIR_VOID +@maindex FUNC_CLOSEDIR_VOID +@cvindex CLOSEDIR_VOID +If the @code{closedir} function does not return a meaningful value, +define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its +return value for an error indicator. +@end defmac + +@defmac AC_FUNC_ERROR_AT_LINE +@maindex FUNC_ERROR_AT_LINE +If the @code{error_at_line} function is not found, require an +@code{AC_LIBOBJ} replacement of @samp{error}. +@end defmac + +@defmac AC_FUNC_FNMATCH +@maindex FUNC_FNMATCH +If the @code{fnmatch} function is available and works (unlike the one on +Solaris 2.4), define @code{HAVE_FNMATCH}. +@end defmac + +@defmac AC_FUNC_FORK +@maindex FUNC_FORK +@cvindex HAVE_VFORK_H +@cvindex HAVE_WORKING_FORK +@cvindex HAVE_WORKING_VFORK +@cvindex vfork +This macro checks for the @code{fork} and @code{vfork} functions. If a +working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro +checks whether @code{fork} is just a stub by trying to run it. + +If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working +@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise, +define @code{vfork} to be @code{fork} for backward compatibility with +previous versions of @command{autoconf}. This macro checks for several known +errors in implementations of @code{vfork} and considers the system to not +have a working @code{vfork} if it detects any of them. It is not considered +to be an implementation error if a child's invocation of @code{signal} +modifies the parent's signal handler, since child processes rarely change +their signal handlers. + +Since this macro defines @code{vfork} only for backward compatibility with +previous versions of @command{autoconf} you're encouraged to define it +yourself in new code: +@example +@group +#if !HAVE_WORKING_VFORK +# define vfork fork +#endif +@end group +@end example +@end defmac + +@defmac AC_FUNC_FSEEKO +@maindex FUNC_FSEEKO +@cvindex _LARGEFILE_SOURCE +If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}. +Define @code{_LARGEFILE_SOURCE} if necessary. +@end defmac + +@defmac AC_FUNC_GETGROUPS +@maindex FUNC_GETGROUPS +@ovindex GETGROUPS_LIBS +If the @code{getgroups} function is available and works (unlike on +Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define +@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries +needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}. +@end defmac + +@defmac AC_FUNC_GETLOADAVG +@maindex FUNC_GETLOADAVG +@cvindex SVR4 +@cvindex DGUX +@cvindex UMAX +@cvindex UMAX4_3 +@cvindex NLIST_STRUCT +@cvindex NLIST_NAME_UNION +@cvindex GETLODAVG_PRIVILEGED +@cvindex NEED_SETGID +@cvindex C_GETLOADAVG +@ovindex LIBOBJS +@ovindex NEED_SETGID +@ovindex KMEM_GROUP +@ovindex GETLOADAVG_LIBS +Check how to get the system load averages. If the system has the +@code{getloadavg} function, define @code{HAVE_GETLOADAVG}, and set +@code{GETLOADAVG_LIBS} to any libraries needed to get that function. +Also add @code{GETLOADAVG_LIBS} to @code{LIBS}. + +Otherwise, require an @code{AC_LIBOBJ} replacement (@file{getloadavg.c}) +of @samp{getloadavg}, and possibly define several other C preprocessor +macros and output variables: + +@enumerate +@item +Define @code{C_GETLOADAVG}. + +@item +Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on +those systems. + +@item +If @file{nlist.h} is found, define @code{NLIST_STRUCT}. + +@item +If @samp{struct nlist} has an @samp{n_un.n_name} member, define +@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol +@code{NLIST_NAME_UNION} is still defined, but do not depend upon it. + +@item +Programs may need to be installed setgid (or setuid) for +@code{getloadavg} to work. In this case, define +@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID} +to @samp{true} (and otherwise to @samp{false}), and set +@code{KMEM_GROUP} to the name of the group that should own the installed +program. +@end enumerate +@end defmac + +@defmac AC_FUNC_GETMNTENT +@maindex FUNC_GETMNTENT +@cvindex HAVE_GETMNTENT +Check for @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen} +libraries, for Irix 4, PTX, and Unixware, respectively. Then, if +@code{getmntent} is available, define @code{HAVE_GETMNTENT}. +@end defmac + +@defmac AC_FUNC_GETPGRP +@maindex FUNC_GETPGRP +@cvindex GETPGRP_VOID +If @code{getpgrp} takes no argument (the @sc{posix.1} version), define +@code{GETPGRP_VOID}. Otherwise, it is the @sc{bsd} version, which takes +a process ID as an argument. This macro does not check whether +@code{getpgrp} exists at all; if you need to work in that situation, +first call @code{AC_CHECK_FUNC} for @code{getpgrp}. +@end defmac + +@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK +@maindex FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK +@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK +If @file{link} is a symbolic link, then @code{lstat} should treat +@file{link/} the same as @file{link/.}. However, many older +@code{lstat} implementations incorrectly ignore trailing slashes. + +It is safe to assume that if @code{lstat} incorrectly ignores +trailing slashes, then other symbolic-link-aware functions like +@code{unlink} and @code{unlink} also incorrectly ignore trailing slashes. + +If @code{lstat} behaves properly, define +@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an +@code{AC_LIBOBJ} replacement of @code{lstat}. +@end defmac + +@defmac AC_FUNC_MALLOC +@maindex FUNC_MALLOC +If the @code{malloc} works correctly (@samp{malloc (0)} returns a valid +pointer), define @code{HAVE_MALLOC}. +@end defmac + +@defmac AC_FUNC_MEMCMP +@maindex FUNC_MEMCMP +@ovindex LIBOBJS +If the @code{memcmp} function is not available, or does not work on +8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16 +bytes or more and with at least one buffer not starting on a 4-byte +boundary (such as the one on NeXT x86 OpenStep), require an +@code{AC_LIBOBJ} replacement for @samp{memcmp}. +@end defmac + +@defmac AC_FUNC_MKTIME +@maindex FUNC_MKTIME +@ovindex LIBOBJS +If the @code{mktime} function is not available, or does not work +correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}. +@end defmac + +@defmac AC_FUNC_MMAP +@maindex FUNC_MMAP +@cvindex HAVE_MMAP +If the @code{mmap} function exists and works correctly, define +@code{HAVE_MMAP}. Only checks private fixed mapping of already-mapped +memory. +@end defmac + +@defmac AC_FUNC_OBSTACK +@maindex FUNC_OBSTACK +@cvindex HAVE_OBSTACK +@cindex obstack +If the obstacks are found, define @code{HAVE_OBSTACK}, else require an +@code{AC_LIBOBJ} replacement for @samp{obstack}. +@end defmac + +@defmac AC_FUNC_SELECT_ARGTYPES +@maindex FUNC_SELECT_ARGTYPES +@cvindex SELECT_TYPE_ARG1 +@cvindex SELECT_TYPE_ARG234 +@cvindex SELECT_TYPE_ARG5 +Determines the correct type to be passed for each of the +@code{select} function's arguments, and defines those types +in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and +@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults +to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *}, +and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}. +@end defmac + +@defmac AC_FUNC_SETPGRP +@maindex FUNC_SETPGRP +@cvindex SETPGRP_VOID +If @code{setpgrp} takes no argument (the @sc{posix.1} version), define +@code{SETPGRP_VOID}. Otherwise, it is the @sc{bsd} version, which takes +two process IDs as arguments. This macro does not check whether +@code{setpgrp} exists at all; if you need to work in that situation, +first call @code{AC_CHECK_FUNC} for @code{setpgrp}. +@end defmac + +@defmac AC_FUNC_STAT +@defmacx AC_FUNC_LSTAT +@maindex FUNC_STAT +@maindex FUNC_LSTAT +@cvindex HAVE_STAT_EMPTY_STRING_BUG +@cvindex HAVE_LSTAT_EMPTY_STRING_BUG +Determine whether @code{stat} or @code{lstat} have the bug that it +succeeds when given the zero-length file name argument. The @code{stat} +and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do +this. + +If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or +@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ} +replacement of it. +@end defmac + +@defmac AC_FUNC_SETVBUF_REVERSED +@maindex FUNC_SETVBUF_REVERSED +@cvindex SETVBUF_REVERSED +If @code{setvbuf} takes the buffering type as its second argument and +the buffer pointer as the third, instead of the other way around, define +@code{SETVBUF_REVERSED}. +@end defmac + +@defmac AC_FUNC_STRCOLL +@maindex FUNC_STRCOLL +@cvindex HAVE_STRCOLL +If the @code{strcoll} function exists and works correctly, define +@code{HAVE_STRCOLL}. This does a bit more than +@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect +definitions of @code{strcoll} that should not be used. +@end defmac + +@defmac AC_FUNC_STRTOD +@maindex FUNC_STRTOD +@ovindex POW_LIB +If the @code{strtod} function does not exist or doesn't work correctly, +ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case, +because @file{strtod.c} is likely to need @samp{pow}, set the output +variable @code{POW_LIB} to the extra library needed. +@end defmac + +@defmac AC_FUNC_STRERROR_R +@maindex FUNC_STRERROR_R +@cvindex HAVE_STRERROR_R +@cvindex HAVE_WORKING_STRERROR_R +If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}. If +its implementation correctly returns a @code{char *}, define +@code{HAVE_WORKING_STRERROR_R}. On at least DEC UNIX 4.0[A-D] and HP-UX +B.10.20, @code{strerror_r} returns @code{int}. Actually, this tests +only whether it returns a scalar or an array, but that should be enough. +This is used by the common @file{error.c}. +@end defmac + +@defmac AC_FUNC_STRFTIME +@maindex FUNC_STRFTIME +@cvindex HAVE_STRFTIME +Check for @code{strftime} in the @file{intl} library, for SCO @sc{unix}. +Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}. +@end defmac + +@defmac AC_FUNC_UTIME_NULL +@maindex FUNC_UTIME_NULL +@cvindex HAVE_UTIME_NULL +If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to +the present, define @code{HAVE_UTIME_NULL}. +@end defmac + +@defmac AC_FUNC_VPRINTF +@maindex FUNC_VPRINTF +@cvindex HAVE_VPRINTF +@cvindex HAVE_DOPRNT +If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if +@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf} +is available, you may assume that @code{vfprintf} and @code{vsprintf} +are also available.) +@end defmac + +@node Generic Functions, , Particular Functions, Library Functions +@subsection Generic Function Checks + +These macros are used to find functions not covered by the ``particular'' +test macros. If the functions might be in libraries other than the +default C library, first call @code{AC_CHECK_LIB} for those libraries. +If you need to check the behavior of a function as well as find out +whether it is present, you have to write your own test for +it (@pxref{Writing Tests}). + +@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex CHECK_FUNC +If C function @var{function} is available, run shell commands +@var{action-if-found}, otherwise @var{action-if-not-found}. If you just +want to define a symbol if the function is available, consider using +@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C +linkage even when @code{AC_LANG(C++)} has been called, since C is more +standardized than C++. (@pxref{Language Choice}, for more information +about selecting the language for checks.) +@end defmac + +@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex CHECK_FUNCS +@cvindex HAVE_@var{function} +For each @var{function} in the whitespace-separated argument list, +define @code{HAVE_@var{function}} (in all capitals) if it is available. +If @var{action-if-found} is given, it is additional shell code to +execute when one of the functions is found. You can give it a value of +@samp{break} to break out of the loop on the first match. If +@var{action-if-not-found} is given, it is executed when one of the +functions is not found. +@end defmac + +Autoconf follows a philosophy that was formed over the years by those +who have struggled for portability: isolate the portability issues in +specific files, and then program as if you were in a @sc{posix} +environment. Some functions may be missing or unfixable, and your +package must be ready to replace them. + +Use the first three of the following macros to specify a function to be +replaced, and the last one (@code{AC_REPLACE_FUNCS}) to check for and +replace the function if needed. + +@defmac AC_LIBOBJ (@var{function}) +@maindex LIBOBJ +@ovindex LIBOBJS +Specify that @samp{@var{function}.c} must be included in the executables +to replace a missing or broken implementation of @var{function}. + +Technically, it adds @samp{@var{function}.$ac_objext} to the output +variable @code{LIBOBJS} and calls @code{AC_LIBSOURCE} for +@samp{@var{function}.c}. You should not directly change @code{LIBOBJS}, +since this is not traceable. +@end defmac + +@defmac AC_LIBSOURCE (@var{file}) +@maindex LIBSOURCE +Specify that @var{file} might be needed to compile the project. If you +need to know what files might be needed by a @file{configure.ac}, you +should trace @code{AC_LIBSOURCE}. @var{file} must be a literal. + +This macro is called automatically from @code{AC_LIBOBJ}, but you must +call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In +that case, since shell variables cannot be traced statically, you must +pass to @code{AC_LIBSOURCE} any possible files that the shell variable +might cause @code{AC_LIBOBJ} to need. For example, if you want to pass +a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either +@code{"foo"} or @code{"bar"}, you should do: + +@example +AC_LIBSOURCE(foo.c) +AC_LIBSOURCE(bar.c) +AC_LIBOBJ($foo_or_bar) +@end example + +@noindent +There is usually a way to avoid this, however, and you are encouraged to +simply call @code{AC_LIBOBJ} with literal arguments. + +Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with +slightly different semantics: the old macro took the function name, +e.g. @code{foo}, as its argument rather than the file name. +@end defmac + +@defmac AC_LIBSOURCES (@var{files}) +@maindex LIBSOURCES +Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a +comma-separated M4 list. Thus, the above example might be rewritten: + +@example +AC_LIBSOURCES([foo.c, bar.c]) +AC_LIBOBJ($foo_or_bar) +@end example +@end defmac + +@defmac AC_REPLACE_FUNCS (@var{function}@dots{}) +@maindex REPLACE_FUNCS +@ovindex LIBOBJS +Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as +@var{action-if-not-found}. You can declare your replacement function by +enclosing the prototype in @samp{#if !HAVE_@var{function}}. If the +system has the function, it probably declares it in a header file you +should be including, so you shouldn't redeclare it lest your declaration +conflict. +@end defmac + +@node Header Files, Declarations, Library Functions, Existing Tests +@section Header Files +@cindex Header, checking + +The following macros check for the presence of certain C header files. +If there is no macro specifically defined to check for a header file you need, +and you don't need to check for any special properties of +it, then you can use one of the general header-file check macros. + +@menu +* Particular Headers:: Special handling to find certain headers +* Generic Headers:: How to find other headers +@end menu + +@node Particular Headers, Generic Headers, Header Files, Header Files +@subsection Particular Header Checks + +These macros check for particular system header files---whether they +exist, and in some cases whether they declare certain symbols. + +@defmac AC_HEADER_DIRENT +@maindex HEADER_DIRENT +@cvindex HAVE_DIRENT_H +@cvindex HAVE_NDIR_H +@cvindex HAVE_SYS_DIR_H +@cvindex HAVE_SYS_NDIR_H +Check for the following header files. For the first one that is +found and defines @samp{DIR}, define the listed C preprocessor macro: + +@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}} +@item @file{dirent.h} @tab @code{HAVE_DIRENT_H} +@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H} +@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H} +@item @file{ndir.h} @tab @code{HAVE_NDIR_H} +@end multitable + +The directory-library declarations in your source code should look +something like the following: + +@example +@group +#if HAVE_DIRENT_H +# include <dirent.h> +# define NAMLEN(dirent) strlen((dirent)->d_name) +#else +# define dirent direct +# define NAMLEN(dirent) (dirent)->d_namlen +# if HAVE_SYS_NDIR_H +# include <sys/ndir.h> +# endif +# if HAVE_SYS_DIR_H +# include <sys/dir.h> +# endif +# if HAVE_NDIR_H +# include <ndir.h> +# endif +#endif +@end group +@end example + +Using the above declarations, the program would declare variables to be +of type @code{struct dirent}, not @code{struct direct}, and would access +the length of a directory entry name by passing a pointer to a +@code{struct dirent} to the @code{NAMLEN} macro. + +This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries. +@end defmac + +@defmac AC_HEADER_MAJOR +@maindex HEADER_MAJOR +@cvindex MAJOR_IN_MKDEV +@cvindex MAJOR_IN_SYSMACROS +If @file{sys/types.h} does not define @code{major}, @code{minor}, and +@code{makedev}, but @file{sys/mkdev.h} does, define +@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define +@code{MAJOR_IN_SYSMACROS}. +@end defmac + + +@defmac AC_HEADER_STAT +@maindex HEADER_STAT +@maindex STAT_MACROS_BROKEN +If the macros @code{S_ISDIR}, @code{S_ISREG} et al. defined in +@file{sys/stat.h} do not work properly (returning false positives), +define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV, +Amdahl UTS and Motorola System V/88. +@end defmac + + +@defmac AC_HEADER_STDC +@maindex HEADER_STDC +@cvindex STDC_HEADERS +Define @code{STDC_HEADERS} if the system has @sc{ansi} C header files. +Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h}, +@file{string.h}, and @file{float.h}; if the system has those, it +probably has the rest of the @sc{ansi} C header files. This macro also +checks whether @file{string.h} declares @code{memchr} (and thus +presumably the other @code{mem} functions), whether @file{stdlib.h} +declare @code{free} (and thus presumably @code{malloc} and other related +functions), and whether the @file{ctype.h} macros work on characters +with the high bit set, as @sc{ansi} C requires. + +Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether +the system has @sc{ansi}-compliant header files (and probably C library +functions) because many systems that have GCC do not have @sc{ansi} C +header files. + +On systems without @sc{ansi} C headers, there is so much variation that +it is probably easier to declare the functions you use than to figure +out exactly what the system header files declare. Some systems contain +a mix of functions @sc{ansi} and @sc{bsd}; some are mostly @sc{ansi} but +lack @samp{memmove}; some define the @sc{bsd} functions as macros in +@file{string.h} or @file{strings.h}; some have only the @sc{bsd} +functions but @file{string.h}; some declare the memory functions in +@file{memory.h}, some in @file{string.h}; etc. It is probably +sufficient to check for one string function and one memory function; if +the library has the @sc{ansi} versions of those then it probably has +most of the others. If you put the following in @file{configure.ac}: + +@example +AC_HEADER_STDC +AC_CHECK_FUNCS(strchr memcpy) +@end example + +@noindent +then, in your code, you can put declarations like this: + +@example +@group +#if STDC_HEADERS +# include <string.h> +#else +# if !HAVE_STRCHR +# define strchr index +# define strrchr rindex +# endif +char *strchr (), *strrchr (); +# if !HAVE_MEMCPY +# define memcpy(d, s, n) bcopy ((s), (d), (n)) +# define memmove(d, s, n) bcopy ((s), (d), (n)) +# endif +#endif +@end group +@end example + +@noindent +If you use a function like @code{memchr}, @code{memset}, @code{strtok}, +or @code{strspn}, which have no @sc{bsd} equivalent, then macros won't +suffice; you must provide an implementation of each function. An easy +way to incorporate your implementations only when needed (since the ones +in system C libraries may be hand optimized) is to, taking @code{memchr} +for example, put it in @file{memchr.c} and use +@samp{AC_REPLACE_FUNCS(memchr)}. +@end defmac + +@defmac AC_HEADER_SYS_WAIT +@maindex HEADER_SYS_WAIT +@cvindex HAVE_SYS_WAIT_H +If @file{sys/wait.h} exists and is compatible with @sc{posix.1}, define +@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h} +does not exist, or if it uses the old @sc{bsd} @code{union wait} instead +of @code{int} to store a status value. If @file{sys/wait.h} is not +@sc{posix.1} compatible, then instead of including it, define the +@sc{posix.1} macros with their usual interpretations. Here is an +example: + +@example +@group +#include <sys/types.h> +#if HAVE_SYS_WAIT_H +# include <sys/wait.h> +#endif +#ifndef WEXITSTATUS +# define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8) +#endif +#ifndef WIFEXITED +# define WIFEXITED(stat_val) (((stat_val) & 255) == 0) +#endif +@end group +@end example +@end defmac + +@cvindex _POSIX_VERSION +@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on +@sc{posix.1} systems. If there is no @file{unistd.h}, it is definitely +not a @sc{posix.1} system. However, some non-@sc{posix.1} systems do +have @file{unistd.h}. + +The way to check if the system supports @sc{posix.1} is: + +@example +@group +#if HAVE_UNISTD_H +# include <sys/types.h> +# include <unistd.h> +#endif + +#ifdef _POSIX_VERSION +/* Code for POSIX.1 systems. */ +#endif +@end group +@end example + +@defmac AC_HEADER_TIME +@maindex HEADER_TIME +@cvindex TIME_WITH_SYS_TIME +If a program may include both @file{time.h} and @file{sys/time.h}, +define @code{TIME_WITH_SYS_TIME}. On some older systems, +@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not +protected against multiple inclusion, so programs should not explicitly +include both files. This macro is useful in programs that use, for +example, @code{struct timeval} or @code{struct timezone} as well as +@code{struct tm}. It is best used in conjunction with +@code{HAVE_SYS_TIME_H}, which can be checked for using +@code{AC_CHECK_HEADERS(sys/time.h)}. + +@example +@group +#if TIME_WITH_SYS_TIME +# include <sys/time.h> +# include <time.h> +#else +# if HAVE_SYS_TIME_H +# include <sys/time.h> +# else +# include <time.h> +# endif +#endif +@end group +@end example +@end defmac + + +@defmac AC_HEADER_TIOCGWINSZ +@maindex HEADER_TIOCGWINSZ +@cvindex GWINSZ_IN_SYS_IOCTL +@c FIXME: I need clarifications from Jim. +If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then +define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be +found in @file{<termios.h>}. + +Use: + +@example +@group +#if HAVE_TERMIOS_H +# include <termios.h> +#endif + +#if GWINSZ_IN_SYS_IOCTL +# include <sys/ioctl.h> +#endif +@end group +@end example +@end defmac + +@node Generic Headers, , Particular Headers, Header Files +@subsection Generic Header Checks + +These macros are used to find system header files not covered by the +``particular'' test macros. If you need to check the contents of a header +as well as find out whether it is present, you have to write your own +test for it (@pxref{Writing Tests}). + +@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_HEADER +If the system header file @var{header-file} is usable, execute shell +commands @var{action-if-found}, otherwise execute +@var{action-if-not-found}. If you just want to define a symbol if the +header file is available, consider using @code{AC_CHECK_HEADERS} +instead. + +The meaning of ``usable'' depends upon the content of @var{includes}: + +@table @asis +@item if @var{includes} is empty +check whether + +@example +@var{header-file} +@end example + +@noindent +can be @emph{preprocessed} without error. + +@item if @var{include} is set +Check whether + +@example +@var{includes} +#include <@var{header-file}> +@end example + +@noindent +can be @emph{compiled} without error. You may use +@code{AC_CHECK_HEADER} (and @code{AC_CHECK_HEADERS}) to check whether +two headers are compatible. +@end table + +You may pass any kind of dummy content for @var{includes}, such as a +single space, a comment, to check whether @var{header-file} compiles +with success. +@end defmac + +@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_HEADERS +@cvindex HAVE_@var{header} +For each given system header file @var{header-file} in the +whitespace-separated argument list that exists, define +@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found} +is given, it is additional shell code to execute when one of the header +files is found. You can give it a value of @samp{break} to break out of +the loop on the first match. If @var{action-if-not-found} is given, it +is executed when one of the header files is not found. + +Be sure to read the documentation of @code{AC_CHECK_HEADER} to +understand the influence of @var{includes}. +@end defmac + +@node Declarations, Structures, Header Files, Existing Tests +@section Declarations +@cindex Declaration, checking + +The following macros check for the declaration of variables and +functions. If there is no macro specifically defined to check for a +symbol you need, then you can use the general macros (@pxref{Generic +Declarations}) or, for more complex tests, you may use +@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}). + +@menu +* Particular Declarations:: Macros to check for certain declarations +* Generic Declarations:: How to find other declarations +@end menu + +@node Particular Declarations, Generic Declarations, Declarations, Declarations +@subsection Particular Declaration Checks + +The following macros check for certain declarations. + +@defmac AC_DECL_SYS_SIGLIST +@maindex DECL_SYS_SIGLIST +@cvindex SYS_SIGLIST_DECLARED +Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist} +is declared in a system header file, either @file{signal.h} or +@file{unistd.h}. +@end defmac + +@node Generic Declarations, , Particular Declarations, Declarations +@subsection Generic Declaration Checks + +These macros are used to find declarations not covered by the ``particular'' +test macros. + +@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_DECL +If @var{symbol} (a function or a variable) is not declared in +@var{includes} and a declaration is needed, run the shell commands +@var{action-if-not-found}, otherwise @var{action-if-found}. If no +@var{includes} are specified, the default includes are used +(@pxref{Default Includes}). + +This macro actually tests whether it is valid to use @var{symbol} as an +r-value, not if it is really declared, because it is much safer to avoid +introducing extra declarations when they are not needed. +@end defmac + +@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_DECLS +@cvindex HAVE_DECL_@var{symbol} +For each of the @var{symbols} (@emph{comma}-separated list), define +@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if +@var{symbol} is declared, otherwise to @samp{0}. If +@var{action-if-not-found} is given, it is additional shell code to +execute when one of the function declarations is needed, otherwise +@var{action-if-found} is executed. + +This macro uses an m4 list as first argument: +@example +AC_CHECK_DECLS(strdup) +AC_CHECK_DECLS([strlen]) +AC_CHECK_DECLS([malloc, realloc, calloc, free]) +@end example + +Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not +declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead +of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are +@emph{sure} that the check was performed, use +@code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf: + +@example +#if !HAVE_DECL_SYMBOL +extern char *symbol; +#endif +@end example + +@noindent +If the test may have not been performed, however, because it is safer +@emph{not} to declare a symbol than to use a declaration that conflicts +with the system's one, you should use: + +@example +#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC +char *malloc (size_t *s); +#endif +@end example + +@noindent +You fall into the second category only in extreme situations: either +your files may be used without being configured, or they are used during +the configuration. In most cases the traditional approach is enough. +@end defmac + + +@node Structures, Types, Declarations, Existing Tests +@section Structures +@cindex Structure, checking + +The following macros check for the presence of certain members in C +structures. If there is no macro specifically defined to check for a +member you need, then you can use the general structure-member macro +(@pxref{Generic Structures}) or, for more complex tests, you may use +@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}). + +@menu +* Particular Structures:: Macros to check for certain structure members +* Generic Structures:: How to find other structure members +@end menu + +@node Particular Structures, Generic Structures, Structures, Structures +@subsection Particular Structure Checks + +The following macros check for certain structures or structure members. + +@defmac AC_STRUCT_ST_BLKSIZE +@maindex STRUCT_ST_BLKSIZE +@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE +@cvindex HAVE_ST_BLKSIZE +If @code{struct stat} contains an @code{st_blksize} member, define +@code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name, +@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in +the future. This macro is obsoleted, and should be replaced by + +@example +AC_CHECK_MEMBERS([struct stat.st_blksize]) +@end example +@end defmac + +@defmac AC_STRUCT_ST_BLOCKS +@maindex STRUCT_ST_BLOCKS +@cvindex HAVE_STRUCT_STAT_ST_BLOCKS +@cvindex HAVE_ST_BLOCKS +@ovindex LIBOBJS +If @code{struct stat} contains an @code{st_blocks} member, define +@code{HAVE_STRUCT STAT_ST_BLOCKS}. Otherwise, require an +@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name, +@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the +future. +@end defmac + +@defmac AC_STRUCT_ST_RDEV +@maindex STRUCT_ST_RDEV +@cvindex HAVE_ST_RDEV +@cvindex HAVE_STRUCT_STAT_ST_RDEV +If @code{struct stat} contains an @code{st_rdev} member, define +@code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro, +@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported +in the future. Actually, even the new macro is obsolete, and should be +replaced by: +@example +AC_CHECK_MEMBERS([struct stat.st_rdev]) +@end example +@end defmac + +@defmac AC_STRUCT_TM +@maindex STRUCT_TM +@cvindex TM_IN_SYS_TIME +If @file{time.h} does not define @code{struct tm}, define +@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h} +had better define @code{struct tm}. +@end defmac + +@defmac AC_STRUCT_TIMEZONE +@maindex STRUCT_TIMEZONE +@cvindex HAVE_TM_ZONE +@cvindex HAVE_TZNAME +Figure out how to get the current timezone. If @code{struct tm} has a +@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the +obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array +@code{tzname} is found, define @code{HAVE_TZNAME}. +@end defmac + +@node Generic Structures, , Particular Structures, Structures +@subsection Generic Structure Checks + +These macros are used to find structure members not covered by the +``particular'' test macros. + +@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_MEMBER +Check whether @var{member} is a member of the aggregate @var{aggregate}. +If no @var{includes} are specified, the default includes are used +(@pxref{Default Includes}). + +@example +AC_CHECK_MEMBER(struct passwd.pw_gecos,, + [AC_MSG_ERROR([We need `passwd.pw_gecos'!])], + [#include <pwd.h>]) +@end example + +You can use this macro for sub-members: + +@example +AC_CHECK_MEMBER(struct top.middle.bot) +@end example +@end defmac + +@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_MEMBERS +Check for the existence of each @samp{@var{aggregate}.@var{member}} of +@var{members} using the previous macro. When @var{member} belongs to +@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all +capitals, with spaces and dots replaced by underscores). + +This macro uses m4 lists: +@example +AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) +@end example +@end defmac + + +@node Types, Compilers and Preprocessors, Structures, Existing Tests +@section Types + +The following macros check for C types, either builtin or typedefs. If +there is no macro specifically defined to check for a type you need, and +you don't need to check for any special properties of it, then you can +use a general type-check macro. + +@menu +* Particular Types:: Special handling to find certain types +* Generic Types:: How to find other types +@end menu + +@node Particular Types, Generic Types, Types, Types +@subsection Particular Type Checks + +These macros check for particular C types in @file{sys/types.h}, +@file{stdlib.h} and others, if they exist. + +@defmac AC_TYPE_GETGROUPS +@maindex TYPE_GETGROUPS +@cvindex GETGROUPS_T +Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int} +is the base type of the array argument to @code{getgroups}. +@end defmac + +@defmac AC_TYPE_MODE_T +@maindex TYPE_MODE_T +@cvindex mode_t +Equivalent to @samp{AC_CHECK_TYPE(mode_t, int)}. +@end defmac + +@defmac AC_TYPE_OFF_T +@maindex TYPE_OFF_T +@cvindex off_t +Equivalent to @samp{AC_CHECK_TYPE(off_t, long)}. +@end defmac + +@defmac AC_TYPE_PID_T +@maindex TYPE_PID_T +@cvindex pid_t +Equivalent to @samp{AC_CHECK_TYPE(pid_t, int)}. +@end defmac + +@defmac AC_TYPE_SIGNAL +@maindex TYPE_SIGNAL +@cvindex RETSIGTYPE +If @file{signal.h} declares @code{signal} as returning a pointer to a +function returning @code{void}, define @code{RETSIGTYPE} to be +@code{void}; otherwise, define it to be @code{int}. + +Define signal handlers as returning type @code{RETSIGTYPE}: + +@example +@group +RETSIGTYPE +hup_handler () +@{ +@dots{} +@} +@end group +@end example +@end defmac + +@defmac AC_TYPE_SIZE_T +@maindex TYPE_SIZE_T +@cvindex size_t +Equivalent to @samp{AC_CHECK_TYPE(size_t, unsigned)}. +@end defmac + +@defmac AC_TYPE_UID_T +@maindex TYPE_UID_T +@cvindex uid_t +@cvindex gid_t +If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and +@code{gid_t} to be @code{int}. +@end defmac + +@node Generic Types, , Particular Types, Types +@subsection Generic Type Checks + +These macros are used to check for types not covered by the ``particular'' +test macros. + +@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_TYPE +Check whether @var{type} is defined. It may be a compiler builtin type +or defined by the @ovar{includes} (@pxref{Default Includes}). +@end defmac + + +@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_TYPES +For each @var{type} of the @var{types} that is defined, define +@code{HAVE_@var{type}} (in all capitals). If no @var{includes} are +specified, the default includes are used (@pxref{Default Includes}). If +@var{action-if-found} is given, it is additional shell code to execute +when one of the types is found. If @var{action-if-not-found} is given, +it is executed when one of the types is not found. + +This macro uses m4 lists: +@example +AC_CHECK_TYPES(ptrdiff_t) +AC_CHECK_TYPES([unsigned long long, uintmax_t]) +@end example + +@end defmac + +Autoconf, up to 2.13, used to provide to another version of +@code{AC_CHECK_TYPE}, broken by design. In order to keep backward +compatibility, a simple heuristics, quite safe but not totally, is +implemented. In case of doubt, read the documentation of the former +@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}. + + +@node Compilers and Preprocessors, System Services, Types, Existing Tests +@section Compilers and Preprocessors + +@ovindex EXEEXT +All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX}, +@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on +the output of the compiler, typically to the empty string if Unix and +@samp{.exe} if Win32 or OS/2. + +@ovindex OBJEXT +They also define the output variable @code{OBJEXT} based on the +output of the compiler, after .c files have been excluded, typically +to @samp{o} if Unix, @samp{obj} if Win32. + +If the compiler being used does not produce executables, they fail. If +the executables can't be run, and cross-compilation is not enabled, they +fail too. @xref{Manual Configuration}, for more on support for cross +compiling. + +@menu +* Generic Compiler Characteristics:: Language independent tests +* C Compiler:: Checking its characteristics +* C++ Compiler:: Likewise +* Fortran 77 Compiler:: Likewise +@end menu + +@node Generic Compiler Characteristics, C Compiler, Compilers and Preprocessors, Compilers and Preprocessors +@subsection Generic Compiler Characteristics + +@defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @ovar{includes}) +@maindex CHECK_SIZEOF +Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the +size in bytes of @var{type}. If @samp{type} is unknown, it gets a size +of 0. If no @var{includes} are specified, the default includes are used +(@pxref{Default Includes}). If you provide @var{include}, make sure to +include @file{stdio.h} which is required for this macro to run. + +This macro now works even when cross-compiling. The @var{unused} +argument was used when cross-compiling. + +For example, the call + +@example +AC_CHECK_SIZEOF(int *) +@end example + +@noindent +defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems. +@end defmac + + +@node C Compiler, C++ Compiler, Generic Compiler Characteristics, Compilers and Preprocessors +@subsection C Compiler Characteristics + +@defmac AC_PROG_CC (@ovar{compiler-search-list}) +@maindex PROG_CC +@ovindex CC +@ovindex CFLAGS +Determine a C compiler to use. If @code{CC} is not already set in the +environment, check for @code{gcc} and @code{cc}, then for other C +compilers. Set output variable @code{CC} to the name of the compiler +found. + +This macro may, however, be invoked with an optional first argument +which, if specified, must be a space separated list of C compilers to +search for. This just gives the user an opportunity to specify an +alternative search list for the C compiler. For example, if you didn't +like the default order, then you could invoke @code{AC_PROG_CC} like +this: + +@example +AC_PROG_CC(cl egcs gcc cc) +@end example + +If using the @sc{gnu} C compiler, set shell variable @code{GCC} to +@samp{yes}. If output variable @code{CFLAGS} was not already set, set +it to @option{-g -O2} for the @sc{gnu} C compiler (@option{-O2} on systems +where GCC does not accept @option{-g}), or @option{-g} for other compilers. +@end defmac + +@defmac AC_PROG_CC_C_O +@maindex PROG_CC_C_O +@cvindex NO_MINUS_C_MINUS_O +If the C compiler does not accept the @option{-c} and @option{-o} options +simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually +tests both the compiler found by @code{AC_PROG_CC}, and, if different, +the first @code{cc} in the path. The test fails if one fails. This +macro was created for @sc{gnu} Make to choose the default C compilation +rule. +@end defmac + +@defmac AC_PROG_CC_STDC +@maindex PROG_CC_STDC +@ovindex CC +If the C compiler is not in @sc{ansi} C mode by default, try to add an +option to output variable @code{CC} to make it so. This macro tries +various options that select @sc{ansi} C on some system or another. It +considers the compiler to be in @sc{ansi} C mode if it handles function +prototypes correctly. + +If you use this macro, you should check after calling it whether the C +compiler has been set to accept @sc{ansi} C; if not, the shell variable +@code{ac_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source +code in @sc{ansi} C, you can make an un-@sc{ansi}fied copy of it by +using the program @code{ansi2knr}, which comes with Automake. +@end defmac + + +@defmac AC_PROG_CPP +@maindex PROG_CPP +@ovindex CPP +Set output variable @code{CPP} to a command that runs the +C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used. +It is only portable to run @code{CPP} on files with a @file{.c} +extension. + +If the current language is C (@pxref{Language Choice}), many of the +specific test macros use the value of @code{CPP} indirectly by calling +@code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, @code{AC_EGREP_HEADER}, or +@code{AC_EGREP_CPP}. + +Some preprocessors don't indicate missing include files by the error +status. For such preprocessors an internal variable is set that causes +other macros to check the standard error from the preprocessor and +consider the test failed if any warnings have been reported. +@end defmac + + +The following macros check for C compiler or machine architecture +features. To check for characteristics not listed here, use +@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}) or @code{AC_TRY_RUN} +(@pxref{Run Time}) + +@defmac AC_C_BIGENDIAN +@maindex C_BIGENDIAN +@cvindex WORDS_BIGENDIAN +@cindex Endianness +If words are stored with the most significant byte first (like Motorola +and SPARC, but not Intel and VAX, CPUs), define @code{WORDS_BIGENDIAN}. +@end defmac + + +@defmac AC_C_CONST +@maindex C_CONST +@cvindex const +If the C compiler does not fully support the @sc{ansi} C qualifier +@code{const}, define @code{const} to be empty. Some C compilers that do +not define @code{__STDC__} do support @code{const}; some compilers that +define @code{__STDC__} do not completely support @code{const}. Programs +can simply use @code{const} as if every C compiler supported it; for +those that don't, the @file{Makefile} or configuration header file will +define it as empty. + +Occasionally installers use a C++ compiler to compile C code, typically +because they lack a C compiler. This causes problems with @code{const}, +because C and C++ treat @code{const} differently. For example: + +@example +const int foo; +@end example + +@noindent +is valid in C but not in C++. These differences unfortunately cannot be +papered over by defining @code{const} to be empty. + +If @code{autoconf} detects this situation, it leaves @code{const} alone, +as this generally yields better results in practice. However, using a +C++ compiler to compile C code is not recommended or supported, and +installers who run into trouble in this area should get a C compiler +like GCC to compile their C code. +@end defmac + +@defmac AC_C_VOLATILE +@maindex C_VOLATILE +@cvindex volatile +If the C compiler does not understand the keyword @code{volatile}, +define @code{volatile} to be empty. Programs can simply use +@code{volatile} as if every C compiler supported it; for those that do +not, the @file{Makefile} or configuration header will define it as +empty. + +If the correctness of your program depends on the semantics of +@code{volatile}, simply defining it to be empty does, in a sense, break +your code. However, given that the compiler does not support +@code{volatile}, you are at its mercy anyway. At least your +program will compile, when it wouldn't before. + +In general, the @code{volatile} keyword is a feature of @sc{ansi} C, so +you might expect that @code{volatile} is available only when +@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does +support volatile, but does not defined @code{__STDC__}. +@end defmac + +@defmac AC_C_INLINE +@maindex C_INLINE +@cvindex inline +If the C compiler supports the keyword @code{inline}, do nothing. +Otherwise define @code{inline} to @code{__inline__} or @code{__inline} +if it accepts one of those, otherwise define @code{inline} to be empty. +@end defmac + +@defmac AC_C_CHAR_UNSIGNED +@maindex C_CHAR_UNSIGNED +@cvindex __CHAR_UNSIGNED__ +If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__}, +unless the C compiler predefines it. +@end defmac + +@defmac AC_C_LONG_DOUBLE +@maindex C_LONG_DOUBLE +@cvindex HAVE_LONG_DOUBLE +If the C compiler supports the @code{long double} type, define +@code{HAVE_LONG_DOUBLE}. Some C compilers that do not define +@code{__STDC__} do support the @code{long double} type; some compilers +that define @code{__STDC__} do not support @code{long double}. +@end defmac + +@defmac AC_C_STRINGIZE +@maindex C_STRINGIZE +@cvindex HAVE_STRINGIZE +If the C preprocessor supports the stringizing operator, define +@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is +found in macros such as this: + +@example +#define x(y) #y +@end example +@end defmac + +@defmac AC_C_PROTOTYPES +@maindex C_PROTOTYPES +@cvindex PROTOTYPES +@cvindex PARAMS +Check to see if function prototypes are understood by the compiler. If +so, define @samp{PROTOTYPES}. In the case the compiler does not handle +prototypes, you should use @code{ansi2knr}, which comes with the +Automake distribution, to unprotoize function definitions. For +function prototypes, you should first define @code{PARAMS}: + +@example +#ifndef PARAMS +# if PROTOTYPES +# define PARAMS(protos) protos +# else /* no PROTOTYPES */ +# define PARAMS(protos) () +# endif /* no PROTOTYPES */ +#endif +@end example + +@noindent +then use it this way: + +@example +size_t my_strlen PARAMS ((const char *)); +@end example +@end defmac + +@defmac AC_PROG_GCC_TRADITIONAL +@maindex PROG_GCC_TRADITIONAL +@ovindex CC +Add @option{-traditional} to output variable @code{CC} if using the +@sc{gnu} C compiler and @code{ioctl} does not work properly without +@option{-traditional}. That usually happens when the fixed header files +have not been installed on an old system. Since recent versions of the +@sc{gnu} C compiler fix the header files automatically when installed, +this is becoming a less prevalent problem. +@end defmac + + +@node C++ Compiler, Fortran 77 Compiler, C Compiler, Compilers and Preprocessors +@subsection C++ Compiler Characteristics + + +@defmac AC_PROG_CXX (@ovar{compiler-search-list}) +@maindex PROG_CXX +@ovindex CXX +@ovindex CXXFLAGS +Determine a C++ compiler to use. Check if the environment variable +@code{CXX} or @code{CCC} (in that order) is set; if so, then set output +variable @code{CXX} to its value. + +Otherwise, if the macro is invoked without an argument, then search for +a C++ compiler under the likely names (first @code{g++} and @code{c++} +then other names). If none of those checks succeed, then as a last +resort set @code{CXX} to @code{g++}. + +This macro may, however, be invoked with an optional first argument +which, if specified, must be a space separated list of C++ compilers to +search for. This just gives the user an opportunity to specify an +alternative search list for the C++ compiler. For example, if you +didn't like the default order, then you could invoke @code{AC_PROG_CXX} +like this: + +@example +AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc) +@end example + +If using the @sc{gnu} C++ compiler, set shell variable @code{GXX} to +@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set +it to @option{-g -O2} for the @sc{gnu} C++ compiler (@option{-O2} on +systems where G++ does not accept @option{-g}), or @option{-g} for other +compilers. +@end defmac + +@defmac AC_PROG_CXXCPP +@maindex PROG_CXXCPP +@ovindex CXXCPP +Set output variable @code{CXXCPP} to a command that runs the C++ +preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used. +It is only portable to run @code{CXXCPP} on files with a @file{.c}, +@file{.C}, or @file{.cc} extension. + +If the current language is C++ (@pxref{Language Choice}), many of the +specific test macros use the value of @code{CXXCPP} indirectly by +calling @code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, +@code{AC_EGREP_HEADER}, or @code{AC_EGREP_CPP}. + +Some preprocessors don't indicate missing include files by the error +status. For such preprocessors an internal variable is set that causes +other macros to check the standard error from the preprocessor and +consider the test failed if any warnings have been reported. However, +it is not known whether such broken preprocessors exist for C++. +@end defmac + + + +@node Fortran 77 Compiler, , C++ Compiler, Compilers and Preprocessors +@subsection Fortran 77 Compiler Characteristics + +@defmac AC_PROG_F77 (@ovar{compiler-search-list}) +@maindex PROG_FORTRAN +@ovindex F77 +@ovindex FFLAGS +Determine a Fortran 77 compiler to use. If @code{F77} is not already +set in the environment, then check for @code{g77} and @code{f77}, and +then some other names. Set the output variable @code{F77} to the name +of the compiler found. + +This macro may, however, be invoked with an optional first argument +which, if specified, must be a space separated list of Fortran 77 +compilers to search for. This just gives the user an opportunity to +specify an alternative search list for the Fortran 77 compiler. For +example, if you didn't like the default order, then you could invoke +@code{AC_PROG_F77} like this: + +@example +AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90) +@end example + +If using @code{g77} (the @sc{gnu} Fortran 77 compiler), then +@code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}. +If the output variable @code{FFLAGS} was not already set in the +environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2} +where @code{g77} does not accept @option{-g}). Otherwise, set +@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers. +@end defmac + +@defmac AC_PROG_F77_C_O +@maindex PROG_F77_C_O +@cvindex F77_NO_MINUS_C_MINUS_O +Test if the Fortran 77 compiler accepts the options @option{-c} and +@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} if it +does not. +@end defmac + + +The following macros check for Fortran 77 compiler characteristics. To +check for characteristics not listed here, use @code{AC_TRY_COMPILE} +(@pxref{Examining Syntax}) or @code{AC_TRY_RUN} (@pxref{Run Time}), +making sure to first set the current language to Fortran 77 +@code{AC_LANG(Fortran 77)} (@pxref{Language Choice}). + + +@defmac AC_F77_LIBRARY_LDFLAGS +@maindex F77_LIBRARY_LDFLAGS +@ovindex FLIBS +Determine the linker flags (e.g. @option{-L} and @option{-l}) for the +@dfn{Fortran 77 intrinsic and run-time libraries} that are required to +successfully link a Fortran 77 program or shared library. The output +variable @code{FLIBS} is set to these flags. + +This macro is intended to be used in those situations when it is +necessary to mix, e.g. C++ and Fortran 77 source code into a single +program or shared library (@pxref{Mixing Fortran 77 With C and C++,,, +automake, GNU Automake}). + +For example, if object files from a C++ and Fortran 77 compiler must be +linked together, then the C++ compiler/linker must be used for linking +(since special C++-ish things need to happen at link time like calling +global constructors, instantiating templates, enabling exception +support, etc.). + +However, the Fortran 77 intrinsic and run-time libraries must be linked +in as well, but the C++ compiler/linker doesn't know by default how to +add these Fortran 77 libraries. Hence, the macro +@code{AC_F77_LIBRARY_LDFLAGS} was created to determine these Fortran 77 +libraries. + +The macro @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN} will probably +also be necessary to link C/C++ with Fortran; see below. +@end defmac + + +@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex F77_DUMMY_MAIN +@cvindex F77_DUMMY_MAIN +With many compilers, the Fortran libraries detected by +@code{AC_F77_LIBRARY_LDFLAGS} provide their own @code{main} entry +function that initializes things like Fortran I/O, and which then calls +a user-provided entry function named e.g. @code{MAIN__} to run the +user's program. The @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN} +macro figures out how to deal with this interaction. + +When using Fortran for purely numerical functions (no I/O, etcetera), +users often prefer to provide their own @code{main} and skip the Fortran +library initializations. In this case, however, one may still need to +provide a dummy @code{MAIN__} routine in order to prevent linking errors +on some systems. @code{AC_F77_DUMMY_MAIN} detects whether any such +routine is @emph{required} for linking, and what its name is; the shell +variable @code{F77_DUMMY_MAIN} holds this name, @code{unknown} when no +solution was found, and @code{none} when no such dummy main is needed. + +By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} to the +name of this routine (e.g. @code{MAIN__}) @emph{if} it is required. +@ovar{action-if-not-found} defaults to exiting with an error. + +In order to link with Fortran routines, the user's C/C++ program should +then include the following code to define the dummy main if it is +needed: + +@example +#ifdef F77_DUMMY_MAIN +# ifdef __cplusplus + extern "C" +# endif + int F77_DUMMY_MAIN() @{ return 1; @} +#endif +@end example + +Note that @code{AC_F77_DUMMY_MAIN} is called automatically from +@code{AC_F77_WRAPPERS}; there is generally no need to call it explicitly +unless one wants to change the default actions. +@end defmac + +@defmac AC_F77_MAIN +@maindex F77_MAIN +@cvindex F77_MAIN +As discussed above for @code{AC_F77_DUMMY_MAIN}, many Fortran libraries +allow you to provide an entry point called e.g. @code{MAIN__} instead of +the usual @code{main}, which is then called by a @code{main} function in +the Fortran libraries that initializes things like Fortran I/O. The +@code{AC_F77_MAIN} macro detects whether it is @emph{possible} to +utilize such an alternate main function, and defines @code{F77_MAIN} to +the name of the function. (If no alternate main function name is found, +@code{F77_MAIN} is simply defined to @code{main}.) + +Thus, when calling Fortran routines from C that perform things like I/O, +one should use this macro and name the "main" function @code{F77_MAIN} +instead of @code{main}. +@end defmac + +@defmac AC_F77_WRAPPERS +@maindex F77_WRAPPERS +@cvindex F77_FUNC +@cvindex F77_FUNC_ +Defines C macros @code{F77_FUNC(name,NAME)} and +@code{F77_FUNC_(name,NAME)} to properly mangle the names of C/C++ +identifiers, and identifiers with underscores, respectively, so that +they match the name-mangling scheme used by the Fortran 77 compiler. + +Fortran 77 is case-insensitive, and in order to achieve this the Fortran +77 compiler converts all identifiers into a canonical case and format. +To call a Fortran 77 subroutine from C or to write a C function that is +callable from Fortran 77, the C program must explicitly use identifiers +in the format expected by the Fortran 77 compiler. In order to do this, +one simply wraps all C identifiers in one of the macros provided by +@code{AC_F77_WRAPPERS}. For example, suppose you have the following +Fortran 77 subroutine: + +@example + subroutine foobar(x,y) + double precision x, y + y = 3.14159 * x + return + end +@end example + +You would then declare its prototype in C or C++ as: + +@example +#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR) +#ifdef __cplusplus +extern "C" /* prevent C++ name mangling */ +#endif +void FOOBAR_F77(double *x, double *y); +@end example + +Note that we pass both the lowercase and uppercase versions of the +function name to @code{F77_FUNC} so that it can select the right one. +Note also that all parameters to Fortran 77 routines are passed as +pointers (@pxref{Mixing Fortran 77 With C and C++,,, automake, GNU +Automake}). + +Although Autoconf tries to be intelligent about detecting the +name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77 +compilers that it doesn't support yet. In this case, the above code +will generate a compile-time error, but some other behavior +(e.g. disabling Fortran-related features) can be induced by checking +whether the @code{F77_FUNC} macro is defined. + +Now, to call that routine from a C program, we would do something like: + +@example +@{ + double x = 2.7183, y; + FOOBAR_F77(&x, &y); +@} +@end example + +If the Fortran 77 identifier contains an underscore +(e.g. @code{foo_bar}), you should use @code{F77_FUNC_} instead of +@code{F77_FUNC} (with the same arguments). This is because some Fortran +77 compilers mangle names differently if they contain an underscore. +@end defmac + +@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar}) +@maindex F77_FUNC +Given an identifier @var{name}, set the shell variable @var{shellvar} to +hold the mangled version @var{name} according to the rules of the +Fortran 77 linker (see also @code{AC_F77_WRAPPERS}). @var{shellvar} is +optional; if it is not supplied, the shell variable will be simply +@var{name}. The purpose of this macro is to give the caller a way to +access the name-mangling information other than through the C +preprocessor as above; for example, to call Fortran routines from some +language other than C/C++. +@end defmac + +@node System Services, UNIX Variants, Compilers and Preprocessors, Existing Tests +@section System Services + +The following macros check for operating system services or capabilities. + +@defmac AC_PATH_X +@maindex PATH_X +Try to locate the X Window System include files and libraries. If the +user gave the command line options @option{--x-includes=@var{dir}} and +@option{--x-libraries=@var{dir}}, use those directories. If either or +both were not given, get the missing values by running @code{xmkmf} on a +trivial @file{Imakefile} and examining the @file{Makefile} that it +produces. If that fails (such as if @code{xmkmf} is not present), look +for them in several directories where they often reside. If either +method is successful, set the shell variables @code{x_includes} and +@code{x_libraries} to their locations, unless they are in directories +the compiler searches by default. + +If both methods fail, or the user gave the command line option +@option{--without-x}, set the shell variable @code{no_x} to @samp{yes}; +otherwise set it to the empty string. +@end defmac + +@defmac AC_PATH_XTRA +@maindex PATH_XTRA +@ovindex X_CFLAGS +@ovindex X_LIBS +@ovindex X_EXTRA_LIBS +@ovindex X_PRE_LIBS +@cvindex X_DISPLAY_MISSING +An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags +that X needs to output variable @code{X_CFLAGS}, and the X linker flags +to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not +available. + +This macro also checks for special libraries that some systems need in +order to compile X programs. It adds any that the system needs to +output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6 +libraries that need to be linked with before @option{-lX11}, and adds +any found to the output variable @code{X_PRE_LIBS}. + +@c This is an incomplete kludge. Make a real way to do it. +@c If you need to check for other X functions or libraries yourself, then +@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to +@c @code{LIBS} temporarily, like this: (FIXME - add example) +@end defmac + +@defmac AC_SYS_INTERPRETER +@maindex SYS_INTERPRETER +Check whether the system supports starting scripts with a line of the +form @samp{#! /bin/csh} to select the interpreter to use for the script. +After running this macro, shell code in @code{configure.ac} can check +the shell variable @code{interpval}; it will be set to @samp{yes} +if the system supports @samp{#!}, @samp{no} if not. +@end defmac + +@defmac AC_SYS_LARGEFILE +@maindex SYS_LARGEFILE +@cvindex _FILE_OFFSET_BITS +@cvindex _LARGE_FILES +@ovindex CC +Arrange for +@href{http://www.sas.com/standards/large.file/x_open.20Mar96.html, +large-file support}. On some hosts, one must use special compiler +options to build programs that can access large files. Append any such +options to the output variable @code{CC}. Define +@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary. + +Large-file support can be disabled by configuring with the +@option{--disable-largefile} option. + +If you use this macro, check that your program works even when +@code{off_t} is longer than @code{long}, since this is common when +large-file support is enabled. For example, it is not correct to print +an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld", +(long) X)}. +@end defmac + +@defmac AC_SYS_LONG_FILE_NAMES +@maindex SYS_LONG_FILE_NAMES +@cvindex HAVE_LONG_FILE_NAMES +If the system supports file names longer than 14 characters, define +@code{HAVE_LONG_FILE_NAMES}. +@end defmac + +@defmac AC_SYS_POSIX_TERMIOS +@maindex SYS_POSIX_TERMIOS +@cindex POSIX termios headers +@cindex termios POSIX headers +Check to see if POSIX termios headers and functions are available on the +system. If so, set the shell variable @code{am_cv_sys_posix_termios} to +@samp{yes}. If not, set the variable to @samp{no}. +@end defmac + +@node UNIX Variants, , System Services, Existing Tests +@section UNIX Variants + +The following macros check for certain operating systems that need +special treatment for some programs, due to exceptional oddities in +their header files or libraries. These macros are warts; they will be +replaced by a more systematic approach, based on the functions they make +available or the environments they provide. + +@defmac AC_AIX +@maindex AIX +@cvindex _ALL_SOURCE +If on AIX, define @code{_ALL_SOURCE}. Allows the use of some @sc{bsd} +functions. Should be called before any macros that run the C compiler. +@end defmac + +@defmac AC_ISC_POSIX +@maindex ISC_POSIX +@cvindex _POSIX_SOURCE +@ovindex CC +If on a POSIXized ISC @sc{unix}, define @code{_POSIX_SOURCE} and add +@option{-posix} (for the @sc{gnu} C compiler) or @option{-Xp} (for other C +compilers) to output variable @code{CC}. This allows the use of +@sc{posix} facilities. Must be called after @code{AC_PROG_CC} and +before any other macros that run the C compiler. +@end defmac + +@defmac AC_MINIX +@maindex MINIX +@cvindex _MINIX +@cvindex _POSIX_SOURCE +@cvindex _POSIX_1_SOURCE +If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define +@code{_POSIX_1_SOURCE} to be 2. This allows the use of @sc{posix} +facilities. Should be called before any macros that run the C compiler. +@end defmac + + + + +@c ========================================================= Writing Tests + +@node Writing Tests, Results, Existing Tests, Top +@chapter Writing Tests + +If the existing feature tests don't do something you need, you have to +write new ones. These macros are the building blocks. They provide +ways for other macros to check whether various kinds of features are +available and report the results. + +This chapter contains some suggestions and some of the reasons why the +existing tests are written the way they are. You can also learn a lot +about how to write Autoconf tests by looking at the existing ones. If +something goes wrong in one or more of the Autoconf tests, this +information can help you understand the assumptions behind them, which +might help you figure out how to best solve the problem. + +These macros check the output of the C compiler system. They do +not cache the results of their tests for future use (@pxref{Caching +Results}), because they don't know enough about the information they are +checking for to generate a cache variable name. They also do not print +any messages, for the same reason. The checks for particular kinds of C +features call these macros and do cache their results and print messages +about what they're checking for. + +When you write a feature test that could be applicable to more than one +software package, the best thing to do is encapsulate it in a new macro. +@xref{Writing Autoconf Macros}, for how to do that. + +@menu +* Examining Declarations:: Detecting header files and declarations +* Examining Syntax:: Detecting language syntax features +* Examining Libraries:: Detecting functions and global variables +* Run Time:: Testing for run-time features +* Systemology:: A zoology of operating systems +* Multiple Cases:: Tests for several possible values +* Language Choice:: Selecting which language to use for testing +@end menu + +@node Examining Declarations, Examining Syntax, Writing Tests, Writing Tests +@section Examining Declarations + +The macro @code{AC_TRY_CPP} is used to check whether particular header +files exist. You can check for one at a time, or more than one if you +need several header files to all exist for some purpose. + +@defmac AC_TRY_CPP (@var{includes}, @ovar{action-if-true}, @ovar{action-if-false}) +@maindex TRY_CPP +@var{includes} is C or C++ @code{#include} statements and declarations, +on which shell variable, back quote, and backslash substitutions are +performed. (Actually, it can be any C program, but other statements are +probably not useful.) If the preprocessor produces no error messages +while processing it, run shell commands @var{action-if-true}. Otherwise +run shell commands @var{action-if-false}. + +This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because +@option{-g}, @option{-O}, etc. are not valid options to many C +preprocessors. +@end defmac + +Here is how to find out whether a header file contains a particular +declaration, such as a typedef, a structure, a structure member, or a +function. Use @code{AC_EGREP_HEADER} instead of running @code{grep} +directly on the header file; on some systems the symbol might be defined +in another header file that the file you are checking @samp{#include}s. + +@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found}) +@maindex EGREP_HEADER +If the output of running the preprocessor on the system header file +@var{header-file} matches the @code{egrep} regular expression +@var{pattern}, execute shell commands @var{action-if-found}, otherwise +execute @var{action-if-not-found}. +@end defmac + +To check for C preprocessor symbols, either defined by header files or +predefined by the C preprocessor, use @code{AC_EGREP_CPP}. Here is an +example of the latter: + +@example +AC_EGREP_CPP(yes, +[#ifdef _AIX + yes +#endif +], is_aix=yes, is_aix=no) +@end example + +@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex EGREP_CPP +@var{program} is the text of a C or C++ program, on which shell +variable, back quote, and backslash substitutions are performed. If the +output of running the preprocessor on @var{program} matches the +@code{egrep} regular expression @var{pattern}, execute shell commands +@var{action-if-found}, otherwise execute @var{action-if-not-found}. + +This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending +on which language is current, @pxref{Language Choice}), if it hasn't +been called already. +@end defmac + +@node Examining Syntax, Examining Libraries, Examining Declarations, Writing Tests +@section Examining Syntax + +To check for a syntax feature of the C, C++ or Fortran 77 compiler, such +as whether it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to +try to compile a small program that uses that feature. You can also use +it to check for structures and structure members that are not present on +all systems. + +@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex TRY_COMPILE +Create a C, C++ or Fortran 77 test program (depending on which language +is current, @pxref{Language Choice}), to see whether a function whose +body consists of @var{function-body} can be compiled. + +For C and C++, @var{includes} is any @code{#include} statements needed +by the code in @var{function-body} (@var{includes} will be ignored if +the currently selected language is Fortran 77). This macro also uses +@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently +selected language, as well as @code{CPPFLAGS}, when compiling. If +Fortran 77 is the currently selected language then @code{FFLAGS} will be +used when compiling. + +If the file compiles successfully, run shell commands +@var{action-if-found}, otherwise run @var{action-if-not-found}. + +This macro does not try to link; use @code{AC_TRY_LINK} if you need to +do that (@pxref{Examining Libraries}). +@end defmac + +@node Examining Libraries, Run Time, Examining Syntax, Writing Tests +@section Examining Libraries + +To check for a library, a function, or a global variable, Autoconf +@code{configure} scripts try to compile and link a small program that +uses it. This is unlike Metaconfig, which by default uses @code{nm} +or @code{ar} on the C library to try to figure out which functions are +available. Trying to link with the function is usually a more reliable +approach because it avoids dealing with the variations in the options +and output formats of @code{nm} and @code{ar} and in the location of the +standard libraries. It also allows configuring for cross-compilation or +checking a function's runtime behavior if needed. On the other hand, it +can be slower than scanning the libraries once. + +A few systems have linkers that do not return a failure exit status when +there are unresolved functions in the link. This bug makes the +configuration scripts produced by Autoconf unusable on those systems. +However, some of them can be given options that make the exit status +correct. This is a problem that Autoconf does not currently handle +automatically. If users encounter this problem, they might be able to +solve it by setting @code{LDFLAGS} in the environment to pass whatever +options the linker needs (for example, @option{-Wl,-dn} on @sc{mips +risc/os}). + +@code{AC_TRY_LINK} is used to compile test programs to test for +functions and global variables. It is also used by @code{AC_CHECK_LIB} +to check for libraries (@pxref{Libraries}), by adding the library being +checked for to @code{LIBS} temporarily and trying to link a small +program. + +@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex TRY_LINK +Depending on the current language (@pxref{Language Choice}), create a +test program to see whether a function whose body consists of +@var{function-body} can be compiled and linked. + +For C and C++, @var{includes} is any @code{#include} statements needed +by the code in @var{function-body} (@var{includes} will be ignored if +the currently selected language is Fortran 77). This macro also uses +@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently +selected language, as well as @code{CPPFLAGS}, when compiling. If +Fortran 77 is the currently selected language then @code{FFLAGS} will be +used when compiling. However, both @code{LDFLAGS} and @code{LIBS} will +be used during linking in all cases. + +If the file compiles and links successfully, run shell commands +@var{action-if-found}, otherwise run @var{action-if-not-found}. +@end defmac + +@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex TRY_LINK_FUNC +Depending on the current language (@pxref{Language Choice}), create a +test program to see whether a program whose body consists of +a prototype of and a call to @var{function} can be compiled and linked. + +If the file compiles and links successfully, run shell commands +@var{action-if-found}, otherwise run @var{action-if-not-found}. +@end defmac + + + +@node Run Time, Systemology, Examining Libraries, Writing Tests +@section Checking Run Time Behavior + +Sometimes you need to find out how a system performs at run time, such +as whether a given function has a certain capability or bug. If you +can, make such checks when your program runs instead of when it is +configured. You can check for things like the machine's endianness when +your program initializes itself. + +If you really need to test for a run-time behavior while configuring, +you can write a test program to determine the result, and compile and +run it using @code{AC_TRY_RUN}. Avoid running test programs if +possible, because this prevents people from configuring your package for +cross-compiling. + +@menu +* Test Programs:: Running test programs +* Guidelines:: General rules for writing test programs +* Test Functions:: Avoiding pitfalls in test programs +@end menu + +@node Test Programs, Guidelines, Run Time, Run Time +@subsection Running Test Programs + +Use the following macro if you need to test run-time behavior of the +system while configuring. + +@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling}) +@maindex TRY_RUN +@var{program} is the text of a C program, on which shell variable and +back quote substitutions are performed. If it compiles and links +successfully and returns an exit status of 0 when executed, run shell +commands @var{action-if-true}. Otherwise, run shell commands +@var{action-if-false}; the exit status of the program is available in +the shell variable @samp{$?}. This macro uses @code{CFLAGS} or +@code{CXXFLAGS}, @code{CPPFLAGS}, @code{LDFLAGS}, and @code{LIBS} when +compiling. + +If the C compiler being used does not produce executables that run on +the system where @code{configure} is being run, then the test program is +not run. If the optional shell commands @var{action-if-cross-compiling} +are given, they are run instead. Otherwise, @code{configure} prints +an error message and exits. +@end defmac + +Try to provide a pessimistic default value to use when cross-compiling +makes run-time tests impossible. You do this by passing the optional +last argument to @code{AC_TRY_RUN}. @code{autoconf} prints a warning +message when creating @code{configure} each time it encounters a call to +@code{AC_TRY_RUN} with no @var{action-if-cross-compiling} argument +given. You may ignore the warning, though users will not be able to +configure your package for cross-compiling. A few of the macros +distributed with Autoconf produce this warning message. + +To configure for cross-compiling you can also choose a value for those +parameters based on the canonical system name (@pxref{Manual +Configuration}). Alternatively, set up a test results cache file with +the correct values for the host system (@pxref{Caching Results}). + +To provide a default for calls of @code{AC_TRY_RUN} that are embedded in +other macros, including a few of the ones that come with Autoconf, you +can call @code{AC_PROG_CC} before running them. Then, if the shell +variable @code{cross_compiling} is set to @samp{yes}, use an alternate +method to get the results instead of calling the macros. + + +@node Guidelines, Test Functions, Test Programs, Run Time +@subsection Guidelines for Test Programs + +Test programs should not write anything to the standard output. They +should return 0 if the test succeeds, nonzero otherwise, so that success +can be distinguished easily from a core dump or other failure; +segmentation violations and other failures produce a nonzero exit +status. Test programs should @code{exit}, not @code{return}, from +@code{main}, because on some systems (old Suns, at least) the argument +to @code{return} in @code{main} is ignored. + +Test programs can use @code{#if} or @code{#ifdef} to check the values of +preprocessor macros defined by tests that have already run. For +example, if you call @code{AC_HEADER_STDC}, then later on in +@file{configure.ac} you can have a test program that includes an +@sc{ansi} C header file conditionally: + +@example +@group +#if STDC_HEADERS +# include <stdlib.h> +#endif +@end group +@end example + +If a test program needs to use or create a data file, give it a name +that starts with @file{conftest}, such as @file{conftest.data}. The +@code{configure} script cleans up by running @samp{rm -rf conftest*} +after running test programs and if the script is interrupted. + +@node Test Functions, , Guidelines, Run Time +@subsection Test Functions + +Function declarations in test programs should have a prototype +conditionalized for C++. In practice, though, test programs rarely need +functions that take arguments. + +@example +#ifdef __cplusplus +foo (int i) +#else +foo (i) int i; +#endif +@end example + +Functions that test programs declare should also be conditionalized for +C++, which requires @samp{extern "C"} prototypes. Make sure to not +include any header files containing clashing prototypes. + +@example +#ifdef __cplusplus +extern "C" void *malloc (size_t); +#else +char *malloc (); +#endif +@end example + +If a test program calls a function with invalid parameters (just to see +whether it exists), organize the program to ensure that it never invokes +that function. You can do this by calling it in another function that is +never invoked. You can't do it by putting it after a call to +@code{exit}, because GCC version 2 knows that @code{exit} never returns +and optimizes out any code that follows it in the same block. + +If you include any header files, make sure to call the functions +relevant to them with the correct number of arguments, even if they are +just 0, to avoid compilation errors due to prototypes. GCC version 2 +has internal prototypes for several functions that it automatically +inlines; for example, @code{memcpy}. To avoid errors when checking for +them, either pass them the correct number of arguments or redeclare them +with a different return type (such as @code{char}). + +@node Systemology, Multiple Cases, Run Time, Writing Tests +@section Systemology + +This section aims at presenting some systems and pointers to +documentation. It may help you addressing particular problems reported +by users. + +@table @asis +@item @sc{qnx 4.25} +@cindex @sc{qnx 4.25} +@c FIXME: Please, if you feel like writing something more precise, +@c it'd be great. In particular, I can't understand the difference with +@c QNX Neutrino. +@sc{qnx} is a realtime operating system running on Intel architecture +meant to be scalable from the small embedded systems to hundred +processor super-computer. It claims to be @sc{posix} certified. More +information is available on the @href{www.qnx.com, @sc{qnx} home page}, +including the @href{http://support.qnx.com/support/docs/qnx4/, @sc{qnx} +man pages}. +@end table + + +@node Multiple Cases, Language Choice, Systemology, Writing Tests +@section Multiple Cases + +Some operations are accomplished in several possible ways, depending on +the @sc{unix} variant. Checking for them essentially requires a ``case +statement''. Autoconf does not directly provide one; however, it is +easy to simulate by using a shell variable to keep track of whether a +way to perform the operation has been found yet. + +Here is an example that uses the shell variable @code{fstype} to keep +track of whether the remaining cases need to be checked. + +@example +@group +AC_MSG_CHECKING([how to get file system type]) +fstype=no +# The order of these tests is important. +AC_TRY_CPP([#include <sys/statvfs.h> +#include <sys/fstyp.h>], + [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4]) +if test $fstype = no; then + AC_TRY_CPP([#include <sys/statfs.h> +#include <sys/fstyp.h>], + [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3]) +fi +if test $fstype = no; then + AC_TRY_CPP([#include <sys/statfs.h> +#include <sys/vmount.h>], + [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX]) +fi +# (more cases omitted here) +AC_MSG_RESULT([$fstype]) +@end group +@end example + +@node Language Choice, , Multiple Cases, Writing Tests +@section Language Choice +@cindex Language + +Autoconf-generated @code{configure} scripts check for the C compiler and +its features by default. Packages that use other programming languages +(maybe more than one, e.g. C and C++) need to test features of the +compilers for the respective languages. The following macros determine +which programming language is used in the subsequent tests in +@file{configure.ac}. + +@defmac AC_LANG (@var{language}) +Do compilation tests using the compiler, preprocessor and file +extensions for the specified @var{language}. + +Supported languages are: + +@table @samp +@item C +Do compilation tests using @code{CC} and @code{CPP} and use extension +@file{.c} for test programs. + +@item C++ +Do compilation tests using @code{CXX} and @code{CXXCPP} and use +extension @file{.C} for test programs. + +@item Fortran 77 +Do compilation tests using @code{F77} and use extension @file{.f} for +test programs. +@end table +@end defmac + +@defmac AC_LANG_PUSH (@var{language}) +@maindex LANG_PUSH +Remember the current language (as set by @code{AC_LANG}) on a stack, and +then select the @var{language}. Use this macro and @code{AC_LANG_POP} +in macros that need to temporarily switch to a particular language. +@end defmac + +@defmac AC_LANG_POP (@ovar{language}) +@maindex LANG_POP +Select the language that is saved on the top of the stack, as set by +@code{AC_LANG_PUSH}, and remove it from the stack. + +If given, @var{language} specifies the language we just @emph{quit}. It +is a good idea to specify it when it's known (which should be the +case@dots{}), since Autoconf will detect inconsistencies. + +@example +AC_LANG_PUSH(Fortran 77) +# Perform some tests on Fortran 77. +# ... +AC_LANG_POP(Fortran 77) +@end example +@end defmac + +@defmac AC_REQUIRE_CPP +@maindex REQUIRE_CPP +Ensure that whichever preprocessor would currently be used for tests has +been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an +argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP}, +depending on which language is current. +@end defmac + + + +@c ====================================================== Results of Tests. + +@node Results, Programming in M4, Writing Tests, Top +@chapter Results of Tests + +Once @code{configure} has determined whether a feature exists, what can +it do to record that information? There are four sorts of things it can +do: define a C preprocessor symbol, set a variable in the output files, +save the result in a cache file for future @code{configure} runs, and +print a message letting the user know the result of the test. + +@menu +* Defining Symbols:: Defining C preprocessor symbols +* Setting Output Variables:: Replacing variables in output files +* Caching Results:: Speeding up subsequent @code{configure} runs +* Printing Messages:: Notifying @code{configure} users +@end menu + +@node Defining Symbols, Setting Output Variables, Results, Results +@section Defining C Preprocessor Symbols + +A common action to take in response to a feature test is to define a C +preprocessor symbol indicating the results of the test. That is done by +calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}. + +By default, @code{AC_OUTPUT} places the symbols defined by these macros +into the output variable @code{DEFS}, which contains an option +@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in +Autoconf version 1, there is no variable @code{DEFS} defined while +@code{configure} is running. To check whether Autoconf macros have +already defined a certain C preprocessor symbol, test the value of the +appropriate cache variable, as in this example: + +@example +AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)]) +if test "$ac_cv_func_vprintf" != yes; then + AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)]) +fi +@end example + +If @code{AC_CONFIG_HEADERS} has been called, then instead of creating +@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the +correct values into @code{#define} statements in a template file. +@xref{Configuration Headers}, for more information about this kind of +output. + +@defmac AC_DEFINE (@var{variable}, @ovar{value}, @ovar{description}) +@maindex DEFINE +Define C preprocessor variable @var{variable}. If @var{value} is given, +set @var{variable} to that value (verbatim), otherwise set it to 1. +@var{value} should not contain literal newlines, and if you are not +using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#} +characters, as @code{make} tends to eat them. To use a shell variable +(which you need to do in order to define a value containing the M4 quote +characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead. +@var{description} is only useful if you are using +@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into +the generated @file{config.h.in} as the comment before the macro define. +The following example defines the C preprocessor variable +@code{EQUATION} to be the string constant @samp{"$a > $b"}: + +@example +AC_DEFINE(EQUATION, "$a > $b") +@end example +@end defmac + +@defmac AC_DEFINE_UNQUOTED (@var{variable}, @ovar{value}, @ovar{description}) +@maindex DEFINE_UNQUOTED +Like @code{AC_DEFINE}, but three shell expansions are +performed---once---on @var{variable} and @var{value}: variable expansion +(@samp{$}), command substitution (@samp{`}), and backslash escaping +(@samp{\}). Single and double quote characters in the value have no +special meaning. Use this macro instead of @code{AC_DEFINE} when +@var{variable} or @var{value} is a shell variable. Examples: + +@example +AC_DEFINE_UNQUOTED(config_machfile, "$machfile") +AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups) +AC_DEFINE_UNQUOTED($ac_tr_hdr) +@end example +@end defmac + +Due to the syntactical bizarreness of the Bourne shell, do not use +semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} +calls from other macro calls or shell code; that can cause syntax errors +in the resulting @code{configure} script. Use either spaces or +newlines. That is, do this: + +@example +AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"]) +@end example + +@noindent +or this: + +@example +AC_CHECK_HEADER(elf.h, + [AC_DEFINE(SVR4) + LIBS="$LIBS -lelf"]) +@end example + +@noindent +instead of this: + +@example +AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"]) +@end example + +@node Setting Output Variables, Caching Results, Defining Symbols, Results +@section Setting Output Variables + +Another way to record the results of tests is to set @dfn{output +variables}, which are shell variables whose values are substituted into +files that @code{configure} outputs. The two macros below create new +output variables. @xref{Preset Output Variables}, for a list of output +variables that are always available. + +@defmac AC_SUBST (@var{variable}, @ovar{value}) +@maindex SUBST +Create an output variable from a shell variable. Make @code{AC_OUTPUT} +substitute the variable @var{variable} into output files (typically one +or more @file{Makefile}s). This means that @code{AC_OUTPUT} will +replace instances of @samp{@@@var{variable}@@} in input files with the +value that the shell variable @var{variable} has when @code{AC_OUTPUT} +is called. This value of @var{variable} should not contain literal +newlines. + +If @var{value} is given, in addition assign it to @samp{variable}. +@end defmac + +@defmac AC_SUBST_FILE (@var{variable}) +@maindex SUBST_FILE +Another way to create an output variable from a shell variable. Make +@code{AC_OUTPUT} insert (without substitutions) the contents of the file +named by shell variable @var{variable} into output files. This means +that @code{AC_OUTPUT} will replace instances of +@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in}) +with the contents of the file that the shell variable @var{variable} +names when @code{AC_OUTPUT} is called. Set the variable to +@file{/dev/null} for cases that do not have a file to insert. + +This macro is useful for inserting @file{Makefile} fragments containing +special dependencies or other @code{make} directives for particular host +or target types into @file{Makefile}s. For example, @file{configure.ac} +could contain: + +@example +AC_SUBST_FILE(host_frag) +host_frag=$srcdir/conf/sun4.mh +@end example + +@noindent +and then a @file{Makefile.in} could contain: + +@example +@@host_frag@@ +@end example +@end defmac + +@cindex Previous Variable +@cindex Variable, Precious +Running @command{configure} in different environments can be extremely +dangerous. If for instance the user runs @samp{CC=bizarre-cc +./configure}, then the cache, @file{config.h} and many other output +files will depend upon @command{bizarre-cc} being the C compiler. If +for some reason the user runs @command{/configure} again, or if it is +run via @samp{./config.status --recheck}, (@xref{Automatic Remaking}, +and @pxref{config.status Invocation}), then the configuration can be +inconsistent, composed of results depending upon two different +compilers. + +Such variables are named @dfn{precious variables}, and can be declared +as such by @code{AC_ARG_VAR}. + +@defmac AC_ARG_VAR (@var{variable}, @var{description}) +@maindex ARG_VAR +Declare @var{variable} is a precious variable, and include its +@var{description} in the variable section of @samp{./configure --help}. + +Being precious means that +@itemize @minus +@item +@var{variable} is @code{AC_SUBST}'d. + +@item +@var{variable} is kept in the cache including if it was not specified on +the @samp{./configure} command line. Indeed, while @command{configure} +can notice the definition of @code{CC} in @samp{./configure +CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc +./configure}, which, unfortunately, is what most users do. + +@item +@var{variable} is checked for consistency between two +@command{configure} runs. For instance: + +@example +$ ./configure --silent --config-cache +$ CC=cc ./configure --silent --config-cache +configure: error: `CC' was not set in the previous run +configure: error: changes in the environment can compromise \ +the build +configure: error: run `make distclean' and/or \ +`rm config.cache' and start over +@end example + +@noindent +and similarly if the variable is unset, or if its content is changed. + + +@item +@var{variable} is kept during automatic reconfiguration +(@pxref{config.status Invocation}) as if it had been passed as a command +line argument, including when no cache is used: + +@example +$ CC=/usr/bin/cc ./configure undeclared_var=raboof --silent +$ ./config.status --recheck +running /bin/sh ./configure undeclared_var=raboof --silent \ + CC=/usr/bin/cc --no-create --no-recursion +@end example +@end itemize +@end defmac + + +@node Caching Results, Printing Messages, Setting Output Variables, Results +@section Caching Results +@cindex Cache + +To avoid checking for the same features repeatedly in various +@code{configure} scripts (or in repeated runs of one script), +@code{configure} can optionally save the results of many checks in a +@dfn{cache file} (@pxref{Cache Files}). If a @code{configure} script +runs with caching enabled and finds a cache file, it reads the results +of previous runs from the cache and avoids rerunning those checks. As a +result, @code{configure} can then run much faster than if it had to +perform all of the checks every time. + +@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it}) +@maindex CACHE_VAL +Ensure that the results of the check identified by @var{cache-id} are +available. If the results of the check were in the cache file that was +read, and @code{configure} was not given the @option{--quiet} or +@option{--silent} option, print a message saying that the result was +cached; otherwise, run the shell commands @var{commands-to-set-it}. If +the shell commands are run to determine the value, the value will be +saved in the cache file just before @code{configure} creates its output +files. @xref{Cache Variable Names}, for how to choose the name of the +@var{cache-id} variable. + +The @var{commands-to-set-it} @emph{must have no side effects} except for +setting the variable @var{cache-id}, see below. +@end defmac + +@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it}) +@maindex CACHE_CHECK +A wrapper for @code{AC_CACHE_VAL} that takes care of printing the +messages. This macro provides a convenient shorthand for the most +common way to use these macros. It calls @code{AC_MSG_CHECKING} for +@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and +@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}. + +The @var{commands-to-set-it} @emph{must have no side effects} except for +setting the variable @var{cache-id}, see below. +@end defmac + +It is very common to find buggy macros using @code{AC_CACHE_VAL} or +@code{AC_CACHE_CHECK}, because people are tempted to call +@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that +@emph{follows} the call to @code{AC_CACHE_VAL} should call +@code{AC_DEFINE}, by examining the value of the cache variable. For +instance, the following macro is broken: + +@example +@group +AC_DEFUN([AC_SHELL_TRUE], +[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], + [ac_cv_shell_true_works=no + true && ac_cv_shell_true_works=yes + if test $ac_cv_shell_true_works = yes; then + AC_DEFINE([TRUE_WORKS], 1 + [Define if `true(1)' works properly.]) + fi]) +]) +@end group +@end example + +@noindent +This fails if the cache is enabled: the second time this macro is run, +@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation +is: + +@example +@group +AC_DEFUN([AC_SHELL_TRUE], +[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], + [ac_cv_shell_true_works=no + true && ac_cv_shell_true_works=yes]) + if test $ac_cv_shell_true_works = yes; then + AC_DEFINE([TRUE_WORKS], 1 + [Define if `true(1)' works properly.]) + fi +]) +@end group +@end example + +Also, @var{commands-to-set-it} should not print any messages, for +example with @code{AC_MSG_CHECKING}; do that before calling +@code{AC_CACHE_VAL}, so the messages are printed regardless of whether +the results of the check are retrieved from the cache or determined by +running the shell commands. + +@menu +* Cache Variable Names:: Shell variables used in caches +* Cache Files:: Files @code{configure} uses for caching +* Cache Checkpointing:: Loading and saving the cache file +@end menu + +@node Cache Variable Names, Cache Files, Caching Results, Caching Results +@subsection Cache Variable Names +@cindex Cache variable + +The names of cache variables should have the following format: + +@example +@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options} +@end example + +@noindent +for example, @samp{ac_cv_header_stat_broken} or +@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are: + +@table @asis +@item @var{package-prefix} +An abbreviation for your package or organization; the same prefix you +begin local Autoconf macros with, except lowercase by convention. +For cache values used by the distributed Autoconf macros, this value is +@samp{ac}. + +@item @code{_cv_} +Indicates that this shell variable is a cache value. This string +@emph{must} be present in the variable name, including the leading +underscore. + +@item @var{value-type} +A convention for classifying cache values, to produce a rational naming +system. The values used in Autoconf are listed in @ref{Macro Names}. + +@item @var{specific-value} +Which member of the class of cache values this test applies to. +For example, which function (@samp{alloca}), program (@samp{gcc}), or +output variable (@samp{INSTALL}). + +@item @var{additional-options} +Any particular behavior of the specific member that this test applies to. +For example, @samp{broken} or @samp{set}. This part of the name may +be omitted if it does not apply. +@end table + +The values assigned to cache variables may not contain newlines. +Usually, their values will be boolean (@samp{yes} or @samp{no}) or the +names of files or functions; so this is not an important restriction. + +@node Cache Files, Cache Checkpointing, Cache Variable Names, Caching Results +@subsection Cache Files + +A cache file is a shell script that caches the results of configure +tests run on one system so they can be shared between configure scripts +and configure runs. It is not useful on other systems. If its contents +are invalid for some reason, the user may delete or edit it. + +By default, @code{configure} uses no cache file (technically, it uses +@option{--cache-file=/dev/null}), to avoid problems caused by accidental +use of stale cache files. + +To enable caching, @code{configure} accepts @option{--config-cache} (or +@option{-C}) to cache results in the file @file{config.cache}. +Alternatively, @option{--cache-file=@var{file}} specifies that +@var{file} be the cache file. The cache file is created if it does not +exist already. When @code{configure} calls @code{configure} scripts in +subdirectories, it uses the @option{--cache-file} argument so that they +share the same cache. @xref{Subdirectories}, for information on +configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro. + +@file{config.status} only pays attention to the cache file if it is +given the @option{--recheck} option, which makes it rerun +@code{configure}. + +It is wrong to try to distribute cache files for particular system types. +There is too much room for error in doing that, and too much +administrative overhead in maintaining them. For any features that +can't be guessed automatically, use the standard method of the canonical +system type and linking files (@pxref{Manual Configuration}). + +The site initialization script can specify a site-wide cache file to +use, instead of the usual per-program cache. In this case, the cache +file will gradually accumulate information whenever someone runs a new +@code{configure} script. (Running @code{configure} merges the new cache +results with the existing cache file.) This may cause problems, +however, if the system configuration (e.g. the installed libraries or +compilers) changes and the stale cache file is not deleted. + +@node Cache Checkpointing, , Cache Files, Caching Results +@subsection Cache Checkpointing + +If your configure script, or a macro called from configure.ac, happens +to abort the configure process, it may be useful to checkpoint the cache +a few times at key points using @code{AC_CACHE_SAVE}. Doing so will +reduce the amount of time it takes to re-run the configure script with +(hopefully) the error that caused the previous abort corrected. + +@c FIXME: Do we really want to document this guy? +@defmac AC_CACHE_LOAD +@maindex CACHE_LOAD +Loads values from existing cache file, or creates a new cache file if a +cache file is not found. Called automatically from @code{AC_INIT}. +@end defmac + +@defmac AC_CACHE_SAVE +@maindex CACHE_SAVE +Flushes all cached values to the cache file. Called automatically from +@code{AC_OUTPUT}, but it can be quite useful to call +@code{AC_CACHE_SAVE} at key points in configure.ac. +@end defmac + +For instance: + +@example +@r{ @dots{} AC_INIT, etc. @dots{}} +@group +# Checks for programs. +AC_PROG_CC +AC_PROG_GCC_TRADITIONAL +@r{ @dots{} more program checks @dots{}} +AC_CACHE_SAVE +@end group + +@group +# Checks for libraries. +AC_CHECK_LIB(nsl, gethostbyname) +AC_CHECK_LIB(socket, connect) +@r{ @dots{} more lib checks @dots{}} +AC_CACHE_SAVE +@end group + +@group +# Might abort... +AM_PATH_GTK(1.0.2,, (exit 1); exit) +AM_PATH_GTKMM(0.9.5,, (exit 1); exit) +@end group +@r{ @dots{} AC_OUTPUT, etc. @dots{}} +@end example + +@node Printing Messages, , Caching Results, Results +@section Printing Messages +@cindex Messages, from @code{configure} + +@code{configure} scripts need to give users running them several kinds +of information. The following macros print messages in ways appropriate +for each kind. The arguments to all of them get enclosed in shell +double quotes, so the shell performs variable and back-quote +substitution on them. + +These macros are all wrappers around the @code{echo} shell command. +@code{configure} scripts should rarely need to run @code{echo} directly +to print messages for the user. Using these macros makes it easy to +change how and when each kind of message is printed; such changes need +only be made to the macro definitions and all of the callers will change +automatically. + +To diagnose static issues, i.e., when @code{autoconf} is run, see +@ref{Reporting Messages}. + +@defmac AC_MSG_CHECKING (@var{feature-description}) +@maindex MSG_CHECKING +Notify the user that @code{configure} is checking for a particular +feature. This macro prints a message that starts with @samp{checking } +and ends with @samp{...} and no newline. It must be followed by a call +to @code{AC_MSG_RESULT} to print the result of the check and the +newline. The @var{feature-description} should be something like +@samp{whether the Fortran compiler accepts C++ comments} or @samp{for +c89}. + +This macro prints nothing if @code{configure} is run with the +@option{--quiet} or @option{--silent} option. +@end defmac + +@defmac AC_MSG_RESULT (@var{result-description}) +@maindex MSG_RESULT +Notify the user of the results of a check. @var{result-description} is +almost always the value of the cache variable for the check, typically +@samp{yes}, @samp{no}, or a file name. This macro should follow a call +to @code{AC_MSG_CHECKING}, and the @var{result-description} should be +the completion of the message printed by the call to +@code{AC_MSG_CHECKING}. + +This macro prints nothing if @code{configure} is run with the +@option{--quiet} or @option{--silent} option. +@end defmac + +@defmac AC_MSG_NOTICE (@var{message}) +@maindex MSG_NOTICE +Deliver the @var{message} to the user. It is useful mainly to print a +general description of the overall purpose of a group of feature checks, +e.g., + +@example +AC_MSG_NOTICE([checking if stack overflow is detectable]) +@end example + +This macro prints nothing if @code{configure} is run with the +@option{--quiet} or @option{--silent} option. +@end defmac + +@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status}) +@maindex MSG_ERROR +Notify the user of an error that prevents @code{configure} from +completing. This macro prints an error message to the standard error +output and exits @code{configure} with @var{exit-status} (1 by default). +@var{error-description} should be something like @samp{invalid value +$HOME for \$HOME}. + +The @var{error-description} should start with a lower-case letter, and +``cannot'' is preferred to ``can't''. +@end defmac + +@defmac AC_MSG_WARN (@var{problem-description}) +@maindex MSG_WARN +Notify the @code{configure} user of a possible problem. This macro +prints the message to the standard error output; @code{configure} +continues running afterward, so macros that call @code{AC_MSG_WARN} should +provide a default (back-up) behavior for the situations they warn about. +@var{problem-description} should be something like @samp{ln -s seems to +make hard links}. +@end defmac + + + +@c ====================================================== Programming in M4. + +@node Programming in M4, Writing Autoconf Macros, Results, Top +@chapter Programming in M4 + +Autoconf is written on top of two layers: @dfn{M4sugar}, which provides +convenient macros for pure M4 programming, and @dfn{M4sh}, which +provides macros dedicated to shell script generation. + +As of this version of Autoconf, these two layers are still experimental, +and their interface might change in the future. As a matter of fact, +@emph{anything that is not documented must not be used}. + +@menu +* M4 Quotation:: Protecting macros from unwanted expansion +* Programming in M4sugar:: Convenient pure M4 macros +@end menu + +@node M4 Quotation, Programming in M4sugar, Programming in M4, Programming in M4 +@section M4 Quotation +@cindex quotation + +@c FIXME: Grmph, yet another quoting myth: quotation has *never* +@c prevented `expansion' of $1. Unless it refers to the expansion +@c of the value of $1? Anyway, we need a rewrite here@dots{} + +The most common brokenness of existing macros is an improper quotation. +This section, which users of Autoconf can skip, but which macro writers +@emph{must} read, first justifies the quotation scheme that was chosen +for Autoconf and then ends with a rule of thumb. Understanding the +former helps one to follow the latter. + +@menu +* Active Characters:: Characters that change the behavior of m4 +* One Macro Call:: Quotation and one macro call +* Quotation and Nested Macros:: Macros calling macros +* Quadrigraphs:: Another way to escape special characters +* Quotation Rule Of Thumb:: One parenthesis, one quote +@end menu + +@node Active Characters, One Macro Call, M4 Quotation, M4 Quotation +@subsection Active Characters + +To fully understand where proper quotation is important, you first need +to know what are the special characters in Autoconf: @samp{#} introduces +a comment inside which no macro expansion is performed, @samp{,} +separates arguments, @samp{[} and @samp{]} are the quotes themselves, +and finally @samp{(} and @samp{)} (which @code{m4} tries to match by +pairs). + +In order to understand the delicate case of macro calls, we first have +to present some obvious failures. Below they are ``obvious-ified'', +although you find them in real life, they are usually in disguise. + +Comments, introduced by a hash and running up to the newline, are opaque +tokens to the top level: active characters are turned off, and there is +no macro expansion: + +@example +# define([def], ine) +@result{}# define([def], ine) +@end example + +Each time there can be a macro expansion, there is a quotation +expansion; i.e., one level of quotes is stripped: + +@example +int tab[10]; +@result{}int tab10; +[int tab[10];] +@result{}int tab[10]; +@end example + +Without this in mind, the reader will try hopelessly to use her macro +@code{array}: + +@example +define([array], [int tab[10];]) +array +@result{}int tab10; +[array] +@result{}array +@end example + +@noindent +How can you correctly output the intended results@footnote{Using +@code{defn}.}? + + +@node One Macro Call, Quotation and Nested Macros, Active Characters, M4 Quotation +@subsection One Macro Call + +Let's proceed on the interaction between active characters and macros +with this small macro, which just returns its first argument: + +@example +define([car], [$1]) +@end example + +@noindent +The two pairs of quotes above are not part of the arguments of +@code{define}; rather, they are understood by the top level when it +tries to find the arguments of @code{define}. Therefore, it is +equivalent to write: + +@example +define(car, $1) +@end example + +@noindent +But, while it is acceptable for a @file{configure.ac} to avoid unneeded +quotes, it is bad practice for Autoconf macros which must both be more +robust and also advocate perfect style. + +At the top level, there are only two possible quotings: either you +quote or you don't: + +@example +car(foo, bar, baz) +@result{}foo +[car(foo, bar, baz)] +@result{}car(foo, bar, baz) +@end example + +Let's pay attention to the special characters: + +@example +car(#) +@error{}EOF in argument list +@end example + +The closing parenthesis is hidden in the comment; with a hypothetical +quoting, the top level understood it this way: + +@example +car([#)] +@end example + +@noindent +Proper quotation, of course, fixes the problem: + +@example +car([#]) +@result{}# +@end example + +The reader will easily understand the following examples: + +@example +car(foo, bar) +@result{}foo +car([foo, bar]) +@result{}foo, bar +car((foo, bar)) +@result{}(foo, bar) +car([(foo], [bar)]) +@result{}(foo +car([], []) +@result{} +car([[]], [[]]) +@result{}[] +@end example + +With this in mind, we can explore the cases where macros invoke +macros@dots{} + + +@node Quotation and Nested Macros, Quadrigraphs, One Macro Call, M4 Quotation +@subsection Quotation and Nested Macros + +The examples below use the following macros: + +@example +define([car], [$1]) +define([active], [ACT, IVE]) +define([array], [int tab[10]]) +@end example + +Each additional embedded macro call introduces other possible +interesting quotations: + +@example +car(active) +@result{}ACT +car([active]) +@result{}ACT, IVE +car([[active]]) +@result{}active +@end example + +In the first case, the top level looks for the arguments of @code{car}, +and finds @samp{active}. Because @code{m4} evaluates its arguments +before applying the macro, @samp{active} is expanded, which results in: + +@example +car(ACT, IVE) +@result{}ACT +@end example + +@noindent +In the second case, the top level gives @samp{active} as first and only +argument of @code{car}, which results in: + +@example +active +@result{}ACT, IVE +@end example + +@noindent +i.e., the argument is evaluated @emph{after} the macro that invokes it. +In the third case, @code{car} receives @samp{[active]}, which results in: + +@example +[active] +@result{}active +@end example + +@noindent +exactly as we already saw above. + +The example above, applied to a more realistic example, gives: + +@example +car(int tab[10];) +@result{}int tab10; +car([int tab[10];]) +@result{}int tab10; +car([[int tab[10];]]) +@result{}int tab[10]; +@end example + +@noindent +Huh? The first case is easily understood, but why is the second wrong, +and the third right? To understand that, you must know that after +@code{m4} expands a macro, the resulting text is immediately subjected +to macro expansion and quote removal. This means that the quote removal +occurs twice---first before the argument is passed to the @code{car} +macro, and second after the @code{car} macro expands to the first +argument. + +As the author of the Autoconf macro @code{car}, you then consider it to +be incorrect that your users have to double-quote the arguments of +@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for +quoted car: + +@example +define([qar], [[$1]]) +@end example + +@noindent +and check that @code{qar} is properly fixed: + +@example +qar([int tab[10];]) +@result{}int tab[10]; +@end example + +@noindent +Ahhh! That's much better. + +But note what you've done: now that the arguments are literal strings, +if the user wants to use the results of expansions as arguments, she has +to use an @emph{unquoted} macro call: + +@example +qar(active) +@result{}ACT +@end example + +@noindent +where she wanted to reproduce what she used to do with @code{car}: + +@example +car([active]) +@result{}ACT, IVE +@end example + +@noindent +Worse yet: she wants to use a macro that produces a set of @code{cpp} +macros: + +@example +define([my_includes], [#include <stdio.h>]) +car([my_includes]) +@result{}#include <stdio.h> +qar(my_includes) +@error{}EOF in argument list +@end example + +This macro, @code{qar}, because it double quotes its arguments, forces +its users to leave their macro calls unquoted, which is dangerous. +Commas and other active symbols are interpreted by @code{m4} before +they are given to the macro, often not in the way the users expect. +Also, because @code{qar} behaves differently from the other macros, +it's an exception that should be avoided in Autoconf. + + +@node Quadrigraphs, Quotation Rule Of Thumb, Quotation and Nested Macros, M4 Quotation +@subsection Quadrigraphs +@cindex quadrigraphs +@cindex @samp{@@<:@@} +@cindex @samp{@@:>@@} +@cindex @samp{@@S|@@} +@cindex @samp{@@%:@@} + +When writing an autoconf macro you may occasionally need to generate +special characters that are difficult to express with the standard +autoconf quoting rules. For example, you may need to output the regular +expression @samp{[^[]}, which matches any character other than @samp{[}. +This expression contains unbalanced brackets so it cannot be put easily +into an M4 macro. + +You can work around this problem by using one of the following +@dfn{quadrigraphs}: + +@table @samp +@item @@<:@@ +@samp{[} +@item @@:>@@ +@samp{]} +@item @@S|@@ +@samp{$} +@item @@%:@@ +@samp{#} +@end table + +Quadrigraphs are replaced at a late stage of the translation process, +after @command{m4} is run, so they do not get in the way of M4 quoting. +For example, the string @samp{[^@@<:@@]}, if properly quoted, will +appear as @samp{[^[]} in the @code{configure} script. + + +@node Quotation Rule Of Thumb, , Quadrigraphs, M4 Quotation +@subsection Quotation Rule Of Thumb + +To conclude, the quotation rule of thumb is: + +@center @emph{One pair of quotes per pair of parentheses.} + +Never over-quote, never under-quote, in particular in the definition of +macros. In the few places where the macros need to use brackets +(usually in C program text or regular expressions), properly quote +@emph{the arguments}! + +It is common to read Autoconf programs with snippets like: + +@example +AC_TRY_LINK( +changequote(<<, >>)dnl +<<#include <time.h> +#ifndef tzname /* For SGI. */ +extern char *tzname[]; /* RS6000 and others reject char **tzname. */ +#endif>>, +changequote([, ])dnl +[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) +@end example + +@noindent +which is incredibly useless since @code{AC_TRY_LINK} is @emph{already} +double quoting, so you just need: + +@example +AC_TRY_LINK( +[#include <time.h> +#ifndef tzname /* For SGI. */ +extern char *tzname[]; /* RS6000 and others reject char **tzname. */ +#endif], + [atoi (*tzname);], + [ac_cv_var_tzname=yes], + [ac_cv_var_tzname=no]) +@end example + +@noindent +The M4-fluent reader will note that these two examples are rigorously +equivalent, since @code{m4} swallows both the @samp{changequote(<<, >>)} +and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these +quotes are not part of the arguments! + +Simplified, the example above is just doing this: + +@example +changequote(<<, >>)dnl +<<[]>> +changequote([, ])dnl +@end example + +@noindent +instead of simply: + +@example +[[]] +@end example + + +With macros that do not double quote their arguments (which is the +rule), double-quote the (risky) literals: + +@example +AC_LINK_IFELSE([AC_LANG_PROGRAM( +[[#include <time.h> +#ifndef tzname /* For SGI. */ +extern char *tzname[]; /* RS6000 and others reject char **tzname. */ +#endif]], + [atoi (*tzname);])], + [ac_cv_var_tzname=yes], + [ac_cv_var_tzname=no]) +@end example + +See @xref{Quadrigraphs}, for what to do if you run into a hopeless case +where quoting does not suffice. + +When you create a @code{configure} script using newly written macros, +examine it carefully to check whether you need to add more quotes in +your macros. If one or more words have disappeared in the @code{m4} +output, you need more quotes. When in doubt, quote. + +However, it's also possible to put on too many layers of quotes. If +this happens, the resulting @code{configure} script will contain +unexpanded macros. The @code{autoconf} program checks for this problem +by doing @samp{grep AC_ configure}. + + +@node Programming in M4sugar, , M4 Quotation, Programming in M4 +@section Programming in M4sugar + +@cindex M4sugar +M4 by itself provides only a small, but sufficient, set of all-purpose +macros. M4sugar introduces additional generic macros. Its name was +coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4 +M4sugar''. + +@menu +* Redefined M4 Macros:: M4 builtins changed in M4sugar +* Forbidden Patterns:: Catching unexpanded macros +@end menu + +@node Redefined M4 Macros, Forbidden Patterns, Programming in M4sugar, Programming in M4sugar +@subsection Redefined M4 Macros + +All the M4 native macros are moved in the @samp{m4_} pseudo-namespace, +e.g., M4sugar renames @code{define} as @code{m4_define} etc. There is +one exception: @code{dnl} kept its original name, and no @code{m4_dnl} +is defined. + +M4sugar redefines some M4 macros, and made them slightly incompatible +with their native equivalent. + +@defmac m4_defn (@var{macro}) +@msindex defn +Contrary to the M4 builtin, this macro fails if @var{macro} is not +defined. See @code{m4_undefine}. +@end defmac + +@defmac m4_undefine (@var{macro}) +@msindex undefine +Contrary to the M4 builtin, this macro fails if @var{macro} is not +defined. Use + +@example +m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])]) +@end example + +@noindent +to recover the behavior of the builtin. +@end defmac + +@defmac m4_popdef (@var{macro}) +@msindex defn +Contrary to the M4 builtin, this macro fails if @var{macro} is not +defined. See @code{m4_undefine}. +@end defmac + +@node Forbidden Patterns, , Redefined M4 Macros, Programming in M4sugar +@subsection Forbidden Patterns + +M4sugar provides a means to define suspicious patterns, patterns +describing tokens which should not be found in the output. For +instance, if an Autoconf @file{configure} script includes tokens such as +@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went +wrong (typically a macro was not evaluated because of over quotation). + +M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}. + +@defmac m4_pattern_forbid (@var{pattern}) +@msindex pattern_forbid +Declare no token matching @var{pattern} must be found in the output. +Comments are not checked; this can be a problem if, for instance, you +have some macro left unexpanded after an @samp{#include}. No consensus +is currently found in the Autoconf community, as some people consider it +should be valid to name macros in comments (which doesn't makes sense to +the author of this documentation, as @samp{#}-comments should document +the output, not the input, documented vy @samp{dnl}-comments). +@end defmac + +Of course, you might encounter exceptions to these generic rules, for +instance you might have to refer to @samp{$m4_flags}. + +@defmac m4_pattern_allow (@var{pattern}) +@msindex pattern_allow +Any token matching @var{pattern} is allowed, including if it matches an +@code{m4_pattern_forbid} pattern. +@end defmac + +@c=================================================== Writing Autoconf Macros. + +@node Writing Autoconf Macros, Portable Shell, Programming in M4, Top +@chapter Writing Autoconf Macros + +When you write a feature test that could be applicable to more than one +software package, the best thing to do is encapsulate it in a new macro. +Here are some instructions and guidelines for writing Autoconf macros. + +@menu +* Macro Definitions:: Basic format of an Autoconf macro +* Macro Names:: What to call your new macros +* Reporting Messages:: Notifying @code{autoconf} users +* Dependencies Between Macros:: What to do when macros depend on other macros +* Obsoleting Macros:: Warning about old ways of doing things +* Coding Style:: Writing Autoconf macros @`a la Autoconf +@end menu + +@node Macro Definitions, Macro Names, Writing Autoconf Macros, Writing Autoconf Macros +@section Macro Definitions + +@maindex DEFUN +Autoconf macros are defined using the @code{AC_DEFUN} macro, which is +similar to the M4 builtin @code{define} macro. In addition to defining +a macro, @code{AC_DEFUN} adds to it some code that is used to constrain +the order in which macros are called (@pxref{Prerequisite Macros}). + +An Autoconf macro definition looks like this: + +@example +AC_DEFUN(@var{macro-name}, @var{macro-body}) +@end example + +You can refer to any arguments passed to the macro as @samp{$1}, +@samp{$2}, etc. @xref{Definitions,, How to define new macros, m4.info, +GNU m4}, for more complete information on writing M4 macros. + +Be sure to properly quote both the @var{macro-body} @emph{and} the +@var{macro-name} to avoid any problems if the macro happens to have +been previously defined. + +Each macro should have a header comment that gives its prototype, and a +brief description. When arguments have default values, display them in +the prototype. For example: + +@example +# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) +# -------------------------------------- +define([AC_MSG_ERROR], +[@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}]) +@end example + +Comments about the macro should be left in the header comment. Most +other comments will make their way into @file{configure}, so just keep +using @samp{#} to introduce comments. + +@cindex @code{dnl} +If you have some very special comments about pure M4 code, comments +that make no sense in @file{configure} and in the header comment, then +use the builtin @code{dnl}: it causes @code{m4} to discard the text +through the next newline. + +Keep in mind that @code{dnl} is rarely needed to introduce comments; +@code{dnl} is more useful to get rid of the newlines following macros +that produce no output, such as @code{AC_REQUIRE}. + + +@node Macro Names, Reporting Messages, Macro Definitions, Writing Autoconf Macros +@section Macro Names + +All of the Autoconf macros have all-uppercase names starting with +@samp{AC_} to prevent them from accidentally conflicting with other +text. All shell variables that they use for internal purposes have +mostly-lowercase names starting with @samp{ac_}. To ensure that your +macros don't conflict with present or future Autoconf macros, you should +prefix your own macro names and any shell variables they use with some +other sequence. Possibilities include your initials, or an abbreviation +for the name of your organization or software package. + +Most of the Autoconf macros' names follow a structured naming convention +that indicates the kind of feature check by the name. The macro names +consist of several words, separated by underscores, going from most +general to most specific. The names of their cache variables use the +same convention (@pxref{Cache Variable Names}, for more information on +them). + +The first word of the name after @samp{AC_} usually tells the category +of feature being tested. Here are the categories used in Autoconf for +specific test macros, the kind of macro that you are more likely to +write. They are also used for cache variables, in all-lowercase. Use +them where applicable; where they're not, invent your own categories. + +@table @code +@item C +C language builtin features. +@item DECL +Declarations of C variables in header files. +@item FUNC +Functions in libraries. +@item GROUP +@sc{unix} group owners of files. +@item HEADER +Header files. +@item LIB +C libraries. +@item PATH +The full path names to files, including programs. +@item PROG +The base names of programs. +@item MEMBER +Members of aggregates. +@item SYS +Operating system features. +@item TYPE +C builtin or declared types. +@item VAR +C variables in libraries. +@end table + +After the category comes the name of the particular feature being +tested. Any further words in the macro name indicate particular aspects +of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the +behavior of the @code{utime} function when called with a @code{NULL} +pointer. + +An internal macro should have a name that starts with an underscore; +Autoconf internals should therefore start with @samp{_AC_}. +Additionally, a macro that is an internal subroutine of another macro +should have a name that starts with an underscore and the name of that +other macro, followed by one or more words saying what the internal +macro does. For example, @code{AC_PATH_X} has internal macros +@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}. + +@node Reporting Messages, Dependencies Between Macros, Macro Names, Writing Autoconf Macros +@section Reporting Messages +@cindex Messages, from @code{autoconf} + +When macros statically diagnose abnormal situations, benign or fatal, +they should report them using these macros. For dynamic issues, i.e., +when @code{configure} is run, see @ref{Printing Messages}. + +@defmac AC_DIAGNOSE (@var{category}, @var{message}) +@maindex DIAGNOSE +Report @var{message} as a warning (or as an error if requested by the +user) if it falls into the @var{category}. You are encouraged to use +standard categories, which currently include: + +@table @samp +@item all +messages that don't fall into one of the following category. Use of an +empty @var{category} is equivalent. + +@item cross +related to cross compilation issues. + +@item obsolete +use of an obsolete construct. + +@item syntax +dubious syntactic constructs, incorrectly ordered macro calls. +@end table +@end defmac + +@defmac AC_WARNING (@var{message}) +@maindex WARNING +Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are +strongly encouraged to use a finer grained category. +@end defmac + +@defmac AC_FATAL (@var{message}) +@maindex FATAL +Report a severe error @var{message}, and have @code{autoconf} die. +@end defmac + +When the user runs @samp{autoconf -W error}, warnings from +@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see +@ref{autoconf Invocation}. + +@node Dependencies Between Macros, Obsoleting Macros, Reporting Messages, Writing Autoconf Macros +@section Dependencies Between Macros + +Some Autoconf macros depend on other macros having been called first in +order to work correctly. Autoconf provides a way to ensure that certain +macros are called if needed and a way to warn the user if macros are +called in an order that might cause incorrect operation. + +@menu +* Prerequisite Macros:: Ensuring required information +* Suggested Ordering:: Warning about possible ordering problems +@end menu + +@node Prerequisite Macros, Suggested Ordering, Dependencies Between Macros, Dependencies Between Macros +@subsection Prerequisite Macros + +A macro that you write might need to use values that have previously +been computed by other macros. For example, @code{AC_DECL_YYTEXT} +examines the output of @code{flex} or @code{lex}, so it depends on +@code{AC_PROG_LEX} having been called first to set the shell variable +@code{LEX}. + +Rather than forcing the user of the macros to keep track of the +dependencies between them, you can use the @code{AC_REQUIRE} macro to do +it automatically. @code{AC_REQUIRE} can ensure that a macro is only +called if it is needed, and only called once. + +@defmac AC_REQUIRE (@var{macro-name}) +@maindex REQUIRE +If the M4 macro @var{macro-name} has not already been called, call it +(without any arguments). Make sure to quote @var{macro-name} with +square brackets. @var{macro-name} must have been defined using +@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate +that it has been called. + +@code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it +must not be called from the top level. +@end defmac + +@code{AC_REQUIRE} is often misunderstood. It really implements +dependencies between macros in the sense that if one macro depends upon +another, the latter will be expanded @emph{before} the body of the +former. In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the +body of @code{FOO}. For instance, this definition of macros: + +@example +@group +AC_DEFUN([TRAVOLTA], +[test "$body_temparature_in_celsius" -gt "38" && + dance_floor=occupied]) +AC_DEFUN([NEWTON_JOHN], +[test "$hair_style" = "curly" && + dance_floor=occupied]) +@end group + +@group +AC_DEFUN([RESERVE_DANCE_FLOOR], +[if date | grep '^Sat.*pm' >/dev/null 2>&1; then + AC_REQUIRE([TRAVOLTA]) + AC_REQUIRE([NEWTON_JOHN]) +fi]) +@end group +@end example + +@noindent +with this @file{configure.ac} + +@example +AC_INIT +RESERVE_DANCE_FLOOR +if test "$dance_floor" = occupied; then + AC_MSG_ERROR([cannot pick up here, let's move]) +fi +@end example + +@noindent +will not leave you with a better chance to meet a kindred soul at +other times than Saturday night since it expands into: + +@example +@group +test "$body_temperature_in_Celsius" -gt "38" && + dance_floor=occupied +test "$hair_style" = "curly" && + dance_floor=occupied +fi +if date | grep '^Sat.*pm' >/dev/null 2>&1; then + + +fi +@end group +@end example + +This behavior was chosen on purpose: (i) it prevents messages in +required macros from interrupting the messages in the requiring macros; +(ii) it avoids bad surprises when shell conditionals are used, as in: + +@example +@group +if @dots{}; then + AC_REQUIRE([SOME_CHECK]) +fi +@dots{} +SOME_CHECK +@end group +@end example + + +You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a +macro. You can use @code{dnl} to avoid the empty lines they leave. + +@node Suggested Ordering, , Prerequisite Macros, Dependencies Between Macros +@subsection Suggested Ordering + +Some macros should be run before another macro if both are called, but +neither @emph{requires} that the other be called. For example, a macro +that changes the behavior of the C compiler should be called before any +macros that run the C compiler. Many of these dependencies are noted in +the documentation. + +Autoconf provides the @code{AC_BEFORE} macro to warn users when macros +with this kind of dependency appear out of order in a +@file{configure.ac} file. The warning occurs when creating +@code{configure} from @file{configure.ac}, not when running +@code{configure}. + +For example, @code{AC_PROG_CPP} checks whether the C compiler +can run the C preprocessor when given the @option{-E} option. It should +therefore be called after any macros that change which C compiler is +being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains: + +@example +AC_BEFORE([$0], [AC_PROG_CPP])dnl +@end example + +@noindent +This warns the user if a call to @code{AC_PROG_CPP} has already occurred +when @code{AC_PROG_CC} is called. + +@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) +@maindex BEFORE +Make @code{m4} print a warning message to the standard error output if +@var{called-macro-name} has already been called. @var{this-macro-name} +should be the name of the macro that is calling @code{AC_BEFORE}. The +macro @var{called-macro-name} must have been defined using +@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate +that it has been called. +@end defmac + +@node Obsoleting Macros, Coding Style, Dependencies Between Macros, Writing Autoconf Macros +@section Obsoleting Macros + +Configuration and portability technology has evolved over the years. +Often better ways of solving a particular problem are developed, or +ad-hoc approaches are systematized. This process has occurred in many +parts of Autoconf. One result is that some of the macros are now +considered @dfn{obsolete}; they still work, but are no longer considered +the best thing to do, hence they should be replaced with more modern +macros. Ideally, @code{autoupdate} should substitute the old macro calls +with their modern implementation. + +Autoconf provides a simple means to obsolete a macro. + +@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message}) +@maindex DEFUN +@maindex AU_DEFUN +Define @var{old-macro} as @var{implementation}. The only difference +with @code{AC_DEFUN} is that the user will be warned that +@var{old-macro} is now obsolete. + +If she then uses @code{autoupdate}, the call to @var{old-macro} will be +replaced by the modern @var{implementation}. The additional +@var{message} is then printed. +@end defmac + +@node Coding Style, , Obsoleting Macros, Writing Autoconf Macros +@section Coding Style + +The Autoconf macros follow a strict coding style. You are encouraged to +follow this style, especially if you intend to distribute your macro, +either by contributing it to Autoconf itself, or via other means. + +The first requirement is to pay great attention to the quotation, for +more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}. + +Do not try to invent new interfaces. It is likely that there is a macro +in Autoconf that resembles the macro you are defining: try to stick to +this existing interface (order of arguments, default values, etc.). We +@emph{are} conscious that some of these interfaces are not perfect; +nevertheless, when harmless, homogeneity should be preferred over +creativity. + +Be careful about clashes both between M4 symbols and between shell +variables. + +If you stick to the suggested M4 naming scheme (@pxref{Macro Names}), +you are unlikely to generate conflicts. Nevertheless, when you need to +set a special value, @emph{avoid using a regular macro name}; rather, +use an ``impossible'' name. For instance, up to version 2.13, the macro +@code{AC_SUBST} used to remember what @var{symbol}s were already defined +by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name. +But since there is a macro named @code{AC_SUBST_FILE}, it was just +impossible to @samp{AC_SUBST(FILE)}! In this case, +@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should +have been used (yes, with the parentheses)@dots{}or better yet, high-level +macros such as @code{AC_EXPAND_ONCE}. + +No Autoconf macro should ever enter the user-variable name space; i.e., +except for the variables that are the actual result of running the +macro, all shell variables should start with @code{ac_}. In +addition, small macros or any macro that is likely to be embedded in +other macros should be careful not to use obvious names. + +@cindex @code{dnl} +Do not use @code{dnl} to introduce comments: most of the comments you +are likely to write are either header comments which are not output +anyway, or comments that should make their way into @file{configure}. +There are exceptional cases where you do want to comment special M4 +constructs, in which case @code{dnl} is right, but keep in mind that it +is unlikely. + +M4 ignores the leading spaces before each argument, use this feature to +indent in such a way that arguments are (more or less) aligned with the +opening parenthesis of the macro being called. For instance, instead of + +@example +AC_CACHE_CHECK(for EMX OS/2 environment, +ac_cv_emxos2, +[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])], +[ac_cv_emxos2=yes], [ac_cv_emxos2=no])]) +@end example + +@noindent +write + +@example +AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], +[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) +@end example + +@noindent +or even + +@example +AC_CACHE_CHECK([for EMX OS/2 environment], + [ac_cv_emxos2], + [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], + [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) +@end example + +When using @code{AC_TRY_RUN} or any macro that cannot work when +cross-compiling, provide a pessimistic value (typically @samp{no}). + +Feel free to use various tricks to prevent auxiliary tools, such as +syntax-highlighting editors, from behaving improperly. For instance, +instead of: + +@example +patsubst([$1], [$"]) +@end example + +@noindent +use + +@example +patsubst([$1], [$""]) +@end example + +@noindent +so that Emacsen do not open a endless ``string'' at the first quote. +For the same reasons, avoid: + +@example +test $[#] != 0 +@end example + +@noindent +and use: + +@example +test $[@@%:@@] != 0 +@end example + +@noindent +Otherwise, the closing bracket would be hidden inside a @samp{#}-comment, +breaking the bracket-matching highlighting from Emacsen. Note the +preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do +not escape when it is unneeded. Common examples of useless quotation +are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}), +etc. If you add portability issues to the picture, you'll prefer +@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something +better than hacking Autoconf @code{:-)}. + +When using @command{sed}, don't use @option{-e} except for indenting +purpose. With the @code{s} command, the preferred separator is @samp{/} +unless @samp{/} itself is used in the command, in which case you should +use @samp{,}. + +@xref{Macro Definitions}, for details on how to define a macro. If a +macro doesn't use @code{AC_REQUIRE} and it is expected to never be the +object of an @code{AC_REQUIRE} directive, then use @code{define}. In +case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE} +statements should be at the beginning of the macro, @code{dnl}'ed. + +You should not rely on the number of arguments: instead of checking +whether an argument is missing, test that it is not empty. It provides +both a simpler and a more predictable interface to the user, and saves +room for further arguments. + +Unless the macro is short, try to leave the closing @samp{])} at the +beginning of a line, followed by a comment that repeats the name of the +macro being defined. This introduces an additional newline in +@code{configure}; normally, that is not a problem, but if you want to +remove it you can use @samp{[]dnl} on the last line. You can similarly +use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl} +is recommended instead of @samp{dnl} to ensure that M4 does not +interpret the @samp{dnl} as being attached to the preceding text or +macro output. For example, instead of: + +@example +AC_DEFUN([AC_PATH_X], +[AC_MSG_CHECKING([for X]) +AC_REQUIRE_CPP() +@r{# @dots{}omitted@dots{}} + AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) +fi]) +@end example + +@noindent +you would write: + +@example +AC_DEFUN([AC_PATH_X], +[AC_REQUIRE_CPP()[]dnl +AC_MSG_CHECKING([for X]) +@r{# @dots{}omitted@dots{}} + AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) +fi[]dnl +])# AC_PATH_X +@end example + +If the macro is long, try to split it into logical chunks. Typically, +macros that check for a bug in a function and prepare its +@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform +this setup. Do not hesitate to introduce auxiliary macros to factor +your code. + +In order to highlight the recommended coding style, here is a macro +written the old way: + +@example +dnl Check for EMX on OS/2. +dnl _AC_EMXOS2 +AC_DEFUN(_AC_EMXOS2, +[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, +[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], +ac_cv_emxos2=yes, ac_cv_emxos2=no)]) +test "$ac_cv_emxos2" = yes && EMXOS2=yes]) +@end example + +@noindent +and the new way: + +@example +# _AC_EMXOS2 +# ---------- +# Check for EMX on OS/2. +define([_AC_EMXOS2], +[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], +[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) +test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl +])# _AC_EMXOS2 +@end example + + + + +@c ============================================= Portable Shell Programming + +@node Portable Shell, Manual Configuration, Writing Autoconf Macros, Top +@chapter Portable Shell Programming + +When writing your own checks, there are some shell-script programming +techniques you should avoid in order to make your code portable. The +Bourne shell and upward-compatible shells like the Korn shell and Bash +have evolved over the years, but to prevent trouble, do not take +advantage of features that were added after @sc{unix} version 7, circa +1977. You should not use shell functions, aliases, negated character +classes, or other features that are not found in all Bourne-compatible +shells; restrict yourself to the lowest common denominator. Even +@code{unset} is not supported by all shells! Also, include a space +after the exclamation point in interpreter specifications, like this: + +@example +#! /usr/bin/perl +@end example + +@noindent +If you omit the space before the path, then 4.2@sc{bsd} based systems +(such as Sequent DYNIX) will ignore the line, because they interpret +@samp{#! /} as a 4-byte magic number. + +The set of external programs you should run in a @code{configure} script +is fairly small. @xref{Utilities in Makefiles,, Utilities in +Makefiles, standards, GNU Coding Standards}, for the list. This +restriction allows users to start out with a fairly small set of +programs and build the rest, avoiding too many interdependencies between +packages. + +Some of these external utilities have a portable subset of features; see +@ref{Limitations of Usual Tools}. + +@menu +* Shellology:: A zoology of shells +* Here-Documents:: Quirks and tricks +* File Descriptors:: FDs and redirections +* File System Conventions:: File- and pathnames +* Shell Substitutions:: Variable and command expansions +* Assignments:: Varying side effects of assignments +* Special Shell Variables:: Variables you should not change +* Limitations of Builtins:: Portable use of not so portable /bin/sh +* Limitations of Usual Tools:: Portable use of portable tools +* Limitations of Make:: Portable Makefiles +@end menu + +@node Shellology, Here-Documents, Portable Shell, Portable Shell +@section Shellology + +There are several families of shells, most prominently the Bourne +family and the C shell family which are deeply incompatible. If you +want to write portable shell scripts, avoid members of the C shell +family. + +Below we describe some of the members of the Bourne shell family. + +@table @asis +@item Ash +@cindex Ash +@command{ash} is often used on @sc{gnu}/Linux and @sc{bsd} systems as a +light-weight Bourne-compatible shell. Ash 0.2 has some bugs that are +fixed in the 0.3.x series, but portable shell scripts should workaround +them, since version 0.2 is still shipped with many @sc{gnu}/Linux +distributions. + +To be compatible with Ash 0.2: + +@itemize @minus +@item +don't use @samp{$?} after expanding empty or unset variables: + +@example +foo= +false +$foo +echo "Don't use it: $?" +@end example + +@item +don't use command substitution within variable expansion: + +@example +cat $@{FOO=`bar`@} +@end example + +@item +beware that single builtin substitutions are not performed by a sub +shell, hence their effect applies to the current shell! @xref{Shell +Substitutions}, item ``Command Substitution''. +@end itemize + +@item Bash +@cindex Bash +To detect whether you are running @command{bash}, test if +@code{BASH_VERSION} is set. To disable its extensions and require +@sc{posix} compatibility, run @samp{set -o posix}. @xref{Bash POSIX +Mode,, Bash @sc{posix} Mode, bash, The GNU Bash Reference Manual}, for +details. + +@item @command{/usr/xpg4/bin/sh} on Solaris +@cindex @command{/usr/xpg4/bin/sh} on Solaris +The @sc{posix}-compliant Bourne shell on a Solaris system is +@command{/usr/xpg4/bin/sh} and is part of an extra optional package. +There is no extra charge for this package, but it is also not part of a +minimal OS install and therefore some folks may not have it. + +@item Zsh +@cindex Zsh +To detect whether you are running @command{zsh}, test if +@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not} +compatible with the Bourne shell: you have to run @samp{emulate sh} and +set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility, +zsh, The Z Shell Manual}, for details. + +Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3. +@end table + +The following discussion between Russ Allbery and Robert Lipe is worth +reading: + +@noindent +Russ Allbery: + +@quotation +The @sc{gnu} assumption that @command{/bin/sh} is the one and only shell +leads to a permanent deadlock. Vendors don't want to break user's +existent shell scripts, and there are some corner cases in the Bourne +shell that are not completely compatible with a @sc{posix} shell. Thus, +vendors who have taken this route will @emph{never} (OK@dots{}``never say +never'') replace the Bourne shell (as @command{/bin/sh}) with a +@sc{posix} shell. +@end quotation + +@noindent +Robert Lipe: + +@quotation +This is exactly the problem. While most (at least most System V's) do +have a bourne shell that accepts shell functions most vendor +@command{/bin/sh} programs are not the @sc{posix} shell. + +So while most modern systems do have a shell _somewhere_ that meets the +@sc{posix} standard, the challenge is to find it. +@end quotation + +@node Here-Documents, File Descriptors, Shellology, Portable Shell +@section Here-Documents + +Don't rely on @samp{\} being preserved just because it has no special +meaning together with the next symbol. in the native @command{/bin/sh} +on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with +unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\} +use @samp{\\} to get @samp{\}. + +With OpenBSD 2.7's @command{/bin/sh} + +@example +@group +$ cat <<EOF +> \" \\ +> EOF +" \ +@end group +@end example + +@noindent +and with Bash: + +@example +@group +bash-2.04$ cat <<EOF +> \" \\ +> EOF +\" \ +@end group +@end example + + +Many older shells (including the Bourne shell) implement here-documents +inefficiently. Users can generally speed things up by using a faster +shell, e.g., by using the command @samp{bash ./configure} rather than +plain @samp{./configure}. + +Some shells can be extremely inefficient when there are a lot of +here-documents inside a single statement. For instance if your +@file{configure.ac} includes something like: + +@example +@group +if <cross_compiling>; then + assume this and that +else + check this + check that + check something else + @dots{} + on and on forever + @dots{} +fi +@end group +@end example + +A shell parses the whole @code{if}/@code{fi} construct, creating +temporary files for each here document in it. Some shells create links +for such here-documents on every @code{fork}, so that the clean-up code +they had installed correctly removes them. It is creating the links +that the shell can take forever. + +Moving the tests out of the @code{if}/@code{fi}, or creating multiple +@code{if}/@code{fi} constructs, would improve the performance +significantly. Anyway, this kind of construct is not exactly the +typical use of Autoconf. In fact, it's even not recommended, because M4 +macros can't look into shell conditionals, so we may fail to expand a +macro when it was expanded before in a conditional path, and the +condition turned out to be false at run-time, and we end up not +executing the macro at all. + +@node File Descriptors, File System Conventions, Here-Documents, Portable Shell +@section File Descriptors + +Some file descriptors shall not be used, since some systems, admittedly +arcane, use them for special purpose: + +@table @asis +@item 3 +some systems may open it to @samp{/dev/tty}. + +@item 4 +used on the Kubota Titan. +@end table + +Don't redirect several times the same file descriptor, as you are doomed +to failure under Ultrix. + +@example +ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 +UWS V4.4 (Rev. 11) +$ eval 'echo matter >fullness' >void +illegal io +$ eval '(echo matter >fullness)' >void +illegal io +$ (eval '(echo matter >fullness)') >void +Ambiguous output redirect. +@end example + +@noindent +In each case the expected result is of course @file{fullness} containing +@samp{matter} and @file{void} being empty. + +Don't try to redirect the standard error of a command substitution: it +must be done @emph{inside} the command substitution: when running +@samp{: `cd /zorglub` 2>/dev/null} expect the error message to +escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly. + +It is worth noting that Zsh (but not Ash nor Bash) makes it possible +in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}. + +Most shells, if not all (including Bash, Zsh, Ash), output traces on +stderr, even for sub-shells. This might result in undesired content +if you meant to capture the standard-error output of the inner command: + +@example +$ ash -x -c '(eval "echo foo >&2") 2>stderr' +$ cat stderr ++ eval echo foo >&2 ++ echo foo +foo +$ bash -x -c '(eval "echo foo >&2") 2>stderr' +$ cat stderr ++ eval 'echo foo >&2' +++ echo foo +foo +$ zsh -x -c '(eval "echo foo >&2") 2>stderr' +@i{# Traces on startup files deleted here.} +$ cat stderr ++zsh:1> eval echo foo >&2 ++zsh:1> echo foo +foo +@end example + +@noindent +You'll appreciate the various levels of detail@dots{} + +One workaround is to grep out uninteresting lines, hoping not to remove +good ones@dots{} + +@node File System Conventions, Shell Substitutions, File Descriptors, Portable Shell +@section File System Conventions + +While @command{autoconf} and friends will usually be run on some Unix +variety, it can and will be used on other systems, most notably @sc{dos} +variants. This impacts several assumptions regarding file and +path names. + +@noindent +For example, the following code: + +@example +case $foo_dir in + /*) # Absolute + ;; + *) + foo_dir=$dots$foo_dir ;; +esac +@end example + +@noindent +will fail to properly detect absolute paths on those systems, because +they can use a drivespec, and will usually use a backslash as directory +separator. The canonical way to check for absolute paths is: + +@example +case $foo_dir in + [\\/]* | ?:[\\/]* ) # Absolute + ;; + *) + foo_dir=$dots$foo_dir ;; +esac +@end example + +@noindent +Make sure you quote the brackets if appropriate and keep the backslash as +first character (@pxref{Limitations of Builtins}). + +Also, because the colon is used as part of a drivespec, these systems don't +use it as path separator. When creating or accessing paths, use +@code{$ac_path_separator} instead (or the @code{PATH_SEPARATOR} output +variable). @command{autoconf} sets this to the appropriate value (@samp{:} +or @samp{;}) when it starts up. + +File names need extra care as well. While @sc{dos}-based environments +that are Unixy enough to run @command{autoconf} (such as DJGPP) will +usually be able to handle long file names properly, there are still +limitations that can seriously break packages. Several of these issues +can be easily detected by the +@href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk} +package. + +A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to +indicate where they apply: @sc{sfn} means the issues are only relevant to +plain @sc{dos}, not to @sc{dos} boxes under Windows, while @sc{lfn} +identifies problems that exist even under Windows. + +@table @asis +@item No multiple dots (@sc{sfn}) +@sc{dos} cannot handle multiple dots in filenames. This is an especially +important thing to remember when building a portable configure script, +as @command{autoconf} uses a .in suffix for template files. + +This is perfectly OK on Unices: + +@example +AC_CONFIG_HEADER(config.h) +AC_CONFIG_FILES([source.c foo.bar]) +AC_OUTPUT +@end example + +@noindent +but it causes problems on @sc{dos}, as it requires @samp{config.h.in}, +@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable +to @sc{dos}-based environments, you should use this instead: + +@example +AC_CONFIG_HEADER(config.h:config.hin) +AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) +AC_OUTPUT +@end example + +@item No leading dot (@sc{sfn}) +@sc{dos} cannot handle filenames that start with a dot. This is usually +not a very important issue for @command{autoconf}. + +@item Case insensitivity (@sc{lfn}) +@sc{dos} is case insensitive, so you cannot, for example, have both a +file called @samp{INSTALL} and a directory called @samp{install}. This +also affects @command{make}; if there's a file called @samp{INSTALL} in +the directory, @command{make install} will do nothing (unless the +@samp{install} target is marked as PHONY). + +@item The 8+3 limit (@sc{sfn}) +Because the @sc{dos} file system only stores the first 8 characters of +the filename and the first 3 of the extension, those must be unique. +That means that @file{foobar-part1.c}, @file{foobar-part2.c} and +@file{foobar-prettybird.c} all resolve to the same filename +(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and +@file{foo.bartender}. + +Note: This is not usually a problem under Windows, as it uses numeric +tails in the short version of filenames to make them unique. However, a +registry setting can turn this behaviour off. While this makes it +possible to share file trees containing long file names between @sc{sfn} +and @sc{lfn} environments, it also means the above problem applies there +as well. + +@item Invalid characters +Some characters are invalid in @sc{dos} filenames, and should therefore +be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\}, +@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}. +In a @sc{sfn} environment, other characters are also invalid. These +include @samp{+}, @samp{,}, @samp{[} and @samp{]}. +@end table + +@node Shell Substitutions, Assignments, File System Conventions, Portable Shell +@section Shell Substitutions + +Contrary to a persistent urban legend, the Bourne shell does not +systematically split variables and backquoted expressions, in particular +on the right-hand side of assignments and in the argument of @code{case}. +For instance, the following code: + +@example +case "$given_srcdir" in +.) top_srcdir="`echo "$dots" | sed 's,/$,,'`" +*) top_srcdir="$dots$given_srcdir" ;; +esac +@end example + +@noindent +is more readable when written as: + +@example +case $given_srcdir in +.) top_srcdir=`echo "$dots" | sed 's,/$,,'` +*) top_srcdir=$dots$given_srcdir ;; +esac +@end example + +@noindent +and in fact it is even @emph{more} portable: in the first case of the +first attempt, the computation of @code{top_srcdir} is not portable, +since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}. +Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"} +the same way. There is just no portable way to use double-quoted +strings inside double-quoted backquoted expressions (pfew!). + +@table @code +@item $@@ +@cindex @samp{"$@@"} +One of the most famous shell-portability issues is related to +@samp{"$@@"}: when there are no positional arguments, it is supposed to +be equivalent to nothing. But some shells, for instance under Digital +Unix 4.0 and 5.0, will then replace it with an empty argument. To be +portable, use @samp{$@{1+"$@@"@}}. + +@item $@{@var{var}:-@var{value}@} +@cindex $@{@var{var}:-@var{value}@} +Old @sc{bsd} shells, including the Ultrix @code{sh}, don't accept the +colon for any shell substitution, and complain and die. + +@item $@{@var{var}=@var{literal}@} +@cindex $@{@var{var}=@var{literal}@} +Be sure to quote: + +@example +: $@{var='Some words'@} +@end example + +@noindent +otherwise some shells, such as on Digital Unix V 5.0, will die because +of a ``bad substitution''. + +Solaris' @command{/bin/sh} has a frightening bug in its interpretation +of this. Imagine you need set a variable to a string containing +@samp{@}}. This @samp{@}} character confuses Solaris' @command{/bin/sh} +when the affected variable was already set. This bug can be exercised +by running: + +@example +$ unset foo +$ foo=$@{foo='@}'@} +$ echo $foo +@} +$ foo=$@{foo='@}' # no error; this hints to what the bug is +$ echo $foo +@} +$ foo=$@{foo='@}'@} +$ echo $foo +@}@} + ^ ugh! +@end example + +It seems that @samp{@}} is interpreted as matching @samp{$@{}, even +though it is enclosed in single quotes. The problem doesn't happen +using double quotes. + +@item $@{@var{var}=@var{expanded-value}@} +@cindex $@{@var{var}=@var{expanded-value}@} +On Ultrix, +running + +@example +default="yu,yaa" +: $@{var="$default"@} +@end example + +@noindent +will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of +each char will be set. You won't observe the phenomenon using a simple +@samp{echo $var} since apparently the shell resets the 8th bit when it +expands $var. Here are two means to make this shell confess its sins: + +@example +$ cat -v <<EOF +$var +EOF +@end example + +@noindent +and + +@example +$ set | grep '^var=' | cat -v +@end example + +One classic incarnation of this bug is: + +@example +default="a b c" +: $@{list="$default"@} +for c in $list; do + echo $c +done +@end example + +@noindent +You'll get @samp{a b c} on a single line. Why? Because there are no +spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th +bit set, hence no IFS splitting is performed!!! + +One piece of good news is that Ultrix works fine with @samp{: +$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is +then that @sc{qnx} 4.25 then sets @var{list} to the @emph{last} item of +@var{default}! + +The portable way out consists in using a double assignment, to switch +the 8th bit twice on Ultrix: + +@example +list=$@{list="$default"@} +@end example + +@noindent +@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety, +use: + +@example +test "$@{var+set@}" = set || var=@var{@{value@}} +@end example + + +@item `@var{commands}` +@cindex `@var{commands}` +@cindex Command Substitution +While in general it makes no sense, do not substitute a single builtin +with side effects as Ash 0.2, trying to optimize, does not fork a +sub-shell to perform the command. + +For instance, if you wanted to check that @command{cd} is silent, do not +use @samp{test -z "`cd /`"} because the following can happen: + +@example +$ pwd +/tmp +$ test -n "`cd /`" && pwd +/ +@end example + +@noindent +The result of @samp{foo=`exit 1`} is left as an exercise to the reader. + + +@item $(@var{commands}) +@cindex $(@var{commands}) +This construct is meant to replace @samp{`@var{commands}`}; they can be +nested while this is impossible to do portably with back quotes. +Unfortunately it is not yet widely supported. Most notably, even recent +releases of Solaris don't support it: + +@example +$ showrev -c /bin/sh | grep version +Command version: SunOS 5.8 Generic 109324-02 February 2001 +$ echo $(echo blah) +syntax error: `(' unexpected +@end example + +@noindent +nor does @sc{irix} 6.5's Bourne shell: +@example +$ uname -a +IRIX firebird-image 6.5 07151432 IP22 +$ echo $(echo blah) +$(echo blah) +@end example +@end table + + +@node Assignments, Special Shell Variables, Shell Substitutions, Portable Shell +@section Assignments + +When setting several variables in a row, be aware that the order of the +evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo} +gives @samp{1} with sh on Solaris, but @samp{2} with Bash. You must use +@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}. + +Don't rely on the exit status of an assignment: Ash 0.2 does not change +the status and propagates that of the last statement: + +@example +$ false || foo=bar; echo $? +1 +$ false || foo=`:`; echo $? +0 +@end example + +@noindent +and to make things even worse, @sc{qnx 4.25} just sets the exit status +to 0 in any case: + +@example +$ foo=`exit 1`; echo $? +0 +@end example + +To assign default values, follow this algorithm: + +@enumerate +@item +If the default value is a literal and does not contain any closing +brace, use: + +@example +: $@{var='my literal'@} +@end example + +@item +If the default value contains no closing brace, has to be expanded, and +the variable being initialized will never be IFS-split (i.e., it's not a +list), then use: + +@example +: $@{var="$default"@} +@end example + +@item +If the default value contains no closing brace, has to be expanded, and +the variable being initialized will be IFS-split (i.e., it's a list), +then use: + +@example +var=$@{var="$default"@} +@end example + +@item +If the default value contains a closing brace, then use: + +@example +test "$@{var+set@}" = set || var='$@{indirection@}' +@end example +@end enumerate + +In most cases @samp{var=$@{var="$default"@}} is fine, but in case of +doubt, just use the latter. @xref{Shell Substitutions}, items +@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}} +for the rationale. + + +@node Special Shell Variables, Limitations of Builtins, Assignments, Portable Shell +@section Special Shell Variables + +Some shell variables should not be used, since they can have a deep +influence on the behavior of the shell. In order to recover a sane +behavior from the shell, some variables should be unset, but +@command{unset} is not portable (@pxref{Limitations of Builtins}) and a +fallback value is needed. We list these values below. + +@c Alphabetical order, case insensitive, `A' before `a'. +@table @code +@item CDPATH +@evindex CDPATH +When this variable is set @code{cd} is verbose, so idioms such as +@samp{abs=`cd $rel && pwd`} break because @code{abs} receives the path +twice. + +@c FIXME: Which shells? How do they behave? +Setting @code{CDPATH} to the empty value is not enough for most shells. +A simple colon is enough except for @code{zsh}, which prefers a leading +dot: + +@example +zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo) +/tmp/foo +zsh-3.1.6 % (CDPATH=:. cd foo) +/tmp/foo +zsh-3.1.6 % (CDPATH=.: cd foo) +zsh-3.1.6 % +@end example + +@noindent +(of course we could just @code{unset} @code{CDPATH}, since it also +behaves properly if set to the empty string). + +Life wouldn't be so much fun if @command{bash} and @command{zsh} had the +same behavior: + +@example +bash-2.02 % (CDPATH=:. cd foo) +bash-2.02 % (CDPATH=.: cd foo) +/tmp/foo +@end example + +Therefore, a portable solution to neutralize @samp{CDPATH} is + +@example +CDPATH=$@{ZSH_VERSION+.@}: +@end example + +@noindent +Note that since @command{zsh} supports @command{unset}, you may unset +@samp{CDPATH} using @samp{:} as a fallback, see +@ref{Limitations of Builtins}. + +@item IFS +@evindex IFS +Don't set the first character of @code{IFS} to backslash. Indeed, +Bourne shells use the first character (backslash) when joining the +components in @samp{"$@@"} and some shells then re-interpret (!) the +backslash escapes, so you can end up with backspace and other strange +characters. + +@item LANG +@itemx LC_ALL +@itemx LC_TIME +@itemx LC_CTYPE +@itemx LANGUAGE +@itemx LC_COLLATE +@itemx LC_NUMERIC +@itemx LC_MESSAGES +@evindex LANG +@evindex LC_ALL +@evindex LC_TIME +@evindex LC_CTYPE +@evindex LANGUAGE +@evindex LC_COLLATE +@evindex LC_NUMERIC +@evindex LC_MESSAGES + +These must not be set unconditionally because not all systems understand +e.g. @samp{LANG=C} (notably SCO). Fixing @env{LC_MESSAGES} prevents +Solaris @command{sh} from translating var values in @code{set}! Non-C +@env{LC_CTYPE} values break the ctype check. Fixing @env{LC_COLLATE} +makes scripts more portable in some cases. For example, it causes the +regular expression @samp{[a-z]} to match only lower-case letters on +@sc{ascii} platforms. However, @samp{[a-z]} does not work in general +even when @env{LC_COLLATE} is fixed; for example, it does not work for +@sc{ebcdic} platforms. For maximum portability, you should use regular +expressions like @samp{[abcdefghijklmnopqrstuvwxyz]} that list +characters explicitly instead of relying on ranges. + +@emph{If} one of these variables is set, you should try to unset it, +using @samp{C} as a fall back value. see @ref{Limitations of Builtins}, +builtin @command{unset}, for more details. + +@item NULLCMD +@evindex NULLCMD +When executing the command @samp{>foo}, @command{zsh} executes +@samp{$NULLCMD >foo}. The Bourne shell considers @code{NULLCMD} is +@samp{:}, while @command{zsh}, even in Bourne shell compatibility mode, +sets @code{NULLCMD} to @samp{cat}. If you forgot to set @code{NULLCMD}, +your script might be suspended waiting for data on its standard input. + +@item status +@evindex status +This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6), +hence read-only. Do not use it. + +@item PATH_SEPARATOR +@evindex PATH_SEPARATOR +On DJGPP systems, the @code{PATH_SEPARATOR} variable can be set to +either @samp{:} or @samp{;} to control the path separator @command{bash} +uses to set up certain environment variables (such as +@code{PATH}). Since this only works inside bash, you want autoconf to +detect the regular @sc{dos} path separator @samp{;}, so it can be safely +substituted in files that may not support @samp{;} as path separator. So +either unset this variable or set it to @samp{;}. + +@item RANDOM +@evindex RANDOM +Many shells provide @code{RANDOM}, a variable that returns a different +integer when used. Most of the time, its value does not change when it +is not used, but on @sc{irix 6.5} the value changes all the time. This +can be observed by using @command{set}. +@end table + + +@node Limitations of Builtins, Limitations of Usual Tools, Special Shell Variables, Portable Shell +@section Limitations of Shell Builtins + +No, no, we are serious: some shells do have limitations! :) + +You should always keep in mind that any built-in or command may support +options, and therefore have a very different behavior with arguments +starting with a dash. For instance, the innocent @samp{echo "$word"} +can give unexpected results when @code{word} starts with a dash. It is +often possible to avoid this problem using @samp{echo "x$word"}, taking +the @samp{x} into account later in the pipe. + +@table @asis +@item @command{!} +@cindex @command{!} +You can't use @command{!}, you'll have to rewrite your code. + + +@item @command{break} +@c ------------------ +@cindex @command{break} +The use of @samp{break 2}, etcetera, is safe. + + +@item @command{case} +@c ----------------- +@cindex @command{case} +You don't need to quote the argument; no splitting is performed. + +You don't need the final @samp{;;}, but you should use it. + +Because of a bug in its @code{fnmatch}, @command{bash} fails to properly +handle backslashes in character classes: + +@example +bash-2.02$ case /tmp in [/\\]*) echo OK;; esac +bash-2.02$ +@end example + +@noindent +This is extremely unfortunate, since you are likely to use this code to +handle @sc{unix} or @sc{ms-dos} absolute paths. To work around this +bug, always put the backslash first: + +@example +bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac +OK +bash-2.02$ case /tmp in [\\/]*) echo OK;; esac +OK +@end example + + +@item @command{echo} +@c ----------------- +@cindex @command{echo} +The simple @code{echo} is probably the most surprising source of +portability troubles. It is not possible to use @samp{echo} portably +unless both options and escape sequences are omitted. New applications +which are not aiming at portability should use @samp{printf} instead of +@samp{echo}. + +Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N} +etc. for a means to simulate @option{-c}. + +Do not use backslashes in the arguments, as there is no consensus on +their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of +Digital Unix 4.0, @sc{mips risc/os} 4.52, answer 2, but the Solaris' +@command{sh}, Bash and Zsh (in @command{sh} emulation mode) report 1. +Please note that the problem is truly @command{echo}: all the shells +understand @samp{'\n'} as the string composed of a backslash and an +@samp{n}. + +Because of these problems, do not pass a string containing arbitrary +characters to @command{echo}. For example, @samp{echo "$foo"} is safe +if you know that @var{foo}'s value cannot contain backslashes and cannot +start with @samp{-}, but otherwise you should use a here-document like +this: + +@example +cat <<EOF +$foo +EOF +@end example + + +@item @command{exit} +@c ----------------- +@cindex @command{exit} +The default value of @command{exit} is supposed to be @code{$?}; +unfortunately, some shells, such as the DJGPP port of Bash 2.04, just +perform @samp{exit 0}. + +@example +bash-2.04$ foo=`exit 1` || echo fail +fail +bash-2.04$ foo=`(exit 1)` || echo fail +fail +bash-2.04$ foo=`(exit 1); exit` || echo fail +bash-2.04$ +@end example + +Using @samp{exit $?} restores the expected behavior. + +Some shell scripts, such as those generated by @command{autoconf}, use a +trap to clean up before exiting. If the last shell command exited with +nonzero status, the trap also exits with nonzero status so that the +invoker can tell that an error occurred. + +Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit +trap ignores the @code{exit} command's status. In these shells, a trap +cannot determine whether it was invoked by plain @code{exit} or by +@code{exit 1}. Instead of calling @code{exit} directly, use the +@code{AC_MSG_ERROR} macro that has a workaround for this problem. + + +@item @command{export} +@c ------------------- +@cindex @command{export} +The builtin @command{export} dubs @dfn{environment variable} a shell +variable. Each update of exported variables corresponds to an update of +the environment variables. Conversely, each environment variable +received by the shell when it is launched should be imported as a shell +variable marked as exported. + +Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5 +and DU 4.0, forget to @command{export} the environment variables they +receive. As a result, two variables are coexisting: the environment +variable and the shell variable. The following code demonstrates this +failure: + +@example +#! /bin/sh +echo $FOO +FOO=bar +echo $FOO +exec /bin/sh $0 +@end example + +@noindent +when run with @samp{FOO=foo} in the environment, these shells will print +alternately @samp{foo} and @samp{bar}, although it should only print +@samp{foo} and then a sequence of @samp{bar}s. + +Therefore you should @command{export} again each environment variable +that you update. + + +@item @command{false} +@c ------------------ +@cindex @command{false} +Don't expect @command{false} to exit with status 1: in the native Bourne +shell of Solaris 8, it exits with status 255. + + +@item @command{for} +@c ---------------- +@cindex @command{for} +To loop over positional arguments, use: + +@example +for arg +do + echo "$arg" +done +@end example + +@noindent +You may @emph{not} leave the @code{do} on the same line as @code{for}, +since some shells improperly grok: + +@example +for arg; do + echo "$arg" +done +@end example + +If you want to explicitly refer to the positional arguments, given the +@samp{$@@} bug (@pxref{Shell Substitutions}), use: + +@example +for arg in $@{1+"$@@"@}; do + echo "$arg" +done +@end example + +@item @command{if} +@c --------------- +@cindex @command{if} +Using @samp{!} is not portable. Instead of: + +@example +if ! cmp -s file file.new; then + mv file.new file +fi +@end example + +@noindent +use: + +@example +if cmp -s file file.new; then :; else + mv file.new file +fi +@end example + +There are shells that do not reset the exit status from an @command{if}: + +@example +$ if (exit 42); then true; fi; echo $? +42 +@end example + +@noindent +whereas a proper shell should have printed @samp{0}. This is especially +bad in Makefiles since it produces false failures. This is why properly +written Makefiles, such as Automake's, have such hairy constructs: + +@example +if test -f "$file"; then + install "$file" "$dest" +else + : +fi +@end example + + +@item @command{set} +@c ---------------- +@cindex @command{set} +This builtin faces the usual problem with arguments starting with a +dash. Modern shells such as Bash or Zsh understand @option{--} to specify +the end of the options (any argument after @option{--} is a parameters, +even @samp{-x} for instance), but most shells simply stop the option +processing as soon as a non-option argument is found. Therefore, use +@samp{dummy} or simply @samp{x} to end the option processing, and use +@command{shift} to pop it out: + +@example +set x $my_list; shift +@end example + +@item @command{shift} +@c ------------------ +@cindex @command{shift} +Not only is @command{shift}ing a bad idea when there is nothing left to +shift, but in addition it is not portable: the shell of @sc{mips +risc/os} 4.52 refuses to do it. + +@item @command{test} +@c ----------------- +@cindex @command{test} +The @code{test} program is the way to perform many file and string +tests. It is often invoked by the alternate name @samp{[}, but using +that name in Autoconf code is asking for trouble since it is an M4 quote +character. + +If you need to make multiple checks using @code{test}, combine them with +the shell operators @samp{&&} and @samp{||} instead of using the +@code{test} operators @option{-a} and @option{-o}. On System V, the +precedence of @option{-a} and @option{-o} is wrong relative to the unary +operators; consequently, @sc{posix} does not specify them, so using them +is nonportable. If you combine @samp{&&} and @samp{||} in the same +statement, keep in mind that they have equal precedence. + +You may use @samp{!} with @command{test}, but not with @command{if}: +@samp{test ! -r foo || exit 1}. + +@item @command{test} (files) +@c ------------------------- +To enable @code{configure} scripts to support cross-compilation, they +shouldn't do anything that tests features of the build system instead of +the host system. But occasionally you may find it necessary to check +whether some arbitrary file exists. To do so, use @samp{test -f} or +@samp{test -r}. Do not use @samp{test -x}, because @sc{4.3bsd} does not +have it. Do not use @samp{test -e} either, because Solaris 2.5 does not +have it. + +@item @command{test} (strings) +@c --------------------------- +Avoid @samp{test "@var{string}"}, in particular if @var{string} might +start with a dash, since @code{test} might interpret its argument as an +option (e.g., @samp{@var{string} = "-n"}). + +Contrary to a common belief, @samp{test -n @var{string}} and @samp{test +-z @var{string}} @strong{are} portable, nevertheless many shells (such +as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have +bizarre precedence and may be confused if @var{string} looks like an +operator: + +@example +$ test -n = +test: argument expected +@end example + +If there are risks, use @samp{test "x@var{string}" = x} or @samp{test +"x@var{string}" != x} instead. + +It is frequent to find variations of the following idiom: + +@example +test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && + @var{action} +@end example + +@noindent +to take an action when a token matches a given pattern. Such constructs +should always be avoided by using: + +@example +echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 && + @var{action} +@end example + +@noindent +Use @code{case} where possible since it is faster, being a shell builtin: + + +@example +case $ac_feature in + *[!-a-zA-Z0-9_]*) @var{action};; +esac +@end example + +Alas, negated character classes are probably not portable, although no +shell is known to not support the @sc{posix.2} syntax @samp{[!@dots{}]} +(when in interactive mode, @command{zsh} is confused by the +@samp{[!@dots{}]} syntax and looks for an event in its history because of +@samp{!}). Many shells do not support the alternative syntax +@samp{[^@dots{}]} (Solaris, Digital Unix, etc.). + +One solution can be: + +@example +expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && + @var{action} +@end example + +@noindent +or better yet + +@example +expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && + @var{action} +@end example + +@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo +"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when +@samp{@var{foo}} contains backslashes. + + +@item @command{trap} +@c ----------------- +@cindex @command{trap} +It is safe to trap at least the signals 1, 2, 13 and 15. You can also +trap 0, i.e., have the @command{trap} run when the script ends (either via an +explicit @command{exit}, or the end of the script). + +Although @sc{posix} is not absolutely clear on this point, it is widely +admitted that when entering the trap @samp{$?} should be set to the exit +status of the last command run before the trap. The ambiguity can be +summarized as: ``when the trap is launched by an @command{exit}, what is +the @emph{last} command run: that before @command{exit}, or +@command{exit} itself?'' + +Bash considers @command{exit} to be the last command, while Zsh and +Solaris 8 @command{sh} consider that when the trap is run it is +@emph{still} in the @command{exit}, hence it is the previous exit status +that the trap receives: + +@example +$ cat trap.sh +trap 'echo $?' 0 +(exit 42); exit 0 +$ zsh trap.sh +42 +$ bash trap.sh +0 +@end example + +The portable solution is then simple: when you want to @samp{exit 42}, +run @samp{(exit 42); exit 42}, the first @command{exit} being used to +set the exit status to 42 for Zsh, and the second to trigger the trap +and pass 42 as exit status for Bash. + +The shell in FreeBSD 4.0 has the following bug: @samp{$?} is reset to 0 +by empty lines if the code is inside @command{trap}. + +@example +$ trap 'false + +echo $?' 0 +$ exit +0 +@end example + +@noindent +Fortunately, this bug only affects @command{trap}. + +@item @command{true} +@c ----------------- +@cindex @command{true} +@cindex @command{:} +Don't worry: as far as we know @command{true} is portable. +Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the +portable shell community tends to prefer using @command{:}. This has a +funny side effect: when asked whether @command{false} is more portable +than @command{true} Alexandre Oliva answered: + +@quotation +In a sense, yes, because if it doesn't exist, the shell will produce an +exit status of failure, which is correct for @command{false}, but not +for @command{true}. +@end quotation + + +@item @command{unset} +@c ------------------ +@cindex @command{unset} +You cannot assume the support of @command{unset}, nevertheless, because +it is extremely useful to disable embarrassing variables such as +@code{CDPATH} or @code{LANG}, you can test for its existence and use +it @emph{provided} you give a neutralizing value when @command{unset} is +not supported: + +@example +if (unset FOO) >/dev/null 2>&1; then + unset=unset +else + unset=false +fi +$unset CDPATH || CDPATH=: +@end example + +@xref{Special Shell Variables}, for some neutralizing values. Also, see +@ref{Limitations of Builtins}, documentation of @command{export}, for +the case of environment variables. +@end table + +@node Limitations of Usual Tools, Limitations of Make, Limitations of Builtins, Portable Shell +@section Limitations of Usual Tools + +The small set of tools you can expect to find on any machine can still +include some limitations you should be aware of. + +@table @asis +@item @command{awk} +@c ---------------- +@cindex @command{awk} +Don't leave white spaces before the parentheses in user functions calls, +@sc{gnu} awk will reject it: + +@example +$ gawk 'function die () @{ print "Aaaaarg!" @} + BEGIN @{ die () @}' +gawk: cmd. line:2: BEGIN @{ die () @} +gawk: cmd. line:2: ^ parse error +$ gawk 'function die () @{ print "Aaaaarg!" @} + BEGIN @{ die() @}' +Aaaaarg! +@end example + +If you want your program to be deterministic, don't depend on @code{for} +on arrays: + +@example +$ cat for.awk +END @{ + arr["foo"] = 1 + arr["bar"] = 1 + for (i in arr) + print i +@} +$ gawk -f for.awk </dev/null +foo +bar +$ nawk -f for.awk </dev/null +bar +foo +@end example + +Some AWK, such as HPUX 11.0's native one, have regex engines fragile to +inner anchors: + +@example +$ echo xfoo | $AWK '/foo|^bar/ @{ print @}' +$ echo bar | $AWK '/foo|^bar/ @{ print @}' +bar +$ echo xfoo | $AWK '/^bar|foo/ @{ print @}' +xfoo +$ echo bar | $AWK '/^bar|foo/ @{ print @}' +bar +@end example + +@noindent +Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/}, +or use a simple test to reject such AWK. + + +@item @command{cat} +@c ---------------- +@cindex @command{cat} +Don't rely on any option. The option @option{-v}, which displays +non-printing characters, @emph{seems} portable, though. + + +@item @command{cc} +@c --------------- +When a compilation such as @samp{cc foo.c -o foo} fails, some compilers +(such as @sc{cds} on Reliant @sc{unix}) leave a @file{foo.o}. + + +@item @command{cmp} +@c ---------------- +@cindex @command{cmp} +@command{cmp} performs a raw data comparison of two files, while +@command{diff} compares two text files. Therefore, if you might compare +DOS files, even if only checking whether two files are different, use +@command{diff} to avoid spurious differences due to differences of +newline encoding. + + +@item @command{cp} +@c --------------- +@cindex @command{cp} +@c This is thanks to Ian. +SunOS @command{cp} does not support @option{-f}, although its +@command{mv} does. It's possible to deduce why @command{mv} and +@command{cp} are different with respect to @option{-f}. @command{mv} +prompts by default before overwriting a read-only file. @command{cp} +does not. Therefore, @command{mv} requires a @option{-f} option, but +@command{cp} does not. @command{mv} and @command{cp} behave differently +with respect to read-only files because the simplest form of +@command{cp} cannot overwrite a read-only file, but the simplest form of +@command{mv} can. This is because @command{cp} opens the target for +write access, whereas @command{mv} simply calls @code{link} (or, in +newer systems, @code{rename}). +@c Ian said: ``I don't think -p or -r are portable''!!! How can you live +@c without -r??? + + +@item @command{diff} +@c ----------------- +@cindex @command{diff} +Option @option{-u} is nonportable. + +Some implementations, such as Tru64's, fail when comparing to +@file{/dev/null}. Use an empty file instead. + +@item @command{dirname} +@c -------------------- +@cindex @command{dirname} +Not all hosts have @command{dirname}, but it is reasonably easy to +emulate, e.g.: + +@example +dir=`expr "x$file" : 'x\(.*\)/[^/]*' \| + '.' : '.' +@end example + +@noindent +But there are a few subtilities, e.g., under UN*X, should @samp{//1} +give @samp{/}? Paul Eggert answers: + +@quotation +No, under some older flavors of Unix, leading @samp{//} is a special +path name: it refers to a ``super-root'' and is used to access other +machines' files. Leading @samp{///}, @samp{////}, etc. are equivalent +to @samp{/}; but leading @samp{//} is special. I think this tradition +started with Apollo Domain/OS, an OS that is still in use on some older +hosts. + +POSIX.2 allows but does not require the special treatment for @samp{//}. +It says that the behavior of dirname on path names of the form +@samp{//([^/]+/*)?} is implementation defined. In these cases, GNU +@command{dirname} returns @samp{/}, but it's more portable to return +@samp{//} as this works even on those older flavors of Unix. + +I have heard rumors that this special treatment of @samp{//} may be +dropped in future versions of POSIX, but for now it's still the +standard. +@end quotation + + +@item @command{egrep} +@c ------------------ +@cindex @command{egrep} +The empty alternative is not portable, use @samp{?} instead. For +instance with Digital Unix v5.0: + +@example +> printf "foo\n|foo\n" | egrep '^(|foo|bar)$' +|foo +> printf "bar\nbar|\n" | egrep '^(foo|bar|)$' +bar| +> printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$' +foo +|bar +@end example + +@command{egrep} also suffers the limitations of @command{grep}. + + +@item @command{expr} +@c ----------------- +@cindex @command{expr} +No @command{expr} keyword starts with @samp{x}, so use @samp{expr +x"@var{word}" : 'x@var{regex}'} to keep @command{expr} from +misinterpreting @var{word}. + +Don't use @code{length}, @code{substr}, @code{match} and @code{index}. + +@item @command{expr} (@samp{|}) +@cindex @command{expr} (@samp{|}) +You can use @samp{|}. Although @sc{posix} does require that @samp{expr +''} return the empty string, it does not specify the result when you +@samp{|} together the empty string (or zero) with the empty string. For +example: + +@example +expr '' \| '' +@end example + +@sc{gnu}/Linux and @sc{posix.2-1992} return the empty string for this +case, but traditional Unix returns @samp{0} (Solaris is one such +example). In the latest @sc{posix} draft, the specification has been +changed to match traditional Unix's behavior (which is bizarre, but it's +too late to fix this). Please note that the same problem does arise +when the empty string results from a computation, as in: + +@example +expr bar : foo \| foo : bar +@end example + +@noindent +Avoid this portability problem by avoiding the empty string. + + +@item @command{expr} (@samp{:}) +@c ---------------------------- +@cindex @command{expr} +Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, they are +not supported on Solaris. + +The @sc{posix.2-1992} standard is ambiguous as to whether @samp{expr a : +b} (and @samp{expr 'a' : '\(b\)'}) output @samp{0} or the empty string. +In practice, it outputs the empty string on most platforms, but portable +scripts should not assume this. For instance, the @sc{qnx} 4.25 native +@command{expr} returns @samp{0}. + +You may believe that one means to get a uniform behavior would be to use +the empty string as a default value: + +@example +expr a : b \| '' +@end example + +@noindent +unfortunately this behaves exactly as the original expression, see the +@samp{@command{expr} (@samp{:})} entry for more information. + +Older @command{expr} implementations (e.g. SunOS 4 @command{expr} and +Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes +@command{expr} to fail if the matched substring is longer than 120 +bytes. In this case, you might want to fall back on @samp{echo|sed} if +@command{expr} fails. + +Don't leave, there is some more! + +The @sc{qnx} 4.25 @command{expr}, in addition of preferring @samp{0} to +the empty string, has a funny behavior in its exit status: it's always 1 +when parentheses are used! + +@example +$ val=`expr 'a' : 'a'`; echo "$?: $val" +0: 1 +$ val=`expr 'a' : 'b'`; echo "$?: $val" +1: 0 + +$ val=`expr 'a' : '\(a\)'`; echo "?: $val" +1: a +$ val=`expr 'a' : '\(b\)'`; echo "?: $val" +1: 0 +@end example + +@noindent +In practice this can be a big problem if you are ready to catch failures +of @command{expr} programs with some other method (such as using +@command{sed}), since you may get twice the result. For instance + +@example +$ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/' +@end example + +@noindent +will output @samp{a} on most hosts, but @samp{aa} on @sc{qnx} 4.25. A +simple work around consists in testing @command{expr} and use a variable +set to @command{expr} or to @command{false} according to the result. + + +@item @command{find} +@c ----------------- +The option @option{-maxdepth} seems to be GNU specific. Tru64 v5.1, +NetBSD 1.5 and Solaris 2.5 @command{find} commands do not understand it. + + +@item @command{grep} +@c ----------------- +@cindex @command{grep} +Don't use @samp{grep -s} to suppress output, because @samp{grep -s} on +System V does not suppress output, only error messages. Instead, +redirect the standard output and standard error (in case the file +doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit +status of @code{grep} to determine whether it found a match. + +Don't use multiple regexps with @option{-e}, as some @code{grep} will only +honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway, +Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{} Instead, use +alternation and @code{egrep}. + + +@item @command{ln} +@c --------------- +@cindex @command{ln} +@cindex Symbolic links +Don't rely on @command{ln} having a @option{-f} option. Symbolic links +are not available on old systems, use @samp{ln} as a fall back. + +For versions of the DJGPP before 2.04, @command{ln} emulates soft links +for executables by generating a stub that in turn calls the real +program. This feature also works with nonexistent files like in the +Unix spec. So @samp{ln -s file link} will generate @file{link.exe}, +which will attempt to call @file{file.exe} if run. But this feature only +works for executables, so @samp{cp -p} is used instead for these +systems. DJGPP versions 2.04 and later have full symlink support. + + +@item @command{mv} +@c --------------- +@cindex @command{mv} +The only portable options are @option{-f} and @option{-i}. + +Moving individual files between file systems is portable (it was in V6), +but it is not always atomic: when doing @samp{mv new existing}, there's +a critical section where neither the old nor the new version of +@file{existing} actually exists. + +Moving directories across mount points is not portable, use @command{cp} +and @command{rm}. + + +@item @command{sed} +@c ---------------- +@cindex @command{sed} +Patterns should not include the separator (unless escaped), even as part +of a character class. In conformance with @sc{posix}, the Cray +@command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}. + +Sed scripts should not use branch labels longer than 8 characters and +should not contain comments. + +Don't include extra @samp{;}, as some @command{sed}, such as NetBSD +1.4.2's, try to interpret the second as a command: + +@example +$ echo a | sed 's/x/x/;;s/x/x/' +sed: 1: "s/x/x/;;s/x/x/": invalid command code ; +@end example + +Input should have reasonably long lines, since some @command{sed} have +an input buffer limited to 4000 bytes. + +Alternation, @samp{\|}, is common but not portable. +@c FIXME: I know Solaris is guilty, but I don't remember how. +Anchors (@samp{^} and @samp{$}) inside groups are not portable. + +Nested groups are extremely portable, but there is at least one +@command{sed} (System V/68 Base Operating System R3V7.1) that does not +support it. + +Of course the option @option{-e} is portable, but it is not needed. No +valid Sed program can start with a dash, so it does not help +disambiguating. Its sole usefulness is helping enforcing indenting as +in: + +@example +sed -e @var{instruction-1} \ + -e @var{instruction-2} +@end example + +@noindent +as opposed to + +@example +sed @var{instruction-1};@var{instruction-2} +@end example + +Contrary to yet another urban legend, you may portably use @samp{&} in +the replacement part of the @code{s} command to mean ``what was +matched''. + + +@item @command{sed} (@samp{t}) +@c --------------------------- +@cindex @command{sed} (@samp{t}) +Some old systems have @command{sed} that ``forget'' to reset their +@samp{t} flag when starting a new cycle. For instance on @sc{mips +risc/os}, and on @sc{irix} 5.3, if you run the following @command{sed} +script (the line numbers are not actual part of the texts): + +@example +s/keep me/kept/g # a +t end # b +s/.*/deleted/g # c +: end # d +@end example + +@noindent +on + +@example +delete me # 1 +delete me # 2 +keep me # 3 +delete me # 4 +@end example + +@noindent +you get + +@example +deleted +delete me +kept +deleted +@end example + +@noindent +instead of + +@example +deleted +deleted +kept +deleted +@end example + +Why? When processing 1, a matches, therefore sets the t flag, b jumps to +d, and the output is produced. When processing line 2, the t flag is +still set (this is the bug). Line a fails to match, but @command{sed} +is not supposed to clear the t flag when a substitution fails. Line b +sees that the flag is set, therefore it clears it, and jumps to d, hence +you get @samp{delete me} instead of @samp{deleted}. When processing 3 t +is clear, a matches, so the flag is set, hence b clears the flags and +jumps. Finally, since the flag is clear, 4 is processed properly. + +There are two things one should remind about @samp{t} in @command{sed}. +Firstly, always remember that @samp{t} jumps if @emph{some} substitution +succeeded, not only the immediately preceding substitution, therefore, +always use a fake @samp{t clear; : clear} to reset the t flag where +indeed. + +Secondly, you cannot rely on @command{sed} to clear the flag at each new +cycle. + +One portable implementation of the script above is: + +@example +t clear +: clear +s/keep me/kept/g +t end +s/.*/deleted/g +: end +@end example + +@item @command{touch} +@c ------------------ +@cindex @command{touch} +On some old @sc{bsd} systems, @command{touch} or any command that +results in an empty file does not update the timestamps, so use a +command like @code{echo} as a workaround. + +GNU @command{touch} 3.16r (and presumably all before that) fails to work +on SunOS 4.1.3 when the empty file is on an @sc{nfs}-mounted 4.2 volume. + +@end table + + +@node Limitations of Make, , Limitations of Usual Tools, Portable Shell +@section Limitations of Make + +Make itself suffers a great number of limitations, only a few of which +being listed here. First of all, remember that since commands are +executed by the shell, all its weaknesses are inherited@dots{} + +@table @asis +@item Leading underscore in macro names +Some Make don't support leading underscores in macro names, such as on +NEWS-OS 4.2R. + +@example +$ cat Makefile +_am_include = # +_am_quote = +all:; @@echo this is test + +% make +Make: Must be a separator on rules line 2. Stop. + +$ cat Makefile2 +am_include = # +am_quote = +all:; @@echo this is test + +$ make -f Makefile2 +this is test +@end example + +@item @code{VPATH} +@cindex @code{VPATH} +Don't use it! For instance any assignment to @code{VPATH} causes Sun +@command{make} to only execute the first set of double-colon rules. +@end table + + + + +@c ================================================== Manual Configuration + +@node Manual Configuration, Site Configuration, Portable Shell, Top +@chapter Manual Configuration + +A few kinds of features can't be guessed automatically by running test +programs. For example, the details of the object-file format, or +special options that need to be passed to the compiler or linker. You +can check for such features using ad-hoc means, such as having +@code{configure} check the output of the @code{uname} program, or +looking for libraries that are unique to particular systems. However, +Autoconf provides a uniform method for handling unguessable features. + +@menu +* Specifying Names:: Specifying the system type +* Canonicalizing:: Getting the canonical system type +* Using System Type:: What to do with the system type +@end menu + +@node Specifying Names, Canonicalizing, Manual Configuration, Manual Configuration +@section Specifying the System Type + +Like other @sc{gnu} @code{configure} scripts, Autoconf-generated +@code{configure} scripts can make decisions based on a canonical name +for the system type, which has the form: +@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be +@samp{@var{system}} or @samp{@var{kernel}-@var{system}} + +@code{configure} can usually guess the canonical name for the type of +system it's running on. To do so it runs a script called +@code{config.guess}, which infers the name using the @code{uname} +command or symbols predefined by the C preprocessor. + +Alternately, the user can specify the system type with command line +arguments to @code{configure}. Doing so is necessary when +cross-compiling. In the most complex case of cross-compiling, three +system types are involved. The options to specify them are@footnote{For +backward compatibility, @code{configure} will accept a system type as an +option by itself. Such an option will override the defaults for build, +host and target system types. The following configure statement will +configure a cross toolchain that will run on NetBSD/alpha but generate +code for GNU Hurd/sparc, which is also the build platform. + +@example +./configure --host=alpha-netbsd sparc-gnu +@end example +}: + +@table @option +@item --build=@var{build-type} +the type of system on which the package is being configured and +compiled. + +@item --host=@var{host-type} +@ovindex cross_compiling +the type of system on which the package will run. + +@item --target=@var{target-type} +the type of system for which any compiler tools in the package will +produce code (rarely needed). By default, it is the same as host. +@end table + +They all default to the result of running @code{config.guess}, unless +you specify either @option{--build} or @option{--host}. In this case, the +default becomes the system type you specified. If you specify both, and +they're different, @code{configure} will enter cross compilation mode, +so it won't run any tests that require execution. + +Hint: if you mean to override the result of @code{config.guess}, prefer +@option{--build} over @option{--host}. In the future, @option{--host} will +not override the name of the build system type. Also, if you specify +@option{--host}, but not @option{--build}, when @code{configure} performs +the first compiler test it will try to run an executable produced by the +compiler. If the execution fails, it will enter cross-compilation mode. +Note, however, that it won't guess the build-system type, since this may +require running test programs. Moreover, by the time the compiler test +is performed, it may be too late to modify the build-system type: other +tests may have already been performed. Therefore, whenever you specify +@code{--host}, be sure to specify @code{--build} too. + +@example +./configure --build=i686-pc-linux-gnu --host=m68k-coff +@end example + +@noindent +will enter cross-compilation mode, but @code{configure} will fail if it +can't run the code generated by the specified compiler if you configure +as follows: + +@example +./configure CC=m68k-coff-gcc +@end example + +@code{configure} recognizes short aliases for many system types; for +example, @samp{decstation} can be used instead of +@samp{mips-dec-ultrix4.2}. @code{configure} runs a script called +@code{config.sub} to canonicalize system type aliases. + + + +@node Canonicalizing, Using System Type, Specifying Names, Manual Configuration +@section Getting the Canonical System Type + +The following macros make the system type available to @code{configure} +scripts. + +@ovindex build_alias +@ovindex host_alias +@ovindex target_alias + +The variables @samp{build_alias}, @samp{host_alias}, and +@samp{target_alias} are always exactly the arguments of @option{--build}, +@option{--host}, and @option{--target}; in particular, they are left empty +if the user did not use them, even if the corresponding +@code{AC_CANONICAL} macro was run. Any configure script may use these +variables anywhere. These are the variables that should be used when in +interaction with the user. + +If you need to recognize some special environments based on their system +type, run the following macros to get canonical system names. These +variables are not set before the macro call. + +If you use these macros, you must distribute @code{config.guess} and +@code{config.sub} along with your source code. @xref{Output}, for +information about the @code{AC_CONFIG_AUX_DIR} macro which you can use +to control in which directory @code{configure} looks for those scripts. + + +@defmac AC_CANONICAL_BUILD +@maindex CANONICAL_BUILD +@ovindex build +@ovindex build_cpu +@ovindex build_vendor +@ovindex build_os +Compute the canonical build-system type variable, @code{build}, and its +three individual parts @code{build_cpu}, @code{build_vendor}, and +@code{build_os}. + +If @option{--build} was specified, then @code{build} is the +canonicalization of @code{build_alias} by @command{config.sub}, +otherwise it is determined by the shell script @code{config.guess}. +@end defmac + +@defmac AC_CANONICAL_HOST +@maindex CANONICAL_HOST +@ovindex host +@ovindex host_cpu +@ovindex host_vendor +@ovindex host_os +Compute the canonical host-system type variable, @code{host}, and its +three individual parts @code{host_cpu}, @code{host_vendor}, and +@code{host_os}. + +If @option{--host} was specified, then @code{host} is the +canonicalization of @code{host_alias} by @command{config.sub}, +otherwise it defaults to @code{build}. + +For temporary backward-compatibility, when @option{--host} is specified +by @option{--build} isn't, the build system will be assumed to be the +same as @option{--host}, and @samp{build_alias} will be set to that +value. Eventually, this historically incorrect behavior will go away. + +@end defmac + +@defmac AC_CANONICAL_TARGET +@maindex CANONICAL_TARGET +@ovindex target +@ovindex target_cpu +@ovindex target_vendor +@ovindex target_os +Compute the canonical target-system type variable, @code{target}, and its +three individual parts @code{target_cpu}, @code{target_vendor}, and +@code{target_os}. + +If @option{--target} was specified, then @code{target} is the +canonicalization of @code{target_alias} by @command{config.sub}, +otherwise it defaults to @code{host}. +@end defmac + + +@node Using System Type, , Canonicalizing, Manual Configuration +@section Using the System Type + +How do you use a canonical system type? Usually, you use it in one or +more @code{case} statements in @file{configure.ac} to select +system-specific C files. Then, using @code{AC_CONFIG_LINKS}, link those +files which have names based on the system name, to generic names, such +as @file{host.h} or @file{target.c} (@pxref{Configuration Links}). The +@code{case} statement patterns can use shell wild cards to group several +cases together, like in this fragment: + +@example +case "$target" in +i386-*-mach* | i386-*-gnu*) + obj_format=aout emulation=mach bfd_gas=yes ;; +i960-*-bout) obj_format=bout ;; +esac +@end example + +@noindent +and in @file{configure.ac}, use: + +@example +AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) +@end example + +You can also use the host system type to find cross-compilation tools. +@xref{Generic Programs}, for information about the @code{AC_CHECK_TOOL} +macro which does that. + + +@c ===================================================== Site Configuration. + +@node Site Configuration, Running configure scripts, Manual Configuration, Top +@chapter Site Configuration + +@code{configure} scripts support several kinds of local configuration +decisions. There are ways for users to specify where external software +packages are, include or exclude optional features, install programs +under modified names, and set default values for @code{configure} +options. + +@menu +* External Software:: Working with other optional software +* Package Options:: Selecting optional features +* Pretty Help Strings:: Formatting help string +* Site Details:: Configuring site details +* Transforming Names:: Changing program names when installing +* Site Defaults:: Giving @code{configure} local defaults +@end menu + +@node External Software, Package Options, Site Configuration, Site Configuration +@section Working With External Software + +Some packages require, or can optionally use, other software packages +that are already installed. The user can give @code{configure} +command line options to specify which such external software to use. +The options have one of these forms: + +@example +--with-@var{package}=@ovar{arg} +--without-@var{package} +@end example + +For example, @option{--with-gnu-ld} means work with the @sc{gnu} linker +instead of some other linker. @option{--with-x} means work with The X +Window System. + +The user can give an argument by following the package name with +@samp{=} and the argument. Giving an argument of @samp{no} is for +packages that are used by default; it says to @emph{not} use the +package. An argument that is neither @samp{yes} nor @samp{no} could +include a name or number of a version of the other package, to specify +more precisely which other package this program is supposed to work +with. If no argument is given, it defaults to @samp{yes}. +@option{--without-@var{package}} is equivalent to +@option{--with-@var{package}=no}. + +@code{configure} scripts do not complain about +@option{--with-@var{package}} options that they do not support. This +behavior permits configuring a source tree containing multiple packages +with a top-level @code{configure} script when the packages support +different options, without spurious error messages about options that +some of the packages support. An unfortunate side effect is that option +spelling errors are not diagnosed. No better approach to this problem +has been suggested so far. + +For each external software package that may be used, @file{configure.ac} +should call @code{AC_ARG_WITH} to detect whether the @code{configure} +user asked to use it. Whether each package is used or not by default, +and which arguments are valid, is up to you. + +@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given}) +@maindex ARG_WITH +If the user gave @code{configure} the option @option{--with-@var{package}} +or @option{--without-@var{package}}, run shell commands +@var{action-if-given}. If neither option was given, run shell commands +@var{action-if-not-given}. The name @var{package} indicates another +software package that this program should work with. It should consist +only of alphanumeric characters and dashes. + +The option's argument is available to the shell commands +@var{action-if-given} in the shell variable @code{withval}, which is +actually just the value of the shell variable @code{with_@var{package}}, +with any @option{-} characters changed into @samp{_}. You may use that +variable instead, if you wish. + +The argument @var{help-string} is a description of the option that +looks like this: +@example + --with-readline support fancy command line editing +@end example + +@noindent +@var{help-string} may be more than one line long, if more detail is +needed. Just make sure the columns line up in @samp{configure --help}. +Avoid tabs in the help string. You'll need to enclose it in @samp{[} +and @samp{]} in order to produce the leading spaces. + +You should format your @var{help-string} with the macro +@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}). +@end defmac + +@defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given}) +@maindex WITH +This is an obsolete version of @code{AC_ARG_WITH} that does not +support providing a help string. +@end defmac + +@node Package Options, Pretty Help Strings, External Software, Site Configuration +@section Choosing Package Options + +If a software package has optional compile-time features, the user can +give @code{configure} command line options to specify whether to +compile them. The options have one of these forms: + +@example +--enable-@var{feature}=@ovar{arg} +--disable-@var{feature} +@end example + +These options allow users to choose which optional features to build and +install. @option{--enable-@var{feature}} options should never make a +feature behave differently or cause one feature to replace another. +They should only cause parts of the program to be built rather than left +out. + +The user can give an argument by following the feature name with +@samp{=} and the argument. Giving an argument of @samp{no} requests +that the feature @emph{not} be made available. A feature with an +argument looks like @option{--enable-debug=stabs}. If no argument is +given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is +equivalent to @option{--enable-@var{feature}=no}. + +@code{configure} scripts do not complain about +@option{--enable-@var{feature}} options that they do not support. +This behavior permits configuring a source tree containing multiple +packages with a top-level @code{configure} script when the packages +support different options, without spurious error messages about options +that some of the packages support. +An unfortunate side effect is that option spelling errors are not diagnosed. +No better approach to this problem has been suggested so far. + +For each optional feature, @file{configure.ac} should call +@code{AC_ARG_ENABLE} to detect whether the @code{configure} user asked +to include it. Whether each feature is included or not by default, and +which arguments are valid, is up to you. + +@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given}) +@maindex ARG_ENABLE +If the user gave @code{configure} the option +@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run +shell commands @var{action-if-given}. If neither option was given, run +shell commands @var{action-if-not-given}. The name @var{feature} +indicates an optional user-level facility. It should consist only of +alphanumeric characters and dashes. + +The option's argument is available to the shell commands +@var{action-if-given} in the shell variable @code{enableval}, which is +actually just the value of the shell variable +@code{enable_@var{feature}}, with any @option{-} characters changed into +@samp{_}. You may use that variable instead, if you wish. The +@var{help-string} argument is like that of @code{AC_ARG_WITH} +(@pxref{External Software}). + +You should format your @var{help-string} with the macro +@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}). +@end defmac + +@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given}) +@maindex ENABLE +This is an obsolete version of @code{AC_ARG_ENABLE} that does not +support providing a help string. +@end defmac + + +@node Pretty Help Strings, Site Details, Package Options, Site Configuration +@section Making Your Help Strings Look Pretty + +Properly formatting the @samp{help strings} which are used in +@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE} +(@pxref{Package Options}) can be challenging. Specifically, you want +your own @samp{help strings} to line up in the appropriate columns of +@samp{configure --help} just like the standard Autoconf @samp{help +strings} do. This is the purpose of the @code{AC_HELP_STRING} macro. + +@defmac AC_HELP_STRING (@var{left-hand-side}, @var{right-hand-side}) +@maindex HELP_STRING + +Expands into an help string that looks pretty when the user executes +@samp{configure --help}. It is typically used in @code{AC_ARG_WITH} +(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package +Options}). The following example will make this clearer. + +@example +AC_DEFUN(TEST_MACRO, +[AC_ARG_WITH(foo, + AC_HELP_STRING([--with-foo], + [use foo (default is NO)]), + ac_cv_use_foo=$withval, ac_cv_use_foo=no), +AC_CACHE_CHECK(whether to use foo, + ac_cv_use_foo, ac_cv_use_foo=no)]) +@end example + +Please note that the call to @code{AC_HELP_STRING} is @strong{unquoted}. +Then the last few lines of @samp{configure --help} will appear like +this: + +@example +--enable and --with options recognized: + --with-foo use foo (default is NO) +@end example + +The @code{AC_HELP_STRING} macro is particularly helpful when the +@var{left-hand-side} and/or @var{right-hand-side} are composed of macro +arguments, as shown in the following example. + +@example +AC_DEFUN(MY_ARG_WITH, +[AC_ARG_WITH([$1], + AC_HELP_STRING([--with-$1], [use $1 (default is $2)]), + ac_cv_use_$1=$withval, ac_cv_use_$1=no), +AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)]) +@end example +@end defmac + + +@node Site Details, Transforming Names, Pretty Help Strings, Site Configuration +@section Configuring Site Details + +Some software packages require complex site-specific information. Some +examples are host names to use for certain services, company names, and +email addresses to contact. Since some configuration scripts generated +by Metaconfig ask for such information interactively, people sometimes +wonder how to get that information in Autoconf-generated configuration +scripts, which aren't interactive. + +Such site configuration information should be put in a file that is +edited @emph{only by users}, not by programs. The location of the file +can either be based on the @code{prefix} variable, or be a standard +location such as the user's home directory. It could even be specified +by an environment variable. The programs should examine that file at +run time, rather than at compile time. Run time configuration is more +convenient for users and makes the configuration process simpler than +getting the information while configuring. @xref{Directory Variables,, +Variables for Installation Directories, standards, GNU Coding +Standards}, for more information on where to put data files. + +@node Transforming Names, Site Defaults, Site Details, Site Configuration +@section Transforming Program Names When Installing + +Autoconf supports changing the names of programs when installing them. +In order to use these transformations, @file{configure.ac} must call the +macro @code{AC_ARG_PROGRAM}. + +@defmac AC_ARG_PROGRAM +@maindex ARG_PROGRAM +@ovindex program_transform_name +Place in output variable @code{program_transform_name} a sequence of +@code{sed} commands for changing the names of installed programs. + +If any of the options described below are given to @code{configure}, +program names are transformed accordingly. Otherwise, if +@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value +is given that differs from the host type (specified with @option{--host}), +the target type followed by a dash is used as a prefix. Otherwise, no +program name transformation is done. +@end defmac + +@menu +* Transformation Options:: @code{configure} options to transform names +* Transformation Examples:: Sample uses of transforming names +* Transformation Rules:: @file{Makefile} uses of transforming names +@end menu + +@node Transformation Options, Transformation Examples, Transforming Names, Transforming Names +@subsection Transformation Options + +You can specify name transformations by giving @code{configure} these +command line options: + +@table @option +@item --program-prefix=@var{prefix} +prepend @var{prefix} to the names; + +@item --program-suffix=@var{suffix} +append @var{suffix} to the names; + +@item --program-transform-name=@var{expression} +perform @code{sed} substitution @var{expression} on the names. +@end table + +@node Transformation Examples, Transformation Rules, Transformation Options, Transforming Names +@subsection Transformation Examples + +These transformations are useful with programs that can be part of a +cross-compilation development environment. For example, a +cross-assembler running on a Sun 4 configured with +@option{--target=i960-vxworks} is normally installed as +@file{i960-vxworks-as}, rather than @file{as}, which could be confused +with a native Sun 4 assembler. + +You can force a program name to begin with @file{g}, if you don't want +@sc{gnu} programs installed on your system to shadow other programs with +the same name. For example, if you configure @sc{gnu} @code{diff} with +@option{--program-prefix=g}, then when you run @samp{make install} it is +installed as @file{/usr/local/bin/gdiff}. + +As a more sophisticated example, you could use + +@example +--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' +@end example +@noindent + +to prepend @samp{g} to most of the program names in a source tree, +excepting those like @code{gdb} that already have one and those like +@code{less} and @code{lesskey} that aren't @sc{gnu} programs. (That is +assuming that you have a source tree containing those programs that is +set up to use this feature.) + +One way to install multiple versions of some programs simultaneously is +to append a version number to the name of one or both. For example, if +you want to keep Autoconf version 1 around for awhile, you can configure +Autoconf version 2 using @option{--program-suffix=2} to install the +programs as @file{/usr/local/bin/autoconf2}, +@file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention +that only the binaries are renamed, therefore you'd have problems with +the library files which might overlap. + +@node Transformation Rules, , Transformation Examples, Transforming Names +@subsection Transformation Rules + +Here is how to use the variable @code{program_transform_name} in a +@file{Makefile.in}: + +@example +transform = @@program_transform_name@@ +install: all + $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog | \ + sed '$(transform)'` + +uninstall: + rm -f $(bindir)/`echo myprog | sed '$(transform)'` +@end example + +@noindent +If you have more than one program to install, you can do it in a loop: + +@example +PROGRAMS = cp ls rm +install: + for p in $(PROGRAMS); do \ + $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p | \ + sed '$(transform)'`; \ + done + +uninstall: + for p in $(PROGRAMS); do \ + rm -f $(bindir)/`echo $$p | sed '$(transform)'`; \ + done +@end example + +It is guaranteed that @code{program_transform_name} is never empty, and +that there are no useless separators. Therefore you may safely embed +@code{program_transform_name} within a sed program using @samp{;}: + +@example +transform = @@program_transform_name@@ +transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ +@end example + +Whether to do the transformations on documentation files (Texinfo or +@code{man}) is a tricky question; there seems to be no perfect answer, +due to the several reasons for name transforming. Documentation is not +usually particular to a specific architecture, and Texinfo files do not +conflict with system documentation. But they might conflict with +earlier versions of the same files, and @code{man} pages sometimes do +conflict with system documentation. As a compromise, it is probably +best to do name transformations on @code{man} pages but not on Texinfo +manuals. + +@node Site Defaults, , Transforming Names, Site Configuration +@section Setting Site Defaults + +Autoconf-generated @code{configure} scripts allow your site to provide +default values for some configuration values. You do this by creating +site- and system-wide initialization files. + +@evindex CONFIG_SITE +If the environment variable @code{CONFIG_SITE} is set, @code{configure} +uses its value as the name of a shell script to read. Otherwise, it +reads the shell script @file{@var{prefix}/share/config.site} if it exists, +then @file{@var{prefix}/etc/config.site} if it exists. Thus, +settings in machine-specific files override those in machine-independent +ones in case of conflict. + +Site files can be arbitrary shell scripts, but only certain kinds of +code are really appropriate to be in them. Because @code{configure} +reads any cache file after it has read any site files, a site file can +define a default cache file to be shared between all Autoconf-generated +@code{configure} scripts run on that system (@pxref{Cache Files}). If +you set a default cache file in a site file, it is a good idea to also +set the output variable @code{CC} in that site file, because the cache +file is only valid for a particular compiler, but many systems have +several available. + +You can examine or override the value set by a command line option to +@code{configure} in a site file; options set shell variables that have +the same names as the options, with any dashes turned into underscores. +The exceptions are that @option{--without-} and @option{--disable-} options +are like giving the corresponding @option{--with-} or @option{--enable-} +option and the value @samp{no}. Thus, @option{--cache-file=localcache} +sets the variable @code{cache_file} to the value @samp{localcache}; +@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable +@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the +variable @code{prefix} to the value @samp{/usr}; etc. + +Site files are also good places to set default values for other output +variables, such as @code{CFLAGS}, if you need to give them non-default +values: anything you would normally do, repetitively, on the command +line. If you use non-default values for @var{prefix} or +@var{exec_prefix} (wherever you locate the site file), you can set them +in the site file if you specify it with the @code{CONFIG_SITE} +environment variable. + +You can set some cache values in the site file itself. Doing this is +useful if you are cross-compiling, so it is impossible to check features +that require running a test program. You could ``prime the cache'' by +setting those values correctly for that system in +@file{@var{prefix}/etc/config.site}. To find out the names of the cache +variables you need to set, look for shell variables with @samp{_cv_} in +their names in the affected @code{configure} scripts, or in the Autoconf +M4 source code for those macros. + +The cache file is careful to not override any variables set in the site +files. Similarly, you should not override command-line options in the +site files. Your code should check that variables such as @code{prefix} +and @code{cache_file} have their default values (as set near the top of +@code{configure}) before changing them. + +Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The +command @samp{configure --prefix=/usr/share/local/gnu} would read this +file (if @code{CONFIG_SITE} is not set to a different file). + +@example +# config.site for configure +# +# Change some defaults. +test "$prefix" = NONE && prefix=/usr/share/local/gnu +test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu +test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var +test "$localstatedir" = '$prefix/var' && localstatedir=/var + +# Give Autoconf 2.x generated configure scripts a shared default +# cache file for feature test results, architecture-specific. +if test "$cache_file" = /dev/null; then + cache_file="$prefix/var/config.cache" + # A cache file is only valid for one C compiler. + CC=gcc +fi +@end example + + +@c ============================================== Running configure Scripts. + +@node Running configure scripts, config.status Invocation, Site Configuration, Top +@chapter Running @code{configure} Scripts +@cindex @code{configure} + +Below are instructions on how to configure a package that uses a +@code{configure} script, suitable for inclusion as an @file{INSTALL} +file in the package. A plain-text version of @file{INSTALL} which you +may use comes with Autoconf. + +@menu +* Basic Installation:: Instructions for typical cases +* Compilers and Options:: Selecting compilers and optimization +* Multiple Architectures:: Compiling for multiple architectures at once +* Installation Names:: Installing in different directories +* Optional Features:: Selecting optional features +* System Type:: Specifying the system type +* Sharing Defaults:: Setting site-wide defaults for @code{configure} +* Environment Variables:: Defining environment variables. +* configure Invocation:: Changing how @code{configure} runs +@end menu + +@include install.texi + + +@c ============================================== Recreating a Configuration + +@node config.status Invocation, Obsolete Constructs, Running configure scripts, Top +@chapter Recreating a Configuration +@cindex @code{config.status} + +The @code{configure} script creates a file named @file{config.status}, +which actually configures, @dfn{instantiates}, the template files. It +also records the configuration options that were specified when the +package was last configured in case reconfiguring is needed. + +Synopsis: +@example +./config.status @var{option}@dots{} [@var{file}@dots{}] +@end example + +It configures the @var{files}, if none are specified, all the templates +are instantiated. The files must be specified without their +dependencies, as in + +@example +./config.status foobar +@end example + +@noindent +not + +@example +./config.status foobar:foo.in:bar.in +@end example + +The supported @var{option}s are: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options, the list of the template +files and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --file=@var{file}[:@var{template}] +Require that @var{file} be instantiated as if +@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both +@var{file} and @var{template} may be @samp{-} in which case the standard +output and/or standard input, respectively, is used. If a +@var{template} filename is relative, it is first looked for in the build +tree, and then in the source tree. @xref{Configuration Actions}, for +more details. + +This option and the following ones provide one way for separately +distributed packages to share the values computed by @code{configure}. +Doing so can be useful if some of the packages need a superset of the +features that one of them, perhaps a common library, does. These +options allow a @file{config.status} file to create files other than the +ones that its @file{configure.ac} specifies, so it can be used for a +different package. + +@item --header=@var{file}[:@var{template}] +Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}. + +@item --recheck +Ask @file{config.status} to update itself and exit (no instantiation). +This option is useful if you change @code{configure}, so that the +results of some tests might be different from the previous run. The +@option{--recheck} option re-runs @code{configure} with the same arguments +you used before, plus the @option{--no-create} option, which prevents +@code{configure} from running @file{config.status} and creating +@file{Makefile} and other files, and the @option{--no-recursion} option, +which prevents @code{configure} from running other @code{configure} +scripts in subdirectories. (This is so other @file{Makefile} rules can +run @file{config.status} when it changes; @pxref{Automatic Remaking}, +for an example). +@end table + +@file{config.status} checks several optional environment variables that +can alter its behavior: + +@defvar CONFIG_SHELL +@evindex CONFIG_SHELL +The shell with which to run @code{configure} for the @option{--recheck} +option. It must be Bourne-compatible. The default is @file{/bin/sh}. +@end defvar + +@defvar CONFIG_STATUS +@evindex CONFIG_STATUS +The file name to use for the shell script that records the +configuration. The default is @file{./config.status}. This variable is +useful when one package uses parts of another and the @code{configure} +scripts shouldn't be merged because they are maintained separately. +@end defvar + +You can use @file{./config.status} in your Makefiles. For example, in +the dependencies given above (@pxref{Automatic Remaking}), +@file{config.status} is run twice when @file{configure.ac} has changed. +If that bothers you, you can make each run only regenerate the files for +that rule: +@example +@group +config.h: stamp-h +stamp-h: config.h.in config.status + ./config.status config.h + echo > stamp-h + +Makefile: Makefile.in config.status + ./config.status Makefile +@end group +@end example + +The calling convention of @file{config.status} has changed, see +@ref{Obsolete config.status Use}, for details. + + +@c =================================================== Obsolete Constructs + +@node Obsolete Constructs, Questions, config.status Invocation, Top +@chapter Obsolete Constructs + +Autoconf changes, and throughout the years some constructs are obsoleted. +Most of the changes involve the macros, but the tools themselves, or +even some concepts, are now considered obsolete. + +You may completely skip this chapter if you are new to Autoconf, its +intention is mainly to help maintainers updating their packages by +understanding how to move to more modern constructs. + +@menu +* Obsolete config.status Use:: Different calling convention +* acconfig.h:: Additional entries in @file{config.h.in} +* autoupdate Invocation:: Automatic update of @file{configure.ac} +* Obsolete Macros:: Backward compatibility macros +* Autoconf 1:: Tips for upgrading your files +* Autoconf 2.13:: Some fresher tips +@end menu + +@node Obsolete config.status Use, acconfig.h, Obsolete Constructs, Obsolete Constructs +@section Obsolete @file{config.status} Invocation + +@file{config.status} now supports arguments to specify the files to +instantiate, see @ref{config.status Invocation}, for more details. +Before, environment variables had to be used. + +@defvar CONFIG_COMMANDS +@evindex CONFIG_COMMANDS +The tags of the commands to execute. The default is the arguments given +to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in +@file{configure.ac}. +@end defvar + +@defvar CONFIG_FILES +@evindex CONFIG_FILES +The files in which to perform @samp{@@@var{variable}@@} substitutions. +The default is the arguments given to @code{AC_OUTPUT} and +@code{AC_CONFIG_FILES} in @file{configure.ac}. +@end defvar + +@defvar CONFIG_HEADERS +@evindex CONFIG_HEADERS +The files in which to substitute C @code{#define} statements. The +default is the arguments given to @code{AC_CONFIG_HEADERS}; if that +macro was not called, @file{config.status} ignores this variable. +@end defvar + +@defvar CONFIG_LINKS +@evindex CONFIG_LINKS +The symbolic links to establish. The default is the arguments given to +@code{AC_CONFIG_LINKS}; if that macro was not called, +@file{config.status} ignores this variable. +@end defvar + +In @ref{config.status Invocation}, using this old interface, the example +would be: + +@example +@group +config.h: stamp-h +stamp-h: config.h.in config.status + CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ + CONFIG_HEADERS=config.h ./config.status + echo > stamp-h + +Makefile: Makefile.in config.status + CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ + CONFIG_FILES=Makefile ./config.status +@end group +@end example + +@noindent +(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is +no need to set @code{CONFIG_HEADERS} in the @code{make} rules, equally +for @code{CONFIG_COMMANDS} etc.) + + +@node acconfig.h, autoupdate Invocation, Obsolete config.status Use, Obsolete Constructs +@section @file{acconfig.h} + +@cindex @file{acconfig.h} +@cindex @file{config.h.top} +@cindex @file{config.h.bot} + +In order to produce @file{config.h.in}, @command{autoheader} needs to +build or to find templates for each symbol. Modern releases of Autoconf +use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader +Macros}), but in older releases a file, @file{acconfig.h}, contained the +list of needed templates. @code{autoheader} copies comments and +@code{#define} and @code{#undef} statements from @file{acconfig.h} in +the current directory, if present. This file used to be mandatory if +you @code{AC_DEFINE} any additional symbols. + +Modern releases of Autoconf also provide @code{AH_TOP} and +@code{AH_BOTTOM} if you need to prepend/append some information to +@file{config.h.in}. Ancient versions of Autoconf had a similar feature: +if @file{./acconfig.h} contains the string @samp{@@TOP@@}, +@code{autoheader} copies the lines before the line containing +@samp{@@TOP@@} into the top of the file that it generates. Similarly, +if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@}, +@code{autoheader} copies the lines after that line to the end of the +file it generates. Either or both of those strings may be omitted. An +even older alternate way to produce the same effect in jurasik versions +of Autoconf is to create the files @file{@var{file}.top} (typically +@file{config.h.top}) and/or @file{@var{file}.bot} in the current +directory. If they exist, @code{autoheader} copies them to the +beginning and end, respectively, of its output. + +In former versions of Autoconf, the files used in preparing a software +package for distribution were: +@example +@group +configure.ac --. .------> autoconf* -----> configure + +---+ +[aclocal.m4] --+ `---. +[acsite.m4] ---' | + +--> [autoheader*] -> [config.h.in] +[acconfig.h] ----. | + +-----' +[config.h.top] --+ +[config.h.bot] --' +@end group +@end example + +Use only the @code{AH_} macros, @file{configure.ac} should be +self-contained, and should not depend upon @file{acconfig.h} etc. + + +@node autoupdate Invocation, Obsolete Macros, acconfig.h, Obsolete Constructs +@section Using @code{autoupdate} to Modernize @file{configure.ac} +@cindex @code{autoupdate} + +The @code{autoupdate} program updates a @file{configure.ac} file that +calls Autoconf macros by their old names to use the current macro names. +In version 2 of Autoconf, most of the macros were renamed to use a more +uniform and descriptive naming scheme. @xref{Macro Names}, for a +description of the new scheme. Although the old names still work +(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding +new names), you can make your @file{configure.ac} files more readable +and make it easier to use the current Autoconf documentation if you +update them to use the new macro names. + +@evindex SIMPLE_BACKUP_SUFFIX +If given no arguments, @code{autoupdate} updates @file{configure.ac}, +backing up the original version with the suffix @file{~} (or the value +of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is +set). If you give @code{autoupdate} an argument, it reads that file +instead of @file{configure.ac} and writes the updated file to the +standard output. + +@noindent +@code{autoupdate} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --verbose +@itemx -v +Report processing steps. + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. + +@item --localdir=@var{dir} +@itemx -l @var{dir} +Look for the package file @file{aclocal.m4} in directory @var{dir} +instead of in the current directory. +@end table + +@node Obsolete Macros, Autoconf 1, autoupdate Invocation, Obsolete Constructs +@section Obsolete Macros + +Several macros are obsoleted in Autoconf, for various reasons (typically +they failed to quote properly, couldn't be extended for more recent +issues etc.). They are still supported, but deprecated: their use +should be avoided. + +During the jump from Autoconf version 1 to version 2, most of the +macros were renamed to use a more uniform and descriptive naming scheme, +but their signature did not change. @xref{Macro Names}, for a +description of the new naming scheme. Below, there is just the mapping +from old names to new names for these macros, the reader is invited to +refer to the definition of the new macro for the signature and the +description. + +@defmac AC_ALLOCA +@maindex ALLOCA +@code{AC_FUNC_ALLOCA} +@end defmac + +@defmac AC_ARG_ARRAY +@maindex ARG_ARRAY +removed because of limited usefulness +@end defmac + +@defmac AC_C_CROSS +@maindex C_CROSS +This macro is obsolete; it does nothing. +@end defmac + +@defmac AC_CANONICAL_SYSTEM +@maindex CANONICAL_SYSTEM +Determine the system type and set output variables to the names of the +canonical system types. @xref{Canonicalizing}, for details about the +variables this macro sets. + +The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or +@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on +the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two +other macros. +@end defmac + +@defmac AC_CHAR_UNSIGNED +@maindex CHAR_UNSIGNED +@code{AC_C_CHAR_UNSIGNED} +@end defmac + +@defmac AC_CHECK_TYPE (@var{type}, @var{default}) +@maindex CHECK_TYPE +Autoconf, up to 2.13, used to provide this version of +@code{AC_CHECK_TYPE}, deprecated because of its flaws. Firstly, although +it is a member of the @code{CHECK} clan, singular sub-family, it does +more than just checking. Second, missing types are not +@code{typedef}'d, they are @code{#define}'d, which can lead to +incompatible code in the case of pointer types. + +This use of @code{AC_CHECK_TYPE} is obsolete and discouraged, see +@ref{Generic Types}, for the description of the current macro. + +If the type @var{type} is not defined, define it to be the C (or C++) +builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}. + +This macro is equivalent to: + +@example +AC_CHECK_TYPE([@var{type}], + [AC_DEFINE([@var{type}], [@var{default}], + [Define to `@var{default}' if <sys/types.h> + does not define.])]) +@end example + +In order to keep backward compatibility, the two versions of +@code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics: + +@enumerate +@item +If there are three or four arguments, the modern version is used. + +@item +If the second argument appears to be a C or C++ type, then the +obsolete version is used. This happens if the argument is a C or C++ +@emph{builtin} type or a C identifier ending in @samp{_t}, optionally +followed by one of @samp{[(* } and then by a string of zero or more +characters taken from the set @samp{[]()* _a-zA-Z0-9}. + +@item +If the second argument is spelled with the alphabet of valid C and C++ +types, the user is warned and the modern version is used. + +@item +Otherwise, the modern version is used. +@end enumerate + +@noindent +You are encouraged either to use a valid builtin type, or to use the +equivalent modern code (see above), or better yet, to use +@code{AC_CHECK_TYPES} together with + +@example +#if !HAVE_LOFF_T +typedef loff_t off_t; +#endif +@end example +@end defmac +@c end of AC_CHECK_TYPE + +@defmac AC_CHECKING (@var{feature-description}) +@maindex CHECKING +Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}. +@end defmac + +@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found}) +@maindex COMPILE_CHECK +This is an obsolete version of @code{AC_TRY_LINK} (@pxref{Examining +Libraries}), with the addition that it prints @samp{checking for +@var{echo-text}} to the standard output first, if @var{echo-text} is +non-empty. Use @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead +to print messages (@pxref{Printing Messages}). +@end defmac + +@defmac AC_CONST +@maindex CONST +@code{AC_C_CONST} +@end defmac + +@defmac AC_CROSS_CHECK +@maindex CROSS_CHECK +Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing +@code{:-)}. +@end defmac + +@defmac AC_CYGWIN +@maindex CYGWIN +Check for the Cygwin environment in which case the shell variable +@code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified +means to check the nature of the host is using +@code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as: + +@example +AC_REQUIRE([AC_CANONICAL_HOST])[]dnl +case $host_os in + *cygwin* ) CYGWIN=yes;; + * ) CYGWIN=no;; +esac +@end example + +Beware that the variable @code{CYGWIN} has a very special meaning when +running CygWin32, and should not be changed. That's yet another reason +not to use this macro. +@end defmac + +@defmac AC_DECL_YYTEXT +@maindex DECL_YYTEXT +Does nothing, now integrated in @code{AC_PROG_LEX}. +@end defmac + +@defmac AC_DIR_HEADER +@maindex DIR_HEADER +@cvindex DIRENT +@cvindex SYSNDIR +@cvindex SYSDIR +@cvindex NDIR +Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT}, +but defines a different set of C preprocessor macros to indicate which +header file is found: + +@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}} +@item Header @tab Old Symbol @tab New Symbol +@item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H} +@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H} +@item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H} +@item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H} +@end multitable +@end defmac + +@defmac AC_DYNIX_SEQ +@maindex DYNIX_SEQ +If on Dynix/PTX (Sequent @sc{unix}), add @option{-lseq} to output variable +@code{LIBS}. This macro used to be defined as + +@example +AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS") +@end example + +@noindent +now it is just @code{AC_FUNC_GETMNTENT}. +@end defmac + +@defmac AC_EXEEXT +@maindex EXEEXT +@ovindex EXEEXT +Defined the output variable @code{EXEEXT} based on the output of the +compiler, which is now done automatically. Typically set to empty +string if Unix and @samp{.exe} if Win32 or OS/2. +@end defmac + +@defmac AC_EMXOS2 +@maindex EMXOS2 +Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2 +and sets @code{EMXOS2}. +@end defmac + +@defmac AC_ERROR +@maindex ERROR +@code{AC_MSG_ERROR} +@end defmac + +@defmac AC_FIND_X +@maindex FIND_X +@code{AC_PATH_X} +@end defmac + +@defmac AC_FIND_XTRA +@maindex FIND_XTRA +@code{AC_PATH_XTRA} +@end defmac + +@defmac AC_FUNC_CHECK +@maindex FUNC_CHECK +@code{AC_CHECK_FUNC} +@end defmac + +@defmac AC_FUNC_WAIT3 +@maindex FUNC_WAIT3 +@cvindex HAVE_WAIT3 +If @code{wait3} is found and fills in the contents of its third argument +(a @samp{struct rusage *}), which HP-UX does not do, define +@code{HAVE_WAIT3}. + +These days portable programs should use @code{waitpid}, not +@code{wait3}, as @code{wait3} is being removed from the Open Group +standards, and will not appear in the next revision of POSIX. +@end defmac + +@defmac AC_GCC_TRADITIONAL +@maindex GCC_TRADITIONAL +@code{AC_PROG_GCC_TRADITIONAL} +@end defmac + +@defmac AC_GETGROUPS_T +@maindex GETGROUPS_T +@code{AC_TYPE_GETGROUPS} +@end defmac + +@defmac AC_GETLOADAVG +@maindex GETLOADAVG +@code{AC_FUNC_GETLOADAVG} +@end defmac + +@defmac AC_HAVE_FUNCS +@maindex HAVE_FUNCS +@code{AC_CHECK_FUNCS} +@end defmac + +@defmac AC_HAVE_HEADERS +@maindex HAVE_HEADERS +@code{AC_CHECK_HEADERS} +@end defmac + +@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) +@maindex HAVE_LIBRARY +This macro is equivalent to calling @code{AC_CHECK_LIB} with a +@var{function} argument of @code{main}. In addition, @var{library} can +be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In +all of those cases, the compiler is passed @option{-lfoo}. However, +@var{library} cannot be a shell variable; it must be a literal name. +@end defmac + +@defmac AC_HAVE_POUNDBANG +@maindex HAVE_POUNDBANG +@code{AC_SYS_INTERPRETER} (different calling convention) +@end defmac + +@defmac AC_HEADER_CHECK +@maindex HEADER_CHECK +@code{AC_CHECK_HEADER} +@end defmac + +@defmac AC_HEADER_EGREP +@maindex HEADER_EGREP +@code{AC_EGREP_HEADER} +@end defmac + +@defmac AC_INIT (@var{unique-file-in-source-dir}) +@maindex INIT +Formerly @code{AC_INIT} used to have a single argument, and was +equivalent to: + +@example +AC_INIT +AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir}) +@end example +@end defmac + +@defmac AC_INLINE +@maindex INLINE +@code{AC_C_INLINE} +@end defmac + +@defmac AC_INT_16_BITS +@maindex INT_16_BITS +@cvindex INT_16_BITS +If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}. +Use @samp{AC_CHECK_SIZEOF(int)} instead. +@end defmac + +@defmac AC_IRIX_SUN +@maindex IRIX_SUN +If on IRIX (Silicon Graphics @sc{unix}), add @option{-lsun} to output +@code{LIBS}. If you were using it to get @code{getmntent}, use +@code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions +of the password and group functions, use @samp{AC_CHECK_LIB(sun, +getpwnam)}. Up to Autoconf 2.13, it used to be + +@example +AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS") +@end example + +@noindent +now it is defined as + +@example +AC_FUNC_GETMNTENT +AC_CHECK_LIB(sun, getpwnam) +@end example +@end defmac + +@defmac AC_LANG_C +@maindex LANG_C +Same as @samp{AC_LANG(C)}. +@end defmac + +@defmac AC_LANG_CPLUSPLUS +@maindex LANG_CPLUSPLUS +Same as @samp{AC_LANG(C++)}. +@end defmac + +@defmac AC_LANG_FORTRAN77 +@maindex LANG_FORTRAN77 +Same as @samp{AC_LANG(Fortran 77)}. +@end defmac + +@defmac AC_LANG_RESTORE +@maindex LANG_RESTORE +Select the @var{language} that is saved on the top of the stack, as set +by @code{AC_LANG_SAVE}, remove it from the stack, and call +@code{AC_LANG(@var{language})}. +@end defmac + +@defmac AC_LANG_SAVE +@maindex LANG_SAVE +Remember the current language (as set by @code{AC_LANG}) on a stack. +The current language does not change. @code{AC_LANG_PUSH} is preferred. +@end defmac + +@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{}) +@maindex LINK_FILES +This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated +version of: + +@example +AC_LINK_FILES(config/$machine.h config/$obj_format.h, + host.h object.h) +@end example + +@noindent +is: + +@example +AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) +@end example +@end defmac + +@defmac AC_LN_S +@maindex LN_S +@code{AC_PROG_LN_S} +@end defmac + +@defmac AC_LONG_64_BITS +@maindex LONG_64_BITS +@cvindex LONG_64_BITS +Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide. +Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead. +@end defmac + +@defmac AC_LONG_DOUBLE +@maindex LONG_DOUBLE +@code{AC_C_LONG_DOUBLE} +@end defmac + +@defmac AC_LONG_FILE_NAMES +@maindex LONG_FILE_NAMES +@code{AC_SYS_LONG_FILE_NAMES} +@end defmac + +@defmac AC_MAJOR_HEADER +@maindex MAJOR_HEADER +@code{AC_HEADER_MAJOR} +@end defmac + +@defmac AC_MEMORY_H +@maindex MEMORY_H +@cvindex NEED_MEMORY_H +Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were +defined in @file{memory.h}. Today it is equivalent to +@samp{AC_CHECK_HEADERS(memory.h)}. Adjust your code to depend upon +@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}, see @xref{Standard +Symbols}. +@end defmac + +@defmac AC_MINGW32 +@maindex MINGW32 +Similar to @code{AC_CYGWIN} but checks for the MingW32 compiler +environment and sets @code{MINGW32}. +@end defmac + +@defmac AC_MINUS_C_MINUS_O +@maindex MINUS_C_MINUS_O +@code{AC_PROG_CC_C_O} +@end defmac + +@defmac AC_MMAP +@maindex MMAP +@code{AC_FUNC_MMAP} +@end defmac + +@defmac AC_MODE_T +@maindex MODE_T +@code{AC_TYPE_MODE_T} +@end defmac + +@defmac AC_OBJEXT +@maindex OBJEXT +@ovindex OBJEXT +Defined the output variable @code{OBJEXT} based on the output of the +compiler, after .c files have been excluded. Typically set to @samp{o} +if Unix, @samp{obj} if Win32. Now the compiler checking macros handle +this automatically. +@end defmac + +@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion}) +@maindex OBSOLETE +Make @code{m4} print a message to the standard error output warning that +@var{this-macro-name} is obsolete, and giving the file and line number +where it was called. @var{this-macro-name} should be the name of the +macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given, +it is printed at the end of the warning message; for example, it can be +a suggestion for what to use instead of @var{this-macro-name}. + +For instance + +@example +AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl +@end example + +You are encouraged to use @code{AU_DEFUN} instead, since it gives better +services to the user. +@end defmac + +@defmac AC_OFF_T +@maindex OFF_T +@code{AC_TYPE_OFF_T} +@end defmac + +@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds}, @ovar{save-defs}) +@maindex OUTPUT +The use of @code{AC_OUTPUT} with argument is deprecated, this obsoleted +interface is equivalent to: + +@example +@group +AC_CONFIG_FILES(@var{file}@dots{}) +AC_CONFIG_COMMANDS([default], + @var{extra-cmds}, @var{init-cmds}) +AC_SETUP_DEFS(@var{save-defs}) +AC_OUTPUT +@end group +@end example + +If you specify @var{save-defs}, autoconf will save the @samp{#define}s in a +different form, for use in the files specified in @code{AC_CONFIG_HEADERS}. +In this case, autoconf substitutes the C-style @samp{#define}s where it finds +@samp{@@DEFS@@}. +This runs faster, and is simpler to maintain +than building a file of @samp{#undef}s, +since autoconf will automatically generate a @samp{#define} for each +@code{AC_DEFINE} that you execute in the @code{configure} script. +The value for @var{save-defs} should be +either @code{cat}, or @code{sort}; +this value is used to filter the list of @samp{#define}s before editing. +Sorted lists are easier to read, +but you may wish to see the definitions in the order that they were +processed. +@end defmac + +@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds}) +@maindex OUTPUT_COMMANDS +Specify additional shell commands to run at the end of +@file{config.status}, and shell commands to initialize any variables +from @code{configure}. This macro may be called multiple times. It is +obsolete, replaced by @code{AC_CONFIG_COMMANDS}. + +Here is an unrealistic example: + +@example +fubar=27 +AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], + fubar=$fubar) +AC_OUTPUT_COMMANDS([echo this is another, extra, bit], + [echo init bit]) +@end example + +Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an +additional key, an important difference is that +@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, while +@code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS} +can safely be given macro calls as arguments: + +@example +AC_CONFIG_COMMANDS(foo, [my_FOO()]) +@end example + +@noindent +conversely, where one level of quoting was enough for literal strings +with @code{AC_OUTPUT_COMMANDS}, you need two with +@code{AC_CONFIG_COMMANDS}. The following lines are equivalent: + +@example +@group +AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) +AC_CONFIG_COMMANDS(default, [[echo "Square brackets: []"]]) +@end group +@end example +@end defmac + +@defmac AC_PID_T +@maindex PID_T +@code{AC_TYPE_PID_T} +@end defmac + +@defmac AC_PREFIX +@maindex PREFIX +@code{AC_PREFIX_PROGRAM} +@end defmac + +@defmac AC_PROGRAMS_CHECK +@maindex PROGRAMS_CHECK +@code{AC_CHECK_PROGS} +@end defmac + +@defmac AC_PROGRAMS_PATH +@maindex PROGRAMS_PATH +@code{AC_PATH_PROGS} +@end defmac + +@defmac AC_PROGRAM_CHECK +@maindex PROGRAM_CHECK +@code{AC_CHECK_PROG} +@end defmac + +@defmac AC_PROGRAM_EGREP +@maindex PROGRAM_EGREP +@code{AC_EGREP_CPP} +@end defmac + +@defmac AC_PROGRAM_PATH +@maindex PROGRAM_PATH +@code{AC_PATH_PROG} +@end defmac + +@defmac AC_REMOTE_TAPE +@maindex REMOTE_TAPE +removed because of limited usefulness +@end defmac + +@defmac AC_RESTARTABLE_SYSCALLS +@maindex RESTARTABLE_SYSCALLS +@code{AC_SYS_RESTARTABLE_SYSCALLS} +@end defmac + +@defmac AC_RETSIGTYPE +@maindex RETSIGTYPE +@code{AC_TYPE_SIGNAL} +@end defmac + +@defmac AC_RSH +@maindex RSH +Removed because of limited usefulness. +@end defmac + +@defmac AC_SCO_INTL +@maindex SCO_INTL +@ovindex LIBS +If on SCO UNIX, add @option{-lintl} to output variable @code{LIBS}. This +macro used to + +@example +AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS") +@end example + +@noindent +now it just calls @code{AC_FUNC_STRFTIME} instead. +@end defmac + +@defmac AC_SETVBUF_REVERSED +@maindex SETVBUF_REVERSED +@code{AC_FUNC_SETVBUF_REVERSED} +@end defmac + +@defmac AC_SET_MAKE +@maindex SET_MAKE +@code{AC_PROG_MAKE_SET} +@end defmac + +@defmac AC_SIZEOF_TYPE +@maindex SIZEOF_TYPE +@code{AC_CHECK_SIZEOF} +@end defmac + +@defmac AC_SIZE_T +@maindex SIZE_T +@code{AC_TYPE_SIZE_T} +@end defmac + +@defmac AC_STAT_MACROS_BROKEN +@maindex STAT_MACROS_BROKEN +@code{AC_HEADER_STAT} +@end defmac + +@defmac AC_STDC_HEADERS +@maindex STDC_HEADERS +@code{AC_HEADER_STDC} +@end defmac + +@defmac AC_STRCOLL +@maindex STRCOLL +@code{AC_FUNC_STRCOLL} +@end defmac + +@defmac AC_ST_BLKSIZE +@maindex ST_BLKSIZE +@code{AC_STRUCT_ST_BLKSIZE} +@end defmac + +@defmac AC_ST_BLOCKS +@maindex ST_BLOCKS +@code{AC_STRUCT_ST_BLOCKS} +@end defmac + +@defmac AC_ST_RDEV +@maindex ST_RDEV +@code{AC_STRUCT_ST_RDEV} +@end defmac + +@defmac AC_SYS_RESTARTABLE_SYSCALLS +@maindex SYS_RESTARTABLE_SYSCALLS +@cvindex HAVE_RESTARTABLE_SYSCALLS +If the system automatically restarts a system call that is interrupted +by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does +not check if system calls are restarted in general--it tests whether a +signal handler installed with @code{signal} (but not @code{sigaction}) +causes system calls to be restarted. It does not test if system calls +can be restarted when interrupted by signals that have no handler. + +These days portable programs should use @code{sigaction} with +@code{SA_RESTART} if they want restartable system calls. They should +not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a +system call is restartable is a dynamic issue, not a configuration-time +issue. +@end defmac + +@defmac AC_SYS_SIGLIST_DECLARED +@maindex SYS_SIGLIST_DECLARED +@code{AC_DECL_SYS_SIGLIST} +@end defmac + +@defmac AC_TEST_CPP +@maindex TEST_CPP +@code{AC_TRY_CPP} +@end defmac + +@defmac AC_TEST_PROGRAM +@maindex TEST_PROGRAM +@code{AC_TRY_RUN} +@end defmac + +@defmac AC_TIMEZONE +@maindex TIMEZONE +@code{AC_STRUCT_TIMEZONE} +@end defmac + +@defmac AC_TIME_WITH_SYS_TIME +@maindex TIME_WITH_SYS_TIME +@code{AC_HEADER_TIME} +@end defmac + +@defmac AC_UID_T +@maindex UID_T +@code{AC_TYPE_UID_T} +@end defmac + +@defmac AC_UNISTD_H +@maindex UNISTD_H +Same as @samp{AC_CHECK_HEADERS(unistd.h)}. +@end defmac + +@defmac AC_USG +@maindex USG +@cvindex USG +Define @code{USG} if the @sc{bsd} string functions are defined in +@file{strings.h}. You should no longer depend upon @code{USG}, but on +@code{HAVE_STRING_H}, see @xref{Standard Symbols}. +@end defmac + +@defmac AC_UTIME_NULL +@maindex UTIME_NULL +@code{AC_FUNC_UTIME_NULL} +@end defmac + +@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd}) +@maindex VALIDATE_CACHED_SYSTEM_TUPLE +If the cache file is inconsistent with the current host, target and +build system types, it used to execute @var{cmd} or print a default +error message. + +This is now handled by default. +@end defmac + +@defmac AC_VERBOSE (@var{result-description}) +@maindex VERBOSE +@code{AC_MSG_RESULT}. +@end defmac + +@defmac AC_VFORK +@maindex VFORK +@code{AC_FUNC_VFORK} +@end defmac + +@defmac AC_VPRINTF +@maindex VPRINTF +@code{AC_FUNC_VPRINTF} +@end defmac + +@defmac AC_WAIT3 +@maindex WAIT3 +@code{AC_FUNC_WAIT3} +@end defmac + +@defmac AC_WARN +@maindex WARN +@code{AC_MSG_WARN} +@end defmac + +@defmac AC_WORDS_BIGENDIAN +@maindex WORDS_BIGENDIAN +@code{AC_C_BIGENDIAN} +@end defmac + +@defmac AC_XENIX_DIR +@maindex XENIX_DIR +@ovindex LIBS +This macro used to add @option{-lx} to output variable @code{LIBS} if on +Xenix. Also, if @file{dirent.h} is being checked for, added +@option{-ldir} to @code{LIBS}. Now it is merely an alias of +@code{AC_HEADER_DIRENT} instead, plus some code to detect whether +running @sc{xenix} on which you should not depend: + +@example +AC_MSG_CHECKING([for Xenix]) +AC_EGREP_CPP(yes, +[#if defined M_XENIX && !defined M_UNIX + yes +#endif], + [AC_MSG_RESULT([yes]); XENIX=yes], + [AC_MSG_RESULT([no]); XENIX=]) +@end example +@end defmac + +@defmac AC_YYTEXT_POINTER +@maindex YYTEXT_POINTER +@code{AC_DECL_YYTEXT} +@end defmac + +@node Autoconf 1, Autoconf 2.13, Obsolete Macros, Obsolete Constructs +@section Upgrading From Version 1 + +Autoconf version 2 is mostly backward compatible with version 1. +However, it introduces better ways to do some things, and doesn't +support some of the ugly things in version 1. So, depending on how +sophisticated your @file{configure.ac} files are, you might have to do +some manual work in order to upgrade to version 2. This chapter points +out some problems to watch for when upgrading. Also, perhaps your +@code{configure} scripts could benefit from some of the new features in +version 2; the changes are summarized in the file @file{NEWS} in the +Autoconf distribution. + +@menu +* Changed File Names:: Files you might rename +* Changed Makefiles:: New things to put in @file{Makefile.in} +* Changed Macros:: Macro calls you might replace +* Changed Results:: Changes in how to check test results +* Changed Macro Writing:: Better ways to write your own macros +@end menu + +@node Changed File Names, Changed Makefiles, Autoconf 1, Autoconf 1 +@subsection Changed File Names + +If you have an @file{aclocal.m4} installed with Autoconf (as opposed to +in a particular package's source directory), you must rename it to +@file{acsite.m4}. @xref{autoconf Invocation}. + +If you distribute @file{install.sh} with your package, rename it to +@file{install-sh} so @code{make} builtin rules won't inadvertently +create a file called @file{install} from it. @code{AC_PROG_INSTALL} +looks for the script under both names, but it is best to use the new name. + +If you were using @file{config.h.top}, @file{config.h.bot}, or +@file{acconfig.h}, you still can, but you will have less clutter if you +use the @code{AH_} macros. @xref{Autoheader Macros}. + +@node Changed Makefiles, Changed Macros, Changed File Names, Autoconf 1 +@subsection Changed Makefiles + +Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in +your @file{Makefile.in} files, so they can take advantage of the values +of those variables in the environment when @code{configure} is run. +Doing this isn't necessary, but it's a convenience for users. + +Also add @samp{@@configure_input@@} in a comment to each input file for +@code{AC_OUTPUT}, so that the output files will contain a comment saying +they were produced by @code{configure}. Automatically selecting the +right comment syntax for all the kinds of files that people call +@code{AC_OUTPUT} on became too much work. + +Add @file{config.log} and @file{config.cache} to the list of files you +remove in @code{distclean} targets. + +If you have the following in @file{Makefile.in}: + +@example +prefix = /usr/local +exec_prefix = $(prefix) +@end example + +@noindent +you must change it to: + +@example +prefix = @@prefix@@ +exec_prefix = @@exec_prefix@@ +@end example + +@noindent +The old behavior of replacing those variables without @samp{@@} +characters around them has been removed. + +@node Changed Macros, Changed Results, Changed Makefiles, Autoconf 1 +@subsection Changed Macros + +Many of the macros were renamed in Autoconf version 2. You can still +use the old names, but the new ones are clearer, and it's easier to find +the documentation for them. @xref{Obsolete Macros}, for a table showing the +new names for the old macros. Use the @code{autoupdate} program to +convert your @file{configure.ac} to using the new macro names. +@xref{autoupdate Invocation}. + +Some macros have been superseded by similar ones that do the job better, +but are not call-compatible. If you get warnings about calling obsolete +macros while running @code{autoconf}, you may safely ignore them, but +your @code{configure} script will generally work better if you follow +the advice it prints about what to replace the obsolete macros with. In +particular, the mechanism for reporting the results of tests has +changed. If you were using @code{echo} or @code{AC_VERBOSE} (perhaps +via @code{AC_COMPILE_CHECK}), your @code{configure} script's output will +look better if you switch to @code{AC_MSG_CHECKING} and +@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best +in conjunction with cache variables. @xref{Caching Results}. + + + +@node Changed Results, Changed Macro Writing, Changed Macros, Autoconf 1 +@subsection Changed Results + +If you were checking the results of previous tests by examining the +shell variable @code{DEFS}, you need to switch to checking the values of +the cache variables for those tests. @code{DEFS} no longer exists while +@code{configure} is running; it is only created when generating output +files. This difference from version 1 is because properly quoting the +contents of that variable turned out to be too cumbersome and +inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache +Variable Names}. + +For example, here is a @file{configure.ac} fragment written for Autoconf +version 1: + +@example +AC_HAVE_FUNCS(syslog) +case "$DEFS" in +*-DHAVE_SYSLOG*) ;; +*) # syslog is not in the default libraries. See if it's in some other. + saved_LIBS="$LIBS" + for lib in bsd socket inet; do + AC_CHECKING(for syslog in -l$lib) + LIBS="$saved_LIBS -l$lib" + AC_HAVE_FUNCS(syslog) + case "$DEFS" in + *-DHAVE_SYSLOG*) break ;; + *) ;; + esac + LIBS="$saved_LIBS" + done ;; +esac +@end example + +Here is a way to write it for version 2: + +@example +AC_CHECK_FUNCS(syslog) +if test $ac_cv_func_syslog = no; then + # syslog is not in the default libraries. See if it's in some other. + for lib in bsd socket inet; do + AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG) + LIBS="$LIBS -l$lib"; break]) + done +fi +@end example + +If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding +backslashes before quotes, you need to remove them. It now works +predictably, and does not treat quotes (except back quotes) specially. +@xref{Setting Output Variables}. + +All of the boolean shell variables set by Autoconf macros now use +@samp{yes} for the true value. Most of them use @samp{no} for false, +though for backward compatibility some use the empty string instead. If +you were relying on a shell variable being set to something like 1 or +@samp{t} for true, you need to change your tests. + +@node Changed Macro Writing, , Changed Results, Autoconf 1 +@subsection Changed Macro Writing + +When defining your own macros, you should now use @code{AC_DEFUN} +instead of @code{define}. @code{AC_DEFUN} automatically calls +@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE} +do not interrupt other macros, to prevent nested @samp{checking@dots{}} +messages on the screen. There's no actual harm in continuing to use the +older way, but it's less convenient and attractive. @xref{Macro +Definitions}. + +You probably looked at the macros that came with Autoconf as a guide for +how to do things. It would be a good idea to take a look at the new +versions of them, as the style is somewhat improved and they take +advantage of some new features. + +If you were doing tricky things with undocumented Autoconf internals +(macros, variables, diversions), check whether you need to change +anything to account for changes that have been made. Perhaps you can +even use an officially supported technique in version 2 instead of +kludging. Or perhaps not. + +To speed up your locally written feature tests, add caching to them. +See whether any of your tests are of general enough usefulness to +encapsulate into macros that you can share. + + +@node Autoconf 2.13, , Autoconf 1, Obsolete Constructs +@section Upgrading From Version 2.13 + +The introduction of the previous section (@pxref{Autoconf 1}) perfectly +suits this section... + +@quotation +Autoconf version 2.50 is mostly backward compatible with version 2.13. +However, it introduces better ways to do some things, and doesn't +support some of the ugly things in version 2.13. So, depending on how +sophisticated your @file{configure.ac} files are, you might have to do +some manual work in order to upgrade to version 2.50. This chapter +points out some problems to watch for when upgrading. Also, perhaps +your @code{configure} scripts could benefit from some of the new +features in version 2.50; the changes are summarized in the file +@file{NEWS} in the Autoconf distribution. +@end quotation + +@menu +* Changed Quotation:: Broken code which used to work +* New Macros:: Interaction with foreign macros +@end menu + +@node Changed Quotation, New Macros, Autoconf 2.13, Autoconf 2.13 +@subsection Changed Quotation + +The most important changes are invisible to you: the implementation of +most macros have completely changed. This allowed more factorization of +the code, better error messages, a higher uniformity of the user's +interface etc. Unfortunately, as a side effect, some construct which +used to (miraculously) work might break starting with Autoconf 2.50. +The most common culprit is bad quotation. + +For instance, in the following example, the message is not properly +quoted: + +@example +AC_INIT +AC_CHECK_HEADERS(foo.h,, +AC_MSG_ERROR(cannot find foo.h, bailing out)) +AC_OUTPUT +@end example + +@noindent +Autoconf 2.13 simply ignores it: + +@example +$ autoconf-2.13; ./configure --silent +creating cache ./config.cache +configure: error: cannot find foo.h +$ +@end example + +@noindent +while Autoconf 2.50 will produce a broken @file{configure}: + +@example +$ autoconf-2.50; ./configure --silent +configure: error: cannot find foo.h +./configure: exit: bad non-numeric arg `bailing' +./configure: exit: bad non-numeric arg `bailing' +$ +@end example + +The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation +too! + +@example +AC_INIT +AC_CHECK_HEADERS(foo.h,, + [AC_MSG_ERROR([cannot find foo.h, bailing out])]) +AC_OUTPUT +@end example + +Many many (and many more) Autoconf macros were lacking proper quotation, +including no less than... @code{AC_DEFUN} itself! + +@example +$ cat configure.in +AC_DEFUN([AC_PROG_INSTALL], +[# My own much better version +]) +AC_INIT +AC_PROG_INSTALL +AC_OUTPUT +$ autoconf-2.13 +autoconf: Undefined macros: +***BUG in Autoconf--please report*** AC_FD_MSG +***BUG in Autoconf--please report*** AC_EPI +configure.in:1:AC_DEFUN([AC_PROG_INSTALL], +configure.in:5:AC_PROG_INSTALL +$ autoconf-2.50 +$ +@end example + + +@node New Macros, , Changed Quotation, Autoconf 2.13 +@subsection New Macros + +@cindex @code{undefined macro: _m4_divert_diversion} + +Because Autoconf has been dormant for years, Automake provided +Autoconf-like macros for a while. Autoconf 2.50 now provides better +versions of these macros, integrated in the @code{AC_} namespace, +instead of @code{AM_}. But in order to ease the upgrading via +@command{autoupdate}, bindings to such @code{AM_} macros are provided. + +Unfortunately Automake did not quote the name of these macros! +Therefore, when @command{m4} find in @file{aclocal.m4} something like +@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)}, @code{AM_TYPE_PTRDIFF_T} is +expanded, replaced with its Autoconf definition. + +Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will +complain, in its own words: + +@example +$ cat configure.in +AC_INIT +AM_TYPE_PTRDIFF_T +$ aclocal-1.4 +$ autoconf +./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion +actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from... +./aclocal.m4:17: the top level +$ +@end example + +Future versions of Automake will simply no longer define most of these +macros, and will properly quote the names of the remaining macros. +But you don't have to wait for it to happen to do the right thing right +now: do not depend upon macros from Automake as it is simply not its job +to provide macros (but the one it requires by itself): + +@example +$ cat configure.in +AC_INIT +AM_TYPE_PTRDIFF_T +$ rm aclocal.m4 +$ autoupdate +autoupdate: `configure.in' is updated +$ cat configure.in +AC_INIT +AC_CHECK_TYPES([ptrdiff_t]) +$ aclocal-1.4 +$ autoconf +$ +@end example + +@c ================================================ Questions About Autoconf. + +@node Questions, History, Obsolete Constructs, Top +@chapter Questions About Autoconf + +Several questions about Autoconf come up occasionally. Here some of them +are addressed. + +@menu +* Distributing:: Distributing @code{configure} scripts +* Why GNU m4:: Why not use the standard M4? +* Bootstrapping:: Autoconf and GNU M4 require each other? +* Why Not Imake:: Why GNU uses @code{configure} instead of Imake +@end menu + +@node Distributing, Why GNU m4, Questions, Questions +@section Distributing @code{configure} Scripts + +@display +What are the restrictions on distributing @code{configure} +scripts that Autoconf generates? How does that affect my +programs that use them? +@end display + +There are no restrictions on how the configuration scripts that Autoconf +produces may be distributed or used. In Autoconf version 1, they were +covered by the @sc{gnu} General Public License. We still encourage +software authors to distribute their work under terms like those of the +GPL, but doing so is not required to use Autoconf. + +Of the other files that might be used with @code{configure}, +@file{config.h.in} is under whatever copyright you use for your +@file{configure.ac}. @file{config.sub} and @file{config.guess} have an +exception to the GPL when they are used with an Autoconf-generated +@code{configure} script, which permits you to distribute them under the +same terms as the rest of your package. @file{install-sh} is from the X +Consortium and is not copyrighted. + +@node Why GNU m4, Bootstrapping, Distributing, Questions +@section Why Require GNU M4? + +@display +Why does Autoconf require @sc{gnu} M4? +@end display + +Many M4 implementations have hard-coded limitations on the size and +number of macros that Autoconf exceeds. They also lack several +builtin macros that it would be difficult to get along without in a +sophisticated application like Autoconf, including: + +@example +builtin +indir +patsubst +__file__ +__line__ +@end example + +Autoconf requires version 1.4 or above of @sc{gnu} M4 because it uses +frozen state files. + +Since only software maintainers need to use Autoconf, and since @sc{gnu} +M4 is simple to configure and install, it seems reasonable to require +@sc{gnu} M4 to be installed also. Many maintainers of @sc{gnu} and +other free software already have most of the @sc{gnu} utilities +installed, since they prefer them. + +@node Bootstrapping, Why Not Imake, Why GNU m4, Questions +@section How Can I Bootstrap? + +@display +If Autoconf requires @sc{gnu} M4 and @sc{gnu} M4 has an Autoconf +@code{configure} script, how do I bootstrap? It seems like a chicken +and egg problem! +@end display + +This is a misunderstanding. Although @sc{gnu} M4 does come with a +@code{configure} script produced by Autoconf, Autoconf is not required +in order to run the script and install @sc{gnu} M4. Autoconf is only +required if you want to change the M4 @code{configure} script, which few +people have to do (mainly its maintainer). + +@node Why Not Imake, , Bootstrapping, Questions +@section Why Not Imake? + +@display +Why not use Imake instead of @code{configure} scripts? +@end display + +Several people have written addressing this question, so I include +adaptations of their explanations here. + +The following answer is based on one written by Richard Pixley: + +@quotation +Autoconf generated scripts frequently work on machines that it has +never been set up to handle before. That is, it does a good job of +inferring a configuration for a new system. Imake cannot do this. + +Imake uses a common database of host specific data. For X11, this makes +sense because the distribution is made as a collection of tools, by one +central authority who has control over the database. + +@sc{gnu} tools are not released this way. Each @sc{gnu} tool has a +maintainer; these maintainers are scattered across the world. Using a +common database would be a maintenance nightmare. Autoconf may appear +to be this kind of database, but in fact it is not. Instead of listing +host dependencies, it lists program requirements. + +If you view the @sc{gnu} suite as a collection of native tools, then the +problems are similar. But the @sc{gnu} development tools can be +configured as cross tools in almost any host+target permutation. All of +these configurations can be installed concurrently. They can even be +configured to share host independent files across hosts. Imake doesn't +address these issues. + +Imake templates are a form of standardization. The @sc{gnu} coding +standards address the same issues without necessarily imposing the same +restrictions. +@end quotation + + +Here is some further explanation, written by Per Bothner: + +@quotation +One of the advantages of Imake is that it easy to generate large +Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms. +However, @code{cpp} is not programmable: it has limited conditional +facilities, and no looping. And @code{cpp} cannot inspect its +environment. + +All of these problems are solved by using @code{sh} instead of +@code{cpp}. The shell is fully programmable, has macro substitution, +can execute (or source) other shell scripts, and can inspect its +environment. +@end quotation + + +Paul Eggert elaborates more: + +@quotation +With Autoconf, installers need not assume that Imake itself is already +installed and working well. This may not seem like much of an advantage +to people who are accustomed to Imake. But on many hosts Imake is not +installed or the default installation is not working well, and requiring +Imake to install a package hinders the acceptance of that package on +those hosts. For example, the Imake template and configuration files +might not be installed properly on a host, or the Imake build procedure +might wrongly assume that all source files are in one big directory +tree, or the Imake configuration might assume one compiler whereas the +package or the installer needs to use another, or there might be a +version mismatch between the Imake expected by the package and the Imake +supported by the host. These problems are much rarer with Autoconf, +where each package comes with its own independent configuration +processor. + +Also, Imake often suffers from unexpected interactions between +@code{make} and the installer's C preprocessor. The fundamental problem +here is that the C preprocessor was designed to preprocess C programs, +not @file{Makefile}s. This is much less of a problem with Autoconf, +which uses the general-purpose preprocessor @code{m4}, and where the +package's author (rather than the installer) does the preprocessing in a +standard way. +@end quotation + + +Finally, Mark Eichin notes: + +@quotation +Imake isn't all that extensible, either. In order to add new features to +Imake, you need to provide your own project template, and duplicate most +of the features of the existing one. This means that for a sophisticated +project, using the vendor-provided Imake templates fails to provide any +leverage---since they don't cover anything that your own project needs +(unless it is an X11 program). + +On the other side, though: + +The one advantage that Imake has over @code{configure}: +@file{Imakefile}s tend to be much shorter (likewise, less redundant) +than @file{Makefile.in}s. There is a fix to this, however---at least +for the Kerberos V5 tree, we've modified things to call in common +@file{post.in} and @file{pre.in} @file{Makefile} fragments for the +entire tree. This means that a lot of common things don't have to be +duplicated, even though they normally are in @code{configure} setups. +@end quotation + + + + +@c ===================================================== History of Autoconf. + +@node History, Environment Variable Index, Questions, Top +@chapter History of Autoconf + +You may be wondering, Why was Autoconf originally written? How did it +get into its present form? (Why does it look like gorilla spit?) If +you're not wondering, then this chapter contains no information useful +to you, and you might as well skip it. If you @emph{are} wondering, +then let there be light@dots{} + +@menu +* Genesis:: Prehistory and naming of @code{configure} +* Exodus:: The plagues of M4 and Perl +* Leviticus:: The priestly code of portability arrives +* Numbers:: Growth and contributors +* Deuteronomy:: Approaching the promises of easy configuration +@end menu + +@node Genesis, Exodus, History, History +@section Genesis + +In June 1991 I was maintaining many of the @sc{gnu} utilities for the +Free Software Foundation. As they were ported to more platforms and +more programs were added, the number of @option{-D} options that users +had to select in the @file{Makefile} (around 20) became burdensome. +Especially for me---I had to test each new release on a bunch of +different systems. So I wrote a little shell script to guess some of +the correct settings for the fileutils package, and released it as part +of fileutils 2.0. That @code{configure} script worked well enough that +the next month I adapted it (by hand) to create similar @code{configure} +scripts for several other @sc{gnu} utilities packages. Brian Berliner +also adapted one of my scripts for his @sc{cvs} revision control system. + +Later that summer, I learned that Richard Stallman and Richard Pixley +were developing similar scripts to use in the @sc{gnu} compiler tools; +so I adapted my @code{configure} scripts to support their evolving +interface: using the file name @file{Makefile.in} as the templates; +adding @samp{+srcdir}, the first option (of many); and creating +@file{config.status} files. + +@node Exodus, Leviticus, Genesis, History +@section Exodus + +As I got feedback from users, I incorporated many improvements, using +Emacs to search and replace, cut and paste, similar changes in each of +the scripts. As I adapted more @sc{gnu} utilities packages to use +@code{configure} scripts, updating them all by hand became impractical. +Rich Murphey, the maintainer of the @sc{gnu} graphics utilities, sent me +mail saying that the @code{configure} scripts were great, and asking if +I had a tool for generating them that I could send him. No, I thought, +but I should! So I started to work out how to generate them. And the +journey from the slavery of hand-written @code{configure} scripts to the +abundance and ease of Autoconf began. + +Cygnus @code{configure}, which was being developed at around that time, +is table driven; it is meant to deal mainly with a discrete number of +system types with a small number of mainly unguessable features (such as +details of the object file format). The automatic configuration system +that Brian Fox had developed for Bash takes a similar approach. For +general use, it seems to me a hopeless cause to try to maintain an +up-to-date database of which features each variant of each operating +system has. It's easier and more reliable to check for most features on +the fly---especially on hybrid systems that people have hacked on +locally or that have patches from vendors installed. + +I considered using an architecture similar to that of Cygnus +@code{configure}, where there is a single @code{configure} script that +reads pieces of @file{configure.in} when run. But I didn't want to have +to distribute all of the feature tests with every package, so I settled +on having a different @code{configure} made from each +@file{configure.in} by a preprocessor. That approach also offered more +control and flexibility. + +I looked briefly into using the Metaconfig package, by Larry Wall, +Harlan Stenn, and Raphael Manfredi, but I decided not to for several +reasons. The @code{Configure} scripts it produces are interactive, +which I find quite inconvenient; I didn't like the ways it checked for +some features (such as library functions); I didn't know that it was +still being maintained, and the @code{Configure} scripts I had +seen didn't work on many modern systems (such as System V R4 and NeXT); +it wasn't very flexible in what it could do in response to a feature's +presence or absence; I found it confusing to learn; and it was too big +and complex for my needs (I didn't realize then how much Autoconf would +eventually have to grow). + +I considered using Perl to generate my style of @code{configure} +scripts, but decided that M4 was better suited to the job of simple +textual substitutions: it gets in the way less, because output is +implicit. Plus, everyone already has it. (Initially I didn't rely on +the @sc{gnu} extensions to M4.) Also, some of my friends at the +University of Maryland had recently been putting M4 front ends on +several programs, including @code{tvtwm}, and I was interested in trying +out a new language. + +@node Leviticus, Numbers, Exodus, History +@section Leviticus + +Since my @code{configure} scripts determine the system's capabilities +automatically, with no interactive user intervention, I decided to call +the program that generates them Autoconfig. But with a version number +tacked on, that name would be too long for old @sc{unix} file systems, +so I shortened it to Autoconf. + +In the fall of 1991 I called together a group of fellow questers after +the Holy Grail of portability (er, that is, alpha testers) to give me +feedback as I encapsulated pieces of my handwritten scripts in M4 macros +and continued to add features and improve the techniques used in the +checks. Prominent among the testers were Fran@,cois Pinard, who came up +with the idea of making an @file{autoconf} shell script to run @code{m4} +and check for unresolved macro calls; Richard Pixley, who suggested +running the compiler instead of searching the file system to find +include files and symbols, for more accurate results; Karl Berry, who +got Autoconf to configure @TeX{} and added the macro index to the +documentation; and Ian Lance Taylor, who added support for creating a C +header file as an alternative to putting @option{-D} options in a +@file{Makefile}, so he could use Autoconf for his @sc{uucp} package. +The alpha testers cheerfully adjusted their files again and again as the +names and calling conventions of the Autoconf macros changed from +release to release. They all contributed many specific checks, great +ideas, and bug fixes. + +@node Numbers, Deuteronomy, Leviticus, History +@section Numbers + +In July 1992, after months of alpha testing, I released Autoconf 1.0, +and converted many @sc{gnu} packages to use it. I was surprised by how +positive the reaction to it was. More people started using it than I +could keep track of, including people working on software that wasn't +part of the @sc{gnu} Project (such as TCL, FSP, and Kerberos V5). +Autoconf continued to improve rapidly, as many people using the +@code{configure} scripts reported problems they encountered. + +Autoconf turned out to be a good torture test for M4 implementations. +@sc{unix} @code{m4} started to dump core because of the length of the +macros that Autoconf defined, and several bugs showed up in @sc{gnu} +@code{m4} as well. Eventually, we realized that we needed to use some +features that only @sc{gnu} M4 has. 4.3@sc{bsd} @code{m4}, in +particular, has an impoverished set of builtin macros; the System V +version is better, but still doesn't provide everything we need. + +More development occurred as people put Autoconf under more stresses +(and to uses I hadn't anticipated). Karl Berry added checks for X11. +david zuhn contributed C++ support. Fran@,cois Pinard made it diagnose +invalid arguments. Jim Blandy bravely coerced it into configuring +@sc{gnu} Emacs, laying the groundwork for several later improvements. +Roland McGrath got it to configure the @sc{gnu} C Library, wrote the +@code{autoheader} script to automate the creation of C header file +templates, and added a @option{--verbose} option to @code{configure}. +Noah Friedman added the @option{--autoconf-dir} option and +@code{AC_MACRODIR} environment variable. (He also coined the term +@dfn{autoconfiscate} to mean ``adapt a software package to use +Autoconf''.) Roland and Noah improved the quoting protection in +@code{AC_DEFINE} and fixed many bugs, especially when I got sick of +dealing with portability problems from February through June, 1993. + +@node Deuteronomy, , Numbers, History +@section Deuteronomy + +A long wish list for major features had accumulated, and the effect of +several years of patching by various people had left some residual +cruft. In April 1994, while working for Cygnus Support, I began a major +revision of Autoconf. I added most of the features of the Cygnus +@code{configure} that Autoconf had lacked, largely by adapting the +relevant parts of Cygnus @code{configure} with the help of david zuhn +and Ken Raeburn. These features include support for using +@file{config.sub}, @file{config.guess}, @option{--host}, and +@option{--target}; making links to files; and running @code{configure} +scripts in subdirectories. Adding these features enabled Ken to convert +@sc{gnu} @code{as}, and Rob Savoye to convert DejaGNU, to using +Autoconf. + +I added more features in response to other peoples' requests. Many +people had asked for @code{configure} scripts to share the results of +the checks between runs, because (particularly when configuring a large +source tree, like Cygnus does) they were frustratingly slow. Mike +Haertel suggested adding site-specific initialization scripts. People +distributing software that had to unpack on MS-DOS asked for a way to +override the @file{.in} extension on the file names, which produced file +names like @file{config.h.in} containing two dots. Jim Avera did an +extensive examination of the problems with quoting in @code{AC_DEFINE} +and @code{AC_SUBST}; his insights led to significant improvements. +Richard Stallman asked that compiler output be sent to @file{config.log} +instead of @file{/dev/null}, to help people debug the Emacs +@code{configure} script. + +I made some other changes because of my dissatisfaction with the quality +of the program. I made the messages showing results of the checks less +ambiguous, always printing a result. I regularized the names of the +macros and cleaned up coding style inconsistencies. I added some +auxiliary utilities that I had developed to help convert source code +packages to use Autoconf. With the help of Fran@,cois Pinard, I made +the macros not interrupt each others' messages. (That feature revealed +some performance bottlenecks in @sc{gnu} @code{m4}, which he hastily +corrected!) I reorganized the documentation around problems people want +to solve. And I began a test suite, because experience had shown that +Autoconf has a pronounced tendency to regress when we change it. + +Again, several alpha testers gave invaluable feedback, especially +Fran@,cois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, +and Mark Eichin. + +Finally, version 2.0 was ready. And there was much rejoicing. (And I +have free time again. I think. Yeah, right.) + + +@c ========================================================== Appendices + +@node Environment Variable Index, Output Variable Index, History, Top +@unnumbered Environment Variable Index + +This is an alphabetical list of the environment variables that Autoconf +checks. + +@printindex ev + +@node Output Variable Index, Preprocessor Symbol Index, Environment Variable Index, Top +@unnumbered Output Variable Index + +This is an alphabetical list of the variables that Autoconf can +substitute into files that it creates, typically one or more +@file{Makefile}s. @xref{Setting Output Variables}, for more information +on how this is done. + +@printindex ov + +@node Preprocessor Symbol Index, Autoconf Macro Index, Output Variable Index, Top +@unnumbered Preprocessor Symbol Index + +This is an alphabetical list of the C preprocessor symbols that the +Autoconf macros define. To work with Autoconf, C source code needs to +use these names in @code{#if} directives. + +@printindex cv + +@node Autoconf Macro Index, M4 Macro Index, Preprocessor Symbol Index, Top +@unnumbered Autoconf Macro Index + +This is an alphabetical list of the Autoconf macros. To make the list +easier to use, the macros are listed without their preceding @samp{AC_}. + +@printindex ma + +@node M4 Macro Index, Concept Index, Autoconf Macro Index, Top +@unnumbered M4 Macro Index + +This is an alphabetical list of the M4, M4sugar, and M4sh macros. To +make the list easier to use, the macros are listed without their +preceding @samp{m4_} or @samp{AS_}. + +@printindex ms + +@node Concept Index, , M4 Macro Index, Top +@unnumbered Concept Index + +This is an alphabetical list of the files, tools, and concepts +introduced in this document. + +@printindex cp + +@contents +@bye + +@c Local Variables: +@c ispell-local-dictionary: "american" +@c End: diff --git a/doc/install.texi b/doc/install.texi new file mode 100644 index 0000000..19fd35e --- /dev/null +++ b/doc/install.texi @@ -0,0 +1,258 @@ +@c This file is included by autoconf.texi and is used to produce +@c the INSTALL file. + +@node Basic Installation +@section Basic Installation + +These are generic installation instructions. + +The @code{configure} shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a @file{Makefile} in each directory of the +package. It may also create one or more @file{.h} files containing +system-dependent definitions. Finally, it creates a shell script +@file{config.status} that you can run in the future to recreate the +current configuration, and a file @file{config.log} containing compiler +output (useful mainly for debugging @code{configure}). + +It can also use an optional file (typically called @file{config.cache} +and enabled with @option{--cache-file=config.cache} or simply +@option{-C}) that saves the results of its tests to speed up +reconfiguring. (Caching is disabled by default to prevent problems with +accidental use of stale cache files.) + +If you need to do unusual things to compile the package, please try to +figure out how @code{configure} could check whether to do them, and mail +diffs or instructions to the address given in the @file{README} so they +can be considered for the next release. If you are using the cache, and +at some point @file{config.cache} contains results you don't want to +keep, you may remove or edit it. + +The file @file{configure.ac} (or @file{configure.in}) is used to create +@file{configure} by a program called @code{autoconf}. You only need +@file{configure.ac} if you want to change it or regenerate +@file{configure} using a newer version of @code{autoconf}. + +@noindent +The simplest way to compile this package is: + +@enumerate +@item +@code{cd} to the directory containing the package's source code and type +@samp{./configure} to configure the package for your system. If you're +using @code{csh} on an old version of System V, you might need to type +@samp{sh ./configure} instead to prevent @code{csh} from trying to +execute @code{configure} itself. + +Running @code{configure} takes awhile. While running, it prints some +messages telling which features it is checking for. + +@item +Type @samp{make} to compile the package. + +@item +Optionally, type @samp{make check} to run any self-tests that come with +the package. + +@item +Type @samp{make install} to install the programs and any data files and +documentation. + +@item +You can remove the program binaries and object files from the source code +directory by typing @samp{make clean}. To also remove the files that +@code{configure} created (so you can compile the package for a different +kind of computer), type @samp{make distclean}. There is also a +@samp{make maintainer-clean} target, but that is intended mainly for the +package's developers. If you use it, you may have to get all sorts of +other programs in order to regenerate files that came with the distribution. +@end enumerate + +@node Compilers and Options +@section Compilers and Options + +Some systems require unusual options for compilation or linking that the +@code{configure} script does not know about. Run @samp{./configure +--help} for details on some of the pertinent environment variables. + +You can give @code{configure} initial values for variables by setting +them in the environment. You can do that on the command line like this: + +@example +./configure CC=c89 CFLAGS=-O2 LIBS=-lposix +@end example + +@xref{Environment Variables}, for more details. + + +@node Multiple Architectures +@section Compiling For Multiple Architectures + +You can compile the package for more than one kind of computer at the +same time, by placing the object files for each architecture in their +own directory. To do this, you must use a version of @code{make} that +supports the @code{VPATH} variable, such as GNU @code{make}. @code{cd} +to the directory where you want the object files and executables to go +and run the @code{configure} script. @code{configure} automatically +checks for the source code in the directory that @code{configure} is in +and in @file{..}. + +If you have to use a @code{make} that does not support the @code{VPATH} +variable, you have to compile the package for one architecture at a time +in the source code directory. After you have installed the package for +one architecture, use @samp{make distclean} before reconfiguring for +another architecture. + +@node Installation Names +@section Installation Names + +By default, @samp{make install} will install the package's files in +@file{/usr/local/bin}, @file{/usr/local/man}, etc. You can specify an +installation prefix other than @file{/usr/local} by giving +@code{configure} the option @option{--prefix=@var{path}}. + +You can specify separate installation prefixes for architecture-specific +files and architecture-independent files. If you give @code{configure} +the option @option{--exec-prefix=@var{path}}, the package will use +@var{path} as the prefix for installing programs and libraries. +Documentation and other data files will still use the regular prefix. + +In addition, if you use an unusual directory layout you can give options +like @option{--bindir=@var{path}} to specify different values for +particular kinds of files. Run @samp{configure --help} for a list of +the directories you can set and what kinds of files go in them. + +If the package supports it, you can cause programs to be installed with +an extra prefix or suffix on their names by giving @code{configure} the +option @option{--program-prefix=@var{PREFIX}} or +@option{--program-suffix=@var{SUFFIX}}. + +@node Optional Features +@section Optional Features + +Some packages pay attention to @option{--enable-@var{feature}} options +to @code{configure}, where @var{feature} indicates an optional part of +the package. They may also pay attention to +@option{--with-@var{package}} options, where @var{package} is something +like @samp{gnu-as} or @samp{x} (for the X Window System). The +@file{README} should mention any @option{--enable-} and @option{--with-} +options that the package recognizes. + +For packages that use the X Window System, @code{configure} can usually +find the X include and library files automatically, but if it doesn't, +you can use the @code{configure} options @option{--x-includes=@var{dir}} +and @option{--x-libraries=@var{dir}} to specify their locations. + +@node System Type +@section Specifying the System Type + +There may be some features @code{configure} cannot figure out +automatically, but needs to determine by the type of host the package +will run on. Usually @code{configure} can figure that out, but if it +prints a message saying it cannot guess the host type, give it the +@option{--build=@var{type}} option. @var{type} can either be a short +name for the system type, such as @samp{sun4}, or a canonical name which +has the form: + +@example +@var{cpu}-@var{company}-@var{system} +@end example + +@noindent +where @var{system} can have one of these forms: + +@example +@var{os} +@var{kernel}-@var{os} +@end example + +See the file @file{config.sub} for the possible values of each field. +If @file{config.sub} isn't included in this package, then this package +doesn't need to know the host type. + +If you are @emph{building} compiler tools for cross-compiling, you should +use the @option{--target=@var{type}} option to select the type of system +they will produce code for. + +If you want to @emph{use} a cross compiler, that generates code for a +platform different from the build platform, you should specify the host +platform (i.e., that on which the generated programs will eventually be +run) with @option{--host=@var{type}}. In this case, you should also +specify the build platform with @option{--build=@var{type}}, because, in +this case, it may not be possible to guess the build platform (it +sometimes involves compiling and running simple test programs, and this +can't be done if the compiler is a cross compiler). + +@node Sharing Defaults +@section Sharing Defaults + +If you want to set default values for @code{configure} scripts to share, +you can create a site shell script called @file{config.site} that gives +default values for variables like @code{CC}, @code{cache_file}, and +@code{prefix}. @code{configure} looks for +@file{@var{prefix}/share/config.site} if it exists, then +@file{@var{prefix}/etc/config.site} if it exists. Or, you can set the +@code{CONFIG_SITE} environment variable to the location of the site +script. A warning: not all @code{configure} scripts look for a site +script. + +@node Environment Variables +@section Environment Variables + +Variables not defined in a site shell script can be set in the +environment passed to configure. However, some packages may run +configure again during the build, and the customized values of these +variables may be lost. In order to avoid this problem, you should set +them in the @code{configure} command line, using @samp{VAR=value}. For +example: + +@example +./configure CC=/usr/local2/bin/gcc +@end example + +@noindent +will cause the specified gcc to be used as the C compiler (unless it is +overridden in the site shell script). + + +@node configure Invocation +@section @code{configure} Invocation + +@code{configure} recognizes the following options to control how it +operates. + +@table @option +@item --help +@itemx -h +Print a summary of the options to @code{configure}, and exit. + +@item --version +@itemx -V +Print the version of Autoconf used to generate the @code{configure} +script, and exit. + +@item --cache-file=@var{file} +@cindex Cache, enabling +Enable the cache: use and save the results of the tests in @var{file}, +traditionally @file{config.cache}. @var{file} defaults to +@file{/dev/null} to disable caching. + +@item --config-cache +@itemx -C +Alias for @option{--cache-file=config.cache}. + +@item --quiet +@itemx --silent +@itemx -q +Do not print messages saying which checks are being made. To suppress +all normal output, redirect it to @file{/dev/null} (any error messages +will still be shown). + +@item --srcdir=@var{dir} +Look for the package's source code in directory @var{dir}. Usually +@code{configure} can determine that directory automatically. +@end table + +@noindent +@code{configure} also accepts some other, not widely useful, options. +Run @samp{configure --help} for more details. diff --git a/doc/make-stds.texi b/doc/make-stds.texi new file mode 100644 index 0000000..68faa8d --- /dev/null +++ b/doc/make-stds.texi @@ -0,0 +1,944 @@ +@comment This file is included by both standards.texi and make.texinfo. +@comment It was broken out of standards.texi on 1/6/93 by roland. + +@node Makefile Conventions +@chapter Makefile Conventions +@comment standards.texi does not print an index, but make.texinfo does. +@cindex makefile, conventions for +@cindex conventions for makefiles +@cindex standards for makefiles + +This +@ifinfo +node +@end ifinfo +@iftex +@ifset CODESTD +section +@end ifset +@ifclear CODESTD +chapter +@end ifclear +@end iftex +describes conventions for writing the Makefiles for GNU programs. +Using Automake will help you write a Makefile that follows these +conventions. + +@menu +* Makefile Basics:: General Conventions for Makefiles +* Utilities in Makefiles:: Utilities in Makefiles +* Command Variables:: Variables for Specifying Commands +* Directory Variables:: Variables for Installation Directories +* Standard Targets:: Standard Targets for Users +* Install Command Categories:: Three categories of commands in the `install' + rule: normal, pre-install and post-install. +@end menu + +@node Makefile Basics +@section General Conventions for Makefiles + +Every Makefile should contain this line: + +@example +SHELL = /bin/sh +@end example + +@noindent +to avoid trouble on systems where the @code{SHELL} variable might be +inherited from the environment. (This is never a problem with GNU +@code{make}.) + +Different @code{make} programs have incompatible suffix lists and +implicit rules, and this sometimes creates confusion or misbehavior. So +it is a good idea to set the suffix list explicitly using only the +suffixes you need in the particular Makefile, like this: + +@example +.SUFFIXES: +.SUFFIXES: .c .o +@end example + +@noindent +The first line clears out the suffix list, the second introduces all +suffixes which may be subject to implicit rules in this Makefile. + +Don't assume that @file{.} is in the path for command execution. When +you need to run programs that are a part of your package during the +make, please make sure that it uses @file{./} if the program is built as +part of the make or @file{$(srcdir)/} if the file is an unchanging part +of the source code. Without one of these prefixes, the current search +path is used. + +The distinction between @file{./} (the @dfn{build directory}) and +@file{$(srcdir)/} (the @dfn{source directory}) is important because +users can build in a separate directory using the @samp{--srcdir} option +to @file{configure}. A rule of the form: + +@smallexample +foo.1 : foo.man sedscript + sed -e sedscript foo.man > foo.1 +@end smallexample + +@noindent +will fail when the build directory is not the source directory, because +@file{foo.man} and @file{sedscript} are in the source directory. + +When using GNU @code{make}, relying on @samp{VPATH} to find the source +file will work in the case where there is a single dependency file, +since the @code{make} automatic variable @samp{$<} will represent the +source file wherever it is. (Many versions of @code{make} set @samp{$<} +only in implicit rules.) A Makefile target like + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o +@end smallexample + +@noindent +should instead be written as + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@ +@end smallexample + +@noindent +in order to allow @samp{VPATH} to work correctly. When the target has +multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest +way to make the rule work well. For example, the target above for +@file{foo.1} is best written as: + +@smallexample +foo.1 : foo.man sedscript + sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ +@end smallexample + +GNU distributions usually contain some files which are not source +files---for example, Info files, and the output from Autoconf, Automake, +Bison or Flex. Since these files normally appear in the source +directory, they should always appear in the source directory, not in the +build directory. So Makefile rules to update them should put the +updated files in the source directory. + +However, if a file does not appear in the distribution, then the +Makefile should not put it in the source directory, because building a +program in ordinary circumstances should not modify the source directory +in any way. + +Try to make the build and installation targets, at least (and all their +subtargets) work correctly with a parallel @code{make}. + +@node Utilities in Makefiles +@section Utilities in Makefiles + +Write the Makefile commands (and any shell scripts, such as +@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any +special features of @code{ksh} or @code{bash}. + +The @code{configure} script and the Makefile rules for building and +installation should not use any utilities directly except these: + +@c dd find +@c gunzip gzip md5sum +@c mkfifo mknod tee uname + +@example +cat cmp cp diff echo egrep expr false grep install-info +ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true +@end example + +The compression program @code{gzip} can be used in the @code{dist} rule. + +Stick to the generally supported options for these programs. For +example, don't use @samp{mkdir -p}, convenient as it may be, because +most systems don't support it. + +It is a good idea to avoid creating symbolic links in makefiles, since a +few systems don't support them. + +The Makefile rules for building and installation can also use compilers +and related programs, but should do so via @code{make} variables so that the +user can substitute alternatives. Here are some of the programs we +mean: + +@example +ar bison cc flex install ld ldconfig lex +make makeinfo ranlib texi2dvi yacc +@end example + +Use the following @code{make} variables to run those programs: + +@example +$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) +$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) +@end example + +When you use @code{ranlib} or @code{ldconfig}, you should make sure +nothing bad happens if the system does not have the program in question. +Arrange to ignore an error from that command, and print a message before +the command to tell the user that failure of this command does not mean +a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with +this.) + +If you use symbolic links, you should implement a fallback for systems +that don't have symbolic links. + +Additional utilities that can be used via Make variables are: + +@example +chgrp chmod chown mknod +@end example + +It is ok to use other utilities in Makefile portions (or scripts) +intended only for particular systems where you know those utilities +exist. + +@node Command Variables +@section Variables for Specifying Commands + +Makefiles should provide variables for overriding certain commands, options, +and so on. + +In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named @code{BISON} whose default +value is set with @samp{BISON = bison}, and refer to it with +@code{$(BISON)} whenever you need to use Bison. + +File management utilities such as @code{ln}, @code{rm}, @code{mv}, and +so on, need not be referred to through variables in this way, since users +don't need to replace them with other programs. + +Each program-name variable should come with an options variable that is +used to supply options to the program. Append @samp{FLAGS} to the +program-name variable name to get the options variable name---for +example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C +compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are +exceptions to this rule, but we keep them because they are standard.) +Use @code{CPPFLAGS} in any compilation command that runs the +preprocessor, and use @code{LDFLAGS} in any compilation command that +does linking as well as in any direct use of @code{ld}. + +If there are C compiler options that @emph{must} be used for proper +compilation of certain files, do not include them in @code{CFLAGS}. +Users expect to be able to specify @code{CFLAGS} freely themselves. +Instead, arrange to pass the necessary options to the C compiler +independently of @code{CFLAGS}, by writing them explicitly in the +compilation commands or by defining an implicit rule, like this: + +@smallexample +CFLAGS = -g +ALL_CFLAGS = -I. $(CFLAGS) +.c.o: + $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< +@end smallexample + +Do include the @samp{-g} option in @code{CFLAGS}, because that is not +@emph{required} for proper compilation. You can consider it a default +that is only recommended. If the package is set up so that it is +compiled with GCC by default, then you might as well include @samp{-O} +in the default value of @code{CFLAGS} as well. + +Put @code{CFLAGS} last in the compilation command, after other variables +containing compiler options, so the user can use @code{CFLAGS} to +override the others. + +@code{CFLAGS} should be used in every invocation of the C compiler, +both those which do compilation and those which do linking. + +Every Makefile should define the variable @code{INSTALL}, which is the +basic command for installing a file into the system. + +Every Makefile should also define the variables @code{INSTALL_PROGRAM} +and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should +be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be +@code{$@{INSTALL@} -m 644}.) Then it should use those variables as the +commands for actual installation, for executables and nonexecutables +respectively. Use these variables as follows: + +@example +$(INSTALL_PROGRAM) foo $(bindir)/foo +$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a +@end example + +Optionally, you may prepend the value of @code{DESTDIR} to the target +filename. Doing this allows the installer to create a snapshot of the +installation to be copied onto the real target filesystem later. Do not +set the value of @code{DESTDIR} in your Makefile, and do not include it +in any installed files. With support for @code{DESTDIR}, the above +examples become: + +@example +$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo +$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a +@end example + +@noindent +Always use a file name, not a directory name, as the second argument of +the installation commands. Use a separate command for each file to be +installed. + +@node Directory Variables +@section Variables for Installation Directories + +Installation directories should always be named by variables, so it is +easy to install in a nonstandard place. The standard names for these +variables are described below. They are based on a standard filesystem +layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4, +and other modern operating systems. + +These two variables set the root for the installation. All the other +installation directories should be subdirectories of one of these two, +and nothing should be directly installed into these two directories. + +@table @code +@item prefix +@vindex prefix +A prefix used in constructing the default values of the variables listed +below. The default value of @code{prefix} should be @file{/usr/local}. +When building the complete GNU system, the prefix will be empty and +@file{/usr} will be a symbolic link to @file{/}. +(If you are using Autoconf, write it as @samp{@@prefix@@}.) + +Running @samp{make install} with a different value of @code{prefix} from +the one used to build the program should @emph{not} recompile the +program. + +@item exec_prefix +@vindex exec_prefix +A prefix used in constructing the default values of some of the +variables listed below. The default value of @code{exec_prefix} should +be @code{$(prefix)}. +(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.) + +Generally, @code{$(exec_prefix)} is used for directories that contain +machine-specific files (such as executables and subroutine libraries), +while @code{$(prefix)} is used directly for other directories. + +Running @samp{make install} with a different value of @code{exec_prefix} +from the one used to build the program should @emph{not} recompile the +program. +@end table + +Executable programs are installed in one of the following directories. + +@table @code +@item bindir +@vindex bindir +The directory for installing executable programs that users can run. +This should normally be @file{/usr/local/bin}, but write it as +@file{$(exec_prefix)/bin}. +(If you are using Autoconf, write it as @samp{@@bindir@@}.) + +@item sbindir +@vindex sbindir +The directory for installing executable programs that can be run from +the shell, but are only generally useful to system administrators. This +should normally be @file{/usr/local/sbin}, but write it as +@file{$(exec_prefix)/sbin}. +(If you are using Autoconf, write it as @samp{@@sbindir@@}.) + +@item libexecdir +@vindex libexecdir +@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 +The directory for installing executable programs to be run by other +programs rather than by users. This directory should normally be +@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. +(If you are using Autoconf, write it as @samp{@@libexecdir@@}.) +@end table + +Data files used by the program during its execution are divided into +categories in two ways. + +@itemize @bullet +@item +Some files are normally modified by programs; others are never normally +modified (though users may edit some of these). + +@item +Some files are architecture-independent and can be shared by all +machines at a site; some are architecture-dependent and can be shared +only by machines of the same kind and operating system; others may never +be shared between two machines. +@end itemize + +This makes for six different possibilities. However, we want to +discourage the use of architecture-dependent files, aside from object +files and libraries. It is much cleaner to make other data files +architecture-independent, and it is generally not hard. + +Therefore, here are the variables Makefiles should use to specify +directories: + +@table @samp +@item datadir +The directory for installing read-only architecture independent data +files. This should normally be @file{/usr/local/share}, but write it as +@file{$(prefix)/share}. +(If you are using Autoconf, write it as @samp{@@datadir@@}.) +As a special exception, see @file{$(infodir)} +and @file{$(includedir)} below. + +@item sysconfdir +The directory for installing read-only data files that pertain to a +single machine--that is to say, files for configuring a host. Mailer +and network configuration files, @file{/etc/passwd}, and so forth belong +here. All the files in this directory should be ordinary ASCII text +files. This directory should normally be @file{/usr/local/etc}, but +write it as @file{$(prefix)/etc}. +(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.) + +Do not install executables here in this directory (they probably belong +in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install +files that are modified in the normal course of their use (programs +whose purpose is to change the configuration of the system excluded). +Those probably belong in @file{$(localstatedir)}. + +@item sharedstatedir +The directory for installing architecture-independent data files which +the programs modify while they run. This should normally be +@file{/usr/local/com}, but write it as @file{$(prefix)/com}. +(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.) + +@item localstatedir +The directory for installing data files which the programs modify while +they run, and that pertain to one specific machine. Users should never +need to modify files in this directory to configure the package's +operation; put such configuration information in separate files that go +in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)} +should normally be @file{/usr/local/var}, but write it as +@file{$(prefix)/var}. +(If you are using Autoconf, write it as @samp{@@localstatedir@@}.) + +@item libdir +The directory for object files and libraries of object code. Do not +install executables here, they probably ought to go in @file{$(libexecdir)} +instead. The value of @code{libdir} should normally be +@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. +(If you are using Autoconf, write it as @samp{@@libdir@@}.) + +@item infodir +The directory for installing the Info files for this package. By +default, it should be @file{/usr/local/info}, but it should be written +as @file{$(prefix)/info}. +(If you are using Autoconf, write it as @samp{@@infodir@@}.) + +@item lispdir +The directory for installing any Emacs Lisp files in this package. By +default, it should be @file{/usr/local/share/emacs/site-lisp}, but it +should be written as @file{$(prefix)/share/emacs/site-lisp}. + +If you are using Autoconf, write the default as @samp{@@lispdir@@}. +In order to make @samp{@@lispdir@@} work, you need the following lines +in your @file{configure.in} file: + +@example +lispdir='$@{datadir@}/emacs/site-lisp' +AC_SUBST(lispdir) +@end example + +@item includedir +@c rewritten to avoid overfull hbox --roland +The directory for installing header files to be included by user +programs with the C @samp{#include} preprocessor directive. This +should normally be @file{/usr/local/include}, but write it as +@file{$(prefix)/include}. +(If you are using Autoconf, write it as @samp{@@includedir@@}.) + +Most compilers other than GCC do not look for header files in directory +@file{/usr/local/include}. So installing the header files this way is +only useful with GCC. Sometimes this is not a problem because some +libraries are only really intended to work with GCC. But some libraries +are intended to work with other compilers. They should install their +header files in two places, one specified by @code{includedir} and one +specified by @code{oldincludedir}. + +@item oldincludedir +The directory for installing @samp{#include} header files for use with +compilers other than GCC. This should normally be @file{/usr/include}. +(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.) + +The Makefile commands should check whether the value of +@code{oldincludedir} is empty. If it is, they should not try to use +it; they should cancel the second installation of the header files. + +A package should not replace an existing header in this directory unless +the header came from the same package. Thus, if your Foo package +provides a header file @file{foo.h}, then it should install the header +file in the @code{oldincludedir} directory if either (1) there is no +@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo +package. + +To tell whether @file{foo.h} came from the Foo package, put a magic +string in the file---part of a comment---and @code{grep} for that string. +@end table + +Unix-style man pages are installed in one of the following: + +@table @samp +@item mandir +The top-level directory for installing the man pages (if any) for this +package. It will normally be @file{/usr/local/man}, but you should +write it as @file{$(prefix)/man}. +(If you are using Autoconf, write it as @samp{@@mandir@@}.) + +@item man1dir +The directory for installing section 1 man pages. Write it as +@file{$(mandir)/man1}. +@item man2dir +The directory for installing section 2 man pages. Write it as +@file{$(mandir)/man2} +@item @dots{} + +@strong{Don't make the primary documentation for any GNU software be a +man page. Write a manual in Texinfo instead. Man pages are just for +the sake of people running GNU software on Unix, which is a secondary +application only.} + +@item manext +The file name extension for the installed man page. This should contain +a period followed by the appropriate digit; it should normally be @samp{.1}. + +@item man1ext +The file name extension for installed section 1 man pages. +@item man2ext +The file name extension for installed section 2 man pages. +@item @dots{} +Use these names instead of @samp{manext} if the package needs to install man +pages in more than one section of the manual. +@end table + +And finally, you should set the following variable: + +@table @samp +@item srcdir +The directory for the sources being compiled. The value of this +variable is normally inserted by the @code{configure} shell script. +(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.) +@end table + +For example: + +@smallexample +@c I have changed some of the comments here slightly to fix an overfull +@c hbox, so the make manual can format correctly. --roland +# Common prefix for installation directories. +# NOTE: This directory must exist when you start the install. +prefix = /usr/local +exec_prefix = $(prefix) +# Where to put the executable for the command `gcc'. +bindir = $(exec_prefix)/bin +# Where to put the directories used by the compiler. +libexecdir = $(exec_prefix)/libexec +# Where to put the Info files. +infodir = $(prefix)/info +@end smallexample + +If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the @code{install} rule to create these subdirectories. + +Do not expect the user to include the subdirectory name in the value of +any of the variables listed above. The idea of having a uniform set of +variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. + +@node Standard Targets +@section Standard Targets for Users + +All GNU programs should have the following targets in their Makefiles: + +@table @samp +@item all +Compile the entire program. This should be the default target. This +target need not rebuild any documentation files; Info files should +normally be included in the distribution, and DVI files should be made +only when explicitly asked for. + +By default, the Make rules should compile and link with @samp{-g}, so +that executable programs have debugging symbols. Users who don't mind +being helpless can strip the executables later if they wish. + +@item install +Compile the program and copy the executables, libraries, and so on to +the file names where they should reside for actual use. If there is a +simple test to verify that a program is properly installed, this target +should run that test. + +Do not strip executables when installing them. Devil-may-care users can +use the @code{install-strip} target to do that. + +If possible, write the @code{install} target rule so that it does not +modify anything in the directory where the program was built, provided +@samp{make all} has just been done. This is convenient for building the +program under one user name and installing it under another. + +The commands should create all the directories in which files are to be +installed, if they don't already exist. This includes the directories +specified as the values of the variables @code{prefix} and +@code{exec_prefix}, as well as all subdirectories that are needed. +One way to do this is by means of an @code{installdirs} target +as described below. + +Use @samp{-} before any command for installing a man page, so that +@code{make} will ignore any errors. This is in case there are systems +that don't have the Unix man page documentation system installed. + +The way to install Info files is to copy them into @file{$(infodir)} +with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run +the @code{install-info} program if it is present. @code{install-info} +is a program that edits the Info @file{dir} file to add or update the +menu entry for the given Info file; it is part of the Texinfo package. +Here is a sample rule to install an Info file: + +@comment This example has been carefully formatted for the Make manual. +@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. +@smallexample +$(DESTDIR)$(infodir)/foo.info: foo.info + $(POST_INSTALL) +# There may be a newer info file in . than in srcdir. + -if test -f foo.info; then d=.; \ + else d=$(srcdir); fi; \ + $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \ +# Run install-info only if it exists. +# Use `if' instead of just prepending `-' to the +# line so we notice real errors from install-info. +# We use `$(SHELL) -c' because some shells do not +# fail gracefully when there is an unknown command. + if $(SHELL) -c 'install-info --version' \ + >/dev/null 2>&1; then \ + install-info --dir-file=$(DESTDIR)$(infodir)/dir \ + $(DESTDIR)$(infodir)/foo.info; \ + else true; fi +@end smallexample + +When writing the @code{install} target, you must classify all the +commands into three categories: normal ones, @dfn{pre-installation} +commands and @dfn{post-installation} commands. @xref{Install Command +Categories}. + +@item uninstall +Delete all the installed files---the copies that the @samp{install} +target creates. + +This rule should not modify the directories where compilation is done, +only the directories where files are installed. + +The uninstallation commands are divided into three categories, just like +the installation commands. @xref{Install Command Categories}. + +@item install-strip +Like @code{install}, but strip the executable files while installing +them. In simple cases, this target can use the @code{install} target in +a simple way: + +@smallexample +install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install +@end smallexample + +But if the package installs scripts as well as real executables, the +@code{install-strip} target can't just refer to the @code{install} +target; it has to strip the executables but not the scripts. + +@code{install-strip} should not strip the executables in the build +directory which are being copied for installation. It should only strip +the copies that are installed. + +Normally we do not recommend stripping an executable unless you are sure +the program has no bugs. However, it can be reasonable to install a +stripped executable for actual execution while saving the unstripped +executable elsewhere in case there is a bug. + +@comment The gratuitous blank line here is to make the table look better +@comment in the printed Make manual. Please leave it in. +@item clean + +Delete all files from the current directory that are normally created by +building the program. Don't delete the files that record the +configuration. Also preserve files that could be made by building, but +normally aren't because the distribution comes with them. + +Delete @file{.dvi} files here if they are not part of the distribution. + +@item distclean +Delete all files from the current directory that are created by +configuring or building the program. If you have unpacked the source +and built the program without creating any other files, @samp{make +distclean} should leave only the files that were in the distribution. + +@item mostlyclean +Like @samp{clean}, but may refrain from deleting a few files that people +normally don't want to recompile. For example, the @samp{mostlyclean} +target for GCC does not delete @file{libgcc.a}, because recompiling it +is rarely necessary and takes a lot of time. + +@item maintainer-clean +Delete almost everything from the current directory that can be +reconstructed with this Makefile. This typically includes everything +deleted by @code{distclean}, plus more: C source files produced by +Bison, tags tables, Info files, and so on. + +The reason we say ``almost everything'' is that running the command +@samp{make maintainer-clean} should not delete @file{configure} even if +@file{configure} can be remade using a rule in the Makefile. More generally, +@samp{make maintainer-clean} should not delete anything that needs to +exist in order to run @file{configure} and then begin to build the +program. This is the only exception; @code{maintainer-clean} should +delete everything else that can be rebuilt. + +The @samp{maintainer-clean} target is intended to be used by a maintainer of +the package, not by ordinary users. You may need special tools to +reconstruct some of the files that @samp{make maintainer-clean} deletes. +Since these files are normally included in the distribution, we don't +take care to make them easy to reconstruct. If you find you need to +unpack the full distribution again, don't blame us. + +To help make users aware of this, the commands for the special +@code{maintainer-clean} target should start with these two: + +@smallexample +@@echo 'This command is intended for maintainers to use; it' +@@echo 'deletes files that may need special tools to rebuild.' +@end smallexample + +@item TAGS +Update a tags table for this program. +@c ADR: how? + +@item info +Generate any Info files needed. The best way to write the rules is as +follows: + +@smallexample +info: foo.info + +foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{MAKEINFO} in the Makefile. It should +run the @code{makeinfo} program, which is part of the Texinfo +distribution. + +Normally a GNU distribution comes with Info files, and that means the +Info files are present in the source directory. Therefore, the Make +rule for an info file should update it in the source directory. When +users build the package, ordinarily Make will not update the Info files +because they will already be up to date. + +@item dvi +Generate DVI files for all Texinfo documentation. +For example: + +@smallexample +dvi: foo.dvi + +foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{TEXI2DVI} in the Makefile. It should +run the program @code{texi2dvi}, which is part of the Texinfo +distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work +of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, +write just the dependencies, and allow GNU @code{make} to provide the command. + +@item dist +Create a distribution tar file for this program. The tar file should be +set up so that the file names in the tar file start with a subdirectory +name which is the name of the package it is a distribution for. This +name can include the version number. + +For example, the distribution tar file of GCC version 1.40 unpacks into +a subdirectory named @file{gcc-1.40}. + +The easiest way to do this is to create a subdirectory appropriately +named, use @code{ln} or @code{cp} to install the proper files in it, and +then @code{tar} that subdirectory. + +Compress the tar file with @code{gzip}. For example, the actual +distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}. + +The @code{dist} target should explicitly depend on all non-source files +that are in the distribution, to make sure they are up to date in the +distribution. +@ifset CODESTD +@xref{Releases, , Making Releases}. +@end ifset +@ifclear CODESTD +@xref{Releases, , Making Releases, standards, GNU Coding Standards}. +@end ifclear + +@item check +Perform self-tests (if any). The user must build the program before +running the tests, but need not install the program; you should write +the self-tests so that they work when the program is built but not +installed. +@end table + +The following targets are suggested as conventional names, for programs +in which they are useful. + +@table @code +@item installcheck +Perform installation tests (if any). The user must build and install +the program before running the tests. You should not assume that +@file{$(bindir)} is in the search path. + +@item installdirs +It's useful to add a target named @samp{installdirs} to create the +directories where files are installed, and their parent directories. +There is a script called @file{mkinstalldirs} which is convenient for +this; you can find it in the Texinfo package. +@c It's in /gd/gnu/lib/mkinstalldirs. +You can use a rule like this: + +@comment This has been carefully formatted to look decent in the Make manual. +@comment Please be sure not to make it extend any further to the right.--roland +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) +@end smallexample + +@noindent +or, if you wish to support @env{DESTDIR}, + +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs \ + $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ + $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ + $(DESTDIR)$(mandir) +@end smallexample + +This rule should not modify the directories where compilation is done. +It should do nothing but create installation directories. +@end table + +@node Install Command Categories +@section Install Command Categories + +@cindex pre-installation commands +@cindex post-installation commands +When writing the @code{install} target, you must classify all the +commands into three categories: normal ones, @dfn{pre-installation} +commands and @dfn{post-installation} commands. + +Normal commands move files into their proper places, and set their +modes. They may not alter any files except the ones that come entirely +from the package they belong to. + +Pre-installation and post-installation commands may alter other files; +in particular, they can edit global configuration files or data bases. + +Pre-installation commands are typically executed before the normal +commands, and post-installation commands are typically run after the +normal commands. + +The most common use for a post-installation command is to run +@code{install-info}. This cannot be done with a normal command, since +it alters a file (the Info directory) which does not come entirely and +solely from the package being installed. It is a post-installation +command because it needs to be done after the normal command which +installs the package's Info files. + +Most programs don't need any pre-installation commands, but we have the +feature just in case it is needed. + +To classify the commands in the @code{install} rule into these three +categories, insert @dfn{category lines} among them. A category line +specifies the category for the commands that follow. + +A category line consists of a tab and a reference to a special Make +variable, plus an optional comment at the end. There are three +variables you can use, one for each category; the variable name +specifies the category. Category lines are no-ops in ordinary execution +because these three Make variables are normally undefined (and you +@emph{should not} define them in the makefile). + +Here are the three possible category lines, each with a comment that +explains what it means: + +@smallexample + $(PRE_INSTALL) # @r{Pre-install commands follow.} + $(POST_INSTALL) # @r{Post-install commands follow.} + $(NORMAL_INSTALL) # @r{Normal commands follow.} +@end smallexample + +If you don't use a category line at the beginning of the @code{install} +rule, all the commands are classified as normal until the first category +line. If you don't use any category lines, all the commands are +classified as normal. + +These are the category lines for @code{uninstall}: + +@smallexample + $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.} + $(POST_UNINSTALL) # @r{Post-uninstall commands follow.} + $(NORMAL_UNINSTALL) # @r{Normal commands follow.} +@end smallexample + +Typically, a pre-uninstall command would be used for deleting entries +from the Info directory. + +If the @code{install} or @code{uninstall} target has any dependencies +which act as subroutines of installation, then you should start +@emph{each} dependency's commands with a category line, and start the +main target's commands with a category line also. This way, you can +ensure that each command is placed in the right category regardless of +which of the dependencies actually run. + +Pre-installation and post-installation commands should not run any +programs except for these: + +@example +[ basename bash cat chgrp chmod chown cmp cp dd diff echo +egrep expand expr false fgrep find getopt grep gunzip gzip +hostname install install-info kill ldconfig ln ls md5sum +mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee +test touch true uname xargs yes +@end example + +@cindex binary packages +The reason for distinguishing the commands in this way is for the sake +of making binary packages. Typically a binary package contains all the +executables and other files that need to be installed, and has its own +method of installing them---so it does not need to run the normal +installation commands. But installing the binary package does need to +execute the pre-installation and post-installation commands. + +Programs to build binary packages work by extracting the +pre-installation and post-installation commands. Here is one way of +extracting the pre-installation commands: + +@smallexample +make -n install -o all \ + PRE_INSTALL=pre-install \ + POST_INSTALL=post-install \ + NORMAL_INSTALL=normal-install \ + | gawk -f pre-install.awk +@end smallexample + +@noindent +where the file @file{pre-install.awk} could contain this: + +@smallexample +$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@} +on @{print $0@} +$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@} +@end smallexample + +The resulting file of pre-installation commands is executed as a shell +script as part of installing the binary package. diff --git a/doc/rename.sh b/doc/rename.sh new file mode 100755 index 0000000..99b248c --- /dev/null +++ b/doc/rename.sh @@ -0,0 +1,21 @@ +#!/bin/sh +# The ac252 package renames the entries in an info directory section to avoid +# install-time conflict with the regular autoconf package. Newer versions of +# install-info have a "--name" option which appears simpler, but does not solve +# this particular problem -T.E.Dickey +SRC=`echo "$1" | sed -e 's,^./,,'` +DST=`echo "$2" | sed -e 's,^./,,'` +SRC_NAME=`basename $SRC .info` +DST_NAME=`basename $DST .info` +if test "$SRC_NAME" != "$DST_NAME" +then + PREFIX=`echo "$DST_NAME" | sed -e "s/$SRC_NAME.*$//"` + SUFFIX=`echo "$DST_NAME" | sed -e "s/^.*$SRC_NAME//"` + + sed -e "s/^\*[ ]*\([^ ][^ ]*\):[ ]*($SRC_NAME)\(.\)/* $PREFIX\1$SUFFIX: ($DST_NAME)\2/" <$SRC | \ + sed -e "s/^This is $SRC_NAME\.info,/This is $DST_NAME.info,/" | + sed -e "s/^File:[ ]*$SRC_NAME\.info/File: $DST_NAME.info/" >$DST +elif test "$SRC" != "$DST" +then + cat $SRC >$DST +fi diff --git a/doc/stamp-vti b/doc/stamp-vti new file mode 100644 index 0000000..d854139 --- /dev/null +++ b/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 2 December 2023 +@set UPDATED-MONTH December 2023 +@set EDITION 2.52.20231210 +@set VERSION 2.52.20231210 diff --git a/doc/standards.info b/doc/standards.info new file mode 100644 index 0000000..9e69fdc --- /dev/null +++ b/doc/standards.info @@ -0,0 +1,4454 @@ +This is standards.info, produced by makeinfo version 6.3 from +standards.texi. + +START-INFO-DIR-ENTRY +* Standards: (standards). GNU coding standards. +END-INFO-DIR-ENTRY + + GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + + +File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir) + +Version +******* + +Last updated March 23, 2001. + +* Menu: + +* Preface:: About the GNU Coding Standards +* Legal Issues:: Keeping Free Software Free +* Design Advice:: General Program Design +* Program Behavior:: Program Behavior for All Programs +* Writing C:: Making The Best Use of C +* Documentation:: Documenting Programs +* Managing Releases:: The Release Process +* References:: References to Non-Free Software or Documentation +* Index:: + + +File: standards.info, Node: Preface, Next: Legal Issues, Up: Top + +1 About the GNU Coding Standards +******************************** + +The GNU Coding Standards were written by Richard Stallman and other GNU +Project volunteers. Their purpose is to make the GNU system clean, +consistent, and easy to install. This document can also be read as a +guide to writing portable, robust and reliable programs. It focuses on +programs written in C, but many of the rules and principles are useful +even if you write in another programming language. The rules often +state reasons for writing in a certain way. + + This release of the GNU Coding Standards was last updated March 23, +2001. + + If you did not obtain this file directly from the GNU project and +recently, please check for a newer version. You can ftp the GNU Coding +Standards from any GNU FTP host in the directory '/pub/gnu/standards/'. +The GNU Coding Standards are available there in several different +formats: 'standards.text', 'standards.info', and 'standards.dvi', as +well as the Texinfo "source" which is divided in two files: +'standards.texi' and 'make-stds.texi'. The GNU Coding Standards are +also available on the GNU World Wide Web server: +<http://www.gnu.org/prep/standards_toc.html>. + + Corrections or suggestions for this document should be sent to +<bug-standards@gnu.org>. If you make a suggestion, please include a +suggested new wording for it; our time is limited. We prefer a context +diff to the 'standards.texi' or 'make-stds.texi' files, but if you don't +have those files, please mail your suggestion anyway. + + +File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top + +2 Keeping Free Software Free +**************************** + +This node discusses how you can make sure that GNU software avoids legal +difficulties, and other related issues. + +* Menu: + +* Reading Non-Free Code:: Referring to Proprietary Programs +* Contributions:: Accepting Contributions +* Trademarks:: How We Deal with Trademark Issues + + +File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues + +2.1 Referring to Proprietary Programs +===================================== + +Don't in any circumstances refer to Unix source code for or during your +work on GNU! (Or to any other proprietary programs.) + + If you have a vague recollection of the internals of a Unix program, +this does not absolutely mean you can't write an imitation of it, but do +try to organize the imitation internally along different lines, because +this is likely to make the details of the Unix version irrelevant and +dissimilar to your results. + + For example, Unix utilities were generally optimized to minimize +memory use; if you go for speed instead, your program will be very +different. You could keep the entire input file in core and scan it +there instead of using stdio. Use a smarter algorithm discovered more +recently than the Unix program. Eliminate use of temporary files. Do +it in one pass instead of two (we did this in the assembler). + + Or, on the contrary, emphasize simplicity instead of speed. For some +applications, the speed of today's computers makes simpler algorithms +adequate. + + Or go for generality. For example, Unix programs often have static +tables or fixed-size strings, which make for arbitrary limits; use +dynamic allocation instead. Make sure your program handles NULs and +other funny characters in the input files. Add a programming language +for extensibility and write part of the program in that language. + + Or turn some parts of the program into independently usable +libraries. Or use a simple garbage collector instead of tracking +precisely when to free memory, or use a new GNU facility such as +obstacks. + + +File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues + +2.2 Accepting Contributions +=========================== + +If the program you are working on is copyrighted by the Free Software +Foundation, then when someone else sends you a piece of code to add to +the program, we need legal papers to use it--just as we asked you to +sign papers initially. _Each_ person who makes a nontrivial +contribution to a program must sign some sort of legal papers in order +for us to have clear title to the program; the main author alone is not +enough. + + So, before adding in any contributions from other people, please tell +us, so we can arrange to get the papers. Then wait until we tell you +that we have received the signed papers, before you actually use the +contribution. + + This applies both before you release the program and afterward. If +you receive diffs to fix a bug, and they make significant changes, we +need legal papers for that change. + + This also applies to comments and documentation files. For copyright +law, comments and code are just text. Copyright applies to all kinds of +text, so we need legal papers for all kinds. + + We know it is frustrating to ask for legal papers; it's frustrating +for us as well. But if you don't wait, you are going out on a limb--for +example, what if the contributor's employer won't sign a disclaimer? +You might have to take that code out again! + + You don't need papers for changes of a few lines here or there, since +they are not significant for copyright purposes. Also, you don't need +papers if all you get from the suggestion is some ideas, not actual code +which you use. For example, if someone send you one implementation, but +you write a different implementation of the same idea, you don't need to +get papers. + + The very worst thing is if you forget to tell us about the other +contributor. We could be very embarrassed in court some day as a +result. + + We have more detailed advice for maintainers of programs; if you have +reached the stage of actually maintaining a program for GNU (whether +released or not), please ask us for a copy. + + +File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues + +2.3 Trademarks +============== + +Please do not include any trademark acknowledgements in GNU software +packages or documentation. + + Trademark acknowledgements are the statements that such-and-such is a +trademark of so-and-so. The GNU Project has no objection to the basic +idea of trademarks, but these acknowledgements feel like kowtowing, so +we don't use them. There is no legal requirement for them. + + What is legally required, as regards other people's trademarks, is to +avoid using them in ways which a reader might read as naming or labeling +our own programs or activities. For example, since "Objective C" is (or +at least was) a trademark, we made sure to say that we provide a +"compiler for the Objective C language" rather than an "Objective C +compiler". The latter is meant to be short for the former, but it does +not explicitly state the relationship, so it could be misinterpreted as +using "Objective C" as a label for the compiler rather than for the +language. + + +File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top + +3 General Program Design +************************ + +This node discusses some of the issues you should take into account when +designing your program. + +* Menu: + +* Source Language:: Which languages to use. +* Compatibility:: Compatibility with other implementations +* Using Extensions:: Using non-standard features +* Standard C:: Using Standard C features + + +File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice + +3.1 Which Languages to Use +========================== + +When you want to use a language that gets compiled and runs at high +speed, the best language to use is C. Using another language is like +using a non-standard feature: it will cause trouble for users. Even if +GCC supports the other language, users may find it inconvenient to have +to install the compiler for that other language in order to build your +program. For example, if you write your program in C++, people will +have to install the GNU C++ compiler in order to compile your program. + + C has one other advantage over C++ and other compiled languages: more +people know C, so more people will find it easy to read and modify the +program if it is written in C. + + So in general it is much better to use C, rather than the comparable +alternatives. + + But there are two exceptions to that conclusion: + + * It is no problem to use another language to write a tool + specifically intended for use with that language. That is because + the only people who want to build the tool will be those who have + installed the other language anyway. + + * If an application is of interest only to a narrow part of the + community, then the question of which language it is written in has + less effect on other people, so you may as well please yourself. + + Many programs are designed to be extensible: they include an +interpreter for a language that is higher level than C. Often much of +the program is written in that language, too. The Emacs editor +pioneered this technique. + + The standard extensibility interpreter for GNU software is GUILE, +which implements the language Scheme (an especially clean and simple +dialect of Lisp). <http://www.gnu.org/software/guile/>. We don't +reject programs written in other "scripting languages" such as Perl and +Python, but using GUILE is very important for the overall consistency of +the GNU system. + + +File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice + +3.2 Compatibility with Other Implementations +============================================ + +With occasional exceptions, utility programs and libraries for GNU +should be upward compatible with those in Berkeley Unix, and upward +compatible with Standard C if Standard C specifies their behavior, and +upward compatible with POSIX if POSIX specifies their behavior. + + When these standards conflict, it is useful to offer compatibility +modes for each of them. + + Standard C and POSIX prohibit many kinds of extensions. Feel free to +make the extensions anyway, and include a '--ansi', '--posix', or +'--compatible' option to turn them off. However, if the extension has a +significant chance of breaking any real programs or scripts, then it is +not really upward compatible. So you should try to redesign its +interface to make it upward compatible. + + Many GNU programs suppress extensions that conflict with POSIX if the +environment variable 'POSIXLY_CORRECT' is defined (even if it is defined +with a null value). Please make your program recognize this variable if +appropriate. + + When a feature is used only by users (not by programs or command +files), and it is done poorly in Unix, feel free to replace it +completely with something totally different and better. (For example, +'vi' is replaced with Emacs.) But it is nice to offer a compatible +feature as well. (There is a free 'vi' clone, so we offer it.) + + Additional useful features are welcome regardless of whether there is +any precedent for them. + + +File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice + +3.3 Using Non-standard Features +=============================== + +Many GNU facilities that already exist support a number of convenient +extensions over the comparable Unix facilities. Whether to use these +extensions in implementing your program is a difficult question. + + On the one hand, using the extensions can make a cleaner program. On +the other hand, people will not be able to build the program unless the +other GNU tools are available. This might cause the program to work on +fewer kinds of machines. + + With some extensions, it might be easy to provide both alternatives. +For example, you can define functions with a "keyword" 'INLINE' and +define that as a macro to expand into either 'inline' or nothing, +depending on the compiler. + + In general, perhaps it is best not to use the extensions if you can +straightforwardly do without them, but to use the extensions if they are +a big improvement. + + An exception to this rule are the large, established programs (such +as Emacs) which run on a great variety of systems. Using GNU extensions +in such programs would make many users unhappy, so we don't do that. + + Another exception is for programs that are used as part of +compilation: anything that must be compiled with other compilers in +order to bootstrap the GNU compilation facilities. If these require the +GNU compiler, then no one can compile them without having them installed +already. That would be extremely troublesome in certain cases. + + +File: standards.info, Node: Standard C, Prev: Using Extensions, Up: Design Advice + +3.4 Standard C and Pre-Standard C +================================= + +1989 Standard C is widespread enough now that it is ok to use its +features in new programs. There is one exception: do not ever use the +"trigraph" feature of Standard C. + + 1999 Standard C is not widespread yet, so please do not require its +features in programs. It is ok to use its features if they are present. + + However, it is easy to support pre-standard compilers in most +programs, so if you know how to do that, feel free. If a program you +are maintaining has such support, you should try to keep it working. + + To support pre-standard C, instead of writing function definitions in +standard prototype form, + + int + foo (int x, int y) + ... + +write the definition in pre-standard style like this, + + int + foo (x, y) + int x, y; + ... + +and use a separate declaration to specify the argument prototype: + + int foo (int, int); + + You need such a declaration anyway, in a header file, to get the +benefit of prototypes in all the files where the function is called. +And once you have the declaration, you normally lose nothing by writing +the function definition in the pre-standard style. + + This technique does not work for integer types narrower than 'int'. +If you think of an argument as being of a type narrower than 'int', +declare it as 'int' instead. + + There are a few special cases where this technique is hard to use. +For example, if a function argument needs to hold the system type +'dev_t', you run into trouble, because 'dev_t' is shorter than 'int' on +some machines; but you cannot use 'int' instead, because 'dev_t' is +wider than 'int' on some machines. There is no type you can safely use +on all machines in a non-standard definition. The only way to support +non-standard C and pass such an argument is to check the width of +'dev_t' using Autoconf and choose the argument type accordingly. This +may not be worth the trouble. + + In order to support pre-standard compilers that do not recognize +prototypes, you may want to use a preprocessor macro like this: + + /* Declare the prototype for a general external function. */ + #if defined (__STDC__) || defined (WINDOWSNT) + #define P_(proto) proto + #else + #define P_(proto) () + #endif + + +File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top + +4 Program Behavior for All Programs +*********************************** + +This node describes conventions for writing robust software. It also +describes general standards for error messages, the command line +interface, and how libraries should behave. + +* Menu: + +* Semantics:: Writing robust programs +* Libraries:: Library behavior +* Errors:: Formatting error messages +* User Interfaces:: Standards about interfaces generally +* Graphical Interfaces:: Standards for graphical interfaces +* Command-Line Interfaces:: Standards for command line interfaces +* Option Table:: Table of long options +* Memory Usage:: When and how to care about memory needs +* File Usage:: Which files to use, and where + + +File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior + +4.1 Writing Robust Programs +=========================== + +Avoid arbitrary limits on the length or number of _any_ data structure, +including file names, lines, files, and symbols, by allocating all data +structures dynamically. In most Unix utilities, "long lines are +silently truncated". This is not acceptable in a GNU utility. + + Utilities reading files should not drop NUL characters, or any other +nonprinting characters _including those with codes above 0177_. The +only sensible exceptions would be utilities specifically intended for +interface to certain types of terminals or printers that can't handle +those characters. Whenever possible, try to make programs work properly +with sequences of bytes that represent multibyte characters, using +encodings such as UTF-8 and others. + + Check every system call for an error return, unless you know you wish +to ignore errors. Include the system error text (from 'perror' or +equivalent) in _every_ error message resulting from a failing system +call, as well as the name of the file if any and the name of the +utility. Just "cannot open foo.c" or "stat failed" is not sufficient. + + Check every call to 'malloc' or 'realloc' to see if it returned zero. +Check 'realloc' even if you are making the block smaller; in a system +that rounds block sizes to a power of 2, 'realloc' may get a different +block if you ask for less space. + + In Unix, 'realloc' can destroy the storage block if it returns zero. +GNU 'realloc' does not have this bug: if it fails, the original block is +unchanged. Feel free to assume the bug is fixed. If you wish to run +your program on Unix, and wish to avoid lossage in this case, you can +use the GNU 'malloc'. + + You must expect 'free' to alter the contents of the block that was +freed. Anything you want to fetch from the block, you must fetch before +calling 'free'. + + If 'malloc' fails in a noninteractive program, make that a fatal +error. In an interactive program (one that reads commands from the +user), it is better to abort the command and return to the command +reader loop. This allows the user to kill other processes to free up +virtual memory, and then try the command again. + + Use 'getopt_long' to decode arguments, unless the argument syntax +makes this unreasonable. + + When static storage is to be written in during program execution, use +explicit C code to initialize it. Reserve C initialized declarations +for data that will not be changed. + + Try to avoid low-level interfaces to obscure Unix data structures +(such as file directories, utmp, or the layout of kernel memory), since +these are less likely to work compatibly. If you need to find all the +files in a directory, use 'readdir' or some other high-level interface. +These are supported compatibly by GNU. + + The preferred signal handling facilities are the BSD variant of +'signal', and the POSIX 'sigaction' function; the alternative USG +'signal' interface is an inferior design. + + Nowadays, using the POSIX signal functions may be the easiest way to +make a program portable. If you use 'signal', then on GNU/Linux systems +running GNU libc version 1, you should include 'bsd/signal.h' instead of +'signal.h', so as to get BSD behavior. It is up to you whether to +support systems where 'signal' has only the USG behavior, or give up on +them. + + In error checks that detect "impossible" conditions, just abort. +There is usually no point in printing any message. These checks +indicate the existence of bugs. Whoever wants to fix the bugs will have +to read the source code and run a debugger. So explain the problem with +comments in the source. The relevant data will be in variables, which +are easy to examine with the debugger, so there is no point moving them +elsewhere. + + Do not use a count of errors as the exit status for a program. _That +does not work_, because exit status values are limited to 8 bits (0 +through 255). A single run of the program might have 256 errors; if you +try to return 256 as the exit status, the parent process will see 0 as +the status, and it will appear that the program succeeded. + + If you make temporary files, check the 'TMPDIR' environment variable; +if that variable is defined, use the specified directory instead of +'/tmp'. + + In addition, be aware that there is a possible security problem when +creating temporary files in world-writable directories. In C, you can +avoid this problem by creating temporary files in this manner: + + fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600); + +or by using the 'mkstemps' function from libiberty. + + In bash, use 'set -C' to avoid this problem. + + +File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior + +4.2 Library Behavior +==================== + +Try to make library functions reentrant. If they need to do dynamic +storage allocation, at least try to avoid any nonreentrancy aside from +that of 'malloc' itself. + + Here are certain name conventions for libraries, to avoid name +conflicts. + + Choose a name prefix for the library, more than two characters long. +All external function and variable names should start with this prefix. +In addition, there should only be one of these in any given library +member. This usually means putting each one in a separate source file. + + An exception can be made when two external symbols are always used +together, so that no reasonable program could use one without the other; +then they can both go in the same file. + + External symbols that are not documented entry points for the user +should have names beginning with '_'. The '_' should be followed by the +chosen name prefix for the library, to prevent collisions with other +libraries. These can go in the same files with user entry points if you +like. + + Static functions and variables can be used as you like and need not +fit any naming convention. + + +File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior + +4.3 Formatting Error Messages +============================= + +Error messages from compilers should look like this: + + SOURCE-FILE-NAME:LINENO: MESSAGE + +If you want to mention the column number, use this format: + + SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE + +Line numbers should start from 1 at the beginning of the file, and +column numbers should start from 1 at the beginning of the line. (Both +of these conventions are chosen for compatibility.) Calculate column +numbers assuming that space and all ASCII printing characters have equal +width, and assuming tab stops every 8 columns. + + Error messages from other noninteractive programs should look like +this: + + PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE + +when there is an appropriate source file, or like this: + + PROGRAM: MESSAGE + +when there is no relevant source file. + + If you want to mention the column number, use this format: + + PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE + + In an interactive program (one that is reading commands from a +terminal), it is better not to include the program name in an error +message. The place to indicate which program is running is in the +prompt or with the screen layout. (When the same program runs with +input from a source other than a terminal, it is not interactive and +would do best to print error messages using the noninteractive style.) + + The string MESSAGE should not begin with a capital letter when it +follows a program name and/or file name. Also, it should not end with a +period. + + Error messages from interactive programs, and other messages such as +usage messages, should start with a capital letter. But they should not +end with a period. + + +File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior + +4.4 Standards for Interfaces Generally +====================================== + +Please don't make the behavior of a utility depend on the name used to +invoke it. It is useful sometimes to make a link to a utility with a +different name, and that should not change what it does. + + Instead, use a run time option or a compilation switch or both to +select among the alternate behaviors. + + Likewise, please don't make the behavior of the program depend on the +type of output device it is used with. Device independence is an +important principle of the system's design; do not compromise it merely +to save someone from typing an option now and then. (Variation in error +message syntax when using a terminal is ok, because that is a side issue +that people do not depend on.) + + If you think one behavior is most useful when the output is to a +terminal, and another is most useful when the output is a file or a +pipe, then it is usually best to make the default behavior the one that +is useful with output to a terminal, and have an option for the other +behavior. + + Compatibility requires certain programs to depend on the type of +output device. It would be disastrous if 'ls' or 'sh' did not do so in +the way all users expect. In some of these cases, we supplement the +program with a preferred alternate version that does not depend on the +output device type. For example, we provide a 'dir' program much like +'ls' except that its default output format is always multi-column +format. + + +File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior + +4.5 Standards for Graphical Interfaces +====================================== + +When you write a program that provides a graphical user interface, +please make it work with X Windows and the GTK toolkit unless the +functionality specifically requires some alternative (for example, +"displaying jpeg images while in console mode"). + + In addition, please provide a command-line interface to control the +functionality. (In many cases, the graphical user interface can be a +separate program which invokes the command-line program.) This is so +that the same jobs can be done from scripts. + + Please also consider providing a CORBA interface (for use from +GNOME), a library interface (for use from C), and perhaps a +keyboard-driven console interface (for use by users from console mode). +Once you are doing the work to provide the functionality and the +graphical interface, these won't be much extra work. + + +File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior + +4.6 Standards for Command Line Interfaces +========================================= + +It is a good idea to follow the POSIX guidelines for the command-line +options of a program. The easiest way to do this is to use 'getopt' to +parse them. Note that the GNU version of 'getopt' will normally permit +options anywhere among the arguments unless the special argument '--' is +used. This is not what POSIX specifies; it is a GNU extension. + + Please define long-named options that are equivalent to the +single-letter Unix-style options. We hope to make GNU more user +friendly this way. This is easy to do with the GNU function +'getopt_long'. + + One of the advantages of long-named options is that they can be +consistent from program to program. For example, users should be able +to expect the "verbose" option of any GNU program which has one, to be +spelled precisely '--verbose'. To achieve this uniformity, look at the +table of common long-option names when you choose the option names for +your program (*note Option Table::). + + It is usually a good idea for file names given as ordinary arguments +to be input files only; any output files would be specified using +options (preferably '-o' or '--output'). Even if you allow an output +file name as an ordinary argument for compatibility, try to provide an +option as another way to specify it. This will lead to more consistency +among GNU utilities, and fewer idiosyncrasies for users to remember. + + All programs should support two standard options: '--version' and +'--help'. + +'--version' + This option should direct the program to print information about + its name, version, origin and legal status, all on standard output, + and then exit successfully. Other options and arguments should be + ignored once this is seen, and the program should not perform its + normal function. + + The first line is meant to be easy for a program to parse; the + version number proper starts after the last space. In addition, it + contains the canonical name for this program, in this format: + + GNU Emacs 19.30 + + The program's name should be a constant string; _don't_ compute it + from 'argv[0]'. The idea is to state the standard or canonical + name for the program, not its file name. There are other ways to + find out the precise file name where a command is found in 'PATH'. + + If the program is a subsidiary part of a larger package, mention + the package name in parentheses, like this: + + emacsserver (GNU Emacs) 19.30 + + If the package has a version number which is different from this + program's version number, you can mention the package version + number just before the close-parenthesis. + + If you *need* to mention the version numbers of libraries which are + distributed separately from the package which contains this + program, you can do so by printing an additional line of version + info for each library you want to mention. Use the same format for + these lines as for the first line. + + Please do not mention all of the libraries that the program uses + "just for completeness"--that would produce a lot of unhelpful + clutter. Please mention library version numbers only if you find + in practice that they are very important to you in debugging. + + The following line, after the version number line or lines, should + be a copyright notice. If more than one copyright notice is called + for, put each on a separate line. + + Next should follow a brief statement that the program is free + software, and that users are free to copy and change it on certain + conditions. If the program is covered by the GNU GPL, say so here. + Also mention that there is no warranty, to the extent permitted by + law. + + It is ok to finish the output with a list of the major authors of + the program, as a way of giving credit. + + Here's an example of output that follows these rules: + + GNU Emacs 19.34.5 + Copyright (C) 1996 Free Software Foundation, Inc. + GNU Emacs comes with NO WARRANTY, + to the extent permitted by law. + You may redistribute copies of GNU Emacs + under the terms of the GNU General Public License. + For more information about these matters, + see the files named COPYING. + + You should adapt this to your program, of course, filling in the + proper year, copyright holder, name of program, and the references + to distribution terms, and changing the rest of the wording as + necessary. + + This copyright notice only needs to mention the most recent year in + which changes were made--there's no need to list the years for + previous versions' changes. You don't have to mention the name of + the program in these notices, if that is inconvenient, since it + appeared in the first line. + +'--help' + This option should output brief documentation for how to invoke the + program, on standard output, then exit successfully. Other options + and arguments should be ignored once this is seen, and the program + should not perform its normal function. + + Near the end of the '--help' option's output there should be a line + that says where to mail bug reports. It should have this format: + + Report bugs to MAILING-ADDRESS. + + +File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior + +4.7 Table of Long Options +========================= + +Here is a table of long options used by GNU programs. It is surely +incomplete, but we aim to list all the options that a new program might +want to be compatible with. If you use names not already in the table, +please send <bug-standards@gnu.org> a list of them, with their meanings, +so we can update the table. + +'after-date' + '-N' in 'tar'. + +'all' + '-a' in 'du', 'ls', 'nm', 'stty', 'uname', and 'unexpand'. + +'all-text' + '-a' in 'diff'. + +'almost-all' + '-A' in 'ls'. + +'append' + '-a' in 'etags', 'tee', 'time'; '-r' in 'tar'. + +'archive' + '-a' in 'cp'. + +'archive-name' + '-n' in 'shar'. + +'arglength' + '-l' in 'm4'. + +'ascii' + '-a' in 'diff'. + +'assign' + '-v' in 'gawk'. + +'assume-new' + '-W' in Make. + +'assume-old' + '-o' in Make. + +'auto-check' + '-a' in 'recode'. + +'auto-pager' + '-a' in 'wdiff'. + +'auto-reference' + '-A' in 'ptx'. + +'avoid-wraps' + '-n' in 'wdiff'. + +'background' + For server programs, run in the background. + +'backward-search' + '-B' in 'ctags'. + +'basename' + '-f' in 'shar'. + +'batch' + Used in GDB. + +'baud' + Used in GDB. + +'before' + '-b' in 'tac'. + +'binary' + '-b' in 'cpio' and 'diff'. + +'bits-per-code' + '-b' in 'shar'. + +'block-size' + Used in 'cpio' and 'tar'. + +'blocks' + '-b' in 'head' and 'tail'. + +'break-file' + '-b' in 'ptx'. + +'brief' + Used in various programs to make output shorter. + +'bytes' + '-c' in 'head', 'split', and 'tail'. + +'c++' + '-C' in 'etags'. + +'catenate' + '-A' in 'tar'. + +'cd' + Used in various programs to specify the directory to use. + +'changes' + '-c' in 'chgrp' and 'chown'. + +'classify' + '-F' in 'ls'. + +'colons' + '-c' in 'recode'. + +'command' + '-c' in 'su'; '-x' in GDB. + +'compare' + '-d' in 'tar'. + +'compat' + Used in 'gawk'. + +'compress' + '-Z' in 'tar' and 'shar'. + +'concatenate' + '-A' in 'tar'. + +'confirmation' + '-w' in 'tar'. + +'context' + Used in 'diff'. + +'copyleft' + '-W copyleft' in 'gawk'. + +'copyright' + '-C' in 'ptx', 'recode', and 'wdiff'; '-W copyright' in 'gawk'. + +'core' + Used in GDB. + +'count' + '-q' in 'who'. + +'count-links' + '-l' in 'du'. + +'create' + Used in 'tar' and 'cpio'. + +'cut-mark' + '-c' in 'shar'. + +'cxref' + '-x' in 'ctags'. + +'date' + '-d' in 'touch'. + +'debug' + '-d' in Make and 'm4'; '-t' in Bison. + +'define' + '-D' in 'm4'. + +'defines' + '-d' in Bison and 'ctags'. + +'delete' + '-D' in 'tar'. + +'dereference' + '-L' in 'chgrp', 'chown', 'cpio', 'du', 'ls', and 'tar'. + +'dereference-args' + '-D' in 'du'. + +'device' + Specify an I/O device (special file name). + +'diacritics' + '-d' in 'recode'. + +'dictionary-order' + '-d' in 'look'. + +'diff' + '-d' in 'tar'. + +'digits' + '-n' in 'csplit'. + +'directory' + Specify the directory to use, in various programs. In 'ls', it + means to show directories themselves rather than their contents. + In 'rm' and 'ln', it means to not treat links to directories + specially. + +'discard-all' + '-x' in 'strip'. + +'discard-locals' + '-X' in 'strip'. + +'dry-run' + '-n' in Make. + +'ed' + '-e' in 'diff'. + +'elide-empty-files' + '-z' in 'csplit'. + +'end-delete' + '-x' in 'wdiff'. + +'end-insert' + '-z' in 'wdiff'. + +'entire-new-file' + '-N' in 'diff'. + +'environment-overrides' + '-e' in Make. + +'eof' + '-e' in 'xargs'. + +'epoch' + Used in GDB. + +'error-limit' + Used in 'makeinfo'. + +'error-output' + '-o' in 'm4'. + +'escape' + '-b' in 'ls'. + +'exclude-from' + '-X' in 'tar'. + +'exec' + Used in GDB. + +'exit' + '-x' in 'xargs'. + +'exit-0' + '-e' in 'unshar'. + +'expand-tabs' + '-t' in 'diff'. + +'expression' + '-e' in 'sed'. + +'extern-only' + '-g' in 'nm'. + +'extract' + '-i' in 'cpio'; '-x' in 'tar'. + +'faces' + '-f' in 'finger'. + +'fast' + '-f' in 'su'. + +'fatal-warnings' + '-E' in 'm4'. + +'file' + '-f' in 'info', 'gawk', Make, 'mt', and 'tar'; '-n' in 'sed'; '-r' + in 'touch'. + +'field-separator' + '-F' in 'gawk'. + +'file-prefix' + '-b' in Bison. + +'file-type' + '-F' in 'ls'. + +'files-from' + '-T' in 'tar'. + +'fill-column' + Used in 'makeinfo'. + +'flag-truncation' + '-F' in 'ptx'. + +'fixed-output-files' + '-y' in Bison. + +'follow' + '-f' in 'tail'. + +'footnote-style' + Used in 'makeinfo'. + +'force' + '-f' in 'cp', 'ln', 'mv', and 'rm'. + +'force-prefix' + '-F' in 'shar'. + +'foreground' + For server programs, run in the foreground; in other words, don't + do anything special to run the server in the background. + +'format' + Used in 'ls', 'time', and 'ptx'. + +'freeze-state' + '-F' in 'm4'. + +'fullname' + Used in GDB. + +'gap-size' + '-g' in 'ptx'. + +'get' + '-x' in 'tar'. + +'graphic' + '-i' in 'ul'. + +'graphics' + '-g' in 'recode'. + +'group' + '-g' in 'install'. + +'gzip' + '-z' in 'tar' and 'shar'. + +'hashsize' + '-H' in 'm4'. + +'header' + '-h' in 'objdump' and 'recode' + +'heading' + '-H' in 'who'. + +'help' + Used to ask for brief usage information. + +'here-delimiter' + '-d' in 'shar'. + +'hide-control-chars' + '-q' in 'ls'. + +'html' + In 'makeinfo', output HTML. + +'idle' + '-u' in 'who'. + +'ifdef' + '-D' in 'diff'. + +'ignore' + '-I' in 'ls'; '-x' in 'recode'. + +'ignore-all-space' + '-w' in 'diff'. + +'ignore-backups' + '-B' in 'ls'. + +'ignore-blank-lines' + '-B' in 'diff'. + +'ignore-case' + '-f' in 'look' and 'ptx'; '-i' in 'diff' and 'wdiff'. + +'ignore-errors' + '-i' in Make. + +'ignore-file' + '-i' in 'ptx'. + +'ignore-indentation' + '-I' in 'etags'. + +'ignore-init-file' + '-f' in Oleo. + +'ignore-interrupts' + '-i' in 'tee'. + +'ignore-matching-lines' + '-I' in 'diff'. + +'ignore-space-change' + '-b' in 'diff'. + +'ignore-zeros' + '-i' in 'tar'. + +'include' + '-i' in 'etags'; '-I' in 'm4'. + +'include-dir' + '-I' in Make. + +'incremental' + '-G' in 'tar'. + +'info' + '-i', '-l', and '-m' in Finger. + +'init-file' + In some programs, specify the name of the file to read as the + user's init file. + +'initial' + '-i' in 'expand'. + +'initial-tab' + '-T' in 'diff'. + +'inode' + '-i' in 'ls'. + +'interactive' + '-i' in 'cp', 'ln', 'mv', 'rm'; '-e' in 'm4'; '-p' in 'xargs'; '-w' + in 'tar'. + +'intermix-type' + '-p' in 'shar'. + +'iso-8601' + Used in 'date' + +'jobs' + '-j' in Make. + +'just-print' + '-n' in Make. + +'keep-going' + '-k' in Make. + +'keep-files' + '-k' in 'csplit'. + +'kilobytes' + '-k' in 'du' and 'ls'. + +'language' + '-l' in 'etags'. + +'less-mode' + '-l' in 'wdiff'. + +'level-for-gzip' + '-g' in 'shar'. + +'line-bytes' + '-C' in 'split'. + +'lines' + Used in 'split', 'head', and 'tail'. + +'link' + '-l' in 'cpio'. + +'lint' +'lint-old' + Used in 'gawk'. + +'list' + '-t' in 'cpio'; '-l' in 'recode'. + +'list' + '-t' in 'tar'. + +'literal' + '-N' in 'ls'. + +'load-average' + '-l' in Make. + +'login' + Used in 'su'. + +'machine' + No listing of which programs already use this; someone should check + to see if any actually do, and tell <gnu@gnu.org>. + +'macro-name' + '-M' in 'ptx'. + +'mail' + '-m' in 'hello' and 'uname'. + +'make-directories' + '-d' in 'cpio'. + +'makefile' + '-f' in Make. + +'mapped' + Used in GDB. + +'max-args' + '-n' in 'xargs'. + +'max-chars' + '-n' in 'xargs'. + +'max-lines' + '-l' in 'xargs'. + +'max-load' + '-l' in Make. + +'max-procs' + '-P' in 'xargs'. + +'mesg' + '-T' in 'who'. + +'message' + '-T' in 'who'. + +'minimal' + '-d' in 'diff'. + +'mixed-uuencode' + '-M' in 'shar'. + +'mode' + '-m' in 'install', 'mkdir', and 'mkfifo'. + +'modification-time' + '-m' in 'tar'. + +'multi-volume' + '-M' in 'tar'. + +'name-prefix' + '-a' in Bison. + +'nesting-limit' + '-L' in 'm4'. + +'net-headers' + '-a' in 'shar'. + +'new-file' + '-W' in Make. + +'no-builtin-rules' + '-r' in Make. + +'no-character-count' + '-w' in 'shar'. + +'no-check-existing' + '-x' in 'shar'. + +'no-common' + '-3' in 'wdiff'. + +'no-create' + '-c' in 'touch'. + +'no-defines' + '-D' in 'etags'. + +'no-deleted' + '-1' in 'wdiff'. + +'no-dereference' + '-d' in 'cp'. + +'no-inserted' + '-2' in 'wdiff'. + +'no-keep-going' + '-S' in Make. + +'no-lines' + '-l' in Bison. + +'no-piping' + '-P' in 'shar'. + +'no-prof' + '-e' in 'gprof'. + +'no-regex' + '-R' in 'etags'. + +'no-sort' + '-p' in 'nm'. + +'no-split' + Used in 'makeinfo'. + +'no-static' + '-a' in 'gprof'. + +'no-time' + '-E' in 'gprof'. + +'no-timestamp' + '-m' in 'shar'. + +'no-validate' + Used in 'makeinfo'. + +'no-wait' + Used in 'emacsclient'. + +'no-warn' + Used in various programs to inhibit warnings. + +'node' + '-n' in 'info'. + +'nodename' + '-n' in 'uname'. + +'nonmatching' + '-f' in 'cpio'. + +'nstuff' + '-n' in 'objdump'. + +'null' + '-0' in 'xargs'. + +'number' + '-n' in 'cat'. + +'number-nonblank' + '-b' in 'cat'. + +'numeric-sort' + '-n' in 'nm'. + +'numeric-uid-gid' + '-n' in 'cpio' and 'ls'. + +'nx' + Used in GDB. + +'old-archive' + '-o' in 'tar'. + +'old-file' + '-o' in Make. + +'one-file-system' + '-l' in 'tar', 'cp', and 'du'. + +'only-file' + '-o' in 'ptx'. + +'only-prof' + '-f' in 'gprof'. + +'only-time' + '-F' in 'gprof'. + +'options' + '-o' in 'getopt', 'fdlist', 'fdmount', 'fdmountd', and 'fdumount'. + +'output' + In various programs, specify the output file name. + +'output-prefix' + '-o' in 'shar'. + +'override' + '-o' in 'rm'. + +'overwrite' + '-c' in 'unshar'. + +'owner' + '-o' in 'install'. + +'paginate' + '-l' in 'diff'. + +'paragraph-indent' + Used in 'makeinfo'. + +'parents' + '-p' in 'mkdir' and 'rmdir'. + +'pass-all' + '-p' in 'ul'. + +'pass-through' + '-p' in 'cpio'. + +'port' + '-P' in 'finger'. + +'portability' + '-c' in 'cpio' and 'tar'. + +'posix' + Used in 'gawk'. + +'prefix-builtins' + '-P' in 'm4'. + +'prefix' + '-f' in 'csplit'. + +'preserve' + Used in 'tar' and 'cp'. + +'preserve-environment' + '-p' in 'su'. + +'preserve-modification-time' + '-m' in 'cpio'. + +'preserve-order' + '-s' in 'tar'. + +'preserve-permissions' + '-p' in 'tar'. + +'print' + '-l' in 'diff'. + +'print-chars' + '-L' in 'cmp'. + +'print-data-base' + '-p' in Make. + +'print-directory' + '-w' in Make. + +'print-file-name' + '-o' in 'nm'. + +'print-symdefs' + '-s' in 'nm'. + +'printer' + '-p' in 'wdiff'. + +'prompt' + '-p' in 'ed'. + +'proxy' + Specify an HTTP proxy. + +'query-user' + '-X' in 'shar'. + +'question' + '-q' in Make. + +'quiet' + Used in many programs to inhibit the usual output. *Note:* every + program accepting '--quiet' should accept '--silent' as a synonym. + +'quiet-unshar' + '-Q' in 'shar' + +'quote-name' + '-Q' in 'ls'. + +'rcs' + '-n' in 'diff'. + +'re-interval' + Used in 'gawk'. + +'read-full-blocks' + '-B' in 'tar'. + +'readnow' + Used in GDB. + +'recon' + '-n' in Make. + +'record-number' + '-R' in 'tar'. + +'recursive' + Used in 'chgrp', 'chown', 'cp', 'ls', 'diff', and 'rm'. + +'reference-limit' + Used in 'makeinfo'. + +'references' + '-r' in 'ptx'. + +'regex' + '-r' in 'tac' and 'etags'. + +'release' + '-r' in 'uname'. + +'reload-state' + '-R' in 'm4'. + +'relocation' + '-r' in 'objdump'. + +'rename' + '-r' in 'cpio'. + +'replace' + '-i' in 'xargs'. + +'report-identical-files' + '-s' in 'diff'. + +'reset-access-time' + '-a' in 'cpio'. + +'reverse' + '-r' in 'ls' and 'nm'. + +'reversed-ed' + '-f' in 'diff'. + +'right-side-defs' + '-R' in 'ptx'. + +'same-order' + '-s' in 'tar'. + +'same-permissions' + '-p' in 'tar'. + +'save' + '-g' in 'stty'. + +'se' + Used in GDB. + +'sentence-regexp' + '-S' in 'ptx'. + +'separate-dirs' + '-S' in 'du'. + +'separator' + '-s' in 'tac'. + +'sequence' + Used by 'recode' to chose files or pipes for sequencing passes. + +'shell' + '-s' in 'su'. + +'show-all' + '-A' in 'cat'. + +'show-c-function' + '-p' in 'diff'. + +'show-ends' + '-E' in 'cat'. + +'show-function-line' + '-F' in 'diff'. + +'show-tabs' + '-T' in 'cat'. + +'silent' + Used in many programs to inhibit the usual output. *Note:* every + program accepting '--silent' should accept '--quiet' as a synonym. + +'size' + '-s' in 'ls'. + +'socket' + Specify a file descriptor for a network server to use for its + socket, instead of opening and binding a new socket. This provides + a way to run, in a nonpriveledged process, a server that normally + needs a reserved port number. + +'sort' + Used in 'ls'. + +'source' + '-W source' in 'gawk'. + +'sparse' + '-S' in 'tar'. + +'speed-large-files' + '-H' in 'diff'. + +'split-at' + '-E' in 'unshar'. + +'split-size-limit' + '-L' in 'shar'. + +'squeeze-blank' + '-s' in 'cat'. + +'start-delete' + '-w' in 'wdiff'. + +'start-insert' + '-y' in 'wdiff'. + +'starting-file' + Used in 'tar' and 'diff' to specify which file within a directory + to start processing with. + +'statistics' + '-s' in 'wdiff'. + +'stdin-file-list' + '-S' in 'shar'. + +'stop' + '-S' in Make. + +'strict' + '-s' in 'recode'. + +'strip' + '-s' in 'install'. + +'strip-all' + '-s' in 'strip'. + +'strip-debug' + '-S' in 'strip'. + +'submitter' + '-s' in 'shar'. + +'suffix' + '-S' in 'cp', 'ln', 'mv'. + +'suffix-format' + '-b' in 'csplit'. + +'sum' + '-s' in 'gprof'. + +'summarize' + '-s' in 'du'. + +'symbolic' + '-s' in 'ln'. + +'symbols' + Used in GDB and 'objdump'. + +'synclines' + '-s' in 'm4'. + +'sysname' + '-s' in 'uname'. + +'tabs' + '-t' in 'expand' and 'unexpand'. + +'tabsize' + '-T' in 'ls'. + +'terminal' + '-T' in 'tput' and 'ul'. '-t' in 'wdiff'. + +'text' + '-a' in 'diff'. + +'text-files' + '-T' in 'shar'. + +'time' + Used in 'ls' and 'touch'. + +'timeout' + Specify how long to wait before giving up on some operation. + +'to-stdout' + '-O' in 'tar'. + +'total' + '-c' in 'du'. + +'touch' + '-t' in Make, 'ranlib', and 'recode'. + +'trace' + '-t' in 'm4'. + +'traditional' + '-t' in 'hello'; '-W traditional' in 'gawk'; '-G' in 'ed', 'm4', + and 'ptx'. + +'tty' + Used in GDB. + +'typedefs' + '-t' in 'ctags'. + +'typedefs-and-c++' + '-T' in 'ctags'. + +'typeset-mode' + '-t' in 'ptx'. + +'uncompress' + '-z' in 'tar'. + +'unconditional' + '-u' in 'cpio'. + +'undefine' + '-U' in 'm4'. + +'undefined-only' + '-u' in 'nm'. + +'update' + '-u' in 'cp', 'ctags', 'mv', 'tar'. + +'usage' + Used in 'gawk'; same as '--help'. + +'uuencode' + '-B' in 'shar'. + +'vanilla-operation' + '-V' in 'shar'. + +'verbose' + Print more information about progress. Many programs support this. + +'verify' + '-W' in 'tar'. + +'version' + Print the version number. + +'version-control' + '-V' in 'cp', 'ln', 'mv'. + +'vgrind' + '-v' in 'ctags'. + +'volume' + '-V' in 'tar'. + +'what-if' + '-W' in Make. + +'whole-size-limit' + '-l' in 'shar'. + +'width' + '-w' in 'ls' and 'ptx'. + +'word-regexp' + '-W' in 'ptx'. + +'writable' + '-T' in 'who'. + +'zeros' + '-z' in 'gprof'. + + +File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior + +4.8 Memory Usage +================ + +If a program typically uses just a few meg of memory, don't bother +making any effort to reduce memory usage. For example, if it is +impractical for other reasons to operate on files more than a few meg +long, it is reasonable to read entire input files into core to operate +on them. + + However, for programs such as 'cat' or 'tail', that can usefully +operate on very large files, it is important to avoid using a technique +that would artificially limit the size of files it can handle. If a +program works by lines and could be applied to arbitrary user-supplied +input files, it should keep only a line in memory, because this is not +very hard and users will want to be able to operate on input files that +are bigger than will fit in core all at once. + + If your program creates complicated data structures, just make them +in core and give a fatal error if 'malloc' returns zero. + + +File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior + +4.9 File Usage +============== + +Programs should be prepared to operate when '/usr' and '/etc' are +read-only file systems. Thus, if the program manages log files, lock +files, backup files, score files, or any other files which are modified +for internal purposes, these files should not be stored in '/usr' or +'/etc'. + + There are two exceptions. '/etc' is used to store system +configuration information; it is reasonable for a program to modify +files in '/etc' when its job is to update the system configuration. +Also, if the user explicitly asks to modify one file in a directory, it +is reasonable for the program to store other files in the same +directory. + + +File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top + +5 Making The Best Use of C +************************** + +This node provides advice on how best to use the C language when writing +GNU software. + +* Menu: + +* Formatting:: Formatting Your Source Code +* Comments:: Commenting Your Work +* Syntactic Conventions:: Clean Use of C Constructs +* Names:: Naming Variables and Functions +* System Portability:: Portability between different operating systems +* CPU Portability:: Supporting the range of CPU types +* System Functions:: Portability and "standard" library functions +* Internationalization:: Techniques for internationalization +* Mmap:: How you can safely use 'mmap'. + + +File: standards.info, Node: Formatting, Next: Comments, Up: Writing C + +5.1 Formatting Your Source Code +=============================== + +It is important to put the open-brace that starts the body of a C +function in column zero, and avoid putting any other open-brace or +open-parenthesis or open-bracket in column zero. Several tools look for +open-braces in column zero to find the beginnings of C functions. These +tools will not work on code not formatted that way. + + It is also important for function definitions to start the name of +the function in column zero. This helps people to search for function +definitions, and may also help certain tools recognize them. Thus, the +proper format is this: + + static char * + concat (s1, s2) /* Name starts in column zero here */ + char *s1, *s2; + { /* Open brace in column zero here */ + ... + } + +or, if you want to use Standard C syntax, format the definition like +this: + + static char * + concat (char *s1, char *s2) + { + ... + } + + In Standard C, if the arguments don't fit nicely on one line, split +it like this: + + int + lots_of_args (int an_integer, long a_long, short a_short, + double a_double, float a_float) + ... + + The rest of this section gives our recommendations for other aspects +of C formatting style, which is also the default style of the 'indent' +program in version 1.2 and newer. It corresponds to the options + + -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 + -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob + + We don't think of these recommendations as requirements, because it +causes no problems for users if two different programs have different +formatting styles. + + But whatever style you use, please use it consistently, since a +mixture of styles within one program tends to look ugly. If you are +contributing changes to an existing program, please follow the style of +that program. + + For the body of the function, our recommended style looks like this: + + if (x < foo (y, z)) + haha = bar[4] + 5; + else + { + while (z) + { + haha += foo (z, z); + z--; + } + return ++x + bar (); + } + + We find it easier to read a program when it has spaces before the +open-parentheses and after the commas. Especially after the commas. + + When you split an expression into multiple lines, split it before an +operator, not after one. Here is the right way: + + if (foo_this_is_long && bar > win (x, y, z) + && remaining_condition) + + Try to avoid having two operators of different precedence at the same +level of indentation. For example, don't write this: + + mode = (inmode[j] == VOIDmode + || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) + ? outmode[j] : inmode[j]); + + Instead, use extra parentheses so that the indentation shows the +nesting: + + mode = ((inmode[j] == VOIDmode + || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) + ? outmode[j] : inmode[j]); + + Insert extra parentheses so that Emacs will indent the code properly. +For example, the following indentation looks nice if you do it by hand, + + v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; + +but Emacs would alter it. Adding a set of parentheses produces +something that looks equally nice, and which Emacs will preserve: + + v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); + + Format do-while statements like this: + + do + { + a = foo (a); + } + while (a > 0); + + Please use formfeed characters (control-L) to divide the program into +pages at logical places (but not within a function). It does not matter +just how long the pages are, since they do not have to fit on a printed +page. The formfeeds should appear alone on lines by themselves. + + +File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C + +5.2 Commenting Your Work +======================== + +Every program should start with a comment saying briefly what it is for. +Example: 'fmt - filter for simple filling of text'. + + Please write the comments in a GNU program in English, because +English is the one language that nearly all programmers in all countries +can read. If you do not write English well, please write comments in +English as well as you can, then ask other people to help rewrite them. +If you can't write comments in English, please find someone to work with +you and translate your comments into English. + + Please put a comment on each function saying what the function does, +what sorts of arguments it gets, and what the possible values of +arguments mean and are used for. It is not necessary to duplicate in +words the meaning of the C argument declarations, if a C type is being +used in its customary fashion. If there is anything nonstandard about +its use (such as an argument of type 'char *' which is really the +address of the second character of a string, not the first), or any +possible values that would not work the way one would expect (such as, +that strings containing newlines are not guaranteed to work), be sure to +say so. + + Also explain the significance of the return value, if there is one. + + Please put two spaces after the end of a sentence in your comments, +so that the Emacs sentence commands will work. Also, please write +complete sentences and capitalize the first word. If a lower-case +identifier comes at the beginning of a sentence, don't capitalize it! +Changing the spelling makes it a different identifier. If you don't +like starting a sentence with a lower case letter, write the sentence +differently (e.g., "The identifier lower-case is ..."). + + The comment on a function is much clearer if you use the argument +names to speak about the argument values. The variable name itself +should be lower case, but write it in upper case when you are speaking +about the value rather than the variable itself. Thus, "the inode +number NODE_NUM" rather than "an inode". + + There is usually no purpose in restating the name of the function in +the comment before it, because the reader can see that for himself. +There might be an exception when the comment is so long that the +function itself would be off the bottom of the screen. + + There should be a comment on each static variable as well, like this: + + /* Nonzero means truncate lines in the display; + zero means continue them. */ + int truncate_lines; + + Every '#endif' should have a comment, except in the case of short +conditionals (just a few lines) that are not nested. The comment should +state the condition of the conditional that is ending, _including its +sense_. '#else' should have a comment describing the condition _and +sense_ of the code that follows. For example: + + #ifdef foo + ... + #else /* not foo */ + ... + #endif /* not foo */ + #ifdef foo + ... + #endif /* foo */ + +but, by contrast, write the comments this way for a '#ifndef': + + #ifndef foo + ... + #else /* foo */ + ... + #endif /* foo */ + #ifndef foo + ... + #endif /* not foo */ + + +File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C + +5.3 Clean Use of C Constructs +============================= + +Please explicitly declare the types of all objects. For example, you +should explicitly declare all arguments to functions, and you should +declare functions to return 'int' rather than omitting the 'int'. + + Some programmers like to use the GCC '-Wall' option, and change the +code whenever it issues a warning. If you want to do this, then do. +Other programmers prefer not to use '-Wall', because it gives warnings +for valid and legitimate code which they do not want to change. If you +want to do this, then do. The compiler should be your servant, not your +master. + + Declarations of external functions and functions to appear later in +the source file should all go in one place near the beginning of the +file (somewhere before the first function definition in the file), or +else should go in a header file. Don't put 'extern' declarations inside +functions. + + It used to be common practice to use the same local variables (with +names like 'tem') over and over for different values within one +function. Instead of doing this, it is better declare a separate local +variable for each distinct purpose, and give it a name which is +meaningful. This not only makes programs easier to understand, it also +facilitates optimization by good compilers. You can also move the +declaration of each local variable into the smallest scope that includes +all its uses. This makes the program even cleaner. + + Don't use local variables or parameters that shadow global +identifiers. + + Don't declare multiple variables in one declaration that spans lines. +Start a new declaration on each line, instead. For example, instead of +this: + + int foo, + bar; + +write either this: + + int foo, bar; + +or this: + + int foo; + int bar; + +(If they are global variables, each should have a comment preceding it +anyway.) + + When you have an 'if'-'else' statement nested in another 'if' +statement, always put braces around the 'if'-'else'. Thus, never write +like this: + + if (foo) + if (bar) + win (); + else + lose (); + +always like this: + + if (foo) + { + if (bar) + win (); + else + lose (); + } + + If you have an 'if' statement nested inside of an 'else' statement, +either write 'else if' on one line, like this, + + if (foo) + ... + else if (bar) + ... + +with its 'then'-part indented like the preceding 'then'-part, or write +the nested 'if' within braces like this: + + if (foo) + ... + else + { + if (bar) + ... + } + + Don't declare both a structure tag and variables or typedefs in the +same declaration. Instead, declare the structure tag separately and +then use it to declare the variables or typedefs. + + Try to avoid assignments inside 'if'-conditions. For example, don't +write this: + + if ((foo = (char *) malloc (sizeof *foo)) == 0) + fatal ("virtual memory exhausted"); + +instead, write this: + + foo = (char *) malloc (sizeof *foo); + if (foo == 0) + fatal ("virtual memory exhausted"); + + Don't make the program ugly to placate 'lint'. Please don't insert +any casts to 'void'. Zero without a cast is perfectly fine as a null +pointer constant, except when calling a varargs function. + + +File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C + +5.4 Naming Variables and Functions +================================== + +The names of global variables and functions in a program serve as +comments of a sort. So don't choose terse names--instead, look for +names that give useful information about the meaning of the variable or +function. In a GNU program, names should be English, like other +comments. + + Local variable names can be shorter, because they are used only +within one context, where (presumably) comments explain their purpose. + + Try to limit your use of abbreviations in symbol names. It is ok to +make a few abbreviations, explain what they mean, and then use them +frequently, but don't use lots of obscure abbreviations. + + Please use underscores to separate words in a name, so that the Emacs +word commands can be useful within them. Stick to lower case; reserve +upper case for macros and 'enum' constants, and for name-prefixes that +follow a uniform convention. + + For example, you should use names like 'ignore_space_change_flag'; +don't use names like 'iCantReadThis'. + + Variables that indicate whether command-line options have been +specified should be named after the meaning of the option, not after the +option-letter. A comment should state both the exact meaning of the +option and its letter. For example, + + /* Ignore changes in horizontal whitespace (-b). */ + int ignore_space_change_flag; + + When you want to define names with constant integer values, use +'enum' rather than '#define'. GDB knows about enumeration constants. + + You might want to make sure that none of the file names would +conflict the files were loaded onto an MS-DOS file system which shortens +the names. You can use the program 'doschk' to test for this. + + Some GNU programs were designed to limit themselves to file names of +14 characters or less, to avoid file name conflicts if they are read +into older System V systems. Please preserve this feature in the +existing GNU programs that have it, but there is no need to do this in +new GNU programs. 'doschk' also reports file names longer than 14 +characters. + + +File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C + +5.5 Portability between System Types +==================================== + +In the Unix world, "portability" refers to porting to different Unix +versions. For a GNU program, this kind of portability is desirable, but +not paramount. + + The primary purpose of GNU software is to run on top of the GNU +kernel, compiled with the GNU C compiler, on various types of CPU. So +the kinds of portability that are absolutely necessary are quite +limited. But it is important to support Linux-based GNU systems, since +they are the form of GNU that is popular. + + Beyond that, it is good to support the other free operating systems +(*BSD), and it is nice to support other Unix-like systems if you want +to. Supporting a variety of Unix-like systems is desirable, although +not paramount. It is usually not too hard, so you may as well do it. +But you don't have to consider it an obligation, if it does turn out to +be hard. + + The easiest way to achieve portability to most Unix-like systems is +to use Autoconf. It's unlikely that your program needs to know more +information about the host platform than Autoconf can provide, simply +because most of the programs that need such knowledge have already been +written. + + Avoid using the format of semi-internal data bases (e.g., +directories) when there is a higher-level alternative ('readdir'). + + As for systems that are not like Unix, such as MSDOS, Windows, the +Macintosh, VMS, and MVS, supporting them is often a lot of work. When +that is the case, it is better to spend your time adding features that +will be useful on GNU and GNU/Linux, rather than on supporting other +incompatible systems. + + It is a good idea to define the "feature test macro" '_GNU_SOURCE' +when compiling your C files. When you compile on GNU or GNU/Linux, this +will enable the declarations of GNU library extension functions, and +that will usually give you a compiler error message if you define the +same function names in some other way in your program. (You don't have +to actually _use_ these functions, if you prefer to make the program +more portable to other systems.) + + But whether or not you use these GNU extensions, you should avoid +using their names for any other meanings. Doing so would make it hard +to move your code into other GNU programs. + + +File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C + +5.6 Portability between CPUs +============================ + +Even GNU systems will differ because of differences among CPU types--for +example, difference in byte ordering and alignment requirements. It is +absolutely essential to handle these differences. However, don't make +any effort to cater to the possibility that an 'int' will be less than +32 bits. We don't support 16-bit machines in GNU. + + Similarly, don't make any effort to cater to the possibility that +'long' will be smaller than predefined types like 'size_t'. For +example, the following code is ok: + + printf ("size = %lu\n", (unsigned long) sizeof array); + printf ("diff = %ld\n", (long) (pointer2 - pointer1)); + + 1989 Standard C requires this to work, and we know of only one +counterexample: 64-bit programs on Microsoft Windows IA-64. We will +leave it to those who want to port GNU programs to that environment to +figure out how to do it. + + Predefined file-size types like 'off_t' are an exception: they are +longer than 'long' on many platforms, so code like the above won't work +with them. One way to print an 'off_t' value portably is to print its +digits yourself, one by one. + + Don't assume that the address of an 'int' object is also the address +of its least-significant byte. This is false on big-endian machines. +Thus, don't make the following mistake: + + int c; + ... + while ((c = getchar()) != EOF) + write(file_descriptor, &c, 1); + + When calling functions, you need not worry about the difference +between pointers of various types, or between pointers and integers. On +most machines, there's no difference anyway. As for the few machines +where there is a difference, all of them support Standard C prototypes, +so you can use prototypes (perhaps conditionalized to be active only in +Standard C) to make the code work on those systems. + + In certain cases, it is ok to pass integer and pointer arguments +indiscriminately to the same function, and use no prototype on any +system. For example, many GNU programs have error-reporting functions +that pass their arguments along to 'printf' and friends: + + error (s, a1, a2, a3) + char *s; + char *a1, *a2, *a3; + { + fprintf (stderr, "error: "); + fprintf (stderr, s, a1, a2, a3); + } + +In practice, this works on all machines, since a pointer is generally +the widest possible kind of argument; it is much simpler than any +"correct" alternative. Be sure _not_ to use a prototype for such +functions. + + If you have decided to use Standard C, then you can instead define +'error' using 'stdarg.h', and pass the arguments along to 'vfprintf'. + + Avoid casting pointers to integers if you can. Such casts greatly +reduce portability, and in most programs they are easy to avoid. In the +cases where casting pointers to integers is essential--such as, a Lisp +interpreter which stores type information as well as an address in one +word--you'll have to make explicit provisions to handle different word +sizes. You will also need to make provision for systems in which the +normal range of addresses you can get from 'malloc' starts far away from +zero. + + +File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C + +5.7 Calling System Functions +============================ + +C implementations differ substantially. Standard C reduces but does not +eliminate the incompatibilities; meanwhile, many GNU packages still +support pre-standard compilers because this is not hard to do. This +chapter gives recommendations for how to use the more-or-less standard C +library functions to avoid unnecessary loss of portability. + + * Don't use the return value of 'sprintf'. It returns the number of + characters written on some systems, but not on all systems. + + * Be aware that 'vfprintf' is not always available. + + * 'main' should be declared to return type 'int'. It should + terminate either by calling 'exit' or by returning the integer + status code; make sure it cannot ever return an undefined value. + + * Don't declare system functions explicitly. + + Almost any declaration for a system function is wrong on some + system. To minimize conflicts, leave it to the system header files + to declare system functions. If the headers don't declare a + function, let it remain undeclared. + + While it may seem unclean to use a function without declaring it, + in practice this works fine for most system library functions on + the systems where this really happens; thus, the disadvantage is + only theoretical. By contrast, actual declarations have frequently + caused actual conflicts. + + * If you must declare a system function, don't specify the argument + types. Use an old-style declaration, not a Standard C prototype. + The more you specify about the function, the more likely a + conflict. + + * In particular, don't unconditionally declare 'malloc' or 'realloc'. + + Most GNU programs use those functions just once, in functions + conventionally named 'xmalloc' and 'xrealloc'. These functions + call 'malloc' and 'realloc', respectively, and check the results. + + Because 'xmalloc' and 'xrealloc' are defined in your program, you + can declare them in other files without any risk of type conflict. + + On most systems, 'int' is the same length as a pointer; thus, the + calls to 'malloc' and 'realloc' work fine. For the few exceptional + systems (mostly 64-bit machines), you can use *conditionalized* + declarations of 'malloc' and 'realloc'--or put these declarations + in configuration files specific to those systems. + + * The string functions require special treatment. Some Unix systems + have a header file 'string.h'; others have 'strings.h'. Neither + file name is portable. There are two things you can do: use + Autoconf to figure out which file to include, or don't include + either file. + + * If you don't include either strings file, you can't get + declarations for the string functions from the header file in the + usual way. + + That causes less of a problem than you might think. The newer + standard string functions should be avoided anyway because many + systems still don't support them. The string functions you can use + are these: + + strcpy strncpy strcat strncat + strlen strcmp strncmp + strchr strrchr + + The copy and concatenate functions work fine without a declaration + as long as you don't use their values. Using their values without + a declaration fails on systems where the width of a pointer differs + from the width of 'int', and perhaps in other cases. It is trivial + to avoid using their values, so do that. + + The compare functions and 'strlen' work fine without a declaration + on most systems, possibly all the ones that GNU software runs on. + You may find it necessary to declare them *conditionally* on a few + systems. + + The search functions must be declared to return 'char *'. Luckily, + there is no variation in the data type they return. But there is + variation in their names. Some systems give these functions the + names 'index' and 'rindex'; other systems use the names 'strchr' + and 'strrchr'. Some systems support both pairs of names, but + neither pair works on all systems. + + You should pick a single pair of names and use it throughout your + program. (Nowadays, it is better to choose 'strchr' and 'strrchr' + for new programs, since those are the standard names.) Declare + both of those names as functions returning 'char *'. On systems + which don't support those names, define them as macros in terms of + the other pair. For example, here is what to put at the beginning + of your file (or in a header) if you want to use the names 'strchr' + and 'strrchr' throughout: + + #ifndef HAVE_STRCHR + #define strchr index + #endif + #ifndef HAVE_STRRCHR + #define strrchr rindex + #endif + + char *strchr (); + char *strrchr (); + + Here we assume that 'HAVE_STRCHR' and 'HAVE_STRRCHR' are macros +defined in systems where the corresponding functions exist. One way to +get them properly defined is to use Autoconf. + + +File: standards.info, Node: Internationalization, Next: Mmap, Prev: System Functions, Up: Writing C + +5.8 Internationalization +======================== + +GNU has a library called GNU gettext that makes it easy to translate the +messages in a program into various languages. You should use this +library in every program. Use English for the messages as they appear +in the program, and let gettext provide the way to translate them into +other languages. + + Using GNU gettext involves putting a call to the 'gettext' macro +around each string that might need translation--like this: + + printf (gettext ("Processing file `%s'...")); + +This permits GNU gettext to replace the string '"Processing file +`%s'..."' with a translated version. + + Once a program uses gettext, please make a point of writing calls to +'gettext' when you add new strings that call for translation. + + Using GNU gettext in a package involves specifying a "text domain +name" for the package. The text domain name is used to separate the +translations for this package from the translations for other packages. +Normally, the text domain name should be the same as the name of the +package--for example, 'fileutils' for the GNU file utilities. + + To enable gettext to work well, avoid writing code that makes +assumptions about the structure of words or sentences. When you want +the precise text of a sentence to vary depending on the data, use two or +more alternative string constants each containing a complete sentences, +rather than inserting conditionalized words or phrases into a single +sentence framework. + + Here is an example of what not to do: + + printf ("%d file%s processed", nfiles, + nfiles != 1 ? "s" : ""); + +The problem with that example is that it assumes that plurals are made +by adding 's'. If you apply gettext to the format string, like this, + + printf (gettext ("%d file%s processed"), nfiles, + nfiles != 1 ? "s" : ""); + +the message can use different words, but it will still be forced to use +'s' for the plural. Here is a better way: + + printf ((nfiles != 1 ? "%d files processed" + : "%d file processed"), + nfiles); + +This way, you can apply gettext to each of the two strings +independently: + + printf ((nfiles != 1 ? gettext ("%d files processed") + : gettext ("%d file processed")), + nfiles); + +This can be any method of forming the plural of the word for "file", and +also handles languages that require agreement in the word for +"processed". + + A similar problem appears at the level of sentence structure with +this code: + + printf ("# Implicit rule search has%s been done.\n", + f->tried_implicit ? "" : " not"); + +Adding 'gettext' calls to this code cannot give correct results for all +languages, because negation in some languages requires adding words at +more than one place in the sentence. By contrast, adding 'gettext' +calls does the job straightfowardly if the code starts out like this: + + printf (f->tried_implicit + ? "# Implicit rule search has been done.\n", + : "# Implicit rule search has not been done.\n"); + + +File: standards.info, Node: Mmap, Prev: Internationalization, Up: Writing C + +5.9 Mmap +======== + +Don't assume that 'mmap' either works on all files or fails for all +files. It may work on some files and fail on others. + + The proper way to use 'mmap' is to try it on the specific file for +which you want to use it--and if 'mmap' doesn't work, fall back on doing +the job in another way using 'read' and 'write'. + + The reason this precaution is needed is that the GNU kernel (the +HURD) provides a user-extensible file system, in which there can be many +different kinds of "ordinary files." Many of them support 'mmap', but +some do not. It is important to make programs handle all these kinds of +files. + + +File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top + +6 Documenting Programs +********************** + +A GNU program should ideally come with full free documentation, adequate +for both reference and tutorial purposes. If the package can be +programmed or extended, the documentation should cover programming or +extending it, as well as just using it. + +* Menu: + +* GNU Manuals:: Writing proper manuals. +* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual. +* Manual Structure Details:: Specific structure conventions. +* License for Manuals:: Writing the distribution terms for a manual. +* Manual Credits:: Giving credit to documentation contributors. +* Printed Manuals:: Mentioning the printed manual. +* NEWS File:: NEWS files supplement manuals. +* Change Logs:: Recording Changes +* Man Pages:: Man pages are secondary. +* Reading other Manuals:: How far you can go in learning + from other manuals. + + +File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation + +6.1 GNU Manuals +=============== + +The preferred document format for the GNU system is the Texinfo +formatting language. Every GNU package should (ideally) have +documentation in Texinfo both for reference and for learners. Texinfo +makes it possible to produce a good quality formatted book, using TeX, +and to generate an Info file. It is also possible to generate HTML +output from Texinfo source. See the Texinfo manual, either the +hardcopy, or the on-line version available through 'info' or the Emacs +Info subsystem ('C-h i'). + + Nowadays some other formats such as Docbook and Sgmltexi can be +converted automatically into Texinfo. It is ok to produce the Texinfo +documentation by conversion this way, as long as it gives good results. + + Programmers often find it most natural to structure the documentation +following the structure of the implementation, which they know. But +this structure is not necessarily good for explaining how to use the +program; it may be irrelevant and confusing for a user. + + At every level, from the sentences in a paragraph to the grouping of +topics into separate manuals, the right way to structure documentation +is according to the concepts and questions that a user will have in mind +when reading it. Sometimes this structure of ideas matches the +structure of the implementation of the software being documented--but +often they are different. Often the most important part of learning to +write good documentation is learning to notice when you are structuring +the documentation like the implementation, and think about better +alternatives. + + For example, each program in the GNU system probably ought to be +documented in one manual; but this does not mean each program should +have its own manual. That would be following the structure of the +implementation, rather than the structure that helps the user +understand. + + Instead, each manual should cover a coherent _topic_. For example, +instead of a manual for 'diff' and a manual for 'diff3', we have one +manual for "comparison of files" which covers both of those programs, as +well as 'cmp'. By documenting these programs together, we can make the +whole subject clearer. + + The manual which discusses a program should certainly document all of +the program's command-line options and all of its commands. It should +give examples of their use. But don't organize the manual as a list of +features. Instead, organize it logically, by subtopics. Address the +questions that a user will ask when thinking about the job that the +program does. + + In general, a GNU manual should serve both as tutorial and reference. +It should be set up for convenient access to each topic through Info, +and for reading straight through (appendixes aside). A GNU manual +should give a good introduction to a beginner reading through from the +start, and should also provide all the details that hackers want. The +Bison manual is a good example of this--please take a look at it to see +what we mean. + + That is not as hard as it first sounds. Arrange each chapter as a +logical breakdown of its topic, but order the sections, and write their +text, so that reading the chapter straight through makes sense. Do +likewise when structuring the book into chapters, and when structuring a +section into paragraphs. The watchword is, _at each point, address the +most fundamental and important issue raised by the preceding text._ + + If necessary, add extra chapters at the beginning of the manual which +are purely tutorial and cover the basics of the subject. These provide +the framework for a beginner to understand the rest of the manual. The +Bison manual provides a good example of how to do this. + + To serve as a reference, a manual should have an Index that list all +the functions, variables, options, and important concepts that are part +of the program. One combined Index should do for a short manual, but +sometimes for a complex package it is better to use multiple indices. +The Texinfo manual includes advice on preparing good index entries, see +*note Making Index Entries: (texinfo)Index Entries, and see *note +Defining the Entries of an Index: (texinfo)Indexing Commands. + + Don't use Unix man pages as a model for how to write GNU +documentation; most of them are terse, badly structured, and give +inadequate explanation of the underlying concepts. (There are, of +course, some exceptions.) Also, Unix man pages use a particular format +which is different from what we use in GNU manuals. + + Please include an email address in the manual for where to report +bugs _in the manual_. + + Please do not use the term "pathname" that is used in Unix +documentation; use "file name" (two words) instead. We use the term +"path" only for search paths, which are lists of directory names. + + Please do not use the term "illegal" to refer to erroneous input to a +computer program. Please use "invalid" for this, and reserve the term +"illegal" for activities punishable by law. + + +File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation + +6.2 Doc Strings and Manuals +=========================== + +Some programming systems, such as Emacs, provide a documentation string +for each function, command or variable. You may be tempted to write a +reference manual by compiling the documentation strings and writing a +little additional text to go around them--but you must not do it. That +approach is a fundamental mistake. The text of well-written +documentation strings will be entirely wrong for a manual. + + A documentation string needs to stand alone--when it appears on the +screen, there will be no other text to introduce or explain it. +Meanwhile, it can be rather informal in style. + + The text describing a function or variable in a manual must not stand +alone; it appears in the context of a section or subsection. Other text +at the beginning of the section should explain some of the concepts, and +should often make some general points that apply to several functions or +variables. The previous descriptions of functions and variables in the +section will also have given information about the topic. A description +written to stand alone would repeat some of that information; this +redundance looks bad. Meanwhile, the informality that is acceptable in +a documentation string is totally unacceptable in a manual. + + The only good way to use documentation strings in writing a good +manual is to use them as a source of information for writing good text. + + +File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation + +6.3 Manual Structure Details +============================ + +The title page of the manual should state the version of the programs or +packages documented in the manual. The Top node of the manual should +also contain this information. If the manual is changing more +frequently than or independent of the program, also state a version +number for the manual in both of these places. + + Each program documented in the manual should have a node named +'PROGRAM Invocation' or 'Invoking PROGRAM'. This node (together with +its subnodes, if any) should describe the program's command line +arguments and how to run it (the sort of information people would look +in a man page for). Start with an '@example' containing a template for +all the options and arguments that the program uses. + + Alternatively, put a menu item in some menu whose item name fits one +of the above patterns. This identifies the node which that item points +to as the node for this purpose, regardless of the node's actual name. + + The '--usage' feature of the Info reader looks for such a node or +menu item in order to find the relevant text, so it is essential for +every Texinfo file to have one. + + If one manual describes several programs, it should have such a node +for each program described in the manual. + + +File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation + +6.4 License for Manuals +======================= + +Please use the GNU Free Documentation License for all GNU manuals that +are more than a few pages long. Likewise for a collection of short +documents--you only need one copy of the GNU FDL for the whole +collection. For a single short document, you can use a very permissive +non-copyleft license, to avoid taking up space with a long license. + + See <http://www.gnu.org/copyleft/fdl-howto.html> for more explanation +of how to employ the GFDL. + + Note that it is not obligatory to include a copy of the GNU GPL or +GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It +can be a good idea to include the program's license in a large manual; +in a short manual, whose size would be increased considerably by +including the program's license, it is probably better not to include +it. + + +File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation + +6.5 Manual Credits +================== + +Please credit the principal human writers of the manual as the authors, +on the title page of the manual. If a company sponsored the work, thank +the company in a suitable place in the manual, but do not cite the +company as an author. + + +File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation + +6.6 Printed Manuals +=================== + +The FSF publishes some GNU manuals in printed form. To encourage sales +of these manuals, the on-line versions of the manual should mention at +the very start that the printed manual is available and should point at +information for getting it--for instance, with a link to the page +<http://www.gnu.org/order/order.html>. This should not be included in +the printed manual, though, because there it is redundant. + + It is also useful to explain in the on-line forms of the manual how +the user can print out the manual from the sources. + + +File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation + +6.7 The NEWS File +================= + +In addition to its manual, the package should have a file named 'NEWS' +which contains a list of user-visible changes worth mentioning. In each +new release, add items to the front of the file and identify the version +they pertain to. Don't discard old items; leave them in the file after +the newer items. This way, a user upgrading from any previous version +can see what is new. + + If the 'NEWS' file gets very long, move some of the older items into +a file named 'ONEWS' and put a note at the end referring the user to +that file. + + +File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation + +6.8 Change Logs +=============== + +Keep a change log to describe all the changes made to program source +files. The purpose of this is so that people investigating bugs in the +future will know about the changes that might have introduced the bug. +Often a new bug can be found by looking at what was recently changed. +More importantly, change logs can help you eliminate conceptual +inconsistencies between different parts of a program, by giving you a +history of how the conflicting concepts arose and who they came from. + +* Menu: + +* Change Log Concepts:: +* Style of Change Logs:: +* Simple Changes:: +* Conditional Changes:: +* Indicating the Part Changed:: + + +File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs + +6.8.1 Change Log Concepts +------------------------- + +You can think of the change log as a conceptual "undo list" which +explains how earlier versions were different from the current version. +People can see the current version; they don't need the change log to +tell them what is in it. What they want from a change log is a clear +explanation of how the earlier version differed. + + The change log file is normally called 'ChangeLog' and covers an +entire directory. Each directory can have its own change log, or a +directory can use the change log of its parent directory-it's up to you. + + Another alternative is to record change log information with a +version control system such as RCS or CVS. This can be converted +automatically to a 'ChangeLog' file using 'rcs2log'; in Emacs, the +command 'C-x v a' ('vc-update-change-log') does the job. + + There's no need to describe the full purpose of the changes or how +they work together. If you think that a change calls for explanation, +you're probably right. Please do explain it--but please put the +explanation in comments in the code, where people will see it whenever +they see the code. For example, "New function" is enough for the change +log when you add a function, because there should be a comment before +the function definition to explain what it does. + + However, sometimes it is useful to write one line to describe the +overall purpose of a batch of changes. + + The easiest way to add an entry to 'ChangeLog' is with the Emacs +command 'M-x add-change-log-entry'. An entry should have an asterisk, +the name of the changed file, and then in parentheses the name of the +changed functions, variables or whatever, followed by a colon. Then +describe the changes you made to that function or variable. + + +File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs + +6.8.2 Style of Change Logs +-------------------------- + +Here are some simple examples of change log entries, starting with the +header line that says who made the change and when, followed by +descriptions of specific changes. (These examples are drawn from Emacs +and GCC.) + + 1998-08-17 Richard Stallman <rms@gnu.org> + + * register.el (insert-register): Return nil. + (jump-to-register): Likewise. + + * sort.el (sort-subr): Return nil. + + * tex-mode.el (tex-bibtex-file, tex-file, tex-region): + Restart the tex shell if process is gone or stopped. + (tex-shell-running): New function. + + * expr.c (store_one_arg): Round size up for move_block_to_reg. + (expand_call): Round up when emitting USE insns. + * stmt.c (assign_parms): Round size up for move_block_from_reg. + + It's important to name the changed function or variable in full. +Don't abbreviate function or variable names, and don't combine them. +Subsequent maintainers will often search for a function name to find all +the change log entries that pertain to it; if you abbreviate the name, +they won't find it when they search. + + For example, some people are tempted to abbreviate groups of function +names by writing '* register.el ({insert,jump-to}-register)'; this is +not a good idea, since searching for 'jump-to-register' or +'insert-register' would not find that entry. + + Separate unrelated change log entries with blank lines. When two +entries represent parts of the same change, so that they work together, +then don't put blank lines between them. Then you can omit the file +name and the asterisk when successive entries are in the same file. + + Break long lists of function names by closing continued lines with +')', rather than ',', and opening the continuation with '(' as in this +example: + + * keyboard.c (menu_bar_items, tool_bar_items) + (Fexecute_extended_command): Deal with `keymap' property. + + +File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs + +6.8.3 Simple Changes +-------------------- + +Certain simple kinds of changes don't need much detail in the change +log. + + When you change the calling sequence of a function in a simple +fashion, and you change all the callers of the function to use the new +calling sequence, there is no need to make individual entries for all +the callers that you changed. Just write in the entry for the function +being called, "All callers changed"--like this: + + * keyboard.c (Fcommand_execute): New arg SPECIAL. + All callers changed. + + When you change just comments or doc strings, it is enough to write +an entry for the file, without mentioning the functions. Just "Doc +fixes" is enough for the change log. + + There's no need to make change log entries for documentation files. +This is because documentation is not susceptible to bugs that are hard +to fix. Documentation does not consist of parts that must interact in a +precisely engineered fashion. To correct an error, you need not know +the history of the erroneous passage; it is enough to compare what the +documentation says with the way the program actually works. + + +File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs + +6.8.4 Conditional Changes +------------------------- + +C programs often contain compile-time '#if' conditionals. Many changes +are conditional; sometimes you add a new definition which is entirely +contained in a conditional. It is very useful to indicate in the change +log the conditions for which the change applies. + + Our convention for indicating conditional changes is to use square +brackets around the name of the condition. + + Here is a simple example, describing a change which is conditional +but does not have a function or entity name associated with it: + + * xterm.c [SOLARIS2]: Include string.h. + + Here is an entry describing a new definition which is entirely +conditional. This new definition for the macro 'FRAME_WINDOW_P' is used +only when 'HAVE_X_WINDOWS' is defined: + + * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. + + Here is an entry for a change within the function 'init_display', +whose definition as a whole is unconditional, but the changes themselves +are contained in a '#ifdef HAVE_LIBNCURSES' conditional: + + * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. + + Here is an entry for a change that takes affect only when a certain +macro is _not_ defined: + + (gethostname) [!HAVE_SOCKETS]: Replace with winsock version. + + +File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs + +6.8.5 Indicating the Part Changed +--------------------------------- + +Indicate the part of a function which changed by using angle brackets +enclosing an indication of what the changed part does. Here is an entry +for a change in the part of the function 'sh-while-getopts' that deals +with 'sh' commands: + + * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that + user-specified option string is empty. + + +File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation + +6.9 Man Pages +============= + +In the GNU project, man pages are secondary. It is not necessary or +expected for every GNU program to have a man page, but some of them do. +It's your choice whether to include a man page in your program. + + When you make this decision, consider that supporting a man page +requires continual effort each time the program is changed. The time +you spend on the man page is time taken away from more useful work. + + For a simple program which changes little, updating the man page may +be a small job. Then there is little reason not to include a man page, +if you have one. + + For a large program that changes a great deal, updating a man page +may be a substantial burden. If a user offers to donate a man page, you +may find this gift costly to accept. It may be better to refuse the man +page unless the same person agrees to take full responsibility for +maintaining it--so that you can wash your hands of it entirely. If this +volunteer later ceases to do the job, then don't feel obliged to pick it +up yourself; it may be better to withdraw the man page from the +distribution until someone else agrees to update it. + + When a program changes only a little, you may feel that the +discrepancies are small enough that the man page remains useful without +updating. If so, put a prominent note near the beginning of the man +page explaining that you don't maintain it and that the Texinfo manual +is more authoritative. The note should say how to access the Texinfo +documentation. + + +File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation + +6.10 Reading other Manuals +========================== + +There may be non-free books or documentation files that describe the +program you are documenting. + + It is ok to use these documents for reference, just as the author of +a new algebra textbook can read other books on algebra. A large portion +of any non-fiction book consists of facts, in this case facts about how +a certain program works, and these facts are necessarily the same for +everyone who writes about the subject. But be careful not to copy your +outline structure, wording, tables or examples from preexisting non-free +documentation. Copying from free documentation may be ok; please check +with the FSF about the individual case. + + +File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top + +7 The Release Process +********************* + +Making a release is more than just bundling up your source files in a +tar file and putting it up for FTP. You should set up your software so +that it can be configured to run on a variety of systems. Your Makefile +should conform to the GNU standards described below, and your directory +layout should also conform to the standards discussed below. Doing so +makes it easy to include your package into the larger framework of all +GNU software. + +* Menu: + +* Configuration:: How Configuration Should Work +* Makefile Conventions:: Makefile Conventions +* Releases:: Making Releases + + +File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases + +7.1 How Configuration Should Work +================================= + +Each GNU distribution should come with a shell script named 'configure'. +This script is given arguments which describe the kind of machine and +system you want to compile the program for. + + The 'configure' script must record the configuration options so that +they affect compilation. + + One way to do this is to make a link from a standard name such as +'config.h' to the proper configuration file for the chosen system. If +you use this technique, the distribution should _not_ contain a file +named 'config.h'. This is so that people won't be able to build the +program without configuring it first. + + Another thing that 'configure' can do is to edit the Makefile. If +you do this, the distribution should _not_ contain a file named +'Makefile'. Instead, it should include a file 'Makefile.in' which +contains the input used for editing. Once again, this is so that people +won't be able to build the program without configuring it first. + + If 'configure' does write the 'Makefile', then 'Makefile' should have +a target named 'Makefile' which causes 'configure' to be rerun, setting +up the same configuration that was set up last time. The files that +'configure' reads should be listed as dependencies of 'Makefile'. + + All the files which are output from the 'configure' script should +have comments at the beginning explaining that they were generated +automatically using 'configure'. This is so that users won't think of +trying to edit them by hand. + + The 'configure' script should write a file named 'config.status' +which describes which configuration options were specified when the +program was last configured. This file should be a shell script which, +if run, will recreate the same configuration. + + The 'configure' script should accept an option of the form +'--srcdir=DIRNAME' to specify the directory where sources are found (if +it is not the current directory). This makes it possible to build the +program in a separate directory, so that the actual source directory is +not modified. + + If the user does not specify '--srcdir', then 'configure' should +check both '.' and '..' to see if it can find the sources. If it finds +the sources in one of these places, it should use them from there. +Otherwise, it should report that it cannot find the sources, and should +exit with nonzero status. + + Usually the easy way to support '--srcdir' is by editing a definition +of 'VPATH' into the Makefile. Some rules may need to refer explicitly +to the specified source directory. To make this possible, 'configure' +can add to the Makefile a variable named 'srcdir' whose value is +precisely the specified directory. + + The 'configure' script should also take an argument which specifies +the type of system to build the program for. This argument should look +like this: + + CPU-COMPANY-SYSTEM + + For example, a Sun 3 might be 'm68k-sun-sunos4.1'. + + The 'configure' script needs to be able to decode all plausible +alternatives for how to describe a machine. Thus, 'sun3-sunos4.1' would +be a valid alias. For many programs, 'vax-dec-ultrix' would be an alias +for 'vax-dec-bsd', simply because the differences between Ultrix and BSD +are rarely noticeable, but a few programs might need to distinguish +them. + + There is a shell script called 'config.sub' that you can use as a +subroutine to validate system types and canonicalize aliases. + + Other options are permitted to specify in more detail the software or +hardware present on the machine, and include or exclude optional parts +of the package: + +'--enable-FEATURE[=PARAMETER]' + Configure the package to build and install an optional user-level + facility called FEATURE. This allows users to choose which + optional features to include. Giving an optional PARAMETER of 'no' + should omit FEATURE, if it is built by default. + + No '--enable' option should *ever* cause one feature to replace + another. No '--enable' option should ever substitute one useful + behavior for another useful behavior. The only proper use for + '--enable' is for questions of whether to build part of the program + or exclude it. + +'--with-PACKAGE' + The package PACKAGE will be installed, so configure this package to + work with PACKAGE. + + Possible values of PACKAGE include 'gnu-as' (or 'gas'), 'gnu-ld', + 'gnu-libc', 'gdb', 'x', and 'x-toolkit'. + + Do not use a '--with' option to specify the file name to use to + find certain files. That is outside the scope of what '--with' + options are for. + + All 'configure' scripts should accept all of these "detail" options, +whether or not they make any difference to the particular package at +hand. In particular, they should accept any option that starts with +'--with-' or '--enable-'. This is so users will be able to configure an +entire GNU source tree at once with a single set of options. + + You will note that the categories '--with-' and '--enable-' are +narrow: they *do not* provide a place for any sort of option you might +think of. That is deliberate. We want to limit the possible +configuration options in GNU software. We do not want GNU programs to +have idiosyncratic configuration options. + + Packages that perform part of the compilation process may support +cross-compilation. In such a case, the host and target machines for the +program may be different. + + The 'configure' script should normally treat the specified type of +system as both the host and the target, thus producing a program which +works for the same type of machine that it runs on. + + To configure a cross-compiler, cross-assembler, or what have you, you +should specify a target different from the host, using the configure +option '--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as +for the host type. So the command would look like this: + + ./configure HOSTTYPE --target=TARGETTYPE + + Programs for which cross-operation is not meaningful need not accept +the '--target' option, because configuring an entire operating system +for cross-operation is not a meaningful operation. + + Bootstrapping a cross-compiler requires compiling it on a machine +other than the host it will run on. Compilation packages accept a +configuration option '--build=BUILDTYPE' for specifying the +configuration on which you will compile them, but the configure script +should normally guess the build machine type (using 'config.guess'), so +this option is probably not necessary. The host and target types +normally default from the build type, so in bootstrapping a +cross-compiler you must specify them both explicitly. + + Some programs have ways of configuring themselves automatically. If +your program is set up to do this, your 'configure' script can simply +ignore most of its arguments. + + +File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases + +7.2 Makefile Conventions +======================== + +This node describes conventions for writing the Makefiles for GNU +programs. Using Automake will help you write a Makefile that follows +these conventions. + +* Menu: + +* Makefile Basics:: General Conventions for Makefiles +* Utilities in Makefiles:: Utilities in Makefiles +* Command Variables:: Variables for Specifying Commands +* Directory Variables:: Variables for Installation Directories +* Standard Targets:: Standard Targets for Users +* Install Command Categories:: Three categories of commands in the 'install' + rule: normal, pre-install and post-install. + + +File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions + +7.2.1 General Conventions for Makefiles +--------------------------------------- + +Every Makefile should contain this line: + + SHELL = /bin/sh + +to avoid trouble on systems where the 'SHELL' variable might be +inherited from the environment. (This is never a problem with GNU +'make'.) + + Different 'make' programs have incompatible suffix lists and implicit +rules, and this sometimes creates confusion or misbehavior. So it is a +good idea to set the suffix list explicitly using only the suffixes you +need in the particular Makefile, like this: + + .SUFFIXES: + .SUFFIXES: .c .o + +The first line clears out the suffix list, the second introduces all +suffixes which may be subject to implicit rules in this Makefile. + + Don't assume that '.' is in the path for command execution. When you +need to run programs that are a part of your package during the make, +please make sure that it uses './' if the program is built as part of +the make or '$(srcdir)/' if the file is an unchanging part of the source +code. Without one of these prefixes, the current search path is used. + + The distinction between './' (the "build directory") and '$(srcdir)/' +(the "source directory") is important because users can build in a +separate directory using the '--srcdir' option to 'configure'. A rule +of the form: + + foo.1 : foo.man sedscript + sed -e sedscript foo.man > foo.1 + +will fail when the build directory is not the source directory, because +'foo.man' and 'sedscript' are in the source directory. + + When using GNU 'make', relying on 'VPATH' to find the source file +will work in the case where there is a single dependency file, since the +'make' automatic variable '$<' will represent the source file wherever +it is. (Many versions of 'make' set '$<' only in implicit rules.) A +Makefile target like + + foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o + +should instead be written as + + foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@ + +in order to allow 'VPATH' to work correctly. When the target has +multiple dependencies, using an explicit '$(srcdir)' is the easiest way +to make the rule work well. For example, the target above for 'foo.1' +is best written as: + + foo.1 : foo.man sedscript + sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@ + + GNU distributions usually contain some files which are not source +files--for example, Info files, and the output from Autoconf, Automake, +Bison or Flex. Since these files normally appear in the source +directory, they should always appear in the source directory, not in the +build directory. So Makefile rules to update them should put the +updated files in the source directory. + + However, if a file does not appear in the distribution, then the +Makefile should not put it in the source directory, because building a +program in ordinary circumstances should not modify the source directory +in any way. + + Try to make the build and installation targets, at least (and all +their subtargets) work correctly with a parallel 'make'. + + +File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions + +7.2.2 Utilities in Makefiles +---------------------------- + +Write the Makefile commands (and any shell scripts, such as 'configure') +to run in 'sh', not in 'csh'. Don't use any special features of 'ksh' +or 'bash'. + + The 'configure' script and the Makefile rules for building and +installation should not use any utilities directly except these: + + cat cmp cp diff echo egrep expr false grep install-info + ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true + + The compression program 'gzip' can be used in the 'dist' rule. + + Stick to the generally supported options for these programs. For +example, don't use 'mkdir -p', convenient as it may be, because most +systems don't support it. + + It is a good idea to avoid creating symbolic links in makefiles, +since a few systems don't support them. + + The Makefile rules for building and installation can also use +compilers and related programs, but should do so via 'make' variables so +that the user can substitute alternatives. Here are some of the +programs we mean: + + ar bison cc flex install ld ldconfig lex + make makeinfo ranlib texi2dvi yacc + + Use the following 'make' variables to run those programs: + + $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) + $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) + + When you use 'ranlib' or 'ldconfig', you should make sure nothing bad +happens if the system does not have the program in question. Arrange to +ignore an error from that command, and print a message before the +command to tell the user that failure of this command does not mean a +problem. (The Autoconf 'AC_PROG_RANLIB' macro can help with this.) + + If you use symbolic links, you should implement a fallback for +systems that don't have symbolic links. + + Additional utilities that can be used via Make variables are: + + chgrp chmod chown mknod + + It is ok to use other utilities in Makefile portions (or scripts) +intended only for particular systems where you know those utilities +exist. + + +File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions + +7.2.3 Variables for Specifying Commands +--------------------------------------- + +Makefiles should provide variables for overriding certain commands, +options, and so on. + + In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named 'BISON' whose default +value is set with 'BISON = bison', and refer to it with '$(BISON)' +whenever you need to use Bison. + + File management utilities such as 'ln', 'rm', 'mv', and so on, need +not be referred to through variables in this way, since users don't need +to replace them with other programs. + + Each program-name variable should come with an options variable that +is used to supply options to the program. Append 'FLAGS' to the +program-name variable name to get the options variable name--for +example, 'BISONFLAGS'. (The names 'CFLAGS' for the C compiler, 'YFLAGS' +for yacc, and 'LFLAGS' for lex, are exceptions to this rule, but we keep +them because they are standard.) Use 'CPPFLAGS' in any compilation +command that runs the preprocessor, and use 'LDFLAGS' in any compilation +command that does linking as well as in any direct use of 'ld'. + + If there are C compiler options that _must_ be used for proper +compilation of certain files, do not include them in 'CFLAGS'. Users +expect to be able to specify 'CFLAGS' freely themselves. Instead, +arrange to pass the necessary options to the C compiler independently of +'CFLAGS', by writing them explicitly in the compilation commands or by +defining an implicit rule, like this: + + CFLAGS = -g + ALL_CFLAGS = -I. $(CFLAGS) + .c.o: + $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< + + Do include the '-g' option in 'CFLAGS', because that is not +_required_ for proper compilation. You can consider it a default that +is only recommended. If the package is set up so that it is compiled +with GCC by default, then you might as well include '-O' in the default +value of 'CFLAGS' as well. + + Put 'CFLAGS' last in the compilation command, after other variables +containing compiler options, so the user can use 'CFLAGS' to override +the others. + + 'CFLAGS' should be used in every invocation of the C compiler, both +those which do compilation and those which do linking. + + Every Makefile should define the variable 'INSTALL', which is the +basic command for installing a file into the system. + + Every Makefile should also define the variables 'INSTALL_PROGRAM' and +'INSTALL_DATA'. (The default for 'INSTALL_PROGRAM' should be +'$(INSTALL)'; the default for 'INSTALL_DATA' should be '${INSTALL} -m +644'.) Then it should use those variables as the commands for actual +installation, for executables and nonexecutables respectively. Use +these variables as follows: + + $(INSTALL_PROGRAM) foo $(bindir)/foo + $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a + + Optionally, you may prepend the value of 'DESTDIR' to the target +filename. Doing this allows the installer to create a snapshot of the +installation to be copied onto the real target filesystem later. Do not +set the value of 'DESTDIR' in your Makefile, and do not include it in +any installed files. With support for 'DESTDIR', the above examples +become: + + $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo + $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a + +Always use a file name, not a directory name, as the second argument of +the installation commands. Use a separate command for each file to be +installed. + + +File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions + +7.2.4 Variables for Installation Directories +-------------------------------------------- + +Installation directories should always be named by variables, so it is +easy to install in a nonstandard place. The standard names for these +variables are described below. They are based on a standard filesystem +layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4, +and other modern operating systems. + + These two variables set the root for the installation. All the other +installation directories should be subdirectories of one of these two, +and nothing should be directly installed into these two directories. + +'prefix' + A prefix used in constructing the default values of the variables + listed below. The default value of 'prefix' should be + '/usr/local'. When building the complete GNU system, the prefix + will be empty and '/usr' will be a symbolic link to '/'. (If you + are using Autoconf, write it as '@prefix@'.) + + Running 'make install' with a different value of 'prefix' from the + one used to build the program should _not_ recompile the program. + +'exec_prefix' + A prefix used in constructing the default values of some of the + variables listed below. The default value of 'exec_prefix' should + be '$(prefix)'. (If you are using Autoconf, write it as + '@exec_prefix@'.) + + Generally, '$(exec_prefix)' is used for directories that contain + machine-specific files (such as executables and subroutine + libraries), while '$(prefix)' is used directly for other + directories. + + Running 'make install' with a different value of 'exec_prefix' from + the one used to build the program should _not_ recompile the + program. + + Executable programs are installed in one of the following +directories. + +'bindir' + The directory for installing executable programs that users can + run. This should normally be '/usr/local/bin', but write it as + '$(exec_prefix)/bin'. (If you are using Autoconf, write it as + '@bindir@'.) + +'sbindir' + The directory for installing executable programs that can be run + from the shell, but are only generally useful to system + administrators. This should normally be '/usr/local/sbin', but + write it as '$(exec_prefix)/sbin'. (If you are using Autoconf, + write it as '@sbindir@'.) + +'libexecdir' + The directory for installing executable programs to be run by other + programs rather than by users. This directory should normally be + '/usr/local/libexec', but write it as '$(exec_prefix)/libexec'. + (If you are using Autoconf, write it as '@libexecdir@'.) + + Data files used by the program during its execution are divided into +categories in two ways. + + * Some files are normally modified by programs; others are never + normally modified (though users may edit some of these). + + * Some files are architecture-independent and can be shared by all + machines at a site; some are architecture-dependent and can be + shared only by machines of the same kind and operating system; + others may never be shared between two machines. + + This makes for six different possibilities. However, we want to +discourage the use of architecture-dependent files, aside from object +files and libraries. It is much cleaner to make other data files +architecture-independent, and it is generally not hard. + + Therefore, here are the variables Makefiles should use to specify +directories: + +'datadir' + The directory for installing read-only architecture independent + data files. This should normally be '/usr/local/share', but write + it as '$(prefix)/share'. (If you are using Autoconf, write it as + '@datadir@'.) As a special exception, see '$(infodir)' and + '$(includedir)' below. + +'sysconfdir' + The directory for installing read-only data files that pertain to a + single machine-that is to say, files for configuring a host. + Mailer and network configuration files, '/etc/passwd', and so forth + belong here. All the files in this directory should be ordinary + ASCII text files. This directory should normally be + '/usr/local/etc', but write it as '$(prefix)/etc'. (If you are + using Autoconf, write it as '@sysconfdir@'.) + + Do not install executables here in this directory (they probably + belong in '$(libexecdir)' or '$(sbindir)'). Also do not install + files that are modified in the normal course of their use (programs + whose purpose is to change the configuration of the system + excluded). Those probably belong in '$(localstatedir)'. + +'sharedstatedir' + The directory for installing architecture-independent data files + which the programs modify while they run. This should normally be + '/usr/local/com', but write it as '$(prefix)/com'. (If you are + using Autoconf, write it as '@sharedstatedir@'.) + +'localstatedir' + The directory for installing data files which the programs modify + while they run, and that pertain to one specific machine. Users + should never need to modify files in this directory to configure + the package's operation; put such configuration information in + separate files that go in '$(datadir)' or '$(sysconfdir)'. + '$(localstatedir)' should normally be '/usr/local/var', but write + it as '$(prefix)/var'. (If you are using Autoconf, write it as + '@localstatedir@'.) + +'libdir' + The directory for object files and libraries of object code. Do + not install executables here, they probably ought to go in + '$(libexecdir)' instead. The value of 'libdir' should normally be + '/usr/local/lib', but write it as '$(exec_prefix)/lib'. (If you + are using Autoconf, write it as '@libdir@'.) + +'infodir' + The directory for installing the Info files for this package. By + default, it should be '/usr/local/info', but it should be written + as '$(prefix)/info'. (If you are using Autoconf, write it as + '@infodir@'.) + +'lispdir' + The directory for installing any Emacs Lisp files in this package. + By default, it should be '/usr/local/share/emacs/site-lisp', but it + should be written as '$(prefix)/share/emacs/site-lisp'. + + If you are using Autoconf, write the default as '@lispdir@'. In + order to make '@lispdir@' work, you need the following lines in + your 'configure.in' file: + + lispdir='${datadir}/emacs/site-lisp' + AC_SUBST(lispdir) + +'includedir' + The directory for installing header files to be included by user + programs with the C '#include' preprocessor directive. This should + normally be '/usr/local/include', but write it as + '$(prefix)/include'. (If you are using Autoconf, write it as + '@includedir@'.) + + Most compilers other than GCC do not look for header files in + directory '/usr/local/include'. So installing the header files + this way is only useful with GCC. Sometimes this is not a problem + because some libraries are only really intended to work with GCC. + But some libraries are intended to work with other compilers. They + should install their header files in two places, one specified by + 'includedir' and one specified by 'oldincludedir'. + +'oldincludedir' + The directory for installing '#include' header files for use with + compilers other than GCC. This should normally be '/usr/include'. + (If you are using Autoconf, you can write it as '@oldincludedir@'.) + + The Makefile commands should check whether the value of + 'oldincludedir' is empty. If it is, they should not try to use it; + they should cancel the second installation of the header files. + + A package should not replace an existing header in this directory + unless the header came from the same package. Thus, if your Foo + package provides a header file 'foo.h', then it should install the + header file in the 'oldincludedir' directory if either (1) there is + no 'foo.h' there or (2) the 'foo.h' that exists came from the Foo + package. + + To tell whether 'foo.h' came from the Foo package, put a magic + string in the file--part of a comment--and 'grep' for that string. + + Unix-style man pages are installed in one of the following: + +'mandir' + The top-level directory for installing the man pages (if any) for + this package. It will normally be '/usr/local/man', but you should + write it as '$(prefix)/man'. (If you are using Autoconf, write it + as '@mandir@'.) + +'man1dir' + The directory for installing section 1 man pages. Write it as + '$(mandir)/man1'. +'man2dir' + The directory for installing section 2 man pages. Write it as + '$(mandir)/man2' +'...' + + *Don't make the primary documentation for any GNU software be a man + page. Write a manual in Texinfo instead. Man pages are just for + the sake of people running GNU software on Unix, which is a + secondary application only.* + +'manext' + The file name extension for the installed man page. This should + contain a period followed by the appropriate digit; it should + normally be '.1'. + +'man1ext' + The file name extension for installed section 1 man pages. +'man2ext' + The file name extension for installed section 2 man pages. +'...' + Use these names instead of 'manext' if the package needs to install + man pages in more than one section of the manual. + + And finally, you should set the following variable: + +'srcdir' + The directory for the sources being compiled. The value of this + variable is normally inserted by the 'configure' shell script. (If + you are using Autconf, use 'srcdir = @srcdir@'.) + + For example: + + # Common prefix for installation directories. + # NOTE: This directory must exist when you start the install. + prefix = /usr/local + exec_prefix = $(prefix) + # Where to put the executable for the command `gcc'. + bindir = $(exec_prefix)/bin + # Where to put the directories used by the compiler. + libexecdir = $(exec_prefix)/libexec + # Where to put the Info files. + infodir = $(prefix)/info + + If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the 'install' rule to create these subdirectories. + + Do not expect the user to include the subdirectory name in the value +of any of the variables listed above. The idea of having a uniform set +of variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. + + +File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions + +7.2.5 Standard Targets for Users +-------------------------------- + +All GNU programs should have the following targets in their Makefiles: + +'all' + Compile the entire program. This should be the default target. + This target need not rebuild any documentation files; Info files + should normally be included in the distribution, and DVI files + should be made only when explicitly asked for. + + By default, the Make rules should compile and link with '-g', so + that executable programs have debugging symbols. Users who don't + mind being helpless can strip the executables later if they wish. + +'install' + Compile the program and copy the executables, libraries, and so on + to the file names where they should reside for actual use. If + there is a simple test to verify that a program is properly + installed, this target should run that test. + + Do not strip executables when installing them. Devil-may-care + users can use the 'install-strip' target to do that. + + If possible, write the 'install' target rule so that it does not + modify anything in the directory where the program was built, + provided 'make all' has just been done. This is convenient for + building the program under one user name and installing it under + another. + + The commands should create all the directories in which files are + to be installed, if they don't already exist. This includes the + directories specified as the values of the variables 'prefix' and + 'exec_prefix', as well as all subdirectories that are needed. One + way to do this is by means of an 'installdirs' target as described + below. + + Use '-' before any command for installing a man page, so that + 'make' will ignore any errors. This is in case there are systems + that don't have the Unix man page documentation system installed. + + The way to install Info files is to copy them into '$(infodir)' + with '$(INSTALL_DATA)' (*note Command Variables::), and then run + the 'install-info' program if it is present. 'install-info' is a + program that edits the Info 'dir' file to add or update the menu + entry for the given Info file; it is part of the Texinfo package. + Here is a sample rule to install an Info file: + + $(DESTDIR)$(infodir)/foo.info: foo.info + $(POST_INSTALL) + # There may be a newer info file in . than in srcdir. + -if test -f foo.info; then d=.; \ + else d=$(srcdir); fi; \ + $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \ + # Run install-info only if it exists. + # Use `if' instead of just prepending `-' to the + # line so we notice real errors from install-info. + # We use `$(SHELL) -c' because some shells do not + # fail gracefully when there is an unknown command. + if $(SHELL) -c 'install-info --version' \ + >/dev/null 2>&1; then \ + install-info --dir-file=$(DESTDIR)$(infodir)/dir \ + $(DESTDIR)$(infodir)/foo.info; \ + else true; fi + + When writing the 'install' target, you must classify all the + commands into three categories: normal ones, "pre-installation" + commands and "post-installation" commands. *Note Install Command + Categories::. + +'uninstall' + Delete all the installed files--the copies that the 'install' + target creates. + + This rule should not modify the directories where compilation is + done, only the directories where files are installed. + + The uninstallation commands are divided into three categories, just + like the installation commands. *Note Install Command + Categories::. + +'install-strip' + Like 'install', but strip the executable files while installing + them. In simple cases, this target can use the 'install' target in + a simple way: + + install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install + + But if the package installs scripts as well as real executables, + the 'install-strip' target can't just refer to the 'install' + target; it has to strip the executables but not the scripts. + + 'install-strip' should not strip the executables in the build + directory which are being copied for installation. It should only + strip the copies that are installed. + + Normally we do not recommend stripping an executable unless you are + sure the program has no bugs. However, it can be reasonable to + install a stripped executable for actual execution while saving the + unstripped executable elsewhere in case there is a bug. + +'clean' + + Delete all files from the current directory that are normally + created by building the program. Don't delete the files that + record the configuration. Also preserve files that could be made + by building, but normally aren't because the distribution comes + with them. + + Delete '.dvi' files here if they are not part of the distribution. + +'distclean' + Delete all files from the current directory that are created by + configuring or building the program. If you have unpacked the + source and built the program without creating any other files, + 'make distclean' should leave only the files that were in the + distribution. + +'mostlyclean' + Like 'clean', but may refrain from deleting a few files that people + normally don't want to recompile. For example, the 'mostlyclean' + target for GCC does not delete 'libgcc.a', because recompiling it + is rarely necessary and takes a lot of time. + +'maintainer-clean' + Delete almost everything from the current directory that can be + reconstructed with this Makefile. This typically includes + everything deleted by 'distclean', plus more: C source files + produced by Bison, tags tables, Info files, and so on. + + The reason we say "almost everything" is that running the command + 'make maintainer-clean' should not delete 'configure' even if + 'configure' can be remade using a rule in the Makefile. More + generally, 'make maintainer-clean' should not delete anything that + needs to exist in order to run 'configure' and then begin to build + the program. This is the only exception; 'maintainer-clean' should + delete everything else that can be rebuilt. + + The 'maintainer-clean' target is intended to be used by a + maintainer of the package, not by ordinary users. You may need + special tools to reconstruct some of the files that 'make + maintainer-clean' deletes. Since these files are normally included + in the distribution, we don't take care to make them easy to + reconstruct. If you find you need to unpack the full distribution + again, don't blame us. + + To help make users aware of this, the commands for the special + 'maintainer-clean' target should start with these two: + + @echo 'This command is intended for maintainers to use; it' + @echo 'deletes files that may need special tools to rebuild.' + +'TAGS' + Update a tags table for this program. + +'info' + Generate any Info files needed. The best way to write the rules is + as follows: + + info: foo.info + + foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi + + You must define the variable 'MAKEINFO' in the Makefile. It should + run the 'makeinfo' program, which is part of the Texinfo + distribution. + + Normally a GNU distribution comes with Info files, and that means + the Info files are present in the source directory. Therefore, the + Make rule for an info file should update it in the source + directory. When users build the package, ordinarily Make will not + update the Info files because they will already be up to date. + +'dvi' + Generate DVI files for all Texinfo documentation. For example: + + dvi: foo.dvi + + foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi + + You must define the variable 'TEXI2DVI' in the Makefile. It should + run the program 'texi2dvi', which is part of the Texinfo + distribution.(1) Alternatively, write just the dependencies, and + allow GNU 'make' to provide the command. + +'dist' + Create a distribution tar file for this program. The tar file + should be set up so that the file names in the tar file start with + a subdirectory name which is the name of the package it is a + distribution for. This name can include the version number. + + For example, the distribution tar file of GCC version 1.40 unpacks + into a subdirectory named 'gcc-1.40'. + + The easiest way to do this is to create a subdirectory + appropriately named, use 'ln' or 'cp' to install the proper files + in it, and then 'tar' that subdirectory. + + Compress the tar file with 'gzip'. For example, the actual + distribution file for GCC version 1.40 is called 'gcc-1.40.tar.gz'. + + The 'dist' target should explicitly depend on all non-source files + that are in the distribution, to make sure they are up to date in + the distribution. *Note Making Releases: Releases. + +'check' + Perform self-tests (if any). The user must build the program + before running the tests, but need not install the program; you + should write the self-tests so that they work when the program is + built but not installed. + + The following targets are suggested as conventional names, for +programs in which they are useful. + +'installcheck' + Perform installation tests (if any). The user must build and + install the program before running the tests. You should not + assume that '$(bindir)' is in the search path. + +'installdirs' + It's useful to add a target named 'installdirs' to create the + directories where files are installed, and their parent + directories. There is a script called 'mkinstalldirs' which is + convenient for this; you can find it in the Texinfo package. You + can use a rule like this: + + # Make sure all installation directories (e.g. $(bindir)) + # actually exist by making them if necessary. + installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) + + or, if you wish to support 'DESTDIR', + + # Make sure all installation directories (e.g. $(bindir)) + # actually exist by making them if necessary. + installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs \ + $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ + $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ + $(DESTDIR)$(mandir) + + This rule should not modify the directories where compilation is + done. It should do nothing but create installation directories. + + ---------- Footnotes ---------- + + (1) 'texi2dvi' uses TeX to do the real work of formatting. TeX is +not distributed with Texinfo. + + +File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions + +7.2.6 Install Command Categories +-------------------------------- + +When writing the 'install' target, you must classify all the commands +into three categories: normal ones, "pre-installation" commands and +"post-installation" commands. + + Normal commands move files into their proper places, and set their +modes. They may not alter any files except the ones that come entirely +from the package they belong to. + + Pre-installation and post-installation commands may alter other +files; in particular, they can edit global configuration files or data +bases. + + Pre-installation commands are typically executed before the normal +commands, and post-installation commands are typically run after the +normal commands. + + The most common use for a post-installation command is to run +'install-info'. This cannot be done with a normal command, since it +alters a file (the Info directory) which does not come entirely and +solely from the package being installed. It is a post-installation +command because it needs to be done after the normal command which +installs the package's Info files. + + Most programs don't need any pre-installation commands, but we have +the feature just in case it is needed. + + To classify the commands in the 'install' rule into these three +categories, insert "category lines" among them. A category line +specifies the category for the commands that follow. + + A category line consists of a tab and a reference to a special Make +variable, plus an optional comment at the end. There are three +variables you can use, one for each category; the variable name +specifies the category. Category lines are no-ops in ordinary execution +because these three Make variables are normally undefined (and you +_should not_ define them in the makefile). + + Here are the three possible category lines, each with a comment that +explains what it means: + + $(PRE_INSTALL) # Pre-install commands follow. + $(POST_INSTALL) # Post-install commands follow. + $(NORMAL_INSTALL) # Normal commands follow. + + If you don't use a category line at the beginning of the 'install' +rule, all the commands are classified as normal until the first category +line. If you don't use any category lines, all the commands are +classified as normal. + + These are the category lines for 'uninstall': + + $(PRE_UNINSTALL) # Pre-uninstall commands follow. + $(POST_UNINSTALL) # Post-uninstall commands follow. + $(NORMAL_UNINSTALL) # Normal commands follow. + + Typically, a pre-uninstall command would be used for deleting entries +from the Info directory. + + If the 'install' or 'uninstall' target has any dependencies which act +as subroutines of installation, then you should start _each_ +dependency's commands with a category line, and start the main target's +commands with a category line also. This way, you can ensure that each +command is placed in the right category regardless of which of the +dependencies actually run. + + Pre-installation and post-installation commands should not run any +programs except for these: + + [ basename bash cat chgrp chmod chown cmp cp dd diff echo + egrep expand expr false fgrep find getopt grep gunzip gzip + hostname install install-info kill ldconfig ln ls md5sum + mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee + test touch true uname xargs yes + + The reason for distinguishing the commands in this way is for the +sake of making binary packages. Typically a binary package contains all +the executables and other files that need to be installed, and has its +own method of installing them--so it does not need to run the normal +installation commands. But installing the binary package does need to +execute the pre-installation and post-installation commands. + + Programs to build binary packages work by extracting the +pre-installation and post-installation commands. Here is one way of +extracting the pre-installation commands: + + make -n install -o all \ + PRE_INSTALL=pre-install \ + POST_INSTALL=post-install \ + NORMAL_INSTALL=normal-install \ + | gawk -f pre-install.awk + +where the file 'pre-install.awk' could contain this: + + $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0} + on {print $0} + $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1} + + The resulting file of pre-installation commands is executed as a +shell script as part of installing the binary package. + + +File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases + +7.3 Making Releases +=================== + +Package the distribution of 'Foo version 69.96' up in a gzipped tar file +with the name 'foo-69.96.tar.gz'. It should unpack into a subdirectory +named 'foo-69.96'. + + Building and installing the program should never modify any of the +files contained in the distribution. This means that all the files that +form part of the program in any way must be classified into "source +files" and "non-source files". Source files are written by humans and +never changed automatically; non-source files are produced from source +files by programs under the control of the Makefile. + + The distribution should contain a file named 'README' which gives the +name of the package, and a general description of what it does. It is +also good to explain the purpose of each of the first-level +subdirectories in the package, if there are any. The 'README' file +should either state the version number of the package, or refer to where +in the package it can be found. + + The 'README' file should refer to the file 'INSTALL', which should +contain an explanation of the installation procedure. + + The 'README' file should also refer to the file which contains the +copying conditions. The GNU GPL, if used, should be in a file called +'COPYING'. If the GNU LGPL is used, it should be in a file called +'COPYING.LIB'. + + Naturally, all the source files must be in the distribution. It is +okay to include non-source files in the distribution, provided they are +up-to-date and machine-independent, so that building the distribution +normally will never modify them. We commonly include non-source files +produced by Bison, 'lex', TeX, and 'makeinfo'; this helps avoid +unnecessary dependencies between our distributions, so that users can +install whichever packages they want to install. + + Non-source files that might actually be modified by building and +installing the program should *never* be included in the distribution. +So if you do distribute non-source files, always make sure they are up +to date when you make a new distribution. + + Make sure that the directory into which the distribution unpacks (as +well as any subdirectories) are all world-writable (octal mode 777). +This is so that old versions of 'tar' which preserve the ownership and +permissions of the files from the tar archive will be able to extract +all the files even if the user is unprivileged. + + Make sure that all the files in the distribution are world-readable. + + Make sure that no file name in the distribution is more than 14 +characters long. Likewise, no file created by building the program +should have a name longer than 14 characters. The reason for this is +that some systems adhere to a foolish interpretation of the POSIX +standard, and refuse to open a longer name, rather than truncating as +they did in the past. + + Don't include any symbolic links in the distribution itself. If the +tar file contains symbolic links, then people cannot even unpack it on +systems that don't support symbolic links. Also, don't use multiple +names for one file in different directories, because certain file +systems cannot handle this and that prevents unpacking the distribution. + + Try to make sure that all the file names will be unique on MS-DOS. A +name on MS-DOS consists of up to 8 characters, optionally followed by a +period and up to three characters. MS-DOS will truncate extra +characters both before and after the period. Thus, 'foobarhacker.c' and +'foobarhacker.o' are not ambiguous; they are truncated to 'foobarha.c' +and 'foobarha.o', which are distinct. + + Include in your distribution a copy of the 'texinfo.tex' you used to +test print any '*.texinfo' or '*.texi' files. + + Likewise, if your program uses small GNU software packages like +regex, getopt, obstack, or termcap, include them in the distribution +file. Leaving them out would make the distribution file a little +smaller at the expense of possible inconvenience to a user who doesn't +know what other files to get. + + +File: standards.info, Node: References, Next: Index, Prev: Managing Releases, Up: Top + +8 References to Non-Free Software and Documentation +*************************************************** + +A GNU program should not recommend use of any non-free program. We +can't stop some people from writing proprietary programs, or stop other +people from using them. But we can and should avoid helping to +advertise them to new customers. + + Sometimes it is important to mention how to build your package on top +of some non-free operating system or other non-free base package. In +such cases, please mention the name of the non-free package or system in +the briefest possible way. Don't include any references for where to +find more information about the proprietary program. The goal should be +that people already using the proprietary program will get the advice +they need about how to use your free program, while people who don't +already use the proprietary program will not see anything to encourage +them to take an interest in it. + + Likewise, a GNU package should not refer the user to any non-free +documentation for free software. The need for free documentation to go +with free software is now a major focus of the GNU project; to show that +we are serious about the need for free documentation, we must not +undermine our position by recommending use of documentation that isn't +free. + + +File: standards.info, Node: Index, Prev: References, Up: Top + +Index +***** + + +* Menu: + +* #endif, commenting: Comments. (line 54) +* --help option: Command-Line Interfaces. + (line 107) +* --version option: Command-Line Interfaces. + (line 34) +* -Wall compiler option: Syntactic Conventions. + (line 10) +* accepting contributions: Contributions. (line 6) +* address for bug reports: Command-Line Interfaces. + (line 113) +* ANSI C standard: Standard C. (line 6) +* arbitrary limits on data: Semantics. (line 6) +* autoconf: System Portability. (line 23) +* avoiding proprietary code: Reading Non-Free Code. + (line 6) +* behavior, dependent on program's name: User Interfaces. (line 6) +* binary packages: Install Command Categories. + (line 80) +* bindir: Directory Variables. (line 45) +* braces, in C source: Formatting. (line 6) +* bug reports: Command-Line Interfaces. + (line 113) +* canonical name of a program: Command-Line Interfaces. + (line 41) +* casting pointers to integers: CPU Portability. (line 66) +* change logs: Change Logs. (line 6) +* change logs, conditional changes: Conditional Changes. (line 6) +* change logs, style: Style of Change Logs. + (line 6) +* command-line arguments, decoding: Semantics. (line 46) +* command-line interface: Command-Line Interfaces. + (line 6) +* commenting: Comments. (line 6) +* compatibility with C and POSIX standards: Compatibility. (line 6) +* compiler warnings: Syntactic Conventions. + (line 10) +* conditional changes, and change logs: Conditional Changes. (line 6) +* conditionals, comments for: Comments. (line 54) +* configure: Configuration. (line 6) +* control-L: Formatting. (line 114) +* conventions for makefiles: Makefile Conventions. + (line 6) +* corba: Graphical Interfaces. + (line 16) +* credits for manuals: Manual Credits. (line 6) +* data types, and portability: CPU Portability. (line 6) +* declaration for system functions: System Functions. (line 21) +* documentation: Documentation. (line 6) +* doschk: Names. (line 38) +* downloading this manual: Preface. (line 17) +* error messages: Semantics. (line 19) +* error messages, formatting: Errors. (line 6) +* exec_prefix: Directory Variables. (line 27) +* expressions, splitting: Formatting. (line 77) +* file usage: File Usage. (line 6) +* file-name limitations: Names. (line 38) +* formatting error messages: Errors. (line 6) +* formatting source code: Formatting. (line 6) +* formfeed: Formatting. (line 114) +* function argument, declaring: Syntactic Conventions. + (line 6) +* function prototypes: Standard C. (line 17) +* getopt: Command-Line Interfaces. + (line 6) +* gettext: Internationalization. + (line 6) +* gnome: Graphical Interfaces. + (line 16) +* graphical user interface: Graphical Interfaces. + (line 6) +* gtk: Graphical Interfaces. + (line 6) +* GUILE: Source Language. (line 37) +* implicit int: Syntactic Conventions. + (line 6) +* impossible conditions: Semantics. (line 70) +* internationalization: Internationalization. + (line 6) +* legal aspects: Legal Issues. (line 6) +* legal papers: Contributions. (line 6) +* libexecdir: Directory Variables. (line 58) +* libraries: Libraries. (line 6) +* library functions, and portability: System Functions. (line 6) +* license for manuals: License for Manuals. (line 6) +* lint: Syntactic Conventions. + (line 109) +* long option names: Option Table. (line 6) +* long-named options: Command-Line Interfaces. + (line 12) +* makefile, conventions for: Makefile Conventions. + (line 6) +* malloc return value: Semantics. (line 25) +* man pages: Man Pages. (line 6) +* manual structure: Manual Structure Details. + (line 6) +* memory allocation failure: Semantics. (line 25) +* memory usage: Memory Usage. (line 6) +* message text, and internationalization: Internationalization. + (line 29) +* mmap: Mmap. (line 6) +* multiple variables in a line: Syntactic Conventions. + (line 35) +* names of variables and functions: Names. (line 6) +* NEWS file: NEWS File. (line 6) +* non-POSIX systems, and portability: System Portability. (line 32) +* non-standard extensions: Using Extensions. (line 6) +* NUL characters: Semantics. (line 11) +* open brace: Formatting. (line 6) +* optional features, configure-time: Configuration. (line 76) +* options for compatibility: Compatibility. (line 14) +* output device and program's behavior: User Interfaces. (line 13) +* packaging: Releases. (line 6) +* portability, and data types: CPU Portability. (line 6) +* portability, and library functions: System Functions. (line 6) +* portability, between system types: System Portability. (line 6) +* POSIX compatibility: Compatibility. (line 6) +* POSIXLY_CORRECT, environment variable: Compatibility. (line 21) +* post-installation commands: Install Command Categories. + (line 6) +* pre-installation commands: Install Command Categories. + (line 6) +* prefix: Directory Variables. (line 17) +* program configuration: Configuration. (line 6) +* program design: Design Advice. (line 6) +* program name and its behavior: User Interfaces. (line 6) +* program's canonical name: Command-Line Interfaces. + (line 41) +* programming languages: Source Language. (line 6) +* proprietary programs: Reading Non-Free Code. + (line 6) +* README file: Releases. (line 17) +* references to non-free material: References. (line 6) +* releasing: Managing Releases. (line 6) +* sbindir: Directory Variables. (line 51) +* signal handling: Semantics. (line 59) +* spaces before open-paren: Formatting. (line 71) +* standard command-line options: Command-Line Interfaces. + (line 31) +* standards for makefiles: Makefile Conventions. + (line 6) +* string library functions: System Functions. (line 54) +* syntactic conventions: Syntactic Conventions. + (line 6) +* table of long options: Option Table. (line 6) +* temporary files: Semantics. (line 84) +* temporary variables: Syntactic Conventions. + (line 23) +* texinfo.tex, in a distribution: Releases. (line 73) +* TMPDIR environment variable: Semantics. (line 84) +* trademarks: Trademarks. (line 6) +* where to obtain standards.texi: Preface. (line 17) + + + +Tag Table: +Node: Top978 +Node: Preface1577 +Node: Legal Issues3167 +Node: Reading Non-Free Code3631 +Node: Contributions5358 +Node: Trademarks7512 +Node: Design Advice8575 +Node: Source Language9082 +Node: Compatibility11087 +Node: Using Extensions12715 +Node: Standard C14292 +Node: Program Behavior16663 +Node: Semantics17582 +Node: Libraries22275 +Node: Errors23520 +Node: User Interfaces25301 +Node: Graphical Interfaces26906 +Node: Command-Line Interfaces27941 +Node: Option Table33430 +Node: Memory Usage48439 +Node: File Usage49464 +Node: Writing C50212 +Node: Formatting51052 +Node: Comments55116 +Node: Syntactic Conventions58417 +Node: Names61829 +Node: System Portability64022 +Node: CPU Portability66407 +Node: System Functions69665 +Node: Internationalization74857 +Node: Mmap78010 +Node: Documentation78720 +Node: GNU Manuals79825 +Node: Doc Strings and Manuals84882 +Node: Manual Structure Details86435 +Node: License for Manuals87853 +Node: Manual Credits88826 +Node: Printed Manuals89219 +Node: NEWS File89905 +Node: Change Logs90583 +Node: Change Log Concepts91377 +Node: Style of Change Logs93240 +Node: Simple Changes95275 +Node: Conditional Changes96519 +Node: Indicating the Part Changed97941 +Node: Man Pages98468 +Node: Reading other Manuals100092 +Node: Managing Releases100883 +Node: Configuration101638 +Node: Makefile Conventions108542 +Node: Makefile Basics109306 +Node: Utilities in Makefiles112480 +Node: Command Variables114626 +Node: Directory Variables118203 +Node: Standard Targets129094 +Ref: Standard Targets-Footnote-1140335 +Node: Install Command Categories140436 +Node: Releases145018 +Node: References149105 +Node: Index150501 + +End Tag Table diff --git a/doc/standards.texi b/doc/standards.texi new file mode 100644 index 0000000..be5bfb5 --- /dev/null +++ b/doc/standards.texi @@ -0,0 +1,3656 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename standards.info +@settitle GNU Coding Standards +@c This date is automagically updated when you save this file: +@set lastupdate March 23, 2001 +@c %**end of header + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Standards: (standards). GNU coding standards. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@c @setchapternewpage odd +@setchapternewpage off + +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex vr cp + +@c This is used by a cross ref in make-stds.texi +@set CODESTD 1 +@iftex +@set CHAPTER chapter +@end iftex +@ifinfo +@set CHAPTER node +@end ifinfo + +@ifinfo +GNU Coding Standards +Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end ifinfo + +@titlepage +@title GNU Coding Standards +@author Richard Stallman +@author last updated @value{lastupdate} +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, Preface, (dir), (dir) +@top Version + +Last updated @value{lastupdate}. +@end ifinfo + +@menu +* Preface:: About the GNU Coding Standards +* Legal Issues:: Keeping Free Software Free +* Design Advice:: General Program Design +* Program Behavior:: Program Behavior for All Programs +* Writing C:: Making The Best Use of C +* Documentation:: Documenting Programs +* Managing Releases:: The Release Process +* References:: References to Non-Free Software or Documentation +* Index:: +@end menu + +@node Preface +@chapter About the GNU Coding Standards + +The GNU Coding Standards were written by Richard Stallman and other GNU +Project volunteers. Their purpose is to make the GNU system clean, +consistent, and easy to install. This document can also be read as a +guide to writing portable, robust and reliable programs. It focuses on +programs written in C, but many of the rules and principles are useful +even if you write in another programming language. The rules often +state reasons for writing in a certain way. + +This release of the GNU Coding Standards was last updated +@value{lastupdate}. + +@cindex where to obtain @code{standards.texi} +@cindex downloading this manual +If you did not obtain this file directly from the GNU project and +recently, please check for a newer version. You can ftp the GNU +Coding Standards from any GNU FTP host in the directory +@file{/pub/gnu/standards/}. The GNU Coding Standards are available +there in several different formats: @file{standards.text}, +@file{standards.info}, and @file{standards.dvi}, as well as the +Texinfo ``source'' which is divided in two files: +@file{standards.texi} and @file{make-stds.texi}. The GNU Coding +Standards are also available on the GNU World Wide Web server: +@uref{http://www.gnu.org/prep/standards_toc.html}. + +Corrections or suggestions for this document should be sent to +@email{bug-standards@@gnu.org}. If you make a suggestion, please include a +suggested new wording for it; our time is limited. We prefer a context +diff to the @file{standards.texi} or @file{make-stds.texi} files, but if +you don't have those files, please mail your suggestion anyway. + +@node Legal Issues +@chapter Keeping Free Software Free +@cindex legal aspects + +This @value{CHAPTER} discusses how you can make sure that GNU software +avoids legal difficulties, and other related issues. + +@menu +* Reading Non-Free Code:: Referring to Proprietary Programs +* Contributions:: Accepting Contributions +* Trademarks:: How We Deal with Trademark Issues +@end menu + +@node Reading Non-Free Code +@section Referring to Proprietary Programs +@cindex proprietary programs +@cindex avoiding proprietary code + +Don't in any circumstances refer to Unix source code for or during +your work on GNU! (Or to any other proprietary programs.) + +If you have a vague recollection of the internals of a Unix program, +this does not absolutely mean you can't write an imitation of it, but +do try to organize the imitation internally along different lines, +because this is likely to make the details of the Unix version +irrelevant and dissimilar to your results. + +For example, Unix utilities were generally optimized to minimize +memory use; if you go for speed instead, your program will be very +different. You could keep the entire input file in core and scan it +there instead of using stdio. Use a smarter algorithm discovered more +recently than the Unix program. Eliminate use of temporary files. Do +it in one pass instead of two (we did this in the assembler). + +Or, on the contrary, emphasize simplicity instead of speed. For some +applications, the speed of today's computers makes simpler algorithms +adequate. + +Or go for generality. For example, Unix programs often have static +tables or fixed-size strings, which make for arbitrary limits; use +dynamic allocation instead. Make sure your program handles NULs and +other funny characters in the input files. Add a programming language +for extensibility and write part of the program in that language. + +Or turn some parts of the program into independently usable libraries. +Or use a simple garbage collector instead of tracking precisely when +to free memory, or use a new GNU facility such as obstacks. + +@node Contributions +@section Accepting Contributions +@cindex legal papers +@cindex accepting contributions + +If the program you are working on is copyrighted by the Free Software +Foundation, then when someone else sends you a piece of code to add to +the program, we need legal papers to use it---just as we asked you to +sign papers initially. @emph{Each} person who makes a nontrivial +contribution to a program must sign some sort of legal papers in order +for us to have clear title to the program; the main author alone is not +enough. + +So, before adding in any contributions from other people, please tell +us, so we can arrange to get the papers. Then wait until we tell you +that we have received the signed papers, before you actually use the +contribution. + +This applies both before you release the program and afterward. If +you receive diffs to fix a bug, and they make significant changes, we +need legal papers for that change. + +This also applies to comments and documentation files. For copyright +law, comments and code are just text. Copyright applies to all kinds of +text, so we need legal papers for all kinds. + +We know it is frustrating to ask for legal papers; it's frustrating for +us as well. But if you don't wait, you are going out on a limb---for +example, what if the contributor's employer won't sign a disclaimer? +You might have to take that code out again! + +You don't need papers for changes of a few lines here or there, since +they are not significant for copyright purposes. Also, you don't need +papers if all you get from the suggestion is some ideas, not actual code +which you use. For example, if someone send you one implementation, but +you write a different implementation of the same idea, you don't need to +get papers. + +The very worst thing is if you forget to tell us about the other +contributor. We could be very embarrassed in court some day as a +result. + +We have more detailed advice for maintainers of programs; if you have +reached the stage of actually maintaining a program for GNU (whether +released or not), please ask us for a copy. + +@node Trademarks +@section Trademarks +@cindex trademarks + +Please do not include any trademark acknowledgements in GNU software +packages or documentation. + +Trademark acknowledgements are the statements that such-and-such is a +trademark of so-and-so. The GNU Project has no objection to the basic +idea of trademarks, but these acknowledgements feel like kowtowing, so +we don't use them. There is no legal requirement for them. + +What is legally required, as regards other people's trademarks, is to +avoid using them in ways which a reader might read as naming or labeling +our own programs or activities. For example, since ``Objective C'' is +(or at least was) a trademark, we made sure to say that we provide a +``compiler for the Objective C language'' rather than an ``Objective C +compiler''. The latter is meant to be short for the former, but it does +not explicitly state the relationship, so it could be misinterpreted as +using ``Objective C'' as a label for the compiler rather than for the +language. + +@node Design Advice +@chapter General Program Design +@cindex program design + +This @value{CHAPTER} discusses some of the issues you should take into +account when designing your program. + +@c Standard or ANSI C +@c +@c In 1989 the American National Standards Institute (ANSI) standardized +@c C as standard X3.159-1989. In December of that year the +@c International Standards Organization ISO adopted the ANSI C standard +@c making minor changes. In 1990 ANSI then re-adopted ISO standard +@c C. This version of C is known as either ANSI C or Standard C. + +@c A major revision of the C Standard appeared in 1999. + +@menu +* Source Language:: Which languages to use. +* Compatibility:: Compatibility with other implementations +* Using Extensions:: Using non-standard features +* Standard C:: Using Standard C features +@end menu + +@node Source Language +@section Which Languages to Use +@cindex programming languages + +When you want to use a language that gets compiled and runs at high +speed, the best language to use is C. Using another language is like +using a non-standard feature: it will cause trouble for users. Even if +GCC supports the other language, users may find it inconvenient to have +to install the compiler for that other language in order to build your +program. For example, if you write your program in C++, people will +have to install the GNU C++ compiler in order to compile your program. + +C has one other advantage over C++ and other compiled languages: more +people know C, so more people will find it easy to read and modify the +program if it is written in C. + +So in general it is much better to use C, rather than the +comparable alternatives. + +But there are two exceptions to that conclusion: + +@itemize @bullet +@item +It is no problem to use another language to write a tool specifically +intended for use with that language. That is because the only people +who want to build the tool will be those who have installed the other +language anyway. + +@item +If an application is of interest only to a narrow part of the community, +then the question of which language it is written in has less effect on +other people, so you may as well please yourself. +@end itemize + +Many programs are designed to be extensible: they include an interpreter +for a language that is higher level than C. Often much of the program +is written in that language, too. The Emacs editor pioneered this +technique. + +@cindex GUILE +The standard extensibility interpreter for GNU software is GUILE, which +implements the language Scheme (an especially clean and simple dialect +of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject +programs written in other ``scripting languages'' such as Perl and +Python, but using GUILE is very important for the overall consistency of +the GNU system. + +@node Compatibility +@section Compatibility with Other Implementations +@cindex compatibility with C and @sc{posix} standards +@cindex @sc{posix} compatibility + +With occasional exceptions, utility programs and libraries for GNU +should be upward compatible with those in Berkeley Unix, and upward +compatible with Standard C if Standard C specifies their +behavior, and upward compatible with @sc{posix} if @sc{posix} specifies +their behavior. + +When these standards conflict, it is useful to offer compatibility +modes for each of them. + +@cindex options for compatibility +Standard C and @sc{posix} prohibit many kinds of extensions. Feel +free to make the extensions anyway, and include a @samp{--ansi}, +@samp{--posix}, or @samp{--compatible} option to turn them off. +However, if the extension has a significant chance of breaking any real +programs or scripts, then it is not really upward compatible. So you +should try to redesign its interface to make it upward compatible. + +@cindex @code{POSIXLY_CORRECT}, environment variable +Many GNU programs suppress extensions that conflict with @sc{posix} if the +environment variable @code{POSIXLY_CORRECT} is defined (even if it is +defined with a null value). Please make your program recognize this +variable if appropriate. + +When a feature is used only by users (not by programs or command +files), and it is done poorly in Unix, feel free to replace it +completely with something totally different and better. (For example, +@code{vi} is replaced with Emacs.) But it is nice to offer a compatible +feature as well. (There is a free @code{vi} clone, so we offer it.) + +Additional useful features are welcome regardless of whether +there is any precedent for them. + +@node Using Extensions +@section Using Non-standard Features +@cindex non-standard extensions + +Many GNU facilities that already exist support a number of convenient +extensions over the comparable Unix facilities. Whether to use these +extensions in implementing your program is a difficult question. + +On the one hand, using the extensions can make a cleaner program. +On the other hand, people will not be able to build the program +unless the other GNU tools are available. This might cause the +program to work on fewer kinds of machines. + +With some extensions, it might be easy to provide both alternatives. +For example, you can define functions with a ``keyword'' @code{INLINE} +and define that as a macro to expand into either @code{inline} or +nothing, depending on the compiler. + +In general, perhaps it is best not to use the extensions if you can +straightforwardly do without them, but to use the extensions if they +are a big improvement. + +An exception to this rule are the large, established programs (such as +Emacs) which run on a great variety of systems. Using GNU extensions in +such programs would make many users unhappy, so we don't do that. + +Another exception is for programs that are used as part of compilation: +anything that must be compiled with other compilers in order to +bootstrap the GNU compilation facilities. If these require the GNU +compiler, then no one can compile them without having them installed +already. That would be extremely troublesome in certain cases. + +@node Standard C +@section Standard C and Pre-Standard C +@cindex @sc{ansi} C standard + +1989 Standard C is widespread enough now that it is ok to use its +features in new programs. There is one exception: do not ever use the +``trigraph'' feature of Standard C. + +1999 Standard C is not widespread yet, so please do not require its +features in programs. It is ok to use its features if they are present. + +However, it is easy to support pre-standard compilers in most programs, +so if you know how to do that, feel free. If a program you are +maintaining has such support, you should try to keep it working. + +@cindex function prototypes +To support pre-standard C, instead of writing function definitions in +standard prototype form, + +@example +int +foo (int x, int y) +@dots{} +@end example + +@noindent +write the definition in pre-standard style like this, + +@example +int +foo (x, y) + int x, y; +@dots{} +@end example + +@noindent +and use a separate declaration to specify the argument prototype: + +@example +int foo (int, int); +@end example + +You need such a declaration anyway, in a header file, to get the benefit +of prototypes in all the files where the function is called. And once +you have the declaration, you normally lose nothing by writing the +function definition in the pre-standard style. + +This technique does not work for integer types narrower than @code{int}. +If you think of an argument as being of a type narrower than @code{int}, +declare it as @code{int} instead. + +There are a few special cases where this technique is hard to use. For +example, if a function argument needs to hold the system type +@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than +@code{int} on some machines; but you cannot use @code{int} instead, +because @code{dev_t} is wider than @code{int} on some machines. There +is no type you can safely use on all machines in a non-standard +definition. The only way to support non-standard C and pass such an +argument is to check the width of @code{dev_t} using Autoconf and choose +the argument type accordingly. This may not be worth the trouble. + +In order to support pre-standard compilers that do not recognize +prototypes, you may want to use a preprocessor macro like this: + +@example +/* Declare the prototype for a general external function. */ +#if defined (__STDC__) || defined (WINDOWSNT) +#define P_(proto) proto +#else +#define P_(proto) () +#endif +@end example + +@node Program Behavior +@chapter Program Behavior for All Programs + +This @value{CHAPTER} describes conventions for writing robust +software. It also describes general standards for error messages, the +command line interface, and how libraries should behave. + +@menu +* Semantics:: Writing robust programs +* Libraries:: Library behavior +* Errors:: Formatting error messages +* User Interfaces:: Standards about interfaces generally +* Graphical Interfaces:: Standards for graphical interfaces +* Command-Line Interfaces:: Standards for command line interfaces +* Option Table:: Table of long options +* Memory Usage:: When and how to care about memory needs +* File Usage:: Which files to use, and where +@end menu + +@node Semantics +@section Writing Robust Programs + +@cindex arbitrary limits on data +Avoid arbitrary limits on the length or number of @emph{any} data +structure, including file names, lines, files, and symbols, by allocating +all data structures dynamically. In most Unix utilities, ``long lines +are silently truncated''. This is not acceptable in a GNU utility. + +@cindex @code{NUL} characters +Utilities reading files should not drop NUL characters, or any other +nonprinting characters @emph{including those with codes above 0177}. +The only sensible exceptions would be utilities specifically intended +for interface to certain types of terminals or printers +that can't handle those characters. +Whenever possible, try to make programs work properly with +sequences of bytes that represent multibyte characters, using encodings +such as UTF-8 and others. + +@cindex error messages +Check every system call for an error return, unless you know you wish to +ignore errors. Include the system error text (from @code{perror} or +equivalent) in @emph{every} error message resulting from a failing +system call, as well as the name of the file if any and the name of the +utility. Just ``cannot open foo.c'' or ``stat failed'' is not +sufficient. + +@cindex @code{malloc} return value +@cindex memory allocation failure +Check every call to @code{malloc} or @code{realloc} to see if it +returned zero. Check @code{realloc} even if you are making the block +smaller; in a system that rounds block sizes to a power of 2, +@code{realloc} may get a different block if you ask for less space. + +In Unix, @code{realloc} can destroy the storage block if it returns +zero. GNU @code{realloc} does not have this bug: if it fails, the +original block is unchanged. Feel free to assume the bug is fixed. If +you wish to run your program on Unix, and wish to avoid lossage in this +case, you can use the GNU @code{malloc}. + +You must expect @code{free} to alter the contents of the block that was +freed. Anything you want to fetch from the block, you must fetch before +calling @code{free}. + +If @code{malloc} fails in a noninteractive program, make that a fatal +error. In an interactive program (one that reads commands from the +user), it is better to abort the command and return to the command +reader loop. This allows the user to kill other processes to free up +virtual memory, and then try the command again. + +@cindex command-line arguments, decoding +Use @code{getopt_long} to decode arguments, unless the argument syntax +makes this unreasonable. + +When static storage is to be written in during program execution, use +explicit C code to initialize it. Reserve C initialized declarations +for data that will not be changed. +@c ADR: why? + +Try to avoid low-level interfaces to obscure Unix data structures (such +as file directories, utmp, or the layout of kernel memory), since these +are less likely to work compatibly. If you need to find all the files +in a directory, use @code{readdir} or some other high-level interface. +These are supported compatibly by GNU. + +@cindex signal handling +The preferred signal handling facilities are the BSD variant of +@code{signal}, and the @sc{posix} @code{sigaction} function; the +alternative USG @code{signal} interface is an inferior design. + +Nowadays, using the @sc{posix} signal functions may be the easiest way +to make a program portable. If you use @code{signal}, then on GNU/Linux +systems running GNU libc version 1, you should include +@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD +behavior. It is up to you whether to support systems where +@code{signal} has only the USG behavior, or give up on them. + +@cindex impossible conditions +In error checks that detect ``impossible'' conditions, just abort. +There is usually no point in printing any message. These checks +indicate the existence of bugs. Whoever wants to fix the bugs will have +to read the source code and run a debugger. So explain the problem with +comments in the source. The relevant data will be in variables, which +are easy to examine with the debugger, so there is no point moving them +elsewhere. + +Do not use a count of errors as the exit status for a program. +@emph{That does not work}, because exit status values are limited to 8 +bits (0 through 255). A single run of the program might have 256 +errors; if you try to return 256 as the exit status, the parent process +will see 0 as the status, and it will appear that the program succeeded. + +@cindex temporary files +@cindex @code{TMPDIR} environment variable +If you make temporary files, check the @code{TMPDIR} environment +variable; if that variable is defined, use the specified directory +instead of @file{/tmp}. + +In addition, be aware that there is a possible security problem when +creating temporary files in world-writable directories. In C, you can +avoid this problem by creating temporary files in this manner: + +@example +fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600); +@end example + +@noindent +or by using the @code{mkstemps} function from libiberty. + +In bash, use @code{set -C} to avoid this problem. + +@node Libraries +@section Library Behavior +@cindex libraries + +Try to make library functions reentrant. If they need to do dynamic +storage allocation, at least try to avoid any nonreentrancy aside from +that of @code{malloc} itself. + +Here are certain name conventions for libraries, to avoid name +conflicts. + +Choose a name prefix for the library, more than two characters long. +All external function and variable names should start with this +prefix. In addition, there should only be one of these in any given +library member. This usually means putting each one in a separate +source file. + +An exception can be made when two external symbols are always used +together, so that no reasonable program could use one without the +other; then they can both go in the same file. + +External symbols that are not documented entry points for the user +should have names beginning with @samp{_}. The @samp{_} should be +followed by the chosen name prefix for the library, to prevent +collisions with other libraries. These can go in the same files with +user entry points if you like. + +Static functions and variables can be used as you like and need not +fit any naming convention. + +@node Errors +@section Formatting Error Messages +@cindex formatting error messages +@cindex error messages, formatting + +Error messages from compilers should look like this: + +@example +@var{source-file-name}:@var{lineno}: @var{message} +@end example + +@noindent +If you want to mention the column number, use this format: + +@example +@var{source-file-name}:@var{lineno}:@var{column}: @var{message} +@end example + +@noindent +Line numbers should start from 1 at the beginning of the file, and +column numbers should start from 1 at the beginning of the line. (Both +of these conventions are chosen for compatibility.) Calculate column +numbers assuming that space and all ASCII printing characters have +equal width, and assuming tab stops every 8 columns. + +Error messages from other noninteractive programs should look like this: + +@example +@var{program}:@var{source-file-name}:@var{lineno}: @var{message} +@end example + +@noindent +when there is an appropriate source file, or like this: + +@example +@var{program}: @var{message} +@end example + +@noindent +when there is no relevant source file. + +If you want to mention the column number, use this format: + +@example +@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message} +@end example + +In an interactive program (one that is reading commands from a +terminal), it is better not to include the program name in an error +message. The place to indicate which program is running is in the +prompt or with the screen layout. (When the same program runs with +input from a source other than a terminal, it is not interactive and +would do best to print error messages using the noninteractive style.) + +The string @var{message} should not begin with a capital letter when +it follows a program name and/or file name. Also, it should not end +with a period. + +Error messages from interactive programs, and other messages such as +usage messages, should start with a capital letter. But they should not +end with a period. + +@node User Interfaces +@section Standards for Interfaces Generally + +@cindex program name and its behavior +@cindex behavior, dependent on program's name +Please don't make the behavior of a utility depend on the name used +to invoke it. It is useful sometimes to make a link to a utility +with a different name, and that should not change what it does. + +Instead, use a run time option or a compilation switch or both +to select among the alternate behaviors. + +@cindex output device and program's behavior +Likewise, please don't make the behavior of the program depend on the +type of output device it is used with. Device independence is an +important principle of the system's design; do not compromise it merely +to save someone from typing an option now and then. (Variation in error +message syntax when using a terminal is ok, because that is a side issue +that people do not depend on.) + +If you think one behavior is most useful when the output is to a +terminal, and another is most useful when the output is a file or a +pipe, then it is usually best to make the default behavior the one that +is useful with output to a terminal, and have an option for the other +behavior. + +Compatibility requires certain programs to depend on the type of output +device. It would be disastrous if @code{ls} or @code{sh} did not do so +in the way all users expect. In some of these cases, we supplement the +program with a preferred alternate version that does not depend on the +output device type. For example, we provide a @code{dir} program much +like @code{ls} except that its default output format is always +multi-column format. + +@node Graphical Interfaces +@section Standards for Graphical Interfaces +@cindex graphical user interface + +@cindex gtk +When you write a program that provides a graphical user interface, +please make it work with X Windows and the GTK toolkit unless the +functionality specifically requires some alternative (for example, +``displaying jpeg images while in console mode''). + +In addition, please provide a command-line interface to control the +functionality. (In many cases, the graphical user interface can be a +separate program which invokes the command-line program.) This is +so that the same jobs can be done from scripts. + +@cindex corba +@cindex gnome +Please also consider providing a CORBA interface (for use from GNOME), a +library interface (for use from C), and perhaps a keyboard-driven +console interface (for use by users from console mode). Once you are +doing the work to provide the functionality and the graphical interface, +these won't be much extra work. + +@node Command-Line Interfaces +@section Standards for Command Line Interfaces +@cindex command-line interface + +@findex getopt +It is a good idea to follow the @sc{posix} guidelines for the +command-line options of a program. The easiest way to do this is to use +@code{getopt} to parse them. Note that the GNU version of @code{getopt} +will normally permit options anywhere among the arguments unless the +special argument @samp{--} is used. This is not what @sc{posix} +specifies; it is a GNU extension. + +@cindex long-named options +Please define long-named options that are equivalent to the +single-letter Unix-style options. We hope to make GNU more user +friendly this way. This is easy to do with the GNU function +@code{getopt_long}. + +One of the advantages of long-named options is that they can be +consistent from program to program. For example, users should be able +to expect the ``verbose'' option of any GNU program which has one, to be +spelled precisely @samp{--verbose}. To achieve this uniformity, look at +the table of common long-option names when you choose the option names +for your program (@pxref{Option Table}). + +It is usually a good idea for file names given as ordinary arguments to +be input files only; any output files would be specified using options +(preferably @samp{-o} or @samp{--output}). Even if you allow an output +file name as an ordinary argument for compatibility, try to provide an +option as another way to specify it. This will lead to more consistency +among GNU utilities, and fewer idiosyncrasies for users to remember. + +@cindex standard command-line options +All programs should support two standard options: @samp{--version} +and @samp{--help}. + +@table @code +@cindex @samp{--version} option +@item --version +This option should direct the program to print information about its name, +version, origin and legal status, all on standard output, and then exit +successfully. Other options and arguments should be ignored once this +is seen, and the program should not perform its normal function. + +@cindex canonical name of a program +@cindex program's canonical name +The first line is meant to be easy for a program to parse; the version +number proper starts after the last space. In addition, it contains +the canonical name for this program, in this format: + +@example +GNU Emacs 19.30 +@end example + +@noindent +The program's name should be a constant string; @emph{don't} compute it +from @code{argv[0]}. The idea is to state the standard or canonical +name for the program, not its file name. There are other ways to find +out the precise file name where a command is found in @code{PATH}. + +If the program is a subsidiary part of a larger package, mention the +package name in parentheses, like this: + +@example +emacsserver (GNU Emacs) 19.30 +@end example + +@noindent +If the package has a version number which is different from this +program's version number, you can mention the package version number +just before the close-parenthesis. + +If you @strong{need} to mention the version numbers of libraries which +are distributed separately from the package which contains this program, +you can do so by printing an additional line of version info for each +library you want to mention. Use the same format for these lines as for +the first line. + +Please do not mention all of the libraries that the program uses ``just +for completeness''---that would produce a lot of unhelpful clutter. +Please mention library version numbers only if you find in practice that +they are very important to you in debugging. + +The following line, after the version number line or lines, should be a +copyright notice. If more than one copyright notice is called for, put +each on a separate line. + +Next should follow a brief statement that the program is free software, +and that users are free to copy and change it on certain conditions. If +the program is covered by the GNU GPL, say so here. Also mention that +there is no warranty, to the extent permitted by law. + +It is ok to finish the output with a list of the major authors of the +program, as a way of giving credit. + +Here's an example of output that follows these rules: + +@smallexample +GNU Emacs 19.34.5 +Copyright (C) 1996 Free Software Foundation, Inc. +GNU Emacs comes with NO WARRANTY, +to the extent permitted by law. +You may redistribute copies of GNU Emacs +under the terms of the GNU General Public License. +For more information about these matters, +see the files named COPYING. +@end smallexample + +You should adapt this to your program, of course, filling in the proper +year, copyright holder, name of program, and the references to +distribution terms, and changing the rest of the wording as necessary. + +This copyright notice only needs to mention the most recent year in +which changes were made---there's no need to list the years for previous +versions' changes. You don't have to mention the name of the program in +these notices, if that is inconvenient, since it appeared in the first +line. + +@cindex @samp{--help} option +@item --help +This option should output brief documentation for how to invoke the +program, on standard output, then exit successfully. Other options and +arguments should be ignored once this is seen, and the program should +not perform its normal function. + +@cindex address for bug reports +@cindex bug reports +Near the end of the @samp{--help} option's output there should be a line +that says where to mail bug reports. It should have this format: + +@example +Report bugs to @var{mailing-address}. +@end example +@end table + +@node Option Table +@section Table of Long Options +@cindex long option names +@cindex table of long options + +Here is a table of long options used by GNU programs. It is surely +incomplete, but we aim to list all the options that a new program might +want to be compatible with. If you use names not already in the table, +please send @email{bug-standards@@gnu.org} a list of them, with their +meanings, so we can update the table. + +@c Please leave newlines between items in this table; it's much easier +@c to update when it isn't completely squashed together and unreadable. +@c When there is more than one short option for a long option name, put +@c a semicolon between the lists of the programs that use them, not a +@c period. --friedman + +@table @samp +@item after-date +@samp{-N} in @code{tar}. + +@item all +@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, +and @code{unexpand}. + +@item all-text +@samp{-a} in @code{diff}. + +@item almost-all +@samp{-A} in @code{ls}. + +@item append +@samp{-a} in @code{etags}, @code{tee}, @code{time}; +@samp{-r} in @code{tar}. + +@item archive +@samp{-a} in @code{cp}. + +@item archive-name +@samp{-n} in @code{shar}. + +@item arglength +@samp{-l} in @code{m4}. + +@item ascii +@samp{-a} in @code{diff}. + +@item assign +@samp{-v} in @code{gawk}. + +@item assume-new +@samp{-W} in Make. + +@item assume-old +@samp{-o} in Make. + +@item auto-check +@samp{-a} in @code{recode}. + +@item auto-pager +@samp{-a} in @code{wdiff}. + +@item auto-reference +@samp{-A} in @code{ptx}. + +@item avoid-wraps +@samp{-n} in @code{wdiff}. + +@item background +For server programs, run in the background. + +@item backward-search +@samp{-B} in @code{ctags}. + +@item basename +@samp{-f} in @code{shar}. + +@item batch +Used in GDB. + +@item baud +Used in GDB. + +@item before +@samp{-b} in @code{tac}. + +@item binary +@samp{-b} in @code{cpio} and @code{diff}. + +@item bits-per-code +@samp{-b} in @code{shar}. + +@item block-size +Used in @code{cpio} and @code{tar}. + +@item blocks +@samp{-b} in @code{head} and @code{tail}. + +@item break-file +@samp{-b} in @code{ptx}. + +@item brief +Used in various programs to make output shorter. + +@item bytes +@samp{-c} in @code{head}, @code{split}, and @code{tail}. + +@item c@t{++} +@samp{-C} in @code{etags}. + +@item catenate +@samp{-A} in @code{tar}. + +@item cd +Used in various programs to specify the directory to use. + +@item changes +@samp{-c} in @code{chgrp} and @code{chown}. + +@item classify +@samp{-F} in @code{ls}. + +@item colons +@samp{-c} in @code{recode}. + +@item command +@samp{-c} in @code{su}; +@samp{-x} in GDB. + +@item compare +@samp{-d} in @code{tar}. + +@item compat +Used in @code{gawk}. + +@item compress +@samp{-Z} in @code{tar} and @code{shar}. + +@item concatenate +@samp{-A} in @code{tar}. + +@item confirmation +@samp{-w} in @code{tar}. + +@item context +Used in @code{diff}. + +@item copyleft +@samp{-W copyleft} in @code{gawk}. + +@item copyright +@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}; +@samp{-W copyright} in @code{gawk}. + +@item core +Used in GDB. + +@item count +@samp{-q} in @code{who}. + +@item count-links +@samp{-l} in @code{du}. + +@item create +Used in @code{tar} and @code{cpio}. + +@item cut-mark +@samp{-c} in @code{shar}. + +@item cxref +@samp{-x} in @code{ctags}. + +@item date +@samp{-d} in @code{touch}. + +@item debug +@samp{-d} in Make and @code{m4}; +@samp{-t} in Bison. + +@item define +@samp{-D} in @code{m4}. + +@item defines +@samp{-d} in Bison and @code{ctags}. + +@item delete +@samp{-D} in @code{tar}. + +@item dereference +@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, +@code{ls}, and @code{tar}. + +@item dereference-args +@samp{-D} in @code{du}. + +@item device +Specify an I/O device (special file name). + +@item diacritics +@samp{-d} in @code{recode}. + +@item dictionary-order +@samp{-d} in @code{look}. + +@item diff +@samp{-d} in @code{tar}. + +@item digits +@samp{-n} in @code{csplit}. + +@item directory +Specify the directory to use, in various programs. In @code{ls}, it +means to show directories themselves rather than their contents. In +@code{rm} and @code{ln}, it means to not treat links to directories +specially. + +@item discard-all +@samp{-x} in @code{strip}. + +@item discard-locals +@samp{-X} in @code{strip}. + +@item dry-run +@samp{-n} in Make. + +@item ed +@samp{-e} in @code{diff}. + +@item elide-empty-files +@samp{-z} in @code{csplit}. + +@item end-delete +@samp{-x} in @code{wdiff}. + +@item end-insert +@samp{-z} in @code{wdiff}. + +@item entire-new-file +@samp{-N} in @code{diff}. + +@item environment-overrides +@samp{-e} in Make. + +@item eof +@samp{-e} in @code{xargs}. + +@item epoch +Used in GDB. + +@item error-limit +Used in @code{makeinfo}. + +@item error-output +@samp{-o} in @code{m4}. + +@item escape +@samp{-b} in @code{ls}. + +@item exclude-from +@samp{-X} in @code{tar}. + +@item exec +Used in GDB. + +@item exit +@samp{-x} in @code{xargs}. + +@item exit-0 +@samp{-e} in @code{unshar}. + +@item expand-tabs +@samp{-t} in @code{diff}. + +@item expression +@samp{-e} in @code{sed}. + +@item extern-only +@samp{-g} in @code{nm}. + +@item extract +@samp{-i} in @code{cpio}; +@samp{-x} in @code{tar}. + +@item faces +@samp{-f} in @code{finger}. + +@item fast +@samp{-f} in @code{su}. + +@item fatal-warnings +@samp{-E} in @code{m4}. + +@item file +@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar}; +@samp{-n} in @code{sed}; +@samp{-r} in @code{touch}. + +@item field-separator +@samp{-F} in @code{gawk}. + +@item file-prefix +@samp{-b} in Bison. + +@item file-type +@samp{-F} in @code{ls}. + +@item files-from +@samp{-T} in @code{tar}. + +@item fill-column +Used in @code{makeinfo}. + +@item flag-truncation +@samp{-F} in @code{ptx}. + +@item fixed-output-files +@samp{-y} in Bison. + +@item follow +@samp{-f} in @code{tail}. + +@item footnote-style +Used in @code{makeinfo}. + +@item force +@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. + +@item force-prefix +@samp{-F} in @code{shar}. + +@item foreground +For server programs, run in the foreground; +in other words, don't do anything special to run the server +in the background. + +@item format +Used in @code{ls}, @code{time}, and @code{ptx}. + +@item freeze-state +@samp{-F} in @code{m4}. + +@item fullname +Used in GDB. + +@item gap-size +@samp{-g} in @code{ptx}. + +@item get +@samp{-x} in @code{tar}. + +@item graphic +@samp{-i} in @code{ul}. + +@item graphics +@samp{-g} in @code{recode}. + +@item group +@samp{-g} in @code{install}. + +@item gzip +@samp{-z} in @code{tar} and @code{shar}. + +@item hashsize +@samp{-H} in @code{m4}. + +@item header +@samp{-h} in @code{objdump} and @code{recode} + +@item heading +@samp{-H} in @code{who}. + +@item help +Used to ask for brief usage information. + +@item here-delimiter +@samp{-d} in @code{shar}. + +@item hide-control-chars +@samp{-q} in @code{ls}. + +@item html +In @code{makeinfo}, output HTML. + +@item idle +@samp{-u} in @code{who}. + +@item ifdef +@samp{-D} in @code{diff}. + +@item ignore +@samp{-I} in @code{ls}; +@samp{-x} in @code{recode}. + +@item ignore-all-space +@samp{-w} in @code{diff}. + +@item ignore-backups +@samp{-B} in @code{ls}. + +@item ignore-blank-lines +@samp{-B} in @code{diff}. + +@item ignore-case +@samp{-f} in @code{look} and @code{ptx}; +@samp{-i} in @code{diff} and @code{wdiff}. + +@item ignore-errors +@samp{-i} in Make. + +@item ignore-file +@samp{-i} in @code{ptx}. + +@item ignore-indentation +@samp{-I} in @code{etags}. + +@item ignore-init-file +@samp{-f} in Oleo. + +@item ignore-interrupts +@samp{-i} in @code{tee}. + +@item ignore-matching-lines +@samp{-I} in @code{diff}. + +@item ignore-space-change +@samp{-b} in @code{diff}. + +@item ignore-zeros +@samp{-i} in @code{tar}. + +@item include +@samp{-i} in @code{etags}; +@samp{-I} in @code{m4}. + +@item include-dir +@samp{-I} in Make. + +@item incremental +@samp{-G} in @code{tar}. + +@item info +@samp{-i}, @samp{-l}, and @samp{-m} in Finger. + +@item init-file +In some programs, specify the name of the file to read as the user's +init file. + +@item initial +@samp{-i} in @code{expand}. + +@item initial-tab +@samp{-T} in @code{diff}. + +@item inode +@samp{-i} in @code{ls}. + +@item interactive +@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; +@samp{-e} in @code{m4}; +@samp{-p} in @code{xargs}; +@samp{-w} in @code{tar}. + +@item intermix-type +@samp{-p} in @code{shar}. + +@item iso-8601 +Used in @code{date} + +@item jobs +@samp{-j} in Make. + +@item just-print +@samp{-n} in Make. + +@item keep-going +@samp{-k} in Make. + +@item keep-files +@samp{-k} in @code{csplit}. + +@item kilobytes +@samp{-k} in @code{du} and @code{ls}. + +@item language +@samp{-l} in @code{etags}. + +@item less-mode +@samp{-l} in @code{wdiff}. + +@item level-for-gzip +@samp{-g} in @code{shar}. + +@item line-bytes +@samp{-C} in @code{split}. + +@item lines +Used in @code{split}, @code{head}, and @code{tail}. + +@item link +@samp{-l} in @code{cpio}. + +@item lint +@itemx lint-old +Used in @code{gawk}. + +@item list +@samp{-t} in @code{cpio}; +@samp{-l} in @code{recode}. + +@item list +@samp{-t} in @code{tar}. + +@item literal +@samp{-N} in @code{ls}. + +@item load-average +@samp{-l} in Make. + +@item login +Used in @code{su}. + +@item machine +No listing of which programs already use this; +someone should check to +see if any actually do, and tell @email{gnu@@gnu.org}. + +@item macro-name +@samp{-M} in @code{ptx}. + +@item mail +@samp{-m} in @code{hello} and @code{uname}. + +@item make-directories +@samp{-d} in @code{cpio}. + +@item makefile +@samp{-f} in Make. + +@item mapped +Used in GDB. + +@item max-args +@samp{-n} in @code{xargs}. + +@item max-chars +@samp{-n} in @code{xargs}. + +@item max-lines +@samp{-l} in @code{xargs}. + +@item max-load +@samp{-l} in Make. + +@item max-procs +@samp{-P} in @code{xargs}. + +@item mesg +@samp{-T} in @code{who}. + +@item message +@samp{-T} in @code{who}. + +@item minimal +@samp{-d} in @code{diff}. + +@item mixed-uuencode +@samp{-M} in @code{shar}. + +@item mode +@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. + +@item modification-time +@samp{-m} in @code{tar}. + +@item multi-volume +@samp{-M} in @code{tar}. + +@item name-prefix +@samp{-a} in Bison. + +@item nesting-limit +@samp{-L} in @code{m4}. + +@item net-headers +@samp{-a} in @code{shar}. + +@item new-file +@samp{-W} in Make. + +@item no-builtin-rules +@samp{-r} in Make. + +@item no-character-count +@samp{-w} in @code{shar}. + +@item no-check-existing +@samp{-x} in @code{shar}. + +@item no-common +@samp{-3} in @code{wdiff}. + +@item no-create +@samp{-c} in @code{touch}. + +@item no-defines +@samp{-D} in @code{etags}. + +@item no-deleted +@samp{-1} in @code{wdiff}. + +@item no-dereference +@samp{-d} in @code{cp}. + +@item no-inserted +@samp{-2} in @code{wdiff}. + +@item no-keep-going +@samp{-S} in Make. + +@item no-lines +@samp{-l} in Bison. + +@item no-piping +@samp{-P} in @code{shar}. + +@item no-prof +@samp{-e} in @code{gprof}. + +@item no-regex +@samp{-R} in @code{etags}. + +@item no-sort +@samp{-p} in @code{nm}. + +@item no-split +Used in @code{makeinfo}. + +@item no-static +@samp{-a} in @code{gprof}. + +@item no-time +@samp{-E} in @code{gprof}. + +@item no-timestamp +@samp{-m} in @code{shar}. + +@item no-validate +Used in @code{makeinfo}. + +@item no-wait +Used in @code{emacsclient}. + +@item no-warn +Used in various programs to inhibit warnings. + +@item node +@samp{-n} in @code{info}. + +@item nodename +@samp{-n} in @code{uname}. + +@item nonmatching +@samp{-f} in @code{cpio}. + +@item nstuff +@samp{-n} in @code{objdump}. + +@item null +@samp{-0} in @code{xargs}. + +@item number +@samp{-n} in @code{cat}. + +@item number-nonblank +@samp{-b} in @code{cat}. + +@item numeric-sort +@samp{-n} in @code{nm}. + +@item numeric-uid-gid +@samp{-n} in @code{cpio} and @code{ls}. + +@item nx +Used in GDB. + +@item old-archive +@samp{-o} in @code{tar}. + +@item old-file +@samp{-o} in Make. + +@item one-file-system +@samp{-l} in @code{tar}, @code{cp}, and @code{du}. + +@item only-file +@samp{-o} in @code{ptx}. + +@item only-prof +@samp{-f} in @code{gprof}. + +@item only-time +@samp{-F} in @code{gprof}. + +@item options +@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount}, +@code{fdmountd}, and @code{fdumount}. + +@item output +In various programs, specify the output file name. + +@item output-prefix +@samp{-o} in @code{shar}. + +@item override +@samp{-o} in @code{rm}. + +@item overwrite +@samp{-c} in @code{unshar}. + +@item owner +@samp{-o} in @code{install}. + +@item paginate +@samp{-l} in @code{diff}. + +@item paragraph-indent +Used in @code{makeinfo}. + +@item parents +@samp{-p} in @code{mkdir} and @code{rmdir}. + +@item pass-all +@samp{-p} in @code{ul}. + +@item pass-through +@samp{-p} in @code{cpio}. + +@item port +@samp{-P} in @code{finger}. + +@item portability +@samp{-c} in @code{cpio} and @code{tar}. + +@item posix +Used in @code{gawk}. + +@item prefix-builtins +@samp{-P} in @code{m4}. + +@item prefix +@samp{-f} in @code{csplit}. + +@item preserve +Used in @code{tar} and @code{cp}. + +@item preserve-environment +@samp{-p} in @code{su}. + +@item preserve-modification-time +@samp{-m} in @code{cpio}. + +@item preserve-order +@samp{-s} in @code{tar}. + +@item preserve-permissions +@samp{-p} in @code{tar}. + +@item print +@samp{-l} in @code{diff}. + +@item print-chars +@samp{-L} in @code{cmp}. + +@item print-data-base +@samp{-p} in Make. + +@item print-directory +@samp{-w} in Make. + +@item print-file-name +@samp{-o} in @code{nm}. + +@item print-symdefs +@samp{-s} in @code{nm}. + +@item printer +@samp{-p} in @code{wdiff}. + +@item prompt +@samp{-p} in @code{ed}. + +@item proxy +Specify an HTTP proxy. + +@item query-user +@samp{-X} in @code{shar}. + +@item question +@samp{-q} in Make. + +@item quiet +Used in many programs to inhibit the usual output. @strong{Note:} every +program accepting @samp{--quiet} should accept @samp{--silent} as a +synonym. + +@item quiet-unshar +@samp{-Q} in @code{shar} + +@item quote-name +@samp{-Q} in @code{ls}. + +@item rcs +@samp{-n} in @code{diff}. + +@item re-interval +Used in @code{gawk}. + +@item read-full-blocks +@samp{-B} in @code{tar}. + +@item readnow +Used in GDB. + +@item recon +@samp{-n} in Make. + +@item record-number +@samp{-R} in @code{tar}. + +@item recursive +Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, +and @code{rm}. + +@item reference-limit +Used in @code{makeinfo}. + +@item references +@samp{-r} in @code{ptx}. + +@item regex +@samp{-r} in @code{tac} and @code{etags}. + +@item release +@samp{-r} in @code{uname}. + +@item reload-state +@samp{-R} in @code{m4}. + +@item relocation +@samp{-r} in @code{objdump}. + +@item rename +@samp{-r} in @code{cpio}. + +@item replace +@samp{-i} in @code{xargs}. + +@item report-identical-files +@samp{-s} in @code{diff}. + +@item reset-access-time +@samp{-a} in @code{cpio}. + +@item reverse +@samp{-r} in @code{ls} and @code{nm}. + +@item reversed-ed +@samp{-f} in @code{diff}. + +@item right-side-defs +@samp{-R} in @code{ptx}. + +@item same-order +@samp{-s} in @code{tar}. + +@item same-permissions +@samp{-p} in @code{tar}. + +@item save +@samp{-g} in @code{stty}. + +@item se +Used in GDB. + +@item sentence-regexp +@samp{-S} in @code{ptx}. + +@item separate-dirs +@samp{-S} in @code{du}. + +@item separator +@samp{-s} in @code{tac}. + +@item sequence +Used by @code{recode} to chose files or pipes for sequencing passes. + +@item shell +@samp{-s} in @code{su}. + +@item show-all +@samp{-A} in @code{cat}. + +@item show-c-function +@samp{-p} in @code{diff}. + +@item show-ends +@samp{-E} in @code{cat}. + +@item show-function-line +@samp{-F} in @code{diff}. + +@item show-tabs +@samp{-T} in @code{cat}. + +@item silent +Used in many programs to inhibit the usual output. +@strong{Note:} every program accepting +@samp{--silent} should accept @samp{--quiet} as a synonym. + +@item size +@samp{-s} in @code{ls}. + +@item socket +Specify a file descriptor for a network server to use for its socket, +instead of opening and binding a new socket. This provides a way to +run, in a nonpriveledged process, a server that normally needs a +reserved port number. + +@item sort +Used in @code{ls}. + +@item source +@samp{-W source} in @code{gawk}. + +@item sparse +@samp{-S} in @code{tar}. + +@item speed-large-files +@samp{-H} in @code{diff}. + +@item split-at +@samp{-E} in @code{unshar}. + +@item split-size-limit +@samp{-L} in @code{shar}. + +@item squeeze-blank +@samp{-s} in @code{cat}. + +@item start-delete +@samp{-w} in @code{wdiff}. + +@item start-insert +@samp{-y} in @code{wdiff}. + +@item starting-file +Used in @code{tar} and @code{diff} to specify which file within +a directory to start processing with. + +@item statistics +@samp{-s} in @code{wdiff}. + +@item stdin-file-list +@samp{-S} in @code{shar}. + +@item stop +@samp{-S} in Make. + +@item strict +@samp{-s} in @code{recode}. + +@item strip +@samp{-s} in @code{install}. + +@item strip-all +@samp{-s} in @code{strip}. + +@item strip-debug +@samp{-S} in @code{strip}. + +@item submitter +@samp{-s} in @code{shar}. + +@item suffix +@samp{-S} in @code{cp}, @code{ln}, @code{mv}. + +@item suffix-format +@samp{-b} in @code{csplit}. + +@item sum +@samp{-s} in @code{gprof}. + +@item summarize +@samp{-s} in @code{du}. + +@item symbolic +@samp{-s} in @code{ln}. + +@item symbols +Used in GDB and @code{objdump}. + +@item synclines +@samp{-s} in @code{m4}. + +@item sysname +@samp{-s} in @code{uname}. + +@item tabs +@samp{-t} in @code{expand} and @code{unexpand}. + +@item tabsize +@samp{-T} in @code{ls}. + +@item terminal +@samp{-T} in @code{tput} and @code{ul}. +@samp{-t} in @code{wdiff}. + +@item text +@samp{-a} in @code{diff}. + +@item text-files +@samp{-T} in @code{shar}. + +@item time +Used in @code{ls} and @code{touch}. + +@item timeout +Specify how long to wait before giving up on some operation. + +@item to-stdout +@samp{-O} in @code{tar}. + +@item total +@samp{-c} in @code{du}. + +@item touch +@samp{-t} in Make, @code{ranlib}, and @code{recode}. + +@item trace +@samp{-t} in @code{m4}. + +@item traditional +@samp{-t} in @code{hello}; +@samp{-W traditional} in @code{gawk}; +@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. + +@item tty +Used in GDB. + +@item typedefs +@samp{-t} in @code{ctags}. + +@item typedefs-and-c++ +@samp{-T} in @code{ctags}. + +@item typeset-mode +@samp{-t} in @code{ptx}. + +@item uncompress +@samp{-z} in @code{tar}. + +@item unconditional +@samp{-u} in @code{cpio}. + +@item undefine +@samp{-U} in @code{m4}. + +@item undefined-only +@samp{-u} in @code{nm}. + +@item update +@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. + +@item usage +Used in @code{gawk}; same as @samp{--help}. + +@item uuencode +@samp{-B} in @code{shar}. + +@item vanilla-operation +@samp{-V} in @code{shar}. + +@item verbose +Print more information about progress. Many programs support this. + +@item verify +@samp{-W} in @code{tar}. + +@item version +Print the version number. + +@item version-control +@samp{-V} in @code{cp}, @code{ln}, @code{mv}. + +@item vgrind +@samp{-v} in @code{ctags}. + +@item volume +@samp{-V} in @code{tar}. + +@item what-if +@samp{-W} in Make. + +@item whole-size-limit +@samp{-l} in @code{shar}. + +@item width +@samp{-w} in @code{ls} and @code{ptx}. + +@item word-regexp +@samp{-W} in @code{ptx}. + +@item writable +@samp{-T} in @code{who}. + +@item zeros +@samp{-z} in @code{gprof}. +@end table + +@node Memory Usage +@section Memory Usage +@cindex memory usage + +If a program typically uses just a few meg of memory, don't bother making any +effort to reduce memory usage. For example, if it is impractical for +other reasons to operate on files more than a few meg long, it is +reasonable to read entire input files into core to operate on them. + +However, for programs such as @code{cat} or @code{tail}, that can +usefully operate on very large files, it is important to avoid using a +technique that would artificially limit the size of files it can handle. +If a program works by lines and could be applied to arbitrary +user-supplied input files, it should keep only a line in memory, because +this is not very hard and users will want to be able to operate on input +files that are bigger than will fit in core all at once. + +If your program creates complicated data structures, just make them in +core and give a fatal error if @code{malloc} returns zero. + +@node File Usage +@section File Usage +@cindex file usage + +Programs should be prepared to operate when @file{/usr} and @file{/etc} +are read-only file systems. Thus, if the program manages log files, +lock files, backup files, score files, or any other files which are +modified for internal purposes, these files should not be stored in +@file{/usr} or @file{/etc}. + +There are two exceptions. @file{/etc} is used to store system +configuration information; it is reasonable for a program to modify +files in @file{/etc} when its job is to update the system configuration. +Also, if the user explicitly asks to modify one file in a directory, it +is reasonable for the program to store other files in the same +directory. + +@node Writing C +@chapter Making The Best Use of C + +This @value{CHAPTER} provides advice on how best to use the C language +when writing GNU software. + +@menu +* Formatting:: Formatting Your Source Code +* Comments:: Commenting Your Work +* Syntactic Conventions:: Clean Use of C Constructs +* Names:: Naming Variables and Functions +* System Portability:: Portability between different operating systems +* CPU Portability:: Supporting the range of CPU types +* System Functions:: Portability and ``standard'' library functions +* Internationalization:: Techniques for internationalization +* Mmap:: How you can safely use @code{mmap}. +@end menu + +@node Formatting +@section Formatting Your Source Code +@cindex formatting source code + +@cindex open brace +@cindex braces, in C source +It is important to put the open-brace that starts the body of a C +function in column zero, and avoid putting any other open-brace or +open-parenthesis or open-bracket in column zero. Several tools look +for open-braces in column zero to find the beginnings of C functions. +These tools will not work on code not formatted that way. + +It is also important for function definitions to start the name of the +function in column zero. This helps people to search for function +definitions, and may also help certain tools recognize them. Thus, +the proper format is this: + +@example +static char * +concat (s1, s2) /* Name starts in column zero here */ + char *s1, *s2; +@{ /* Open brace in column zero here */ + @dots{} +@} +@end example + +@noindent +or, if you want to use Standard C syntax, format the definition like +this: + +@example +static char * +concat (char *s1, char *s2) +@{ + @dots{} +@} +@end example + +In Standard C, if the arguments don't fit nicely on one line, +split it like this: + +@example +int +lots_of_args (int an_integer, long a_long, short a_short, + double a_double, float a_float) +@dots{} +@end example + +The rest of this section gives our recommendations for other aspects of +C formatting style, which is also the default style of the @code{indent} +program in version 1.2 and newer. It corresponds to the options + +@smallexample +-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 +-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob +@end smallexample + +We don't think of these recommendations as requirements, because it +causes no problems for users if two different programs have different +formatting styles. + +But whatever style you use, please use it consistently, since a mixture +of styles within one program tends to look ugly. If you are +contributing changes to an existing program, please follow the style of +that program. + +For the body of the function, our recommended style looks like this: + +@example +if (x < foo (y, z)) + haha = bar[4] + 5; +else + @{ + while (z) + @{ + haha += foo (z, z); + z--; + @} + return ++x + bar (); + @} +@end example + +@cindex spaces before open-paren +We find it easier to read a program when it has spaces before the +open-parentheses and after the commas. Especially after the commas. + +When you split an expression into multiple lines, split it +before an operator, not after one. Here is the right way: + +@cindex expressions, splitting +@example +if (foo_this_is_long && bar > win (x, y, z) + && remaining_condition) +@end example + +Try to avoid having two operators of different precedence at the same +level of indentation. For example, don't write this: + +@example +mode = (inmode[j] == VOIDmode + || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) + ? outmode[j] : inmode[j]); +@end example + +Instead, use extra parentheses so that the indentation shows the nesting: + +@example +mode = ((inmode[j] == VOIDmode + || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) + ? outmode[j] : inmode[j]); +@end example + +Insert extra parentheses so that Emacs will indent the code properly. +For example, the following indentation looks nice if you do it by hand, + +@example +v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; +@end example + +@noindent +but Emacs would alter it. Adding a set of parentheses produces +something that looks equally nice, and which Emacs will preserve: + +@example +v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); +@end example + +Format do-while statements like this: + +@example +do + @{ + a = foo (a); + @} +while (a > 0); +@end example + +@cindex formfeed +@cindex control-L +Please use formfeed characters (control-L) to divide the program into +pages at logical places (but not within a function). It does not matter +just how long the pages are, since they do not have to fit on a printed +page. The formfeeds should appear alone on lines by themselves. + +@node Comments +@section Commenting Your Work +@cindex commenting + +Every program should start with a comment saying briefly what it is for. +Example: @samp{fmt - filter for simple filling of text}. + +Please write the comments in a GNU program in English, because English +is the one language that nearly all programmers in all countries can +read. If you do not write English well, please write comments in +English as well as you can, then ask other people to help rewrite them. +If you can't write comments in English, please find someone to work with +you and translate your comments into English. + +Please put a comment on each function saying what the function does, +what sorts of arguments it gets, and what the possible values of +arguments mean and are used for. It is not necessary to duplicate in +words the meaning of the C argument declarations, if a C type is being +used in its customary fashion. If there is anything nonstandard about +its use (such as an argument of type @code{char *} which is really the +address of the second character of a string, not the first), or any +possible values that would not work the way one would expect (such as, +that strings containing newlines are not guaranteed to work), be sure +to say so. + +Also explain the significance of the return value, if there is one. + +Please put two spaces after the end of a sentence in your comments, so +that the Emacs sentence commands will work. Also, please write +complete sentences and capitalize the first word. If a lower-case +identifier comes at the beginning of a sentence, don't capitalize it! +Changing the spelling makes it a different identifier. If you don't +like starting a sentence with a lower case letter, write the sentence +differently (e.g., ``The identifier lower-case is @dots{}''). + +The comment on a function is much clearer if you use the argument +names to speak about the argument values. The variable name itself +should be lower case, but write it in upper case when you are speaking +about the value rather than the variable itself. Thus, ``the inode +number NODE_NUM'' rather than ``an inode''. + +There is usually no purpose in restating the name of the function in +the comment before it, because the reader can see that for himself. +There might be an exception when the comment is so long that the function +itself would be off the bottom of the screen. + +There should be a comment on each static variable as well, like this: + +@example +/* Nonzero means truncate lines in the display; + zero means continue them. */ +int truncate_lines; +@end example + +@cindex conditionals, comments for +@cindex @code{#endif}, commenting +Every @samp{#endif} should have a comment, except in the case of short +conditionals (just a few lines) that are not nested. The comment should +state the condition of the conditional that is ending, @emph{including +its sense}. @samp{#else} should have a comment describing the condition +@emph{and sense} of the code that follows. For example: + +@example +@group +#ifdef foo + @dots{} +#else /* not foo */ + @dots{} +#endif /* not foo */ +@end group +@group +#ifdef foo + @dots{} +#endif /* foo */ +@end group +@end example + +@noindent +but, by contrast, write the comments this way for a @samp{#ifndef}: + +@example +@group +#ifndef foo + @dots{} +#else /* foo */ + @dots{} +#endif /* foo */ +@end group +@group +#ifndef foo + @dots{} +#endif /* not foo */ +@end group +@end example + +@node Syntactic Conventions +@section Clean Use of C Constructs +@cindex syntactic conventions + +@cindex implicit @code{int} +@cindex function argument, declaring +Please explicitly declare the types of all objects. For example, you +should explicitly declare all arguments to functions, and you should +declare functions to return @code{int} rather than omitting the +@code{int}. + +@cindex compiler warnings +@cindex @samp{-Wall} compiler option +Some programmers like to use the GCC @samp{-Wall} option, and change the +code whenever it issues a warning. If you want to do this, then do. +Other programmers prefer not to use @samp{-Wall}, because it gives +warnings for valid and legitimate code which they do not want to change. +If you want to do this, then do. The compiler should be your servant, +not your master. + +Declarations of external functions and functions to appear later in the +source file should all go in one place near the beginning of the file +(somewhere before the first function definition in the file), or else +should go in a header file. Don't put @code{extern} declarations inside +functions. + +@cindex temporary variables +It used to be common practice to use the same local variables (with +names like @code{tem}) over and over for different values within one +function. Instead of doing this, it is better declare a separate local +variable for each distinct purpose, and give it a name which is +meaningful. This not only makes programs easier to understand, it also +facilitates optimization by good compilers. You can also move the +declaration of each local variable into the smallest scope that includes +all its uses. This makes the program even cleaner. + +Don't use local variables or parameters that shadow global identifiers. + +@cindex multiple variables in a line +Don't declare multiple variables in one declaration that spans lines. +Start a new declaration on each line, instead. For example, instead +of this: + +@example +@group +int foo, + bar; +@end group +@end example + +@noindent +write either this: + +@example +int foo, bar; +@end example + +@noindent +or this: + +@example +int foo; +int bar; +@end example + +@noindent +(If they are global variables, each should have a comment preceding it +anyway.) + +When you have an @code{if}-@code{else} statement nested in another +@code{if} statement, always put braces around the @code{if}-@code{else}. +Thus, never write like this: + +@example +if (foo) + if (bar) + win (); + else + lose (); +@end example + +@noindent +always like this: + +@example +if (foo) + @{ + if (bar) + win (); + else + lose (); + @} +@end example + +If you have an @code{if} statement nested inside of an @code{else} +statement, either write @code{else if} on one line, like this, + +@example +if (foo) + @dots{} +else if (bar) + @dots{} +@end example + +@noindent +with its @code{then}-part indented like the preceding @code{then}-part, +or write the nested @code{if} within braces like this: + +@example +if (foo) + @dots{} +else + @{ + if (bar) + @dots{} + @} +@end example + +Don't declare both a structure tag and variables or typedefs in the +same declaration. Instead, declare the structure tag separately +and then use it to declare the variables or typedefs. + +Try to avoid assignments inside @code{if}-conditions. For example, +don't write this: + +@example +if ((foo = (char *) malloc (sizeof *foo)) == 0) + fatal ("virtual memory exhausted"); +@end example + +@noindent +instead, write this: + +@example +foo = (char *) malloc (sizeof *foo); +if (foo == 0) + fatal ("virtual memory exhausted"); +@end example + +@pindex lint +Don't make the program ugly to placate @code{lint}. Please don't insert any +casts to @code{void}. Zero without a cast is perfectly fine as a null +pointer constant, except when calling a varargs function. + +@node Names +@section Naming Variables and Functions + +@cindex names of variables and functions +The names of global variables and functions in a program serve as +comments of a sort. So don't choose terse names---instead, look for +names that give useful information about the meaning of the variable or +function. In a GNU program, names should be English, like other +comments. + +Local variable names can be shorter, because they are used only within +one context, where (presumably) comments explain their purpose. + +Try to limit your use of abbreviations in symbol names. It is ok to +make a few abbreviations, explain what they mean, and then use them +frequently, but don't use lots of obscure abbreviations. + +Please use underscores to separate words in a name, so that the Emacs +word commands can be useful within them. Stick to lower case; reserve +upper case for macros and @code{enum} constants, and for name-prefixes +that follow a uniform convention. + +For example, you should use names like @code{ignore_space_change_flag}; +don't use names like @code{iCantReadThis}. + +Variables that indicate whether command-line options have been +specified should be named after the meaning of the option, not after +the option-letter. A comment should state both the exact meaning of +the option and its letter. For example, + +@example +@group +/* Ignore changes in horizontal whitespace (-b). */ +int ignore_space_change_flag; +@end group +@end example + +When you want to define names with constant integer values, use +@code{enum} rather than @samp{#define}. GDB knows about enumeration +constants. + +@cindex file-name limitations +@pindex doschk +You might want to make sure that none of the file names would conflict +the files were loaded onto an MS-DOS file system which shortens the +names. You can use the program @code{doschk} to test for this. + +Some GNU programs were designed to limit themselves to file names of 14 +characters or less, to avoid file name conflicts if they are read into +older System V systems. Please preserve this feature in the existing +GNU programs that have it, but there is no need to do this in new GNU +programs. @code{doschk} also reports file names longer than 14 +characters. + +@node System Portability +@section Portability between System Types +@cindex portability, between system types + +In the Unix world, ``portability'' refers to porting to different Unix +versions. For a GNU program, this kind of portability is desirable, but +not paramount. + +The primary purpose of GNU software is to run on top of the GNU kernel, +compiled with the GNU C compiler, on various types of @sc{cpu}. So the +kinds of portability that are absolutely necessary are quite limited. +But it is important to support Linux-based GNU systems, since they +are the form of GNU that is popular. + +Beyond that, it is good to support the other free operating systems +(*BSD), and it is nice to support other Unix-like systems if you want +to. Supporting a variety of Unix-like systems is desirable, although +not paramount. It is usually not too hard, so you may as well do it. +But you don't have to consider it an obligation, if it does turn out to +be hard. + +@pindex autoconf +The easiest way to achieve portability to most Unix-like systems is to +use Autoconf. It's unlikely that your program needs to know more +information about the host platform than Autoconf can provide, simply +because most of the programs that need such knowledge have already been +written. + +Avoid using the format of semi-internal data bases (e.g., directories) +when there is a higher-level alternative (@code{readdir}). + +@cindex non-@sc{posix} systems, and portability +As for systems that are not like Unix, such as MSDOS, Windows, the +Macintosh, VMS, and MVS, supporting them is often a lot of work. When +that is the case, it is better to spend your time adding features that +will be useful on GNU and GNU/Linux, rather than on supporting other +incompatible systems. + +It is a good idea to define the ``feature test macro'' +@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU +or GNU/Linux, this will enable the declarations of GNU library extension +functions, and that will usually give you a compiler error message if +you define the same function names in some other way in your program. +(You don't have to actually @emph{use} these functions, if you prefer +to make the program more portable to other systems.) + +But whether or not you use these GNU extensions, you should avoid +using their names for any other meanings. Doing so would make it hard +to move your code into other GNU programs. + +@node CPU Portability +@section Portability between @sc{cpu}s + +@cindex data types, and portability +@cindex portability, and data types +Even GNU systems will differ because of differences among @sc{cpu} +types---for example, difference in byte ordering and alignment +requirements. It is absolutely essential to handle these differences. +However, don't make any effort to cater to the possibility that an +@code{int} will be less than 32 bits. We don't support 16-bit machines +in GNU. + +Similarly, don't make any effort to cater to the possibility that +@code{long} will be smaller than predefined types like @code{size_t}. +For example, the following code is ok: + +@example +printf ("size = %lu\n", (unsigned long) sizeof array); +printf ("diff = %ld\n", (long) (pointer2 - pointer1)); +@end example + +1989 Standard C requires this to work, and we know of only one +counterexample: 64-bit programs on Microsoft Windows IA-64. We will +leave it to those who want to port GNU programs to that environment +to figure out how to do it. + +Predefined file-size types like @code{off_t} are an exception: they are +longer than @code{long} on many platforms, so code like the above won't +work with them. One way to print an @code{off_t} value portably is to +print its digits yourself, one by one. + +Don't assume that the address of an @code{int} object is also the +address of its least-significant byte. This is false on big-endian +machines. Thus, don't make the following mistake: + +@example +int c; +@dots{} +while ((c = getchar()) != EOF) + write(file_descriptor, &c, 1); +@end example + +When calling functions, you need not worry about the difference between +pointers of various types, or between pointers and integers. On most +machines, there's no difference anyway. As for the few machines where +there is a difference, all of them support Standard C prototypes, so you can +use prototypes (perhaps conditionalized to be active only in Standard C) +to make the code work on those systems. + +In certain cases, it is ok to pass integer and pointer arguments +indiscriminately to the same function, and use no prototype on any +system. For example, many GNU programs have error-reporting functions +that pass their arguments along to @code{printf} and friends: + +@example +error (s, a1, a2, a3) + char *s; + char *a1, *a2, *a3; +@{ + fprintf (stderr, "error: "); + fprintf (stderr, s, a1, a2, a3); +@} +@end example + +@noindent +In practice, this works on all machines, since a pointer is generally +the widest possible kind of argument; it is much simpler than any +``correct'' alternative. Be sure @emph{not} to use a prototype for such +functions. + +If you have decided to use Standard C, then you can instead define +@code{error} using @file{stdarg.h}, and pass the arguments along to +@code{vfprintf}. + +@cindex casting pointers to integers +Avoid casting pointers to integers if you can. Such casts greatly +reduce portability, and in most programs they are easy to avoid. In the +cases where casting pointers to integers is essential---such as, a Lisp +interpreter which stores type information as well as an address in one +word---you'll have to make explicit provisions to handle different word +sizes. You will also need to make provision for systems in which the +normal range of addresses you can get from @code{malloc} starts far away +from zero. + +@node System Functions +@section Calling System Functions +@cindex library functions, and portability +@cindex portability, and library functions + +C implementations differ substantially. Standard C reduces but does +not eliminate the incompatibilities; meanwhile, many GNU packages still +support pre-standard compilers because this is not hard to do. This +chapter gives recommendations for how to use the more-or-less standard C +library functions to avoid unnecessary loss of portability. + +@itemize @bullet +@item +Don't use the return value of @code{sprintf}. It returns the number of +characters written on some systems, but not on all systems. + +@item +Be aware that @code{vfprintf} is not always available. + +@item +@code{main} should be declared to return type @code{int}. It should +terminate either by calling @code{exit} or by returning the integer +status code; make sure it cannot ever return an undefined value. + +@cindex declaration for system functions +@item +Don't declare system functions explicitly. + +Almost any declaration for a system function is wrong on some system. +To minimize conflicts, leave it to the system header files to declare +system functions. If the headers don't declare a function, let it +remain undeclared. + +While it may seem unclean to use a function without declaring it, in +practice this works fine for most system library functions on the +systems where this really happens; thus, the disadvantage is only +theoretical. By contrast, actual declarations have frequently caused +actual conflicts. + +@item +If you must declare a system function, don't specify the argument types. +Use an old-style declaration, not a Standard C prototype. The more you +specify about the function, the more likely a conflict. + +@item +In particular, don't unconditionally declare @code{malloc} or +@code{realloc}. + +Most GNU programs use those functions just once, in functions +conventionally named @code{xmalloc} and @code{xrealloc}. These +functions call @code{malloc} and @code{realloc}, respectively, and +check the results. + +Because @code{xmalloc} and @code{xrealloc} are defined in your program, +you can declare them in other files without any risk of type conflict. + +On most systems, @code{int} is the same length as a pointer; thus, the +calls to @code{malloc} and @code{realloc} work fine. For the few +exceptional systems (mostly 64-bit machines), you can use +@strong{conditionalized} declarations of @code{malloc} and +@code{realloc}---or put these declarations in configuration files +specific to those systems. + +@cindex string library functions +@item +The string functions require special treatment. Some Unix systems have +a header file @file{string.h}; others have @file{strings.h}. Neither +file name is portable. There are two things you can do: use Autoconf to +figure out which file to include, or don't include either file. + +@item +If you don't include either strings file, you can't get declarations for +the string functions from the header file in the usual way. + +That causes less of a problem than you might think. The newer standard +string functions should be avoided anyway because many systems still +don't support them. The string functions you can use are these: + +@example +strcpy strncpy strcat strncat +strlen strcmp strncmp +strchr strrchr +@end example + +The copy and concatenate functions work fine without a declaration as +long as you don't use their values. Using their values without a +declaration fails on systems where the width of a pointer differs from +the width of @code{int}, and perhaps in other cases. It is trivial to +avoid using their values, so do that. + +The compare functions and @code{strlen} work fine without a declaration +on most systems, possibly all the ones that GNU software runs on. +You may find it necessary to declare them @strong{conditionally} on a +few systems. + +The search functions must be declared to return @code{char *}. Luckily, +there is no variation in the data type they return. But there is +variation in their names. Some systems give these functions the names +@code{index} and @code{rindex}; other systems use the names +@code{strchr} and @code{strrchr}. Some systems support both pairs of +names, but neither pair works on all systems. + +You should pick a single pair of names and use it throughout your +program. (Nowadays, it is better to choose @code{strchr} and +@code{strrchr} for new programs, since those are the standard +names.) Declare both of those names as functions returning @code{char +*}. On systems which don't support those names, define them as macros +in terms of the other pair. For example, here is what to put at the +beginning of your file (or in a header) if you want to use the names +@code{strchr} and @code{strrchr} throughout: + +@example +#ifndef HAVE_STRCHR +#define strchr index +#endif +#ifndef HAVE_STRRCHR +#define strrchr rindex +#endif + +char *strchr (); +char *strrchr (); +@end example +@end itemize + +Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are +macros defined in systems where the corresponding functions exist. +One way to get them properly defined is to use Autoconf. + +@node Internationalization +@section Internationalization +@cindex internationalization + +@pindex gettext +GNU has a library called GNU gettext that makes it easy to translate the +messages in a program into various languages. You should use this +library in every program. Use English for the messages as they appear +in the program, and let gettext provide the way to translate them into +other languages. + +Using GNU gettext involves putting a call to the @code{gettext} macro +around each string that might need translation---like this: + +@example +printf (gettext ("Processing file `%s'...")); +@end example + +@noindent +This permits GNU gettext to replace the string @code{"Processing file +`%s'..."} with a translated version. + +Once a program uses gettext, please make a point of writing calls to +@code{gettext} when you add new strings that call for translation. + +Using GNU gettext in a package involves specifying a @dfn{text domain +name} for the package. The text domain name is used to separate the +translations for this package from the translations for other packages. +Normally, the text domain name should be the same as the name of the +package---for example, @samp{fileutils} for the GNU file utilities. + +@cindex message text, and internationalization +To enable gettext to work well, avoid writing code that makes +assumptions about the structure of words or sentences. When you want +the precise text of a sentence to vary depending on the data, use two or +more alternative string constants each containing a complete sentences, +rather than inserting conditionalized words or phrases into a single +sentence framework. + +Here is an example of what not to do: + +@example +printf ("%d file%s processed", nfiles, + nfiles != 1 ? "s" : ""); +@end example + +@noindent +The problem with that example is that it assumes that plurals are made +by adding `s'. If you apply gettext to the format string, like this, + +@example +printf (gettext ("%d file%s processed"), nfiles, + nfiles != 1 ? "s" : ""); +@end example + +@noindent +the message can use different words, but it will still be forced to use +`s' for the plural. Here is a better way: + +@example +printf ((nfiles != 1 ? "%d files processed" + : "%d file processed"), + nfiles); +@end example + +@noindent +This way, you can apply gettext to each of the two strings +independently: + +@example +printf ((nfiles != 1 ? gettext ("%d files processed") + : gettext ("%d file processed")), + nfiles); +@end example + +@noindent +This can be any method of forming the plural of the word for ``file'', and +also handles languages that require agreement in the word for +``processed''. + +A similar problem appears at the level of sentence structure with this +code: + +@example +printf ("# Implicit rule search has%s been done.\n", + f->tried_implicit ? "" : " not"); +@end example + +@noindent +Adding @code{gettext} calls to this code cannot give correct results for +all languages, because negation in some languages requires adding words +at more than one place in the sentence. By contrast, adding +@code{gettext} calls does the job straightfowardly if the code starts +out like this: + +@example +printf (f->tried_implicit + ? "# Implicit rule search has been done.\n", + : "# Implicit rule search has not been done.\n"); +@end example + +@node Mmap +@section Mmap +@findex mmap + +Don't assume that @code{mmap} either works on all files or fails +for all files. It may work on some files and fail on others. + +The proper way to use @code{mmap} is to try it on the specific file for +which you want to use it---and if @code{mmap} doesn't work, fall back on +doing the job in another way using @code{read} and @code{write}. + +The reason this precaution is needed is that the GNU kernel (the HURD) +provides a user-extensible file system, in which there can be many +different kinds of ``ordinary files.'' Many of them support +@code{mmap}, but some do not. It is important to make programs handle +all these kinds of files. + +@node Documentation +@chapter Documenting Programs +@cindex documentation + +A GNU program should ideally come with full free documentation, adequate +for both reference and tutorial purposes. If the package can be +programmed or extended, the documentation should cover programming or +extending it, as well as just using it. + +@menu +* GNU Manuals:: Writing proper manuals. +* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual. +* Manual Structure Details:: Specific structure conventions. +* License for Manuals:: Writing the distribution terms for a manual. +* Manual Credits:: Giving credit to documentation contributors. +* Printed Manuals:: Mentioning the printed manual. +* NEWS File:: NEWS files supplement manuals. +* Change Logs:: Recording Changes +* Man Pages:: Man pages are secondary. +* Reading other Manuals:: How far you can go in learning + from other manuals. +@end menu + +@node GNU Manuals +@section GNU Manuals + +The preferred document format for the GNU system is the Texinfo +formatting language. Every GNU package should (ideally) have +documentation in Texinfo both for reference and for learners. Texinfo +makes it possible to produce a good quality formatted book, using +@TeX{}, and to generate an Info file. It is also possible to generate +HTML output from Texinfo source. See the Texinfo manual, either the +hardcopy, or the on-line version available through @code{info} or the +Emacs Info subsystem (@kbd{C-h i}). + +Nowadays some other formats such as Docbook and Sgmltexi can be +converted automatically into Texinfo. It is ok to produce the Texinfo +documentation by conversion this way, as long as it gives good results. + +Programmers often find it most natural to structure the documentation +following the structure of the implementation, which they know. But +this structure is not necessarily good for explaining how to use the +program; it may be irrelevant and confusing for a user. + +At every level, from the sentences in a paragraph to the grouping of +topics into separate manuals, the right way to structure documentation +is according to the concepts and questions that a user will have in mind +when reading it. Sometimes this structure of ideas matches the +structure of the implementation of the software being documented---but +often they are different. Often the most important part of learning to +write good documentation is learning to notice when you are structuring +the documentation like the implementation, and think about better +alternatives. + +For example, each program in the GNU system probably ought to be +documented in one manual; but this does not mean each program should +have its own manual. That would be following the structure of the +implementation, rather than the structure that helps the user +understand. + +Instead, each manual should cover a coherent @emph{topic}. For example, +instead of a manual for @code{diff} and a manual for @code{diff3}, we +have one manual for ``comparison of files'' which covers both of those +programs, as well as @code{cmp}. By documenting these programs +together, we can make the whole subject clearer. + +The manual which discusses a program should certainly document all of +the program's command-line options and all of its commands. It should +give examples of their use. But don't organize the manual as a list of +features. Instead, organize it logically, by subtopics. Address the +questions that a user will ask when thinking about the job that the +program does. + +In general, a GNU manual should serve both as tutorial and reference. +It should be set up for convenient access to each topic through Info, +and for reading straight through (appendixes aside). A GNU manual +should give a good introduction to a beginner reading through from the +start, and should also provide all the details that hackers want. +The Bison manual is a good example of this---please take a look at it +to see what we mean. + +That is not as hard as it first sounds. Arrange each chapter as a +logical breakdown of its topic, but order the sections, and write their +text, so that reading the chapter straight through makes sense. Do +likewise when structuring the book into chapters, and when structuring a +section into paragraphs. The watchword is, @emph{at each point, address +the most fundamental and important issue raised by the preceding text.} + +If necessary, add extra chapters at the beginning of the manual which +are purely tutorial and cover the basics of the subject. These provide +the framework for a beginner to understand the rest of the manual. The +Bison manual provides a good example of how to do this. + +To serve as a reference, a manual should have an Index that list all the +functions, variables, options, and important concepts that are part of +the program. One combined Index should do for a short manual, but +sometimes for a complex package it is better to use multiple indices. +The Texinfo manual includes advice on preparing good index entries, see +@ref{Index Entries, , Making Index Entries, texinfo, The GNU Texinfo +Manual}, and see @ref{Indexing Commands, , Defining the Entries of an +Index, texinfo, The GNU Texinfo manual}. + +Don't use Unix man pages as a model for how to write GNU documentation; +most of them are terse, badly structured, and give inadequate +explanation of the underlying concepts. (There are, of course, some +exceptions.) Also, Unix man pages use a particular format which is +different from what we use in GNU manuals. + +Please include an email address in the manual for where to report +bugs @emph{in the manual}. + +Please do not use the term ``pathname'' that is used in Unix +documentation; use ``file name'' (two words) instead. We use the term +``path'' only for search paths, which are lists of directory names. + +Please do not use the term ``illegal'' to refer to erroneous input to a +computer program. Please use ``invalid'' for this, and reserve the term +``illegal'' for activities punishable by law. + +@node Doc Strings and Manuals +@section Doc Strings and Manuals + +Some programming systems, such as Emacs, provide a documentation string +for each function, command or variable. You may be tempted to write a +reference manual by compiling the documentation strings and writing a +little additional text to go around them---but you must not do it. That +approach is a fundamental mistake. The text of well-written +documentation strings will be entirely wrong for a manual. + +A documentation string needs to stand alone---when it appears on the +screen, there will be no other text to introduce or explain it. +Meanwhile, it can be rather informal in style. + +The text describing a function or variable in a manual must not stand +alone; it appears in the context of a section or subsection. Other text +at the beginning of the section should explain some of the concepts, and +should often make some general points that apply to several functions or +variables. The previous descriptions of functions and variables in the +section will also have given information about the topic. A description +written to stand alone would repeat some of that information; this +redundance looks bad. Meanwhile, the informality that is acceptable in +a documentation string is totally unacceptable in a manual. + +The only good way to use documentation strings in writing a good manual +is to use them as a source of information for writing good text. + +@node Manual Structure Details +@section Manual Structure Details +@cindex manual structure + +The title page of the manual should state the version of the programs or +packages documented in the manual. The Top node of the manual should +also contain this information. If the manual is changing more +frequently than or independent of the program, also state a version +number for the manual in both of these places. + +Each program documented in the manual should have a node named +@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This +node (together with its subnodes, if any) should describe the program's +command line arguments and how to run it (the sort of information people +would look in a man page for). Start with an @samp{@@example} +containing a template for all the options and arguments that the program +uses. + +Alternatively, put a menu item in some menu whose item name fits one of +the above patterns. This identifies the node which that item points to +as the node for this purpose, regardless of the node's actual name. + +The @samp{--usage} feature of the Info reader looks for such a node +or menu item in order to find the relevant text, so it is essential +for every Texinfo file to have one. + +If one manual describes several programs, it should have such a node for +each program described in the manual. + +@node License for Manuals +@section License for Manuals +@cindex license for manuals + +Please use the GNU Free Documentation License for all GNU manuals that +are more than a few pages long. Likewise for a collection of short +documents---you only need one copy of the GNU FDL for the whole +collection. For a single short document, you can use a very permissive +non-copyleft license, to avoid taking up space with a long license. + +See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation +of how to employ the GFDL. + +Note that it is not obligatory to include a copy of the GNU GPL or GNU +LGPL in a manual whose license is neither the GPL nor the LGPL. It can +be a good idea to include the program's license in a large manual; in a +short manual, whose size would be increased considerably by including +the program's license, it is probably better not to include it. + +@node Manual Credits +@section Manual Credits +@cindex credits for manuals + +Please credit the principal human writers of the manual as the authors, +on the title page of the manual. If a company sponsored the work, thank +the company in a suitable place in the manual, but do not cite the +company as an author. + +@node Printed Manuals +@section Printed Manuals + +The FSF publishes some GNU manuals in printed form. To encourage sales +of these manuals, the on-line versions of the manual should mention at +the very start that the printed manual is available and should point at +information for getting it---for instance, with a link to the page +@url{http://www.gnu.org/order/order.html}. This should not be included +in the printed manual, though, because there it is redundant. + +It is also useful to explain in the on-line forms of the manual how the +user can print out the manual from the sources. + +@node NEWS File +@section The NEWS File +@cindex @file{NEWS} file + +In addition to its manual, the package should have a file named +@file{NEWS} which contains a list of user-visible changes worth +mentioning. In each new release, add items to the front of the file and +identify the version they pertain to. Don't discard old items; leave +them in the file after the newer items. This way, a user upgrading from +any previous version can see what is new. + +If the @file{NEWS} file gets very long, move some of the older items +into a file named @file{ONEWS} and put a note at the end referring the +user to that file. + +@node Change Logs +@section Change Logs +@cindex change logs + +Keep a change log to describe all the changes made to program source +files. The purpose of this is so that people investigating bugs in the +future will know about the changes that might have introduced the bug. +Often a new bug can be found by looking at what was recently changed. +More importantly, change logs can help you eliminate conceptual +inconsistencies between different parts of a program, by giving you a +history of how the conflicting concepts arose and who they came from. + +@menu +* Change Log Concepts:: +* Style of Change Logs:: +* Simple Changes:: +* Conditional Changes:: +* Indicating the Part Changed:: +@end menu + +@node Change Log Concepts +@subsection Change Log Concepts + +You can think of the change log as a conceptual ``undo list'' which +explains how earlier versions were different from the current version. +People can see the current version; they don't need the change log +to tell them what is in it. What they want from a change log is a +clear explanation of how the earlier version differed. + +The change log file is normally called @file{ChangeLog} and covers an +entire directory. Each directory can have its own change log, or a +directory can use the change log of its parent directory--it's up to +you. + +Another alternative is to record change log information with a version +control system such as RCS or CVS. This can be converted automatically +to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command +@kbd{C-x v a} (@code{vc-update-change-log}) does the job. + +There's no need to describe the full purpose of the changes or how they +work together. If you think that a change calls for explanation, you're +probably right. Please do explain it---but please put the explanation +in comments in the code, where people will see it whenever they see the +code. For example, ``New function'' is enough for the change log when +you add a function, because there should be a comment before the +function definition to explain what it does. + +However, sometimes it is useful to write one line to describe the +overall purpose of a batch of changes. + +The easiest way to add an entry to @file{ChangeLog} is with the Emacs +command @kbd{M-x add-change-log-entry}. An entry should have an +asterisk, the name of the changed file, and then in parentheses the name +of the changed functions, variables or whatever, followed by a colon. +Then describe the changes you made to that function or variable. + +@node Style of Change Logs +@subsection Style of Change Logs +@cindex change logs, style + +Here are some simple examples of change log entries, starting with the +header line that says who made the change and when, followed by +descriptions of specific changes. (These examples are drawn from Emacs +and GCC.) + +@example +1998-08-17 Richard Stallman <rms@@gnu.org> + +* register.el (insert-register): Return nil. +(jump-to-register): Likewise. + +* sort.el (sort-subr): Return nil. + +* tex-mode.el (tex-bibtex-file, tex-file, tex-region): +Restart the tex shell if process is gone or stopped. +(tex-shell-running): New function. + +* expr.c (store_one_arg): Round size up for move_block_to_reg. +(expand_call): Round up when emitting USE insns. +* stmt.c (assign_parms): Round size up for move_block_from_reg. +@end example + +It's important to name the changed function or variable in full. Don't +abbreviate function or variable names, and don't combine them. +Subsequent maintainers will often search for a function name to find all +the change log entries that pertain to it; if you abbreviate the name, +they won't find it when they search. + +For example, some people are tempted to abbreviate groups of function +names by writing @samp{* register.el (@{insert,jump-to@}-register)}; +this is not a good idea, since searching for @code{jump-to-register} or +@code{insert-register} would not find that entry. + +Separate unrelated change log entries with blank lines. When two +entries represent parts of the same change, so that they work together, +then don't put blank lines between them. Then you can omit the file +name and the asterisk when successive entries are in the same file. + +Break long lists of function names by closing continued lines with +@samp{)}, rather than @samp{,}, and opening the continuation with +@samp{(} as in this example: + +@example +* keyboard.c (menu_bar_items, tool_bar_items) +(Fexecute_extended_command): Deal with `keymap' property. +@end example + +@node Simple Changes +@subsection Simple Changes + +Certain simple kinds of changes don't need much detail in the change +log. + +When you change the calling sequence of a function in a simple fashion, +and you change all the callers of the function to use the new calling +sequence, there is no need to make individual entries for all the +callers that you changed. Just write in the entry for the function +being called, ``All callers changed''---like this: + +@example +* keyboard.c (Fcommand_execute): New arg SPECIAL. +All callers changed. +@end example + +When you change just comments or doc strings, it is enough to write an +entry for the file, without mentioning the functions. Just ``Doc +fixes'' is enough for the change log. + +There's no need to make change log entries for documentation files. +This is because documentation is not susceptible to bugs that are hard +to fix. Documentation does not consist of parts that must interact in a +precisely engineered fashion. To correct an error, you need not know +the history of the erroneous passage; it is enough to compare what the +documentation says with the way the program actually works. + +@node Conditional Changes +@subsection Conditional Changes +@cindex conditional changes, and change logs +@cindex change logs, conditional changes + +C programs often contain compile-time @code{#if} conditionals. Many +changes are conditional; sometimes you add a new definition which is +entirely contained in a conditional. It is very useful to indicate in +the change log the conditions for which the change applies. + +Our convention for indicating conditional changes is to use square +brackets around the name of the condition. + +Here is a simple example, describing a change which is conditional but +does not have a function or entity name associated with it: + +@example +* xterm.c [SOLARIS2]: Include string.h. +@end example + +Here is an entry describing a new definition which is entirely +conditional. This new definition for the macro @code{FRAME_WINDOW_P} is +used only when @code{HAVE_X_WINDOWS} is defined: + +@example +* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. +@end example + +Here is an entry for a change within the function @code{init_display}, +whose definition as a whole is unconditional, but the changes themselves +are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional: + +@example +* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. +@end example + +Here is an entry for a change that takes affect only when +a certain macro is @emph{not} defined: + +@example +(gethostname) [!HAVE_SOCKETS]: Replace with winsock version. +@end example + +@node Indicating the Part Changed +@subsection Indicating the Part Changed + +Indicate the part of a function which changed by using angle brackets +enclosing an indication of what the changed part does. Here is an entry +for a change in the part of the function @code{sh-while-getopts} that +deals with @code{sh} commands: + +@example +* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that +user-specified option string is empty. +@end example + + +@node Man Pages +@section Man Pages +@cindex man pages + +In the GNU project, man pages are secondary. It is not necessary or +expected for every GNU program to have a man page, but some of them do. +It's your choice whether to include a man page in your program. + +When you make this decision, consider that supporting a man page +requires continual effort each time the program is changed. The time +you spend on the man page is time taken away from more useful work. + +For a simple program which changes little, updating the man page may be +a small job. Then there is little reason not to include a man page, if +you have one. + +For a large program that changes a great deal, updating a man page may +be a substantial burden. If a user offers to donate a man page, you may +find this gift costly to accept. It may be better to refuse the man +page unless the same person agrees to take full responsibility for +maintaining it---so that you can wash your hands of it entirely. If +this volunteer later ceases to do the job, then don't feel obliged to +pick it up yourself; it may be better to withdraw the man page from the +distribution until someone else agrees to update it. + +When a program changes only a little, you may feel that the +discrepancies are small enough that the man page remains useful without +updating. If so, put a prominent note near the beginning of the man +page explaining that you don't maintain it and that the Texinfo manual +is more authoritative. The note should say how to access the Texinfo +documentation. + +@node Reading other Manuals +@section Reading other Manuals + +There may be non-free books or documentation files that describe the +program you are documenting. + +It is ok to use these documents for reference, just as the author of a +new algebra textbook can read other books on algebra. A large portion +of any non-fiction book consists of facts, in this case facts about how +a certain program works, and these facts are necessarily the same for +everyone who writes about the subject. But be careful not to copy your +outline structure, wording, tables or examples from preexisting non-free +documentation. Copying from free documentation may be ok; please check +with the FSF about the individual case. + +@node Managing Releases +@chapter The Release Process +@cindex releasing + +Making a release is more than just bundling up your source files in a +tar file and putting it up for FTP. You should set up your software so +that it can be configured to run on a variety of systems. Your Makefile +should conform to the GNU standards described below, and your directory +layout should also conform to the standards discussed below. Doing so +makes it easy to include your package into the larger framework of +all GNU software. + +@menu +* Configuration:: How Configuration Should Work +* Makefile Conventions:: Makefile Conventions +* Releases:: Making Releases +@end menu + +@node Configuration +@section How Configuration Should Work +@cindex program configuration + +@pindex configure +Each GNU distribution should come with a shell script named +@code{configure}. This script is given arguments which describe the +kind of machine and system you want to compile the program for. + +The @code{configure} script must record the configuration options so +that they affect compilation. + +One way to do this is to make a link from a standard name such as +@file{config.h} to the proper configuration file for the chosen system. +If you use this technique, the distribution should @emph{not} contain a +file named @file{config.h}. This is so that people won't be able to +build the program without configuring it first. + +Another thing that @code{configure} can do is to edit the Makefile. If +you do this, the distribution should @emph{not} contain a file named +@file{Makefile}. Instead, it should include a file @file{Makefile.in} which +contains the input used for editing. Once again, this is so that people +won't be able to build the program without configuring it first. + +If @code{configure} does write the @file{Makefile}, then @file{Makefile} +should have a target named @file{Makefile} which causes @code{configure} +to be rerun, setting up the same configuration that was set up last +time. The files that @code{configure} reads should be listed as +dependencies of @file{Makefile}. + +All the files which are output from the @code{configure} script should +have comments at the beginning explaining that they were generated +automatically using @code{configure}. This is so that users won't think +of trying to edit them by hand. + +The @code{configure} script should write a file named @file{config.status} +which describes which configuration options were specified when the +program was last configured. This file should be a shell script which, +if run, will recreate the same configuration. + +The @code{configure} script should accept an option of the form +@samp{--srcdir=@var{dirname}} to specify the directory where sources are found +(if it is not the current directory). This makes it possible to build +the program in a separate directory, so that the actual source directory +is not modified. + +If the user does not specify @samp{--srcdir}, then @code{configure} should +check both @file{.} and @file{..} to see if it can find the sources. If +it finds the sources in one of these places, it should use them from +there. Otherwise, it should report that it cannot find the sources, and +should exit with nonzero status. + +Usually the easy way to support @samp{--srcdir} is by editing a +definition of @code{VPATH} into the Makefile. Some rules may need to +refer explicitly to the specified source directory. To make this +possible, @code{configure} can add to the Makefile a variable named +@code{srcdir} whose value is precisely the specified directory. + +The @code{configure} script should also take an argument which specifies the +type of system to build the program for. This argument should look like +this: + +@example +@var{cpu}-@var{company}-@var{system} +@end example + +For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. + +The @code{configure} script needs to be able to decode all plausible +alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} +would be a valid alias. For many programs, @samp{vax-dec-ultrix} would +be an alias for @samp{vax-dec-bsd}, simply because the differences +between Ultrix and @sc{bsd} are rarely noticeable, but a few programs +might need to distinguish them. +@c Real 4.4BSD now runs on some Suns. + +There is a shell script called @file{config.sub} that you can use +as a subroutine to validate system types and canonicalize aliases. + +@cindex optional features, configure-time +Other options are permitted to specify in more detail the software +or hardware present on the machine, and include or exclude optional +parts of the package: + +@table @samp +@item --enable-@var{feature}@r{[}=@var{parameter}@r{]} +Configure the package to build and install an optional user-level +facility called @var{feature}. This allows users to choose which +optional features to include. Giving an optional @var{parameter} of +@samp{no} should omit @var{feature}, if it is built by default. + +No @samp{--enable} option should @strong{ever} cause one feature to +replace another. No @samp{--enable} option should ever substitute one +useful behavior for another useful behavior. The only proper use for +@samp{--enable} is for questions of whether to build part of the program +or exclude it. + +@item --with-@var{package} +@c @r{[}=@var{parameter}@r{]} +The package @var{package} will be installed, so configure this package +to work with @var{package}. + +@c Giving an optional @var{parameter} of +@c @samp{no} should omit @var{package}, if it is used by default. + +Possible values of @var{package} include +@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, +@samp{gdb}, +@samp{x}, +and +@samp{x-toolkit}. + +Do not use a @samp{--with} option to specify the file name to use to +find certain files. That is outside the scope of what @samp{--with} +options are for. +@end table + +All @code{configure} scripts should accept all of these ``detail'' +options, whether or not they make any difference to the particular +package at hand. In particular, they should accept any option that +starts with @samp{--with-} or @samp{--enable-}. This is so users will +be able to configure an entire GNU source tree at once with a single set +of options. + +You will note that the categories @samp{--with-} and @samp{--enable-} +are narrow: they @strong{do not} provide a place for any sort of option +you might think of. That is deliberate. We want to limit the possible +configuration options in GNU software. We do not want GNU programs to +have idiosyncratic configuration options. + +Packages that perform part of the compilation process may support +cross-compilation. In such a case, the host and target machines for the +program may be different. + +The @code{configure} script should normally treat the specified type of +system as both the host and the target, thus producing a program which +works for the same type of machine that it runs on. + +To configure a cross-compiler, cross-assembler, or what have you, you +should specify a target different from the host, using the configure +option @samp{--target=@var{targettype}}. The syntax for +@var{targettype} is the same as for the host type. So the command would +look like this: + +@example +./configure @var{hosttype} --target=@var{targettype} +@end example + +Programs for which cross-operation is not meaningful need not accept the +@samp{--target} option, because configuring an entire operating system for +cross-operation is not a meaningful operation. + +Bootstrapping a cross-compiler requires compiling it on a machine other +than the host it will run on. Compilation packages accept a +configuration option @samp{--build=@var{buildtype}} for specifying the +configuration on which you will compile them, but the configure script +should normally guess the build machine type (using +@file{config.guess}), so this option is probably not necessary. The +host and target types normally default from the build type, so in +bootstrapping a cross-compiler you must specify them both explicitly. + +Some programs have ways of configuring themselves automatically. If +your program is set up to do this, your @code{configure} script can simply +ignore most of its arguments. + +@comment The makefile standards are in a separate file that is also +@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. +@comment For this document, turn chapters into sections, etc. +@lowersections +@include make-stds.texi +@raisesections + +@node Releases +@section Making Releases +@cindex packaging + +Package the distribution of @code{Foo version 69.96} up in a gzipped tar +file with the name @file{foo-69.96.tar.gz}. It should unpack into a +subdirectory named @file{foo-69.96}. + +Building and installing the program should never modify any of the files +contained in the distribution. This means that all the files that form +part of the program in any way must be classified into @dfn{source +files} and @dfn{non-source files}. Source files are written by humans +and never changed automatically; non-source files are produced from +source files by programs under the control of the Makefile. + +@cindex @file{README} file +The distribution should contain a file named @file{README} which gives +the name of the package, and a general description of what it does. It +is also good to explain the purpose of each of the first-level +subdirectories in the package, if there are any. The @file{README} file +should either state the version number of the package, or refer to where +in the package it can be found. + +The @file{README} file should refer to the file @file{INSTALL}, which +should contain an explanation of the installation procedure. + +The @file{README} file should also refer to the file which contains the +copying conditions. The GNU GPL, if used, should be in a file called +@file{COPYING}. If the GNU LGPL is used, it should be in a file called +@file{COPYING.LIB}. + +Naturally, all the source files must be in the distribution. It is okay +to include non-source files in the distribution, provided they are +up-to-date and machine-independent, so that building the distribution +normally will never modify them. We commonly include non-source files +produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid +unnecessary dependencies between our distributions, so that users can +install whichever packages they want to install. + +Non-source files that might actually be modified by building and +installing the program should @strong{never} be included in the +distribution. So if you do distribute non-source files, always make +sure they are up to date when you make a new distribution. + +Make sure that the directory into which the distribution unpacks (as +well as any subdirectories) are all world-writable (octal mode 777). +This is so that old versions of @code{tar} which preserve the +ownership and permissions of the files from the tar archive will be +able to extract all the files even if the user is unprivileged. + +Make sure that all the files in the distribution are world-readable. + +Make sure that no file name in the distribution is more than 14 +characters long. Likewise, no file created by building the program +should have a name longer than 14 characters. The reason for this is +that some systems adhere to a foolish interpretation of the @sc{posix} +standard, and refuse to open a longer name, rather than truncating as +they did in the past. + +Don't include any symbolic links in the distribution itself. If the tar +file contains symbolic links, then people cannot even unpack it on +systems that don't support symbolic links. Also, don't use multiple +names for one file in different directories, because certain file +systems cannot handle this and that prevents unpacking the +distribution. + +Try to make sure that all the file names will be unique on MS-DOS. A +name on MS-DOS consists of up to 8 characters, optionally followed by a +period and up to three characters. MS-DOS will truncate extra +characters both before and after the period. Thus, +@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they +are truncated to @file{foobarha.c} and @file{foobarha.o}, which are +distinct. + +@cindex @file{texinfo.tex}, in a distribution +Include in your distribution a copy of the @file{texinfo.tex} you used +to test print any @file{*.texinfo} or @file{*.texi} files. + +Likewise, if your program uses small GNU software packages like regex, +getopt, obstack, or termcap, include them in the distribution file. +Leaving them out would make the distribution file a little smaller at +the expense of possible inconvenience to a user who doesn't know what +other files to get. + +@node References +@chapter References to Non-Free Software and Documentation +@cindex references to non-free material + +A GNU program should not recommend use of any non-free program. We +can't stop some people from writing proprietary programs, or stop other +people from using them. But we can and should avoid helping to +advertise them to new customers. + +Sometimes it is important to mention how to build your package on top of +some non-free operating system or other non-free base package. In such +cases, please mention the name of the non-free package or system in the +briefest possible way. Don't include any references for where to find +more information about the proprietary program. The goal should be that +people already using the proprietary program will get the advice they +need about how to use your free program, while people who don't already +use the proprietary program will not see anything to encourage them to +take an interest in it. + +Likewise, a GNU package should not refer the user to any non-free +documentation for free software. The need for free documentation to go +with free software is now a major focus of the GNU project; to show that +we are serious about the need for free documentation, we must not +undermine our position by recommending use of documentation that isn't +free. + +@node Index +@unnumbered Index +@printindex cp + +@contents + +@bye +Local variables: +update-date-leading-regexp: "@c This date is automagically updated when you save this file:\n@set lastupdate " +update-date-trailing-regexp: "" +eval: (load "/gd/gnuorg/update-date.el") +eval: (add-hook 'write-file-hooks 'update-date) +compile-command: "make just-standards" +End: diff --git a/doc/version.texi b/doc/version.texi new file mode 100644 index 0000000..d854139 --- /dev/null +++ b/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 2 December 2023 +@set UPDATED-MONTH December 2023 +@set EDITION 2.52.20231210 +@set VERSION 2.52.20231210 |