From: Mark Eichin Date: Thu, 30 Jun 1994 23:09:56 +0000 (+0000) Subject: autoconf-1.11 base X-Git-Tag: krb5-1.0-beta4.2~182 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=bcb453d9de5333f997c049f1afb4f9806e69a661;p=krb5.git autoconf-1.11 base git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@3928 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/src/util/autoconf/NEWS b/src/util/autoconf/NEWS new file mode 100644 index 000000000..982a81f92 --- /dev/null +++ b/src/util/autoconf/NEWS @@ -0,0 +1,152 @@ +Major changes in release 1.11: + +* AC_PROG_INSTALL calls install.sh with the -c option. +* AC_SET_MAKE cleans up after itself. +* AC_OUTPUT sets prefix and exec_prefix if they weren't set already. +* AC_OUTPUT prevents shells from looking in PATH for config.status. + +Plus a few other bug fixes. + +Major changes in release 1.10: + +* autoheader uses config.h.bot if present, analogous to config.h.top. +* AC_PROG_INSTALL looks for install.sh in srcdir or srcdir/.. or + srcdir/../.. and never uses cp. +* AC_PROG_CXX looks for cxx as a C++ compiler. + +Plus several bugs fixed. + +Major changes in release 1.9: + +* AC_YYTEXT_POINTER replaces AC_DECLARE_YYTEXT. +* AC_SIZEOF_TYPE generates the cpp symbol name automatically, + and autoheader generates entries for those names automatically. +* AC_FIND_X gets the result from xmkmf correctly. +* AC_FIND_X assumes no X if --without-x was given. +* AC_FIND_XTRA adds libraries to the variable X_EXTRA_LIBS. +* AC_PROG_INSTALL finds OSF/1 installbsd. + +Major changes in release 1.8: + +** New macros: +* New macros AC_LANG_C, AC_LANG_CPLUSPLUS, AC_LANG_SAVE, AC_LANG_RESTORE, + AC_PROG_CXX, AC_PROG_CXXCPP, AC_REQUIRE_CPP + for checking both C++ and C features in one configure script. +* New macros AC_CHECKING, AC_VERBOSE, AC_WARN, AC_ERROR for printing messages. +* New macros AC_FIND_XTRA, AC_MMAP, AC_SIZEOF_TYPE, AC_PREREQ, + AC_SET_MAKE, AC_ENABLE. + +** Changed macros: +* AC_FIND_X looks for X in more places. +* AC_PROG_INSTALL defaults to install.sh instead of cp, if it's in srcdir. + install.sh is distributed with Autoconf. +* AC_DECLARE_YYTEXT has been removed because it can't work, pending + a rewrite of quoting in AC_DEFINE. +* AC_OUTPUT adds its comments in C format when substituting in C files. +* AC_COMPILE_CHECK protects its ECHO-TEXT argument with double quotes. + +** New or changed command line options: +* configure accepts --enable-FEATURE[=ARG] and --disable-FEATURE options. +* configure accepts --without-PACKAGE, which sets withval=no. +* configure accepts --x-includes=DIR and --x-libraries=DIR. +* Giving --with-PACKAGE no argument sets withval=yes instead of withval=1. +* configure accepts --help, --version, --silent/--quiet, --no-create options. +* configure accepts and ignores most other Cygnus configure options, and + warns about unknown options. +* config.status accepts --help, --version options. + +** Paths and other changes: +* Relative srcdir values are not made absolute. +* The values of @prefix@ and @exec_prefix@ and @top_srcdir@ get substituted. +* Autoconf library files are installed in ${datadir}/autoconf, not ${datadir}. +* autoheader optionally copies config.h.top to the beginning of config.h.in. +* The example Makefile dependencies for configure et al. work better. +* Namespace cleanup: all shell variables used internally by Autoconf + have names beginning with `ac_'. + +More big improvements are in process for future releases, but have not +yet been (variously) finished, integrated, tested, or documented enough +to release yet. + +Major changes in release 1.7: + +* New macro AC_OBSOLETE. +* Bugs in Makefile.in fixed. +* AC_LONG_FILE_NAMES improved. + +Major changes in release 1.6: + +* New macro AC_LONG_64_BITS. +* Multiple .h files can be created. +* AC_FIND_X looks for X files directly if it doesn't find xmkmf. +* AC_ALLOCA defines C_ALLOCA if using alloca.c. +* --with-NAME can take a value, e.g., --with-targets=sun4,hp300bsd. +* Unused --no-create option to configure removed. +* autoheader doesn't change the timestamp of its output file if + the file didn't change. +* All macros that look for libraries now use AC_HAVE_LIBRARY. +* config.status checks three optional environment variables to + modify its behavior. +* The usual bug fixes. + +Major changes in release 1.5: + +* New macros AC_FIND_X, AC_OFF_T, AC_STAT_MACROS_BROKEN, AC_REVISION. +* autoconf and autoheader scripts have GNU standards conforming + --version and --help options (they print their message and exit). +* Many bug fixes. + +Major changes in release 1.4: + +* New macros AC_HAVE_POUNDBANG, AC_TIME_WITH_SYS_TIME, AC_LONG_DOUBLE, + AC_GETGROUPS_T, AC_DEFINE_UNQUOTED. +* autoconf and autoheader use the M4 environment variable to determine the + path of the m4 program to use. +* The --macrodir option to autoconf and autoheader specifies the directory + in which acspecific.m4, acgeneral.m4, etc. reside if not the default. +* autoconf and autoheader can take `-' as their file names, which means to + read stdin as input. +* Resulting configure scripts can take a --verbose option which causes them + to print the results of their tests. +* AC_DEFINE quotes its second argument in such a way that spaces, magic + shell characters, etc. will be preserved during various stages of + expansion done by the shell. If you don't want this, use + AC_DEFINE_UNQUOTED instead. +* Much textual processing done with external calls to tr and sed have been + internalized with builtin m4 `patsubst' and `translit' calls. +* AC_OUTPUT doesn't hardwire the filenames it outputs. Instead, you can + 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. +* AC_PROGRAMS_CHECK takes an optional third arg. If given, it is used as + 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. + +Major changes in release 1.3: + +configure no longer requires awk for packages that use a config.h. +Support handling --with-PACKAGE options. +New `autoheader' script to create `config.h.in' from `configure.in'. +Ignore troublesome -lucb and -lPW when searching for alloca. +Rename --exec_prefix to --exec-prefix for GNU standards conformance. +Improve detection of STDC library. +Add AC_HAVE_LIBRARY to check for non-default libraries. +Function checking should work with future GNU libc releases. + +Major changes in release 1.2: + +The --srcdir option is now usually unnecessary. +Add a file containing sample comments describing CPP macros. +A comment in config.status tells which host it was configured on. +Substituted variable values can now contain commas. +Fix bugs in various feature checks. + +Major changes in release 1.1: + +Added AC_STRCOLL macro. +Made AC_GETLOADAVG check for more things. +AC_OUTPUT argument is now optional. +Various bug fixes. diff --git a/src/util/autoconf/README b/src/util/autoconf/README new file mode 100644 index 000000000..2cc58e295 --- /dev/null +++ b/src/util/autoconf/README @@ -0,0 +1,30 @@ +Autoconf -- generate automatic software configuration scripts from templates + +Autoconf is an extensible package of m4 macros that produce shell +scripts to automatically configure software source code packages. +These scripts can adapt the packages to many kinds of UNIX-like +systems without manual user intervention. Autoconf creates a +configuration script for a package from a template file that lists the +operating system features that the package can use, in the form of m4 +macro calls. + +Autoconf requires GNU m4. The configuration scripts produced by +Autoconf are independent of Autoconf when they are run, so their users +do not need to have Autoconf (or GNU m4). + +The file INSTALL can be distributed with packages that use +Autoconf-generated configure scripts and Makefiles that conform to the +GNU coding standards. The package's README can just give an overview +of the package, where to report bugs, and a pointer to INSTALL for +instructions on compilation and installation. This removes the need +to maintain many similar sets of installation instructions. + +The file `acconfig.h' contains short descriptions of the C preprocessor +variables that Autoconf can define, suitable for copying into other +packages' configuration headers or Makefile.in files. You can use the +program `autoheader' to automatically creates a configuration header +from a `configure.in', based on the information in `acconfig.h'. + +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". diff --git a/src/util/autoconf/acconfig.h b/src/util/autoconf/acconfig.h new file mode 100644 index 000000000..97e976fa8 --- /dev/null +++ b/src/util/autoconf/acconfig.h @@ -0,0 +1,255 @@ +/* acconfig.h + This file is in the public domain. + + Descriptive text for the C preprocessor macros that + the distributed Autoconf macros can define. + No software package will use all of them; autoheader copies the ones + your configure.in uses into your configuration header file templates. + + The entries are in sort -df order: alphabetical, case insensitive, + ignoring punctuation (such as underscores). Although this order + can split up related entries, it makes it easier to check whether + a given entry is in the file. + + Leave the following blank line there!! Autoheader needs it. */ + + +/* Define if on AIX 3. + System headers sometimes define this. + We just want to avoid a redefinition error message. */ +#ifndef _ALL_SOURCE +#undef _ALL_SOURCE +#endif + +/* Define if using alloca.c. */ +#undef C_ALLOCA + +/* Define if type char is unsigned and you are not using gcc. */ +#undef __CHAR_UNSIGNED__ + +/* Define to empty if the keyword does not work. */ +#undef const + +/* Define to one of _getb67, GETB67, getb67 for Cray-2 and Cray-YMP systems. + This function is required for alloca.c support on those systems. */ +#undef CRAY_STACKSEG_END + +/* Define for DGUX with . */ +#undef DGUX + +/* Define if you have dirent.h. */ +#undef DIRENT + +/* Define to the type of elements in the array set by `getgroups'. + Usually this is either `int' or `gid_t'. */ +#undef GETGROUPS_T + +/* Define if the `getloadavg' function needs to be run setuid or setgid. */ +#undef GETLOADAVG_PRIVILEGED + +/* Define to `int' if doesn't define. */ +#undef gid_t + +/* Define if you have alloca.h and it should be used (not Ultrix). */ +#undef HAVE_ALLOCA_H + +/* Define if you don't have vprintf but do have _doprnt. */ +#undef HAVE_DOPRNT + +/* Define if your system has its own `getloadavg' function. */ +#undef HAVE_GETLOADAVG + +/* Define if the `long double' type works. */ +#undef HAVE_LONG_DOUBLE + +/* Define if you support file names longer than 14 characters. */ +#undef HAVE_LONG_FILE_NAMES + +/* Define if you have a working `mmap' system call. */ +#undef HAVE_MMAP + +/* Define if you have netdb.h (and thus the rexec function). */ +#undef HAVE_NETDB_H + +/* Define if system calls automatically restart after interruption + by a signal. */ +#undef HAVE_RESTARTABLE_SYSCALLS + +/* Define if your struct stat has st_blksize. */ +#undef HAVE_ST_BLKSIZE + +/* Define if your struct stat has st_blocks. */ +#undef HAVE_ST_BLOCKS + +/* Define if you have the strcoll function and it is properly defined. */ +#undef HAVE_STRCOLL + +/* Define if your struct stat has st_rdev. */ +#undef HAVE_ST_RDEV + +/* Define if you have sys/mtio.h. */ +#undef HAVE_SYS_MTIO_H + +/* Define if you have a with `union wait'. */ +#undef HAVE_SYS_WAIT + +/* Define if your struct tm has tm_zone. */ +#undef HAVE_TM_ZONE + +/* Define if you don't have tm_zone but do have the external array + tzname. */ +#undef HAVE_TZNAME + +/* Define if `union wait' is the type of the first arg to wait functions. */ +#undef HAVE_UNION_WAIT + +/* Define if you have unistd.h. */ +#undef HAVE_UNISTD_H + +/* Define if utime(file, NULL) sets file's timestamp to the present. */ +#undef HAVE_UTIME_NULL + +/* Define if you have vfork.h. */ +#undef HAVE_VFORK_H + +/* Define if you have the vprintf function. */ +#undef HAVE_VPRINTF + +/* Define if you have the wait3 system call. */ +#undef HAVE_WAIT3 + +/* Define if you have the POSIX.1 `waitpid' function. */ +#undef HAVE_WAITPID + +/* Define as __inline if that's what the C compiler calls it. */ +#undef inline + +/* Define if int is 16 bits instead of 32. */ +#undef INT_16_BITS + +/* Define if long int is 64 bits. */ +#undef LONG_64_BITS + +/* Define if major, minor, and makedev are declared in mkdev.h. */ +#undef MAJOR_IN_MKDEV + +/* Define if major, minor, and makedev are declared in sysmacros.h. */ +#undef MAJOR_IN_SYSMACROS + +/* Define if on MINIX. */ +#undef _MINIX + +/* Define to `int' if doesn't define. */ +#undef mode_t + +/* Define if you don't have dirent.h, but have ndir.h. */ +#undef NDIR + +/* Define if you have memory.h, and string.h doesn't declare the + mem* functions. */ +#undef NEED_MEMORY_H + +/* Define if your struct nlist has an n_un member. */ +#undef NLIST_NAME_UNION + +/* Define if you have nlist.h. */ +#undef NLIST_STRUCT + +/* Define if you can't use the address of an argument to a function + as the start of an array. */ +#undef NO_ARG_ARRAY + +/* Define if your C compiler doesn't accept -c and -o together. */ +#undef NO_MINUS_C_MINUS_O + +/* Define if you have neither a remote shell nor the rexec function. */ +#undef NO_REMOTE + +/* Define to `long' if doesn't define. */ +#undef off_t + +/* Define to `int' if doesn't define. */ +#undef pid_t + +/* Define if the system does not provide POSIX.1 features except + with this defined. */ +#undef _POSIX_1_SOURCE + +/* Define if you need to in order for stat and other things to work. */ +#undef _POSIX_SOURCE + +/* Define as the return type of signal handlers (int or void). */ +#undef RETSIGTYPE + +/* Define if the setvbuf function takes the buffering type as its second + argument and the buffer pointer as the third, as on System V + before release 3. */ +#undef SETVBUF_REVERSED + +/* Define to `unsigned' if doesn't define. */ +#undef size_t + +/* If using the C implementation of alloca, define if you know the + direction of stack growth for your system; otherwise it will be + automatically deduced at run-time. + STACK_DIRECTION > 0 => grows toward higher addresses + STACK_DIRECTION < 0 => grows toward lower addresses + STACK_DIRECTION = 0 => direction of growth unknown + */ +#undef STACK_DIRECTION + +/* Define if the `S_IS*' macros in do not work properly. */ +#undef STAT_MACROS_BROKEN + +/* Define if you have the ANSI C header files. */ +#undef STDC_HEADERS + +/* Define on System V Release 4. */ +#undef SVR4 + +/* Define if you don't have dirent.h, but have sys/dir.h. */ +#undef SYSDIR + +/* Define if you don't have dirent.h, but have sys/ndir.h. */ +#undef SYSNDIR + +/* Define if `sys_siglist' is declared by . */ +#undef SYS_SIGLIST_DECLARED + +/* Define if you can safely include both and . */ +#undef TIME_WITH_SYS_TIME + +/* Define if your declares struct tm. */ +#undef TM_IN_SYS_TIME + +/* Define to `int' if doesn't define. */ +#undef uid_t + +/* Define for Encore UMAX. */ +#undef UMAX + +/* Define for Encore UMAX 4.3 that has + instead of . */ +#undef UMAX4_3 + +/* Define if you do not have strings.h, index, bzero, etc.. */ +#undef USG + +/* Define vfork as fork if vfork does not work. */ +#undef vfork + +/* Define if the closedir function returns void instead of int. */ +#undef VOID_CLOSEDIR + +/* Define if your processor stores words with the most significant + byte first (like Motorola and SPARC, unlike Intel and VAX). */ +#undef WORDS_BIGENDIAN + +/* Define if lex declares yytext as a char * by default, not a char[]. */ +#undef YYTEXT_POINTER + + +/* Leave that blank line there!! Autoheader needs it. + If you're adding to this file, keep in mind: + The entries are in sort -df order: alphabetical, case insensitive, + ignoring punctuation (such as underscores). */ diff --git a/src/util/autoconf/acgeneral.m4 b/src/util/autoconf/acgeneral.m4 new file mode 100644 index 000000000..b2dfbf2fd --- /dev/null +++ b/src/util/autoconf/acgeneral.m4 @@ -0,0 +1,1174 @@ +dnl Parameterized macros that do not check for something specific. +dnl This file is part of Autoconf. +dnl Copyright (C) 1992, 1993, 1994 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 +dnl the Free Software Foundation; either version 2, or (at your option) +dnl any later version. +dnl +dnl This program is distributed in the hope that it will be useful, +dnl but WITHOUT ANY WARRANTY; without even the implied warranty of +dnl MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +dnl GNU General Public License for more details. +dnl +dnl You should have received a copy of the GNU General Public License +dnl along with this program; if not, write to the Free Software +dnl Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +dnl +dnl Written by David MacKenzie, with help from +dnl Franc,ois Pinard, Karl Berry, Richard Pixley, Ian Lance Taylor, +dnl Roland McGrath, Noah Friedman, and david d zuhn. +dnl +changequote([,])dnl +undefine([eval])dnl +undefine([include])dnl +undefine([shift])dnl +undefine([format])dnl +dnl +ifdef([__gnu__], , [errprint(Autoconf requires GNU m4 +)m4exit(2)])dnl +dnl +dnl +dnl Utility functions for stamping the configure script. +dnl +dnl +define(AC_ACVERSION, 1.11)dnl +dnl This is defined by the --version option of the autoconf script. +ifdef([AC_PRINT_VERSION], [errprint(Autoconf version AC_ACVERSION +)])dnl +dnl +dnl These are currently not used, for the sake of people who diff +dnl configure scripts and don't want spurious differences. +dnl But they are too clever to just delete. +dnl +define(AC_USER, [esyscmd( +changequote({,})dnl +# Extract the user name from the first pair of parentheses. +({ac_sedcmd='s/[^(]*(\([^)]*\)).*/\1/';} +changequote([,])dnl +whoami || id|sed "$ac_sedcmd") 2>/dev/null|tr -d '\012')])dnl +dnl +define(AC_HOST, [esyscmd((hostname || uname -n) 2>/dev/null|tr -d '\012')])dnl +dnl +define(AC_DATE, [esyscmd(date|tr -d '\012')])dnl +dnl +dnl +dnl Controlling Autoconf operation +dnl +dnl +dnl This is separate from AC_INIT to prevent GNU m4 1.0 from coredumping +dnl when AC_CONFIG_HEADER is used. +define(AC_NOTICE, +[# Guess values for system-dependent variables and create Makefiles. +dnl [#] Generated automatically using autoconf. +# Generated automatically using autoconf version] AC_ACVERSION [ +dnl [#] by AC_USER@AC_HOST on AC_DATE +# Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc. + +# This configure script is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License as published +# by the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This script is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General +# Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +])dnl +dnl +define(AC_PARSEARGS, +[# Save the original args to write them into config.status later. +configure_args="[$]*" + +# Only options that might do something get documented. +changequote(,)dnl +ac_usage="Usage: configure [options] [host] +Options: [defaults in brackets after descriptions] +--build=BUILD configure for building on BUILD [BUILD=HOST] +--disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) +--enable-FEATURE[=ARG] include FEATURE [ARG=yes] +--exec-prefix=PREFIX install host dependent files in PREFIX [/usr/local] +--help print this message +--host=HOST configure for HOST [guessed] +--prefix=PREFIX install host independent files in PREFIX [/usr/local] +--quiet, --silent do not print \`checking for...' messages +--srcdir=DIR find the sources in DIR [configure dir or ..] +--target=TARGET configure for TARGET [TARGET=HOST] +--verbose print results of checks +--version print the version of autoconf that created configure +--with-PACKAGE[=ARG] use PACKAGE [ARG=yes] +--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" +changequote([,])dnl + +# Initialize some variables set by options. +# The variables have the same names as the options, with +# dashes changed to underlines. +build=NONE +exec_prefix= +host=NONE +no_create= +nonopt=NONE +norecursion= +prefix= +program_prefix= +program_suffix= +program_transform_name= +silent= +srcdir= +target=NONE +verbose= +x_includes= +x_libraries= + +ac_prev= +for ac_option +do + + # If the previous option needs an argument, assign it. + if test -n "$ac_prev"; then + eval "$ac_prev=\$ac_option" + ac_prev= + continue + fi + + # Accept (but ignore some of) the important Cygnus configure + # options, so we can diagnose typos. + + case "$ac_option" in +changequote(,)dnl + -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; +changequote([,])dnl + *) ac_optarg= ;; + esac + + case "$ac_option" in + + -build | --build | --buil | --bui | --bu | --b) + ac_prev=build ;; + -build=* | --build=* | --buil=* | --bui=* | --bu=* | --b=*) + build="$ac_optarg" ;; + + -disable-* | --disable-*) + ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` + # Reject names that aren't valid shell variable names. +changequote(,)dnl + if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then +changequote([,])dnl + AC_ERROR($ac_feature: invalid feature name) + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + eval "enable_${ac_feature}=no" ;; + + -enable-* | --enable-*) + ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` + # Reject names that aren't valid shell variable names. +changequote(,)dnl + if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then +changequote([,])dnl + AC_ERROR($ac_feature: invalid feature name) + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "enable_${ac_feature}='$ac_optarg'" ;; + + # For backward compatibility, recognize -exec-prefix and --exec_prefix. + -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ + | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ + | --exec | --exe | --ex) + ac_prev=exec_prefix ;; + -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ + | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ + | --exec=* | --exe=* | --ex=*) + exec_prefix="$ac_optarg" ;; + + -gas | --gas | --ga | --g) + with_gas=yes ;; # Obsolete; use --with-gas. + + -help | --help | --hel | --he) + cat << EOF +$ac_usage +EOF + exit 0 ;; + + -host | --host | --hos | --ho) + ac_prev=host ;; + -host=* | --host=* | --hos=* | --ho=*) + host="$ac_optarg" ;; + + -nfp | --nfp | --nf) + with_fp=no ;; # Obsolete; use --without-fp. + + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) + no_create=yes ;; + + -norecursion | --norecursion | --norecursio | --norecursi \ + | --norecurs | --norecur | --norecu | --norec | --nore | --nor) + norecursion=yes ;; + + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) + ac_prev=prefix ;; + -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) + prefix="$ac_optarg" ;; + + -program-prefix | --program-prefix | --program-prefi | --program-pref \ + | --program-pre | --program-pr | --program-p) + ac_prev=program_prefix ;; + -program-prefix=* | --program-prefix=* | --program-prefi=* \ + | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) + program_prefix="$ac_optarg" ;; + + -program-suffix | --program-suffix | --program-suffi | --program-suff \ + | --program-suf | --program-su | --program-s) + ac_prev=program_suffix ;; + -program-suffix=* | --program-suffix=* | --program-suffi=* \ + | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) + program_suffix="$ac_optarg" ;; + + -program-transform-name | --program-transform-name \ + | --program-transform-nam | --program-transform-na \ + | --program-transform-n | --program-transform- \ + | --program-transform | --program-transfor \ + | --program-transfo | --program-transf \ + | --program-trans | --program-tran \ + | --progr-tra | --program-tr | --program-t) + ac_prev=program_transform_name ;; + -program-transform-name=* | --program-transform-name=* \ + | --program-transform-nam=* | --program-transform-na=* \ + | --program-transform-n=* | --program-transform-=* \ + | --program-transform=* | --program-transfor=* \ + | --program-transfo=* | --program-transf=* \ + | --program-trans=* | --program-tran=* \ + | --progr-tra=* | --program-tr=* | --program-t=*) + program_transform_name="$ac_optarg" ;; + + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + silent=yes ;; + + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) + ac_prev=srcdir ;; + -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) + srcdir="$ac_optarg" ;; + + -target | --target | --targe | --targ | --tar | --ta | --t) + ac_prev=target ;; + -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) + target="$ac_optarg" ;; + + -v | -verbose | --verbose | --verbos | --verbo | --verb) + verbose=yes ;; + + -version | --version | --versio | --versi | --vers) + echo "configure generated by autoconf version AC_ACVERSION" + exit 0 ;; + + -with-* | --with-*) + ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` + # Reject names that aren't valid shell variable names. +changequote(,)dnl + if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then +changequote([,])dnl + AC_ERROR($ac_package: invalid package name) + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "with_${ac_package}='$ac_optarg'" ;; + + -without-* | --without-*) + ac_package=`echo $ac_option|sed -e 's/-*without-//'` + # Reject names that aren't valid shell variable names. +changequote(,)dnl + if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then +changequote([,])dnl + AC_ERROR($ac_package: invalid package name) + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + eval "with_${ac_package}=no" ;; + + --x) with_x=yes ;; # Obsolete; use --with-x. + + -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ + | --x-incl | --x-inc | --x-in | --x-i) + ac_prev=x_includes ;; + -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ + | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) + x_includes="$ac_optarg" ;; + + -x-libraries | --x-libraries | --x-librarie | --x-librari \ + | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) + ac_prev=x_libraries ;; + -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ + | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) + x_libraries="$ac_optarg" ;; + + -*) AC_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 + AC_WARN($ac_option: invalid host type) + fi + if test "x$nonopt" != xNONE; then + AC_ERROR(can only configure for one host and one target at a time) + fi + nonopt="$ac_option" + ;; + + esac +done + +if test -n "$ac_prev"; then + AC_ERROR(missing argument to --`echo $ac_prev | sed 's/_/-/g'`) +fi +])dnl +dnl +define(AC_INIT, +[#!/bin/sh +AC_NOTICE +AC_PARSEARGS +AC_PREPARE($1)])dnl +dnl +define(AC_PREPARE, +[trap 'rm -fr conftest* confdefs* core $ac_clean_files; exit 1' 1 2 15 +trap 'rm -fr confdefs* $ac_clean_files' 0 + +# Save the original args if we used an alternate arg parser. +ac_configure_temp="${configure_args-[$]*}" +# Strip out --no-create and --norecursion so they don't pile up. +configure_args= +for ac_arg in $ac_configure_temp; do + case "$ac_arg" in + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) ;; + -norecursion | --norecursion | --norecursio | --norecursi \ + | --norecurs | --norecur | --norecu | --norec | --nore | --nor) ;; + *) configure_args="$configure_args $ac_arg" ;; + esac +done + +# NLS nuisances. +# These must not be set unconditionally because not all systems understand +# e.g. LANG=C (notably SCO). +if test "${LC_ALL+set}" = 'set'; then LC_ALL=C; export LC_ALL; fi +if test "${LANG+set}" = 'set'; then LANG=C; export LANG; fi + +# confdefs.h avoids OS command line length limits that DEFS can exceed. +rm -rf conftest* confdefs.h +# AIX cpp loses on an empty file, so make sure it contains at least a newline. +echo > confdefs.h + +# A filename unique to this package, relative to the directory that +# configure is in, which we can look for to find out if srcdir is correct. +ac_unique_file=$1 + +# Find the source files, if location was not specified. +if test -z "$srcdir"; then + ac_srcdir_defaulted=yes + # Try the directory containing this script, then `..'. + ac_prog=[$]0 +changequote(,)dnl + ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` +changequote([,])dnl + test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. + srcdir=$ac_confdir + if test ! -r $srcdir/$ac_unique_file; then + srcdir=.. + fi +fi +if test ! -r $srcdir/$ac_unique_file; then + if test x$ac_srcdir_defaulted = xyes; then + AC_ERROR(can not find sources in ${ac_confdir} or ..) + else + AC_ERROR(can not find sources in ${srcdir}) + fi +fi +AC_LANG_C +])dnl +dnl +define(AC_ENABLE, +[[#] check whether --enable-$1 was given +enableval="[$enable_]patsubst($1,-,_)" +if test -n "$enableval"; then + ifelse([$2], , :, [$2]) +ifelse([$3], , , [else + $3 +])dnl +fi +])dnl +dnl +dnl Giving --with an argument is deprecated. +define(AC_WITH, +[[#] check whether --with-$1 or --without-$1 was given. +withval="[$with_]patsubst($1,-,_)" +if test -n "$withval"; then + ifelse([$2], , :, [$2]) +ifelse([$3], , , [else + $3 +])dnl +fi +])dnl +dnl +dnl Guess the value for the `prefix' variable by looking for +dnl the argument program along PATH and taking its parent. +dnl Example: if the argument is `gcc' and we find /usr/local/gnu/bin/gcc, +dnl set `prefix' to /usr/local/gnu. +define(AC_PREFIX, +[if test -z "$prefix" +then + AC_CHECKING([for $1 to derive installation directory prefix]) + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="$IFS:" + for ac_dir in $PATH; do + test -z "$ac_dir" && ac_dir=. + if test $ac_dir != . && test -f $ac_dir/$1; then +changequote(,)dnl + # Not all systems have dirname. + prefix=`echo $ac_dir|sed 's%/[^/][^/]*$%%'` +changequote([,])dnl + break + fi + done + IFS="$ac_save_ifs" + AC_VERBOSE(chose installation directory prefix ${prefix}) +fi +])dnl +dnl +define(AC_CONFIG_HEADER, [define(AC_CONFIG_NAMES, $1)])dnl +dnl +define(AC_DOREV, [#!/bin/sh +# From configure.in $1 +])dnl +define(AC_REVISION, [AC_DOREV(translit($1,$"))])dnl +dnl +dnl Subroutines of AC_PREREQ. +dnl +dnl Change the dots in version number $1 into commas. +define(AC_PREREQ_SPLIT, [translit($1,.,[,])])dnl +dnl +dnl Default the ternary version number to 0 (e.g., 1,7 -> 1,7,0). +define(AC_PREREQ_CANON, [$1,$2,ifelse([$3],,0,[$3])])dnl +dnl +dnl Complain and exit if the version number in $1 through $3 is less than +dnl the version number in $4 through $6. +dnl $7 is the printable version of the second version number. +define(AC_PREREQ_COMPARE, +[ifelse(builtin([eval], +[$3 + $2 * 100 + $1 * 10000 < $6 + $5 * 100 + $4 * 10000]),1, +[errprint(Autoconf version $7 or higher is required +)m4exit(3)])])dnl +dnl +dnl Complain and exit if the Autoconf version is less than $1. +define(AC_PREREQ, +[AC_PREREQ_COMPARE(AC_PREREQ_CANON(AC_PREREQ_SPLIT(AC_ACVERSION)), +AC_PREREQ_CANON(AC_PREREQ_SPLIT([$1])),[$1])])dnl +dnl +dnl +dnl Setting variables +dnl +dnl +dnl Several simple subroutines to do various flavors of quoting. +dnl +dnl Quote $1 against shell "s. +define(AC_QUOTE_DQUOTE, [dnl We use \1 instead of \& to avoid an m4 1.0.3 bug. +patsubst($1, changequote(,)\([$"`\\]\)changequote([,]), \\\1)])dnl +dnl +dnl Quote $1 against shell 's. +define(AC_QUOTE_SQUOTE, [patsubst($1, ', '\\'')])dnl +dnl +dnl Quote $1 against shell here documents (<> confdefs.h +dnl Define DEFS even if AC_CONFIG_NAMES for use in user case statements. +DEFS="$DEFS -D$1=AC_QUOTE_SQUOTE(AC_VAL)" +ifdef([AC_CONFIG_NAMES], +ac_sed_defs="dnl +${ac_sed_defs}\${ac_dA}$1\${ac_dB}$1\${ac_dC}AC_DEFINE_SEDQUOTE(AC_VAL)\${ac_dD} +\${ac_uA}$1\${ac_uB}$1\${ac_uC}AC_DEFINE_SEDQUOTE(AC_VAL)\${ac_uD} +\${ac_eA}$1\${ac_eB}$1\${ac_eC}AC_DEFINE_SEDQUOTE(AC_VAL)\${ac_eD} +" +)dnl +} +])dnl +dnl +dnl Unsafe version of AC_DEFINE. +dnl Users are responsible for the quoting nightmare. +dnl Well, not all of it. We need to pull the identify function out to +dnl the top level, because m4 doesn't really support nested functions; +dnl it doesn't distinguish between the arguments to the outer +dnl function, which should be expanded, and the arguments to the inner +dnl function, which shouldn't yet. +define(AC_IDENTITY,$1)dnl +define(AC_DEFINE_UNQUOTED,[dnl +pushdef([AC_QUOTE_SQUOTE],defn([AC_IDENTITY]))dnl +pushdef([AC_DEFINE_SEDQUOTE],defn([AC_IDENTITY]))dnl +AC_DEFINE($1,$2)dnl +popdef([AC_DEFINE_SEDQUOTE])dnl +popdef([AC_QUOTE_SQUOTE])dnl +])dnl +dnl +dnl Protects the argument from being diverted twice +dnl if this macro is called twice for it. +dnl Diversion 0 is the normal output. +dnl Diversion 1 is sed substitutions for output files. +dnl Diversion 2 is variable assignments for config.status. +define(AC_SUBST, +[ifdef([AC_SUBST_$1], , +[define([AC_SUBST_$1], )dnl +divert(1)dnl +s%@$1@%[$]$1%g +divert(2)dnl +$1='[$]$1' +divert(0)dnl +])])dnl +dnl +dnl +dnl Printing messages +dnl +dnl +define(AC_CHECKING, +[test -n "$silent" || echo "checking $1"])dnl +dnl +define(AC_VERBOSE, +[test -n "$verbose" && echo " $1"])dnl +dnl +define(AC_WARN, +[echo "configure: warning: $1" >&2])dnl +dnl +define(AC_ERROR, +[echo "configure: $1" >&2; exit 1])dnl +dnl +dnl +dnl Selecting which language to use for testing +dnl +dnl +define(AC_LANG_C, +[define([AC_LANG],[C])AC_PROVIDE([$0])ac_ext=c +# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. +ac_cpp='${CPP}' +ac_compile='${CC-cc} $CFLAGS $LDFLAGS conftest.${ac_ext} -o conftest $LIBS >/dev/null 2>&1' +])dnl +dnl +define(AC_LANG_CPLUSPLUS, +[define([AC_LANG],[CPLUSPLUS])AC_PROVIDE([$0])ac_ext=C +# CXXFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. +ac_cpp='${CXXCPP}' +ac_compile='${CXX-gcc} $CXXFLAGS $LDFLAGS conftest.${ac_ext} -o conftest $LIBS >/dev/null 2>&1' +])dnl +dnl +dnl Push the current language on a stack. +define(AC_LANG_SAVE, [pushdef([AC_LANG_STACK], AC_LANG)])dnl +dnl +dnl Restore the current language from the stack. +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 +dnl +dnl +dnl Enforcing ordering constraints +dnl +dnl +define(AC_BEFORE, +[ifdef([AC_PROVIDE_$2], [errprint(__file__:__line__: [$2 was called before $1 +])])])dnl +dnl +define(AC_REQUIRE, +[ifdef([AC_PROVIDE_$1],,[indir([$1]) +])])dnl +dnl +define(AC_PROVIDE, +[define([AC_PROVIDE_$1],)])dnl +dnl +define(AC_OBSOLETE, +[errprint(__file__:__line__: warning: [$1] is obsolete[$2] +)])dnl +dnl +dnl +dnl Checking for kinds of features +dnl +dnl +define(AC_PROGRAM_CHECK, +[if test -z "[$]$1"; then + # Extract the first word of `$2', so it can be a program name with args. + set ac_dummy $2; ac_word=[$]2 + AC_CHECKING([for $ac_word]) + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" + for ac_dir in $PATH; do + test -z "$ac_dir" && ac_dir=. + if test -f $ac_dir/$ac_word; then + $1="$3" + break + fi + done + IFS="$ac_save_ifs" +fi +ifelse([$4],,, [test -z "[$]$1" && $1="$4"]) +test -n "[$]$1" && AC_VERBOSE(setting $1 to [$]$1) +AC_SUBST($1)dnl +])dnl +dnl +define(AC_PROGRAMS_CHECK, +[for ac_prog in $2 +do +AC_PROGRAM_CHECK($1, [$]ac_prog, [$]ac_prog, ) +test -n "[$]$1" && break +done +ifelse([$3],,, [test -n "[$]$1" || $1="$3" +])])dnl +dnl +define(AC_PROGRAM_PATH, +[if test -z "[$]$1"; then + # Extract the first word of `$2', so it can be a program name with args. + set ac_dummy $2; ac_word=[$]2 + AC_CHECKING([for $ac_word]) + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" + for ac_dir in $PATH; do + test -z "$ac_dir" && ac_dir=. + if test -f $ac_dir/$ac_word; then + $1="$ac_dir/$ac_word" + break + fi + done + IFS="$ac_save_ifs" +fi +ifelse([$3],,, [test -z "[$]$1" && $1="$3"]) +test -n "[$]$1" && AC_VERBOSE(setting $1 to [$]$1) +AC_SUBST($1)dnl +])dnl +define(AC_PROGRAMS_PATH, +[for ac_prog in $2 +do +AC_PROGRAM_PATH($1, [$]ac_prog) +test -n "[$]$1" && break +done +ifelse([$3],,, [test -n "[$]$1" || $1="$3" +])])dnl +define(AC_HEADER_EGREP, +[AC_REQUIRE_CPP()AC_PROVIDE([$0])echo '#include "confdefs.h" +#include <$2>' > conftest.${ac_ext} +eval "$ac_cpp conftest.${ac_ext} > conftest.out 2>&1" +if egrep "$1" conftest.out >/dev/null 2>&1; then + ifelse([$3], , :, [rm -rf conftest* + $3 +]) +ifelse([$4], , , [else + rm -rf conftest* + $4 +])dnl +fi +rm -f conftest* +])dnl +dnl +dnl Because this macro is used by AC_GCC_TRADITIONAL, which must come early, +dnl it is not included in AC_BEFORE checks. +define(AC_PROGRAM_EGREP, +[AC_REQUIRE_CPP()AC_PROVIDE([$0])cat > conftest.${ac_ext} < conftest.out 2>&1" +if egrep "$1" conftest.out >/dev/null 2>&1; then + ifelse([$3], , :, [rm -rf conftest* + $3 +]) +ifelse([$4], , , [else + rm -rf conftest* + $4 +])dnl +fi +rm -f conftest* +])dnl +dnl +define(AC_HEADER_CHECK, +[AC_CHECKING([for $1]) +ifelse([$3], , [AC_TEST_CPP([#include <$1>], [$2])], +[AC_TEST_CPP([#include <$1>], [$2], [$3])]) +])dnl +dnl +define(AC_COMPILE_CHECK, +[AC_PROVIDE([$0])dnl +ifelse([$1], , , [AC_CHECKING([for $1])] +)dnl +dnl We use return because because C++ requires a prototype for exit. +cat > conftest.${ac_ext} < conftest.${ac_ext} </dev/null; then + ifelse([$2], , :, [$2 +]) +ifelse([$3], , , [else + $3 +])dnl +fi +ifelse([$4], , , fi +)dnl +rm -fr conftest*])dnl +dnl +define(AC_TEST_CPP, +[AC_REQUIRE_CPP()dnl +cat > conftest.${ac_ext} </dev/null) 2>&1"` +if test -z "$ac_err"; then + ifelse([$2], , :, [rm -rf conftest* + $2 +]) +ifelse([$3], , , [else + rm -rf conftest* + $3 +])dnl +fi +rm -f conftest*])dnl +dnl +define(AC_REPLACE_FUNCS, +[for ac_func in $1 +do +AC_COMPILE_CHECK([${ac_func}], [#include ], [ +/* The GNU C library defines this for functions which it implements + to always fail with ENOSYS. Some functions are actually named + something starting with __ and the normal name is an alias. */ +#if defined (__stub_${ac_func}) || defined (__stub___${ac_func}) +choke me +#else +/* Override any gcc2 internal prototype to avoid an error. */ +extern char ${ac_func}(); ${ac_func}(); +#endif +], , [LIBOBJS="$LIBOBJS ${ac_func}.o" +AC_VERBOSE(using ${ac_func}.o instead)]) +done +AC_SUBST(LIBOBJS)dnl +])dnl +dnl +define(AC_FUNC_CHECK, +[ifelse([$3], , [AC_COMPILE_CHECK($1, [#include ], [ +/* The GNU C library defines this for functions which it implements + to always fail with ENOSYS. Some functions are actually named + something starting with __ and the normal name is an alias. */ +#if defined (__stub_$1) || defined (__stub___$1) +choke me +#else +/* Override any gcc2 internal prototype to avoid an error. */ +extern char $1(); $1(); +#endif +], +$2)], [AC_COMPILE_CHECK($1, [#include ], [ +/* The GNU C library defines this for functions which it implements + to always fail with ENOSYS. Some functions are actually named + something starting with __ and the normal name is an alias. */ +#if defined (__stub_$1) || defined (__stub___$1) +choke me +#else +/* Override any gcc2 internal prototype to avoid an error. */ +extern char $1(); $1(); +#endif +], +$2, $3)])dnl +])dnl +dnl +define(AC_HAVE_FUNCS, +[for ac_func in $1 +do +changequote(,)dnl +ac_tr_func=HAVE_`echo $ac_func | tr '[a-z]' '[A-Z]'` +changequote([,])dnl +AC_FUNC_CHECK(${ac_func}, +AC_DEFINE(${ac_tr_func}))dnl +done +])dnl +dnl +define(AC_HAVE_HEADERS, +[AC_REQUIRE_CPP()dnl Make sure the cpp check happens outside the loop. +for ac_hdr in $1 +do +changequote(,)dnl +ac_tr_hdr=HAVE_`echo $ac_hdr | tr '[a-z]./' '[A-Z]__'` +changequote([,])dnl +AC_HEADER_CHECK(${ac_hdr}, +AC_DEFINE(${ac_tr_hdr}))dnl +done +])dnl +dnl +define(AC_HAVE_LIBRARY, [dnl +changequote(/,/)dnl +define(/AC_LIB_NAME/, dnl +patsubst(patsubst($1, /lib\([^\.]*\)\.a/, /\1/), /-l/, //))dnl +changequote([,])dnl +ac_save_LIBS="${LIBS}" +LIBS="${LIBS} -l[]AC_LIB_NAME[]" +ac_have_lib="" +AC_COMPILE_CHECK([-l[]AC_LIB_NAME[]], , [main();], [ac_have_lib="1"])dnl +LIBS="${ac_save_LIBS}" +ifelse($#, 1, [dnl +if test -n "${ac_have_lib}"; then + AC_DEFINE([HAVE_LIB]translit(AC_LIB_NAME, [a-z], [A-Z])) + LIBS="${LIBS} -l[]AC_LIB_NAME[]" +fi +undefine(AC_LIB_NAME)dnl +], [dnl +if test -n "${ac_have_lib}"; then + :; $2 +else + :; $3 +fi +])])dnl +dnl +define(AC_SIZEOF_TYPE, +[AC_CHECKING(size of $1) +AC_TEST_PROGRAM([#include +main() +{ + FILE *f=fopen("conftestval", "w"); + if (!f) exit(1); + fprintf(f, "%d\n", sizeof($1)); + exit(0); +}], ac_size=`cat conftestval`, AC_ERROR(can not determine size of $1)) +AC_DEFINE_UNQUOTED(changequote(<<,>>) translit(sizeof_$1, [a-z *], [A-Z_P])<<>>changequote([,]), $ac_size)])dnl +dnl +dnl +dnl The big finish +dnl +dnl +define(AC_OUTPUT, +[changequote(,)dnl + +# The preferred way to propogate these variables is regular @ substitutions. +if test -n "$prefix"; then + ac_prsub="s%^prefix\\([ ]*\\)=\\([ ]*\\).*$%prefix\\1=\\2$prefix%" +else + prefix=/usr/local +fi +if test -n "$exec_prefix"; then + ac_prsub="$ac_prsub +s%^exec_prefix\\([ ]*\\)=\\([ ]*\\).*$%exec_prefix\\1=\\2$exec_prefix%" +else + exec_prefix='${prefix}' # Let make expand it. +fi + +# Any assignment to VPATH causes Sun make to only execute +# the first set of double-colon rules, so remove it if not needed. +# If there is a colon in the path, we need to keep it. +if test "x$srcdir" = x.; then + ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' +fi + +# Quote sed substitution magic chars in DEFS. +cat >conftest.def < config.status </dev/null | sed 1q`: +# +[#] [$]0 [$]configure_args + +changequote(,)dnl +ac_cs_usage="Usage: config.status [--recheck] [--version] [--help]" +changequote([,])dnl +for ac_option +do + case "[\$]ac_option" in + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + echo running [\$]{CONFIG_SHELL-/bin/sh} [$]0 [$]configure_args --no-create + exec [\$]{CONFIG_SHELL-/bin/sh} [$]0 [$]configure_args --no-create ;; + -version | --version | --versio | --versi | --vers | --ver | --ve | --v) + echo "config.status generated by autoconf version AC_ACVERSION" + exit 0 ;; + -help | --help | --hel | --he | --h) + echo "[\$]ac_cs_usage"; exit 0 ;; + *) echo "[\$]ac_cs_usage"; exit 1 ;; + esac +done + +ifdef([AC_CONFIG_NAMES], +[trap 'rm -fr $1 AC_CONFIG_NAMES conftest*; exit 1' 1 2 15], +[trap 'rm -f $1; exit 1' 1 2 15]) +dnl Insert the variable assignments. +undivert(2)dnl +EOF +cat >> config.status <<\EOF + +ac_given_srcdir=$srcdir + +CONFIG_FILES=${CONFIG_FILES-"$1"} +for ac_file in .. ${CONFIG_FILES}; do if test "x$ac_file" != x..; then + # 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" + ac_dir_suffix="/$ac_dir" + else + ac_dir_suffix= + fi + +changequote(,)dnl + # A "../" for each directory in $ac_dir_suffix. + ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` +changequote([,])dnl + case "$ac_given_srcdir" in + .) srcdir=. + if test -z "$ac_dir_suffix"; then top_srcdir=. + else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; + /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; + *) # Relative path. + srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" + top_srcdir="$ac_dots$ac_given_srcdir" ;; + esac + + echo creating "$ac_file" + rm -f "$ac_file" + comment_str="Generated automatically from `echo $ac_file|sed 's|.*/||'`.in by configure." + case "$ac_file" in + *.c | *.h | *.C | *.cc | *.m ) echo "/* $comment_str */" > "$ac_file" ;; + * ) echo "# $comment_str" > "$ac_file" ;; + esac + sed -e " +$ac_prsub +$ac_vpsub +dnl Shell code in configure.in might set extrasub. +$extrasub +dnl Insert the sed substitutions. +undivert(1)dnl +" $ac_given_srcdir/${ac_file}.in >> $ac_file +fi; done +AC_OUTPUT_HEADER +$2 +exit 0 +EOF +chmod +x config.status +# Some shells look in PATH for config.status without the "./". +test -n "$no_create" || ${CONFIG_SHELL-/bin/sh} ./config.status +])dnl +dnl This is a subroutine of AC_OUTPUT, broken out primarily to avoid bugs +dnl with long definitions in GNU m4 1.0. This is called inside a quoted +dnl here document whose contents are going into config.status. +define(AC_OUTPUT_HEADER,[dnl +ifdef([AC_CONFIG_NAMES],[dnl +changequote(<<,>>)dnl + +# These sed commands are put into ac_sed_defs when defining a macro. +# They are broken into pieces to make the sed script easier to manage. +# They are passed to sed as "A NAME B NAME C VALUE D", where NAME +# is the cpp macro being defined and VALUE is the value it is being given. +# Each defining turns into a single global substitution command. +# Hopefully no one uses "!" as a variable value. +# Other candidates for the sed separators, like , and @, do get used. +# +# ac_d sets the value in "#define NAME VALUE" lines. +ac_dA='s!^\([ ]*\)#\([ ]*define[ ][ ]*\)' +ac_dB='\([ ][ ]*\)[^ ]*!\1#\2' +ac_dC='\3' +ac_dD='!g' +# ac_u turns "#undef NAME" with trailing blanks into "#define NAME VALUE". +ac_uA='s!^\([ ]*\)#\([ ]*\)undef\([ ][ ]*\)' +ac_uB='\([ ]\)!\1#\2define\3' +ac_uC=' ' +ac_uD='\4!g' +# ac_e turns "#undef NAME" without trailing blanks into "#define NAME VALUE". +ac_eA='s!^\([ ]*\)#\([ ]*\)undef\([ ][ ]*\)' +ac_eB='<<$>>!\1#\2define\3' +ac_eC=' ' +ac_eD='!g' +changequote([,])dnl +rm -f conftest.sed +EOF +# Turn off quoting long enough to insert the sed commands. +rm -f conftest.sh +cat > conftest.sh < conftest.s1 # Like head -9. + sed 1,${ac_max_sh_lines}d conftest.sh > conftest.s2 # Like tail +10. + # Write a limited-size here document to append to conftest.sed. + echo 'cat >> conftest.sed <> config.status + cat conftest.s1 >> config.status + echo 'CONFEOF' >> config.status + rm -f conftest.s1 conftest.sh + mv conftest.s2 conftest.sh +done +rm -f conftest.sh + +# Now back to your regularly scheduled config.status. +cat >> config.status <<\EOF +# This sed command replaces #undef's with comments. This is necessary, for +# example, in the case of _POSIX_SOURCE, which is predefined and required +# on some systems where configure will not decide to define it in +[#] AC_CONFIG_NAMES. +cat >> conftest.sed <<\CONFEOF +changequote(,)dnl +s,^[ ]*#[ ]*undef[ ][ ]*[a-zA-Z_][a-zA-Z_0-9]*,/* & */, +changequote([,])dnl +CONFEOF +rm -f conftest.h +# Break up the sed commands because old seds have small limits. +ac_max_sed_lines=20 + +CONFIG_HEADERS=${CONFIG_HEADERS-"AC_CONFIG_NAMES"} +for ac_file in .. ${CONFIG_HEADERS}; do if test "x$ac_file" != x..; then + echo creating $ac_file + + cp $ac_given_srcdir/$ac_file.in conftest.h1 + cp conftest.sed conftest.stm + while : + do + ac_lines=`grep -c . conftest.stm` + if test -z "$ac_lines" || test "$ac_lines" -eq 0; then break; fi + rm -f conftest.s1 conftest.s2 conftest.h2 + sed ${ac_max_sed_lines}q conftest.stm > conftest.s1 # Like head -20. + sed 1,${ac_max_sed_lines}d conftest.stm > conftest.s2 # Like tail +21. + sed -f conftest.s1 < conftest.h1 > conftest.h2 + rm -f conftest.s1 conftest.h1 conftest.stm + mv conftest.h2 conftest.h1 + mv conftest.s2 conftest.stm + done + rm -f conftest.stm conftest.h + echo "/* $ac_file. Generated automatically by configure. */" > conftest.h + cat conftest.h1 >> conftest.h + rm -f conftest.h1 + if cmp -s $ac_file conftest.h 2>/dev/null; then + # The file exists and we would not be changing it. + echo "$ac_file is unchanged" + rm -f conftest.h + else + rm -f $ac_file + mv conftest.h $ac_file + fi +fi; done +rm -f conftest.sed + +])])dnl diff --git a/src/util/autoconf/acspecific.m4 b/src/util/autoconf/acspecific.m4 new file mode 100644 index 000000000..5a74a0aac --- /dev/null +++ b/src/util/autoconf/acspecific.m4 @@ -0,0 +1,1402 @@ +dnl Macros that test for specific features. +dnl This file is part of Autoconf. +dnl Copyright (C) 1992, 1993, 1994 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 +dnl the Free Software Foundation; either version 2, or (at your option) +dnl any later version. +dnl +dnl This program is distributed in the hope that it will be useful, +dnl but WITHOUT ANY WARRANTY; without even the implied warranty of +dnl MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +dnl GNU General Public License for more details. +dnl +dnl You should have received a copy of the GNU General Public License +dnl along with this program; if not, write to the Free Software +dnl Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +dnl +dnl Written by David MacKenzie, with help from +dnl Franc,ois Pinard, Karl Berry, Richard Pixley, Ian Lance Taylor, +dnl Roland McGrath, and Noah Friedman. +dnl +dnl +dnl checks for programs +dnl +dnl +define(AC_PROG_CC, +[AC_BEFORE([$0], [AC_PROG_CPP])AC_PROVIDE([$0])AC_PROGRAM_CHECK(CC, gcc, gcc, cc) +# Find out if we are using GNU C, under whatever name. +cat > conftest.c < conftest.out 2>&1 +if egrep yes conftest.out >/dev/null 2>&1; then + GCC=1 # For later tests. +fi +rm -f conftest* +])dnl +dnl +define(AC_PROG_CXX, +[AC_BEFORE([$0], [AC_PROG_CXXCPP])AC_PROVIDE([$0]) +AC_PROGRAMS_CHECK(CXX, $CCC c++ g++ gcc CC cxx, gcc) +# Find out if we are using GNU C++, under whatever name. +cat > conftest.C < conftest.out 2>&1 +if egrep yes conftest.out >/dev/null 2>&1; then + GXX=1 # For later tests. +fi +rm -f conftest* +])dnl +dnl +define(AC_GCC_TRADITIONAL, +[AC_REQUIRE([AC_PROG_CC])AC_REQUIRE([AC_PROG_CPP])if test -n "$GCC"; then + AC_CHECKING(whether -traditional is needed) +changequote(,)dnl + ac_pattern="Autoconf.*'x'" +changequote([,])dnl + ac_prog='#include +Autoconf TIOCGETP' + AC_PROGRAM_EGREP($ac_pattern, $ac_prog, ac_need_trad=1) + + if test -z "$ac_need_trad"; then + ac_prog='#include +Autoconf TCGETA' + AC_PROGRAM_EGREP($ac_pattern, $ac_prog, ac_need_trad=1) + fi + test -n "$ac_need_trad" && CC="$CC -traditional" +fi +])dnl +dnl +define(AC_MINUS_C_MINUS_O, +[AC_CHECKING(whether $CC and cc understand -c and -o together) +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 >/dev/null 2>&1 \ + && test -f conftest.o && ${CC-cc} -c conftest.c -o conftest.o >/dev/null 2>&1 +then + # Test first that cc exists at all. + if cc -c conftest.c >/dev/null 2>&1 + then + if cc -c conftest.c -o conftest2.o >/dev/null 2>&1 && \ + test -f conftest2.o && cc -c conftest.c -o conftest2.o >/dev/null 2>&1 + then + : + else + AC_DEFINE(NO_MINUS_C_MINUS_O) + fi + fi +else + AC_DEFINE(NO_MINUS_C_MINUS_O) +fi +rm -f conftest* +])dnl +dnl +dnl Define SET_MAKE to set ${MAKE} if make doesn't. +define(AC_SET_MAKE, +[cat > conftestmake <<'EOF' +all: + @echo 'ac_maketemp="${MAKE}"' +EOF +changequote(,)dnl +# GNU make sometimes prints "make[1]: Entering...", which would confuse us. +eval `${MAKE-make} -f conftestmake 2>/dev/null | grep temp=` +changequote([,])dnl +if test -n "$ac_maketemp"; then SET_MAKE= +else SET_MAKE="MAKE=${MAKE-make}"; fi +rm -f conftestmake +AC_SUBST([SET_MAKE])dnl +])dnl +dnl +define(AC_PROG_RANLIB, [AC_PROGRAM_CHECK(RANLIB, ranlib, ranlib, :)])dnl +dnl +define(AC_PROG_AWK, [AC_PROGRAMS_CHECK(AWK, mawk gawk nawk awk,)])dnl +dnl +define(AC_PROG_YACC,[AC_PROGRAMS_CHECK(YACC, 'bison -y' byacc, yacc)])dnl +dnl +define(AC_PROG_CPP, +[AC_PROVIDE([$0])AC_CHECKING(how to run the C preprocessor) +if test -z "$CPP"; then + # This must be in double quotes, not single quotes, because CPP may get + # substituted into the Makefile and ``${CC-cc}'' will simply confuse + # make. It must be expanded now. + CPP="${CC-cc} -E" +dnl On the NeXT, cc -E runs the code through the compiler's parser, +dnl not just through cpp. + AC_TEST_CPP([#include +Syntax Error], , + CPP="${CC-cc} -E -traditional-cpp" + AC_TEST_CPP([#include +Syntax Error], ,CPP=/lib/cpp)) +fi +AC_VERBOSE(setting CPP to $CPP) +AC_SUBST(CPP)dnl +])dnl +dnl +define(AC_PROG_CXXCPP, +[AC_PROVIDE([$0])AC_CHECKING(how to run the C++ preprocessor) +AC_LANG_SAVE[]dnl +AC_LANG_CPLUSPLUS[]dnl +if test -z "$CXXCPP"; then + CXXCPP="${CXX-c++} -E" + AC_TEST_CPP([#include ], , CXXCPP=/lib/cpp) +fi +AC_VERBOSE(setting CXXCPP to $CXXCPP) +AC_LANG_RESTORE[]dnl +AC_SUBST(CXXCPP)dnl +])dnl +dnl +dnl Require finding the C or C++ preprocessor, whichever is the +dnl current language. +define(AC_REQUIRE_CPP, +[ifelse(AC_LANG,C,[AC_REQUIRE([AC_PROG_CPP])],[AC_REQUIRE([AC_PROG_CXXCPP])])])dnl +dnl +define(AC_PROG_LEX, +[AC_PROVIDE([$0])AC_PROGRAM_CHECK(LEX, flex, flex, lex) +if test -z "$LEXLIB" +then + case "$LEX" in + flex*) AC_HAVE_LIBRARY(fl, LEXLIB="-lfl") ;; + *) LEXLIB="-ll" ;; + esac +fi +AC_VERBOSE(setting LEXLIB to $LEXLIB) +AC_SUBST(LEXLIB)])dnl +dnl +define(AC_YYTEXT_POINTER,[dnl +AC_REQUIRE_CPP()AC_REQUIRE([AC_PROG_LEX])dnl +AC_CHECKING(for yytext declaration) +# 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. +# +# 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 '%% +%%' | ${LEX} +if test -f lex.yy.c; then + LEX_OUTPUT_ROOT=lex.yy +elif test -f lexyy.c; then + LEX_OUTPUT_ROOT=lexyy +else + # Don't know what to do here. + AC_ERROR(cannot find output from $LEX, giving up on yytext declaration) + LEX_OUTPUT_ROOT= +fi +if test -n "$LEX_OUTPUT_ROOT"; then + echo 'extern char *yytext; main () { exit (0); }' >>$LEX_OUTPUT_ROOT.c + ac_save_LIBS="$LIBS" + LIBS="$LIBS $LEXLIB" + AC_TEST_PROGRAM(`cat $LEX_OUTPUT_ROOT.c`, AC_DEFINE(YYTEXT_POINTER)) + LIBS="$ac_save_LIBS" + rm -f "${LEX_OUTPUT_ROOT}.c" +fi +AC_SUBST(LEX_OUTPUT_ROOT)dnl +])dnl +dnl +define(AC_PROG_INSTALL, +[# Make sure to not get the incompatible SysV /etc/install and +# /usr/sbin/install, which might be in PATH before a BSD-like install, +# or the SunOS /usr/etc/install directory, or the AIX /bin/install, +# or the AFS install, which mishandles nonexistent args, or +# /usr/ucb/install on SVR4, which tries to use the nonexistent group +# `staff', or /sbin/install on IRIX which has incompatible command-line +# syntax. Sigh. +# +# On most BSDish systems install is in /usr/bin, not /usr/ucb +# anyway. +# This turns out not to be true, so the mere pathname isn't an indication +# of whether the program works. What we really need is a set of tests for +# the install program to see if it actually works in all the required ways. +# +# Avoid using ./install, which might have been erroneously created +# by make from ./install.sh. +if test -z "${INSTALL}"; then + AC_CHECKING(for a BSD compatible install) + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" + for ac_dir in $PATH; do + case "$ac_dir" in + ''|.|/etc|/sbin|/usr/sbin|/usr/etc|/usr/afsws/bin|/usr/ucb) ;; + *) + # OSF1 and SCO ODT 3.0 have their own names for install. + for ac_prog in installbsd scoinst install; do + if test -f $ac_dir/$ac_prog; then + if test $ac_prog = install && + grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then + # AIX install. It has an incompatible calling convention. + # OSF/1 installbsd also uses dspmsg, but is usable. + : + else + INSTALL="$ac_dir/$ac_prog -c" + break 2 + fi + fi + done + ;; + esac + done + IFS="$ac_save_ifs" +fi + +if test -z "$INSTALL"; then + # As a last resort, use the slow shell script. + for ac_dir in ${srcdir} ${srcdir}/.. ${srcdir}/../..; do + if test -f $ac_dir/install.sh; then + INSTALL="$ac_dir/install.sh -c"; break + fi + done +fi +if test -z "$INSTALL"; then + AC_ERROR([can not find install.sh in ${srcdir} or ${srcdir}/.. or ${srcdir}/../..]) +fi +AC_SUBST(INSTALL)dnl +AC_VERBOSE(setting INSTALL to $INSTALL) + +# Use test -z because SunOS4 sh mishandles ${INSTALL_PROGRAM-'${INSTALL}'}. +# It thinks the first close brace ends the variable substitution. +test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}' +AC_SUBST(INSTALL_PROGRAM)dnl +AC_VERBOSE(setting INSTALL_PROGRAM to $INSTALL_PROGRAM) + +test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' +AC_SUBST(INSTALL_DATA)dnl +AC_VERBOSE(setting INSTALL_DATA to $INSTALL_DATA) +])dnl +dnl +define(AC_LN_S, +[AC_CHECKING(for ln -s) +rm -f conftestdata +if ln -s X conftestdata 2>/dev/null +then + rm -f conftestdata + LN_S="ln -s" +else + LN_S=ln +fi +AC_SUBST(LN_S) +])dnl +dnl +define(AC_RSH, +[AC_CHECKING(for remote shell) +if test -f /usr/ucb/rsh || test -f /usr/bin/remsh || test -f /usr/bin/rsh || + test -f /usr/bsd/rsh || test -f /usr/bin/nsh; then + RTAPELIB=rtapelib.o +else + AC_HEADER_CHECK(netdb.h, AC_DEFINE(HAVE_NETDB_H) RTAPELIB=rtapelib.o, + AC_DEFINE(NO_REMOTE)) +fi +AC_SUBST(RTAPELIB)dnl +])dnl +dnl +dnl +dnl checks for header files +dnl +dnl +define(AC_STDC_HEADERS, +[AC_REQUIRE_CPP()dnl +AC_CHECKING(for ANSI C header files) +AC_TEST_CPP([#include +#include +#include +#include ], +[# SunOS 4.x string.h does not declare mem*, contrary to ANSI. +AC_HEADER_EGREP(memchr, string.h, +# SGI's /bin/cc from Irix-4.0.5 gets non-ANSI ctype macros unless using -ansi. +AC_TEST_PROGRAM([#include +#define ISLOWER(c) ('a' <= (c) && (c) <= 'z') +#define TOUPPER(c) (ISLOWER(c) ? 'A' + ((c) - 'a') : (c)) +#define XOR(e,f) (((e) && !(f)) || (!(e) && (f))) +int main () { int i; for (i = 0; i < 256; i++) +if (XOR (islower (i), ISLOWER (i)) || toupper (i) != TOUPPER (i)) exit(2); +exit (0); } +], +[# ISC 2.0.2 stdlib.h does not declare free, contrary to ANSI. +AC_HEADER_EGREP(free, stdlib.h, AC_DEFINE(STDC_HEADERS))]))]) +])dnl +dnl +define(AC_UNISTD_H, [AC_OBSOLETE([$0], [; instead use AC_HAVE_HEADERS(unistd.h)])AC_HEADER_CHECK(unistd.h, + AC_DEFINE(HAVE_UNISTD_H))])dnl +dnl +define(AC_USG, +[AC_OBSOLETE([$0], [; instead use AC_HAVE_HEADERS(string.h) and HAVE_STRING_H])AC_COMPILE_CHECK([BSD string and memory functions], +[#include ], [rindex(0, 0); bzero(0, 0);], , AC_DEFINE(USG))])dnl +dnl +dnl +dnl If memchr and the like aren't declared in , include . +dnl To avoid problems, don't check for gcc2 built-ins. +define(AC_MEMORY_H, +[AC_OBSOLETE([$0], [; instead use AC_HAVE_HEADERS(memory.h) and HAVE_MEMORY_H])AC_CHECKING(whether string.h declares mem functions) +AC_HEADER_EGREP(memchr, string.h, , + AC_HEADER_CHECK(memory.h, AC_DEFINE(NEED_MEMORY_H)))] +)dnl +dnl +define(AC_MAJOR_HEADER, +[AC_COMPILE_CHECK([major, minor and makedev header], +[#include ], +[return makedev(0, 0);], ac_makedev=1) +if test -z "$ac_makedev"; then +AC_HEADER_CHECK(sys/mkdev.h, AC_DEFINE(MAJOR_IN_MKDEV) ac_makedev=1) +fi +if test -z "$ac_makedev"; then +AC_HEADER_CHECK(sys/sysmacros.h, AC_DEFINE(MAJOR_IN_SYSMACROS)) +fi] +)dnl +dnl +define(AC_DIR_HEADER, +[AC_PROVIDE([$0])AC_CHECKING(for directory library header) +ac_dir_header= +AC_DIR_HEADER_CHECK(dirent.h, DIRENT) +AC_DIR_HEADER_CHECK(sys/ndir.h, SYSNDIR) +AC_DIR_HEADER_CHECK(sys/dir.h, SYSDIR) +AC_DIR_HEADER_CHECK(ndir.h, NDIR) + +AC_CHECKING(for closedir return value) +AC_TEST_PROGRAM([#include +#include <$ac_dir_header> +int closedir(); main() { exit(closedir(opendir(".")) != 0); }], , +AC_DEFINE(VOID_CLOSEDIR)) +])dnl +dnl Subroutine of AC_DIR_HEADER. +dnl ??? I tried to put this define inside AC_DIR_HEADER, but when I did +dnl that, $1 and $2 did not get expanded. --roland +dnl Check if $1 is the winning directory library header file. +dnl It must not only exist, but also correctly define the `DIR' type. +dnl If it is really winning, define $2 and set shell var `ac_dir_header' to $1. +define(AC_DIR_HEADER_CHECK, [dnl +if test -z "$ac_dir_header"; then + AC_COMPILE_CHECK($1, [#include +#include <]$1[>], + [DIR *dirp = 0;], + AC_DEFINE($2) ac_dir_header=$1)dnl +fi])dnl +dnl +dnl +dnl checks for typedefs +dnl +dnl +define(AC_GETGROUPS_T, +[AC_REQUIRE([AC_UID_T])dnl +AC_CHECKING(for type of array argument to getgroups) +changequote(,)dnl +dnl Do not put single quotes in the C program text!! +ac_prog='/* Thanks to Mike Rendell for this test. */ +#include +#define NGID 256 +#undef MAX +#define MAX(x,y) ((x) > (y) ? (x) : (y)) +main() +{ + gid_t gidset[NGID]; + int i, n; + union { gid_t gval; long lval; } val; + + val.lval = -1; + for (i = 0; i < NGID; i++) + gidset[i] = val.gval; + n = getgroups (sizeof (gidset) / MAX (sizeof (int), sizeof (gid_t)) - 1, + gidset); + /* Exit non-zero if getgroups seems to require an array of ints. This + happens when gid_t is short but getgroups modifies an array of ints. */ + exit ((n > 0 && gidset[n] != val.gval) ? 1 : 0); +}' +changequote([,])dnl +AC_TEST_PROGRAM([$ac_prog], + AC_DEFINE(GETGROUPS_T, gid_t), + AC_DEFINE(GETGROUPS_T, int)) +])dnl +dnl +define(AC_UID_T, +[AC_PROVIDE([$0])AC_CHECKING(for uid_t in sys/types.h) +AC_HEADER_EGREP(uid_t, sys/types.h, , + AC_DEFINE(uid_t, int) AC_DEFINE(gid_t, int))])dnl +dnl +define(AC_SIZE_T, +[AC_CHECKING(for size_t in sys/types.h) +AC_HEADER_EGREP(size_t, sys/types.h, , AC_DEFINE(size_t, unsigned))])dnl +dnl +define(AC_PID_T, +[AC_PROVIDE([$0])AC_CHECKING(for pid_t in sys/types.h) +AC_HEADER_EGREP(pid_t, sys/types.h, , AC_DEFINE(pid_t, int))])dnl +dnl +define(AC_OFF_T, +[AC_PROVIDE([$0])AC_CHECKING(for off_t in sys/types.h) +AC_HEADER_EGREP(off_t, sys/types.h, , AC_DEFINE(off_t, long))])dnl +dnl +define(AC_MODE_T, +[AC_CHECKING(for mode_t in sys/types.h) +AC_HEADER_EGREP(mode_t, sys/types.h, , AC_DEFINE(mode_t, int))])dnl +dnl +define(AC_RETSIGTYPE, +[AC_PROVIDE([$0])AC_COMPILE_CHECK([return type of signal handlers], +[#include +#include +#ifdef signal +#undef signal +#endif +extern void (*signal ()) ();], +[int i;], +[AC_DEFINE(RETSIGTYPE, void)], +[AC_DEFINE(RETSIGTYPE, int)])] +)dnl +dnl +dnl +dnl checks for functions +dnl +dnl +define(AC_MMAP, [ +AC_CHECKING(for working mmap) +AC_TEST_PROGRAM([/* 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 +#define getpagesize() EXEC_PAGESIZE +#else +#ifdef NBPG +#define getpagesize() NBPG * CLSIZE +#ifndef CLSIZE +#define CLSIZE 1 +#endif /* no CLSIZE */ +#else /* no NBPG */ +#ifdef NBPC +#define getpagesize() NBPC +#else /* no NBPC */ +#define getpagesize() PAGESIZE /* SVR4 */ +#endif /* no NBPC */ +#endif /* no NBPG */ +#endif /* no EXEC_PAGESIZE */ +#endif /* not HAVE_GETPAGESIZE */ + +#ifdef __osf__ +#define valloc malloc +#endif + +extern char *valloc(); +extern char *malloc(); + +int +main() +{ + char *buf1, *buf2, *buf3; + int i = getpagesize(), j; + int i2 = getpagesize()*2; + int fd; + + buf1 = valloc(i2); + buf2 = valloc(i); + buf3 = malloc(i2); + for (j = 0; j < i2; ++j) + *(buf1 + j) = rand(); + fd = open("conftestmmap", O_CREAT | O_RDWR, 0666); + write(fd, buf1, i2); + mmap(buf2, i, PROT_READ | PROT_WRITE, MAP_FIXED | MAP_PRIVATE, fd, 0); + for (j = 0; j < i; ++j) + if (*(buf1 + j) != *(buf2 + j)) + exit(1); + lseek(fd, (long)i, 0); + read(fd, buf2, i); /* read into mapped memory -- file should not change */ + /* (it does in i386 SVR4.0 - Jim Avera) */ + lseek(fd, (long)0, 0); + read(fd, buf3, i2); + for (j = 0; j < i2; ++j) + if (*(buf1 + j) != *(buf3 + j)) + exit(1); + exit(0); +} +], AC_DEFINE(HAVE_MMAP)) +])dnl +dnl +define(AC_VPRINTF, +[AC_COMPILE_CHECK([vprintf], , [vprintf();], AC_DEFINE(HAVE_VPRINTF), +ac_vprintf_missing=1) +if test -n "$ac_vprintf_missing"; then +AC_COMPILE_CHECK([_doprnt], , [_doprnt();], AC_DEFINE(HAVE_DOPRNT)) +fi +])dnl +dnl +define(AC_VFORK, +[AC_REQUIRE([AC_PID_T])AC_HEADER_CHECK(vfork.h, AC_DEFINE(HAVE_VFORK_H)) +AC_CHECKING(for working vfork) +AC_REQUIRE([AC_RETSIGTYPE]) +AC_TEST_PROGRAM([/* Thanks to Paul Eggert for this test. */ +#include +#include +#include +#include +#ifdef HAVE_UNISTD_H +#include +#endif +#ifdef HAVE_VFORK_H +#include +#endif +static int signalled; +static RETSIGTYPE catch (s) int s; { signalled = 1; } +main() { + pid_t parent = getpid (); + pid_t child; + + signal (SIGINT, catch); + + child = vfork (); + + if (child == 0) { + /* On sparc systems, changes by the child to local and incoming + argument registers are propagated back to the parent. + The compiler is told about this with #include , + but some compilers (e.g. gcc -O) don't grok . + Test for this by using lots of local variables, at least + as many local variables as main has allocated so far + including compiler temporaries. 4 locals are enough for + gcc 1.40.3 on a sparc, but we use 8 to be safe. + A buggy compiler should reuse the register of parent + for one of the local variables, since it will think that + parent can't possibly be used any more in this routine. + Assigning to the local variable will thus munge parent + in the parent process. */ + pid_t + p = getpid(), p1 = getpid(), p2 = getpid(), p3 = getpid(), + p4 = getpid(), p5 = getpid(), p6 = getpid(), p7 = getpid(); + /* Convince the compiler that p..p7 are live; otherwise, it might + use the same hardware register for all 8 local variables. */ + if (p != p1 || p != p2 || p != p3 || p != p4 + || p != p5 || p != p6 || p != p7) + _exit(1); + + /* On some systems (e.g. SunOS 5.2), if the parent is catching + a signal, the child ignores the signal before execing, + and the parent later receives that signal, the parent dumps core. + Test for this by ignoring SIGINT in the child. */ + signal (SIGINT, SIG_IGN); + + /* On some systems (e.g. IRIX 3.3), + vfork doesn't separate parent from child file descriptors. + If the child closes a descriptor before it execs or exits, + this munges the parent's descriptor as well. + Test for this by closing stdout in the child. */ + _exit(close(fileno(stdout)) != 0); + } else { + int status; + struct stat st; + + while (wait(&status) != child) + ; + exit( + /* Was there some problem with vforking? */ + child < 0 + + /* Did the child fail? (This shouldn't happen.) */ + || status + + /* Did the vfork/compiler bug occur? */ + || parent != getpid() + + /* Did the signal handling bug occur? */ + || kill(parent, SIGINT) != 0 + || signalled != 1 + + /* Did the file descriptor bug occur? */ + || fstat(fileno(stdout), &st) != 0 + ); + } +}], , AC_DEFINE(vfork, fork)) +])dnl +dnl +define(AC_WAIT3, +[AC_CHECKING(for wait3 that fills in rusage) +AC_TEST_PROGRAM([#include +#include +#include +#include +/* HP-UX has wait3 but does not fill in rusage at all. */ +main() { + struct rusage r; + int i; + /* Use a field that we can force nonzero -- + voluntary context switches. + For systems like NeXT and OSF/1 that don't set it, + also use the system CPU time. */ + r.ru_nvcsw = 0; + r.ru_stime.tv_sec = 0; + r.ru_stime.tv_usec = 0; + switch (fork()) { + case 0: /* Child. */ + sleep(1); /* Give up the CPU. */ + _exit(0); + case -1: _exit(0); /* What can we do? */ + default: /* Parent. */ + wait3(&i, 0, &r); + sleep(1); /* Avoid "text file busy" from rm on fast HP-UX machines. */ + exit(r.ru_nvcsw == 0 + && r.ru_stime.tv_sec == 0 && r.ru_stime.tv_usec == 0); + } +}], AC_DEFINE(HAVE_WAIT3)) +])dnl +dnl +define(AC_ALLOCA, +[# The Ultrix 4.2 mips builtin alloca declared by alloca.h only works +# for constant arguments. Useless! +AC_COMPILE_CHECK(working alloca.h, [#include ], + [char *p = alloca(2 * sizeof(int));], AC_DEFINE(HAVE_ALLOCA_H)) +ac_decl="#ifdef __GNUC__ +#define alloca __builtin_alloca +#else +#if HAVE_ALLOCA_H +#include +#else +#ifdef _AIX + #pragma alloca +#else +char *alloca (); +#endif +#endif +#endif +" +AC_COMPILE_CHECK([alloca], $ac_decl, +[char *p = (char *) alloca(1);], [AC_DEFINE([HAVE_ALLOCA])], [dnl +ac_alloca_missing=1 +AC_PROGRAM_EGREP(winnitude, [ +#if defined(CRAY) && ! defined(CRAY2) +winnitude +#else +lossage +#endif +], +AC_FUNC_CHECK([_getb67],AC_DEFINE([CRAY_STACKSEG_END],[_getb67]), +AC_FUNC_CHECK([GETB67],AC_DEFINE([CRAY_STACKSEG_END],[GETB67]), +AC_FUNC_CHECK([getb67],AC_DEFINE([CRAY_STACKSEG_END],[getb67]))))) +]) +if test -n "$ac_alloca_missing"; then + # The SVR3 libPW and SVR4 libucb both contain 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. + ALLOCA=alloca.o + AC_DEFINE(C_ALLOCA) + + AC_CHECKING(stack direction for C alloca) + AC_TEST_PROGRAM([find_stack_direction () +{ + static char *addr = 0; + auto char dummy; + if (addr == 0) + { + addr = &dummy; + return find_stack_direction (); + } + else + return (&dummy > addr) ? 1 : -1; +} +main () +{ + exit (find_stack_direction() < 0); +}], dnl +AC_DEFINE(STACK_DIRECTION,1), AC_DEFINE(STACK_DIRECTION,-1), dnl +AC_DEFINE(STACK_DIRECTION,0)) +fi +AC_SUBST(ALLOCA)dnl +])dnl +dnl +define(AC_GETLOADAVG, +[# Some definitions of getloadavg require that the program be installed setgid. +AC_SUBST(NEED_SETGID)NEED_SETGID=false +ac_need_func=true + +# Check for the 4.4BSD definition of getloadavg. +AC_HAVE_LIBRARY(util, LIBS="$LIBS -lutil" ac_need_func=false) +# Some systems with -lutil have (and need) -lkvm as well, some do not. +AC_HAVE_LIBRARY(kvm, LIBS="$LIBS -lkvm") + +if $ac_need_func; then +# There is a commonly available library for RS/6000 AIX. +# Since it is not a standard part of AIX, it might be installed locally. +LIBS_old="$LIBS" +LIBS="-L/usr/local/lib $LIBS" +AC_HAVE_LIBRARY(getloadavg, LIBS="$LIBS -lgetloadavg" ac_need_func=false, + LIBS="$LIBS_old") +fi + +# Make sure it is really in the library, if we think we found it at all. +AC_REPLACE_FUNCS(getloadavg) + +case "$LIBOBJS" in +*getloadavg*) +ac_need_func=true +AC_HEADER_CHECK(sys/dg_sys_info.h, [dnl +AC_DEFINE(DGUX) ac_need_func=false +# Some versions of DGUX need -ldgc for dg_sys_info. +AC_HAVE_LIBRARY(dgc)]) +if $ac_need_func; then +# We cannot check for , because Solaris 2 does not use dwarf (it +# uses stabs), but it's still SVR4. We cannot check for because +# Irix 4.0.5F has the header but not the library. +AC_HAVE_LIBRARY(elf, AC_DEFINE(SVR4) LIBS="$LIBS -lelf" ac_need_func=false + AC_HAVE_LIBRARY(kvm, LIBS="$LIBS -lkvm")) +fi +if $ac_need_func; then +AC_HEADER_CHECK(inq_stats/cpustats.h, AC_DEFINE(UMAX4_3) AC_DEFINE(UMAX) + ac_need_func=false) +fi +if $ac_need_func; then +AC_HEADER_CHECK(sys/cpustats.h, AC_DEFINE(UMAX) ac_need_func=false) +fi +if $ac_need_func; then +AC_HAVE_HEADERS(mach/mach.h) +fi + +AC_HEADER_CHECK(nlist.h, +[AC_DEFINE(NLIST_STRUCT) +AC_COMPILE_CHECK(n_un in struct nlist, [#include ], +[struct nlist n; n.n_un.n_name = 0;], +AC_DEFINE(NLIST_NAME_UNION))])dnl + +# Figure out whether we will need to install setgid. +AC_PROGRAM_EGREP([Yowza Am I SETGID yet], [dnl +#include "${srcdir}/getloadavg.c" +#ifdef LDAV_PRIVILEGED +Yowza Am I SETGID yet +#endif], [AC_DEFINE(GETLOADAVG_PRIVILEGED) NEED_SETGID=true])dnl +;; + +*) AC_DEFINE(HAVE_GETLOADAVG) ;; +esac + +if $NEED_SETGID; then +AC_SUBST(KMEM_GROUP)dnl + # Figure out what group owns /dev/kmem. + # The installed program will need to be setgid and owned by that group. +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` + # If we got an error (system does not support symlinks), try without -L. + test -z "$ac_ls_output" && ac_ls_output=`ls -lg /dev/kmem` + KMEM_GROUP=`echo $ac_ls_output \ + | sed -ne 's/[ ][ ]*/ /g; + s/^.[sSrwx-]* *[0-9]* *\([^0-9]*\) *.*/\1/; + / /s/.* //;p;'` +changequote([,])dnl +fi +])dnl +dnl +define(AC_UTIME_NULL, +[AC_CHECKING(utime with null argument) +rm -f conftestdata; > conftestdata +# Sequent interprets utime(file, 0) to mean use start of epoch. Wrong. +AC_TEST_PROGRAM([#include +#include +main() { +struct stat s, t; +exit(!(stat ("conftestdata", &s) == 0 && utime("conftestdata", (long *)0) == 0 +&& stat("conftestdata", &t) == 0 && t.st_mtime >= s.st_mtime +&& t.st_mtime - s.st_mtime < 120)); +}], AC_DEFINE(HAVE_UTIME_NULL)) +rm -f core +])dnl +dnl +define(AC_STRCOLL, [AC_CHECKING(for strcoll) +AC_TEST_PROGRAM([#include +main () +{ + exit (strcoll ("abc", "def") >= 0 || + strcoll ("ABC", "DEF") >= 0 || + strcoll ("123", "456") >= 0); +}], AC_DEFINE(HAVE_STRCOLL))])dnl +dnl +define(AC_SETVBUF_REVERSED, +[AC_TEST_PROGRAM([#include +/* If setvbuf has the reversed format, exit 0. */ +main () { + /* This call has the arguments reversed. + A reversed system may check and see that the address of main + is not _IOLBF, _IONBF, or _IOFBF, and return nonzero. */ + if (setvbuf(stdout, _IOLBF, (char *) main, BUFSIZ) != 0) + exit(1); + putc('\r', stdout); + exit(0); /* Non-reversed systems segv here. */ +}], AC_DEFINE(SETVBUF_REVERSED)) +rm -f core +])dnl +dnl +dnl +dnl checks for structure members +dnl +dnl +define(AC_STRUCT_TM, +[AC_PROVIDE([$0])AC_COMPILE_CHECK([struct tm in time.h], +[#include +#include ], +[struct tm *tp; tp->tm_sec;], , AC_DEFINE(TM_IN_SYS_TIME))])dnl +dnl +define(AC_TIME_WITH_SYS_TIME, +[AC_COMPILE_CHECK([whether time.h and sys/time.h may both be included], +[#include +#include +#include ], +[struct tm *tp;], AC_DEFINE(TIME_WITH_SYS_TIME))])dnl +dnl +define(AC_TIMEZONE, +[AC_REQUIRE([AC_STRUCT_TM])ac_decl='#include +' +case "$DEFS" in + *TM_IN_SYS_TIME*) ac_decl="$ac_decl +#include +" ;; + *) ac_decl="$ac_decl +#include +" ;; +esac +AC_COMPILE_CHECK([tm_zone in struct tm], $ac_decl, +[struct tm tm; tm.tm_zone;], AC_DEFINE(HAVE_TM_ZONE), ac_no_tm_zone=1) +if test -n "$ac_no_tm_zone"; then +AC_COMPILE_CHECK(tzname, changequote(<<,>>)dnl +<<#include +#ifndef tzname /* For SGI. */ +extern char *tzname[]; /* RS6000 and others want it this way. */ +#endif>>, changequote([,])dnl +[atoi(*tzname);], AC_DEFINE(HAVE_TZNAME)) +fi +])dnl +dnl +define(AC_ST_BLOCKS, +[AC_COMPILE_CHECK([st_blocks in struct stat], +[#include +#include ], [struct stat s; s.st_blocks;], +AC_DEFINE(HAVE_ST_BLOCKS), LIBOBJS="$LIBOBJS fileblocks.o")dnl +AC_SUBST(LIBOBJS)dnl +])dnl +dnl +define(AC_ST_BLKSIZE, +[AC_COMPILE_CHECK([st_blksize in struct stat], +[#include +#include ], [struct stat s; s.st_blksize;], +AC_DEFINE(HAVE_ST_BLKSIZE))])dnl +dnl +define(AC_ST_RDEV, +[AC_COMPILE_CHECK([st_rdev in struct stat], +[#include +#include ], [struct stat s; s.st_rdev;], +AC_DEFINE(HAVE_ST_RDEV))])dnl +dnl +dnl +dnl checks for compiler characteristics +dnl +dnl +define(AC_CROSS_CHECK, +[AC_PROVIDE([$0])AC_CHECKING(whether cross-compiling) +# If we cannot run a trivial program, we must be cross compiling. +AC_TEST_PROGRAM([main(){exit(0);}], , cross_compiling=1) +])dnl +dnl +define(AC_CHAR_UNSIGNED, +[AC_CHECKING(for unsigned characters) +AC_TEST_PROGRAM( +[/* volatile prevents gcc2 from optimizing the test away on sparcs. */ +#if !__STDC__ +#define volatile +#endif +main() { +#ifdef __CHAR_UNSIGNED__ + exit(1); /* No need to redefine it. */ +#else + volatile char c = 255; exit(c < 0); +#endif +}], AC_DEFINE(__CHAR_UNSIGNED__))] +)dnl +dnl +define(AC_LONG_DOUBLE, +[AC_REQUIRE([AC_PROG_CC])dnl +AC_CHECKING(for long double) +if test -n "$GCC"; then +AC_DEFINE(HAVE_LONG_DOUBLE) +else +AC_TEST_PROGRAM([int main() { +/* The Stardent Vistra knows sizeof(long double), but does not support it. */ +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_DEFINE(HAVE_LONG_DOUBLE)) +fi +])dnl +dnl +define(AC_INT_16_BITS, +[AC_OBSOLETE([$0], [; instead use AC_SIZEOF_TYPE(int)]) +AC_CHECKING(integer size) +AC_TEST_PROGRAM([main() { exit(sizeof(int) != 2); }], + AC_DEFINE(INT_16_BITS)) +])dnl +dnl +define(AC_LONG_64_BITS, +[AC_OBSOLETE([$0], [; instead use AC_SIZEOF_TYPE(long)]) +AC_CHECKING(for 64-bit long ints) +AC_TEST_PROGRAM([main() { exit(sizeof(long int) != 8); }], + AC_DEFINE(LONG_64_BITS)) +])dnl +dnl +define(AC_WORDS_BIGENDIAN, +[AC_CHECKING(byte ordering) +AC_TEST_PROGRAM([main () { + /* Are we little or big endian? From Harbison&Steele. */ + union + { + long l; + char c[sizeof (long)]; + } u; + u.l = 1; + exit (u.c[sizeof (long) - 1] == 1); +}], , AC_DEFINE(WORDS_BIGENDIAN)) +])dnl +dnl +define(AC_ARG_ARRAY, +[AC_CHECKING(whether the address of an argument can be used as an array) +AC_TEST_PROGRAM([main() { +/* Return 0 iff arg arrays are ok. */ +exit(!x(1, 2, 3, 4)); +} +x(a, b, c, d) { + return y(a, &b); +} +/* Return 1 iff arg arrays are ok. */ +y(a, b) int *b; { + return a == 1 && b[0] == 2 && b[1] == 3 && b[2] == 4; +}], , AC_DEFINE(NO_ARG_ARRAY)) +rm -f core +])dnl +dnl +define(AC_INLINE, +[AC_REQUIRE([AC_PROG_CC])if test -n "$GCC"; then +AC_COMPILE_CHECK([inline], , [} inline foo() {], , AC_DEFINE(inline, __inline)) +fi +])dnl +define(AC_CONST, +[changequote(,)dnl +dnl Do not put single quotes in the C program text!! +ac_prog='/* Ultrix mips cc rejects this. */ +typedef int charset[2]; const charset x; +/* SunOS 4.1.1 cc rejects this. */ +char const *const *ccp; +char **p; +/* 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 */ +const char *g = "string"; +ccp = &g + (g ? g-g : 0); +/* HPUX 7.0 cc rejects these. */ +++ccp; +p = (char**) ccp; +ccp = (char const *const *) p; +{ /* SCO 3.2v4 cc rejects this. */ + char *t; + char const *s = 0 ? (char *) 0 : (char const *) 0; + + *t++ = 0; +} +{ /* Someone thinks the Sun supposedly-ANSI compiler will reject this. */ + int x[] = {25,17}; + const int *foo = &x[0]; + ++foo; +} +{ /* Sun SC1.0 ANSI compiler rejects this -- but not the above. */ + typedef const int *iptr; + iptr p = 0; + ++p; +} +{ /* AIX XL C 1.02.0.0 rejects this saying + "k.c", line 2.27: 1506-025 (S) Operand must be a modifiable lvalue. */ + struct s { int j; const int *ap[3]; }; + struct s *b; b->j = 5; +} +{ /* ULTRIX-32 V3.1 (Rev 9) vcc rejects this */ + const int foo = 10; +}' +changequote([,])dnl +AC_COMPILE_CHECK([dnl Do not "break" this again. +lack of working const], , [$ac_prog], , AC_DEFINE(const,))])dnl +dnl +dnl +dnl checks for operating system services +dnl +dnl +define(AC_HAVE_POUNDBANG, [dnl +AC_CHECKING(whether \`[#]!' works in shell scripts) +echo '#!/bin/cat +exit 69 +' > conftest +chmod u+x conftest +(SHELL=/bin/sh; export SHELL; ./conftest > /dev/null) +if test $? -ne 69; then + :; $1 +else + :; $2 +fi +rm -f conftest +])dnl +define(AC_REMOTE_TAPE, +[AC_CHECKING(for remote tape and socket header files) +AC_HEADER_CHECK(sys/mtio.h, AC_DEFINE(HAVE_SYS_MTIO_H) ac_have_mtio_h=1) +if test -n "$ac_have_mtio_h"; then +AC_TEST_CPP([#include +#include ], PROGS="$PROGS rmt") +fi +])dnl +dnl +define(AC_LONG_FILE_NAMES, +[AC_CHECKING(for long file names) +ac_some_dir_failed=false +# Test for long file names in all the places we know might matter: +# . the current directory, where building will happen +# /tmp where it might want to write temporary files +# /var/tmp likewise +# /usr/tmp likewise +# $prefix/lib where we will be installing things +# $exec_prefix/lib likewise +# eval it to expand exec_prefix. +for ac_dir in `eval echo . /tmp /var/tmp /usr/tmp $prefix/lib $exec_prefix/lib` ; do + test -d $ac_dir || continue + test -w $ac_dir || continue # It's less confusing to not echo anything here. + (echo 1 > $ac_dir/conftest9012345) 2>/dev/null + (echo 2 > $ac_dir/conftest9012346) 2>/dev/null + val=`cat $ac_dir/conftest9012345 2>/dev/null` + test -f $ac_dir/conftest9012345 && test "$val" = 1 || ac_some_dir_failed=true + rm -f $ac_dir/conftest9012345 $ac_dir/conftest9012346 2> /dev/null +done +$ac_some_dir_failed || AC_DEFINE(HAVE_LONG_FILE_NAMES) +])dnl +dnl +define(AC_RESTARTABLE_SYSCALLS, +[AC_CHECKING(for restartable system calls) +AC_TEST_PROGRAM( +[/* Exit 0 (true) if wait returns something other than -1, + i.e. the pid of the child, which means that wait was restarted + after getting the signal. */ +#include +#include +ucatch (isig) { } +main () { + int i = fork (), status; + if (i == 0) { sleep (3); kill (getppid (), SIGINT); sleep (3); exit (0); } + signal (SIGINT, ucatch); + status = wait(&i); + if (status == -1) wait(&i); + exit (status == -1); +} +], AC_DEFINE(HAVE_RESTARTABLE_SYSCALLS)) +])dnl +dnl +define(AC_FIND_X, +[AC_REQUIRE_CPP()dnl Set CPP; we run AC_FIND_X_DIRECT conditionally. +AC_PROVIDE([$0])# If we find X, set shell vars x_includes and x_libraries to the paths. +no_x=true +if test "x$with_x" != xno; then +AC_FIND_X_XMKMF +if test -z "$ac_im_usrlibdir"; then +AC_FIND_X_DIRECT +fi +test -n "$x_includes" && AC_VERBOSE(X11 headers are in $x_includes) +test -n "$x_libraries" && AC_VERBOSE(X11 libraries are in $x_libraries) +fi +])dnl +dnl +dnl Internal subroutine of AC_FIND_X. +define(AC_FIND_X_XMKMF, +[AC_CHECKING(for X include and library files with xmkmf) +rm -fr conftestdir +if mkdir conftestdir; then + cd conftestdir + # Make sure to not put "make" in the Imakefile rules, since we grep it out. + cat > Imakefile <<'EOF' +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` + # Open Windows xmkmf reportedly sets LIBDIR instead of USRLIBDIR. + if test ! -f $ac_im_usrlibdir/libX11.a && test -f $ac_im_libdir/libX11.a + then + ac_im_usrlibdir=$ac_im_libdir + fi + case "$ac_im_incroot" in + /usr/include) ;; + *) test -z "$x_includes" && x_includes="$ac_im_incroot" ;; + esac + case "$ac_im_usrlibdir" in + /usr/lib | /lib) ;; + *) test -z "$x_libraries" && x_libraries="$ac_im_usrlibdir" ;; + esac + fi + cd .. + rm -fr conftestdir +fi +])dnl +dnl +dnl Internal subroutine of AC_FIND_X. +define(AC_FIND_X_DIRECT, +[AC_CHECKING(for X include and library files directly) +if test ".$x_direct_test_library" = . ; then + x_direct_test_library='Xt' +fi +if test ".$x_direct_test_include" = . ; then + x_direct_test_include='X11/Intrinsic.h' +fi +AC_TEST_CPP([#include <$x_direct_test_include>], no_x=, + for ac_dir in \ + /usr/X11R6/include \ + /usr/X11R5/include \ + /usr/X11R4/include \ + \ + /usr/include/X11R6 \ + /usr/include/X11R5 \ + /usr/include/X11R4 \ + \ + /usr/local/X11R6/include \ + /usr/local/X11R5/include \ + /usr/local/X11R4/include \ + \ + /usr/local/include/X11R6 \ + /usr/local/include/X11R5 \ + /usr/local/include/X11R4 \ + \ + /usr/X11/include \ + /usr/include/X11 \ + /usr/local/X11/include \ + /usr/local/include/X11 \ + \ + /usr/X386/include \ + /usr/x386/include \ + /usr/XFree86/include/X11 \ + \ + /usr/include \ + /usr/local/include \ + /usr/unsupported/include \ + /usr/athena/include \ + /usr/local/x11r5/include \ + /usr/lpp/Xamples/include \ + \ + /usr/openwin/include \ + /usr/openwin/share/include \ + ; \ + do + if test -r "$ac_dir/$x_direct_test_include"; then + test -z "$x_includes" && x_includes=$ac_dir + no_x= + break + fi + done) + +# Check for the libraries. First see if replacing the `include' by +# `lib' works. +AC_HAVE_LIBRARY("$x_direct_test_library", no_x=, +for ac_dir in `echo "$x_includes" | sed s/include/lib/` \ + /usr/X11R6/lib \ + /usr/X11R5/lib \ + /usr/X11R4/lib \ + \ + /usr/lib/X11R6 \ + /usr/lib/X11R5 \ + /usr/lib/X11R4 \ + \ + /usr/local/X11R6/lib \ + /usr/local/X11R5/lib \ + /usr/local/X11R4/lib \ + \ + /usr/local/lib/X11R6 \ + /usr/local/lib/X11R5 \ + /usr/local/lib/X11R4 \ + \ + /usr/X11/lib \ + /usr/lib/X11 \ + /usr/local/X11/lib \ + /usr/local/lib/X11 \ + \ + /usr/X386/lib \ + /usr/x386/lib \ + /usr/XFree86/lib/X11 \ + \ + /usr/lib \ + /usr/local/lib \ + /usr/unsupported/lib \ + /usr/athena/lib \ + /usr/local/x11r5/lib \ + /usr/lpp/Xamples/lib \ + \ + /usr/openwin/lib \ + /usr/openwin/share/lib \ + ; \ +do + for ac_extension in a so sl; do + if test -r $ac_dir/lib${x_direct_test_library}.$ac_extension; then + test -z "$x_libraries" && x_libraries=$ac_dir + no_x= + break 2 + fi + done +done)])dnl +dnl +dnl Find additional X libraries, magic flags, etc. +define(AC_FIND_XTRA, [AC_REQUIRE([AC_ISC_POSIX])AC_REQUIRE([AC_FIND_X]) +AC_CHECKING(for additional X libraries and flags) +if test -n "$x_includes"; then + X_CFLAGS="$X_CFLAGS -I$x_includes" +elif test -n "$no_x"; then + # Not all programs may use this symbol, but it won't hurt to define it. + X_CFLAGS="$X_CFLAGS -DX_DISPLAY_MISSING" +fi + +# It would be nice to have a more robust check for the -R ld option than +# just checking for Solaris. +# It would also be nice to do this for all -L options, not just this one. +if test -n "$x_libraries"; then + 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" + fi +fi + +# Check for additional X libraries. + +if test -n "$ISC"; then + X_EXTRA_LIBS="$X_EXTRA_LIBS -lnsl_s -linet" +else + # Martyn.Johnson@cl.cam.ac.uk says this is needed for Ultrix, if the X + # libraries were built with DECnet support. And karl@cs.umb.edu's Alpha + # needs dnet_stub (dnet doesn't exist). + AC_HAVE_LIBRARY(dnet, + [X_EXTRA_LIBS="$X_EXTRA_LIBS -ldnet" + ac_have_dnet=t]) + if test -z "$ac_have_dnet"; then + AC_HAVE_LIBRARY(dnet_stub, [X_EXTRA_LIBS="$X_EXTRA_LIBS -ldnet_stub"]) + fi + # lieder@skyler.mavd.honeywell.com says without -lsocket, + # socket/setsockopt and other routines are undefined under SCO ODT 2.0. + # But -lsocket is broken on IRIX, according to simon@lia.di.epfl.ch. + if test "`(uname) 2>/dev/null`" != IRIX; then + AC_HAVE_LIBRARY(socket, [X_EXTRA_LIBS="$X_EXTRA_LIBS -lsocket"]) + fi +fi +# +AC_VERBOSE(X compiler flags: $X_CFLAGS) +AC_VERBOSE(X library flags: $X_LIBS) +AC_VERBOSE(extra X libraries: $X_EXTRA_LIBS) +AC_SUBST(X_CFLAGS)dnl +AC_SUBST(X_LIBS)dnl +AC_SUBST(X_EXTRA_LIBS)dnl +])dnl +dnl +dnl +dnl checks for UNIX variants +dnl +dnl +define(AC_AIX, +[AC_CHECKING(for AIX) +AC_BEFORE([$0], [AC_COMPILE_CHECK])AC_BEFORE([$0], [AC_TEST_PROGRAM])AC_BEFORE([$0], [AC_HEADER_EGREP])AC_BEFORE([$0], [AC_TEST_CPP])AC_PROGRAM_EGREP(yes, +[#ifdef _AIX + yes +#endif +], AC_DEFINE(_ALL_SOURCE)) +])dnl +dnl +define(AC_MINIX, +[AC_BEFORE([$0], [AC_COMPILE_CHECK])AC_BEFORE([$0], [AC_TEST_PROGRAM])AC_BEFORE([$0], [AC_HEADER_EGREP])AC_BEFORE([$0], [AC_TEST_CPP])AC_HEADER_CHECK(minix/config.h, MINIX=1) +# The Minix shell can't assign to the same variable on the same line! +if test -n "$MINIX"; then + AC_DEFINE(_POSIX_SOURCE) + AC_DEFINE(_POSIX_1_SOURCE, 2) + AC_DEFINE(_MINIX) +fi +])dnl +dnl +define(AC_ISC_POSIX, +[AC_PROVIDE([$0])AC_BEFORE([$0], [AC_COMPILE_CHECK])AC_BEFORE([$0], [AC_TEST_PROGRAM])AC_BEFORE([$0], [AC_HEADER_EGREP])AC_BEFORE([$0], [AC_TEST_CPP])AC_CHECKING(for POSIXized ISC) +if test -d /etc/conf/kconfig.d && + grep _POSIX_VERSION [/usr/include/sys/unistd.h] >/dev/null 2>&1 +then + ISC=1 # If later tests want to check for ISC. + AC_DEFINE(_POSIX_SOURCE) + if test -n "$GCC"; then + CC="$CC -posix" + else + CC="$CC -Xp" + fi +fi +])dnl +dnl +define(AC_XENIX_DIR, +[AC_REQUIRE([AC_DIR_HEADER])AC_CHECKING(for Xenix) +AC_PROGRAM_EGREP(yes, +[#if defined(M_XENIX) && !defined(M_UNIX) + yes +#endif +], XENIX=1) +if test -n "$XENIX"; then + LIBS="$LIBS -lx" + case "$DEFS" in + *SYSNDIR*) ;; + *) LIBS="-ldir $LIBS" ;; # Make sure -ldir precedes any -lx. + esac +fi +])dnl +dnl +define(AC_SCO_INTL, +[AC_HAVE_LIBRARY(intl, LIBS="$LIBS -lintl") +])dnl +dnl +define(AC_IRIX_SUN, +[AC_HAVE_LIBRARY(sun, LIBS="$LIBS -lsun") +])dnl +dnl +define(AC_DYNIX_SEQ, +[AC_HAVE_LIBRARY(seq, LIBS="$LIBS -lseq") +])dnl +dnl +define(AC_STAT_MACROS_BROKEN,[AC_CHECKING(for broken stat file mode macros) +AC_PROGRAM_EGREP([You lose], [#include +#include +#ifdef S_ISBLK +#if S_ISBLK (S_IFDIR) +You lose. +#endif +#ifdef S_IFCHR +#if S_ISBLK (S_IFCHR) +You lose. +#endif +#endif /* S_IFCHR */ +#endif /* S_ISBLK */ +#ifdef S_ISLNK +#if S_ISLNK (S_IFREG) +You lose. +#endif +#endif /* S_ISLNK */ +#ifdef S_ISSOCK +#if S_ISSOCK (S_IFREG) +You lose. +#endif +#endif /* S_ISSOCK */ +], AC_DEFINE(STAT_MACROS_BROKEN))])dnl +dnl +dnl +define(AC_SYS_SIGLIST_DECLARED,[dnl +AC_COMPILE_CHECK(sys_siglist declaration in signal.h or unistd.h, + [#include +/* NetBSD declares sys_siglist in . */ +#ifdef HAVE_UNISTD_H +#include +#endif], [char *msg = *(sys_siglist + 1);], + AC_DEFINE(SYS_SIGLIST_DECLARED))])dnl +dnl diff --git a/src/util/autoconf/autoconf b/src/util/autoconf/autoconf new file mode 100644 index 000000000..4edeea656 --- /dev/null +++ b/src/util/autoconf/autoconf @@ -0,0 +1,120 @@ +#!/bin/sh +# autoconf -- create `configure' using m4 macros +# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +# If given no args, create `configure' from template file `configure.in'. +# With one arg, create a configure script on standard output from +# the given template file. + +usage="Usage: autoconf [-h] [--help] [-m dir] [--macrodir=dir] + [-v] [--version] [template-file]" + +# NLS nuisances. +# These must not be set unconditionally because not all systems understand +# e.g. LANG=C (notably SCO). +if test "${LC_ALL+set}" = 'set' ; then LC_ALL=C; export LC_ALL; fi +if test "${LANG+set}" = 'set' ; then LANG=C; export LANG; fi + +test -z "${AC_MACRODIR}" && AC_MACRODIR=/usr/latest/lib/autoconf +test -z "${M4}" && M4=/usr/latest/bin/m4 +case "${M4}" in +/*) # Handle the case that m4 has moved since we were configured. + # It may have been found originally in a build directory. + test -f "${M4}" || M4=m4 ;; +esac + +tmpout=/tmp/acout.$$ + +print_version= +while test $# -gt 0 ; do + case "z${1}" in + z-h | z--help | z--h* ) + echo "${usage}" 1>&2; exit 0 ;; + z--macrodir=* | z--m*=* ) + AC_MACRODIR="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" + shift ;; + z-m | z--macrodir | z--m* ) + shift + test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } + AC_MACRODIR="${1}" + shift ;; + z-v | z--version | z--v* ) + print_version="-DAC_PRINT_VERSION" + infile=/dev/null tmpout=/dev/null + shift ;; + z-- ) # Stop option processing + shift; break ;; + z- ) # Use stdin as input. + break ;; + z-* ) + echo "${usage}" 1>&2; exit 1 ;; + * ) + break ;; + esac +done + +if test -z "$print_version"; then + case $# in + 0) infile=configure.in ;; + 1) infile="$1" ;; + *) echo "$usage" >&2; exit 1 ;; + esac + + trap 'rm -f $tmpin $tmpout; exit 1' 1 2 15 + + if test z$infile = z-; then + tmpin=/tmp/acin.$$ + infile=$tmpin + cat > $infile + elif test ! -s "${infile}"; then + echo "autoconf: ${infile}: No such file or directory" >&2 + exit 1 + fi +fi + +MACROFILES="${AC_MACRODIR}/acgeneral.m4 ${AC_MACRODIR}/acspecific.m4" +test -r ${AC_MACRODIR}/aclocal.m4 \ + && MACROFILES="${MACROFILES} ${AC_MACRODIR}/aclocal.m4" +test -r aclocal.m4 && MACROFILES="${MACROFILES} aclocal.m4" +MACROFILES="${print_version} ${MACROFILES}" + +$M4 $MACROFILES $infile > $tmpout || { st=$?; rm -f $tmpin $tmpout; exit $st; } + +test -n "$print_version" && exit 0 + +# You could add your own prefixes to pattern if you wanted to check for +# them too, e.g. pattern="AC_\|ILT_", except that UNIX sed doesn't do +# alternation. +pattern="AC_" + +status=0 +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 + done | sort -u >&2 + status=1 +fi + +case $# in + 0) cat $tmpout > configure; chmod +x configure ;; + 1) cat $tmpout ;; +esac + +rm -f $tmpout +exit $status diff --git a/src/util/autoconf/autoconf.info b/src/util/autoconf/autoconf.info new file mode 100644 index 000000000..d0b9fe30b --- /dev/null +++ b/src/util/autoconf/autoconf.info @@ -0,0 +1,2918 @@ +This is Info file autoconf.info, produced by Makeinfo-1.55 from the +input file ./autoconf.texi. + +START-INFO-DIR-ENTRY +* autoconf: (autoconf). The Autoconf configuration system. +END-INFO-DIR-ENTRY + + This file documents the GNU Autoconf package for creating scripts to +configure source code packages using templates and an `m4' macro +package. + + Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + +File: autoconf.info, Node: Top, Next: Introduction, 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 1.11, for Autoconf version 1.11. + +* Menu: + +* Introduction:: Autoconf's purpose, strengths, and weaknesses. +* Distributing:: Legal restrictions on Autoconf output. +* Making configure Scripts:: How to organize and produce Autoconf scripts. +* Specific Tests:: Macros that check for particular features. +* General Purpose Macros:: Macros that check for kinds of features. +* Writing Macros:: How to add your own macros to Autoconf. +* Makefiles:: Information Autoconf uses in `Makefile's. +* Invoking configure:: How to use the Autoconf output. +* Example:: Sample Autoconf input 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 autoconf:: How to create configuration scripts. +* Invoking autoheader:: How to create configuration header files. + +Specific Tests + +* Alternative Programs:: Selecting between alternative programs. +* Header Files:: Header files that might be missing. +* Typedefs:: `typedef's that might be missing. +* Library Functions:: C library functions that might be missing. +* Structures:: Structures or members that might be missing. +* Compiler Characteristics:: C compiler or machine architecture features. +* System Services:: Operating system services. +* UNIX Variants:: Special cases for specific UNIX variants. + +General Purpose Macros + +* Setup:: Controlling Autoconf operation. +* General Feature Tests:: Checking for kinds of features. +* Command Line:: Checking command line arguments. +* Setting Variables:: Setting shell and `make' variables. +* Printing Messages:: Notifying users of progress or problems. +* Language Choice:: Selecting which language to use for testing. +* Macro Ordering:: Enforcing ordering constraints. + +Writing Macros + +* Macro Format:: Basic format of an Autoconf macro. +* Quoting:: Protecting macros from unwanted expansion. +* Dependencies Between Macros:: What to do when macros depend on other macros. +* Checking for Files:: Finding whether a file exists. +* Checking for Symbols:: Finding whether a symbol is defined. +* Test Programs:: Writing programs to test for features. +* Multiple Cases:: Tests for several possible values. + +Dependencies Between Macros + +* Prerequisite Macros:: Ensuring required information. +* Suggested Ordering:: Warning about possible ordering problems. + +Test Programs + +* Guidelines:: General rules for writing test programs. +* Tricks:: Special ways to work around problems. + +Makefiles + +* Predefined Variables:: Heavily used `make' variables. +* Installation Prefixes:: A special variable substitution. +* VPATH Substitutions:: Compiling in a different directory. +* Automatic Remaking:: Makefile rules for configuring. + +Running `configure' Scripts + +* Overriding variables:: Workarounds for unusual systems. +* Invoking config.status:: Recreating a configuration. + +An Example + +* Sample configure.in:: An example of a `configure' template. +* Sample Makefile.in:: An example of a `Makefile' template. + + +File: autoconf.info, Node: Introduction, Next: Distributing, Prev: Top, Up: Top + +Introduction +************ + + 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 normally require no +manual user intervention when run; they do not even take 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 operating +system features that the package can use. After the shell code to +recognize and respond to an operating 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 the configuration scripts can be regenerated +automatically to take advantage of the updated code. + + Larry Wall's Metaconfig package is similar in purpose to Autoconf, +but is more general. 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. They should +avoid executing test programs, since test programs compiled with a +cross-compiler can not be executed on the host system. Also, they +shouldn't do anything that tests features of the host system instead of +the target system. + + 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; so use a later version of GNU `m4'. + + Autoconf does not work well with GNU C library releases before 1.06. +The GNU C library contains stubs (which always return an error) for +functions that are not available instead of omitting them from the +library. As a result, Autoconf scripts are fooled into thinking that +those functions are available. This problem does not exist with +releases 1.06 and later of the GNU C library, which define C +preprocessor macros that the Autoconf macros `AC_FUNC_CHECK' and +`AC_REPLACE_FUNCS' test, indicating that certain functions are stubs +(*note General Feature Tests::., for more information on checking for +functions). + + Autoconf was written by David MacKenzie, with help from Franc,ois +Pinard, Karl Berry, Richard Pixley, Ian Lance Taylor, Roland McGrath, +Noah Friedman, and david d zuhn. It was inspired by Brian Fox's +automatic configuration system for Bash, by Larry Wall's Metaconfig, and +by Richard Stallman, Richard Pixley, and John Gilmore's configuration +tools for the GNU compiler and object file utilities. + + 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: Distributing, Next: Making configure Scripts, Prev: Introduction, Up: Top + +Distributing Autoconf Output +**************************** + + The configuration scripts that Autoconf produces are covered by the +GNU General Public License. This is because they consist almost +entirely of parts of Autoconf itself, rearranged somewhat, and Autoconf +is distributed under the terms of the GPL. As applied to Autoconf, the +GPL just means that you need to distribute `configure.in', and +`aclocal.m4', `acconfig.h', and `CONFIG.h.top' and `CONFIG.h.bot' if +you use them, along with `configure'. + + Programs that use Autoconf scripts to configure themselves do not +automatically come under the GPL. Distributing an Autoconf +configuration script as part of a program is considered to be *mere +aggregation* of that work with the Autoconf script. Such programs are +not derivative works based on Autoconf; only their configuration scripts +are. 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. + + +File: autoconf.info, Node: Making configure Scripts, Next: Specific Tests, Prev: Distributing, 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 values appropriate for +the system being configured. The files that `configure' creates are: + + * one or more `Makefile' files (one in each subdirectory of the + package), from template `Makefile.in' files (*note Makefiles::.); + + * optionally, a C header file, the name of which is configurable, + containing `#define' statements (*note Setup::.); + + * a shell script called `config.status' that, when run, will recreate + the files listed above (*note Invoking config.status::.). + + To create a `configure' script with Autoconf, you need to write an +Autoconf input file (`configure.in') and run Autoconf on it to produce +the script. If you write your own feature tests to supplement those +that come with Autoconf, you might also write a file called +`aclocal.m4'. If you use a C header file to contain `#define' +directives, you might also write `config.h.top', `config.h.bot', and +`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 files +`acgeneral.m4' and `acspecific.m4', and also an installed `aclocal.m4' +if it exists. + +Files used in preparing a software package for distribution: + configure.in --. .------> autoconf* -----> configure + +---+ + [aclocal.m4] --' `---. + +--> [autoheader*] -> [config.h.in] + [acconfig.h] ----. | + +-----' + [config.h.top] --+ + [config.h.bot] --' + + Makefile.in -------------------------------> Makefile.in + +Files used in configuring a software package: + configure* ------------. + | + [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 autoconf:: How to create configuration scripts. +* Invoking autoheader:: How to create configuration header files. + + +File: autoconf.info, Node: Writing configure.in, Next: Invoking autoconf, 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 +Specific Tests::, for their descriptions. For most other features, you +can use Autoconf template macros to produce custom checks; see *Note +General Feature Tests::, for information about them. For especially +tricky or specialized features, `configure.in' might need to contain +some hand-crafted shell commands. *Note Writing Macros::, for +guidelines on writing tests from scratch. + + Every `configure.in' must begin with a call to `AC_INIT' and end +with a call to `AC_OUTPUT' (*note Setup::.). Other than that, the +order in which `configure.in' calls the Autoconf macros is generally +not important, except that 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 Specific Tests::.). + + To encourage consistency, here is a suggested order for calling the +Autoconf macros. A few macros need to be called in a different order +from the one given here; they are noted in their individual descriptions +(*note Specific Tests::.). Note that there must not be any space +between the macro name and the open parentheses. + + `AC_INIT(FILE)' + checks for alternative programs + checks for UNIX variants that set C preprocessor variables + checks for header files + checks for typedefs + checks for library functions + checks for structures + checks for compiler characteristics + checks for system services + other checks for UNIX variants + `AC_OUTPUT([FILE...])' + + You can include comments in `configure.in' files by starting them +with the `m4' predefined 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. + + *Note Sample configure.in::, for an example of a real `configure.in' +script. + + +File: autoconf.info, Node: Invoking autoconf, Next: Invoking autoheader, Prev: Writing configure.in, Up: Making configure Scripts + +Invoking `autoconf' +=================== + + 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 two or more files. Two of the +files are distributed with Autoconf: `autoconf' first reads +`acgeneral.m4' (*note General Purpose Macros::.), then `acspecific.m4' +(*note Specific Tests::.). After reading them, `autoconf' looks for an +optional file called `aclocal.m4', first in the directory that contains +other installed Autoconf macro files, and then in the current +directory. If both files exist, it uses both of them. Those files can +contain your site's own locally written 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. + + You can override the directory where `autoconf' looks for the +installed macro files by setting the `AC_MACRODIR' environment variable +to a different directory. You can also give `autoconf' the +`--macrodir' option, which overrides `AC_MACRODIR'. + + `autoconf' also accepts the options `--version', which prints the +Autoconf version number and exits, and `--help', which prints a summary +of the command-line options and exits. + + +File: autoconf.info, Node: Invoking autoheader, Prev: Invoking autoconf, Up: Making configure Scripts + +Invoking `autoheader' +===================== + + You can use the `autoheader' program to create a template file of C +`#define' statements for `configure' to use. By default, the file that +`autoheader' creates is called `config.h.in'; if `configure.in' invokes +`AC_CONFIG_HEADER(FILE)', `autoheader' creates `FILE.in'. + + `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; you must create that +file to contain entries for any additional symbols that you +`AC_DEFINE'. For symbols defined by `AC_HAVE_HEADERS', +`AC_HAVE_FUNCS', `AC_SIZEOF_TYPE', or `AC_HAVE_LIBRARY', `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 usually contains only `#define' +and `#undef' statements and their accompanying comments. However, if a +file called `FILE.top' (typically `config.h.top') exists in the current +directory, `autoheader' copies that file to the beginning of its output. + + 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. + + You can override the directory where `autoheader' looks for the +installed macro and `acconfig.h' files by setting the `AC_MACRODIR' +environment variable to a different directory. You can also give +`autoheader' the `--macrodir' option, which overrides `AC_MACRODIR'. + + `autoheader' also accepts the options `--version', which prints the +Autoconf version number and exits, and `--help', which prints a summary +of the command-line options and exits. + + +File: autoconf.info, Node: Specific Tests, Next: General Purpose Macros, Prev: Making configure Scripts, Up: Top + +Specific Tests +************** + + These macros test for particular operating system features that +packages might need or want to use. If you need to test for a feature +that none of these macros check for, you can probably do it by calling +one of the general purpose test macros with appropriate arguments +(*note General Feature Tests::.). + + All of these macros that set `make' variables call `AC_SUBST' on +those variables (*note Setting Variables::., for details about +`AC_SUBST'). The phrase "define NAME" is used below as a shorthand to +mean either add `-DNAME=1' to the `make' variable `DEFS', or put +`#define NAME 1' in the configuration header file, depending on whether +`AC_CONFIG_HEADER' has been called. *Note Setting Variables::, for +more information. + + Within each section below, the macros are listed in alphabetical +order. The macros are generally named for the `make' variables or C +preprocessor macros that they define; those names are based largely on +what existing GNU programs use. These macros are defined in the file +`acspecific.m4'. + +* Menu: + +* Alternative Programs:: Selecting between alternative programs. +* Header Files:: Header files that might be missing. +* Typedefs:: `typedef's that might be missing. +* Library Functions:: C library functions that might be missing. +* Structures:: Structures or members that might be missing. +* Compiler Characteristics:: C compiler or machine architecture features. +* System Services:: Operating system services. +* UNIX Variants:: Special cases for specific UNIX variants. + + +File: autoconf.info, Node: Alternative Programs, Next: Header Files, Up: Specific Tests + +Alternative Programs +==================== + + The following macros check for the presence or behavior of particular +programs: + + - Macro: AC_GCC_TRADITIONAL + Add `-traditional' to `make' variable `CC' if using the GNU C + compiler and `ioctl' does not work properly without + `-traditional'. This macro calls `AC_PROG_CC' and `AC_PROG_CPP' + if they haven't been called already. + + - Macro: AC_LN_S + If `ln -s' works on the current filesystem (the O.S. and filesystem + support symbolic links), set shell and `make' variable `LN_S' to + `ln -s', otherwise set it to `ln'. + + - Macro: AC_MINUS_C_MINUS_O + If the C compiler does not accept the `-c' and `-o' options + simultaneously, define `NO_MINUS_C_MINUS_O'. + + - Macro: AC_PROG_AWK + Check for `mawk', `gawk', `nawk', and `awk', in that order, and + set `make' variable `AWK' to the first one that it finds. + + - Macro: AC_PROG_CC + If `gcc' is found, set `make' variable `CC' to `gcc', and set + shell variable `GCC' to 1 for use by macros such as + `AC_GCC_TRADITIONAL'. + + - Macro: AC_PROG_CPP + Set shell and `make' 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_TEST_CPP', `AC_HEADER_CHECK', `AC_HEADER_EGREP', or + `AC_PROGRAM_EGREP'. Those macros call this macro first if it + hasn't been called already. It calls `AC_PROG_CC' if it hasn't + been called already. + + - 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 `make' variable + `CXX' to its value. Otherwise search for a C++ compiler under + likely names (`c++', `g++', `gcc', and `CC'). If none of those + checks succeed, as a last resort set `CXX' to `gcc'. + + - Macro: AC_PROG_CXXCPP + Set shell and `make' 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' 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_TEST_CPP', `AC_HEADER_CHECK', `AC_HEADER_EGREP', or + `AC_PROGRAM_EGREP'. Those macros call this macro first if it + hasn't been called already. This macro calls `AC_PROG_CXX' if it + hasn't been called already. + + - Macro: AC_PROG_INSTALL + Set `make' variable `INSTALL' to `install -c' if `install' is + found and is compatible with the BSD and GNU versions. Otherwise, + set `INSTALL' to `DIR/install.sh -c', where it checks for + `install.sh' in the directories `$srcdir', `$srcdir/..', and + `$srcdir/../..' to determine DIR. + + This macro screens out the false matches `/etc/install', + `/usr/sbin/install', and other instances of `install' known not to + work. It also sets the variable `INSTALL_PROGRAM' to `${INSTALL}' + and `INSTALL_DATA' to `${INSTALL} -m 644'. + + If you need to use your own `install.sh' 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 script into your + `Makefile.in' files. + + - Macro: AC_PROG_LEX + If `flex' is found, set `make' 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_RANLIB + Set `make' variable `RANLIB' to `ranlib' if `ranlib' is found, + otherwise to `:' (do nothing). + + - Macro: AC_PROG_YACC + If `bison' is found, set `make' variable `YACC' to `bison -y'. + Otherwise, if `byacc' is found, set `YACC' to `byacc'. Otherwise + set `YACC' to `yacc'. + + - Macro: AC_RSH + If a remote shell is available, put `rtapelib.o' in `make' + variable `RTAPELIB'. Otherwise, also do so if `netdb.h' exists + (implying the `rexec' function), and in addition define + `HAVE_NETDB_H'. If neither a remote shell nor `rexec' is + available, define `NO_REMOTE'. + + - Macro: AC_SET_MAKE + If `make' predefines the variable `MAKE', define `make' variable + `SET_MAKE' to be empty. Otherwise, define `SET_MAKE' to contain + `MAKE=make'. Calls `AC_SUBST' for `SET_MAKE'. + + In recent versions of `make', the variable `MAKE' contains the + name of the `make' program plus options it was given. It is used + when running `make' recursively in subdirectories. But some old + versions of `make' don't set the `MAKE' variable. This macro + allows use of `MAKE' on all systems. + + If you use this macro, simply place a line like this in your + `Makefile.in' file(s): + + @SET_MAKE@ + + - Macro: AC_YYTEXT_POINTER + Define `YYTEXT_POINTER' if `yytext' is a `char *' instead of a + `char []'. This depends on whether `lex' or `flex' is being used. + This macro calls `AC_PROG_CPP' (or `AC_PROG_CXXCPP' if C++ is the + current language, *note Language Choice::.) and `AC_PROG_LEX' if + they haven't been called already. + + This macro replaces `AC_DECLARE_YYTEXT', which didn't work. + + +File: autoconf.info, Node: Header Files, Next: Typedefs, Prev: Alternative Programs, Up: Specific Tests + +Header Files +============ + + The following macros check for the presence of certain C header +files: + + - Macro: AC_DIR_HEADER + If the system has `dirent.h', define `DIRENT'; otherwise, if it + has `sys/ndir.h', define `SYSNDIR'; otherwise, if it has + `sys/dir.h', define `SYSDIR'; otherwise, if it has `ndir.h', + define `NDIR'. Also, if the directory library header file + contains a declaration of the `closedir' function with a `void' + return type, define `VOID_CLOSEDIR'. + + The directory library declarations in the source code should look + something like the following, which assumes that you have also + called `AC_HAVE_HEADERS(unistd.h)': + + #ifdef HAVE_UNISTD_H + #include + #include + #endif + + /* unistd.h defines _POSIX_VERSION on POSIX.1 systems. */ + #if defined(DIRENT) || defined(_POSIX_VERSION) + #include + #define NLENGTH(dirent) (strlen((dirent)->d_name)) + #else /* not (DIRENT or _POSIX_VERSION) */ + #define dirent direct + #define NLENGTH(dirent) ((dirent)->d_namlen) + #ifdef SYSNDIR + #include + #endif /* SYSNDIR */ + #ifdef SYSDIR + #include + #endif /* SYSDIR */ + #ifdef NDIR + #include + #endif /* NDIR */ + #endif /* not (DIRENT or _POSIX_VERSION) */ + + 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 `NLENGTH' macro. + + - Macro: AC_MAJOR_HEADER + 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_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_HAVE_HEADERS(memory.h)'. See the + example for `AC_STDC_HEADERS'. + + - Macro: AC_STDC_HEADERS + 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. + + To check whether to use the System V/ANSI C string functions and + header file, you can put the following in `configure.in': + + AC_STDC_HEADERS + AC_HAVE_HEADERS(string.h memory.h) + + Then, in the code, use a test like this: + + #if STDC_HEADERS || HAVE_STRING_H + #include + /* An ANSI string.h and pre-ANSI memory.h might conflict. */ + #if !STDC_HEADERS && HAVE_MEMORY_H + #include + #endif /* not STDC_HEADERS and HAVE_MEMORY_H */ + #define index strchr + #define rindex strrchr + #define bcopy(s, d, n) memcpy ((d), (s), (n)) + #define bcmp(s1, s2, n) memcmp ((s1), (s2), (n)) + #define bzero(s, n) memset ((s), 0, (n)) + #else /* not STDC_HEADERS and not HAVE_STRING_H */ + #include + /* memory.h and strings.h conflict on some systems. */ + #endif /* not STDC_HEADERS and not HAVE_STRING_H */ + + This example asssumes that your code uses the BSD style functions. + If you use the System V/ANSI C style functions, you will need to + replace the macro definitions with ones that go in the other + direction. + + 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. + + - Macro: AC_UNISTD_H + Define `HAVE_UNISTD_H' if the system has `unistd.h'. This macro + is obsolete; instead, use `AC_HAVE_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, use + `AC_HAVE_HEADERS(string.h)' and use `HAVE_STRING_H' in your code. + See the example for `AC_STDC_HEADERS'. + + - Macro: AC_SYS_SIGLIST_DECLARED + Define `SYS_SIGLIST_DECLARED' if the variable `sys_siglist' is + declared in a system header file, either `signal.h' or `unistd.h'. + + +File: autoconf.info, Node: Typedefs, Next: Library Functions, Prev: Header Files, Up: Specific Tests + +Typedefs +======== + + The following macros check for predefined C types: + + - Macro: AC_GETGROUPS_T + Define `GETGROUPS_T' to be whichever of `gid_t' or `int' is the + base type of the array argument to `getgroups'. + + - Macro: AC_MODE_T + If `mode_t' is not defined in `sys/types.h', define `mode_t' to be + `int'. + + - Macro: AC_OFF_T + If `off_t' is not defined in `sys/types.h', define `off_t' to be + `long'. + + - Macro: AC_PID_T + If `pid_t' is not defined in `sys/types.h', define `pid_t' to be + `int'. + + - Macro: AC_RETSIGTYPE + 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_SIZE_T + If `size_t' is not defined in `sys/types.h', define `size_t' to be + `unsigned'. + + - Macro: AC_UID_T + If `uid_t' is not defined in `sys/types.h', define `uid_t' to be + `int' and `gid_t' to be `int'. + + +File: autoconf.info, Node: Library Functions, Next: Structures, Prev: Typedefs, Up: Specific Tests + +Library Functions +================= + + The following macros check for particular C library functions: + + - Macro: AC_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 that fails, it looks for a function in + the standard C library. If that fails, it sets the `make' + 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'. + + If this macro finds `alloca.h', it defines `HAVE_ALLOCA_H'. + + This macro does not try to get `alloca' from the SVR3 `libPW' or + the SVR4 `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. Note that 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 /* not __GNUC__ */ + #if HAVE_ALLOCA_H + #include + #else /* not HAVE_ALLOCA_H */ + #ifdef _AIX + #pragma alloca + #else /* not _AIX */ + char *alloca (); + #endif /* not _AIX */ + #endif /* not HAVE_ALLOCA_H */ + #endif /* not __GNUC__ */ + + - Macro: AC_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 `make' variable + `LIBOBJS', and possibly defines several other C preprocessor + macros and `make' 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 always defines `NEED_SETGID', for `make'. The + value is `true' if special installation is required, `false' + if not. If `NEED_SETGID' is `true', it sets `KMEM_GROUP' to + the name of the group that should own the installed program. + + - Macro: AC_MMAP + If the `mmap' function exists and works correctly, define + `HAVE_MMAP'. + + - Macro: AC_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_STRCOLL + If the `strcoll' function exists and works correctly, define + `HAVE_STRCOLL'. This does a bit more than + `AC_HAVE_FUNCS(strcoll)', because some systems have incorrect + definitions of `strcoll', which should not be used. + + - Macro: AC_UTIME_NULL + If `utime(FILE, NULL)' sets FILE's timestamp to the present, + define `HAVE_UTIME_NULL'. + + - Macro: AC_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. + + - Macro: AC_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_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: Structures, Next: Compiler Characteristics, Prev: Library Functions, Up: Specific Tests + +Structures +========== + + The following macros check for certain structures or structure +members: + + - Macro: AC_STAT_MACROS_BROKEN + 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_ST_BLKSIZE + If `struct stat' contains an `st_blksize' member, define + `HAVE_ST_BLKSIZE'. + + - Macro: AC_ST_BLOCKS + If `struct stat' contains an `st_blocks' member, define + `HAVE_ST_BLOCKS'. Otherwise, add `fileblocks.o' to the `make' + variable `LIBOBJS'. + + - Macro: AC_ST_RDEV + If `struct stat' contains an `st_rdev' member, define + `HAVE_ST_RDEV'. + + - Macro: AC_TIME_WITH_SYS_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'. + + #ifdef TIME_WITH_SYS_TIME + #include + #include + #else + #ifdef HAVE_SYS_TIME_H + #include + #else + #include + #endif + #endif + + - Macro: AC_STRUCT_TM + If `time.h' does not define `struct tm', define `TM_IN_SYS_TIME', + which means that including `sys/time.h' defines `struct tm'. + + - Macro: AC_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'. This + macro calls `AC_STRUCT_TM' if it hasn't been called already. + + +File: autoconf.info, Node: Compiler Characteristics, Next: System Services, Prev: Structures, Up: Specific Tests + +Compiler Characteristics +======================== + + The following macros check for C compiler or machine architecture +features: + + - Macro: AC_ARG_ARRAY + If the address of an argument to a C function can not be used like + the start of an array, define `NO_ARG_ARRAY'. This ability allows + a sequence of arguments with the same type to be accessed as if + they were an array of values. + + - Macro: AC_CROSS_CHECK + 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 1. This information can be used by + `AC_TEST_PROGRAM' to determine whether to take a default action + instead of trying to run a test program (*note General Feature + Tests::.). + + - Macro: AC_CHAR_UNSIGNED + If the C type `char' is unsigned, define `__CHAR_UNSIGNED__', + unless the C compiler predefines it. + + - Macro: AC_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. (If using a configuration header file, the program + should include it before any other header files, to prevent + inconsistencies in declarations.) + + - Macro: AC_INLINE + If the C compiler is a version of GCC that supports the keyword + `__inline' but not `inline' (such as some NeXT versions), define + `inline' to be `__inline'. This macro calls `AC_PROG_CC' if it + hasn't been called already. + + - 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_SIZEOF_TYPE(int)' + instead (*note General Feature Tests::.). + + - 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_SIZEOF_TYPE(long)' instead (*note General Feature Tests::.). + + - Macro: AC_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_WORDS_BIGENDIAN + If words are stored with the most significant byte first (like + Motorola and SPARC, but not Intel and VAX, CPUs), define + `WORDS_BIGENDIAN'. + + +File: autoconf.info, Node: System Services, Next: UNIX Variants, Prev: Compiler Characteristics, Up: Specific Tests + +System Services +=============== + + The following macros check for operating system services: + + - Macro: AC_FIND_X + Try to locate the X Window System include files and libraries. Try + first 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 `true'; otherwise + set it to the empty string. + + The command line options `--x-includes=DIR' and + `--x-libraries=DIR' override the values chosen by this macro. + + - Macro: AC_FIND_XTRA + An enhanced version of `AC_FIND_X'. Put the C compiler flags that + X needs into `make' variable `X_CFLAGS', and the X linker flags + into `X_LIBS'. If X is not available, put `-DX_DISPLAY_MISSING' + into `X_CFLAGS'. + + Also check for special libraries that some systems need in order to + compile X programs. Add any that the system needs to `make' + variable `X_EXTRA_LIBS'. This macro calls `AC_FIND_X' and + `AC_ISC_POSIX' (*note UNIX Variants::.) if they have not already + been called. Because of the macro dependencies, if you call this + macro, you should let it call `AC_FIND_X' rather than doing that + yourself. + + - Macro: AC_HAVE_POUNDBANG (ACTION-IF-SUPPORTED [, + ACTION-IF-NOT-SUPPORTED]) + Check whether the system supports starting shell scripts with a + line of the form `#!/bin/csh' to select the shell to use. If `#!' + works, execute shell commands ACTION-IF-SUPPORTED; if not, execute + ACTION-IF-NOT-SUPPORTED. + + - Macro: AC_LONG_FILE_NAMES + If the system supports file names longer than 14 characters, define + `HAVE_LONG_FILE_NAMES'. + + - Macro: AC_REMOTE_TAPE + If BSD tape drive ioctls are available, define `HAVE_SYS_MTIO_H', + and if sockets are available add `rmt' to `make' variable `PROGS'. + + - Macro: AC_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: Specific 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: + + - 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 `make' variable + `LIBS'. Allows use of some BSD system calls and `getmntent'. + + - Macro: AC_IRIX_SUN + If on IRIX (Silicon Graphics UNIX), add `-lsun' to `make' variable + `LIBS'. Needed to get `getmntent'. At sites using Yellow + Pages/NIS, it is also needed to get properly working `gethostby*', + `getpw*', `getgr*', `getnetby*', and so on. + + - 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 `make' 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 `make' variable `LIBS'. Used to + get `strftime'. It must be called before checking for `strftime'. + + - Macro: AC_XENIX_DIR + If on Xenix, define `VOID_CLOSEDIR' and add `-lx' to `make' + variable `LIBS'. Also, if `sys/ndir.h' is not being used, add + `-ldir' to `LIBS'. Needed when using the directory reading + functions. This macro must be called after `AC_DIR_HEADER'. + + +File: autoconf.info, Node: General Purpose Macros, Next: Writing Macros, Prev: Specific Tests, Up: Top + +General Purpose Macros +********************** + + These macros provide ways for other macros to control the kind of +output that Autoconf produces or to check whether various kinds of +features are available. They all take arguments. When calling these +macros, there must not be any blank space between the macro name and +the open parentheses. + + Arguments to these macros can be more than one line long if they are +enclosed within the `m4' quote characters `[' and `]'. + + Within each section below, the macros are listed in alphabetical +order. These macros are defined in the file `acgeneral.m4'. + +* Menu: + +* Setup:: Controlling Autoconf operation. +* General Feature Tests:: Checking for kinds of features. +* Command Line:: Checking command line arguments. +* Setting Variables:: Setting shell and `make' variables. +* Printing Messages:: Notifying users of progress or problems. +* Language Choice:: Selecting which language to use for testing. +* Macro Ordering:: Enforcing ordering constraints. + + +File: autoconf.info, Node: Setup, Next: General Feature Tests, Up: General Purpose Macros + +Controlling Autoconf Setup +========================== + + The following macros control the kind of output that Autoconf +produces. + + - 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'. This macro + should be called right after `AC_INIT'. 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. + + Your distribution should contain a file `HEADER-TO-CREATE.in' that + looks as you want the final header file to look, including + comments, with default values in the `#define' statements. A + default value can be to `#undef' the variable instead of to define + it to a value, if your code tests for configuration options using + `#ifdef' instead of `#if'. + + You can use the program `autoheader' to create + `HEADER-TO-CREATE.in' (*note Invoking autoheader::.). + + - Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR) + Process the 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 (*note Invoking configure::., for + more information). + + - Macro: AC_OUTPUT ([FILE...] [,EXTRA-CMDS]) + Create output files (typically one or more `Makefile's) and + `config.status'. If `AC_CONFIG_HEADER' has been called, also + create the header file that was named as its argument. The + argument is a whitespace-separated list of files to create; if it + is omitted, no files are created. `AC_OUTPUT' creates each file + `FILE' in the list by copying `FILE.in', substituting the variable + values that have been selected by calling `AC_SUBST'. It creates + the directory that each file is in if it doesn't exist (but not the + parents of that directory). A plausible value for the argument to + `AC_OUTPUT' is `Makefile src/Makefile man/Makefile X/Imakefile'. + + If you pass EXTRA-CMDS, those commands will be inserted into + `config.status' to be run after all its other processing. + + - Macro: AC_PREPARE (UNIQUE-FILE-IN-SOURCE-DIR) + Find the source code directory and set up shell variables + necessary for other Autoconf macros to work. + 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 (*note Invoking configure::., for more + information). `AC_PREPARE' is the last thing done by `AC_INIT'. + Use `AC_PREPARE' instead of `AC_INIT' if you want to do argument + parsing yourself; never use both. + + - 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 (e.g., `1.8'), print an error message on the standard + error output and do not create `configure'. + + 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: General Feature Tests, Next: Command Line, Prev: Setup, Up: General Purpose Macros + +Checking for Kinds of Features +============================== + + These macros are templates that, when called with actual parameters, +check for various kinds of features. Many of these 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 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. + + One shell programming construction that you should not use in the +action arguments to these macros is `VAR=${VAR:-VALUE}'. Old BSD +shells, including the Ultrix `sh', don't understand the colon, and +complain and die. If you omit the colon, it works fine: +`VAR=${VAR-VALUE}'. Using the form without the colon has one small +disadvantage. Users can not select a default value by giving a +variable an empty value, e.g., `CC= configure'. Instead, they must +unset the variable, e.g., `unset CC; configure'. + + *Note Writing Macros::, for more information on how best to use these +macros. + + - Macro: AC_COMPILE_CHECK (ECHO-TEXT, INCLUDES, FUNCTION-BODY, + ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]) + Print `checking for ECHO-TEXT' to the standard output (using + `AC_CHECKING', *note Printing Messages::.). 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. + + - Macro: AC_FUNC_CHECK (FUNCTION, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]) + If FUNCTION is available, run shell commands ACTION-IF-FOUND, + otherwise ACTION-IF-NOT-FOUND. If the functions might be in + libraries other than the default C library, first call + `AC_HAVE_LIBRARY' for those libraries. If you just want to define + a symbol if the function is available, consider using + `AC_HAVE_FUNCS' instead. + + - Macro: AC_HAVE_FUNCS (FUNCTION...) + For each given FUNCTION in the whitespace-separated argument list + that is available, define `HAVE_FUNCTION' (in all caps). *Note + Specific Tests::, for a precise definition of "define" as it is + used here. If the functions might be in libraries other than the + default C library, first call `AC_HAVE_LIBRARY' for those + libraries. + + - Macro: AC_HAVE_HEADERS (HEADER-FILE...) + For each given HEADER-FILE in the whitespace-separated argument + list that exists, define `HAVE_HEADER-FILE' (in all caps). *Note + Specific Tests::, for a precise definition of "define" as it is + used here. + + - Macro: AC_HAVE_LIBRARY (LIBRARY [, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]]) + Create a test C program to see whether that program can be linked + with the specified library. ACTION-IF-FOUND is a list of shell + commands to run if the link succeeds (which means that the library + is present); 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 `-lfoo' to `LIBS' and + define `HAVE_LIBfoo' for library `foo'. LIBRARY can be written as + any of `foo', `-lfoo', or `libfoo.a'. In all of those cases, the + compiler is passed `-lfoo'. + + - Macro: AC_HEADER_CHECK (HEADER-FILE, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]) + If 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_HAVE_HEADERS' instead. + + - Macro: AC_HEADER_EGREP (PATTERN, HEADER-FILE, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]) + If the output of running the preprocessor on HEADER-FILE contains + the `egrep' regular expression PATTERN, execute shell commands + ACTION-IF-FOUND, otherwise execute + + 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. ACTION-IF-NOT-FOUND. + + You can not check whether preprocessor symbols are defined this + way, because they get expanded before `egrep' sees them. But you + can almost always detect them by simply using `#ifdef' directives + in your programs. + + - Macro: AC_PROGRAM_CHECK (VARIABLE, PROG-TO-CHECK-FOR, + VALUE-IF-FOUND, VALUE-IF-NOT-FOUND) + 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 VARIABLE was already set, do nothing. + Calls `AC_SUBST' for VARIABLE. + + - Macro: AC_PROGRAM_EGREP (PATTERN, PROGRAM, ACTION-IF-FOUND [, + ACTION-IF-NOT-FOUND]) + PROGRAM is the text of a C or C++ program, on which shell variable + and backquote substitutions are performed. If the output of + running the preprocessor on PROGRAM contains the `egrep' regular + expression PATTERN, execute shell commands ACTION-IF-FOUND, + otherwise execute ACTION-IF-NOT-FOUND. (It is an unfortunate + oversight that we use the word `PROGRAM' in Autoconf macro names to + sometimes mean C or C++ source code and sometimes mean a UNIX + command.) + + 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. + + - Macro: AC_PROGRAM_PATH (VARIABLE, PROG-TO-CHECK-FOR, + VALUE-IF-NOT-FOUND) + Similar to `AC_PROGRAM_CHECK', but set VARIABLE to the entire path + of PROG-TO-CHECK-FOR if found. Otherwise, set VARIABLE to the + value VALUE-IF-NOT-FOUND and perform no path checking. If + VARIABLE was already set, do nothing. Calls `AC_SUBST' for + VARIABLE. + + - Macro: AC_PROGRAMS_CHECK (VARIABLE, PROGS-TO-CHECK-FOR [, + VALUE-IF-NOT-FOUND]) + 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 will not be changed. + Calls `AC_SUBST' for VARIABLE. + + - Macro: AC_PROGRAMS_PATH (VARIABLE, PROGS-TO-CHECK-FOR [, + VALUE-IF-NOT-FOUND]) + Like `AC_PROGRAMS_CHECK', but if any of PROGS-TO-CHECK-FOR are + found, set VARIABLE to the entire pathname of the program 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 `make' variable `LIBOBJS'. If the functions might be + in libraries other than the default C library, first call + `AC_HAVE_LIBRARY' for those libraries. + + - Macro: AC_SIZEOF_TYPE (TYPE) + 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, gets a size of 0. UCTYPE is TYPE, with lowercase + converted to uppercase, spaces changed to underscores, and + asterisks changed to `P'. For example, the call + AC_SIZEOF_TYPE(int *) + + defines `SIZEOF_INT_P' to be 8 on DEC Alpha AXP systems. + + - Macro: AC_TEST_PROGRAM (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. + + If the optional argument ACTION-IF-CROSS-COMPILING is given and + 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. Instead, the shell commands ACTION-IF-CROSS-COMPILING + are run. If that argument is given, this macro calls + `AC_CROSS_CHECK' if it has not already been called (*note Compiler + Characteristics::.). + + - Macro: AC_TEST_CPP (INCLUDES, ACTION-IF-TRUE [, ACTION-IF-FALSE]) + INCLUDES is C or C++ `#include' statements and declarations, on + which shell variable and backquote 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 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: Command Line, Next: Setting Variables, Prev: General Feature Tests, Up: General Purpose Macros + +Checking Command Line Arguments +=============================== + + These macros check whether the user gave `configure' various command +line arguments. Like the general feature tests (*note General Feature +Tests::.), they may take an argument to use if the argument was given +and one for if it was not given. + + - Macro: AC_ENABLE (FEATURE, ACTION-IF-TRUE [, ACTION-IF-FALSE]) + If the user gave `configure' the option `--enable-FEATURE' or + `--disable-FEATURE', run shell commands ACTION-IF-TRUE. Otherwise + run shell commands ACTION-IF-FALSE. The name FEATURE should + consist only of alphanumeric characters and dashes. + + The FEATURE indicates an optional user-level facility. This + option allows 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' indicates that + the feature is *not* available. A feature with an argument looks + like `--enable-debug=stabs'. + + The argument is available to the shell commands ACTION-IF-TRUE in + the shell variable `enableval'. If no argument was given to + `--enable-FEATURE', `enableval' is `yes'. `--disable-FEATURE' is + equivalent to `--enable-FEATURE=no'. At present, arguments + containing blanks are not handled correctly; if you need an + argument to contain a list, require the items to be separated by + commas instead. (This restriction might disappear in the future.) + + - Macro: AC_PREFIX (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'. + + - Macro: AC_WITH (PACKAGE, ACTION-IF-TRUE [, ACTION-IF-FALSE]) + If the user gave `configure' the option `--with-PACKAGE' or + `--without-PACKAGE', run shell commands ACTION-IF-TRUE. Otherwise + run shell commands ACTION-IF-FALSE. The name PACKAGE should + consist only of alphanumeric characters and dashes. + + The PACKAGE indicates another software package that this program + should work with. For example, `--with-gnu-ld' means work with the + GNU linker instead of some other linker. `--with-x11' means work + with X11. + + The user can give an argument by following the package name with + `=' and the argument. Giving an argument of `no' is for packages + that would be 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. + + The argument is available to the shell commands ACTION-IF-TRUE in + the shell variable `withval'. If no argument was given to + `--with-PACKAGE', `withval' is `yes'. `--without-PACKAGE' is + equivalent to `--with-PACKAGE=no'. At present, arguments + containing blanks are not handled correctly; if you need an + argument to contain a list, require the items to be separated by + commas instead. (This restriction might disappear in the future.) + + +File: autoconf.info, Node: Setting Variables, Next: Printing Messages, Prev: Command Line, Up: General Purpose Macros + +Setting Variables +================= + + These macros help other macros to define shell and `make' variables. + + - Macro: AC_DEFINE (VARIABLE [, VALUE]) + Define C preprocessor variable VARIABLE. If VALUE is given, set + VARIABLE to that value, otherwise set it to 1. To use a shell + variable as the value, use `AC_DEFINE_UNQUOTED' instead and precede + double quotes in the value with backslashes. + + This macro adds to the shell variable `DEFS'. `AC_OUTPUT' later + substitutes the values in `DEFS' into the file(s) that it + generates (typically `Makefile'). Alternately, if + `AC_CONFIG_HEADER' has been called, `AC_OUTPUT' creates a header + file by substituting the correct values into `#define' statements + in a template file. + + For example, suppose your `configure.in' calls + `AC_CONFIG_HEADER(conf.h)' and `AC_HAVE_HEADERS(unistd.h)'. You + could have code like this in `conf.h.in': + + /* Define as 1 if you have unistd.h. */ + #define HAVE_UNISTD_H 0 + + On systems that have `unistd.h', `configure' will change the 0 to + a 1. On other systems, it will leave the line unchanged. + Alternately, if you prefer to use `#ifdef', your `conf.h.in' could + have code like this: + + /* Define if you have unistd.h. */ + #undef HAVE_UNISTD_H + + 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). + + Due to the syntactical bizarreness of the Bourne shell, do not use + semicolons to separate `AC_DEFINE' 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_HEADER_CHECK(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf") + + or this: + + AC_HEADER_CHECK(elf.h, + AC_DEFINE(SVR4) + LIBS="$LIBS -lelf") + + instead of this: + + AC_HEADER_CHECK(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf") + + - Macro: AC_DEFINE_UNQUOTED (VARIABLE [, VALUE]) + Like `AC_DEFINE', but it does nothing to quote VALUE from various + shell and `sed' expansions it will undergo. VALUE will be used in + many different contexts requiring different quoting, and it is up + to you to make sure it works right. Use this macro instead of + `AC_DEFINE' when VALUE contains a shell variable. For example: + + AC_DEFINE_UNQUOTED(config_machfile, ${machfile}) + + - Macro: AC_SUBST (VARIABLE) + Substitute the variable VARIABLE when creating the output files + (typically one or more `Makefile's). This means replace instances + of `@VARIABLE@', e.g. in `Makefile.in', with the current value of + the shell variable VARIABLE. If this macro were not called, the + value of VARIABLE would not be set in the output files, even + though `configure' had figured out a value for it. + + You can set or add to the value of VARIABLE in the usual shell + way. For example, to add `-ltermcap' to the value of the variable + `LIBS': + + LIBS="$LIBS -ltermcap" + + +File: autoconf.info, Node: Printing Messages, Next: Language Choice, Prev: Setting Variables, Up: General Purpose Macros + +Printing Messages +================= + + `configure' scripts need to give users running them several kinds of +information. The following macros print messages in ways appropriate +for different kinds of information. 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. +Other macros should rarely need to run `echo' directly to print +messages for the `configure' 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_CHECKING (FEATURE-DESCRIPTION) + Notify the user that `configure' is checking for a particular + feature. This macro prints a message that starts with `checking '. + It prints nothing if `configure' is run with the `--silent' or + `--quiet' option. The FEATURE-DESCRIPTION should be something + like `whether the Fortran compiler accepts C++ comments' or `for + c89'. + + - Macro: AC_ERROR (ERROR-DESCRIPTION) + Notify the user of an error that prevents `configure' from + completing. This macro prints an error message on the standard + error stream and exits `configure' with a nonzero status. + eRROR-DESCRIPTION should be something like `invalid value $HOME + for \$HOME'. + + - Macro: AC_VERBOSE (RESULT-DESCRIPTION) + Notify the user of the results of a check. This information is + only printed if `configure' is run with the `--verbose' option. + rESULT-DESCRIPTION should be something like `setting ADA to $ADA'. + + - Macro: AC_WARN (PROBLEM-DESCRIPTION) + Notify the `configure' user of a possible problem. This macro + prints the message on the standard error stream; `configure' + continues running afterward, so macros that call `AC_WARN' should + provide a default (back-up) behavior for the situations they warn + about. PROBLEM-DESCRIPTION should be something like `ln -s seems + to make hard links'. + + +File: autoconf.info, Node: Language Choice, Next: Macro Ordering, Prev: Printing Messages, Up: General Purpose Macros + +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. + + This is the initial state. + + - Macro: AC_LANG_CPLUSPLUS + Do compilation tests using `CXX' and `CXXCPP' and use extension + `.C' for test programs. + + - 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_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_REQUIRE_CPP + Ensure that whichever preprocessor would currently be used for + tests has been found. Calls `AC_REQUIRE' (*note Macro + Ordering::.) with an argument of either `AC_PROG_CPP' or + `AC_PROG_CXXCPP', depending on which language is current. + + +File: autoconf.info, Node: Macro Ordering, Prev: Language Choice, Up: General Purpose Macros + +Macro Ordering +============== + + These macros provide ways for other macros to make sure that they are +called in the correct order. + + - 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 contain a call to `AC_PROVIDE' to indicate + that it has been called. + + This macro should be used when one macro makes changes that might + affect another macro, so that the other macro should probably not + be called first. 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]) + + This warns the user if a call to `AC_PROG_CPP' has already occurred + when `AC_PROG_CC' is called. + + - 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_BEFORE'. 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. + + A sample call is: + + AC_OBSOLETE([$0], [; use AC_HAVE_HEADERS(unistd.h) instead]) + + - Macro: AC_PROVIDE (MACRO-NAME) + Set a flag recording that MACRO-NAME has been called. The + argument 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]) + + - 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. The body of MACRO-NAME must contain a call to + `AC_PROVIDE' to indicate that it has been called. + + Macros that need some other macro to be called before they are + called can use `AC_REQUIRE' to ensure that it has been, in case + the person who made `configure.in' forgot or didn't know to do it. + `AC_REQUIRE' and `AC_PROVIDE' together can ensure that a macro is + only called if it is needed, and only called once. *Note + Dependencies Between Macros::, for more information. + + +File: autoconf.info, Node: Writing Macros, Next: Makefiles, Prev: General Purpose Macros, Up: Top + +Writing Macros +************** + + If your package needs to test for some feature that none of the +macros supplied with Autoconf handles, you'll need to write one or more +new Autoconf macros. Here are some suggestions and some of the +rationale behind why the existing macros are written the way they are. +You can also learn a lot about how to write Autoconf macros by looking +at the existing ones. If something goes wrong in one or more of the +Autoconf tests, this information can help you understand why they work +the way they do and the assumptions behind them, which might help you +figure out how to best solve the problem. + + If you add macros that you think would be useful to other people, or +find problems with the distributed macros, please send electronic mail +to `bug-gnu-utils@prep.ai.mit.edu', so we can consider them for future +releases of Autoconf. Please include the Autoconf version number, +which you can get by running `autoconf --version'. + +* Menu: + +* Macro Format:: Basic format of an Autoconf macro. +* Quoting:: Protecting macros from unwanted expansion. +* Dependencies Between Macros:: What to do when macros depend on other macros. +* Checking for Files:: Finding whether a file exists. +* Checking for Symbols:: Finding whether a symbol is defined. +* Test Programs:: Writing programs to test for features. +* Multiple Cases:: Tests for several possible values. + + +File: autoconf.info, Node: Macro Format, Next: Quoting, Up: Writing Macros + +Macro Format +============ + + Autoconf macros are defined as arguments to the `m4' builtin command +`define'. Their overall structure looks like this: + + define(MACRO-NAME, [MACRO-BODY])dnl + +The square brackets here do not indicate optional text: they should +literally be present in the macro definition. + + All of the Autoconf macros have names starting with `AC_' to prevent +them from accidentally conflicting with other text. All shell +variables that they use for internal purposes have 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. + + The `m4' builtin `dnl' prevents a newline from being inserted in the +output where the macro is defined; without it, the generated +`configure' script would begin with dozens of blank lines. `dnl' is +also used to introduce comments in `m4'; it causes `m4' to discard the +rest of the input line. + + You should quote the entire macro body with square brackets to avoid +macro expansion problems (*note Quoting::.). You can refer to any +arguments passed to the macro as `$1', `$2', etc. + + *Note How to define new macros: (m4.info)Definitions, for more +complete information on writing `m4' macros. + + +File: autoconf.info, Node: Quoting, Next: Dependencies Between Macros, Prev: Macro Format, 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. + + Autoconf (in `acgeneral.m4') 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. In those places, they use the `m4' builtin command +`changequote' to temporarily disable quoting before the code that uses +brackets, like this: + + changequote(,)dnl + +Then they turn quoting back on again with another call to `changequote': + + changequote([,])dnl + + 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, Next: Checking for Files, 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. + + +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, if you write a new macro +that uses the C preprocessor, it depends on `AC_PROG_CPP' having been +called first to set the shell variable `CPP' (*note Alternative +Programs::.). + + Rather than forcing the user of the macros to keep track of all of +the dependencies between them, you can use the macros `AC_PROVIDE' and +`AC_REQUIRE' to do it automatically. *Note Macro Ordering::, for more +information on their syntax. + + The new macro that runs the C preprocessor should contain, somewhere +before `CPP' is used, the statement + + AC_REQUIRE([AC_PROG_CPP]) + +and the macro `AC_PROG_CPP' should contain the statement (anywhere in +its body) + + AC_PROVIDE([$0]) + +Then, when the new macro is run, it will invoke `AC_PROG_CPP' if and +only if `AC_PROG_CPP' has not already been run. + + +File: autoconf.info, Node: Suggested Ordering, Prev: Prerequisite Macros, Up: Dependencies Between Macros + +Suggested Ordering +------------------ + + Some macros should be run before another macro if both are called, +but neither requires the other to be called. For example, a macro like +`AC_AIX' that changes the behavior of the C compiler (*note UNIX +Variants::.) should be called before any macros that run the C compiler. +Many of these dependencies are noted in the documentation. + + Autoconf provides a way 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'. It is not a fatal error; `configure' is created as usual. + + The `AC_BEFORE' macro causes `m4' to print a warning message on the +standard error output when a macro is used before another macro which +might change its behavior. The macro which should come first should +contain a call to `AC_BEFORE' and the macro which should come later +should contain a call to `AC_PROVIDE'. + + For example, `AC_AIX' contains + + AC_BEFORE([$0], [AC_COMPILE_CHECK]) + +and `AC_COMPILE_CHECK' contains + + AC_PROVIDE([$0]) + +As a result, if `AC_AIX' is called after `AC_COMPILE_CHECK', it will +note that `AC_COMPILE_CHECK' has already been called and print a +warning message. + + +File: autoconf.info, Node: Checking for Files, Next: Checking for Symbols, Prev: Dependencies Between Macros, Up: Writing Macros + +Checking for Files +================== + + If you need to check whether a file other than a C header file +exists, use `test -f FILENAME'. 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. + + Do not use `test -x', because 4.3BSD does not have it. Use `test +-f' or `test -r' instead. + + +File: autoconf.info, Node: Checking for Symbols, Next: Test Programs, Prev: Checking for Files, Up: Writing Macros + +Checking for Symbols +==================== + + If you need to check whether a symbol is defined in a C header file, +you can use `AC_HEADER_EGREP' if the symbol is not a C preprocessor +macro (*note General Feature Tests::.), or compile a small test program +that includes the file and references the symbol (*note Test +Programs::.). Don't directly `grep' for the symbol in the file, +because on some systems it might be defined in another header file that +the file you are checking `#include's. + + However, if you need to check for a particular UNIX variant which is +distinguished by having certain text in a certain file, then use `grep' +(or `egrep'). But 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. + + To check whether the Autoconf macros have already defined a certain C +preprocessor symbol, you can use a `case' statement like this: + + case "$DEFS" in + *HAVE_FOO*) ;; + *) LIBOBJS="$LIBOBJS foo.o" ;; + esac + +Make sure to enclose the variable name you are checking (usually +`DEFS') in double quotes, because otherwise some old versions of `bash' +misinterpret the statement. + + +File: autoconf.info, Node: Test Programs, Next: Multiple Cases, Prev: Checking for Symbols, Up: Writing Macros + +Test Programs +============= + + Autoconf checks for many features by compiling small test programs. +To find out whether a library function is available, Autoconf tries to +compile a small program that uses it. This is unlike Larry Wall's +Metaconfig, which 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 and flexible 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 +`configure' to check aspects of the function's runtime behavior if +needed. On the other hand, it is sometimes slower than scanning the +libraries. + + If you need to check for a condition other than whether some symbol +exists on the system or has a certain value, then you can't use +`AC_COMPILE_CHECK' (*note General Feature Tests::.). You have to write +a test program by hand. You can compile and run it using +`AC_TEST_PROGRAM' (*note General Feature Tests::.). + + Try to avoid writing test programs if possible, because using them +prevents people from configuring your package for cross-compiling. If +it's really best that you test for a run-time behavior, try to provide a +default "worst case" value to use when cross-compiling makes run-time +tests impossible. You do this by passing the optional last argument to +`AC_TEST_PROGRAM'. + +* Menu: + +* Guidelines:: General rules for writing test programs. +* Tricks:: Special ways to work around problems. + + +File: autoconf.info, Node: Guidelines, Next: Tricks, Up: Test Programs + +Guidelines for Test Programs +---------------------------- + + Test programs 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 the argument to `return' in `main' is +ignored. They should not write anything to the standard output. + + 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_STDC_HEADERS', 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: Tricks, Prev: Guidelines, Up: Test Programs + +Tricks for Test Programs +------------------------ + + 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: Multiple Cases, Prev: Test Programs, Up: Writing Macros + +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 excerpted from the `configure.in' for GNU `find'. +It uses the shell variable `fstype' to keep track of whether the +remaining cases need to be checked. There are several more cases which +are not shown here but follow the same pattern. + + echo checking how to get filesystem type + # SVR4. + AC_TEST_CPP([#include + #include ], AC_DEFINE(FSTYPE_STATVFS) fstype=1) + if test -z "$fstype"; then + # SVR3. + AC_TEST_CPP([#include + #include ], AC_DEFINE(FSTYPE_USG_STATFS) fstype=1) + fi + if test -z "$fstype"; then + # AIX. + AC_TEST_CPP([#include + #include ], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=1) + fi + + +File: autoconf.info, Node: Makefiles, Next: Invoking configure, Prev: Writing Macros, Up: Top + +Makefiles +********* + + Each subdirectory in a distribution should come with a file +`Makefile.in', from which `configure' will produce a `Makefile' in that +directory. Most of the substitutions that `configure' does are simple: +for each configuration variable that the package uses, it just replaces +occurrences of `@VARIABLE@' with the value that `configure' has +determined for that variable. Any occurrences of `@VARIABLE@' for +variables that `configure' does not know about are passed through +unchanged. + + There is no point in checking for the correct value to give a +variable that is never used. Every variable that the `configure' script +might set a value for should appear in a `@VARIABLE@' reference in at +least one `Makefile.in'. If `AC_CONFIG_HEADER' is called, `configure' +replaces `@DEFS@' with `-DHAVE_CONFIG_H', since the contents of `DEFS' +would be redundant. + + *Note Makefile Conventions: (standards.info)Makefiles, for more +information on what to put in Makefiles. *Note Sample Makefile.in::, +for an example of a real `Makefile.in'. + +* Menu: + +* Predefined Variables:: Heavily used `make' variables. +* Installation Prefixes:: A special variable substitution. +* VPATH Substitutions:: Compiling in a different directory. +* Automatic Remaking:: Makefile rules for configuring. + + +File: autoconf.info, Node: Predefined Variables, Next: Installation Prefixes, Up: Makefiles + +Predefined Variables +==================== + + Some `make' variables are predefined by the Autoconf macros. +`AC_SUBST' is called for them automatically (*note Setting +Variables::.), so in your `Makefile.in' files you can get their values +by enclosing their names in `@' characters. *Note Makefiles::, for +more information on `@' substitutions. The variables that are defined +by the general purpose Autoconf macros are: + + - Variable: exec_prefix + The installation prefix for architecture-specific files. + + - Variable: prefix + The installation prefix for architecture-independent files. *Note + Installation Prefixes::, for an alternate way to set this variable. + + - Variable: srcdir + The directory that contains the source code for that `Makefile'. + *Note Installation Prefixes::, for an alternate way to set this + variable. + + - Variable: top_srcdir + The top-level source code directory for the package. In the + top-level directory, this is the same as `srcdir'. + + - Variable: DEFS + `-D' options to pass to the C compiler. If `AC_CONFIG_HEADER' is + called, `configure' replaces `@DEFS@' with `-DHAVE_CONFIG_H', + since the contents of `DEFS' would be redundant. + + - Variable: LIBS + `-l' and `-L' options to pass to the linker. + + - Variable: LIBOBJS + Names of object files (ending in `.o'). Set by `AC_REPLACE_FUNCS' + (*note General Feature Tests::.). + + +File: autoconf.info, Node: Installation Prefixes, Next: VPATH Substitutions, Prev: Predefined Variables, Up: Makefiles + +Installation Prefixes +===================== + + Autoconf-generated `configure' scripts support an alternate method +for substituting two particular variables, for compatibility with +Cygnus `configure'. This method is not recommended. + + If `configure' has figured out a value for the installation prefix, +either by the user supplying one on the command line (*note Invoking +configure::.) or with `AC_PREFIX' (*note General Feature Tests::.), +then it substitutes that value in `Makefile's that it creates. +Wherever a `Makefile.in' contains lines like + + prefix = /usr/local + exec_prefix = ${prefix} + +`configure' substitutes the value it figured out. The substitution +only occurs if the word `prefix' or `exec_prefix' is not preceded by +any other characters on the line, and `configure' has figured out a +value for the prefix. + + There can be separate installation prefixes for architecture-specific +files (`exec_prefix') and architecture-independent files (`prefix'). +*Note Invoking configure::, for more information on setting them. + + Autoconf `configure' scripts replace these two variables without +requiring them to be enclosed in `@' characters, and only if they have +been set, because the Cygnus `configure' does so. In retrospect, being +compatible in this way was a bad decision, because it created an +inconsistency in Autoconf without giving significant benefits. This +wart will be removed in a future release of Autoconf. + + +File: autoconf.info, Node: VPATH Substitutions, Next: Automatic Remaking, Prev: Installation Prefixes, Up: Makefiles + +`VPATH' Substitutions +===================== + + You might want to compile a software package in a different directory +from the one that contains the source code. Doing this allows you to +compile the package for several architectures simultaneously from the +same copy of the source code and keep multiple sets of object files on +disk. + + 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.in'. + + 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: VPATH Substitutions, Up: Makefiles + +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 `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. + + configure: configure.in aclocal.m4 + cd ${srcdir} && autoconf + + # autoheader might not change config.h.in + config.h.in: stamp-h.in + stamp-h.in: configure.in aclocal.m4 acconfig.h config.h.top + cd ${srcdir} && autoheader + touch ${srcdir}/stamp-h.in + + # config.status might not change config.h + config.h: stamp-h + stamp-h: config.h.in config.status + ./config.status + touch stamp-h + + Makefile: Makefile.in config.status + ./config.status + + config.status: configure + ./config.status --recheck + + *Note Invoking config.status::, for more information on handling +configuration-related dependencies. + + +File: autoconf.info, Node: Invoking configure, Next: Example, Prev: Makefiles, Up: Top + +Running `configure' Scripts +*************************** + + 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. Here is how to configure a package that uses a +`configure' script. + + Normally, you just `cd' to the directory containing the package's +source code and type `./configure'. 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 it is running, it prints +some messages that tell what it is doing. If you don't want to see any +messages, run `configure' with its standard output redirected to +`/dev/null'; for example, `./configure >/dev/null'. + + To compile the package in a different directory from the one +containing the source code, 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 +for some reason `configure' is not in the source code directory that +you are configuring, then it will report that it can't find the source +code. In that case, run `configure' with the option `--srcdir=DIR', +where DIR is the directory that contains the source code. + + 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'. Alternately, you can do so by consistently +giving a value for the `prefix' variable when you run `make', e.g., + make prefix=/usr/gnu + make prefix=/usr/gnu install + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +give `configure' the option `--exec-prefix=PATH' or set the `make' +variable `exec_prefix' to PATH, the package will use PATH as the prefix +for installing programs and libraries. Data files and documentation +will still use the regular prefix. Normally, all files are installed +using the same prefix. + + Some packages pay attention to `--with-PACKAGE' options to +`configure', where PACKAGE is something like `gnu-as' or `x' (for the X +Window System). They may also pay attention to `--enable-FEATURE' +options, where FEATURE indicates an optional part of the package. The +README should mention any `--with-' and `--enable-' options that the +package recognizes. + + `configure' also recognizes the following options: + +`--help' + Print a summary of the options to `configure', and exit. + +`--quiet' +`--silent' + Do not print messages saying which checks are being made. + +`--verbose' + Print the results of the checks. + +`--version' + Print the version of Autoconf used to generate the `configure' + script, and exit. + +`--x-includes=DIR' + X include files are in DIR. + +`--x-libraries=DIR' + X library files are in DIR. + + `configure' also accepts and ignores some other options. + +* Menu: + +* Overriding variables:: Workarounds for unusual systems. +* Invoking config.status:: Recreating a configuration. + + +File: autoconf.info, Node: Overriding variables, Next: Invoking config.status, Up: Invoking configure + +Overriding variables +==================== + + On systems that require unusual options for compilation or linking +that the package's `configure' script does not know about, you can give +`configure' initial values for variables by setting them in the +environment. In Bourne-compatible shells, you can do that on the +command line like this: + + CC='gcc -traditional' LIBS=-lposix ./configure + +On systems that have the `env' program, you can do it like this: + + env CC='gcc -traditional' LIBS=-lposix ./configure + + Here are the `make' variables that you might want to override with +environment variables when running `configure'. + + For these variables, any value given in the environment overrides the +value that `configure' would choose: + + - Variable: CC + C compiler program. The default is `cc'. + + - Variable: INSTALL + Program to use to install files. The default is `install' if you + have it, `cp' otherwise. + + For these variables, any value given in the environment is added to +the value that `configure' chooses: + + - Variable: DEFS + Configuration options, in the form `-Dfoo -Dbar...'. Do not use + this variable in packages that create a configuration header file. + + - Variable: LIBS + Libraries to link with, in the form `-lfoo -lbar...'. + + In the long term, most problems requiring manual intervention should +be fixed by updating either the Autoconf macros or the `configure.in' +file for that package. *Note Making configure Scripts::, for a +discussion of that subject. + + +File: autoconf.info, Node: Invoking config.status, Prev: Overriding variables, Up: Invoking configure + +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 prevents `configure' from +running `config.status' and creating `Makefile' and other files. (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. The default is `/bin/sh'. + + The following two 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.status might not change config.h + config.h: stamp-h + stamp-h: config.h.in config.status + CONFIG_FILES= CONFIG_HEADERS=config.h ./config.status + touch 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: Example, Next: Preprocessor Symbol Index, Prev: Invoking configure, Up: Top + +An Example +********** + + Here are sample `configure.in' and `Makefile.in' files, to give a +real illustration of using Autoconf. They are from the GNU `cpio' +package, which also includes the `mt' and `rmt' programs. This package +does not use a configuration header file; it passes `-D' options to the +C compiler on the command line. + +* Menu: + +* Sample configure.in:: An example of a `configure' template. +* Sample Makefile.in:: An example of a `Makefile' template. + + +File: autoconf.info, Node: Sample configure.in, Next: Sample Makefile.in, Up: Example + +Sample `configure.in' +===================== + +Here is `configure.in' from GNU `cpio'. The `dnl' macro after +`AC_SUBST' is suppresses an extra (though harmless) newline in the +generated `configure' script (because the `AC_SUBST' macro does not +produce any output where it is called). + + dnl Process this file with autoconf to produce a configure script. + AC_INIT(cpio.h) + PROGS="cpio" + AC_SUBST(PROGS)dnl + AC_PROG_CC + AC_PROG_CPP + AC_GCC_TRADITIONAL + AC_PROG_INSTALL + AC_AIX + AC_MINIX + AC_ISC_POSIX + AC_RETSIGTYPE + AC_MAJOR_HEADER + AC_REMOTE_TAPE + test -n "$have_mtio" && PROGS="$PROGS mt" + AC_RSH + AC_CONST + AC_UID_T + AC_STDC_HEADERS + AC_HAVE_HEADERS(string.h fcntl.h utime.h unistd.h sys/io/trioctl.h) + AC_REPLACE_FUNCS(fnmatch bcopy mkdir strdup) + AC_HAVE_FUNCS(strerror lchown) + AC_VPRINTF + AC_ALLOCA + AC_XENIX_DIR + AC_HAVE_LIBRARY(socket, [LIBS="$LIBS -lsocket"]) + AC_HAVE_LIBRARY(nsl, [LIBS="$LIBS -lnsl"]) + AC_OUTPUT(Makefile) + + +File: autoconf.info, Node: Sample Makefile.in, Prev: Sample configure.in, Up: Example + +Sample `Makefile.in' +==================== + +Here is `Makefile.in' from GNU `cpio', with some irrelevant lines +omitted, for brevity. + + srcdir = @srcdir@ + VPATH = @srcdir@ + + CC = @CC@ + + INSTALL = @INSTALL@ + INSTALL_PROGRAM = @INSTALL_PROGRAM@ + INSTALL_DATA = @INSTALL_DATA@ + + DEFS = @DEFS@ + LIBS = @LIBS@ + RTAPELIB = @RTAPELIB@ + + CFLAGS = -g + LDFLAGS = -g + + prefix = /usr/local + exec_prefix = $(prefix) + binprefix = + manprefix = + + bindir = $(exec_prefix)/bin + libdir = $(exec_prefix)/lib + mandir = $(prefix)/man/man1 + manext = 1 + + SHELL = /bin/sh + + SRCS = copyin.c copyout.c copypass.c defer.c dstring.c global.c \ + main.c tar.c util.c error.c getopt.c getopt1.c filemode.c version.c \ + rtapelib.c dirname.c idcache.c makepath.c xmalloc.c stripslash.c \ + userspec.c xstrdup.c bcopy.c fnmatch.c mkdir.c strdup.c + OBJS = copyin.o copyout.o copypass.o defer.o dstring.o global.o \ + main.o tar.o util.o error.o getopt.o getopt1.o filemode.o version.o \ + $(RTAPELIB) dirname.o idcache.o makepath.o xmalloc.o stripslash.o \ + userspec.o xstrdup.o @LIBOBJS@ @ALLOCA@ + # mt source files not shared with cpio. + MT_SRCS = mt.c argmatch.c + MT_OBJS = mt.o argmatch.o error.o getopt.o getopt1.o \ + xmalloc.o version.o $(RTAPELIB) @ALLOCA@ + HDRS = cpio.h cpiohdr.h tar.h tarhdr.h defer.h dstring.h extern.h filetypes.h \ + system.h fnmatch.h getopt.h rmt.h + DISTFILES = $(SRCS) $(HDRS) COPYING COPYING.LIB ChangeLog Makefile.in \ + README NEWS INSTALL cpio.1 mt.1 makefile.pc makefile.os2 cpio.def \ + configure configure.in mkinstalldirs $(MT_SRCS) rmt.c tcexparg.c alloca.c + + all: @PROGS@ + + .c.o: + $(CC) -c $(CPPFLAGS) $(DEFS) -I$(srcdir) $(CFLAGS) $< + + install: installdirs all $(srcdir)/cpio.1 $(srcdir)/mt.1 + $(INSTALL_PROGRAM) cpio $(bindir)/$(binprefix)cpio + test ! -f mt || $(INSTALL_PROGRAM) mt $(bindir)/$(binprefix)mt + -test ! -f rmt || $(INSTALL_PROGRAM) rmt $(libdir)/rmt + $(INSTALL_DATA) $(srcdir)/cpio.1 $(mandir)/$(manprefix)cpio.$(manext) + test ! -f mt || \ + $(INSTALL_DATA) $(srcdir)/mt.1 $(mandir)/$(manprefix)mt.$(manext) + + installdirs: + $(srcdir)/mkinstalldirs $(bindir) $(libdir) $(mandir) + + uninstall: + cd $(bindir); rm -f $(binprefix)cpio $(binprefix)mt + -rm -f $(libdir)/rmt + cd $(mandir); rm -f $(manprefix)cpio.$(manext) $(manprefix)mt.$(manext) + + check: + @echo No tests are supplied. + + cpio: $(OBJS) + $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) + + rmt: rmt.o + $(CC) $(LDFLAGS) -o $@ rmt.o $(LIBS) + + mt: $(MT_OBJS) + $(CC) $(LDFLAGS) -o $@ $(MT_OBJS) $(LIBS) + + Makefile: Makefile.in config.status + $(SHELL) config.status + config.status: configure + $(SHELL) config.status --recheck + configure: configure.in + cd $(srcdir); autoconf + + TAGS: $(SRCS) + etags $(SRCS) + + clean: + rm -f cpio rmt mt *.o core + + mostlyclean: clean + + distclean: clean + rm -f Makefile config.status + + realclean: distclean + rm -f TAGS + + dist: $(DISTFILES) + echo cpio-`sed -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname + rm -rf `cat .fname` + mkdir `cat .fname` + -ln $(DISTFILES) `cat .fname` + for file in $(DISTFILES); do \ + test -r `cat .fname`/$$file || cp -p $$file `cat .fname`; \ + done + tar chzf `cat .fname`.tar.gz `cat .fname` + rm -rf `cat .fname` .fname + + +File: autoconf.info, Node: Preprocessor Symbol Index, Next: Macro Index, Prev: Example, 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: + +* CC: Overriding variables. +* CONFIG_FILES: Invoking config.status. +* CONFIG_HEADERS: Invoking config.status. +* CONFIG_SHELL: Invoking config.status. +* const: Compiler Characteristics. +* C_ALLOCA: Library Functions. +* DEFS: Overriding variables. +* DEFS: Predefined Variables. +* DGUX: Library Functions. +* DIRENT: Header Files. +* exec_prefix: Predefined Variables. +* GETGROUPS_T: Typedefs. +* GETLODAVG_PRIVILEGED: Library Functions. +* gid_t: Typedefs. +* HAVE_FUNCTION: General Feature Tests. +* HAVE_HEADER: General Feature Tests. +* HAVE_ALLOCA_H: Library Functions. +* HAVE_CONFIG_H: Setup. +* HAVE_DOPRNT: Library Functions. +* HAVE_LONG_DOUBLE: Compiler Characteristics. +* HAVE_LONG_FILE_NAMES: System Services. +* HAVE_MMAP: Library Functions. +* HAVE_NETDB_H: Alternative Programs. +* HAVE_RESTARTABLE_SYSCALLS: System Services. +* HAVE_STRCOLL: Library Functions. +* HAVE_ST_BLKSIZE: Structures. +* HAVE_ST_BLOCKS: Structures. +* HAVE_ST_RDEV: Structures. +* HAVE_SYS_MTIO_H: System Services. +* HAVE_TM_ZONE: Structures. +* HAVE_TZNAME: Structures. +* HAVE_UNISTD_H: Header Files. +* HAVE_UTIME_NULL: Library Functions. +* HAVE_VFORK_H: Library Functions. +* HAVE_VPRINTF: Library Functions. +* HAVE_WAIT3: Library Functions. +* inline: Compiler Characteristics. +* INSTALL: Overriding variables. +* INT_16_BITS: Compiler Characteristics. +* LIBOBJS: Predefined Variables. +* LIBS: Predefined Variables. +* LIBS: Overriding variables. +* LONG_64_BITS: Compiler Characteristics. +* MAJOR_IN_MKDEV: Header Files. +* MAJOR_IN_SYSMACROS: Header Files. +* mode_t: Typedefs. +* NDIR: Header Files. +* NEED_MEMORY_H: Header Files. +* NEED_SETGID: Library Functions. +* NLIST_NAME_UNION: Library Functions. +* NLIST_STRUCT: Library Functions. +* NO_ARG_ARRAY: Compiler Characteristics. +* NO_MINUS_C_MINUS_O: Alternative Programs. +* NO_REMOTE: Alternative Programs. +* off_t: Typedefs. +* pid_t: Typedefs. +* prefix: Predefined Variables. +* RETSIGTYPE: Typedefs. +* SETVBUF_REVERSED: Library Functions. +* size_t: Typedefs. +* srcdir: Predefined Variables. +* STDC_HEADERS: Header Files. +* SVR4: Library Functions. +* SYSDIR: Header Files. +* SYSNDIR: Header Files. +* SYS_SIGLIST_DECLARED: Header Files. +* TIME_WITH_SYS_TIME: Structures. +* TM_IN_SYS_TIME: Structures. +* top_srcdir: Predefined Variables. +* uid_t: Typedefs. +* UMAX: Library Functions. +* UMAX4_3: Library Functions. +* USG: Header Files. +* vfork: Library Functions. +* VOID_CLOSEDIR: Header Files. +* VOID_CLOSEDIR: UNIX Variants. +* WORDS_BIGENDIAN: Compiler Characteristics. +* YYTEXT_POINTER: Alternative Programs. +* _ALL_SOURCE: UNIX Variants. +* _MINIX: UNIX Variants. +* _POSIX_1_SOURCE: UNIX Variants. +* _POSIX_SOURCE: UNIX Variants. +* _POSIX_SOURCE: UNIX Variants. +* _POSIX_VERSION: Header Files. +* __CHAR_UNSIGNED__: Compiler Characteristics. + + +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: Library Functions. +* ARG_ARRAY: Compiler Characteristics. +* BEFORE: Macro Ordering. +* CHAR_UNSIGNED: Compiler Characteristics. +* CHECKING: Printing Messages. +* COMPILE_CHECK: General Feature Tests. +* CONFIG_HEADER: Setup. +* CONST: Compiler Characteristics. +* CROSS_CHECK: Compiler Characteristics. +* DEFINE: Setting Variables. +* DEFINE_UNQUOTED: Setting Variables. +* DIR_HEADER: Header Files. +* DYNIX_SEQ: UNIX Variants. +* ENABLE: Command Line. +* ERROR: Printing Messages. +* FIND_X: System Services. +* FIND_XTRA: System Services. +* FUNC_CHECK: General Feature Tests. +* GCC_TRADITIONAL: Alternative Programs. +* GETGROUPS_T: Typedefs. +* GETLOADAVG: Library Functions. +* HAVE_FUNCS: General Feature Tests. +* HAVE_HEADERS: General Feature Tests. +* HAVE_LIBRARY: General Feature Tests. +* HAVE_LONG_DOUBLE: Compiler Characteristics. +* HAVE_POUNDBANG: System Services. +* HEADER_CHECK: General Feature Tests. +* HEADER_EGREP: General Feature Tests. +* INIT: Setup. +* INLINE: Compiler Characteristics. +* 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. +* LN_S: Alternative Programs. +* LONG_64_BITS: Compiler Characteristics. +* LONG_FILE_NAMES: System Services. +* MAJOR_HEADER: Header Files. +* MEMORY_H: Header Files. +* MINIX: UNIX Variants. +* MINUS_C_MINUS_O: Alternative Programs. +* MMAP: Library Functions. +* MODE_T: Typedefs. +* OBSOLETE: Macro Ordering. +* OFF_T: Typedefs. +* OUTPUT: Setup. +* PID_T: Typedefs. +* PREFIX: Command Line. +* PREPARE: Setup. +* PREREQ: Setup. +* PROGRAMS_CHECK: General Feature Tests. +* PROGRAMS_PATH: General Feature Tests. +* PROGRAM_CHECK: General Feature Tests. +* PROGRAM_EGREP: General Feature Tests. +* PROGRAM_PATH: General Feature Tests. +* PROG_AWK: Alternative Programs. +* PROG_CC: Alternative Programs. +* PROG_CPP: Alternative Programs. +* PROG_CXX: Alternative Programs. +* PROG_CXXCPP: Alternative Programs. +* PROG_INSTALL: Alternative Programs. +* PROG_LEX: Alternative Programs. +* PROG_RANLIB: Alternative Programs. +* PROG_YACC: Alternative Programs. +* PROVIDE: Macro Ordering. +* REMOTE_TAPE: System Services. +* REPLACE_FUNCS: General Feature Tests. +* REQUIRE: Macro Ordering. +* REQUIRE_CPP: Language Choice. +* RESTARTABLE_SYSCALLS: System Services. +* RETSIGTYPE: Typedefs. +* REVISION: Setup. +* RSH: Alternative Programs. +* SCO_INTL: UNIX Variants. +* SETVBUF_REVERSED: Library Functions. +* SET_MAKE: Alternative Programs. +* SIZEOF_TYPE: General Feature Tests. +* SIZE_T: Typedefs. +* STAT_MACROS_BROKEN: Structures. +* STAT_MACROS_BROKEN: Structures. +* STDC_HEADERS: Header Files. +* STRCOLL: Library Functions. +* STRUCT_TM: Structures. +* ST_BLKSIZE: Structures. +* ST_BLOCKS: Structures. +* ST_RDEV: Structures. +* SUBST: Setting Variables. +* SYS_SIGLIST_DECLARED: Header Files. +* TEST_CPP: General Feature Tests. +* TEST_PROGRAM: General Feature Tests. +* TIMEZONE: Structures. +* TIME_WITH_SYS_TIME: Structures. +* UID_T: Typedefs. +* UNISTD_H: Header Files. +* USG: Header Files. +* UTIME_NULL: Library Functions. +* VERBOSE: Printing Messages. +* VFORK: Library Functions. +* VPRINTF: Library Functions. +* WAIT3: Library Functions. +* WARN: Printing Messages. +* WITH: Command Line. +* WORDS_BIGENDIAN: Compiler Characteristics. +* XENIX_DIR: UNIX Variants. +* YYTEXT_POINTER: Alternative Programs. + + + +Tag Table: +Node: Top1070 +Node: Introduction4458 +Node: Distributing8287 +Node: Making configure Scripts9395 +Node: Writing configure.in11992 +Node: Invoking autoconf14425 +Node: Invoking autoheader16274 +Node: Specific Tests18427 +Node: Alternative Programs20099 +Node: Header Files25593 +Node: Typedefs31278 +Node: Library Functions32495 +Node: Structures37266 +Node: Compiler Characteristics39356 +Node: System Services42168 +Node: UNIX Variants44673 +Node: General Purpose Macros46581 +Node: Setup47732 +Node: General Feature Tests52686 +Node: Command Line61952 +Node: Setting Variables65766 +Node: Printing Messages69098 +Node: Language Choice71326 +Node: Macro Ordering72947 +Node: Writing Macros75693 +Node: Macro Format77189 +Node: Quoting78686 +Node: Dependencies Between Macros80144 +Node: Prerequisite Macros80731 +Node: Suggested Ordering81780 +Node: Checking for Files83159 +Node: Checking for Symbols83945 +Node: Test Programs85424 +Node: Guidelines87089 +Node: Tricks88232 +Node: Multiple Cases89235 +Node: Makefiles90439 +Node: Predefined Variables91840 +Node: Installation Prefixes93348 +Node: VPATH Substitutions94918 +Node: Automatic Remaking96639 +Node: Invoking configure98223 +Node: Overriding variables101711 +Node: Invoking config.status103334 +Node: Example106313 +Node: Sample configure.in106893 +Node: Sample Makefile.in108030 +Node: Preprocessor Symbol Index112015 +Node: Macro Index117272 + +End Tag Table diff --git a/src/util/autoconf/autoconf.sh b/src/util/autoconf/autoconf.sh new file mode 100644 index 000000000..e222c0a8c --- /dev/null +++ b/src/util/autoconf/autoconf.sh @@ -0,0 +1,120 @@ +#!/bin/sh +# autoconf -- create `configure' using m4 macros +# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +# If given no args, create `configure' from template file `configure.in'. +# With one arg, create a configure script on standard output from +# the given template file. + +usage="Usage: autoconf [-h] [--help] [-m dir] [--macrodir=dir] + [-v] [--version] [template-file]" + +# NLS nuisances. +# These must not be set unconditionally because not all systems understand +# e.g. LANG=C (notably SCO). +if test "${LC_ALL+set}" = 'set' ; then LC_ALL=C; export LC_ALL; fi +if test "${LANG+set}" = 'set' ; then LANG=C; export LANG; fi + +test -z "${AC_MACRODIR}" && AC_MACRODIR=@datadir@ +test -z "${M4}" && M4=@M4@ +case "${M4}" in +/*) # Handle the case that m4 has moved since we were configured. + # It may have been found originally in a build directory. + test -f "${M4}" || M4=m4 ;; +esac + +tmpout=/tmp/acout.$$ + +print_version= +while test $# -gt 0 ; do + case "z${1}" in + z-h | z--help | z--h* ) + echo "${usage}" 1>&2; exit 0 ;; + z--macrodir=* | z--m*=* ) + AC_MACRODIR="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" + shift ;; + z-m | z--macrodir | z--m* ) + shift + test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } + AC_MACRODIR="${1}" + shift ;; + z-v | z--version | z--v* ) + print_version="-DAC_PRINT_VERSION" + infile=/dev/null tmpout=/dev/null + shift ;; + z-- ) # Stop option processing + shift; break ;; + z- ) # Use stdin as input. + break ;; + z-* ) + echo "${usage}" 1>&2; exit 1 ;; + * ) + break ;; + esac +done + +if test -z "$print_version"; then + case $# in + 0) infile=configure.in ;; + 1) infile="$1" ;; + *) echo "$usage" >&2; exit 1 ;; + esac + + trap 'rm -f $tmpin $tmpout; exit 1' 1 2 15 + + if test z$infile = z-; then + tmpin=/tmp/acin.$$ + infile=$tmpin + cat > $infile + elif test ! -s "${infile}"; then + echo "autoconf: ${infile}: No such file or directory" >&2 + exit 1 + fi +fi + +MACROFILES="${AC_MACRODIR}/acgeneral.m4 ${AC_MACRODIR}/acspecific.m4" +test -r ${AC_MACRODIR}/aclocal.m4 \ + && MACROFILES="${MACROFILES} ${AC_MACRODIR}/aclocal.m4" +test -r aclocal.m4 && MACROFILES="${MACROFILES} aclocal.m4" +MACROFILES="${print_version} ${MACROFILES}" + +$M4 $MACROFILES $infile > $tmpout || { st=$?; rm -f $tmpin $tmpout; exit $st; } + +test -n "$print_version" && exit 0 + +# You could add your own prefixes to pattern if you wanted to check for +# them too, e.g. pattern="AC_\|ILT_", except that UNIX sed doesn't do +# alternation. +pattern="AC_" + +status=0 +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 + done | sort -u >&2 + status=1 +fi + +case $# in + 0) cat $tmpout > configure; chmod +x configure ;; + 1) cat $tmpout ;; +esac + +rm -f $tmpout +exit $status diff --git a/src/util/autoconf/autoconf.texi b/src/util/autoconf/autoconf.texi new file mode 100644 index 000000000..230218214 --- /dev/null +++ b/src/util/autoconf/autoconf.texi @@ -0,0 +1,3071 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename autoconf.info +@settitle Autoconf +@c For double-sided printing, uncomment: +@c @setchapternewpage odd +@c %**end of header + +@set EDITION 1.11 +@set VERSION 1.11 +@set UPDATED May 1994 + +@iftex +@finalout +@end iftex + +@ifinfo +@format +START-INFO-DIR-ENTRY +* autoconf: (autoconf). The Autoconf configuration system. +END-INFO-DIR-ENTRY +@end format + +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. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ifinfo + +@titlepage +@title Autoconf +@subtitle Generating Automatic Configuration Scripts +@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION} +@subtitle @value{UPDATED} +@author by David MacKenzie, Roland McGrath, and Noah Friedman + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end titlepage + +@c Define a macro index that @@defmac doesn't write to. +@defcodeindex ma + +@node Top, Introduction, , (dir) +@comment node-name, next, previous, up + +@ifinfo +This file documents the GNU Autoconf package for creating scripts to +configure source code packages using templates and an @code{m4} macro +package. This is edition @value{EDITION}, for Autoconf version @value{VERSION}. + +@end ifinfo + +@c The master menu, created with texinfo-master-menu, goes here. + +@menu +* Introduction:: Autoconf's purpose, strengths, and weaknesses. +* Distributing:: Legal restrictions on Autoconf output. +* Making configure Scripts:: How to organize and produce Autoconf scripts. +* Specific Tests:: Macros that check for particular features. +* General Purpose Macros:: Macros that check for kinds of features. +* Writing Macros:: How to add your own macros to Autoconf. +* Makefiles:: Information Autoconf uses in @file{Makefile}s. +* Invoking configure:: How to use the Autoconf output. +* Example:: Sample Autoconf input files. +* Preprocessor Symbol Index:: Index of C preprocessor symbols defined. +* Macro Index:: Index of Autoconf macros. + + --- The Detailed Node Listing --- + +Making @code{configure} Scripts + +* Writing configure.in:: What to put in an Autoconf input file. +* Invoking autoconf:: How to create configuration scripts. +* Invoking autoheader:: How to create configuration header files. + +Specific Tests + +* Alternative Programs:: Selecting between alternative programs. +* Header Files:: Header files that might be missing. +* Typedefs:: @code{typedef}s that might be missing. +* Library Functions:: C library functions that might be missing. +* Structures:: Structures or members that might be missing. +* Compiler Characteristics:: C compiler or machine architecture features. +* System Services:: Operating system services. +* UNIX Variants:: Special cases for specific UNIX variants. + +General Purpose Macros + +* Setup:: Controlling Autoconf operation. +* General Feature Tests:: Checking for kinds of features. +* Command Line:: Checking command line arguments. +* Setting Variables:: Setting shell and @code{make} variables. +* Printing Messages:: Notifying users of progress or problems. +* Language Choice:: Selecting which language to use for testing. +* Macro Ordering:: Enforcing ordering constraints. + +Writing Macros + +* Macro Format:: Basic format of an Autoconf macro. +* Quoting:: Protecting macros from unwanted expansion. +* Dependencies Between Macros:: What to do when macros depend on other macros. +* Checking for Files:: Finding whether a file exists. +* Checking for Symbols:: Finding whether a symbol is defined. +* Test Programs:: Writing programs to test for features. +* Multiple Cases:: Tests for several possible values. + +Dependencies Between Macros + +* Prerequisite Macros:: Ensuring required information. +* Suggested Ordering:: Warning about possible ordering problems. + +Test Programs + +* Guidelines:: General rules for writing test programs. +* Tricks:: Special ways to work around problems. + +Makefiles + +* Predefined Variables:: Heavily used @code{make} variables. +* Installation Prefixes:: A special variable substitution. +* VPATH Substitutions:: Compiling in a different directory. +* Automatic Remaking:: Makefile rules for configuring. + +Running @code{configure} Scripts + +* Overriding variables:: Workarounds for unusual systems. +* Invoking config.status:: Recreating a configuration. + +An Example + +* Sample configure.in:: An example of a @file{configure} template. +* Sample Makefile.in:: An example of a @file{Makefile} template. +@end menu + +@node Introduction, Distributing, Top, Top +@chapter Introduction + +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 normally require no +manual user intervention when run; they do not even take 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 operating +system features that the package can use. After the shell code to +recognize and respond to an operating 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 the configuration scripts can be regenerated +automatically to take advantage of the updated code. + +Larry Wall's Metaconfig package is similar in purpose to Autoconf, but +is more general. 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. They should avoid executing test +programs, since test programs compiled with a cross-compiler can not be +executed on the host system. Also, they shouldn't do anything that +tests features of the host system instead of the target system. + +Autoconf imposes some restrictions on the names of macros used with +@code{#ifdef} in C programs (@pxref{Preprocessor Symbol Index}). + +Autoconf requires GNU @code{m4} in order to generate the scripts. It +uses features that some UNIX versions of @code{m4} do not have. It also +overflows internal limits of some versions of @code{m4}, including GNU +@code{m4} 1.0; so use a later version of GNU @code{m4}. + +Autoconf does not work well with GNU C library releases before 1.06. +The GNU C library contains stubs (which always return an error) for +functions that are not available instead of omitting them from the +library. As a result, Autoconf scripts are fooled into thinking that +those functions are available. This problem does not exist with +releases 1.06 and later of the GNU C library, which define C +preprocessor macros that the Autoconf macros @code{AC_FUNC_CHECK} and +@code{AC_REPLACE_FUNCS} test, indicating that certain functions are +stubs (@pxref{General Feature Tests}, for more information on checking for +functions). + +@ifinfo +Autoconf was written by David MacKenzie, with help from Franc,ois +@end ifinfo +@tex +Autoconf was written by David MacKenzie, with help from Fran\c cois +@end tex +Pinard, Karl Berry, Richard Pixley, Ian Lance Taylor, Roland McGrath, +Noah Friedman, and david d zuhn. It was inspired by Brian Fox's +automatic configuration system for Bash, by Larry Wall's Metaconfig, and +by Richard Stallman, Richard Pixley, and John Gilmore's configuration +tools for the GNU compiler and object file utilities. + +Mail suggestions and bug reports for Autoconf to +@code{bug-gnu-utils@@prep.ai.mit.edu}. Please include the Autoconf version +number, which you can get by running @samp{autoconf --version}. + +@node Distributing, Making configure Scripts, Introduction, Top +@chapter Distributing Autoconf Output + +The configuration scripts that Autoconf produces are covered by the GNU +General Public License. This is because they consist almost entirely of +parts of Autoconf itself, rearranged somewhat, and Autoconf is +distributed under the terms of the GPL. As applied to Autoconf, the GPL +just means that you need to distribute @file{configure.in}, and +@file{aclocal.m4}, @file{acconfig.h}, and @file{@var{config}.h.top} and +@file{@var{config}.h.bot} if you use them, along with @file{configure}. + +Programs that use Autoconf scripts to configure themselves do not +automatically come under the GPL. Distributing an Autoconf +configuration script as part of a program is considered to be @emph{mere +aggregation} of that work with the Autoconf script. Such programs are +not derivative works based on Autoconf; only their configuration scripts +are. 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. + +@node Making configure Scripts, Specific Tests, Distributing, Top +@chapter Making @code{configure} Scripts + +The configuration scripts that Autoconf produces are by convention +called @code{configure}. When run, @code{configure} creates several +files, replacing configuration parameters in them with values +appropriate for the system being configured. The files that +@code{configure} creates are: + +@itemize @bullet +@item +one or more @file{Makefile} files (one in each subdirectory of the +package), from template @file{Makefile.in} files (@pxref{Makefiles}); + +@item +optionally, a C header file, the name of which is configurable, +containing @code{#define} statements (@pxref{Setup}); + +@item +a shell script called @file{config.status} that, when run, will recreate +the files listed above (@pxref{Invoking config.status}). +@end itemize + +To create a @code{configure} script with Autoconf, you need to write an +Autoconf input file (@file{configure.in}) and run Autoconf on it to +produce the script. If you write your own feature tests to supplement +those that come with Autoconf, you might also write a file called +@file{aclocal.m4}. If you use a C header file to contain @code{#define} +directives, you might also write @file{config.h.top}, +@file{config.h.bot}, and @file{acconfig.h}, and you will distribute the +Autoconf-generated file @file{config.h.in} with the package. + +Here is a diagram showing how the files that can be used in +configuration are produced. Programs that are executed are suffixed by +@samp{*}. Optional files are enclosed in square brackets (@samp{[]}). +@code{autoconf} and @code{autoheader} also read the installed files +@file{acgeneral.m4} and @file{acspecific.m4}, and also an installed +@file{aclocal.m4} if it exists. + +@noindent +Files used in preparing a software package for distribution: +@example +@group +configure.in --. .------> autoconf* -----> configure + +---+ +[aclocal.m4] --' `---. + +--> [autoheader*] -> [config.h.in] +[acconfig.h] ----. | + +-----' +[config.h.top] --+ +[config.h.bot] --' + +Makefile.in -------------------------------> Makefile.in +@end group +@end example + +@noindent +Files used in configuring a software package: +@example +@group +configure* ------------. + | +[config.h.in] -. v .-> [config.h] -. + +--> config.status* -+ +--> make* +Makefile.in ---' `-> Makefile ---' +@end group +@end example + +@menu +* Writing configure.in:: What to put in an Autoconf input file. +* Invoking autoconf:: How to create configuration scripts. +* Invoking autoheader:: How to create configuration header files. +@end menu + +@node Writing configure.in, Invoking autoconf, , Making configure Scripts +@section Writing @file{configure.in} + +To produce a @code{configure} script for a software package, create a +file called @file{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 +@ref{Specific Tests}, for their descriptions. For most other +features, you can use Autoconf template macros to produce custom checks; +see @ref{General Feature Tests}, for information about them. For especially +tricky or specialized features, @file{configure.in} might need to +contain some hand-crafted shell commands. @xref{Writing Macros}, for +guidelines on writing tests from scratch. + +Every @file{configure.in} must begin with a call to @code{AC_INIT} and +end with a call to @code{AC_OUTPUT} (@pxref{Setup}). Other than that, +the order in which @file{configure.in} calls the Autoconf macros is +generally not important, except that some macros rely on other macros +having been called first, because they check previously set values of +some variables to decide what to do. These macros are noted in the +individual descriptions (@pxref{Specific Tests}). + +To encourage consistency, here is a suggested order for calling the +Autoconf macros. A few macros need to be called in a different order +from the one given here; they are noted in their individual descriptions +(@pxref{Specific Tests}). Note that there must not be any space +between the macro name and the open parentheses. + +@display +@group +@code{AC_INIT(@var{file})} +checks for alternative programs +checks for UNIX variants that set C preprocessor variables +checks for header files +checks for typedefs +checks for library functions +checks for structures +checks for compiler characteristics +checks for system services +other checks for UNIX variants +@code{AC_OUTPUT(@r{[}@var{file@dots{}}@r{]})} +@end group +@end display + +You can include comments in @file{configure.in} files by starting them +with the @code{m4} predefined macro @code{dnl}, which discards text up +through the next newline. These comments do not appear in the generated +@code{configure} scripts. For example, it is helpful to begin +@file{configure.in} files with a line like this: + +@example +dnl Process this file with autoconf to produce a configure script. +@end example + +@xref{Sample configure.in}, for an example of a real @file{configure.in} +script. + +@node Invoking autoconf, Invoking autoheader, Writing configure.in, Making configure Scripts +@section Invoking @code{autoconf} + +To create @code{configure} from @file{configure.in}, run the +@code{autoconf} program with no arguments. @code{autoconf} processes +@file{configure.in} with the @code{m4} macro processor, using the +Autoconf macros. If you give @code{autoconf} an argument, it reads that +file instead of @file{configure.in} and writes the configuration script +to the standard output instead of to @file{configure}. If you give +@code{autoconf} the argument @samp{-}, it reads the standard input +instead of @file{configure.in} and writes the configuration script on +the standard output. + +The Autoconf macros are defined in two or more files. Two of the files +are distributed with Autoconf: @code{autoconf} first reads +@file{acgeneral.m4} (@pxref{General Purpose Macros}), then +@file{acspecific.m4} (@pxref{Specific Tests}). After reading them, +@code{autoconf} looks for an optional file called @file{aclocal.m4}, +first in the directory that contains other installed Autoconf macro +files, and then in the current directory. If both files exist, it uses +both of them. Those files can contain your site's own locally written +Autoconf macro definitions (@pxref{Writing Macros}, for more +information). If a macro is defined in more than one of the files that +@code{autoconf} reads, the last definition it reads overrides the +earlier ones. + +You can override the directory where @code{autoconf} looks for the +installed macro files by setting the @code{AC_MACRODIR} environment +variable to a different directory. You can also give @code{autoconf} +the @samp{--macrodir} option, which overrides @code{AC_MACRODIR}. + +@code{autoconf} also accepts the options @code{--version}, which prints +the Autoconf version number and exits, and @code{--help}, which prints a +summary of the command-line options and exits. + +@node Invoking autoheader, , Invoking autoconf, Making configure Scripts +@section Invoking @code{autoheader} + +You can use the @code{autoheader} program to create a template file of C +@samp{#define} statements for @code{configure} to use. By default, the +file that @code{autoheader} creates is called @file{config.h.in}; if +@file{configure.in} invokes @code{AC_CONFIG_HEADER(@var{file})}, +@code{autoheader} creates @file{@var{file}.in}. + +@code{autoheader} scans @file{configure.in} and figures out which C +preprocessor symbols it might define. It copies comments and +@code{#define} and @code{#undef} statements from a file called +@file{acconfig.h}, which comes with and is installed with Autoconf. It +also uses a file called @file{acconfig.h} in the current directory, if +present; you must create that file to contain entries for any additional +symbols that you @code{AC_DEFINE}. For symbols defined by +@code{AC_HAVE_HEADERS}, @code{AC_HAVE_FUNCS}, @code{AC_SIZEOF_TYPE}, +or @code{AC_HAVE_LIBRARY}, +@code{autoheader} generates comments and @code{#undef} statements itself +rather than copying them from a file, since the possible symbols are +effectively limitless. + +The file that @code{autoheader} creates usually contains only +@code{#define} and @code{#undef} statements and their accompanying +comments. However, if a file called @file{@var{file}.top} (typically +@file{config.h.top}) exists in the current directory, @code{autoheader} +copies that file to the beginning of its output. + +If you give @code{autoheader} an argument, it uses that file instead of +@file{configure.in} and writes the header file to the standard output +instead of to @file{config.h.in}. If you give @code{autoheader} an +argument of @samp{-}, it reads the standard input instead of +@file{configure.in} and writes the header file to the standard output. + +You can override the directory where @code{autoheader} looks for the +installed macro and @file{acconfig.h} files by setting the +@code{AC_MACRODIR} environment variable to a different directory. You +can also give @code{autoheader} the @samp{--macrodir} option, which +overrides @code{AC_MACRODIR}. + +@code{autoheader} also accepts the options @code{--version}, which prints +the Autoconf version number and exits, and @code{--help}, which prints a +summary of the command-line options and exits. + +@node Specific Tests, General Purpose Macros, Making configure Scripts, Top +@chapter Specific Tests + +These macros test for particular operating system features that packages +might need or want to use. If you need to test for a feature that none +of these macros check for, you can probably do it by calling one of the +general purpose test macros with appropriate arguments (@pxref{General +Feature Tests}). + +All of these macros that set @code{make} variables call @code{AC_SUBST} +on those variables (@pxref{Setting Variables}, for details about +@code{AC_SUBST}). The phrase ``define @var{name}'' is used below as a +shorthand to mean either add @samp{-D@var{name}=1} to the @code{make} +variable @code{DEFS}, or put @samp{#define @var{name} 1} in the +configuration header file, depending on whether @code{AC_CONFIG_HEADER} has +been called. @xref{Setting Variables}, for more information. + +Within each section below, the macros are listed in alphabetical order. +The macros are generally named for the @code{make} variables or C +preprocessor macros that they define; those names are based largely on +what existing GNU programs use. These macros are defined in the file +@file{acspecific.m4}. + +@menu +* Alternative Programs:: Selecting between alternative programs. +* Header Files:: Header files that might be missing. +* Typedefs:: @code{typedef}s that might be missing. +* Library Functions:: C library functions that might be missing. +* Structures:: Structures or members that might be missing. +* Compiler Characteristics:: C compiler or machine architecture features. +* System Services:: Operating system services. +* UNIX Variants:: Special cases for specific UNIX variants. +@end menu + +@node Alternative Programs, Header Files, , Specific Tests +@section Alternative Programs + +The following macros check for the presence or behavior of particular +programs: + +@defmac AC_GCC_TRADITIONAL +@maindex GCC_TRADITIONAL +Add @samp{-traditional} to @code{make} variable @code{CC} if using the +GNU C compiler and @code{ioctl} does not work properly without +@samp{-traditional}. This macro calls @code{AC_PROG_CC} and +@code{AC_PROG_CPP} if they haven't been called already. +@end defmac + +@defmac AC_LN_S +@maindex LN_S +If @samp{ln -s} works on the current filesystem (the O.S. and filesystem +support symbolic links), set shell and @code{make} variable @code{LN_S} +to @samp{ln -s}, otherwise set it to @samp{ln}. +@end defmac + +@defmac AC_MINUS_C_MINUS_O +@maindex MINUS_C_MINUS_O +@vindex NO_MINUS_C_MINUS_O +If the C compiler does not accept the @samp{-c} and @samp{-o} options +simultaneously, define @code{NO_MINUS_C_MINUS_O}. +@end defmac + +@defmac AC_PROG_AWK +@maindex PROG_AWK +Check for @code{mawk}, @code{gawk}, @code{nawk}, and @code{awk}, in that +order, and set @code{make} variable @code{AWK} to the first one that it +finds. +@end defmac + +@defmac AC_PROG_CC +@maindex PROG_CC +If @code{gcc} is found, set @code{make} variable @code{CC} to @samp{gcc}, +and set shell variable @code{GCC} to 1 for use by macros such as +@code{AC_GCC_TRADITIONAL}. +@end defmac + +@defmac AC_PROG_CPP +@maindex PROG_CPP +Set shell and @code{make} variable @code{CPP} to a command that runs the +C preprocessor. If @samp{$CC -E} doesn't work, it uses @file{/lib/cpp}. +It is only portable to run @code{CPP} on files with a @file{.c} +extension. + +If the current language is C (@pxref{Language Choice}), many of the +specific test macros use the value of @code{CPP} indirectly by calling +@code{AC_TEST_CPP}, @code{AC_HEADER_CHECK}, @code{AC_HEADER_EGREP}, or +@code{AC_PROGRAM_EGREP}. Those macros call this macro first if it +hasn't been called already. It calls @code{AC_PROG_CC} if it hasn't +been called already. +@end defmac + +@defmac AC_PROG_CXX +@maindex PROG_CXX +Determine a C++ compiler to use. Check if the environment variable +@var{CXX} or @var{CCC} (in that order) is set; if so, set @code{make} +variable @code{CXX} to its value. Otherwise search for a C++ compiler +under likely names (@code{c++}, @code{g++}, @code{gcc}, and @code{CC}). +If none of those checks succeed, as a last resort set @code{CXX} to +@code{gcc}. +@end defmac + +@defmac AC_PROG_CXXCPP +@maindex PROG_CXXCPP +Set shell and @code{make} variable @code{CXXCPP} to a command that runs the +C++ preprocessor. If @samp{$CXX -E} doesn't work, it uses @file{/lib/cpp}. +It is only portable to run @code{CXXCPP} on files with a @file{.C} or +@file{.cc} extension. + +If the current language is C++ (@pxref{Language Choice}), many of the +specific test macros use the value of @code{CXXCPP} indirectly by +calling @code{AC_TEST_CPP}, @code{AC_HEADER_CHECK}, +@code{AC_HEADER_EGREP}, or @code{AC_PROGRAM_EGREP}. Those macros call +this macro first if it hasn't been called already. This macro calls +@code{AC_PROG_CXX} if it hasn't been called already. +@end defmac + +@defmac AC_PROG_INSTALL +@maindex PROG_INSTALL +Set @code{make} variable @code{INSTALL} to @samp{install -c} if +@code{install} is found and is compatible with the BSD and GNU versions. +Otherwise, set @code{INSTALL} to @samp{@var{dir}/install.sh -c}, where +it checks for @file{install.sh} in the directories @file{$srcdir}, +@file{$srcdir/..}, and @file{$srcdir/../..} to determine @var{dir}. + +This macro screens out the false matches @file{/etc/install}, +@file{/usr/sbin/install}, and other instances of @code{install} known +not to work. It also sets the variable @code{INSTALL_PROGRAM} to +@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m +644}. + +If you need to use your own @file{install.sh} because it has features +not found in standard @code{install} programs, there is no reason to use +@code{AC_PROG_INSTALL}; just put the pathname of your script into your +@file{Makefile.in} files. +@end defmac + +@defmac AC_PROG_LEX +@maindex PROG_LEX +If @code{flex} is found, set @code{make} variable @code{LEX} to +@samp{flex} and @code{LEXLIB} to @samp{-lfl}, if that library is in a +standard place. Otherwise set @code{LEX} to @samp{lex} and +@code{LEXLIB} to @samp{-ll}. +@end defmac + +@defmac AC_PROG_RANLIB +@maindex PROG_RANLIB +Set @code{make} variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} +is found, otherwise to @samp{:} (do nothing). +@end defmac + +@defmac AC_PROG_YACC +@maindex PROG_YACC +If @code{bison} is found, set @code{make} variable @code{YACC} to +@samp{bison -y}. Otherwise, if @code{byacc} is found, set @code{YACC} +to @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}. +@end defmac + +@defmac AC_RSH +@maindex RSH +@vindex NO_REMOTE +@vindex HAVE_NETDB_H +If a remote shell is available, put @samp{rtapelib.o} in @code{make} +variable @code{RTAPELIB}. Otherwise, also do so if @file{netdb.h} +exists (implying the @code{rexec} function), and in addition define +@code{HAVE_NETDB_H}. If neither a remote shell nor @code{rexec} is +available, define @code{NO_REMOTE}. +@end defmac + +@defmac AC_SET_MAKE +@maindex SET_MAKE +If @code{make} predefines the variable @code{MAKE}, define @code{make} +variable @code{SET_MAKE} to be empty. Otherwise, define @code{SET_MAKE} +to contain @samp{MAKE=make}. Calls @code{AC_SUBST} for @code{SET_MAKE}. + +In recent versions of @code{make}, the variable @code{MAKE} contains the +name of the @code{make} program plus options it was given. It is used +when running @code{make} recursively in subdirectories. But some old +versions of @code{make} don't set the @code{MAKE} variable. +This macro allows use of @code{MAKE} on all systems. + +If you use this macro, simply place a line like this in your +@file{Makefile.in} file(s): + +@example +@@SET_MAKE@@ +@end example +@end defmac + +@defmac AC_YYTEXT_POINTER +@maindex YYTEXT_POINTER +@vindex YYTEXT_POINTER +Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead +of a @samp{char []}. This depends on whether @code{lex} or @code{flex} +is being used. This macro calls @code{AC_PROG_CPP} (or +@code{AC_PROG_CXXCPP} if C++ is the current language, @pxref{Language +Choice}) and @code{AC_PROG_LEX} if they haven't been called already. + +This macro replaces @code{AC_DECLARE_YYTEXT}, which didn't work. +@end defmac + +@node Header Files, Typedefs, Alternative Programs, Specific Tests +@section Header Files + +The following macros check for the presence of certain C header files: + +@defmac AC_DIR_HEADER +@maindex DIR_HEADER +@vindex DIRENT +@vindex SYSDIR +@vindex SYSNDIR +@vindex NDIR +@vindex VOID_CLOSEDIR +If the system has @file{dirent.h}, define @code{DIRENT}; otherwise, if +it has @file{sys/ndir.h}, define @code{SYSNDIR}; otherwise, if it has +@file{sys/dir.h}, define @code{SYSDIR}; otherwise, if it has +@file{ndir.h}, define @code{NDIR}. Also, if the directory library +header file contains a declaration of the @code{closedir} function with +a @code{void} return type, define @code{VOID_CLOSEDIR}. + +The directory library declarations in the source code should look +something like the following, which assumes that you have also called +@samp{AC_HAVE_HEADERS(unistd.h)}: + +@example +@group +#ifdef HAVE_UNISTD_H +#include +#include +#endif + +/* unistd.h defines _POSIX_VERSION on POSIX.1 systems. */ +#if defined(DIRENT) || defined(_POSIX_VERSION) +#include +#define NLENGTH(dirent) (strlen((dirent)->d_name)) +#else /* not (DIRENT or _POSIX_VERSION) */ +#define dirent direct +#define NLENGTH(dirent) ((dirent)->d_namlen) +#ifdef SYSNDIR +#include +#endif /* SYSNDIR */ +#ifdef SYSDIR +#include +#endif /* SYSDIR */ +#ifdef NDIR +#include +#endif /* NDIR */ +#endif /* not (DIRENT or _POSIX_VERSION) */ +@end group +@end example + +Using the above declarations, the program would declare variables to be +type @code{struct dirent}, not @code{struct direct}, and would access +the length of a directory entry name by passing a pointer to a +@code{struct dirent} to the @code{NLENGTH} macro. +@end defmac + +@defmac AC_MAJOR_HEADER +@maindex MAJOR_HEADER +@vindex MAJOR_IN_MKDEV +@vindex MAJOR_IN_SYSMACROS +If @file{sys/types.h} does not define @code{major}, @code{minor}, and +@code{makedev}, but @file{sys/mkdev.h} does, define +@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define +@code{MAJOR_IN_SYSMACROS}. +@end defmac + +@defmac AC_MEMORY_H +@maindex MEMORY_H +@vindex NEED_MEMORY_H +Define @code{NEED_MEMORY_H} if @code{memcpy}, @code{memcmp}, etc. are +not declared in @file{string.h} and @file{memory.h} exists. This macro +is obsolete; instead, use @code{AC_HAVE_HEADERS(memory.h)}. See the +example for @code{AC_STDC_HEADERS}. +@end defmac + +@defmac AC_STDC_HEADERS +@maindex STDC_HEADERS +@vindex STDC_HEADERS +Define @code{STDC_HEADERS} if the system has ANSI C header files. +Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h}, +@file{string.h}, and @file{float.h}; if the system has those, it +probably has the rest of the ANSI C header files. This macro also +checks whether @file{string.h} declares @code{memchr} (and thus +presumably the other @code{mem} functions), whether @file{stdlib.h} +declare @code{free} (and thus presumably @code{malloc} and other related +functions), and whether the @file{ctype.h} macros work on characters +with the high bit set, as ANSI C requires. + +Use @code{STDC_HEADERS} instead of @code{__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. + +To check whether to use the System V/ANSI C string functions and header +file, you can put the following in @file{configure.in}: + +@example +AC_STDC_HEADERS +AC_HAVE_HEADERS(string.h memory.h) +@end example + +@noindent +Then, in the code, use a test like this: + +@example +@group +#if STDC_HEADERS || HAVE_STRING_H +#include +/* An ANSI string.h and pre-ANSI memory.h might conflict. */ +#if !STDC_HEADERS && HAVE_MEMORY_H +#include +#endif /* not STDC_HEADERS and HAVE_MEMORY_H */ +#define index strchr +#define rindex strrchr +#define bcopy(s, d, n) memcpy ((d), (s), (n)) +#define bcmp(s1, s2, n) memcmp ((s1), (s2), (n)) +#define bzero(s, n) memset ((s), 0, (n)) +#else /* not STDC_HEADERS and not HAVE_STRING_H */ +#include +/* memory.h and strings.h conflict on some systems. */ +#endif /* not STDC_HEADERS and not HAVE_STRING_H */ +@end group +@end example + +@noindent +This example asssumes that your code uses the BSD style functions. If +you use the System V/ANSI C style functions, you will need to replace +the macro definitions with ones that go in the other direction. + +This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending +on which language is current, @pxref{Language Choice}), if it hasn't +been called already. +@end defmac + +@defmac AC_UNISTD_H +@maindex UNISTD_H +@vindex HAVE_UNISTD_H +Define @code{HAVE_UNISTD_H} if the system has @file{unistd.h}. This +macro is obsolete; instead, use @samp{AC_HAVE_HEADERS(unistd.h)}. + +The way to check if the system supports POSIX.1 is: + +@example +@group +#if HAVE_UNISTD_H +#include +#include +#endif + +#ifdef _POSIX_VERSION +/* Code for POSIX.1 systems. */ +#endif +@end group +@end example + +@vindex _POSIX_VERSION +@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on +POSIX.1 systems. If there is no @file{unistd.h}, it is definitely not a +POSIX.1 system. However, some non-POSIX.1 systems do have @file{unistd.h}. +@end defmac + +@defmac AC_USG +@maindex USG +@vindex USG +Define @code{USG} if the system does not have @file{strings.h}, +@code{rindex}, @code{bzero}, etc. This implies that it has +@file{string.h}, @code{strrchr}, @code{memset}, etc. + +The symbol @code{USG} is obsolete. Instead of this macro, use +@code{AC_HAVE_HEADERS(string.h)} and use @code{HAVE_STRING_H} in your +code. See the example for @code{AC_STDC_HEADERS}. +@end defmac + +@defmac AC_SYS_SIGLIST_DECLARED +@maindex SYS_SIGLIST_DECLARED +@vindex SYS_SIGLIST_DECLARED +Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist} is +declared in a system header file, either @file{signal.h} or +@file{unistd.h}. +@end defmac + +@node Typedefs, Library Functions, Header Files, Specific Tests +@section Typedefs + +The following macros check for predefined C types: + +@defmac AC_GETGROUPS_T +@maindex GETGROUPS_T +@vindex GETGROUPS_T +Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int} +is the base type of the array argument to @code{getgroups}. +@end defmac + +@defmac AC_MODE_T +@maindex MODE_T +@vindex mode_t +If @code{mode_t} is not defined in @file{sys/types.h}, define +@code{mode_t} to be @code{int}. +@end defmac + +@defmac AC_OFF_T +@maindex OFF_T +@vindex off_t +If @code{off_t} is not defined in @file{sys/types.h}, define +@code{off_t} to be @code{long}. +@end defmac + +@defmac AC_PID_T +@maindex PID_T +@vindex pid_t +If @code{pid_t} is not defined in @file{sys/types.h}, define +@code{pid_t} to be @code{int}. +@end defmac + +@defmac AC_RETSIGTYPE +@maindex RETSIGTYPE +@vindex RETSIGTYPE +If @file{signal.h} declares @code{signal} as returning a pointer to a +function returning @code{void}, define @code{RETSIGTYPE} to be +@code{void}; otherwise, define it to be @code{int}. + +Define signal handlers as returning type @code{RETSIGTYPE}: + +@example +@group +RETSIGTYPE +hup_handler () +@{ +@dots{} +@} +@end group +@end example +@end defmac + +@defmac AC_SIZE_T +@maindex SIZE_T +@vindex size_t +If @code{size_t} is not defined in @file{sys/types.h}, define +@code{size_t} to be @code{unsigned}. +@end defmac + +@defmac AC_UID_T +@maindex UID_T +@vindex uid_t +@vindex gid_t +If @code{uid_t} is not defined in @file{sys/types.h}, define +@code{uid_t} to be @code{int} and @code{gid_t} to be @code{int}. +@end defmac + +@node Library Functions, Structures, Typedefs, Specific Tests +@section Library Functions + +The following macros check for particular C library functions: + +@defmac AC_ALLOCA +@maindex ALLOCA +@vindex C_ALLOCA +@vindex HAVE_ALLOCA_H +Check how to get @code{alloca}. Tries to get a builtin version by +checking for @file{alloca.h} or the predefined C preprocessor macros +@code{__GNUC__} and @code{_AIX}. If that fails, it looks for a function +in the standard C library. If that fails, it sets the @code{make} +variable @code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} +(so programs can periodically call @samp{alloca(0)} to garbage collect). +This variable is separate from @code{LIBOBJS} so multiple programs can +share the value of @code{ALLOCA} without needing to create an actual +library, in case only some of them use the code in @code{LIBOBJS}. + +If this macro finds @file{alloca.h}, it defines @code{HAVE_ALLOCA_H}. + +This macro does not try to get @code{alloca} from the SVR3 @file{libPW} +or the SVR4 @file{libucb} because those libraries contain some +incompatible functions that cause trouble. Some versions do not even +contain @code{alloca} or contain a buggy version. If you still want to +use their @code{alloca}, use @code{ar} to extract @file{alloca.o} from +them instead of compiling @file{alloca.c}. + +Source files that use @code{alloca} should start with a piece of code +like the following, to declare it properly. Note that in some versions +of AIX, the declaration of @code{alloca} must precede everything else +except for comments and preprocessor directives. The @code{#pragma} +directive is indented so that pre-ANSI C compilers will ignore it, +rather than choke on it. + +@example +@group +/* AIX requires this to be the first thing in the file. */ +#ifdef __GNUC__ +#define alloca __builtin_alloca +#else /* not __GNUC__ */ +#if HAVE_ALLOCA_H +#include +#else /* not HAVE_ALLOCA_H */ +#ifdef _AIX + #pragma alloca +#else /* not _AIX */ +char *alloca (); +#endif /* not _AIX */ +#endif /* not HAVE_ALLOCA_H */ +#endif /* not __GNUC__ */ +@end group +@end example +@end defmac + +@defmac AC_GETLOADAVG +@maindex GETLOADAVG +@vindex SVR4 +@vindex DGUX +@vindex UMAX +@vindex UMAX4_3 +@vindex NLIST_STRUCT +@vindex NLIST_NAME_UNION +@vindex GETLODAVG_PRIVILEGED +@vindex NEED_SETGID +Check how to get the system load averages. If the system has the +@code{getloadavg} function, this macro defines @code{HAVE_GETLOADAVG}, +and adds to @code{LIBS} any libraries needed to get that function. + +Otherwise, it adds @samp{getloadavg.o} to the @code{make} variable +@code{LIBOBJS}, and possibly defines several other C preprocessor +macros and @code{make} variables: + +@enumerate +@item +It defines @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if +on those systems. + +@item +If it finds @file{nlist.h}, it defines @code{NLIST_STRUCT}. + +@item +If @samp{struct nlist} has an @samp{n_un} member, it defines +@code{NLIST_NAME_UNION}. + +@item +If compiling @file{getloadavg.c} defines @code{LDAV_PRIVILEGED}, +programs need to be installed specially on this system for +@code{getloadavg} to work, and this macro defines +@code{GETLOADAVG_PRIVILEGED}. + +@item +This macro always defines @code{NEED_SETGID}, for @code{make}. The +value is @samp{true} if special installation is required, @samp{false} +if not. If @code{NEED_SETGID} is @samp{true}, it sets @code{KMEM_GROUP} +to the name of the group that should own the installed program. +@end enumerate +@end defmac + +@defmac AC_MMAP +@maindex MMAP +@vindex HAVE_MMAP +If the @code{mmap} function exists and works correctly, define +@code{HAVE_MMAP}. +@end defmac + +@defmac AC_SETVBUF_REVERSED +@maindex SETVBUF_REVERSED +@vindex SETVBUF_REVERSED +If @code{setvbuf} takes the buffering type as its second argument and +the buffer pointer as the third, instead of the other way around, define +@code{SETVBUF_REVERSED}. This is the case on System V before release 3. +@end defmac + +@defmac AC_STRCOLL +@maindex STRCOLL +@vindex HAVE_STRCOLL +If the @code{strcoll} function exists and works correctly, define +@code{HAVE_STRCOLL}. This does a bit more than +@samp{AC_HAVE_FUNCS(strcoll)}, because some systems have incorrect +definitions of @code{strcoll}, which should not be used. +@end defmac + +@defmac AC_UTIME_NULL +@maindex UTIME_NULL +@vindex HAVE_UTIME_NULL +If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to +the present, define @code{HAVE_UTIME_NULL}. +@end defmac + +@defmac AC_VFORK +@maindex VFORK +@vindex HAVE_VFORK_H +@vindex vfork +If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working +@code{vfork} is not found, define @code{vfork} to be @code{fork}. This +macro checks for several known errors in implementations of @code{vfork} +and considers the system to not have a working @code{vfork} if it +detects any of them. +@end defmac + +@defmac AC_VPRINTF +@maindex VPRINTF +@vindex HAVE_VPRINTF +@vindex HAVE_DOPRNT +If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if +@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf} +is available, you may assume that @code{vfprintf} and @code{vsprintf} +are also available.) +@end defmac + +@defmac AC_WAIT3 +@maindex WAIT3 +@vindex HAVE_WAIT3 +If @code{wait3} is found and fills in the contents of its third argument +(a @samp{struct rusage *}), which HP-UX does not do, define +@code{HAVE_WAIT3}. +@end defmac + +@node Structures, Compiler Characteristics, Library Functions, Specific Tests +@section Structures + +The following macros check for certain structures or structure members: + +@defmac AC_STAT_MACROS_BROKEN +@maindex STAT_MACROS_BROKEN +@maindex STAT_MACROS_BROKEN +If the macros @code{S_ISDIR}, @code{S_ISREG} et al. defined in +@file{sys/stat.h} do not work properly (returning false positives), +define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV, +Amdahl UTS and Motorola System V/88. +@end defmac + +@defmac AC_ST_BLKSIZE +@maindex ST_BLKSIZE +@vindex HAVE_ST_BLKSIZE +If @code{struct stat} contains an @code{st_blksize} member, define +@code{HAVE_ST_BLKSIZE}. +@end defmac + +@defmac AC_ST_BLOCKS +@maindex ST_BLOCKS +@vindex HAVE_ST_BLOCKS +If @code{struct stat} contains an @code{st_blocks} member, define +@code{HAVE_ST_BLOCKS}. Otherwise, add @samp{fileblocks.o} to the +@code{make} variable @code{LIBOBJS}. +@end defmac + +@defmac AC_ST_RDEV +@maindex ST_RDEV +@vindex HAVE_ST_RDEV +If @code{struct stat} contains an @code{st_rdev} member, define +@code{HAVE_ST_RDEV}. +@end defmac + +@defmac AC_TIME_WITH_SYS_TIME +@maindex TIME_WITH_SYS_TIME +@vindex TIME_WITH_SYS_TIME +If a program may include both @file{time.h} and @file{sys/time.h}, +define @code{TIME_WITH_SYS_TIME}. On some older systems, +@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not +protected against multiple inclusion, so programs should not explicitly +include both files. This macro is useful in programs that use, for +example, @code{struct timeval} or @code{struct timezone} as well as +@code{struct tm}. It is best used in conjunction with +@code{HAVE_SYS_TIME_H}. + +@example +#ifdef TIME_WITH_SYS_TIME +#include +#include +#else +#ifdef HAVE_SYS_TIME_H +#include +#else +#include +#endif +#endif +@end example +@end defmac + +@defmac AC_STRUCT_TM +@maindex STRUCT_TM +@vindex TM_IN_SYS_TIME +If @file{time.h} does not define @code{struct tm}, define +@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h} +defines @code{struct tm}. +@end defmac + +@defmac AC_TIMEZONE +@maindex TIMEZONE +@vindex HAVE_TM_ZONE +@vindex HAVE_TZNAME +Figure out how to get the current timezone. If @code{struct tm} has a +@code{tm_zone} member, define @code{HAVE_TM_ZONE}. Otherwise, if the +external array @code{tzname} is found, define @code{HAVE_TZNAME}. This +macro calls @code{AC_STRUCT_TM} if it hasn't been called already. +@end defmac + +@node Compiler Characteristics, System Services, Structures, Specific Tests +@section Compiler Characteristics + +The following macros check for C compiler or machine architecture +features: + +@defmac AC_ARG_ARRAY +@maindex ARG_ARRAY +@vindex NO_ARG_ARRAY +If the address of an argument to a C function can not be used like +the start of an array, define @code{NO_ARG_ARRAY}. This ability allows +a sequence of arguments with the same type to be accessed as if they +were an array of values. +@end defmac + +@defmac AC_CROSS_CHECK +@maindex CROSS_CHECK +If the C compiler being used does not produce executables that can run +on the system where @code{configure} is being run, set the shell +variable @code{cross_compiling} to 1. This information can be used by +@code{AC_TEST_PROGRAM} to determine whether to take a default action +instead of trying to run a test program (@pxref{General Feature Tests}). +@end defmac + +@defmac AC_CHAR_UNSIGNED +@maindex CHAR_UNSIGNED +@vindex __CHAR_UNSIGNED__ +If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__}, +unless the C compiler predefines it. +@end defmac + +@defmac AC_CONST +@maindex CONST +@vindex const +If the C compiler does not fully support the keyword @code{const}, +define @code{const} to be empty. Some C compilers that do not define +@code{__STDC__} do support @code{const}; some compilers that define +@code{__STDC__} do not completely support @code{const}. Programs can +simply use @code{const} as if every C compiler supported it; for those +that don't, the @file{Makefile} or configuration header file will define +it as empty. (If using a configuration header file, the program should +include it before any other header files, to prevent inconsistencies in +declarations.) +@end defmac + +@defmac AC_INLINE +@maindex INLINE +@vindex inline +If the C compiler is a version of GCC that supports the keyword +@code{__inline} but not @code{inline} (such as some NeXT versions), +define @code{inline} to be @code{__inline}. This macro calls +@code{AC_PROG_CC} if it hasn't been called already. +@end defmac + +@defmac AC_INT_16_BITS +@maindex INT_16_BITS +@vindex INT_16_BITS +If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}. +This macro is obsolete; it is more general to use +@samp{AC_SIZEOF_TYPE(int)} instead (@pxref{General Feature Tests}). +@end defmac + +@defmac AC_LONG_64_BITS +@maindex LONG_64_BITS +@vindex LONG_64_BITS +If the C type @code{long int} is 64 bits wide, define +@code{LONG_64_BITS}. This macro is obsolete; it is more general to use +@samp{AC_SIZEOF_TYPE(long)} instead (@pxref{General Feature Tests}). +@end defmac + +@defmac AC_LONG_DOUBLE +@maindex HAVE_LONG_DOUBLE +@vindex HAVE_LONG_DOUBLE +If the C compiler supports the @code{long double} type, define +@code{HAVE_LONG_DOUBLE}. Some C compilers that do not define +@code{__STDC__} do support the @code{long double} type; some compilers +that define @code{__STDC__} do not support @code{long double}. +@end defmac + +@defmac AC_WORDS_BIGENDIAN +@maindex WORDS_BIGENDIAN +@vindex WORDS_BIGENDIAN +If words are stored with the most significant byte first (like Motorola +and SPARC, but not Intel and VAX, CPUs), define @code{WORDS_BIGENDIAN}. +@end defmac + +@node System Services, UNIX Variants, Compiler Characteristics, Specific Tests +@section System Services + +The following macros check for operating system services: + +@defmac AC_FIND_X +@maindex FIND_X +Try to locate the X Window System include files and libraries. Try +first by running @code{xmkmf} on a trivial @file{Imakefile} and +examining the @file{Makefile} that it produces. If that fails (such as +if @code{xmkmf} is not present), look for them in several directories +where they often reside. If either method is successful, set the shell +variables @code{x_includes} and @code{x_libraries} to their locations, +unless they are in directories the compiler searches by default. + +If both methods fail, or the user gave the command line option +@samp{--without-x}, set the shell variable @code{no_x} to @samp{true}; +otherwise set it to the empty string. + +The command line options @samp{--x-includes=@var{dir}} and +@samp{--x-libraries=@var{dir}} override the values chosen by this macro. +@end defmac + +@defmac AC_FIND_XTRA +@maindex FIND_XTRA +An enhanced version of @code{AC_FIND_X}. Put the C compiler flags that +X needs into @code{make} variable @code{X_CFLAGS}, and the X linker +flags into @code{X_LIBS}. If X is not available, put +@samp{-DX_DISPLAY_MISSING} into @code{X_CFLAGS}. + +Also check for special libraries that some systems need in order to +compile X programs. Add any that the system needs to @code{make} +variable @code{X_EXTRA_LIBS}. This macro calls @code{AC_FIND_X} and +@code{AC_ISC_POSIX} (@pxref{UNIX Variants}) if they have not already +been called. Because of the macro dependencies, if you call this macro, +you should let it call @code{AC_FIND_X} rather than doing that yourself. +@end defmac + +@defmac AC_HAVE_POUNDBANG (@var{action-if-supported} @r{[}, @var{action-if-not-supported}@r{]}) +@maindex HAVE_POUNDBANG +Check whether the system supports starting shell scripts with a line of +the form @samp{#!/bin/csh} to select the shell to use. If @samp{#!} +works, execute shell commands @var{action-if-supported}; if not, execute +@var{action-if-not-supported}. +@end defmac + +@defmac AC_LONG_FILE_NAMES +@maindex LONG_FILE_NAMES +@vindex HAVE_LONG_FILE_NAMES +If the system supports file names longer than 14 characters, define +@code{HAVE_LONG_FILE_NAMES}. +@end defmac + +@defmac AC_REMOTE_TAPE +@maindex REMOTE_TAPE +@vindex HAVE_SYS_MTIO_H +If BSD tape drive ioctls are available, define @code{HAVE_SYS_MTIO_H}, +and if sockets are available add @code{rmt} to @code{make} variable +@code{PROGS}. +@end defmac + +@defmac AC_RESTARTABLE_SYSCALLS +@maindex RESTARTABLE_SYSCALLS +@vindex HAVE_RESTARTABLE_SYSCALLS +If the system automatically restarts a system call that is interrupted +by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. +@end defmac + +@node UNIX Variants, , System Services, Specific Tests +@section UNIX Variants + +The following macros check for certain operating systems that need +special treatment for some programs, due to exceptional oddities in +their header files or libraries: + +@defmac AC_AIX +@maindex AIX +@vindex _ALL_SOURCE +If on AIX, define @code{_ALL_SOURCE}. Allows the use of some BSD +functions. Should be called before any macros that run the C compiler. +@end defmac + +@defmac AC_DYNIX_SEQ +@maindex DYNIX_SEQ +If on DYNIX/ptx (Sequent UNIX), add @samp{-lseq} to @code{make} +variable @code{LIBS}. Allows use of some BSD system calls and +@code{getmntent}. +@end defmac + +@defmac AC_IRIX_SUN +@maindex IRIX_SUN +If on IRIX (Silicon Graphics UNIX), add @samp{-lsun} to @code{make} +variable @code{LIBS}. Needed to get @code{getmntent}. At sites using +Yellow Pages/NIS, it is also needed to get properly working +@code{gethostby*}, @code{getpw*}, @code{getgr*}, @code{getnetby*}, and +so on. +@c (According to Garrett.Wollman@uvm.edu.) +@end defmac + +@defmac AC_ISC_POSIX +@maindex ISC_POSIX +@vindex _POSIX_SOURCE +If on a POSIXized ISC UNIX, define @code{_POSIX_SOURCE} and add +@samp{-posix} (for the GNU C compiler) or @samp{-Xp} (for other C +compilers) to @code{make} variable @code{CC}. This allows the use of +POSIX facilities. Must be called after @code{AC_PROG_CC} and before +any other macros that run the C compiler. +@end defmac + +@defmac AC_MINIX +@maindex MINIX +@vindex _MINIX +@vindex _POSIX_SOURCE +@vindex _POSIX_1_SOURCE +If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define +@code{_POSIX_1_SOURCE} to be 2. This allows the use of POSIX +facilities. Should be called before any macros that run the C compiler. +@end defmac + +@defmac AC_SCO_INTL +@maindex SCO_INTL +If on SCO UNIX, add @samp{-lintl} to @code{make} variable @code{LIBS}. +Used to get @code{strftime}. It must be called before checking for +@code{strftime}. +@end defmac + +@defmac AC_XENIX_DIR +@maindex XENIX_DIR +@vindex VOID_CLOSEDIR +If on Xenix, define @code{VOID_CLOSEDIR} and add @samp{-lx} to +@code{make} variable @code{LIBS}. Also, if @file{sys/ndir.h} is not +being used, add @samp{-ldir} to @code{LIBS}. Needed when using the +directory reading functions. This macro must be called after +@code{AC_DIR_HEADER}. +@end defmac + +@node General Purpose Macros, Writing Macros, Specific Tests, Top +@chapter General Purpose Macros + +These macros provide ways for other macros to control the kind of output +that Autoconf produces or to check whether various kinds of features are +available. They all take arguments. When calling these macros, there +must not be any blank space between the macro name and the open +parentheses. + +Arguments to these macros can be more than one line long if they are +enclosed within the @code{m4} quote characters @samp{[} and @samp{]}. + +Within each section below, the macros are listed in alphabetical order. +These macros are defined in the file @file{acgeneral.m4}. + +@menu +* Setup:: Controlling Autoconf operation. +* General Feature Tests:: Checking for kinds of features. +* Command Line:: Checking command line arguments. +* Setting Variables:: Setting shell and @code{make} variables. +* Printing Messages:: Notifying users of progress or problems. +* Language Choice:: Selecting which language to use for testing. +* Macro Ordering:: Enforcing ordering constraints. +@end menu + +@node Setup, General Feature Tests, , General Purpose Macros +@section Controlling Autoconf Setup + +The following macros control the kind of output that Autoconf produces. + +@defmac AC_CONFIG_HEADER (@var{header-to-create} @dots{}) +@maindex CONFIG_HEADER +@vindex HAVE_CONFIG_H +Make @code{AC_OUTPUT} create the file(s) in the +whitespace-separated list @var{header-to-create} containing C +preprocessor @code{#define} statements and replace @samp{@@DEFS@@} in +generated files with @samp{-DHAVE_CONFIG_H} instead of the value of +@code{DEFS}. +This macro should be called right after @code{AC_INIT}. The usual name +for @var{header-to-create} is @file{config.h}. + +If @var{header-to-create} already exists and its contents are identical +to what @code{AC_OUTPUT} would put in it, it is left alone. Doing this +allows some changes in configuration without needlessly causing object +files that depend on the header file to be recompiled. + +Your distribution should contain a file @file{@var{header-to-create}.in} +that looks as you want the final header file to look, including +comments, with default values in the @code{#define} statements. A +default value can be to @code{#undef} the variable instead of to define +it to a value, if your code tests for configuration options using +@code{#ifdef} instead of @code{#if}. + +You can use the program @code{autoheader} to create +@file{@var{header-to-create}.in} (@pxref{Invoking autoheader}). +@end defmac + +@defmac AC_INIT (@var{unique-file-in-source-dir}) +@maindex INIT +Process the command-line arguments and find the source code directory. +@var{unique-file-in-source-dir} is some file that is in the package's +source directory; @code{configure} checks for this file's existence to +make sure that the directory that it is told contains the source code in +fact does (@pxref{Invoking configure}, for more information). +@end defmac + +@defmac AC_OUTPUT (@r{[}@var{file}@dots{}@r{] [,}@var{extra-cmds}@r{]}) +@maindex OUTPUT +Create output files (typically one or more @file{Makefile}s) and +@file{config.status}. If @code{AC_CONFIG_HEADER} has been called, also +create the header file that was named as its argument. The argument is +a whitespace-separated list of files to create; if it is omitted, no +files are created. @code{AC_OUTPUT} creates each file @file{@var{file}} +in the list by copying @file{@var{file}.in}, substituting the variable +values that have been selected by calling @code{AC_SUBST}. It creates +the directory that each file is in if it doesn't exist (but not the +parents of that directory). A plausible value for the argument to +@code{AC_OUTPUT} is @samp{Makefile src/Makefile man/Makefile +X/Imakefile}. + +If you pass @var{extra-cmds}, those commands will be inserted into +@file{config.status} to be run after all its other processing. +@end defmac + +@defmac AC_PREPARE (@var{unique-file-in-source-dir}) +@maindex PREPARE +Find the source code directory and set up shell variables necessary for +other Autoconf macros to work. @var{unique-file-in-source-dir} is some +file that is in the package's source directory; @code{configure} checks +for this file's existence to make sure that the directory that it is +told contains the source code in fact does (@pxref{Invoking configure}, +for more information). @code{AC_PREPARE} is the last thing done by +@code{AC_INIT}. Use @code{AC_PREPARE} instead of @code{AC_INIT} if you +want to do argument parsing yourself; never use both. +@end defmac + +@defmac AC_PREREQ (@var{version}) +@maindex PREREQ +Ensure that a recent enough version of Autoconf is being used. If the +version of Autoconf being used to create @code{configure} is earlier +than @var{version} (e.g., @samp{1.8}), print an error message on the +standard error output and do not create @code{configure}. + +This macro is useful if your @file{configure.in} relies on non-obvious +behavior that changed between Autoconf releases. If it merely needs +recently added macros, then @code{AC_PREREQ} is less useful, because the +@code{autoconf} program already tells the user which macros are not +found. The same thing happens if @file{configure.in} is processed by a +version of Autoconf older than when @code{AC_PREREQ} was added. +@end defmac + +@defmac AC_REVISION (@var{revision-info}) +@maindex REVISION +Copy revision stamp @var{revision-info} into the @file{configure} +script, with any dollar signs or double-quotes removed. This macro lets +you put a revision stamp from @file{configure.in} into @file{configure} +without RCS or CVS changing it when you check in @file{configure}. That +way, you can determine easily which revision of @file{configure.in} a +particular @file{configure} corresponds to. + +It is a good idea to call this macro before @code{AC_INIT} so that the +revision number is near the top of both @file{configure.in} and +@file{configure}. To support doing that, the @code{AC_REVISION} output +begins with @samp{#!/bin/sh}, like the normal start of a +@file{configure} script does. + +For example, this line in @file{configure.in}: + +@example +AC_REVISION($@asis{Revision: 1.30 }$)dnl +@end example + +@noindent +produces this in @file{configure}: + +@example +#!/bin/sh +# From configure.in Revision: 1.30 +@end example +@end defmac + +@node General Feature Tests, Command Line, Setup, General Purpose Macros +@section Checking for Kinds of Features + +These macros are templates that, when called with actual parameters, +check for various kinds of features. Many of these 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 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 @var{action-if-found} +argument to the macro. To omit the false case, omit the +@var{action-if-not-found} argument to the macro, including the comma +before it. + +One shell programming construction that you should not use in the action +arguments to these macros is +@samp{@var{var}=$@{@var{var}:-@var{value}@}}. Old BSD shells, including +the Ultrix @code{sh}, don't understand the colon, and complain and die. +If you omit the colon, it works fine: +@samp{@var{var}=$@{@var{var}-@var{value}@}}. Using the form without the +colon has one small disadvantage. Users can not select a default value +by giving a variable an empty value, e.g., @samp{CC= configure}. +Instead, they must unset the variable, e.g., @samp{unset CC; configure}. + +@xref{Writing Macros}, for more information on how best to use these +macros. + +@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@maindex COMPILE_CHECK + +Print @samp{checking for @var{echo-text}} to the standard output +(using @code{AC_CHECKING}, @pxref{Printing Messages}). +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 +@code{#include} statements needed by the code in @var{function-body}. +If the file compiles and links successfully, run shell commands +@var{action-if-found}, otherwise run @var{action-if-not-found}. +@end defmac + +@defmac AC_FUNC_CHECK (@var{function}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@maindex FUNC_CHECK +If @var{function} is available, run shell commands +@var{action-if-found}, otherwise @var{action-if-not-found}. If the +functions might be in libraries other than the default C library, first +call @code{AC_HAVE_LIBRARY} for those libraries. If you just want to +define a symbol if the function is available, consider using +@code{AC_HAVE_FUNCS} instead. +@end defmac + +@defmac AC_HAVE_FUNCS (@var{function}@dots{}) +@maindex HAVE_FUNCS +@vindex HAVE_@var{function} +For each given @var{function} in the whitespace-separated argument list +that is available, define @code{HAVE_@var{function}} (in all caps). +@xref{Specific Tests}, for a precise definition of ``define'' as it +is used here. If the functions might be in libraries other than the +default C library, first call @code{AC_HAVE_LIBRARY} for those libraries. +@end defmac + +@defmac AC_HAVE_HEADERS (@var{header-file}@dots{}) +@maindex HAVE_HEADERS +@vindex HAVE_@var{header} +For each given @var{header-file} in the whitespace-separated argument +list that exists, define @code{HAVE_@var{header-file}} (in all caps). +@xref{Specific Tests}, for a precise definition of ``define'' as +it is used here. +@end defmac + +@defmac AC_HAVE_LIBRARY (@var{library} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) +@maindex HAVE_LIBRARY +Create a test C program to see whether that program can be linked with +the specified library. @var{action-if-found} is a list of shell +commands to run if the link succeeds (which means that the library is +present); @var{action-if-not-found} is a list of shell commands to run +if the link fails. If @var{action-if-found} and +@var{action-if-not-found} are not specified, the default action is to +add @samp{-lfoo} to @code{LIBS} and define @samp{HAVE_LIBfoo} +for library @samp{foo}. @var{library} can be written as any of +@samp{foo}, @samp{-lfoo}, or @samp{libfoo.a}. In all of those cases, +the compiler is passed @samp{-lfoo}. +@end defmac + +@defmac AC_HEADER_CHECK (@var{header-file}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@maindex HEADER_CHECK +If @var{header-file} exists, execute shell commands +@var{action-if-found}, otherwise execute @var{action-if-not-found}. If +you just want to define a symbol if the header file is available, +consider using @code{AC_HAVE_HEADERS} instead. +@end defmac + +@defmac AC_HEADER_EGREP (@var{pattern}, @var{header-file}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@maindex HEADER_EGREP +If the output of running the preprocessor on @var{header-file} +contains the @code{egrep} regular expression @var{pattern}, execute +shell commands @var{action-if-found}, otherwise execute + +This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending +on which language is current, @pxref{Language Choice}), if it hasn't +been called already. +@var{action-if-not-found}. + +You can not check whether preprocessor symbols are defined this way, +because they get expanded before @code{egrep} sees them. But you can +almost always detect them by simply using @code{#ifdef} directives in +your programs. +@end defmac + +@defmac AC_PROGRAM_CHECK (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @var{value-if-not-found}) +@maindex PROGRAM_CHECK +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 @var{variable} was already set, do nothing. +Calls @code{AC_SUBST} for @var{variable}. +@end defmac + +@defmac AC_PROGRAM_EGREP (@var{pattern}, @var{program}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) +@maindex PROGRAM_EGREP +@var{program} is the text of a C or C++ program, on which shell variable and +backquote substitutions are performed. If the output of running the +preprocessor on @var{program} contains the @code{egrep} regular +expression @var{pattern}, execute shell commands @var{action-if-found}, +otherwise execute @var{action-if-not-found}. (It is an unfortunate +oversight that we use the word @code{PROGRAM} in Autoconf macro names to +sometimes mean C or C++ source code and sometimes mean a UNIX command.) + +This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending +on which language is current, @pxref{Language Choice}), if it hasn't +been called already. +@end defmac + +@defmac AC_PROGRAM_PATH (@var{variable}, @var{prog-to-check-for}, @var{value-if-not-found}) +@maindex PROGRAM_PATH +Similar to @code{AC_PROGRAM_CHECK}, but set @var{variable} to the entire +path of @var{prog-to-check-for} if found. Otherwise, set @var{variable} +to the value @var{value-if-not-found} and perform no path checking. +If @var{variable} was already set, do nothing. +Calls @code{AC_SUBST} for @var{variable}. +@end defmac + +@defmac AC_PROGRAMS_CHECK (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found}@r{]}) +@maindex PROGRAMS_CHECK +Check for each program in the whitespace-separated list +@var{progs-to-check-for} exists in @code{PATH}. If it is found, set +@var{variable} to the name of that program. Otherwise, continue +checking the next program in the list. If none of the programs in the +list are found, set @var{variable} to @var{value-if-not-found}; if +@var{value-if-not-found} is not specified, the value of @var{variable} +will not be changed. Calls @code{AC_SUBST} for @var{variable}. +@end defmac + +@defmac AC_PROGRAMS_PATH (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found}@r{]}) +@maindex PROGRAMS_PATH +Like @code{AC_PROGRAMS_CHECK}, but if any of @var{progs-to-check-for} +are found, set @var{variable} to the entire pathname of the program +found. +@end defmac + +@defmac AC_REPLACE_FUNCS (@var{function-name}@dots{}) +@maindex REPLACE_FUNCS +For each given @var{function-name} in the whitespace-separated argument +list that is not in the C library, add @samp{@var{function-name}.o} to +the value of the @code{make} variable @code{LIBOBJS}. If the functions +might be in libraries other than the default C library, first call +@code{AC_HAVE_LIBRARY} for those libraries. +@end defmac + +@defmac AC_SIZEOF_TYPE (@var{type}) +@maindex SIZEOF_TYPE +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, 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 +@example +AC_SIZEOF_TYPE(int *) +@end example +@noindent +defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems. +@end defmac + +@defmac AC_TEST_PROGRAM (@var{program}, @var{action-if-true} @r{[}, @var{action-if-false} @r{[}, @var{action-if-cross-compiling}@r{]]}) +@maindex TEST_PROGRAM +@var{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 @var{action-if-true}. Otherwise run shell commands +@var{action-if-false}. + +If the optional argument @var{action-if-cross-compiling} is given and +the C compiler being used does not produce executables that run on the +system where @code{configure} is being run, then the test program is not +run. Instead, the shell commands @var{action-if-cross-compiling} are +run. If that argument is given, this macro calls @code{AC_CROSS_CHECK} +if it has not already been called (@pxref{Compiler Characteristics}). +@end defmac + +@defmac AC_TEST_CPP (@var{includes}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) +@maindex TEST_CPP +@var{includes} is C or C++ @code{#include} statements and declarations, on +which shell variable and backquote substitutions are performed. +(Actually, it can be any C program, but other statements are probably +not useful.) If the preprocessor produces no error messages while +processing it, run shell commands @var{action-if-true}. Otherwise run +shell commands @var{action-if-false}. + +This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending +on which language is current, @pxref{Language Choice}), if it hasn't +been called already. +@end defmac + +@node Command Line, Setting Variables, General Feature Tests, General Purpose Macros +@section Checking Command Line Arguments + +These macros check whether the user gave @code{configure} various +command line arguments. Like the general feature tests (@pxref{General +Feature Tests}), they may take an argument to use if the argument was +given and one for if it was not given. + +@defmac AC_ENABLE (@var{feature}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) +@maindex ENABLE +If the user gave @code{configure} the option +@samp{--enable-@var{feature}} or @samp{--disable-@var{feature}}, run +shell commands @var{action-if-true}. Otherwise run shell commands +@var{action-if-false}. The name @var{feature} should consist only of +alphanumeric characters and dashes. + +The @var{feature} indicates an optional user-level facility. This +option allows users to choose which optional features to build and +install. @samp{--enable-@var{feature}} options should never make a +feature behave differently or cause one feature to replace another. +They should only cause parts of the program to be built rather than left +out. + +The user can give an argument by following the feature name with +@samp{=} and the argument. Giving an argument of @samp{no} indicates +that the feature is @emph{not} available. A feature with an argument +looks like @samp{--enable-debug=stabs}. + +The argument is available to the shell commands @var{action-if-true} in +the shell variable @code{enableval}. If no argument was given to +@samp{--enable-@var{feature}}, @code{enableval} is @samp{yes}. +@samp{--disable-@var{feature}} is equivalent to +@samp{--enable-@var{feature}=no}. At present, arguments containing blanks +are not handled correctly; if you need an argument to contain a list, +require the items to be separated by commas instead. (This restriction +might disappear in the future.) +@end defmac + +@defmac AC_PREFIX (@var{program}) +@maindex PREFIX +If the user did not specify an installation prefix (using the +@samp{--prefix} option), guess a value for it by looking for +@var{program} in @code{PATH}, the way the shell does. If @var{program} +is found, set the prefix to the parent of the directory containing +@var{program}; otherwise leave the prefix specified in +@file{Makefile.in} unchanged. For example, if @var{program} is +@code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc}, +set the prefix to @file{/usr/local/gnu}. +@end defmac + +@defmac AC_WITH (@var{package}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) +@maindex WITH +If the user gave @code{configure} the option @samp{--with-@var{package}} +or @samp{--without-@var{package}}, run shell commands +@var{action-if-true}. Otherwise run shell commands +@var{action-if-false}. The name @var{package} should consist only of +alphanumeric characters and dashes. + +The @var{package} indicates another software package that this program +should work with. For example, @samp{--with-gnu-ld} means work with the +GNU linker instead of some other linker. @samp{--with-x11} means work +with X11. + +The user can give an argument by following the package name with +@samp{=} and the argument. Giving an argument of @samp{no} is for +packages that would be used by default; it says to @emph{not} use the +package. An argument that is neither @samp{yes} nor @samp{no} could +include a name or number of a version of the other package, to specify +more precisely which other package this program is supposed to work +with. + +The argument is available to the shell commands @var{action-if-true} in +the shell variable @code{withval}. If no argument was given to +@samp{--with-@var{package}}, @code{withval} is @samp{yes}. +@samp{--without-@var{package}} is equivalent to +@samp{--with-@var{package}=no}. At present, arguments containing blanks +are not handled correctly; if you need an argument to contain a list, +require the items to be separated by commas instead. (This restriction +might disappear in the future.) +@end defmac + +@node Setting Variables, Printing Messages, Command Line, General Purpose Macros +@section Setting Variables + +These macros help other macros to define shell and @code{make} +variables. + +@defmac AC_DEFINE (@var{variable} @r{[}, @var{value}@r{]}) +@maindex DEFINE +Define C preprocessor variable @var{variable}. If @var{value} is given, +set @var{variable} to that value, otherwise set it to 1. To use a shell +variable as the value, use @code{AC_DEFINE_UNQUOTED} instead and precede +double quotes in the value with backslashes. + +This macro adds to the shell variable @code{DEFS}. @code{AC_OUTPUT} +later substitutes the values in @code{DEFS} into the file(s) that it +generates (typically @file{Makefile}). Alternately, if +@code{AC_CONFIG_HEADER} has been called, @code{AC_OUTPUT} creates a +header file by substituting the correct values into @code{#define} +statements in a template file. + +For example, suppose your @file{configure.in} calls +@code{AC_CONFIG_HEADER(conf.h)} and @code{AC_HAVE_HEADERS(unistd.h)}. +You could have code like this in @file{conf.h.in}: + +@example +@group +/* Define as 1 if you have unistd.h. */ +#define HAVE_UNISTD_H 0 +@end group +@end example + +On systems that have @file{unistd.h}, @code{configure} will change the 0 +to a 1. On other systems, it will leave the line unchanged. +Alternately, if you prefer to use @code{#ifdef}, your @file{conf.h.in} +could have code like this: + +@example +@group +/* Define if you have unistd.h. */ +#undef HAVE_UNISTD_H +@end group +@end example + +On systems that have @file{unistd.h}, @code{configure} will change the +second line to read @samp{#define HAVE_UNISTD_H 1}. On other systems, +it will comment that line out (in case the system predefines that symbol). + +Due to the syntactical bizarreness of the Bourne shell, do not use +semicolons to separate @code{AC_DEFINE} calls from other macro calls or +shell code; that can cause syntax errors in the resulting +@code{configure} script. Use either spaces or newlines. That is, do +this: + +@example +AC_HEADER_CHECK(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf") +@end example + +@noindent +or this: + +@example +AC_HEADER_CHECK(elf.h, + AC_DEFINE(SVR4) + LIBS="$LIBS -lelf") +@end example + +@noindent +instead of this: + +@example +AC_HEADER_CHECK(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf") +@end example +@end defmac + +@defmac AC_DEFINE_UNQUOTED (@var{variable} @r{[}, @var{value}@r{]}) +@maindex DEFINE_UNQUOTED +Like @code{AC_DEFINE}, but it does nothing to quote @var{value} from +various shell and @code{sed} expansions it will undergo. @var{value} +will be used in many different contexts requiring different quoting, and +it is up to you to make sure it works right. Use this macro instead of +@code{AC_DEFINE} when @var{value} contains a shell variable. For +example: + +@example +AC_DEFINE_UNQUOTED(config_machfile, $@{machfile@}) +@end example +@end defmac + +@defmac AC_SUBST (@var{variable}) +@maindex SUBST +Substitute the variable @var{variable} when creating the output files +(typically one or more @file{Makefile}s). This means replace instances +of @samp{@@@var{variable}@@}, e.g. in @file{Makefile.in}, with the +current value of the shell variable @var{variable}. If this macro were +not called, the value of @var{variable} would not be set in the output +files, even though @code{configure} had figured out a value for it. + +You can set or add to the value of @var{variable} in the usual shell +way. For example, to add @samp{-ltermcap} to the value of the variable +@code{LIBS}: + +@example +LIBS="$LIBS -ltermcap" +@end example +@end defmac + +@node Printing Messages, Language Choice, Setting Variables, General Purpose Macros +@section Printing Messages + +@code{configure} scripts need to give users running them several kinds +of information. The following macros print messages in ways appropriate +for different kinds of information. 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 @code{echo} shell command. +Other macros should rarely need to run @code{echo} directly to print +messages for the @code{configure} 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. + +@defmac AC_CHECKING (@var{feature-description}) +@maindex CHECKING +Notify the user that @code{configure} is checking for a particular +feature. This macro prints a message that starts with @samp{checking }. +It prints nothing if @code{configure} is run with the @samp{--silent} or +@samp{--quiet} option. The @var{feature-description} should be +something like @samp{whether the Fortran compiler accepts C++ comments} +or @samp{for c89}. +@end defmac + +@defmac AC_ERROR (@var{error-description}) +@maindex ERROR +Notify the user of an error that prevents @code{configure} from +completing. This macro prints an error message on the standard error +stream and exits @code{configure} with a nonzero status. +@var{error-description} should be something like @samp{invalid value +$HOME for \$HOME}. +@end defmac + +@defmac AC_VERBOSE (@var{result-description}) +@maindex VERBOSE +Notify the user of the results of a check. This information is +only printed if @code{configure} is run with the @samp{--verbose} +option. @var{result-description} should be something like @samp{setting +ADA to $ADA}. +@end defmac + +@defmac AC_WARN (@var{problem-description}) +@maindex WARN +Notify the @code{configure} user of a possible problem. This macro +prints the message on the standard error stream; @code{configure} +continues running afterward, so macros that call @code{AC_WARN} should +provide a default (back-up) behavior for the situations they warn about. +@var{problem-description} should be something like @samp{ln -s seems to +make hard links}. +@end defmac + +@node Language Choice, Macro Ordering, Printing Messages, General Purpose Macros +@section Language Choice + +Packages that use both C and C++ need to test features of both +compilers. Autoconf-generated @code{configure} scripts check for C +features by default. The following macros determine which language's +compiler is used in tests that follow in @file{configure.in}. + +@defmac AC_LANG_C +@maindex LANG_C +Do compilation tests using @code{CC} and @code{CPP} and use extension +@file{.c} for test programs. + +This is the initial state. +@end defmac + +@defmac AC_LANG_CPLUSPLUS +@maindex LANG_CPLUSPLUS +Do compilation tests using @code{CXX} and @code{CXXCPP} and use +extension @file{.C} for test programs. +@end defmac + +@defmac AC_LANG_RESTORE +@maindex LANG_RESTORE +Select the language that is saved on the top of the stack, as set by +@code{AC_LANG_SAVE}, and remove it from the stack. This macro is +equivalent to either @code{AC_LANG_C} or @code{AC_LANG_CPLUSPLUS}, +whichever had been run most recently when @code{AC_LANG_SAVE} was last +called. + +Do not call this macro more times than @code{AC_LANG_SAVE}. +@end defmac + +@defmac AC_LANG_SAVE +@maindex LANG_SAVE +Remember the current language (as set by @code{AC_LANG_C} or +@code{AC_LANG_CPLUSPLUS}) on a stack. Does not change which language is +current. Use this macro and @code{AC_LANG_RESTORE} in macros that need +to temporarily switch to a particular language. +@end defmac + +@defmac AC_REQUIRE_CPP +@maindex REQUIRE_CPP +Ensure that whichever preprocessor would currently be used for tests has +been found. Calls @code{AC_REQUIRE} (@pxref{Macro Ordering}) with an +argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP}, +depending on which language is current. +@end defmac + +@node Macro Ordering, , Language Choice, General Purpose Macros +@section Macro Ordering + +These macros provide ways for other macros to make sure that they are +called in the correct order. + +@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) +@maindex BEFORE +Make @code{m4} print a warning message on the standard error output if +@var{called-macro-name} has already been called. @var{this-macro-name} +should be the name of the macro that is calling @code{AC_BEFORE}. The +macro @var{called-macro-name} must contain a call to @code{AC_PROVIDE} +to indicate that it has been called. + +This macro should be used when one macro makes changes that might affect +another macro, so that the other macro should probably not be called +first. For example, @code{AC_PROG_CPP} checks whether the C compiler +can run the C preprocessor when given the @samp{-E} option. It should +therefore be called after any macros that change which C compiler is +being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains: + +@example +AC_BEFORE([$0], [AC_PROG_CPP]) +@end example + +@noindent +This warns the user if a call to @code{AC_PROG_CPP} has already occurred +when @code{AC_PROG_CC} is called. +@end defmac + +@defmac AC_OBSOLETE (@var{this-macro-name} @r{[}, @var{suggestion}@r{]}) +@maindex OBSOLETE +Make @code{m4} print a message on the standard error output warning that +@var{this-macro-name} is obsolete, and giving the file and line number +where it was called. @var{this-macro-name} should be the name of the +macro that is calling @code{AC_BEFORE}. If @var{suggestion} is given, +it is printed at the end of the warning message; for example, it can be +a suggestion for what to use instead of @var{this-macro-name}. + +A sample call is: + +@example +AC_OBSOLETE([$0], [; use AC_HAVE_HEADERS(unistd.h) instead]) +@end example +@end defmac + +@defmac AC_PROVIDE (@var{macro-name}) +@maindex PROVIDE +Set a flag recording that @var{macro-name} has been called. The +argument should be the name of the macro that is calling +@code{AC_PROVIDE}. An easy way to get it is from the @code{m4} builtin +variable @code{$0}, like this: + +@example +AC_PROVIDE([$0]) +@end example +@end defmac + +@defmac AC_REQUIRE (@var{macro-name}) +@maindex REQUIRE +If the @code{m4} macro @var{macro-name} has not already been called, +call it (without any arguments). Make sure to quote @var{macro-name} +with square brackets. The body of @var{macro-name} must contain a call +to @code{AC_PROVIDE} to indicate that it has been called. + +Macros that need some other macro to be called before they are called +can use @code{AC_REQUIRE} to ensure that it has been, in case the person +who made @file{configure.in} forgot or didn't know to do it. +@code{AC_REQUIRE} and @code{AC_PROVIDE} together can ensure that a macro +is only called if it is needed, and only called once. +@xref{Dependencies Between Macros}, for more information. +@end defmac + +@node Writing Macros, Makefiles, General Purpose Macros, Top +@chapter Writing Macros + +If your package needs to test for some feature that none of the macros +supplied with Autoconf handles, you'll need to write one or more new +Autoconf macros. Here are some suggestions and some of the rationale +behind why the existing macros are written the way they are. You can +also learn a lot about how to write Autoconf macros by looking at the +existing ones. If something goes wrong in one or more of the Autoconf +tests, this information can help you understand why they work the way +they do and the assumptions behind them, which might help you figure out +how to best solve the problem. + +If you add macros that you think would be useful to other people, or +find problems with the distributed macros, please send electronic mail +to @file{bug-gnu-utils@@prep.ai.mit.edu}, so we can consider them for +future releases of Autoconf. Please include the Autoconf version +number, which you can get by running @samp{autoconf --version}. + +@menu +* Macro Format:: Basic format of an Autoconf macro. +* Quoting:: Protecting macros from unwanted expansion. +* Dependencies Between Macros:: What to do when macros depend on other macros. +* Checking for Files:: Finding whether a file exists. +* Checking for Symbols:: Finding whether a symbol is defined. +* Test Programs:: Writing programs to test for features. +* Multiple Cases:: Tests for several possible values. +@end menu + +@node Macro Format, Quoting, , Writing Macros +@section Macro Format + +Autoconf macros are defined as arguments to the @code{m4} builtin +command @code{define}. Their overall structure looks like this: + +@example +define(@var{macro-name}, [@var{macro-body}])dnl +@end example + +@noindent +The square brackets here do not indicate optional text: they should +literally be present in the macro definition. + +All of the Autoconf macros have names starting with @samp{AC_} to +prevent them from accidentally conflicting with other text. All shell +variables that they use for internal purposes have names starting with +@samp{ac_}. To ensure that your macros don't conflict with present or +future Autoconf macros, you should prefix your own macro names and any +shell variables they use with some other sequence. Possibilities +include your initials, or an abbreviation for the name of your +organization or software package. + +The @code{m4} builtin @code{dnl} prevents a newline from being inserted +in the output where the macro is defined; without it, the generated +@code{configure} script would begin with dozens of blank lines. +@code{dnl} is also used to introduce comments in @code{m4}; it causes +@code{m4} to discard the rest of the input line. + +You should quote the entire macro body with square brackets to avoid +macro expansion problems (@pxref{Quoting}). You can refer to any +arguments passed to the macro as @samp{$1}, @samp{$2}, etc. + +@xref{Definitions, , How to define new macros, m4.info, GNU m4}, for +more complete information on writing @code{m4} macros. + +@node Quoting, Dependencies Between Macros, Macro Format, Writing Macros +@section Quoting + +Macros that are called by other macros are evaluated by @code{m4} +several times; each evaluation might require another layer of quotes to +prevent unwanted expansions of macros or @code{m4} builtins, such as +@samp{define} and @samp{$1}. Quotes are also required around macro +arguments that contain commas, since commas separate the arguments from +each other. + +Autoconf (in @file{acgeneral.m4}) changes the @code{m4} quote characters +from the default @samp{`} and @samp{'} to @samp{[} and @samp{]}, because +many of the macros use @samp{`} and @samp{'}, mismatched. However, in a +few places the macros need to use brackets. In those places, they use +the @code{m4} builtin command @code{changequote} to temporarily disable +quoting before the code that uses brackets, like this: + +@example +changequote(,)dnl +@end example + +@noindent +Then they turn quoting back on again with another call to +@code{changequote}: + +@example +changequote([,])dnl +@end example + +When you create a @code{configure} script using newly written macros, +examine it carefully to check whether you need to add more quotes in +your macros. If one or more words have disappeared in the @code{m4} +output, you need more quotes. When in doubt, quote. + +However, it's also possible to put on too many layers of quotes. If +this happens, the resulting @code{configure} script will contain +unexpanded macros. The @code{autoconf} program checks for this problem +by doing @samp{grep AC_ configure}. + +@node Dependencies Between Macros, Checking for Files, Quoting, Writing Macros +@section Dependencies Between Macros + +Some Autoconf macros depend on other macros having been called first in +order to work correctly. Autoconf provides a way to ensure that certain +macros are called if needed and a way to warn the user if macros are +called in an order that might cause incorrect operation. + +@menu +* Prerequisite Macros:: Ensuring required information. +* Suggested Ordering:: Warning about possible ordering problems. +@end menu + +@node Prerequisite Macros, Suggested Ordering, , Dependencies Between Macros +@subsection Prerequisite Macros + +A macro that you write might need to use values that have previously +been computed by other macros. For example, if you write a new macro +that uses the C preprocessor, it depends on @code{AC_PROG_CPP} having +been called first to set the shell variable @code{CPP} +(@pxref{Alternative Programs}). + +Rather than forcing the user of the macros to keep track of all of the +dependencies between them, you can use the macros @code{AC_PROVIDE} and +@code{AC_REQUIRE} to do it automatically. @xref{Macro Ordering}, for more +information on their syntax. + +The new macro that runs the C preprocessor should contain, somewhere +before @code{CPP} is used, the statement + +@example +AC_REQUIRE([AC_PROG_CPP]) +@end example + +@noindent +and the macro @code{AC_PROG_CPP} should contain the statement (anywhere +in its body) + +@example +AC_PROVIDE([$0]) +@end example + +@noindent +Then, when the new macro is run, it will invoke @code{AC_PROG_CPP} if +and only if @code{AC_PROG_CPP} has not already been run. + +@node Suggested Ordering, , Prerequisite Macros, Dependencies Between Macros +@subsection Suggested Ordering + +Some macros should be run before another macro if both are called, but +neither requires the other to be called. For example, a macro like +@code{AC_AIX} that changes the behavior of the C compiler (@pxref{UNIX +Variants}) should be called before any macros that run the C compiler. +Many of these dependencies are noted in the documentation. + +Autoconf provides a way to warn users when macros with this kind of +dependency appear out of order in a @file{configure.in} file. The +warning occurs when creating @file{configure} from @file{configure.in}, +not when running @file{configure}. It is not a fatal error; +@file{configure} is created as usual. + +The @code{AC_BEFORE} macro causes @code{m4} to print a warning message +on the standard error output when a macro is used before another macro +which might change its behavior. The macro which should come first +should contain a call to @code{AC_BEFORE} and the macro which should +come later should contain a call to @code{AC_PROVIDE}. + +For example, @code{AC_AIX} contains + +@example +AC_BEFORE([$0], [AC_COMPILE_CHECK]) +@end example + +@noindent +and @code{AC_COMPILE_CHECK} contains + +@example +AC_PROVIDE([$0]) +@end example + +@noindent +As a result, if @code{AC_AIX} is called after @code{AC_COMPILE_CHECK}, +it will note that @code{AC_COMPILE_CHECK} has already been called and +print a warning message. + +@node Checking for Files, Checking for Symbols, Dependencies Between Macros, Writing Macros +@section Checking for Files + +If you need to check whether a file other than a C header file exists, +use @samp{test -f @var{filename}}. If you need to make multiple checks +using @code{test}, combine them with the shell operators @samp{&&} and +@samp{||} instead of using the @code{test} operators @samp{-a} and +@samp{-o}. On System V, the precedence of @samp{-a} and @samp{-o} is +wrong relative to the unary operators; consequently, POSIX does not +specify them, so using them is nonportable. If you combine @samp{&&} +and @samp{||} in the same statement, keep in mind that they have equal +precedence. + +Do not use @samp{test -x}, because 4.3BSD does not have it. Use +@samp{test -f} or @samp{test -r} instead. + +@node Checking for Symbols, Test Programs, Checking for Files, Writing Macros +@section Checking for Symbols + +If you need to check whether a symbol is defined in a C header file, you +can use @code{AC_HEADER_EGREP} if the symbol is not a C preprocessor +macro (@pxref{General Feature Tests}), or compile a small test program that includes +the file and references the symbol (@pxref{Test Programs}). Don't +directly @code{grep} for the symbol in the file, because on some systems +it might be defined in another header file that the file you are +checking @samp{#include}s. + +However, if you need to check for a particular UNIX variant which is +distinguished by having certain text in a certain file, then use +@code{grep} (or @code{egrep}). But don't use @samp{grep -s} to suppress +output, because @samp{grep -s} on System V does not suppress output, +only error messages. Instead, redirect the standard output and standard +error (in case the file doesn't exist) of @code{grep} to +@file{/dev/null}. Check the exit status of @code{grep} to determine +whether it found a match. + +To check whether the Autoconf macros have already defined a certain C +preprocessor symbol, you can use a @code{case} statement like this: + +@example +case "$DEFS" in + *HAVE_FOO*) ;; + *) LIBOBJS="$LIBOBJS foo.o" ;; +esac +@end example + +@noindent +Make sure to enclose the variable name you are checking (usually +@code{DEFS}) in double quotes, because otherwise some old versions of +@code{bash} misinterpret the statement. + +@node Test Programs, Multiple Cases, Checking for Symbols, Writing Macros +@section Test Programs + +Autoconf checks for many features by compiling small test programs. To +find out whether a library function is available, Autoconf tries to +compile a small program that uses it. This is unlike Larry Wall's +Metaconfig, which uses @code{nm} or @code{ar} on the C library to try to +figure out which functions are available. Trying to link with the +function is usually a more reliable and flexible approach because it +avoids dealing with the variations in the options and output formats of +@code{nm} and @code{ar} and in the location of the standard libraries. +It also allows @code{configure} to check aspects of the function's +runtime behavior if needed. On the other hand, it is sometimes slower +than scanning the libraries. + +If you need to check for a condition other than whether some symbol +exists on the system or has a certain value, then you can't use +@code{AC_COMPILE_CHECK} (@pxref{General Feature Tests}). You have to write a +test program by hand. You can compile and run it using +@code{AC_TEST_PROGRAM} (@pxref{General Feature Tests}). + +Try to avoid writing test programs if possible, because using them +prevents people from configuring your package for cross-compiling. If +it's really best that you test for a run-time behavior, try to provide a +default ``worst case'' value to use when cross-compiling makes run-time +tests impossible. You do this by passing the optional last argument to +@code{AC_TEST_PROGRAM}. + +@menu +* Guidelines:: General rules for writing test programs. +* Tricks:: Special ways to work around problems. +@end menu + +@node Guidelines, Tricks, , Test Programs +@subsection Guidelines for Test Programs + +Test programs should return 0 if the test succeeds, nonzero otherwise, +so that success can be distinguished easily from a core dump or other +failure; segmentation violations and other failures produce a nonzero +exit status. Test programs should @code{exit}, not @code{return}, from +@code{main}, because on some systems the argument to @code{return} in +@code{main} is ignored. They should not write anything to the standard +output. + +Test programs can use @code{#if} or @code{#ifdef} to check the values of +preprocessor macros defined by tests that have already run. For +example, if you call @code{AC_STDC_HEADERS}, then later on in +@file{configure.in} you can have a test program that includes an ANSI C +header file conditionally: + +@example +@group +#if STDC_HEADERS +#include +#endif +@end group +@end example + +If a test program needs to use or create a data file, give it a name +that starts with @file{conftest}, such as @file{conftestdata}. The +@code{configure} script cleans up by running @samp{rm -rf conftest*} +after running test programs and if the script is interrupted. + +@node Tricks, , Guidelines, Test Programs +@subsection Tricks for Test Programs + +If a test program calls a function with invalid parameters (just to see +whether it exists), organize the program to ensure that it never invokes +that function. You can do this by calling it in another function that is +never invoked. You can't do it by putting it after a call to +@code{exit}, because GCC version 2 knows that @code{exit} never returns +and optimizes out any code that follows it in the same block. + +If you include any header files, make sure to call the functions +relevant to them with the correct number of arguments, even if they are +just 0, to avoid compilation errors due to prototypes. GCC version 2 +has internal prototypes for several functions that it automatically +inlines; for example, @code{memcpy}. To avoid errors when checking for +them, either pass them the correct number of arguments or redeclare them +with a different return type (such as @code{char}). + +@node Multiple Cases, , Test Programs, Writing Macros +@section 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 excerpted from the @file{configure.in} for GNU +@code{find}. It uses the shell variable @code{fstype} to keep track of +whether the remaining cases need to be checked. There are several more +cases which are not shown here but follow the same pattern. + +@example +@group +echo checking how to get filesystem type +# SVR4. +AC_TEST_CPP([#include +#include ], AC_DEFINE(FSTYPE_STATVFS) fstype=1) +if test -z "$fstype"; then +# SVR3. +AC_TEST_CPP([#include +#include ], AC_DEFINE(FSTYPE_USG_STATFS) fstype=1) +fi +if test -z "$fstype"; then +# AIX. +AC_TEST_CPP([#include +#include ], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=1) +fi +@end group +@end example + +@node Makefiles, Invoking configure, Writing Macros, Top +@chapter Makefiles + +Each subdirectory in a distribution should come with a file +@file{Makefile.in}, from which @code{configure} will produce a +@file{Makefile} in that directory. Most of the substitutions that +@code{configure} does are simple: for each configuration variable that +the package uses, it just replaces occurrences of +@samp{@@@var{variable}@@} with the value that @code{configure} has +determined for that variable. Any occurrences of +@samp{@@@var{variable}@@} for variables that @code{configure} does not +know about are passed through unchanged. + +There is no point in checking for the correct value to give a variable +that is never used. Every variable that the @code{configure} script +might set a value for should appear in a @samp{@@@var{variable}@@} reference +in at least one @file{Makefile.in}. If @code{AC_CONFIG_HEADER} is +called, @code{configure} replaces @samp{@@DEFS@@} with +@samp{-DHAVE_CONFIG_H}, since the contents of @code{DEFS} would be +redundant. + +@xref{Makefiles, , Makefile Conventions, standards.info, The GNU Coding +Standards}, for more information on what to put in Makefiles. +@xref{Sample Makefile.in}, for an example of a real @file{Makefile.in}. + +@menu +* Predefined Variables:: Heavily used @code{make} variables. +* Installation Prefixes:: A special variable substitution. +* VPATH Substitutions:: Compiling in a different directory. +* Automatic Remaking:: Makefile rules for configuring. +@end menu + +@node Predefined Variables, Installation Prefixes, , Makefiles +@section Predefined Variables + +Some @code{make} variables are predefined by the Autoconf macros. +@code{AC_SUBST} is called for them automatically (@pxref{Setting +Variables}), so in your @file{Makefile.in} files you can get their +values by enclosing their names in @samp{@@} characters. +@ifinfo +@xref{Makefiles}, for more information on @samp{@@} substitutions. +@end ifinfo +The variables that are defined by the general +purpose Autoconf macros are: + +@defvar exec_prefix +The installation prefix for architecture-specific files. +@end defvar + +@defvar prefix +The installation prefix for architecture-independent files. +@xref{Installation Prefixes}, for an alternate way to set this variable. +@end defvar + +@defvar srcdir +The directory that contains the source code for that @file{Makefile}. +@xref{Installation Prefixes}, for an alternate way to set this variable. +@end defvar + +@defvar top_srcdir +The top-level source code directory for the package. In the top-level +directory, this is the same as @code{srcdir}. +@end defvar + +@defvar DEFS +@samp{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADER} +is called, @code{configure} replaces @samp{@@DEFS@@} with +@samp{-DHAVE_CONFIG_H}, since the contents of @code{DEFS} would be +redundant. +@end defvar + +@defvar LIBS +@samp{-l} and @samp{-L} options to pass to the linker. +@end defvar + +@defvar LIBOBJS +Names of object files (ending in @file{.o}). Set by +@code{AC_REPLACE_FUNCS} (@pxref{General Feature Tests}). +@end defvar + +@node Installation Prefixes, VPATH Substitutions, Predefined Variables, Makefiles +@section Installation Prefixes + +Autoconf-generated @code{configure} scripts support an alternate +method for substituting two particular variables, for compatibility with +Cygnus @code{configure}. This method is not recommended. + +If @code{configure} has figured out a value for the installation prefix, +either by the user supplying one on the command line (@pxref{Invoking +configure}) or with @code{AC_PREFIX} (@pxref{General Feature Tests}), then it +substitutes that value in @file{Makefile}s that it creates. Wherever a +@file{Makefile.in} contains lines like + +@example +prefix = /usr/local +exec_prefix = $@{prefix@} +@end example + +@noindent +@code{configure} substitutes the value it figured out. The substitution +only occurs if the word @samp{prefix} or @samp{exec_prefix} is not +preceded by any other characters on the line, and @code{configure} has +figured out a value for the prefix. + +There can be separate installation prefixes for architecture-specific +files (@code{exec_prefix}) and architecture-independent files +(@code{prefix}). @xref{Invoking configure}, for more information +on setting them. + +Autoconf @code{configure} scripts replace these two variables without +requiring them to be enclosed in @samp{@@} characters, and only if they +have been set, because the Cygnus @code{configure} does so. In +retrospect, being compatible in this way was a bad decision, because it +created an inconsistency in Autoconf without giving significant +benefits. This wart will be removed in a future release of Autoconf. + +@node VPATH Substitutions, Automatic Remaking, Installation Prefixes, Makefiles +@section @code{VPATH} Substitutions + +You might want to compile a software package in a different directory +from the one that contains the source code. Doing this allows you to +compile the package for several architectures simultaneously from the +same copy of the source code and keep multiple sets of object files on +disk. + +To support doing this, @code{make} uses the @code{VPATH} variable to +find the files that are in the source directory. GNU @code{make} and +most other recent @code{make} programs can do this. Older @code{make} +programs do not support @code{VPATH}; when using them, the source code +must be in the same directory as the object files. + +To support @code{VPATH}, each @file{Makefile.in} should contain two +lines that look like: + +@example +srcdir = @@srcdir@@ +VPATH = @@srcdir@@ +@end example + +Do not set @code{VPATH} to the value of another variable, for example +@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do +variable substitutions on the value of @code{VPATH}. + +@code{configure} substitutes in the correct value for @code{srcdir} when +it produces @file{Makefile.in}. + +Do not use the @code{make} variable @code{$<}, which expands to the +pathname of the file in the source directory (found with @code{VPATH}), +except in implicit rules. (An implicit rule is one such as @samp{.c.o}, +which tells how to create a @file{.o} file from a @file{.c} file.) Some +versions of @code{make} do not set @code{$<} in explicit rules; they +expand it to an empty value. + +Instead, @file{Makefile} command lines should always refer to source +files by prefixing them with @samp{$(srcdir)/}. For example: + +@example +time.info: time.texinfo + $(MAKEINFO) $(srcdir)/time.texinfo +@end example + +@node Automatic Remaking, , VPATH Substitutions, Makefiles +@section Automatic Remaking + +You can put rules like the following in the top-level @file{Makefile.in} +for a package to automatically update the configuration information when +you change the configuration files. This example includes all of the +optional files, such as @file{aclocal.m4} and those related to +configuration header files. Omit from the @file{Makefile.in} rules any +of these files that your package does not use. + +The @file{stamp-} files are necessary because the timestamps of +@file{config.h.in} and @file{config.h} will not be changed if remaking +them does not change their contents. This feature avoids unnecessary +recompilation. You should include the file @file{stamp-h.in} your +package's distribution, so @code{make} will consider @file{config.h.in} +up to date. + +@example +@group +configure: configure.in aclocal.m4 + cd $@{srcdir@} && autoconf + +# autoheader might not change config.h.in +config.h.in: stamp-h.in +stamp-h.in: configure.in aclocal.m4 acconfig.h config.h.top + cd $@{srcdir@} && autoheader + touch $@{srcdir@}/stamp-h.in + +# config.status might not change config.h +config.h: stamp-h +stamp-h: config.h.in config.status + ./config.status + touch stamp-h + +Makefile: Makefile.in config.status + ./config.status + +config.status: configure + ./config.status --recheck +@end group +@end example + +@xref{Invoking config.status}, for more information on handling +configuration-related dependencies. + +@node Invoking configure, Example, Makefiles, Top +@chapter Running @code{configure} Scripts + +A software package that uses a @code{configure} script +should be distributed with a file @file{Makefile.in}, but no +@file{Makefile}; that way, the user has to properly configure the +package for the local system before compiling it. +Here is how to configure a package that uses a @code{configure} script. + +Normally, you just @code{cd} to the directory containing the package's +source code and type @samp{./configure}. If you're using @code{csh} on +an old version of System V, you might need to type @samp{sh configure} +instead to prevent @code{csh} from trying to execute @code{configure} +itself. + +Running @code{configure} takes awhile. While it is running, it +prints some messages that tell what it is doing. If you don't want to +see any messages, run @code{configure} with its standard output +redirected to @file{/dev/null}; for example, @samp{./configure >/dev/null}. + +To compile the package in a different directory from the one containing +the source code, you must use a version of @code{make} that supports the +@code{VPATH} variable, such as GNU @code{make}. @code{cd} to the +directory where you want the object files and executables to go and run +the @code{configure} script. @code{configure} automatically checks for +the source code in the directory that @code{configure} is in and in +@file{..}. If for some reason @code{configure} is not in the source +code directory that you are configuring, then it will report that it +can't find the source code. In that case, run @code{configure} with the +option @samp{--srcdir=@var{dir}}, where @var{dir} is the directory that +contains the source code. + +By default, @samp{make install} will install the package's files in +@file{/usr/local/bin}, @file{/usr/local/man}, etc. You can specify an +installation prefix other than @file{/usr/local} by giving +@code{configure} the option @samp{--prefix=@var{path}}. Alternately, +you can do so by consistently giving a value for the @samp{prefix} +variable when you run @code{make}, e.g., +@example +make prefix=/usr/gnu +make prefix=/usr/gnu install +@end example + +You can specify separate installation prefixes for architecture-specific +files and architecture-independent files. If you give @code{configure} +the option @samp{--exec-prefix=@var{path}} or set the @code{make} +variable @samp{exec_prefix} to @var{path}, the package will use +@var{path} as the prefix for installing programs and libraries. Data +files and documentation will still use the regular prefix. Normally, +all files are installed using the same prefix. + +Some packages pay attention to @samp{--with-@var{package}} options to +@code{configure}, where @var{package} is something like @samp{gnu-as} or +@samp{x} (for the X Window System). They may also pay attention to +@samp{--enable-@var{feature}} options, where @var{feature} indicates an +optional part of the package. The README should mention any +@samp{--with-} and @samp{--enable-} options that the package recognizes. + +@code{configure} also recognizes the following options: + +@table @code +@item --help +Print a summary of the options to @code{configure}, and exit. + +@itemx --quiet +@item --silent +Do not print messages saying which checks are being made. + +@item --verbose +Print the results of the checks. + +@item --version +Print the version of Autoconf used to generate the @code{configure} +script, and exit. + +@item --x-includes=@var{dir} +X include files are in @var{dir}. + +@item --x-libraries=@var{dir} +X library files are in @var{dir}. +@end table + +@code{configure} also accepts and ignores some other options. + +@menu +* Overriding variables:: Workarounds for unusual systems. +* Invoking config.status:: Recreating a configuration. +@end menu + +@node Overriding variables, Invoking config.status, , Invoking configure +@section Overriding variables + +On systems that require unusual options for compilation or linking that +the package's @code{configure} script does not know about, you can give +@code{configure} initial values for variables by setting them in the +environment. In Bourne-compatible shells, you can do that on the +command line like this: + +@example +CC='gcc -traditional' LIBS=-lposix ./configure +@end example + +@noindent +On systems that have the @code{env} program, you can do it like this: + +@example +env CC='gcc -traditional' LIBS=-lposix ./configure +@end example + +Here are the @code{make} variables that you might want to override with +environment variables when running @code{configure}. + +For these variables, any value given in the environment overrides the +value that @code{configure} would choose: + +@defvar CC +C compiler program. The default is @code{cc}. +@end defvar + +@defvar INSTALL +Program to use to install files. The default is @code{install} if you +have it, @code{cp} otherwise. +@end defvar + +For these variables, any value given in the environment is added to +the value that @code{configure} chooses: + +@defvar DEFS +Configuration options, in the form @samp{-Dfoo -Dbar@dots{}}. Do not +use this variable in packages that create a configuration header file. +@end defvar + +@defvar LIBS +Libraries to link with, in the form @samp{-lfoo -lbar@dots{}}. +@end defvar + +In the long term, most problems requiring manual intervention should be +fixed by updating either the Autoconf macros or the @file{configure.in} +file for that package. @xref{Making configure Scripts}, for a +discussion of that subject. + +@node Invoking config.status, , Overriding variables, Invoking configure +@section Recreating a Configuration + +The @code{configure} script creates a file named @file{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 @file{config.status} the @samp{--recheck} option to update +itself. This option is useful if you change @code{configure}, so that +the results of some tests might be different from the previous run. The +@samp{--recheck} option re-runs @code{configure} with the same arguments +you used before, plus the @samp{--no-create} option, which prevents +@code{configure} from running @file{config.status} and creating +@file{Makefile} and other files. (This is so other @file{Makefile} +rules can run @file{config.status} when it changes; @pxref{Automatic +Remaking}, for an example). + +@file{config.status} also accepts the options @samp{--help}, which +prints a summary of the options to @file{config.status}, and +@samp{--version}, which prints the version of Autoconf used to create +the @code{configure} script that generated @file{config.status}. + +@file{config.status} checks several optional environment variables that +can alter its behavior: + +@defvar CONFIG_SHELL +The shell with which to run @code{configure} for the @samp{--recheck} +option. The default is @file{/bin/sh}. +@end defvar + +The following two variables provide one way for separately distributed +packages to share the values computed by @code{configure}. Doing so can +be useful if some of the packages need a superset of the features that +one of them, perhaps a common library, does. These variables allow a +@file{config.status} file to create files other than the ones that its +@file{configure.in} specifies, so it can be used for a different package. + +@defvar CONFIG_FILES +The files in which to perform @samp{@@@var{variable}@@} substitutions. +The default is the arguments given to @code{AC_OUTPUT} in @file{configure.in}. +@end defvar + +@defvar CONFIG_HEADERS +The files in which to substitute C @code{#define} statements. +The default is the arguments given to @code{AC_CONFIG_HEADER}; if that +macro was not called, @file{config.status} ignores this variable. +@end defvar + +These variables also allow you to write @file{Makefile} rules that +regenerate only some of the files. For example, in the dependencies +given above (@pxref{Automatic Remaking}), @file{config.status} is run +twice when @file{configure.in} has changed. If that bothers you, you +can make each run only regenerate the files for that rule: + +@example +@group +# config.status might not change config.h +config.h: stamp-h +stamp-h: config.h.in config.status + CONFIG_FILES= CONFIG_HEADERS=config.h ./config.status + touch stamp-h + +Makefile: Makefile.in config.status + CONFIG_FILES=Makefile CONFIG_HEADERS= ./config.status +@end group +@end example + +@noindent +(If @file{configure.in} does not call @code{AC_CONFIG_HEADER}, there is +no need to set @code{CONFIG_HEADERS} in the @code{make} rules.) + +@node Example, Preprocessor Symbol Index, Invoking configure, Top +@chapter An Example + +Here are sample @file{configure.in} and @file{Makefile.in} files, to +give a real illustration of using Autoconf. They are from the GNU +@code{cpio} package, which also includes the @code{mt} and @code{rmt} +programs. This package does not use a configuration header file; it +passes @samp{-D} options to the C compiler on the command line. + +@menu +* Sample configure.in:: An example of a @file{configure} template. +* Sample Makefile.in:: An example of a @file{Makefile} template. +@end menu + +@node Sample configure.in, Sample Makefile.in, , Example +@section Sample @file{configure.in} + +@noindent +Here is @file{configure.in} from GNU @code{cpio}. The @code{dnl} macro +after @code{AC_SUBST} is suppresses an extra (though harmless) newline +in the generated @code{configure} script (because the @code{AC_SUBST} +macro does not produce any output where it is called). + +@example +dnl Process this file with autoconf to produce a configure script. +AC_INIT(cpio.h) +PROGS="cpio" +AC_SUBST(PROGS)dnl +AC_PROG_CC +AC_PROG_CPP +AC_GCC_TRADITIONAL +AC_PROG_INSTALL +AC_AIX +AC_MINIX +AC_ISC_POSIX +AC_RETSIGTYPE +AC_MAJOR_HEADER +AC_REMOTE_TAPE +test -n "$have_mtio" && PROGS="$PROGS mt" +AC_RSH +AC_CONST +AC_UID_T +AC_STDC_HEADERS +AC_HAVE_HEADERS(string.h fcntl.h utime.h unistd.h sys/io/trioctl.h) +AC_REPLACE_FUNCS(fnmatch bcopy mkdir strdup) +AC_HAVE_FUNCS(strerror lchown) +AC_VPRINTF +AC_ALLOCA +AC_XENIX_DIR +AC_HAVE_LIBRARY(socket, [LIBS="$LIBS -lsocket"]) +AC_HAVE_LIBRARY(nsl, [LIBS="$LIBS -lnsl"]) +AC_OUTPUT(Makefile) +@end example + +@node Sample Makefile.in, , Sample configure.in, Example +@section Sample @file{Makefile.in} + +@noindent +Here is @file{Makefile.in} from GNU @code{cpio}, with some irrelevant +lines omitted, for brevity. + +@example +srcdir = @@srcdir@@ +VPATH = @@srcdir@@ + +CC = @@CC@@ + +INSTALL = @@INSTALL@@ +INSTALL_PROGRAM = @@INSTALL_PROGRAM@@ +INSTALL_DATA = @@INSTALL_DATA@@ + +DEFS = @@DEFS@@ +LIBS = @@LIBS@@ +RTAPELIB = @@RTAPELIB@@ + +CFLAGS = -g +LDFLAGS = -g + +prefix = /usr/local +exec_prefix = $(prefix) +binprefix = +manprefix = + +bindir = $(exec_prefix)/bin +libdir = $(exec_prefix)/lib +mandir = $(prefix)/man/man1 +manext = 1 + +SHELL = /bin/sh + +SRCS = copyin.c copyout.c copypass.c defer.c dstring.c global.c \ +main.c tar.c util.c error.c getopt.c getopt1.c filemode.c version.c \ +rtapelib.c dirname.c idcache.c makepath.c xmalloc.c stripslash.c \ +userspec.c xstrdup.c bcopy.c fnmatch.c mkdir.c strdup.c +OBJS = copyin.o copyout.o copypass.o defer.o dstring.o global.o \ +main.o tar.o util.o error.o getopt.o getopt1.o filemode.o version.o \ +$(RTAPELIB) dirname.o idcache.o makepath.o xmalloc.o stripslash.o \ +userspec.o xstrdup.o @@LIBOBJS@@ @@ALLOCA@@ +# mt source files not shared with cpio. +MT_SRCS = mt.c argmatch.c +MT_OBJS = mt.o argmatch.o error.o getopt.o getopt1.o \ +xmalloc.o version.o $(RTAPELIB) @@ALLOCA@@ +HDRS = cpio.h cpiohdr.h tar.h tarhdr.h defer.h dstring.h extern.h filetypes.h \ +system.h fnmatch.h getopt.h rmt.h +DISTFILES = $(SRCS) $(HDRS) COPYING COPYING.LIB ChangeLog Makefile.in \ +README NEWS INSTALL cpio.1 mt.1 makefile.pc makefile.os2 cpio.def \ +configure configure.in mkinstalldirs $(MT_SRCS) rmt.c tcexparg.c alloca.c + +all: @@PROGS@@ + +.c.o: + $(CC) -c $(CPPFLAGS) $(DEFS) -I$(srcdir) $(CFLAGS) $< + +install: installdirs all $(srcdir)/cpio.1 $(srcdir)/mt.1 + $(INSTALL_PROGRAM) cpio $(bindir)/$(binprefix)cpio + test ! -f mt || $(INSTALL_PROGRAM) mt $(bindir)/$(binprefix)mt + -test ! -f rmt || $(INSTALL_PROGRAM) rmt $(libdir)/rmt + $(INSTALL_DATA) $(srcdir)/cpio.1 $(mandir)/$(manprefix)cpio.$(manext) + test ! -f mt || \ + $(INSTALL_DATA) $(srcdir)/mt.1 $(mandir)/$(manprefix)mt.$(manext) + +installdirs: + $(srcdir)/mkinstalldirs $(bindir) $(libdir) $(mandir) + +uninstall: + cd $(bindir); rm -f $(binprefix)cpio $(binprefix)mt + -rm -f $(libdir)/rmt + cd $(mandir); rm -f $(manprefix)cpio.$(manext) $(manprefix)mt.$(manext) + +check: + @@echo No tests are supplied. + +cpio: $(OBJS) + $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS) + +rmt: rmt.o + $(CC) $(LDFLAGS) -o $@@ rmt.o $(LIBS) + +mt: $(MT_OBJS) + $(CC) $(LDFLAGS) -o $@@ $(MT_OBJS) $(LIBS) + +Makefile: Makefile.in config.status + $(SHELL) config.status +config.status: configure + $(SHELL) config.status --recheck +configure: configure.in + cd $(srcdir); autoconf + +TAGS: $(SRCS) + etags $(SRCS) + +clean: + rm -f cpio rmt mt *.o core + +mostlyclean: clean + +distclean: clean + rm -f Makefile config.status + +realclean: distclean + rm -f TAGS + +dist: $(DISTFILES) + echo cpio-`sed -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname + rm -rf `cat .fname` + mkdir `cat .fname` + -ln $(DISTFILES) `cat .fname` + for file in $(DISTFILES); do \ + test -r `cat .fname`/$$file || cp -p $$file `cat .fname`; \ + done + tar chzf `cat .fname`.tar.gz `cat .fname` + rm -rf `cat .fname` .fname +@end example + +@node Preprocessor Symbol Index, Macro Index, Example, Top +@unnumbered Preprocessor Symbol Index + +This is an alphabetical list of the C preprocessor symbols that the +Autoconf macros define. To work with Autoconf, C source code needs to +use these names in @code{#if} directives. + +@printindex vr + +@node Macro Index, , Preprocessor Symbol Index, Top +@unnumbered Macro Index + +This is an alphabetical list of the Autoconf macros. To make the list +easier to use, the macros are listed without their preceding @samp{AC_}. + +@printindex ma + +@contents +@bye + +@c Local variables: +@c compile-command: "makeinfo --no-split autoconf.texi" +@c End: diff --git a/src/util/autoconf/autoheader b/src/util/autoconf/autoheader new file mode 100644 index 000000000..b49a0ee81 --- /dev/null +++ b/src/util/autoconf/autoheader @@ -0,0 +1,235 @@ +#!/bin/sh +# autoheader -- create `config.h.in' from `configure.in' +# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +# Written by Roland McGrath. + +# If given no args, create `config.h.in' from template file `configure.in'. +# With one arg, create a header file on standard output from +# the given template file. + +usage="Usage: autoheader [-h] [--help] [-m dir] [--macrodir=dir] + [-v] [--version] [template-file]" + +# NLS nuisances. +# These must not be set unconditionally because not all systems understand +# e.g. LANG=C (notably SCO). +if test "${LC_ALL+set}" = 'set' ; then LC_ALL=C; export LC_ALL; fi +if test "${LANG+set}" = 'set' ; then LANG=C; export LANG; fi + +test -z "${AC_MACRODIR}" && AC_MACRODIR=/usr/latest/lib/autoconf +test -z "${M4}" && M4=/usr/latest/bin/m4 +case "${M4}" in +/*) # Handle the case that m4 has moved since we were configured. + # It may have been found originally in a build directory. + test -f "${M4}" || M4=m4 ;; +esac + +print_version="" +while test $# -gt 0 ; do + case "z${1}" in + z-h | z--help | z--h* ) + echo "${usage}"; exit 0 ;; + z--macrodir=* | z--m*=* ) + AC_MACRODIR="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" + shift ;; + z-m | z--macrodir | z--m* ) + shift + test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } + AC_MACRODIR="${1}" + shift ;; + z-v | z--version | z--v* ) + print_version="-DAC_PRINT_VERSION" + shift ;; + z-- ) # Stop option processing + shift; break ;; + z- ) # Use stdin as input. + break ;; + z-* ) + echo "${usage}" 1>&2; exit 1 ;; + * ) + break ;; + esac +done + +TEMPLATES="${AC_MACRODIR}/acconfig.h" +test -r acconfig.h && TEMPLATES="${TEMPLATES} acconfig.h" +MACROFILES="${AC_MACRODIR}/acgeneral.m4 ${AC_MACRODIR}/acspecific.m4" +test -r ${AC_MACRODIR}/aclocal.m4 \ + && MACROFILES="${MACROFILES} ${AC_MACRODIR}/aclocal.m4" +test -r aclocal.m4 && MACROFILES="${MACROFILES} aclocal.m4" +MACROFILES="${print_version} ${MACROFILES}" + +case $# in + 0) if test -n "$print_version" + then infile=/dev/null + else infile=configure.in; fi ;; + 1) infile=$1 ;; + *) echo "$usage" >&2; exit 1 ;; +esac + +# These are the alternate definitions of the acgeneral.m4 macros we want to +# redefine. They produce strings in the output marked with "@@@" so we can +# easily extract the information we want. The `#' at the end of the first +# line of each definition seems to be necessary to prevent m4 from eating +# the newline, which makes the @@@ not always be at the beginning of a line. +frob='define([AC_DEFINE],[# +@@@syms="$syms $1"@@@ +])dnl +define([AC_SIZEOF_TYPE],[# +@@@types="$types,$1"@@@ +])dnl +define([AC_HAVE_FUNCS],[# +@@@funcs="$funcs $1"@@@ +])dnl +define([AC_HAVE_HEADERS],[# +@@@headers="$headers $1"@@@ +])dnl +define([AC_CONFIG_HEADER],[# +@@@config_h=$1@@@ +])dnl +define([AC_HAVE_LIBRARY], [# +changequote(/,/)dnl +define(/libname/, dnl +patsubst(patsubst($1, /lib\([^\.]*\)\.a/, /\1/), /-l/, //))dnl +changequote([,])dnl +@@@libs="$libs libname"@@@ +# If it was found, we do: +$2 +# If it was not found, we do: +$3 +])dnl +' + +config_h=config.h +syms= +types= +funcs= +headers= +libs= + +# We extract assignments of SYMS, TYPES, FUNCS, HEADERS, and LIBS from the +# modified autoconf processing of the input file. The sed hair is +# necessary to win for multi-line macro invocations. +eval "`echo \"$frob\" \ + | $M4 $MACROFILES - $infile \ + | sed -n -e ' + : again + /^@@@.*@@@$/s/^@@@\(.*\)@@@$/\1/p + /^@@@/{ + s/^@@@//p + n + s/^/@@@/ + b again + }'`" + +test -n "$print_version" && exit 0 + +# Make SYMS newline-separated rather than blank-separated, and remove dups. +syms="`for sym in $syms; do echo $sym; done | sort | uniq`" + +if test $# -eq 0; then + tmpout=autoh$$ + trap "rm -f $tmpout; exit 1" 1 2 15 + exec > $tmpout +fi + +# Don't write "do not edit" -- it will get copied into the +# config.h, which it's ok to edit. +echo "/* ${config_h}.in. Generated automatically from $infile by autoheader. */" + +test -f ${config_h}.top && cat ${config_h}.top + +# This puts each paragraph on its own line, separated by @s. +if test -n "$syms"; then + # Make sure the boundary of template files is also the boundary + # of the paragraph. Extra newlines don't hurt since they will + # be removed. + for t in $TEMPLATES; do cat $t; echo; echo; done | + # The sed script is suboptimal because it has to take care of + # some broken seds (e.g. AIX) that remove '\n' from the + # pattern/hold space if the line is empty. (junio@twinsun.com). + sed -n -e ' + /^[ ]*$/{ + x + s/\n/@/g + p + s/.*/@/ + x + } + H' | sed -e 's/@@*/@/g' | + # Select each paragraph that refers to a symbol we picked out above. + fgrep "$syms" | + tr @ \\012 +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'`" + echo " +/* The number of bytes in a ${ctype}. */ +#undef SIZEOF_${sym}" +done + +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]'`" + echo " +/* Define if you have ${func}. */ +#undef HAVE_${sym}" +done + +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]'`" + echo " +/* Define if you have the <${header}> header file. */ +#undef HAVE_${sym}" +done + +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]'`" + echo " +/* Define if you have the ${lib} library (-l${lib}). */ +#undef HAVE_LIB${sym}" +done + +test -f ${config_h}.bot && cat ${config_h}.bot + +status=0 + +for sym in $syms; do + if fgrep $sym $TEMPLATES >/dev/null; then + : # All is well. + else + echo "$0: Symbol \`${sym}' is not covered by $TEMPLATES" >&2 + status=1 + fi +done + +if test $# -eq 0; then + if test $status -eq 0; then + if cmp -s $tmpout ${config_h}.in; then + rm -f $tmpout + else + mv -f $tmpout ${config_h}.in + fi + else + rm -f $tmpout + fi +fi + +exit $status diff --git a/src/util/autoconf/autoheader.sh b/src/util/autoconf/autoheader.sh new file mode 100644 index 000000000..ccba6beb1 --- /dev/null +++ b/src/util/autoconf/autoheader.sh @@ -0,0 +1,235 @@ +#!/bin/sh +# autoheader -- create `config.h.in' from `configure.in' +# Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +# Written by Roland McGrath. + +# If given no args, create `config.h.in' from template file `configure.in'. +# With one arg, create a header file on standard output from +# the given template file. + +usage="Usage: autoheader [-h] [--help] [-m dir] [--macrodir=dir] + [-v] [--version] [template-file]" + +# NLS nuisances. +# These must not be set unconditionally because not all systems understand +# e.g. LANG=C (notably SCO). +if test "${LC_ALL+set}" = 'set' ; then LC_ALL=C; export LC_ALL; fi +if test "${LANG+set}" = 'set' ; then LANG=C; export LANG; fi + +test -z "${AC_MACRODIR}" && AC_MACRODIR=@datadir@ +test -z "${M4}" && M4=@M4@ +case "${M4}" in +/*) # Handle the case that m4 has moved since we were configured. + # It may have been found originally in a build directory. + test -f "${M4}" || M4=m4 ;; +esac + +print_version="" +while test $# -gt 0 ; do + case "z${1}" in + z-h | z--help | z--h* ) + echo "${usage}"; exit 0 ;; + z--macrodir=* | z--m*=* ) + AC_MACRODIR="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" + shift ;; + z-m | z--macrodir | z--m* ) + shift + test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } + AC_MACRODIR="${1}" + shift ;; + z-v | z--version | z--v* ) + print_version="-DAC_PRINT_VERSION" + shift ;; + z-- ) # Stop option processing + shift; break ;; + z- ) # Use stdin as input. + break ;; + z-* ) + echo "${usage}" 1>&2; exit 1 ;; + * ) + break ;; + esac +done + +TEMPLATES="${AC_MACRODIR}/acconfig.h" +test -r acconfig.h && TEMPLATES="${TEMPLATES} acconfig.h" +MACROFILES="${AC_MACRODIR}/acgeneral.m4 ${AC_MACRODIR}/acspecific.m4" +test -r ${AC_MACRODIR}/aclocal.m4 \ + && MACROFILES="${MACROFILES} ${AC_MACRODIR}/aclocal.m4" +test -r aclocal.m4 && MACROFILES="${MACROFILES} aclocal.m4" +MACROFILES="${print_version} ${MACROFILES}" + +case $# in + 0) if test -n "$print_version" + then infile=/dev/null + else infile=configure.in; fi ;; + 1) infile=$1 ;; + *) echo "$usage" >&2; exit 1 ;; +esac + +# These are the alternate definitions of the acgeneral.m4 macros we want to +# redefine. They produce strings in the output marked with "@@@" so we can +# easily extract the information we want. The `#' at the end of the first +# line of each definition seems to be necessary to prevent m4 from eating +# the newline, which makes the @@@ not always be at the beginning of a line. +frob='define([AC_DEFINE],[# +@@@syms="$syms $1"@@@ +])dnl +define([AC_SIZEOF_TYPE],[# +@@@types="$types,$1"@@@ +])dnl +define([AC_HAVE_FUNCS],[# +@@@funcs="$funcs $1"@@@ +])dnl +define([AC_HAVE_HEADERS],[# +@@@headers="$headers $1"@@@ +])dnl +define([AC_CONFIG_HEADER],[# +@@@config_h=$1@@@ +])dnl +define([AC_HAVE_LIBRARY], [# +changequote(/,/)dnl +define(/libname/, dnl +patsubst(patsubst($1, /lib\([^\.]*\)\.a/, /\1/), /-l/, //))dnl +changequote([,])dnl +@@@libs="$libs libname"@@@ +# If it was found, we do: +$2 +# If it was not found, we do: +$3 +])dnl +' + +config_h=config.h +syms= +types= +funcs= +headers= +libs= + +# We extract assignments of SYMS, TYPES, FUNCS, HEADERS, and LIBS from the +# modified autoconf processing of the input file. The sed hair is +# necessary to win for multi-line macro invocations. +eval "`echo \"$frob\" \ + | $M4 $MACROFILES - $infile \ + | sed -n -e ' + : again + /^@@@.*@@@$/s/^@@@\(.*\)@@@$/\1/p + /^@@@/{ + s/^@@@//p + n + s/^/@@@/ + b again + }'`" + +test -n "$print_version" && exit 0 + +# Make SYMS newline-separated rather than blank-separated, and remove dups. +syms="`for sym in $syms; do echo $sym; done | sort | uniq`" + +if test $# -eq 0; then + tmpout=autoh$$ + trap "rm -f $tmpout; exit 1" 1 2 15 + exec > $tmpout +fi + +# Don't write "do not edit" -- it will get copied into the +# config.h, which it's ok to edit. +echo "/* ${config_h}.in. Generated automatically from $infile by autoheader. */" + +test -f ${config_h}.top && cat ${config_h}.top + +# This puts each paragraph on its own line, separated by @s. +if test -n "$syms"; then + # Make sure the boundary of template files is also the boundary + # of the paragraph. Extra newlines don't hurt since they will + # be removed. + for t in $TEMPLATES; do cat $t; echo; echo; done | + # The sed script is suboptimal because it has to take care of + # some broken seds (e.g. AIX) that remove '\n' from the + # pattern/hold space if the line is empty. (junio@twinsun.com). + sed -n -e ' + /^[ ]*$/{ + x + s/\n/@/g + p + s/.*/@/ + x + } + H' | sed -e 's/@@*/@/g' | + # Select each paragraph that refers to a symbol we picked out above. + fgrep "$syms" | + tr @ \\012 +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'`" + echo " +/* The number of bytes in a ${ctype}. */ +#undef SIZEOF_${sym}" +done + +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]'`" + echo " +/* Define if you have ${func}. */ +#undef HAVE_${sym}" +done + +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]'`" + echo " +/* Define if you have the <${header}> header file. */ +#undef HAVE_${sym}" +done + +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]'`" + echo " +/* Define if you have the ${lib} library (-l${lib}). */ +#undef HAVE_LIB${sym}" +done + +test -f ${config_h}.bot && cat ${config_h}.bot + +status=0 + +for sym in $syms; do + if fgrep $sym $TEMPLATES >/dev/null; then + : # All is well. + else + echo "$0: Symbol \`${sym}' is not covered by $TEMPLATES" >&2 + status=1 + fi +done + +if test $# -eq 0; then + if test $status -eq 0; then + if cmp -s $tmpout ${config_h}.in; then + rm -f $tmpout + else + mv -f $tmpout ${config_h}.in + fi + else + rm -f $tmpout + fi +fi + +exit $status diff --git a/src/util/autoconf/config.status b/src/util/autoconf/config.status new file mode 100644 index 000000000..736384ce8 --- /dev/null +++ b/src/util/autoconf/config.status @@ -0,0 +1,91 @@ +#!/bin/sh +# Generated automatically by configure. +# Run this file to recreate the current configuration. +# This directory was configured as follows, +# on host tweedledumber.cygnus.com: +# +# ./configure -prefix /usr/latest + +ac_cs_usage="Usage: config.status [--recheck] [--version] [--help]" +for ac_option +do + case "$ac_option" in + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + echo running ${CONFIG_SHELL-/bin/sh} ./configure -prefix /usr/latest --no-create + exec ${CONFIG_SHELL-/bin/sh} ./configure -prefix /usr/latest --no-create ;; + -version | --version | --versio | --versi | --vers | --ver | --ve | --v) + echo "config.status generated by autoconf version 1.11" + exit 0 ;; + -help | --help | --hel | --he | --h) + echo "$ac_cs_usage"; exit 0 ;; + *) echo "$ac_cs_usage"; exit 1 ;; + esac +done + +trap 'rm -f Makefile; exit 1' 1 2 15 +M4='/usr/latest/bin/m4' +INSTALL='/usr/latest/bin/install -c' +INSTALL_PROGRAM='${INSTALL}' +INSTALL_DATA='${INSTALL} -m 644' +LIBS='' +srcdir='.' +top_srcdir='' +prefix='/usr/latest' +exec_prefix='${prefix}' +DEFS='' +ac_prsub='s%^prefix\([ ]*\)=\([ ]*\).*$%prefix\1=\2/usr/latest%' +ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' +extrasub='' + +ac_given_srcdir=$srcdir + +CONFIG_FILES=${CONFIG_FILES-"Makefile"} +for ac_file in .. ${CONFIG_FILES}; do if test "x$ac_file" != x..; then + # Remove last slash and all that follows it. Not all systems have dirname. + ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` + if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then + # The file is in a subdirectory. + test ! -d "$ac_dir" && mkdir "$ac_dir" + ac_dir_suffix="/$ac_dir" + else + ac_dir_suffix= + fi + + # A "../" for each directory in $ac_dir_suffix. + ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` + case "$ac_given_srcdir" in + .) srcdir=. + if test -z "$ac_dir_suffix"; then top_srcdir=. + else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; + /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; + *) # Relative path. + srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" + top_srcdir="$ac_dots$ac_given_srcdir" ;; + esac + + echo creating "$ac_file" + rm -f "$ac_file" + comment_str="Generated automatically from `echo $ac_file|sed 's|.*/||'`.in by configure." + case "$ac_file" in + *.c | *.h | *.C | *.cc | *.m ) echo "/* $comment_str */" > "$ac_file" ;; + * ) echo "# $comment_str" > "$ac_file" ;; + esac + sed -e " +$ac_prsub +$ac_vpsub +$extrasub +s%@M4@%$M4%g +s%@INSTALL@%$INSTALL%g +s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g +s%@INSTALL_DATA@%$INSTALL_DATA%g +s%@LIBS@%$LIBS%g +s%@srcdir@%$srcdir%g +s%@top_srcdir@%$top_srcdir%g +s%@prefix@%$prefix%g +s%@exec_prefix@%$exec_prefix%g +s%@DEFS@%$DEFS% +" $ac_given_srcdir/${ac_file}.in >> $ac_file +fi; done + + +exit 0 diff --git a/src/util/autoconf/configure b/src/util/autoconf/configure new file mode 100644 index 000000000..943429b91 --- /dev/null +++ b/src/util/autoconf/configure @@ -0,0 +1,536 @@ +#!/bin/sh +# Guess values for system-dependent variables and create Makefiles. +# Generated automatically using autoconf version 1.11 +# Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc. + +# This configure script is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License as published +# by the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This script is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General +# Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +# Save the original args to write them into config.status later. +configure_args="$*" + +# Only options that might do something get documented. +ac_usage="Usage: configure [options] [host] +Options: [defaults in brackets after descriptions] +--build=BUILD configure for building on BUILD [BUILD=HOST] +--disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) +--enable-FEATURE[=ARG] include FEATURE [ARG=yes] +--exec-prefix=PREFIX install host dependent files in PREFIX [/usr/local] +--help print this message +--host=HOST configure for HOST [guessed] +--prefix=PREFIX install host independent files in PREFIX [/usr/local] +--quiet, --silent do not print \`checking for...' messages +--srcdir=DIR find the sources in DIR [configure dir or ..] +--target=TARGET configure for TARGET [TARGET=HOST] +--verbose print results of checks +--version print the version of autoconf that created configure +--with-PACKAGE[=ARG] use PACKAGE [ARG=yes] +--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" + +# Initialize some variables set by options. +# The variables have the same names as the options, with +# dashes changed to underlines. +build=NONE +exec_prefix= +host=NONE +no_create= +nonopt=NONE +norecursion= +prefix= +program_prefix= +program_suffix= +program_transform_name= +silent= +srcdir= +target=NONE +verbose= +x_includes= +x_libraries= + +ac_prev= +for ac_option +do + + # If the previous option needs an argument, assign it. + if test -n "$ac_prev"; then + eval "$ac_prev=\$ac_option" + ac_prev= + continue + fi + + # Accept (but ignore some of) the important Cygnus configure + # options, so we can diagnose typos. + + case "$ac_option" in + -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; + *) ac_optarg= ;; + esac + + case "$ac_option" in + + -build | --build | --buil | --bui | --bu | --b) + ac_prev=build ;; + -build=* | --build=* | --buil=* | --bui=* | --bu=* | --b=*) + build="$ac_optarg" ;; + + -disable-* | --disable-*) + ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` + # Reject names that aren't valid shell variable names. + if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then + echo "configure: $ac_feature: invalid feature name" >&2; exit 1 + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + eval "enable_${ac_feature}=no" ;; + + -enable-* | --enable-*) + ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` + # Reject names that aren't valid shell variable names. + if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then + echo "configure: $ac_feature: invalid feature name" >&2; exit 1 + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "enable_${ac_feature}='$ac_optarg'" ;; + + # For backward compatibility, recognize -exec-prefix and --exec_prefix. + -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ + | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ + | --exec | --exe | --ex) + ac_prev=exec_prefix ;; + -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ + | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ + | --exec=* | --exe=* | --ex=*) + exec_prefix="$ac_optarg" ;; + + -gas | --gas | --ga | --g) + with_gas=yes ;; # Obsolete; use --with-gas. + + -help | --help | --hel | --he) + cat << EOF +$ac_usage +EOF + exit 0 ;; + + -host | --host | --hos | --ho) + ac_prev=host ;; + -host=* | --host=* | --hos=* | --ho=*) + host="$ac_optarg" ;; + + -nfp | --nfp | --nf) + with_fp=no ;; # Obsolete; use --without-fp. + + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) + no_create=yes ;; + + -norecursion | --norecursion | --norecursio | --norecursi \ + | --norecurs | --norecur | --norecu | --norec | --nore | --nor) + norecursion=yes ;; + + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) + ac_prev=prefix ;; + -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) + prefix="$ac_optarg" ;; + + -program-prefix | --program-prefix | --program-prefi | --program-pref \ + | --program-pre | --program-pr | --program-p) + ac_prev=program_prefix ;; + -program-prefix=* | --program-prefix=* | --program-prefi=* \ + | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) + program_prefix="$ac_optarg" ;; + + -program-suffix | --program-suffix | --program-suffi | --program-suff \ + | --program-suf | --program-su | --program-s) + ac_prev=program_suffix ;; + -program-suffix=* | --program-suffix=* | --program-suffi=* \ + | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) + program_suffix="$ac_optarg" ;; + + -program-transform-name | --program-transform-name \ + | --program-transform-nam | --program-transform-na \ + | --program-transform-n | --program-transform- \ + | --program-transform | --program-transfor \ + | --program-transfo | --program-transf \ + | --program-trans | --program-tran \ + | --progr-tra | --program-tr | --program-t) + ac_prev=program_transform_name ;; + -program-transform-name=* | --program-transform-name=* \ + | --program-transform-nam=* | --program-transform-na=* \ + | --program-transform-n=* | --program-transform-=* \ + | --program-transform=* | --program-transfor=* \ + | --program-transfo=* | --program-transf=* \ + | --program-trans=* | --program-tran=* \ + | --progr-tra=* | --program-tr=* | --program-t=*) + program_transform_name="$ac_optarg" ;; + + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + silent=yes ;; + + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) + ac_prev=srcdir ;; + -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) + srcdir="$ac_optarg" ;; + + -target | --target | --targe | --targ | --tar | --ta | --t) + ac_prev=target ;; + -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) + target="$ac_optarg" ;; + + -v | -verbose | --verbose | --verbos | --verbo | --verb) + verbose=yes ;; + + -version | --version | --versio | --versi | --vers) + echo "configure generated by autoconf version 1.11" + exit 0 ;; + + -with-* | --with-*) + ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` + # Reject names that aren't valid shell variable names. + if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then + echo "configure: $ac_package: invalid package name" >&2; exit 1 + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "with_${ac_package}='$ac_optarg'" ;; + + -without-* | --without-*) + ac_package=`echo $ac_option|sed -e 's/-*without-//'` + # Reject names that aren't valid shell variable names. + if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then + echo "configure: $ac_package: invalid package name" >&2; exit 1 + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + eval "with_${ac_package}=no" ;; + + --x) with_x=yes ;; # Obsolete; use --with-x. + + -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ + | --x-incl | --x-inc | --x-in | --x-i) + ac_prev=x_includes ;; + -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ + | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) + x_includes="$ac_optarg" ;; + + -x-libraries | --x-libraries | --x-librarie | --x-librari \ + | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) + ac_prev=x_libraries ;; + -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ + | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) + x_libraries="$ac_optarg" ;; + + -*) echo "configure: $ac_option: invalid option; use --help to show usage" >&2; exit 1 + ;; + + *) + if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then + echo "configure: warning: $ac_option: invalid host type" >&2 + fi + if test "x$nonopt" != xNONE; then + echo "configure: can only configure for one host and one target at a time" >&2; exit 1 + fi + nonopt="$ac_option" + ;; + + esac +done + +if test -n "$ac_prev"; then + echo "configure: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" >&2; exit 1 +fi + +trap 'rm -fr conftest* confdefs* core $ac_clean_files; exit 1' 1 2 15 +trap 'rm -fr confdefs* $ac_clean_files' 0 + +# Save the original args if we used an alternate arg parser. +ac_configure_temp="${configure_args-$*}" +# Strip out --no-create and --norecursion so they don't pile up. +configure_args= +for ac_arg in $ac_configure_temp; do + case "$ac_arg" in + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) ;; + -norecursion | --norecursion | --norecursio | --norecursi \ + | --norecurs | --norecur | --norecu | --norec | --nore | --nor) ;; + *) configure_args="$configure_args $ac_arg" ;; + esac +done + +# NLS nuisances. +# These must not be set unconditionally because not all systems understand +# e.g. LANG=C (notably SCO). +if test "${LC_ALL+set}" = 'set'; then LC_ALL=C; export LC_ALL; fi +if test "${LANG+set}" = 'set'; then LANG=C; export LANG; fi + +# confdefs.h avoids OS command line length limits that DEFS can exceed. +rm -rf conftest* confdefs.h +# AIX cpp loses on an empty file, so make sure it contains at least a newline. +echo > confdefs.h + +# A filename unique to this package, relative to the directory that +# configure is in, which we can look for to find out if srcdir is correct. +ac_unique_file=acgeneral.m4 + +# Find the source files, if location was not specified. +if test -z "$srcdir"; then + ac_srcdir_defaulted=yes + # Try the directory containing this script, then `..'. + ac_prog=$0 + ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` + test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. + srcdir=$ac_confdir + if test ! -r $srcdir/$ac_unique_file; then + srcdir=.. + fi +fi +if test ! -r $srcdir/$ac_unique_file; then + if test x$ac_srcdir_defaulted = xyes; then + echo "configure: can not find sources in ${ac_confdir} or .." >&2; exit 1 + else + echo "configure: can not find sources in ${srcdir}" >&2; exit 1 + fi +fi +ac_ext=c +# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. +ac_cpp='${CPP}' +ac_compile='${CC-cc} $CFLAGS $LDFLAGS conftest.${ac_ext} -o conftest $LIBS >/dev/null 2>&1' + + +for ac_prog in gnum4 gm4 m4 +do +if test -z "$M4"; then + # Extract the first word of `$ac_prog', so it can be a program name with args. + set ac_dummy $ac_prog; ac_word=$2 + test -n "$silent" || echo "checking for $ac_word" + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" + for ac_dir in $PATH; do + test -z "$ac_dir" && ac_dir=. + if test -f $ac_dir/$ac_word; then + M4="$ac_dir/$ac_word" + break + fi + done + IFS="$ac_save_ifs" +fi + +test -n "$M4" && test -n "$verbose" && echo " setting M4 to $M4" + +test -n "$M4" && break +done +test -n "$M4" || M4="m4" + +# Make sure to not get the incompatible SysV /etc/install and +# /usr/sbin/install, which might be in PATH before a BSD-like install, +# or the SunOS /usr/etc/install directory, or the AIX /bin/install, +# or the AFS install, which mishandles nonexistent args, or +# /usr/ucb/install on SVR4, which tries to use the nonexistent group +# `staff', or /sbin/install on IRIX which has incompatible command-line +# syntax. Sigh. +# +# On most BSDish systems install is in /usr/bin, not /usr/ucb +# anyway. +# This turns out not to be true, so the mere pathname isn't an indication +# of whether the program works. What we really need is a set of tests for +# the install program to see if it actually works in all the required ways. +# +# Avoid using ./install, which might have been erroneously created +# by make from ./install.sh. +if test -z "${INSTALL}"; then + test -n "$silent" || echo "checking for a BSD compatible install" + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}:" + for ac_dir in $PATH; do + case "$ac_dir" in + ''|.|/etc|/sbin|/usr/sbin|/usr/etc|/usr/afsws/bin|/usr/ucb) ;; + *) + # OSF1 and SCO ODT 3.0 have their own names for install. + for ac_prog in installbsd scoinst install; do + if test -f $ac_dir/$ac_prog; then + if test $ac_prog = install && + grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then + # AIX install. It has an incompatible calling convention. + # OSF/1 installbsd also uses dspmsg, but is usable. + : + else + INSTALL="$ac_dir/$ac_prog -c" + break 2 + fi + fi + done + ;; + esac + done + IFS="$ac_save_ifs" +fi + +if test -z "$INSTALL"; then + # As a last resort, use the slow shell script. + for ac_dir in ${srcdir} ${srcdir}/.. ${srcdir}/../..; do + if test -f $ac_dir/install.sh; then + INSTALL="$ac_dir/install.sh -c"; break + fi + done +fi +if test -z "$INSTALL"; then + echo "configure: can not find install.sh in ${srcdir} or ${srcdir}/.. or ${srcdir}/../.." >&2; exit 1 +fi +test -n "$verbose" && echo " setting INSTALL to $INSTALL" + +# Use test -z because SunOS4 sh mishandles ${INSTALL_PROGRAM-'${INSTALL}'}. +# It thinks the first close brace ends the variable substitution. +test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}' +test -n "$verbose" && echo " setting INSTALL_PROGRAM to $INSTALL_PROGRAM" + +test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' +test -n "$verbose" && echo " setting INSTALL_DATA to $INSTALL_DATA" + + +# The preferred way to propogate these variables is regular @ substitutions. +if test -n "$prefix"; then + ac_prsub="s%^prefix\\([ ]*\\)=\\([ ]*\\).*$%prefix\\1=\\2$prefix%" +else + prefix=/usr/local +fi +if test -n "$exec_prefix"; then + ac_prsub="$ac_prsub +s%^exec_prefix\\([ ]*\\)=\\([ ]*\\).*$%exec_prefix\\1=\\2$exec_prefix%" +else + exec_prefix='${prefix}' # Let make expand it. +fi + +# Any assignment to VPATH causes Sun make to only execute +# the first set of double-colon rules, so remove it if not needed. +# If there is a colon in the path, we need to keep it. +if test "x$srcdir" = x.; then + ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' +fi + +# Quote sed substitution magic chars in DEFS. +cat >conftest.def < config.status </dev/null | sed 1q`: +# +# $0 $configure_args + +ac_cs_usage="Usage: config.status [--recheck] [--version] [--help]" +for ac_option +do + case "\$ac_option" in + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + echo running \${CONFIG_SHELL-/bin/sh} $0 $configure_args --no-create + exec \${CONFIG_SHELL-/bin/sh} $0 $configure_args --no-create ;; + -version | --version | --versio | --versi | --vers | --ver | --ve | --v) + echo "config.status generated by autoconf version 1.11" + exit 0 ;; + -help | --help | --hel | --he | --h) + echo "\$ac_cs_usage"; exit 0 ;; + *) echo "\$ac_cs_usage"; exit 1 ;; + esac +done + +trap 'rm -f Makefile; exit 1' 1 2 15 +M4='$M4' +INSTALL='$INSTALL' +INSTALL_PROGRAM='$INSTALL_PROGRAM' +INSTALL_DATA='$INSTALL_DATA' +LIBS='$LIBS' +srcdir='$srcdir' +top_srcdir='$top_srcdir' +prefix='$prefix' +exec_prefix='$exec_prefix' +DEFS='$DEFS' +ac_prsub='$ac_prsub' +ac_vpsub='$ac_vpsub' +extrasub='$extrasub' +EOF +cat >> config.status <<\EOF + +ac_given_srcdir=$srcdir + +CONFIG_FILES=${CONFIG_FILES-"Makefile"} +for ac_file in .. ${CONFIG_FILES}; do if test "x$ac_file" != x..; then + # Remove last slash and all that follows it. Not all systems have dirname. + ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` + if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then + # The file is in a subdirectory. + test ! -d "$ac_dir" && mkdir "$ac_dir" + ac_dir_suffix="/$ac_dir" + else + ac_dir_suffix= + fi + + # A "../" for each directory in $ac_dir_suffix. + ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` + case "$ac_given_srcdir" in + .) srcdir=. + if test -z "$ac_dir_suffix"; then top_srcdir=. + else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; + /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; + *) # Relative path. + srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" + top_srcdir="$ac_dots$ac_given_srcdir" ;; + esac + + echo creating "$ac_file" + rm -f "$ac_file" + comment_str="Generated automatically from `echo $ac_file|sed 's|.*/||'`.in by configure." + case "$ac_file" in + *.c | *.h | *.C | *.cc | *.m ) echo "/* $comment_str */" > "$ac_file" ;; + * ) echo "# $comment_str" > "$ac_file" ;; + esac + sed -e " +$ac_prsub +$ac_vpsub +$extrasub +s%@M4@%$M4%g +s%@INSTALL@%$INSTALL%g +s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g +s%@INSTALL_DATA@%$INSTALL_DATA%g +s%@LIBS@%$LIBS%g +s%@srcdir@%$srcdir%g +s%@top_srcdir@%$top_srcdir%g +s%@prefix@%$prefix%g +s%@exec_prefix@%$exec_prefix%g +s%@DEFS@%$DEFS% +" $ac_given_srcdir/${ac_file}.in >> $ac_file +fi; done + + +exit 0 +EOF +chmod +x config.status +# Some shells look in PATH for config.status without the "./". +test -n "$no_create" || ${CONFIG_SHELL-/bin/sh} ./config.status + diff --git a/src/util/autoconf/configure.in b/src/util/autoconf/configure.in new file mode 100644 index 000000000..3b4ca4766 --- /dev/null +++ b/src/util/autoconf/configure.in @@ -0,0 +1,5 @@ +dnl Process this file with autoconf to produce a configure script. +AC_INIT(acgeneral.m4) +AC_PROGRAMS_PATH(M4, gnum4 gm4 m4, m4) +AC_PROG_INSTALL +AC_OUTPUT(Makefile) diff --git a/src/util/autoconf/install.sh b/src/util/autoconf/install.sh new file mode 100644 index 000000000..0ff4b6a08 --- /dev/null +++ b/src/util/autoconf/install.sh @@ -0,0 +1,119 @@ +#!/bin/sh + +# +# install - install a program, script, or datafile +# This comes from X11R5; it is not part of GNU. +# +# $XConsortium: install.sh,v 1.2 89/12/18 14:47:22 jim Exp $ +# +# This script is compatible with the BSD install script, but was written +# from scratch. +# + + +# set DOITPROG to echo to test this script + +# Don't use :- since 4.3BSD and earlier shells don't like it. +doit="${DOITPROG-}" + + +# put in absolute paths if you don't have them in your path; or use env. vars. + +mvprog="${MVPROG-mv}" +cpprog="${CPPROG-cp}" +chmodprog="${CHMODPROG-chmod}" +chownprog="${CHOWNPROG-chown}" +chgrpprog="${CHGRPPROG-chgrp}" +stripprog="${STRIPPROG-strip}" +rmprog="${RMPROG-rm}" + +instcmd="$mvprog" +chmodcmd="" +chowncmd="" +chgrpcmd="" +stripcmd="" +rmcmd="$rmprog -f" +mvcmd="$mvprog" +src="" +dst="" + +while [ x"$1" != x ]; do + case $1 in + -c) instcmd="$cpprog" + shift + continue;; + + -m) chmodcmd="$chmodprog $2" + shift + shift + continue;; + + -o) chowncmd="$chownprog $2" + shift + shift + continue;; + + -g) chgrpcmd="$chgrpprog $2" + shift + shift + continue;; + + -s) stripcmd="$stripprog" + shift + continue;; + + *) if [ x"$src" = x ] + then + src=$1 + else + dst=$1 + fi + shift + continue;; + esac +done + +if [ x"$src" = x ] +then + echo "install: no input file specified" + exit 1 +fi + +if [ x"$dst" = x ] +then + echo "install: no destination specified" + exit 1 +fi + + +# If destination is a directory, append the input filename; if your system +# does not like double slashes in filenames, you may need to add some logic + +if [ -d $dst ] +then + dst="$dst"/`basename $src` +fi + +# Make a temp file name in the proper directory. + +dstdir=`dirname $dst` +dsttmp=$dstdir/#inst.$$# + +# Move or copy the file name to the temp name + +$doit $instcmd $src $dsttmp + +# and set any options; do chmod last to preserve setuid bits + +if [ x"$chowncmd" != x ]; then $doit $chowncmd $dsttmp; fi +if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dsttmp; fi +if [ x"$stripcmd" != x ]; then $doit $stripcmd $dsttmp; fi +if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dsttmp; fi + +# Now rename the file to the real destination. + +$doit $rmcmd $dst +$doit $mvcmd $dsttmp $dst + + +exit 0 diff --git a/src/util/autoconf/make-stds.texi b/src/util/autoconf/make-stds.texi new file mode 100644 index 000000000..4b4ff7ef9 --- /dev/null +++ b/src/util/autoconf/make-stds.texi @@ -0,0 +1,528 @@ +@comment This file is included by both standards.texi and make.texinfo. +@comment It was broken out of standards.texi on 1/6/93 by roland. + +@node Makefile Conventions +@chapter Makefile Conventions +@comment standards.texi does not print an index, but make.texinfo does. +@cindex makefile, conventions for +@cindex conventions for makefiles +@cindex standards for makefiles + +This chapter describes conventions for writing the Makefiles for GNU programs. + +@menu +* Makefile Basics:: +* Utilities in Makefiles:: +* Standard Targets:: +* Command Variables:: +* Directory Variables:: +@end menu + +@node Makefile Basics +@section General Conventions for Makefiles + +Every Makefile should contain this line: + +@example +SHELL = /bin/sh +@end example + +@noindent +to avoid trouble on systems where the @code{SHELL} variable might be +inherited from the environment. (This is never a problem with GNU +@code{make}.) + +Don't assume that @file{.} is in the path for command execution. When +you need to run programs that are a part of your package during the +make, please make sure that it uses @file{./} if the program is built as +part of the make or @file{$(srcdir)/} if the file is an unchanging part +of the source code. Without one of these prefixes, the current search +path is used. + +The distinction between @file{./} and @file{$(srcdir)/} is important +when using the @samp{--srcdir} option to @file{configure}. A rule of +the form: + +@smallexample +foo.1 : foo.man sedscript + sed -e sedscript foo.man > foo.1 +@end smallexample + +@noindent +will fail when the current directory is not the source directory, +because @file{foo.man} and @file{sedscript} are not in the current +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 +source file wherever it is. (Many versions of @code{make} set @samp{$<} +only in implicit rules.) A makefile target like + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o +@end smallexample + +@noindent +should instead be written as + +@smallexample +foo.o : bar.c + $(CC) $(CFLAGS) $< -o $@@ +@end smallexample + +@noindent +in order to allow @samp{VPATH} to work correctly. When the target has +multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest +way to make the rule work well. For example, the target above for +@file{foo.1} is best written as: + +@smallexample +foo.1 : foo.man sedscript + sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1 +@end smallexample + +@node Utilities in Makefiles +@section Utilities in Makefiles + +Write the Makefile commands (and any shell scripts, such as +@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any +special features of @code{ksh} or @code{bash}. + +The @code{configure} script and the Makefile rules for building and +installation should not use any utilities directly except these: + +@example +cat cmp cp echo egrep expr grep +ln mkdir mv pwd rm rmdir sed test touch +@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. + +The Makefile rules for building and installation can also use compilers +and related programs, but should do so via @code{make} variables so that the +user can substitute alternatives. Here are some of the programs we +mean: + +@example +ar bison cc flex install ld lex +make makeinfo ranlib texi2dvi yacc +@end example + +When you use @code{ranlib}, you should test whether it exists, and run +it only if it exists, so that the distribution will work on systems that +don't have @code{ranlib}. + +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 +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. + +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). + +@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 realclean +Delete 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. + +One exception, however: @samp{make realclean} should not delete +@file{configure} even if @file{configure} can be remade using a rule in +the Makefile. More generally, @samp{make realclean} should not delete +anything that needs to exist in order to run @file{configure} +and then begin to build the program. + +@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 +@end table + +@node Command Variables +@section Variables for Specifying Commands + +Makefiles should provide variables for overriding certain commands, options, +and so on. + +In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named @code{BISON} whose default +value is set with @samp{BISON = bison}, and refer to it with +@code{$(BISON)} whenever you need to use Bison. + +File management utilities such as @code{ln}, @code{rm}, @code{mv}, and +so on, need not be referred to through variables in this way, since users +don't need to replace them with other programs. + +Each program-name variable should come with an options variable that is +used to supply options to the program. Append @samp{FLAGS} to the +program-name variable name to get the options variable name---for +example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to +this rule, but we keep it because it is standard.) Use @code{CPPFLAGS} +in any compilation command that runs the preprocessor, and use +@code{LDFLAGS} in any compilation command that does linking as well as +in any direct use of @code{ld}. + +If there are C compiler options that @emph{must} be used for proper +compilation of certain files, do not include them in @code{CFLAGS}. +Users expect to be able to specify @code{CFLAGS} freely themselves. +Instead, arrange to pass the necessary options to the C compiler +independently of @code{CFLAGS}, by writing them explicitly in the +compilation commands or by defining an implicit rule, like this: + +@smallexample +CFLAGS = -g +ALL_CFLAGS = -I. $(CFLAGS) +.c.o: + $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< +@end smallexample + +Do include the @samp{-g} option in @code{CFLAGS}, because that is not +@emph{required} for proper compilation. You can consider it a default +that is only recommended. If the package is set up so that it is +compiled with GCC by default, then you might as well include @samp{-O} +in the default value of @code{CFLAGS} as well. + +Put @code{CFLAGS} last in the compilation command, after other variables +containing compiler options, so the user can use @code{CFLAGS} to +override the others. + +Every Makefile should define the variable @code{INSTALL}, which is the +basic command for installing a file into the system. + +Every Makefile should also define the variables @code{INSTALL_PROGRAM} +and @code{INSTALL_DATA}. (The default for each of these should be +@code{$(INSTALL)}.) Then it should use those variables as the commands +for actual installation, for executables and nonexecutables +respectively. Use these variables as follows: + +@example +$(INSTALL_PROGRAM) foo $(bindir)/foo +$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a +@end example + +@noindent +Always use a file name, not a directory name, as the second argument of +the installation commands. Use a separate command for each file to be +installed. + +@node Directory Variables +@section Variables for Installation Directories + +Installation directories should always be named by variables, so it is +easy to install in a nonstandard place. The standard names for these +variables are: + +@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} +(at least for now). + +@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)}. + +Generally, @code{$(exec_prefix)} is used for directories that contain +machine-specific files (such as executables and subroutine libraries), +while @code{$(prefix)} is used directly for other directories. + +@item bindir +The directory for installing executable programs that users can run. +This should normally be @file{/usr/local/bin}, but write it as +@file{$(exec_prefix)/bin}. + +@item libdir +The directory for installing executable files to be run by the program +rather than by users. Object files and libraries of object code should +also go in this directory. The idea is that this directory is used for +files that pertain to a specific machine architecture, but need not be +in the path for commands. The value of @code{libdir} should normally be +@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. + +@item datadir +The directory for installing read-only data files which the programs +refer to while they run. This directory is used for files which are +independent of the type of machine being used. This should normally be +@file{/usr/local/lib}, but write it as @file{$(prefix)/lib}. + +@item statedir +The directory for installing data files which the programs modify while +they run. These files should be independent of the type of machine +being used, and it should be possible to share them among machines at a +network installation. This should normally be @file{/usr/local/lib}, +but write it as @file{$(prefix)/lib}. + +@item includedir +@c rewritten to avoid overfull hbox --roland +The directory for installing header files to be included by user +programs with the C @samp{#include} preprocessor directive. This +should normally be @file{/usr/local/include}, but write it as +@file{$(prefix)/include}. + +Most compilers other than GCC do not look for header files in +@file{/usr/local/include}. So installing the header files this way is +only useful with GCC. Sometimes this is not a problem because some +libraries are only really intended to work with GCC. But some libraries +are intended to work with other compilers. They should install their +header files in two places, one specified by @code{includedir} and one +specified by @code{oldincludedir}. + +@item oldincludedir +The directory for installing @samp{#include} header files for use with +compilers other than GCC. This should normally be @file{/usr/include}. + +The Makefile commands should check whether the value of +@code{oldincludedir} is empty. If it is, they should not try to use +it; they should cancel the second installation of the header files. + +A package should not replace an existing header in this directory unless +the header came from the same package. Thus, if your Foo package +provides a header file @file{foo.h}, then it should install the header +file in the @code{oldincludedir} directory if either (1) there is no +@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo +package. + +To tell whether @file{foo.h} came from the Foo package, put a magic +string in the file---part of a comment---and grep for that string. + +@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}. + +@item man1dir +The directory for installing section 1 man pages. +@item man2dir +The directory for installing section 2 man pages. +@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 +the sake of people running GNU software on Unix, which is a secondary +application only.} + +@item manext +The file name extension for the installed man page. This should contain +a period followed by the appropriate digit; it should normally be @samp{.1}. + +@item man1ext +The file name extension for installed section 1 man pages. +@item man2ext +The file name extension for installed section 2 man pages. +@item @dots{} +Use these names instead of @samp{manext} if the package needs to install man +pages in more than one section of the manual. + +@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}. + +@item srcdir +The directory for the sources being compiled. The value of this +variable is normally inserted by the @code{configure} shell script. +@end table + +For example: + +@smallexample +@c I have changed some of the comments here slightly to fix an overfull +@c hbox, so the make manual can format correctly. --roland +# Common prefix for installation directories. +# NOTE: This directory must exist when you start the install. +prefix = /usr/local +exec_prefix = $(prefix) +# Where to put the executable for the command `gcc'. +bindir = $(exec_prefix)/bin +# Where to put the directories used by the compiler. +libdir = $(exec_prefix)/lib +# Where to put the Info files. +infodir = $(prefix)/info +@end smallexample + +If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the @code{install} rule to create these subdirectories. + +Do not expect the user to include the subdirectory name in the value of +any of the variables listed above. The idea of having a uniform set of +variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. + diff --git a/src/util/autoconf/mkinstalldirs b/src/util/autoconf/mkinstalldirs new file mode 100644 index 000000000..91f6d04e1 --- /dev/null +++ b/src/util/autoconf/mkinstalldirs @@ -0,0 +1,32 @@ +#!/bin/sh +# mkinstalldirs --- make directory hierarchy +# Author: Noah Friedman +# Created: 1993-05-16 +# Last modified: 1994-03-25 +# Public domain + +errstatus=0 + +for file in ${1+"$@"} ; do + set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` + shift + + pathcomp= + for d in ${1+"$@"} ; do + pathcomp="$pathcomp$d" + case "$pathcomp" in + -* ) pathcomp=./$pathcomp ;; + esac + + if test ! -d "$pathcomp"; then + echo "mkdir $pathcomp" 1>&2 + mkdir "$pathcomp" || errstatus=$? + fi + + pathcomp="$pathcomp/" + done +done + +exit $errstatus + +# mkinstalldirs ends here diff --git a/src/util/autoconf/standards.info b/src/util/autoconf/standards.info new file mode 100644 index 000000000..766c4459b --- /dev/null +++ b/src/util/autoconf/standards.info @@ -0,0 +1,2693 @@ +This is Info file standards.info, produced by Makeinfo-1.55 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 + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + + +File: standards.info, Node: Top, Next: Reading Non-Free Code, Prev: (dir), Up: (dir) + +Version +******* + + Last updated 28 March 1994. + +* Menu: + +* 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 and Functions +* 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 +* Documentation:: Documenting Programs +* Releases:: Making Releases + + +File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Prev: Top, Up: Top + +Referring to Proprietary Programs +********************************* + + Don't in any circumstances refer to Unix source code for or during +your work on GNU! (Or to any other proprietary programs.) + + If you have a vague recollection of the internals of a Unix program, +this does not absolutely mean you can't write an imitation of it, but +do try to organize the imitation internally along different lines, +because this is likely to make the details of the Unix version +irrelevant and dissimilar to your results. + + For example, Unix utilities were generally optimized to minimize +memory use; if you go for speed instead, your program will be very +different. You could keep the entire input file in core and scan it +there instead of using stdio. Use a smarter algorithm discovered more +recently than the Unix program. Eliminate use of temporary files. Do +it in one pass instead of two (we did this in the assembler). + + Or, on the contrary, emphasize simplicity instead of speed. For some +applications, the speed of today's computers makes simpler algorithms +adequate. + + Or go for generality. For example, Unix programs often have static +tables or fixed-size strings, which make for arbitrary limits; use +dynamic allocation instead. Make sure your program handles NULs and +other funny characters in the input files. Add a programming language +for extensibility and write part of the program in that language. + + Or turn some parts of the program into independently usable +libraries. Or use a simple garbage collector instead of tracking +precisely when to free memory, or use a new GNU facility such as +obstacks. + + +File: standards.info, Node: Contributions, Next: Change Logs, Prev: Reading Non-Free Code, Up: Top + +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 change, 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. + + I 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: Change Logs, Next: Compatibility, Prev: Contributions, Up: Top + +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' 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 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 `* 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: Compatibility, Next: Makefile Conventions, Prev: Change Logs, Up: Top + +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 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' 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: Makefile Conventions, Next: Configuration, Prev: Compatibility, Up: Top + +Makefile Conventions +******************** + + This chapter describes conventions for writing the Makefiles for GNU +programs. + +* Menu: + +* Makefile Basics:: +* Utilities in Makefiles:: +* Standard Targets:: +* Command Variables:: +* Directory Variables:: + + +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'.) + + 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) $(CFLAGS) $< -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 -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1 + + +File: standards.info, Node: Utilities in Makefiles, Next: Standard Targets, 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 grep + ln mkdir mv pwd rm rmdir sed test touch + + 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. + + 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 + + When you use `ranlib', you should test whether it exists, and run it +only if it exists, so that the distribution will work on systems that +don't have `ranlib'. + + 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 +exist. + + +File: standards.info, Node: Standard Targets, Next: Command Variables, Prev: Utilities in Makefiles, 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. + +`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. + + 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 + script that edits the Info `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: + + $(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 + +`uninstall' + Delete all the installed files that the `install' target would + create (but not the noninstalled files such as `make all' would + create). + +`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. + +`realclean' + Delete 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. + + One exception, however: `make realclean' should not delete + `configure' even if `configure' can be remade using a rule in the + Makefile. More generally, `make realclean' should not delete + anything that needs to exist in order to run `configure' and then + begin to build the program. + +`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. 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. + + 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: (standards)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; 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) + + +File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Standard Targets, 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, 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: + +`prefix' + A prefix used in constructing the default values of the variables + listed below. The default value of `prefix' should be `/usr/local' + (at least for now). + +`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)'. + + 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. + +`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'. + +`libdir' + The directory for installing executable files to be run by the + program rather than by users. Object files and libraries of + object code should also go in this directory. The idea is that + this directory is used for files that pertain to a specific + machine architecture, but need not be in the path for commands. + The value of `libdir' should normally be `/usr/local/lib', but + write it as `$(exec_prefix)/lib'. + +`datadir' + The directory for installing read-only data files which the + programs refer to while they run. This directory is used for + files which are independent of the type of machine being used. + This should normally be `/usr/local/lib', but write it as + `$(prefix)/lib'. + +`statedir' + The directory for installing data files which the programs modify + while they run. These files should be independent of the type of + machine being used, and it should be possible to share them among + machines at a network installation. This should normally be + `/usr/local/lib', but write it as `$(prefix)/lib'. + +`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'. + + 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'. + + 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. + +`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 `1' for a utility. It will normally be + `/usr/local/man/man1', but you should write it as + `$(prefix)/man/man1'. + +`man1dir' + The directory for installing section 1 man pages. + +`man2dir' + The directory for installing section 2 man pages. + +`...' + Use these names instead of `mandir' if the package needs to + install man pages in more than one section of the manual. + + *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. + +`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'. + +`srcdir' + The directory for the sources being compiled. The value of this + variable is normally inserted by the `configure' shell script. + + 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. + libdir = $(exec_prefix)/lib + # 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: Configuration, Next: Source Language, Prev: Makefile Conventions, Up: Top + +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, 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. So would `sun3-bsd4.2', since SunOS is +basically BSD and no other BSD system is used on a Sun. 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 compilation 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: Source Language, Next: Formatting, Prev: Configuration, Up: Top + +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. + + Thus, it is not a problem that GNU Emacs contains code written in + Emacs Lisp, because it comes with a Lisp interpreter. + + * 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: Formatting, Next: Comments, Prev: Source Language, Up: Top + +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: Top + +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 +identifer 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: Top + +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: Using Extensions, Prev: Syntactic Conventions, Up: Top + +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 System V. 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: Using Extensions, Next: System Functions, Prev: Names, Up: Top + +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. + + Since most computer systems do not yet implement ANSI C, using the +ANSI C features is effectively using a GNU extension, so the same +considerations apply. (Except for ANSI features that we discourage, +such as trigraphs--don't ever use them.) + + +File: standards.info, Node: System Functions, Next: Semantics, Prev: Using Extensions, Up: Top + +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. The problem 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'; other 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 are off-limits 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'.) 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: Semantics, Next: Errors, Prev: System Functions, Up: Top + +Program Behavior for All Programs +********************************* + + Avoid arbitrary limits on the length or number of *any* data +structure, including filenames, 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'. + + 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. + + +File: standards.info, Node: Errors, Next: Libraries, Prev: Semantics, Up: Top + +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 filename. 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: Libraries, Next: Portability, Prev: Errors, Up: Top + +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: Portability, Next: User Interfaces, Prev: Libraries, Up: Top + +Portability As It Applies to GNU +******************************** + + 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. + + 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. + + 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 +(`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 `int' object is +also the address of its least-significant byte. Thus, don't make the +following mistake: + + int c; + ... + while ((c = getchar()) != EOF) + write(file_descriptor, &c, 1); + + 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. + + 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. + + +File: standards.info, Node: User Interfaces, Next: Documentation, Prev: Portability, Up: Top + +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. + +`auto-check' + `-a' in `recode'. + +`auto-reference' + `-A' in `ptx'. + +`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'. + +`arglength' + `-l' in `m4'. + +`ascii' + `-a' in `diff'. + +`assume-new' + `-W' in Make. + +`assume-old' + `-o' in Make. + +`backward-search' + `-B' in etags. + +`batch' + Used in GDB. + +`baud' + Used in GDB. + +`before' + `-b' in `tac'. + +`binary' + `-b' in `cpio' and `diff'. + +`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'. + +`compress' + `-Z' in `tar'. + +`concatenate' + `-A' in `tar'. + +`confirmation' + `-w' in `tar'. + +`context' + Used in `diff'. + +`copyright' + `-C' in `ptx' and `recode'. + +`core' + Used in GDB. + +`count' + `-q' in `who'. + +`count-links' + `-l' in `du'. + +`create' + Used in `tar' and `cpio'. + +`cxref' + `-x' in `etags'. + +`date' + `-d' in `touch'. + +`debug' + `-d' in Make and `m4'; `-t' in Bison. + +`define' + `-D' in `m4'. + +`defines' + `-d' in Bison and `etags'. + +`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'. + +`diversions' + `-N' in `m4'. + +`dry-run' + `-n' in Make. + +`ed' + `-e' in `diff'. + +`elide-empty-files' + `-z' in `csplit'. + +`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'. + +`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'. + +`file' + `-f' in `info', Make, `mt', and `tar'; `-n' in `sed'; `-r' in + `touch'. + +`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'. + +`format' + Used in `ls', `time', and `ptx'. + +`forward-search' + `-F' in `etags'. + +`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'. + +`hashsize' + `-H' in `m4'. + +`header' + `-h' in `objdump' and `recode' + +`heading' + `-H' in `who'. + +`help' + Used to ask for brief usage information. + +`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'. + +`ignore-errors' + `-i' in Make. + +`ignore-file' + `-i' in `ptx'. + +`ignore-indentation' + `-S' 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'. + +`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'. + +`line-bytes' + `-C' in `split'. + +`lines' + Used in `split', `head', and `tail'. + +`link' + `-l' in `cpio'. + +`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'. + +`mode' + `-m' in `install', `mkdir', and `mkfifo'. + +`modification-time' + `-m' in `tar'. + +`multi-volume' + `-M' in `tar'. + +`name-prefix' + `-a' in Bison. + +`new-file' + `-W' in Make. + +`no-builtin-rules' + `-r' in Make. + +`no-create' + `-c' in `touch'. + +`no-defines' + `-D' in `etags'. + +`no-dereference' + `-d' in `cp'. + +`no-keep-going' + `-S' in Make. + +`no-lines' + `-l' in Bison. + +`no-prof' + `-e' in `gprof'. + +`no-sort' + `-p' in `nm'. + +`no-split' + Used in Makeinfo. + +`no-static' + `-a' in `gprof'. + +`no-time' + `-E' in `gprof'. + +`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. + +`override' + `-o' in `rm'. + +`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'. + +`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'. + +`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. + +`quote-name' + `-Q' in `ls'. + +`rcs' + `-n' in `diff'. + +`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'. + +`release' + `-r' in `uname'. + +`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'. + +`sparse' + `-S' in `tar'. + +`speed-large-files' + `-H' in `diff'. + +`squeeze-blank' + `-s' in `cat'. + +`starting-file' + Used in `tar' and `diff' to specify which file within a directory + to start processing with. + +`stop' + `-S' in Make. + +`strict' + `-s' in `recode'. + +`strip' + `-s' in `install'. + +`strip-all' + `-s' in `strip'. + +`strip-debug' + `-S' in `strip'. + +`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'. + +`text' + `-a' in `diff'. + +`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'; `-G' in `m4' and `ptx'. + +`tty' + Used in GDB. + +`typedefs' + `-t' in `etags'. + +`typedefs-and-c++' + `-T' in `etags'. + +`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', `etags', `mv', `tar'. + +`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 `etags'. + +`volume' + `-V' in `tar'. + +`what-if' + `-W' in Make. + +`width' + `-w' in `ls' and `ptx'. + +`word-regexp' + `-W' in `ptx'. + +`writable' + `-T' in `who'. + +`zeros' + `-z' in `gprof'. + + +File: standards.info, Node: Documentation, Next: Releases, Prev: User Interfaces, Up: Top + +Documenting Programs +******************** + + Please use Texinfo for documenting GNU programs. See the Texinfo +manual, either the hardcopy or the version in the GNU Emacs Info +subsystem (`C-h i'). See existing GNU Texinfo files (e.g., those under +the `man/' directory in the GNU Emacs distribution) for examples. + + 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 +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 document all command-line arguments and all +commands. It should give examples of their use. But don't organize +the manual as a list of features. Instead, organize it by the concepts +a user will have before reaching that point in the manual. Address the +goals that a user will have in mind, and explain how to accomplish +them. Don't use Unix man pages as a model for how to write GNU +documentation; they are a bad example to follow. + + 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. + + 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. + + 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. + + 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 documentation. + + +File: standards.info, Node: Releases, Prev: Documentation, Up: Top + +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-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 +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' 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: +Node: Top950 +Node: Reading Non-Free Code2051 +Node: Contributions3777 +Node: Change Logs5375 +Node: Compatibility9091 +Node: Makefile Conventions10730 +Node: Makefile Basics11087 +Node: Utilities in Makefiles12978 +Node: Standard Targets14414 +Node: Command Variables21523 +Node: Directory Variables24353 +Node: Configuration30825 +Node: Source Language37849 +Node: Formatting38979 +Node: Comments42269 +Node: Syntactic Conventions45055 +Node: Names47947 +Node: Using Extensions49237 +Node: System Functions50978 +Node: Semantics55781 +Node: Errors58747 +Node: Libraries59950 +Node: Portability61174 +Node: User Interfaces64461 +Node: Documentation79291 +Node: Releases83225 + +End Tag Table diff --git a/src/util/autoconf/standards.texi b/src/util/autoconf/standards.texi new file mode 100644 index 000000000..13908d65f --- /dev/null +++ b/src/util/autoconf/standards.texi @@ -0,0 +1,2295 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename standards.info +@settitle GNU Coding Standards +@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES! +@set lastupdate 28 March 1994 +@c %**end of header + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Standards: (standards). GNU coding standards. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@setchapternewpage off + +@ifinfo +GNU Coding Standards +Copyright (C) 1992, 1993, 1994 Free Software Foundation + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end ifinfo + +@titlepage +@title GNU Coding Standards +@author Richard Stallman +@author last updated @value{lastupdate} +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993 Free Software Foundation + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, Reading Non-Free Code, (dir), (dir) +@top Version + +Last updated @value{lastupdate}. +@end ifinfo + +@menu +* 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 and Functions +* 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 +* Documentation:: Documenting Programs +* Releases:: Making Releases +@end menu + +@node Reading Non-Free Code +@chapter 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. + + +@node Contributions +@chapter 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. @emph{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 change, 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. + +I 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. + +@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} 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.'' + +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 Compatibility +@chapter 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. + +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. + +Many GNU programs suppress extensions that conflict with POSIX if the +environment variable @code{POSIXLY_CORRECT} is defined (even if it is +defined with a null value). Please make your program recognize this +variable if appropriate. + +When a feature is used only by users (not by programs or command +files), and it is done poorly in Unix, feel free to replace it +completely with something totally different and better. (For example, +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. + +@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 Configuration +@chapter 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, 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. So would @samp{sun3-bsd4.2}, since SunOS is +basically @sc{BSD} and no other @sc{BSD} system is used on a Sun. 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. + +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 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. + +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. + + +@node Source Language +@chapter 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: + +@itemize @bullet +@item +It is okay to use a special language if the same program contains an +interpreter for that language. + +Thus, it is not a problem that GNU Emacs contains code written in Emacs +Lisp, because it comes with a Lisp interpreter. + +@item +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. + +@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 + +@node Formatting +@chapter 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: + +@example +static char * +concat (s1, s2) /* Name starts in column zero here */ + char *s1, *s2; +@{ /* Open brace in column zero here */ + @dots{} +@} +@end example + +@noindent +or, if you want to use @sc{ANSI} C, format the definition like this: + +@example +static char * +concat (char *s1, char *s2) +@{ + @dots{} +@} +@end example + +In @sc{ANSI} C, if the arguments don't fit nicely on one line, +split it like this: + +@example +int +lots_of_args (int an_integer, long a_long, short a_short, + double a_double, float a_float) +@dots{} +@end example + +For the body of the function, we prefer code formatted like this: + +@example +if (x < foo (y, z)) + haha = bar[4] + 5; +else + @{ + while (z) + @{ + haha += foo (z, z); + z--; + @} + return ++x + bar (); + @} +@end example + +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: + +@example +if (foo_this_is_long && bar > win (x, y, z) + && remaining_condition) +@end example + +Try to avoid having two operators of different precedence at the same +level of indentation. For example, don't write this: + +@example +mode = (inmode[j] == VOIDmode + || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) + ? outmode[j] : inmode[j]); +@end example + +Instead, use extra parentheses so that the indentation shows the nesting: + +@example +mode = ((inmode[j] == VOIDmode + || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) + ? outmode[j] : inmode[j]); +@end example + +Insert extra parentheses so that Emacs will indent the code properly. +For example, the following indentation looks nice if you do it by hand, +but Emacs would mess it up: + +@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 + +But adding a set of parentheses solves the problem: + +@example +v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); +@end example + +Format do-while statements like this: + +@example +do + @{ + a = foo (a); + @} +while (a > 0); +@end example + +Please use formfeed characters (control-L) to divide the program into +pages at logical places (but not within a function). It does not matter +just how long the pages are, since they do not have to fit on a printed +page. The formfeeds should appear alone on lines by themselves. + + +@node Comments +@chapter Commenting Your Work + +Every program should start with a comment saying briefly what it is for. +Example: @samp{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 @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 +identifer 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}: + +@example +#ifndef foo + @dots{} +#else /* foo */ + @dots{} +#endif /* foo */ +@end example + + +@node Syntactic Conventions +@chapter Clean Use of C Constructs + +Please explicitly declare all arguments to functions. +Don't omit them just because they are @code{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 @code{extern} declarations inside +functions. + +It used to be common practice to use the same local variables (with +names like @code{tem}) over and over for different values within one +function. Instead of doing this, it is better declare a separate local +variable for each distinct purpose, and give it a name which is +meaningful. This not only makes programs easier to understand, it also +facilitates optimization by good compilers. You can also move the +declaration of each local variable into the smallest scope that includes +all its uses. This makes the program even cleaner. + +Don't use local variables or parameters that shadow global identifiers. + +Don't declare multiple variables in one declaration that spans lines. +Start a new declaration on each line, instead. For example, instead +of this: + +@example +int foo, + bar; +@end example + +@noindent +write either this: + +@example +int foo, bar; +@end example + +@noindent +or this: + +@example +int foo; +int bar; +@end example + +@noindent +(If they are global variables, each should have a comment preceding it +anyway.) + +When you have an @code{if}-@code{else} statement nested in another +@code{if} statement, always put braces around the @code{if}-@code{else}. +Thus, never write like this: + +@example +if (foo) + if (bar) + win (); + else + lose (); +@end example + +@noindent +always like this: + +@example +if (foo) + @{ + if (bar) + win (); + else + lose (); + @} +@end example + +If you have an @code{if} statement nested inside of an @code{else} +statement, either write @code{else if} on one line, like this, + +@example +if (foo) + @dots{} +else if (bar) + @dots{} +@end example + +@noindent +with its @code{then}-part indented like the preceding @code{then}-part, +or write the nested @code{if} within braces like this: + +@example +if (foo) + @dots{} +else + @{ + if (bar) + @dots{} + @} +@end example + +Don't declare both a structure tag and variables or typedefs in the +same declaration. Instead, declare the structure tag separately +and then use it to declare the variables or typedefs. + +Try to avoid assignments inside @code{if}-conditions. For example, +don't write this: + +@example +if ((foo = (char *) malloc (sizeof *foo)) == 0) + fatal ("virtual memory exhausted"); +@end example + +@noindent +instead, write this: + +@example +foo = (char *) malloc (sizeof *foo); +if (foo == 0) + fatal ("virtual memory exhausted"); +@end example + +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. + +@node Names +@chapter 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 @code{enum} constants, and for name-prefixes +that follow a uniform convention. + +For example, you should use names like @code{ignore_space_change_flag}; +don't use names like @code{iCantReadThis}. + +Variables that indicate whether command-line options have been +specified should be named after the meaning of the option, not after +the option-letter. A comment should state both the exact meaning of +the option and its letter. For example, + +@example +/* Ignore changes in horizontal whitespace (-b). */ +int ignore_space_change_flag; +@end example + +When you want to define names with constant integer values, use +@code{enum} rather than @samp{#define}. GDB knows about enumeration +constants. + +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. + + +@node Using Extensions +@chapter 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'' @code{INLINE} +and define that as a macro to expand into either @code{inline} or +nothing, depending on the compiler. + +In general, perhaps it is best not to use the extensions if you can +straightforwardly do without them, but to use the extensions if they +are a big improvement. + +An exception to this rule are the large, established programs (such as +Emacs) which run on a great variety of systems. 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. + +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.) + + +@node System Functions +@chapter 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. + +@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 +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. The problem is only theoretical. By +contrast, actual declarations have frequently caused actual conflicts. + +@item +If you must declare a system function, don't specify the argument types. +Use an old-style declaration, not an ANSI prototype. The more you +specify about the function, the more likely a conflict. + +@item +In particular, don't unconditionally declare @code{malloc} or +@code{realloc}. + +Most GNU programs use those functions just once, in functions +conventionally named @code{xmalloc} and @code{xrealloc}. These +functions call @code{malloc} and @code{realloc}, respectively, and +check the results. + +Because @code{xmalloc} and @code{xrealloc} are defined in your program, +you can declare them in other files without any risk of type conflict. + +On most systems, @code{int} is the same length as a pointer; thus, the +calls to @code{malloc} and @code{realloc} work fine. For the few +exceptional systems (mostly 64-bit machines), you can use +@strong{conditionalized} declarations of @code{malloc} and +@code{realloc}---or put these declarations in configuration files +specific to those systems. + +@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 +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 are off-limits anyway because many systems still don't +support them. The string functions you can use are these: + +@example +strcpy strncpy strcat strncat +strlen strcmp strncmp +strchr strrchr +@end example + +The copy and concatenate functions work fine without a declaration as +long as you don't use their values. Using their values without a +declaration fails on systems where the width of a pointer differs from +the width of @code{int}, and perhaps in other cases. It is trivial to +avoid using their values, so do that. + +The compare functions and @code{strlen} work fine without a declaration +on most systems, possibly all the ones that GNU software runs on. +You may find it necessary to declare them @strong{conditionally} on a +few systems. + +The search functions must be declared to return @code{char *}. Luckily, +there is no variation in the data type they return. But there is +variation in their names. Some systems give these functions the names +@code{index} and @code{rindex}; other systems use the names +@code{strchr} and @code{strrchr}. Some systems support both pairs of +names, but neither pair works on all systems. + +You should pick a single pair of names and use it throughout your +program. (Nowadays, it is better to choose @code{strchr} and +@code{strrchr}.) Declare both of those names as functions returning +@code{char *}. On systems which don't support those names, define them +as macros in terms of the other pair. For example, here is what to put +at the beginning of your file (or in a header) if you want to use the +names @code{strchr} and @code{strrchr} throughout: + +@example +#ifndef HAVE_STRCHR +#define strchr index +#endif +#ifndef HAVE_STRRCHR +#define strrchr rindex +#endif + +char *strchr (); +char *strrchr (); +@end example +@end itemize + +Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are +macros defined in systems where the corresponding functions exist. +One way to get them properly defined is to use Autoconf. + +@node Semantics +@chapter Program Behavior for All Programs + +Avoid arbitrary limits on the length or number of @emph{any} data +structure, including filenames, 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 @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. + +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. + +Check every call to @code{malloc} or @code{realloc} to see if it +returned zero. Check @code{realloc} even if you are making the block +smaller; in a system that rounds block sizes to a power of 2, +@code{realloc} may get a different block if you ask for less space. + +In Unix, @code{realloc} can destroy the storage block if it returns +zero. GNU @code{realloc} does not have this bug: if it fails, the +original block is unchanged. Feel free to assume the bug is fixed. If +you wish to run your program on Unix, and wish to avoid lossage in this +case, you can use the GNU @code{malloc}. + +You must expect @code{free} to alter the contents of the block that was +freed. Anything you want to fetch from the block, you must fetch before +calling @code{free}. + +Use @code{getopt_long} to decode arguments, unless the argument syntax +makes this unreasonable. + +When static storage is to be written in during program execution, use +explicit C code to initialize it. Reserve C initialized declarations +for data that will not be changed. + +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. + +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. + +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. + + +@node Errors +@chapter Formatting Error Messages + +Error messages from compilers should look like this: + +@example +@var{source-file-name}:@var{lineno}: @var{message} +@end example + +Error messages from other noninteractive programs should look like this: + +@example +@var{program}:@var{source-file-name}:@var{lineno}: @var{message} +@end example + +@noindent +when there is an appropriate source file, or like this: + +@example +@var{program}: @var{message} +@end example + +@noindent +when there is no relevant source file. + +In an interactive program (one that is reading commands from a +terminal), it is better not to include the program name in an error +message. The place to indicate which program is running is in the +prompt or with the screen layout. (When the same program runs with +input from a source other than a terminal, it is not interactive and +would do best to print error messages using the noninteractive style.) + +The string @var{message} should not begin with a capital letter when +it follows a program name and/or filename. Also, it should not end +with a period. + +Error messages from interactive programs, and other messages such as +usage messages, should start with a capital letter. But they should not +end with a period. + + +@node Libraries +@chapter 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 @code{malloc} itself. + +Here are certain name conventions for libraries, to avoid name +conflicts. + +Choose a name prefix for the library, more than two characters long. +All external function and variable names should start with this +prefix. In addition, there should only be one of these in any given +library member. This usually means putting each one in a separate +source file. + +An exception can be made when two external symbols are always used +together, so that no reasonable program could use one without the +other; then they can both go in the same file. + +External symbols that are not documented entry points for the user +should have names beginning with @samp{_}. 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. + + +@node Portability +@chapter Portability As It Applies to GNU + +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. + +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. + +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: + +@example +int c; +@dots{} +while ((c = getchar()) != EOF) + write(file_descriptor, &c, 1); +@end example + +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. + +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. + + +@node User Interfaces +@chapter 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 @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. + +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. + +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. + +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. + +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. + +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. + +@c Please leave newlines between items in this table; it's much easier +@c to update when it isn't completely squashed together and unreadable. +@c When there is more than one short option for a long option name, put +@c a semicolon between the lists of the programs that use them, not a +@c period. --friedman + +@table @samp + +@item auto-check +@samp{-a} in @code{recode}. + +@item auto-reference +@samp{-A} in @code{ptx}. + +@item after-date +@samp{-N} in @code{tar}. + +@item all +@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, +and @code{unexpand}. + +@item all-text +@samp{-a} in @code{diff}. + +@item almost-all +@samp{-A} in @code{ls}. + +@item append +@samp{-a} in @code{etags}, @code{tee}, @code{time}; +@samp{-r} in @code{tar}. + +@item archive +@samp{-a} in @code{cp}. + +@item arglength +@samp{-l} in @code{m4}. + +@item ascii +@samp{-a} in @code{diff}. + +@item assume-new +@samp{-W} in Make. + +@item assume-old +@samp{-o} in Make. + +@item backward-search +@samp{-B} in etags. + +@item batch +Used in GDB. + +@item baud +Used in GDB. + +@item before +@samp{-b} in @code{tac}. + +@item binary +@samp{-b} in @code{cpio} and @code{diff}. + +@item block-size +Used in @code{cpio} and @code{tar}. + +@item blocks +@samp{-b} in @code{head} and @code{tail}. + +@item break-file +@samp{-b} in @code{ptx}. + +@item brief +Used in various programs to make output shorter. + +@item bytes +@samp{-c} in @code{head}, @code{split}, and @code{tail}. + +@item c++ +@samp{-C} in @code{etags}. + +@item catenate +@samp{-A} in @code{tar}. + +@item cd +Used in various programs to specify the directory to use. + +@item changes +@samp{-c} in @code{chgrp} and @code{chown}. + +@item classify +@samp{-F} in @code{ls}. + +@item colons +@samp{-c} in @code{recode}. + +@item command +@samp{-c} in @code{su}; +@samp{-x} in GDB. + +@item compare +@samp{-d} in @code{tar}. + +@item compress +@samp{-Z} in @code{tar}. + +@item concatenate +@samp{-A} in @code{tar}. + +@item confirmation +@samp{-w} in @code{tar}. + +@item context +Used in @code{diff}. + +@item copyright +@samp{-C} in @code{ptx} and @code{recode}. + +@item core +Used in GDB. + +@item count +@samp{-q} in @code{who}. + +@item count-links +@samp{-l} in @code{du}. + +@item create +Used in @code{tar} and @code{cpio}. + +@item cxref +@samp{-x} in @code{etags}. + +@item date +@samp{-d} in @code{touch}. + +@item debug +@samp{-d} in Make and @code{m4}; +@samp{-t} in Bison. + +@item define +@samp{-D} in @code{m4}. + +@item defines +@samp{-d} in Bison and @code{etags}. + +@item delete +@samp{-D} in @code{tar}. + +@item dereference +@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, +@code{ls}, and @code{tar}. + +@item dereference-args +@samp{-D} in @code{du}. + +@item diacritics +@samp{-d} in @code{recode}. + +@item dictionary-order +@samp{-d} in @code{look}. + +@item diff +@samp{-d} in @code{tar}. + +@item digits +@samp{-n} in @code{csplit}. + +@item directory +Specify the directory to use, in various programs. In @code{ls}, it +means to show directories themselves rather than their contents. In +@code{rm} and @code{ln}, it means to not treat links to directories +specially. + +@item discard-all +@samp{-x} in @code{strip}. + +@item discard-locals +@samp{-X} in @code{strip}. + +@item diversions +@samp{-N} in @code{m4}. + +@item dry-run +@samp{-n} in Make. + +@item ed +@samp{-e} in @code{diff}. + +@item elide-empty-files +@samp{-z} in @code{csplit}. + +@item entire-new-file +@samp{-N} in @code{diff}. + +@item environment-overrides +@samp{-e} in Make. + +@item eof +@samp{-e} in @code{xargs}. + +@item epoch +Used in GDB. + +@item error-limit +Used in Makeinfo. + +@item error-output +@samp{-o} in @code{m4}. + +@item escape +@samp{-b} in @code{ls}. + +@item exclude-from +@samp{-X} in @code{tar}. + +@item exec +Used in GDB. + +@item exit +@samp{-x} in @code{xargs}. + +@item expand-tabs +@samp{-t} in @code{diff}. + +@item expression +@samp{-e} in @code{sed}. + +@item extern-only +@samp{-g} in @code{nm}. + +@item extract +@samp{-i} in @code{cpio}; +@samp{-x} in @code{tar}. + +@item faces +@samp{-f} in @code{finger}. + +@item fast +@samp{-f} in @code{su}. + +@item file +@samp{-f} in @code{info}, Make, @code{mt}, and @code{tar}; +@samp{-n} in @code{sed}; +@samp{-r} in @code{touch}. + +@item file-prefix +@samp{-b} in Bison. + +@item file-type +@samp{-F} in @code{ls}. + +@item files-from +@samp{-T} in @code{tar}. + +@item fill-column +Used in Makeinfo. + +@item flag-truncation +@samp{-F} in @code{ptx}. + +@item fixed-output-files +@samp{-y} in Bison. + +@item follow +@samp{-f} in @code{tail}. + +@item footnote-style +Used in Makeinfo. + +@item force +@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. + +@item format +Used in @code{ls}, @code{time}, and @code{ptx}. + +@item forward-search +@samp{-F} in @code{etags}. + +@item fullname +Used in GDB. + +@item gap-size +@samp{-g} in @code{ptx}. + +@item get +@samp{-x} in @code{tar}. + +@item graphic +@samp{-i} in @code{ul}. + +@item graphics +@samp{-g} in @code{recode}. + +@item group +@samp{-g} in @code{install}. + +@item gzip +@samp{-z} in @code{tar}. + +@item hashsize +@samp{-H} in @code{m4}. + +@item header +@samp{-h} in @code{objdump} and @code{recode} + +@item heading +@samp{-H} in @code{who}. + +@item help +Used to ask for brief usage information. + +@item hide-control-chars +@samp{-q} in @code{ls}. + +@item idle +@samp{-u} in @code{who}. + +@item ifdef +@samp{-D} in @code{diff}. + +@item ignore +@samp{-I} in @code{ls}; +@samp{-x} in @code{recode}. + +@item ignore-all-space +@samp{-w} in @code{diff}. + +@item ignore-backups +@samp{-B} in @code{ls}. + +@item ignore-blank-lines +@samp{-B} in @code{diff}. + +@item ignore-case +@samp{-f} in @code{look} and @code{ptx}; +@samp{-i} in @code{diff}. + +@item ignore-errors +@samp{-i} in Make. + +@item ignore-file +@samp{-i} in @code{ptx}. + +@item ignore-indentation +@samp{-S} in @code{etags}. + +@item ignore-init-file +@samp{-f} in Oleo. + +@item ignore-interrupts +@samp{-i} in @code{tee}. + +@item ignore-matching-lines +@samp{-I} in @code{diff}. + +@item ignore-space-change +@samp{-b} in @code{diff}. + +@item ignore-zeros +@samp{-i} in @code{tar}. + +@item include +@samp{-i} in @code{etags}; +@samp{-I} in @code{m4}. + +@item include-dir +@samp{-I} in Make. + +@item incremental +@samp{-G} in @code{tar}. + +@item info +@samp{-i}, @samp{-l}, and @samp{-m} in Finger. + +@item initial +@samp{-i} in @code{expand}. + +@item initial-tab +@samp{-T} in @code{diff}. + +@item inode +@samp{-i} in @code{ls}. + +@item interactive +@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; +@samp{-e} in @code{m4}; +@samp{-p} in @code{xargs}; +@samp{-w} in @code{tar}. + +@item jobs +@samp{-j} in Make. + +@item just-print +@samp{-n} in Make. + +@item keep-going +@samp{-k} in Make. + +@item keep-files +@samp{-k} in @code{csplit}. + +@item kilobytes +@samp{-k} in @code{du} and @code{ls}. + +@item line-bytes +@samp{-C} in @code{split}. + +@item lines +Used in @code{split}, @code{head}, and @code{tail}. + +@item link +@samp{-l} in @code{cpio}. + +@item list +@samp{-t} in @code{cpio}; +@samp{-l} in @code{recode}. + +@item list +@samp{-t} in @code{tar}. + +@item literal +@samp{-N} in @code{ls}. + +@item load-average +@samp{-l} in Make. + +@item login +Used in @code{su}. + +@item machine +No listing of which programs already use this; +someone should check to +see if any actually do and tell @code{gnu@@prep.ai.mit.edu}. + +@item macro-name +@samp{-M} in @code{ptx}. + +@item mail +@samp{-m} in @code{hello} and @code{uname}. + +@item make-directories +@samp{-d} in @code{cpio}. + +@item makefile +@samp{-f} in Make. + +@item mapped +Used in GDB. + +@item max-args +@samp{-n} in @code{xargs}. + +@item max-chars +@samp{-n} in @code{xargs}. + +@item max-lines +@samp{-l} in @code{xargs}. + +@item max-load +@samp{-l} in Make. + +@item max-procs +@samp{-P} in @code{xargs}. + +@item mesg +@samp{-T} in @code{who}. + +@item message +@samp{-T} in @code{who}. + +@item minimal +@samp{-d} in @code{diff}. + +@item mode +@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. + +@item modification-time +@samp{-m} in @code{tar}. + +@item multi-volume +@samp{-M} in @code{tar}. + +@item name-prefix +@samp{-a} in Bison. + +@item new-file +@samp{-W} in Make. + +@item no-builtin-rules +@samp{-r} in Make. + +@item no-create +@samp{-c} in @code{touch}. + +@item no-defines +@samp{-D} in @code{etags}. + +@item no-dereference +@samp{-d} in @code{cp}. + +@item no-keep-going +@samp{-S} in Make. + +@item no-lines +@samp{-l} in Bison. + +@item no-prof +@samp{-e} in @code{gprof}. + +@item no-sort +@samp{-p} in @code{nm}. + +@item no-split +Used in Makeinfo. + +@item no-static +@samp{-a} in @code{gprof}. + +@item no-time +@samp{-E} in @code{gprof}. + +@item no-validate +Used in Makeinfo. + +@item no-warn +Used in various programs to inhibit warnings. + +@item node +@samp{-n} in @code{info}. + +@item nodename +@samp{-n} in @code{uname}. + +@item nonmatching +@samp{-f} in @code{cpio}. + +@item nstuff +@samp{-n} in @code{objdump}. + +@item null +@samp{-0} in @code{xargs}. + +@item number +@samp{-n} in @code{cat}. + +@item number-nonblank +@samp{-b} in @code{cat}. + +@item numeric-sort +@samp{-n} in @code{nm}. + +@item numeric-uid-gid +@samp{-n} in @code{cpio} and @code{ls}. + +@item nx +Used in GDB. + +@item old-archive +@samp{-o} in @code{tar}. + +@item old-file +@samp{-o} in Make. + +@item one-file-system +@samp{-l} in @code{tar}, @code{cp}, and @code{du}. + +@item only-file +@samp{-o} in @code{ptx}. + +@item only-prof +@samp{-f} in @code{gprof}. + +@item only-time +@samp{-F} in @code{gprof}. + +@item output +In various programs, specify the output file name. + +@item override +@samp{-o} in @code{rm}. + +@item owner +@samp{-o} in @code{install}. + +@item paginate +@samp{-l} in @code{diff}. + +@item paragraph-indent +Used in Makeinfo. + +@item parents +@samp{-p} in @code{mkdir} and @code{rmdir}. + +@item pass-all +@samp{-p} in @code{ul}. + +@item pass-through +@samp{-p} in @code{cpio}. + +@item port +@samp{-P} in @code{finger}. + +@item portability +@samp{-c} in @code{cpio} and @code{tar}. + +@item prefix-builtins +@samp{-P} in @code{m4}. + +@item prefix +@samp{-f} in @code{csplit}. + +@item preserve +Used in @code{tar} and @code{cp}. + +@item preserve-environment +@samp{-p} in @code{su}. + +@item preserve-modification-time +@samp{-m} in @code{cpio}. + +@item preserve-order +@samp{-s} in @code{tar}. + +@item preserve-permissions +@samp{-p} in @code{tar}. + +@item print +@samp{-l} in @code{diff}. + +@item print-chars +@samp{-L} in @code{cmp}. + +@item print-data-base +@samp{-p} in Make. + +@item print-directory +@samp{-w} in Make. + +@item print-file-name +@samp{-o} in @code{nm}. + +@item print-symdefs +@samp{-s} in @code{nm}. + +@item question +@samp{-q} in Make. + +@item quiet +Used in many programs to inhibit the usual output. @strong{Note:} every +program accepting @samp{--quiet} should accept @samp{--silent} as a +synonym. + +@item quote-name +@samp{-Q} in @code{ls}. + +@item rcs +@samp{-n} in @code{diff}. + +@item read-full-blocks +@samp{-B} in @code{tar}. + +@item readnow +Used in GDB. + +@item recon +@samp{-n} in Make. + +@item record-number +@samp{-R} in @code{tar}. + +@item recursive +Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, +and @code{rm}. + +@item reference-limit +Used in Makeinfo. + +@item references +@samp{-r} in @code{ptx}. + +@item regex +@samp{-r} in @code{tac}. + +@item release +@samp{-r} in @code{uname}. + +@item relocation +@samp{-r} in @code{objdump}. + +@item rename +@samp{-r} in @code{cpio}. + +@item replace +@samp{-i} in @code{xargs}. + +@item report-identical-files +@samp{-s} in @code{diff}. + +@item reset-access-time +@samp{-a} in @code{cpio}. + +@item reverse +@samp{-r} in @code{ls} and @code{nm}. + +@item reversed-ed +@samp{-f} in @code{diff}. + +@item right-side-defs +@samp{-R} in @code{ptx}. + +@item same-order +@samp{-s} in @code{tar}. + +@item same-permissions +@samp{-p} in @code{tar}. + +@item save +@samp{-g} in @code{stty}. + +@item se +Used in GDB. + +@item sentence-regexp +@samp{-S} in @code{ptx}. + +@item separate-dirs +@samp{-S} in @code{du}. + +@item separator +@samp{-s} in @code{tac}. + +@item sequence +Used by @code{recode} to chose files or pipes for sequencing passes. + +@item shell +@samp{-s} in @code{su}. + +@item show-all +@samp{-A} in @code{cat}. + +@item show-c-function +@samp{-p} in @code{diff}. + +@item show-ends +@samp{-E} in @code{cat}. + +@item show-function-line +@samp{-F} in @code{diff}. + +@item show-tabs +@samp{-T} in @code{cat}. + +@item silent +Used in many programs to inhibit the usual output. +@strong{Note:} every program accepting +@samp{--silent} should accept @samp{--quiet} as a synonym. + +@item size +@samp{-s} in @code{ls}. + +@item sort +Used in @code{ls}. + +@item sparse +@samp{-S} in @code{tar}. + +@item speed-large-files +@samp{-H} in @code{diff}. + +@item squeeze-blank +@samp{-s} in @code{cat}. + +@item starting-file +Used in @code{tar} and @code{diff} to specify which file within +a directory to start processing with. + +@item stop +@samp{-S} in Make. + +@item strict +@samp{-s} in @code{recode}. + +@item strip +@samp{-s} in @code{install}. + +@item strip-all +@samp{-s} in @code{strip}. + +@item strip-debug +@samp{-S} in @code{strip}. + +@item suffix +@samp{-S} in @code{cp}, @code{ln}, @code{mv}. + +@item suffix-format +@samp{-b} in @code{csplit}. + +@item sum +@samp{-s} in @code{gprof}. + +@item summarize +@samp{-s} in @code{du}. + +@item symbolic +@samp{-s} in @code{ln}. + +@item symbols +Used in GDB and @code{objdump}. + +@item synclines +@samp{-s} in @code{m4}. + +@item sysname +@samp{-s} in @code{uname}. + +@item tabs +@samp{-t} in @code{expand} and @code{unexpand}. + +@item tabsize +@samp{-T} in @code{ls}. + +@item terminal +@samp{-T} in @code{tput} and @code{ul}. + +@item text +@samp{-a} in @code{diff}. + +@item time +Used in @code{ls} and @code{touch}. + +@item to-stdout +@samp{-O} in @code{tar}. + +@item total +@samp{-c} in @code{du}. + +@item touch +@samp{-t} in Make, @code{ranlib}, and @code{recode}. + +@item trace +@samp{-t} in @code{m4}. + +@item traditional +@samp{-t} in @code{hello}; +@samp{-G} in @code{m4} and @code{ptx}. + +@item tty +Used in GDB. + +@item typedefs +@samp{-t} in @code{etags}. + +@item typedefs-and-c++ +@samp{-T} in @code{etags}. + +@item typeset-mode +@samp{-t} in @code{ptx}. + +@item uncompress +@samp{-z} in @code{tar}. + +@item unconditional +@samp{-u} in @code{cpio}. + +@item undefine +@samp{-U} in @code{m4}. + +@item undefined-only +@samp{-u} in @code{nm}. + +@item update +@samp{-u} in @code{cp}, @samp{etags}, @samp{mv}, @samp{tar}. + +@item verbose +Print more information about progress. Many programs support this. + +@item verify +@samp{-W} in @code{tar}. + +@item version +Print the version number. + +@item version-control +@samp{-V} in @code{cp}, @code{ln}, @code{mv}. + +@item vgrind +@samp{-v} in @code{etags}. + +@item volume +@samp{-V} in @code{tar}. + +@item what-if +@samp{-W} in Make. + +@item width +@samp{-w} in @code{ls} and @code{ptx}. + +@item word-regexp +@samp{-W} in @code{ptx}. + +@item writable +@samp{-T} in @code{who}. + +@item zeros +@samp{-z} in @code{gprof}. + +@end table + +@node Documentation +@chapter Documenting Programs + +Please use Texinfo for documenting GNU programs. See the Texinfo +manual, either the hardcopy or the version in the GNU Emacs Info +subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g., those +under the @file{man/} directory in the GNU Emacs distribution) for +examples. + +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 +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 document all command-line arguments and all +commands. It should give examples of their use. But don't organize +the manual as a list of features. Instead, organize it by the +concepts a user will have before reaching that point in the manual. +Address the goals that a user will have in mind, and explain how to +accomplish them. Don't use Unix man pages as a model for how to +write GNU documentation; they are a bad example to follow. + +The manual should have a node named @samp{@var{program} Invocation} or +@samp{Invoking @var{program}}, where @var{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 +@samp{@@example} containing a template for all the options and arguments +that the program uses. + +Alternatively, put a menu item in some menu whose item name fits one of +the above patterns. This identifies the node which that item points to +as the node for this purpose, regardless of the node's actual name. + +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. + +In addition to its manual, the package should have a file named +@file{NEWS} which contains a list of user-visible changes worth +mentioning. In each new release, add items to the front of the file and +identify the version they pertain to. Don't discard old items; leave +them in the file after the newer items. This way, a user upgrading from +any previous version can see what is new. + +If the @file{NEWS} file gets very long, move some of the older items +into a file named @file{ONEWS} and put a note at the end referring the +user to that file. + +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. + +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 +documentation. + +@node Releases +@chapter 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 +named @file{foo-69.96}. + +Building and installing the program should never modify any of the files +contained in the distribution. This means that all the files that form +part of the program in any way must be classified into @dfn{source +files} and @dfn{non-source files}. Source files are written by humans +and never changed automatically; non-source files are produced from +source files by programs under the control of the Makefile. + +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 @strong{never} be included in the +distribution. So if you do distribute non-source files, always make +sure they are up to date when you make a new distribution. + +Make sure that the directory into which the distribution unpacks (as +well as any subdirectories) are all world-writable (octal mode 777). +This is so that old versions of @code{tar} which preserve the +ownership and permissions of the files from the tar archive will be +able to extract all the files even if the user is unprivileged. + +Make sure that all the files in the distribution are world-readable. + +Make sure that no file name in the distribution is more than 14 +characters long. Likewise, no file created by building the program +should have a name longer than 14 characters. The reason for this is +that some systems adhere to a foolish interpretation of the 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-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 +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. + +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. + +@contents + +@bye diff --git a/src/util/autoconf/texinfo.tex b/src/util/autoconf/texinfo.tex new file mode 100644 index 000000000..65f5d06cc --- /dev/null +++ b/src/util/autoconf/texinfo.tex @@ -0,0 +1,4137 @@ +%% TeX macros to handle texinfo files + +% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 1994 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 +%published by the Free Software Foundation; either version 2, or (at +%your option) any later version. + +%This texinfo.tex file is distributed in the hope that it will be +%useful, but WITHOUT ANY WARRANTY; without even the implied warranty +%of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +%General Public License for more details. + +%You should have received a copy of the GNU General Public License +%along with this texinfo.tex file; see the file COPYING. If not, write +%to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, +%USA. + + +%In other words, you are welcome to use, share and improve this program. +%You are forbidden to forbid anyone else to use, share and improve +%what you give them. Help stamp out software-hoarding! + +% This automatically updates the version number based on RCS. +\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} +\deftexinfoversion$Revision$ +\message{Loading texinfo package [Version \texinfoversion]:} + +% Print the version number if in a .fmt file. +\everyjob{\message{[Texinfo version \texinfoversion]}\message{}} + +% Save some parts of plain tex whose names we will redefine. + +\let\ptextilde=\~ +\let\ptexlbrace=\{ +\let\ptexrbrace=\} +\let\ptexdots=\dots +\let\ptexdot=\. +\let\ptexstar=\* +\let\ptexend=\end +\let\ptexbullet=\bullet +\let\ptexb=\b +\let\ptexc=\c +\let\ptexi=\i +\let\ptext=\t +\let\ptexl=\l +\let\ptexL=\L + +\def\tie{\penalty 10000\ } % Save plain tex definition of ~. +\let\~ = \tie % And make it available as @~. + +\message{Basics,} +\chardef\other=12 + +% If this character appears in an error message or help string, it +% starts a new line in the output. +\newlinechar = `^^J + +% Set up fixed words for English. +\ifx\putwordChapter\undefined{\gdef\putwordChapter{Chapter}}\fi% +\def\putwordInfo{Info}% +\ifx\putwordSee\undefined{\gdef\putwordSee{See}}\fi% +\ifx\putwordsee\undefined{\gdef\putwordsee{see}}\fi% +\ifx\putwordfile\undefined{\gdef\putwordfile{file}}\fi% +\ifx\putwordpage\undefined{\gdef\putwordpage{page}}\fi% +\ifx\putwordsection\undefined{\gdef\putwordsection{section}}\fi% +\ifx\putwordSection\undefined{\gdef\putwordSection{Section}}\fi% +\ifx\putwordTableofContents\undefined{\gdef\putwordTableofContents{Table of Contents}}\fi% +\ifx\putwordShortContents\undefined{\gdef\putwordShortContents{Short Contents}}\fi% +\ifx\putwordAppendix\undefined{\gdef\putwordAppendix{Appendix}}\fi% + +% Ignore a token. +% +\def\gobble#1{} + +\hyphenation{ap-pen-dix} +\hyphenation{mini-buf-fer mini-buf-fers} +\hyphenation{eshell} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen \bindingoffset \bindingoffset=0pt +\newdimen \normaloffset \normaloffset=\hoffset +\newdimen\pagewidth \newdimen\pageheight +\pagewidth=\hsize \pageheight=\vsize + +% Sometimes it is convenient to have everything in the transcript file +% and nothing on the terminal. We don't just call \tracingall here, +% since that produces some useless output on the terminal. +% +\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% +\def\loggingall{\tracingcommands2 \tracingstats2 + \tracingpages1 \tracingoutput1 \tracinglostchars1 + \tracingmacros2 \tracingparagraphs1 \tracingrestores1 + \showboxbreadth\maxdimen\showboxdepth\maxdimen +}% + +%---------------------Begin change----------------------- +% +%%%% For @cropmarks command. +% Dimensions to add cropmarks at corners Added by P. A. MacKay, 12 Nov. 1986 +% +\newdimen\cornerlong \newdimen\cornerthick +\newdimen \topandbottommargin +\newdimen \outerhsize \newdimen \outervsize +\cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks +\outerhsize=7in +%\outervsize=9.5in +% Alternative @smallbook page size is 9.25in +\outervsize=9.25in +\topandbottommargin=.75in +% +%---------------------End change----------------------- + +% \onepageout takes a vbox as an argument. Note that \pagecontents +% does insertions itself, but you have to call it yourself. +\chardef\PAGE=255 \output={\onepageout{\pagecontents\PAGE}} +\def\onepageout#1{\hoffset=\normaloffset +\ifodd\pageno \advance\hoffset by \bindingoffset +\else \advance\hoffset by -\bindingoffset\fi +{\escapechar=`\\\relax % makes sure backslash is used in output files. +\shipout\vbox{{\let\hsize=\pagewidth \makeheadline} \pagebody{#1}% +{\let\hsize=\pagewidth \makefootline}}}% +\advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi} + +%%%% For @cropmarks command %%%% + +% Here is a modification of the main output routine for Near East Publications +% This provides right-angle cropmarks at all four corners. +% The contents of the page are centerlined into the cropmarks, +% and any desired binding offset is added as an \hskip on either +% site of the centerlined box. (P. A. MacKay, 12 November, 1986) +% +\def\croppageout#1{\hoffset=0pt % make sure this doesn't mess things up +{\escapechar=`\\\relax % makes sure backslash is used in output files. + \shipout + \vbox to \outervsize{\hsize=\outerhsize + \vbox{\line{\ewtop\hfill\ewtop}} + \nointerlineskip + \line{\vbox{\moveleft\cornerthick\nstop} + \hfill + \vbox{\moveright\cornerthick\nstop}} + \vskip \topandbottommargin + \centerline{\ifodd\pageno\hskip\bindingoffset\fi + \vbox{ + {\let\hsize=\pagewidth \makeheadline} + \pagebody{#1} + {\let\hsize=\pagewidth \makefootline}} + \ifodd\pageno\else\hskip\bindingoffset\fi} + \vskip \topandbottommargin plus1fill minus1fill + \boxmaxdepth\cornerthick + \line{\vbox{\moveleft\cornerthick\nsbot} + \hfill + \vbox{\moveright\cornerthick\nsbot}} + \nointerlineskip + \vbox{\line{\ewbot\hfill\ewbot}} + }} + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi} +% +% Do @cropmarks to get crop marks +\def\cropmarks{\let\onepageout=\croppageout } + +\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} +{\catcode`\@ =11 +\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi +\dimen@=\dp#1 \unvbox#1 +\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi +\ifr@ggedbottom \kern-\dimen@ \vfil \fi} +} + +% +% Here are the rules for the cropmarks. Note that they are +% offset so that the space between them is truly \outerhsize or \outervsize +% (P. A. MacKay, 12 November, 1986) +% +\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} +\def\nstop{\vbox + {\hrule height\cornerthick depth\cornerlong width\cornerthick}} +\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} +\def\nsbot{\vbox + {\hrule height\cornerlong depth\cornerthick width\cornerthick}} + +% Parse an argument, then pass it to #1. The argument is the rest of +% the input line (except we remove a trailing comment). #1 should be a +% macro which expects an ordinary undelimited TeX argument. +% +\def\parsearg#1{% + \let\next = #1% + \begingroup + \obeylines + \futurelet\temp\parseargx +} + +% If the next token is an obeyed space (from an @example environment or +% the like), remove it and recurse. Otherwise, we're done. +\def\parseargx{% + % \obeyedspace is defined far below, after the definition of \sepspaces. + \ifx\obeyedspace\temp + \expandafter\parseargdiscardspace + \else + \expandafter\parseargline + \fi +} + +% Remove a single space (as the delimiter token to the macro call). +{\obeyspaces % + \gdef\parseargdiscardspace {\futurelet\temp\parseargx}} + +{\obeylines % + \gdef\parseargline#1^^M{% + \endgroup % End of the group started in \parsearg. + % + % First remove any @c comment, then any @comment. + % Result of each macro is put in \toks0. + \argremovec #1\c\relax % + \expandafter\argremovecomment \the\toks0 \comment\relax % + % + % Call the caller's macro, saved as \next in \parsearg. + \expandafter\next\expandafter{\the\toks0}% + }% +} + +% Since all \c{,omment} does is throw away the argument, we can let TeX +% do that for us. The \relax here is matched by the \relax in the call +% in \parseargline; it could be more or less anything, its purpose is +% just to delimit the argument to the \c. +\def\argremovec#1\c#2\relax{\toks0 = {#1}} +\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}} + +% \argremovec{,omment} might leave us with trailing spaces, though; e.g., +% @end itemize @c foo +% will have two active spaces as part of the argument with the +% `itemize'. Here we remove all active spaces from #1, and assign the +% result to \toks0. +% +% This loses if there are any *other* active characters besides spaces +% in the argument -- _ ^ +, for example -- since they get expanded. +% Fortunately, Texinfo does not define any such commands. (If it ever +% does, the catcode of the characters in questionwill have to be changed +% here.) But this means we cannot call \removeactivespaces as part of +% \argremovec{,omment}, since @c uses \parsearg, and thus the argument +% that \parsearg gets might well have any character at all in it. +% +\def\removeactivespaces#1{% + \begingroup + \ignoreactivespaces + \edef\temp{#1}% + \global\toks0 = \expandafter{\temp}% + \endgroup +} + +% Change the active space to expand to nothing. +% +\begingroup + \obeyspaces + \gdef\ignoreactivespaces{\obeyspaces\let =\empty} +\endgroup + + +\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} + +%% These are used to keep @begin/@end levels from running away +%% Call \inENV within environments (after a \begingroup) +\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi} +\def\ENVcheck{% +\ifENV\errmessage{Still within an environment. Type Return to continue.} +\endgroup\fi} % This is not perfect, but it should reduce lossage + +% @begin foo is the same as @foo, for now. +\newhelp\EMsimple{Type to continue.} + +\outer\def\begin{\parsearg\beginxxx} + +\def\beginxxx #1{% +\expandafter\ifx\csname #1\endcsname\relax +{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else +\csname #1\endcsname\fi} + +% @end foo executes the definition of \Efoo. +% +\def\end{\parsearg\endxxx} +\def\endxxx #1{% + \removeactivespaces{#1}% + \edef\endthing{\the\toks0}% + % + \expandafter\ifx\csname E\endthing\endcsname\relax + \expandafter\ifx\csname \endthing\endcsname\relax + % There's no \foo, i.e., no ``environment'' foo. + \errhelp = \EMsimple + \errmessage{Undefined command `@end \endthing'}% + \else + \unmatchedenderror\endthing + \fi + \else + % Everything's ok; the right environment has been started. + \csname E\endthing\endcsname + \fi +} + +% There is an environment #1, but it hasn't been started. Give an error. +% +\def\unmatchedenderror#1{% + \errhelp = \EMsimple + \errmessage{This `@end #1' doesn't have a matching `@#1'}% +} + +% Define the control sequence \E#1 to give an unmatched @end error. +% +\def\defineunmatchedend#1{% + \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}% +} + + +% Single-spacing is done by various environments (specifically, in +% \nonfillstart and \quotations). +\newskip\singlespaceskip \singlespaceskip = 12.5pt +\def\singlespace{% + % Why was this kern here? It messes up equalizing space above and below + % environments. --karl, 6may93 + %{\advance \baselineskip by -\singlespaceskip + %\kern \baselineskip}% + \setleading \singlespaceskip +} + +%% Simple single-character @ commands + +% @@ prints an @ +% Kludge this until the fonts are right (grr). +\def\@{{\tt \char '100}} + +% This is turned off because it was never documented +% and you can use @w{...} around a quote to suppress ligatures. +%% Define @` and @' to be the same as ` and ' +%% but suppressing ligatures. +%\def\`{{`}} +%\def\'{{'}} + +% Used to generate quoted braces. + +\def\mylbrace {{\tt \char '173}} +\def\myrbrace {{\tt \char '175}} +\let\{=\mylbrace +\let\}=\myrbrace + +% @: forces normal size whitespace following. +\def\:{\spacefactor=1000 } + +% @* forces a line break. +\def\*{\hfil\break\hbox{}\ignorespaces} + +% @. is an end-of-sentence period. +\def\.{.\spacefactor=3000 } + +% @w prevents a word break. Without the \leavevmode, @w at the +% beginning of a paragraph, when TeX is still in vertical mode, would +% produce a whole line of output instead of starting the paragraph. +\def\w#1{\leavevmode\hbox{#1}} + +% @group ... @end group forces ... to be all on one page, by enclosing +% it in a TeX vbox. We use \vtop instead of \vbox to construct the box +% to keep its height that of a normal line. According to the rules for +% \topskip (p.114 of the TeXbook), the glue inserted is +% max (\topskip - \ht (first item), 0). If that height is large, +% therefore, no glue is inserted, and the space between the headline and +% the text is small, which looks bad. +% +\def\group{\begingroup + \ifnum\catcode13=\active \else + \errhelp = \groupinvalidhelp + \errmessage{@group invalid in context where filling is enabled}% + \fi + % + % The \vtop we start below produces a box with normal height and large + % depth; thus, TeX puts \baselineskip glue before it, and (when the + % next line of text is done) \lineskip glue after it. (See p.82 of + % the TeXbook.) Thus, space below is not quite equal to space + % above. But it's pretty close. + \def\Egroup{% + \egroup % End the \vtop. + \endgroup % End the \group. + }% + % + \vtop\bgroup + % We have to put a strut on the last line in case the @group is in + % the midst of an example, rather than completely enclosing it. + % Otherwise, the interline space between the last line of the group + % and the first line afterwards is too small. But we can't put the + % strut in \Egroup, since there it would be on a line by itself. + % Hence this just inserts a strut at the beginning of each line. + \everypar = {\strut}% + % + % Since we have a strut on every line, we don't need any of TeX's + % normal interline spacing. + \offinterlineskip + % + % OK, but now we have to do something about blank + % lines in the input in @example-like environments, which normally + % just turn into \lisppar, which will insert no space now that we've + % turned off the interline space. Simplest is to make them be an + % empty paragraph. + \ifx\par\lisppar + \edef\par{\leavevmode \par}% + % + % Reset ^^M's definition to new definition of \par. + \obeylines + \fi + % + % Do @comment since we are called inside an environment such as + % @example, where each end-of-line in the input causes an + % end-of-line in the output. We don't want the end-of-line after + % the `@group' to put extra space in the output. Since @group + % should appear on a line by itself (according to the Texinfo + % manual), we don't worry about eating any user text. + \comment +} +% +% TeX puts in an \escapechar (i.e., `@') at the beginning of the help +% message, so this ends up printing `@group can only ...'. +% +\newhelp\groupinvalidhelp{% +group can only be used in environments such as @example,^^J% +where each line of input produces a line of output.} + +% @need space-in-mils +% forces a page break if there is not space-in-mils remaining. + +\newdimen\mil \mil=0.001in + +\def\need{\parsearg\needx} + +% Old definition--didn't work. +%\def\needx #1{\par % +%% This method tries to make TeX break the page naturally +%% if the depth of the box does not fit. +%{\baselineskip=0pt% +%\vtop to #1\mil{\vfil}\kern -#1\mil\penalty 10000 +%\prevdepth=-1000pt +%}} + +\def\needx#1{% + % Go into vertical mode, so we don't make a big box in the middle of a + % paragraph. + \par + % + % Don't add any leading before our big empty box, but allow a page + % break, since the best break might be right here. + \allowbreak + \nointerlineskip + \vtop to #1\mil{\vfil}% + % + % TeX does not even consider page breaks if a penalty added to the + % main vertical list is 10000 or more. But in order to see if the + % empty box we just added fits on the page, we must make it consider + % page breaks. On the other hand, we don't want to actually break the + % page after the empty box. So we use a penalty of 9999. + % + % There is an extremely small chance that TeX will actually break the + % page at this \penalty, if there are no other feasible breakpoints in + % sight. (If the user is using lots of big @group commands, which + % almost-but-not-quite fill up a page, TeX will have a hard time doing + % good page breaking, for example.) However, I could not construct an + % example where a page broke at this \penalty; if it happens in a real + % document, then we can reconsider our strategy. + \penalty9999 + % + % Back up by the size of the box, whether we did a page break or not. + \kern -#1\mil + % + % Do not allow a page break right after this kern. + \nobreak +} + +% @br forces paragraph break + +\let\br = \par + +% @dots{} output some dots + +\def\dots{$\ldots$} + +% @page forces the start of a new page + +\def\page{\par\vfill\supereject} + +% @exdent text.... +% outputs text on separate line in roman font, starting at standard page margin + +% This records the amount of indent in the innermost environment. +% That's how much \exdent should take out. +\newskip\exdentamount + +% This defn is used inside fill environments such as @defun. +\def\exdent{\parsearg\exdentyyy} +\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}} + +% This defn is used inside nofill environments such as @example. +\def\nofillexdent{\parsearg\nofillexdentyyy} +\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount +\leftline{\hskip\leftskip{\rm#1}}}} + +%\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 +\endgroup} + +\def\thisfile{} + +% @center line outputs that line, centered + +\def\center{\parsearg\centerzzz} +\def\centerzzz #1{{\advance\hsize by -\leftskip +\advance\hsize by -\rightskip +\centerline{#1}}} + +% @sp n outputs n lines of vertical space + +\def\sp{\parsearg\spxxx} +\def\spxxx #1{\par \vskip #1\baselineskip} + +% @comment ...line which is ignored... +% @c is the same as @comment +% @ignore ... @end ignore is another way to write a comment + +\def\comment{\catcode 64=\other \catcode 123=\other \catcode 125=\other% +\parsearg \commentxxx} + +\def\commentxxx #1{\catcode 64=0 \catcode 123=1 \catcode 125=2 } + +\let\c=\comment + +% Prevent errors for section commands. +% Used in @ignore and in failing conditionals. +\def\ignoresections{% +\let\chapter=\relax +\let\unnumbered=\relax +\let\top=\relax +\let\unnumberedsec=\relax +\let\unnumberedsection=\relax +\let\unnumberedsubsec=\relax +\let\unnumberedsubsection=\relax +\let\unnumberedsubsubsec=\relax +\let\unnumberedsubsubsection=\relax +\let\section=\relax +\let\subsec=\relax +\let\subsubsec=\relax +\let\subsection=\relax +\let\subsubsection=\relax +\let\appendix=\relax +\let\appendixsec=\relax +\let\appendixsection=\relax +\let\appendixsubsec=\relax +\let\appendixsubsection=\relax +\let\appendixsubsubsec=\relax +\let\appendixsubsubsection=\relax +\let\contents=\relax +\let\smallbook=\relax +\let\titlepage=\relax +} + +% Used in nested conditionals, where we have to parse the Texinfo source +% and so want to turn off most commands, in case they are used +% incorrectly. +% +\def\ignoremorecommands{% + \let\defcv = \relax + \let\deffn = \relax + \let\deffnx = \relax + \let\defindex = \relax + \let\defivar = \relax + \let\defmac = \relax + \let\defmethod = \relax + \let\defop = \relax + \let\defopt = \relax + \let\defspec = \relax + \let\deftp = \relax + \let\deftypefn = \relax + \let\deftypefun = \relax + \let\deftypevar = \relax + \let\deftypevr = \relax + \let\defun = \relax + \let\defvar = \relax + \let\defvr = \relax + \let\ref = \relax + \let\xref = \relax + \let\printindex = \relax + \let\pxref = \relax + \let\settitle = \relax + \let\include = \relax + \let\lowersections = \relax + \let\down = \relax + \let\raisesections = \relax + \let\up = \relax + \let\set = \relax + \let\clear = \relax + \let\item = \relax + \let\message = \relax +} + +% Ignore @ignore ... @end ignore. +% +\def\ignore{\doignore{ignore}} + +% Also ignore @ifinfo, @menu, and @direntry text. +% +\def\ifinfo{\doignore{ifinfo}} +\def\menu{\doignore{menu}} +\def\direntry{\doignore{direntry}} + +% Ignore text until a line `@end #1'. +% +\def\doignore#1{\begingroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define a command to swallow text until we reach `@end #1'. + \long\def\doignoretext##1\end #1{\enddoignore}% + % + % Make sure that spaces turn into tokens that match what \doignoretext wants. + \catcode32 = 10 + % + % And now expand that command. + \doignoretext +} + +% What we do to finish off ignored text. +% +\def\enddoignore{\endgroup\ignorespaces}% + +\newif\ifwarnedobs\warnedobsfalse +\def\obstexwarn{% + \ifwarnedobs\relax\else + % We need to warn folks that they may have trouble with TeX 3.0. + % This uses \immediate\write16 rather than \message to get newlines. + \immediate\write16{} + \immediate\write16{***WARNING*** for users of Unix TeX 3.0!} + \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).} + \immediate\write16{If you are running another version of TeX, relax.} + \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} + \immediate\write16{ Then upgrade your TeX installation if you can.} + \immediate\write16{If you are stuck with version 3.0, run the} + \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} + \immediate\write16{ to use a workaround.} + \immediate\write16{} + \warnedobstrue + \fi +} + +% **In TeX 3.0, setting text in \nullfont hangs tex. For a +% workaround (which requires the file ``dummy.tfm'' to be installed), +% uncomment the following line: +%%%%%\font\nullfont=dummy\let\obstexwarn=\relax + +% Ignore text, except that we keep track of conditional commands for +% purposes of nesting, up to an `@end #1' command. +% +\def\nestedignore#1{% + \obstexwarn + % We must actually expand the ignored text to look for the @end + % command, so that nested ignore constructs work. Thus, we put the + % text into a \vbox and then do nothing with the result. To minimize + % the change of memory overflow, we follow the approach outlined on + % page 401 of the TeXbook: make the current font be a dummy font. + % + \setbox0 = \vbox\bgroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define `@end #1' to end the box, which will in turn undefine the + % @end command again. + \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}% + % + % We are going to be parsing Texinfo commands. Most cause no + % trouble when they are used incorrectly, but some commands do + % complicated argument parsing or otherwise get confused, so we + % undefine them. + % + % We can't do anything about stray @-signs, unfortunately; + % they'll produce `undefined control sequence' errors. + \ignoremorecommands + % + % Set the current font to be \nullfont, a TeX primitive, and define + % all the font commands to also use \nullfont. We don't use + % dummy.tfm, as suggested in the TeXbook, because not all sites + % might have that installed. Therefore, math mode will still + % produce output, but that should be an extremely small amount of + % stuff compared to the main input. + % + \nullfont + \let\tenrm = \nullfont \let\tenit = \nullfont \let\tensl = \nullfont + \let\tenbf = \nullfont \let\tentt = \nullfont \let\smallcaps = \nullfont + \let\tensf = \nullfont + % Similarly for index fonts (mostly for their use in + % smallexample) + \let\indrm = \nullfont \let\indit = \nullfont \let\indsl = \nullfont + \let\indbf = \nullfont \let\indtt = \nullfont \let\indsc = \nullfont + \let\indsf = \nullfont + % + % Don't complain when characters are missing from the fonts. + \tracinglostchars = 0 + % + % Don't bother to do space factor calculations. + \frenchspacing + % + % Don't report underfull hboxes. + \hbadness = 10000 + % + % Do minimal line-breaking. + \pretolerance = 10000 + % + % Do not execute instructions in @tex + \def\tex{\doignore{tex}} +} + +% @set VAR sets the variable VAR to an empty value. +% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. +% +% 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. +% +\def\set{\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 +} +\def\setzzz#1#2 \endsetzzz{\expandafter\xdef\csname SET#1\endcsname{#2}} + +% @clear VAR clears (i.e., unsets) the variable VAR. +% +\def\clear{\parsearg\clearxxx} +\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax} + +% @value{foo} gets the text saved in variable foo. +% +\def\value#1{\expandafter + \ifx\csname SET#1\endcsname\relax + {\{No value for ``#1''\}} + \else \csname SET#1\endcsname \fi} + +% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined +% with @set. +% +\def\ifset{\parsearg\ifsetxxx} +\def\ifsetxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifsetfail + \else + \expandafter\ifsetsucceed + \fi +} +\def\ifsetsucceed{\conditionalsucceed{ifset}} +\def\ifsetfail{\nestedignore{ifset}} +\defineunmatchedend{ifset} + +% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been +% defined with @set, or has been undefined with @clear. +% +\def\ifclear{\parsearg\ifclearxxx} +\def\ifclearxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifclearsucceed + \else + \expandafter\ifclearfail + \fi +} +\def\ifclearsucceed{\conditionalsucceed{ifclear}} +\def\ifclearfail{\nestedignore{ifclear}} +\defineunmatchedend{ifclear} + +% @iftex always succeeds; we read the text following, through @end +% iftex). But `@end iftex' should be valid only after an @iftex. +% +\def\iftex{\conditionalsucceed{iftex}} +\defineunmatchedend{iftex} + +% We can't just want to start a group at @iftex (for example) and end it +% at @end iftex, since then @set commands inside the conditional have no +% effect (they'd get reverted at the end of the group). So we must +% define \Eiftex to redefine itself to be its previous value. (We can't +% just define it to fail again with an ``unmatched end'' error, since +% the @ifset might be nested.) +% +\def\conditionalsucceed#1{% + \edef\temp{% + % Remember the current value of \E#1. + \let\nece{prevE#1} = \nece{E#1}% + % + % At the `@end #1', redefine \E#1 to be its previous value. + \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}% + }% + \temp +} + +% We need to expand lots of \csname's, but we don't want to expand the +% control sequences after we've constructed them. +% +\def\nece#1{\expandafter\noexpand\csname#1\endcsname} + +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math means output in math mode. +% We don't use $'s directly in the definition of \math because control +% sequences like \math are expanded when the toc file is written. Then, +% we read the toc file back, the $'s will be normal characters (as they +% should be, according to the definition of Texinfo). So we must use a +% control sequence to switch into and out of math mode. +% +% This isn't quite enough for @math to work properly in indices, but it +% seems unlikely it will ever be needed there. +% +\let\implicitmath = $ +\def\math#1{\implicitmath #1\implicitmath} + +% @bullet and @minus need the same treatment as @math, just above. +\def\bullet{\implicitmath\ptexbullet\implicitmath} +\def\minus{\implicitmath-\implicitmath} + +\def\node{\ENVcheck\parsearg\nodezzz} +\def\nodezzz#1{\nodexxx [#1,]} +\def\nodexxx[#1,#2]{\gdef\lastnode{#1}} +\let\nwnode=\node +\let\lastnode=\relax + +\def\donoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\setref{\lastnode}\fi +\let\lastnode=\relax} + +\def\unnumbnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\unnumbsetref{\lastnode}\fi +\let\lastnode=\relax} + +\def\appendixnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\appendixsetref{\lastnode}\fi +\let\lastnode=\relax} + +\let\refill=\relax + +% @setfilename is done at the beginning of every texinfo file. +% So open here the files we need to have open while reading the input. +% This makes it possible to make a .fmt file for texinfo. +\def\setfilename{% + \readauxfile + \opencontents + \openindices + \fixbackslash % Turn off hack to swallow `\input texinfo'. + \global\let\setfilename=\comment % Ignore extra @setfilename cmds. + \comment % Ignore the actual filename. +} + +\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} + +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + +\message{fonts,} + +% Font-change commands. + +% Texinfo supports the sans serif font style, which plain TeX does not. +% So we set up a \sf analogous to plain's \rm, etc. +\newfam\sffam +\def\sf{\fam=\sffam \tensf} +\let\li = \sf % Sometimes we call it \li, not \sf. + +%% Try out Computer Modern fonts at \magstephalf +\let\mainmagstep=\magstephalf + +\ifx\bigger\relax +\let\mainmagstep=\magstep1 +\font\textrm=cmr12 +\font\texttt=cmtt12 +\else +\font\textrm=cmr10 scaled \mainmagstep +\font\texttt=cmtt10 scaled \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. +\font\textbf=cmb10 scaled \mainmagstep +\font\textit=cmti10 scaled \mainmagstep +\font\textsl=cmsl10 scaled \mainmagstep +\font\textsf=cmss10 scaled \mainmagstep +\font\textsc=cmcsc10 scaled \mainmagstep +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep + +% A few fonts for @defun, etc. +\font\defbf=cmbx10 scaled \magstep1 %was 1314 +\font\deftt=cmtt10 scaled \magstep1 +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} + +% Fonts for indices and small examples. +% We actually use the slanted font rather than the italic, +% 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. +\font\ninett=cmtt9 +\font\indrm=cmr9 +\font\indit=cmsl9 +\let\indsl=\indit +\let\indtt=\ninett +\let\indsf=\indrm +\let\indbf=\indrm +\let\indsc=\indrm +\font\indi=cmmi9 +\font\indsy=cmsy9 + +% Fonts for headings +\font\chaprm=cmbx12 scaled \magstep2 +\font\chapit=cmti12 scaled \magstep2 +\font\chapsl=cmsl12 scaled \magstep2 +\font\chaptt=cmtt12 scaled \magstep2 +\font\chapsf=cmss12 scaled \magstep2 +\let\chapbf=\chaprm +\font\chapsc=cmcsc10 scaled\magstep3 +\font\chapi=cmmi12 scaled \magstep2 +\font\chapsy=cmsy10 scaled \magstep3 + +\font\secrm=cmbx12 scaled \magstep1 +\font\secit=cmti12 scaled \magstep1 +\font\secsl=cmsl12 scaled \magstep1 +\font\sectt=cmtt12 scaled \magstep1 +\font\secsf=cmss12 scaled \magstep1 +\font\secbf=cmbx12 scaled \magstep1 +\font\secsc=cmcsc10 scaled\magstep2 +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 + +% \font\ssecrm=cmbx10 scaled \magstep1 % This size an font looked bad. +% \font\ssecit=cmti10 scaled \magstep1 % The letters were too crowded. +% \font\ssecsl=cmsl10 scaled \magstep1 +% \font\ssectt=cmtt10 scaled \magstep1 +% \font\ssecsf=cmss10 scaled \magstep1 + +%\font\ssecrm=cmb10 scaled 1315 % Note the use of cmb rather than cmbx. +%\font\ssecit=cmti10 scaled 1315 % Also, the size is a little larger than +%\font\ssecsl=cmsl10 scaled 1315 % being scaled magstep1. +%\font\ssectt=cmtt10 scaled 1315 +%\font\ssecsf=cmss10 scaled 1315 + +%\let\ssecbf=\ssecrm + +\font\ssecrm=cmbx12 scaled \magstephalf +\font\ssecit=cmti12 scaled \magstephalf +\font\ssecsl=cmsl12 scaled \magstephalf +\font\ssectt=cmtt12 scaled \magstephalf +\font\ssecsf=cmss12 scaled \magstephalf +\font\ssecbf=cmbx12 scaled \magstephalf +\font\ssecsc=cmcsc10 scaled \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: +\font\titlerm = cmbx12 scaled \magstep3 +\let\authorrm = \secrm + +% In order for the font changes to affect most math symbols and letters, +% we have to define the \textfont of the standard families. Since +% texinfo doesn't allow for producing subscripts and superscripts, we +% don't bother to reset \scriptfont and \scriptscriptfont (which would +% also require loading a lot more fonts). +% +\def\resetmathfonts{% + \textfont0 = \tenrm \textfont1 = \teni \textfont2 = \tensy + \textfont\itfam = \tenit \textfont\slfam = \tensl \textfont\bffam = \tenbf + \textfont\ttfam = \tentt \textfont\sffam = \tensf +} + + +% 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. +\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 + \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 + \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 + \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 + \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 + \resetmathfonts} + +% Set up the default fonts, so we can use them for creating boxes. +% +\textfonts + +% Count depth in font-changes, for error checks +\newcount\fontdepth \fontdepth=0 + +% Fonts for short table of contents. +\font\shortcontrm=cmr12 +\font\shortcontbf=cmbx12 +\font\shortcontsl=cmsl12 + +%% Add scribe-like font environments, plus @l for inline lisp (usually sans +%% serif) and @ii for TeX italic + +% \smartitalic{ARG} outputs arg in italics, followed by an italic correction +% unless the following character is such as not to need one. +\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi} +\def\smartitalic#1{{\sl #1}\futurelet\next\smartitalicx} + +\let\i=\smartitalic +\let\var=\smartitalic +\let\dfn=\smartitalic +\let\emph=\smartitalic +\let\cite=\smartitalic + +\def\b#1{{\bf #1}} +\let\strong=\b + +% We can't just use \exhyphenpenalty, because that only has effect at +% the end of a paragraph. Restore normal hyphenation at the end of the +% group within which \nohyphenation is presumably called. +% +\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} +\def\restorehyphenation{\hyphenchar\font = `- } + +\def\t#1{% + {\tt \nohyphenation \rawbackslash \frenchspacing #1}% + \null +} +\let\ttfont = \t +%\def\samp #1{`{\tt \rawbackslash \frenchspacing #1}'\null} +\def\samp #1{`\tclose{#1}'\null} +\def\key #1{{\tt \nohyphenation \uppercase{#1}}\null} +\def\ctrl #1{{\tt \rawbackslash \hat}#1} + +\let\file=\samp + +% @code is a modification of @t, +% which makes spaces the same size as normal in the surrounding text. +\def\tclose#1{% + {% + % Change normal interword space to be same as for the current font. + \spaceskip = \fontdimen2\font + % + % Switch to typewriter. + \tt + % + % But `\ ' produces the large typewriter interword space. + \def\ {{\spaceskip = 0pt{} }}% + % + % Turn off hyphenation. + \nohyphenation + % + \rawbackslash + \frenchspacing + #1% + }% + \null +} + +% We *must* turn on hyphenation at `-' and `_' in \code. +% Otherwise, it is too hard to avoid overful hboxes +% in the Emacs manual, the Library manual, etc. + +% Unfortunately, TeX uses one parameter (\hyphenchar) to control +% both hyphenation at - and hyphenation within words. +% We must therefore turn them both off (\tclose does that) +% and arrange explicitly to hyphenate an a dash. +% -- rms. +{ +\catcode`\-=\active +\catcode`\_=\active +\global\def\code{\begingroup \catcode`\-=\active \let-\codedash \catcode`\_=\active \let_\codeunder \codex} +% The following is used by \doprintindex to insure that long function names +% wrap around. It is necessary for - and _ to be active before the index is +% read from the file, as \entry parses the arguments long before \code is +% ever called. -- mycroft +\global\def\indexbreaks{\catcode`\-=\active \let-\realdash \catcode`\_=\active \let_\realunder} +} +\def\realdash{-} +\def\realunder{_} +\def\codedash{-\discretionary{}{}{}} +\def\codeunder{\normalunderscore\discretionary{}{}{}} +\def\codex #1{\tclose{#1}\endgroup} + +%\let\exp=\tclose %Was temporary + +% @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} + +% 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 +% @dmn{}pt. +% +\def\dmn#1{\thinspace #1} + +\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} + +\def\l#1{{\li #1}\null} % + +\def\r#1{{\rm #1}} % roman font +% Use of \lowercase was suggested. +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +\message{page headings,} + +\newskip\titlepagetopglue \titlepagetopglue = 1.5in +\newskip\titlepagebottomglue \titlepagebottomglue = 2pc + +% First the title page. Must do @settitle before @titlepage. +\def\titlefont#1{{\titlerm #1}} + +\newif\ifseenauthor +\newif\iffinishedtitlepage + +\def\shorttitlepage{\parsearg\shorttitlepagezzz} +\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% + \endgroup\page\hbox{}\page} + +\def\titlepage{\begingroup \parindent=0pt \textfonts + \let\subtitlerm=\tenrm +% I deinstalled the following change because \cmr12 is undefined. +% This change was not in the ChangeLog anyway. --rms. +% \let\subtitlerm=\cmr12 + \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% + % + \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}% + % + % Leave some space at the very top of the page. + \vglue\titlepagetopglue + % + % Now you can print the title using @title. + \def\title{\parsearg\titlezzz}% + \def\titlezzz##1{\leftline{\titlefont{##1}} + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% + % No rule at page bottom unless we print one at the top with @title. + \finishedtitlepagetrue + % + % Now you can put text using @subtitle. + \def\subtitle{\parsearg\subtitlezzz}% + \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}% + % + % @author should come last, but may come many times. + \def\author{\parsearg\authorzzz}% + \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi + {\authorfont \leftline{##1}}}% + % + % Most title ``pages'' are actually two pages long, with space + % at the top of the second. We don't want the ragged left on the second. + \let\oldpage = \page + \def\page{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + \oldpage + \let\page = \oldpage + \hbox{}}% +% \def\page{\oldpage \hbox{}} +} + +\def\Etitlepage{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + % It is important to do the page break before ending the group, + % because the headline and footline are only empty inside the group. + % If we use the new definition of \page, we always get a blank page + % after the title page, which we certainly don't want. + \oldpage + \endgroup + \HEADINGSon +} + +\def\finishtitlepage{% + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue +} + +%%% Set up page headings and footings. + +\let\thispage=\folio + +\newtoks \evenheadline % Token sequence for heading line of even pages +\newtoks \oddheadline % Token sequence for heading line of odd pages +\newtoks \evenfootline % Token sequence for footing line of even pages +\newtoks \oddfootline % Token sequence for footing line of odd pages + +% Now make Tex use those variables +\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline + \else \the\evenheadline \fi}} +\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline + \else \the\evenfootline \fi}\HEADINGShook} +\let\HEADINGShook=\relax + +% Commands to set those variables. +% For example, this is what @headings on does +% @evenheading @thistitle|@thispage|@thischapter +% @oddheading @thischapter|@thispage|@thistitle +% @evenfooting @thisfile|| +% @oddfooting ||@thisfile + +\def\evenheading{\parsearg\evenheadingxxx} +\def\oddheading{\parsearg\oddheadingxxx} +\def\everyheading{\parsearg\everyheadingxxx} + +\def\evenfooting{\parsearg\evenfootingxxx} +\def\oddfooting{\parsearg\oddfootingxxx} +\def\everyfooting{\parsearg\everyfootingxxx} + +{\catcode`\@=0 % + +\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish} +\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish} +\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{% +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyheadingxxx #1{\everyheadingyyy #1@|@|@|@|\finish} +\gdef\everyheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}} +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish} +\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish} +\gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{% +\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyfootingxxx #1{\everyfootingyyy #1@|@|@|@|\finish} +\gdef\everyfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}} +\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} +% +}% unbind the catcode of @. + +% @headings double turns headings on for double-sided printing. +% @headings single turns headings on for single-sided printing. +% @headings off turns them off. +% @headings on same as @headings double, retained for compatibility. +% @headings after turns on double-sided headings after this page. +% @headings doubleafter turns on double-sided headings after this page. +% @headings singleafter turns on single-sided headings after this page. +% By default, they are off. + +\def\headings #1 {\csname HEADINGS#1\endcsname} + +\def\HEADINGSoff{ +\global\evenheadline={\hfil} \global\evenfootline={\hfil} +\global\oddheadline={\hfil} \global\oddfootline={\hfil}} +\HEADINGSoff +% When we turn headings on, set the page number to 1. +% For double-sided printing, put current file name in lower left corner, +% chapter name on inside top of right hand pages, document +% title on inside top of left hand pages, and page numbers on outside top +% edge of all pages. +\def\HEADINGSdouble{ +%\pagealignmacro +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} +% For single-sided printing, chapter title goes across top left of page, +% page number on top right. +\def\HEADINGSsingle{ +%\pagealignmacro +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} +\def\HEADINGSon{\HEADINGSdouble} + +\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} +\let\HEADINGSdoubleafter=\HEADINGSafter +\def\HEADINGSdoublex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} + +\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} +\def\HEADINGSsinglex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} + +% Subroutines used in generating headings +% Produces Day Month Year style of output. +\def\today{\number\day\space +\ifcase\month\or +January\or February\or March\or April\or May\or June\or +July\or August\or September\or October\or November\or December\fi +\space\number\year} + +% Use this if you want the Month Day, Year style of output. +%\def\today{\ifcase\month\or +%January\or February\or March\or April\or May\or June\or +%July\or August\or September\or October\or November\or December\fi +%\space\number\day, \number\year} + +% @settitle line... specifies the title of the document, for headings +% It generates no output of its own + +\def\thistitle{No Title} +\def\settitle{\parsearg\settitlezzz} +\def\settitlezzz #1{\gdef\thistitle{#1}} + +\message{tables,} + +% @tabs -- simple alignment + +% These don't work. For one thing, \+ is defined as outer. +% So these macros cannot even be defined. + +%\def\tabs{\parsearg\tabszzz} +%\def\tabszzz #1{\settabs\+#1\cr} +%\def\tabline{\parsearg\tablinezzz} +%\def\tablinezzz #1{\+#1\cr} +%\def\&{&} + +% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(x). + +% default indentation of table text +\newdimen\tableindent \tableindent=.8in +% default indentation of @itemize and @enumerate text +\newdimen\itemindent \itemindent=.3in +% margin between end of table item and start of table text. +\newdimen\itemmargin \itemmargin=.1in + +% used internally for \itemindent minus \itemmargin +\newdimen\itemmax + +% Note @table, @vtable, and @vtable define @item, @itemx, etc., with +% these defs. +% They also define \itemindex +% to index the item name in whatever manner is desired (perhaps none). + +\newif\ifitemxneedsnegativevskip + +\def\itemxpar{\par\ifitemxneedsnegativevskip\vskip-\parskip\nobreak\fi} + +\def\internalBitem{\smallbreak \parsearg\itemzzz} +\def\internalBitemx{\itemxpar \parsearg\itemzzz} + +\def\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz} +\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz} + +\def\internalBkitem{\smallbreak \parsearg\kitemzzz} +\def\internalBkitemx{\itemxpar \parsearg\kitemzzz} + +\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}% + \itemzzz {#1}} + +\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}% + \itemzzz {#1}} + +\def\itemzzz #1{\begingroup % + \advance\hsize by -\rightskip + \advance\hsize by -\tableindent + \setbox0=\hbox{\itemfont{#1}}% + \itemindex{#1}% + \nobreak % This prevents a break before @itemx. + % + % Be sure we are not still in the middle of a paragraph. + %{\parskip = 0in + %\par + %}% + % + % If the item text does not fit in the space we have, put it on a line + % by itself, and do not allow a page break either before or after that + % line. We do not start a paragraph here because then if the next + % command is, e.g., @kindex, the whatsit would get put into the + % horizontal list on a line by itself, resulting in extra blank space. + \ifdim \wd0>\itemmax + % + % Make this a paragraph so we get the \parskip glue and wrapping, + % but leave it ragged-right. + \begingroup + \advance\leftskip by-\tableindent + \advance\hsize by\tableindent + \advance\rightskip by0pt plus1fil + \leavevmode\unhbox0\par + \endgroup + % + % We're going to be starting a paragraph, but we don't want the + % \parskip glue -- logically it's part of the @item we just started. + \nobreak \vskip-\parskip + % + % Stop a page break at the \parskip glue coming up. Unfortunately + % we can't prevent a possible page break at the following + % \baselineskip glue. + \nobreak + \endgroup + \itemxneedsnegativevskipfalse + \else + % The item text fits into the space. Start a paragraph, so that the + % following text (if any) will end up on the same line. Since that + % text will be indented by \tableindent, we make the item text be in + % a zero-width box. + \noindent + \rlap{\hskip -\tableindent\box0}\ignorespaces% + \endgroup% + \itemxneedsnegativevskiptrue% + \fi +} + +\def\item{\errmessage{@item while not in a table}} +\def\itemx{\errmessage{@itemx while not in a table}} +\def\kitem{\errmessage{@kitem while not in a table}} +\def\kitemx{\errmessage{@kitemx while not in a table}} +\def\xitem{\errmessage{@xitem while not in a table}} +\def\xitemx{\errmessage{@xitemx while not in a table}} + +%% Contains a kludge to get @end[description] to work +\def\description{\tablez{\dontindex}{1}{}{}{}{}} + +\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex} +{\obeylines\obeyspaces% +\gdef\tablex #1^^M{% +\tabley\dontindex#1 \endtabley}} + +\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex} +{\obeylines\obeyspaces% +\gdef\ftablex #1^^M{% +\tabley\fnitemindex#1 \endtabley +\def\Eftable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex} +{\obeylines\obeyspaces% +\gdef\vtablex #1^^M{% +\tabley\vritemindex#1 \endtabley +\def\Evtable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\dontindex #1{} +\def\fnitemindex #1{\doind {fn}{\code{#1}}}% +\def\vritemindex #1{\doind {vr}{\code{#1}}}% + +{\obeyspaces % +\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup% +\tablez{#1}{#2}{#3}{#4}{#5}{#6}}} + +\def\tablez #1#2#3#4#5#6{% +\aboveenvbreak % +\begingroup % +\def\Edescription{\Etable}% Neccessary kludge. +\let\itemindex=#1% +\ifnum 0#3>0 \advance \leftskip by #3\mil \fi % +\ifnum 0#4>0 \tableindent=#4\mil \fi % +\ifnum 0#5>0 \advance \rightskip by #5\mil \fi % +\def\itemfont{#2}% +\itemmax=\tableindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \tableindent % +\exdentamount=\tableindent +\parindent = 0pt +\parskip = \smallskipamount +\ifdim \parskip=0pt \parskip=2pt \fi% +\def\Etable{\endgraf\afterenvbreak\endgroup}% +\let\item = \internalBitem % +\let\itemx = \internalBitemx % +\let\kitem = \internalBkitem % +\let\kitemx = \internalBkitemx % +\let\xitem = \internalBxitem % +\let\xitemx = \internalBxitemx % +} + +% This is the counter used by @enumerate, which is really @itemize + +\newcount \itemno + +\def\itemize{\parsearg\itemizezzz} + +\def\itemizezzz #1{% + \begingroup % ended by the @end itemsize + \itemizey {#1}{\Eitemize} +} + +\def\itemizey #1#2{% +\aboveenvbreak % +\itemmax=\itemindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \itemindent % +\exdentamount=\itemindent +\parindent = 0pt % +\parskip = \smallskipamount % +\ifdim \parskip=0pt \parskip=2pt \fi% +\def#2{\endgraf\afterenvbreak\endgroup}% +\def\itemcontents{#1}% +\let\item=\itemizeitem} + +% Set sfcode to normal for the chars that usually have another value. +% These are `.?!:;,' +\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000 + \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 } + +% \splitoff TOKENS\endmark defines \first to be the first token in +% TOKENS, and \rest to be the remainder. +% +\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% + +% Allow an optional argument of an uppercase letter, lowercase letter, +% or number, to specify the first label in the enumerated list. No +% argument is the same as `1'. +% +\def\enumerate{\parsearg\enumeratezzz} +\def\enumeratezzz #1{\enumeratey #1 \endenumeratey} +\def\enumeratey #1 #2\endenumeratey{% + \begingroup % ended by the @end enumerate + % + % If we were given no argument, pretend we were given `1'. + \def\thearg{#1}% + \ifx\thearg\empty \def\thearg{1}\fi + % + % Detect if the argument is a single token. If so, it might be a + % letter. Otherwise, the only valid thing it can be is a number. + % (We will always have one token, because of the test we just made. + % This is a good thing, since \splitoff doesn't work given nothing at + % all -- the first parameter is undelimited.) + \expandafter\splitoff\thearg\endmark + \ifx\rest\empty + % Only one token in the argument. It could still be anything. + % A ``lowercase letter'' is one whose \lccode is nonzero. + % An ``uppercase letter'' is one whose \lccode is both nonzero, and + % not equal to itself. + % Otherwise, we assume it's a number. + % + % We need the \relax at the end of the \ifnum lines to stop TeX from + % continuing to look for a . + % + \ifnum\lccode\expandafter`\thearg=0\relax + \numericenumerate % a number (we hope) + \else + % It's a letter. + \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax + \lowercaseenumerate % lowercase letter + \else + \uppercaseenumerate % uppercase letter + \fi + \fi + \else + % Multiple tokens in the argument. We hope it's a number. + \numericenumerate + \fi +} + +% An @enumerate whose labels are integers. The starting integer is +% given in \thearg. +% +\def\numericenumerate{% + \itemno = \thearg + \startenumeration{\the\itemno}% +} + +% The starting (lowercase) letter is in \thearg. +\def\lowercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more lowercase letters in @enumerate; get a bigger + alphabet}% + \fi + \char\lccode\itemno + }% +} + +% The starting (uppercase) letter is in \thearg. +\def\uppercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more uppercase letters in @enumerate; get a bigger + alphabet} + \fi + \char\uccode\itemno + }% +} + +% Call itemizey, adding a period to the first argument and supplying the +% common last two arguments. Also subtract one from the initial value in +% \itemno, since @item increments \itemno. +% +\def\startenumeration#1{% + \advance\itemno by -1 + \itemizey{#1.}\Eenumerate\flushcr +} + +% @alphaenumerate and @capsenumerate are abbreviations for giving an arg +% to @enumerate. +% +\def\alphaenumerate{\enumerate{a}} +\def\capsenumerate{\enumerate{A}} +\def\Ealphaenumerate{\Eenumerate} +\def\Ecapsenumerate{\Eenumerate} + +% Definition of @item while inside @itemize. + +\def\itemizeitem{% +\advance\itemno by 1 +{\let\par=\endgraf \smallbreak}% +\ifhmode \errmessage{\in hmode at itemizeitem}\fi +{\parskip=0in \hskip 0pt +\hbox to 0pt{\hss \itemcontents\hskip \itemmargin}% +\vadjust{\penalty 1200}}% +\flushcr} + +\message{indexing,} +% Index generation facilities + +% Define \newwrite to be identical to plain tex's \newwrite +% except not \outer, so it can be used within \newindex. +{\catcode`\@=11 +\gdef\newwrite{\alloc@7\write\chardef\sixt@@n}} + +% \newindex {foo} defines an index named foo. +% It automatically defines \fooindex such that +% \fooindex ...rest of line... puts an entry in the index foo. +% It also defines \fooindfile to be the number of the output channel for +% the file that accumulates this index. The file's extension is foo. +% The name of an index should be no more than 2 characters long +% for the sake of vms. + +\def\newindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#1}} +} + +% @defindex foo == \newindex{foo} + +\def\defindex{\parsearg\newindex} + +% Define @defcodeindex, like @defindex except put all entries in @code. + +\def\newcodeindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#1}} +} + +\def\defcodeindex{\parsearg\newcodeindex} + +% @synindex foo bar makes index foo feed into index bar. +% Do this instead of @defindex foo if you don't want it as a separate index. +\def\synindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#2}}% +} + +% @syncodeindex foo bar similar, but put all entries made for index foo +% inside @code. +\def\syncodeindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#2}}% +} + +% Define \doindex, the driver for all \fooindex macros. +% Argument #1 is generated by the calling \fooindex macro, +% and it is "foo", the name of the index. + +% \doindex just uses \parsearg; it calls \doind for the actual work. +% This is because \doind is more useful to call from other macros. + +% There is also \dosubind {index}{topic}{subtopic} +% which makes an entry in a two-level index such as the operation index. + +\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} +\def\singleindexer #1{\doind{\indexname}{#1}} + +% like the previous two, but they put @code around the argument. +\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} +\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} + +\def\indexdummies{% +% Take care of the plain tex accent commands. +\def\"{\realbackslash "}% +\def\`{\realbackslash `}% +\def\'{\realbackslash '}% +\def\^{\realbackslash ^}% +\def\~{\realbackslash ~}% +\def\={\realbackslash =}% +\def\b{\realbackslash b}% +\def\c{\realbackslash c}% +\def\d{\realbackslash d}% +\def\u{\realbackslash u}% +\def\v{\realbackslash v}% +\def\H{\realbackslash H}% +% Take care of the plain tex special European modified letters. +\def\oe{\realbackslash oe}% +\def\ae{\realbackslash ae}% +\def\aa{\realbackslash aa}% +\def\OE{\realbackslash OE}% +\def\AE{\realbackslash AE}% +\def\AA{\realbackslash AA}% +\def\o{\realbackslash o}% +\def\O{\realbackslash O}% +\def\l{\realbackslash l}% +\def\L{\realbackslash L}% +\def\ss{\realbackslash ss}% +% Take care of texinfo commands likely to appear in an index entry. +\def\_{{\realbackslash _}}% +\def\w{\realbackslash w }% +\def\bf{\realbackslash bf }% +\def\rm{\realbackslash rm }% +\def\sl{\realbackslash sl }% +\def\sf{\realbackslash sf}% +\def\tt{\realbackslash tt}% +\def\gtr{\realbackslash gtr}% +\def\less{\realbackslash less}% +\def\hat{\realbackslash hat}% +\def\char{\realbackslash char}% +\def\TeX{\realbackslash TeX}% +\def\dots{\realbackslash dots }% +\def\copyright{\realbackslash copyright }% +\def\tclose##1{\realbackslash tclose {##1}}% +\def\code##1{\realbackslash code {##1}}% +\def\samp##1{\realbackslash samp {##1}}% +\def\t##1{\realbackslash r {##1}}% +\def\r##1{\realbackslash r {##1}}% +\def\i##1{\realbackslash i {##1}}% +\def\b##1{\realbackslash b {##1}}% +\def\cite##1{\realbackslash cite {##1}}% +\def\key##1{\realbackslash key {##1}}% +\def\file##1{\realbackslash file {##1}}% +\def\var##1{\realbackslash var {##1}}% +\def\kbd##1{\realbackslash kbd {##1}}% +\def\dfn##1{\realbackslash dfn {##1}}% +\def\emph##1{\realbackslash emph {##1}}% +} + +% \indexnofonts no-ops all font-change commands. +% This is used when outputting the strings to sort the index by. +\def\indexdummyfont#1{#1} +\def\indexdummytex{TeX} +\def\indexdummydots{...} + +\def\indexnofonts{% +% Just ignore accents. +\let\"=\indexdummyfont +\let\`=\indexdummyfont +\let\'=\indexdummyfont +\let\^=\indexdummyfont +\let\~=\indexdummyfont +\let\==\indexdummyfont +\let\b=\indexdummyfont +\let\c=\indexdummyfont +\let\d=\indexdummyfont +\let\u=\indexdummyfont +\let\v=\indexdummyfont +\let\H=\indexdummyfont +% Take care of the plain tex special European modified letters. +\def\oe{oe}% +\def\ae{ae}% +\def\aa{aa}% +\def\OE{OE}% +\def\AE{AE}% +\def\AA{AA}% +\def\o{o}% +\def\O{O}% +\def\l{l}% +\def\L{L}% +\def\ss{ss}% +\let\w=\indexdummyfont +\let\t=\indexdummyfont +\let\r=\indexdummyfont +\let\i=\indexdummyfont +\let\b=\indexdummyfont +\let\emph=\indexdummyfont +\let\strong=\indexdummyfont +\let\cite=\indexdummyfont +\let\sc=\indexdummyfont +%Don't no-op \tt, since it isn't a user-level command +% and is used in the definitions of the active chars like <, >, |... +%\let\tt=\indexdummyfont +\let\tclose=\indexdummyfont +\let\code=\indexdummyfont +\let\file=\indexdummyfont +\let\samp=\indexdummyfont +\let\kbd=\indexdummyfont +\let\key=\indexdummyfont +\let\var=\indexdummyfont +\let\TeX=\indexdummytex +\let\dots=\indexdummydots +} + +% To define \realbackslash, we must make \ not be an escape. +% We must first make another character (@) an escape +% so we do not become unable to do a definition. + +{\catcode`\@=0 \catcode`\\=\other +@gdef@realbackslash{\}} + +\let\indexbackslash=0 %overridden during \printindex. + +\def\doind #1#2{% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% Expand all macros now EXCEPT \folio +\def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now +% so it will be output as is; and it will print as backslash in the indx. +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}}}% +\temp }% +}\penalty\count10}} + +\def\dosubind #1#2#3{% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% +\def\rawbackslashxx{\indexbackslash}% +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2 #3}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}{#3}}}% +\temp }% +}\penalty\count10}} + +% The index entry written in the file actually looks like +% \entry {sortstring}{page}{topic} +% or +% \entry {sortstring}{page}{topic}{subtopic} +% The texindex program reads in these files and writes files +% containing these kinds of lines: +% \initial {c} +% before the first topic whose initial is c +% \entry {topic}{pagelist} +% for a topic that is used without subtopics +% \primary {topic} +% for the beginning of a topic that is used with subtopics +% \secondary {subtopic}{pagelist} +% for each subtopic. + +% Define the user-accessible indexing commands +% @findex, @vindex, @kindex, @cindex. + +\def\findex {\fnindex} +\def\kindex {\kyindex} +\def\cindex {\cpindex} +\def\vindex {\vrindex} +\def\tindex {\tpindex} +\def\pindex {\pgindex} + +\def\cindexsub {\begingroup\obeylines\cindexsub} +{\obeylines % +\gdef\cindexsub "#1" #2^^M{\endgroup % +\dosubind{cp}{#2}{#1}}} + +% Define the macros used in formatting output of the sorted index material. + +% This is what you call to cause a particular index to get printed. +% Write +% @unnumbered Function Index +% @printindex fn + +\def\printindex{\parsearg\doprintindex} + +\def\doprintindex#1{% + \tex + \dobreak \chapheadingskip {10000} + \catcode`\%=\other\catcode`\&=\other\catcode`\#=\other + \catcode`\$=\other + \catcode`\~=\other + \indexbreaks + % + % The following don't help, since the chars were translated + % when the raw index was written, and their fonts were discarded + % due to \indexnofonts. + %\catcode`\"=\active + %\catcode`\^=\active + %\catcode`\_=\active + %\catcode`\|=\active + %\catcode`\<=\active + %\catcode`\>=\active + % % + \def\indexbackslash{\rawbackslashxx} + \indexfonts\rm \tolerance=9500 \advance\baselineskip -1pt + \begindoublecolumns + % + % See if the index file exists and is nonempty. + \openin 1 \jobname.#1s + \ifeof 1 + % \enddoublecolumns gets confused if there is no text in the index, + % and it loses the chapter title and the aux file entries for the + % index. The easiest way to prevent this problem is to make sure + % there is some text. + (Index is nonexistent) + \else + % + % If the index file exists but is empty, then \openin leaves \ifeof + % false. We have to make TeX try to read something from the file, so + % it can discover if there is anything in it. + \read 1 to \temp + \ifeof 1 + (Index is empty) + \else + \input \jobname.#1s + \fi + \fi + \closein 1 + \enddoublecolumns + \Etex +} + +% These macros are used by the sorted index file itself. +% Change them to control the appearance of the index. + +% Same as \bigskipamount except no shrink. +% \balancecolumns gets confused if there is any shrink. +\newskip\initialskipamount \initialskipamount 12pt plus4pt + +\def\initial #1{% +{\let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt +\ifdim\lastskip<\initialskipamount +\removelastskip \penalty-200 \vskip \initialskipamount\fi +\line{\secbf#1\hfill}\kern 2pt\penalty10000}} + +% This typesets a paragraph consisting of #1, dot leaders, and then #2 +% flush to the right margin. It is used for index and table of contents +% entries. The paragraph is indented by \leftskip. +% +\def\entry #1#2{\begingroup + % + % Start a new paragraph if necessary, so our assignments below can't + % affect previous text. + \par + % + % Do not fill out the last line with white space. + \parfillskip = 0in + % + % No extra space above this paragraph. + \parskip = 0in + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 + % + % \hangindent is only relevant when the entry text and page number + % don't both fit on one line. In that case, bob suggests starting the + % dots pretty far over on the line. Unfortunately, a large + % indentation looks wrong when the entry text itself is broken across + % lines. So we use a small indentation and put up with long leaders. + % + % \hangafter is reset to 1 (which is the value we want) at the start + % of each paragraph, so we need not do anything with that. + \hangindent=2em + % + % When the entry text needs to be broken, just fill out the first line + % with blank space. + \rightskip = 0pt plus1fil + % + % Start a ``paragraph'' for the index entry so the line breaking + % parameters we've set above will have an effect. + \noindent + % + % 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 + % there are no page numbers. The next person who breaks this will be + % cursed by a Unix daemon. + \def\tempa{{\rm }}% + \def\tempb{#2}% + \edef\tempc{\tempa}% + \edef\tempd{\tempb}% + \ifx\tempc\tempd\ \else% + % + % If we must, put the page number on a line of its own, and fill out + % this line with blank space. (The \hfil is overwhelmed with the + % fill leaders glue in \indexdotfill if the page number does fit.) + \hfil\penalty50 + \null\nobreak\indexdotfill % Have leaders before the page number. + % + % The `\ ' here is removed by the implicit \unskip that TeX does as + % part of (the primitive) \par. Without it, a spurious underfull + % \hbox ensues. + \ #2% The page number ends the paragraph. + \fi% + \par +\endgroup} + +% Like \dotfill except takes at least 1 em. +\def\indexdotfill{\cleaders + \hbox{$\mathsurround=0pt \mkern1.5mu ${\it .}$ \mkern1.5mu$}\hskip 1em plus 1fill} + +\def\primary #1{\line{#1\hfil}} + +\newskip\secondaryindent \secondaryindent=0.5cm + +\def\secondary #1#2{ +{\parfillskip=0in \parskip=0in +\hangindent =1in \hangafter=1 +\noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par +}} + +%% Define two-column mode, which is used in indexes. +%% Adapted from the TeXbook, page 416. +\catcode `\@=11 + +\newbox\partialpage + +\newdimen\doublecolumnhsize + +\def\begindoublecolumns{\begingroup + % Grab any single-column material above us. + \output = {\global\setbox\partialpage + =\vbox{\unvbox255\kern -\topskip \kern \baselineskip}}% + \eject + % + % Now switch to the double-column output routine. + \output={\doublecolumnout}% + % + % Change the page size parameters. We could do this once outside this + % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 + % format, but then we repeat the same computation. Repeating a couple + % of assignments once per index is clearly meaningless for the + % execution time, so we may as well do it once. + % + % First we halve the line length, less a little for the gutter between + % the columns. We compute the gutter based on the line length, so it + % changes automatically with the paper format. The magic constant + % below is chosen so that the gutter has the same value (well, +- < + % 1pt) as it did when we hard-coded it. + % + % We put the result in a separate register, \doublecolumhsize, so we + % can restore it in \pagesofar, after \hsize itself has (potentially) + % been clobbered. + % + \doublecolumnhsize = \hsize + \advance\doublecolumnhsize by -.04154\hsize + \divide\doublecolumnhsize by 2 + \hsize = \doublecolumnhsize + % + % Double the \vsize as well. (We don't need a separate register here, + % since nobody clobbers \vsize.) + \vsize = 2\vsize + \doublecolumnpagegoal +} + +\def\enddoublecolumns{\eject \endgroup \pagegoal=\vsize \unvbox\partialpage} + +\def\doublecolumnsplit{\splittopskip=\topskip \splitmaxdepth=\maxdepth + \global\dimen@=\pageheight \global\advance\dimen@ by-\ht\partialpage + \global\setbox1=\vsplit255 to\dimen@ \global\setbox0=\vbox{\unvbox1} + \global\setbox3=\vsplit255 to\dimen@ \global\setbox2=\vbox{\unvbox3} + \ifdim\ht0>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi + \ifdim\ht2>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi +} +\def\doublecolumnpagegoal{% + \dimen@=\vsize \advance\dimen@ by-2\ht\partialpage \global\pagegoal=\dimen@ +} +\def\pagesofar{\unvbox\partialpage % + \hsize=\doublecolumnhsize % have to restore this since output routine + \wd0=\hsize \wd2=\hsize \hbox to\pagewidth{\box0\hfil\box2}} +\def\doublecolumnout{% + \setbox5=\copy255 + {\vbadness=10000 \doublecolumnsplit} + \ifvbox255 + \setbox0=\vtop to\dimen@{\unvbox0} + \setbox2=\vtop to\dimen@{\unvbox2} + \onepageout\pagesofar \unvbox255 \penalty\outputpenalty + \else + \setbox0=\vbox{\unvbox5} + \ifvbox0 + \dimen@=\ht0 \advance\dimen@ by\topskip \advance\dimen@ by-\baselineskip + \divide\dimen@ by2 \splittopskip=\topskip \splitmaxdepth=\maxdepth + {\vbadness=10000 + \loop \global\setbox5=\copy0 + \setbox1=\vsplit5 to\dimen@ + \setbox3=\vsplit5 to\dimen@ + \ifvbox5 \global\advance\dimen@ by1pt \repeat + \setbox0=\vbox to\dimen@{\unvbox1} + \setbox2=\vbox to\dimen@{\unvbox3} + \global\setbox\partialpage=\vbox{\pagesofar} + \doublecolumnpagegoal + } + \fi + \fi +} + +\catcode `\@=\other +\message{sectioning,} +% Define chapters, sections, etc. + +\newcount \chapno +\newcount \secno \secno=0 +\newcount \subsecno \subsecno=0 +\newcount \subsubsecno \subsubsecno=0 + +% This counter is funny since it counts through charcodes of letters A, B, ... +\newcount \appendixno \appendixno = `\@ +\def\appendixletter{\char\the\appendixno} + +\newwrite \contentsfile +% This is called from \setfilename. +\def\opencontents{\openout \contentsfile = \jobname.toc} + +% Each @chapter defines this as the name of the chapter. +% page headings and footings can use it. @section does likewise + +\def\thischapter{} \def\thissection{} +\def\seccheck#1{\if \pageno<0 % +\errmessage{@#1 not allowed after generating table of contents}\fi +% +} + +\def\chapternofonts{% +\let\rawbackslash=\relax% +\let\frenchspacing=\relax% +\def\result{\realbackslash result} +\def\equiv{\realbackslash equiv} +\def\expansion{\realbackslash expansion} +\def\print{\realbackslash print} +\def\TeX{\realbackslash TeX} +\def\dots{\realbackslash dots} +\def\copyright{\realbackslash copyright} +\def\tt{\realbackslash tt} +\def\bf{\realbackslash bf } +\def\w{\realbackslash w} +\def\less{\realbackslash less} +\def\gtr{\realbackslash gtr} +\def\hat{\realbackslash hat} +\def\char{\realbackslash char} +\def\tclose##1{\realbackslash tclose {##1}} +\def\code##1{\realbackslash code {##1}} +\def\samp##1{\realbackslash samp {##1}} +\def\r##1{\realbackslash r {##1}} +\def\b##1{\realbackslash b {##1}} +\def\key##1{\realbackslash key {##1}} +\def\file##1{\realbackslash file {##1}} +\def\kbd##1{\realbackslash kbd {##1}} +% These are redefined because @smartitalic wouldn't work inside xdef. +\def\i##1{\realbackslash i {##1}} +\def\cite##1{\realbackslash cite {##1}} +\def\var##1{\realbackslash var {##1}} +\def\emph##1{\realbackslash emph {##1}} +\def\dfn##1{\realbackslash dfn {##1}} +} + +\newcount\absseclevel % used to calculate proper heading level +\newcount\secbase\secbase=0 % @raise/lowersections modify this count + +% @raisesections: treat @section as chapter, @subsection as section, etc. +\def\raisesections{\global\advance\secbase by -1} +\let\up=\raisesections % original BFox name + +% @lowersections: treat @chapter as section, @section as subsection, etc. +\def\lowersections{\global\advance\secbase by 1} +\let\down=\lowersections % original BFox name + +% Choose a numbered-heading macro +% #1 is heading level if unmodified by @raisesections or @lowersections +% #2 is text for heading +\def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \chapterzzz{#2} +\or + \seczzz{#2} +\or + \numberedsubseczzz{#2} +\or + \numberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \chapterzzz{#2} + \else + \numberedsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses appendix heading levels +\def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \appendixzzz{#2} +\or + \appendixsectionzzz{#2} +\or + \appendixsubseczzz{#2} +\or + \appendixsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \appendixzzz{#2} + \else + \appendixsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses numberless heading levels +\def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \unnumberedzzz{#2} +\or + \unnumberedseczzz{#2} +\or + \unnumberedsubseczzz{#2} +\or + \unnumberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \unnumberedzzz{#2} + \else + \unnumberedsubsubseczzz{#2} + \fi +\fi +} + + +\def\thischaptername{No Chapter Title} +\outer\def\chapter{\parsearg\chapteryyy} +\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz #1{\seccheck{chapter}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \chapno by 1 \message{Chapter \the\chapno}% +\chapmacro {#1}{\the\chapno}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +% We don't substitute the actual chapter name into \thischapter +% because we don't want its macros evaluated now. +\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% +{\chapternofonts% +\edef\temp{{\realbackslash chapentry {#1}{\the\chapno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec +}} + +\outer\def\appendix{\parsearg\appendixyyy} +\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz +\def\appendixzzz #1{\seccheck{appendix}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \appendixno by 1 \message{Appendix \appendixletter}% +\chapmacro {#1}{\putwordAppendix{} \appendixletter}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% +{\chapternofonts% +\edef\temp{{\realbackslash chapentry + {#1}{\putwordAppendix{} \appendixletter}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\global\let\section = \appendixsec +\global\let\subsection = \appendixsubsec +\global\let\subsubsection = \appendixsubsubsec +}} + +\outer\def\top{\parsearg\unnumberedyyy} +\outer\def\unnumbered{\parsearg\unnumberedyyy} +\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +\def\unnumberedzzz #1{\seccheck{unnumbered}% +\secno=0 \subsecno=0 \subsubsecno=0 +% +% This used to be simply \message{#1}, but TeX fully expands the +% argument to \message. Therefore, if #1 contained @-commands, TeX +% expanded them. For example, in `@unnumbered The @cite{Book}', TeX +% expanded @cite (which turns out to cause errors because \cite is meant +% to be executed, not expanded). +% +% Anyway, we don't want the fully-expanded definition of @cite to appear +% as a result of the \message, we just want `@cite' itself. We use +% \the to achieve this: TeX expands \the only once, +% simply yielding the contents of the . +\toks0 = {#1}\message{(\the\toks0)}% +% +\unnumbchapmacro {#1}% +\gdef\thischapter{#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbchapentry {#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\global\let\section = \unnumberedsec +\global\let\subsection = \unnumberedsubsec +\global\let\subsubsection = \unnumberedsubsubsec +}} + +\outer\def\numberedsec{\parsearg\secyyy} +\def\secyyy #1{\numhead1{#1}} % normally calls seczzz +\def\seczzz #1{\seccheck{section}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% +{\chapternofonts% +\edef\temp{{\realbackslash secentry % +{#1}{\the\chapno}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appenixsection{\parsearg\appendixsecyyy} +\outer\def\appendixsec{\parsearg\appendixsecyyy} +\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz +\def\appendixsectionzzz #1{\seccheck{appendixsection}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% +{\chapternofonts% +\edef\temp{{\realbackslash secentry % +{#1}{\appendixletter}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} +\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz +\def\unnumberedseczzz #1{\seccheck{unnumberedsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} +\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz +\def\numberedsubseczzz #1{\seccheck{subsection}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsecentry % +{#1}{\the\chapno}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} +\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz +\def\appendixsubseczzz #1{\seccheck{appendixsubsec}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsecentry % +{#1}{\appendixletter}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} +\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +\def\unnumberedsubseczzz #1{\seccheck{unnumberedsubsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsubsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} +\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz +\def\numberedsubsubseczzz #1{\seccheck{subsubsection}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsubsecentry % + {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno} + {\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} +\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz +\def\appendixsubsubseczzz #1{\seccheck{appendixsubsubsec}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsubsecentry{#1}% + {\appendixletter} + {\the\secno}{\the\subsecno}{\the\subsubsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} +\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +\def\unnumberedsubsubseczzz #1{\seccheck{unnumberedsubsubsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsubsubsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +% These are variants which are not "outer", so they can appear in @ifinfo. +% Actually, they should now be obsolete; ordinary section commands should work. +\def\infotop{\parsearg\unnumberedzzz} +\def\infounnumbered{\parsearg\unnumberedzzz} +\def\infounnumberedsec{\parsearg\unnumberedseczzz} +\def\infounnumberedsubsec{\parsearg\unnumberedsubseczzz} +\def\infounnumberedsubsubsec{\parsearg\unnumberedsubsubseczzz} + +\def\infoappendix{\parsearg\appendixzzz} +\def\infoappendixsec{\parsearg\appendixseczzz} +\def\infoappendixsubsec{\parsearg\appendixsubseczzz} +\def\infoappendixsubsubsec{\parsearg\appendixsubsubseczzz} + +\def\infochapter{\parsearg\chapterzzz} +\def\infosection{\parsearg\sectionzzz} +\def\infosubsection{\parsearg\subsectionzzz} +\def\infosubsubsection{\parsearg\subsubsectionzzz} + +% These macros control what the section commands do, according +% to what kind of chapter we are in (ordinary, appendix, or unnumbered). +% Define them by default for a numbered chapter. +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec + +% Define @majorheading, @heading and @subheading + +% NOTE on use of \vbox for chapter headings, section headings, and +% such: +% 1) We use \vbox rather than the earlier \line to permit +% overlong headings to fold. +% 2) \hyphenpenalty is set to 10000 because hyphenation in a +% heading is obnoxious; this forbids it. +% 3) Likewise, headings look best if no \parindent is used, and +% if justification is not attempted. Hence \raggedright. + + +\def\majorheading{\parsearg\majorheadingzzz} +\def\majorheadingzzz #1{% +{\advance\chapheadingskip by 10pt \chapbreak }% +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\chapheading{\parsearg\chapheadingzzz} +\def\chapheadingzzz #1{\chapbreak % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\heading{\parsearg\secheadingi} + +\def\subheading{\parsearg\subsecheadingi} + +\def\subsubheading{\parsearg\subsubsecheadingi} + +% These macros generate a chapter, section, etc. heading only +% (including whitespace, linebreaking, etc. around it), +% given all the information in convenient, parsed form. + +%%% Args are the skip and penalty (usually negative) +\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} + +\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} + +%%% Define plain chapter starts, and page on/off switching for it +% Parameter controlling skip before chapter headings (if needed) + +\newskip \chapheadingskip \chapheadingskip = 30pt plus 8pt minus 4pt + +\def\chapbreak{\dobreak \chapheadingskip {-4000}} +\def\chappager{\par\vfill\supereject} +\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi} + +\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} + +\def\CHAPPAGoff{ +\global\let\pchapsepmacro=\chapbreak +\global\let\pagealignmacro=\chappager} + +\def\CHAPPAGon{ +\global\let\pchapsepmacro=\chappager +\global\let\pagealignmacro=\chappager +\global\def\HEADINGSon{\HEADINGSsingle}} + +\def\CHAPPAGodd{ +\global\let\pchapsepmacro=\chapoddpage +\global\let\pagealignmacro=\chapoddpage +\global\def\HEADINGSon{\HEADINGSdouble}} + +\CHAPPAGon + +\def\CHAPFplain{ +\global\let\chapmacro=\chfplain +\global\let\unnumbchapmacro=\unnchfplain} + +\def\chfplain #1#2{% + \pchapsepmacro + {% + \chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #2\enspace #1}% + }% + \bigskip + \penalty5000 +} + +\def\unnchfplain #1{% +\pchapsepmacro % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} +\CHAPFplain % The default + +\def\unnchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} + +\def\chfopen #1#2{\chapoddpage {\chapfonts +\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% +\par\penalty 5000 % +} + +\def\CHAPFopen{ +\global\let\chapmacro=\chfopen +\global\let\unnumbchapmacro=\unnchfopen} + +% Parameter controlling skip before section headings. + +\newskip \subsecheadingskip \subsecheadingskip = 17pt plus 8pt minus 4pt +\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} + +\newskip \secheadingskip \secheadingskip = 21pt plus 8pt minus 4pt +\def\secheadingbreak{\dobreak \secheadingskip {-1000}} + +% @paragraphindent is defined for the Info formatting commands only. +\let\paragraphindent=\comment + +% Section fonts are the base font at magstep2, which produces +% a size a bit more than 14 points in the default situation. + +\def\secheading #1#2#3{\secheadingi {#2.#3\enspace #1}} +\def\plainsecheading #1{\secheadingi {#1}} +\def\secheadingi #1{{\advance \secheadingskip by \parskip % +\secheadingbreak}% +{\secfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } + + +% Subsection fonts are the base font at magstep1, +% which produces a size of 12 points. + +\def\subsecheading #1#2#3#4{\subsecheadingi {#2.#3.#4\enspace #1}} +\def\subsecheadingi #1{{\advance \subsecheadingskip by \parskip % +\subsecheadingbreak}% +{\subsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } + +\def\subsubsecfonts{\subsecfonts} % Maybe this should change: + % Perhaps make sssec fonts scaled + % magstep half +\def\subsubsecheading #1#2#3#4#5{\subsubsecheadingi {#2.#3.#4.#5\enspace #1}} +\def\subsubsecheadingi #1{{\advance \subsecheadingskip by \parskip % +\subsecheadingbreak}% +{\subsubsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000} + + +\message{toc printing,} + +% Finish up the main text and prepare to read what we've written +% to \contentsfile. + +\newskip\contentsrightmargin \contentsrightmargin=1in +\def\startcontents#1{% + \pagealignmacro + \immediate\closeout \contentsfile + \ifnum \pageno>0 + \pageno = -1 % Request roman numbered pages. + \fi + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \unnumbchapmacro{#1}\def\thischapter{}% + \begingroup % Set up to handle contents files properly. + \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 + \raggedbottom % Worry more about breakpoints than the bottom. + \advance\hsize by -\contentsrightmargin % Don't use the full line length. +} + + +% Normal (long) toc. +\outer\def\contents{% + \startcontents{\putwordTableofContents}% + \input \jobname.toc + \endgroup + \vfill \eject +} + +% And just the chapters. +\outer\def\summarycontents{% + \startcontents{\putwordShortContents}% + % + \let\chapentry = \shortchapentry + \let\unnumbchapentry = \shortunnumberedentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl + \rm + \advance\baselineskip by 1pt % Open it up a little. + \def\secentry ##1##2##3##4{} + \def\unnumbsecentry ##1##2{} + \def\subsecentry ##1##2##3##4##5{} + \def\unnumbsubsecentry ##1##2{} + \def\subsubsecentry ##1##2##3##4##5##6{} + \def\unnumbsubsubsecentry ##1##2{} + \input \jobname.toc + \endgroup + \vfill \eject +} +\let\shortcontents = \summarycontents + +% These macros generate individual entries in the table of contents. +% The first argument is the chapter or section name. +% The last argument is the page number. +% The arguments in between are the chapter number, section number, ... + +% Chapter-level things, for both the long and short contents. +\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}} + +% See comments in \dochapentry re vbox and related settings +\def\shortchapentry#1#2#3{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno{#3}}% +} + +% Typeset the label for a chapter or appendix for the short contents. +% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter. +% We could simplify the code here by writing out an \appendixentry +% command in the toc file for appendices, instead of using \chapentry +% for both, but it doesn't seem worth it. +\setbox0 = \hbox{\shortcontrm \putwordAppendix } +\newdimen\shortappendixwidth \shortappendixwidth = \wd0 + +\def\shortchaplabel#1{% + % We typeset #1 in a box of constant width, regardless of the text of + % #1, so the chapter titles will come out aligned. + \setbox0 = \hbox{#1}% + \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi + % + % This space should be plenty, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in in \shortchapentry above.) + \advance\dimen0 by 1.1em + \hbox to \dimen0{#1\hfil}% +} + +\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}} +\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno{#2}}} + +% Sections. +\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} +\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}} + +% Subsections. +\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} +\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}} + +% And subsubsections. +\def\subsubsecentry#1#2#3#4#5#6{% + \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} +\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}} + + +% This parameter controls the indentation of the various levels. +\newdimen\tocindent \tocindent = 3pc + +% Now for the actual typesetting. In all these, #1 is the text and #2 is the +% page number. +% +% If the toc has to be broken over pages, we would want to be at chapters +% if at all possible; hence the \penalty. +\def\dochapentry#1#2{% + \penalty-300 \vskip\baselineskip + \begingroup + \chapentryfonts + \tocentry{#1}{\dopageno{#2}}% + \endgroup + \nobreak\vskip .25\baselineskip +} + +\def\dosecentry#1#2{\begingroup + \secentryfonts \leftskip=\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsecentry#1#2{\begingroup + \subsecentryfonts \leftskip=2\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsubsecentry#1#2{\begingroup + \subsubsecentryfonts \leftskip=3\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +% Final typesetting of a toc entry; we use the same \entry macro as for +% the index entries, but we want to suppress hyphenation here. (We +% 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.) +% +\def\tocentry#1#2{\begingroup + \hyphenpenalty = 10000 + \entry{#1}{#2}% +\endgroup} + +% Space between chapter (or whatever) number and the title. +\def\labelspace{\hskip1em \relax} + +\def\dopageno#1{{\rm #1}} +\def\doshortpageno#1{{\rm #1}} + +\def\chapentryfonts{\secfonts \rm} +\def\secentryfonts{\textfonts} +\let\subsecentryfonts = \textfonts +\let\subsubsecentryfonts = \textfonts + + +\message{environments,} + +% Since these characters are used in examples, it should be an even number of +% \tt widths. Each \tt character is 1en, so two makes it 1em. +% Furthermore, these definitions must come after we define our fonts. +\newbox\dblarrowbox \newbox\longdblarrowbox +\newbox\pushcharbox \newbox\bullbox +\newbox\equivbox \newbox\errorbox + +\let\ptexequiv = \equiv + +%{\tentt +%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil} +%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil} +%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil} +%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil} +% Adapted from the manmac format (p.420 of TeXbook) +%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex +% depth .1ex\hfil} +%} + +\def\point{$\star$} + +\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} +\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} +\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} + +\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} + +% Adapted from the TeXbook's \boxit. +{\tentt \global\dimen0 = 3em}% Width of the box. +\dimen2 = .55pt % Thickness of rules +% The text. (`r' is open on the right, `e' somewhat less so on the left.) +\setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt} + +\global\setbox\errorbox=\hbox to \dimen0{\hfil + \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. + \advance\hsize by -2\dimen2 % Rules. + \vbox{ + \hrule height\dimen2 + \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. + \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. + \kern3pt\vrule width\dimen2}% Space to right. + \hrule height\dimen2} + \hfil} + +% The @error{} command. +\def\error{\leavevmode\lower.7ex\copy\errorbox} + +% @tex ... @end tex escapes into raw Tex temporarily. +% One exception: @ is still an escape character, so that @end tex works. +% But \@ or @@ will get a plain tex @ character. + +\def\tex{\begingroup +\catcode `\\=0 \catcode `\{=1 \catcode `\}=2 +\catcode `\$=3 \catcode `\&=4 \catcode `\#=6 +\catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie +\catcode `\%=14 +\catcode 43=12 +\catcode`\"=12 +\catcode`\==12 +\catcode`\|=12 +\catcode`\<=12 +\catcode`\>=12 +\escapechar=`\\ +% +\let\~=\ptextilde +\let\{=\ptexlbrace +\let\}=\ptexrbrace +\let\.=\ptexdot +\let\*=\ptexstar +\let\dots=\ptexdots +\def\@{@}% +\let\bullet=\ptexbullet +\let\b=\ptexb \let\c=\ptexc \let\i=\ptexi \let\t=\ptext \let\l=\ptexl +\let\L=\ptexL +% +\let\Etex=\endgroup} + +% Define @lisp ... @endlisp. +% @lisp does a \begingroup so it can rebind things, +% including the definition of @endlisp (which normally is erroneous). + +% Amount to narrow the margins by for @lisp. +\newskip\lispnarrowing \lispnarrowing=0.4in + +% This is the definition that ^^M gets inside @lisp, @example, and other +% such environments. \null is better than a space, since it doesn't +% have any width. +\def\lisppar{\null\endgraf} + +% Make each space character in the input produce a normal interword +% space in the output. Don't allow a line break at this space, as this +% is used only in environments like @example, where each line of input +% should produce a line of output anyway. +% +{\obeyspaces % +\gdef\sepspaces{\obeyspaces\let =\tie}} + +% Define \obeyedspace to be our active space, whatever it is. This is +% for use in \parsearg. +{\sepspaces% +\global\let\obeyedspace= } + +% This space is always present above and below environments. +\newskip\envskipamount \envskipamount = 0pt + +% Make spacing and below environment symmetrical. We use \parskip here +% to help in doing that, since in @example-like environments \parskip +% is reset to zero; thus the \afterenvbreak inserts no space -- but the +% start of the next paragraph will insert \parskip +% +\def\aboveenvbreak{{\advance\envskipamount by \parskip +\endgraf \ifdim\lastskip<\envskipamount +\removelastskip \penalty-50 \vskip\envskipamount \fi}} + +\let\afterenvbreak = \aboveenvbreak + +% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins. +\let\nonarrowing=\relax + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \cartouche: draw rectangle w/rounded corners around argument +\font\circle=lcircle10 +\newdimen\circthick +\newdimen\cartouter\newdimen\cartinner +\newskip\normbskip\newskip\normpskip\newskip\normlskip +\circthick=\fontdimen8\circle +% +\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth +\def\ctr{{\hskip 6pt\circle\char'010}} +\def\cbl{{\circle\char'012\hskip -6pt}} +\def\cbr{{\hskip 6pt\circle\char'011}} +\def\carttop{\hbox to \cartouter{\hskip\lskip + \ctl\leaders\hrule height\circthick\hfil\ctr + \hskip\rskip}} +\def\cartbot{\hbox to \cartouter{\hskip\lskip + \cbl\leaders\hrule height\circthick\hfil\cbr + \hskip\rskip}} +% +\newskip\lskip\newskip\rskip + +\long\def\cartouche{% +\begingroup + \lskip=\leftskip \rskip=\rightskip + \leftskip=0pt\rightskip=0pt %we want these *outside*. + \cartinner=\hsize \advance\cartinner by-\lskip + \advance\cartinner by-\rskip + \cartouter=\hsize + \advance\cartouter by 18pt % allow for 3pt kerns on either +% side, and for 6pt waste from +% each corner char + \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip + % Flag to tell @lisp, etc., not to narrow margin. + \let\nonarrowing=\comment + \vbox\bgroup + \baselineskip=0pt\parskip=0pt\lineskip=0pt + \carttop + \hbox\bgroup + \hskip\lskip + \vrule\kern3pt + \vbox\bgroup + \hsize=\cartinner + \kern3pt + \begingroup + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip +\def\Ecartouche{% + \endgroup + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup +\endgroup +}} + + +% This macro is called at the beginning of all the @example variants, +% inside a group. +\def\nonfillstart{% + \aboveenvbreak + \inENV % This group ends at the end of the body + \hfuzz = 12pt % Don't be fussy + \sepspaces % Make spaces be word-separators rather than space tokens. + \singlespace + \let\par = \lisppar % don't ignore blank lines + \obeylines % each line of input is a line of output + \parskip = 0pt + \parindent = 0pt + \emergencystretch = 0pt % don't try to avoid overfull boxes + % @cartouche defines \nonarrowing to inhibit narrowing + % at next level down. + \ifx\nonarrowing\relax + \advance \leftskip by \lispnarrowing + \exdentamount=\lispnarrowing + \let\exdent=\nofillexdent + \let\nonarrowing=\relax + \fi +} + +% To ending an @example-like environment, we first end the paragraph +% (via \afterenvbreak's vertical glue), and then the group. That way we +% keep the zero \parskip that the environments set -- \parskip glue +% will be inserted at the beginning of the next paragraph in the +% document, after the environment. +% +\def\nonfillfinish{\afterenvbreak\endgroup}% + +% This macro is +\def\lisp{\begingroup + \nonfillstart + \let\Elisp = \nonfillfinish + \tt + \rawbackslash % have \ input char produce \ char from current font + \gobble +} + +% Define the \E... control sequence only if we are inside the +% environment, so the error checking in \end will work. +% +% We must call \lisp last in the definition, since it reads the +% return following the @example (or whatever) command. +% +\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} +\def\smallexample{\begingroup \def\Esmallexample{\nonfillfinish\endgroup}\lisp} +\def\smalllisp{\begingroup \def\Esmalllisp{\nonfillfinish\endgroup}\lisp} + +% @smallexample and @smalllisp. This is not used unless the @smallbook +% command is given. Originally contributed by Pavel@xerox. +% +\def\smalllispx{\begingroup + \nonfillstart + \let\Esmalllisp = \nonfillfinish + \let\Esmallexample = \nonfillfinish + % + % Smaller interline space and fonts for small examples. + \setleading{10pt}% + \indexfonts \tt + \rawbackslash % make \ output the \ character from the current font (tt) + \gobble +} + +% This is @display; same as @lisp except use roman font. +% +\def\display{\begingroup + \nonfillstart + \let\Edisplay = \nonfillfinish + \gobble +} + +% This is @format; same as @display except don't narrow margins. +% +\def\format{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eformat = \nonfillfinish + \gobble +} + +% @flushleft (same as @format) and @flushright. +% +\def\flushleft{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushleft = \nonfillfinish + \gobble +} +\def\flushright{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushright = \nonfillfinish + \advance\leftskip by 0pt plus 1fill + \gobble} + +% @quotation does normal linebreaking and narrows the margins. +% +\def\quotation{% +\begingroup\inENV %This group ends at the end of the @quotation body +{\parskip=0pt % because we will skip by \parskip too, later +\aboveenvbreak}% +\singlespace +\parindent=0pt +\let\Equotation = \nonfillfinish +% @cartouche defines \nonarrowing to inhibit narrowing +% at next level down. +\ifx\nonarrowing\relax +\advance \leftskip by \lispnarrowing +\advance \rightskip by \lispnarrowing +\exdentamount=\lispnarrowing +\let\nonarrowing=\relax +\fi} + +\message{defuns,} +% Define formatter for defuns +% First, allow user to change definition object font (\df) internally +\def\setdeffont #1 {\csname DEF#1\endcsname} + +\newskip\defbodyindent \defbodyindent=.4in +\newskip\defargsindent \defargsindent=50pt +\newskip\deftypemargin \deftypemargin=12pt +\newskip\deflastargmargin \deflastargmargin=18pt + +\newcount\parencount +% define \functionparens, which makes ( and ) and & do special things. +% \functionparens affects the group it is contained in. +\def\activeparens{% +\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active +\catcode`\[=\active \catcode`\]=\active} + +% Make control sequences which act like normal parenthesis chars. +\let\lparen = ( \let\rparen = ) + +{\activeparens % Now, smart parens don't turn on until &foo (see \amprm) + +% Be sure that we always have a definition for `(', etc. For example, +% if the fn name has parens in it, \boldbrax will not be in effect yet, +% so TeX would otherwise complain about undefined control sequence. +\global\let(=\lparen \global\let)=\rparen +\global\let[=\lbrack \global\let]=\rbrack + +\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 } +\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} + +% Definitions of (, ) and & used in args for functions. +% This is the definition of ( outside of all parentheses. +\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested % +\global\advance\parencount by 1 } +% +% This is the definition of ( when already inside a level of parens. +\gdef\opnested{\char`\(\global\advance\parencount by 1 } +% +\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0. +% also in that case restore the outer-level definition of (. +\ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi +\global\advance \parencount by -1 } +% If we encounter &foo, then turn on ()-hacking afterwards +\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ } +% +\gdef\normalparens{\boldbrax\let&=\ampnr} +} % End of definition inside \activeparens +%% These parens (in \boldbrax) actually are a little bolder than the +%% contained text. This is especially needed for [ and ] +\def\opnr{{\sf\char`\(}} \def\clnr{{\sf\char`\)}} \def\ampnr{\&} +\def\lbrb{{\bf\char`\[}} \def\rbrb{{\bf\char`\]}} + +% First, defname, which formats the header line itself. +% #1 should be the function name. +% #2 should be the type of definition, such as "Function". + +\def\defname #1#2{% +% Get the values of \leftskip and \rightskip as they were +% outside the @def... +\dimen2=\leftskip +\advance\dimen2 by -\defbodyindent +\dimen3=\rightskip +\advance\dimen3 by -\defbodyindent +\noindent % +\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}% +\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line +\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations +\parshape 2 0in \dimen0 \defargsindent \dimen1 % +% Now output arg 2 ("Function" or some such) +% ending at \deftypemargin from the right margin, +% but stuck inside a box of width 0 so it does not interfere with linebreaking +{% Adjust \hsize to exclude the ambient margins, +% so that \rightline will obey them. +\advance \hsize by -\dimen2 \advance \hsize by -\dimen3 +\rlap{\rightline{{\rm #2}\hskip \deftypemargin}}}% +% Make all lines underfull and no complaints: +\tolerance=10000 \hbadness=10000 +\advance\leftskip by -\defbodyindent +\exdentamount=\defbodyindent +{\df #1}\enskip % Generate function name +} + +% Actually process the body of a definition +% #1 should be the terminating control sequence, such as \Edefun. +% #2 should be the "another name" control sequence, such as \defunx. +% #3 should be the control sequence that actually processes the header, +% such as \defunheader. + +\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\activeparens\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % 61 is `=' +\obeylines\activeparens\spacesplit#3} + +\def\defmethparsebody #1#2#3#4 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#4}}} + +\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#5}}} + +% These parsing functions are similar to the preceding ones +% except that they do not make parens into active characters. +% These are used for "variables" since they have no arguments. + +\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % +\obeylines\spacesplit#3} + +% This is used for \def{tp,vr}parsebody. It could probably be used for +% some of the others, too, with some judicious conditionals. +% +\def\parsebodycommon#1#2#3{% + \begingroup\inENV % + \medbreak % + % Define the end token that this defining construct specifies + % so that it will exit this group. + \def#1{\endgraf\endgroup\medbreak}% + \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}% + \parindent=0in + \advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent + \exdentamount=\defbodyindent + \begingroup\obeylines +} + +\def\defvrparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{#3{#4}}% +} + +% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the +% type is just `struct', because we lose the braces in `{struct +% termios}' when \spacesplit reads its undelimited argument. Sigh. +% \let\deftpparsebody=\defvrparsebody +% +% So, to get around this, we put \empty in with the type name. That +% way, TeX won't find exactly `{...}' as an undelimited argument, and +% won't strip off the braces. +% +\def\deftpparsebody #1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{\parsetpheaderline{#3{#4}}}\empty +} + +% Fine, but then we have to eventually remove the \empty *and* the +% braces (if any). That's what this does, putting the result in \tptemp. +% +\def\removeemptybraces\empty#1\relax{\def\tptemp{#1}}% + +% After \spacesplit has done its work, this is called -- #1 is the final +% thing to call, #2 the type name (which starts with \empty), and #3 +% (which might be empty) the arguments. +% +\def\parsetpheaderline#1#2#3{% + \removeemptybraces#2\relax + #1{\tptemp}{#3}% +}% + +\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\spacesplit{#3{#5}}} + +% Split up #2 at the first space token. +% call #1 with two arguments: +% the first is all of #2 before the space token, +% the second is all of #2 after that space token. +% If #2 contains no space token, all of it is passed as the first arg +% and the second is passed as empty. + +{\obeylines +\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}% +\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{% +\ifx\relax #3% +#1{#2}{}\else #1{#2}{#3#4}\fi}} + +% So much for the things common to all kinds of definitions. + +% Define @defun. + +% First, define the processing that is wanted for arguments of \defun +% Use this to expand the args and terminate the paragraph they make up + +\def\defunargs #1{\functionparens \sl +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +\hyphenchar\tensl=0 +#1% +\hyphenchar\tensl=45 +\ifnum\parencount=0 \else \errmessage{unbalanced parens in @def arguments}\fi% +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +\def\deftypefunargs #1{% +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +\functionparens +\tclose{#1}% avoid \code because of side effects on active chars +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +% Do complete processing of one @defun or @defunx line already parsed. + +% @deffn Command forward-char nchars + +\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader} + +\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}% +\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defun == @deffn Function + +\def\defun{\defparsebody\Edefun\defunx\defunheader} + +\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Function}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefun int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader} + +% #1 is the data type. #2 is the name and args. +\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax} +% #1 is the data type, #2 the name, #3 the args. +\def\deftypefunheaderx #1#2 #3\relax{% +\doind {fn}{\code{#2}}% Make entry in function index +\begingroup\defname {\code{#1} #2}{Function}% +\deftypefunargs {#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader} + +% #1 is the classification. #2 is the data type. #3 is the name and args. +\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax} +% #1 is the classification, #2 the data type, #3 the name, #4 the args. +\def\deftypefnheaderx #1#2#3 #4\relax{% +\doind {fn}{\code{#3}}% Make entry in function index +\begingroup +\normalparens % notably, turn off `&' magic, which prevents +% at least some C++ text from working +\defname {\code{#2} #3}{#1}% +\deftypefunargs {#4}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defmac == @deffn Macro + +\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader} + +\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Macro}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defspec == @deffn Special Form + +\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader} + +\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Special Form}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% This definition is run if you use @defunx +% anywhere other than immediately after a @defun or @defunx. + +\def\deffnx #1 {\errmessage{@deffnx in invalid context}} +\def\defunx #1 {\errmessage{@defunx in invalid context}} +\def\defmacx #1 {\errmessage{@defmacx in invalid context}} +\def\defspecx #1 {\errmessage{@defspecx in invalid context}} +\def\deftypefnx #1 {\errmessage{@deftypefnx in invalid context}} +\def\deftypeunx #1 {\errmessage{@deftypeunx in invalid context}} + +% @defmethod, and so on + +% @defop {Funny Method} foo-class frobnicate argument + +\def\defop #1 {\def\defoptype{#1}% +\defopparsebody\Edefop\defopx\defopheader\defoptype} + +\def\defopheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% Make entry in function index +\begingroup\defname {#2}{\defoptype{} on #1}% +\defunargs {#3}\endgroup % +} + +% @defmethod == @defop Method + +\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} + +\def\defmethodheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% entry in function index +\begingroup\defname {#2}{Method on #1}% +\defunargs {#3}\endgroup % +} + +% @defcv {Class Option} foo-class foo-flag + +\def\defcv #1 {\def\defcvtype{#1}% +\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype} + +\def\defcvarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{\defcvtype{} of #1}% +\defvarargs {#3}\endgroup % +} + +% @defivar == @defcv {Instance Variable} + +\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} + +\def\defivarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{Instance Variable of #1}% +\defvarargs {#3}\endgroup % +} + +% These definitions are run if you use @defmethodx, etc., +% anywhere other than immediately after a @defmethod, etc. + +\def\defopx #1 {\errmessage{@defopx in invalid context}} +\def\defmethodx #1 {\errmessage{@defmethodx in invalid context}} +\def\defcvx #1 {\errmessage{@defcvx in invalid context}} +\def\defivarx #1 {\errmessage{@defivarx in invalid context}} + +% Now @defvar + +% First, define the processing that is wanted for arguments of @defvar. +% This is actually simple: just print them in roman. +% This must expand the args and terminate the paragraph they make up +\def\defvarargs #1{\normalparens #1% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000} + +% @defvr Counter foo-count + +\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader} + +\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}% +\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup} + +% @defvar == @defvr Variable + +\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader} + +\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{Variable}% +\defvarargs {#2}\endgroup % +} + +% @defopt == @defvr {User Option} + +\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader} + +\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{User Option}% +\defvarargs {#2}\endgroup % +} + +% @deftypevar int foobar + +\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} + +% #1 is the data type. #2 is the name. +\def\deftypevarheader #1#2{% +\doind {vr}{\code{#2}}% Make entry in variables index +\begingroup\defname {\code{#1} #2}{Variable}% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% @deftypevr {Global Flag} int enable + +\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} + +\def\deftypevrheader #1#2#3{\doind {vr}{\code{#3}}% +\begingroup\defname {\code{#2} #3}{#1} +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% This definition is run if you use @defvarx +% anywhere other than immediately after a @defvar or @defvarx. + +\def\defvrx #1 {\errmessage{@defvrx in invalid context}} +\def\defvarx #1 {\errmessage{@defvarx in invalid context}} +\def\defoptx #1 {\errmessage{@defoptx in invalid context}} +\def\deftypevarx #1 {\errmessage{@deftypevarx in invalid context}} +\def\deftypevrx #1 {\errmessage{@deftypevrx in invalid context}} + +% Now define @deftp +% Args are printed in bold, a slight difference from @defvar. + +\def\deftpargs #1{\bf \defvarargs{#1}} + +% @deftp Class window height width ... + +\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader} + +\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}% +\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup} + +% This definition is run if you use @deftpx, etc +% anywhere other than immediately after a @deftp, etc. + +\def\deftpx #1 {\errmessage{@deftpx in invalid context}} + +\message{cross reference,} +% Define cross-reference macros +\newwrite \auxfile + +\newif\ifhavexrefs % True if xref values are known. +\newif\ifwarnedxrefs % True if we warned once that they aren't known. + +% \setref{foo} defines a cross-reference point named foo. + +\def\setref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ysectionnumberandtype}} + +\def\unnumbsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ynothing}} + +\def\appendixsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Yappendixletterandtype}} + +% \xref, \pxref, and \ref generate cross-references to specified points. +% For \xrefX, #1 is the node name, #2 the name of the Info +% cross-reference, #3 the printed node name, #4 the name of the Info +% file, #5 the name of the printed manual. All but the node name can be +% omitted. +% +\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} +\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} +\def\ref#1{\xrefX[#1,,,,,,,]} +\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup% +\def\printedmanual{\ignorespaces #5}% +\def\printednodename{\ignorespaces #3}% +\def\correctnodename{{\normalturnoffactive\printednodename}}% +\setbox1=\hbox{\printedmanual}% +\setbox0=\hbox{\printednodename}% +\ifdim \wd0=0pt% +% No printed node name was explicitly given. +\ifx SETxref-automatic-section-title % +% This line should make the actual chapter or section title appear inside +% the square brackets. Use the real section title if we have it. +\ifdim \wd1>0pt% +% It is in another manual, so we don't have it. +\def\printednodename{\ignorespaces #1} \else% +% We know the real title if we have the xref values. +\ifhavexrefs \def\printednodename{\refx{#1-title}}% +% Otherwise just copy the Info node name. +\else \def\printednodename{\ignorespaces #1} \fi% +\fi\def\printednodename{#1-title}% +\else% This line just uses the node name. +\def\printednodename{\ignorespaces #1}% +\fi% ends \ifx SETxref-automatic-section-title +\fi% ends \ifdim \wd0 +% +% +% If we use \unhbox0 and \unhbox1 to print the node names, TeX does +% not insert empty discretionaries after hyphens, which means that it +% will not find a line break at a hyphen in a node names. Since some +% manuals are best written with fairly long node names, containing +% hyphens, this is a loss. Therefore, we simply give the text of +% the node name again, so it is as if TeX is seeing it for the first +% time. +\ifdim \wd1>0pt +\putwordsection{} ``\correctnodename'' in \cite{\printedmanual}% +\else% +\turnoffactive% +\refx{#1-snt}{} [\correctnodename], \putwordpage\tie\refx{#1-pg}{}% +\fi +\endgroup} + +% \dosetq is the interface for calls from other macros + +% Use \turnoffactive so that punctuation chars such as underscore +% work in node names. +\def\dosetq #1#2{{\let\folio=0 \turnoffactive% +\edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% +\next}} + +% \internalsetq {foo}{page} expands into +% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...} +% When the aux file is read, ' is the escape character + +\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}} + +% Things to be expanded by \internalsetq + +\def\Ypagenumber{\folio} + +\def\Ytitle{\thissection} + +\def\Ynothing{} + +\def\Ysectionnumberandtype{% +\ifnum\secno=0 \putwordChapter\xreftie\the\chapno % +\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\def\Yappendixletterandtype{% +\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}% +\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\gdef\xreftie{'tie} + +% Use TeX 3.0's \inputlineno to get the line number, for better error +% messages, but if we're using an old version of TeX, don't do anything. +% +\ifx\inputlineno\thisisundefined + \let\linenumber = \empty % Non-3.0. +\else + \def\linenumber{\the\inputlineno:\space} +\fi + +% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. +% If its value is nonempty, SUFFIX is output afterward. + +\def\refx#1#2{% + \expandafter\ifx\csname X#1\endcsname\relax + % If not defined, say something at least. + $\langle$un\-de\-fined$\rangle$% + \ifhavexrefs + \message{\linenumber Undefined cross reference `#1'.}% + \else + \ifwarnedxrefs\else + \global\warnedxrefstrue + \message{Cross reference values unknown; you must run TeX again.}% + \fi + \fi + \else + % It's defined, so just use it. + \csname X#1\endcsname + \fi + #2% Output the suffix in any case. +} + +% Read the last existing aux file, if any. No error if none exists. + +% This is the macro invoked by entries in the aux file. +\def\xrdef #1#2{ +{\catcode`\'=\other\expandafter \gdef \csname X#1\endcsname {#2}}} + +\def\readauxfile{% +\begingroup +\catcode `\^^@=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\^^C=\other +\catcode `\^^D=\other +\catcode `\^^E=\other +\catcode `\^^F=\other +\catcode `\^^G=\other +\catcode `\^^H=\other +\catcode `\ =\other +\catcode `\^^L=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode 26=\other +\catcode `\^^[=\other +\catcode `\^^\=\other +\catcode `\^^]=\other +\catcode `\^^^=\other +\catcode `\^^_=\other +\catcode `\@=\other +\catcode `\^=\other +\catcode `\~=\other +\catcode `\[=\other +\catcode `\]=\other +\catcode`\"=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode `\$=\other +\catcode `\#=\other +\catcode `\&=\other +% `\+ does not work, so use 43. +\catcode 43=\other +% the aux file uses ' as the escape. +% Turn off \ as an escape so we do not lose on +% entries which were dumped with control sequences in their names. +% For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^ +% Reference to such entries still does not work the way one would wish, +% but at least they do not bomb out when the aux file is read in. +\catcode `\{=1 \catcode `\}=2 +\catcode `\%=\other +\catcode `\'=0 +\catcode `\\=\other +\openin 1 \jobname.aux +\ifeof 1 \else \closein 1 \input \jobname.aux \global\havexrefstrue +\global\warnedobstrue +\fi +% Open the new aux file. Tex will close it automatically at exit. +\openout \auxfile=\jobname.aux +\endgroup} + + +% Footnotes. + +\newcount \footnoteno + +% The trailing space in the following definition for supereject is +% vital for proper filling; pages come out unaligned when you do a +% pagealignmacro call if that space before the closing brace is +% removed. +\def\supereject{\par\penalty -20000\footnoteno =0 } + +% @footnotestyle is meaningful for info output only.. +\let\footnotestyle=\comment + +\let\ptexfootnote=\footnote + +{\catcode `\@=11 +% +% Auto-number footnotes. Otherwise like plain. +\gdef\footnote{% + \global\advance\footnoteno by \@ne + \edef\thisfootno{$^{\the\footnoteno}$}% + % + % In case the footnote comes at the end of a sentence, preserve the + % extra spacing after we do the footnote number. + \let\@sf\empty + \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi + % + % Remove inadvertent blank space before typesetting the footnote number. + \unskip + \thisfootno\@sf + \footnotezzz +}% + +% Don't bother with the trickery in plain.tex to not require the +% footnote text as a parameter. Our footnotes don't need to be so general. +% +\long\gdef\footnotezzz#1{\insert\footins{% + % We want to typeset this text as a normal paragraph, even if the + % footnote reference occurs in (for example) a display environment. + % So reset some parameters. + \interlinepenalty\interfootnotelinepenalty + \splittopskip\ht\strutbox % top baseline for broken footnotes + \splitmaxdepth\dp\strutbox + \floatingpenalty\@MM + \leftskip\z@skip + \rightskip\z@skip + \spaceskip\z@skip + \xspaceskip\z@skip + \parindent\defaultparindent + % + % Hang the footnote text off the number. + \hang + \textindent{\thisfootno}% + % + % Don't crash into the line above the footnote text. Since this + % expands into a box, it must come within the paragraph, lest it + % provide a place where TeX can split the footnote. + \footstrut + #1\strut}% +} + +}%end \catcode `\@=11 + +% Set the baselineskip to #1, and the lineskip and strut size +% correspondingly. There is no deep meaning behind these magic numbers +% used as factors; they just match (closely enough) what Knuth defined. +% +\def\lineskipfactor{.08333} +\def\strutheightpercent{.70833} +\def\strutdepthpercent {.29167} +% +\def\setleading#1{% + \normalbaselineskip = #1\relax + \normallineskip = \lineskipfactor\normalbaselineskip + \normalbaselines + \setbox\strutbox =\hbox{% + \vrule width0pt height\strutheightpercent\baselineskip + depth \strutdepthpercent \baselineskip + }% +} + +% @| inserts a changebar to the left of the current line. It should +% surround any changed text. This approach does *not* work if the +% change spans more than two lines of output. To handle that, we would +% have adopt a much more difficult approach (putting marks into the main +% vertical list for the beginning and end of each change). +% +\def\|{% + % \vadjust can only be used in horizontal mode. + \leavevmode + % + % Append this vertical mode material after the current line in the output. + \vadjust{% + % We want to insert a rule with the height and depth of the current + % leading; that is exactly what \strutbox is supposed to record. + \vskip-\baselineskip + % + % \vadjust-items are inserted at the left edge of the type. So + % the \llap here moves out into the left-hand margin. + \llap{% + % + % For a thicker or thinner bar, change the `1pt'. + \vrule height\baselineskip width1pt + % + % This is the space between the bar and the text. + \hskip 12pt + }% + }% +} + +% For a final copy, take out the rectangles +% that mark overfull boxes (in case you have decided +% that the text looks ok even though it passes the margin). +% +\def\finalout{\overfullrule=0pt} + + +% End of control word definitions. + +\message{and turning on texinfo input format.} + +\def\openindices{% + \newindex{cp}% + \newcodeindex{fn}% + \newcodeindex{vr}% + \newcodeindex{tp}% + \newcodeindex{ky}% + \newcodeindex{pg}% +} + +% Set some numeric style parameters, for 8.5 x 11 format. + +%\hsize = 6.5in +\newdimen\defaultparindent \defaultparindent = 15pt +\parindent = \defaultparindent +\parskip 18pt plus 1pt +\setleading{15pt} +\advance\topskip by 1.2cm + +% Prevent underfull vbox error messages. +\vbadness=10000 + +% Following George Bush, just get rid of widows and orphans. +\widowpenalty=10000 +\clubpenalty=10000 + +% Use TeX 3.0's \emergencystretch to help line breaking, but if we're +% using an old version of TeX, don't do anything. We want the amount of +% stretch added to depend on the line length, hence the dependence on +% \hsize. This makes it come to about 9pt for the 8.5x11 format. +% +\ifx\emergencystretch\thisisundefined + % Allow us to assign to \emergencystretch anyway. + \def\emergencystretch{\dimen0}% +\else + \emergencystretch = \hsize + \divide\emergencystretch by 45 +\fi + +% Use @smallbook to reset parameters for 7x9.5 format (or else 7x9.25) +\def\smallbook{ + +% These values for secheadingskip and subsecheadingskip are +% experiments. RJC 7 Aug 1992 +\global\secheadingskip = 17pt plus 6pt minus 3pt +\global\subsecheadingskip = 14pt plus 6pt minus 3pt + +\global\lispnarrowing = 0.3in +\setleading{12pt} +\advance\topskip by -1cm +\global\parskip 3pt plus 1pt +\global\hsize = 5in +\global\vsize=7.5in +\global\tolerance=700 +\global\hfuzz=1pt +\global\contentsrightmargin=0pt +\global\deftypemargin=0pt +\global\defbodyindent=.5cm + +\global\pagewidth=\hsize +\global\pageheight=\vsize + +\global\let\smalllisp=\smalllispx +\global\let\smallexample=\smalllispx +\global\def\Esmallexample{\Esmalllisp} +} + +% Use @afourpaper to print on European A4 paper. +\def\afourpaper{ +\global\tolerance=700 +\global\hfuzz=1pt +\setleading{12pt} +\global\parskip 15pt plus 1pt + +\global\vsize= 53\baselineskip +\advance\vsize by \topskip +%\global\hsize= 5.85in % A4 wide 10pt +\global\hsize= 6.5in +\global\outerhsize=\hsize +\global\advance\outerhsize by 0.5in +\global\outervsize=\vsize +\global\advance\outervsize by 0.6in + +\global\pagewidth=\hsize +\global\pageheight=\vsize +} + +% Define macros to output various characters with catcode for normal text. +\catcode`\"=\other +\catcode`\~=\other +\catcode`\^=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode`\+=\other +\def\normaldoublequote{"} +\def\normaltilde{~} +\def\normalcaret{^} +\def\normalunderscore{_} +\def\normalverticalbar{|} +\def\normalless{<} +\def\normalgreater{>} +\def\normalplus{+} + +% This macro is used to make a character print one way in ttfont +% where it can probably just be output, and another way in other fonts, +% where something hairier probably needs to be done. +% +% #1 is what to print if we are indeed using \tt; #2 is what to print +% otherwise. 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, we can check that font parameter. +% +\def\ifusingtt#1#2{\ifdim \fontdimen3\the\font=0pt #1\else #2\fi} + +% Turn off all special characters except @ +% (and those which the user can use as if they were ordinary). +% Most of these we simply print from the \tt font, but for some, we can +% use math or other variants that look better in normal text. + +\catcode`\"=\active +\def\activedoublequote{{\tt \char '042}} +\let"=\activedoublequote +\catcode`\~=\active +\def~{{\tt \char '176}} +\chardef\hat=`\^ +\catcode`\^=\active +\def^{{\tt \hat}} + +\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{}} + +\catcode`\|=\active +\def|{{\tt \char '174}} +\chardef \less=`\< +\catcode`\<=\active +\def<{{\tt \less}} +\chardef \gtr=`\> +\catcode`\>=\active +\def>{{\tt \gtr}} +\catcode`\+=\active +\def+{{\tt \char 43}} +%\catcode 27=\active +%\def^^[{$\diamondsuit$} + +% Set up an active definition for =, but don't enable it most of the time. +{\catcode`\==\active +\global\def={{\tt \char 61}}} + +\catcode`\@=0 + +% \rawbackslashxx output one backslash character in current font +\global\chardef\rawbackslashxx=`\\ +%{\catcode`\\=\other +%@gdef@rawbackslashxx{\}} + +% \rawbackslash redefines \ as input to do \rawbackslashxx. +{\catcode`\\=\active +@gdef@rawbackslash{@let\=@rawbackslashxx }} + +% \normalbackslash outputs one backslash in fixed width font. +\def\normalbackslash{{\tt\rawbackslashxx}} + +% Say @foo, not \foo, in error messages. +\escapechar=`\@ + +% \catcode 17=0 % Define control-q +\catcode`\\=\active + +% Used sometimes to turn off (effectively) the active characters +% even after parsing them. +@def@turnoffactive{@let"=@normaldoublequote +@let\=@realbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +@def@normalturnoffactive{@let"=@normaldoublequote +@let\=@normalbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +% If a .fmt file is being used, we don't want the `\input texinfo' to show up. +% That is what \eatinput is for; after that, the `\' should revert to printing +% a backslash. +% +@gdef@eatinput input texinfo{@fixbackslash} +@global@let\ = @eatinput + +% On the other hand, perhaps the file did not have a `\input texinfo'. Then +% the first `\{ in the file would cause an error. This macro tries to fix +% that, assuming it is called before the first `\' could plausibly occur. +% +@gdef@fixbackslash{@ifx\@eatinput @let\ = @normalbackslash @fi} + +%% These look ok in all fonts, so just make them not special. The @rm below +%% makes sure that the current font starts out as the newly loaded cmr10 +@catcode`@$=@other @catcode`@%=@other @catcode`@&=@other @catcode`@#=@other + +@textfonts +@rm + +@c Local variables: +@c page-delimiter: "^\\\\message" +@c End: