summaryrefslogtreecommitdiff
path: root/gnu
diff options
context:
space:
mode:
authortv <tv@NetBSD.org>2001-11-14 19:55:57 +0000
committertv <tv@NetBSD.org>2001-11-14 19:55:57 +0000
commit7ae8ff46edd8c2e56a4195c114104f017ab415a2 (patch)
tree5b8befb3e8d03318407273bbee3ec5084526548f /gnu
parent4218eaa02528aa5bf4eaf035c2cb2b9f4dfe3d2f (diff)
Shrink size quite a bit by leaving only autoconf.info (remove all sources).
Diffstat (limited to 'gnu')
-rw-r--r--gnu/dist/autoconf/Makefile.in2
-rw-r--r--gnu/dist/autoconf/doc/Makefile.am41
-rw-r--r--gnu/dist/autoconf/doc/Makefile.in354
-rw-r--r--gnu/dist/autoconf/doc/autoconf.texi11334
-rw-r--r--gnu/dist/autoconf/doc/install.texi258
-rw-r--r--gnu/dist/autoconf/doc/make-stds.texi944
-rw-r--r--gnu/dist/autoconf/doc/stamp-vti3
-rw-r--r--gnu/dist/autoconf/doc/standards.info4430
-rw-r--r--gnu/dist/autoconf/doc/standards.texi3656
-rw-r--r--gnu/dist/autoconf/doc/version.texi3
10 files changed, 1 insertions, 21024 deletions
diff --git a/gnu/dist/autoconf/Makefile.in b/gnu/dist/autoconf/Makefile.in
index dec0decb048..a585fd0148e 100644
--- a/gnu/dist/autoconf/Makefile.in
+++ b/gnu/dist/autoconf/Makefile.in
@@ -69,7 +69,7 @@ VERSION = @VERSION@
AUTOMAKE_OPTIONS = check-news 1.4 readme-alpha
-SUBDIRS = . config m4 man doc tests
+SUBDIRS = . config m4 man tests
SUFFIXES = .m4 .m4f
ACLOCAL_AMFLAGS = --version >/dev/null && touch aclocal.m4
diff --git a/gnu/dist/autoconf/doc/Makefile.am b/gnu/dist/autoconf/doc/Makefile.am
deleted file mode 100644
index 4e11f334ff4..00000000000
--- a/gnu/dist/autoconf/doc/Makefile.am
+++ /dev/null
@@ -1,41 +0,0 @@
-## Process this file with automake to create Makefile.in.
-
-## Makefile for Autoconf.
-## Copyright 2000, 2001 Free Software Foundation, Inc.
-
-## This program is free software; you can redistribute it and/or modify
-## it under the terms of the GNU General Public License as published by
-## the Free Software Foundation; either version 2, or (at your option)
-## any later version.
-
-## This program is distributed in the hope that it will be useful,
-## but WITHOUT ANY WARRANTY; without even the implied warranty of
-## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-## GNU General Public License for more details.
-
-## You should have received a copy of the GNU General Public License
-## along with this program; if not, write to the Free Software
-## Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
-## 02111-1307, USA.
-
-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
-
-# 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
diff --git a/gnu/dist/autoconf/doc/Makefile.in b/gnu/dist/autoconf/doc/Makefile.in
deleted file mode 100644
index 626c7a2cbea..00000000000
--- a/gnu/dist/autoconf/doc/Makefile.in
+++ /dev/null
@@ -1,354 +0,0 @@
-# Makefile.in generated automatically by automake 1.4-p4 from Makefile.am
-
-# Copyright (C) 1994, 1995-8, 1999 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.
-
-
-SHELL = @SHELL@
-
-srcdir = @srcdir@
-top_srcdir = @top_srcdir@
-VPATH = @srcdir@
-prefix = @prefix@
-exec_prefix = @exec_prefix@
-
-bindir = @bindir@
-sbindir = @sbindir@
-libexecdir = @libexecdir@
-datadir = @datadir@
-sysconfdir = @sysconfdir@
-sharedstatedir = @sharedstatedir@
-localstatedir = @localstatedir@
-libdir = @libdir@
-infodir = @infodir@
-mandir = @mandir@
-includedir = @includedir@
-oldincludedir = /usr/include
-
-DESTDIR =
-
-pkgdatadir = $(datadir)/@PACKAGE@
-pkglibdir = $(libdir)/@PACKAGE@
-pkgincludedir = $(includedir)/@PACKAGE@
-
-top_builddir = ..
-
-ACLOCAL = @ACLOCAL@
-AUTOCONF = @AUTOCONF@
-AUTOMAKE = @AUTOMAKE@
-AUTOHEADER = @AUTOHEADER@
-
-INSTALL = @INSTALL@
-INSTALL_PROGRAM = @INSTALL_PROGRAM@ $(AM_INSTALL_PROGRAM_FLAGS)
-INSTALL_DATA = @INSTALL_DATA@
-INSTALL_SCRIPT = @INSTALL_SCRIPT@
-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
-
-mkinstalldirs = $(SHELL) $(top_srcdir)/config/mkinstalldirs
-CONFIG_CLEAN_FILES =
-TEXI2DVI = texi2dvi
-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
-
-
-DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST)
-
-TAR = tar
-GZIP_ENV = --best
-all: all-redirect
-.SUFFIXES:
-.SUFFIXES: .dvi .info .ps .texi .texinfo .txi
-$(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.ac $(ACLOCAL_M4)
- cd $(top_srcdir) && $(AUTOMAKE) --gnu --include-deps doc/Makefile
-
-Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
- cd $(top_builddir) \
- && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status
-
-
-$(srcdir)/version.texi: stamp-vti
- @:
-
-$(srcdir)/stamp-vti: autoconf.texi $(top_srcdir)/configure.ac
- @echo "@set UPDATED `$(SHELL) $(top_srcdir)/config/mdate-sh $(srcdir)/autoconf.texi`" > vti.tmp
- @echo "@set EDITION $(VERSION)" >> vti.tmp
- @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
-
-clean-vti:
-
-distclean-vti:
-
-maintainer-clean-vti:
- -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
-
-autoconf.info: autoconf.texi version.texi $(autoconf_TEXINFOS)
-autoconf.dvi: autoconf.texi version.texi $(autoconf_TEXINFOS)
-
-
-standards.info: standards.texi $(standards_TEXINFOS)
-standards.dvi: standards.texi $(standards_TEXINFOS)
-
-
-DVIPS = dvips
-
-.texi.info:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.texi.dvi:
- TEXINPUTS=$(top_srcdir)/config/texinfo.tex:$$TEXINPUTS \
- MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
-
-.texi:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.texinfo.info:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.texinfo:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.texinfo.dvi:
- TEXINPUTS=$(top_srcdir)/config/texinfo.tex:$$TEXINPUTS \
- MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
-
-.txi.info:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-
-.txi.dvi:
- TEXINPUTS=$(top_srcdir)/config/texinfo.tex:$$TEXINPUTS \
- MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
-
-.txi:
- @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
- cd $(srcdir) \
- && $(MAKEINFO) `echo $< | sed 's,.*/,,'`
-.dvi.ps:
- $(DVIPS) $< -o $@
-
-install-info-am: $(INFO_DEPS)
- @$(NORMAL_INSTALL)
- $(mkinstalldirs) $(DESTDIR)$(infodir)
- @list='$(INFO_DEPS)'; \
- for file in $$list; do \
- d=$(srcdir); \
- for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \
- if test -f $$d/$$ifile; then \
- echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \
- $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \
- else : ; fi; \
- done; \
- done
- @$(POST_INSTALL)
- @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
- list='$(INFO_DEPS)'; \
- for file in $$list; do \
- echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\
- install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\
- done; \
- else : ; fi
-
-uninstall-info:
- $(PRE_UNINSTALL)
- @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
- ii=yes; \
- else ii=; fi; \
- list='$(INFO_DEPS)'; \
- for file in $$list; do \
- test -z "$$ii" \
- || install-info --info-dir=$(DESTDIR)$(infodir) --remove $$file; \
- done
- @$(NORMAL_UNINSTALL)
- list='$(INFO_DEPS)'; \
- for file in $$list; do \
- (cd $(DESTDIR)$(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \
- done
-
-dist-info: $(INFO_DEPS)
- list='$(INFO_DEPS)'; \
- for base in $$list; do \
- d=$(srcdir); \
- for file in `cd $$d && eval echo $$base*`; do \
- test -f $(distdir)/$$file \
- || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
- || cp -p $$d/$$file $(distdir)/$$file; \
- done; \
- done
-
-mostlyclean-aminfo:
- -rm -f autoconf.aux autoconf.cp autoconf.cps autoconf.dvi autoconf.fn \
- autoconf.fns autoconf.ky autoconf.kys autoconf.ps \
- autoconf.log autoconf.pg autoconf.toc autoconf.tp \
- autoconf.tps autoconf.vr autoconf.vrs autoconf.op autoconf.tr \
- autoconf.cv autoconf.cn standards.aux standards.cp \
- standards.cps standards.dvi standards.fn standards.fns \
- standards.ky standards.kys standards.ps standards.log \
- standards.pg standards.toc standards.tp standards.tps \
- standards.vr standards.vrs standards.op standards.tr \
- standards.cv standards.cn
-
-clean-aminfo:
-
-distclean-aminfo:
-
-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:
-
-
-distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir)
-
-subdir = doc
-
-distdir: $(DISTFILES)
- @for file in $(DISTFILES); do \
- d=$(srcdir); \
- if test -d $$d/$$file; then \
- cp -pr $$d/$$file $(distdir)/$$file; \
- else \
- test -f $(distdir)/$$file \
- || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
- || cp -p $$d/$$file $(distdir)/$$file || :; \
- fi; \
- done
- $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info
-info-am: $(INFO_DEPS)
-info: info-am
-dvi-am: $(DVIS)
-dvi: dvi-am
-check-am: all-am
-check: check-am
-installcheck-am:
-installcheck: installcheck-am
-install-exec-am:
-install-exec: install-exec-am
-
-install-data-am: install-info-am
-install-data: install-data-am
-
-install-am: all-am
- @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
-install: install-am
-uninstall-am: uninstall-info
-uninstall: uninstall-am
-all-am: Makefile $(INFO_DEPS)
-all-redirect: all-am
-install-strip:
- $(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install
-installdirs:
- $(mkinstalldirs) $(DESTDIR)$(infodir)
-
-
-mostlyclean-generic:
-
-clean-generic:
- -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
-
-distclean-generic:
- -rm -f Makefile $(CONFIG_CLEAN_FILES)
- -rm -f config.cache config.log stamp-h stamp-h[0-9]*
-
-maintainer-clean-generic:
-mostlyclean-am: mostlyclean-vti mostlyclean-aminfo mostlyclean-generic
-
-mostlyclean: mostlyclean-am
-
-clean-am: clean-vti clean-aminfo clean-generic mostlyclean-am
-
-clean: clean-am
-
-distclean-am: distclean-vti distclean-aminfo distclean-generic clean-am
-
-distclean: distclean-am
-
-maintainer-clean-am: maintainer-clean-vti maintainer-clean-aminfo \
- maintainer-clean-generic distclean-am
- @echo "This command is intended for maintainers to use;"
- @echo "it deletes files that may require special tools to rebuild."
-
-maintainer-clean: maintainer-clean-am
-
-.PHONY: mostlyclean-vti distclean-vti clean-vti maintainer-clean-vti \
-install-info-am uninstall-info mostlyclean-aminfo distclean-aminfo \
-clean-aminfo maintainer-clean-aminfo tags distdir info-am info dvi-am \
-dvi check check-am installcheck-am installcheck install-exec-am \
-install-exec install-data-am install-data install-am install \
-uninstall-am uninstall all-redirect all-am all installdirs \
-mostlyclean-generic distclean-generic clean-generic \
-maintainer-clean-generic clean mostlyclean distclean maintainer-clean
-
-
-# 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/gnu/dist/autoconf/doc/autoconf.texi b/gnu/dist/autoconf/doc/autoconf.texi
deleted file mode 100644
index 41390d51142..00000000000
--- a/gnu/dist/autoconf/doc/autoconf.texi
+++ /dev/null
@@ -1,11334 +0,0 @@
-\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 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:: Formating 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},
-@href{http://www.gnu.org/software/automake/,Automake}, and
-@href{http://www.gnu.org/software/libtool/,Libtool}.
-
-@item Automake Manual
-
-@xref{Top,,Automake,automake,GNU Automake}, for more
-information on Automake.
-
-@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:$@{|:::::|@}*'
-ACLOCAL|:::::|aclocal|:::::|$missing_dir
-AUTOCONF|:::::|autoconf|:::::|$missing_dir
-AUTOMAKE|:::::|automake|:::::|$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 @code{automake}.
-
-@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
-
-Additionally, the following options are recognized and passed to
-@code{automake}:
-
-@table @option
-@item --cygnus
-Assume program is part of Cygnus-style tree.
-
-@item --foreign
-Set strictness to foreign.
-
-@item --gnits
-Set strictness to gnits.
-
-@item --gnu
-Set strictness to gnu.
-
-@item --include-deps
-Include generated dependencies in @file{Makefile.in}.
-@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_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{bison} is found, set output variable @code{YACC} to @samp{bison
--y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
-@samp{byacc}. Otherwise 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
-existant 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:: Formating 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})
-@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_OUTPUT
-@end group
-@end example
-@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/gnu/dist/autoconf/doc/install.texi b/gnu/dist/autoconf/doc/install.texi
deleted file mode 100644
index 19fd35e315d..00000000000
--- a/gnu/dist/autoconf/doc/install.texi
+++ /dev/null
@@ -1,258 +0,0 @@
-@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/gnu/dist/autoconf/doc/make-stds.texi b/gnu/dist/autoconf/doc/make-stds.texi
deleted file mode 100644
index 68faa8dba19..00000000000
--- a/gnu/dist/autoconf/doc/make-stds.texi
+++ /dev/null
@@ -1,944 +0,0 @@
-@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/gnu/dist/autoconf/doc/stamp-vti b/gnu/dist/autoconf/doc/stamp-vti
deleted file mode 100644
index 52505df6878..00000000000
--- a/gnu/dist/autoconf/doc/stamp-vti
+++ /dev/null
@@ -1,3 +0,0 @@
-@set UPDATED 17 July 2001
-@set EDITION 2.52
-@set VERSION 2.52
diff --git a/gnu/dist/autoconf/doc/standards.info b/gnu/dist/autoconf/doc/standards.info
deleted file mode 100644
index bcc449e14fa..00000000000
--- a/gnu/dist/autoconf/doc/standards.info
+++ /dev/null
@@ -1,4430 +0,0 @@
-Ceci est le fichier Info standards.info, produit par Makeinfo version
-4.0 à partir 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, Prev: Top, Up: Top
-
-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
-
-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
-
-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
-
-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
-
-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
-
-General Program Design
-**********************
-
- This node discusses some of the issues you should take into account
-when designing your program.
-
-* Menu:
-
-* Source Language:: Which languges 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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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 idiosyncracies 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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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.
-* --help option: Command-Line Interfaces.
-* --version option: Command-Line Interfaces.
-* -Wall compiler option: Syntactic Conventions.
-* accepting contributions: Contributions.
-* address for bug reports: Command-Line Interfaces.
-* ANSI C standard: Standard C.
-* arbitrary limits on data: Semantics.
-* autoconf: System Portability.
-* avoiding proprietary code: Reading Non-Free Code.
-* behavior, dependent on program's name: User Interfaces.
-* binary packages: Install Command Categories.
-* bindir: Directory Variables.
-* braces, in C source: Formatting.
-* bug reports: Command-Line Interfaces.
-* canonical name of a program: Command-Line Interfaces.
-* casting pointers to integers: CPU Portability.
-* change logs: Change Logs.
-* change logs, conditional changes: Conditional Changes.
-* change logs, style: Style of Change Logs.
-* command-line arguments, decoding: Semantics.
-* command-line interface: Command-Line Interfaces.
-* commenting: Comments.
-* compatibility with C and POSIX standards: Compatibility.
-* compiler warnings: Syntactic Conventions.
-* conditional changes, and change logs: Conditional Changes.
-* conditionals, comments for: Comments.
-* configure: Configuration.
-* control-L: Formatting.
-* conventions for makefiles: Makefile Conventions.
-* corba: Graphical Interfaces.
-* credits for manuals: Manual Credits.
-* data types, and portability: CPU Portability.
-* declaration for system functions: System Functions.
-* documentation: Documentation.
-* doschk: Names.
-* downloading this manual: Preface.
-* error messages: Semantics.
-* error messages, formatting: Errors.
-* exec_prefix: Directory Variables.
-* expressions, splitting: Formatting.
-* file usage: File Usage.
-* file-name limitations: Names.
-* formatting error messages: Errors.
-* formatting source code: Formatting.
-* formfeed: Formatting.
-* function argument, declaring: Syntactic Conventions.
-* function prototypes: Standard C.
-* getopt: Command-Line Interfaces.
-* gettext: Internationalization.
-* gnome: Graphical Interfaces.
-* graphical user interface: Graphical Interfaces.
-* gtk: Graphical Interfaces.
-* GUILE: Source Language.
-* implicit int: Syntactic Conventions.
-* impossible conditions: Semantics.
-* internationalization: Internationalization.
-* legal aspects: Legal Issues.
-* legal papers: Contributions.
-* libexecdir: Directory Variables.
-* libraries: Libraries.
-* library functions, and portability: System Functions.
-* license for manuals: License for Manuals.
-* lint: Syntactic Conventions.
-* long option names: Option Table.
-* long-named options: Command-Line Interfaces.
-* makefile, conventions for: Makefile Conventions.
-* malloc return value: Semantics.
-* man pages: Man Pages.
-* manual structure: Manual Structure Details.
-* memory allocation failure: Semantics.
-* memory usage: Memory Usage.
-* message text, and internationalization: Internationalization.
-* mmap: Mmap.
-* multiple variables in a line: Syntactic Conventions.
-* names of variables and functions: Names.
-* NEWS file: NEWS File.
-* non-POSIX systems, and portability: System Portability.
-* non-standard extensions: Using Extensions.
-* NUL characters: Semantics.
-* open brace: Formatting.
-* optional features, configure-time: Configuration.
-* options for compatibility: Compatibility.
-* output device and program's behavior: User Interfaces.
-* packaging: Releases.
-* portability, and data types: CPU Portability.
-* portability, and library functions: System Functions.
-* portability, between system types: System Portability.
-* POSIX compatibility: Compatibility.
-* POSIXLY_CORRECT, environment variable: Compatibility.
-* post-installation commands: Install Command Categories.
-* pre-installation commands: Install Command Categories.
-* prefix: Directory Variables.
-* program configuration: Configuration.
-* program design: Design Advice.
-* program name and its behavior: User Interfaces.
-* program's canonical name: Command-Line Interfaces.
-* programming languges: Source Language.
-* proprietary programs: Reading Non-Free Code.
-* README file: Releases.
-* references to non-free material: References.
-* releasing: Managing Releases.
-* sbindir: Directory Variables.
-* signal handling: Semantics.
-* spaces before open-paren: Formatting.
-* standard command-line options: Command-Line Interfaces.
-* standards for makefiles: Makefile Conventions.
-* string library functions: System Functions.
-* syntactic conventions: Syntactic Conventions.
-* table of long options: Option Table.
-* temporary files: Semantics.
-* temporary variables: Syntactic Conventions.
-* texinfo.tex, in a distribution: Releases.
-* TMPDIR environment variable: Semantics.
-* trademarks: Trademarks.
-* where to obtain standards.texi: Preface.
-
-
-
-Tag Table:
-Node: Top999
-Node: Preface1601
-Node: Legal Issues3202
-Node: Reading Non-Free Code3665
-Node: Contributions5388
-Node: Trademarks7537
-Node: Design Advice8595
-Node: Source Language9101
-Node: Compatibility11108
-Node: Using Extensions12731
-Node: Standard C14302
-Node: Program Behavior16668
-Node: Semantics17586
-Node: Libraries22274
-Node: Errors23514
-Node: User Interfaces25290
-Node: Graphical Interfaces26890
-Node: Command-Line Interfaces27920
-Node: Option Table33405
-Node: Memory Usage48409
-Node: File Usage49429
-Node: Writing C50172
-Node: Formatting51013
-Node: Comments55071
-Node: Syntactic Conventions58369
-Node: Names61776
-Node: System Portability63964
-Node: CPU Portability66344
-Node: System Functions69595
-Node: Internationalization74797
-Node: Mmap77945
-Node: Documentation78650
-Node: GNU Manuals79754
-Node: Doc Strings and Manuals84806
-Node: Manual Structure Details86354
-Node: License for Manuals87767
-Node: Manual Credits88736
-Node: Printed Manuals89124
-Node: NEWS File89805
-Node: Change Logs90477
-Node: Change Log Concepts91226
-Node: Style of Change Logs93081
-Node: Simple Changes95127
-Node: Conditional Changes96362
-Node: Indicating the Part Changed97775
-Node: Man Pages98293
-Node: Reading other Manuals99912
-Node: Managing Releases100696
-Node: Configuration101451
-Node: Makefile Conventions108351
-Node: Makefile Basics109110
-Node: Utilities in Makefiles112275
-Node: Command Variables114411
-Node: Directory Variables117979
-Node: Standard Targets128864
-Ref: Standard Targets-Footnote-1140115
-Node: Install Command Categories140215
-Node: Releases144788
-Node: References148871
-Node: Index150265
-
-End Tag Table
diff --git a/gnu/dist/autoconf/doc/standards.texi b/gnu/dist/autoconf/doc/standards.texi
deleted file mode 100644
index b93984bd8a4..00000000000
--- a/gnu/dist/autoconf/doc/standards.texi
+++ /dev/null
@@ -1,3656 +0,0 @@
-\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 languges 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 languges
-
-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 idiosyncracies 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/gnu/dist/autoconf/doc/version.texi b/gnu/dist/autoconf/doc/version.texi
deleted file mode 100644
index 52505df6878..00000000000
--- a/gnu/dist/autoconf/doc/version.texi
+++ /dev/null
@@ -1,3 +0,0 @@
-@set UPDATED 17 July 2001
-@set EDITION 2.52
-@set VERSION 2.52