From: Theodore Tso Date: Mon, 20 May 1996 22:09:09 +0000 (+0000) Subject: Update autoconf to version 2.10. This will fix the reported bugs of X-Git-Tag: krb5-1.0-beta6~51 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=6c256441346e5198259aaed35a657121891de704;p=krb5.git Update autoconf to version 2.10. This will fix the reported bugs of the install-sh script getting cached with the wrong values, as well as bringing us to a more recent version of autoconf. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@8078 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/src/util/autoconf/ChangeLog b/src/util/autoconf/ChangeLog index 03b28d95e..40bb41e14 100644 --- a/src/util/autoconf/ChangeLog +++ b/src/util/autoconf/ChangeLog @@ -1,15 +1,269 @@ -Thu Aug 24 18:21:07 1995 Theodore Y. Ts'o +Tue May 7 13:20:33 1996 Roland McGrath - * .Sanitize: Updated for autoconf 2.4 + * acgeneral.m4: Verion 2.10 released. -Wed Jun 21 14:48:19 1995 +Tue Mar 26 13:03:12 1996 Roland McGrath - * Installed autoconf 2.4 in the Kerberos V5 tree. This reverted a - few Krb5-specific changes: tytso Ultrix /bin/sh - workarounds (which are supposedly fixed in another way in - autoconf 2.4), eichin's change to autoreconf to allow it to - work in symlink farms, jgilmore's change acgeneral.m4 to - report the update status of the cache better (???). + * acgeneral.m4 (AC_OUTPUT_HEADER): Make subdir if necessary. + +Thu Mar 21 10:52:03 1996 Roland McGrath + + * acspecific.m4 (AC_FUNC_GETLOADAVG): Fix name of -lelf cache variable + name in test of it. + (AC_PATH_XTRA): Fix name of -ldnet cache variable name in test of it. + +Wed Mar 20 09:37:31 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_LIB): Use \055 for -; leading and trailing + both lose with some tr. + + * acspecific.m4 (AC_C_CONST): Remove check for gcc 2.7 bug. + RMS wants everyone to lose until gcc is fixed. + + * acgeneral.m4 (AC_CHECK_LIB): Put - last in tr set so it is not + considered a range. + + * acspecific.m4 (AC_C_CONST): Add check for gcc 2.7 bug. + From Paul Eggert and Jim Meyering. + + * acgeneral.m4 (AC_CHECK_LIB): Omit `char $2' decl when $2 is `main'. + +Wed Mar 13 22:10:42 1996 Andreas Schwab + + * acgeneral.m4 (AC_CHECK_LIB): Put quotes around _ when + constructing cache variable name, to separate it from preceding + text. + +Sat Mar 16 15:53:22 1996 Roland McGrath + + * Version 2.9 released. + * acgeneral.m4 (AC_ACVERSION): Updated to 2.9. + +Wed Mar 13 12:49:51 1996 Roland McGrath + + * acgeneral.m4 (AC_OUTPUT_HEADER): Undo last change to $ac_dB, + and instead change the code written into conftest.hdr. + +Tue Mar 12 02:51:24 1996 Roland McGrath + + * acgeneral.m4 (AC_OUTPUT_HEADER): Apply Jan 15 fix to + AC_OUTPUT_MAKE_DEFS here too: Match `#define foo' without trailing + space in confdefs.h. Before configure would lose if all its trailing + whitespace got stripped, and that can happen in mail. + +Sun Mar 10 20:30:09 1996 Roland McGrath + + * acgeneral.m4 (AC_INIT_NOTICE): Add 95 and 96 to copyright years. + +Sat Mar 9 18:28:42 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_LIB): Add missing [. + +Fri Mar 8 15:06:48 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_LIB): Declare $2 to override gcc2 internal + prototype. + + * Version 2.8 released. + +Wed Mar 6 14:38:31 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_LIB): Use a cache variable name containing + both the library and function name. + +Tue Jan 16 16:39:21 1996 Roland McGrath + + * acgeneral.m4 (AC_CHECK_PROG): Take optional 6th arg, full name + of program to reject if found in search path. + * acspecific.m4 (AC_PROG_CC): If gcc not found use AC_CHECK_PROG + for cc, rejecting /usr/ucb/cc. + Fatal configure error if no $CC found at all. + +Mon Jan 15 15:57:36 1996 Roland McGrath + + * acgeneral.m4 (AC_OUTPUT_MAKE_DEFS): Match `#define foo' without + trailing space in confdefs.h. Before configure would lose if + all its trailing whitespace got stripped, and that can happen in mail. + +Fri Jan 12 14:38:37 1996 Roland McGrath + + * acgeneral.m4 (AC_TRY_CPP): Use "" instead of '' when setting + ac_try; we need one level of expansion there for $ac_cpp, then + AC_TRY_EVAL does one more for its the expansion of $ac_cpp. + +Thu Jan 11 10:38:19 1996 Roland McGrath + + * acgeneral.m4 (AC_LANG_C, AC_LANG_CPLUSPLUS): Removed echo cmds + from $ac_cpp, $ac_compile, and $ac_link. + (AC_TRY_EVAL, AC_TRY_COMMAND): New macros for running tests' commands. + Always put the configure source line and command line into config.log. + (AC_TRY_CPP, AC_TRY_COMPILE, AC_TRY_LINK): Use them. + * acspecific.m4: Use AC_TRY_EVAL and AC_TRY_COMMAND for running + all tests. + +Fri Jan 5 17:50:28 1996 Roland McGrath + + * acspecific.m4 (AC_PATH_X, AC_PATH_X_XMKMF, AC_PATH_X_DIRECT): + Rearrange logic: do no tests if $with_x=no; make incl and lib + tests independent, and distinguish unset from empty. + + * autoconf.sh (undefined macro check): \ sed \s inside "". If + grep $name in $infile misses, give error message that there must + be an Autoconf bug. + +Tue Dec 19 10:49:20 1995 David J. MacKenzie + + * autoconf.sh: Ignore undefined macros in shell comments. + +Mon Dec 11 22:12:54 1995 Roland McGrath + + * acspecific.m4 (AC_PROG_CC_C_O): Rearrange logic to get the right + answer for cc. + +Fri Nov 24 17:26:38 1995 Miles Bader + + * autoconf.sh: Define $AWK from the subst @AWK@, and use it. + +Wed Nov 22 11:01:16 1995 David J. MacKenzie + + * Version 2.7. + + * autoheader.m4 (AC_CHECK_FUNCS, AC_CHECK_HEADERS): Expand the + optional action args. From jj@jfch.vc.cvut.cz (Jakub Jelinek). + + * acgeneral.m4 (AC_CHECK_LIB): Translate - in library names to _. + (AC_ARG_PROGRAM): Use cat instead of echo to avoid SysV echo + interpreting backslashes. From kim@tac.nyc.ny.US (Kimmo Suominen). + (AC_OUTPUT_FILES): Quote $ and \ for being in an unquoted here + document. From Paul Eggert . + + * acspecific.m4 (AC_PATH_X_XMKMF): Use ${MAKE-make}, not plain make. + (AC_C_CONST): Avoid a warning from g++. + From tgl@sss.pgh.pa.us (Tom Lane). + (AC_FUNC_MMAP): Check for valloc and getpagesize; don't rely on + predefines. + (AC_HEADER_STDC): If cross-compiling, assume the ctype macros are + ANSI. From dje@cygnus.com (Doug Evans). + (AC_TYPE_SIGNAL) [__cplusplus]: Give a full prototype. + From churritz@cts.com (Chad Hurwitz). + (AC_FUNC_VFORK): If cross-compiling, use AC_CHECK_FUNC instead. + From steve chamberlain . + +Tue Sep 5 20:37:48 1995 Paul Eggert + + * acspecific.m4 (X_LIBS): Use `-R lib', not `-Rlib', since Sun + CC 3.0 requires this. + +Tue Aug 8 20:10:12 1995 Paul Eggert + + * acgeneral.m4: When creating config.status, start a new + here-script just before building conftest.subs, to work around + a bug in the HP-UX 9 HP9000-800 sh. + +Tue Nov 21 17:36:41 1995 David J. MacKenzie + + * Makefile.in (install): Undo last ASCRIPTS panic change. + The bug reporter hadn't cleaned up his source dir. + +Mon Nov 20 15:26:50 1995 David J. MacKenzie + + * Version 2.6. + + * acgeneral.m4 (AC_INIT_PARSE_ARGS): Prettify usage message somewhat. + + * Makefile.in: Use @bindir@, @datadir@, @infodir@. + (install): Find ASCRIPTS in $(srcdir). + +Sat Nov 18 14:21:55 1995 Karl Berry + + * autoconf.sh: Allow lowercase letters in the undefined-macro name. + +Fri Nov 17 15:05:44 1995 Roland McGrath + + * Version 2.5 released. + +Fri Nov 17 15:23:04 1995 David J. MacKenzie + + * acgeneral.m4 (AC_CHECK_LIB): Don't start tr argument with '+', + so as not to confuse old GNU tr's. From + Ian Lance Taylor . + (AC_INIT_PARSE_ARGS): Make sure MFLAGS and MAKEFLAGS are empty. + From Paul Townsend (aab@cc.purdue.edu). + (AC_CHECK_LIB, AC_CHECK_HEADERS, AC_CHECK_FUNC): Remove + duplicate `d' from alphabets. + + * acspecific.m4 (AC_USG): Define USG if we don't have rindex and + bzero, not if we do have them. + From Viktor Dukhovni . + +Sun Oct 29 15:13:37 1995 Richard Stallman + + * acgeneral.m4 (AC_CHECK_PROG): Use arg 5 as search list, not arg 4. + +Wed Aug 30 17:34:48 1995 Roland McGrath + + * acspecific.m4 (AC_PROG_CC_C_O): If $CC groks it and cc doesn't + exist, choose yes. + +Wed Jul 26 00:03:26 1995 David J. MacKenzie + + * Test release 2.4.2. + + * acgeneral.m4 (AC_CHECK_SIZEOF): Take an optional size to + use when cross-compiling. + + * acspecific.m4 (AC_FUNC_CLOSEDIR_VOID, AC_DIR_HEADER): If + cross-compiling, assume it returns void. It's not a big loss. + From Karl Berry. + + * acgeneral.m4 autoheader.sh: Change tr [a-z] [A-Z] into expansion + of the full alphabet, to combat losing AIX 4.1.1 tr when LANG + isn't set the way it likes. + + * acspecific.m4 (AC_FUNC_GETMNTENT): Check in -lgen for Unixware. + From miguel@roxanne.nuclecu.unam.mx (Miguel de Icaza). + + * autoheader.m4 (AC_CONFIG_HEADER): Set config_h to the first + argument. From ghudson@mit.edu (Greg Hudson). + + * Makefile.in (all): Depend on info. + + * acgeneral.m4 (AC_CHECK_PROG, AC_PATH_PROG, AC_CHECK_PROGS, + AC_PATH_PROGS, AC_CHECK_TOOL): Add optional PATH + parameter. + +Mon Jul 24 17:27:11 1995 David J. MacKenzie + + * acgeneral.m4 (AC_CHECK_LIB): Don't enclose tr args in [], for + SysV and POSIX. From Karl Heuer. + +Wed Jul 19 17:43:44 1995 David J. MacKenzie + + * acgeneral.m4 (AC_CHECK_LIB): Translate + to p in lib name. + +Wed Jun 28 13:45:16 1995 David J. MacKenzie + + * acgeneral.m4 (AC_ARG_ENABLE, AC_ARG_WITH): Allow an empty value + for --enable and --with args. + (AC_CACHE_CHECK): New macro. + * acspecific.m4: Use it where possible. + +Tue Jun 27 13:29:54 1995 David J. MacKenzie + + * acgeneral.m4 (AC_INIT_PARSE_ARGS, AC_INIT_PREPARE): Add options + --bindir, --libdir, etc. + +Mon Jun 26 20:54:36 1995 David J. MacKenzie + + * acgeneral.m4 (AC_LANG_C, AC_LANG_CPLUSPLUS): Put the command + being run into the log file. + +Thu Jun 22 22:33:23 1995 David J. MacKenzie + + * acspecific.m4 (AC_PROG_INSTALL): Don't cache a shell script path. + + * acgeneral.m4 (AC_CHECK_LIB): Allow lib name to contain a . or /, + by fixing the cache variable name. Wed Jun 14 23:07:20 1995 David J. MacKenzie @@ -40,7 +294,7 @@ Thu Mar 23 18:02:25 1995 David J. MacKenzie after compiler name. Same for "-o conftest". * ifnames.sh (AC_MACRODIR): Default to @datadir@, not a hardcoded - path. + path. * Test release 2.2.1. @@ -86,7 +340,7 @@ Mon Mar 6 15:07:00 1995 David J. MacKenzie Fri Mar 3 11:41:01 1995 David J. MacKenzie * Makefile.in (autoconf.info, standards.info): Use --no-split to - avoid creating filenames > 14 chars. + avoid creating filenames > 14 chars. * acgeneral.m4 (AC_CHECK_FUNC): Use assert.h, to avoid protype conflicts from ctype.h (!!) on OSF/1 3.0. @@ -162,7 +416,7 @@ Thu Feb 9 14:42:20 1995 David J. MacKenzie * Makefile.in (editsh): Substitute in AWK. * acspecific.m4 (AC_PROG_INSTALL): Allow trailing slashes in PATH - elements. + elements. * acgeneral.m4 (AC_PREFIX_PROGRAM): Ditto. Tue Feb 7 11:32:09 1995 David J. MacKenzie @@ -286,7 +540,7 @@ Thu Nov 3 10:24:08 1994 David J. MacKenzie obsolete warning. * autoscan.pl (output_programs): Use AC_CHECK_LIB, not - AC_HAVE_LIBRARY. + AC_HAVE_LIBRARY. * acgeneral.m4 (AC_CHECK_FUNC): Move prototype outside of function so it works with C++. From ejb@era.COM (E. Jay Berkenbilt). @@ -303,7 +557,7 @@ Wed Oct 26 18:40:41 1994 David J. MacKenzie Tue Oct 25 11:04:16 1994 David J. MacKenzie - * acgeneral.m4 (AC_CHECK_HEADER, AC_CHECK_HEADERS): Change - + * acgeneral.m4 (AC_CHECK_HEADER, AC_CHECK_HEADERS): Change - in file names to _. * acspecific.m4 (AC_CHECK_HEADER_DIRENT, AC_CHECK_HEADERS_DIRENT): Likewise. @@ -620,7 +874,7 @@ Thu Sep 1 15:34:15 1994 David J. MacKenzie (djm@geech.gnu.ai.mit.edu) * acgeneral.m4 (AC_TRY_RUN): Always warn if no cross-compile default is given. * acspecific.m4 (AC_FUNC_MMAP, AC_FUNC_VFORK, AC_FUNC_WAIT3, - AC_FUNC_UTIME_NULL, AC_FUNC_STRCOLL): Provide a default + AC_FUNC_UTIME_NULL, AC_FUNC_STRCOLL): Provide a default for AC_TRY_RUN. (AC_FUNC_CLOSEDIR_VOID): New macro, broken out of AC_HEADER_DIRENT. @@ -705,7 +959,7 @@ Sat Aug 27 13:31:58 1994 David J. MacKenzie (djm@geech.gnu.ai.mit.edu) Fri Aug 26 17:03:18 1994 David J. MacKenzie (djm@geech.gnu.ai.mit.edu) - * autoconf.sh, acgeneral.m4: __LINE__ -> __oline__. + * autoconf.sh, acgeneral.m4: __LINE__ -> __oline__. * acgeneral.m4 (AC_TRY_CPP, AC_EGREP_CPP): Append any error output to config.log. @@ -725,7 +979,7 @@ Fri Aug 26 17:03:18 1994 David J. MacKenzie (djm@geech.gnu.ai.mit.edu) Fri Aug 26 00:34:11 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) * acconfig.h (HAVE_UNION_WAIT): Entry removed; it wasn't defined - anywhere. + anywhere. * acgeneral.m4 (AC_OUTPUT_HEADER): rm files before mv onto them. (AC_OUTPUT): Remove explicit exit at end of configure, to allow @@ -784,7 +1038,7 @@ Thu Aug 25 09:26:36 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) Write to the appropriate diversions. (AC_ENABLE, AC_WITH): Supply default help string. (AC_ENABLE_INTERNAL, AC_WITH_INTERNAL, AC_PREFIX_INTERNAL): - Macros removed. + Macros removed. (AC_CONFIG_SUBDIRS): Set `subdirs' here instead of in AC_INIT_PREPARE. (AC_PREFIX): Macro removed. @@ -824,7 +1078,7 @@ Wed Aug 24 00:19:05 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) * testsuite/autoconf.s/specific.exp: Add AC_HEADER_DIRENT. Remove AC_SYS_REMOTE_TAPE. Replace AC_HAVE_POUNDBANG with - AC_SYS_INTERPRETER. + AC_SYS_INTERPRETER. * acspecific.m4 (AC_INT_16_BITS, AC_LONG_64_BITS): Reword messages. @@ -868,7 +1122,7 @@ Tue Aug 23 00:03:06 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) symbolic constants. * acgeneral.m4, acoldnames.m4 (AC_INIT_PARSE_ARGS): Renamed from - AC_INIT_PARSEARGS. + AC_INIT_PARSEARGS. * autoupdate.sh: Use $SIMPLE_BACKUP_SUFFIX, if set. @@ -899,7 +1153,7 @@ Tue Aug 23 00:03:06 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) * Makefile.in (DISTFILES): Add it. * autoupdate.sh: Update the regexps to account for changes to - acoldnames.m4. + acoldnames.m4. Mon Aug 22 23:57:18 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) @@ -922,7 +1176,7 @@ Fri Aug 12 10:15:51 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) whether or not we found the program. (AC_CHECKING): Not obsolete. (AC_WITH, AC_ENABLE, AC_INIT_PREPARE): Merge the --enable and - --with diversions. + --with diversions. * acgeneral.m4 (AC_DEFUN): New macro. Use it globally to define macros that are used as functions, @@ -951,7 +1205,7 @@ Wed Aug 10 09:30:11 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) * acgeneral.m4 (AC_CACHE_LOAD, AC_CACHE_SAVE, AC_SITE_LOAD, AC_MSG_CHECKING): Aesthetic changes to messages, suggested by - Franc,ois Pinard. + Franc,ois Pinard. * acspecific.m4 acgeneral.m4 acoldnames.m4: Rename AC_TRY_CROSS to AC_C_CROSS. @@ -998,7 +1252,7 @@ Tue Aug 9 00:17:28 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) calls without parameters. * acgeneral.m4 (AC_CACHE_VAL): Omit the cache var name from the - result message. + result message. * acspecific.m4 (AC_DIR_HEADER): Define to be similar to AC_HEADER_DIRENT, but only define the old cpp macros. @@ -1011,7 +1265,7 @@ Tue Aug 9 00:17:28 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) * Makefile.in, testsuite/Makefile.in: Fix *clean targets. - * acgeneral.m4 (AC_CACHE_SAVE, AC_CACHE_LOAD, AC_SITE_LOAD): + * acgeneral.m4 (AC_CACHE_SAVE, AC_CACHE_LOAD, AC_SITE_LOAD): Use echo instead of AC_MSG_RESULT. (AC_INIT_PARSEARGS): Group options by topic in help message. Idea from Franc,ois Pinard. @@ -1028,7 +1282,7 @@ Tue Aug 2 19:54:26 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) * autoheader.sh: Read acoldnames.m4. Redefine the new macro names. Only define HAVE_LIBFOO where AC_CHECK_LIB is called with only one - argument. + argument. Sat Jul 30 09:53:38 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) @@ -1072,7 +1326,7 @@ Tue Jul 19 14:49:02 1994 David J. MacKenzie (djm@aria.eng.umd.edu) whether it's non-empty. * acspecific.m4 (AC_MINUS_C_MINUS_O, AC_SET_MAKE): Eval the cache var - assignments. + assignments. (AC_YYTEXT_POINTER): Fix typo. * testsuite/autoconf.s/specific.exp, @@ -1102,7 +1356,7 @@ Thu Jun 30 09:47:17 1994 David J. MacKenzie (djm@vortex.eng.umd.edu) * acgeneral.m4 (AC_OUTPUT_SUBDIRS): Pass correct --srcdir option to sub configures. Quote args containing spaces. (AC_PREPARE): Set and substitute `subdirs'. Quote args containing - spaces. + spaces. (AC_CANONICAL_HOST, AC_CANONICAL_TARGET, AC_CANONICAL_BUILD): Substitute the cpu, vendor, os variables. @@ -1254,7 +1508,7 @@ Wed May 18 09:08:39 1994 David J. MacKenzie (djm@burnout.eng.umd.edu) Tue May 17 15:18:00 1994 David J. MacKenzie (djm@bleen.eng.umd.edu) * acgeneral.m4 (AC_REVISION): Move quotes around to make it work - again. + again. Sat May 14 07:30:57 1994 David J. MacKenzie (djm@aria.eng.umd.edu) @@ -1275,8 +1529,8 @@ Mon May 9 08:20:14 1994 David J. MacKenzie (djm@aria.eng.umd.edu) * acgeneral.m4 (AC_TEST_PROGRAM): If no default for cross-compiling is given, but we are cross-compiling, give an error. - (AC_PROGRAM_EGREP, AC_TEST_LINK, AC_TEST_PROGRAM, AC_TEST_CPP): - Don't add an extra blank line after the if-clause. + (AC_PROGRAM_EGREP, AC_TEST_LINK, AC_TEST_PROGRAM, AC_TEST_CPP): + Don't add an extra blank line after the if-clause. (AC_REVISION): Merge AC_DOREV into this macro. Rename some macros: AC_SYSTEM_TYPE -> AC_CANON_SYSTEM @@ -1377,17 +1631,17 @@ Wed May 4 15:05:11 1994 David J. MacKenzie (djm@aria.eng.umd.edu) Checking for C features - derived (caching) * acgeneral.m4 (AC_CACHE_LOAD, AC_CACHE_SAVE, AC_CACHE_VAL): - New macros. + New macros. (AC_PREPARE): Call AC_CACHE_LOAD. (AC_OUTPUT): Call AC_CACHE_SAVE. (AC_PARSEARGS): Add --cache-file=FILE option. (AC_CONFIG_SUBDIRS): Pass --cache-file to subdirectory configures. * acgeneral.m4 (AC_OUTPUT_CONFIG_SUBDIRS): Renamed from - AC_CONFIG_SUBDIRS. + AC_CONFIG_SUBDIRS. (AC_CONFIG_SUBDIRS): Just define AC_SUBDIR_LIST. (AC_OUTPUT): Call AC_OUTPUT_CONFIG_SUBDIRS if AC_SUBDIR_LIST is - defined. + defined. Make config.status --recheck pass --norecursion to configure. * acspecific.m4 (AC_SETVBUF_REVERSED): Print "checking" message. diff --git a/src/util/autoconf/INSTALL b/src/util/autoconf/INSTALL index 95d84c820..a2c8722cc 100644 --- a/src/util/autoconf/INSTALL +++ b/src/util/autoconf/INSTALL @@ -95,6 +95,11 @@ give `configure' the option `--exec-prefix=PATH', the package will use PATH as the prefix for installing programs and libraries. Documentation and other data files will still use the regular prefix. + In addition, if you use an unusual directory layout you can give +options like `--bindir=PATH' to specify different values for particular +kinds of files. Run `configure --help' for a list of the directories +you can set and what kinds of files go in them. + If the package supports it, you can cause programs to be installed with an extra prefix or suffix on their names by giving `configure' the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. diff --git a/src/util/autoconf/Makefile.in b/src/util/autoconf/Makefile.in index 4066ce47c..29a69b6c2 100644 --- a/src/util/autoconf/Makefile.in +++ b/src/util/autoconf/Makefile.in @@ -29,8 +29,9 @@ M4 = @M4@ AWK = @AWK@ PERL = @PERL@ -# Programs that are always installed. +# Programs that are ALWAYS installed (and are created in the build dir). ASCRIPTS = autoconf autoheader autoreconf autoupdate ifnames +# All programs, including those only installed if you have perl. SCRIPTS = $(ASCRIPTS) @SCRIPTS@ transform=@program_transform_name@ @@ -39,14 +40,14 @@ prefix = @prefix@ exec_prefix = @exec_prefix@ # Directory in which to install scripts. -bindir = $(exec_prefix)/bin +bindir = @bindir@ # Directory in which to install library files. -datadir = $(prefix)/share +datadir = @datadir@ acdatadir = $(datadir)/autoconf # Directory in which to install documentation info files. -infodir = $(prefix)/info +infodir = @infodir@ #### End of system configuration section. #### @@ -75,7 +76,7 @@ editsh = sed -e 's,@''datadir''@,$(acdatadir),g' -e \ 's,@''M4''@,$(M4),g' -e 's,@''AWK''@,$(AWK),g' editpl = sed -e 's,@''datadir''@,$(acdatadir),g' -e 's,@''PERL''@,$(PERL),g' -all: ${SCRIPTS} +all: ${SCRIPTS} info .SUFFIXES: .SUFFIXES: .sh .pl diff --git a/src/util/autoconf/NEWS b/src/util/autoconf/NEWS index b5dd50c3a..aa01cad1f 100644 --- a/src/util/autoconf/NEWS +++ b/src/util/autoconf/NEWS @@ -1,3 +1,25 @@ +Major changes in release 2.10: + +* Bug fixes. +* The cache variable names used by `AC_CHECK_LIB(LIB, FUNC, ...)' has + changed: now $ac_cv_lib_LIB_FUNC, previously $ac_cv_lib_LIB. + +Major changes in releases 2.6 through 2.9: + +* Bug fixes. + +Major changes in release 2.5: + +* New configure options --bindir, --libdir, --datadir, etc., with + corresponding output variables. +* New macro: AC_CACHE_CHECK, to make using the cache easier. +* config.log contains the command being run as well as any output from it. +* AC_CHECK_LIB can check for libraries with "." or "/" or "+" in their name. +* AC_PROG_INSTALL doesn't cache a path to install-sh, for sharing caches. +* AC_CHECK_PROG, AC_PATH_PROG, AC_CHECK_PROGS, AC_PATH_PROGS, and + AC_CHECK_TOOL can search a path other than $PATH. +* AC_CHECK_SIZEOF takes an optional size to use when cross-compiling. + Major changes in release 2.4: * Fix a few bugs found by Emacs testers. @@ -131,7 +153,7 @@ Major changes in release 2.0: * Uses config.cache to cache test results. An alternate cache file can be selected with the --cache-file=FILE option. * Uses optional shell scripts $prefix/share/config.site and - $prefix/etc/config.site to perform site or system specific initializations. + $prefix/etc/config.site to perform site or system specific initializations. * configure saves compiler output to ./config.log for debugging. * New files autoconf.m4 and autoheader.m4 load the other Autoconf macros. * acsite.m4 is the new name for the system-wide aclocal.m4. @@ -257,9 +279,9 @@ Major changes in release 1.4: set the shell variables `gen_files' and `gen_config' to the list of filenames to output. * AC_DECLARE_YYTEXT does an AC_SUBST of `LEX_OUTPUT_ROOT', which may be - "lex.yy" or "lexyy", depending on the system. + "lex.yy" or "lexyy", depending on the system. * AC_PROGRAMS_CHECK takes an optional third arg. If given, it is used as - the default value. + the default value. * If AC_ALLOCA chooses alloca.c, it also defines STACK_DIRECTION. * AC_CONST works much more reliably on more systems. * Many bug fixes. diff --git a/src/util/autoconf/TODO b/src/util/autoconf/TODO index 0f757e0d9..819a50336 100644 --- a/src/util/autoconf/TODO +++ b/src/util/autoconf/TODO @@ -114,6 +114,10 @@ substitutions done on them. ------------------------------------------------------------------------------ Have AC_CANONICAL_* cache the host/build/target types. +They have to be overridden by the command line arguments, +just as for X includes and libraries. Should they be cached +all in one variable, or three? In that case, what if only one +or two of the cache variables are set? ------------------------------------------------------------------------------ @@ -134,16 +138,6 @@ From: "K. Berry" ------------------------------------------------------------------------------ -I would find it a wonderful boon if config.log contained not just the -output from the compilers, but also the invocation. Almost all -the errors I've found are due to the wrong options getting passed for -one reason or another. - -Saving the input test file(s) that failed would be useful, too. -From: "K. Berry" - ------------------------------------------------------------------------------- - The default of unlimited permission is fine, but there should be some easy way for configure to have copyright terms passed through from configure.in. Maybe AC_LICENSE([...]). @@ -219,7 +213,7 @@ From Roland McGrath. ls -lt configure configure.in | sort doesn't work right if configure.in is from a symlink farm, where the -symlink has either a timestamp of it's own, or under BSD 4.4, it has +symlink has either a timestamp of its own, or under BSD 4.4, it has the timestamp of the current directory, neither of which helps. Changing it to ls -Llt configure configure.in | sort @@ -261,8 +255,8 @@ From: Randall Winchester AC_C_CROSS assumes that configure was called like 'CC=target-gcc; ./configure'. I want to write a package -that has target dependend libraries and host dependend tools. So I -dont't like to lose the distinction between CC and [G]CC_FOR_TARGET. +that has target dependent libraries and host dependent tools. So I +don't like to lose the distinction between CC and [G]CC_FOR_TARGET. AC_C_CROSS should check for equality of target and host. It would be great if @@ -317,25 +311,6 @@ Make easy macros for checking for X functions and libraries. ------------------------------------------------------------------------------ -We probably shouldn't cache a path for INSTALL within a source -directory, because that will break other packages using the cache if -that directory is removed. - ------------------------------------------------------------------------------- - -Document this trick: - ->> Half my time these days seems to be spent porting ->> configure.in files to new OS releases.) Alas, there doesn't seem to ->> be any way to turn off caching (with a configure.in directive). - -define([AC_CACHE_LOAD], )dnl -define([AC_CACHE_SAVE], )dnl -AC_INIT(whatever) - ... rest of configure.in ... - ------------------------------------------------------------------------------- - Testing for ANSI header files (AC_HEADER_STDC) fails under linux when using the latest libraries (libc-4.6.30, at least libc-4.6.27 works ok) when LC_CTYPE is set to ISO-8859-1. The islower/toupper test @@ -347,22 +322,6 @@ From: tom@vlsivie.tuwien.ac.AT (Thomas Winder) ------------------------------------------------------------------------------ -A number of people have tried to fix configuration problems by editing -acconfig.h. (Despite comments at the top of the file.) I think they're -confused because anything.h looks like a regular source file name. -Maybe acconfig.h could be called acconfig.extra or something? -From: kb@cs.umb.edu (K. Berry) - ------------------------------------------------------------------------------- - -Using the macro AC_CHECK_LIB, if the library name contains a dot (which is -the case of the library complib.sgimath on Irix 5.x) a syntax error occurs -because the corresponding cache variable name contains a dot. -Should dots be converted to underlines in variable names by autoconf? -From: Frederic.DEvernay@sophia.inria.fr (Frederic Devernay) - ------------------------------------------------------------------------------- - * Test suite: more things to test: ** That the shell scripts produce correct output on some simple data. ** Configuration header files. That autoheader does the right thing, diff --git a/src/util/autoconf/acgeneral.m4 b/src/util/autoconf/acgeneral.m4 index 2ed88cdf5..f2ac545cd 100644 --- a/src/util/autoconf/acgeneral.m4 +++ b/src/util/autoconf/acgeneral.m4 @@ -1,7 +1,7 @@ dnl Parameterized macros. dnl Requires GNU m4. dnl This file is part of Autoconf. -dnl Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +dnl Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. dnl dnl This program is free software; you can redistribute it and/or modify dnl it under the terms of the GNU General Public License as published by @@ -51,7 +51,7 @@ dnl divert(-1)dnl Throw away output until AC_INIT is called. changequote([, ]) -define(AC_ACVERSION, 2.4) +define(AC_ACVERSION, 2.10) dnl Some old m4's don't support m4exit. But they provide dnl equivalent functionality by core dumping because of the @@ -130,7 +130,7 @@ dnl it will bring back all the code accumulated in the diversion stack. dnl This, combined with AC_REQUIRE, achieves the topological ordering of dnl macros. We don't use this macro to define some frequently called dnl macros that are not involved in ordering constraints, to save m4 -dnl processing. +dnl processing. dnl AC_DEFUN(NAME, EXPANSION) define([AC_DEFUN], [define($1, [AC_PRO([$1])$2[]AC_EPI()])]) @@ -143,7 +143,7 @@ dnl AC_INIT_NOTICE() AC_DEFUN(AC_INIT_NOTICE, [# Guess values for system-dependent variables and create Makefiles. # Generated automatically using autoconf version] AC_ACVERSION [ -# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. +# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. # # This configure script is free software; the Free Software Foundation # gives unlimited permission to copy, distribute and modify it. @@ -183,9 +183,23 @@ target=NONE verbose= x_includes=NONE x_libraries=NONE +dnl Installation directory options. +bindir='${exec_prefix}/bin' +sbindir='${exec_prefix}/sbin' +libexecdir='${exec_prefix}/libexec' +datadir='${prefix}/share' +sysconfdir='${prefix}/etc' +sharedstatedir='${prefix}/com' +localstatedir='${prefix}/var' +libdir='${exec_prefix}/lib' +includedir='${prefix}/include' +oldincludedir='/usr/include' +infodir='${prefix}/info' +mandir='${prefix}/man' # Initialize some other variables. subdirs= +MFLAGS= MAKEFLAGS= ac_prev= for ac_option @@ -209,9 +223,14 @@ changequote([, ])dnl case "$ac_option" in - -build | --build | --buil | --bui | --bu | --b) + -bindir | --bindir | --bindi | --bind | --bin | --bi) + ac_prev=bindir ;; + -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) + bindir="$ac_optarg" ;; + + -build | --build | --buil | --bui | --bu) ac_prev=build ;; - -build=* | --build=* | --buil=* | --bui=* | --bu=* | --b=*) + -build=* | --build=* | --buil=* | --bui=* | --bu=*) build="$ac_optarg" ;; -cache-file | --cache-file | --cache-fil | --cache-fi \ @@ -221,6 +240,12 @@ changequote([, ])dnl | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) cache_file="$ac_optarg" ;; + -datadir | --datadir | --datadi | --datad | --data | --dat | --da) + ac_prev=datadir ;; + -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ + | --da=*) + datadir="$ac_optarg" ;; + -disable-* | --disable-*) ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` # Reject names that are not valid shell variable names. @@ -276,12 +301,29 @@ Configuration: Directory and file names: --prefix=PREFIX install architecture-independent files in PREFIX [$ac_default_prefix] - --exec-prefix=PREFIX install architecture-dependent files in PREFIX + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX [same as prefix] + --bindir=DIR user executables in DIR [EPREFIX/bin] + --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] + --libexecdir=DIR program executables in DIR [EPREFIX/libexec] + --datadir=DIR read-only architecture-independent data in DIR + [PREFIX/share] + --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] + --sharedstatedir=DIR modifiable architecture-independent data in DIR + [PREFIX/com] + --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] + --libdir=DIR object code libraries in DIR [EPREFIX/lib] + --includedir=DIR C header files in DIR [PREFIX/include] + --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] + --infodir=DIR info documentation in DIR [PREFIX/info] + --mandir=DIR man documentation in DIR [PREFIX/man] --srcdir=DIR find the sources in DIR [configure dir or ..] --program-prefix=PREFIX prepend PREFIX to installed program names --program-suffix=SUFFIX append SUFFIX to installed program names - --program-transform-name=PROGRAM run sed PROGRAM on installed program names + --program-transform-name=PROGRAM + run sed PROGRAM on installed program names +EOF + cat << EOF Host type: --build=BUILD configure for building on BUILD [BUILD=HOST] --host=HOST configure for HOST [guessed] @@ -293,9 +335,11 @@ Features and packages: --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) --x-includes=DIR X include files are in DIR --x-libraries=DIR X library files are in DIR ---enable and --with options recognized:$ac_help changequote([, ])dnl EOF + if test -n "$ac_help"; then + echo "--enable and --with options recognized:$ac_help" + fi exit 0 ;; -host | --host | --hos | --ho) @@ -303,6 +347,44 @@ EOF -host=* | --host=* | --hos=* | --ho=*) host="$ac_optarg" ;; + -includedir | --includedir | --includedi | --included | --include \ + | --includ | --inclu | --incl | --inc) + ac_prev=includedir ;; + -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ + | --includ=* | --inclu=* | --incl=* | --inc=*) + includedir="$ac_optarg" ;; + + -infodir | --infodir | --infodi | --infod | --info | --inf) + ac_prev=infodir ;; + -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) + infodir="$ac_optarg" ;; + + -libdir | --libdir | --libdi | --libd) + ac_prev=libdir ;; + -libdir=* | --libdir=* | --libdi=* | --libd=*) + libdir="$ac_optarg" ;; + + -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ + | --libexe | --libex | --libe) + ac_prev=libexecdir ;; + -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ + | --libexe=* | --libex=* | --libe=*) + libexecdir="$ac_optarg" ;; + + -localstatedir | --localstatedir | --localstatedi | --localstated \ + | --localstate | --localstat | --localsta | --localst \ + | --locals | --local | --loca | --loc | --lo) + ac_prev=localstatedir ;; + -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ + | --localstate=* | --localstat=* | --localsta=* | --localst=* \ + | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) + localstatedir="$ac_optarg" ;; + + -mandir | --mandir | --mandi | --mand | --man | --ma | --m) + ac_prev=mandir ;; + -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) + mandir="$ac_optarg" ;; + -nfp | --nfp | --nf) # Obsolete; use --without-fp. with_fp=no ;; @@ -315,6 +397,15 @@ EOF | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) no_recursion=yes ;; + -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ + | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ + | --oldin | --oldi | --old | --ol | --o) + ac_prev=oldincludedir ;; + -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ + | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ + | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) + oldincludedir="$ac_optarg" ;; + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) ac_prev=prefix ;; -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) @@ -355,6 +446,23 @@ EOF | -silent | --silent | --silen | --sile | --sil) silent=yes ;; + -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) + ac_prev=sbindir ;; + -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ + | --sbi=* | --sb=*) + sbindir="$ac_optarg" ;; + + -sharedstatedir | --sharedstatedir | --sharedstatedi \ + | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ + | --sharedst | --shareds | --shared | --share | --shar \ + | --sha | --sh) + ac_prev=sharedstatedir ;; + -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ + | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ + | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ + | --sha=* | --sh=*) + sharedstatedir="$ac_optarg" ;; + -site | --site | --sit) ac_prev=site ;; -site=* | --site=* | --sit=*) @@ -365,6 +473,13 @@ EOF -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) srcdir="$ac_optarg" ;; + -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ + | --syscon | --sysco | --sysc | --sys | --sy) + ac_prev=sysconfdir ;; + -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ + | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) + sysconfdir="$ac_optarg" ;; + -target | --target | --targe | --targ | --tar | --ta | --t) ac_prev=target ;; -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) @@ -424,7 +539,7 @@ changequote([, ])dnl -*) AC_MSG_ERROR([$ac_option: invalid option; use --help to show usage]) ;; - *) + *) changequote(, )dnl if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then changequote([, ])dnl @@ -570,6 +685,19 @@ AC_SUBST(LIBS)dnl AC_SUBST(exec_prefix)dnl AC_SUBST(prefix)dnl AC_SUBST(program_transform_name)dnl +dnl Installation directory options. +AC_SUBST(bindir)dnl +AC_SUBST(sbindir)dnl +AC_SUBST(libexecdir)dnl +AC_SUBST(datadir)dnl +AC_SUBST(sysconfdir)dnl +AC_SUBST(sharedstatedir)dnl +AC_SUBST(localstatedir)dnl +AC_SUBST(libdir)dnl +AC_SUBST(includedir)dnl +AC_SUBST(oldincludedir)dnl +AC_SUBST(infodir)dnl +AC_SUBST(mandir)dnl ]) @@ -583,8 +711,8 @@ ac_help="$ac_help [$2]" AC_DIVERT_POP()dnl [#] Check whether --enable-[$1] or --disable-[$1] was given. -enableval="[$enable_]patsubst([$1], -, _)" -if test -n "$enableval"; then +if test "[${enable_]patsubst([$1], -, _)+set}" = set; then + enableval="[$enable_]patsubst([$1], -, _)" ifelse([$3], , :, [$3]) ifelse([$4], , , [else $4 @@ -608,8 +736,8 @@ ac_help="$ac_help [$2]" AC_DIVERT_POP()dnl [#] Check whether --with-[$1] or --without-[$1] was given. -withval="[$with_]patsubst([$1], -, _)" -if test -n "$withval"; then +if test "[${with_]patsubst([$1], -, _)+set}" = set; then + withval="[$with_]patsubst([$1], -, _)" ifelse([$3], , :, [$3]) ifelse([$4], , , [else $4 @@ -631,8 +759,10 @@ AC_DEFUN(AC_ARG_PROGRAM, [if test "$program_transform_name" = s,x,x,; then program_transform_name= else - # Double any \ or $. - echo 's,\\,\\\\,g; s,\$,$$,g' > conftestsed + # Double any \ or $. echo might interpret backslashes. + cat <<\EOF_SED > conftestsed +s,\\,\\\\,g; s,\$,$$,g +EOF_SED program_transform_name="`echo $program_transform_name|sed -f conftestsed`" rm -f conftestsed fi @@ -736,7 +866,7 @@ AC_BEFORE([$0], [AC_ARG_PROGRAM]) # # The rules are: # 1. You are not allowed to specify --host, --target, and nonopt at the -# same time. +# same time. # 2. Host defaults to nonopt. # 3. If nonopt is not specified, then host defaults to the current host, # as determined by config.guess. @@ -940,6 +1070,12 @@ else fi ]) +dnl AC_CACHE_CHECK(MESSAGE, CACHE-ID, COMMANDS) +define(AC_CACHE_CHECK, +[AC_MSG_CHECKING([$1]) +AC_CACHE_VAL([$2], [$3]) +AC_MSG_RESULT([$]$2)]) + dnl ### Defining symbols @@ -1023,8 +1159,8 @@ AC_DEFUN(AC_LANG_C, ac_ext=c # CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. ac_cpp='$CPP $CPPFLAGS' -ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC 2>&AC_FD_CC' -ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC 2>&AC_FD_CC' +ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC' +ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC' ]) dnl AC_LANG_CPLUSPLUS() @@ -1033,8 +1169,8 @@ AC_DEFUN(AC_LANG_CPLUSPLUS, ac_ext=C # CXXFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. ac_cpp='$CXXCPP $CPPFLAGS' -ac_compile='${CXX-g++} -c $CXXFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC 2>&AC_FD_CC' -ac_link='${CXX-g++} -o conftest $CXXFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC 2>&AC_FD_CC' +ac_compile='${CXX-g++} -c $CXXFLAGS $CPPFLAGS conftest.$ac_ext 1>&AC_FD_CC' +ac_link='${CXX-g++} -o conftest $CXXFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&AC_FD_CC' ]) dnl Push the current language on a stack. @@ -1048,6 +1184,21 @@ define(AC_LANG_RESTORE, [ifelse(AC_LANG_STACK, C, [ifelse(AC_LANG, C, , [AC_LANG_C])], [ifelse(AC_LANG, CPLUSPLUS, , [AC_LANG_CPLUSPLUS])])[]popdef([AC_LANG_STACK])]) +dnl ### Compiler-running mechanics + + +dnl The purpose of this macro is to "configure:123: command line" +dnl written into config.log for every test run. +dnl AC_TRY_EVAL(VARIABLE) +AC_DEFUN(AC_TRY_EVAL, +[{ (eval echo configure:__oline__: \"[$]$1\") 1>&AC_FD_CC; dnl +(eval [$]$1) 2>&AC_FD_CC; }]) + +dnl AC_TRY_COMMAND(COMMAND) +AC_DEFUN(AC_TRY_COMMAND, +[{ ac_try='$1'; AC_TRY_EVAL(ac_try); }]) + + dnl ### Dependencies between macros @@ -1078,7 +1229,7 @@ dnl ### Checking for programs dnl AC_CHECK_PROG(VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND -dnl [, VALUE-IF-NOT-FOUND]) +dnl [, [VALUE-IF-NOT-FOUND] [, [PATH] [, [REJECT]]]]) AC_DEFUN(AC_CHECK_PROG, [# Extract the first word of "$2", so it can be a program name with args. set dummy $2; ac_word=[$]2 @@ -1088,14 +1239,43 @@ AC_CACHE_VAL(ac_cv_prog_$1, ac_cv_prog_$1="[$]$1" # Let the user override the test. else IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" - for ac_dir in $PATH; do +ifelse([$6], , , [ ac_prog_rejected=no +])dnl + for ac_dir in ifelse([$5], , $PATH, [$5]); do test -z "$ac_dir" && ac_dir=. if test -f $ac_dir/$ac_word; then +ifelse([$6], , , dnl +[ if test "[$ac_dir/$ac_word]" = "$6"; then + ac_prog_rejected=yes + continue + fi +])dnl ac_cv_prog_$1="$3" break fi done IFS="$ac_save_ifs" +ifelse([$6], , , [if test $ac_prog_rejected = yes; then + # We found a bogon in the path, so make sure we never use it. + set dummy [$]ac_cv_prog_$1 + shift + if test [$]# -gt 0; then + # We chose a different compiler from the bogus one. + # However, it has the same basename, so the bogon will be chosen + # first if we set $1 to just the basename; use the full file name. + shift + set dummy "$ac_dir/$ac_word" "[$]@" + shift + ac_cv_prog_$1="[$]@" +ifelse([$2], [$4], dnl +[ else + # Default is a loser. + AC_MSG_ERROR([$1=$6 unacceptable, but no other $4 found in dnl +ifelse([$5], , [\$]PATH, [$5])]) +])dnl + fi +fi +])dnl dnl If no 4th arg is given, leave the cache variable unset, dnl so AC_CHECK_PROGS will keep looking. ifelse([$4], , , [ test -z "[$]ac_cv_prog_$1" && ac_cv_prog_$1="$4" @@ -1110,7 +1290,7 @@ fi AC_SUBST($1)dnl ]) -dnl AC_PATH_PROG(VARIABLE, PROG-TO-CHECK-FOR [, VALUE-IF-NOT-FOUND]) +dnl AC_PATH_PROG(VARIABLE, PROG-TO-CHECK-FOR [, VALUE-IF-NOT-FOUND [, PATH]]) AC_DEFUN(AC_PATH_PROG, [# Extract the first word of "$2", so it can be a program name with args. set dummy $2; ac_word=[$]2 @@ -1122,7 +1302,7 @@ AC_CACHE_VAL(ac_cv_path_$1, ;; *) IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" - for ac_dir in $PATH; do + for ac_dir in ifelse([$4], , $PATH, [$4]); do test -z "$ac_dir" && ac_dir=. if test -f $ac_dir/$ac_word; then ac_cv_path_$1="$ac_dir/$ac_word" @@ -1145,21 +1325,23 @@ fi AC_SUBST($1)dnl ]) -dnl AC_CHECK_PROGS(VARIABLE, PROGS-TO-CHECK-FOR [, VALUE-IF-NOT-FOUND]) +dnl AC_CHECK_PROGS(VARIABLE, PROGS-TO-CHECK-FOR [, VALUE-IF-NOT-FOUND +dnl [, PATH]]) AC_DEFUN(AC_CHECK_PROGS, [for ac_prog in $2 do -AC_CHECK_PROG($1, [$]ac_prog, [$]ac_prog, ) +AC_CHECK_PROG($1, [$]ac_prog, [$]ac_prog, , $4) test -n "[$]$1" && break done ifelse([$3], , , [test -n "[$]$1" || $1="$3" ])]) -dnl AC_PATH_PROGS(VARIABLE, PROGS-TO-CHECK-FOR [, VALUE-IF-NOT-FOUND]) +dnl AC_PATH_PROGS(VARIABLE, PROGS-TO-CHECK-FOR [, VALUE-IF-NOT-FOUND +dnl [, PATH]]) AC_DEFUN(AC_PATH_PROGS, [for ac_prog in $2 do -AC_PATH_PROG($1, [$]ac_prog) +AC_PATH_PROG($1, [$]ac_prog, , $4) test -n "[$]$1" && break done ifelse([$3], , , [test -n "[$]$1" || $1="$3" @@ -1175,11 +1357,11 @@ else fi ]) -dnl AC_CHECK_TOOL(VARIABLE, PROG-TO-CHECK-FOR[, VALUE-IF-NOT-FOUND]) +dnl AC_CHECK_TOOL(VARIABLE, PROG-TO-CHECK-FOR[, VALUE-IF-NOT-FOUND [, PATH]]) AC_DEFUN(AC_CHECK_TOOL, [AC_REQUIRE([AC_CHECK_TOOL_PREFIX])dnl -AC_CHECK_PROG($1, ${ac_tool_prefix}$2, ${ac_tool_prefix}$2, - ifelse([$3], , [$2], )) +AC_CHECK_PROG($1, ${ac_tool_prefix}$2, ${ac_tool_prefix}$2, + ifelse([$3], , [$2], ), $4) ifelse([$3], , , [ if test -z "$ac_cv_prog_$1"; then if test -n "$ac_tool_prefix"; then @@ -1222,17 +1404,35 @@ dnl AC_CHECK_LIB(LIBRARY, FUNCTION [, ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND dnl [, OTHER-LIBRARIES]]]) AC_DEFUN(AC_CHECK_LIB, [AC_MSG_CHECKING([for -l$1]) -AC_CACHE_VAL(ac_cv_lib_$1, +dnl Use a cache variable name containing both the library and function name, +dnl because the test really is for library $1 defining function $2, not +dnl just for library $1. Separate tests with the same $1 and different $2s +dnl may have different results. +ac_lib_var=`echo $1['_']$2 | tr './+\055' '__p_'` +AC_CACHE_VAL(ac_cv_lib_$ac_lib_var, [ac_save_LIBS="$LIBS" LIBS="-l$1 $5 $LIBS" -AC_TRY_LINK(, [$2()], eval "ac_cv_lib_$1=yes", eval "ac_cv_lib_$1=no")dnl +AC_TRY_LINK(dnl +ifelse([$2], [main], , dnl Avoid conflicting decl of main. +[/* Override any gcc2 internal prototype to avoid an error. */ +]ifelse(AC_LANG, CPLUSPLUS, [#ifdef __cplusplus +extern "C" +#endif +])dnl +[/* We use char because int might match the return type of a gcc2 + builtin and then its argument prototype would still apply. */ +char $2(); +]), + [$2()], + eval "ac_cv_lib_$ac_lib_var=yes", + eval "ac_cv_lib_$ac_lib_var=no")dnl LIBS="$ac_save_LIBS" ])dnl -if eval "test \"`echo '$ac_cv_lib_'$1`\" = yes"; then +if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes"; then AC_MSG_RESULT(yes) - ifelse([$3], , + ifelse([$3], , [changequote(, )dnl - ac_tr_lib=HAVE_LIB`echo $1 | tr '[a-z]' '[A-Z]'` + ac_tr_lib=HAVE_LIB`echo $1 | tr 'abcdefghijklmnopqrstuvwxyz' 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'` changequote([, ])dnl AC_DEFINE_UNQUOTED($ac_tr_lib) LIBS="-l$1 $LIBS" @@ -1262,7 +1462,7 @@ LIBS="$ac_save_LIBS" ])dnl AC_MSG_RESULT($AC_CV_NAME) if test "$AC_CV_NAME" = yes; then - ifelse([$2], , + ifelse([$2], , [AC_DEFINE([HAVE_LIB]translit(AC_LIB_NAME, [a-z], [A-Z])) LIBS="-l[]AC_LIB_NAME[] $LIBS" ], [$2]) @@ -1278,7 +1478,7 @@ undefine([AC_CV_NAME])dnl dnl ### Examining declarations -dnl AC_TRY_CPP(INCLUDES, ACTION-IF-TRUE [, ACTION-IF-FALSE]) +dnl AC_TRY_CPP(INCLUDES, [ACTION-IF-TRUE [, ACTION-IF-FALSE]]) AC_DEFUN(AC_TRY_CPP, [AC_REQUIRE_CPP()dnl cat > conftest.$ac_ext </dev/null 2>conftest.out" +ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out" +AC_TRY_EVAL(ac_try) ac_err=`grep -v '^ *+' conftest.out` if test -z "$ac_err"; then ifelse([$2], , :, [rm -rf conftest* @@ -1310,8 +1511,8 @@ AC_DEFUN(AC_EGREP_HEADER, dnl Because this macro is used by AC_PROG_GCC_TRADITIONAL, which must dnl come early, it is not included in AC_BEFORE checks. -dnl AC_EGREP_CPP(PATTERN, PROGRAM, ACTION-IF-FOUND [, -dnl ACTION-IF-NOT-FOUND]) +dnl AC_EGREP_CPP(PATTERN, PROGRAM, [ACTION-IF-FOUND [, +dnl ACTION-IF-NOT-FOUND]]) AC_DEFUN(AC_EGREP_CPP, [AC_REQUIRE_CPP()dnl cat > conftest.$ac_ext < conftest.$ac_ext < conftest.$ac_ext </dev/null; then ifelse([$2], , :, [$2]) ifelse([$3], , , [else @@ -1438,7 +1639,7 @@ rm -fr conftest*]) dnl ### Checking for header files -dnl AC_CHECK_HEADER(HEADER-FILE, ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]) +dnl AC_CHECK_HEADER(HEADER-FILE, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]) AC_DEFUN(AC_CHECK_HEADER, [dnl Do the transliteration at runtime so arg 1 can be a shell variable. ac_safe=`echo "$1" | tr './\055' '___'` @@ -1462,7 +1663,7 @@ AC_DEFUN(AC_CHECK_HEADERS, do AC_CHECK_HEADER($ac_hdr, [changequote(, )dnl - ac_tr_hdr=HAVE_`echo $ac_hdr | tr '[a-z]./\055' '[A-Z]___'` + ac_tr_hdr=HAVE_`echo $ac_hdr | tr 'abcdefghijklmnopqrstuvwxyz./\055' 'ABCDEFGHIJKLMNOPQRSTUVWXYZ___'` changequote([, ])dnl AC_DEFINE_UNQUOTED($ac_tr_hdr) $2], $3)dnl done @@ -1472,7 +1673,7 @@ done dnl ### Checking for library functions -dnl AC_CHECK_FUNC(FUNCTION, ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]) +dnl AC_CHECK_FUNC(FUNCTION, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]) AC_DEFUN(AC_CHECK_FUNC, [AC_MSG_CHECKING([for $1]) AC_CACHE_VAL(ac_cv_func_$1, @@ -1488,7 +1689,9 @@ dnl select. Similarly for bzero. extern "C" #endif ])dnl -[char $1(); +[/* We use char because int might match the return type of a gcc2 + builtin and then its argument prototype would still apply. */ +char $1(); ], [ /* The GNU C library defines this for functions which it implements to always fail with ENOSYS. Some functions are actually named @@ -1515,7 +1718,7 @@ AC_DEFUN(AC_CHECK_FUNCS, do AC_CHECK_FUNC($ac_func, [changequote(, )dnl - ac_tr_func=HAVE_`echo $ac_func | tr '[a-z]' '[A-Z]'` + ac_tr_func=HAVE_`echo $ac_func | tr 'abcdefghijklmnopqrstuvwxyz' 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'` changequote([, ])dnl AC_DEFINE_UNQUOTED($ac_tr_func) $2], $3)dnl done @@ -1534,7 +1737,7 @@ AC_SUBST(LIBOBJS)dnl dnl ### Checking compiler characteristics -dnl AC_CHECK_SIZEOF(TYPE) +dnl AC_CHECK_SIZEOF(TYPE [, CROSS-SIZE]) AC_DEFUN(AC_CHECK_SIZEOF, [changequote(<<, >>)dnl dnl The name to #define. @@ -1551,7 +1754,7 @@ main() if (!f) exit(1); fprintf(f, "%d\n", sizeof($1)); exit(0); -}], AC_CV_NAME=`cat conftestval`, AC_CV_NAME=0)])dnl +}], AC_CV_NAME=`cat conftestval`, AC_CV_NAME=0, ifelse([$2], , , AC_CV_NAME=$2))])dnl AC_MSG_RESULT($AC_CV_NAME) AC_DEFINE_UNQUOTED(AC_TYPE_NAME, $AC_CV_NAME) undefine([AC_TYPE_NAME])dnl @@ -1670,11 +1873,13 @@ ifdef(<>, <>, <>) changequote([, ])dnl +EOF +cat >> $CONFIG_STATUS <> $CONFIG_STATUS < conftest.defs <<\EOF changequote(<<, >>)dnl -s%<<#define>> \([A-Za-z_][A-Za-z0-9_]*\) \(.*\)%-D\1=\2%g +s%<<#define>> \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g s%[ `~<<#>>$^&*(){}\\|;'"<>?]%\\&%g s%\[%\\&%g s%\]%\\&%g @@ -1715,10 +1920,10 @@ dnl This is a subroutine of AC_OUTPUT. It is called inside an unquoted dnl here document whose contents are going into config.status. dnl AC_OUTPUT_FILES(FILE...) define(AC_OUTPUT_FILES, -[# Protect against being on the right side of a sed subst in config.status. +[# Protect against being on the right side of a sed subst in config.status. changequote(, )dnl -sed 's/%@/@@/; s/@%/@@/; s/%g$/@g/; /@g$/s/[\\\\&%]/\\\\&/g; - s/@@/%@/; s/@@/@%/; s/@g$/%g/' > conftest.subs <<\CEOF +sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; + s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF changequote([, ])dnl dnl These here document variables are unquoted when configure runs dnl but quoted when config.status runs, so variables are expanded once. @@ -1795,6 +2000,14 @@ s%@top_srcdir@%$top_srcdir%g ifdef([AC_PROVIDE_AC_PROG_INSTALL], [s%@INSTALL@%$INSTALL%g ])dnl " -f conftest.subs $ac_given_srcdir/$ac_file_in > $ac_file +dnl This would break Makefile dependencies. +dnl if cmp -s $ac_file conftest.out 2>/dev/null; then +dnl echo "$ac_file is unchanged" +dnl rm -f conftest.out +dnl else +dnl rm -f $ac_file +dnl mv conftest.out $ac_file +dnl fi fi; done rm -f conftest.subs ]) @@ -1842,7 +2055,7 @@ EOF # Transform confdefs.h into a sed script conftest.vals that substitutes # the proper values into config.h.in to produce config.h. And first: -# Protect against being on the right side of a sed subst in config.status. +# Protect against being on the right side of a sed subst in config.status. # Protect against being in an unquoted here document in config.status. rm -f conftest.vals dnl Using a here document instead of a string reduces the quoting nightmare. @@ -1851,7 +2064,7 @@ cat > conftest.hdr <<\EOF changequote(<<, >>)dnl s/[\\&%]/\\&/g s%[\\$`]%\\&%g -s%<<#define>> \([A-Za-z_][A-Za-z0-9_]*\) \(.*\)%${ac_dA}\1${ac_dB}\1${ac_dC}\2${ac_dD}%gp +s%<<#define>> \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%${ac_dA}\1${ac_dB}\1${ac_dC}\2${ac_dD}%gp s%ac_d%ac_u%gp s%ac_u%ac_e%gp changequote([, ])dnl @@ -1903,6 +2116,14 @@ cat >> $CONFIG_STATUS <<\EOF echo "$ac_file is unchanged" rm -f conftest.h else + # Remove last slash and all that follows it. Not all systems have dirname. + changequote(, )dnl + ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` + changequote([, ])dnl + if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then + # The file is in a subdirectory. + test ! -d "$ac_dir" && mkdir "$ac_dir" + fi rm -f $ac_file mv conftest.h $ac_file fi diff --git a/src/util/autoconf/acspecific.m4 b/src/util/autoconf/acspecific.m4 index e48e42f46..0182dfd17 100644 --- a/src/util/autoconf/acspecific.m4 +++ b/src/util/autoconf/acspecific.m4 @@ -1,6 +1,6 @@ dnl Macros that test for specific features. dnl This file is part of Autoconf. -dnl Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +dnl Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. dnl dnl This program is free software; you can redistribute it and/or modify dnl it under the terms of the GNU General Public License as published by @@ -71,27 +71,28 @@ fi AC_DEFUN(AC_PROG_CC, [AC_BEFORE([$0], [AC_PROG_CPP])dnl -AC_CHECK_PROG(CC, gcc, gcc, cc) +AC_CHECK_PROG(CC, gcc, gcc) +if test -z "$CC"; then + AC_CHECK_PROG(CC, cc, cc, , , /usr/ucb/cc) + test -z "$CC" && AC_MSG_ERROR([no acceptable cc found in \$PATH]) +fi -AC_MSG_CHECKING(whether we are using GNU C) -AC_CACHE_VAL(ac_cv_prog_gcc, +AC_CACHE_CHECK(whether we are using GNU C, ac_cv_prog_gcc, [dnl The semicolon is to pacify NeXT's syntax-checking cpp. cat > conftest.c <&AC_FD_CC | egrep yes >/dev/null 2>&1; then +if AC_TRY_COMMAND(${CC-cc} -E conftest.c) | egrep yes >/dev/null 2>&1; then ac_cv_prog_gcc=yes else ac_cv_prog_gcc=no -fi])dnl -AC_MSG_RESULT($ac_cv_prog_gcc) +fi]) if test $ac_cv_prog_gcc = yes; then GCC=yes if test "${CFLAGS+set}" != set; then - AC_MSG_CHECKING(whether ${CC-cc} accepts -g) -AC_CACHE_VAL(ac_cv_prog_gcc_g, + AC_CACHE_CHECK(whether ${CC-cc} accepts -g, ac_cv_prog_gcc_g, [echo 'void f(){}' > conftest.c if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then ac_cv_prog_gcc_g=yes @@ -99,8 +100,7 @@ else ac_cv_prog_gcc_g=no fi rm -f conftest* -])dnl - AC_MSG_RESULT($ac_cv_prog_gcc_g) +]) if test $ac_cv_prog_gcc_g = yes; then CFLAGS="-g -O" else @@ -117,25 +117,22 @@ AC_DEFUN(AC_PROG_CXX, [AC_BEFORE([$0], [AC_PROG_CXXCPP])dnl AC_CHECK_PROGS(CXX, $CCC c++ g++ gcc CC cxx, gcc) -AC_MSG_CHECKING(whether we are using GNU C++) -AC_CACHE_VAL(ac_cv_prog_gxx, +AC_CACHE_CHECK(whether we are using GNU C++, ac_cv_prog_gxx, [dnl The semicolon is to pacify NeXT's syntax-checking cpp. cat > conftest.C <&AC_FD_CC | egrep yes >/dev/null 2>&1; then +if AC_TRY_COMMAND(${CXX-g++} -E conftest.C) | egrep yes >/dev/null 2>&1; then ac_cv_prog_gxx=yes else ac_cv_prog_gxx=no -fi])dnl -AC_MSG_RESULT($ac_cv_prog_gxx) +fi]) if test $ac_cv_prog_gxx = yes; then GXX=yes if test "${CXXFLAGS+set}" != set; then - AC_MSG_CHECKING(whether ${CXX-g++} accepts -g) -AC_CACHE_VAL(ac_cv_prog_gxx_g, + AC_CACHE_CHECK(whether ${CXX-g++} accepts -g, ac_cv_prog_gxx_g, [echo 'void f(){}' > conftest.cc if test -z "`${CXX-g++} -g -c conftest.cc 2>&1`"; then ac_cv_prog_gxx_g=yes @@ -143,8 +140,8 @@ else ac_cv_prog_gxx_g=no fi rm -f conftest* -])dnl - AC_MSG_RESULT($ac_cv_prog_gxx_g) +]) +dnl if test $ac_cv_prog_gxx_g = yes; then CXXFLAGS="-g -O" else @@ -161,8 +158,8 @@ AC_DEFUN(AC_PROG_GCC_TRADITIONAL, [AC_REQUIRE([AC_PROG_CC])dnl AC_REQUIRE([AC_PROG_CPP])dnl if test $ac_cv_prog_gcc = yes; then - AC_MSG_CHECKING(whether ${CC-cc} needs -traditional) -AC_CACHE_VAL(ac_cv_prog_gcc_traditional, + AC_CACHE_CHECK(whether ${CC-cc} needs -traditional, + ac_cv_prog_gcc_traditional, [ ac_pattern="Autoconf.*'x'" AC_EGREP_CPP($ac_pattern, [#include Autoconf TIOCGETP], @@ -172,8 +169,7 @@ Autoconf TIOCGETP], AC_EGREP_CPP($ac_pattern, [#include Autoconf TCGETA], ac_cv_prog_gcc_traditional=yes) - fi])dnl - AC_MSG_RESULT($ac_cv_prog_gcc_traditional) + fi]) if test $ac_cv_prog_gcc_traditional = yes; then CC="$CC -traditional" fi @@ -186,30 +182,37 @@ AC_DEFUN(AC_PROG_CC_C_O, else AC_MSG_CHECKING(whether cc understands -c and -o together) fi -set dummy $CC; ac_cc="`echo [$]2 | +set dummy $CC; ac_cc="`echo [$]2 | changequote(, )dnl sed -e 's/[^a-zA-Z0-9_]/_/g' -e 's/^[0-9]/_/'`" changequote([, ])dnl AC_CACHE_VAL(ac_cv_prog_cc_${ac_cc}_c_o, -[eval ac_cv_prog_cc_${ac_cc}_c_o=no -echo 'foo(){}' > conftest.c +[echo 'foo(){}' > conftest.c # Make sure it works both with $CC and with simple cc. # We do the test twice because some compilers refuse to overwrite an # existing .o file with -o, though they will create one. -if ${CC-cc} -c conftest.c -o conftest.o 1>&AC_FD_CC 2>&AC_FD_CC && - test -f conftest.o && ${CC-cc} -c conftest.c -o conftest.o 1>&AC_FD_CC 2>&AC_FD_CC +ac_try='${CC-cc} -c conftest.c -o conftest.o 1>&AC_FD_CC' +if AC_TRY_EVAL(ac_try) && + test -f conftest.o && AC_TRY_EVAL(ac_try); then + eval ac_cv_prog_cc_${ac_cc}_c_o=yes if test "x$CC" != xcc; then # Test first that cc exists at all. - if cc -c conftest.c 1>&AC_FD_CC 2>&AC_FD_CC - then - if cc -c conftest.c -o conftest2.o 1>&AC_FD_CC 2>&AC_FD_CC && - test -f conftest2.o && cc -c conftest.c -o conftest2.o 1>&AC_FD_CC 2>&AC_FD_CC + if AC_TRY_COMMAND(cc -c conftest.c 1>&AC_FD_CC); then + ac_try='cc -c conftest.c -o conftest.o 1>&AC_FD_CC' + if AC_TRY_EVAL(ac_try) && + test -f conftest.o && AC_TRY_EVAL(ac_try); then - eval ac_cv_prog_cc_${ac_cc}_c_o=yes + # cc works too. + : + else + # cc exists but doesn't like -o. + eval ac_cv_prog_cc_${ac_cc}_c_o=no fi fi fi +else + eval ac_cv_prog_cc_${ac_cc}_c_o=no fi rm -f conftest* ])dnl @@ -327,8 +330,7 @@ undefine([AC_DECL_YYTEXT]) AC_DEFUN(AC_DECL_YYTEXT, [AC_REQUIRE_CPP()dnl AC_REQUIRE([AC_PROG_LEX])dnl -AC_MSG_CHECKING(lex output file root) -AC_CACHE_VAL(ac_cv_prog_lex_root, +AC_CACHE_CHECK(lex output file root, ac_cv_prog_lex_root, [# The minimal lex program is just a single line: %%. But some broken lexes # (Solaris, I think it was) want two %% lines, so accommodate them. echo '%% @@ -339,13 +341,11 @@ elif test -f lexyy.c; then ac_cv_prog_lex_root=lexyy else AC_MSG_ERROR(cannot find output from $LEX; giving up) -fi])dnl +fi]) LEX_OUTPUT_ROOT=$ac_cv_prog_lex_root -AC_MSG_RESULT($ac_cv_prog_lex_root) AC_SUBST(LEX_OUTPUT_ROOT)dnl -AC_MSG_CHECKING(whether yytext is a pointer) -AC_CACHE_VAL(ac_cv_prog_lex_yytext_pointer, +AC_CACHE_CHECK(whether yytext is a pointer, ac_cv_prog_lex_yytext_pointer, [# POSIX says lex can declare yytext either as a pointer or an array; the # default is implementation-dependent. Figure out which it is, since # not all implementations provide the %pointer and %array declarations. @@ -355,8 +355,8 @@ ac_save_LIBS="$LIBS" LIBS="$LIBS $LEXLIB" AC_TRY_LINK(`cat $LEX_OUTPUT_ROOT.c`, , ac_cv_prog_lex_yytext_pointer=yes) LIBS="$ac_save_LIBS" -rm -f "${LEX_OUTPUT_ROOT}.c"])dnl -AC_MSG_RESULT($ac_cv_prog_lex_yytext_pointer) +rm -f "${LEX_OUTPUT_ROOT}.c"]) +dnl if test $ac_cv_prog_lex_yytext_pointer = yes; then AC_DEFINE(YYTEXT_POINTER) fi @@ -401,15 +401,19 @@ AC_CACHE_VAL(ac_cv_path_install, esac done IFS="$ac_save_ifs" - # As a last resort, use the slow shell script. -dnl FIXME We probably shouldn't cache a path within a source directory, -dnl because that will break other packages using the cache if -dnl that directory is removed. - test -z "$ac_cv_path_install" && ac_cv_path_install="$ac_install_sh"])dnl - INSTALL="$ac_cv_path_install" +])dnl + if test "${ac_cv_path_install+set}" = set; then + INSTALL="$ac_cv_path_install" + else + # As a last resort, use the slow shell script. We don't cache a + # path for INSTALL within a source directory, because that will + # break other packages using the cache if that directory is + # removed, or if the path is relative. + INSTALL="$ac_install_sh" + fi fi dnl We do special magic for INSTALL instead of AC_SUBST, to get -dnl relative paths right. +dnl relative paths right. AC_MSG_RESULT($INSTALL) # Use test -z because SunOS4 sh mishandles braces in ${var-val}. @@ -451,8 +455,7 @@ dnl ### Checks for header files AC_DEFUN(AC_HEADER_STDC, [AC_REQUIRE_CPP()dnl -AC_MSG_CHECKING(for ANSI C header files) -AC_CACHE_VAL(ac_cv_header_stdc, +AC_CACHE_CHECK(for ANSI C header files, ac_cv_header_stdc, [AC_TRY_CPP([#include #include #include @@ -477,9 +480,8 @@ AC_TRY_RUN([#include int main () { int i; for (i = 0; i < 256; i++) if (XOR (islower (i), ISLOWER (i)) || toupper (i) != TOUPPER (i)) exit(2); exit (0); } -], , ac_cv_header_stdc=no, ac_cv_header_stdc=no) -fi])dnl -AC_MSG_RESULT($ac_cv_header_stdc) +], , ac_cv_header_stdc=no, :) +fi]) if test $ac_cv_header_stdc = yes; then AC_DEFINE(STDC_HEADERS) fi @@ -494,7 +496,7 @@ AC_DEFUN(AC_USG, [; instead use AC_CHECK_HEADERS(string.h) and HAVE_STRING_H])dnl AC_MSG_CHECKING([for BSD string and memory functions]) AC_TRY_LINK([#include ], [rindex(0, 0); bzero(0, 0);], - [AC_MSG_RESULT(yes); AC_DEFINE(USG)], [AC_MSG_RESULT(no)])]) + [AC_MSG_RESULT(yes)], [AC_MSG_RESULT(no); AC_DEFINE(USG)])]) dnl If memchr and the like aren't declared in , include . @@ -510,12 +512,11 @@ fi ]) AC_DEFUN(AC_HEADER_MAJOR, -[AC_MSG_CHECKING(whether sys/types.h defines makedev) -AC_CACHE_VAL(ac_cv_header_sys_types_h_makedev, +[AC_CACHE_CHECK(whether sys/types.h defines makedev, + ac_cv_header_sys_types_h_makedev, [AC_TRY_LINK([#include ], [return makedev(0, 0);], ac_cv_header_sys_types_h_makedev=yes, ac_cv_header_sys_types_h_makedev=no) -])dnl -AC_MSG_RESULT($ac_cv_header_sys_types_h_makedev) +]) if test $ac_cv_header_sys_types_h_makedev = no; then AC_CHECK_HEADER(sys/mkdev.h, [AC_DEFINE(MAJOR_IN_MKDEV)]) @@ -565,7 +566,7 @@ define(AC_CHECK_HEADERS_DIRENT, do AC_CHECK_HEADER_DIRENT($ac_hdr, [changequote(, )dnl - ac_tr_hdr=HAVE_`echo $ac_hdr | tr '[a-z]./\055' '[A-Z]___'` + ac_tr_hdr=HAVE_`echo $ac_hdr | tr 'abcdedfghijklmnopqrstuvwxyz./\055' 'ABCDEDFGHIJKLMNOPQRSTUVWXYZ___'` changequote([, ])dnl AC_DEFINE_UNQUOTED($ac_tr_hdr) $2])dnl done]) @@ -584,21 +585,19 @@ sys/dir.h) AC_DEFINE(SYSDIR) ;; ndir.h) AC_DEFINE(NDIR) ;; esac -AC_MSG_CHECKING(whether closedir returns void) -AC_CACHE_VAL(ac_cv_func_closedir_void, +AC_CACHE_CHECK(whether closedir returns void, ac_cv_func_closedir_void, [AC_TRY_RUN([#include #include <$ac_header_dirent> int closedir(); main() { exit(closedir(opendir(".")) != 0); }], - ac_cv_func_closedir_void=no, ac_cv_func_closedir_void=yes)])dnl -AC_MSG_RESULT($ac_cv_func_closedir_void) + ac_cv_func_closedir_void=no, ac_cv_func_closedir_void=yes, ac_cv_func_closedir_void=yes)]) if test $ac_cv_func_closedir_void = yes; then AC_DEFINE(VOID_CLOSEDIR) fi ]) AC_DEFUN(AC_HEADER_STAT, -[AC_MSG_CHECKING(whether stat file-mode macros are broken) -AC_CACHE_VAL(ac_cv_header_stat_broken, +[AC_CACHE_CHECK(whether stat file-mode macros are broken, + ac_cv_header_stat_broken, [AC_EGREP_CPP([You lose], [#include #include @@ -625,32 +624,30 @@ You lose. You lose. # endif #endif -], ac_cv_header_stat_broken=yes, ac_cv_header_stat_broken=no)])dnl -AC_MSG_RESULT($ac_cv_header_stat_broken) +], ac_cv_header_stat_broken=yes, ac_cv_header_stat_broken=no)]) if test $ac_cv_header_stat_broken = yes; then AC_DEFINE(STAT_MACROS_BROKEN) fi ]) AC_DEFUN(AC_DECL_SYS_SIGLIST, -[AC_MSG_CHECKING([for sys_siglist declaration in signal.h or unistd.h]) -AC_CACHE_VAL(ac_cv_decl_sys_siglist, +[AC_CACHE_CHECK([for sys_siglist declaration in signal.h or unistd.h], + ac_cv_decl_sys_siglist, [AC_TRY_COMPILE([#include #include /* NetBSD declares sys_siglist in unistd.h. */ #ifdef HAVE_UNISTD_H #include #endif], [char *msg = *(sys_siglist + 1);], - ac_cv_decl_sys_siglist=yes, ac_cv_decl_sys_siglist=no)])dnl -AC_MSG_RESULT($ac_cv_decl_sys_siglist) + ac_cv_decl_sys_siglist=yes, ac_cv_decl_sys_siglist=no)]) if test $ac_cv_decl_sys_siglist = yes; then AC_DEFINE(SYS_SIGLIST_DECLARED) fi ]) AC_DEFUN(AC_HEADER_SYS_WAIT, -[AC_MSG_CHECKING([for sys/wait.h that is POSIX.1 compatible]) -AC_CACHE_VAL(ac_cv_header_sys_wait_h, +[AC_CACHE_CHECK([for sys/wait.h that is POSIX.1 compatible], + ac_cv_header_sys_wait_h, [AC_TRY_COMPILE([#include #include #ifndef WEXITSTATUS @@ -661,8 +658,7 @@ AC_CACHE_VAL(ac_cv_header_sys_wait_h, #endif], [int s; wait (&s); s = WIFEXITED (s) ? WEXITSTATUS (s) : 1;], -ac_cv_header_sys_wait_h=yes, ac_cv_header_sys_wait_h=no)])dnl -AC_MSG_RESULT($ac_cv_header_sys_wait_h) +ac_cv_header_sys_wait_h=yes, ac_cv_header_sys_wait_h=no)]) if test $ac_cv_header_sys_wait_h = yes; then AC_DEFINE(HAVE_SYS_WAIT_H) fi @@ -674,8 +670,7 @@ dnl ### Checks for typedefs AC_DEFUN(AC_TYPE_GETGROUPS, [AC_REQUIRE([AC_TYPE_UID_T])dnl -AC_MSG_CHECKING(type of array argument to getgroups) -AC_CACHE_VAL(ac_cv_type_getgroups, +AC_CACHE_CHECK(type of array argument to getgroups, ac_cv_type_getgroups, [AC_TRY_RUN( changequote(<<, >>)dnl << @@ -709,17 +704,14 @@ if test $ac_cv_type_getgroups = cross; then dnl Old systems without prototypes probably use int. AC_EGREP_HEADER([getgroups.*int.*gid_t], unistd.h, ac_cv_type_getgroups=gid_t, ac_cv_type_getgroups=int) -fi])dnl -AC_MSG_RESULT($ac_cv_type_getgroups) +fi]) AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups) ]) AC_DEFUN(AC_TYPE_UID_T, -[AC_MSG_CHECKING(for uid_t in sys/types.h) -AC_CACHE_VAL(ac_cv_type_uid_t, +[AC_CACHE_CHECK(for uid_t in sys/types.h, ac_cv_type_uid_t, [AC_EGREP_HEADER(uid_t, sys/types.h, - ac_cv_type_uid_t=yes, ac_cv_type_uid_t=no)])dnl -AC_MSG_RESULT($ac_cv_type_uid_t) + ac_cv_type_uid_t=yes, ac_cv_type_uid_t=no)]) if test $ac_cv_type_uid_t = no; then AC_DEFINE(uid_t, int) AC_DEFINE(gid_t, int) @@ -740,19 +732,19 @@ AC_DEFUN(AC_TYPE_MODE_T, dnl Note that identifiers starting with SIG are reserved by ANSI C. AC_DEFUN(AC_TYPE_SIGNAL, -[AC_MSG_CHECKING([return type of signal handlers]) -AC_CACHE_VAL(ac_cv_type_signal, +[AC_CACHE_CHECK([return type of signal handlers], ac_cv_type_signal, [AC_TRY_COMPILE([#include #include #ifdef signal #undef signal #endif #ifdef __cplusplus -extern "C" +extern "C" void (*signal (int, void (*)(int)))(int); +#else +void (*signal ()) (); #endif -void (*signal ()) ();], -[int i;], ac_cv_type_signal=void, ac_cv_type_signal=int)])dnl -AC_MSG_RESULT($ac_cv_type_signal) +], +[int i;], ac_cv_type_signal=void, ac_cv_type_signal=int)]) AC_DEFINE_UNQUOTED(RETSIGTYPE, $ac_cv_type_signal) ]) @@ -762,33 +754,25 @@ dnl ### Checks for functions AC_DEFUN(AC_FUNC_CLOSEDIR_VOID, [AC_REQUIRE([AC_HEADER_DIRENT])dnl -AC_MSG_CHECKING(whether closedir returns void) -AC_CACHE_VAL(ac_cv_func_closedir_void, +AC_CACHE_CHECK(whether closedir returns void, ac_cv_func_closedir_void, [AC_TRY_RUN([#include #include <$ac_header_dirent> int closedir(); main() { exit(closedir(opendir(".")) != 0); }], - ac_cv_func_closedir_void=no, ac_cv_func_closedir_void=yes)])dnl -AC_MSG_RESULT($ac_cv_func_closedir_void) + ac_cv_func_closedir_void=no, ac_cv_func_closedir_void=yes, ac_cv_func_closedir_void=yes)]) if test $ac_cv_func_closedir_void = yes; then AC_DEFINE(CLOSEDIR_VOID) fi ]) AC_DEFUN(AC_FUNC_MMAP, -[AC_MSG_CHECKING(for working mmap) -AC_CACHE_VAL(ac_cv_func_mmap, +[AC_CHECK_FUNCS(valloc getpagesize) +AC_CACHE_CHECK(for working mmap, ac_cv_func_mmap, [AC_TRY_RUN([ /* Thanks to Mike Haertel and Jim Avera for this test. */ #include #include #include -#ifdef BSD -# ifndef BSD4_1 -# define HAVE_GETPAGESIZE -# endif -#endif - #ifndef HAVE_GETPAGESIZE # include # ifdef EXEC_PAGESIZE @@ -809,7 +793,7 @@ AC_CACHE_VAL(ac_cv_func_mmap, # endif #endif -#ifdef __osf__ +#ifndef HAVE_VALLOC # define valloc malloc #endif @@ -824,7 +808,7 @@ main() { char *buf1, *buf2, *buf3; int i = getpagesize(), j; - int i2 = getpagesize()*2; + int i2 = i * 2; int fd; buf1 = (char *)valloc(i2); @@ -848,16 +832,14 @@ main() exit(1); exit(0); } -], ac_cv_func_mmap=yes, ac_cv_func_mmap=no, ac_cv_func_mmap=no)])dnl -AC_MSG_RESULT($ac_cv_func_mmap) +], ac_cv_func_mmap=yes, ac_cv_func_mmap=no, ac_cv_func_mmap=no)]) if test $ac_cv_func_mmap = yes; then AC_DEFINE(HAVE_MMAP) fi ]) AC_DEFUN(AC_FUNC_GETPGRP, -[AC_MSG_CHECKING(whether getpgrp takes no argument) -AC_CACHE_VAL(ac_cv_func_getpgrp_void, +[AC_CACHE_CHECK(whether getpgrp takes no argument, ac_cv_func_getpgrp_void, [AC_TRY_RUN([ /* * If this system has a BSD-style getpgrp(), @@ -912,7 +894,6 @@ main() ], ac_cv_func_getpgrp_void=yes, ac_cv_func_getpgrp_void=no, AC_MSG_ERROR(cannot check getpgrp if cross compiling)) ]) -AC_MSG_RESULT($ac_cv_func_getpgrp_void) if test $ac_cv_func_getpgrp_void = yes; then AC_DEFINE(GETPGRP_VOID) fi @@ -928,8 +909,7 @@ fi AC_DEFUN(AC_FUNC_VFORK, [AC_REQUIRE([AC_TYPE_PID_T])dnl AC_CHECK_HEADER(vfork.h, AC_DEFINE(HAVE_VFORK_H)) -AC_MSG_CHECKING(for working vfork) -AC_CACHE_VAL(ac_cv_func_vfork, +AC_CACHE_CHECK(for working vfork, ac_cv_func_vfork, [AC_TRY_RUN([/* Thanks to Paul Eggert for this test. */ #include #include @@ -1019,16 +999,15 @@ main() { || fstat(fileno(stdout), &st) != 0 ); } -}], ac_cv_func_vfork=yes, ac_cv_func_vfork=no, ac_cv_func_vfork=no)])dnl -AC_MSG_RESULT($ac_cv_func_vfork) +}], +ac_cv_func_vfork=yes, ac_cv_func_vfork=no, AC_CHECK_FUNC(vfork))]) if test $ac_cv_func_vfork = no; then AC_DEFINE(vfork, fork) fi ]) AC_DEFUN(AC_FUNC_WAIT3, -[AC_MSG_CHECKING(for wait3 that fills in rusage) -AC_CACHE_VAL(ac_cv_func_wait3, +[AC_CACHE_CHECK(for wait3 that fills in rusage, ac_cv_func_wait3, [AC_TRY_RUN([#include #include #include @@ -1056,8 +1035,7 @@ main() { exit(r.ru_nvcsw == 0 && r.ru_majflt == 0 && r.ru_minflt == 0 && r.ru_stime.tv_sec == 0 && r.ru_stime.tv_usec == 0); } -}], ac_cv_func_wait3=yes, ac_cv_func_wait3=no, ac_cv_func_wait3=no)])dnl -AC_MSG_RESULT($ac_cv_func_wait3) +}], ac_cv_func_wait3=yes, ac_cv_func_wait3=no, ac_cv_func_wait3=no)]) if test $ac_cv_func_wait3 = yes; then AC_DEFINE(HAVE_WAIT3) fi @@ -1067,17 +1045,14 @@ AC_DEFUN(AC_FUNC_ALLOCA, [AC_REQUIRE_CPP()dnl Set CPP; we run AC_EGREP_CPP conditionally. # The Ultrix 4.2 mips builtin alloca declared by alloca.h only works # for constant arguments. Useless! -AC_MSG_CHECKING([for working alloca.h]) -AC_CACHE_VAL(ac_cv_header_alloca_h, +AC_CACHE_CHECK([for working alloca.h], ac_cv_header_alloca_h, [AC_TRY_LINK([#include ], [char *p = alloca(2 * sizeof(int));], - ac_cv_header_alloca_h=yes, ac_cv_header_alloca_h=no)])dnl -AC_MSG_RESULT($ac_cv_header_alloca_h) + ac_cv_header_alloca_h=yes, ac_cv_header_alloca_h=no)]) if test $ac_cv_header_alloca_h = yes; then AC_DEFINE(HAVE_ALLOCA_H) fi -AC_MSG_CHECKING([for alloca]) -AC_CACHE_VAL(ac_cv_func_alloca, +AC_CACHE_CHECK([for alloca], ac_cv_func_alloca, [AC_TRY_LINK([ #ifdef __GNUC__ # define alloca __builtin_alloca @@ -1095,8 +1070,7 @@ char *alloca (); # endif #endif ], [char *p = (char *) alloca(1);], - ac_cv_func_alloca=yes, ac_cv_func_alloca=no)])dnl -AC_MSG_RESULT($ac_cv_func_alloca) + ac_cv_func_alloca=yes, ac_cv_func_alloca=no)]) if test $ac_cv_func_alloca = yes; then AC_DEFINE(HAVE_ALLOCA) fi @@ -1109,16 +1083,14 @@ if test $ac_cv_func_alloca = no; then ALLOCA=alloca.o AC_DEFINE(C_ALLOCA) -AC_MSG_CHECKING(whether alloca needs Cray hooks) -AC_CACHE_VAL(ac_cv_os_cray, +AC_CACHE_CHECK(whether alloca needs Cray hooks, ac_cv_os_cray, [AC_EGREP_CPP(webecray, [#if defined(CRAY) && ! defined(CRAY2) webecray #else wenotbecray #endif -], ac_cv_os_cray=yes, ac_cv_os_cray=no)])dnl -AC_MSG_RESULT($ac_cv_os_cray) +], ac_cv_os_cray=yes, ac_cv_os_cray=no)]) if test $ac_cv_os_cray = yes; then for ac_func in _getb67 GETB67 getb67; do AC_CHECK_FUNC($ac_func, [AC_DEFINE_UNQUOTED(CRAY_STACKSEG_END, $ac_func) @@ -1126,8 +1098,7 @@ for ac_func in _getb67 GETB67 getb67; do done fi -AC_MSG_CHECKING(stack direction for C alloca) -AC_CACHE_VAL(ac_cv_c_stack_direction, +AC_CACHE_CHECK(stack direction for C alloca, ac_cv_c_stack_direction, [AC_TRY_RUN([find_stack_direction () { static char *addr = 0; @@ -1144,8 +1115,7 @@ main () { exit (find_stack_direction() < 0); }], ac_cv_c_stack_direction=1, ac_cv_c_stack_direction=-1, - ac_cv_c_stack_direction=0)])dnl -AC_MSG_RESULT($ac_cv_c_stack_direction) + ac_cv_c_stack_direction=0)]) AC_DEFINE_UNQUOTED(STACK_DIRECTION, $ac_cv_c_stack_direction) fi AC_SUBST(ALLOCA)dnl @@ -1187,7 +1157,7 @@ else # We cannot check for , because Solaris 2 does not use dwarf (it # uses stabs), but it is still SVR4. We cannot check for because # Irix 4.0.5F has the header but not the library. - if test $ac_have_func = no && test $ac_cv_lib_elf = yes; then + if test $ac_have_func = no && test $ac_cv_lib_elf_elf_begin = yes; then ac_have_func=yes; AC_DEFINE(SVR4) fi @@ -1208,12 +1178,10 @@ else AC_CHECK_HEADER(nlist.h, [AC_DEFINE(NLIST_STRUCT) - AC_MSG_CHECKING([for n_un in struct nlist]) - AC_CACHE_VAL(ac_cv_struct_nlist_n_un, + AC_CACHE_CHECK([for n_un in struct nlist], ac_cv_struct_nlist_n_un, [AC_TRY_COMPILE([#include ], [struct nlist n; n.n_un.n_name = 0;], - ac_cv_struct_nlist_n_un=yes, ac_cv_struct_nlist_n_un=no)])dnl - AC_MSG_RESULT($ac_cv_struct_nlist_n_un) + ac_cv_struct_nlist_n_un=yes, ac_cv_struct_nlist_n_un=no)]) if test $ac_cv_struct_nlist_n_un = yes; then AC_DEFINE(NLIST_NAME_UNION) fi @@ -1222,15 +1190,14 @@ fi # Do not have getloadavg in system libraries. # Some definitions of getloadavg require that the program be installed setgid. dnl FIXME Don't hardwire the path of getloadavg.c in the top-level directory. -AC_MSG_CHECKING(whether getloadavg requires setgid) -AC_CACHE_VAL(ac_cv_func_getloadavg_setgid, +AC_CACHE_CHECK(whether getloadavg requires setgid, + ac_cv_func_getloadavg_setgid, [AC_EGREP_CPP([Yowza Am I SETGID yet], [#include "$srcdir/getloadavg.c" #ifdef LDAV_PRIVILEGED Yowza Am I SETGID yet #endif], - ac_cv_func_getloadavg_setgid=yes, ac_cv_func_getloadavg_setgid=no)])dnl -AC_MSG_RESULT($ac_cv_func_getloadavg_setgid) + ac_cv_func_getloadavg_setgid=yes, ac_cv_func_getloadavg_setgid=no)]) if test $ac_cv_func_getloadavg_setgid = yes; then NEED_SETGID=true; AC_DEFINE(GETLOADAVG_PRIVILEGED) else @@ -1239,8 +1206,7 @@ fi AC_SUBST(NEED_SETGID)dnl if test $ac_cv_func_getloadavg_setgid = yes; then - AC_MSG_CHECKING(group of /dev/kmem) -AC_CACHE_VAL(ac_cv_group_kmem, + AC_CACHE_CHECK(group of /dev/kmem, ac_cv_group_kmem, [changequote(, )dnl # On Solaris, /dev/kmem is a symlink. Get info on the real file. ac_ls_output=`ls -lgL /dev/kmem 2>/dev/null` @@ -1251,16 +1217,14 @@ AC_CACHE_VAL(ac_cv_group_kmem, s/^.[sSrwx-]* *[0-9]* *\([^0-9]*\) *.*/\1/; / /s/.* //;p;'` changequote([, ])dnl -])dnl +]) KMEM_GROUP=$ac_cv_group_kmem - AC_MSG_RESULT($KMEM_GROUP) fi AC_SUBST(KMEM_GROUP)dnl ]) AC_DEFUN(AC_FUNC_UTIME_NULL, -[AC_MSG_CHECKING(whether utime accepts a null argument) -AC_CACHE_VAL(ac_cv_func_utime_null, +[AC_CACHE_CHECK(whether utime accepts a null argument, ac_cv_func_utime_null, [rm -f conftestdata; > conftestdata # Sequent interprets utime(file, 0) to mean use start of epoch. Wrong. AC_TRY_RUN([#include @@ -1272,32 +1236,29 @@ exit(!(stat ("conftestdata", &s) == 0 && utime("conftestdata", (long *)0) == 0 && t.st_mtime - s.st_mtime < 120)); }], ac_cv_func_utime_null=yes, ac_cv_func_utime_null=no, ac_cv_func_utime_null=no) -rm -f core core.* *.core])dnl -AC_MSG_RESULT($ac_cv_func_utime_null) +rm -f core core.* *.core]) if test $ac_cv_func_utime_null = yes; then AC_DEFINE(HAVE_UTIME_NULL) fi ]) AC_DEFUN(AC_FUNC_STRCOLL, -[AC_MSG_CHECKING(for strcoll) -AC_CACHE_VAL(ac_cv_func_strcoll, +[AC_CACHE_CHECK(for strcoll, ac_cv_func_strcoll, [AC_TRY_RUN([#include main () { exit (strcoll ("abc", "def") >= 0 || strcoll ("ABC", "DEF") >= 0 || strcoll ("123", "456") >= 0); -}], ac_cv_func_strcoll=yes, ac_cv_func_strcoll=no, ac_cv_func_strcoll=no)])dnl -AC_MSG_RESULT($ac_cv_func_strcoll) +}], ac_cv_func_strcoll=yes, ac_cv_func_strcoll=no, ac_cv_func_strcoll=no)]) if test $ac_cv_func_strcoll = yes; then AC_DEFINE(HAVE_STRCOLL) fi ]) AC_DEFUN(AC_FUNC_SETVBUF_REVERSED, -[AC_MSG_CHECKING(whether setvbuf arguments are reversed) -AC_CACHE_VAL(ac_cv_func_setvbuf_reversed, +[AC_CACHE_CHECK(whether setvbuf arguments are reversed, + ac_cv_func_setvbuf_reversed, [AC_TRY_RUN([#include /* If setvbuf has the reversed format, exit 0. */ main () { @@ -1309,17 +1270,17 @@ main () { putc('\r', stdout); exit(0); /* Non-reversed systems segv here. */ }], ac_cv_func_setvbuf_reversed=yes, ac_cv_func_setvbuf_reversed=no) -rm -f core core.* *.core])dnl -AC_MSG_RESULT($ac_cv_func_setvbuf_reversed) +rm -f core core.* *.core]) if test $ac_cv_func_setvbuf_reversed = yes; then AC_DEFINE(SETVBUF_REVERSED) fi ]) AC_DEFUN(AC_FUNC_GETMNTENT, -[# getmntent is in -lsun on Irix 4, -lseq on Dynix/PTX. +[# getmntent is in -lsun on Irix 4, -lseq on Dynix/PTX, -lgen on Unixware. AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS", - [AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS")]) + [AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS", + [AC_CHECK_LIB(gen, getmntent, LIBS="-lgen $LIBS")])]) AC_CHECK_FUNC(getmntent, [AC_DEFINE(HAVE_GETMNTENT)])]) AC_DEFUN(AC_FUNC_STRFTIME, @@ -1328,16 +1289,14 @@ AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS") AC_CHECK_FUNC(strftime, [AC_DEFINE(HAVE_STRFTIME)])]) AC_DEFUN(AC_FUNC_MEMCMP, -[AC_MSG_CHECKING(for 8-bit clean memcmp) -AC_CACHE_VAL(ac_cv_func_memcmp, +[AC_CACHE_CHECK(for 8-bit clean memcmp, ac_cv_func_memcmp, [AC_TRY_RUN([ main() { char c0 = 0x40, c1 = 0x80, c2 = 0x81; exit(memcmp(&c0, &c2, 1) < 0 && memcmp(&c1, &c2, 1) < 0 ? 0 : 1); } -], ac_cv_func_memcmp=yes, ac_cv_func_memcmp=no, ac_cv_func_memcmp=no)])dnl -AC_MSG_RESULT($ac_cv_func_memcmp) +], ac_cv_func_memcmp=yes, ac_cv_func_memcmp=no, ac_cv_func_memcmp=no)]) test $ac_cv_func_memcmp = no && LIBOBJS="$LIBOBJS memcmp.o" AC_SUBST(LIBOBJS)dnl ]) @@ -1347,26 +1306,24 @@ dnl ### Checks for structure members AC_DEFUN(AC_HEADER_TIME, -[AC_MSG_CHECKING([whether time.h and sys/time.h may both be included]) -AC_CACHE_VAL(ac_cv_header_time, +[AC_CACHE_CHECK([whether time.h and sys/time.h may both be included], + ac_cv_header_time, [AC_TRY_COMPILE([#include #include #include ], -[struct tm *tp;], ac_cv_header_time=yes, ac_cv_header_time=no)])dnl -AC_MSG_RESULT($ac_cv_header_time) +[struct tm *tp;], ac_cv_header_time=yes, ac_cv_header_time=no)]) if test $ac_cv_header_time = yes; then AC_DEFINE(TIME_WITH_SYS_TIME) fi ]) AC_DEFUN(AC_STRUCT_TM, -[AC_MSG_CHECKING([whether struct tm is in sys/time.h or time.h]) -AC_CACHE_VAL(ac_cv_struct_tm, +[AC_CACHE_CHECK([whether struct tm is in sys/time.h or time.h], + ac_cv_struct_tm, [AC_TRY_COMPILE([#include #include ], [struct tm *tp; tp->tm_sec;], - ac_cv_struct_tm=time.h, ac_cv_struct_tm=sys/time.h)])dnl -AC_MSG_RESULT($ac_cv_struct_tm) + ac_cv_struct_tm=time.h, ac_cv_struct_tm=sys/time.h)]) if test $ac_cv_struct_tm = sys/time.h; then AC_DEFINE(TM_IN_SYS_TIME) fi @@ -1374,17 +1331,14 @@ fi AC_DEFUN(AC_STRUCT_TIMEZONE, [AC_REQUIRE([AC_STRUCT_TM])dnl -AC_MSG_CHECKING([for tm_zone in struct tm]) -AC_CACHE_VAL(ac_cv_struct_tm_zone, +AC_CACHE_CHECK([for tm_zone in struct tm], ac_cv_struct_tm_zone, [AC_TRY_COMPILE([#include #include <$ac_cv_struct_tm>], [struct tm tm; tm.tm_zone;], - ac_cv_struct_tm_zone=yes, ac_cv_struct_tm_zone=no)])dnl -AC_MSG_RESULT($ac_cv_struct_tm_zone) + ac_cv_struct_tm_zone=yes, ac_cv_struct_tm_zone=no)]) if test "$ac_cv_struct_tm_zone" = yes; then AC_DEFINE(HAVE_TM_ZONE) else - AC_MSG_CHECKING([for tzname]) -AC_CACHE_VAL(ac_cv_var_tzname, + AC_CACHE_CHECK(for tzname, ac_cv_var_tzname, [AC_TRY_LINK( changequote(<<, >>)dnl <<#include @@ -1392,8 +1346,7 @@ changequote(<<, >>)dnl extern char *tzname[]; /* RS6000 and others reject char **tzname. */ #endif>>, changequote([, ])dnl -[atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)])dnl - AC_MSG_RESULT($ac_cv_var_tzname) +[atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)]) if test $ac_cv_var_tzname = yes; then AC_DEFINE(HAVE_TZNAME) fi @@ -1401,12 +1354,10 @@ fi ]) AC_DEFUN(AC_STRUCT_ST_BLOCKS, -[AC_MSG_CHECKING([for st_blocks in struct stat]) -AC_CACHE_VAL(ac_cv_struct_st_blocks, +[AC_CACHE_CHECK([for st_blocks in struct stat], ac_cv_struct_st_blocks, [AC_TRY_COMPILE([#include #include ], [struct stat s; s.st_blocks;], -ac_cv_struct_st_blocks=yes, ac_cv_struct_st_blocks=no)])dnl -AC_MSG_RESULT($ac_cv_struct_st_blocks) +ac_cv_struct_st_blocks=yes, ac_cv_struct_st_blocks=no)]) if test $ac_cv_struct_st_blocks = yes; then AC_DEFINE(HAVE_ST_BLOCKS) else @@ -1416,24 +1367,20 @@ AC_SUBST(LIBOBJS)dnl ]) AC_DEFUN(AC_STRUCT_ST_BLKSIZE, -[AC_MSG_CHECKING([for st_blksize in struct stat]) -AC_CACHE_VAL(ac_cv_struct_st_blksize, +[AC_CACHE_CHECK([for st_blksize in struct stat], ac_cv_struct_st_blksize, [AC_TRY_COMPILE([#include #include ], [struct stat s; s.st_blksize;], -ac_cv_struct_st_blksize=yes, ac_cv_struct_st_blksize=no)])dnl -AC_MSG_RESULT($ac_cv_struct_st_blksize) +ac_cv_struct_st_blksize=yes, ac_cv_struct_st_blksize=no)]) if test $ac_cv_struct_st_blksize = yes; then AC_DEFINE(HAVE_ST_BLKSIZE) fi ]) AC_DEFUN(AC_STRUCT_ST_RDEV, -[AC_MSG_CHECKING([for st_rdev in struct stat]) -AC_CACHE_VAL(ac_cv_struct_st_rdev, +[AC_CACHE_CHECK([for st_rdev in struct stat], ac_cv_struct_st_rdev, [AC_TRY_COMPILE([#include #include ], [struct stat s; s.st_rdev;], -ac_cv_struct_st_rdev=yes, ac_cv_struct_st_rdev=no)])dnl -AC_MSG_RESULT($ac_cv_struct_st_rdev) +ac_cv_struct_st_rdev=yes, ac_cv_struct_st_rdev=no)]) if test $ac_cv_struct_st_rdev = yes; then AC_DEFINE(HAVE_ST_RDEV) fi @@ -1445,17 +1392,14 @@ dnl ### Checks for compiler characteristics AC_DEFUN(AC_C_CROSS, [# If we cannot run a trivial program, we must be cross compiling. -AC_MSG_CHECKING(whether cross-compiling) -AC_CACHE_VAL(ac_cv_c_cross, +AC_CACHE_CHECK(whether cross-compiling, ac_cv_c_cross, [AC_TRY_RUN([main(){return(0);}], - ac_cv_c_cross=no, ac_cv_c_cross=yes, ac_cv_c_cross=yes)])dnl + ac_cv_c_cross=no, ac_cv_c_cross=yes, ac_cv_c_cross=yes)]) cross_compiling=$ac_cv_c_cross -AC_MSG_RESULT($ac_cv_c_cross) ]) AC_DEFUN(AC_C_CHAR_UNSIGNED, -[AC_MSG_CHECKING(whether char is unsigned) -AC_CACHE_VAL(ac_cv_c_char_unsigned, +[AC_CACHE_CHECK(whether char is unsigned, ac_cv_c_char_unsigned, [if test "$GCC" = yes; then # GCC predefines this symbol on systems where it applies. AC_EGREP_CPP(yes, @@ -1472,16 +1416,14 @@ AC_TRY_RUN( main() { volatile char c = 255; exit(c < 0); }], ac_cv_c_char_unsigned=yes, ac_cv_c_char_unsigned=no) -fi])dnl -AC_MSG_RESULT($ac_cv_c_char_unsigned) +fi]) if test $ac_cv_c_char_unsigned = yes && test "$GCC" != yes; then AC_DEFINE(__CHAR_UNSIGNED__) fi ]) AC_DEFUN(AC_C_LONG_DOUBLE, -[AC_MSG_CHECKING(for long double) -AC_CACHE_VAL(ac_cv_c_long_double, +[AC_CACHE_CHECK(for long double, ac_cv_c_long_double, [if test "$GCC" = yes; then ac_cv_c_long_double=yes else @@ -1491,8 +1433,7 @@ long double foo = 0.0; /* On Ultrix 4.3 cc, long double is 4 and double is 8. */ exit(sizeof(long double) < sizeof(double)); }], ac_cv_c_long_double=yes, ac_cv_c_long_double=no) -fi])dnl -AC_MSG_RESULT($ac_cv_c_long_double) +fi]) if test $ac_cv_c_long_double = yes; then AC_DEFINE(HAVE_LONG_DOUBLE) fi @@ -1515,8 +1456,7 @@ AC_TRY_RUN([main() { exit(sizeof(long int) != 8); }], ]) AC_DEFUN(AC_C_BIGENDIAN, -[AC_MSG_CHECKING(whether byte ordering is bigendian) -AC_CACHE_VAL(ac_cv_c_bigendian, +[AC_CACHE_CHECK(whether byte ordering is bigendian, ac_cv_c_bigendian, [ac_cv_c_bigendian=unknown # See if sys/param.h defines the BYTE_ORDER macro. AC_TRY_COMPILE([#include @@ -1540,8 +1480,7 @@ AC_TRY_RUN([main () { u.l = 1; exit (u.c[sizeof (long) - 1] == 1); }], ac_cv_c_bigendian=no, ac_cv_c_bigendian=yes) -fi])dnl -AC_MSG_RESULT($ac_cv_c_bigendian) +fi]) if test $ac_cv_c_bigendian = yes; then AC_DEFINE(WORDS_BIGENDIAN) fi @@ -1551,14 +1490,12 @@ dnl Do nothing if the compiler accepts the inline keyword. dnl Otherwise define inline to __inline__ or __inline if one of those work, dnl otherwise define inline to be empty. AC_DEFUN(AC_C_INLINE, -[AC_MSG_CHECKING([for inline]) -AC_CACHE_VAL(ac_cv_c_inline, +[AC_CACHE_CHECK([for inline], ac_cv_c_inline, [ac_cv_c_inline=no for ac_kw in inline __inline__ __inline; do AC_TRY_COMPILE(, [} $ac_kw foo() {], [ac_cv_c_inline=$ac_kw; break]) done -])dnl -AC_MSG_RESULT($ac_cv_c_inline) +]) case "$ac_cv_c_inline" in inline | yes) ;; no) AC_DEFINE(inline, ) ;; @@ -1569,8 +1506,7 @@ esac AC_DEFUN(AC_C_CONST, [dnl This message is consistent in form with the other checking messages, dnl and with the result message. -AC_MSG_CHECKING([for working const]) -AC_CACHE_VAL(ac_cv_c_const, +AC_CACHE_CHECK([for working const], ac_cv_c_const, [AC_TRY_COMPILE(, changequote(<<, >>)dnl << @@ -1581,7 +1517,7 @@ char const *const *ccp; char **p; /* NEC SVR4.0.2 mips cc rejects this. */ struct point {int x, y;}; -static struct point const zero; +static struct point const zero = {0,0}; /* AIX XL C 1.02.0.0 rejects this. It does not let you subtract one const X* pointer from another in an arm of an if-expression whose if-part is not a constant expression */ @@ -1617,8 +1553,7 @@ ccp = (char const *const *) p; } >>, changequote([, ])dnl -ac_cv_c_const=yes, ac_cv_c_const=no)])dnl -AC_MSG_RESULT($ac_cv_c_const) +ac_cv_c_const=yes, ac_cv_c_const=no)]) if test $ac_cv_c_const = no; then AC_DEFINE(const, ) fi @@ -1635,8 +1570,7 @@ dnl ### Checks for operating system services AC_DEFUN(AC_SYS_INTERPRETER, [# Pull the hash mark out of the macro call to avoid m4 problems. ac_msg="whether #! works in shell scripts" -AC_MSG_CHECKING($ac_msg) -AC_CACHE_VAL(ac_cv_sys_interpreter, +AC_CACHE_CHECK($ac_msg, ac_cv_sys_interpreter, [echo '#! /bin/cat exit 69 ' > conftest @@ -1647,8 +1581,7 @@ if test $? -ne 69; then else ac_cv_sys_interpreter=no fi -rm -f conftest])dnl -AC_MSG_RESULT($ac_cv_sys_interpreter) +rm -f conftest]) ]) define(AC_HAVE_POUNDBANG, @@ -1656,8 +1589,7 @@ define(AC_HAVE_POUNDBANG, ])m4exit(4)]) AC_DEFUN(AC_SYS_LONG_FILE_NAMES, -[AC_MSG_CHECKING(for long file names) -AC_CACHE_VAL(ac_cv_sys_long_file_names, +[AC_CACHE_CHECK(for long file names, ac_cv_sys_long_file_names, [ac_cv_sys_long_file_names=yes # Test for long file names in all the places we know might matter: # . the current directory, where building will happen @@ -1679,16 +1611,14 @@ for ac_dir in `eval echo . /tmp /var/tmp /usr/tmp $prefix/lib $exec_prefix/lib` break fi rm -f $ac_dir/conftest9012345 $ac_dir/conftest9012346 2>/dev/null -done])dnl -AC_MSG_RESULT($ac_cv_sys_long_file_names) +done]) if test $ac_cv_sys_long_file_names = yes; then AC_DEFINE(HAVE_LONG_FILE_NAMES) fi ]) AC_DEFUN(AC_SYS_RESTARTABLE_SYSCALLS, -[AC_MSG_CHECKING(for restartable system calls) -AC_CACHE_VAL(ac_cv_sys_restartable_syscalls, +[AC_CACHE_CHECK(for restartable system calls, ac_cv_sys_restartable_syscalls, [AC_TRY_RUN( [/* Exit 0 (true) if wait returns something other than -1, i.e. the pid of the child, which means that wait was restarted @@ -1704,8 +1634,7 @@ main () { if (status == -1) wait(&i); exit (status == -1); } -], ac_cv_sys_restartable_syscalls=yes, ac_cv_sys_restartable_syscalls=no)])dnl -AC_MSG_RESULT($ac_cv_sys_restartable_syscalls) +], ac_cv_sys_restartable_syscalls=yes, ac_cv_sys_restartable_syscalls=no)]) if test $ac_cv_sys_restartable_syscalls = yes; then AC_DEFINE(HAVE_RESTARTABLE_SYSCALLS) fi @@ -1720,40 +1649,48 @@ AC_DEFUN(AC_PATH_X, AC_MSG_CHECKING(for X) AC_ARG_WITH(x, [ --with-x use the X Window System]) +# $have_x is `yes', `no', `disabled', or empty when we do not yet know. if test "x$with_x" = xno; then - no_x=yes + # The user explicitly disabled X. + have_x=disabled else if test "x$x_includes" != xNONE && test "x$x_libraries" != xNONE; then - no_x= + # Both variables are already set. + have_x=yes else -AC_CACHE_VAL(ac_cv_path_x, +AC_CACHE_VAL(ac_cv_have_x, [# One or both of the vars are not set, and there is no cached value. -no_x=yes +ac_x_includes=NO ac_x_libraries=NO AC_PATH_X_XMKMF -if test "$no_x" = yes; then AC_PATH_X_DIRECT -fi -if test "$no_x" = yes; then - ac_cv_path_x="no_x=yes" +if test "$ac_x_includes" = NO || test "$ac_x_libraries" = NO; then + # Didn't find X anywhere. Cache the known absence of X. + ac_cv_have_x="have_x=no" else - ac_cv_path_x="no_x= ac_x_includes=$ac_x_includes ac_x_libraries=$ac_x_libraries" + # Record where we found X for the cache. + ac_cv_have_x="have_x=yes \ + ac_x_includes=$ac_x_includes ac_x_libraries=$ac_x_libraries" fi])dnl fi - eval "$ac_cv_path_x" + eval "$ac_cv_have_x" fi # $with_x != no -if test "$no_x" = yes; then - AC_MSG_RESULT(no) +if test "$have_x" != yes; then + AC_MSG_RESULT($have_x) + no_x=yes else + # If each of the values was on the command line, it overrides each guess. test "x$x_includes" = xNONE && x_includes=$ac_x_includes test "x$x_libraries" = xNONE && x_libraries=$ac_x_libraries - ac_cv_path_x="no_x= ac_x_includes=$x_includes ac_x_libraries=$x_libraries" + # Update the cache value to reflect the command line values. + ac_cv_have_x="have_x=yes \ + ac_x_includes=$x_includes ac_x_libraries=$x_libraries" AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) fi ]) dnl Internal subroutine of AC_PATH_X. -dnl Set ac_x_includes, ac_x_libraries, and no_x (initially yes). +dnl Set ac_x_includes and/or ac_x_libraries. AC_DEFUN(AC_PATH_X_XMKMF, [rm -fr conftestdir if mkdir conftestdir; then @@ -1764,9 +1701,8 @@ acfindx: @echo 'ac_im_incroot="${INCROOT}"; ac_im_usrlibdir="${USRLIBDIR}"; ac_im_libdir="${LIBDIR}"' EOF if (xmkmf) >/dev/null 2>/dev/null && test -f Makefile; then - no_x= # GNU make sometimes prints "make[1]: Entering...", which would confuse us. - eval `make acfindx 2>/dev/null | grep -v make` + eval `${MAKE-make} acfindx 2>/dev/null | grep -v make` # Open Windows xmkmf reportedly sets LIBDIR instead of USRLIBDIR. for ac_extension in a so sl; do if test ! -f $ac_im_usrlibdir/libX11.$ac_extension && @@ -1790,14 +1726,18 @@ fi ]) dnl Internal subroutine of AC_PATH_X. -dnl Set ac_x_includes, ac_x_libraries, and no_x (initially yes). +dnl Set ac_x_includes and/or ac_x_libraries. AC_DEFUN(AC_PATH_X_DIRECT, -[test -z "$x_direct_test_library" && x_direct_test_library=Xt -test -z "$x_direct_test_function" && x_direct_test_function=XtMalloc -test -z "$x_direct_test_include" && x_direct_test_include=X11/Intrinsic.h +[if test "$ac_x_includes" = NO; then + # Guess where to find include files, by looking for this one X11 .h file. + test -z "$x_direct_test_include" && x_direct_test_include=X11/Intrinsic.h + + # First, try using that file with no special directory specified. AC_TRY_CPP([#include <$x_direct_test_include>], -[no_x= ac_x_includes=], -[ for ac_dir in \ +[# We can compile using X headers with no special include directory. +ac_x_includes=], +[# Look for the header file in a standard set of common directories. + for ac_dir in \ /usr/X11R6/include \ /usr/X11R5/include \ /usr/X11R4/include \ @@ -1835,18 +1775,26 @@ AC_TRY_CPP([#include <$x_direct_test_include>], ; \ do if test -r "$ac_dir/$x_direct_test_include"; then - no_x= ac_x_includes=$ac_dir + ac_x_includes=$ac_dir break fi done]) +fi # $ac_x_includes = NO -# Check for the libraries. -# See if we find them without any special options. -# Don't add to $LIBS permanently. -ac_save_LIBS="$LIBS" -LIBS="-l$x_direct_test_library $LIBS" +if test "$ac_x_libraries" = NO; then + # Check for the libraries. + + test -z "$x_direct_test_library" && x_direct_test_library=Xt + test -z "$x_direct_test_function" && x_direct_test_function=XtMalloc + + # See if we find them without any special options. + # Don't add to $LIBS permanently. + ac_save_LIBS="$LIBS" + LIBS="-l$x_direct_test_library $LIBS" AC_TRY_LINK(, [${x_direct_test_function}()], -[LIBS="$ac_save_LIBS" no_x= ac_x_libraries=], +[LIBS="$ac_save_LIBS" +# We can link X programs with no special library path. +ac_x_libraries=], [LIBS="$ac_save_LIBS" # First see if replacing the include by lib works. for ac_dir in `echo "$ac_x_includes" | sed s/include/lib/` \ @@ -1886,19 +1834,22 @@ for ac_dir in `echo "$ac_x_includes" | sed s/include/lib/` \ /usr/openwin/share/lib \ ; \ do +dnl XXX Shouldn't this really use AC_TRY_LINK to be portable & robust?? for ac_extension in a so sl; do if test -r $ac_dir/lib${x_direct_test_library}.$ac_extension; then - no_x= ac_x_libraries=$ac_dir + ac_x_libraries=$ac_dir break 2 fi done -done])]) +done]) +fi # $ac_x_libraries = NO +]) dnl Find additional X libraries, magic flags, etc. AC_DEFUN(AC_PATH_XTRA, [AC_REQUIRE([AC_ISC_POSIX])dnl AC_REQUIRE([AC_PATH_X])dnl -if test "$no_x" = yes; then +if test "$no_x" = yes; then # Not all programs may use this symbol, but it does not hurt to define it. X_CFLAGS="$X_CFLAGS -DX_DISPLAY_MISSING" else @@ -1913,7 +1864,7 @@ else X_LIBS="$X_LIBS -L$x_libraries" if test "`(uname) 2>/dev/null`" = SunOS && uname -r | grep '^5' >/dev/null; then - X_LIBS="$X_LIBS -R$x_libraries" + X_LIBS="$X_LIBS -R $x_libraries" fi fi @@ -1940,7 +1891,7 @@ else # libraries were built with DECnet support. And karl@cs.umb.edu says # the Alpha needs dnet_stub (dnet does not exist). AC_CHECK_LIB(dnet, dnet_ntoa, [X_EXTRA_LIBS="$X_EXTRA_LIBS -ldnet"]) - if test $ac_cv_lib_dnet = no; then + if test $ac_cv_lib_dnet_dnet_ntoa = no; then AC_CHECK_LIB(dnet_stub, dnet_ntoa, [X_EXTRA_LIBS="$X_EXTRA_LIBS -ldnet_stub"]) fi diff --git a/src/util/autoconf/autoconf.info b/src/util/autoconf/autoconf.info index 0bbcfc693..050a253b8 100644 --- a/src/util/autoconf/autoconf.info +++ b/src/util/autoconf/autoconf.info @@ -1,5 +1,5 @@ -This is Info file autoconf.info, produced by Makeinfo-1.55 from the -input file autoconf.texi. +This is Info file ../autoconf.info, produced by Makeinfo-1.63 from the +input file ../autoconf.texi. START-INFO-DIR-ENTRY * Autoconf: (autoconf). Create source code configuration scripts. @@ -12,7 +12,8 @@ MacKenzie. configure source code packages using templates and an `m4' macro package. - Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. + Copyright (C) 1992, 1993, 1994, 1995, 1996 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 @@ -29,127 +30,5430 @@ versions, except that this permission notice may be stated in a translation approved by the Foundation.  -Indirect: -autoconf.info-1: 1159 -autoconf.info-2: 51142 -autoconf.info-3: 99599 -autoconf.info-4: 149475 -autoconf.info-5: 197599 +File: autoconf.info, Node: Top, Next: Introduction, Up: (dir) + + This file documents the GNU Autoconf package for creating scripts to +configure source code packages using templates and an `m4' macro +package. This is edition 2.8, for Autoconf version 2.8. + +* Menu: + +* Introduction:: Autoconf's purpose, strengths, and weaknesses. +* 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. +* Writing Macros:: Adding new macros to Autoconf. +* Manual Configuration:: Selecting features that can't be guessed. +* Site Configuration:: Local defaults for `configure'. +* Invoking configure:: How to use the Autoconf output. +* Invoking config.status:: Recreating a configuration. +* Questions:: Questions about Autoconf, with answers. +* Upgrading:: Tips for upgrading from version 1. +* History:: History of Autoconf. +* Old Macro Names:: Backward compatibility macros. +* 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. +* Macro Index:: Index of Autoconf macros. + + -- The Detailed Node Listing -- + +Making `configure' Scripts + +* Writing configure.in:: What to put in an Autoconf input file. +* Invoking autoscan:: Semi-automatic `configure.in' writing. +* Invoking ifnames:: Listing the conditionals in source code. +* Invoking autoconf:: How to create configuration scripts. +* Invoking autoreconf:: Remaking multiple `configure' scripts. + +Initialization and Output Files + +* Input:: Where Autoconf should find files. +* Output:: Creating output files. +* Makefile Substitutions:: Using output variables in `Makefile's. +* Configuration Headers:: Creating a configuration header file. +* Subdirectories:: Configuring independent packages together. +* Default Prefix:: Changing the default installation prefix. +* Versions:: Version numbers in `configure'. + +Substitutions in Makefiles + +* Preset Output Variables:: Output variables that are always set. +* Build Directories:: Supporting multiple concurrent compiles. +* Automatic Remaking:: Makefile rules for configuring. + +Configuration Header Files + +* Header Templates:: Input for the configuration headers. +* Invoking autoheader:: How to create configuration templates. + +Existing Tests + +* Alternative Programs:: Selecting between alternative programs. +* Libraries:: Library archives that might be missing. +* Library Functions:: C library functions that might be missing. +* Header Files:: Header files that might be missing. +* Structures:: Structures or members that might be missing. +* Typedefs:: `typedef's that might be missing. +* Compiler Characteristics:: C compiler or machine architecture features. +* System Services:: Operating system services. +* UNIX Variants:: Special kludges for specific UNIX variants. + +Alternative Programs + +* Particular Programs:: Special handling to find certain programs. +* Generic Programs:: How to find other programs. + +Library 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. + +Typedefs + +* Particular Typedefs:: Special handling to find certain types. +* Generic Typedefs:: How to find other types. + +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. +* Portable Shell:: Shell script portability pitfalls. +* Testing Values and Files:: Checking strings and files. +* Multiple Cases:: Tests for several possible values. +* Language Choice:: Selecting which language to use for testing. + +Checking Run Time Behavior + +* Test Programs:: Running test programs. +* Guidelines:: General rules for writing test programs. +* Test Functions:: Avoiding pitfalls in test programs. + +Results of Tests + +* Defining Symbols:: Defining C preprocessor symbols. +* Setting Output Variables:: Replacing variables in output files. +* Caching Results:: Speeding up subsequent `configure' runs. +* Printing Messages:: Notifying users of progress or problems. + +Caching Results + +* Cache Variable Names:: Shell variables used in caches. +* Cache Files:: Files `configure' uses for caching. + +Writing Macros + +* Macro Definitions:: Basic format of an Autoconf macro. +* Macro Names:: What to call your new macros. +* Quoting:: Protecting macros from unwanted expansion. +* Dependencies Between Macros:: What to do when macros depend on other macros. + +Dependencies Between Macros + +* Prerequisite Macros:: Ensuring required information. +* Suggested Ordering:: Warning about possible ordering problems. +* Obsolete Macros:: Warning about old ways of doing things. + +Manual Configuration + +* Specifying Names:: Specifying the system type. +* Canonicalizing:: Getting the canonical system type. +* System Type Variables:: Variables containing the 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. +* Site Details:: Configuring site details. +* Transforming Names:: Changing program names when installing. +* Site Defaults:: Giving `configure' local defaults. + +Transforming Program Names When Installing + +* Transformation Options:: `configure' options to transform names. +* Transformation Examples:: Sample uses of transforming names. +* Transformation Rules:: `Makefile' uses of transforming names. + +Running `configure' Scripts + +* Basic Installation:: Instructions for typical cases. +* Compilers and Options:: Selecting compilers and optimization. +* Multiple Architectures:: Compiling for multiple architectures at once. +* Installation Names:: Installing in different directories. +* Optional Features:: Selecting optional features. +* System Type:: Specifying the system type. +* Sharing Defaults:: Setting site-wide defaults for `configure'. +* Operation Controls:: Changing how `configure' runs. + +Questions About Autoconf + +* Distributing:: Distributing `configure' scripts. +* Why GNU m4:: Why not use the standard `m4'? +* Bootstrapping:: Autoconf and GNU `m4' require each other? +* Why Not Imake:: Why GNU uses `configure' instead of Imake. + +Upgrading From Version 1 + +* Changed File Names:: Files you might rename. +* Changed Makefiles:: New things to put in `Makefile.in'. +* Changed Macros:: Macro calls you might replace. +* Invoking autoupdate:: Replacing old macro names in `configure.in'. +* Changed Results:: Changes in how to check test results. +* Changed Macro Writing:: Better ways to write your own macros. + +History of Autoconf + +* Genesis:: Prehistory and naming of `configure'. +* Exodus:: The plagues of `m4' and Perl. +* Leviticus:: The priestly code of portability arrives. +* Numbers:: Growth and contributors. +* Deuteronomy:: Approaching the promises of easy configuration. + + +File: autoconf.info, Node: Introduction, Next: Making configure Scripts, Prev: Top, Up: Top + +Introduction +************ + + A physicist, an engineer, and a computer scientist were + discussing the nature of God. Surely a Physicist, said the + physicist, because early in the Creation, God made Light; and you + know, Maxwell's equations, the dual nature of electro-magnetic + waves, the relativist consequences... An Engineer!, said the + engineer, because before making Light, God split the Chaos into + Land and Water; it takes a hell of an engineer to handle that big + amount of mud, and orderly separation of solids from + liquids... The computer scientist shouted: And the Chaos, + where do you think it was coming from, hmm? + + ---Anonymous + + Autoconf is a tool for producing shell scripts that automatically +configure software source code packages to adapt to many kinds of +UNIX-like systems. The configuration scripts produced by Autoconf are +independent of Autoconf when they are run, so their users do not need to +have Autoconf. + + The configuration scripts produced by Autoconf require no manual user +intervention when run; they do not normally even need an argument +specifying the system type. Instead, they test for the presence of each +feature that the software package they are for might need individually. +(Before each check, they print a one-line message stating what they are +checking for, so the user doesn't get too bored while waiting for the +script to finish.) As a result, they deal well with systems that are +hybrids or customized from the more common UNIX variants. There is no +need to maintain files that list the features supported by each release +of each variant of UNIX. + + For each software package that Autoconf is used with, it creates a +configuration script from a template file that lists the system +features that the package needs or can use. After the shell code to +recognize and respond to a system feature has been written, Autoconf +allows it to be shared by many software packages that can use (or need) +that feature. If it later turns out that the shell code needs +adjustment for some reason, it needs to be changed in only one place; +all of the configuration scripts can be regenerated automatically to +take advantage of the updated code. + + The Metaconfig package is similar in purpose to Autoconf, but the +scripts it produces require manual user intervention, which is quite +inconvenient when configuring large source trees. Unlike Metaconfig +scripts, Autoconf scripts can support cross-compiling, if some care is +taken in writing them. + + There are several jobs related to making portable software packages +that Autoconf currently does not do. Among these are automatically +creating `Makefile' files with all of the standard targets, and +supplying replacements for standard library functions and header files +on systems that lack them. Work is in progress to add those features in +the future. + + Autoconf imposes some restrictions on the names of macros used with +`#ifdef' in C programs (*note Preprocessor Symbol Index::.). + + Autoconf requires GNU `m4' in order to generate the scripts. It +uses features that some UNIX versions of `m4' do not have. It also +overflows internal limits of some versions of `m4', including GNU `m4' +1.0. You must use version 1.1 or later of GNU `m4'. Using version 1.3 +or later will be much faster than 1.1 or 1.2. + + *Note Upgrading::, for information about upgrading from version 1. +*Note History::, for the story of Autoconf's development. *Note +Questions::, for answers to some common questions about Autoconf. + + Mail suggestions and bug reports for Autoconf to +`bug-gnu-utils@prep.ai.mit.edu'. Please include the Autoconf version +number, which you can get by running `autoconf --version'. + + +File: autoconf.info, Node: Making configure Scripts, Next: Setup, Prev: Introduction, Up: Top + +Making `configure' Scripts +************************** + + The configuration scripts that Autoconf produces are by convention +called `configure'. When run, `configure' creates several files, +replacing configuration parameters in them with appropriate values. +The files that `configure' creates are: + + * one or more `Makefile' files, one in each subdirectory of the + package (*note Makefile Substitutions::.); + + * optionally, a C header file, the name of which is configurable, + containing `#define' directives (*note Configuration Headers::.); + + * a shell script called `config.status' that, when run, will recreate + the files listed above (*note Invoking config.status::.); + + * a shell script called `config.cache' that saves the results of + running many of the tests (*note Cache Files::.); + + * a file called `config.log' containing any messages produced by + compilers, to help debugging if `configure' makes a mistake. + + To create a `configure' script with Autoconf, you need to write an +Autoconf input file `configure.in' and run `autoconf' on it. If you +write your own feature tests to supplement those that come with +Autoconf, you might also write files called `aclocal.m4' and +`acsite.m4'. If you use a C header file to contain `#define' +directives, you might also write `acconfig.h', and you will distribute +the Autoconf-generated file `config.h.in' with the package. + + Here is a diagram showing how the files that can be used in +configuration are produced. Programs that are executed are suffixed by +`*'. Optional files are enclosed in square brackets (`[]'). +`autoconf' and `autoheader' also read the installed Autoconf macro +files (by reading `autoconf.m4'). + +Files used in preparing a software package for distribution: + your source files --> [autoscan*] --> [configure.scan] --> configure.in + + configure.in --. .------> autoconf* -----> configure + +---+ + [aclocal.m4] --+ `---. + [acsite.m4] ---' | + +--> [autoheader*] -> [config.h.in] + [acconfig.h] ----. | + +-----' + [config.h.top] --+ + [config.h.bot] --' + + Makefile.in -------------------------------> Makefile.in + +Files used in configuring a software package: + .-------------> config.cache + configure* ------------+-------------> config.log + | + [config.h.in] -. v .-> [config.h] -. + +--> config.status* -+ +--> make* + Makefile.in ---' `-> Makefile ---' + +* Menu: + +* Writing configure.in:: What to put in an Autoconf input file. +* Invoking autoscan:: Semi-automatic `configure.in' writing. +* Invoking ifnames:: Listing the conditionals in source code. +* Invoking autoconf:: How to create configuration scripts. +* Invoking autoreconf:: Remaking multiple `configure' scripts. + + +File: autoconf.info, Node: Writing configure.in, Next: Invoking autoscan, Up: Making configure Scripts + +Writing `configure.in' +====================== + + To produce a `configure' script for a software package, create a +file called `configure.in' that contains invocations of the Autoconf +macros that test the system features your package needs or can use. +Autoconf macros already exist to check for many features; see *Note +Existing Tests::, for their descriptions. For most other features, you +can use Autoconf template macros to produce custom checks; see *Note +Writing Tests::, for information about them. For especially tricky or +specialized features, `configure.in' might need to contain some +hand-crafted shell commands. The `autoscan' program can give you a +good start in writing `configure.in' (*note Invoking autoscan::., for +more information). + + The order in which `configure.in' calls the Autoconf macros is not +important, with a few exceptions. Every `configure.in' must contain a +call to `AC_INIT' before the checks, and a call to `AC_OUTPUT' at the +end (*note Output::.). Additionally, some macros rely on other macros +having been called first, because they check previously set values of +some variables to decide what to do. These macros are noted in the +individual descriptions (*note Existing Tests::.), and they also warn +you when creating `configure' 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 could depend on things earlier in it. For example, library +functions could be affected by typedefs and libraries. + + `AC_INIT(FILE)' + checks for programs + checks for libraries + checks for header files + checks for typedefs + checks for structures + checks for compiler characteristics + checks for library functions + checks for system services + `AC_OUTPUT([FILE...])' + + It is best to put each macro call on its own line in `configure.in'. +Most of the macros don't add extra newlines; they rely on the newline +after the macro call to terminate the commands. This approach makes +the generated `configure' script a little easier to read by not +inserting lots of blank lines. It is generally safe to set shell +variables on the same line as a macro call, because the shell allows +assignments without intervening newlines. + + When calling macros that take arguments, there must not be any blank +space between the macro name and the open parenthesis. Arguments can be +more than one line long if they are enclosed within the `m4' quote +characters `[' and `]'. If you have a long line such as a list of file +names, you can generally use a backslash at the end of a line to +continue it logically on the next line (this is implemented by the +shell, not by anything special that Autoconf does). + + Some macros handle two cases: what to do if the given condition is +met, and what to do if the condition is not met. In some places you +might want to do something if a condition is true but do nothing if it's +false, or vice versa. To omit the true case, pass an empty value for +the ACTION-IF-FOUND argument to the macro. To omit the false case, +omit the ACTION-IF-NOT-FOUND argument to the macro, including the comma +before it. + + You can include comments in `configure.in' files by starting them +with the `m4' builtin macro `dnl', which discards text up through the +next newline. These comments do not appear in the generated +`configure' scripts. For example, it is helpful to begin +`configure.in' files with a line like this: + + dnl Process this file with autoconf to produce a configure script. + + +File: autoconf.info, Node: Invoking autoscan, Next: Invoking ifnames, Prev: Writing configure.in, Up: Making configure Scripts + +Using `autoscan' to Create `configure.in' +========================================= + + The `autoscan' program can help you create a `configure.in' file for +a software package. `autoscan' examines source files in the directory +tree rooted at a directory given as a command line argument, or the +current directory if none is given. It searches the source files for +common portability problems and creates a file `configure.scan' which +is a preliminary `configure.in' for that package. + + You should manually examine `configure.scan' before renaming it to +`configure.in'; it will probably need some adjustments. Occasionally +`autoscan' outputs a macro in the wrong order relative to another +macro, so that `autoconf' produces a warning; you need to move such +macros manually. Also, if you want the package to use a configuration +header file, you must add a call to `AC_CONFIG_HEADER' (*note +Configuration Headers::.). You might also have to change or add some +`#if' directives to your program in order to make it work with Autoconf +(*note Invoking ifnames::., for information about a program that can +help with that job). + + `autoscan' uses several data files, which are installed along with +the distributed Autoconf macro files, to determine which macros to +output when it finds particular symbols in a package's source files. +These files all have the same format. Each line consists of a symbol, +whitespace, and the Autoconf macro to output if that symbol is +encountered. Lines starting with `#' are comments. + + `autoscan' is only installed if you already have Perl installed. +`autoscan' accepts the following options: + +`--help' + Print a summary of the command line options and exit. + +`--macrodir=DIR' + Look for the data files in directory DIR instead of the default + installation directory. You can also set the `AC_MACRODIR' + environment variable to a directory; this option overrides the + environment variable. + +`--verbose' + Print the names of the files it examines and the potentially + interesting symbols it finds in them. This output can be + voluminous. + +`--version' + Print the version number of Autoconf and exit. + + +File: autoconf.info, Node: Invoking ifnames, Next: Invoking autoconf, Prev: Invoking autoscan, Up: Making configure Scripts + +Using `ifnames' to List Conditionals +==================================== + + `ifnames' can help when writing a `configure.in' 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, this program can help you figure out what its +`configure' needs to check for. It may help fill in some gaps in a +`configure.in' generated by `autoscan' (*note Invoking autoscan::.). + + `ifnames' scans all of the C source files named on the command line +(or the standard input, if none are given) and writes to the standard +output a sorted list of all the identifiers that appear in those files +in `#if', `#elif', `#ifdef', or `#ifndef' directives. It prints each +identifier on a line, followed by a space-separated list of the files +in which that identifier occurs. + +`ifnames' accepts the following options: + +`--help' +`-h' + Print a summary of the command line options and exit. + +`--macrodir=DIR' +`-m DIR' + Look for the Autoconf macro files in directory DIR instead of the + default installation directory. Only used to get the version + number. You can also set the `AC_MACRODIR' environment variable + to a directory; this option overrides the environment variable. + +`--version' + Print the version number of Autoconf and exit. + + +File: autoconf.info, Node: Invoking autoconf, Next: Invoking autoreconf, Prev: Invoking ifnames, Up: Making configure Scripts + +Using `autoconf' to Create `configure' +====================================== + + To create `configure' from `configure.in', run the `autoconf' +program with no arguments. `autoconf' processes `configure.in' with +the `m4' macro processor, using the Autoconf macros. If you give +`autoconf' an argument, it reads that file instead of `configure.in' +and writes the configuration script to the standard output instead of +to `configure'. If you give `autoconf' the argument `-', it reads the +standard input instead of `configure.in' and writes the configuration +script on the standard output. + + The Autoconf macros are defined in several files. Some of the files +are distributed with Autoconf; `autoconf' reads them first. Then it +looks for the optional file `acsite.m4' in the directory that contains +the distributed Autoconf macro files, and for the optional file +`aclocal.m4' in the current directory. Those files can contain your +site's or the package's own Autoconf macro definitions (*note Writing +Macros::., for more information). If a macro is defined in more than +one of the files that `autoconf' reads, the last definition it reads +overrides the earlier ones. + + `autoconf' accepts the following options: + +`--help' +`-h' + Print a summary of the command line options and exit. + +`--localdir=DIR' +`-l DIR' + Look for the package file `aclocal.m4' in directory DIR instead of + in the current directory. + +`--macrodir=DIR' +`-m DIR' + Look for the installed macro files in directory DIR. You can also + set the `AC_MACRODIR' environment variable to a directory; this + option overrides the environment variable. + +`--version' + Print the version number of Autoconf and exit. + + +File: autoconf.info, Node: Invoking autoreconf, Prev: Invoking autoconf, Up: Making configure Scripts + +Using `autoreconf' to Update `configure' Scripts +================================================ + + If you have a lot of Autoconf-generated `configure' scripts, the +`autoreconf' program can save you some work. It runs `autoconf' (and +`autoheader', where appropriate) repeatedly to remake the Autoconf +`configure' scripts and configuration header templates in the directory +tree rooted at the current directory. By default, it only remakes +those files that are older than their `configure.in' or (if present) +`aclocal.m4'. Since `autoheader' does not change the timestamp of its +output file if the file wouldn't be changing, this is not necessarily +the minimum amount of work. If you install a new version of Autoconf, +you can make `autoreconf' remake *all* of the files by giving it the +`--force' option. + + If you give `autoreconf' the `--macrodir=DIR' or `--localdir=DIR' +options, it passes them down to `autoconf' and `autoheader' (with +relative paths adjusted properly). + + *Note Automatic Remaking::, for `Makefile' rules to automatically +remake `configure' scripts when their source files change. That method +handles the timestamps of configuration header templates properly, but +does not pass `--macrodir=DIR' or `--localdir=DIR'. + +`autoreconf' accepts the following options: + +`--help' +`-h' + Print a summary of the command line options and exit. + +`--force' +`-f' + Remake even `configure' scripts and configuration headers that are + newer than their input files (`configure.in' and, if present, + `aclocal.m4'). + +`--localdir=DIR' +`-l DIR' + Look for the package files `aclocal.m4' and `acconfig.h' (but not + `FILE.top' and `FILE.bot') in directory DIR instead of in the + directory containing each `configure.in'. + +`--macrodir=DIR' +`-m DIR' + Look for the Autoconf macro files in directory DIR instead of the + default installation directory. You can also set the `AC_MACRODIR' + environment variable to a directory; this option overrides the + environment variable. + +`--verbose' + Print the name of each directory where `autoreconf' runs + `autoconf' (and `autoheader', if appropriate). + +`--version' + Print the version number of Autoconf and exit. + + +File: autoconf.info, Node: Setup, Next: Existing Tests, Prev: Making configure Scripts, Up: Top + +Initialization and Output Files +******************************* + + Autoconf-generated `configure' scripts need some information about +how to initialize, such as how to find the package's source files; and +about the output files to produce. The following sections describe +initialization and creating output files. + +* Menu: + +* Input:: Where Autoconf should find files. +* Output:: Creating output files. +* Makefile Substitutions:: Using output variables in `Makefile's. +* Configuration Headers:: Creating a configuration header file. +* Subdirectories:: Configuring independent packages together. +* Default Prefix:: Changing the default installation prefix. +* Versions:: Version numbers in `configure'. + + +File: autoconf.info, Node: Input, Next: Output, Up: Setup + +Finding `configure' Input +========================= + + Every `configure' script must call `AC_INIT' before doing anything +else. The only other required macro is `AC_OUTPUT' (*note Output::.). + + - Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR) + Process any command-line arguments and find the source code + directory. UNIQUE-FILE-IN-SOURCE-DIR is some file that is in the + package's source directory; `configure' checks for this file's + existence to make sure that the directory that it is told contains + the source code in fact does. Occasionally people accidentally + specify the wrong directory with `--srcdir'; this is a safety + check. *Note Invoking configure::, for more information. + + Packages that do manual configuration or use the `install' program +might need to tell `configure' where to find some other shell scripts +by calling `AC_CONFIG_AUX_DIR', though the default places it looks are +correct for most cases. + + - Macro: AC_CONFIG_AUX_DIR(DIR) + Use the `install-sh', `config.sub', `config.guess', and Cygnus + `configure' scripts that are in directory DIR. These are + auxiliary files used in configuration. DIR can be either absolute + or relative to `SRCDIR'. The default is `SRCDIR' or `SRCDIR/..' or + `SRCDIR/../..', whichever is the first that contains `install-sh'. + The other files are not checked for, so that using + `AC_PROG_INSTALL' does not automatically require distributing the + other auxiliary files. It checks for `install.sh' also, but that + name is obsolete because some `make' programs have a rule that + creates `install' from it if there is no `Makefile'. + + +File: autoconf.info, Node: Output, Next: Makefile Substitutions, Prev: Input, Up: Setup + +Creating Output Files +===================== + + Every Autoconf-generated `configure' script must finish by calling +`AC_OUTPUT'. It is the macro that creates the `Makefile's and optional +other files resulting from configuration. The only other required +macro is `AC_INIT' (*note Input::.). + + - Macro: AC_OUTPUT ([FILE...] [,EXTRA-CMDS] [,INIT-CMDS]) + Create output files. The FILE... argument is a + whitespace-separated list of output files; it may be empty. This + macro creates each file `FILE' by copying an input file (by default + named `FILE.in'), substituting the output variable values. *Note + Makefile Substitutions::, for more information on using output + variables. *Note Setting Output Variables::, for more information + on creating them. This macro creates the directory that the file + is in if it doesn't exist (but not the parents of that directory). + Usually, `Makefile's are created this way, but other files, such + as `.gdbinit', can be specified as well. + + If `AC_CONFIG_HEADER', `AC_LINK_FILES', or `AC_CONFIG_SUBDIRS' has + been called, this macro also creates the files named as their + arguments. + + A typical call to `AC_OUTPUT' looks like this: + AC_OUTPUT(Makefile src/Makefile man/Makefile X/Imakefile) + + You can override an input file name by appending it to FILE, + separated by a colon. For example, + AC_OUTPUT(Makefile:templates/top.mk lib/Makefile:templates/lib.mk) + + If you pass EXTRA-CMDS, those commands will be inserted into + `config.status' to be run after all its other processing. If + INIT-CMDS are given, they are inserted just before EXTRA-CMDS, + with shell variable, command, and backslash substitutions + performed on them in `configure'. You can use INIT-CMDS to pass + variables from `configure' to the EXTRA-CMDS. + + If you run `make' on subdirectories, you should run it using the +`make' variable `MAKE'. Most versions of `make' set `MAKE' to the name +of the `make' program plus any options it was given. (But many do not +include in it the values of any variables set on the command line, so +those are not passed on automatically.) Some old versions of `make' do +not set this variable. The following macro allows you to use it even +with those versions. + + - Macro: AC_PROG_MAKE_SET + If `make' predefines the variable `MAKE', define output variable + `SET_MAKE' to be empty. Otherwise, define `SET_MAKE' to contain + `MAKE=make'. Calls `AC_SUBST' for `SET_MAKE'. + + To use this macro, place a line like this in each `Makefile.in' that +runs `MAKE' on other directories: + + @SET_MAKE@ + + +File: autoconf.info, Node: Makefile Substitutions, Next: Configuration Headers, Prev: Output, Up: Setup + +Substitutions in Makefiles +========================== + + Each subdirectory in a distribution that contains something to be +compiled or installed should come with a file `Makefile.in', from which +`configure' will create a `Makefile' in that directory. To create a +`Makefile', `configure' performs a simple variable substitution, +replacing occurrences of `@VARIABLE@' in `Makefile.in' with the value +that `configure' has determined for that variable. Variables that are +substituted into output files in this way are called "output +variables". They are ordinary shell variables that are set in +`configure'. To make `configure' substitute a particular variable into +the output files, the macro `AC_SUBST' must be called with that +variable name as an argument. Any occurrences of `@VARIABLE@' for +other variables are left unchanged. *Note Setting Output Variables::, +for more information on creating output variables with `AC_SUBST'. + + A software package that uses a `configure' script should be +distributed with a file `Makefile.in', but no `Makefile'; that way, the +user has to properly configure the package for the local system before +compiling it. + + *Note Makefile Conventions: (standards)Makefile Conventions, for +more information on what to put in `Makefile's. + +* Menu: + +* Preset Output Variables:: Output variables that are always set. +* Build Directories:: Supporting multiple concurrent compiles. +* Automatic Remaking:: Makefile rules for configuring. + + +File: autoconf.info, Node: Preset Output Variables, Next: Build Directories, Up: Makefile Substitutions + +Preset Output Variables +----------------------- + + Some output variables are preset by the Autoconf macros. Some of the +Autoconf macros set additional output variables, which are mentioned in +the descriptions for those macros. *Note Output Variable Index::, for a +complete list of output variables. Here is what each of the preset ones +contains. *Note Variables for Installation Directories: +(standards)Directory Variables, for more information about the +variables with names that end in `dir'. + + - Variable: bindir + The directory for installing executables that users run. + + - Variable: configure_input + A comment saying that the file was generated automatically by + `configure' and giving the name of the input file. `AC_OUTPUT' + adds a comment line containing this variable to the top of every + `Makefile' it creates. For other files, you should reference this + variable in a comment at the top of each input file. For example, + an input shell script should begin like this: + + #! /bin/sh + # @configure_input@ + + The presence of that line also reminds people editing the file + that it needs to be processed by `configure' in order to be used. + + - Variable: datadir + The directory for installing read-only architecture-independent + data. + + - Variable: exec_prefix + The installation prefix for architecture-dependent files. + + - Variable: includedir + The directory for installing C header files. + + - Variable: infodir + The directory for installing documentation in Info format. + + - Variable: libdir + The directory for installing object code libraries. + + - Variable: libexecdir + The directory for installing executables that other programs run. + + - Variable: localstatedir + The directory for installing modifiable single-machine data. + + - Variable: mandir + The top-level directory for installing documentation in man format. + + - Variable: oldincludedir + The directory for installing C header files for non-gcc compilers. + + - Variable: prefix + The installation prefix for architecture-independent files. + + - Variable: sbindir + The directory for installing executables that system + administrators run. + + - Variable: sharedstatedir + The directory for installing modifiable architecture-independent + data. + + - Variable: srcdir + The directory that contains the source code for that `Makefile'. + + - Variable: sysconfdir + The directory for installing read-only single-machine data. + + - Variable: top_srcdir + The top-level source code directory for the package. In the + top-level directory, this is the same as `srcdir'. + + - Variable: CFLAGS + Debugging and optimization options for the C compiler. If it is + not set in the environment when `configure' runs, the default + value is set when you call `AC_PROG_CC' (or empty if you don't). + `configure' uses this variable when compiling programs to test for + C features. + + - Variable: CPPFLAGS + Header file search directory (`-IDIR') and any other miscellaneous + options for the C preprocessor and compiler. If it is not set in + the environment when `configure' runs, the default value is empty. + `configure' uses this variable when compiling or preprocessing + programs to test for C features. + + - Variable: CXXFLAGS + Debugging and optimization options for the C++ compiler. If it is + not set in the environment when `configure' runs, the default + value is set when you call `AC_PROG_CXX' (or empty if you don't). + `configure' uses this variable when compiling programs to test for + C++ features. + + - Variable: DEFS + `-D' options to pass to the C compiler. If `AC_CONFIG_HEADER' is + called, `configure' replaces `@DEFS@' with `-DHAVE_CONFIG_H' + instead (*note Configuration Headers::.). This variable is not + defined while `configure' is performing its tests, only when + creating the output files. *Note Setting Output Variables::, for + how to check the results of previous tests. + + - Variable: LDFLAGS + Stripping (`-s') and any other miscellaneous options for the + linker. If it is not set in the environment when `configure' runs, + the default value is empty. `configure' uses this variable when + linking programs to test for C features. + + - Variable: LIBS + `-l' and `-L' options to pass to the linker. + + +File: autoconf.info, Node: Build Directories, Next: Automatic Remaking, Prev: Preset Output Variables, Up: Makefile Substitutions + +Build Directories +----------------- + + You can support compiling a software package for several +architectures simultaneously from the same copy of the source code. +The object files for each architecture are kept in their own directory. + + To support doing this, `make' uses the `VPATH' variable to find the +files that are in the source directory. GNU `make' and most other +recent `make' programs can do this. Older `make' programs do not +support `VPATH'; when using them, the source code must be in the same +directory as the object files. + + To support `VPATH', each `Makefile.in' should contain two lines that +look like: + + srcdir = @srcdir@ + VPATH = @srcdir@ + + Do not set `VPATH' to the value of another variable, for example +`VPATH = $(srcdir)', because some versions of `make' do not do variable +substitutions on the value of `VPATH'. + + `configure' substitutes in the correct value for `srcdir' when it +produces `Makefile'. + + Do not use the `make' variable `$<', which expands to the pathname +of the file in the source directory (found with `VPATH'), except in +implicit rules. (An implicit rule is one such as `.c.o', which tells +how to create a `.o' file from a `.c' file.) Some versions of `make' +do not set `$<' in explicit rules; they expand it to an empty value. + + Instead, `Makefile' command lines should always refer to source +files by prefixing them with `$(srcdir)/'. For example: + + time.info: time.texinfo + $(MAKEINFO) $(srcdir)/time.texinfo + + +File: autoconf.info, Node: Automatic Remaking, Prev: Build Directories, Up: Makefile Substitutions + +Automatic Remaking +------------------ + + You can put rules like the following in the top-level `Makefile.in' +for a package to automatically update the configuration information when +you change the configuration files. This example includes all of the +optional files, such as `aclocal.m4' and those related to configuration +header files. Omit from the `Makefile.in' rules any of these files +that your package does not use. + + The `${srcdir}/' prefix is included because of limitations in the +`VPATH' mechanism. + + The `stamp-' files are necessary because the timestamps of +`config.h.in' and `config.h' will not be changed if remaking them does +not change their contents. This feature avoids unnecessary +recompilation. You should include the file `stamp-h.in' your package's +distribution, so `make' will consider `config.h.in' up to date. On +some old BSD systems, `touch' or any command that results in an empty +file does not update the timestamps, so use a command like `echo' as a +workaround. + + ${srcdir}/configure: configure.in 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.in aclocal.m4 acconfig.h \ + config.h.top config.h.bot + 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 + + In addition, you should pass `echo timestamp > stamp-h' in the +EXTRA-CMDS argument to `AC_OUTPUT', so `config.status' will ensure that +`config.h' is considered up to date. *Note Output::, for more +information about `AC_OUTPUT'. + + *Note Invoking config.status::, for more examples of handling +configuration-related dependencies. + + +File: autoconf.info, Node: Configuration Headers, Next: Subdirectories, Prev: Makefile Substitutions, Up: Setup + +Configuration Header Files +========================== + + When a package tests more than a few C preprocessor symbols, the +command lines to pass `-D' options to the compiler can get quite long. +This causes two problems. One is that the `make' output is hard to +visually scan for errors. More seriously, the command lines can exceed +the length limits of some operating systems. As an alternative to +passing `-D' options to the compiler, `configure' scripts can create a +C header file containing `#define' directives. The `AC_CONFIG_HEADER' +macro selects this kind of output. It should be called right after +`AC_INIT'. + + The package should `#include' the configuration header file before +any other header files, to prevent inconsistencies in declarations (for +example, if it redefines `const'). Use `#include ' instead +of `#include "config.h"', and pass the C compiler a `-I.' option (or +`-I..'; whichever directory contains `config.h'). That way, even if +the source directory is configured itself (perhaps to make a +distribution), other build directories can also be configured without +finding the `config.h' from the source directory. + + - Macro: AC_CONFIG_HEADER (HEADER-TO-CREATE ...) + Make `AC_OUTPUT' create the file(s) in the whitespace-separated + list HEADER-TO-CREATE containing C preprocessor `#define' + statements, and replace `@DEFS@' in generated files with + `-DHAVE_CONFIG_H' instead of the value of `DEFS'. The usual name + for HEADER-TO-CREATE is `config.h'. + + If HEADER-TO-CREATE already exists and its contents are identical + to what `AC_OUTPUT' would put in it, it is left alone. Doing this + allows some changes in configuration without needlessly causing + object files that depend on the header file to be recompiled. + + Usually the input file is named `HEADER-TO-CREATE.in'; however, + you can override the input file name by appending it to + HEADER-TO-CREATE, separated by a colon. For example, + AC_CONFIG_HEADER(defines.h:defines.hin) + + Doing this allows you to keep your filenames acceptable to MS-DOS. + +* Menu: + +* Header Templates:: Input for the configuration headers. +* Invoking autoheader:: How to create configuration templates. + + +File: autoconf.info, Node: Header Templates, Next: Invoking autoheader, Up: Configuration Headers + +Configuration Header Templates +------------------------------ + + Your distribution should contain a template file that looks as you +want the final header file to look, including comments, with default +values in the `#define' statements. For example, suppose your +`configure.in' makes these calls: + + AC_CONFIG_HEADER(conf.h) + AC_CHECK_HEADERS(unistd.h) + +Then you could have code like the following in `conf.h.in'. On systems +that have `unistd.h', `configure' will change the 0 to a 1. On other +systems, it will leave the line unchanged. + + /* Define as 1 if you have unistd.h. */ + #define HAVE_UNISTD_H 0 + + Alternately, if your code tests for configuration options using +`#ifdef' instead of `#if', a default value can be to `#undef' the +variable instead of to define it to a value. On systems that have +`unistd.h', `configure' will change the second line to read `#define +HAVE_UNISTD_H 1'. On other systems, it will comment that line out (in +case the system predefines that symbol). + + /* Define if you have unistd.h. */ + #undef HAVE_UNISTD_H + + +File: autoconf.info, Node: Invoking autoheader, Prev: Header Templates, Up: Configuration Headers + +Using `autoheader' to Create `config.h.in' +------------------------------------------ + + The `autoheader' program can create a template file of C `#define' +statements for `configure' to use. If `configure.in' invokes +`AC_CONFIG_HEADER(FILE)', `autoheader' creates `FILE.in'; if multiple +file arguments are given, the first one is used. Otherwise, +`autoheader' creates `config.h.in'. + + If you give `autoheader' an argument, it uses that file instead of +`configure.in' and writes the header file to the standard output +instead of to `config.h.in'. If you give `autoheader' an argument of +`-', it reads the standard input instead of `configure.in' and writes +the header file to the standard output. + + `autoheader' scans `configure.in' and figures out which C +preprocessor symbols it might define. It copies comments and `#define' +and `#undef' statements from a file called `acconfig.h', which comes +with and is installed with Autoconf. It also uses a file called +`acconfig.h' in the current directory, if present. If you `AC_DEFINE' +any additional symbols, you must create that file with entries for +them. For symbols defined by `AC_CHECK_HEADERS', `AC_CHECK_FUNCS', +`AC_CHECK_SIZEOF', or `AC_CHECK_LIB', `autoheader' generates comments +and `#undef' statements itself rather than copying them from a file, +since the possible symbols are effectively limitless. + + The file that `autoheader' creates contains mainly `#define' and +`#undef' statements and their accompanying comments. If `./acconfig.h' +contains the string `@TOP@', `autoheader' copies the lines before the +line containing `@TOP@' into the top of the file that it generates. +Similarly, if `./acconfig.h' contains the string `@BOTTOM@', +`autoheader' copies the lines after that line to the end of the file it +generates. Either or both of those strings may be omitted. + + An alternate way to produce the same effect is to create the files +`FILE.top' (typically `config.h.top') and/or `FILE.bot' in the current +directory. If they exist, `autoheader' copies them to the beginning +and end, respectively, of its output. Their use is discouraged because +they have file names that contain two periods, and so can not be stored +on MS-DOS; also, they are two more files to clutter up the directory. +But if you use the `--localdir=DIR' option to use an `acconfig.h' in +another directory, they give you a way to put custom boilerplate in each +individual `config.h.in'. + + `autoheader' accepts the following options: + +`--help' +`-h' + Print a summary of the command line options and exit. + +`--localdir=DIR' +`-l DIR' + Look for the package files `aclocal.m4' and `acconfig.h' (but not + `FILE.top' and `FILE.bot') in directory DIR instead of in the + current directory. + +`--macrodir=DIR' +`-m DIR' + Look for the installed macro files and `acconfig.h' in directory + DIR. You can also set the `AC_MACRODIR' environment variable to a + directory; this option overrides the environment variable. + +`--version' + Print the version number of Autoconf and exit. + + +File: autoconf.info, Node: Subdirectories, Next: Default Prefix, Prev: Configuration Headers, Up: Setup + +Configuring Other Packages in Subdirectories +============================================ + + In most situations, calling `AC_OUTPUT' is sufficient to produce +`Makefile's in subdirectories. However, `configure' scripts that +control more than one independent package can use `AC_CONFIG_SUBDIRS' +to run `configure' scripts for other packages in subdirectories. + + - Macro: AC_CONFIG_SUBDIRS (DIR ...) + Make `AC_OUTPUT' run `configure' in each subdirectory DIR in the + given whitespace-separated list. If a given DIR is not found, no + error is reported, so a `configure' script can configure whichever + parts of a large source tree are present. If a given DIR contains + `configure.in' but no `configure', the Cygnus `configure' script + found by `AC_CONFIG_AUXDIR' is used. The subdirectory `configure' + scripts are given the same command line options that were given to + this `configure' script, with minor changes if needed (e.g., to + adjust a relative path for the cache file or source directory). + This macro also sets the output variable `subdirs' to the list of + directories `DIR ...'. `Makefile' rules can use this variable to + determine which subdirectories to recurse into. + + +File: autoconf.info, Node: Default Prefix, Next: Versions, Prev: Subdirectories, Up: Setup + +Default Prefix +============== + + By default, `configure' sets the prefix for files it installs to +`/usr/local'. The user of `configure' can select a different prefix +using the `--prefix' and `--exec-prefix' options. There are two ways +to change the default: when creating `configure', and when running it. + + Some software packages might want to install in a directory besides +`/usr/local' by default. To accomplish that, use the +`AC_PREFIX_DEFAULT' macro. + + - Macro: AC_PREFIX_DEFAULT (PREFIX) + Set the default installation prefix to PREFIX instead of + `/usr/local'. + + It may be convenient for users to have `configure' guess the +installation prefix from the location of a related program that they +have already installed. If you wish to do that, you can call +`AC_PREFIX_PROGRAM'. + + - Macro: AC_PREFIX_PROGRAM (PROGRAM) + If the user did not specify an installation prefix (using the + `--prefix' option), guess a value for it by looking for PROGRAM in + `PATH', the way the shell does. If PROGRAM is found, set the + prefix to the parent of the directory containing PROGRAM; + otherwise leave the prefix specified in `Makefile.in' unchanged. + For example, if PROGRAM is `gcc' and the `PATH' contains + `/usr/local/gnu/bin/gcc', set the prefix to `/usr/local/gnu'. + + +File: autoconf.info, Node: Versions, Prev: Default Prefix, Up: Setup + +Version Numbers in `configure' +============================== + + The following macros manage version numbers for `configure' scripts. +Using them is optional. + + - Macro: AC_PREREQ (VERSION) + Ensure that a recent enough version of Autoconf is being used. If + the version of Autoconf being used to create `configure' is earlier + than VERSION, print an error message on the standard error output + and do not create `configure'. For example: + + AC_PREREQ(1.8) + + This macro is useful if your `configure.in' relies on non-obvious + behavior that changed between Autoconf releases. If it merely + needs recently added macros, then `AC_PREREQ' is less useful, + because the `autoconf' program already tells the user which macros + are not found. The same thing happens if `configure.in' is + processed by a version of Autoconf older than when `AC_PREREQ' was + added. + + - Macro: AC_REVISION (REVISION-INFO) + Copy revision stamp REVISION-INFO into the `configure' script, + with any dollar signs or double-quotes removed. This macro lets + you put a revision stamp from `configure.in' into `configure' + without RCS or CVS changing it when you check in `configure'. That + way, you can determine easily which revision of `configure.in' a + particular `configure' corresponds to. + + It is a good idea to call this macro before `AC_INIT' so that the + revision number is near the top of both `configure.in' and + `configure'. To support doing that, the `AC_REVISION' output + begins with `#! /bin/sh', like the normal start of a `configure' + script does. + + For example, this line in `configure.in': + + AC_REVISION($Revision$)dnl + + produces this in `configure': + + #! /bin/sh + # From configure.in Revision: 1.30 + + +File: autoconf.info, Node: Existing Tests, Next: Writing Tests, Prev: Setup, Up: Top + +Existing Tests +************** + + These macros test for particular system features that packages might +need or want to use. If you need to test for a kind of feature that +none of these macros check for, you can probably do it by calling +primitive test macros with appropriate arguments (*note Writing +Tests::.). + + These tests print messages telling the user which feature they're +checking for, and what they find. They cache their results for future +`configure' runs (*note Caching Results::.). + + Some of these macros set output variables. *Note Makefile +Substitutions::, for how to get their values. The phrase "define NAME" +is used below as a shorthand to mean "define C preprocessor symbol NAME +to the value 1". *Note Defining Symbols::, for how to get those symbol +definitions into your program. + +* Menu: + +* Alternative Programs:: Selecting between alternative programs. +* Libraries:: Library archives that might be missing. +* Library Functions:: C library functions that might be missing. +* Header Files:: Header files that might be missing. +* Structures:: Structures or members that might be missing. +* Typedefs:: `typedef's that might be missing. +* Compiler Characteristics:: C compiler or machine architecture features. +* System Services:: Operating system services. +* UNIX Variants:: Special kludges for specific UNIX variants. + + +File: autoconf.info, Node: Alternative Programs, Next: Libraries, Up: Existing Tests + +Alternative Programs +==================== + + These macros check for the presence or behavior of particular +programs. They are used to choose between several alternative programs +and to decide what to do once one has been chosen. If there is no +macro specifically defined to check for a program you need, and you +don't need to check for any special properties of it, then you can use +one of the general program check macros. + +* Menu: + +* Particular Programs:: Special handling to find certain programs. +* Generic Programs:: How to find other programs. + + +File: autoconf.info, Node: Particular Programs, Next: Generic Programs, Up: Alternative Programs + +Particular Program Checks +------------------------- + + These macros check for particular programs--whether they exist, and +in some cases whether they support certain features. + + - Macro: AC_DECL_YYTEXT + Define `YYTEXT_POINTER' if `yytext' is a `char *' instead of a + `char []'. Also set output variable `LEX_OUTPUT_ROOT' to the base + of the file name that the lexer generates; usually `lex.yy', but + sometimes something else. These results vary according to whether + `lex' or `flex' is being used. + + - Macro: AC_PROG_AWK + Check for `mawk', `gawk', `nawk', and `awk', in that order, and + set output variable `AWK' to the first one that it finds. It + tries `mawk' first because that is reported to be the fastest + implementation. + + - Macro: AC_PROG_CC + Determine a C compiler to use. If `CC' is not already set in the + environment, check for `gcc', and use `cc' if it's not found. Set + output variable `CC' to the name of the compiler found. + + If using the GNU C compiler, set shell variable `GCC' to `yes', + empty otherwise. If output variable `CFLAGS' was not already set, + set it to `-g -O' for the GNU C compiler (`-O' on systems where + GCC does not accept `-g'), or `-g' for other compilers. + + - Macro: AC_PROG_CC_C_O + If the C compiler does not accept the `-c' and `-o' options + simultaneously, define `NO_MINUS_C_MINUS_O'. + + - Macro: AC_PROG_CPP + Set output variable `CPP' to a command that runs the C + preprocessor. If `$CC -E' doesn't work, it uses `/lib/cpp'. It + is only portable to run `CPP' on files with a `.c' extension. + + If the current language is C (*note Language Choice::.), many of + the specific test macros use the value of `CPP' indirectly by + calling `AC_TRY_CPP', `AC_CHECK_HEADER', `AC_EGREP_HEADER', or + `AC_EGREP_CPP'. + + - Macro: AC_PROG_CXX + Determine a C++ compiler to use. Check if the environment variable + `CXX' or `CCC' (in that order) is set; if so, set output variable + `CXX' to its value. Otherwise search for a C++ compiler under + likely names (`c++', `g++', `gcc', `CC', and `cxx'). If none of + those checks succeed, as a last resort set `CXX' to `gcc'. + + If using the GNU C++ compiler, set shell variable `GXX' to `yes', + empty otherwise. If output variable `CXXFLAGS' was not already + set, set it to `-g -O' for the GNU C++ compiler (`-O' on systems + where G++ does not accept `-g'), or `-g' for other compilers. + + - Macro: AC_PROG_CXXCPP + Set output variable `CXXCPP' to a command that runs the C++ + preprocessor. If `$CXX -E' doesn't work, it uses `/lib/cpp'. It + is only portable to run `CXXCPP' on files with a `.c', `.C', or + `.cc' extension. + + If the current language is C++ (*note Language Choice::.), many of + the specific test macros use the value of `CXXCPP' indirectly by + calling `AC_TRY_CPP', `AC_CHECK_HEADER', `AC_EGREP_HEADER', or + `AC_EGREP_CPP'. + + - Macro: AC_PROG_GCC_TRADITIONAL + Add `-traditional' to output variable `CC' if using the GNU C + compiler and `ioctl' does not work properly without + `-traditional'. That usually happens when the fixed header files + have not been installed on an old system. Since recent versions + of the GNU C compiler fix the header files automatically when + installed, this is becoming a less prevalent problem. + + - Macro: AC_PROG_INSTALL + Set output variable `INSTALL' to the path of a BSD compatible + `install' program, if one is found in the current `PATH'. + Otherwise, set `INSTALL' to `DIR/install-sh -c', checking the + directories specified to `AC_CONFIG_AUX_DIR' (or its default + directories) to determine DIR (*note Output::.). Also set the + variable `INSTALL_PROGRAM' to `${INSTALL}' and `INSTALL_DATA' to + `${INSTALL} -m 644'. + + This macro screens out various instances of `install' known to not + work. It prefers to find a C program rather than a shell script, + for speed. Instead of `install-sh', it can also use `install.sh', + but that name is obsolete because some `make' programs have a rule + that creates `install' from it if there is no `Makefile'. + + A copy of `install-sh' which you may use comes with Autoconf. If + you use `AC_PROG_INSTALL', you must include either `install-sh' or + `install.sh' in your distribution, or `configure' will produce an + error message saying it can't find them--even if the system you're + on has a good `install' program. This check is a safety measure + to prevent you from accidentally leaving that file out, which + would prevent your package from installing on systems that don't + have a BSD-compatible `install' program. + + If you need to use your own installation program because it has + features not found in standard `install' programs, there is no + reason to use `AC_PROG_INSTALL'; just put the pathname of your + program into your `Makefile.in' files. + + - Macro: AC_PROG_LEX + If `flex' is found, set output variable `LEX' to `flex' and + `LEXLIB' to `-lfl', if that library is in a standard place. + Otherwise set `LEX' to `lex' and `LEXLIB' to `-ll'. + + - Macro: AC_PROG_LN_S + If `ln -s' works on the current filesystem (the operating system + and filesystem support symbolic links), set output variable `LN_S' + to `ln -s', otherwise set it to `ln'. + + - Macro: AC_PROG_RANLIB + Set output variable `RANLIB' to `ranlib' if `ranlib' is found, + otherwise to `:' (do nothing). + + - Macro: AC_PROG_YACC + If `bison' is found, set output variable `YACC' to `bison -y'. + Otherwise, if `byacc' is found, set `YACC' to `byacc'. Otherwise + set `YACC' to `yacc'. + + +File: autoconf.info, Node: Generic Programs, Prev: Particular Programs, Up: Alternative Programs + +Generic Program Checks +---------------------- + + These macros are used to find programs not covered by the particular +test macros. If you need to check the behavior of a program as well as +find out whether it is present, you have to write your own test for it +(*note Writing Tests::.). By default, these macros use the environment +variable `PATH'. If you need to check for a program that might not be +in the user's `PATH', you can pass a modified path to use instead, like +this: + + AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd, + $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc) + + - Macro: AC_CHECK_PROG (VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND [, + VALUE-IF-NOT-FOUND [, PATH, [ REJECT ]]]) + Check whether program PROG-TO-CHECK-FOR exists in `PATH'. If it + is found, set VARIABLE to VALUE-IF-FOUND, otherwise to + VALUE-IF-NOT-FOUND, if given. Always pass over REJECT (an + absolute file name) even if it is the first found in the search + path; in that case, set VARIABLE using the absolute file name of + the PROG-TO-CHECK-FOR found that is not REJECT. If VARIABLE was + already set, do nothing. Calls `AC_SUBST' for VARIABLE. + + - Macro: AC_CHECK_PROGS (VARIABLE, PROGS-TO-CHECK-FOR [, + VALUE-IF-NOT-FOUND [, PATH]]) + Check for each program in the whitespace-separated list + PROGS-TO-CHECK-FOR exists in `PATH'. If it is found, set VARIABLE + to the name of that program. Otherwise, continue checking the + next program in the list. If none of the programs in the list are + found, set VARIABLE to VALUE-IF-NOT-FOUND; if VALUE-IF-NOT-FOUND + is not specified, the value of VARIABLE is not changed. Calls + `AC_SUBST' for VARIABLE. + + - Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR [, + VALUE-IF-NOT-FOUND [, PATH]]) + Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a + prefix of the host type as determined by `AC_CANONICAL_HOST', + followed by a dash (*note Canonicalizing::.). For example, if the + user runs `configure --host=i386-gnu', then this call: + AC_CHECK_TOOL(RANLIB, ranlib, :) + + sets `RANLIB' to `i386-gnu-ranlib' if that program exists in + `PATH', or to `ranlib' if that program exists in `PATH', or to `:' + if neither program exists. + + - Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR [, + VALUE-IF-NOT-FOUND [, PATH]]) + Like `AC_CHECK_PROG', but set VARIABLE to the entire path of + PROG-TO-CHECK-FOR if found. + + - Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR [, + VALUE-IF-NOT-FOUND [, PATH]]) + Like `AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found, + set VARIABLE to the entire path of the program found. + + +File: autoconf.info, Node: Libraries, Next: Library Functions, Prev: Alternative Programs, Up: Existing Tests + +Library Files +============= + + The following macros check for the presence of certain C library +archive files. + + - Macro: AC_CHECK_LIB (LIBRARY, FUNCTION [, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND [, OTHER-LIBRARIES]]]) + Try to ensure that C function FUNCTION is available by checking + whether a test C program can be linked with the library LIBRARY to + get the function. LIBRARY is the base name of the library; e.g., + to check for `-lmp', use `mp' as the LIBRARY argument. + + ACTION-IF-FOUND is a list of shell commands to run if the link + with the library succeeds; ACTION-IF-NOT-FOUND is a list of shell + commands to run if the link fails. If ACTION-IF-FOUND and + ACTION-IF-NOT-FOUND are not specified, the default action is to + add `-lLIBRARY' to `LIBS' and define `HAVE_LIBLIBRARY' (in all + capitals). + + If linking with LIBRARY results in unresolved symbols, which would + be resolved by linking with additional libraries, give those + libraries as the OTHER-LIBRARIES argument, separated by spaces: + `-lXt -lX11'. Otherwise this macro will fail to detect that + LIBRARY is present, because linking the test program will always + fail with unresolved symbols. + + - Macro: AC_HAVE_LIBRARY (LIBRARY, [, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND [, OTHER-LIBRARIES]]]) + This macro is equivalent to calling `AC_CHECK_LIB' with a FUNCTION + argument of `main'. In addition, LIBRARY can be written as any of + `foo', `-lfoo', or `libfoo.a'. In all of those cases, the + compiler is passed `-lfoo'. However, LIBRARY can not be a shell + variable; it must be a literal name. This macro is considered + obsolete. + + +File: autoconf.info, Node: Library Functions, Next: Header Files, Prev: Libraries, Up: Existing Tests + +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: + +* Particular Functions:: Special handling to find certain functions. +* Generic Functions:: How to find other functions. + + +File: autoconf.info, Node: Particular Functions, Next: Generic Functions, Up: Library Functions + +Particular Function Checks +-------------------------- + + These macros check for particular C functions--whether they exist, +and in some cases how they respond when given certain arguments. + + - Macro: AC_FUNC_ALLOCA + Check how to get `alloca'. Tries to get a builtin version by + checking for `alloca.h' or the predefined C preprocessor macros + `__GNUC__' and `_AIX'. If this macro finds `alloca.h', it defines + `HAVE_ALLOCA_H'. + + If those attempts fail, it looks for the function in the standard C + library. If any of those methods succeed, it defines + `HAVE_ALLOCA'. Otherwise, it sets the output variable `ALLOCA' to + `alloca.o' and defines `C_ALLOCA' (so programs can periodically + call `alloca(0)' to garbage collect). This variable is separate + from `LIBOBJS' so multiple programs can share the value of + `ALLOCA' without needing to create an actual library, in case only + some of them use the code in `LIBOBJS'. + + This macro does not try to get `alloca' from the System V R3 + `libPW' or the System V R4 `libucb' because those libraries + contain some incompatible functions that cause trouble. Some + versions do not even contain `alloca' or contain a buggy version. + If you still want to use their `alloca', use `ar' to extract + `alloca.o' from them instead of compiling `alloca.c'. + + Source files that use `alloca' should start with a piece of code + like the following, to declare it properly. In some versions of + AIX, the declaration of `alloca' must precede everything else + except for comments and preprocessor directives. The `#pragma' + directive is indented so that pre-ANSI C compilers will ignore it, + rather than choke on it. + + /* AIX requires this to be the first thing in the file. */ + #ifdef __GNUC__ + # define alloca __builtin_alloca + #else + # if HAVE_ALLOCA_H + # include + # else + # ifdef _AIX + #pragma alloca + # else + # ifndef alloca /* predefined by HP cc +Olibcalls */ + char *alloca (); + # endif + # endif + # endif + #endif + + - Macro: AC_FUNC_CLOSEDIR_VOID + If the `closedir' function does not return a meaningful value, + define `CLOSEDIR_VOID'. Otherwise, callers ought to check its + return value for an error indicator. + + - Macro: AC_FUNC_GETLOADAVG + Check how to get the system load averages. If the system has the + `getloadavg' function, this macro defines `HAVE_GETLOADAVG', and + adds to `LIBS' any libraries needed to get that function. + + Otherwise, it adds `getloadavg.o' to the output variable + `LIBOBJS', and possibly defines several other C preprocessor + macros and output variables: + + 1. It defines `SVR4', `DGUX', `UMAX', or `UMAX4_3' if on those + systems. + + 2. If it finds `nlist.h', it defines `NLIST_STRUCT'. + + 3. If `struct nlist' has an `n_un' member, it defines + `NLIST_NAME_UNION'. + + 4. If compiling `getloadavg.c' defines `LDAV_PRIVILEGED', + programs need to be installed specially on this system for + `getloadavg' to work, and this macro defines + `GETLOADAVG_PRIVILEGED'. + + 5. This macro sets the output variable `NEED_SETGID'. The value + is `true' if special installation is required, `false' if not. + If `NEED_SETGID' is `true', this macro sets `KMEM_GROUP' to + the name of the group that should own the installed program. + + - Macro: AC_FUNC_GETMNTENT + Check for `getmntent' in the `sun', `seq', and `gen' libraries, + for Irix 4, PTX, and Unixware, respectively. Then, if `getmntent' + is available, define `HAVE_GETMNTENT'. + + - Macro: AC_FUNC_GETPGRP + If `getpgrp' takes no argument (the POSIX.1 version), define + `GETPGRP_VOID'. Otherwise, it is the BSD version, which takes a + process ID as an argument. This macro does not check whether + `getpgrp' exists at all; if you need to work in that situation, + first call `AC_CHECK_FUNC' for `getpgrp'. + + - Macro: AC_FUNC_MEMCMP + If the `memcmp' function is not available, or does not work on + 8-bit data (like the one on SunOS 4.1.3), add `memcmp.o' to output + variable `LIBOBJS'. + + - Macro: AC_FUNC_MMAP + If the `mmap' function exists and works correctly on memory mapped + files, define `HAVE_MMAP'. + + - Macro: AC_FUNC_SETVBUF_REVERSED + If `setvbuf' takes the buffering type as its second argument and + the buffer pointer as the third, instead of the other way around, + define `SETVBUF_REVERSED'. This is the case on System V before + release 3. + + - Macro: AC_FUNC_STRCOLL + If the `strcoll' function exists and works correctly, define + `HAVE_STRCOLL'. This does a bit more than + `AC_CHECK_FUNCS(strcoll)', because some systems have incorrect + definitions of `strcoll', which should not be used. + + - Macro: AC_FUNC_STRFTIME + Check for `strftime' in the `intl' library, for SCO UNIX. Then, + if `strftime' is available, define `HAVE_STRFTIME'. + + - Macro: AC_FUNC_UTIME_NULL + If `utime(FILE, NULL)' sets FILE's timestamp to the present, + define `HAVE_UTIME_NULL'. + + - Macro: AC_FUNC_VFORK + If `vfork.h' is found, define `HAVE_VFORK_H'. If a working + `vfork' is not found, define `vfork' to be `fork'. This macro + checks for several known errors in implementations of `vfork' and + considers the system to not have a working `vfork' if it detects + any of them. It is not considered to be an implementation error + if a child's invocation of `signal' modifies the parent's signal + handler, since child processes rarely change their signal handlers. + + - Macro: AC_FUNC_VPRINTF + If `vprintf' is found, define `HAVE_VPRINTF'. Otherwise, if + `_doprnt' is found, define `HAVE_DOPRNT'. (If `vprintf' is + available, you may assume that `vfprintf' and `vsprintf' are also + available.) + + - Macro: AC_FUNC_WAIT3 + If `wait3' is found and fills in the contents of its third argument + (a `struct rusage *'), which HP-UX does not do, define + `HAVE_WAIT3'. + + +File: autoconf.info, Node: Generic Functions, Prev: Particular Functions, Up: Library Functions + +Generic Function Checks +----------------------- + + These macros are used to find functions not covered by the particular +test macros. If the functions might be in libraries other than the +default C library, first call `AC_CHECK_LIB' for those libraries. If +you need to check the behavior of a function as well as find out +whether it is present, you have to write your own test for it (*note +Writing Tests::.). + + - Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]]) + If C function FUNCTION is available, run shell commands + ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND. If you just want + to define a symbol if the function is available, consider using + `AC_CHECK_FUNCS' instead. This macro checks for functions with C + linkage even when `AC_LANG_CPLUSPLUS' has been called, since C++ is + more standardized than C is. (*note Language Choice::., for more + information about selecting the language for checks.) + + - Macro: AC_CHECK_FUNCS (FUNCTION... [, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]]) + For each given FUNCTION in the whitespace-separated argument list + that is available, define `HAVE_FUNCTION' (in all capitals). If + ACTION-IF-FOUND is given, it is additional shell code to execute + when one of the functions is found. You can give it a value of + `break' to break out of the loop on the first match. If + ACTION-IF-NOT-FOUND is given, it is executed when one of the + functions is not found. + + - Macro: AC_REPLACE_FUNCS (FUNCTION-NAME...) + For each given FUNCTION-NAME in the whitespace-separated argument + list that is not in the C library, add `FUNCTION-NAME.o' to the + value of the output variable `LIBOBJS'. + + +File: autoconf.info, Node: Header Files, Next: Structures, Prev: Library Functions, Up: Existing Tests + +Header Files +============ + + The following macros check for the presence of certain C header +files. If there is no macro specifically defined to check for a header +file you need, and you don't need to check for any special properties of +it, then you can use one of the general header file check macros. + +* Menu: + +* Particular Headers:: Special handling to find certain headers. +* Generic Headers:: How to find other headers. + + +File: autoconf.info, Node: Particular Headers, Next: Generic Headers, Up: Header Files + +Particular Header Checks +------------------------ + + These macros check for particular system header files--whether they +exist, and in some cases whether they declare certain symbols. + + - Macro: AC_DECL_SYS_SIGLIST + Define `SYS_SIGLIST_DECLARED' if the variable `sys_siglist' is + declared in a system header file, either `signal.h' or `unistd.h'. + + - Macro: AC_DIR_HEADER + Like calling `AC_HEADER_DIRENT' and `AC_FUNC_CLOSEDIR_VOID', but + defines a different set of C preprocessor macros to indicate which + header file is found. This macro and the names it defines are + considered obsolete. The names it defines are: + + `dirent.h' + `DIRENT' + + `sys/ndir.h' + `SYSNDIR' + + `sys/dir.h' + `SYSDIR' + + `ndir.h' + `NDIR' + + In addition, if the `closedir' function does not return a + meaningful value, define `VOID_CLOSEDIR'. + + - Macro: AC_HEADER_DIRENT + Check for the following header files, and for the first one that is + found and defines `DIR', define the listed C preprocessor macro: + + `dirent.h' + `HAVE_DIRENT_H' + + `sys/ndir.h' + `HAVE_SYS_NDIR_H' + + `sys/dir.h' + `HAVE_SYS_DIR_H' + + `ndir.h' + `HAVE_NDIR_H' + + The directory library declarations in the source code should look + something like the following: + + #if HAVE_DIRENT_H + # include + # define NAMLEN(dirent) strlen((dirent)->d_name) + #else + # define dirent direct + # define NAMLEN(dirent) (dirent)->d_namlen + # if HAVE_SYS_NDIR_H + # include + # endif + # if HAVE_SYS_DIR_H + # include + # endif + # if HAVE_NDIR_H + # include + # endif + #endif + + Using the above declarations, the program would declare variables + to be type `struct dirent', not `struct direct', and would access + the length of a directory entry name by passing a pointer to a + `struct dirent' to the `NAMLEN' macro. + + This macro also checks for the SCO Xenix `dir' and `x' libraries. + + - Macro: AC_HEADER_MAJOR + If `sys/types.h' does not define `major', `minor', and `makedev', + but `sys/mkdev.h' does, define `MAJOR_IN_MKDEV'; otherwise, if + `sys/sysmacros.h' does, define `MAJOR_IN_SYSMACROS'. + + - Macro: AC_HEADER_STDC + Define `STDC_HEADERS' if the system has ANSI C header files. + Specifically, this macro checks for `stdlib.h', `stdarg.h', + `string.h', and `float.h'; if the system has those, it probably + has the rest of the ANSI C header files. This macro also checks + whether `string.h' declares `memchr' (and thus presumably the + other `mem' functions), whether `stdlib.h' declare `free' (and + thus presumably `malloc' and other related functions), and whether + the `ctype.h' macros work on characters with the high bit set, as + ANSI C requires. + + Use `STDC_HEADERS' instead of `__STDC__' to determine whether the + system has ANSI-compliant header files (and probably C library + functions) because many systems that have GCC do not have ANSI C + header files. + + On systems without ANSI C headers, there is so much variation that + it is probably easier to declare the functions you use than to + figure out exactly what the system header files declare. Some + systems contain a mix of functions ANSI and BSD; some are mostly + ANSI but lack `memmove'; some define the BSD functions as macros in + `string.h' or `strings.h'; some have only the BSD functions but + `string.h'; some declare the memory functions in `memory.h', some + in `string.h'; etc. It is probably sufficient to check for one + string function and one memory function; if the library has the + ANSI versions of those then it probably has most of the others. + If you put the following in `configure.in': + + AC_HEADER_STDC + AC_CHECK_FUNCS(strchr memcpy) + + then, in your code, you can put declarations like this: + + #if STDC_HEADERS + # include + #else + # ifndef HAVE_STRCHR + # define strchr index + # define strrchr rindex + # endif + char *strchr (), *strrchr (); + # ifndef HAVE_MEMCPY + # define memcpy(d, s, n) bcopy ((s), (d), (n)) + # define memmove(d, s, n) bcopy ((s), (d), (n)) + # endif + #endif + + If you use a function like `memchr', `memset', `strtok', or + `strspn', which have no BSD equivalent, then macros won't suffice; + you must provide an implementation of each function. An easy way + to incorporate your implementations only when needed (since the + ones in system C libraries may be hand optimized) is to, taking + `memchr' for example, put it in `memchr.c' and use + `AC_REPLACE_FUNCS(memchr)'. + + - Macro: AC_HEADER_SYS_WAIT + If `sys/wait.h' exists and is compatible with POSIX.1, define + `HAVE_SYS_WAIT_H'. Incompatibility can occur if `sys/wait.h' does + not exist, or if it uses the old BSD `union wait' instead of `int' + to store a status value. If `sys/wait.h' is not POSIX.1 + compatible, then instead of including it, define the POSIX.1 + macros with their usual interpretations. Here is an example: + + #include + #if HAVE_SYS_WAIT_H + # include + #endif + #ifndef WEXITSTATUS + # define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8) + #endif + #ifndef WIFEXITED + # define WIFEXITED(stat_val) (((stat_val) & 255) == 0) + #endif + + - Macro: AC_MEMORY_H + Define `NEED_MEMORY_H' if `memcpy', `memcmp', etc. are not + declared in `string.h' and `memory.h' exists. This macro is + obsolete; instead, use `AC_CHECK_HEADERS(memory.h)'. See the + example for `AC_HEADER_STDC'. + + - Macro: AC_UNISTD_H + Define `HAVE_UNISTD_H' if the system has `unistd.h'. This macro + is obsolete; instead, use `AC_CHECK_HEADERS(unistd.h)'. + + The way to check if the system supports POSIX.1 is: + + #if HAVE_UNISTD_H + # include + # include + #endif + + #ifdef _POSIX_VERSION + /* Code for POSIX.1 systems. */ + #endif + + `_POSIX_VERSION' is defined when `unistd.h' is included on POSIX.1 + systems. If there is no `unistd.h', it is definitely not a + POSIX.1 system. However, some non-POSIX.1 systems do have + `unistd.h'. + + - Macro: AC_USG + Define `USG' if the system does not have `strings.h', `rindex', + `bzero', etc. This implies that it has `string.h', `strrchr', + `memset', etc. + + The symbol `USG' is obsolete. Instead of this macro, see the + example for `AC_HEADER_STDC'. + + +File: autoconf.info, Node: Generic Headers, Prev: Particular Headers, Up: Header Files + +Generic Header Checks +--------------------- + + These macros are used to find system header files not covered by the +particular test macros. If you need to check the contents of a header +as well as find out whether it is present, you have to write your own +test for it (*note Writing Tests::.). + + - Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]]) + If the system header file HEADER-FILE exists, execute shell + commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. + If you just want to define a symbol if the header file is + available, consider using `AC_CHECK_HEADERS' instead. + + - Macro: AC_CHECK_HEADERS (HEADER-FILE... [, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]]) + For each given system header file HEADER-FILE in the + whitespace-separated argument list that exists, define + `HAVE_HEADER-FILE' (in all capitals). If ACTION-IF-FOUND is + given, it is additional shell code to execute when one of the + header files is found. You can give it a value of `break' to + break out of the loop on the first match. If ACTION-IF-NOT-FOUND + is given, it is executed when one of the header files is not found. + + +File: autoconf.info, Node: Structures, Next: Typedefs, Prev: Header Files, Up: Existing Tests + +Structures +========== + + The following macros check for certain structures or structure +members. To check structures not listed here, use `AC_EGREP_CPP' +(*note Examining Declarations::.) or `AC_TRY_COMPILE' (*note Examining +Syntax::.). + + - Macro: AC_HEADER_STAT + If the macros `S_ISDIR', `S_ISREG' et al. defined in `sys/stat.h' + do not work properly (returning false positives), define + `STAT_MACROS_BROKEN'. This is the case on Tektronix UTekV, Amdahl + UTS and Motorola System V/88. + + - Macro: AC_HEADER_TIME + If a program may include both `time.h' and `sys/time.h', define + `TIME_WITH_SYS_TIME'. On some older systems, `sys/time.h' + includes `time.h', but `time.h' is not protected against multiple + inclusion, so programs should not explicitly include both files. + This macro is useful in programs that use, for example, `struct + timeval' or `struct timezone' as well as `struct tm'. It is best + used in conjunction with `HAVE_SYS_TIME_H', which can be checked + for using `AC_CHECK_HEADERS(sys/time.h)'. + + #if TIME_WITH_SYS_TIME + # include + # include + #else + # if HAVE_SYS_TIME_H + # include + # else + # include + # endif + #endif + + - Macro: AC_STRUCT_ST_BLKSIZE + If `struct stat' contains an `st_blksize' member, define + `HAVE_ST_BLKSIZE'. + + - Macro: AC_STRUCT_ST_BLOCKS + If `struct stat' contains an `st_blocks' member, define + `HAVE_ST_BLOCKS'. Otherwise, add `fileblocks.o' to the output + variable `LIBOBJS'. + + - Macro: AC_STRUCT_ST_RDEV + If `struct stat' contains an `st_rdev' member, define + `HAVE_ST_RDEV'. + + - Macro: AC_STRUCT_TM + If `time.h' does not define `struct tm', define `TM_IN_SYS_TIME', + which means that including `sys/time.h' had better define `struct + tm'. + + - Macro: AC_STRUCT_TIMEZONE + Figure out how to get the current timezone. If `struct tm' has a + `tm_zone' member, define `HAVE_TM_ZONE'. Otherwise, if the + external array `tzname' is found, define `HAVE_TZNAME'. + + +File: autoconf.info, Node: Typedefs, Next: Compiler Characteristics, Prev: Structures, Up: Existing Tests + +Typedefs +======== + + The following macros check for C typedefs. If there is no macro +specifically defined to check for a typedef you need, and you don't need +to check for any special properties of it, then you can use a general +typedef check macro. + +* Menu: + +* Particular Typedefs:: Special handling to find certain types. +* Generic Typedefs:: How to find other types. + + +File: autoconf.info, Node: Particular Typedefs, Next: Generic Typedefs, Up: Typedefs + +Particular Typedef Checks +------------------------- + + These macros check for particular C typedefs in `sys/types.h' and +`stdlib.h' (if it exists). + + - Macro: AC_TYPE_GETGROUPS + Define `GETGROUPS_T' to be whichever of `gid_t' or `int' is the + base type of the array argument to `getgroups'. + + - Macro: AC_TYPE_MODE_T + If `mode_t' is not defined, define `mode_t' to be `int'. + + - Macro: AC_TYPE_OFF_T + If `off_t' is not defined, define `off_t' to be `long'. + + - Macro: AC_TYPE_PID_T + If `pid_t' is not defined, define `pid_t' to be `int'. + + - Macro: AC_TYPE_SIGNAL + If `signal.h' declares `signal' as returning a pointer to a + function returning `void', define `RETSIGTYPE' to be `void'; + otherwise, define it to be `int'. + + Define signal handlers as returning type `RETSIGTYPE': + + RETSIGTYPE + hup_handler () + { + ... + } + + - Macro: AC_TYPE_SIZE_T + If `size_t' is not defined, define `size_t' to be `unsigned'. + + - Macro: AC_TYPE_UID_T + If `uid_t' is not defined, define `uid_t' to be `int' and `gid_t' + to be `int'. + + +File: autoconf.info, Node: Generic Typedefs, Prev: Particular Typedefs, Up: Typedefs + +Generic Typedef Checks +---------------------- + + This macro is used to check for typedefs not covered by the +particular test macros. + + - Macro: AC_CHECK_TYPE (TYPE, DEFAULT) + If the type TYPE is not defined in `sys/types.h' or `stdlib.h' (if + it exists), define it to be the C (or C++) builtin type DEFAULT; + e.g., `short' or `unsigned'. + + +File: autoconf.info, Node: Compiler Characteristics, Next: System Services, Prev: Typedefs, Up: Existing Tests + +Compiler Characteristics +======================== + + The following macros check for C compiler or machine architecture +features. To check for characteristics not listed here, use +`AC_TRY_COMPILE' (*note Examining Syntax::.) or `AC_TRY_RUN' (*note Run +Time::.) + + - Macro: AC_C_BIGENDIAN + If words are stored with the most significant byte first (like + Motorola and SPARC, but not Intel and VAX, CPUs), define + `WORDS_BIGENDIAN'. + + - Macro: AC_C_CONST + If the C compiler does not fully support the keyword `const', + define `const' to be empty. Some C compilers that do not define + `__STDC__' do support `const'; some compilers that define + `__STDC__' do not completely support `const'. Programs can simply + use `const' as if every C compiler supported it; for those that + don't, the `Makefile' or configuration header file will define it + as empty. + + - Macro: AC_C_INLINE + If the C compiler supports the keyword `inline', do nothing. + Otherwise define `inline' to `__inline__' or `__inline' if it + accepts one of those, otherwise define `inline' to be empty. + + - Macro: AC_C_CHAR_UNSIGNED + If the C type `char' is unsigned, define `__CHAR_UNSIGNED__', + unless the C compiler predefines it. + + - Macro: AC_C_LONG_DOUBLE + If the C compiler supports the `long double' type, define + `HAVE_LONG_DOUBLE'. Some C compilers that do not define + `__STDC__' do support the `long double' type; some compilers that + define `__STDC__' do not support `long double'. + + - Macro: AC_CHECK_SIZEOF (TYPE [, CROSS-SIZE]) + Define `SIZEOF_UCTYPE' to be the size in bytes of the C (or C++) + builtin type TYPE, e.g. `int' or `char *'. If `type' is unknown + to the compiler, it gets a size of 0. UCTYPE is TYPE, with + lowercase converted to uppercase, spaces changed to underscores, + and asterisks changed to `P'. If cross-compiling, the value + CROSS-SIZE is used if given, otherwise `configure' exits with an + error message. + + For example, the call + AC_CHECK_SIZEOF(int *) + + defines `SIZEOF_INT_P' to be 8 on DEC Alpha AXP systems. + + - Macro: AC_INT_16_BITS + If the C type `int' is 16 bits wide, define `INT_16_BITS'. This + macro is obsolete; it is more general to use + `AC_CHECK_SIZEOF(int)' instead. + + - Macro: AC_LONG_64_BITS + If the C type `long int' is 64 bits wide, define `LONG_64_BITS'. + This macro is obsolete; it is more general to use + `AC_CHECK_SIZEOF(long)' instead. + + +File: autoconf.info, Node: System Services, Next: UNIX Variants, Prev: Compiler Characteristics, Up: Existing Tests + +System Services +=============== + + The following macros check for operating system services or +capabilities. + + - Macro: AC_SYS_INTERPRETER + Check whether the system supports starting scripts with a line of + the form `#! /bin/csh' to select the interpreter to use for the + script. After running this macro, shell code in `configure.in' + can check the variable `ac_cv_sys_interpreter'; it will be set to + `yes' if the system supports `#!', `no' if not. + + - Macro: AC_PATH_X + Try to locate the X Window System include files and libraries. If + the user gave the command line options `--x-includes=DIR' and + `--x-libraries=DIR', use those directories. If either or both + were not given, get the missing values by running `xmkmf' on a + trivial `Imakefile' and examining the `Makefile' that it produces. + If that fails (such as if `xmkmf' is not present), look for them + in several directories where they often reside. If either method + is successful, set the shell variables `x_includes' and + `x_libraries' to their locations, unless they are in directories + the compiler searches by default. + + If both methods fail, or the user gave the command line option + `--without-x', set the shell variable `no_x' to `yes'; otherwise + set it to the empty string. + + - Macro: AC_PATH_XTRA + An enhanced version of `AC_PATH_X'. It adds the C compiler flags + that X needs to output variable `X_CFLAGS', and the X linker flags + to `X_LIBS'. If X is not available, adds `-DX_DISPLAY_MISSING' to + `X_CFLAGS'. + + This macro also checks for special libraries that some systems + need in order to compile X programs. It adds any that the system + needs to output variable `X_EXTRA_LIBS'. And it checks for + special X11R6 libraries that need to be linked with before + `-lX11', and adds any found to the output variable `X_PRE_LIBS'. + + + - Macro: AC_SYS_LONG_FILE_NAMES + If the system supports file names longer than 14 characters, define + `HAVE_LONG_FILE_NAMES'. + + - Macro: AC_SYS_RESTARTABLE_SYSCALLS + If the system automatically restarts a system call that is + interrupted by a signal, define `HAVE_RESTARTABLE_SYSCALLS'. + + +File: autoconf.info, Node: UNIX Variants, Prev: System Services, Up: Existing Tests + +UNIX Variants +============= + + The following macros check for certain operating systems that need +special treatment for some programs, due to exceptional oddities in +their header files or libraries. These macros are warts; they will be +replaced by a more systematic approach, based on the functions they make +available or the environments they provide. + + - Macro: AC_AIX + If on AIX, define `_ALL_SOURCE'. Allows the use of some BSD + functions. Should be called before any macros that run the C + compiler. + + - Macro: AC_DYNIX_SEQ + If on Dynix/PTX (Sequent UNIX), add `-lseq' to output variable + `LIBS'. This macro is obsolete; instead, use `AC_FUNC_GETMNTENT'. + + - Macro: AC_IRIX_SUN + If on IRIX (Silicon Graphics UNIX), add `-lsun' to output variable + `LIBS'. This macro is obsolete. If you were using it to get + `getmntent', use `AC_FUNC_GETMNTENT' instead. If you used it for + the NIS versions of the password and group functions, use + `AC_CHECK_LIB(sun, getpwnam)'. + + - Macro: AC_ISC_POSIX + If on a POSIXized ISC UNIX, define `_POSIX_SOURCE' and add + `-posix' (for the GNU C compiler) or `-Xp' (for other C compilers) + to output variable `CC'. This allows the use of POSIX facilities. + Must be called after `AC_PROG_CC' and before any other macros + that run the C compiler. + + - Macro: AC_MINIX + If on Minix, define `_MINIX' and `_POSIX_SOURCE' and define + `_POSIX_1_SOURCE' to be 2. This allows the use of POSIX + facilities. Should be called before any macros that run the C + compiler. + + - Macro: AC_SCO_INTL + If on SCO UNIX, add `-lintl' to output variable `LIBS'. This + macro is obsolete; instead, use `AC_FUNC_STRFTIME'. + + - Macro: AC_XENIX_DIR + If on Xenix, add `-lx' to output variable `LIBS'. Also, if + `dirent.h' is being used, add `-ldir' to `LIBS'. This macro is + obsolete; use `AC_HEADER_DIRENT' instead. + + +File: autoconf.info, Node: Writing Tests, Next: Results, Prev: Existing Tests, Up: Top + +Writing Tests +************* + + If the existing feature tests don't do something you need, you have +to write new ones. These macros are the building blocks. They provide +ways for other macros to check whether various kinds of features are +available and report the results. + + This chapter contains some suggestions and some of the reasons why +the existing tests are written the way they are. You can also learn a +lot about how to write Autoconf tests by looking at the existing ones. +If something goes wrong in one or more of the Autoconf tests, this +information can help you understand the assumptions behind them, which +might help you figure out how to best solve the problem. + + These macros check the output of the C compiler system. They do not +cache the results of their tests for future use (*note Caching +Results::.), because they don't know enough about the information they +are checking for to generate a cache variable name. They also do not +print any messages, for the same reason. The checks for particular +kinds of C features call these macros and do cache their results and +print messages about what they're checking for. + + When you write a feature test that could be applicable to more than +one software package, the best thing to do is encapsulate it in a new +macro. *Note Writing 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. +* Portable Shell:: Shell script portability pitfalls. +* Testing Values and Files:: Checking strings and files. +* Multiple Cases:: Tests for several possible values. +* Language Choice:: Selecting which language to use for testing. + + +File: autoconf.info, Node: Examining Declarations, Next: Examining Syntax, Up: Writing Tests + +Examining Declarations +====================== + + The macro `AC_TRY_CPP' is used to check whether particular header +files exist. You can check for one at a time, or more than one if you +need several header files to all exist for some purpose. + + - Macro: AC_TRY_CPP (INCLUDES, [ACTION-IF-TRUE [, ACTION-IF-FALSE]]) + INCLUDES is C or C++ `#include' statements and declarations, on + which shell variable, backquote, and backslash substitutions are + performed. (Actually, it can be any C program, but other + statements are probably not useful.) If the preprocessor produces + no error messages while processing it, run shell commands + ACTION-IF-TRUE. Otherwise run shell commands ACTION-IF-FALSE. + + This macro uses `CPPFLAGS', but not `CFLAGS', because `-g', `-O', + etc. are not valid options to many C preprocessors. + + Here is how to find out whether a header file contains a particular +declaration, such as a typedef, a structure, a structure member, or a +function. Use `AC_EGREP_HEADER' instead of running `grep' directly on +the header file; on some systems the symbol might be defined in another +header file that the file you are checking `#include's. + + - Macro: AC_EGREP_HEADER (PATTERN, HEADER-FILE, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]) + If the output of running the preprocessor on the system header file + HEADER-FILE matches the `egrep' regular expression PATTERN, + execute shell commands ACTION-IF-FOUND, otherwise execute + ACTION-IF-NOT-FOUND. + + To check for C preprocessor symbols, either defined by header files +or predefined by the C preprocessor, use `AC_EGREP_CPP'. Here is an +example of the latter: + + AC_EGREP_CPP(yes, + [#ifdef _AIX + yes + #endif + ], is_aix=yes, is_aix=no) + + - Macro: AC_EGREP_CPP (PATTERN, PROGRAM, [ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]]) + PROGRAM is the text of a C or C++ program, on which shell + variable, backquote, and backslash substitutions are performed. + If the output of running the preprocessor on PROGRAM matches the + `egrep' regular expression PATTERN, execute shell commands + ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. + + This macro calls `AC_PROG_CPP' or `AC_PROG_CXXCPP' (depending on + which language is current, *note Language Choice::.), if it hasn't + been called already. + + +File: autoconf.info, Node: Examining Syntax, Next: Examining Libraries, Prev: Examining Declarations, Up: Writing Tests + +Examining Syntax +================ + + To check for a syntax feature of the C or C++ compiler, such as +whether it recognizes a certain keyword, use `AC_TRY_COMPILE' to try to +compile a small program that uses that feature. You can also use it to +check for structures and structure members that are not present on all +systems. + + - Macro: AC_TRY_COMPILE (INCLUDES, FUNCTION-BODY, [ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]]) + Create a test C program to see whether a function whose body + consists of FUNCTION-BODY can be compiled; INCLUDES is any + `#include' statements needed by the code in FUNCTION-BODY. If the + file compiles successfully, run shell commands ACTION-IF-FOUND, + otherwise run ACTION-IF-NOT-FOUND. This macro uses `CFLAGS' or + `CXXFLAGS', and `CPPFLAGS', when compiling. It does not try to + link; use `AC_TRY_LINK' if you need to do that (*note Examining + Libraries::.). + + +File: autoconf.info, Node: Examining Libraries, Next: Run Time, Prev: Examining Syntax, Up: Writing Tests + +Examining Libraries +=================== + + To check for a library, a function, or a global variable, Autoconf +`configure' scripts try to compile and link a small program that uses +it. This is unlike Metaconfig, which by default uses `nm' or `ar' on +the C library to try to figure out which functions are available. +Trying to link with the function is usually a more reliable approach +because it avoids dealing with the variations in the options and output +formats of `nm' and `ar' and in the location of the standard libraries. +It also allows configuring for cross-compilation or checking a +function's runtime behavior if needed. On the other hand, it can be +slower than scanning the libraries once. + + A few systems have linkers that do not return a failure exit status +when there are unresolved functions in the link. This bug makes the +configuration scripts produced by Autoconf unusable on those systems. +However, some of them can be given options that make the exit status +correct. This is a problem that Autoconf does not currently handle +automatically. If users encounter this problem, they might be able to +solve it by setting `LDFLAGS' in the environment to pass whatever +options the linker needs (for example, `-Wl,-dn' on MIPS RISC/OS). + + `AC_TRY_LINK' is used to compile test programs to test for functions +and global variables. It is also used (by `AC_CHECK_LIB') to check for +libraries, by adding the library being checked for to `LIBS' +temporarily and trying to link a small program. + + - Macro: AC_TRY_LINK (INCLUDES, FUNCTION-BODY, [ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]]) + Create a test C program to see whether a function whose body + consists of FUNCTION-BODY can be compiled and linked; INCLUDES is + any `#include' statements needed by the code in FUNCTION-BODY. If + the file compiles and links successfully, run shell commands + ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. This macro + uses `CFLAGS' or `CXXFLAGS', `CPPFLAGS', `LDFLAGS', and `LIBS' + when compiling. + + - Macro: AC_COMPILE_CHECK (ECHO-TEXT, INCLUDES, FUNCTION-BODY, + ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]) + This is an obsolete version of `AC_TRY_LINK', with the addition + that it prints `checking for ECHO-TEXT' to the standard output + first, if ECHO-TEXT is non-empty. Use `AC_MSG_CHECKING' and + `AC_MSG_RESULT' instead to print messages (*note Printing + Messages::.). + + +File: autoconf.info, Node: Run Time, Next: Portable Shell, Prev: Examining Libraries, Up: Writing Tests + +Checking Run Time Behavior +========================== + + Sometimes you need to find out how a system performs at run time, +such as whether a given function has a certain capability or bug. If +you can, make such checks when your program runs instead of when it is +configured. You can check for things like the machine's endianness when +your program initializes itself. + + If you really need to test for a run-time behavior while configuring, +you can write a test program to determine the result, and compile and +run it using `AC_TRY_RUN'. Avoid running test programs if possible, +because using them prevents people from configuring your package for +cross-compiling. + +* Menu: + +* Test Programs:: Running test programs. +* Guidelines:: General rules for writing test programs. +* Test Functions:: Avoiding pitfalls in test programs. + + +File: autoconf.info, Node: Test Programs, Next: Guidelines, Up: Run Time + +Running Test Programs +--------------------- + + Use the following macro if you need to test run-time behavior of the +system while configuring. + + - Macro: AC_TRY_RUN (PROGRAM, [ACTION-IF-TRUE [, ACTION-IF-FALSE [, + ACTION-IF-CROSS-COMPILING]]]) + PROGRAM is the text of a C program, on which shell variable and + backquote substitutions are performed. If it compiles and links + successfully and returns an exit status of 0 when executed, run + shell commands ACTION-IF-TRUE. Otherwise run shell commands + ACTION-IF-FALSE; the exit status of the program is available in + the shell variable `$?'. This macro uses `CFLAGS' or `CXXFLAGS', + `CPPFLAGS', `LDFLAGS', and `LIBS' when compiling. + + If the C compiler being used does not produce executables that run + on the system where `configure' is being run, then the test + program is not run. If the optional shell commands + ACTION-IF-CROSS-COMPILING are given, they are run instead and this + macro calls `AC_C_CROSS' if it has not already been called. + Otherwise, `configure' prints an error message and exits. + + Try to provide a pessimistic default value to use when +cross-compiling makes run-time tests impossible. You do this by +passing the optional last argument to `AC_TRY_RUN'. `autoconf' prints +a warning message when creating `configure' each time it encounters a +call to `AC_TRY_RUN' with no ACTION-IF-CROSS-COMPILING argument given. +You may ignore the warning, though users will not be able to configure +your package for cross-compiling. A few of the macros distributed with +Autoconf produce this warning message. + + To configure for cross-compiling you can also choose a value for +those parameters based on the canonical system name (*note Manual +Configuration::.). Alternatively, set up a test results cache file with +the correct values for the target system (*note Caching Results::.). + + To provide a default for calls of `AC_TRY_RUN' that are embedded in +other macros, including a few of the ones that come with Autoconf, you +can call `AC_C_CROSS' before running them. Then, if the shell variable +`cross_compiling' is set to `yes', use an alternate method to get the +results instead of calling the macros. + + - Macro: AC_C_CROSS + If the C compiler being used does not produce executables that can + run on the system where `configure' is being run, set the shell + variable `cross_compiling' to `yes', otherwise `no'. + + +File: autoconf.info, Node: Guidelines, Next: Test Functions, Prev: Test Programs, Up: Run Time + +Guidelines for Test Programs +---------------------------- + + Test programs should not write anything to the standard output. They +should return 0 if the test succeeds, nonzero otherwise, so that success +can be distinguished easily from a core dump or other failure; +segmentation violations and other failures produce a nonzero exit +status. Test programs should `exit', not `return', from `main', +because on some systems (old Suns, at least) the argument to `return' +in `main' is ignored. + + Test programs can use `#if' or `#ifdef' to check the values of +preprocessor macros defined by tests that have already run. For +example, if you call `AC_HEADER_STDC', then later on in `configure.in' +you can have a test program that includes an ANSI C header file +conditionally: + + #if STDC_HEADERS + # include + #endif + + If a test program needs to use or create a data file, give it a name +that starts with `conftest', such as `conftestdata'. The `configure' +script cleans up by running `rm -rf conftest*' after running test +programs and if the script is interrupted. + + +File: autoconf.info, Node: Test Functions, Prev: Guidelines, Up: Run Time + +Test Functions +-------------- + + Function declarations in test programs should have a prototype +conditionalized for C++. In practice, though, test programs rarely need +functions that take arguments. + + #ifdef __cplusplus + foo(int i) + #else + foo(i) int i; + #endif + + Functions that test programs declare should also be conditionalized +for C++, which requires `extern "C"' prototypes. Make sure to not +include any header files containing clashing prototypes. + + #ifdef __cplusplus + extern "C" void *malloc(size_t); + #else + char *malloc(); + #endif + + If a test program calls a function with invalid parameters (just to +see whether it exists), organize the program to ensure that it never +invokes that function. You can do this by calling it in another +function that is never invoked. You can't do it by putting it after a +call to `exit', because GCC version 2 knows that `exit' never returns +and optimizes out any code that follows it in the same block. + + If you include any header files, make sure to call the functions +relevant to them with the correct number of arguments, even if they are +just 0, to avoid compilation errors due to prototypes. GCC version 2 +has internal prototypes for several functions that it automatically +inlines; for example, `memcpy'. To avoid errors when checking for +them, either pass them the correct number of arguments or redeclare them +with a different return type (such as `char'). + + +File: autoconf.info, Node: Portable Shell, Next: Testing Values and Files, Prev: Run Time, Up: Writing Tests + +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 Bash and the Korn shell +have evolved over the years, but to prevent trouble, do not take +advantage of features that were added after UNIX version 7, circa 1977. +You should not use shell functions, aliases, negated character classes, +or other features that are not found in all Bourne-compatible shells; +restrict yourself to the lowest common denominator. Even `unset' is +not supported by all shells! Also, include a space after the +exclamation point in interpreter specifications, like this: + #! /usr/bin/perl + If you omit the space before the path, then 4.2BSD based systems +(such as Sequent DYNIX) will ignore the line, because they interpret +`#! /' as a 4-byte magic number. + + The set of external programs you should run in a `configure' script +is fairly small. *Note Utilities in Makefiles: (standards)Utilities in +Makefiles, for the list. This restriction allows users to start out +with a fairly small set of programs and build the rest, avoiding too +many interdependencies between packages. + + Some of these external utilities have a portable subset of features, +as well; for example, don't rely on `ln' having a `-f' option or `cat' +having any options. `sed' scripts should not contain comments or use +branch labels longer than 8 characters. Don't use `grep -s' to +suppress output, because `grep -s' on System V does not suppress +output, only error messages. Instead, redirect the standard output and +standard error (in case the file doesn't exist) of `grep' to +`/dev/null'. Check the exit status of `grep' to determine whether it +found a match. + + +File: autoconf.info, Node: Testing Values and Files, Next: Multiple Cases, Prev: Portable Shell, Up: Writing Tests + +Testing Values and Files +======================== + + `configure' scripts need to test properties of many files and +strings. Here are some portability problems to watch out for when doing +those tests. + + The `test' program is the way to perform many file and string tests. +It is often invoked by the alternate name `[', but using that name in +Autoconf code is asking for trouble since it is an `m4' quote character. + + If you need to make multiple checks using `test', combine them with +the shell operators `&&' and `||' instead of using the `test' operators +`-a' and `-o'. On System V, the precedence of `-a' and `-o' is wrong +relative to the unary operators; consequently, POSIX does not specify +them, so using them is nonportable. If you combine `&&' and `||' in +the same statement, keep in mind that they have equal precedence. + + To enable `configure' scripts to support cross-compilation, they +shouldn't do anything that tests features of the host system instead of +the target system. But occasionally you may find it necessary to check +whether some arbitrary file exists. To do so, use `test -f' or `test +-r'. Do not use `test -x', because 4.3BSD does not have it. + + Another nonportable shell programming construction is + VAR=${VAR:-VALUE} + +The intent is to set VAR to VALUE only if it is not already set, but if +VAR has any value, even the empty string, to leave it alone. Old BSD +shells, including the Ultrix `sh', don't accept the colon, and complain +and die. A portable equivalent is + : ${VAR=VALUE} + + +File: autoconf.info, Node: Multiple Cases, Next: Language Choice, Prev: Testing Values and Files, Up: Writing Tests + +Multiple Cases +============== + + Some operations are accomplished in several possible ways, depending +on the UNIX variant. Checking for them essentially requires a "case +statement". Autoconf does not directly provide one; however, it is +easy to simulate by using a shell variable to keep track of whether a +way to perform the operation has been found yet. + + Here is an example that uses the shell variable `fstype' to keep +track of whether the remaining cases need to be checked. + + AC_MSG_CHECKING(how to get filesystem type) + fstype=no + # The order of these tests is important. + AC_TRY_CPP([#include + #include ], AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4) + if test $fstype = no; then + AC_TRY_CPP([#include + #include ], AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3) + fi + if test $fstype = no; then + AC_TRY_CPP([#include + #include ], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX) + fi + # (more cases omitted here) + AC_MSG_RESULT($fstype) + + +File: autoconf.info, Node: Language Choice, Prev: Multiple Cases, Up: Writing Tests + +Language Choice +=============== + + Packages that use both C and C++ need to test features of both +compilers. Autoconf-generated `configure' scripts check for C features +by default. The following macros determine which language's compiler +is used in tests that follow in `configure.in'. + + - Macro: AC_LANG_C + Do compilation tests using `CC' and `CPP' and use extension `.c' + for test programs. + + - Macro: AC_LANG_CPLUSPLUS + Do compilation tests using `CXX' and `CXXCPP' and use extension + `.C' for test programs. + + - Macro: AC_LANG_SAVE + Remember the current language (as set by `AC_LANG_C' or + `AC_LANG_CPLUSPLUS') on a stack. Does not change which language is + current. Use this macro and `AC_LANG_RESTORE' in macros that need + to temporarily switch to a particular language. + + - Macro: AC_LANG_RESTORE + Select the language that is saved on the top of the stack, as set + by `AC_LANG_SAVE', and remove it from the stack. This macro is + equivalent to either `AC_LANG_C' or `AC_LANG_CPLUSPLUS', whichever + had been run most recently when `AC_LANG_SAVE' was last called. + + Do not call this macro more times than `AC_LANG_SAVE'. + + - Macro: AC_REQUIRE_CPP + Ensure that whichever preprocessor would currently be used for + tests has been found. Calls `AC_REQUIRE' (*note Prerequisite + Macros::.) with an argument of either `AC_PROG_CPP' or + `AC_PROG_CXXCPP', depending on which language is current. + + +File: autoconf.info, Node: Results, Next: Writing Macros, Prev: Writing Tests, Up: Top + +Results of Tests +**************** + + Once `configure' has determined whether a feature exists, what can +it do to record that information? There are four sorts of things it can +do: define a C preprocessor symbol, set a variable in the output files, +save the result in a cache file for future `configure' runs, and print +a message letting the user know the result of the test. + +* Menu: + +* Defining Symbols:: Defining C preprocessor symbols. +* Setting Output Variables:: Replacing variables in output files. +* Caching Results:: Speeding up subsequent `configure' runs. +* Printing Messages:: Notifying users of progress or problems. + + +File: autoconf.info, Node: Defining Symbols, Next: Setting Output Variables, Up: Results + +Defining C Preprocessor Symbols +=============================== + + A common action to take in response to a feature test is to define a +C preprocessor symbol indicating the results of the test. That is done +by calling `AC_DEFINE' or `AC_DEFINE_UNQUOTED'. + + By default, `AC_OUTPUT' places the symbols defined by these macros +into the output variable `DEFS', which contains an option +`-DSYMBOL=VALUE' for each symbol defined. Unlike in Autoconf version +1, there is no variable `DEFS' defined while `configure' is running. +To check whether Autoconf macros have already defined a certain C +preprocessor symbol, test the value of the appropriate cache variable, +as in this example: + + AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF)) + if test "$ac_cv_func_vprintf" != yes; then + AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT)) + fi + + If `AC_CONFIG_HEADER' has been called, then instead of creating +`DEFS', `AC_OUTPUT' creates a header file by substituting the correct +values into `#define' statements in a template file. *Note +Configuration Headers::, for more information about this kind of output. + + - Macro: AC_DEFINE (VARIABLE [, VALUE]) + Define C preprocessor variable VARIABLE. If VALUE is given, set + VARIABLE to that value (verbatim), otherwise set it to 1. VALUE + should not contain literal newlines, and if you are not using + `AC_CONFIG_HEADER' it should not contain any `#' characters, as + `make' tends to eat them. To use a shell variable (which you need + to do in order to define a value containing the `m4' quote + characters `[' or `]'), use `AC_DEFINE_UNQUOTED' instead. The + following example defines the C preprocessor variable `EQUATION' + to be the string constant `"$a > $b"': + + AC_DEFINE(EQUATION, "$a > $b") + + - Macro: AC_DEFINE_UNQUOTED (VARIABLE [, VALUE]) + Like `AC_DEFINE', but three shell expansions are + performed--once--on VARIABLE and VALUE: variable expansion (`$'), + command substitution (``'), and backslash escaping (`\'). Single + and double quote characters in the value have no special meaning. + Use this macro instead of `AC_DEFINE' when VARIABLE or VALUE is a + shell variable. Examples: + + AC_DEFINE_UNQUOTED(config_machfile, "${machfile}") + AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups) + AC_DEFINE_UNQUOTED(${ac_tr_hdr}) + + Due to the syntactical bizarreness of the Bourne shell, do not use +semicolons to separate `AC_DEFINE' or `AC_DEFINE_UNQUOTED' calls from +other macro calls or shell code; that can cause syntax errors in the +resulting `configure' script. Use either spaces or newlines. That is, +do this: + + AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf") + +or this: + + AC_CHECK_HEADER(elf.h, + AC_DEFINE(SVR4) + LIBS="$LIBS -lelf") + +instead of this: + + AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf") + + +File: autoconf.info, Node: Setting Output Variables, Next: Caching Results, Prev: Defining Symbols, Up: Results + +Setting Output Variables +======================== + + One way to record the results of tests is to set "output variables", +which are shell variables whose values are substituted into files that +`configure' outputs. The two macros below create new output variables. +*Note Preset Output Variables::, for a list of output variables that +are always available. + + - Macro: AC_SUBST (VARIABLE) + Create an output variable from a shell variable. Make `AC_OUTPUT' + substitute the variable VARIABLE into output files (typically one + or more `Makefile's). This means that `AC_OUTPUT' will replace + instances of `@VARIABLE@' in input files with the value that the + shell variable VARIABLE has when `AC_OUTPUT' is called. The value + of VARIABLE should not contain literal newlines. + + - Macro: AC_SUBST_FILE (VARIABLE) + Another way to create an output variable from a shell variable. + Make `AC_OUTPUT' insert (without substitutions) the contents of + the file named by shell variable VARIABLE into output files. This + means that `AC_OUTPUT' will replace instances of `@VARIABLE@' in + output files (such as `Makefile.in') with the contents of the file + that the shell variable VARIABLE names when `AC_OUTPUT' is called. + Set the variable to `/dev/null' for cases that do not have a file + to insert. + + This macro is useful for inserting `Makefile' fragments containing + special dependencies or other `make' directives for particular host + or target types into `Makefile's. For example, `configure.in' + could contain: + + AC_SUBST_FILE(host_frag)dnl + host_frag=$srcdir/conf/sun4.mh + + and then a `Makefile.in' could contain: + + @host_frag@ + + +File: autoconf.info, Node: Caching Results, Next: Printing Messages, Prev: Setting Output Variables, Up: Results + +Caching Results +=============== + + To avoid checking for the same features repeatedly in various +`configure' scripts (or repeated runs of one script), `configure' saves +the results of many of its checks in a "cache file". If, when a +`configure' script runs, it finds a cache file, it reads from it the +results from previous runs and avoids rerunning those checks. As a +result, `configure' can run much faster than if it had to perform all +of the checks every time. + + - Macro: AC_CACHE_VAL (CACHE-ID, COMMANDS-TO-SET-IT) + Ensure that the results of the check identified by CACHE-ID are + available. If the results of the check were in the cache file + that was read, and `configure' was not given the `--quiet' or + `--silent' option, print a message saying that the result was + cached; otherwise, run the shell commands COMMANDS-TO-SET-IT. + Those commands should have no side effects except for setting the + variable CACHE-ID. In particular, they should not call + `AC_DEFINE'; the code that follows the call to `AC_CACHE_VAL' + should do that, based on the cached value. Also, they should not + print any messages, for example with `AC_MSG_CHECKING'; do that + before calling `AC_CACHE_VAL', so the messages are printed + regardless of whether the results of the check are retrieved from + the cache or determined by running the shell commands. If the + shell commands are run to determine the value, the value will be + saved in the cache file just before `configure' creates its output + files. *Note Cache Variable Names::, for how to choose the name + of the CACHE-ID variable. + + - Macro: AC_CACHE_CHECK (MESSAGE, CACHE-ID, COMMANDS) + A wrapper for `AC_CACHE_VAL' that takes care of printing the + messages. This macro provides a convenient shorthand for the most + common way to use these macros. It calls `AC_MSG_CHECKING' for + MESSAGE, then `AC_CACHE_VAL' with the CACHE-ID and COMMANDS + arguments, and `AC_MSG_RESULT' with CACHE-ID. + +* Menu: + +* Cache Variable Names:: Shell variables used in caches. +* Cache Files:: Files `configure' uses for caching. + + +File: autoconf.info, Node: Cache Variable Names, Next: Cache Files, Up: Caching Results + +Cache Variable Names +-------------------- + + The names of cache variables should have the following format: + + PACKAGE-PREFIX_cv_VALUE-TYPE_SPECIFIC-VALUE[_ADDITIONAL-OPTIONS] + +for example, `ac_cv_header_stat_broken' or +`ac_cv_prog_gcc_traditional'. The parts of the variable name are: + +PACKAGE-PREFIX + An abbreviation for your package or organization; the same prefix + you begin local Autoconf macros with, except lowercase by + convention. For cache values used by the distributed Autoconf + macros, this value is `ac'. + +`_cv_' + Indicates that this shell variable is a cache value. + +VALUE-TYPE + A convention for classifying cache values, to produce a rational + naming system. The values used in Autoconf are listed in *Note + Macro Names::. + +SPECIFIC-VALUE + Which member of the class of cache values this test applies to. + For example, which function (`alloca'), program (`gcc'), or output + variable (`INSTALL'). + +ADDITIONAL-OPTIONS + Any particular behavior of the specific member that this test + applies to. For example, `broken' or `set'. This part of the + name may be omitted if it does not apply. + + Like their names, the values that may be assigned to cache variables +have a few restrictions. The values may not contain single quotes or +curly braces. Usually, their values will be boolean (`yes' or `no') or +the names of files or functions; so this is not an important +restriction. + + +File: autoconf.info, Node: Cache Files, Prev: Cache Variable Names, Up: Caching Results + +Cache Files +----------- + + A cache file is a shell script that caches the results of configure +tests run on one system so they can be shared between configure scripts +and configure runs. It is not useful on other systems. If its contents +are invalid for some reason, the user may delete or edit it. + + By default, configure uses `./config.cache' as the cache file, +creating it if it does not exist already. `configure' accepts the +`--cache-file=FILE' option to use a different cache file; that is what +`configure' does when it calls `configure' scripts in subdirectories, +so they share the cache. *Note Subdirectories::, for information on +configuring subdirectories with the `AC_CONFIG_SUBDIRS' macro. + + Giving `--cache-file=/dev/null' disables caching, for debugging +`configure'. `config.status' only pays attention to the cache file if +it is given the `--recheck' option, which makes it rerun `configure'. +If you are anticipating a long debugging period, you can also disable +cache loading and saving for a `configure' script by redefining the +cache macros at the start of `configure.in': + + define([AC_CACHE_LOAD], )dnl + define([AC_CACHE_SAVE], )dnl + AC_INIT(whatever) + ... rest of configure.in ... + + It is wrong to try to distribute cache files for particular system +types. There is too much room for error in doing that, and too much +administrative overhead in maintaining them. For any features that +can't be guessed automatically, use the standard method of the canonical +system type and linking files (*note Manual Configuration::.). + + The cache file on a particular system will gradually accumulate +whenever someone runs a `configure' script; it will be initially +nonexistent. Running `configure' merges the new cache results with the +existing cache file. The site initialization script can specify a +site-wide cache file to use instead of the default, to make it work +transparently, as long as the same C compiler is used every time (*note +Site Defaults::.). + + +File: autoconf.info, Node: Printing Messages, Prev: Caching Results, Up: Results + +Printing Messages +================= + + `configure' scripts need to give users running them several kinds of +information. The following macros print messages in ways appropriate +for each kind. The arguments to all of them get enclosed in shell +double quotes, so the shell performs variable and backquote substitution +on them. + + These macros are all wrappers around the `echo' shell command. +`configure' scripts should rarely need to run `echo' directly to print +messages for the user. Using these macros makes it easy to change how +and when each kind of message is printed; such changes need only be +made to the macro definitions, and all of the callers change +automatically. + + - Macro: AC_MSG_CHECKING (FEATURE-DESCRIPTION) + Notify the user that `configure' is checking for a particular + feature. This macro prints a message that starts with `checking ' + and ends with `...' and no newline. It must be followed by a call + to `AC_MSG_RESULT' to print the result of the check and the + newline. The FEATURE-DESCRIPTION should be something like + `whether the Fortran compiler accepts C++ comments' or `for c89'. + + This macro prints nothing if `configure' is run with the `--quiet' + or `--silent' option. + + - Macro: AC_MSG_RESULT (RESULT-DESCRIPTION) + Notify the user of the results of a check. RESULT-DESCRIPTION is + almost always the value of the cache variable for the check, + typically `yes', `no', or a file name. This macro should follow a + call to `AC_MSG_CHECKING', and the RESULT-DESCRIPTION should be + the completion of the message printed by the call to + `AC_MSG_CHECKING'. + + This macro prints nothing if `configure' is run with the `--quiet' + or `--silent' option. + + - Macro: AC_MSG_ERROR (ERROR-DESCRIPTION) + Notify the user of an error that prevents `configure' from + completing. This macro prints an error message on the standard + error output and exits `configure' with a nonzero status. + ERROR-DESCRIPTION should be something like `invalid value $HOME + for \$HOME'. + + - Macro: AC_MSG_WARN (PROBLEM-DESCRIPTION) + Notify the `configure' user of a possible problem. This macro + prints the message on the standard error output; `configure' + continues running afterward, so macros that call `AC_MSG_WARN' + should provide a default (back-up) behavior for the situations + they warn about. PROBLEM-DESCRIPTION should be something like `ln + -s seems to make hard links'. + + The following two macros are an obsolete alternative to +`AC_MSG_CHECKING' and `AC_MSG_RESULT'. + + - Macro: AC_CHECKING (FEATURE-DESCRIPTION) + This macro is similar to `AC_MSG_CHECKING', except that it prints a + newline after the FEATURE-DESCRIPTION. It is useful mainly to + print a general description of the overall purpose of a group of + feature checks, e.g., + + AC_CHECKING(if stack overflow is detectable) + + - Macro: AC_VERBOSE (RESULT-DESCRIPTION) + This macro is similar to `AC_MSG_RESULT', except that it is meant + to follow a call to `AC_CHECKING' instead of `AC_MSG_CHECKING'; it + starts the message it prints with a tab. It is considered + obsolete. + + +File: autoconf.info, Node: Writing Macros, Next: Manual Configuration, Prev: Results, Up: Top + +Writing 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. +* Quoting:: Protecting macros from unwanted expansion. +* Dependencies Between Macros:: What to do when macros depend on other macros. + + +File: autoconf.info, Node: Macro Definitions, Next: Macro Names, Up: Writing Macros + +Macro Definitions +================= + + Autoconf macros are defined using the `AC_DEFUN' macro, which is +similar to the `m4' builtin `define' macro. In addition to defining a +macro, `AC_DEFUN' adds to it some code which is used to constrain the +order in which macros are called (*note Prerequisite Macros::.). + + An Autoconf macro definition looks like this: + + AC_DEFUN(MACRO-NAME, [MACRO-BODY]) + +The square brackets here do not indicate optional text: they should +literally be present in the macro definition to avoid macro expansion +problems (*note Quoting::.). You can refer to any arguments passed to +the macro as `$1', `$2', etc. + + To introduce comments in `m4', use the `m4' builtin `dnl'; it causes +`m4' to discard the text through the next newline. It is not needed +between macro definitions in `acsite.m4' and `aclocal.m4', because all +output is discarded until `AC_INIT' is called. + + *Note How to define new macros: (m4.info)Definitions, for more +complete information on writing `m4' macros. + + +File: autoconf.info, Node: Macro Names, Next: Quoting, Prev: Macro Definitions, Up: Writing Macros + +Macro Names +=========== + + All of the Autoconf macros have all-uppercase names starting with +`AC_' to prevent them from accidentally conflicting with other text. +All shell variables that they use for internal purposes have +mostly-lowercase names starting with `ac_'. To ensure that your macros +don't conflict with present or future Autoconf macros, you should +prefix your own macro names and any shell variables they use with some +other sequence. Possibilities include your initials, or an abbreviation +for the name of your organization or software package. + + Most of the Autoconf macros' names follow a structured naming +convention that indicates the kind of feature check by the name. The +macro names consist of several words, separated by underscores, going +from most general to most specific. The names of their cache +variables use the same convention (*note Cache Variable Names::., for +more information on them). + + The first word of the name after `AC_' usually tells the category of +feature being tested. Here are the categories used in Autoconf for +specific test macros, the kind of macro that you are more likely to +write. They are also used for cache variables, in all-lowercase. Use +them where applicable; where they're not, invent your own categories. + +`C' + C language builtin features. + +`DECL' + Declarations of C variables in header files. + +`FUNC' + Functions in libraries. + +`GROUP' + UNIX group owners of files. + +`HEADER' + Header files. + +`LIB' + C libraries. + +`PATH' + The full path names to files, including programs. + +`PROG' + The base names of programs. + +`STRUCT' + Definitions of C structures in header files. + +`SYS' + Operating system features. + +`TYPE' + C builtin or declared types. + +`VAR' + C variables in libraries. + + After the category comes the name of the particular feature being +tested. Any further words in the macro name indicate particular aspects +of the feature. For example, `AC_FUNC_UTIME_NULL' checks the behavior +of the `utime' function when called with a `NULL' pointer. + + A macro that is an internal subroutine of another macro should have a +name that starts with the name of that other macro, followed by one or +more words saying what the internal macro does. For example, +`AC_PATH_X' has internal macros `AC_PATH_X_XMKMF' and +`AC_PATH_X_DIRECT'. + + +File: autoconf.info, Node: Quoting, Next: Dependencies Between Macros, Prev: Macro Names, Up: Writing Macros + +Quoting +======= + + Macros that are called by other macros are evaluated by `m4' several +times; each evaluation might require another layer of quotes to prevent +unwanted expansions of macros or `m4' builtins, such as `define' and +`$1'. Quotes are also required around macro arguments that contain +commas, since commas separate the arguments from each other. It's a +good idea to quote any macro arguments that contain newlines or calls +to other macros, as well. + + Autoconf changes the `m4' quote characters from the default ``' and +`'' to `[' and `]', because many of the macros use ``' and `'', +mismatched. However, in a few places the macros need to use brackets +(usually in C program text or regular expressions). In those places, +they use the `m4' builtin command `changequote' to temporarily change +the quote characters to `<<' and `>>'. (Sometimes, if they don't need +to quote anything, they disable quoting entirely instead by setting the +quote characters to empty strings.) Here is an example: + + AC_TRY_LINK( + changequote(<<, >>)dnl + <<#include + #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) + + When you create a `configure' script using newly written macros, +examine it carefully to check whether you need to add more quotes in +your macros. If one or more words have disappeared in the `m4' output, +you need more quotes. When in doubt, quote. + + However, it's also possible to put on too many layers of quotes. If +this happens, the resulting `configure' script will contain unexpanded +macros. The `autoconf' program checks for this problem by doing `grep +AC_ configure'. + + +File: autoconf.info, Node: Dependencies Between Macros, Prev: Quoting, Up: Writing Macros + +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. +* Obsolete Macros:: Warning about old ways of doing things. + + +File: autoconf.info, Node: Prerequisite Macros, Next: Suggested Ordering, Up: Dependencies Between Macros + +Prerequisite Macros +------------------- + + A macro that you write might need to use values that have previously +been computed by other macros. For example, `AC_DECL_YYTEXT' examines +the output of `flex' or `lex', so it depends on `AC_PROG_LEX' having +been called first to set the shell variable `LEX'. + + Rather than forcing the user of the macros to keep track of the +dependencies between them, you can use the `AC_REQUIRE' macro to do it +automatically. `AC_REQUIRE' can ensure that a macro is only called if +it is needed, and only called once. + + - Macro: AC_REQUIRE (MACRO-NAME) + If the `m4' macro MACRO-NAME has not already been called, call it + (without any arguments). Make sure to quote MACRO-NAME with + square brackets. MACRO-NAME must have been defined using + `AC_DEFUN' or else contain a call to `AC_PROVIDE' to indicate that + it has been called. + + An alternative to using `AC_DEFUN' is to use `define' and call +`AC_PROVIDE'. Because this technique does not prevent nested messages, +it is considered obsolete. + + - Macro: AC_PROVIDE (THIS-MACRO-NAME) + Record the fact that THIS-MACRO-NAME has been called. + THIS-MACRO-NAME should be the name of the macro that is calling + `AC_PROVIDE'. An easy way to get it is from the `m4' builtin + variable `$0', like this: + + AC_PROVIDE([$0]) + + +File: autoconf.info, Node: Suggested Ordering, Next: Obsolete Macros, Prev: Prerequisite Macros, Up: Dependencies Between Macros + +Suggested Ordering +------------------ + + Some macros should be run before another macro if both are called, +but neither *requires* that the other be called. For example, a macro +that changes the behavior of the C compiler should be called before any +macros that run the C compiler. Many of these dependencies are noted in +the documentation. + + Autoconf provides the `AC_BEFORE' macro to warn users when macros +with this kind of dependency appear out of order in a `configure.in' +file. The warning occurs when creating `configure' from +`configure.in', not when running `configure'. For example, +`AC_PROG_CPP' checks whether the C compiler can run the C preprocessor +when given the `-E' option. It should therefore be called after any +macros that change which C compiler is being used, such as +`AC_PROG_CC'. So `AC_PROG_CC' contains: + + AC_BEFORE([$0], [AC_PROG_CPP])dnl + +This warns the user if a call to `AC_PROG_CPP' has already occurred +when `AC_PROG_CC' is called. + + - Macro: AC_BEFORE (THIS-MACRO-NAME, CALLED-MACRO-NAME) + Make `m4' print a warning message on the standard error output if + CALLED-MACRO-NAME has already been called. THIS-MACRO-NAME should + be the name of the macro that is calling `AC_BEFORE'. The macro + CALLED-MACRO-NAME must have been defined using `AC_DEFUN' or else + contain a call to `AC_PROVIDE' to indicate that it has been called. + + +File: autoconf.info, Node: Obsolete Macros, Prev: Suggested Ordering, Up: Dependencies Between Macros + +Obsolete Macros +--------------- + + Configuration and portability technology has evolved over the years. +Often better ways of solving a particular problem are developed, or +ad-hoc approaches are systematized. This process has occurred in many +parts of Autoconf. One result is that some of the macros are now +considered "obsolete"; they still work, but are no longer considered +the best thing to do. Autoconf provides the `AC_OBSOLETE' macro to +warn users producing `configure' scripts when they use obsolete macros, +to encourage them to modernize. A sample call is: + + AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl + + - Macro: AC_OBSOLETE (THIS-MACRO-NAME [, SUGGESTION]) + Make `m4' print a message on the standard error output warning that + THIS-MACRO-NAME is obsolete, and giving the file and line number + where it was called. THIS-MACRO-NAME should be the name of the + macro that is calling `AC_OBSOLETE'. If SUGGESTION is given, it + is printed at the end of the warning message; for example, it can + be a suggestion for what to use instead of THIS-MACRO-NAME. + + +File: autoconf.info, Node: Manual Configuration, Next: Site Configuration, Prev: Writing Macros, Up: Top + +Manual Configuration +******************** + + A few kinds of features can't be guessed automatically by running +test programs. For example, the details of the object file format, or +special options that need to be passed to the compiler or linker. You +can check for such features using ad-hoc means, such as having +`configure' check the output of the `uname' program, or looking for +libraries that are unique to particular systems. However, Autoconf +provides a uniform method for handling unguessable features. + +* Menu: + +* Specifying Names:: Specifying the system type. +* Canonicalizing:: Getting the canonical system type. +* System Type Variables:: Variables containing the system type. +* Using System Type:: What to do with the system type. + + +File: autoconf.info, Node: Specifying Names, Next: Canonicalizing, Up: Manual Configuration + +Specifying the System Type +========================== + + Like other GNU `configure' scripts, Autoconf-generated `configure' +scripts can make decisions based on a canonical name for the system +type, which has the form: + + CPU-COMPANY-SYSTEM + + `configure' can usually guess the canonical name for the type of +system it's running on. To do so it runs a script called +`config.guess', which derives the name using the `uname' command or +symbols predefined by the C preprocessor. + + Alternately, the user can specify the system type with command line +arguments to `configure'. Doing so is necessary when cross-compiling. +In the most complex case of cross-compiling, three system types are +involved. The options to specify them are: + +`--build=BUILD-TYPE' + the type of system on which the package is being configured and + compiled (rarely needed); + +`--host=HOST-TYPE' + the type of system on which the package will run; + +`--target=TARGET-TYPE' + the type of system for which any compiler tools in the package will + produce code. + +If the user gives `configure' a non-option argument, it is used as the +default for the host, target, and build system types if the user does +not specify them explicitly with options. The target and build types +default to the host type if it is given and they are not. If you are +cross-compiling, you still have to specify the names of the cross-tools +you use, in particular the C compiler, on the `configure' command line, +e.g., + + CC=m68k-coff-gcc configure --target=m68k-coff + + `configure' recognizes short aliases for many system types; for +example, `decstation' can be given on the command line instead of +`mips-dec-ultrix4.2'. `configure' runs a script called `config.sub' to +canonicalize system type aliases. + + +File: autoconf.info, Node: Canonicalizing, Next: System Type Variables, Prev: Specifying Names, Up: Manual Configuration + +Getting the Canonical System Type +================================= + + The following macros make the system type available to `configure' +scripts. They run the shell script `config.guess' to determine any +values for the host, target, and build types that they need and the user +did not specify on the command line. They run `config.sub' to +canonicalize any aliases the user gave. If you use these macros, you +must distribute those two shell scripts along with your source code. +*Note Output::, for information about the `AC_CONFIG_AUX_DIR' macro +which you can use to control which directory `configure' looks for +those scripts in. If you do not use either of these macros, +`configure' ignores any `--host', `--target', and `--build' options +given to it. + + - Macro: AC_CANONICAL_SYSTEM + Determine the system type and set output variables to the names of + the canonical system types. *Note System Type Variables::, for + details about the variables this macro sets. + + - Macro: AC_CANONICAL_HOST + Perform only the subset of `AC_CANONICAL_SYSTEM' relevant to the + host type. This is all that is needed for programs that are not + part of a compiler toolchain. + + +File: autoconf.info, Node: System Type Variables, Next: Using System Type, Prev: Canonicalizing, Up: Manual Configuration + +System Type Variables +===================== + + After calling `AC_CANONICAL_SYSTEM', the following output variables +contain the system type information. After `AC_CANONICAL_HOST', only +the `host' variables below are set. + +``build', `host', `target'' + the canonical system names; + +``build_alias', `host_alias', `target_alias'' + the names the user specified, or the canonical names if + `config.guess' was used; + +``build_cpu', `build_vendor', `build_os'' +``host_cpu', `host_vendor', `host_os'' +``target_cpu', `target_vendor', `target_os'' + the individual parts of the canonical names (for convenience). + + +File: autoconf.info, Node: Using System Type, Prev: System Type Variables, Up: Manual Configuration + +Using the System Type +===================== + + How do you use a canonical system type? Usually, you use it in one +or more `case' statements in `configure.in' to select system-specific C +files. Then link those files, which have names based on the system +name, to generic names, such as `host.h' or `target.c'. The `case' +statement patterns can use shell wildcards to group several cases +together, like in this fragment: + + case "$target" in + i386-*-mach* | i386-*-gnu*) obj_format=aout emulation=mach bfd_gas=yes ;; + i960-*-bout) obj_format=bout ;; + esac + + - Macro: AC_LINK_FILES (SOURCE..., DEST...) + Make `AC_OUTPUT' link each of the existing files SOURCE to the + corresponding link name DEST. Makes a symbolic link if possible, + otherwise a hard link. The DEST and SOURCE names should be + relative to the top level source or build directory. + + For example, this call: + + AC_LINK_FILES(config/${machine}.h config/${obj_format}.h, host.h object.h) + + creates in the current directory `host.h', which is a link to + `SRCDIR/config/${machine}.h', and `object.h', which is a link to + `SRCDIR/config/${obj_format}.h'. + + You can also use the host system type to find cross-compilation +tools. *Note Generic Programs::, for information about the +`AC_CHECK_TOOL' macro which does that. + + +File: autoconf.info, Node: Site Configuration, Next: Invoking configure, Prev: Manual Configuration, Up: Top + +Site Configuration +****************** + + `configure' scripts support several kinds of local configuration +decisions. There are ways for users to specify where external software +packages are, include or exclude optional features, install programs +under modified names, and set default values for `configure' options. + +* Menu: + +* External Software:: Working with other optional software. +* Package Options:: Selecting optional features. +* Site Details:: Configuring site details. +* Transforming Names:: Changing program names when installing. +* Site Defaults:: Giving `configure' local defaults. + + +File: autoconf.info, Node: External Software, Next: Package Options, Up: Site Configuration + +Working With External Software +============================== + + Some packages require, or can optionally use, other software packages +which are already installed. The user can give `configure' command +line options to specify which such external software to use. The +options have one of these forms: + + --with-PACKAGE[=ARG] + --without-PACKAGE + + For example, `--with-gnu-ld' means work with the GNU linker instead +of some other linker. `--with-x' means work with The X Window System. + + The user can give an argument by following the package name with `=' +and the argument. Giving an argument of `no' is for packages that are +used by default; it says to *not* use the package. An argument that is +neither `yes' nor `no' could include a name or number of a version of +the other package, to specify more precisely which other package this +program is supposed to work with. If no argument is given, it defaults +to `yes'. `--without-PACKAGE' is equivalent to `--with-PACKAGE=no'. + + For each external software package that may be used, `configure.in' +should call `AC_ARG_WITH' to detect whether the `configure' user asked +to use it. Whether each package is used or not by default, and which +arguments are valid, is up to you. + + - Macro: AC_ARG_WITH (PACKAGE, HELP-STRING [, ACTION-IF-GIVEN [, + ACTION-IF-NOT-GIVEN]]) + If the user gave `configure' the option `--with-PACKAGE' or + `--without-PACKAGE', run shell commands ACTION-IF-GIVEN. If + neither option was given, run shell commands ACTION-IF-NOT-GIVEN. + The name PACKAGE indicates another software package that this + program should work with. It should consist only of alphanumeric + characters and dashes. + + The option's argument is available to the shell commands + ACTION-IF-GIVEN in the shell variable `withval', which is actually + just the value of the shell variable `with_PACKAGE', with any `-' + characters changed into `_'. You may use that variable instead, + if you wish. + + The argument HELP-STRING is a description of the option which + looks like this: + --with-readline support fancy command line editing + + HELP-STRING may be more than one line long, if more detail is + needed. Just make sure the columns line up in `configure --help'. + Avoid tabs in the help string. You'll need to enclose it in `[' + and `]' in order to produce the leading spaces. + + - Macro: AC_WITH (PACKAGE, ACTION-IF-GIVEN [, ACTION-IF-NOT-GIVEN]) + This is an obsolete version of `AC_ARG_WITH' that does not support + providing a help string. + + +File: autoconf.info, Node: Package Options, Next: Site Details, Prev: External Software, Up: Site Configuration + +Choosing Package Options +======================== + + If a software package has optional compile-time features, the user +can give `configure' command line options to specify whether to compile +them. The options have one of these forms: + + --enable-FEATURE[=ARG] + --disable-FEATURE + + These options allow users to choose which optional features to build +and install. `--enable-FEATURE' options should never make a feature +behave differently or cause one feature to replace another. They +should only cause parts of the program to be built rather than left out. + + The user can give an argument by following the feature name with `=' +and the argument. Giving an argument of `no' requests that the feature +*not* be made available. A feature with an argument looks like +`--enable-debug=stabs'. If no argument is given, it defaults to `yes'. +`--disable-FEATURE' is equivalent to `--enable-FEATURE=no'. + + For each optional feature, `configure.in' should call +`AC_ARG_ENABLE' to detect whether the `configure' user asked to include +it. Whether each feature is included or not by default, and which +arguments are valid, is up to you. + + - Macro: AC_ARG_ENABLE (FEATURE, HELP-STRING [, ACTION-IF-GIVEN [, + ACTION-IF-NOT-GIVEN]]) + If the user gave `configure' the option `--enable-FEATURE' or + `--disable-FEATURE', run shell commands ACTION-IF-GIVEN. If + neither option was given, run shell commands ACTION-IF-NOT-GIVEN. + The name FEATURE indicates an optional user-level facility. It + should consist only of alphanumeric characters and dashes. + + The option's argument is available to the shell commands + ACTION-IF-GIVEN in the shell variable `enableval', which is + actually just the value of the shell variable `enable_PACKAGE', + with any `-' characters changed into `_'. You may use that + variable instead, if you wish. The HELP-STRING argument is like + that of `AC_ARG_WITH' (*note External Software::.). + + - Macro: AC_ENABLE (FEATURE, ACTION-IF-GIVEN [, ACTION-IF-NOT-GIVEN]) + This is an obsolete version of `AC_ARG_ENABLE' that does not + support providing a help string. + + +File: autoconf.info, Node: Site Details, Next: Transforming Names, Prev: Package Options, Up: Site Configuration + +Configuring Site Details +======================== + + Some software packages require complex site-specific information. +Some examples are host names to use for certain services, company +names, and email addresses to contact. Since some configuration +scripts generated by Metaconfig ask for such information interactively, +people sometimes wonder how to get that information in +Autoconf-generated configuration scripts, which aren't interactive. + + Such site configuration information should be put in a file that is +edited *only by users*, not by programs. The location of the file can +either be based on the `prefix' variable, or be a standard location +such as the user's home directory. It could even be specified by an +environment variable. The programs should examine that file at run +time, rather than at compile time. Run time configuration is more +convenient for users and makes the configuration process simpler than +getting the information while configuring. *Note Variables for +Installation Directories: (standards)Directory Variables, for more +information on where to put data files. + + +File: autoconf.info, Node: Transforming Names, Next: Site Defaults, Prev: Site Details, Up: Site Configuration + +Transforming Program Names When Installing +========================================== + + Autoconf supports changing the names of programs when installing +them. In order to use these transformations, `configure.in' must call +the macro `AC_ARG_PROGRAM'. + + - Macro: AC_ARG_PROGRAM + Place in output variable `program_transform_name' a sequence of + `sed' commands for changing the names of installed programs. + + If any of the options described below are given to `configure', + program names are transformed accordingly. Otherwise, if + `AC_CANONICAL_SYSTEM' has been called and a `--target' value is + given that differs from the host type (specified with `--host' or + defaulted by `config.sub'), the target type followed by a dash is + used as a prefix. Otherwise, no program name transformation is + done. + +* Menu: + +* Transformation Options:: `configure' options to transform names. +* Transformation Examples:: Sample uses of transforming names. +* Transformation Rules:: `Makefile' uses of transforming names. + + +File: autoconf.info, Node: Transformation Options, Next: Transformation Examples, Up: Transforming Names + +Transformation Options +---------------------- + + You can specify name transformations by giving `configure' these +command line options: + +`--program-prefix=PREFIX' + prepend PREFIX to the names; + +`--program-suffix=SUFFIX' + append SUFFIX to the names; + +`--program-transform-name=EXPRESSION' + perform `sed' substitution EXPRESSION on the names. + + +File: autoconf.info, Node: Transformation Examples, Next: Transformation Rules, Prev: Transformation Options, Up: Transforming Names + +Transformation Examples +----------------------- + + These transformations are useful with programs that can be part of a +cross-compilation development environment. For example, a +cross-assembler running on a Sun 4 configured with +`--target=i960-vxworks' is normally installed as `i960-vxworks-as', +rather than `as', which could be confused with a native Sun 4 assembler. + + You can force a program name to begin with `g', if you don't want +GNU programs installed on your system to shadow other programs with the +same name. For example, if you configure GNU `diff' with +`--program-prefix=g', then when you run `make install' it is installed +as `/usr/local/bin/gdiff'. + + As a more sophisticated example, you could use + --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' + +to prepend `g' to most of the program names in a source tree, excepting +those like `gdb' that already have one and those like `less' and +`lesskey' that aren't GNU programs. (That is assuming that you have a +source tree containing those programs that is set up to use this +feature.) + + One way to install multiple versions of some programs simultaneously +is to append a version number to the name of one or both. For example, +if you want to keep Autoconf version 1 around for awhile, you can +configure Autoconf version 2 using `--program-suffix=2' to install the +programs as `/usr/local/bin/autoconf2', `/usr/local/bin/autoheader2', +etc. + + +File: autoconf.info, Node: Transformation Rules, Prev: Transformation Examples, Up: Transforming Names + +Transformation Rules +-------------------- + + Here is how to use the variable `program_transform_name' in a +`Makefile.in': + + transform=@program_transform_name@ + install: all + $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog|sed '$(transform)'` + + uninstall: + rm -f $(bindir)/`echo myprog|sed '$(transform)'` + +If you have more than one program to install, you can do it in a loop: + + PROGRAMS=cp ls rm + install: + for p in $(PROGRAMS); do \ + $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p|sed '$(transform)'`; \ + done + + uninstall: + for p in $(PROGRAMS); do \ + rm -f $(bindir)/`echo $$p|sed '$(transform)'`; \ + done + + Whether to do the transformations on documentation files (Texinfo or +`man') is a tricky question; there seems to be no perfect answer, due +to the several reasons for name transforming. Documentation is not +usually particular to a specific architecture, and Texinfo files do not +conflict with system documentation. But they might conflict with +earlier versions of the same files, and `man' pages sometimes do +conflict with system documentation. As a compromise, it is probably +best to do name transformations on `man' pages but not on Texinfo +manuals. + + +File: autoconf.info, Node: Site Defaults, Prev: Transforming Names, Up: Site Configuration + +Setting Site Defaults +===================== + + Autoconf-generated `configure' scripts allow your site to provide +default values for some configuration values. You do this by creating +site- and system-wide initialization files. + + If the environment variable `CONFIG_SITE' is set, `configure' uses +its value as the name of a shell script to read. Otherwise, it reads +the shell script `PREFIX/share/config.site' if it exists, then +`PREFIX/etc/config.site' if it exists. Thus, settings in +machine-specific files override those in machine-independent ones in +case of conflict. + + Site files can be arbitrary shell scripts, but only certain kinds of +code are really appropriate to be in them. Because `configure' reads +any cache file after it has read any site files, a site file can define +a default cache file to be shared between all Autoconf-generated +`configure' scripts run on that system. If you set a default cache +file in a site file, it is a good idea to also set the output variable +`CC' in that site file, because the cache file is only valid for a +particular compiler, but many systems have several available. + + You can examine or override the value set by a command line option to +`configure' in a site file; options set shell variables that have the +same names as the options, with any dashes turned into underscores. +The exceptions are that `--without-' and `--disable-' options are like +giving the corresponding `--with-' or `--enable-' option and the value +`no'. Thus, `--cache-file=localcache' sets the variable `cache_file' +to the value `localcache'; `--enable-warnings=no' or +`--disable-warnings' sets the variable `enable_warnings' to the value +`no'; `--prefix=/usr' sets the variable `prefix' to the value `/usr'; +etc. + + Site files are also good places to set default values for other +output variables, such as `CFLAGS', if you need to give them non-default +values: anything you would normally do, repetitively, on the command +line. If you use non-default values for PREFIX or EXEC_PREFIX +(wherever you locate the site file), you can set them in the site file +if you specify it with the `CONFIG_SITE' environment variable. + + You can set some cache values in the site file itself. Doing this is +useful if you are cross-compiling, so it is impossible to check features +that require running a test program. You could "prime the cache" by +setting those values correctly for that system in +`PREFIX/etc/config.site'. To find out the names of the cache variables +you need to set, look for shell variables with `_cv_' in their names in +the affected `configure' scripts, or in the Autoconf `m4' source code +for those macros. + + The cache file is careful to not override any variables set in the +site files. Similarly, you should not override command-line options in +the site files. Your code should check that variables such as `prefix' +and `cache_file' have their default values (as set near the top of +`configure') before changing them. + + Here is a sample file `/usr/share/local/gnu/share/config.site'. The +command `configure --prefix=/usr/share/local/gnu' would read this file +(if `CONFIG_SITE' is not set to a different file). + + # config.site for configure + # + # Default --prefix and --exec-prefix. + test "$prefix" = NONE && prefix=/usr/share/local/gnu + test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu + # + # Give Autoconf 2.x generated configure scripts a shared default + # cache file for feature test results, architecture-specific. + if test "$cache_file" = ./config.cache; then + cache_file="$prefix/var/config.cache" + # A cache file is only valid for one C compiler. + CC=gcc + fi + + +File: autoconf.info, Node: Invoking configure, Next: Invoking config.status, Prev: Site Configuration, Up: Top + +Running `configure' Scripts +*************************** + + Below are instructions on how to configure a package that uses a +`configure' script, suitable for inclusion as an `INSTALL' file in the +package. A plain-text version of `INSTALL' which you may use comes +with Autoconf. + +* Menu: + +* Basic Installation:: Instructions for typical cases. +* Compilers and Options:: Selecting compilers and optimization. +* Multiple Architectures:: Compiling for multiple architectures at once. +* Installation Names:: Installing in different directories. +* Optional Features:: Selecting optional features. +* System Type:: Specifying the system type. +* Sharing Defaults:: Setting site-wide defaults for `configure'. +* Operation Controls:: Changing how `configure' runs. + + +File: autoconf.info, Node: Basic Installation, Next: Compilers and Options, Up: Invoking configure + +Basic Installation +================== + + These are generic installation instructions. + + The `configure' shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a `Makefile' in each directory of the package. +It may also create one or more `.h' files containing system-dependent +definitions. Finally, it creates a shell script `config.status' that +you can run in the future to recreate the current configuration, a file +`config.cache' that saves the results of its tests to speed up +reconfiguring, and a file `config.log' containing compiler output +(useful mainly for debugging `configure'). + + If you need to do unusual things to compile the package, please try +to figure out how `configure' could check whether to do them, and mail +diffs or instructions to the address given in the `README' so they can +be considered for the next release. If at some point `config.cache' +contains results you don't want to keep, you may remove or edit it. + + The file `configure.in' is used to create `configure' by a program +called `autoconf'. You only need `configure.in' if you want to change +it or regenerate `configure' using a newer version of `autoconf'. + +The simplest way to compile this package is: + + 1. `cd' to the directory containing the package's source code and type + `./configure' to configure the package for your system. If you're + using `csh' on an old version of System V, you might need to type + `sh ./configure' instead to prevent `csh' from trying to execute + `configure' itself. + + Running `configure' takes awhile. While running, it prints some + messages telling which features it is checking for. + + 2. Type `make' to compile the package. + + 3. Optionally, type `make check' to run any self-tests that come with + the package. + + 4. Type `make install' to install the programs and any data files and + documentation. + + 5. You can remove the program binaries and object files from the + source code directory by typing `make clean'. To also remove the + files that `configure' created (so you can compile the package for + a different kind of computer), type `make distclean'. There is + also a `make maintainer-clean' target, but that is intended mainly + for the package's developers. If you use it, you may have to get + all sorts of other programs in order to regenerate files that came + with the distribution. + + +File: autoconf.info, Node: Compilers and Options, Next: Multiple Architectures, Prev: Basic Installation, Up: Invoking configure + +Compilers and Options +===================== + + Some systems require unusual options for compilation or linking that +the `configure' script does not know about. You can give `configure' +initial values for variables by setting them in the environment. Using +a Bourne-compatible shell, you can do that on the command line like +this: + CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure + +Or on systems that have the `env' program, you can do it like this: + env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure + + +File: autoconf.info, Node: Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Invoking configure + +Compiling For Multiple Architectures +==================================== + + You can compile the package for more than one kind of computer at the +same time, by placing the object files for each architecture in their +own directory. To do this, you must use a version of `make' that +supports the `VPATH' variable, such as GNU `make'. `cd' to the +directory where you want the object files and executables to go and run +the `configure' script. `configure' automatically checks for the +source code in the directory that `configure' is in and in `..'. + + If you have to use a `make' that does not supports the `VPATH' +variable, you have to compile the package for one architecture at a time +in the source code directory. After you have installed the package for +one architecture, use `make distclean' before reconfiguring for another +architecture. + + +File: autoconf.info, Node: Installation Names, Next: Optional Features, Prev: Multiple Architectures, Up: Invoking configure + +Installation Names +================== + + By default, `make install' will install the package's files in +`/usr/local/bin', `/usr/local/man', etc. You can specify an +installation prefix other than `/usr/local' by giving `configure' the +option `--prefix=PATH'. + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +give `configure' the option `--exec-prefix=PATH', the package will use +PATH as the prefix for installing programs and libraries. +Documentation and other data files will still use the regular prefix. + + In addition, if you use an unusual directory layout you can give +options like `--bindir=PATH' to specify different values for particular +kinds of files. Run `configure --help' for a list of the directories +you can set and what kinds of files go in them. + + If the package supports it, you can cause programs to be installed +with an extra prefix or suffix on their names by giving `configure' the +option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. + + +File: autoconf.info, Node: Optional Features, Next: System Type, Prev: Installation Names, Up: Invoking configure + +Optional Features +================= + + Some packages pay attention to `--enable-FEATURE' options to +`configure', where FEATURE indicates an optional part of the package. +They may also pay attention to `--with-PACKAGE' options, where PACKAGE +is something like `gnu-as' or `x' (for the X Window System). The +`README' should mention any `--enable-' and `--with-' options that the +package recognizes. + + For packages that use the X Window System, `configure' can usually +find the X include and library files automatically, but if it doesn't, +you can use the `configure' options `--x-includes=DIR' and +`--x-libraries=DIR' to specify their locations. + + +File: autoconf.info, Node: System Type, Next: Sharing Defaults, Prev: Optional Features, Up: Invoking configure + +Specifying the System Type +========================== + + There may be some features `configure' can not figure out +automatically, but needs to determine by the type of host the package +will run on. Usually `configure' can figure that out, but if it prints +a message saying it can not guess the host type, give it the +`--host=TYPE' option. TYPE can either be a short name for the system +type, such as `sun4', or a canonical name with three fields: + CPU-COMPANY-SYSTEM + +See the file `config.sub' for the possible values of each field. If +`config.sub' isn't included in this package, then this package doesn't +need to know the host type. + + If you are building compiler tools for cross-compiling, you can also +use the `--target=TYPE' option to select the type of system they will +produce code for and the `--build=TYPE' option to select the type of +system on which you are compiling the package. + + +File: autoconf.info, Node: Sharing Defaults, Next: Operation Controls, Prev: System Type, Up: Invoking configure + +Sharing Defaults +================ + + If you want to set default values for `configure' scripts to share, +you can create a site shell script called `config.site' that gives +default values for variables like `CC', `cache_file', and `prefix'. +`configure' looks for `PREFIX/share/config.site' if it exists, then +`PREFIX/etc/config.site' if it exists. Or, you can set the +`CONFIG_SITE' environment variable to the location of the site script. +A warning: not all `configure' scripts look for a site script. + + +File: autoconf.info, Node: Operation Controls, Prev: Sharing Defaults, Up: Invoking configure + +Operation Controls +================== + + `configure' recognizes the following options to control how it +operates. + +`--cache-file=FILE' + Use and save the results of the tests in FILE instead of + `./config.cache'. Set FILE to `/dev/null' to disable caching, for + debugging `configure'. + +`--help' + Print a summary of the options to `configure', and exit. + +`--quiet' +`--silent' +`-q' + Do not print messages saying which checks are being made. + +`--srcdir=DIR' + Look for the package's source code in directory DIR. Usually + `configure' can determine that directory automatically. + +`--version' + Print the version of Autoconf used to generate the `configure' + script, and exit. + +`configure' also accepts some other, not widely useful, options. + + +File: autoconf.info, Node: Invoking config.status, Next: Questions, Prev: Invoking configure, Up: Top + +Recreating a Configuration +************************** + + The `configure' script creates a file named `config.status' which +describes which configuration options were specified when the package +was last configured. This file is a shell script which, if run, will +recreate the same configuration. + + You can give `config.status' the `--recheck' option to update +itself. This option is useful if you change `configure', so that the +results of some tests might be different from the previous run. The +`--recheck' option re-runs `configure' with the same arguments you used +before, plus the `--no-create' option, which prevent `configure' from +running `config.status' and creating `Makefile' and other files, and +the `--no-recursion' option, which prevents `configure' from running +other `configure' scripts in subdirectories. (This is so other +`Makefile' rules can run `config.status' when it changes; *note +Automatic Remaking::., for an example). + + `config.status' also accepts the options `--help', which prints a +summary of the options to `config.status', and `--version', which +prints the version of Autoconf used to create the `configure' script +that generated `config.status'. + + `config.status' checks several optional environment variables that +can alter its behavior: + + - Variable: CONFIG_SHELL + The shell with which to run `configure' for the `--recheck' + option. It must be Bourne-compatible. The default is `/bin/sh'. + + - Variable: CONFIG_STATUS + The file name to use for the shell script that records the + configuration. The default is `./config.status'. This variable is + useful when one package uses parts of another and the `configure' + scripts shouldn't be merged because they are maintained separately. + + The following variables provide one way for separately distributed +packages to share the values computed by `configure'. Doing so can be +useful if some of the packages need a superset of the features that one +of them, perhaps a common library, does. These variables allow a +`config.status' file to create files other than the ones that its +`configure.in' specifies, so it can be used for a different package. + + - Variable: CONFIG_FILES + The files in which to perform `@VARIABLE@' substitutions. The + default is the arguments given to `AC_OUTPUT' in `configure.in'. + + - Variable: CONFIG_HEADERS + The files in which to substitute C `#define' statements. The + default is the arguments given to `AC_CONFIG_HEADER'; if that + macro was not called, `config.status' ignores this variable. + + These variables also allow you to write `Makefile' rules that +regenerate only some of the files. For example, in the dependencies +given above (*note Automatic Remaking::.), `config.status' is run twice +when `configure.in' has changed. If that bothers you, you can make +each run only regenerate the files for that rule: + + config.h: stamp-h + stamp-h: config.h.in config.status + CONFIG_FILES= CONFIG_HEADERS=config.h ./config.status + echo > stamp-h + + Makefile: Makefile.in config.status + CONFIG_FILES=Makefile CONFIG_HEADERS= ./config.status + +(If `configure.in' does not call `AC_CONFIG_HEADER', there is no need +to set `CONFIG_HEADERS' in the `make' rules.) + + +File: autoconf.info, Node: Questions, Next: Upgrading, Prev: Invoking config.status, Up: Top + +Questions About Autoconf +************************ + + Several questions about Autoconf come up occasionally. Here some of +them are addressed. + +* Menu: + +* Distributing:: Distributing `configure' scripts. +* Why GNU m4:: Why not use the standard `m4'? +* Bootstrapping:: Autoconf and GNU `m4' require each other? +* Why Not Imake:: Why GNU uses `configure' instead of Imake. + + +File: autoconf.info, Node: Distributing, Next: Why GNU m4, Up: Questions + +Distributing `configure' Scripts +================================ + + What are the restrictions on distributing `configure' + scripts that Autoconf generates? How does that affect my + programs that use them? + + There are no restrictions on how the configuration scripts that +Autoconf produces may be distributed or used. In Autoconf version 1, +they were covered by the GNU General Public License. We still +encourage software authors to distribute their work under terms like +those of the GPL, but doing so is not required to use Autoconf. + + Of the other files that might be used with `configure', +`config.h.in' is under whatever copyright you use for your +`configure.in', since it is derived from that file and from the public +domain file `acconfig.h'. `config.sub' and `config.guess' have an +exception to the GPL when they are used with an Autoconf-generated +`configure' script, which permits you to distribute them under the same +terms as the rest of your package. `install-sh' is from the X +Consortium and is not copyrighted. + + +File: autoconf.info, Node: Why GNU m4, Next: Bootstrapping, Prev: Distributing, Up: Questions + +Why Require GNU `m4'? +===================== + + Why does Autoconf require GNU `m4'? + + Many `m4' implementations have hard-coded limitations on the size +and number of macros, which Autoconf exceeds. They also lack several +builtin macros that it would be difficult to get along without in a +sophisticated application like Autoconf, including: + + builtin + indir + patsubst + __file__ + __line__ + + Since only software maintainers need to use Autoconf, and since GNU +`m4' is simple to configure and install, it seems reasonable to require +GNU `m4' to be installed also. Many maintainers of GNU and other free +software already have most of the GNU utilities installed, since they +prefer them. + + +File: autoconf.info, Node: Bootstrapping, Next: Why Not Imake, Prev: Why GNU m4, Up: Questions + +How Can I Bootstrap? +==================== + + If Autoconf requires GNU `m4' and GNU `m4' has an + Autoconf `configure' script, how do I bootstrap? It seems + like a chicken and egg problem! + + This is a misunderstanding. Although GNU `m4' does come with a +`configure' script produced by Autoconf, Autoconf is not required in +order to run the script and install GNU `m4'. Autoconf is only +required if you want to change the `m4' `configure' script, which few +people have to do (mainly its maintainer). + + +File: autoconf.info, Node: Why Not Imake, Prev: Bootstrapping, Up: Questions + +Why Not Imake? +============== + + Why not use Imake instead of `configure' scripts? + + Several people have written addressing this question, so I include +adaptations of their explanations here. + + The following answer is based on one written by Richard Pixley: + + Autoconf generated scripts frequently work on machines which it has +never been set up to handle before. That is, it does a good job of +inferring a configuration for a new system. Imake cannot do this. + + Imake uses a common database of host specific data. For X11, this +makes sense because the distribution is made as a collection of tools, +by one central authority who has control over the database. + + GNU tools are not released this way. Each GNU tool has a maintainer; +these maintainers are scattered across the world. Using a common +database would be a maintenance nightmare. Autoconf may appear to be +this kind of database, but in fact it is not. Instead of listing host +dependencies, it lists program requirements. + + If you view the GNU suite as a collection of native tools, then the +problems are similar. But the GNU development tools can be configured +as cross tools in almost any host+target permutation. All of these +configurations can be installed concurrently. They can even be +configured to share host independent files across hosts. Imake doesn't +address these issues. + + Imake templates are a form of standardization. The GNU coding +standards address the same issues without necessarily imposing the same +restrictions. + + Here is some further explanation, written by Per Bothner: + + One of the advantages of Imake is that it easy to generate large +Makefiles using `cpp''s `#include' and macro mechanisms. However, +`cpp' is not programmable: it has limited conditional facilities, and +no looping. And `cpp' cannot inspect its environment. + + All of these problems are solved by using `sh' instead of `cpp'. +The shell is fully programmable, has macro substitution, can execute +(or source) other shell scripts, and can inspect its environment. + + Paul Eggert elaborates more: + + With Autoconf, installers need not assume that Imake itself is +already installed and working well. This may not seem like much of an +advantage to people who are accustomed to Imake. But on many hosts +Imake is not installed or the default installation is not working well, +and requiring Imake to install a package hinders the acceptance of that +package on those hosts. For example, the Imake template and +configuration files might not be installed properly on a host, or the +Imake build procedure might wrongly assume that all source files are in +one big directory tree, or the Imake configuration might assume one +compiler whereas the package or the installer needs to use another, or +there might be a version mismatch between the Imake expected by the +package and the Imake supported by the host. These problems are much +rarer with Autoconf, where each package comes with its own independent +configuration processor. + + Also, Imake often suffers from unexpected interactions between +`make' and the installer's C preprocessor. The fundamental problem +here is that the C preprocessor was designed to preprocess C programs, +not `Makefile's. This is much less of a problem with Autoconf, which +uses the general-purpose preprocessor `m4', and where the package's +author (rather than the installer) does the preprocessing in a standard +way. + + Finally, Mark Eichin notes: + + Imake isn't all that extensible, either. In order to add new +features to Imake, you need to provide your own project template, and +duplicate most of the features of the existing one. This means that +for a sophisticated project, using the vendor-provided Imake templates +fails to provide any leverage--since they don't cover anything that +your own project needs (unless it is an X11 program). + + On the other side, though: + + The one advantage that Imake has over `configure': `Imakefile's tend +to be much shorter (likewise, less redundant) than `Makefile.in's. +There is a fix to this, however--at least for the Kerberos V5 tree, +we've modified things to call in common `post.in' and `pre.in' +`Makefile' fragments for the entire tree. This means that a lot of +common things don't have to be duplicated, even though they normally +are in `configure' setups. + + +File: autoconf.info, Node: Upgrading, Next: History, Prev: Questions, Up: Top + +Upgrading From Version 1 +************************ + + Autoconf version 2 is mostly backward compatible with version 1. +However, it introduces better ways to do some things, and doesn't +support some of the ugly things in version 1. So, depending on how +sophisticated your `configure.in' files are, you might have to do some +manual work in order to upgrade to version 2. This chapter points out +some problems to watch for when upgrading. Also, perhaps your +`configure' scripts could benefit from some of the new features in +version 2; the changes are summarized in the file `NEWS' in the +Autoconf distribution. + + First, make sure you have GNU `m4' version 1.1 or higher installed, +preferably 1.3 or higher. Versions before 1.1 have bugs that prevent +them from working with Autoconf version 2. Versions 1.3 and later are +much faster than earlier versions, because as of version 1.3, GNU `m4' +has a more efficient implementation of diversions and can freeze its +internal state in a file that it can read back quickly. + +* Menu: + +* Changed File Names:: Files you might rename. +* Changed Makefiles:: New things to put in `Makefile.in'. +* Changed Macros:: Macro calls you might replace. +* Invoking autoupdate:: Replacing old macro names in `configure.in'. +* Changed Results:: Changes in how to check test results. +* Changed Macro Writing:: Better ways to write your own macros. + + +File: autoconf.info, Node: Changed File Names, Next: Changed Makefiles, Up: Upgrading + +Changed File Names +================== + + If you have an `aclocal.m4' installed with Autoconf (as opposed to +in a particular package's source directory), you must rename it to +`acsite.m4'. *Note Invoking autoconf::. + + If you distribute `install.sh' with your package, rename it to +`install-sh' so `make' builtin rules won't inadvertently create a file +called `install' from it. `AC_PROG_INSTALL' looks for the script under +both names, but it is best to use the new name. + + If you were using `config.h.top' or `config.h.bot', you still can, +but you will have less clutter if you merge them into `acconfig.h'. +*Note Invoking autoheader::. + + +File: autoconf.info, Node: Changed Makefiles, Next: Changed Macros, Prev: Changed File Names, Up: Upgrading + +Changed Makefiles +================= + + Add `@CFLAGS@', `@CPPFLAGS@', and `@LDFLAGS@' in your `Makefile.in' +files, so they can take advantage of the values of those variables in +the environment when `configure' is run. Doing this isn't necessary, +but it's a convenience for users. + + Also add `@configure_input@' in a comment to each non-`Makefile' +input file for `AC_OUTPUT', so that the output files will contain a +comment saying they were produced by `configure'. Automatically +selecting the right comment syntax for all the kinds of files that +people call `AC_OUTPUT' on became too much work. + + Add `config.log' and `config.cache' to the list of files you remove +in `distclean' targets. + + If you have the following in `Makefile.in': + + prefix = /usr/local + exec_prefix = ${prefix} + +you must change it to: + + prefix = @prefix@ + exec_prefix = @exec_prefix@ + +The old behavior of replacing those variables without `@' characters +around them has been removed. + + +File: autoconf.info, Node: Changed Macros, Next: Invoking autoupdate, Prev: Changed Makefiles, Up: Upgrading + +Changed Macros +============== + + Many of the macros were renamed in Autoconf version 2. You can still +use the old names, but the new ones are clearer, and it's easier to find +the documentation for them. *Note Old Macro Names::, for a table +showing the new names for the old macros. Use the `autoupdate' program +to convert your `configure.in' to using the new macro names. *Note +Invoking autoupdate::. + + Some macros have been superseded by similar ones that do the job +better, but are not call-compatible. If you get warnings about calling +obsolete macros while running `autoconf', you may safely ignore them, +but your `configure' script will generally work better if you follow +the advice it prints about what to replace the obsolete macros with. In +particular, the mechanism for reporting the results of tests has +changed. If you were using `echo' or `AC_VERBOSE' (perhaps via +`AC_COMPILE_CHECK'), your `configure' script's output will look better +if you switch to `AC_MSG_CHECKING' and `AC_MSG_RESULT'. *Note Printing +Messages::. Those macros work best in conjunction with cache +variables. *Note Caching Results::. + + +File: autoconf.info, Node: Invoking autoupdate, Next: Changed Results, Prev: Changed Macros, Up: Upgrading + +Using `autoupdate' to Modernize `configure' +=========================================== + + The `autoupdate' program updates a `configure.in' file that calls +Autoconf macros by their old names to use the current macro names. In +version 2 of Autoconf, most of the macros were renamed to use a more +uniform and descriptive naming scheme. *Note Macro Names::, for a +description of the new scheme. Although the old names still work +(*note Old Macro Names::., for a list of the old macro names and the +corresponding new names), you can make your `configure.in' files more +readable and make it easier to use the current Autoconf documentation +if you update them to use the new macro names. + + If given no arguments, `autoupdate' updates `configure.in', backing +up the original version with the suffix `~' (or the value of the +environment variable `SIMPLE_BACKUP_SUFFIX', if that is set). If you +give `autoupdate' an argument, it reads that file instead of +`configure.in' and writes the updated file to the standard output. + +`autoupdate' accepts the following options: + +`--help' +`-h' + Print a summary of the command line options and exit. + +`--macrodir=DIR' +`-m DIR' + Look for the Autoconf macro files in directory DIR instead of the + default installation directory. You can also set the `AC_MACRODIR' + environment variable to a directory; this option overrides the + environment variable. + +`--version' + Print the version number of `autoupdate' and exit. + + +File: autoconf.info, Node: Changed Results, Next: Changed Macro Writing, Prev: Invoking autoupdate, Up: Upgrading + +Changed Results +=============== + + If you were checking the results of previous tests by examining the +shell variable `DEFS', you need to switch to checking the values of the +cache variables for those tests. `DEFS' no longer exists while +`configure' is running; it is only created when generating output +files. This difference from version 1 is because properly quoting the +contents of that variable turned out to be too cumbersome and +inefficient to do every time `AC_DEFINE' is called. *Note Cache +Variable Names::. + + For example, here is a `configure.in' fragment written for Autoconf +version 1: + + AC_HAVE_FUNCS(syslog) + case "$DEFS" in + *-DHAVE_SYSLOG*) ;; + *) # syslog is not in the default libraries. See if it's in some other. + saved_LIBS="$LIBS" + for lib in bsd socket inet; do + AC_CHECKING(for syslog in -l$lib) + LIBS="$saved_LIBS -l$lib" + AC_HAVE_FUNCS(syslog) + case "$DEFS" in + *-DHAVE_SYSLOG*) break ;; + *) ;; + esac + LIBS="$saved_LIBS" + done ;; + esac + + Here is a way to write it for version 2: + + AC_CHECK_FUNCS(syslog) + if test $ac_cv_func_syslog = no; then + # syslog is not in the default libraries. See if it's in some other. + for lib in bsd socket inet; do + AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG) + LIBS="$LIBS $lib"; break]) + done + fi + + If you were working around bugs in `AC_DEFINE_UNQUOTED' by adding +backslashes before quotes, you need to remove them. It now works +predictably, and does not treat quotes (except backquotes) specially. +*Note Setting Output Variables::. + + All of the boolean shell variables set by Autoconf macros now use +`yes' for the true value. Most of them use `no' for false, though for +backward compatibility some use the empty string instead. If you were +relying on a shell variable being set to something like 1 or `t' for +true, you need to change your tests. + + +File: autoconf.info, Node: Changed Macro Writing, Prev: Changed Results, Up: Upgrading + +Changed Macro Writing +===================== + + When defining your own macros, you should now use `AC_DEFUN' instead +of `define'. `AC_DEFUN' automatically calls `AC_PROVIDE' and ensures +that macros called via `AC_REQUIRE' do not interrupt other macros, to +prevent nested `checking...' messages on the screen. There's no actual +harm in continuing to use the older way, but it's less convenient and +attractive. *Note Macro Definitions::. + + You probably looked at the macros that came with Autoconf as a guide +for how to do things. It would be a good idea to take a look at the new +versions of them, as the style is somewhat improved and they take +advantage of some new features. + + If you were doing tricky things with undocumented Autoconf internals +(macros, variables, diversions), check whether you need to change +anything to account for changes that have been made. Perhaps you can +even use an officially supported technique in version 2 instead of +kludging. Or perhaps not. + + To speed up your locally written feature tests, add caching to them. +See whether any of your tests are of general enough usefulness to +encapsulate into macros that you can share. + + +File: autoconf.info, Node: History, Next: Old Macro Names, Prev: Upgrading, Up: Top + +History of Autoconf +******************* + + You may be wondering, Why was Autoconf originally written? How did +it get into its present form? (Why does it look like gorilla spit?) If +you're not wondering, then this chapter contains no information useful +to you, and you might as well skip it. If you *are* wondering, then +let there be light... + +* Menu: + +* Genesis:: Prehistory and naming of `configure'. +* Exodus:: The plagues of `m4' and Perl. +* Leviticus:: The priestly code of portability arrives. +* Numbers:: Growth and contributors. +* Deuteronomy:: Approaching the promises of easy configuration. + + +File: autoconf.info, Node: Genesis, Next: Exodus, Up: History + +Genesis +======= + + In June 1991 I was maintaining many of the GNU utilities for the Free +Software Foundation. As they were ported to more platforms and more +programs were added, the number of `-D' options that users had to +select in the `Makefile' (around 20) became burdensome. Especially for +me--I had to test each new release on a bunch of different systems. So +I wrote a little shell script to guess some of the correct settings for +the fileutils package, and released it as part of fileutils 2.0. That +`configure' script worked well enough that the next month I adapted it +(by hand) to create similar `configure' scripts for several other GNU +utilities packages. Brian Berliner also adapted one of my scripts for +his CVS revision control system. + + Later that summer, I learned that Richard Stallman and Richard Pixley +were developing similar scripts to use in the GNU compiler tools; so I +adapted my `configure' scripts to support their evolving interface: +using the file name `Makefile.in' as the templates; adding `+srcdir', +the first option (of many); and creating `config.status' files. + + +File: autoconf.info, Node: Exodus, Next: Leviticus, Prev: Genesis, Up: History + +Exodus +====== + + As I got feedback from users, I incorporated many improvements, using +Emacs to search and replace, cut and paste, similar changes in each of +the scripts. As I adapted more GNU utilities packages to use +`configure' scripts, updating them all by hand became impractical. +Rich Murphey, the maintainer of the GNU graphics utilities, sent me mail +saying that the `configure' scripts were great, and asking if I had a +tool for generating them that I could send him. No, I thought, but I +should! So I started to work out how to generate them. And the +journey from the slavery of hand-written `configure' scripts to the +abundance and ease of Autoconf began. + + Cygnus `configure', which was being developed at around that time, +is table driven; it is meant to deal mainly with a discrete number of +system types with a small number of mainly unguessable features (such as +details of the object file format). The automatic configuration system +that Brian Fox had developed for Bash takes a similar approach. For +general use, it seems to me a hopeless cause to try to maintain an +up-to-date database of which features each variant of each operating +system has. It's easier and more reliable to check for most features on +the fly--especially on hybrid systems that people have hacked on +locally or that have patches from vendors installed. + + I considered using an architecture similar to that of Cygnus +`configure', where there is a single `configure' script that reads +pieces of `configure.in' when run. But I didn't want to have to +distribute all of the feature tests with every package, so I settled on +having a different `configure' made from each `configure.in' by a +preprocessor. That approach also offered more control and flexibility. + + I looked briefly into using the Metaconfig package, by Larry Wall, +Harlan Stenn, and Raphael Manfredi, but I decided not to for several +reasons. The `Configure' scripts it produces are interactive, which I +find quite inconvenient; I didn't like the ways it checked for some +features (such as library functions); I didn't know that it was still +being maintained, and the `Configure' scripts I had seen didn't work on +many modern systems (such as System V R4 and NeXT); it wasn't very +flexible in what it could do in response to a feature's presence or +absence; I found it confusing to learn; and it was too big and complex +for my needs (I didn't realize then how much Autoconf would eventually +have to grow). + + I considered using Perl to generate my style of `configure' scripts, +but decided that `m4' was better suited to the job of simple textual +substitutions: it gets in the way less, because output is implicit. +Plus, everyone already has it. (Initially I didn't rely on the GNU +extensions to `m4'.) Also, some of my friends at the University of +Maryland had recently been putting `m4' front ends on several programs, +including `tvtwm', and I was interested in trying out a new language. + + +File: autoconf.info, Node: Leviticus, Next: Numbers, Prev: Exodus, Up: History + +Leviticus +========= + + Since my `configure' scripts determine the system's capabilities +automatically, with no interactive user intervention, I decided to call +the program that generates them Autoconfig. But with a version number +tacked on, that name would be too long for old UNIX file systems, so I +shortened it to Autoconf. + + In the fall of 1991 I called together a group of fellow questers +after the Holy Grail of portability (er, that is, alpha testers) to +give me feedback as I encapsulated pieces of my handwritten scripts in +`m4' macros and continued to add features and improve the techniques +used in the checks. Prominent among the testers were Franc,ois Pinard, +who came up with the idea of making an `autoconf' shell script to run +`m4' and check for unresolved macro calls; Richard Pixley, who +suggested running the compiler instead of searching the file system to +find include files and symbols, for more accurate results; Karl Berry, +who got Autoconf to configure TeX and added the macro index to the +documentation; and Ian Taylor, who added support for creating a C +header file as an alternative to putting `-D' options in a `Makefile', +so he could use Autoconf for his UUCP package. The alpha testers +cheerfully adjusted their files again and again as the names and +calling conventions of the Autoconf macros changed from release to +release. They all contributed many specific checks, great ideas, and +bug fixes. + + +File: autoconf.info, Node: Numbers, Next: Deuteronomy, Prev: Leviticus, Up: History + +Numbers +======= + + In July 1992, after months of alpha testing, I released Autoconf 1.0, +and converted many GNU packages to use it. I was surprised by how +positive the reaction to it was. More people started using it than I +could keep track of, including people working on software that wasn't +part of the GNU Project (such as TCL, FSP, and Kerberos V5). Autoconf +continued to improve rapidly, as many people using the `configure' +scripts reported problems they encountered. + + Autoconf turned out to be a good torture test for `m4' +implementations. UNIX `m4' started to dump core because of the length +of the macros that Autoconf defined, and several bugs showed up in GNU +`m4' as well. Eventually, we realized that we needed to use some +features that only GNU `m4' has. 4.3BSD `m4', in particular, has an +impoverished set of builtin macros; the System V version is better, but +still doesn't provide everything we need. + + More development occurred as people put Autoconf under more stresses +(and to uses I hadn't anticipated). Karl Berry added checks for X11. +david zuhn contributed C++ support. Franc,ois Pinard made it diagnose +invalid arguments. Jim Blandy bravely coerced it into configuring GNU +Emacs, laying the groundwork for several later improvements. Roland +McGrath got it to configure the GNU C Library, wrote the `autoheader' +script to automate the creation of C header file templates, and added a +`--verbose' option to `configure'. Noah Friedman added the +`--macrodir' option and `AC_MACRODIR' environment variable. (He also +coined the term "autoconfiscate" to mean "adapt a software package to +use Autoconf".) Roland and Noah improved the quoting protection in +`AC_DEFINE' and fixed many bugs, especially when I got sick of dealing +with portability problems from February through June, 1993. + + +File: autoconf.info, Node: Deuteronomy, Prev: Numbers, Up: History + +Deuteronomy +=========== + + A long wish list for major features had accumulated, and the effect +of several years of patching by various people had left some residual +cruft. In April 1994, while working for Cygnus Support, I began a major +revision of Autoconf. I added most of the features of the Cygnus +`configure' that Autoconf had lacked, largely by adapting the relevant +parts of Cygnus `configure' with the help of david zuhn and Ken +Raeburn. These features include support for using `config.sub', +`config.guess', `--host', and `--target'; making links to files; and +running `configure' scripts in subdirectories. Adding these features +enabled Ken to convert GNU `as', and Rob Savoye to convert DejaGNU, to +using Autoconf. + + I added more features in response to other peoples' requests. Many +people had asked for `configure' scripts to share the results of the +checks between runs, because (particularly when configuring a large +source tree, like Cygnus does) they were frustratingly slow. Mike +Haertel suggested adding site-specific initialization scripts. People +distributing software that had to unpack on MS-DOS asked for a way to +override the `.in' extension on the file names, which produced file +names like `config.h.in' containing two dots. Jim Avera did an +extensive examination of the problems with quoting in `AC_DEFINE' and +`AC_SUBST'; his insights led to significant improvements. Richard +Stallman asked that compiler output be sent to `config.log' instead of +`/dev/null', to help people debug the Emacs `configure' script. + + I made some other changes because of my dissatisfaction with the +quality of the program. I made the messages showing results of the +checks less ambiguous, always printing a result. I regularized the +names of the macros and cleaned up coding style inconsistencies. I +added some auxiliary utilities that I had developed to help convert +source code packages to use Autoconf. With the help of Franc,ois +Pinard, I made the macros not interrupt each others' messages. (That +feature revealed some performance bottlenecks in GNU `m4', which he +hastily corrected!) I reorganized the documentation around problems +people want to solve. And I began a testsuite, because experience had +shown that Autoconf has a pronounced tendency to regress when we change +it. + + Again, several alpha testers gave invaluable feedback, especially +Franc,ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, +and Mark Eichin. + + Finally, version 2.0 was ready. And there was much rejoicing. (And +I have free time again. I think. Yeah, right.) + + +File: autoconf.info, Node: Old Macro Names, Next: Environment Variable Index, Prev: History, Up: Top + +Old Macro Names +*************** + + In version 2 of Autoconf, most of the macros were renamed to use a +more uniform and descriptive naming scheme. Here are the old names of +the macros that were renamed, followed by the current names of those +macros. Although the old names are still accepted by the `autoconf' +program for backward compatibility, the old names are considered +obsolete. *Note Macro Names::, for a description of the new naming +scheme. + +`AC_ALLOCA' + `AC_FUNC_ALLOCA' + +`AC_ARG_ARRAY' + removed because of limited usefulness + +`AC_CHAR_UNSIGNED' + `AC_C_CHAR_UNSIGNED' + +`AC_CONST' + `AC_C_CONST' + +`AC_CROSS_CHECK' + `AC_C_CROSS' + +`AC_ERROR' + `AC_MSG_ERROR' + +`AC_FIND_X' + `AC_PATH_X' + +`AC_FIND_XTRA' + `AC_PATH_XTRA' + +`AC_FUNC_CHECK' + `AC_CHECK_FUNC' + +`AC_GCC_TRADITIONAL' + `AC_PROG_GCC_TRADITIONAL' + +`AC_GETGROUPS_T' + `AC_TYPE_GETGROUPS' + +`AC_GETLOADAVG' + `AC_FUNC_GETLOADAVG' + +`AC_HAVE_FUNCS' + `AC_CHECK_FUNCS' + +`AC_HAVE_HEADERS' + `AC_CHECK_HEADERS' + +`AC_HAVE_POUNDBANG' + `AC_SYS_INTERPRETER' (different calling convention) + +`AC_HEADER_CHECK' + `AC_CHECK_HEADER' + +`AC_HEADER_EGREP' + `AC_EGREP_HEADER' + +`AC_INLINE' + `AC_C_INLINE' + +`AC_LN_S' + `AC_PROG_LN_S' + +`AC_LONG_DOUBLE' + `AC_C_LONG_DOUBLE' + +`AC_LONG_FILE_NAMES' + `AC_SYS_LONG_FILE_NAMES' + +`AC_MAJOR_HEADER' + `AC_HEADER_MAJOR' + +`AC_MINUS_C_MINUS_O' + `AC_PROG_CC_C_O' + +`AC_MMAP' + `AC_FUNC_MMAP' + +`AC_MODE_T' + `AC_TYPE_MODE_T' + +`AC_OFF_T' + `AC_TYPE_OFF_T' + +`AC_PID_T' + `AC_TYPE_PID_T' + +`AC_PREFIX' + `AC_PREFIX_PROGRAM' + +`AC_PROGRAMS_CHECK' + `AC_CHECK_PROGS' + +`AC_PROGRAMS_PATH' + `AC_PATH_PROGS' + +`AC_PROGRAM_CHECK' + `AC_CHECK_PROG' + +`AC_PROGRAM_EGREP' + `AC_EGREP_CPP' + +`AC_PROGRAM_PATH' + `AC_PATH_PROG' + +`AC_REMOTE_TAPE' + removed because of limited usefulness + +`AC_RESTARTABLE_SYSCALLS' + `AC_SYS_RESTARTABLE_SYSCALLS' + +`AC_RETSIGTYPE' + `AC_TYPE_SIGNAL' + +`AC_RSH' + removed because of limited usefulness + +`AC_SETVBUF_REVERSED' + `AC_FUNC_SETVBUF_REVERSED' + +`AC_SET_MAKE' + `AC_PROG_MAKE_SET' + +`AC_SIZEOF_TYPE' + `AC_CHECK_SIZEOF' + +`AC_SIZE_T' + `AC_TYPE_SIZE_T' + +`AC_STAT_MACROS_BROKEN' + `AC_HEADER_STAT' + +`AC_STDC_HEADERS' + `AC_HEADER_STDC' + +`AC_STRCOLL' + `AC_FUNC_STRCOLL' + +`AC_ST_BLKSIZE' + `AC_STRUCT_ST_BLKSIZE' + +`AC_ST_BLOCKS' + `AC_STRUCT_ST_BLOCKS' + +`AC_ST_RDEV' + `AC_STRUCT_ST_RDEV' + +`AC_SYS_SIGLIST_DECLARED' + `AC_DECL_SYS_SIGLIST' + +`AC_TEST_CPP' + `AC_TRY_CPP' + +`AC_TEST_PROGRAM' + `AC_TRY_RUN' + +`AC_TIMEZONE' + `AC_STRUCT_TIMEZONE' + +`AC_TIME_WITH_SYS_TIME' + `AC_HEADER_TIME' + +`AC_UID_T' + `AC_TYPE_UID_T' + +`AC_UTIME_NULL' + `AC_FUNC_UTIME_NULL' + +`AC_VFORK' + `AC_FUNC_VFORK' + +`AC_VPRINTF' + `AC_FUNC_VPRINTF' + +`AC_WAIT3' + `AC_FUNC_WAIT3' + +`AC_WARN' + `AC_MSG_WARN' + +`AC_WORDS_BIGENDIAN' + `AC_C_BIGENDIAN' + +`AC_YYTEXT_POINTER' + `AC_DECL_YYTEXT' + + +File: autoconf.info, Node: Environment Variable Index, Next: Output Variable Index, Prev: Old Macro Names, Up: Top + +Environment Variable Index +************************** + + This is an alphabetical list of the environment variables that +Autoconf checks. + +* Menu: + +* AC_MACRODIR <1>: Invoking autoupdate. +* AC_MACRODIR <1>: Invoking autoheader. +* AC_MACRODIR <1>: Invoking autoreconf. +* AC_MACRODIR <1>: Invoking autoconf. +* AC_MACRODIR <1>: Invoking ifnames. +* AC_MACRODIR: Invoking autoscan. +* CONFIG_FILES: Invoking config.status. +* CONFIG_HEADERS: Invoking config.status. +* CONFIG_SHELL: Invoking config.status. +* CONFIG_SITE: Site Defaults. +* CONFIG_STATUS: Invoking config.status. +* SIMPLE_BACKUP_SUFFIX: Invoking autoupdate. + + +File: autoconf.info, Node: Output Variable Index, Next: Preprocessor Symbol Index, Prev: Environment Variable Index, Up: Top + +Output Variable Index +********************* + + This is an alphabetical list of the variables that Autoconf can +substitute into files that it creates, typically one or more +`Makefile's. *Note Setting Output Variables::, for more information on +how this is done. + +* Menu: + +* ALLOCA: Particular Functions. +* AWK: Particular Programs. +* bindir: Preset Output Variables. +* build: System Type Variables. +* build_alias: System Type Variables. +* build_cpu: System Type Variables. +* build_os: System Type Variables. +* build_vendor: System Type Variables. +* CC <1>: UNIX Variants. +* CC: Particular Programs. +* CFLAGS <1>: Particular Programs. +* CFLAGS: Preset Output Variables. +* configure_input: Preset Output Variables. +* CPP: Particular Programs. +* CPPFLAGS: Preset Output Variables. +* CXX: Particular Programs. +* CXXCPP: Particular Programs. +* CXXFLAGS <1>: Particular Programs. +* CXXFLAGS: Preset Output Variables. +* datadir: Preset Output Variables. +* DEFS: Preset Output Variables. +* exec_prefix: Preset Output Variables. +* host: System Type Variables. +* host_alias: System Type Variables. +* host_cpu: System Type Variables. +* host_os: System Type Variables. +* host_vendor: System Type Variables. +* includedir: Preset Output Variables. +* infodir: Preset Output Variables. +* INSTALL: Particular Programs. +* INSTALL_DATA: Particular Programs. +* INSTALL_PROGRAM: Particular Programs. +* KMEM_GROUP: Particular Functions. +* LDFLAGS: Preset Output Variables. +* LEX: Particular Programs. +* LEX_OUTPUT_ROOT: Particular Programs. +* LEXLIB: Particular Programs. +* libdir: Preset Output Variables. +* libexecdir: Preset Output Variables. +* LIBOBJS <1>: Structures. +* LIBOBJS <1>: Generic Functions. +* LIBOBJS: Particular Functions. +* LIBS <1>: UNIX Variants. +* LIBS: Preset Output Variables. +* LN_S: Particular Programs. +* localstatedir: Preset Output Variables. +* mandir: Preset Output Variables. +* NEED_SETGID: Particular Functions. +* oldincludedir: Preset Output Variables. +* prefix: Preset Output Variables. +* program_transform_name: Transforming Names. +* RANLIB: Particular Programs. +* sbindir: Preset Output Variables. +* SET_MAKE: Output. +* sharedstatedir: Preset Output Variables. +* srcdir: Preset Output Variables. +* subdirs: Subdirectories. +* sysconfdir: Preset Output Variables. +* target: System Type Variables. +* target_alias: System Type Variables. +* target_cpu: System Type Variables. +* target_os: System Type Variables. +* target_vendor: System Type Variables. +* top_srcdir: Preset Output Variables. +* X_CFLAGS: System Services. +* X_EXTRA_LIBS: System Services. +* X_LIBS: System Services. +* X_PRE_LIBS: System Services. +* YACC: Particular Programs. + + +File: autoconf.info, Node: Preprocessor Symbol Index, Next: Macro Index, Prev: Output Variable Index, Up: Top + +Preprocessor Symbol Index +************************* + + This is an alphabetical list of the C preprocessor symbols that the +Autoconf macros define. To work with Autoconf, C source code needs to +use these names in `#if' directives. + +* Menu: + +* __CHAR_UNSIGNED__: Compiler Characteristics. +* _ALL_SOURCE: UNIX Variants. +* _MINIX: UNIX Variants. +* _POSIX_1_SOURCE: UNIX Variants. +* _POSIX_SOURCE: UNIX Variants. +* _POSIX_VERSION: Particular Headers. +* C_ALLOCA: Particular Functions. +* CLOSEDIR_VOID: Particular Functions. +* const: Compiler Characteristics. +* DGUX: Particular Functions. +* DIRENT: Particular Headers. +* GETGROUPS_T: Particular Typedefs. +* GETLODAVG_PRIVILEGED: Particular Functions. +* GETPGRP_VOID: Particular Functions. +* gid_t: Particular Typedefs. +* HAVE_FUNCTION: Generic Functions. +* HAVE_HEADER: Generic Headers. +* HAVE_ALLOCA_H: Particular Functions. +* HAVE_CONFIG_H: Configuration Headers. +* HAVE_DIRENT_H: Particular Headers. +* HAVE_DOPRNT: Particular Functions. +* HAVE_GETMNTENT: Particular Functions. +* HAVE_LONG_DOUBLE: Compiler Characteristics. +* HAVE_LONG_FILE_NAMES: System Services. +* HAVE_MMAP: Particular Functions. +* HAVE_NDIR_H: Particular Headers. +* HAVE_RESTARTABLE_SYSCALLS: System Services. +* HAVE_ST_BLKSIZE: Structures. +* HAVE_ST_BLOCKS: Structures. +* HAVE_ST_RDEV: Structures. +* HAVE_STRCOLL: Particular Functions. +* HAVE_STRFTIME: Particular Functions. +* HAVE_SYS_DIR_H: Particular Headers. +* HAVE_SYS_NDIR_H: Particular Headers. +* HAVE_SYS_WAIT_H: Particular Headers. +* HAVE_TM_ZONE: Structures. +* HAVE_TZNAME: Structures. +* HAVE_UNISTD_H: Particular Headers. +* HAVE_UTIME_NULL: Particular Functions. +* HAVE_VFORK_H: Particular Functions. +* HAVE_VPRINTF: Particular Functions. +* HAVE_WAIT3: Particular Functions. +* inline: Compiler Characteristics. +* INT_16_BITS: Compiler Characteristics. +* LONG_64_BITS: Compiler Characteristics. +* MAJOR_IN_MKDEV: Particular Headers. +* MAJOR_IN_SYSMACROS: Particular Headers. +* mode_t: Particular Typedefs. +* NDIR: Particular Headers. +* NEED_MEMORY_H: Particular Headers. +* NEED_SETGID: Particular Functions. +* NLIST_NAME_UNION: Particular Functions. +* NLIST_STRUCT: Particular Functions. +* NO_MINUS_C_MINUS_O: Particular Programs. +* off_t: Particular Typedefs. +* pid_t: Particular Typedefs. +* RETSIGTYPE: Particular Typedefs. +* SETVBUF_REVERSED: Particular Functions. +* size_t: Particular Typedefs. +* STDC_HEADERS: Particular Headers. +* SVR4: Particular Functions. +* SYS_SIGLIST_DECLARED: Particular Headers. +* SYSDIR: Particular Headers. +* SYSNDIR: Particular Headers. +* TIME_WITH_SYS_TIME: Structures. +* TM_IN_SYS_TIME: Structures. +* uid_t: Particular Typedefs. +* UMAX: Particular Functions. +* UMAX4_3: Particular Functions. +* USG: Particular Headers. +* vfork: Particular Functions. +* VOID_CLOSEDIR: Particular Headers. +* WORDS_BIGENDIAN: Compiler Characteristics. +* YYTEXT_POINTER: Particular Programs. + + +File: autoconf.info, Node: Macro Index, Prev: Preprocessor Symbol Index, Up: Top + +Macro Index +*********** + + This is an alphabetical list of the Autoconf macros. To make the +list easier to use, the macros are listed without their preceding `AC_'. + +* Menu: + +* AIX: UNIX Variants. +* ALLOCA: Old Macro Names. +* ARG_ARRAY: Old Macro Names. +* ARG_ENABLE: Package Options. +* ARG_PROGRAM: Transforming Names. +* ARG_WITH: External Software. +* BEFORE: Suggested Ordering. +* C_BIGENDIAN: Compiler Characteristics. +* C_CHAR_UNSIGNED: Compiler Characteristics. +* C_CONST: Compiler Characteristics. +* C_CROSS: Test Programs. +* C_INLINE: Compiler Characteristics. +* C_LONG_DOUBLE: Compiler Characteristics. +* CACHE_CHECK: Caching Results. +* CACHE_VAL: Caching Results. +* CANONICAL_HOST: Canonicalizing. +* CANONICAL_SYSTEM: Canonicalizing. +* CHAR_UNSIGNED: Old Macro Names. +* CHECK_FUNC: Generic Functions. +* CHECK_FUNCS: Generic Functions. +* CHECK_HEADER: Generic Headers. +* CHECK_HEADERS: Generic Headers. +* CHECK_LIB: Libraries. +* CHECK_PROG: Generic Programs. +* CHECK_PROGS: Generic Programs. +* CHECK_SIZEOF: Compiler Characteristics. +* CHECK_TOOL: Generic Programs. +* CHECK_TYPE: Generic Typedefs. +* CHECKING: Printing Messages. +* COMPILE_CHECK: Examining Libraries. +* CONFIG_AUX_DIR: Input. +* CONFIG_HEADER: Configuration Headers. +* CONFIG_SUBDIRS: Subdirectories. +* CONST: Old Macro Names. +* CROSS_CHECK: Old Macro Names. +* DECL_SYS_SIGLIST: Particular Headers. +* DECL_YYTEXT: Particular Programs. +* DEFINE: Defining Symbols. +* DEFINE_UNQUOTED: Defining Symbols. +* DEFUN: Macro Definitions. +* DIR_HEADER: Particular Headers. +* DYNIX_SEQ: UNIX Variants. +* EGREP_CPP: Examining Declarations. +* EGREP_HEADER: Examining Declarations. +* ENABLE: Package Options. +* ERROR: Old Macro Names. +* FIND_X: Old Macro Names. +* FIND_XTRA: Old Macro Names. +* FUNC_ALLOCA: Particular Functions. +* FUNC_CHECK: Old Macro Names. +* FUNC_CLOSEDIR_VOID: Particular Functions. +* FUNC_GETLOADAVG: Particular Functions. +* FUNC_GETMNTENT: Particular Functions. +* FUNC_GETPGRP: Particular Functions. +* FUNC_MEMCMP: Particular Functions. +* FUNC_MMAP: Particular Functions. +* FUNC_SETVBUF_REVERSED: Particular Functions. +* FUNC_STRCOLL: Particular Functions. +* FUNC_STRFTIME: Particular Functions. +* FUNC_UTIME_NULL: Particular Functions. +* FUNC_VFORK: Particular Functions. +* FUNC_VPRINTF: Particular Functions. +* FUNC_WAIT3: Particular Functions. +* GCC_TRADITIONAL: Old Macro Names. +* GETGROUPS_T: Old Macro Names. +* GETLOADAVG: Old Macro Names. +* HAVE_FUNCS: Old Macro Names. +* HAVE_HEADERS: Old Macro Names. +* HAVE_LIBRARY: Libraries. +* HAVE_POUNDBANG: Old Macro Names. +* HEADER_CHECK: Old Macro Names. +* HEADER_DIRENT: Particular Headers. +* HEADER_EGREP: Old Macro Names. +* HEADER_MAJOR: Particular Headers. +* HEADER_STAT: Structures. +* HEADER_STDC: Particular Headers. +* HEADER_SYS_WAIT: Particular Headers. +* HEADER_TIME: Structures. +* INIT: Input. +* INLINE: Old Macro Names. +* INT_16_BITS: Compiler Characteristics. +* IRIX_SUN: UNIX Variants. +* ISC_POSIX: UNIX Variants. +* LANG_C: Language Choice. +* LANG_CPLUSPLUS: Language Choice. +* LANG_RESTORE: Language Choice. +* LANG_SAVE: Language Choice. +* LINK_FILES: Using System Type. +* LN_S: Old Macro Names. +* LONG_64_BITS: Compiler Characteristics. +* LONG_DOUBLE: Old Macro Names. +* LONG_FILE_NAMES: Old Macro Names. +* MAJOR_HEADER: Old Macro Names. +* MEMORY_H: Particular Headers. +* MINIX: UNIX Variants. +* MINUS_C_MINUS_O: Old Macro Names. +* MMAP: Old Macro Names. +* MODE_T: Old Macro Names. +* MSG_CHECKING: Printing Messages. +* MSG_ERROR: Printing Messages. +* MSG_RESULT: Printing Messages. +* MSG_WARN: Printing Messages. +* OBSOLETE: Obsolete Macros. +* OFF_T: Old Macro Names. +* OUTPUT: Output. +* PATH_PROG: Generic Programs. +* PATH_PROGS: Generic Programs. +* PATH_X: System Services. +* PATH_XTRA: System Services. +* PID_T: Old Macro Names. +* PREFIX: Old Macro Names. +* PREFIX_PROGRAM: Default Prefix. +* PREREQ: Versions. +* PROG_AWK: Particular Programs. +* PROG_CC: Particular Programs. +* PROG_CC_C_O: Particular Programs. +* PROG_CPP: Particular Programs. +* PROG_CXX: Particular Programs. +* PROG_CXXCPP: Particular Programs. +* PROG_GCC_TRADITIONAL: Particular Programs. +* PROG_INSTALL: Particular Programs. +* PROG_LEX: Particular Programs. +* PROG_LN_S: Particular Programs. +* PROG_MAKE_SET: Output. +* PROG_RANLIB: Particular Programs. +* PROG_YACC: Particular Programs. +* PROGRAM_CHECK: Old Macro Names. +* PROGRAM_EGREP: Old Macro Names. +* PROGRAM_PATH: Old Macro Names. +* PROGRAMS_CHECK: Old Macro Names. +* PROGRAMS_PATH: Old Macro Names. +* PROVIDE: Prerequisite Macros. +* REMOTE_TAPE: Old Macro Names. +* REPLACE_FUNCS: Generic Functions. +* REQUIRE: Prerequisite Macros. +* REQUIRE_CPP: Language Choice. +* RESTARTABLE_SYSCALLS: Old Macro Names. +* RETSIGTYPE: Old Macro Names. +* REVISION: Versions. +* RSH: Old Macro Names. +* SCO_INTL: UNIX Variants. +* SET_MAKE: Old Macro Names. +* SETVBUF_REVERSED: Old Macro Names. +* SIZE_T: Old Macro Names. +* SIZEOF_TYPE: Old Macro Names. +* ST_BLKSIZE: Old Macro Names. +* ST_BLOCKS: Old Macro Names. +* ST_RDEV: Old Macro Names. +* STAT_MACROS_BROKEN <1>: Old Macro Names. +* STAT_MACROS_BROKEN: Structures. +* STDC_HEADERS: Old Macro Names. +* STRCOLL: Old Macro Names. +* STRUCT_ST_BLKSIZE: Structures. +* STRUCT_ST_BLOCKS: Structures. +* STRUCT_ST_RDEV: Structures. +* STRUCT_TIMEZONE: Structures. +* STRUCT_TM: Structures. +* SUBST: Setting Output Variables. +* SUBST_FILE: Setting Output Variables. +* SYS_INTERPRETER: System Services. +* SYS_LONG_FILE_NAMES: System Services. +* SYS_RESTARTABLE_SYSCALLS: System Services. +* SYS_SIGLIST_DECLARED: Old Macro Names. +* TEST_CPP: Old Macro Names. +* TEST_PROGRAM: Old Macro Names. +* TIME_WITH_SYS_TIME: Old Macro Names. +* TIMEZONE: Old Macro Names. +* TRY_COMPILE: Examining Syntax. +* TRY_CPP: Examining Declarations. +* TRY_LINK: Examining Libraries. +* TRY_RUN: Test Programs. +* TYPE_GETGROUPS: Particular Typedefs. +* TYPE_MODE_T: Particular Typedefs. +* TYPE_OFF_T: Particular Typedefs. +* TYPE_PID_T: Particular Typedefs. +* TYPE_SIGNAL: Particular Typedefs. +* TYPE_SIZE_T: Particular Typedefs. +* TYPE_UID_T: Particular Typedefs. +* UID_T: Old Macro Names. +* UNISTD_H: Particular Headers. +* USG: Particular Headers. +* UTIME_NULL: Old Macro Names. +* VERBOSE: Printing Messages. +* VFORK: Old Macro Names. +* VPRINTF: Old Macro Names. +* WAIT3: Old Macro Names. +* WARN: Old Macro Names. +* WITH: External Software. +* WORDS_BIGENDIAN: Old Macro Names. +* XENIX_DIR: UNIX Variants. +* YYTEXT_POINTER: Old Macro Names. + +  Tag Table: -(Indirect) -Node: Top1159 -Node: Introduction9298 -Node: Making configure Scripts13138 -Node: Writing configure.in16203 -Node: Invoking autoscan19903 -Node: Invoking ifnames22208 -Node: Invoking autoconf23698 -Node: Invoking autoreconf25536 -Node: Setup27856 -Node: Input28742 -Node: Output30465 -Node: Makefile Substitutions33215 -Node: Preset Output Variables34804 -Node: Build Directories38043 -Node: Automatic Remaking39676 -Node: Configuration Headers41762 -Node: Header Templates44129 -Node: Invoking autoheader45308 -Node: Subdirectories48395 -Node: Default Prefix49738 -Node: Versions51142 -Node: Existing Tests53046 -Node: Alternative Programs54511 -Node: Particular Programs55175 -Node: Generic Programs61025 -Node: Libraries63534 -Node: Library Functions65363 -Node: Particular Functions65921 -Node: Generic Functions72205 -Node: Header Files74046 -Node: Particular Headers74605 -Node: Generic Headers81576 -Node: Structures82876 -Node: Typedefs85113 -Node: Particular Typedefs85617 -Node: Generic Typedefs86817 -Node: Compiler Characteristics87260 -Node: System Services89744 -Node: UNIX Variants92093 -Node: Writing Tests94112 -Node: Examining Declarations96078 -Node: Examining Syntax98544 -Node: Examining Libraries99599 -Node: Run Time102156 -Node: Test Programs103117 -Node: Guidelines105652 -Node: Test Functions106841 -Node: Portable Shell108384 -Node: Testing Values and Files110321 -Node: Multiple Cases111976 -Node: Language Choice113174 -Node: Results114732 -Node: Defining Symbols115491 -Node: Setting Output Variables118500 -Node: Caching Results120346 -Node: Cache Variable Names122248 -Node: Cache Files123797 -Node: Printing Messages125582 -Node: Writing Macros128869 -Node: Macro Definitions129488 -Node: Macro Names130593 -Node: Quoting133044 -Node: Dependencies Between Macros134946 -Node: Prerequisite Macros135578 -Node: Suggested Ordering137033 -Node: Obsolete Macros138563 -Node: Manual Configuration139787 -Node: Specifying Names140686 -Node: Canonicalizing142558 -Node: System Type Variables143872 -Node: Using System Type144619 -Node: Site Configuration146066 -Node: External Software146839 -Node: Package Options149475 -Node: Site Details151699 -Node: Transforming Names152922 -Node: Transformation Options154100 -Node: Transformation Examples154566 -Node: Transformation Rules156134 -Node: Site Defaults157543 -Node: Invoking configure161327 -Node: Basic Installation162276 -Node: Compilers and Options164856 -Node: Multiple Architectures165505 -Node: Installation Names166491 -Node: Optional Features167416 -Node: System Type168186 -Node: Sharing Defaults169208 -Node: Operation Controls169832 -Node: Invoking config.status170707 -Node: Questions174095 -Node: Distributing174627 -Node: Why GNU m4175753 -Node: Bootstrapping176566 -Node: Why Not Imake177182 -Node: Upgrading181591 -Node: Changed File Names183112 -Node: Changed Makefiles183848 -Node: Changed Macros184944 -Node: Invoking autoupdate186191 -Node: Changed Results187782 -Node: Changed Macro Writing189884 -Node: History191147 -Node: Genesis191854 -Node: Exodus193027 -Node: Leviticus196076 -Node: Numbers197599 -Node: Deuteronomy199515 -Node: Old Macro Names202179 -Node: Environment Variable Index205228 -Node: Output Variable Index206230 -Node: Preprocessor Symbol Index210311 -Node: Macro Index215181 +Node: Top1177 +Node: Introduction9316 +Node: Making configure Scripts13156 +Node: Writing configure.in16221 +Node: Invoking autoscan19921 +Node: Invoking ifnames22226 +Node: Invoking autoconf23716 +Node: Invoking autoreconf25554 +Node: Setup27874 +Node: Input28760 +Node: Output30483 +Node: Makefile Substitutions33233 +Node: Preset Output Variables34817 +Node: Build Directories39319 +Node: Automatic Remaking40952 +Node: Configuration Headers43038 +Node: Header Templates45405 +Node: Invoking autoheader46584 +Node: Subdirectories49732 +Node: Default Prefix51075 +Node: Versions52479 +Node: Existing Tests54383 +Node: Alternative Programs55848 +Node: Particular Programs56512 +Node: Generic Programs62362 +Node: Libraries65188 +Node: Library Functions67017 +Node: Particular Functions67575 +Node: Generic Functions73878 +Node: Header Files75721 +Node: Particular Headers76280 +Node: Generic Headers83251 +Node: Structures84553 +Node: Typedefs86790 +Node: Particular Typedefs87294 +Node: Generic Typedefs88494 +Node: Compiler Characteristics88937 +Node: System Services91562 +Node: UNIX Variants93911 +Node: Writing Tests95930 +Node: Examining Declarations97896 +Node: Examining Syntax100366 +Node: Examining Libraries101423 +Node: Run Time103982 +Node: Test Programs104943 +Node: Guidelines107480 +Node: Test Functions108669 +Node: Portable Shell110212 +Node: Testing Values and Files112144 +Node: Multiple Cases113799 +Node: Language Choice114997 +Node: Results116555 +Node: Defining Symbols117314 +Node: Setting Output Variables120323 +Node: Caching Results122169 +Node: Cache Variable Names124450 +Node: Cache Files125999 +Node: Printing Messages128097 +Node: Writing Macros131384 +Node: Macro Definitions132003 +Node: Macro Names133108 +Node: Quoting135559 +Node: Dependencies Between Macros137461 +Node: Prerequisite Macros138093 +Node: Suggested Ordering139548 +Node: Obsolete Macros141078 +Node: Manual Configuration142302 +Node: Specifying Names143201 +Node: Canonicalizing145073 +Node: System Type Variables146387 +Node: Using System Type147134 +Node: Site Configuration148581 +Node: External Software149354 +Node: Package Options152052 +Node: Site Details154319 +Node: Transforming Names155542 +Node: Transformation Options156720 +Node: Transformation Examples157186 +Node: Transformation Rules158754 +Node: Site Defaults160163 +Node: Invoking configure163947 +Node: Basic Installation164896 +Node: Compilers and Options167476 +Node: Multiple Architectures168125 +Node: Installation Names169111 +Node: Optional Features170295 +Node: System Type171065 +Node: Sharing Defaults172087 +Node: Operation Controls172711 +Node: Invoking config.status173586 +Node: Questions176974 +Node: Distributing177506 +Node: Why GNU m4178632 +Node: Bootstrapping179445 +Node: Why Not Imake180061 +Node: Upgrading184470 +Node: Changed File Names185991 +Node: Changed Makefiles186727 +Node: Changed Macros187823 +Node: Invoking autoupdate189070 +Node: Changed Results190661 +Node: Changed Macro Writing192763 +Node: History194026 +Node: Genesis194733 +Node: Exodus195906 +Node: Leviticus198955 +Node: Numbers200478 +Node: Deuteronomy202394 +Node: Old Macro Names205058 +Node: Environment Variable Index208107 +Node: Output Variable Index209109 +Node: Preprocessor Symbol Index213792 +Node: Macro Index218607  End Tag Table diff --git a/src/util/autoconf/autoconf.sh b/src/util/autoconf/autoconf.sh index 65b1326d8..41a182cb7 100644 --- a/src/util/autoconf/autoconf.sh +++ b/src/util/autoconf/autoconf.sh @@ -1,6 +1,6 @@ #! /bin/sh # autoconf -- create `configure' using m4 macros -# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. +# Copyright (C) 1992, 1993, 1994, 1996 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 @@ -21,8 +21,8 @@ # the given template file. usage="\ -Usage: autoconf [-h] [--help] [-m dir] [--macrodir=dir] - [-l dir] [--localdir=dir] [--version] [template-file]" +Usage: autoconf [-h] [--help] [-m dir] [--macrodir=dir] + [-l dir] [--localdir=dir] [--version] [template-file]" # NLS nuisances. # Only set `LANG' and `LC_ALL' to "C" if already set. @@ -33,6 +33,7 @@ if test "${LANG+set}" = set; then LANG=C; export LANG; fi : ${AC_MACRODIR=@datadir@} : ${M4=@M4@} +: ${AWK=@AWK@} case "${M4}" in /*) # Handle the case that m4 has moved since we were configured. # It may have been found originally in a build directory. @@ -45,7 +46,7 @@ localdir= show_version=no while test $# -gt 0 ; do - case "${1}" in + case "${1}" in -h | --help | --h* ) echo "${usage}" 1>&2; exit 0 ;; --localdir=* | --l*=* ) @@ -59,7 +60,7 @@ while test $# -gt 0 ; do --macrodir=* | --m*=* ) AC_MACRODIR="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" shift ;; - -m | --macrodir | --m* ) + -m | --macrodir | --m* ) shift test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } AC_MACRODIR="${1}" @@ -125,11 +126,12 @@ $M4 -I$AC_MACRODIR $use_localdir $r autoconf.m4$f $infile > $tmpout || pattern="AC_" status=0 -if grep "${pattern}" $tmpout > /dev/null 2>&1; then +if grep "^[^#]*${pattern}" $tmpout > /dev/null 2>&1; then echo "autoconf: Undefined macros:" >&2 - grep "${pattern}" $tmpout | sed "s/.*\(${pattern}[_A-Z0-9]*\).*/\1/" | - while read name; do - grep -n $name $infile /dev/null + sed -n "s/^[^#]*\\(${pattern}[_A-Za-z0-9]*\\).*/\\1/p" $tmpout | + while read macro; do + grep -n "^[^#]*$macro" $infile /dev/null + test $? -eq 1 && echo >&2 "***BUG in Autoconf--please report*** $macro" done | sort -u >&2 status=1 fi @@ -141,11 +143,11 @@ else fi # Put the real line numbers into configure to make config.log more helpful. -awk ' +$AWK ' /__oline__/ { printf "%d:", NR + 1 } { print } ' $tmpout | sed ' -/__oline__/s/^\([0-9][0-9]*\):\(.*\)__oline__\(.*\)$/\2\1\3/ +/__oline__/s/^\([0-9][0-9]*\):\(.*\)__oline__/\2\1/ ' >&4 rm -f $tmpout diff --git a/src/util/autoconf/autoconf.texi b/src/util/autoconf/autoconf.texi index 476a2cc35..92354729a 100644 --- a/src/util/autoconf/autoconf.texi +++ b/src/util/autoconf/autoconf.texi @@ -6,9 +6,9 @@ @c @setchapternewpage odd @c %**end of header -@set EDITION 2.3 -@set VERSION 2.3 -@set UPDATED March 1995 +@set EDITION 2.8 +@set VERSION 2.8 +@set UPDATED January 1996 @iftex @finalout @@ -27,7 +27,7 @@ This file documents the GNU Autoconf package for creating scripts to configure source code packages using templates and an @code{m4} macro package. -Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. +Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -61,7 +61,7 @@ by the Foundation. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. +Copyright @copyright{} 1992, '93, '94, '95, '96 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -410,7 +410,7 @@ Files used in preparing a software package for distribution: your source files --> [autoscan*] --> [configure.scan] --> configure.in configure.in --. .------> autoconf* -----> configure - +---+ + +---+ [aclocal.m4] --+ `---. [acsite.m4] ---' | +--> [autoheader*] -> [config.h.in] @@ -719,7 +719,7 @@ environment variable. @item --verbose Print the name of each directory where @code{autoreconf} runs @code{autoconf} (and @code{autoheader}, if appropriate). - + @item --version Print the version number of Autoconf and exit. @end table @@ -794,6 +794,7 @@ Create output files. The @var{file}@dots{} argument is a whitespace-separated list of output files; it may be empty. This macro creates each file @file{@var{file}} by copying an input file (by default named @file{@var{file}.in}), substituting the output variable values. +@c If the file would be unchanged, it is left untouched, to preserve its timestamp. @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 (but @@ -871,7 +872,7 @@ 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.info, The +@xref{Makefile Conventions, , Makefile Conventions, standards, The GNU Coding Standards}, for more information on what to put in @file{Makefile}s. @@ -888,7 +889,14 @@ 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. Here is what each of the preset ones -contains. +contains. @xref{Directory Variables, , Variables for Installation Directories, +standards, The GNU Coding Standards}, for more information about +the variables with names that end in @samp{dir}. + +@defvar bindir +@ovindex bindir +The directory for installing executables that users run. +@end defvar @defvar configure_input @ovindex configure_input @@ -909,21 +917,77 @@ 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 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. @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 installation prefix 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 srcdir @ovindex srcdir The directory that contains the source code for that @file{Makefile}. @end defvar +@defvar sysconfdir +@ovindex sysconfdir +The directory for installing read-only single-machine data. +@end defvar + @defvar top_srcdir @ovindex top_srcdir The top-level source code directory for the package. In the top-level @@ -1175,7 +1239,8 @@ symbol). The @code{autoheader} program can create a template file of C @samp{#define} statements for @code{configure} to use. If @file{configure.in} invokes @code{AC_CONFIG_HEADER(@var{file})}, -@code{autoheader} creates @file{@var{file}.in}. Otherwise, +@code{autoheader} creates @file{@var{file}.in}; if multiple file +arguments are given, the first one is used. Otherwise, @code{autoheader} creates @file{config.h.in}. If you give @code{autoheader} an argument, it uses that file instead of @@ -1353,7 +1418,7 @@ produces this in @code{configure}: @example #! /bin/sh -# From configure.in Revision: 1.30 +# From configure.in Revision: 1.30 @end example @end defmac @@ -1392,7 +1457,7 @@ Symbols}, for how to get those symbol definitions into your program. 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. +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. @@ -1579,26 +1644,30 @@ to @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}. 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}). If you need to check for a program that -might not be in the user's @code{PATH}, you can temporarily add to it: +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_save_path="$PATH" -PATH=/usr/libexec:/usr/sbin:/usr/etc:/etc -AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd) -PATH="$ac_save_path" +AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd, + $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc) @end example -@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found} @r{[}, @var{value-if-not-found}@r{]}) +@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found} @r{[}, @var{value-if-not-found} @r{[}, @var{path}, @r{[} @var{reject} @r{]]]}) @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. If @var{variable} was already set, -do nothing. Calls @code{AC_SUBST} for @var{variable}. +@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} @r{[}, @var{value-if-not-found}@r{]}) +@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) @maindex CHECK_PROGS Check for each program in the whitespace-separated list @var{progs-to-check-for} exists in @code{PATH}. If it is found, set @@ -1609,7 +1678,7 @@ list are found, set @var{variable} to @var{value-if-not-found}; if is not changed. Calls @code{AC_SUBST} for @var{variable}. @end defmac -@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for} @r{[}, @var{value-if-not-found}@r{]}) +@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) @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}, @@ -1624,13 +1693,13 @@ sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in or to @samp{:} if neither program exists. @end defmac -@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for} @r{[}, @var{value-if-not-found}@r{]}) +@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) @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} @r{[}, @var{value-if-not-found}@r{]}) +@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) @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 @@ -1807,9 +1876,9 @@ to the name of the group that should own the installed program. @defmac AC_FUNC_GETMNTENT @maindex FUNC_GETMNTENT @cvindex HAVE_GETMNTENT -Check for @code{getmntent} in the @file{sun} and @file{seq} -libraries, for Irix 4 and PTX, respectively. Then, if @code{getmntent} is -available, define @code{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 @@ -1909,7 +1978,7 @@ 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}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@defmac AC_CHECK_FUNC (@var{function}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) @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 @@ -2205,7 +2274,7 @@ 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}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@defmac AC_CHECK_HEADER (@var{header-file}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) @maindex CHECK_HEADER If the system header file @var{header-file} exists, execute shell commands @var{action-if-found}, otherwise execute @var{action-if-not-found}. If @@ -2454,13 +2523,17 @@ If the C compiler supports the @code{long double} type, define that define @code{__STDC__} do not support @code{long double}. @end defmac -@defmac AC_CHECK_SIZEOF (@var{type}) +@defmac AC_CHECK_SIZEOF (@var{type} @r{[}, @var{cross-size}@r{]}) @maindex CHECK_SIZEOF Define @code{SIZEOF_@var{uctype}} to be the size in bytes of the C (or C++) builtin type @var{type}, e.g. @samp{int} or @samp{char *}. If @samp{type} is unknown to the compiler, it gets a size of 0. @var{uctype} is @var{type}, with lowercase converted to uppercase, spaces changed to -underscores, and asterisks changed to @samp{P}. For example, the call +underscores, and asterisks changed to @samp{P}. If cross-compiling, the +value @var{cross-size} is used if given, otherwise @code{configure} +exits with an error message. + +For example, the call @example AC_CHECK_SIZEOF(int *) @end example @@ -2666,7 +2739,7 @@ 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}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) +@defmac AC_TRY_CPP (@var{includes}, @r{[}@var{action-if-true} @r{[}, @var{action-if-false}@r{]]}) @maindex TRY_CPP @var{includes} is C or C++ @code{#include} statements and declarations, on which shell variable, backquote, and backslash substitutions are @@ -2680,7 +2753,7 @@ This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because preprocessors. @end defmac -Here is now to find out whether a header file contains a particular +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 @@ -2706,7 +2779,7 @@ AC_EGREP_CPP(yes, ], is_aix=yes, is_aix=no) @end example -@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) @maindex EGREP_CPP @var{program} is the text of a C or C++ program, on which shell variable, backquote, and backslash substitutions are performed. If the @@ -2728,7 +2801,7 @@ 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}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) @maindex TRY_COMPILE Create a test C program to see whether a function whose body consists of @var{function-body} can be compiled; @var{includes} is any @@ -2769,7 +2842,7 @@ functions and global variables. It is also used (by checked for to @code{LIBS} temporarily and trying to link a small program. -@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) @maindex TRY_LINK Create a test C program to see whether a function whose body consists of @var{function-body} can be compiled and linked; @var{includes} is any @@ -2815,7 +2888,7 @@ package for cross-compiling. Use the following macro if you need to test run-time behavior of the system while configuring. -@defmac AC_TRY_RUN (@var{program}, @var{action-if-true} @r{[}, @var{action-if-false} @r{[}, @var{action-if-cross-compiling}@r{]]}) +@defmac AC_TRY_RUN (@var{program}, @r{[}@var{action-if-true} @r{[}, @var{action-if-false} @r{[}, @var{action-if-cross-compiling}@r{]]]}) @maindex TRY_RUN @var{program} is the text of a C program, on which shell variable and backquote substitutions are performed. If it compiles and links @@ -2955,10 +3028,10 @@ 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.info, GNU Coding Standards}, for the list. This +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. +packages. Some of these external utilities have a portable subset of features, as well; for example, don't rely on @code{ln} having a @samp{-f} option or @@ -3273,6 +3346,15 @@ before @code{configure} creates its output files. @xref{Cache Variable Names}, for how to choose the name of the @var{cache-id} variable. @end defmac +@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands}) +@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}. +@end defmac + @menu * Cache Variable Names:: Shell variables used in caches. * Cache Files:: Files @code{configure} uses for caching. @@ -3296,7 +3378,7 @@ for example, @samp{ac_cv_header_stat_broken} or 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}. +@samp{ac}. @item @code{_cv_} Indicates that this shell variable is a cache value. @@ -3334,13 +3416,23 @@ By default, configure uses @file{./config.cache} as the cache file, creating it if it does not exist already. @code{configure} accepts the @samp{--cache-file=@var{file}} option to use a different cache file; that is what @code{configure} does when it calls @code{configure} -scripts in subdirectories, so they share the cache. Giving -@samp{--cache-file=/dev/null} disables caching, for debugging -@code{configure}. @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 @samp{--recheck} option, which makes it rerun -@code{configure}. +scripts in subdirectories, so they share the cache. +@xref{Subdirectories}, for information on configuring subdirectories +with the @code{AC_CONFIG_SUBDIRS} macro. + +Giving @samp{--cache-file=/dev/null} disables caching, for debugging +@code{configure}. @file{config.status} only pays attention to the cache +file if it is given the @samp{--recheck} option, which makes it rerun +@code{configure}. If you are anticipating a long debugging period, you +can also disable cache loading and saving for a @code{configure} script +by redefining the cache macros at the start of @file{configure.in}: + +@example +define([AC_CACHE_LOAD], )dnl +define([AC_CACHE_SAVE], )dnl +AC_INIT(@r{whatever}) +@r{ ... rest of configure.in ...} +@end example 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 @@ -3532,7 +3624,7 @@ Definitions of C structures in header files. @item SYS Operating system features. @item TYPE -C builtin or declared types. +C builtin or declared types. @item VAR C variables in libraries. @end table @@ -3778,7 +3870,7 @@ example, @samp{decstation} can be given on the command line instead of @code{config.sub} to canonicalize system type aliases. @node Canonicalizing, System Type Variables, Specifying Names, Manual Configuration -@section Getting the Canonical System Type +@section Getting the Canonical System Type The following macros make the system type available to @code{configure} scripts. They run the shell script @code{config.guess} to determine any @@ -3913,7 +4005,7 @@ The options have one of these forms: @end example For example, @samp{--with-gnu-ld} means work with the GNU linker instead -of some other linker. @samp{--with-x11} means work with X11. +of some other linker. @samp{--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 @@ -3941,8 +4033,9 @@ 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}}; -you may use that variable instead, if you wish. +actually just the value of the shell variable @code{with_@var{package}}, +with any @samp{-} characters changed into @samp{_}. +You may use that variable instead, if you wish. The argument @var{help-string} is a description of the option which looks like this: @@ -4003,9 +4096,10 @@ 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{package}}; -you may use that variable instead, if you wish. -The @var{help-string} argument is like that of @code{AC_ARG_WITH} +actually just the value of the shell variable +@code{enable_@var{package}}, with any @samp{-} 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}). @end defmac diff --git a/src/util/autoconf/autoheader.m4 b/src/util/autoconf/autoheader.m4 index 62427d9e1..eac62579b 100644 --- a/src/util/autoconf/autoheader.m4 +++ b/src/util/autoconf/autoheader.m4 @@ -1,6 +1,6 @@ dnl Driver and redefinitions of some Autoconf macros for autoheader. dnl This file is part of Autoconf. -dnl Copyright (C) 1994 Free Software Foundation, Inc. +dnl Copyright (C) 1994, 1995 Free Software Foundation, Inc. dnl dnl This program is free software; you can redistribute it and/or modify dnl it under the terms of the GNU General Public License as published by @@ -31,10 +31,22 @@ dnl a line. define([AC_CHECK_FUNCS], [# @@@funcs="$funcs $1"@@@ +ifelse([$2], , , [ +# If it was found, we do: +$2 +# If it was not found, we do: +$3 +]) ]) define([AC_CHECK_HEADERS], [# @@@headers="$headers $1"@@@ +ifelse([$2], , , [ +# If it was found, we do: +$2 +# If it was not found, we do: +$3 +]) ]) define([AC_CHECK_HEADERS_DIRENT], [# @@ -72,7 +84,8 @@ define([AC_CHECK_SIZEOF], [# ]) define([AC_CONFIG_HEADER], [# -@@@config_h=$1@@@ +define([AC_CONFIG_H], patsubst($1, [ .*$], []))dnl +@@@config_h=AC_CONFIG_H@@@ ]) define([AC_DEFINE], [# diff --git a/src/util/autoconf/autoheader.sh b/src/util/autoconf/autoheader.sh index 3fbec2c07..abbc98350 100644 --- a/src/util/autoconf/autoheader.sh +++ b/src/util/autoconf/autoheader.sh @@ -182,8 +182,7 @@ fi echo "$types" | tr , \\012 | sort | uniq | while read ctype; do test -z "$ctype" && continue - # Solaris 2.3 tr rejects noncontiguous characters in character classes. - sym="`echo "${ctype}" | tr '[a-z] *' '[A-Z]_P'`" + sym="`echo "${ctype}" | tr 'abcdefghijklmnopqrstuvwxyz *' 'ABCDEFGHIJKLMNOPQRSTUVWXYZ_P'`" echo " /* The number of bytes in a ${ctype}. */ #undef SIZEOF_${sym}" @@ -192,7 +191,7 @@ done # /bin/sh on the Alpha gives `for' a random value if $funcs is empty. if test -n "$funcs"; then for func in `for x in $funcs; do echo $x; done | sort | uniq`; do - sym="`echo ${func} | sed 's/[^a-zA-Z0-9_]/_/g' | tr '[a-z]' '[A-Z]'`" + sym="`echo ${func} | sed 's/[^a-zA-Z0-9_]/_/g' | tr 'abcdefghijklmnopqrstuvwxyz' 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'`" echo " /* Define if you have the ${func} function. */ #undef HAVE_${sym}" @@ -201,7 +200,8 @@ fi if test -n "$headers"; then for header in `for x in $headers; do echo $x; done | sort | uniq`; do - sym="`echo ${header} | sed 's/[^a-zA-Z0-9_]/_/g' | tr '[a-z]' '[A-Z]'`" + + sym="`echo ${header} | sed 's/[^a-zA-Z0-9_]/_/g' | tr 'abcdefghijklmnopqrstuvwxyz' 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'`" echo " /* Define if you have the <${header}> header file. */ #undef HAVE_${sym}" @@ -210,7 +210,7 @@ fi if test -n "$libs"; then for lib in `for x in $libs; do echo $x; done | sort | uniq`; do - sym="`echo ${lib} | sed 's/[^a-zA-Z0-9_]/_/g' | tr '[a-z]' '[A-Z]'`" + sym="`echo ${lib} | sed 's/[^a-zA-Z0-9_]/_/g' | tr 'abcdefghijklmnopqrstuvwxyz' 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'`" echo " /* Define if you have the ${lib} library (-l${lib}). */ #undef HAVE_LIB${sym}" diff --git a/src/util/autoconf/autoreconf.sh b/src/util/autoconf/autoreconf.sh index 0b1826198..538a754c2 100644 --- a/src/util/autoconf/autoreconf.sh +++ b/src/util/autoconf/autoreconf.sh @@ -111,7 +111,7 @@ while read dir; do test ! -f $aclocal && aclocal= if test $force = no && test -f configure && - ls -Llt configure configure.in $aclocal | sed 1q | + ls -lt configure configure.in $aclocal | sed 1q | grep 'configure$' > /dev/null then : @@ -134,7 +134,7 @@ q }' configure.in` if test ! -f $template || grep autoheader $template >/dev/null; then if test $force = no && test -f $template && - ls -Llt $template configure.in $aclocal | sed 1q | + ls -lt $template configure.in $aclocal | sed 1q | grep "$template$" > /dev/null then : diff --git a/src/util/autoconf/config.guess b/src/util/autoconf/config.guess index 19066fbac..d8c24708a 100644 --- a/src/util/autoconf/config.guess +++ b/src/util/autoconf/config.guess @@ -1,6 +1,6 @@ #! /bin/sh # Attempt to guess a canonical system name. -# Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc. +# Copyright (C) 1992, 93, 94, 95, 1996 Free Software Foundation, Inc. # # This file is free software; you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by @@ -14,7 +14,7 @@ # # 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., 675 Mass Ave, Cambridge, MA 02139, USA. +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. # # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a @@ -51,17 +51,19 @@ trap 'rm -f dummy.c dummy.o dummy; exit 1' 1 2 15 # Note: order is significant - the case branches are not exclusive. case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in - alpha:OSF1:V*:*) - # After 1.2, OSF1 uses "V1.3" for uname -r. - echo alpha-dec-osf`echo ${UNAME_RELEASE} | sed -e 's/^V//'` - exit 0 ;; alpha:OSF1:*:*) + # A Vn.n version is a released version. + # A Tn.n version is a released field test version. + # A Xn.n version is an unreleased experimental baselevel. # 1.2 uses "1.2" for uname -r. - echo alpha-dec-osf${UNAME_RELEASE} - exit 0 ;; + echo alpha-dec-osf`echo ${UNAME_RELEASE} | sed -e 's/^[VTX]//'` + exit 0 ;; 21064:Windows_NT:50:3) echo alpha-dec-winnt3.5 exit 0 ;; + Amiga*:UNIX_System_V:4.0:*) + echo m68k-cbm-sysv4 + exit 0;; amiga:NetBSD:*:*) echo m68k-cbm-netbsd${UNAME_RELEASE} exit 0 ;; @@ -114,9 +116,15 @@ case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in VAX*:ULTRIX*:*:*) echo vax-dec-ultrix${UNAME_RELEASE} exit 0 ;; + mips:*:4*:UMIPS) + echo mips-mips-riscos4sysv + exit 0 ;; mips:*:5*:RISCos) echo mips-mips-riscos${UNAME_RELEASE} exit 0 ;; + Night_Hawk:Power_UNIX:*:*) + echo powerpc-harris-powerunix + exit 0 ;; m88k:CX/UX:7*:*) echo m88k-harris-cxux7 exit 0 ;; @@ -127,12 +135,17 @@ case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in echo m88k-motorola-sysv3 exit 0 ;; AViiON:dgux:*:*) + # DG/UX returns AViiON for all architectures + UNAME_PROCESSOR=`/usr/bin/uname -p` + if [ $UNAME_PROCESSOR = mc88100 -o $UNAME_PROCESSOR = mc88100 ] ; then if [ ${TARGET_BINARY_INTERFACE}x = m88kdguxelfx \ -o ${TARGET_BINARY_INTERFACE}x = x ] ; then echo m88k-dg-dgux${UNAME_RELEASE} else echo m88k-dg-dguxbcs${UNAME_RELEASE} fi + else echo i586-dg-dgux${UNAME_RELEASE} + fi exit 0 ;; M88*:DolphinOS:*:*) # DolphinOS (SVR3) echo m88k-dolphin-sysv3 @@ -184,10 +197,8 @@ EOF else IBM_ARCH=powerpc fi - if grep bos410 /usr/include/stdio.h >/dev/null 2>&1; then - IBM_REV=4.1 - elif grep bos411 /usr/include/stdio.h >/dev/null 2>&1; then - IBM_REV=4.1.1 + if [ -x /usr/bin/oslevel ] ; then + IBM_REV=`/usr/bin/oslevel` else IBM_REV=4.${UNAME_RELEASE} fi @@ -218,7 +229,7 @@ EOF case "${UNAME_MACHINE}" in 9000/31? ) HP_ARCH=m68000 ;; 9000/[34]?? ) HP_ARCH=m68k ;; - 9000/7?? | 9000/8?7 ) HP_ARCH=hppa1.1 ;; + 9000/7?? | 9000/8?[679] ) HP_ARCH=hppa1.1 ;; 9000/8?? ) HP_ARCH=hppa1.0 ;; esac HPUX_REV=`echo ${UNAME_RELEASE}|sed -e 's/[^.]*.[0B]*//'` @@ -254,13 +265,13 @@ EOF rm -f dummy.c dummy echo unknown-hitachi-hiuxwe2 exit 0 ;; - 9000/7??:4.3bsd:*:* | 9000/8?7:4.3bsd:*:* ) + 9000/7??:4.3bsd:*:* | 9000/8?[79]:4.3bsd:*:* ) echo hppa1.1-hp-bsd exit 0 ;; 9000/8??:4.3bsd:*:*) echo hppa1.0-hp-bsd exit 0 ;; - hp7??:OSF1:*:* | hp8?7:OSF1:*:* ) + hp7??:OSF1:*:* | hp8?[79]:OSF1:*:* ) echo hppa1.1-hp-osf exit 0 ;; hp8??:OSF1:*:*) @@ -311,19 +322,41 @@ EOF *:NetBSD:*:*) echo ${UNAME_MACHINE}-unknown-netbsd`echo ${UNAME_RELEASE}|sed -e 's/[-_].*/\./'` exit 0 ;; + i*:CYGWIN*:*) + echo i386-unknown-cygwin32 + exit 0 ;; + p*:CYGWIN*:*) + echo powerpcle-unknown-cygwin32 + exit 0 ;; + prep*:SunOS:5.*:*) + echo powerpcle-unknown-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` + exit 0 ;; *:GNU:*:*) echo `echo ${UNAME_MACHINE}|sed -e 's,/.*$,,'`-unknown-gnu`echo ${UNAME_RELEASE}|sed -e 's,/.*$,,'` exit 0 ;; *:Linux:*:*) - # Systems without a BFD linker - if test -d /usr/lib/ldscripts/. ; then - : + # The BFD linker knows what the default object file format is, so + # first see if it will tell us. + ld_help_string=`ld --help 2>&1` + if echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: elf_i[345]86"; then + echo "${UNAME_MACHINE}-unknown-linux" ; exit 0 + elif echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: i[345]86linux"; then + echo "${UNAME_MACHINE}-unknown-linuxaout" ; exit 0 + elif echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: i[345]86coff"; then + echo "${UNAME_MACHINE}-unknown-linuxcoff" ; exit 0 + elif echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: m68kelf"; then + echo "${UNAME_MACHINE}-unknown-linux" ; exit 0 + elif echo "$ld_help_string" | grep >/dev/null 2>&1 "supported emulations: m68klinux"; then + echo "${UNAME_MACHINE}-unknown-linuxaout" ; exit 0 + elif test "${UNAME_MACHINE}" = "alpha" ; then + echo alpha-unknown-linux ; exit 0 else - echo "${UNAME_MACHINE}-unknown-linuxoldld" - exit 0 - fi - # Determine whether the default compiler is a.out or elf - cat >dummy.c <dummy.c </dev/null && ./dummy "${UNAME_MACHINE}" && rm dummy.c dummy && exit 0 - rm -f dummy.c dummy;; + ${CC-cc} dummy.c -o dummy 2>/dev/null && ./dummy "${UNAME_MACHINE}" && rm dummy.c dummy && exit 0 + rm -f dummy.c dummy + fi ;; # ptx 4.0 does uname -s correctly, with DYNIX/ptx in there. earlier versions # are messed up and put the nodename in both sysname and nodename. i[34]86:DYNIX/ptx:4*:*) @@ -357,6 +391,8 @@ EOF elif /bin/uname -X 2>/dev/null >/dev/null ; then UNAME_REL=`(/bin/uname -X|egrep Release|sed -e 's/.*= //')` (/bin/uname -X|egrep i80486 >/dev/null) && UNAME_MACHINE=i486 + (/bin/uname -X|egrep '^Machine.*Pentium' >/dev/null) \ + && UNAME_MACHINE=i586 echo ${UNAME_MACHINE}-unknown-sco$UNAME_REL else echo ${UNAME_MACHINE}-unknown-sysv32 @@ -387,19 +423,19 @@ EOF 3[34]??:*:4.0:* | 3[34]??,*:*:4.0:*) uname -p 2>/dev/null | grep 86 >/dev/null \ && echo i486-ncr-sysv4 && exit 0 ;; - m680[234]0:LynxOS:2.2*:*) + m680[234]0:LynxOS:2.[23]*:*) echo m68k-lynx-lynxos${UNAME_RELEASE} exit 0 ;; mc68030:UNIX_System_V:4.*:*) echo m68k-atari-sysv4 exit 0 ;; - i[34]86:LynxOS:2.2*:*) + i[34]86:LynxOS:2.[23]*:*) echo i386-lynx-lynxos${UNAME_RELEASE} exit 0 ;; - TSUNAMI:LynxOS:2.2*:*) + TSUNAMI:LynxOS:2.[23]*:*) echo sparc-lynx-lynxos${UNAME_RELEASE} exit 0 ;; - rs6000:LynxOS:2.2*:*) + rs6000:LynxOS:2.[23]*:*) echo rs6000-lynx-lynxos${UNAME_RELEASE} exit 0 ;; RM*:SINIX-*:*:*) @@ -413,12 +449,26 @@ EOF echo ns32k-sni-sysv fi exit 0 ;; + mc68*:A/UX:*:*) + echo m68k-apple-aux${UNAME_RELEASE} + exit 0 ;; + R3000:*System_V*:*:*) + if [ -d /usr/nec ]; then + echo mips-nec-sysv${UNAME_RELEASE} + else + echo mips-unknown-sysv${UNAME_RELEASE} + fi + exit 0 ;; esac #echo '(No uname command or uname output not recognized.)' 1>&2 #echo "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" 1>&2 cat >dummy.c < +# include +#endif main () { #if defined (sony) @@ -482,7 +532,18 @@ main () #endif #if defined (_SEQUENT_) - printf ("i386-sequent-ptx\n"); exit (0); + struct utsname un; + + uname(&un); + + if (strncmp(un.version, "V2", 2) == 0) { + printf ("i386-sequent-ptx2\n"); exit (0); + } + if (strncmp(un.version, "V1", 2) == 0) { /* XXX is V1 correct? */ + printf ("i386-sequent-ptx1\n"); exit (0); + } + printf ("i386-sequent-ptx\n"); exit (0); + #endif #if defined (vax) diff --git a/src/util/autoconf/config.sub b/src/util/autoconf/config.sub index 93371be14..e67a800b5 100644 --- a/src/util/autoconf/config.sub +++ b/src/util/autoconf/config.sub @@ -17,7 +17,8 @@ # # 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., 675 Mass Ave, Cambridge, MA 02139, USA. +# Foundation, Inc., 59 Temple Place - Suite 330, +# Boston, MA 02111-1307, USA. # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a diff --git a/src/util/autoconf/configure b/src/util/autoconf/configure index ea89dcbde..65ce229d5 100644 --- a/src/util/autoconf/configure +++ b/src/util/autoconf/configure @@ -1,8 +1,8 @@ #! /bin/sh # Guess values for system-dependent variables and create Makefiles. -# Generated automatically using autoconf version 2.4 -# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. +# Generated automatically using autoconf version 2.10 +# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. # # This configure script is free software; the Free Software Foundation # gives unlimited permission to copy, distribute and modify it. @@ -33,9 +33,22 @@ target=NONE verbose= x_includes=NONE x_libraries=NONE +bindir='${exec_prefix}/bin' +sbindir='${exec_prefix}/sbin' +libexecdir='${exec_prefix}/libexec' +datadir='${prefix}/share' +sysconfdir='${prefix}/etc' +sharedstatedir='${prefix}/com' +localstatedir='${prefix}/var' +libdir='${exec_prefix}/lib' +includedir='${prefix}/include' +oldincludedir='/usr/include' +infodir='${prefix}/info' +mandir='${prefix}/man' # Initialize some other variables. subdirs= +MFLAGS= MAKEFLAGS= ac_prev= for ac_option @@ -57,9 +70,14 @@ do case "$ac_option" in - -build | --build | --buil | --bui | --bu | --b) + -bindir | --bindir | --bindi | --bind | --bin | --bi) + ac_prev=bindir ;; + -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) + bindir="$ac_optarg" ;; + + -build | --build | --buil | --bui | --bu) ac_prev=build ;; - -build=* | --build=* | --buil=* | --bui=* | --bu=* | --b=*) + -build=* | --build=* | --buil=* | --bui=* | --bu=*) build="$ac_optarg" ;; -cache-file | --cache-file | --cache-fil | --cache-fi \ @@ -69,6 +87,12 @@ do | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) cache_file="$ac_optarg" ;; + -datadir | --datadir | --datadi | --datad | --data | --dat | --da) + ac_prev=datadir ;; + -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ + | --da=*) + datadir="$ac_optarg" ;; + -disable-* | --disable-*) ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` # Reject names that are not valid shell variable names. @@ -119,12 +143,29 @@ Configuration: Directory and file names: --prefix=PREFIX install architecture-independent files in PREFIX [$ac_default_prefix] - --exec-prefix=PREFIX install architecture-dependent files in PREFIX + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX [same as prefix] + --bindir=DIR user executables in DIR [EPREFIX/bin] + --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] + --libexecdir=DIR program executables in DIR [EPREFIX/libexec] + --datadir=DIR read-only architecture-independent data in DIR + [PREFIX/share] + --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] + --sharedstatedir=DIR modifiable architecture-independent data in DIR + [PREFIX/com] + --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] + --libdir=DIR object code libraries in DIR [EPREFIX/lib] + --includedir=DIR C header files in DIR [PREFIX/include] + --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] + --infodir=DIR info documentation in DIR [PREFIX/info] + --mandir=DIR man documentation in DIR [PREFIX/man] --srcdir=DIR find the sources in DIR [configure dir or ..] --program-prefix=PREFIX prepend PREFIX to installed program names --program-suffix=SUFFIX append SUFFIX to installed program names - --program-transform-name=PROGRAM run sed PROGRAM on installed program names + --program-transform-name=PROGRAM + run sed PROGRAM on installed program names +EOF + cat << EOF Host type: --build=BUILD configure for building on BUILD [BUILD=HOST] --host=HOST configure for HOST [guessed] @@ -136,8 +177,10 @@ Features and packages: --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) --x-includes=DIR X include files are in DIR --x-libraries=DIR X library files are in DIR ---enable and --with options recognized:$ac_help EOF + if test -n "$ac_help"; then + echo "--enable and --with options recognized:$ac_help" + fi exit 0 ;; -host | --host | --hos | --ho) @@ -145,6 +188,44 @@ EOF -host=* | --host=* | --hos=* | --ho=*) host="$ac_optarg" ;; + -includedir | --includedir | --includedi | --included | --include \ + | --includ | --inclu | --incl | --inc) + ac_prev=includedir ;; + -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ + | --includ=* | --inclu=* | --incl=* | --inc=*) + includedir="$ac_optarg" ;; + + -infodir | --infodir | --infodi | --infod | --info | --inf) + ac_prev=infodir ;; + -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) + infodir="$ac_optarg" ;; + + -libdir | --libdir | --libdi | --libd) + ac_prev=libdir ;; + -libdir=* | --libdir=* | --libdi=* | --libd=*) + libdir="$ac_optarg" ;; + + -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ + | --libexe | --libex | --libe) + ac_prev=libexecdir ;; + -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ + | --libexe=* | --libex=* | --libe=*) + libexecdir="$ac_optarg" ;; + + -localstatedir | --localstatedir | --localstatedi | --localstated \ + | --localstate | --localstat | --localsta | --localst \ + | --locals | --local | --loca | --loc | --lo) + ac_prev=localstatedir ;; + -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ + | --localstate=* | --localstat=* | --localsta=* | --localst=* \ + | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) + localstatedir="$ac_optarg" ;; + + -mandir | --mandir | --mandi | --mand | --man | --ma | --m) + ac_prev=mandir ;; + -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) + mandir="$ac_optarg" ;; + -nfp | --nfp | --nf) # Obsolete; use --without-fp. with_fp=no ;; @@ -157,6 +238,15 @@ EOF | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) no_recursion=yes ;; + -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ + | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ + | --oldin | --oldi | --old | --ol | --o) + ac_prev=oldincludedir ;; + -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ + | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ + | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) + oldincludedir="$ac_optarg" ;; + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) ac_prev=prefix ;; -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) @@ -197,6 +287,23 @@ EOF | -silent | --silent | --silen | --sile | --sil) silent=yes ;; + -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) + ac_prev=sbindir ;; + -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ + | --sbi=* | --sb=*) + sbindir="$ac_optarg" ;; + + -sharedstatedir | --sharedstatedir | --sharedstatedi \ + | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ + | --sharedst | --shareds | --shared | --share | --shar \ + | --sha | --sh) + ac_prev=sharedstatedir ;; + -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ + | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ + | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ + | --sha=* | --sh=*) + sharedstatedir="$ac_optarg" ;; + -site | --site | --sit) ac_prev=site ;; -site=* | --site=* | --sit=*) @@ -207,6 +314,13 @@ EOF -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) srcdir="$ac_optarg" ;; + -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ + | --syscon | --sysco | --sysc | --sys | --sy) + ac_prev=sysconfdir ;; + -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ + | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) + sysconfdir="$ac_optarg" ;; + -target | --target | --targe | --targ | --tar | --ta | --t) ac_prev=target ;; -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) @@ -216,7 +330,7 @@ EOF verbose=yes ;; -version | --version | --versio | --versi | --vers) - echo "configure generated by autoconf version 2.4" + echo "configure generated by autoconf version 2.10" exit 0 ;; -with-* | --with-*) @@ -262,7 +376,7 @@ EOF -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } ;; - *) + *) if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then echo "configure: warning: $ac_option: invalid host type" 1>&2 fi @@ -382,8 +496,8 @@ fi ac_ext=c # CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. ac_cpp='$CPP $CPPFLAGS' -ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5 2>&5' -ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5 2>&5' +ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' +ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. @@ -402,8 +516,10 @@ fi if test "$program_transform_name" = s,x,x,; then program_transform_name= else - # Double any \ or $. - echo 's,\\,\\\\,g; s,\$,$$,g' > conftestsed + # Double any \ or $. echo might interpret backslashes. + cat <<\EOF_SED > conftestsed +s,\\,\\\\,g; s,\$,$$,g +EOF_SED program_transform_name="`echo $program_transform_name|sed -f conftestsed`" rm -f conftestsed fi @@ -581,10 +697,17 @@ else esac done IFS="$ac_save_ifs" - # As a last resort, use the slow shell script. - test -z "$ac_cv_path_install" && ac_cv_path_install="$ac_install_sh" + fi - INSTALL="$ac_cv_path_install" + if test "${ac_cv_path_install+set}" = set; then + INSTALL="$ac_cv_path_install" + else + # As a last resort, use the slow shell script. We don't cache a + # path for INSTALL within a source directory, because that will + # break other packages using the cache if that directory is + # removed, or if the path is relative. + INSTALL="$ac_install_sh" + fi fi echo "$ac_t""$INSTALL" 1>&6 @@ -653,7 +776,7 @@ trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 # Protect against shell expansion while executing Makefile rules. # Protect against Makefile macro expansion. cat > conftest.defs <<\EOF -s%#define \([A-Za-z_][A-Za-z0-9_]*\) \(.*\)%-D\1=\2%g +s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g s%\[%\\&%g s%\]%\\&%g @@ -688,7 +811,7 @@ do echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; -version | --version | --versio | --versi | --vers | --ver | --ve | --v) - echo "$CONFIG_STATUS generated by autoconf version 2.4" + echo "$CONFIG_STATUS generated by autoconf version 2.10" exit 0 ;; -help | --help | --hel | --he | --h) echo "\$ac_cs_usage"; exit 0 ;; @@ -700,10 +823,12 @@ ac_given_srcdir=$srcdir ac_given_INSTALL="$INSTALL" trap 'rm -fr `echo "Makefile testsuite/Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 +EOF +cat >> $CONFIG_STATUS < conftest.subs <<\CEOF +# Protect against being on the right side of a sed subst in config.status. +sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; + s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF $ac_vpsub $extrasub s%@CFLAGS@%$CFLAGS%g @@ -715,6 +840,18 @@ s%@LIBS@%$LIBS%g s%@exec_prefix@%$exec_prefix%g s%@prefix@%$prefix%g s%@program_transform_name@%$program_transform_name%g +s%@bindir@%$bindir%g +s%@sbindir@%$sbindir%g +s%@libexecdir@%$libexecdir%g +s%@datadir@%$datadir%g +s%@sysconfdir@%$sysconfdir%g +s%@sharedstatedir@%$sharedstatedir%g +s%@localstatedir@%$localstatedir%g +s%@libdir@%$libdir%g +s%@includedir@%$includedir%g +s%@oldincludedir@%$oldincludedir%g +s%@infodir@%$infodir%g +s%@mandir@%$mandir%g s%@M4@%$M4%g s%@AWK@%$AWK%g s%@PERL@%$PERL%g diff --git a/src/util/autoconf/install-sh b/src/util/autoconf/install-sh index 89fc9b098..58719246f 100644 --- a/src/util/autoconf/install-sh +++ b/src/util/autoconf/install-sh @@ -29,7 +29,7 @@ stripprog="${STRIPPROG-strip}" rmprog="${RMPROG-rm}" mkdirprog="${MKDIRPROG-mkdir}" -tranformbasename="" +transformbasename="" transform_arg="" instcmd="$mvprog" chmodcmd="$chmodprog 0755" diff --git a/src/util/autoconf/install.texi b/src/util/autoconf/install.texi index 0d9483116..67c284b06 100644 --- a/src/util/autoconf/install.texi +++ b/src/util/autoconf/install.texi @@ -114,6 +114,11 @@ the option @samp{--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 @samp{--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 @samp{--program-prefix=@var{PREFIX}} or diff --git a/src/util/autoconf/make-stds.texi b/src/util/autoconf/make-stds.texi index 887b7ade2..24ffd557e 100644 --- a/src/util/autoconf/make-stds.texi +++ b/src/util/autoconf/make-stds.texi @@ -8,14 +8,26 @@ @cindex conventions for makefiles @cindex standards for makefiles -This chapter describes conventions for writing the Makefiles for GNU programs. +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. @menu -* Makefile Basics:: -* Utilities in Makefiles:: -* Standard Targets:: -* Command Variables:: -* Directory Variables:: +* 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 @end menu @node Makefile Basics @@ -51,7 +63,7 @@ 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. +path is used. The distinction between @file{./} and @file{$(srcdir)/} is important when using the @samp{--srcdir} option to @file{configure}. A rule of @@ -69,9 +81,9 @@ 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 @file{make} automatic variable @samp{$<} will represent the +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 +only in implicit rules.) A Makefile target like @smallexample foo.o : bar.c @@ -97,6 +109,9 @@ foo.1 : foo.man sedscript sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ @end smallexample +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 @@ -108,14 +123,17 @@ The @code{configure} script and the Makefile rules for building and installation should not use any utilities directly except these: @example -cat cmp cp echo egrep expr grep -ln mkdir mv pwd rm rmdir sed test touch +cat cmp cp echo egrep expr false grep +ln mkdir mv pwd rm rmdir sed test touch true @end example 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 @@ -137,226 +155,15 @@ When you use @code{ranlib}, you should make sure nothing bad happens if the system does not have @code{ranlib}. Arrange to ignore an error from that command, and print a message before the command to tell the user that failure of the @code{ranlib} 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. It is ok to use other utilities in Makefile portions (or scripts) -intended only for particular systems where you know those utilities to +intended only for particular systems where you know those utilities exist. -@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. - -@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. - -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 script that edits the Info @file{dir} file to add or update the -menu entry for the given Info file; it will be 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 -$(infodir)/foo.info: foo.info -# 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 $@@; \ -# 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 --infodir=$(infodir) $$d/foo.info; \ - else true; fi -@end smallexample - -@item uninstall -Delete all the installed files that the @samp{install} target would -create (but not the noninstalled files such as @samp{make all} would -create). - -This rule should not modify the directories where compilation is done, -only the directories where files are installed. - -@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 @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} 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 -@code{maintainer-clean} should start with these two: - -@example -@@echo "This command is intended for maintainers to use;" -@@echo "it deletes files that may require special tools to rebuild." -@end example - -@item TAGS -Update a tags table for this program. - -@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. - -@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. Alternatively, write just the dependencies, and allow GNU -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. - -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. -@xref{Releases, , Making Releases, standards, GNU Coding Standards}. - -@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; 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 - -This rule should not modify the directories where compilation is done. -It should do nothing but create installation directories. -@end table - @node Command Variables @section Variables for Specifying Commands @@ -440,14 +247,16 @@ and nothing should be directly installed into these two directories. @table @samp @item 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} +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@@}.) @item 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), @@ -461,18 +270,21 @@ Executable programs are installed in one of the following directories. 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 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 @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 @@ -491,18 +303,20 @@ 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 of object +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 +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}. As a special exception, see @file{$(infodir)} +@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 @@ -512,12 +326,13 @@ 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@@}.) @c rewritten to avoid overfull hbox --tower Do not install executables @c here in this directory (they probably -belong in @file{$(libexecdir)} or @file{$(sbindir))}. Also do not +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)}. @@ -526,26 +341,30 @@ excluded). Those probably belong in @file{$(localstatedir)}. 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)} +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 belong in @file{$(libexecdir)} +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 includedir @c rewritten to avoid overfull hbox --roland @@ -553,6 +372,7 @@ 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 @file{/usr/local/include}. So installing the header files this way is @@ -565,6 +385,7 @@ 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 @@ -578,26 +399,25 @@ file in the @code{oldincludedir} directory if either (1) there is no package. To tell whether @file{foo.h} came from the Foo package, put a magic -string in the file---part of a comment---and grep for that string. +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 directory for installing the man pages (if any) for this package. -It should include the suffix for the proper section of the -manual---usually @samp{1} for a utility. It will normally be -@file{/usr/local/man/man1}, but you should write it as -@file{$(prefix)/man/man1}. +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. +The directory for installing section 1 man pages. Write it as +@file{$(mandir)/man1}. @item man2dir -The directory for installing section 2 man pages. +The directory for installing section 2 man pages. Write it as +@file{$(mandir)/man2} @item @dots{} -Use these names instead of @samp{mandir} if the package needs to install man -pages in more than one section of the manual. @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 @@ -623,6 +443,7 @@ And finally, you should set the following variable: @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: @@ -654,3 +475,248 @@ 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 +$(infodir)/foo.info: foo.info +# 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 $@@; \ +# 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=$(infodir)/dir \ + $(infodir)/foo.info; \ + else true; fi +@end smallexample + +@item uninstall +Delete all the installed files that the @samp{install} target would +create (but not the noninstalled files such as @samp{make all} would +create). + +This rule should not modify the directories where compilation is done, +only the directories where files are installed. + +@item install-strip +Like @code{install}, but strip the executable files while installing +them. The definition of this target can be very simple: + +@smallexample +install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install +@end smallexample + +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. + +@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 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 + +This rule should not modify the directories where compilation is done. +It should do nothing but create installation directories. +@end table diff --git a/src/util/autoconf/mkinstalldirs b/src/util/autoconf/mkinstalldirs index 0801ec2c9..d0fd194fd 100644 --- a/src/util/autoconf/mkinstalldirs +++ b/src/util/autoconf/mkinstalldirs @@ -2,17 +2,20 @@ # mkinstalldirs --- make directory hierarchy # Author: Noah Friedman # Created: 1993-05-16 -# Last modified: 1994-03-25 # Public domain +# $Id$ + errstatus=0 -for file in ${1+"$@"} ; do +for file +do set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` shift pathcomp= - for d in ${1+"$@"} ; do + for d + do pathcomp="$pathcomp$d" case "$pathcomp" in -* ) pathcomp=./$pathcomp ;; @@ -20,7 +23,12 @@ for file in ${1+"$@"} ; do if test ! -d "$pathcomp"; then echo "mkdir $pathcomp" 1>&2 - mkdir "$pathcomp" || errstatus=$? + + mkdir "$pathcomp" || lasterr=$? + + if test ! -d "$pathcomp"; then + errstatus=$lasterr + fi fi pathcomp="$pathcomp/" diff --git a/src/util/autoconf/standards.info b/src/util/autoconf/standards.info index 6252e51ae..c673f9261 100644 --- a/src/util/autoconf/standards.info +++ b/src/util/autoconf/standards.info @@ -1,12 +1,12 @@ -This is Info file standards.info, produced by Makeinfo-1.55 from the -input file standards.texi. +This is Info file standards.info, produced by Makeinfo-1.63 from the +input file ./standards.texi. START-INFO-DIR-ENTRY * Standards: (standards). GNU coding standards. END-INFO-DIR-ENTRY - GNU Coding Standards Copyright (C) 1992, 1993, 1994 Free Software -Foundation, Inc. + GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 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 @@ -23,44 +23,3279 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  -Indirect: -standards.info-1: 954 -standards.info-2: 48207 -standards.info-3: 95193 +File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir) + +Version +******* + + Last updated 27 February 1996. + +* Menu: + +* Preface:: About the GNU Coding Standards +* Intellectual Property:: 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 + + +File: standards.info, Node: Preface, Next: Intellectual Property, 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. + + Corrections or suggestions regarding this document should be sent to +`gnu@prep.ai.mit.edu'. 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. + + This release of the GNU Coding Standards was last updated 27 +February 1996. + + +File: standards.info, Node: Intellectual Property, Next: Design Advice, Prev: Preface, Up: Top + +Keeping Free Software Free +************************** + + This node discusses how you can make sure that GNU software remains +unencumbered. + +* Menu: + +* Reading Non-Free Code:: Referring to Proprietary Programs +* Contributions:: Accepting Contributions + + +File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Intellectual Property + +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, Prev: Reading Non-Free Code, Up: Intellectual Property + +Accepting Contributions +======================= + + If someone else sends you a piece of code to add to the program you +are working on, we need legal papers to use it--the same sort of legal +papers we will need to get from you. *Each* significant contributor 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, 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 it. + + 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 you write a different solution to the +problem, you don't need to get papers. + + We know this is frustrating; 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! + + 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. + + +File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Intellectual Property, Up: Top + +General Program Design +********************** + + This node discusses some of the issues you should take into account +when designing your program. + +* Menu: + +* Compatibility:: Compatibility with other implementations +* Using Extensions:: Using non-standard features +* ANSI C:: Using ANSI C features +* Source Language:: Using languages other than C + + +File: standards.info, Node: Compatibility, Next: Using Extensions, 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 ANSI C if ANSI 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. + + ANSI 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. Try to redesign its interface. + + 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 not in Berkeley Unix are welcome. +Additional programs with no counterpart in Unix may be useful, but our +first priority is usually to duplicate what Unix already has. + + +File: standards.info, Node: Using Extensions, Next: ANSI 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. Such programs would +be broken by use of GNU extensions. + + 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 no good. + + +File: standards.info, Node: ANSI C, Next: Source Language, Prev: Using Extensions, Up: Design Advice + +ANSI C and pre-ANSI C +===================== + + Do not ever use the "trigraph" feature of ANSI C. + + ANSI C is widespread enough now that it is ok to write new programs +that use ANSI C features (and therefore will not work in non-ANSI +compilers). And if a program is already written in ANSI C, there's no +need to convert it to support non-ANSI compilers. + + However, it is easy to support non-ANSI compilers in most programs, +so you might still consider doing so when you write a program. Instead +of writing function definitions in ANSI prototype form, + + int + foo (int x, int y) + ... + +write the definition in pre-ANSI 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 ANSI C prototypes in all the files where the function is +called. And once you have it, you lose nothing by writing the function +definition in the pre-ANSI style. + + If you don't know non-ANSI C, there's no need to learn it; just +write in ANSI C. + + +File: standards.info, Node: Source Language, Prev: ANSI C, Up: Design Advice + +Using Languages Other Than C +============================ + + Using a language other than C 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. So +please write in C. + + There are three exceptions for this rule: + + * It is okay to use a special language if the same program contains + an interpreter for that language. + + For example, if your program links with GUILE, it is ok to write + part of the program in Scheme or another language supported by + GUILE. + + * It is okay to use another language in a tool specifically intended + for use with that language. + + This is okay because the only people who want to build the tool + will be those who have installed the other language anyway. + + * If an application is not of extremely widespread interest, then + perhaps it's not important if the application is inconvenient to + install. + + +File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top + +Program Behavior for All Programs +********************************* + + This node describes how to write 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 for command line interfaces +* Memory Usage:: When and how to care about memory needs + + +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 printers that can't handle those +characters. + + 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 will be supported compatibly by GNU. + + By default, the GNU system will provide the signal handling +functions of BSD and of POSIX. So GNU software should be written to use +these. + + 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'. + + +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 `_'. They should also contain 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 + + 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. + + 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: Memory Usage, Prev: Errors, Up: Program Behavior + +Standards for Command Line Interfaces +===================================== + + 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. + + 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. + + 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. The table appears below. + + If you use names not already in the table, please send +`gnu@prep.ai.mit.edu' a list of them, with their meanings, so we can +update the 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'). Even if you allow an output file name as an +ordinary argument for compatibility, try to provide a suitable option +as well. This will lead to more consistency among GNU utilities, so +that there are fewer idiosyncracies for users to remember. + + Programs should support an option `--version' which prints the +program's version number on standard output and exits successfully, and +an option `--help' which prints option usage information on standard +output and exits successfully. These options should inhibit the normal +function of the command; they should do nothing except print the +requested information. + + Here is the table of long options used by GNU programs. + +`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'. + +`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'. + +`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'. + +`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'. + +`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. + +`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'. + +`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@prep.ai.mit.edu'. + +`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-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'. + +`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'. + +`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'. + +`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'. + +`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, Prev: User Interfaces, Up: Program Behavior + +Memory Usage +============ + + If it 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: 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 + + +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 ANSI C, format the definition like this: + + static char * + concat (char *s1, char *s2) + { + ... + } + + In ANSI 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) + ... + + For the body of the function, we prefer code formatted 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, +but Emacs would mess it up: + + 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 adding a set of parentheses solves the problem: + + 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 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 */ + +but, by contrast, write the comments this way for a `#ifndef': + + #ifndef foo + ... + #else /* foo */ + ... + #endif /* foo */ + + +File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C + +Clean Use of C Constructs +========================= + + Please explicitly declare all arguments to functions. Don't omit +them just because they are `int's. + + 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. + + +File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C + +Naming Variables and Functions +============================== + + 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. + + Use file names of 14 characters or less, to avoid creating gratuitous +problems on older System V systems. You can use the program `doschk' +to test for this. `doschk' also tests for potential name conflicts if +the files were loaded onto an MS-DOS file system--something you may or +may not care about. + + +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. The +amount and kinds of variation among GNU systems on different CPUs will +be comparable to the variation among Linux-based GNU systems or among +BSD systems today. So the kinds of portability that are absolutely +necessary are quite limited. + + But many users do run GNU software on non-GNU Unix or Unix-like +systems. So supporting a variety of Unix-like systems is desirable, +although not paramount. + + 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 usually so much work that it +is better if you don't. + + The planned GNU kernel is not finished yet, but you can tell which +facilities it will provide by looking at the GNU C Library Manual. The +GNU kernel is based on Mach, so the features of Mach will also be +available. However, if you use Mach features, you'll probably have +trouble debugging your program today. + + +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. + + 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 an integers. On +most machines, there's no difference anyway. As for the few machines +where there is a difference, all of them support ANSI C, so you can use +prototypes (conditionalized to be active only in ANSI 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; + int a1, a2, a3; + { + fprintf (stderr, "error: "); + fprintf (stderr, s, a1, a2, a3); + } + +In practice, this works on all machines, and it is much simpler than any +"correct" alternative. + + However, avoid casting pointers to integers unless you really need +to. These assumptions really 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--it is ok to do so, but +you'll have to make explicit provisions to handle different word sizes. + + +File: standards.info, Node: System Functions, Prev: CPU Portability, Up: Writing C + +Calling System Functions +======================== + + C implementations differ substantially. ANSI C reduces but does not +eliminate the incompatibilities; meanwhile, many users wish to compile +GNU software with pre-ANSI compilers. 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 value of `sprintf'. It returns the number of + characters written on some systems, but not on all systems. + + * 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 an ANSI 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 ANSI + 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 ANSI 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: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top + +Documenting Programs +******************** + +* Menu: + +* GNU Manuals:: Writing proper manuals. +* Manual Structure Details:: Specific structure conventions. +* 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: Manual Structure Details, Up: Documentation + +GNU Manuals +=========== + + The preferred way to document part of the GNU system is to write a +manual in the Texinfo formatting language. See the Texinfo manual, +either the hardcopy, or the on-line version available through `info' or +the Emacs Info subsystem (`C-h i'). + + The manual should 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 goals that a user will have in +mind, and explain how to accomplish them. + + 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. + + 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. + + Don't use Unix man pages as a model for how to write GNU +documentation; they are a bad example to follow. + + 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 file names. + + +File: standards.info, Node: Manual Structure Details, Next: NEWS File, Prev: GNU Manuals, Up: Documentation + +Manual Structure Details +======================== + + The title page of the manual should state the version of the program +to which the manual applies. 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. + + The manual should have a node named `PROGRAM Invocation' or +`Invoking PROGRAM', where PROGRAM stands for the name of the program +being described, as you would type it in the shell to run the 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. + + There will be automatic features for specifying a program name and +quickly reading just this part of its manual. + + If one manual describes several programs, it should have such a node +for each program described. + + +File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Manual Structure Details, 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 for each directory, describing the changes made to +source files in that directory. 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 +eliminate conceptual inconsistencies between different parts of a +program; they can give you a history of how the conflicting concepts +arose. + + Use the Emacs command `M-x add-change-log-entry' to start a new +entry in the change log. 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. + + Separate unrelated 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. + + Here are some examples: + + * 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 the entry. + + There's no need to describe the full purpose of the changes or how +they work together. It is better to put such explanations in comments +in the code. That's why just "New function" is enough; there is a +comment with the function in the source to explain what it does. + + However, sometimes it is useful to write one line to describe the +overall purpose of a large batch of changes. + + 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. + + When you change the calling sequence of a function in a simple +fashion, and you change all the callers of the function, there is no +need to make individual entries for all the callers. Just write in the +entry for the function being called, "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. Write just, +"Doc fix." There's no need to keep a change log 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. + + +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, 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 `x', `x-toolkit', `gnu-as' (or + `gas'), `gnu-ld', `gnu-libc', and `gdb'. + + 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. + +`--nfp' + The target machine has no floating point processor. + +`--gas' + The target machine assembler is GAS, the GNU assembler. This is + obsolete; users should use `--with-gnu-as' instead. + +`--x' + The target machine has the X Window System installed. This is + obsolete; users should use `--with-x' instead. + + 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. + + The way to build a cross-compiler, cross-assembler, or what have +you, is to specify the option `--host=HOSTTYPE' when running +`configure'. This specifies the host system without changing the type +of target system. The syntax for HOSTTYPE is the same as described +above. + + 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=HOSTTYPE' for specifying the +configuration on which you will compile them, in case that is different +from the host. + + Programs for which cross-operation is not meaningful need not accept +the `--host' option, because configuring an entire operating system for +cross-operation is not a meaningful thing. + + 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. + +* 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 + + +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 `./' and `$(srcdir)/' is important when +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 current directory is not the source directory, +because `foo.man' and `sedscript' are not in the current 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 > $@ + + 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 echo egrep expr false grep + ln mkdir mv pwd rm rmdir sed test touch true + + 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 lex + make makeinfo ranlib texi2dvi yacc + + Use the following `make' variables: + + $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX) + $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) + + When you use `ranlib', you should make sure nothing bad happens if +the system does not have `ranlib'. Arrange to ignore an error from +that command, and print a message before the command to tell the user +that failure of the `ranlib' 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. + + 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 name `CFLAGS' is an exception to this +rule, but we keep it because it is 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. + + 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 each of these should be +`$(INSTALL)'.) 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 + +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, 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@'.) + +`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. + + 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 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@'.) + +`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 + `/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, 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: + + $(infodir)/foo.info: foo.info + # 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 $@; \ + # 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=$(infodir)/dir \ + $(infodir)/foo.info; \ + else true; fi + +`uninstall' + Delete all the installed files that the `install' target would + create (but not the noninstalled files such as `make all' would + create). + + This rule should not modify the directories where compilation is + done, only the directories where files are installed. + +`install-strip' + Like `install', but strip the executable files while installing + them. The definition of this target can be very simple: + + install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install + + 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. + +`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 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) + + 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: Releases, Prev: Makefile Conventions, Up: Managing Releases + +Making Releases +=============== + + Package the distribution of Foo version 69.96 in a gzipped tar file +named `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. + + 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. + +  Tag Table: -(Indirect) -Node: Top954 -Node: Preface2091 -Node: Reading Non-Free Code3127 -Node: Contributions4857 -Node: Change Logs6455 -Node: Compatibility10181 -Node: Makefile Conventions11820 -Node: Makefile Basics12177 -Node: Utilities in Makefiles14521 -Node: Standard Targets16218 -Node: Command Variables24726 -Node: Directory Variables27556 -Node: Configuration36859 -Node: Source Language43787 -Node: Formatting44917 -Node: Comments48207 -Node: Syntactic Conventions50994 -Node: Names53886 -Node: Using Extensions55623 -Node: System Functions57364 -Node: Semantics62167 -Node: Errors65800 -Node: Libraries67004 -Node: Portability68228 -Node: User Interfaces71515 -Node: Documentation88583 -Node: GNU Manuals89090 -Node: Manual Structure Details91101 -Node: NEWS File92506 -Node: Man Pages93185 -Node: Reading other Manuals94409 -Node: Releases95193 +Node: Top968 +Node: Preface1482 +Node: Intellectual Property2525 +Node: Reading Non-Free Code2881 +Node: Contributions4613 +Node: Design Advice6211 +Node: Compatibility6694 +Node: Using Extensions8338 +Node: ANSI C9840 +Node: Source Language11076 +Node: Program Behavior12210 +Node: Semantics12802 +Node: Libraries16556 +Node: Errors17791 +Node: User Interfaces19014 +Node: Memory Usage36015 +Node: Writing C37012 +Node: Formatting37654 +Node: Comments40926 +Node: Syntactic Conventions43719 +Node: Names46617 +Node: System Portability47929 +Node: CPU Portability49705 +Node: System Functions51812 +Node: Documentation56684 +Node: GNU Manuals57228 +Node: Manual Structure Details59270 +Node: NEWS File60675 +Node: Change Logs61356 +Node: Man Pages65109 +Node: Reading other Manuals66728 +Node: Managing Releases67512 +Node: Configuration68218 +Node: Makefile Conventions75158 +Node: Makefile Basics75682 +Node: Utilities in Makefiles78153 +Node: Command Variables80027 +Node: Directory Variables82863 +Node: Standard Targets92968 +Node: Releases102716  End Tag Table diff --git a/src/util/autoconf/standards.texi b/src/util/autoconf/standards.texi index 17e312f0c..7bbe70f14 100644 --- a/src/util/autoconf/standards.texi +++ b/src/util/autoconf/standards.texi @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES! -@set lastupdate 16 May 1995 +@set lastupdate 27 February 1996 @c %**end of header @ifinfo @@ -14,11 +14,21 @@ END-INFO-DIR-ENTRY @end format @end ifinfo +@c @setchapternewpage odd @setchapternewpage off +@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 Free Software Foundation, Inc. +Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -49,7 +59,7 @@ by the Free Software Foundation. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. +Copyright @copyright{} 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -75,26 +85,12 @@ Last updated @value{lastupdate}. @menu * Preface:: About the GNU Coding Standards -* Reading Non-Free Code:: Referring to Proprietary Programs -* Contributions:: Accepting Contributions -* Change Logs:: Recording Changes -* Compatibility:: Compatibility with Other Implementations -* Makefile Conventions:: Makefile Conventions -* Configuration:: How Configuration Should Work -* Source Language:: Using Languages Other Than C -* Formatting:: Formatting Your Source Code -* Comments:: Commenting Your Work -* Syntactic Conventions:: Clean Use of C Constructs -* Names:: Naming Variables, Functions and Files -* Using Extensions:: Using Non-standard Features -* System Functions:: Portability and ``standard'' library functions -* Semantics:: Program Behavior for All Programs -* Errors:: Formatting Error Messages -* Libraries:: Library Behavior -* Portability:: Portability As It Applies to GNU -* User Interfaces:: Standards for Command Line Interfaces +* Intellectual Property:: 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 -* Releases:: Making Releases +* Managing Releases:: The Release Process @end menu @node Preface @@ -103,7 +99,7 @@ Last updated @value{lastupdate}. 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 write portable, robust and reliable programs. It focuses on +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. @@ -117,8 +113,19 @@ you don't have those files, please mail your suggestion anyway. This release of the GNU Coding Standards was last updated @value{lastupdate}. +@node Intellectual Property +@chapter Keeping Free Software Free + +This @value{CHAPTER} discusses how you can make sure that GNU software +remains unencumbered. + +@menu +* Reading Non-Free Code:: Referring to Proprietary Programs +* Contributions:: Accepting Contributions +@end menu + @node Reading Non-Free Code -@chapter Referring to Proprietary Programs +@section 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.) @@ -152,7 +159,7 @@ to free memory, or use a new GNU facility such as obstacks. @node Contributions -@chapter Accepting Contributions +@section Accepting Contributions If someone else sends you a piece of code to add to the program you are working on, we need legal papers to use it---the same sort of legal @@ -167,7 +174,7 @@ 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 change, we +you receive diffs to fix a bug, and they make significant changes, we need legal papers for it. You don't need papers for changes of a few lines here or there, since @@ -176,7 +183,7 @@ papers if all you get from the suggestion is some ideas, not actual code which you use. For example, if you write a different solution to the problem, you don't need to get papers. -I know this is frustrating; it's frustrating for us as well. But if +We know this is frustrating; 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! @@ -185,102 +192,37 @@ 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. -@node Change Logs -@chapter Change Logs - -Keep a change log for each directory, describing the changes made to -source files in that directory. 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 eliminate conceptual inconsistencies between different parts -of a program; they can give you a history of how the conflicting -concepts arose. - -Use the Emacs command @kbd{M-x add-change-log-entry} to start a new -entry in the -change log. 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. - -Separate unrelated 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. - -Here are some examples: - -@example -* 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 them; 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 the -entry. - -There's no need to describe the full purpose of the changes or how they -work together. It is better to put such explanations in comments in the -code. That's why just ``New function'' is enough; there is a comment -with the function in the source to explain what it does. - -However, sometimes it is useful to write one line to describe the -overall purpose of a large batch of changes. - -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. - -When you change the calling sequence of a function in a simple -fashion, and you change all the callers of the function, there is no -need to make individual entries for all the callers. Just write in -the entry for the function being called, ``All callers changed.'' +@node Design Advice +@chapter General Program Design -When you change just comments or doc strings, it is enough to write an -entry for the file, without mentioning the functions. Write just, -``Doc fix.'' There's no need to keep a change log 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. +This @value{CHAPTER} discusses some of the issues you should take into +account when designing your program. +@menu +* Compatibility:: Compatibility with other implementations +* Using Extensions:: Using non-standard features +* ANSI C:: Using ANSI C features +* Source Language:: Using languages other than C +@end menu @node Compatibility -@chapter Compatibility with Other Implementations +@section Compatibility with Other Implementations -With certain exceptions, utility programs and libraries for GNU should -be upward compatible with those in Berkeley Unix, and upward compatible -with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward -compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior. +With occasional exceptions, utility programs and libraries for GNU +should be upward compatible with those in Berkeley Unix, and upward +compatible with @sc{ansi} C if @sc{ansi} 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. -@sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions. Feel -free to make the extensions anyway, and include a @samp{--ansi} 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. Try to redesign its -interface. +@sc{ansi} 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. Try to +redesign its interface. Many GNU programs suppress extensions that conflict with POSIX if the environment variable @code{POSIXLY_CORRECT} is defined (even if it is @@ -290,2060 +232,2017 @@ 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.) +@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 not in Berkeley Unix are welcome. Additional programs with no counterpart in Unix may be useful, but our first priority is usually to duplicate what Unix already has. -@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. -@include make-stds.texi +@node Using Extensions +@section Using Non-standard Features -@node Configuration -@chapter How Configuration Should Work +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. -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. +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. -The @code{configure} script must record the configuration options so -that they affect compilation. +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. -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. +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. -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, 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. +An exception to this rule are the large, established programs (such as +Emacs) which run on a great variety of systems. Such programs would +be broken by use of GNU extensions. -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}. +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 no good. -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. +@node ANSI C +@section @sc{ansi} C and pre-@sc{ansi} C -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. +Do not ever use the ``trigraph'' feature of @sc{ansi} C. -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. +@sc{ansi} C is widespread enough now that it is ok to write new programs +that use @sc{ansi} C features (and therefore will not work in +non-@sc{ansi} compilers). And if a program is already written in +@sc{ansi} C, there's no need to convert it to support non-@sc{ansi} +compilers. -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. +However, it is easy to support non-@sc{ansi} compilers in most programs, +so you might still consider doing so when you write a program. Instead +of writing function definitions in @sc{ansi} prototype form, -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. +@example +int +foo (int x, int y) +@dots{} +@end example -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: +@noindent +write the definition in pre-@sc{ansi} style like this, @example -@var{cpu}-@var{company}-@var{system} +int +foo (x, y) + int x, y; +@dots{} @end example -For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. +@noindent +and use a separate declaration to specify the argument prototype: -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. +@example +int foo (int, int); +@end example -There is a shell script called @file{config.sub} that you can use -as a subroutine to validate system types and canonicalize aliases. +You need such a declaration anyway, in a header file, to get the benefit +of @sc{ansi} C prototypes in all the files where the function is called. +And once you have it, you lose nothing by writing the function +definition in the pre-@sc{ansi} style. -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: +If you don't know non-@sc{ansi} C, there's no need to learn it; just +write in @sc{ansi} C. -@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. +@node Source Language +@section Using Languages Other Than C -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. +Using a language other than C 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. So please write in C. -@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}. +There are three exceptions for this rule: -@c Giving an optional @var{parameter} of -@c @samp{no} should omit @var{package}, if it is used by default. +@itemize @bullet +@item +It is okay to use a special language if the same program contains an +interpreter for that language. -Possible values of @var{package} include @samp{x}, @samp{x-toolkit}, -@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and -@samp{gdb}. +For example, if your program links with GUILE, it is ok to write part of +the program in Scheme or another language supported by GUILE. -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. +@item +It is okay to use another language in a tool specifically intended for +use with that language. -@item --nfp -The target machine has no floating point processor. +This is okay because the only people who want to build the tool will be +those who have installed the other language anyway. -@item --gas -The target machine assembler is GAS, the GNU assembler. -This is obsolete; users should use @samp{--with-gnu-as} instead. +@item +If an application is not of extremely widespread interest, then perhaps +it's not important if the application is inconvenient to install. +@end itemize -@item --x -The target machine has the X Window System installed. -This is obsolete; users should use @samp{--with-x} instead. -@end table +@node Program Behavior +@chapter Program Behavior for All Programs -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. +This @value{CHAPTER} describes how to write robust software. It also +describes general standards for error messages, the command line interface, +and how libraries should behave. -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 compilation 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. +@menu +* Semantics:: Writing robust programs +* Libraries:: Library behavior +* Errors:: Formatting error messages +* User Interfaces:: Standards for command line interfaces +* Memory Usage:: When and how to care about memory needs +@end menu -The way to build a cross-compiler, cross-assembler, or what have you, is -to specify the option @samp{--host=@var{hosttype}} when running -@code{configure}. This specifies the host system without changing the -type of target system. The syntax for @var{hosttype} is the same as -described above. +@node Semantics +@section Writing Robust Programs -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{hosttype}} for specifying the -configuration on which you will compile them, in case that is different -from the host. +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. -Programs for which cross-operation is not meaningful need not accept the -@samp{--host} option, because configuring an entire operating system for -cross-operation is not a meaningful thing. +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 printers that can't handle those characters. -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. +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. -@node Source Language -@chapter Using Languages Other Than C +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. -Using a language other than C 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. So please write in C. +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}. -There are three exceptions for this rule: +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}. -@itemize @bullet -@item -It is okay to use a special language if the same program contains an -interpreter for that language. +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. -Thus, it is not a problem that GNU Emacs contains code written in Emacs -Lisp, because it comes with a Lisp interpreter. +Use @code{getopt_long} to decode arguments, unless the argument syntax +makes this unreasonable. -@item -It is okay to use another language in a tool specifically intended for -use with that language. +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? -This is okay because the only people who want to build the tool will be -those who have installed the other language anyway. +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 will be supported compatibly by GNU. -@item -If an application is not of extremely widespread interest, then perhaps -it's not important if the application is inconvenient to install. -@end itemize +By default, the GNU system will provide the signal handling functions of +@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use +these. -@node Formatting -@chapter Formatting Your Source Code +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. -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. +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. -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: +If you make temporary files, check the @code{TMPDIR} environment +variable; if that variable is defined, use the specified directory +instead of @file{/tmp}. -@example -static char * -concat (s1, s2) /* Name starts in column zero here */ - char *s1, *s2; -@{ /* Open brace in column zero here */ - @dots{} -@} -@end example +@node Libraries +@section Library Behavior -@noindent -or, if you want to use @sc{ANSI} C, format the definition like this: +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. -@example -static char * -concat (char *s1, char *s2) -@{ - @dots{} -@} -@end example +Here are certain name conventions for libraries, to avoid name +conflicts. -In @sc{ANSI} C, if the arguments don't fit nicely on one line, -split it like this: +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. -@example -int -lots_of_args (int an_integer, long a_long, short a_short, - double a_double, float a_float) -@dots{} -@end example +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. -For the body of the function, we prefer code formatted like this: +External symbols that are not documented entry points for the user +should have names beginning with @samp{_}. They should also contain +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. -@example -if (x < foo (y, z)) - haha = bar[4] + 5; -else - @{ - while (z) - @{ - haha += foo (z, z); - z--; - @} - return ++x + bar (); - @} -@end example +Static functions and variables can be used as you like and need not +fit any naming convention. -We find it easier to read a program when it has spaces before the -open-parentheses and after the commas. Especially after the commas. +@node Errors +@section Formatting Error Messages -When you split an expression into multiple lines, split it -before an operator, not after one. Here is the right way: +Error messages from compilers should look like this: @example -if (foo_this_is_long && bar > win (x, y, z) - && remaining_condition) +@var{source-file-name}:@var{lineno}: @var{message} @end example -Try to avoid having two operators of different precedence at the same -level of indentation. For example, don't write this: +Error messages from other noninteractive programs should look like this: @example -mode = (inmode[j] == VOIDmode - || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) - ? outmode[j] : inmode[j]); +@var{program}:@var{source-file-name}:@var{lineno}: @var{message} @end example -Instead, use extra parentheses so that the indentation shows the nesting: +@noindent +when there is an appropriate source file, or like this: @example -mode = ((inmode[j] == VOIDmode - || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) - ? outmode[j] : inmode[j]); +@var{program}: @var{message} @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, -but Emacs would mess it up: +@noindent +when there is no relevant source file. -@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 +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.) -But adding a set of parentheses solves the problem: +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. -@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 +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. -Format do-while statements like this: +@node User Interfaces +@section Standards for Command Line Interfaces -@example -do - @{ - a = foo (a); - @} -while (a > 0); -@end example +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. -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. +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. -@node Comments -@chapter Commenting Your Work +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. -Every program should start with a comment saying briefly what it is for. -Example: @samp{fmt - filter for simple filling of text}. +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. -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 - -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 -#ifdef foo - @dots{} -#else /* not foo */ - @dots{} -#endif /* not foo */ -@end example - -@noindent -but, by contrast, write the comments this way for a @samp{#ifndef}: +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. -@example -#ifndef foo - @dots{} -#else /* foo */ - @dots{} -#endif /* foo */ -@end example +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. The table appears below. -@node Syntactic Conventions -@chapter Clean Use of C Constructs +If you use names not already in the table, please send +@samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we +can update the table. -Please explicitly declare all arguments to functions. -Don't omit them just because they are @code{int}s. +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}). Even if you allow an output file name +as an ordinary argument for compatibility, try to provide a suitable +option as well. This will lead to more consistency among GNU +utilities, so that there are fewer idiosyncracies for users to +remember. -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. +Programs should support an option @samp{--version} which prints the +program's version number on standard output and exits successfully, and +an option @samp{--help} which prints option usage information on +standard output and exits successfully. These options should inhibit +the normal function of the command; they should do nothing except print +the requested information. -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. +@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 -Don't use local variables or parameters that shadow global identifiers. +Here is the table of long options used by GNU programs. -Don't declare multiple variables in one declaration that spans lines. -Start a new declaration on each line, instead. For example, instead -of this: +@table @samp -@example -int foo, - bar; -@end example +@item after-date +@samp{-N} in @code{tar}. -@noindent -write either this: +@item all +@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, +and @code{unexpand}. -@example -int foo, bar; -@end example +@item all-text +@samp{-a} in @code{diff}. -@noindent -or this: +@item almost-all +@samp{-A} in @code{ls}. -@example -int foo; -int bar; -@end example +@item append +@samp{-a} in @code{etags}, @code{tee}, @code{time}; +@samp{-r} in @code{tar}. -@noindent -(If they are global variables, each should have a comment preceding it -anyway.) +@item archive +@samp{-a} in @code{cp}. -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: +@item archive-name +@samp{-n} in @code{shar}. -@example -if (foo) - if (bar) - win (); - else - lose (); -@end example +@item arglength +@samp{-l} in @code{m4}. -@noindent -always like this: +@item ascii +@samp{-a} in @code{diff}. -@example -if (foo) - @{ - if (bar) - win (); - else - lose (); - @} -@end example +@item assign +@samp{-v} in @code{gawk}. -If you have an @code{if} statement nested inside of an @code{else} -statement, either write @code{else if} on one line, like this, +@item assume-new +@samp{-W} in Make. -@example -if (foo) - @dots{} -else if (bar) - @dots{} -@end example +@item assume-old +@samp{-o} in Make. -@noindent -with its @code{then}-part indented like the preceding @code{then}-part, -or write the nested @code{if} within braces like this: +@item auto-check +@samp{-a} in @code{recode}. -@example -if (foo) - @dots{} -else - @{ - if (bar) - @dots{} - @} -@end example +@item auto-pager +@samp{-a} in @code{wdiff}. -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. +@item auto-reference +@samp{-A} in @code{ptx}. -Try to avoid assignments inside @code{if}-conditions. For example, -don't write this: +@item avoid-wraps +@samp{-n} in @code{wdiff}. -@example -if ((foo = (char *) malloc (sizeof *foo)) == 0) - fatal ("virtual memory exhausted"); -@end example +@item backward-search +@samp{-B} in @code{ctags}. -@noindent -instead, write this: +@item basename +@samp{-f} in @code{shar}. -@example -foo = (char *) malloc (sizeof *foo); -if (foo == 0) - fatal ("virtual memory exhausted"); -@end example +@item batch +Used in GDB. -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. +@item baud +Used in GDB. -@node Names -@chapter Naming Variables, Functions, and Files +@item before +@samp{-b} in @code{tac}. -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. +@item binary +@samp{-b} in @code{cpio} and @code{diff}. -For example, you should use names like @code{ignore_space_change_flag}; -don't use names like @code{iCantReadThis}. +@item bits-per-code +@samp{-b} in @code{shar}. -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, +@item block-size +Used in @code{cpio} and @code{tar}. -@example -/* Ignore changes in horizontal whitespace (-b). */ -int ignore_space_change_flag; -@end example +@item blocks +@samp{-b} in @code{head} and @code{tail}. -When you want to define names with constant integer values, use -@code{enum} rather than @samp{#define}. GDB knows about enumeration -constants. +@item break-file +@samp{-b} in @code{ptx}. -Use file names of 14 characters or less, to avoid creating gratuitous -problems on System V. You can use the program @code{doschk} to test for -this. @code{doschk} also tests for potential name conflicts if the -files were loaded onto an MS-DOS file system---something you may or may -not care about. +@item brief +Used in various programs to make output shorter. -In general, use @samp{-} to separate words in file names, not @samp{_}. -Make all letters in file names be lower case, except when following -specific conventions that call for upper case in certain kinds of names. -Conventional occasions for using upper case letters in file names -include @file{Makefile}, @file{ChangeLog}, @file{COPYING} and -@file{README}. It is common to name other @file{README}-like -documentation files in all upper case just like @file{README}. +@item bytes +@samp{-c} in @code{head}, @code{split}, and @code{tail}. -@node Using Extensions -@chapter Using Non-standard Features +@item c@t{++} +@samp{-C} in @code{etags}. -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. +@item catenate +@samp{-A} in @code{tar}. -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. +@item cd +Used in various programs to specify the directory to use. -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. +@item changes +@samp{-c} in @code{chgrp} and @code{chown}. -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. +@item classify +@samp{-F} in @code{ls}. -An exception to this rule are the large, established programs (such as -Emacs) which run on a great variety of systems. Such programs would -be broken by use of GNU extensions. +@item colons +@samp{-c} in @code{recode}. -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 no good. +@item command +@samp{-c} in @code{su}; +@samp{-x} in GDB. -Since most computer systems do not yet implement @sc{ANSI} C, using the -@sc{ANSI} C features is effectively using a GNU extension, so the -same considerations apply. (Except for @sc{ANSI} features that we -discourage, such as trigraphs---don't ever use them.) +@item compare +@samp{-d} in @code{tar}. +@item compat +Used in @code{gawk}. -@node System Functions -@chapter Calling System Functions +@item compress +@samp{-Z} in @code{tar} and @code{shar}. -C implementations differ substantially. ANSI C reduces but does not -eliminate the incompatibilities; meanwhile, many users wish to compile -GNU software with pre-ANSI compilers. This chapter gives -recommendations for how to use the more or less standard C library -functions to avoid unnecessary loss of portability. +@item concatenate +@samp{-A} in @code{tar}. -@itemize @bullet -@item -Don't use the value of @code{sprintf}. It returns the number of -characters written on some systems, but not on all systems. +@item confirmation +@samp{-w} in @code{tar}. -@item -Don't declare system functions explicitly. +@item context +Used in @code{diff}. -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. +@item copyleft +@samp{-W copyleft} in @code{gawk}. -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. The problem is only theoretical. By -contrast, actual declarations have frequently caused actual conflicts. +@item copyright +@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}; +@samp{-W copyright} in @code{gawk}. -@item -If you must declare a system function, don't specify the argument types. -Use an old-style declaration, not an ANSI prototype. The more you -specify about the function, the more likely a conflict. +@item core +Used in GDB. -@item -In particular, don't unconditionally declare @code{malloc} or -@code{realloc}. +@item count +@samp{-q} in @code{who}. -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. +@item count-links +@samp{-l} in @code{du}. -Because @code{xmalloc} and @code{xrealloc} are defined in your program, -you can declare them in other files without any risk of type conflict. +@item create +Used in @code{tar} and @code{cpio}. -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. +@item cut-mark +@samp{-c} in @code{shar}. -@item -The string functions require special treatment. Some Unix systems have -a header file @file{string.h}; other 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 cxref +@samp{-x} in @code{ctags}. -@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. +@item date +@samp{-d} in @code{touch}. -That causes less of a problem than you might think. The newer ANSI -string functions are off-limits anyway because many systems still don't -support them. The string functions you can use are these: +@item debug +@samp{-d} in Make and @code{m4}; +@samp{-t} in Bison. -@example -strcpy strncpy strcat strncat -strlen strcmp strncmp -strchr strrchr -@end example +@item define +@samp{-D} in @code{m4}. -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. +@item defines +@samp{-d} in Bison and @code{ctags}. -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. +@item delete +@samp{-D} in @code{tar}. -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. +@item dereference +@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, +@code{ls}, and @code{tar}. -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}.) 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: +@item dereference-args +@samp{-D} in @code{du}. -@example -#ifndef HAVE_STRCHR -#define strchr index -#endif -#ifndef HAVE_STRRCHR -#define strrchr rindex -#endif +@item diacritics +@samp{-d} in @code{recode}. -char *strchr (); -char *strrchr (); -@end example -@end itemize +@item dictionary-order +@samp{-d} in @code{look}. -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. +@item diff +@samp{-d} in @code{tar}. -@node Semantics -@chapter Program Behavior for All Programs +@item digits +@samp{-n} in @code{csplit}. -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. +@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. -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 printers that can't handle those characters. +@item discard-all +@samp{-x} in @code{strip}. -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. +@item discard-locals +@samp{-X} in @code{strip}. -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. +@item dry-run +@samp{-n} in Make. -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}. +@item ed +@samp{-e} in @code{diff}. -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}. +@item elide-empty-files +@samp{-z} in @code{csplit}. -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. +@item end-delete +@samp{-x} in @code{wdiff}. -Use @code{getopt_long} to decode arguments, unless the argument syntax -makes this unreasonable. +@item end-insert +@samp{-z} in @code{wdiff}. -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. +@item entire-new-file +@samp{-N} in @code{diff}. -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 will be supported compatibly by GNU. +@item environment-overrides +@samp{-e} in Make. -By default, the GNU system will provide the signal handling functions of -@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use -these. +@item eof +@samp{-e} in @code{xargs}. -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. +@item epoch +Used in GDB. -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. +@item error-limit +Used in @code{makeinfo}. -@node Errors -@chapter Formatting Error Messages +@item error-output +@samp{-o} in @code{m4}. -Error messages from compilers should look like this: +@item escape +@samp{-b} in @code{ls}. -@example -@var{source-file-name}:@var{lineno}: @var{message} -@end example +@item exclude-from +@samp{-X} in @code{tar}. -Error messages from other noninteractive programs should look like this: +@item exec +Used in GDB. -@example -@var{program}:@var{source-file-name}:@var{lineno}: @var{message} -@end example +@item exit +@samp{-x} in @code{xargs}. -@noindent -when there is an appropriate source file, or like this: +@item exit-0 +@samp{-e} in @code{unshar}. -@example -@var{program}: @var{message} -@end example +@item expand-tabs +@samp{-t} in @code{diff}. -@noindent -when there is no relevant source file. +@item expression +@samp{-e} in @code{sed}. -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.) +@item extern-only +@samp{-g} in @code{nm}. -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. +@item extract +@samp{-i} in @code{cpio}; +@samp{-x} in @code{tar}. -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. +@item faces +@samp{-f} in @code{finger}. +@item fast +@samp{-f} in @code{su}. -@node Libraries -@chapter Library Behavior +@item fatal-warnings +@samp{-E} in @code{m4}. -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. +@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}. -Here are certain name conventions for libraries, to avoid name -conflicts. +@item field-separator +@samp{-F} in @code{gawk}. -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. +@item file-prefix +@samp{-b} in Bison. -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. +@item file-type +@samp{-F} in @code{ls}. -External symbols that are not documented entry points for the user -should have names beginning with @samp{_}. They should also contain -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. +@item files-from +@samp{-T} in @code{tar}. -Static functions and variables can be used as you like and need not -fit any naming convention. +@item fill-column +Used in @code{makeinfo}. +@item flag-truncation +@samp{-F} in @code{ptx}. -@node Portability -@chapter Portability As It Applies to GNU +@item fixed-output-files +@samp{-y} in Bison. -Much of what is called ``portability'' in the Unix world refers to -porting to different Unix versions. This is a secondary consideration -for GNU software, because its primary purpose is to run on top of one -and only one kernel, the GNU kernel, compiled with one and only one C -compiler, the GNU C compiler. The amount and kinds of variation among -GNU systems on different cpu's will be like the variation among Berkeley -4.3 systems on different cpu's. +@item follow +@samp{-f} in @code{tail}. -All users today run GNU software on non-GNU systems. So supporting a -variety of non-GNU systems is desirable; simply not paramount. -The easiest way to achieve portability to a reasonable range of systems -is to use Autoconf. It's unlikely that your program needs to know more -information about the host machine than Autoconf can provide, simply -because most of the programs that need such knowledge have already been -written. +@item footnote-style +Used in @code{makeinfo}. -It is difficult to be sure exactly what facilities the GNU kernel -will provide, since it isn't finished yet. Therefore, assume you can -use anything in 4.3; just avoid using the format of semi-internal data -bases (e.g., directories) when there is a higher-level alternative -(@code{readdir}). - -You can freely assume any reasonably standard facilities in the C -language, libraries or kernel, because we will find it necessary to -support these facilities in the full GNU system, whether or not we -have already done so. The fact that there may exist kernels or C -compilers that lack these facilities is irrelevant as long as the GNU -kernel and C compiler support them. - -It remains necessary to worry about differences among cpu types, such -as the difference in byte ordering and alignment restrictions. It's -unlikely that 16-bit machines will ever be supported by GNU, so there -is no point in spending any time to consider the possibility that an -int will be less than 32 bits. - -You can assume that all pointers have the same format, regardless -of the type they point to, and that this is really an integer. -There are some weird machines where this isn't true, but they aren't -important; don't waste time catering to them. Besides, eventually -we will put function prototypes into all GNU programs, and that will -probably make your program work even on weird machines. - -Since some important machines (including the 68000) are big-endian, -it is important not to assume that the address of an @code{int} object -is also the address of its least-significant byte. Thus, don't -make the following mistake: +@item force +@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. -@example -int c; -@dots{} -while ((c = getchar()) != EOF) - write(file_descriptor, &c, 1); -@end example +@item force-prefix +@samp{-F} in @code{shar}. -You can assume that it is reasonable to use a meg of memory. Don't -strain to reduce memory usage unless it can get to that level. If -your program creates complicated data structures, just make them in -core and give a fatal error if malloc returns zero. +@item format +Used in @code{ls}, @code{time}, and @code{ptx}. -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. +@item freeze-state +@samp{-F} in @code{m4}. +@item fullname +Used in GDB. -@node User Interfaces -@chapter Standards for Command Line Interfaces +@item gap-size +@samp{-g} in @code{ptx}. -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. +@item get +@samp{-x} in @code{tar}. -Instead, use a run time option or a compilation switch or both -to select among the alternate behaviors. +@item graphic +@samp{-i} in @code{ul}. -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. +@item graphics +@samp{-g} in @code{recode}. -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. +@item group +@samp{-g} in @code{install}. -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. +@item gzip +@samp{-z} in @code{tar} and @code{shar}. -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. +@item hashsize +@samp{-H} in @code{m4}. -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}. +@item header +@samp{-h} in @code{objdump} and @code{recode} -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. The table appears below. +@item heading +@samp{-H} in @code{who}. -If you use names not already in the table, please send -@samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we -can update the table. +@item help +Used to ask for brief usage information. -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}). Even if you allow an output file name -as an ordinary argument for compatibility, try to provide a suitable -option as well. This will lead to more consistency among GNU -utilities, so that there are fewer idiosyncracies for users to -remember. +@item here-delimiter +@samp{-d} in @code{shar}. + +@item hide-control-chars +@samp{-q} in @code{ls}. -Programs should support an option @samp{--version} which prints the -program's version number on standard output and exits successfully, and -an option @samp{--help} which prints option usage information on -standard output and exits successfully. These options should inhibit -the normal function of the command; they should do nothing except print -the requested information. +@item idle +@samp{-u} in @code{who}. -@c longopts begin here (keyword for isearch) -@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 +@item ifdef +@samp{-D} in @code{diff}. -@table @samp +@item ignore +@samp{-I} in @code{ls}; +@samp{-x} in @code{recode}. -@item after-date -@samp{-N} in @code{tar}. +@item ignore-all-space +@samp{-w} in @code{diff}. -@item all -@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, -and @code{unexpand}. +@item ignore-backups +@samp{-B} in @code{ls}. -@item all-text -@samp{-a} in @code{diff}. +@item ignore-blank-lines +@samp{-B} in @code{diff}. -@item almost-all -@samp{-A} in @code{ls}. +@item ignore-case +@samp{-f} in @code{look} and @code{ptx}; +@samp{-i} in @code{diff} and @code{wdiff}. -@item append -@samp{-a} in @code{etags}, @code{tee}, @code{time}; -@samp{-r} in @code{tar}. +@item ignore-errors +@samp{-i} in Make. -@item archive -@samp{-a} in @code{cp}. +@item ignore-file +@samp{-i} in @code{ptx}. -@item archive-name -@samp{-n} in @code{shar}. +@item ignore-indentation +@samp{-I} in @code{etags}. -@item arglength -@samp{-l} in @code{m4}. +@item ignore-init-file +@samp{-f} in Oleo. -@item ascii -@samp{-a} in @code{diff}. +@item ignore-interrupts +@samp{-i} in @code{tee}. -@item assign -@samp{-v} in Gawk. +@item ignore-matching-lines +@samp{-I} in @code{diff}. -@item assume-new -@samp{-W} in Make. +@item ignore-space-change +@samp{-b} in @code{diff}. -@item assume-old -@samp{-o} in Make. +@item ignore-zeros +@samp{-i} in @code{tar}. -@item auto-check -@samp{-a} in @code{recode}. +@item include +@samp{-i} in @code{etags}; +@samp{-I} in @code{m4}. -@item auto-pager -@samp{-a} in @code{wdiff}. +@item include-dir +@samp{-I} in Make. -@item auto-reference -@samp{-A} in @code{ptx}. +@item incremental +@samp{-G} in @code{tar}. -@item avoid-wraps -@samp{-n} in @code{wdiff}. +@item info +@samp{-i}, @samp{-l}, and @samp{-m} in Finger. -@item backward-search -@samp{-B} in @code{ctags}. +@item initial +@samp{-i} in @code{expand}. -@item basename -@samp{-f} in @code{shar}. +@item initial-tab +@samp{-T} in @code{diff}. -@item batch -Used in GDB. +@item inode +@samp{-i} in @code{ls}. -@item baud -Used in GDB. +@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 before -@samp{-b} in @code{tac}. +@item intermix-type +@samp{-p} in @code{shar}. -@item binary -@samp{-b} in @code{cpio} and @code{diff}. +@item jobs +@samp{-j} in Make. -@item bits-per-code -@samp{-b} in @code{shar}. +@item just-print +@samp{-n} in Make. -@item block-size -Used in @code{cpio} and @code{tar}. +@item keep-going +@samp{-k} in Make. -@item blocks -@samp{-b} in @code{head} and @code{tail}. +@item keep-files +@samp{-k} in @code{csplit}. -@item break-file -@samp{-b} in @code{ptx}. +@item kilobytes +@samp{-k} in @code{du} and @code{ls}. -@item brief -Used in various programs to make output shorter. +@item language +@samp{-l} in @code{etags}. -@item bytes -@samp{-c} in @code{head}, @code{split}, and @code{tail}. +@item less-mode +@samp{-l} in @code{wdiff}. -@item c@t{++} -@samp{-C} in @code{etags}. +@item level-for-gzip +@samp{-g} in @code{shar}. -@item catenate -@samp{-A} in @code{tar}. +@item line-bytes +@samp{-C} in @code{split}. -@item cd -Used in various programs to specify the directory to use. +@item lines +Used in @code{split}, @code{head}, and @code{tail}. -@item changes -@samp{-c} in @code{chgrp} and @code{chown}. +@item link +@samp{-l} in @code{cpio}. -@item classify -@samp{-F} in @code{ls}. +@item lint +@itemx lint-old +Used in @code{gawk}. -@item colons -@samp{-c} in @code{recode}. +@item list +@samp{-t} in @code{cpio}; +@samp{-l} in @code{recode}. -@item command -@samp{-c} in @code{su}; -@samp{-x} in GDB. +@item list +@samp{-t} in @code{tar}. -@item compare -@samp{-d} in @code{tar}. +@item literal +@samp{-N} in @code{ls}. -@item compat -Used in gawk (no corresponding single-letter option). +@item load-average +@samp{-l} in Make. -@item compress -@samp{-Z} in @code{tar} and @code{shar}. +@item login +Used in @code{su}. -@item concatenate -@samp{-A} in @code{tar}. +@item machine +No listing of which programs already use this; +someone should check to +see if any actually do and tell @code{gnu@@prep.ai.mit.edu}. -@item confirmation -@samp{-w} in @code{tar}. +@item macro-name +@samp{-M} in @code{ptx}. -@item context -Used in @code{diff}. +@item mail +@samp{-m} in @code{hello} and @code{uname}. -@item copyleft -Used in gawk (no corresponding single-letter option). +@item make-directories +@samp{-d} in @code{cpio}. -@item copyright -@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}. -Also used in gawk (no corresponding single-letter option). +@item makefile +@samp{-f} in Make. -@item core +@item mapped Used in GDB. -@item count -@samp{-q} in @code{who}. +@item max-args +@samp{-n} in @code{xargs}. -@item count-links -@samp{-l} in @code{du}. +@item max-chars +@samp{-n} in @code{xargs}. -@item create -Used in @code{tar} and @code{cpio}. +@item max-lines +@samp{-l} in @code{xargs}. -@item cut-mark -@samp{-c} in @code{shar}. +@item max-load +@samp{-l} in Make. -@item cxref -@samp{-x} in @code{ctags}. +@item max-procs +@samp{-P} in @code{xargs}. -@item date -@samp{-d} in @code{touch}. +@item mesg +@samp{-T} in @code{who}. -@item debug -@samp{-d} in Make and @code{m4}; -@samp{-t} in Bison. +@item message +@samp{-T} in @code{who}. -@item define -@samp{-D} in @code{m4}. +@item minimal +@samp{-d} in @code{diff}. -@item defines -@samp{-d} in Bison and @code{ctags}. +@item mixed-uuencode +@samp{-M} in @code{shar}. -@item delete -@samp{-D} in @code{tar}. +@item mode +@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. -@item dereference -@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, -@code{ls}, and @code{tar}. +@item modification-time +@samp{-m} in @code{tar}. -@item dereference-args -@samp{-D} in @code{du}. +@item multi-volume +@samp{-M} in @code{tar}. -@item diacritics -@samp{-d} in @code{recode}. +@item name-prefix +@samp{-a} in Bison. + +@item nesting-limit +@samp{-L} in @code{m4}. -@item dictionary-order -@samp{-d} in @code{look}. +@item net-headers +@samp{-a} in @code{shar}. -@item diff -@samp{-d} in @code{tar}. +@item new-file +@samp{-W} in Make. -@item digits -@samp{-n} in @code{csplit}. +@item no-builtin-rules +@samp{-r} in Make. -@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 no-character-count +@samp{-w} in @code{shar}. -@item discard-all -@samp{-x} in @code{strip}. +@item no-check-existing +@samp{-x} in @code{shar}. -@item discard-locals -@samp{-X} in @code{strip}. +@item no-common +@samp{-3} in @code{wdiff}. -@item dry-run -@samp{-n} in Make. +@item no-create +@samp{-c} in @code{touch}. -@item ed -@samp{-e} in @code{diff}. +@item no-defines +@samp{-D} in @code{etags}. -@item elide-empty-files -@samp{-z} in @code{csplit}. +@item no-deleted +@samp{-1} in @code{wdiff}. -@item end-delete -@samp{-x} in @code{wdiff}. +@item no-dereference +@samp{-d} in @code{cp}. -@item end-insert -@samp{-z} in @code{wdiff}. +@item no-inserted +@samp{-2} in @code{wdiff}. -@item entire-new-file -@samp{-N} in @code{diff}. +@item no-keep-going +@samp{-S} in Make. -@item environment-overrides -@samp{-e} in Make. +@item no-lines +@samp{-l} in Bison. -@item eof -@samp{-e} in @code{xargs}. +@item no-piping +@samp{-P} in @code{shar}. -@item epoch -Used in GDB. +@item no-prof +@samp{-e} in @code{gprof}. -@item error-limit -Used in Makeinfo. +@item no-regex +@samp{-R} in @code{etags}. -@item error-output -@samp{-o} in @code{m4}. +@item no-sort +@samp{-p} in @code{nm}. -@item escape -@samp{-b} in @code{ls}. +@item no-split +Used in @code{makeinfo}. -@item exclude-from -@samp{-X} in @code{tar}. +@item no-static +@samp{-a} in @code{gprof}. -@item exec -Used in GDB. +@item no-time +@samp{-E} in @code{gprof}. -@item exit -@samp{-x} in @code{xargs}. +@item no-timestamp +@samp{-m} in @code{shar}. -@item exit-0 -@samp{-e} in @code{unshar}. +@item no-validate +Used in @code{makeinfo}. -@item expand-tabs -@samp{-t} in @code{diff}. +@item no-warn +Used in various programs to inhibit warnings. -@item expression -@samp{-e} in @code{sed}. +@item node +@samp{-n} in @code{info}. -@item extern-only -@samp{-g} in @code{nm}. +@item nodename +@samp{-n} in @code{uname}. -@item extract -@samp{-i} in @code{cpio}; -@samp{-x} in @code{tar}. +@item nonmatching +@samp{-f} in @code{cpio}. -@item faces -@samp{-f} in @code{finger}. +@item nstuff +@samp{-n} in @code{objdump}. -@item fast -@samp{-f} in @code{su}. +@item null +@samp{-0} in @code{xargs}. -@item fatal-warnings -@samp{-E} in @code{m4}. +@item number +@samp{-n} in @code{cat}. -@item field-separator -p@samp{-F} in Gawk. +@item number-nonblank +@samp{-b} in @code{cat}. -@item file -@samp{-f} in Gawk, @code{info}, Make, @code{mt}, and @code{tar}; -@samp{-n} in @code{sed}; -@samp{-r} in @code{touch}. +@item numeric-sort +@samp{-n} in @code{nm}. -@item file-prefix -@samp{-b} in Bison. +@item numeric-uid-gid +@samp{-n} in @code{cpio} and @code{ls}. -@item file-type -@samp{-F} in @code{ls}. +@item nx +Used in GDB. -@item files-from -@samp{-T} in @code{tar}. +@item old-archive +@samp{-o} in @code{tar}. -@item fill-column -Used in Makeinfo. +@item old-file +@samp{-o} in Make. -@item flag-truncation -@samp{-F} in @code{ptx}. +@item one-file-system +@samp{-l} in @code{tar}, @code{cp}, and @code{du}. -@item fixed-output-files -@samp{-y} in Bison. +@item only-file +@samp{-o} in @code{ptx}. -@item follow -@samp{-f} in @code{tail}. +@item only-prof +@samp{-f} in @code{gprof}. -@item footnote-style -Used in Makeinfo. +@item only-time +@samp{-F} in @code{gprof}. -@item force -@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. +@item output +In various programs, specify the output file name. -@item force-prefix -@samp{-F} in @code{shar}. +@item output-prefix +@samp{-o} in @code{shar}. -@item format -Used in @code{ls}, @code{time}, and @code{ptx}. +@item override +@samp{-o} in @code{rm}. -@item freeze-state -@samp{-F} in @code{m4}. +@item overwrite +@samp{-c} in @code{unshar}. -@item fullname -Used in GDB. +@item owner +@samp{-o} in @code{install}. -@item gap-size -@samp{-g} in @code{ptx}. +@item paginate +@samp{-l} in @code{diff}. -@item get -@samp{-x} in @code{tar}. +@item paragraph-indent +Used in @code{makeinfo}. -@item graphic -@samp{-i} in @code{ul}. +@item parents +@samp{-p} in @code{mkdir} and @code{rmdir}. -@item graphics -@samp{-g} in @code{recode}. +@item pass-all +@samp{-p} in @code{ul}. -@item group -@samp{-g} in @code{install}. +@item pass-through +@samp{-p} in @code{cpio}. -@item gzip -@samp{-z} in @code{tar} and @code{shar}. +@item port +@samp{-P} in @code{finger}. -@item hashsize -@samp{-H} in @code{m4}. +@item portability +@samp{-c} in @code{cpio} and @code{tar}. -@item header -@samp{-h} in @code{objdump} and @code{recode} +@item posix +Used in @code{gawk}. -@item heading -@samp{-H} in @code{who}. +@item prefix-builtins +@samp{-P} in @code{m4}. -@item help -Used to ask for brief usage information. +@item prefix +@samp{-f} in @code{csplit}. -@item here-delimiter -@samp{-d} in @code{shar}. +@item preserve +Used in @code{tar} and @code{cp}. -@item hide-control-chars -@samp{-q} in @code{ls}. +@item preserve-environment +@samp{-p} in @code{su}. -@item idle -@samp{-u} in @code{who}. +@item preserve-modification-time +@samp{-m} in @code{cpio}. -@item ifdef -@samp{-D} in @code{diff}. +@item preserve-order +@samp{-s} in @code{tar}. -@item ignore -@samp{-I} in @code{ls}; -@samp{-x} in @code{recode}. +@item preserve-permissions +@samp{-p} in @code{tar}. -@item ignore-all-space -@samp{-w} in @code{diff}. +@item print +@samp{-l} in @code{diff}. -@item ignore-backups -@samp{-B} in @code{ls}. +@item print-chars +@samp{-L} in @code{cmp}. -@item ignore-blank-lines -@samp{-B} in @code{diff}. +@item print-data-base +@samp{-p} in Make. -@item ignore-case -@samp{-f} in @code{look} and @code{ptx}; -@samp{-i} in @code{diff} and @code{wdiff}. +@item print-directory +@samp{-w} in Make. -@item ignore-errors -@samp{-i} in Make. +@item print-file-name +@samp{-o} in @code{nm}. -@item ignore-file -@samp{-i} in @code{ptx}. +@item print-symdefs +@samp{-s} in @code{nm}. -@item ignore-indentation -@samp{-I} in @code{etags}. +@item printer +@samp{-p} in @code{wdiff}. -@item ignore-init-file -@samp{-f} in Oleo. +@item prompt +@samp{-p} in @code{ed}. -@item ignore-interrupts -@samp{-i} in @code{tee}. +@item query-user +@samp{-X} in @code{shar}. -@item ignore-matching-lines -@samp{-I} in @code{diff}. +@item question +@samp{-q} in Make. -@item ignore-space-change -@samp{-b} in @code{diff}. +@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 ignore-zeros -@samp{-i} in @code{tar}. +@item quiet-unshar +@samp{-Q} in @code{shar} -@item include -@samp{-i} in @code{etags}; -@samp{-I} in @code{m4}. +@item quote-name +@samp{-Q} in @code{ls}. -@item include-dir -@samp{-I} in Make. +@item rcs +@samp{-n} in @code{diff}. -@item incremental -@samp{-G} in @code{tar}. +@item re-interval +Used in @code{gawk}. -@item info -@samp{-i}, @samp{-l}, and @samp{-m} in Finger. +@item read-full-blocks +@samp{-B} in @code{tar}. -@item initial -@samp{-i} in @code{expand}. +@item readnow +Used in GDB. -@item initial-tab -@samp{-T} in @code{diff}. +@item recon +@samp{-n} in Make. -@item inode -@samp{-i} in @code{ls}. +@item record-number +@samp{-R} in @code{tar}. -@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 recursive +Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, +and @code{rm}. -@item intermix-type -@samp{-p} in @code{shar}. +@item reference-limit +Used in @code{makeinfo}. -@item jobs -@samp{-j} in Make. +@item references +@samp{-r} in @code{ptx}. -@item just-print -@samp{-n} in Make. +@item regex +@samp{-r} in @code{tac} and @code{etags}. -@item keep-going -@samp{-k} in Make. +@item release +@samp{-r} in @code{uname}. -@item keep-files -@samp{-k} in @code{csplit}. +@item reload-state +@samp{-R} in @code{m4}. -@item kilobytes -@samp{-k} in @code{du} and @code{ls}. +@item relocation +@samp{-r} in @code{objdump}. -@item language -@samp{-l} in @code{etags}. +@item rename +@samp{-r} in @code{cpio}. -@item less-mode -@samp{-l} in @code{wdiff}. +@item replace +@samp{-i} in @code{xargs}. -@item level-for-gzip -@samp{-g} in @code{shar}. +@item report-identical-files +@samp{-s} in @code{diff}. -@item line-bytes -@samp{-C} in @code{split}. +@item reset-access-time +@samp{-a} in @code{cpio}. -@item lines -Used in @code{split}, @code{head}, and @code{tail}. +@item reverse +@samp{-r} in @code{ls} and @code{nm}. -@item link -@samp{-l} in @code{cpio}. +@item reversed-ed +@samp{-f} in @code{diff}. -@item lint -Used in gawk (no corresponding single-letter option). +@item right-side-defs +@samp{-R} in @code{ptx}. -@item list -@samp{-t} in @code{cpio}; -@samp{-l} in @code{recode}. +@item same-order +@samp{-s} in @code{tar}. -@item list -@samp{-t} in @code{tar}. +@item same-permissions +@samp{-p} in @code{tar}. -@item literal -@samp{-N} in @code{ls}. +@item save +@samp{-g} in @code{stty}. -@item load-average -@samp{-l} in Make. +@item se +Used in GDB. -@item login -Used in @code{su}. +@item sentence-regexp +@samp{-S} in @code{ptx}. -@item machine -No listing of which programs already use this; -someone should check to -see if any actually do and tell @code{gnu@@prep.ai.mit.edu}. +@item separate-dirs +@samp{-S} in @code{du}. -@item macro-name -@samp{-M} in @code{ptx}. +@item separator +@samp{-s} in @code{tac}. -@item mail -@samp{-m} in @code{hello} and @code{uname}. +@item sequence +Used by @code{recode} to chose files or pipes for sequencing passes. -@item make-directories -@samp{-d} in @code{cpio}. +@item shell +@samp{-s} in @code{su}. -@item makefile -@samp{-f} in Make. +@item show-all +@samp{-A} in @code{cat}. -@item mapped -Used in GDB. +@item show-c-function +@samp{-p} in @code{diff}. -@item max-args -@samp{-n} in @code{xargs}. +@item show-ends +@samp{-E} in @code{cat}. -@item max-chars -@samp{-n} in @code{xargs}. +@item show-function-line +@samp{-F} in @code{diff}. -@item max-lines -@samp{-l} in @code{xargs}. +@item show-tabs +@samp{-T} in @code{cat}. -@item max-load -@samp{-l} in Make. +@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 max-procs -@samp{-P} in @code{xargs}. +@item size +@samp{-s} in @code{ls}. -@item mesg -@samp{-T} in @code{who}. +@item sort +Used in @code{ls}. -@item message -@samp{-T} in @code{who}. +@item source +@samp{-W source} in @code{gawk}. -@item minimal -@samp{-d} in @code{diff}. +@item sparse +@samp{-S} in @code{tar}. -@item mixed-uuencode -@samp{-M} in @code{shar}. +@item speed-large-files +@samp{-H} in @code{diff}. -@item mode -@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. +@item split-at +@samp{-E} in @code{unshar}. -@item modification-time -@samp{-m} in @code{tar}. +@item split-size-limit +@samp{-L} in @code{shar}. -@item multi-volume -@samp{-M} in @code{tar}. +@item squeeze-blank +@samp{-s} in @code{cat}. -@item name-prefix -@samp{-a} in Bison. +@item start-delete +@samp{-w} in @code{wdiff}. -@item nesting-limit -@samp{-L} in @code{m4}. +@item start-insert +@samp{-y} in @code{wdiff}. -@item net-headers -@samp{-a} in @code{shar}. +@item starting-file +Used in @code{tar} and @code{diff} to specify which file within +a directory to start processing with. -@item new-file -@samp{-W} in Make. +@item statistics +@samp{-s} in @code{wdiff}. -@item no-builtin-rules -@samp{-r} in Make. +@item stdin-file-list +@samp{-S} in @code{shar}. -@item no-character-count -@samp{-w} in @code{shar}. +@item stop +@samp{-S} in Make. -@item no-check-existing -@samp{-x} in @code{shar}. +@item strict +@samp{-s} in @code{recode}. -@item no-common -@samp{-3} in @code{wdiff}. +@item strip +@samp{-s} in @code{install}. -@item no-create -@samp{-c} in @code{touch}. +@item strip-all +@samp{-s} in @code{strip}. -@item no-defines -@samp{-D} in @code{etags}. +@item strip-debug +@samp{-S} in @code{strip}. -@item no-deleted -@samp{-1} in @code{wdiff}. +@item submitter +@samp{-s} in @code{shar}. -@item no-dereference -@samp{-d} in @code{cp}. +@item suffix +@samp{-S} in @code{cp}, @code{ln}, @code{mv}. -@item no-inserted -@samp{-2} in @code{wdiff}. +@item suffix-format +@samp{-b} in @code{csplit}. -@item no-keep-going -@samp{-S} in Make. +@item sum +@samp{-s} in @code{gprof}. -@item no-lines -@samp{-l} in Bison. +@item summarize +@samp{-s} in @code{du}. -@item no-piping -@samp{-P} in @code{shar}. +@item symbolic +@samp{-s} in @code{ln}. -@item no-prof -@samp{-e} in @code{gprof}. +@item symbols +Used in GDB and @code{objdump}. -@item no-regex -@samp{-R} in @code{etags}. +@item synclines +@samp{-s} in @code{m4}. -@item no-sort -@samp{-p} in @code{nm}. +@item sysname +@samp{-s} in @code{uname}. -@item no-split -Used in Makeinfo. +@item tabs +@samp{-t} in @code{expand} and @code{unexpand}. -@item no-static -@samp{-a} in @code{gprof}. +@item tabsize +@samp{-T} in @code{ls}. -@item no-time -@samp{-E} in @code{gprof}. +@item terminal +@samp{-T} in @code{tput} and @code{ul}. +@samp{-t} in @code{wdiff}. -@item no-timestamp -@samp{-m} in @code{shar}. +@item text +@samp{-a} in @code{diff}. -@item no-validate -Used in Makeinfo. +@item text-files +@samp{-T} in @code{shar}. -@item no-warn -Used in various programs to inhibit warnings. +@item time +Used in @code{ls} and @code{touch}. -@item node -@samp{-n} in @code{info}. +@item to-stdout +@samp{-O} in @code{tar}. -@item nodename -@samp{-n} in @code{uname}. +@item total +@samp{-c} in @code{du}. -@item nonmatching -@samp{-f} in @code{cpio}. +@item touch +@samp{-t} in Make, @code{ranlib}, and @code{recode}. -@item nstuff -@samp{-n} in @code{objdump}. +@item trace +@samp{-t} in @code{m4}. -@item null -@samp{-0} in @code{xargs}. +@item traditional +@samp{-t} in @code{hello}; +@samp{-W traditional} in @code{gawk}; +@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. -@item number -@samp{-n} in @code{cat}. +@item tty +Used in GDB. -@item number-nonblank -@samp{-b} in @code{cat}. +@item typedefs +@samp{-t} in @code{ctags}. -@item numeric-sort -@samp{-n} in @code{nm}. +@item typedefs-and-c++ +@samp{-T} in @code{ctags}. -@item numeric-uid-gid -@samp{-n} in @code{cpio} and @code{ls}. +@item typeset-mode +@samp{-t} in @code{ptx}. -@item nx -Used in GDB. +@item uncompress +@samp{-z} in @code{tar}. -@item old-archive -@samp{-o} in @code{tar}. +@item unconditional +@samp{-u} in @code{cpio}. -@item old-file -@samp{-o} in Make. +@item undefine +@samp{-U} in @code{m4}. -@item one-file-system -@samp{-l} in @code{tar}, @code{cp}, and @code{du}. +@item undefined-only +@samp{-u} in @code{nm}. -@item only-file -@samp{-o} in @code{ptx}. +@item update +@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. -@item only-prof -@samp{-f} in @code{gprof}. +@item usage +Used in @code{gawk}; same as @samp{--help}. -@item only-time -@samp{-F} in @code{gprof}. +@item uuencode +@samp{-B} in @code{shar}. -@item output -In various programs, specify the output file name. +@item vanilla-operation +@samp{-V} in @code{shar}. -@item output-prefix -@samp{-o} in @code{shar}. +@item verbose +Print more information about progress. Many programs support this. -@item override -@samp{-o} in @code{rm}. +@item verify +@samp{-W} in @code{tar}. -@item overwrite -@samp{-c} in @code{unshar}. +@item version +Print the version number. -@item owner -@samp{-o} in @code{install}. +@item version-control +@samp{-V} in @code{cp}, @code{ln}, @code{mv}. -@item paginate -@samp{-l} in @code{diff}. +@item vgrind +@samp{-v} in @code{ctags}. -@item paragraph-indent -Used in Makeinfo. +@item volume +@samp{-V} in @code{tar}. -@item parents -@samp{-p} in @code{mkdir} and @code{rmdir}. +@item what-if +@samp{-W} in Make. -@item pass-all -@samp{-p} in @code{ul}. +@item whole-size-limit +@samp{-l} in @code{shar}. -@item pass-through -@samp{-p} in @code{cpio}. +@item width +@samp{-w} in @code{ls} and @code{ptx}. -@item port -@samp{-P} in @code{finger}. +@item word-regexp +@samp{-W} in @code{ptx}. -@item portability -@samp{-c} in @code{cpio} and @code{tar}. +@item writable +@samp{-T} in @code{who}. -@item posix -Used in gawk (no corresponding single-letter option). +@item zeros +@samp{-z} in @code{gprof}. +@end table -@item prefix-builtins -@samp{-P} in @code{m4}. +@node Memory Usage +@section Memory Usage -@item prefix -@samp{-f} in @code{csplit}. +If it 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. -@item preserve -Used in @code{tar} and @code{cp}. +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. -@item preserve-environment -@samp{-p} in @code{su}. +If your program creates complicated data structures, just make them in +core and give a fatal error if @code{malloc} returns zero. -@item preserve-modification-time -@samp{-m} in @code{cpio}. +@node Writing C +@chapter Making The Best Use of C -@item preserve-order -@samp{-s} in @code{tar}. +This @value{CHAPTER} provides advice on how best to use the C language +when writing GNU software. -@item preserve-permissions -@samp{-p} in @code{tar}. +@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 +@end menu -@item print -@samp{-l} in @code{diff}. +@node Formatting +@section Formatting Your Source Code -@item print-chars -@samp{-L} in @code{cmp}. +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. -@item print-data-base -@samp{-p} in Make. +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: -@item print-directory -@samp{-w} in Make. +@example +static char * +concat (s1, s2) /* Name starts in column zero here */ + char *s1, *s2; +@{ /* Open brace in column zero here */ + @dots{} +@} +@end example -@item print-file-name -@samp{-o} in @code{nm}. +@noindent +or, if you want to use @sc{ansi} C, format the definition like this: -@item print-symdefs -@samp{-s} in @code{nm}. +@example +static char * +concat (char *s1, char *s2) +@{ + @dots{} +@} +@end example -@item printer -@samp{-p} in @code{wdiff}. +In @sc{ansi} C, if the arguments don't fit nicely on one line, +split it like this: -@item prompt -@samp{-p} in @code{ed}. +@example +int +lots_of_args (int an_integer, long a_long, short a_short, + double a_double, float a_float) +@dots{} +@end example -@item query-user -@samp{-X} in @code{shar}. +For the body of the function, we prefer code formatted like this: -@item question -@samp{-q} in Make. +@example +if (x < foo (y, z)) + haha = bar[4] + 5; +else + @{ + while (z) + @{ + haha += foo (z, z); + z--; + @} + return ++x + bar (); + @} +@end example -@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. +We find it easier to read a program when it has spaces before the +open-parentheses and after the commas. Especially after the commas. -@item quiet-unshar -@samp{-Q} in @code{shar} +When you split an expression into multiple lines, split it +before an operator, not after one. Here is the right way: -@item quote-name -@samp{-Q} in @code{ls}. +@example +if (foo_this_is_long && bar > win (x, y, z) + && remaining_condition) +@end example -@item rcs -@samp{-n} in @code{diff}. +Try to avoid having two operators of different precedence at the same +level of indentation. For example, don't write this: -@item read-full-blocks -@samp{-B} in @code{tar}. +@example +mode = (inmode[j] == VOIDmode + || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) + ? outmode[j] : inmode[j]); +@end example -@item readnow -Used in GDB. +Instead, use extra parentheses so that the indentation shows the nesting: -@item recon -@samp{-n} in Make. +@example +mode = ((inmode[j] == VOIDmode + || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) + ? outmode[j] : inmode[j]); +@end example -@item record-number -@samp{-R} in @code{tar}. +Insert extra parentheses so that Emacs will indent the code properly. +For example, the following indentation looks nice if you do it by hand, +but Emacs would mess it up: -@item recursive -Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, -and @code{rm}. +@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 -@item reference-limit -Used in Makeinfo. +But adding a set of parentheses solves the problem: -@item references -@samp{-r} in @code{ptx}. +@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 -@item regex -@samp{-r} in @code{tac} and @code{etags}. +Format do-while statements like this: -@item release -@samp{-r} in @code{uname}. +@example +do + @{ + a = foo (a); + @} +while (a > 0); +@end example -@item reload-state -@samp{-R} in @code{m4}. +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. -@item relocation -@samp{-r} in @code{objdump}. -@item rename -@samp{-r} in @code{cpio}. +@node Comments +@section Commenting Your Work -@item replace -@samp{-i} in @code{xargs}. +Every program should start with a comment saying briefly what it is for. +Example: @samp{fmt - filter for simple filling of text}. -@item report-identical-files -@samp{-s} in @code{diff}. +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. -@item reset-access-time -@samp{-a} in @code{cpio}. +Also explain the significance of the return value, if there is one. -@item reverse -@samp{-r} in @code{ls} and @code{nm}. +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{}''). -@item reversed-ed -@samp{-f} in @code{diff}. +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''. -@item right-side-defs -@samp{-R} in @code{ptx}. +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. -@item same-order -@samp{-s} in @code{tar}. +There should be a comment on each static variable as well, like this: -@item same-permissions -@samp{-p} in @code{tar}. +@example +/* Nonzero means truncate lines in the display; + zero means continue them. */ +int truncate_lines; +@end example -@item save -@samp{-g} in @code{stty}. +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: -@item se -Used in GDB. +@example +@group +#ifdef foo + @dots{} +#else /* not foo */ + @dots{} +#endif /* not foo */ +@end group +@end example -@item sentence-regexp -@samp{-S} in @code{ptx}. +@noindent +but, by contrast, write the comments this way for a @samp{#ifndef}: -@item separate-dirs -@samp{-S} in @code{du}. +@example +@group +#ifndef foo + @dots{} +#else /* foo */ + @dots{} +#endif /* foo */ +@end group +@end example -@item separator -@samp{-s} in @code{tac}. -@item sequence -Used by @code{recode} to chose files or pipes for sequencing passes. +@node Syntactic Conventions +@section Clean Use of C Constructs -@item shell -@samp{-s} in @code{su}. +Please explicitly declare all arguments to functions. +Don't omit them just because they are @code{int}s. -@item show-all -@samp{-A} in @code{cat}. +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. -@item show-c-function -@samp{-p} in @code{diff}. +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. -@item show-ends -@samp{-E} in @code{cat}. +Don't use local variables or parameters that shadow global identifiers. -@item show-function-line -@samp{-F} in @code{diff}. +Don't declare multiple variables in one declaration that spans lines. +Start a new declaration on each line, instead. For example, instead +of this: -@item show-tabs -@samp{-T} in @code{cat}. +@example +@group +int foo, + bar; +@end group +@end example -@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. +@noindent +write either this: -@item size -@samp{-s} in @code{ls}. +@example +int foo, bar; +@end example -@item sort -Used in @code{ls}. +@noindent +or this: -@item source -Used in gawk (no corresponding single-letter option). +@example +int foo; +int bar; +@end example -@item sparse -@samp{-S} in @code{tar}. +@noindent +(If they are global variables, each should have a comment preceding it +anyway.) -@item speed-large-files -@samp{-H} in @code{diff}. +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: -@item split-at -@samp{-E} in @code{unshar}. +@example +if (foo) + if (bar) + win (); + else + lose (); +@end example -@item split-size-limit -@samp{-L} in @code{shar}. +@noindent +always like this: -@item squeeze-blank -@samp{-s} in @code{cat}. +@example +if (foo) + @{ + if (bar) + win (); + else + lose (); + @} +@end example -@item start-delete -@samp{-w} in @code{wdiff}. +If you have an @code{if} statement nested inside of an @code{else} +statement, either write @code{else if} on one line, like this, -@item start-insert -@samp{-y} in @code{wdiff}. +@example +if (foo) + @dots{} +else if (bar) + @dots{} +@end example -@item starting-file -Used in @code{tar} and @code{diff} to specify which file within -a directory to start processing with. +@noindent +with its @code{then}-part indented like the preceding @code{then}-part, +or write the nested @code{if} within braces like this: -@item statistics -@samp{-s} in @code{wdiff}. +@example +if (foo) + @dots{} +else + @{ + if (bar) + @dots{} + @} +@end example -@item stdin-file-list -@samp{-S} in @code{shar}. +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. -@item stop -@samp{-S} in Make. +Try to avoid assignments inside @code{if}-conditions. For example, +don't write this: -@item strict -@samp{-s} in @code{recode}. +@example +if ((foo = (char *) malloc (sizeof *foo)) == 0) + fatal ("virtual memory exhausted"); +@end example -@item strip -@samp{-s} in @code{install}. +@noindent +instead, write this: -@item strip-all -@samp{-s} in @code{strip}. +@example +foo = (char *) malloc (sizeof *foo); +if (foo == 0) + fatal ("virtual memory exhausted"); +@end example -@item strip-debug -@samp{-S} in @code{strip}. +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. -@item submitter -@samp{-s} in @code{shar}. +@node Names +@section Naming Variables and Functions -@item suffix -@samp{-S} in @code{cp}, @code{ln}, @code{mv}. +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. -@item suffix-format -@samp{-b} in @code{csplit}. +For example, you should use names like @code{ignore_space_change_flag}; +don't use names like @code{iCantReadThis}. -@item sum -@samp{-s} in @code{gprof}. +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, -@item summarize -@samp{-s} in @code{du}. +@example +@group +/* Ignore changes in horizontal whitespace (-b). */ +int ignore_space_change_flag; +@end group +@end example -@item symbolic -@samp{-s} in @code{ln}. +When you want to define names with constant integer values, use +@code{enum} rather than @samp{#define}. GDB knows about enumeration +constants. -@item symbols -Used in GDB and @code{objdump}. +Use file names of 14 characters or less, to avoid creating gratuitous +problems on older System V systems. You can use the program @code{doschk} to test for +this. @code{doschk} also tests for potential name conflicts if the +files were loaded onto an MS-DOS file system---something you may or may +not care about. -@item synclines -@samp{-s} in @code{m4}. +@node System Portability +@section Portability between System Types -@item sysname -@samp{-s} in @code{uname}. +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. -@item tabs -@samp{-t} in @code{expand} and @code{unexpand}. +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}. The +amount and kinds of variation among GNU systems on different @sc{cpu}s +will be comparable to the variation among Linux-based GNU systems or +among BSD systems today. So the kinds of portability that are absolutely +necessary are quite limited. -@item tabsize -@samp{-T} in @code{ls}. +But many users do run GNU software on non-GNU Unix or Unix-like systems. +So supporting a variety of Unix-like systems is desirable, although not +paramount. -@item terminal -@samp{-T} in @code{tput} and @code{ul}. -@samp{-t} in @code{wdiff}. +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. -@item text -@samp{-a} in @code{diff}. +Avoid using the format of semi-internal data bases (e.g., directories) +when there is a higher-level alternative (@code{readdir}). -@item text-files -@samp{-T} in @code{shar}. +As for systems that are not like Unix, such as MSDOS, Windows, the +Macintosh, VMS, and MVS, supporting them is usually so much work that it +is better if you don't. -@item time -Used in @code{ls} and @code{touch}. +The planned GNU kernel is not finished yet, but you can tell which +facilities it will provide by looking at the GNU C Library Manual. The +GNU kernel is based on Mach, so the features of Mach will also be +available. However, if you use Mach features, you'll probably have +trouble debugging your program today. -@item to-stdout -@samp{-O} in @code{tar}. +@node CPU Portability +@section Portability between @sc{cpu}s -@item total -@samp{-c} in @code{du}. +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. -@item touch -@samp{-t} in Make, @code{ranlib}, and @code{recode}. +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: -@item trace -@samp{-t} in @code{m4}. +@example +int c; +@dots{} +while ((c = getchar()) != EOF) + write(file_descriptor, &c, 1); +@end example -@item traditional -@samp{-t} in @code{hello}; -@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. +When calling functions, you need not worry about the difference between +pointers of various types, or between pointers an integers. On most +machines, there's no difference anyway. As for the few machines where +there is a difference, all of them support @sc{ansi} C, so you can use +prototypes (conditionalized to be active only in @sc{ansi} C) to make +the code work on those systems. -@item tty -Used in GDB. +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: -@item typedefs -@samp{-t} in @code{ctags}. +@example +error (s, a1, a2, a3) + char *s; + int a1, a2, a3; +@{ + fprintf (stderr, "error: "); + fprintf (stderr, s, a1, a2, a3); +@} +@end example -@item typedefs-and-c++ -@samp{-T} in @code{ctags}. +@noindent +In practice, this works on all machines, and it is much simpler than any +``correct'' alternative. -@item typeset-mode -@samp{-t} in @code{ptx}. +However, avoid casting pointers to integers unless you really need to. +These assumptions really 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---it is ok to do so, but you'll have to +make explicit provisions to handle different word sizes. -@item uncompress -@samp{-z} in @code{tar}. +@node System Functions +@section Calling System Functions -@item unconditional -@samp{-u} in @code{cpio}. +C implementations differ substantially. @sc{ansi} C reduces but does not +eliminate the incompatibilities; meanwhile, many users wish to compile +GNU software with pre-@sc{ansi} compilers. This chapter gives +recommendations for how to use the more or less standard C library +functions to avoid unnecessary loss of portability. -@item undefine -@samp{-U} in @code{m4}. +@itemize @bullet +@item +Don't use the value of @code{sprintf}. It returns the number of +characters written on some systems, but not on all systems. -@item undefined-only -@samp{-u} in @code{nm}. +@item +Don't declare system functions explicitly. -@item update -@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. +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. -@item usage -Used in gawk (no corresponding single-letter option). +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 uuencode -@samp{-B} in @code{shar}. +@item +If you must declare a system function, don't specify the argument types. +Use an old-style declaration, not an @sc{ansi} prototype. The more you +specify about the function, the more likely a conflict. -@item vanilla-operation -@samp{-V} in @code{shar}. +@item +In particular, don't unconditionally declare @code{malloc} or +@code{realloc}. -@item verbose -Print more information about progress. Many programs support this. +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. -@item verify -@samp{-W} in @code{tar}. +Because @code{xmalloc} and @code{xrealloc} are defined in your program, +you can declare them in other files without any risk of type conflict. -@item version -Print the version number. +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. -@item version-control -@samp{-V} in @code{cp}, @code{ln}, @code{mv}. +@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 vgrind -@samp{-v} in @code{ctags}. +@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. -@item volume -@samp{-V} in @code{tar}. +That causes less of a problem than you might think. The newer @sc{ansi} +string functions should be avoided anyway because many systems still +don't support them. The string functions you can use are these: -@item what-if -@samp{-W} in Make. +@example +strcpy strncpy strcat strncat +strlen strcmp strncmp +strchr strrchr +@end example -@item whole-size-limit -@samp{-l} in @code{shar}. +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. -@item width -@samp{-w} in @code{ls} and @code{ptx}. +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. -@item word-regexp -@samp{-W} in @code{ptx}. +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. -@item writable -@samp{-T} in @code{who}. +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 @sc{ansi} +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: -@item zeros -@samp{-z} in @code{gprof}. +@example +#ifndef HAVE_STRCHR +#define strchr index +#endif +#ifndef HAVE_STRRCHR +#define strrchr rindex +#endif -@end table -@c longopts end here (keyword for isearch) +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 Documentation @chapter Documenting Programs @@ -2352,9 +2251,10 @@ Print the version number. * GNU Manuals:: Writing proper manuals. * Manual Structure Details:: Specific structure conventions. * 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. + from other manuals. @end menu @node GNU Manuals @@ -2362,8 +2262,8 @@ Print the version number. The preferred way to document part of the GNU system is to write a manual in the Texinfo formatting language. See the Texinfo manual, -either the hardcopy or the version in the Emacs Info subsystem (@kbd{C-h -i}). +either the hardcopy, or the on-line version available through +@code{info} or the Emacs Info subsystem (@kbd{C-h i}). The manual should document all of the program's command-line options and all of its commands. It should give examples of their use. But don't @@ -2377,7 +2277,7 @@ 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. -That is not as hard as it sounds at first. Arrange each chapter as a +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 @@ -2400,7 +2300,7 @@ documentation; use ``file name'' (two words) instead. We use the term @section Manual Structure Details The title page of the manual should state the version of the program -which the manual applies to. The Top node of the manual should also +to which the manual applies. 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. @@ -2438,27 +2338,114 @@ 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 + +Keep a change log for each directory, describing the changes made to +source files in that directory. 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 eliminate conceptual inconsistencies between different parts +of a program; they can give you a history of how the conflicting +concepts arose. + +Use the Emacs command @kbd{M-x add-change-log-entry} to start a new +entry in the +change log. 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. + +Separate unrelated 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. + +Here are some examples: + +@example +* 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 the +entry. + +There's no need to describe the full purpose of the changes or how they +work together. It is better to put such explanations in comments in the +code. That's why just ``New function'' is enough; there is a comment +with the function in the source to explain what it does. + +However, sometimes it is useful to write one line to describe the +overall purpose of a large batch of changes. + +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. + +When you change the calling sequence of a function in a simple +fashion, and you change all the callers of the function, there is no +need to make individual entries for all the callers. Just write in +the entry for the function being called, ``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. Write just, +``Doc fix.'' There's no need to keep a change log 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. + @node Man Pages @section Man Pages -It is ok to supply a man page for the program as well as a Texinfo -manual if you wish to. But keep in mind that supporting a man page -requires continual effort, each time the program is changed. Any time -you spend on the man page is time taken away from more useful things you -could contribute. - -Thus, even if a user volunteers to donate a man page, you may find this -gift costly to accept. Unless you have time on your hands, it may be -better to refuse the man page unless the same volunteer agrees to take -full responsibility for maintaining it---so that you can wash your hands -of it entirely. If the volunteer ceases to do the job, then don't feel -obliged to pick it up yourself; it may be better to withdraw the man -page until another volunteer offers to carry on with it. - -Alternatively, if you expect the discrepancies to be small enough that -the man page remains useful, 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, and describing how to access the Texinfo +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 @@ -2476,8 +2463,193 @@ 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 + +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 + +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. + +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{x}, @samp{x-toolkit}, +@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and +@samp{gdb}. + +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. + +@item --nfp +The target machine has no floating point processor. + +@item --gas +The target machine assembler is GAS, the GNU assembler. +This is obsolete; users should use @samp{--with-gnu-as} instead. + +@item --x +The target machine has the X Window System installed. +This is obsolete; users should use @samp{--with-x} instead. +@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. + +The way to build a cross-compiler, cross-assembler, or what have you, is +to specify the option @samp{--host=@var{hosttype}} when running +@code{configure}. This specifies the host system without changing the +type of target system. The syntax for @var{hosttype} is the same as +described above. + +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{hosttype}} for specifying the +configuration on which you will compile them, in case that is different +from the host. + +Programs for which cross-operation is not meaningful need not accept the +@samp{--host} option, because configuring an entire operating system for +cross-operation is not a meaningful thing. + +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 -@chapter Making Releases +@section Making Releases Package the distribution of Foo version 69.96 in a gzipped tar file named @file{foo-69.96.tar.gz}. It should unpack into a subdirectory @@ -2494,7 +2666,7 @@ 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 +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. @@ -2525,16 +2697,16 @@ 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-DOG. A -name on MS-DOG consists of up to 8 characters, optionally followed by a -period and up to three characters. MS-DOG will truncate extra +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. Include in your distribution a copy of the @file{texinfo.tex} you used -to test print any @file{*.texinfo} files. +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. diff --git a/src/util/autoconf/texinfo.tex b/src/util/autoconf/texinfo.tex index dfd57a9ed..7489021c5 100644 --- a/src/util/autoconf/texinfo.tex +++ b/src/util/autoconf/texinfo.tex @@ -1,6 +1,7 @@ %% TeX macros to handle texinfo files -% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 1994 Free Software Foundation, Inc. +% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, +% 94, 95, 1996 Free Software Foundation, Inc. %This texinfo.tex file is free software; you can redistribute it and/or %modify it under the terms of the GNU General Public License as @@ -14,8 +15,8 @@ %You should have received a copy of the GNU General Public License %along with this texinfo.tex file; see the file COPYING. If not, write -%to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, -%USA. +%to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +%Boston, MA 02111-1307, USA. %In other words, you are welcome to use, share and improve this program. @@ -66,7 +67,10 @@ % since \penalty is valid in vertical mode, we'd end up putting the % penalty on the vertical list instead of in the new paragraph. {\catcode`@ = 11 - \gdef\tie{\leavevmode\penalty\@M\ } + % Avoid using \@M directly, because that causes trouble + % if the definition is written into an index file. + \global\let\tiepenalty = \@M + \gdef\tie{\leavevmode\penalty\tiepenalty\ } } \let\~ = \tie % And make it available as @~. @@ -533,17 +537,34 @@ where each line of input produces a line of output.} \def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount \leftline{\hskip\leftskip{\rm#1}}}} +% @inmargin{TEXT} puts TEXT in the margin next to the current paragraph. + +\def\inmargin#1{% +\strut\vadjust{\nobreak\kern-\strutdepth + \vtop to \strutdepth{\baselineskip\strutdepth\vss + \llap{\rightskip=\inmarginspacing \vbox{\noindent #1}}\null}}} +\newskip\inmarginspacing \inmarginspacing=1cm +\def\strutdepth{\dp\strutbox} + %\hbox{{\rm#1}}\hfil\break}} % @include file insert text of that file as input. - -\def\include{\parsearg\includezzz} -%Use \input\thisfile to avoid blank after \input, which may be an active -%char (in which case the blank would become the \input argument). -%The grouping keeps the value of \thisfile correct even when @include -%is nested. -\def\includezzz #1{\begingroup -\def\thisfile{#1}\input\thisfile +% Allow normal characters that we make active in the argument (a file name). +\def\include{\begingroup + \catcode`\\=12 + \catcode`~=12 + \catcode`^=12 + \catcode`_=12 + \catcode`|=12 + \catcode`<=12 + \catcode`>=12 + \catcode`+=12 + \parsearg\includezzz} +% Restore active chars for included file. +\def\includezzz#1{\endgroup\begingroup + % Read the included file in a group so nested @include's work. + \def\thisfile{#1}% + \input\thisfile \endgroup} \def\thisfile{} @@ -628,6 +649,15 @@ where each line of input produces a line of output.} \let\printindex = \relax \let\pxref = \relax \let\settitle = \relax + \let\setchapternewpage = \relax + \let\setchapterstyle = \relax + \let\everyheading = \relax + \let\evenheading = \relax + \let\oddheading = \relax + \let\everyfooting = \relax + \let\evenfooting = \relax + \let\oddfooting = \relax + \let\headings = \relax \let\include = \relax \let\lowersections = \relax \let\down = \relax @@ -651,6 +681,11 @@ where each line of input produces a line of output.} \def\menu{\doignore{menu}} \def\direntry{\doignore{direntry}} +% @dircategory CATEGORY -- specify a category of the dir file +% which this file should belong to. Ignore this in TeX. + +\def\dircategory{\comment} + % Ignore text until a line `@end #1'. % \def\doignore#1{\begingroup @@ -686,7 +721,7 @@ where each line of input produces a line of output.} \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} \immediate\write16{ to use a workaround.} \immediate\write16{} - \warnedobstrue + \global\warnedobstrue \fi } @@ -762,15 +797,17 @@ where each line of input produces a line of output.} % Since we want to separate VAR from REST-OF-LINE (which might be % empty), we can't just use \parsearg; we have to insert a space of our % own to delimit the rest of the line, and then take it out again if we -% didn't need it. +% didn't need it. Make sure the catcode of space is correct to avoid +% losing inside @example, for instance. % -\def\set{\parsearg\setxxx} +\def\set{\begingroup\catcode` =10 \parsearg\setxxx} \def\setxxx#1{\setyyy#1 \endsetyyy} \def\setyyy#1 #2\endsetyyy{% \def\temp{#2}% \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. \fi + \endgroup } % Can't use \xdef to pre-expand #2 and save some time, since \temp or % \next or other control sequences that we've defined might get us into @@ -907,6 +944,21 @@ where each line of input produces a line of output.} \def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, node \samp{\ignorespaces#1{}}} +\def\macro#1{\begingroup\ignoresections\catcode`\#=6\def\macrotemp{#1}\parsearg\macroxxx} +\def\macroxxx#1#2 \end macro{% +\expandafter\gdef\macrotemp#1{#2}% +\endgroup} + +%\def\linemacro#1{\begingroup\ignoresections\catcode`\#=6\def\macrotemp{#1}\parsearg\linemacroxxx} +%\def\linemacroxxx#1#2 \end linemacro{% +%\let\parsearg=\relax +%\edef\macrotempx{\csname M\butfirst\expandafter\string\macrotemp\endcsname}% +%\expandafter\xdef\macrotemp{\parsearg\macrotempx}% +%\expandafter\gdef\macrotempx#1{#2}% +%\endgroup} + +%\def\butfirst#1{} + \message{fonts,} % Font-change commands. @@ -917,12 +969,16 @@ where each line of input produces a line of output.} \def\sf{\fam=\sffam \tensf} \let\li = \sf % Sometimes we call it \li, not \sf. +% We don't need math for this one. +\def\ttsl{\tenttsl} + %% Try out Computer Modern fonts at \magstephalf \let\mainmagstep=\magstephalf % Set the font macro #1 to the font named #2, adding on the % specified font prefix (normally `cm'). -\def\setfont#1#2{\font#1=\fontprefix#2} +% #3 is the font's design size, #4 is a scale factor +\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4} % Use cm as the default font prefix. % To specify the font prefix, you must define \fontprefix @@ -930,29 +986,46 @@ where each line of input produces a line of output.} \ifx\fontprefix\undefined \def\fontprefix{cm} \fi +% Support font families that don't use the same naming scheme as CM. +\def\rmshape{r} +\def\rmbshape{bx} %where the normal face is bold +\def\bfshape{b} +\def\bxshape{bx} +\def\ttshape{tt} +\def\ttbshape{tt} +\def\ttslshape{sltt} +\def\itshape{ti} +\def\itbshape{bxti} +\def\slshape{sl} +\def\slbshape{bxsl} +\def\sfshape{ss} +\def\sfbshape{ss} +\def\scshape{csc} +\def\scbshape{csc} \ifx\bigger\relax \let\mainmagstep=\magstep1 -\setfont\textrm{r12} -\setfont\texttt{tt12} +\setfont\textrm\rmshape{12}{1000} +\setfont\texttt\ttshape{12}{1000} \else -\setfont\textrm{r10 scaled \mainmagstep} -\setfont\texttt{tt10 scaled \mainmagstep} +\setfont\textrm\rmshape{10}{\mainmagstep} +\setfont\texttt\ttshape{10}{\mainmagstep} \fi % Instead of cmb10, you many want to use cmbx10. % cmbx10 is a prettier font on its own, but cmb10 % looks better when embedded in a line with cmr10. -\setfont\textbf{b10 scaled \mainmagstep} -\setfont\textit{ti10 scaled \mainmagstep} -\setfont\textsl{sl10 scaled \mainmagstep} -\setfont\textsf{ss10 scaled \mainmagstep} -\setfont\textsc{csc10 scaled \mainmagstep} +\setfont\textbf\bfshape{10}{\mainmagstep} +\setfont\textit\itshape{10}{\mainmagstep} +\setfont\textsl\slshape{10}{\mainmagstep} +\setfont\textsf\sfshape{10}{\mainmagstep} +\setfont\textsc\scshape{10}{\mainmagstep} +\setfont\textttsl\ttslshape{10}{\mainmagstep} \font\texti=cmmi10 scaled \mainmagstep \font\textsy=cmsy10 scaled \mainmagstep % A few fonts for @defun, etc. -\setfont\defbf{bx10 scaled \magstep1} %was 1314 -\setfont\deftt{tt10 scaled \magstep1} +\setfont\defbf\bxshape{10}{\magstep1} %was 1314 +\setfont\deftt\ttshape{10}{\magstep1} \def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} % Fonts for indices and small examples. @@ -960,66 +1033,70 @@ where each line of input produces a line of output.} % because texinfo normally uses the slanted fonts for that. % Do not make many font distinctions in general in the index, since they % aren't very useful. -\setfont\ninett{tt9} -\setfont\indrm{r9} -\setfont\indit{sl9} +\setfont\ninett\ttshape{9}{1000} +\setfont\indrm\rmshape{9}{1000} +\setfont\indit\slshape{9}{1000} \let\indsl=\indit \let\indtt=\ninett +\let\indttsl=\ninett \let\indsf=\indrm \let\indbf=\indrm -\setfont\indsc{csc10 at 9pt} +\setfont\indsc\scshape{10}{900} \font\indi=cmmi9 \font\indsy=cmsy9 % Fonts for headings -\setfont\chaprm{bx12 scaled \magstep2} -\setfont\chapit{ti12 scaled \magstep2} -\setfont\chapsl{sl12 scaled \magstep2} -\setfont\chaptt{tt12 scaled \magstep2} -\setfont\chapsf{ss12 scaled \magstep2} +\setfont\chaprm\rmbshape{12}{\magstep2} +\setfont\chapit\itbshape{10}{\magstep3} +\setfont\chapsl\slbshape{10}{\magstep3} +\setfont\chaptt\ttbshape{12}{\magstep2} +\setfont\chapttsl\ttslshape{10}{\magstep3} +\setfont\chapsf\sfbshape{12}{\magstep2} \let\chapbf=\chaprm -\setfont\chapsc{csc10 scaled\magstep3} +\setfont\chapsc\scbshape{10}{\magstep3} \font\chapi=cmmi12 scaled \magstep2 \font\chapsy=cmsy10 scaled \magstep3 -\setfont\secrm{bx12 scaled \magstep1} -\setfont\secit{ti12 scaled \magstep1} -\setfont\secsl{sl12 scaled \magstep1} -\setfont\sectt{tt12 scaled \magstep1} -\setfont\secsf{ss12 scaled \magstep1} -\setfont\secbf{bx12 scaled \magstep1} -\setfont\secsc{csc10 scaled\magstep2} +\setfont\secrm\rmbshape{12}{\magstep1} +\setfont\secit\itbshape{10}{\magstep2} +\setfont\secsl\slbshape{10}{\magstep2} +\setfont\sectt\ttbshape{12}{\magstep1} +\setfont\secttsl\ttslshape{10}{\magstep2} +\setfont\secsf\sfbshape{12}{\magstep1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep2} \font\seci=cmmi12 scaled \magstep1 \font\secsy=cmsy10 scaled \magstep2 -% \setfont\ssecrm{bx10 scaled \magstep1} % This size an font looked bad. -% \setfont\ssecit{cmti10 scaled \magstep1} % The letters were too crowded. -% \setfont\ssecsl{sl10 scaled \magstep1} -% \setfont\ssectt{tt10 scaled \magstep1} -% \setfont\ssecsf{ss10 scaled \magstep1} +% \setfont\ssecrm\bxshape{10}{\magstep1} % This size an font looked bad. +% \setfont\ssecit\itshape{10}{\magstep1} % The letters were too crowded. +% \setfont\ssecsl\slshape{10}{\magstep1} +% \setfont\ssectt\ttshape{10}{\magstep1} +% \setfont\ssecsf\sfshape{10}{\magstep1} -%\setfont\ssecrm{b10 scaled 1315} % Note the use of cmb rather than cmbx. -%\setfont\ssecit{ti10 scaled 1315} % Also, the size is a little larger than -%\setfont\ssecsl{sl10 scaled 1315} % being scaled magstep1. -%\setfont\ssectt{tt10 scaled 1315} -%\setfont\ssecsf{ss10 scaled 1315} +%\setfont\ssecrm\bfshape{10}{1315} % Note the use of cmb rather than cmbx. +%\setfont\ssecit\itshape{10}{1315} % Also, the size is a little larger than +%\setfont\ssecsl\slshape{10}{1315} % being scaled magstep1. +%\setfont\ssectt\ttshape{10}{1315} +%\setfont\ssecsf\sfshape{10}{1315} %\let\ssecbf=\ssecrm -\setfont\ssecrm{bx12 scaled \magstephalf} -\setfont\ssecit{ti12 scaled \magstephalf} -\setfont\ssecsl{sl12 scaled \magstephalf} -\setfont\ssectt{tt12 scaled \magstephalf} -\setfont\ssecsf{ss12 scaled \magstephalf} -\setfont\ssecbf{bx12 scaled \magstephalf} -\setfont\ssecsc{csc10 scaled \magstep1} +\setfont\ssecrm\rmbshape{12}{\magstephalf} +\setfont\ssecit\itbshape{10}{1315} +\setfont\ssecsl\slbshape{10}{1315} +\setfont\ssectt\ttbshape{12}{\magstephalf} +\setfont\ssecttsl\ttslshape{10}{\magstep1} +\setfont\ssecsf\sfbshape{12}{\magstephalf} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{\magstep1} \font\sseci=cmmi12 scaled \magstephalf \font\ssecsy=cmsy10 scaled \magstep1 % The smallcaps and symbol fonts should actually be scaled \magstep1.5, % but that is not a standard magnification. % Fonts for title page: -\setfont\titlerm{bx12 scaled \magstep3} +\setfont\titlerm\rmbshape{12}{\magstep3} \let\authorrm = \secrm % In order for the font changes to affect most math symbols and letters, @@ -1038,33 +1115,33 @@ where each line of input produces a line of output.} % The font-changing commands redefine the meanings of \tenSTYLE, instead % of just \STYLE. We do this so that font changes will continue to work % in math mode, where it is the current \fam that is relevant in most -% cases, not the current. Plain TeX does, for example, -% \def\bf{\fam=\bffam \tenbf} By redefining \tenbf, we obviate the need -% to redefine \bf itself. +% cases, not the current font. Plain TeX does \def\bf{\fam=\bffam +% \tenbf}, for example. By redefining \tenbf, we obviate the need to +% redefine \bf itself. \def\textfonts{% \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl \resetmathfonts} \def\chapfonts{% \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc - \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy + \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy \let\tenttsl=\chapttsl \resetmathfonts} \def\secfonts{% \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy \let\tenttsl=\secttsl \resetmathfonts} \def\subsecfonts{% \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy \let\tenttsl=\ssecttsl \resetmathfonts} \def\indexfonts{% \let\tenrm=\indrm \let\tenit=\indit \let\tensl=\indsl \let\tenbf=\indbf \let\tentt=\indtt \let\smallcaps=\indsc - \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy + \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy \let\tenttsl=\indttsl \resetmathfonts} % Set up the default fonts, so we can use them for creating boxes. @@ -1075,9 +1152,9 @@ where each line of input produces a line of output.} \newcount\fontdepth \fontdepth=0 % Fonts for short table of contents. -\setfont\shortcontrm{r12} -\setfont\shortcontbf{bx12} -\setfont\shortcontsl{sl12} +\setfont\shortcontrm\rmshape{12}{1000} +\setfont\shortcontbf\bxshape{12}{1000} +\setfont\shortcontsl\slshape{12}{1000} %% Add scribe-like font environments, plus @l for inline lisp (usually sans %% serif) and @ii for TeX italic @@ -1104,16 +1181,16 @@ where each line of input produces a line of output.} \def\restorehyphenation{\hyphenchar\font = `- } \def\t#1{% - {\tt \nohyphenation \rawbackslash \frenchspacing #1}% + {\tt \rawbackslash \frenchspacing #1}% \null } -\let\ttfont = \t -%\def\samp #1{`{\tt \rawbackslash \frenchspacing #1}'\null} +\let\ttfont=\t \def\samp #1{`\tclose{#1}'\null} -\def\key #1{{\tt \nohyphenation \uppercase{#1}}\null} +\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} \def\ctrl #1{{\tt \rawbackslash \hat}#1} \let\file=\samp +\let\url=\samp % perhaps include a hypertex \special eventually % @code is a modification of @t, % which makes spaces the same size as normal in the surrounding text. @@ -1139,7 +1216,7 @@ where each line of input produces a line of output.} } % We *must* turn on hyphenation at `-' and `_' in \code. -% Otherwise, it is too hard to avoid overful hboxes +% Otherwise, it is too hard to avoid overfull hboxes % in the Emacs manual, the Library manual, etc. % Unfortunately, TeX uses one parameter (\hyphenchar) to control @@ -1157,6 +1234,7 @@ where each line of input produces a line of output.} % ever called. -- mycroft \global\def\indexbreaks{\catcode`\-=\active \let-\realdash \catcode`\_=\active \let_\realunder} } + \def\realdash{-} \def\realunder{_} \def\codedash{-\discretionary{}{}{}} @@ -1167,12 +1245,19 @@ where each line of input produces a line of output.} % @kbd is like @code, except that if the argument is just one @key command, % then @kbd has no effect. - +% \def\xkey{\key} \def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% \ifx\one\xkey\ifx\threex\three \key{#2}% -\else\tclose{\look}\fi -\else\tclose{\look}\fi} +\else{\tclose{\ttsl\look}}\fi +\else{\tclose{\ttsl\look}}\fi} + +% Check if we are currently using a typewriter font. Since all the +% Computer Modern typewriter fonts have zero interword stretch (and +% shrink), and it is reasonable to expect all typewriter fonts to have +% this property, we can check that font parameter. +% +\def\ifmonospace{\ifdim\fontdimen3\font=0pt } % Typeset a dimension, e.g., `in' or `pt'. The only reason for the % argument is to make the input look right: @dmn{pt} instead of @@ -1437,7 +1522,7 @@ July\or August\or September\or October\or November\or December\fi \newif\ifitemxneedsnegativevskip -\def\itemxpar{\par\ifitemxneedsnegativevskip\vskip-\parskip\nobreak\fi} +\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} \def\internalBitem{\smallbreak \parsearg\itemzzz} \def\internalBitemx{\itemxpar \parsearg\itemzzz} @@ -1544,7 +1629,7 @@ July\or August\or September\or October\or November\or December\fi \def\tablez #1#2#3#4#5#6{% \aboveenvbreak % \begingroup % -\def\Edescription{\Etable}% Neccessary kludge. +\def\Edescription{\Etable}% Necessary kludge. \let\itemindex=#1% \ifnum 0#3>0 \advance \leftskip by #3\mil \fi % \ifnum 0#4>0 \tableindent=#4\mil \fi % @@ -1708,10 +1793,10 @@ July\or August\or September\or October\or November\or December\fi \flushcr} % @multitable macros -% Amy Hendrickson, 8/18/94 +% Amy Hendrickson, 8/18/94, 3/6/96 % -% @multitable ... @endmultitable will make as many columns as desired. -% Contents of each column will wrap at width given in preamble. Width +% @multitable ... @end multitable will make as many columns as desired. +% Contents of each column will wrap at width given in preamble. Width % can be specified either with sample text given in a template line, % or in percent of \hsize, the current width of text on page. @@ -1720,10 +1805,10 @@ July\or August\or September\or October\or November\or December\fi % To make preamble: % % Either define widths of columns in terms of percent of \hsize: -% @multitable @percentofhsize .2 .3 .5 +% @multitable @columnfractions .25 .3 .45 % @item ... % -% Numbers following @percentofhsize are the percent of the total +% Numbers following @columnfractions are the percent of the total % current hsize to be used for each column. You may use as many % columns as desired. @@ -1731,7 +1816,16 @@ July\or August\or September\or October\or November\or December\fi % @multitable {Column 1 template} {Column 2 template} {Column 3 template} % @item ... % using the widest term desired in each column. - +% +% For those who want to use more than one line's worth of words in +% the preamble, break the line within one argument and it +% will parse correctly, i.e., +% +% @multitable {Column 1 template} {Column 2 template} {Column 3 +% template} +% Not: +% @multitable {Column 1 template} {Column 2 template} +% {Column 3 template} % Each new table line starts with @item, each subsequent new column % starts with @tab. Empty columns may be produced by supplying @tab's @@ -1756,71 +1850,84 @@ July\or August\or September\or October\or November\or December\fi % % They will wrap at the width determined by the template. % @item@tab@tab This will be in third column. -% @endmultitable +% @end multitable % Default dimensions may be reset by user. -% @intableparskip will set vertical space between paragraphs in table. -% @intableparindent will set paragraph indent in table. -% @spacebetweencols will set horizontal space to be left between columns. -% @spacebetweenlines will set vertical space to be left between lines. +% @multitableparskip is vertical space between paragraphs in table. +% @multitableparindent is paragraph indent in table. +% @multitablecolmargin is horizontal space to be left between columns. +% @multitablelinespace is space to leave between table items; +% 0 means it depends on current normal line spacing. %%%% % Dimensions -\newdimen\intableparskip -\newdimen\intableparindent -\newdimen\spacebetweencols -\newdimen\spacebetweenlines -\intableparskip=0pt -\intableparindent=6pt -\spacebetweencols=12pt -\spacebetweenlines=12pt +\newskip\multitableparskip +\newskip\multitableparindent +\newdimen\multitablecolspace +\newskip\multitablelinespace +\multitableparskip=0pt +\multitableparindent=6pt +\multitablecolspace=12pt +\multitablelinespace=0pt %%%% % Macros used to set up halign preamble: \let\endsetuptable\relax \def\xendsetuptable{\endsetuptable} -\let\percentofhsize\relax -\def\xpercentofhsize{\percentofhsize} +\let\columnfractions\relax +\def\xcolumnfractions{\columnfractions} \newif\ifsetpercent +%% 2/1/96, to allow fractions to be given with more than one digit. +\def\pickupwholefraction#1 {\global\advance\colcount by1 % +\expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% +\setuptable} + \newcount\colcount \def\setuptable#1{\def\firstarg{#1}% \ifx\firstarg\xendsetuptable\let\go\relax% \else - \ifx\firstarg\xpercentofhsize\global\setpercenttrue% + \ifx\firstarg\xcolumnfractions\global\setpercenttrue% \else \ifsetpercent - \if#1.\else% - \global\advance\colcount by1 % - \expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% - \fi + \let\go\pickupwholefraction % In this case arg of setuptable + % is the decimal point before the + % number given in percent of hsize. + % We don't need this so we don't use it. \else \global\advance\colcount by1 \setbox0=\hbox{#1}% \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% \fi% \fi% - \let\go\setuptable% +\ifx\go\pickupwholefraction\else\let\go\setuptable\fi% \fi\go} + %%%% % multitable syntax -\def\tab{&} +\def\tab{&\hskip1sp\relax} % 2/2/96 + % tiny skip here makes sure this column space is + % maintained, even if it is never used. + %%%% -% @multitable ... @endmultitable definitions: +% @multitable ... @end multitable definitions: -\def\multitable#1\item{\bgroup +\def\multitable{\parsearg\dotable} + +\def\dotable#1{\bgroup \let\item\cr \tolerance=9500 \hbadness=9500 -\parskip=\intableparskip -\parindent=\intableparindent +\setmultitablespacing +\parskip=\multitableparskip +\parindent=\multitableparindent \overfullrule=0pt \global\colcount=0\relax% \def\Emultitable{\global\setpercentfalse\global\everycr{}\cr\egroup\egroup}% % To parse everything between @multitable and @item : -\def\one{#1}\expandafter\setuptable\one\endsetuptable +\setuptable#1 \endsetuptable % Need to reset this to 0 after \setuptable. \global\colcount=0\relax% % @@ -1831,9 +1938,9 @@ July\or August\or September\or October\or November\or December\fi \halign\bgroup&\global\advance\colcount by 1\relax% \vtop{\hsize=\expandafter\csname col\the\colcount\endcsname % In order to keep entries from bumping into each other - % we will add a \leftskip of \spacebetweencols to all columns after + % we will add a \leftskip of \multitablecolspace to all columns after % the first one. - % If a template has been used, we will add \spacebetweencols + % If a template has been used, we will add \multitablecolspace % to the width of each template entry. % If user has set preamble in terms of percent of \hsize % we will use that dimension as the width of the column, and @@ -1845,21 +1952,42 @@ July\or August\or September\or October\or November\or December\fi \ifsetpercent \else % If user has set preamble in terms of percent of \hsize - % we will advance \hsize by \spacebetweencols - \advance\hsize by \spacebetweencols + % we will advance \hsize by \multitablecolspace + \advance\hsize by \multitablecolspace \fi - % In either case we will make \leftskip=\spacebetweencols: -\leftskip=\spacebetweencols + % In either case we will make \leftskip=\multitablecolspace: +\leftskip=\multitablecolspace \fi -\noindent##}\cr% +\noindent##%\par +%\vskip\multitablelinespace +}\cr% % \everycr will reset column counter, \colcount, at the end of % each line. Every column entry will cause \colcount to advance by one. % The table preamble % looks at the current \colcount to find the correct column width. -\global\everycr{\noalign{\nointerlineskip\vskip\spacebetweenlines +\global\everycr{\noalign{\nointerlineskip\vskip\multitablelinespace \filbreak%% keeps underfull box messages off when table breaks over pages. \global\colcount=0\relax}}} +\def\setmultitablespacing{% test to see if user has set \multitablelinespace. +% If so, do nothing. If not, give it an appropriate dimension based on +% current baselineskip. +\ifdim\multitablelinespace=0pt +\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip +\global\advance\multitablelinespace by-\ht0\fi +%% Test to see if parskip is larger than space between lines of +%% table. If not, do nothing. +%% If so, set to same dimension as multitablelinespace. +\ifdim\multitableparskip>\multitablelinespace +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi% +\ifdim\multitableparskip=0pt +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi} \message{indexing,} % Index generation facilities @@ -1988,8 +2116,15 @@ July\or August\or September\or October\or November\or December\fi \def\kbd##1{\realbackslash kbd {##1}}% \def\dfn##1{\realbackslash dfn {##1}}% \def\emph##1{\realbackslash emph {##1}}% +\unsepspaces } +% If an index command is used in an @example environment, any spaces +% therein should become regular spaces in the raw index file, not the +% expansion of \tie (\\leavevmode \penalty \@M \ ). +{\obeyspaces + \gdef\unsepspaces{\obeyspaces\let =\space}} + % \indexnofonts no-ops all font-change commands. % This is used when outputting the strings to sort the index by. \def\indexdummyfont#1{#1} @@ -2240,7 +2375,7 @@ July\or August\or September\or October\or November\or December\fi % % Insert the text of the index entry. TeX will do line-breaking on it. #1% - % The following is kluged to not output a line of dots in the index if + % The following is kludged to not output a line of dots in the index if % there are no page numbers. The next person who breaks this will be % cursed by a Unix daemon. \def\tempa{{\rm }}% @@ -2578,7 +2713,7 @@ July\or August\or September\or October\or November\or December\fi \penalty 10000 % }} -\outer\def\appenixsection{\parsearg\appendixsecyyy} +\outer\def\appendixsection{\parsearg\appendixsecyyy} \outer\def\appendixsec{\parsearg\appendixsecyyy} \def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz \def\appendixsectionzzz #1{\seccheck{appendixsection}% @@ -3010,9 +3145,10 @@ July\or August\or September\or October\or November\or December\fi % can't do that in the \entry macro, since index entries might consist % of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.) % +% \turnoffactive is for the sake of @" used for umlauts. \def\tocentry#1#2{\begingroup \hyphenpenalty = 10000 - \entry{#1}{#2}% + \entry{\turnoffactive #1}{\turnoffactive #2}% \endgroup} % Space between chapter (or whatever) number and the title. @@ -3836,7 +3972,10 @@ July\or August\or September\or October\or November\or December\fi \setbox0=\hbox{\printednodename}% \ifdim \wd0 = 0pt % No printed node name was explicitly given. - \ifx\SETxref-automatic-section-title\relax % + \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax + % Use the node name inside the square brackets. + \def\printednodename{\ignorespaces #1}% + \else % Use the actual chapter/section title appear inside % the square brackets. Use the real section title if we have it. \ifdim \wd1>0pt% @@ -3845,16 +3984,12 @@ July\or August\or September\or October\or November\or December\fi \else \ifhavexrefs % We know the real title if we have the xref values. - \def\printednodename{\refx{#1-title}}% + \def\printednodename{\refx{#1-title}{}}% \else % Otherwise just copy the Info node name. \def\printednodename{\ignorespaces #1}% \fi% \fi - \def\printednodename{#1-title}% - \else - % Use the node name inside the square brackets. - \def\printednodename{\ignorespaces #1}% \fi \fi % @@ -4240,11 +4375,13 @@ July\or August\or September\or October\or November\or December\fi } % Allow control of the text dimensions. Parameters in order: textheight; -% textwidth; \voffset; \hoffset (!); binding offset. All require a dimension; +% textwidth; voffset; hoffset; binding offset; topskip. +% All require a dimension; % header is additional; added length extends the bottom of the page. -\def\changepagesizes#1#2#3#4#5{ +\def\changepagesizes#1#2#3#4#5#6{ \global\vsize= #1 + \global\topskip= #6 \advance\vsize by \topskip \global\voffset= #3 \global\hsize= #2 @@ -4257,13 +4394,20 @@ July\or August\or September\or October\or November\or December\fi \global\normaloffset= #4 \global\bindingoffset= #5} -% This layout is compatible with Latex on A4 paper. - -\def\afourlatex{\changepagesizes{22cm}{15cm}{7mm}{4.6mm}{5mm}} +% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin +% 29mm, hence bottom margin 28mm, nominal side margin 3cm. +\def\afourlatex + {\global\tolerance=700 + \global\hfuzz=1pt + \setleading{12pt} + \global\parskip 15pt plus 1pt + \advance\baselineskip by 1.6pt + \changepagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm} + } % Use @afourwide to print on European A4 paper in wide format. \def\afourwide{\afourpaper -\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}} +\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}} % Define macros to output various characters with catcode for normal text. \catcode`\"=\other @@ -4312,14 +4456,7 @@ July\or August\or September\or October\or November\or December\fi \catcode`\_=\active \def_{\ifusingtt\normalunderscore\_} % Subroutine for the previous macro. -\def\_{\lvvmode \kern.06em \vbox{\hrule width.3em height.1ex}} - -% \lvvmode is equivalent in function to \leavevmode. -% Using \leavevmode runs into trouble when written out to -% an index file due to the expansion of \leavevmode into ``\unhbox -% \voidb@x'' ---which looks to TeX like ``\unhbox \voidb\x'' due to our -% magic tricks with @. -\def\lvvmode{\vbox to 0pt{}} +\def\_{\leavevmode \kern.06em \vbox{\hrule width.3em height.1ex}} \catcode`\|=\active \def|{{\tt \char '174}}