diff options
| author | tv <tv@NetBSD.org> | 2001-11-14 19:55:57 +0000 |
|---|---|---|
| committer | tv <tv@NetBSD.org> | 2001-11-14 19:55:57 +0000 |
| commit | 7ae8ff46edd8c2e56a4195c114104f017ab415a2 (patch) | |
| tree | 5b8befb3e8d03318407273bbee3ec5084526548f /gnu | |
| parent | 4218eaa02528aa5bf4eaf035c2cb2b9f4dfe3d2f (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.in | 2 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/Makefile.am | 41 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/Makefile.in | 354 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/autoconf.texi | 11334 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/install.texi | 258 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/make-stds.texi | 944 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/stamp-vti | 3 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/standards.info | 4430 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/standards.texi | 3656 | ||||
| -rw-r--r-- | gnu/dist/autoconf/doc/version.texi | 3 |
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 |
