diff options
author | 1994-10-26 16:52:50 +0000 | |
---|---|---|
committer | 1994-10-26 16:52:50 +0000 | |
commit | 29f84717e9d1ac7aebd90d553ca9d0d6e89a2222 (patch) | |
tree | 49274dd97e14234822d2611753fe4fc6d4cf48fd /util | |
parent | 3dbe801c58450f1acc0135bc66debaa8af848a26 (diff) |
Initial revision
Diffstat (limited to 'util')
-rw-r--r-- | util/autoconf/INSTALL | 167 | ||||
-rw-r--r-- | util/autoconf/Makefile.in | 207 | ||||
-rw-r--r-- | util/autoconf/README | 38 | ||||
-rw-r--r-- | util/autoconf/acconfig.h | 248 | ||||
-rwxr-xr-x | util/autoconf/autoconf.sh | 152 | ||||
-rwxr-xr-x | util/autoconf/autoheader.sh | 250 | ||||
-rw-r--r-- | util/autoconf/configure.in | 31 | ||||
-rw-r--r-- | util/autoconf/make-stds.texi | 625 | ||||
-rw-r--r-- | util/autoconf/standards.info | 60 | ||||
-rw-r--r-- | util/autoconf/standards.texi | 2409 | ||||
-rw-r--r-- | util/et/Makefile.in | 126 | ||||
-rw-r--r-- | util/ss/ChangeLog | 65 | ||||
-rw-r--r-- | util/ss/Makefile.in | 159 | ||||
-rw-r--r-- | util/ss/list_rqs.c | 88 | ||||
-rw-r--r-- | util/ss/listen.c | 130 |
15 files changed, 4755 insertions, 0 deletions
diff --git a/util/autoconf/INSTALL b/util/autoconf/INSTALL new file mode 100644 index 0000000..0338fbc --- /dev/null +++ b/util/autoconf/INSTALL @@ -0,0 +1,167 @@ +Basic Installation +================== + + These are generic installation instructions. + + The `configure' shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a `Makefile' in each directory of the package. +It may also create one or more `.h' files containing system-dependent +definitions. Finally, it creates a shell script `config.status' that +you can run in the future to recreate the current configuration, a file +`config.cache' that saves the results of its tests to speed up +reconfiguring, and a file `config.log' containing compiler output +(useful mainly for debugging `configure'). + + If you need to do unusual things to compile the package, please try +to figure out how `configure' could check whether to do them, and mail +diffs or instructions to the address given in the `README' so they can +be considered for the next release. If at some point `config.cache' +contains results you don't want to keep, you may remove or edit it. + + The file `configure.in' is used to create `configure' by a program +called `autoconf'. You only need `configure.in' if you want to change +it or regenerate `configure' using a newer version of `autoconf'. + +The simplest way to compile this package is: + + 1. `cd' to the directory containing the package's source code and type + `./configure' to configure the package for your system. If you're + using `csh' on an old version of System V, you might need to type + `sh ./configure' instead to prevent `csh' from trying to execute + `configure' itself. + + Running `configure' takes awhile. While running, it prints some + messages telling which features it is checking for. + + 2. Type `make' to compile the package. + + 3. Optionally, type `make check' to run any self-tests that come with + the package. + + 4. Type `make install' to install the programs and any data files and + documentation. + + 5. You can remove the program binaries and object files from the + source directory by typing `make clean'. To also remove the files + that `configure' created (so you can compile the package for a + different kind of computer), type `make distclean'. + +Compilers and Options +===================== + + Some systems require unusual options for compilation or linking that +the `configure' script does not know about. You can give `configure' +initial values for variables by setting them in the environment. Using +a Bourne-compatible shell, you can do that on the command line like +this: + CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure + +Or on systems that have the `env' program, you can do it like this: + env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure + +Using a Different Build Directory +================================= + + You can compile the package in a different directory from the one +containing the source code. Doing so allows you to compile it on more +than one kind of computer at the same time. To do this, you must use a +version of `make' that supports the `VPATH' variable, such as GNU +`make'. `cd' to the directory where you want the object files and +executables to go and run the `configure' script. `configure' +automatically checks for the source code in the directory that +`configure' is in and in `..'. + +Installation Names +================== + + By default, `make install' will install the package's files in +`/usr/local/bin', `/usr/local/man', etc. You can specify an +installation prefix other than `/usr/local' by giving `configure' the +option `--prefix=PATH'. + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +give `configure' the option `--exec-prefix=PATH', the package will use +PATH as the prefix for installing programs and libraries. +Documentation and other data files will still use the regular prefix. + + If the package supports it, you can cause programs to be installed +with an extra prefix or suffix on their names by giving `configure' the +option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. + +Optional Features +================= + + Some packages pay attention to `--enable-FEATURE' options to +`configure', where FEATURE indicates an optional part of the package. +They may also pay attention to `--with-PACKAGE' options, where PACKAGE +is something like `gnu-as' or `x' (for the X Window System). The +`README' should mention any `--enable-' and `--with-' options that the +package recognizes. + + For packages that use the X Window System, `configure' can usually +find the X include and library files automatically, but if it doesn't, +you can use the `configure' options `--x-includes=DIR' and +`--x-libraries=DIR' to specify their locations. + +Specifying the System Type +========================== + + There may be some features `configure' can not figure out +automatically, but needs to determine by the type of host the package +will run on. Usually `configure' can figure that out, but if it prints +a message saying it can not guess the host type, give it the +`--host=TYPE' option. TYPE can either be a short name for the system +type, such as `sun4', or a canonical name with three fields: + CPU-COMPANY-SYSTEM + +See the file `config.sub' for the possible values of each field. If +`config.sub' isn't included in this package, then this package doesn't +need to know the host type. + + If you are building compiler tools for cross-compiling, you can also +use the `--target=TYPE' option to select the type of system they will +produce code for and the `--build=TYPE' option to select the type of +system on which you are compiling the package. + +Sharing Defaults +================ + + If you want to set default values for `configure' scripts to share, +you can create a site shell script called `config.site' that gives +default values for variables like `CC', `cache_file', and `prefix'. +`configure' looks for `PREFIX/share/config.site' if it exists, then +`PREFIX/etc/config.site' if it exists. Or, you can set the +`CONFIG_SITE' environment variable to the location of the site script. +A warning: not all `configure' scripts look for a site script. + +Operation Controls +================== + + `configure' recognizes the following options to control how it +operates. + +`--cache-file=FILE' + Save the results of the tests in FILE instead of `config.cache'. + Set FILE to `/dev/null' to disable caching, for debugging + `configure'. + +`--help' + Print a summary of the options to `configure', and exit. + +`--quiet' +`--silent' +`-q' + Do not print messages saying which checks are being made. + +`--srcdir=DIR' + Look for the package's source code in directory DIR. Usually + `configure' can determine that directory automatically. + +`--version' + Print the version of Autoconf used to generate the `configure' + script, and exit. + +`configure' also accepts some other, not widely useful, options. + diff --git a/util/autoconf/Makefile.in b/util/autoconf/Makefile.in new file mode 100644 index 0000000..e7aab1d --- /dev/null +++ b/util/autoconf/Makefile.in @@ -0,0 +1,207 @@ +# Makefile for Autoconf. +# 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. + +#### Start of system configuration section. #### + +srcdir = @srcdir@ +VPATH = @srcdir@ + +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_DATA = @INSTALL_DATA@ +MAKEINFO = makeinfo +TEXI2DVI = texi2dvi +M4 = @M4@ +PERL = @PERL@ + +# Programs that are always installed. +ASCRIPTS = autoconf autoheader autoreconf autoupdate ifnames +SCRIPTS = $(ASCRIPTS) @SCRIPTS@ + +transform=@program_transform_name@ + +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +# Directory in which to install scripts. +bindir = $(exec_prefix)/bin + +# Directory in which to install library files. +datadir = $(prefix)/share +acdatadir = $(datadir)/autoconf + +# Directory in which to install documentation info files. +infodir = $(prefix)/info + +#### End of system configuration section. #### + +SHELL = /bin/sh + +SUBDIRS = testsuite + +M4FILES = autoconf.m4 acgeneral.m4 acoldnames.m4 acspecific.m4 autoheader.m4 + +# Files that can be generated, but should be up to date for a distribution. +DISTDEP = info Makefile +# Files to distribute. +DISTFILES = COPYING ChangeLog ChangeLog.1 INSTALL \ + Makefile.in NEWS README TODO $(M4FILES) \ + acconfig.h acfunctions acheaders acidentifiers \ + acmakevars acprograms autoconf.info* \ + autoconf.sh autoconf.texi install.texi \ + autoheader.sh autoscan.pl autoreconf.sh autoupdate.sh ifnames.sh \ + config.guess config.sub configure configure.in \ + install-sh mkinstalldirs texinfo.tex \ + testsuite/Makefile.in testsuite/config/*.exp \ + testsuite/lib/*.exp testsuite/autoconf.[gs]/*.exp \ + standards.texi make-stds.texi standards.info* + +editsh = sed -e 's,@''datadir''@,$(acdatadir),g' -e 's,@''M4''@,$(M4),g' +editpl = sed -e 's,@''datadir''@,$(acdatadir),g' -e 's,@''PERL''@,$(PERL),g' + +all: ${SCRIPTS} + +.SUFFIXES: +.SUFFIXES: .sh .pl + +.sh: + rm -f $@ $@.tmp + $(editsh) $< > $@.tmp && chmod +x $@.tmp && mv $@.tmp $@ + +.pl: + rm -f $@ $@.tmp + $(editpl) $< > $@.tmp && chmod +x $@.tmp && mv $@.tmp $@ + +info: autoconf.info @standards_info@ INSTALL + +autoconf.info: autoconf.texi install.texi + $(MAKEINFO) -I$(srcdir) $(srcdir)/autoconf.texi --output=$@ + +INSTALL: install.texi + $(MAKEINFO) -I$(srcdir) $(srcdir)/install.texi --output=$@ \ + --no-headers --no-validate + +standards.info: standards.texi make-stds.texi + $(MAKEINFO) -I$(srcdir) $(srcdir)/standards.texi --output=$@ + +dvi: autoconf.dvi @standards_dvi@ + +autoconf.dvi: autoconf.texi + $(TEXI2DVI) $(srcdir)/autoconf.texi + +standards.dvi: standards.texi make-stds.texi + $(TEXI2DVI) $(srcdir)/standards.texi + +check: all + rootme=`pwd`; srcrootme=`cd $(srcdir); pwd`; \ + test -r install-sh || cp $(srcdir)/install-sh .; \ + cd testsuite && ${MAKE} $@ AUTOCONF=$$rootme/autoconf \ + AUTOCONFFLAGS="-m $$srcrootme" + +installcheck: all install + cd testsuite && ${MAKE} AUTOCONF=${bindir}/autoconf $@ + +installdirs: + $(SHELL) ${srcdir}/mkinstalldirs $(bindir) $(infodir) $(acdatadir) + +install: all $(M4FILES) acconfig.h installdirs install-info + @case `$(M4) --help < /dev/null 2>&1` in \ + *reload-state*) echo installing frozen m4 files; \ + $(M4) -F $(acdatadir)/autoconf.m4f -I${srcdir} ${srcdir}/autoconf.m4 ; \ + $(M4) -F $(acdatadir)/autoheader.m4f -I${srcdir} ${srcdir}/autoheader.m4 ;; \ + *traditional*) ;; \ + *) echo Error: Autoconf requires GNU m4 1.1 or later; exit 1 ;; \ + esac + for p in $(ASCRIPTS); do \ + $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p|sed '$(transform)'`; \ + done + for i in $(M4FILES) acconfig.h; do \ + $(INSTALL_DATA) $(srcdir)/$$i $(acdatadir)/$$i; \ + done + -if test -f autoscan; then \ + $(INSTALL_PROGRAM) autoscan $(bindir)/`echo autoscan|sed '$(transform)'`; \ + for i in acfunctions acheaders acidentifiers acprograms \ + acmakevars; do \ + $(INSTALL_DATA) $(srcdir)/$$i $(acdatadir)/$$i; \ + done; \ + else :; fi + +install-info: info installdirs + -test -f autoconf.info || cd $(srcdir); \ + for i in autoconf.info*; do \ + $(INSTALL_DATA) $$i $(infodir)/$$i; \ + done + -test -f standards.info || cd $(srcdir); \ + for i in standards.info*; do \ + $(INSTALL_DATA) $$i $(infodir)/$$i; \ + done + +uninstall: + for p in $(SCRIPTS); do \ + rm -f $(bindir)/`echo $$p|sed '$(transform)'`; \ + done + rm -fr $(acdatadir) + cd $(infodir); rm -f autoconf.info* + if test -f standards.info || test -f $(srcdir)/standards.info; \ + then cd $(infodir); rm -f standards.info*; fi + +${srcdir}/configure: configure.in $(M4FILES) + cd $(srcdir); \ + rm -f $@ $@.tmp; \ + $(M4) autoconf.m4 configure.in > $@.tmp && \ + chmod +x $@.tmp && mv $@.tmp $@ +Makefile: Makefile.in config.status + ./config.status +config.status: configure + ./config.status --recheck + +clean mostlyclean distclean realclean:: + for dir in $(SUBDIRS); do \ + echo making $@ in $$dir ; \ + (cd $$dir; $(MAKE) $@) ; \ + done + +clean mostlyclean distclean realclean:: + rm -f $(SCRIPTS) *.tmp + rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log + rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs + rm -f *.ev *.evs *.ov *.ovs *.cv *.cvs *.ma *.mas + +distclean realclean:: + rm -f Makefile config.status config.cache config.log + +realclean:: + rm -f TAGS *.info* INSTALL + +TAGS: + etags ${srcdir}/*.m4 ${srcdir}/*.sh ${srcdir}/[a-z]*.in ${srcdir}/*.texi + +# Don't depend on DISTFILES because there's no rule for "standards.info*". +dist: $(DISTDEP) + distname=`sed -e '/define(AC_ACVERSION,/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/autoconf-\1/' -e q acgeneral.m4`; \ + rm -fr $$distname; \ + mkdir $$distname $$distname/testsuite $$distname/testsuite/config \ + $$distname/testsuite/lib $$distname/testsuite/autoconf.g \ + $$distname/testsuite/autoconf.s; \ + for file in $(DISTFILES); do \ + ln $$file $$distname/$$file \ + || { echo copying $$file instead; cp -p $$file $$distname/$$file;}; \ + done; \ + chmod -R a+rX $$distname; \ + tar -chz -f $$distname.tar.gz $$distname; \ + rm -fr $$distname diff --git a/util/autoconf/README b/util/autoconf/README new file mode 100644 index 0000000..959b195 --- /dev/null +++ b/util/autoconf/README @@ -0,0 +1,38 @@ +Autoconf + +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. + +Producing configuration scripts using Autoconf requires GNU m4. You +must install GNU m4 (version 1.1 or later, preferably 1.3 or later +for better performance) before configuring Autoconf, so that +Autoconf's configure script can find it. The configuration scripts +produced by Autoconf are self-contained, so their users do not need to +have Autoconf (or GNU m4). + +Also, some optional utilities that come with Autoconf use Perl, TCL, +and the TCL packages Expect and DejaGNU. However, none of those +are required in order to use the main Autoconf program. If they are +not present, the affected Autoconf utilities will not be installed. + +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 create 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/util/autoconf/acconfig.h b/util/autoconf/acconfig.h new file mode 100644 index 0000000..801a8ac --- /dev/null +++ b/util/autoconf/acconfig.h @@ -0,0 +1,248 @@ +/* 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 if the closedir function returns void instead of int. */ +#undef CLOSEDIR_VOID + +/* 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 <sys/dg_sys_info.h>. */ +#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 <sys/types.h> doesn't define. */ +#undef gid_t + +/* Define if you have alloca, as a function or macro. */ +#undef HAVE_ALLOCA + +/* Define if you have <alloca.h> and it should be used (not on 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 you have the getmntent function. */ +#undef HAVE_GETMNTENT + +/* 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 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 the strftime function. */ +#undef HAVE_STRFTIME + +/* Define if you have <sys/wait.h> that is POSIX.1 compatible. */ +#undef HAVE_SYS_WAIT_H + +/* 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 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 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 <sys/types.h> 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 your C compiler doesn't accept -c and -o together. */ +#undef NO_MINUS_C_MINUS_O + +/* Define to `long' if <sys/types.h> doesn't define. */ +#undef off_t + +/* Define to `int' if <sys/types.h> 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 <sys/types.h> 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 <sys/stat.h> 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 <signal.h>. */ +#undef SYS_SIGLIST_DECLARED + +/* Define if you can safely include both <sys/time.h> and <time.h>. */ +#undef TIME_WITH_SYS_TIME + +/* Define if your <sys/time.h> declares struct tm. */ +#undef TM_IN_SYS_TIME + +/* Define to `int' if <sys/types.h> doesn't define. */ +#undef uid_t + +/* Define for Encore UMAX. */ +#undef UMAX + +/* Define for Encore UMAX 4.3 that has <inq_status/cpustats.h> + instead of <sys/cpustats.h>. */ +#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/util/autoconf/autoconf.sh b/util/autoconf/autoconf.sh new file mode 100755 index 0000000..5ae95c7 --- /dev/null +++ b/util/autoconf/autoconf.sh @@ -0,0 +1,152 @@ +#!/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] + [-l dir] [--localdir=dir] [--version] [template-file]" + +# NLS nuisances. +# Only set `LANG' and `LC_ALL' to "C" if already set. +# 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.$$ +localdir= +show_version=no + +while test $# -gt 0 ; do + case "${1}" in + -h | --help | --h* ) + echo "${usage}" 1>&2; exit 0 ;; + --localdir=* | --l*=* ) + localdir="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" + shift ;; + -l | --localdir | --l*) + shift + test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } + localdir="${1}" + shift ;; + --macrodir=* | --m*=* ) + AC_MACRODIR="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" + shift ;; + -m | --macrodir | --m* ) + shift + test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } + AC_MACRODIR="${1}" + shift ;; + --version | --v* ) + show_version=yes; shift ;; + -- ) # Stop option processing + shift; break ;; + - ) # Use stdin as input. + break ;; + -* ) + echo "${usage}" 1>&2; exit 1 ;; + * ) + break ;; + esac +done + +if test $show_version = yes; then + version=`sed -n 's/define.AC_ACVERSION.[ ]*\([0-9.]*\).*/\1/p' \ + $AC_MACRODIR/acgeneral.m4` + echo "Autoconf version $version" + exit 0 +fi + +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 + +tmpin=/tmp/acin.$$ # Always set this, to avoid bogus errors from some rm's. +if test z$infile = z-; then + infile=$tmpin + cat > $infile +elif test ! -r "$infile"; then + echo "autoconf: ${infile}: No such file or directory" >&2 + exit 1 +fi + +if test -n "$localdir"; then + use_localdir="-I$localdir -DAC_LOCALDIR=$localdir" +else + use_localdir= +fi + +# Use the frozen version of Autoconf if available. +r= f= +# Some non-GNU m4's don't reject the --help option, so give them /dev/null. +case `$M4 --help < /dev/null 2>&1` in +*reload-state*) test -r $AC_MACRODIR/autoconf.m4f && { r=--reload f=f; } ;; +*traditional*) ;; +*) echo Autoconf requires GNU m4 1.1 or later >&2; rm -f $tmpin; exit 1 ;; +esac + +$M4 -I$AC_MACRODIR $use_localdir $r autoconf.m4$f $infile > $tmpout || + { rm -f $tmpin $tmpout; exit 2; } + +# 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 + +if test $# -eq 0; then + exec 4> configure; chmod +x configure +else + exec 4>&1 +fi + +# Put the real line numbers into configure to make config.log more helpful. +awk ' +/__oline__/ { printf "%d:", NR + 1 } + { print } +' $tmpout | sed ' +/__oline__/s/^\([0-9][0-9]*\):\(.*\)__oline__\(.*\)$/\2\1\3/ +' >&4 + +rm -f $tmpout + +exit $status diff --git a/util/autoconf/autoheader.sh b/util/autoconf/autoheader.sh new file mode 100755 index 0000000..354d4d0 --- /dev/null +++ b/util/autoconf/autoheader.sh @@ -0,0 +1,250 @@ +#!/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] + [-l dir] [--localdir=dir] [--version] [template-file]" + +# NLS nuisances. +# Only set `LANG' and `LC_ALL' to "C" if already set. +# 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 + +localdir=. +show_version=no + +while test $# -gt 0 ; do + case "${1}" in + -h | --help | --h* ) + echo "${usage}"; exit 0 ;; + --localdir=* | --l*=* ) + localdir="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" + shift ;; + -l | --localdir | --l*) + shift + test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } + localdir="${1}" + shift ;; + --macrodir=* | --m*=* ) + AC_MACRODIR="`echo \"${1}\" | sed -e 's/^[^=]*=//'`" + shift ;; + -m | --macrodir | --m* ) + shift + test $# -eq 0 && { echo "${usage}" 1>&2; exit 1; } + AC_MACRODIR="${1}" + shift ;; + --version | --v* ) + show_version=yes; shift ;; + -- ) # Stop option processing + shift; break ;; + - ) # Use stdin as input. + break ;; + -* ) + echo "${usage}" 1>&2; exit 1 ;; + * ) + break ;; + esac +done + +if test $show_version = yes; then + version=`sed -n 's/define.AC_ACVERSION.[ ]*\([0-9.]*\).*/\1/p' \ + $AC_MACRODIR/acgeneral.m4` + echo "Autoconf version $version" + exit 0 +fi + +TEMPLATES="${AC_MACRODIR}/acconfig.h" +test -r $localdir/acconfig.h && TEMPLATES="${TEMPLATES} $localdir/acconfig.h" + +case $# in + 0) infile=configure.in ;; + 1) infile=$1 ;; + *) echo "$usage" >&2; exit 1 ;; +esac + +config_h=config.h +syms= +types= +funcs= +headers= +libs= + +if test "$localdir" != .; then + use_localdir="-I$localdir -DAC_LOCALDIR=$localdir" +else + use_localdir= +fi + +# Use the frozen version of Autoconf if available. +r= f= +# Some non-GNU m4's don't reject the --help option, so give them /dev/null. +case `$M4 --help < /dev/null 2>&1` in +*reload-state*) test -r $AC_MACRODIR/autoheader.m4f && { r=--reload f=f; } ;; +*traditional*) ;; +*) echo Autoconf requires GNU m4 1.1 or later >&2; exit 1 ;; +esac + +# 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 "`$M4 -I$AC_MACRODIR $use_localdir $r autoheader.m4$f $infile | + sed -n -e ' + : again + /^@@@.*@@@$/s/^@@@\(.*\)@@@$/\1/p + /^@@@/{ + s/^@@@//p + n + s/^/@@@/ + b again + }'`" + +# Make SYMS newline-separated rather than blank-separated, and remove dups. +# Start each symbol with a blank (to match the blank after "#undef") +# to reduce the possibility of mistakenly matching another symbol that +# is a substring of it. +syms="`for sym in $syms; do echo $sym; done | sort | uniq | sed 's@^@ @'`" + +if test $# -eq 0; then + tmpout=autoh$$ + trap "rm -f $tmpout; exit 1" 1 2 15 + exec > $tmpout +fi + +# Support "outfile[:infile]", defaulting infile="outfile.in". +case "$config_h" in +*:*) config_h_in=`echo "$config_h"|sed 's%.*:%%'` + config_h=`echo "$config_h"|sed 's%:.*%%'` ;; +*) config_h_in="${config_h}.in" ;; +esac + +# 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 -r ${config_h}.top && cat ${config_h}.top +test -r $localdir/acconfig.h && + grep @TOP@ $localdir/acconfig.h >/dev/null && + sed '/@TOP@/,$d' $localdir/acconfig.h + +# This puts each template 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 + +# /bin/sh on the Alpha gives `for' a random value if $funcs is empty. +if test -n "$funcs"; then + for func in `for x in $funcs; do echo $x; done | sort | uniq`; do + sym="`echo ${func} | sed 's/[^a-zA-Z0-9_]/_/g' | tr '[a-z]' '[A-Z]'`" + echo " +/* Define if you have the ${func} function. */ +#undef HAVE_${sym}" + done +fi + +if test -n "$headers"; then + for header in `for x in $headers; do echo $x; done | sort | uniq`; do + sym="`echo ${header} | sed 's/[^a-zA-Z0-9_]/_/g' | tr '[a-z]' '[A-Z]'`" + echo " +/* Define if you have the <${header}> header file. */ +#undef HAVE_${sym}" + done +fi + +if test -n "$libs"; then + for lib in `for x in $libs; do echo $x; done | sort | uniq`; do + sym="`echo ${lib} | sed 's/[^a-zA-Z0-9_]/_/g' | tr '[a-z]' '[A-Z]'`" + echo " +/* Define if you have the ${lib} library (-l${lib}). */ +#undef HAVE_LIB${sym}" + done +fi + +test -r $localdir/acconfig.h && + grep @BOTTOM@ $localdir/acconfig.h >/dev/null && + sed '1,/@BOTTOM@/d' $localdir/acconfig.h +test -f ${config_h}.bot && cat ${config_h}.bot + +status=0 + +if test -n "$syms"; then + 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 +fi + +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/util/autoconf/configure.in b/util/autoconf/configure.in new file mode 100644 index 0000000..7fd871e --- /dev/null +++ b/util/autoconf/configure.in @@ -0,0 +1,31 @@ +dnl Process this file with autoconf to produce a configure script. +AC_INIT(acgeneral.m4) + +AC_ARG_PROGRAM + +dnl We use a path for GNU m4 so even if users have another m4 first in +dnl their path, the installer can configure with a path that has GNU m4 +dnl first and get that path embedded in the installed autoconf and +dnl autoheader scripts. +AC_PATH_PROGS(M4, gm4 gnum4 m4, m4) + +dnl We use a path for perl so the #! line in autoscan will work. +AC_PATH_PROG(PERL, perl, no) +AC_SUBST(PERL)dnl +AC_SUBST(SCRIPTS)dnl +if test "$PERL" != no; then + SCRIPTS=autoscan +else + AC_MSG_WARN(autoscan will not be built since perl is not found) +fi + +AC_PROG_INSTALL + +# Work with the GNU or Cygnus source tree layout. +if test -f $srcdir/standards.texi; then + standards_info=standards.info standards_dvi=standards.dvi +fi +AC_SUBST(standards_info)dnl +AC_SUBST(standards_dvi)dnl + +AC_OUTPUT(Makefile testsuite/Makefile) diff --git a/util/autoconf/make-stds.texi b/util/autoconf/make-stds.texi new file mode 100644 index 0000000..95a42ec --- /dev/null +++ b/util/autoconf/make-stds.texi @@ -0,0 +1,625 @@ +@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}.) + +Different @code{make} programs have incompatible suffix lists and +implicit rules, and this sometimes creates confusion or misbehavior. So +it is a good idea to set the suffix list explicitly using only the +suffixes you need in the particular Makefile, like this: + +@example +.SUFFIXES: +.SUFFIXES: .c .o +@end example + +@noindent +The first line clears out the suffix list, the second introduces all +suffixes which may be subject to implicit rules in this Makefile. + +Don't assume that @file{.} is in the path for command execution. When +you need to run programs that are a part of your package during the +make, please make sure that it uses @file{./} if the program is built as +part of the make or @file{$(srcdir)/} if the file is an unchanging part +of the source code. Without one of these prefixes, the current search +path is used. + +The distinction between @file{./} 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) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@ +@end smallexample + +@noindent +in order to allow @samp{VPATH} to work correctly. When the target has +multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest +way to make the rule work well. For example, the target above for +@file{foo.1} is best written as: + +@smallexample +foo.1 : foo.man sedscript + sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ +@end smallexample + +@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 + +Use the following @code{make} variables: + +@example +$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX) +$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) +@end example + +When you use @code{ranlib}, you should make sure nothing bad happens if +the system does not have @code{ranlib}. Arrange to ignore an error +from that command, and print a message before the command to tell the +user that failure of the @code{ranlib} command does not mean a problem. + +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 as follows. + +These two variables set the root for the installation. All the other +installation directories should be subdirectories of one of these two, +and nothing should be directly installed into these two directories. + +@table @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. +@end table + +Executable programs are installed in one of the following directories. + +@table @samp +@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 sbindir +The directory for installing executable programs that can be run from +the shell, but are only generally useful to system administrators. This +should normally be @file{/usr/local/sbin}, but write it as +@file{$(exec_prefix)/sbin}. + +@item libexecdir +@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 +The directory for installing executable programs to be run by other +programs rather than by users. This directory should normally be +@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. +@end table + +Data files used by the program during its execution are divided into +categories in two ways. + +@itemize @bullet +@item +Some files are normally modified by programs; others are never normally +modified (though users may edit some of these). + +@item +Some files are architecture-independent and can be shared by all +machines at a site; some are architecture-dependent and can be shared +only by machines of the same kind and operating system; others may never +be shared between two machines. +@end itemize + +This makes for six different possibilities. However, we want to +discourage the use of architecture-dependent files, aside from of object +files and libraries. It is much cleaner to make other data files +architecture-independent, and it is generally not hard. + +Therefore, here are the variables makefiles should use to specify +directories: + +@table @samp +@item datadir +The directory for installing read-only architecture independent data +files. This should normally be @file{/usr/local/share}, but write it as +@file{$(prefix)/share}. As a special exception, see @file{$(infodir)} +and @file{$(includedir)} below. + +@item sysconfdir +The directory for installing read-only data files that pertain to a +single machine--that is to say, files for configuring a host. Mailer +and network configuration files, @file{/etc/passwd}, and so forth belong +here. All the files in this directory should be ordinary ASCII text +files. This directory should normally be @file{/usr/local/etc}, but +write it as @file{$(prefix)/etc}. + +@c rewritten to avoid overfull hbox --tower +Do not install executables +@c here +in this directory (they probably +belong in @file{$(libexecdir)} or @file{$(sbindir))}. Also do not +install files that are modified in the normal course of their use +(programs whose purpose is to change the configuration of the system +excluded). Those probably belong in @file{$(localstatedir)}. + +@item sharedstatedir +The directory for installing architecture-independent data files which +the programs modify while they run. This should normally be +@file{/usr/local/com}, but write it as @file{$(prefix)/com}. + +@item localstatedir +The directory for installing data files which the programs modify while +they run, and that pertain to one specific machine. Users should never +need to modify files in this directory to configure the package's +operation; put such configuration information in separate files that go +in @file{datadir} or @file{$(sysconfdir)}. @file{$(localstatedir)} +should normally be @file{/usr/local/var}, but write it as +@file{$(prefix)/var}. + +@item libdir +The directory for object files and libraries of object code. Do not +install executables here, they probably belong in @file{$(libexecdir)} +instead. The value of @code{libdir} should normally be +@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. + +@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 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. +@end table + +Unix-style man pages are installed in one of the following: + +@table @samp +@item mandir +The directory for installing the man pages (if any) for this package. +It should include the suffix for the proper section of the +manual---usually @samp{1} for a utility. It will normally be +@file{/usr/local/man/man1}, but you should write it as +@file{$(prefix)/man/man1}. + +@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. +@end table + +And finally, you should set the following variable: + +@table @samp +@item srcdir +The directory for the sources being compiled. The value of this +variable is normally inserted by the @code{configure} shell script. +@end table + +For example: + +@smallexample +@c I have changed some of the comments here slightly to fix an overfull +@c hbox, so the make manual can format correctly. --roland +# Common prefix for installation directories. +# NOTE: This directory must exist when you start the install. +prefix = /usr/local +exec_prefix = $(prefix) +# Where to put the executable for the command `gcc'. +bindir = $(exec_prefix)/bin +# Where to put the directories used by the compiler. +libexecdir = $(exec_prefix)/libexec +# Where to put the Info files. +infodir = $(prefix)/info +@end smallexample + +If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the @code{install} rule to create these subdirectories. + +Do not expect the user to include the subdirectory name in the value of +any of the variables listed above. The idea of having a uniform set of +variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. + diff --git a/util/autoconf/standards.info b/util/autoconf/standards.info new file mode 100644 index 0000000..7f3dda8 --- /dev/null +++ b/util/autoconf/standards.info @@ -0,0 +1,60 @@ +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, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + + +Indirect: +standards.info-1: 960 +standards.info-2: 49450 + +Tag Table: +(Indirect) +Node: Top960 +Node: Preface2096 +Node: Reading Non-Free Code3138 +Node: Contributions4868 +Node: Change Logs6466 +Node: Compatibility10182 +Node: Makefile Conventions11821 +Node: Makefile Basics12178 +Node: Utilities in Makefiles14522 +Node: Standard Targets16219 +Node: Command Variables23328 +Node: Directory Variables26158 +Node: Configuration35220 +Node: Source Language42244 +Node: Formatting43374 +Node: Comments46664 +Node: Syntactic Conventions49450 +Node: Names52342 +Node: Using Extensions53632 +Node: System Functions55373 +Node: Semantics60176 +Node: Errors63464 +Node: Libraries64667 +Node: Portability65891 +Node: User Interfaces69178 +Node: Documentation85106 +Node: Releases89040 + +End Tag Table diff --git a/util/autoconf/standards.texi b/util/autoconf/standards.texi new file mode 100644 index 0000000..e50b367 --- /dev/null +++ b/util/autoconf/standards.texi @@ -0,0 +1,2409 @@ +\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 21 September 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, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end ifinfo + +@titlepage +@title GNU Coding Standards +@author Richard Stallman +@author last updated @value{lastupdate} +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, Preface, (dir), (dir) +@top Version + +Last updated @value{lastupdate}. +@end ifinfo + +@menu +* Preface:: About the GNU Coding Standards +* 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 Preface +@chapter About the GNU Coding Standards + +The GNU Coding Standards were written by Richard Stallman and other GNU +Project volunteers. Their purpose is to make the GNU system clean, +consistent, and easy to install. This document can also be read as a +guide to write portable, robust and reliable programs. It focuses on +programs written in C, but many of the rules and principles are useful +even if you write in another programming language. The rules often +state reasons for writing in a certain way. + +Corrections or suggestions regarding this document should be sent to +@code{gnu@@prep.ai.mit.edu}. If you make a suggestion, please include a +suggested new wording for it; our time is limited. We prefer a context +diff to the @file{standards.texi} or @file{make-stds.texi} files, but if +you don't have those files, please mail your suggestion anyway. + +This release of the GNU Coding Standards was last updated +@value{lastupdate}. + +@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}. + +If @code{malloc} fails in a noninteractive program, make that a fatal +error. In an interactive program (one that reads commands from the +user), it is better to abort the command and return to the command +reader loop. This allows the user to kill other processes to free up +virtual memory, and then try the command again. + +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 archive-name +@samp{-n} in @code{shar}. + +@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 basename +@samp{-f} in @code{shar}. + +@item batch +Used in GDB. + +@item baud +Used in GDB. + +@item before +@samp{-b} in @code{tac}. + +@item binary +@samp{-b} in @code{cpio} and @code{diff}. + +@item bits-per-code +@samp{-b} in @code{shar}. + +@item block-size +Used in @code{cpio} and @code{tar}. + +@item blocks +@samp{-b} in @code{head} and @code{tail}. + +@item break-file +@samp{-b} in @code{ptx}. + +@item brief +Used in various programs to make output shorter. + +@item bytes +@samp{-c} in @code{head}, @code{split}, and @code{tail}. + +@item c@t{++} +@samp{-C} in @code{etags}. + +@item catenate +@samp{-A} in @code{tar}. + +@item cd +Used in various programs to specify the directory to use. + +@item changes +@samp{-c} in @code{chgrp} and @code{chown}. + +@item classify +@samp{-F} in @code{ls}. + +@item colons +@samp{-c} in @code{recode}. + +@item command +@samp{-c} in @code{su}; +@samp{-x} in GDB. + +@item compare +@samp{-d} in @code{tar}. + +@item compress +@samp{-Z} in @code{tar} and @code{shar}. + +@item concatenate +@samp{-A} in @code{tar}. + +@item confirmation +@samp{-w} in @code{tar}. + +@item context +Used in @code{diff}. + +@item 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 cut-mark +@samp{-c} in @code{shar}. + +@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 exit-0 +@samp{-e} in @code{unshar}. + +@item expand-tabs +@samp{-t} in @code{diff}. + +@item expression +@samp{-e} in @code{sed}. + +@item extern-only +@samp{-g} in @code{nm}. + +@item extract +@samp{-i} in @code{cpio}; +@samp{-x} in @code{tar}. + +@item faces +@samp{-f} in @code{finger}. + +@item fast +@samp{-f} in @code{su}. + +@item fatal-warnings +@samp{-E} in @code{m4}. + +@item file +@samp{-f} in @code{info}, 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 force-prefix +@samp{-F} in @code{shar}. + +@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} and @code{shar}. + +@item hashsize +@samp{-H} in @code{m4}. + +@item header +@samp{-h} in @code{objdump} and @code{recode} + +@item heading +@samp{-H} in @code{who}. + +@item help +Used to ask for brief usage information. + +@item here-delimiter +@samp{-d} in @code{shar}. + +@item hide-control-chars +@samp{-q} in @code{ls}. + +@item 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 intermix-type +@samp{-p} in @code{shar}. + +@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 level-for-gzip +@samp{-g} in @code{shar}. + +@item line-bytes +@samp{-C} in @code{split}. + +@item lines +Used in @code{split}, @code{head}, and @code{tail}. + +@item link +@samp{-l} in @code{cpio}. + +@item 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 mixed-uuencode +@samp{-M} in @code{shar}. + +@item mode +@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. + +@item modification-time +@samp{-m} in @code{tar}. + +@item multi-volume +@samp{-M} in @code{tar}. + +@item name-prefix +@samp{-a} in Bison. + +@item nesting-limit +@samp{-L} in @code{m4}. + +@item net-headers +@samp{-a} in @code{shar}. + +@item new-file +@samp{-W} in Make. + +@item no-builtin-rules +@samp{-r} in Make. + +@item no-character-count +@samp{-w} in @code{shar}. + +@item no-check-existing +@samp{-x} in @code{shar}. + +@item no-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-piping +@samp{-P} in @code{shar}. + +@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-timestamp +@samp{-m} in @code{shar}. + +@item no-validate +Used in Makeinfo. + +@item no-verbose +@samp{-v} in @code{shar}. + +@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 output-prefix +@samp{-o} in @code{shar}. + +@item override +@samp{-o} in @code{rm}. + +@item overwrite +@samp{-c} in @code{unshar}. + +@item owner +@samp{-o} in @code{install}. + +@item paginate +@samp{-l} in @code{diff}. + +@item paragraph-indent +Used in 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 query-user +@samp{-X} in @code{shar}. + +@item question +@samp{-q} in Make. + +@item quiet +Used in many programs to inhibit the usual output. @strong{Note:} every +program accepting @samp{--quiet} should accept @samp{--silent} as a +synonym. + +@item 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 split-at +@samp{-E} in @code{unshar}. + +@item split-size-limit +@samp{-L} in @code{shar}. + +@item squeeze-blank +@samp{-s} in @code{cat}. + +@item starting-file +Used in @code{tar} and @code{diff} to specify which file within +a directory to start processing with. + +@item stdin-file-list +@samp{-S} in @code{shar}. + +@item stop +@samp{-S} in Make. + +@item strict +@samp{-s} in @code{recode}. + +@item strip +@samp{-s} in @code{install}. + +@item strip-all +@samp{-s} in @code{strip}. + +@item strip-debug +@samp{-S} in @code{strip}. + +@item submitter +@samp{-s} in @code{shar}. + +@item suffix +@samp{-S} in @code{cp}, @code{ln}, @code{mv}. + +@item suffix-format +@samp{-b} in @code{csplit}. + +@item sum +@samp{-s} in @code{gprof}. + +@item summarize +@samp{-s} in @code{du}. + +@item symbolic +@samp{-s} in @code{ln}. + +@item symbols +Used in GDB and @code{objdump}. + +@item synclines +@samp{-s} in @code{m4}. + +@item sysname +@samp{-s} in @code{uname}. + +@item tabs +@samp{-t} in @code{expand} and @code{unexpand}. + +@item tabsize +@samp{-T} in @code{ls}. + +@item terminal +@samp{-T} in @code{tput} and @code{ul}. + +@item text +@samp{-a} in @code{diff}. + +@item text-files +@samp{-T} in @code{shar}. + +@item time +Used in @code{ls} and @code{touch}. + +@item 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 uuencode +@samp{-B} in @code{shar}. + +@item vanilla-operation +@samp{-V} in @code{shar}. + +@item verbose +Print more information about progress. Many programs support this. + +@item verify +@samp{-W} in @code{tar}. + +@item version +Print the version number. + +@item version-control +@samp{-V} in @code{cp}, @code{ln}, @code{mv}. + +@item vgrind +@samp{-v} in @code{etags}. + +@item volume +@samp{-V} in @code{tar}. + +@item what-if +@samp{-W} in Make. + +@item whole-size-limit +@samp{-l} in @code{shar}. + +@item width +@samp{-w} in @code{ls} and @code{ptx}. + +@item word-regexp +@samp{-W} in @code{ptx}. + +@item writable +@samp{-T} in @code{who}. + +@item zeros +@samp{-z} in @code{gprof}. + +@end table + +@node 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/util/et/Makefile.in b/util/et/Makefile.in new file mode 100644 index 0000000..0b37e72 --- /dev/null +++ b/util/et/Makefile.in @@ -0,0 +1,126 @@ +CFLAGS = $(CCOPTS) $(DEFS) $(LOCALINCLUDE) +LDFLAGS = -g +SED = sed + +INSTALLFILE = cp + +all:: + +LINTFLAGS=-uhvb +LINTFILES= error_message.c et_name.c init_et.c com_err.c +LIBOBJS= error_message.o et_name.o init_et.o com_err.o +# for et_lex.lex.c include in error_table.y +LOCALINCLUDE=-I. -I$(srcdir) + +FILES= Makefile et_name.c error_message.c compile_et.c \ + et_lex.lex.l error_table.y init_et.c \ + com_err.c com_err.h \ + error_table.h mit-sipb-copyright.h \ + test_et.c test1.et test2.et \ + compiler.h internal.h \ + com_err.texinfo texinfo.tex +CFILES= compile_et.c error_table.c error_message.c et_name.c \ + init_et.c com_err.c + +SRCS=$(CFILES) + +# +# what to build... +# + +# +# rules +# +error_table.o: et_lex.lex.c + +# +# real entries... +# + +all:: compile_et includes + +# The realm compile_et just isn't portable. (But then again, anything using +# lex and yacc isn't portable by definition. :-( ) +# +#compile_et: compile_et.o error_table.o +# $(CC) $(CFLAGS) -o $@ compile_et.o error_table.o $(LEXLIB) $(BSDLIB) +# +#install:: +# $(INSTALLPROG) compile_et ${DESTDIR}$(PROGDIR)/compile_et + +compile_et: $(srcdir)/compile_et.sh $(srcdir)/config_script + $(srcdir)/config_script $(srcdir)/compile_et.sh $(AWK) $(SED) > compile_et + chmod 755 compile_et + +et_c.awk: $(srcdir)/et_c.awk + $(CP) $(srcdir)/et_c.awk et_c.awk + +et_h.awk: $(srcdir)/et_h.awk + $(CP) $(srcdir)/et_h.awk et_h.awk + +clean:: + $(RM) compile_et compile_et.o error_table.o + +depend:: + +install:: com_err.h + $(INSTALLFILE) $(srcdir)/com_err.h $(DESTDIR)$(INCLDIR)/com_err.h + +install:: mit-sipb-copyright.h + $(INSTALLFILE) $(srcdir)/mit-sipb-copyright.h $(DESTDIR)$(INCLDIR)/mit-sipb-copyright.h + +install:: com_err.3 + $(INSTALLFILE) $(srcdir)/com_err.3 ${DESTDIR}${MANDIR}/man3/com_err.3 + +install:: compile_et.1 + $(INSTALLFILE) $(srcdir)/compile_et.1 ${DESTDIR}${MANDIR}/man1/compile_et.1 + + +## install_library_target(com_err,$(LIBOBJS),$(LINTFILES),) +all:: libcom_err.a + +libcom_err.a: $(LIBOBJS) + $(ARCHIVE) $@ $(LIBOBJS) + $(RANLIB) $@ + +clean:: + $(RM) libcom_err.a + $(RM) $(LIBOBJS) + +install:: + $(INSTALLLIB) libcom_err.a $(DESTDIR)$(LIBDIR)/libcom_err.a + $(CHMOD) 644 $(DESTDIR)$(LIBDIR)/libcom_err.a + $(RANLIB) $(DESTDIR)$(LIBDIR)/libcom_err.a + $(CHMOD) 444 $(DESTDIR)$(LIBDIR)/libcom_err.a +## + +clean:: + rm -f *~ \#* *.bak \ + *.otl *.aux *.toc *.PS *.dvi *.x9700 *.ps \ + *.cp *.fn *.ky *.log *.pg *.tp *.vr \ + *.o profiled/?*.o libcom_err.a libcom_err_p.a \ + com_err.o compile_et \ + et.ar TAGS y.tab.c lex.yy.c error_table.c \ + et_lex.lex.c \ + test1.h test1.c test2.h test2.c test_et \ + eddep makedep *.ln + + + +com_err.ps : com_err.dvi +com_err.dvi: com_err.texinfo + +libcom_err.o: $(LIBOBJS) + ld -r -s -o libcom_err.o $(LIBOBJS) + chmod -x libcom_err.o + + +archive: et.tar + +TAGS: et_name.c error_message.c compile_et.c error_table.c \ + lex.yy.c init_et.c + etags et_name.c error_message.c compile_et.c \ + error_table.c init_et.c + +depend:: et_lex.lex.c + diff --git a/util/ss/ChangeLog b/util/ss/ChangeLog new file mode 100644 index 0000000..a5ce5ab --- /dev/null +++ b/util/ss/ChangeLog @@ -0,0 +1,65 @@ +Sat Oct 22 09:54:50 1994 (tytso@rsx-11) + + * list_rqs.c (ss_list_requests): + * listen.c (ss_listen): + * configure.in: Add AC_RETSIGTYPE to get proper return type for + signal hanlders. + +Fri Oct 21 21:07:16 1994 (tytso@rsx-11) + + * Makefile.in (SED): Don't specify an explicit pathname for sed. + +Tue Oct 11 12:41:40 1994 Theodore Y. Ts'o (tytso@dcl) + + * Makefile.in: Don't rm the awk and sed scripts during a make clean! + +Fri Oct 7 15:37:19 1994 Theodore Y. Ts'o (tytso@dcl) + + * ct_c.sed: Add extra check to make sure blank lines get squeezed + out. Needed for AIX's sed, for some reason. + +Thu Oct 6 19:40:09 1994 Theodore Y. Ts'o (tytso@dcl) + + * mk_cmds.sh -- replace basename with sed -- more portable + +Mon Oct 3 17:26:27 1994 Theodore Y. Ts'o (tytso@dcl) + + * Makefile.in: + configure.in: Don't try to compile mk_cmds. Use awk/sed shell + script replacement instead. It's more apt to be + portable, since it doesn't use lex or yacc. :-( + +Tue Aug 30 21:30:18 1994 Theodore Y. Ts'o (tytso at tsx-11) + + * cmd_tbl.lex.l: Add declaration for strdup() if HAS_STRDUP is not + defined. + + * ct.y: Added #include of string.h; added declaration for + strdup() if HAS_STRDUP is not defined. + +Tue Jul 19 20:27:59 1994 Tom Yu (tlyu at dragons-lair) + + * Makefile.in: remove spurious includes rules + +Wed Jul 13 23:20:44 1994 Tom Yu (tlyu at dragons-lair) + + * Makefile.in: nuke libss.a.bak crud + +Sun Jul 3 07:48:43 1994 Tom Yu (tlyu at dragons-lair) + + * Makefile.in: changing things to now spew ignored errors. + +Wed Jun 22 18:51:50 1994 Mark Eichin (eichin@cygnus.com) + + * configure.in: ss_err.h is *not* a SrcHeader. Note that there is + duplication between the Copy*Header lines and the includes: rule + in the Makefile.in, which should later be fixed. + +Tue Jun 21 00:21:05 1994 Tom Yu (tlyu at dragons-lair) + + * configure.in: should be CopySrcHeader + +Mon Jun 20 21:58:40 1994 Tom Yu (tlyu at dragons-lair) + + * configure.in: install headers during build + diff --git a/util/ss/Makefile.in b/util/ss/Makefile.in new file mode 100644 index 0000000..dd1b12d --- /dev/null +++ b/util/ss/Makefile.in @@ -0,0 +1,159 @@ +CFLAGS = $(CCOPTS) $(DEFS) $(LOCALINCLUDE) +LDFLAGS = -g +SED = sed + +INSTALLLIB=cp +INSTALLFILE=cp + +all:: + +TOP=$(BUILDTOP) + +# hard coded srcdir/.. is so that ss/ss.h works + +# hard coded .. is so that ss/ss_err.h works +# hard coded ../et is so com_err.h works +# CFLAGS= -I${INCDIR} -I. -I.. -I../et -g +LOCALINCLUDE= -I. -I$(srcdir)/ -I$(srcdir)/.. -I$(srcdir)/../et -I.. + +# for the library + +LIB= libss.a + +# with ss_err.o first, ss_err.h should get rebuilt first too. should not +# be relying on this, though. +OBJS= ss_err.o \ + std_rqs.o \ + invocation.o help.o \ + execute_cmd.o listen.o parse.o error.o prompt.o \ + request_tbl.o list_rqs.o pager.o requests.o \ + data.o + +SRCS= invocation.c help.c \ + execute_cmd.c listen.c parse.c error.c prompt.c \ + request_tbl.c list_rqs.c pager.c requests.c \ + data.c \ + ss_err.h +# ss_err.h here, so that make depend catches it. + +std_rqs.o:: std_rqs.c ss_err.h + +CODE= $(SRCS) $(MKCMDSFILES) + +MKCMDSOBJS= mk_cmds.o utils.o options.o ct.tab.o cmd_tbl.lex.o + +MKCMDSFILES= mk_cmds.c utils.c options.c ct.y cmd_tbl.lex.l + +MKCMDSCSRCS= mk_cmds.c utils.c options.c ct.tab.c cmd_tbl.lex.c + + +HFILES= ss.h ss_internal.h copyright.h + +# for 'tags' and dependencies + +CFILES= $(SRCS) $(MKCMDSCSRCS) test_ss.c + +# for building archives + +FILES= $(SRCS) $(MKCMDSFILES) $(HFILES) \ + ss_err.et std_rqs.ct Makefile \ + test_ss.c ss mit-sipb-copyright.h copyright.h + +# +# stuff to build +# + +all:: mk_cmds libss.a includes # libss_p.a lint + +dist: archives + +install:: libss.a + $(INSTALLLIB) libss.a ${DESTDIR}$(LIBDIR)/libss.a + $(RANLIB) ${DESTDIR}$(LIBDIR)/libss.a + @rm -rf ${DESTDIR}$(INCLDIR)/ss + @mkdir ${DESTDIR}$(INCLDIR)/ss + + +includes:: mk_cmds ss_err.h + +install:: $(HFILES) copyright.h + for i in $(HFILES) copyright.h; do \ + $(INSTALLFILE) $(srcdir)/$$i ${DESTDIR}$(INCLDIR)/ss/$$i; \ + done + +install:: copyright.h + $(INSTALLFILE) $(srcdir)/copyright.h ${DESTDIR}$(INCLDIR)/ss/mit-sipb-copyright.h + +std_rqs.c: std_rqs.ct + +ss_err.h: ss_err.et + +ss_err.c: ss_err.et + +clean:: + $(RM) ss_err.o ss_err.c ss_err.h std_rqs.c + +depend:: ss_err.h + +ct.tab.c ct.tab.h: ct.y + $(RM) ct.tab.* y.* + $(YACC) -d $(srcdir)/ct.y + $(MV) y.tab.c ct.tab.c + $(MV) y.tab.h ct.tab.h + +# install_library_target(ss,$(OBJS),$(SRCS),) +all:: libss.a + +libss.a: $(OBJS) + $(ARCHIVE) $@ $(OBJS) + $(RANLIB) $@ + +clean:: + $(RM) libss.a + +install:: + $(INSTALLLIB) libss.a $(DESTDIR)$(LIBDIR)/libss.a + $(CHMOD) 644 $(DESTDIR)$(LIBDIR)/libss.a + $(RANLIB) $(DESTDIR)$(LIBDIR)/libss.a + $(CHMOD) 444 $(DESTDIR)$(LIBDIR)/libss.a +## + + +libss.o: $(OBJS) + $(LD) -r -s -o $@ $(OBJS) + $(CHMOD) -x $@ + +# program(mk_cmds,$(MKCMDSOBJS), , LEXLIB BSDLIB,$(PROGDIR)) +all:: mk_cmds + +#mk_cmds: $(MKCMDSOBJS) +# $(CC) $(CFLAGS) -o $@ $(MKCMDSOBJS) $(LEXLIB) $(BSDLIB) +# +#mk_cmds.o: ss_err.h +# +#install:: +# $(INSTALLPROG) mk_cmds ${DESTDIR}$(PROGDIR)/mk_cmds + +mk_cmds: $(srcdir)/mk_cmds.sh $(srcdir)/config_script + $(srcdir)/config_script $(srcdir)/mk_cmds.sh $(AWK) $(SED) > mk_cmds + chmod 755 mk_cmds + +ct_c.awk: $(srcdir)/ct_c.awk + $(CP) $(srcdir)/ct_c.awk ct_c.awk + +ct_c.sed: $(srcdir)/ct_c.sed + $(CP) $(srcdir)/ct_c.sed ct_c.sed + +clean:: + $(RM) mk_cmds $(MKCMDSOBJS) + +# + +clean:: + rm -f *.o *~ \#* *.bak core \ + ss_err.h ct.tab.c ct.tab.h cmd_tbl.lex.c \ + lex.yy.c y.tab.c \ + libss.a libss_p.a llib-lss.ln mk_cmds \ + ss.ar ss.tar \ + TAGS test_ss + diff --git a/util/ss/list_rqs.c b/util/ss/list_rqs.c new file mode 100644 index 0000000..c44ebed --- /dev/null +++ b/util/ss/list_rqs.c @@ -0,0 +1,88 @@ +/* + * Copyright 1987, 1988 by MIT Student Information Processing Board + * + * For copyright information, see copyright.h. + */ +#include "copyright.h" +#include "ss_internal.h" +#include <signal.h> +#include <setjmp.h> +#include <sys/wait.h> + +#ifdef lint /* "lint returns a value which is sometimes ignored" */ +#define DONT_USE(x) x=x; +#else /* !lint */ +#define DONT_USE(x) ; +#endif /* lint */ + +static char const twentyfive_spaces[26] = + " "; +static char const NL[2] = "\n"; + +ss_list_requests(argc, argv, sci_idx, info_ptr) + int argc; + char **argv; + int sci_idx; + pointer info_ptr; +{ + register ss_request_entry *entry; + register char const * const *name; + register int spacing; + register ss_request_table **table; + + char buffer[BUFSIZ]; + FILE *output; + int fd; + int mask; + RETSIGTYPE (*func)(); +#ifndef WAIT_USES_INT + union wait waitb; +#else + int waitb; +#endif + + DONT_USE(argc); + DONT_USE(argv); + + mask = sigblock(sigmask(SIGINT)); + func = signal(SIGINT, SIG_IGN); + fd = ss_pager_create(); + output = fdopen(fd, "w"); + sigsetmask(mask); + + fprintf (output, "Available %s requests:\n\n", + ss_info (sci_idx) -> subsystem_name); + + for (table = ss_info(sci_idx)->rqt_tables; *table; table++) { + entry = (*table)->requests; + for (; entry->command_names; entry++) { + spacing = -2; + buffer[0] = '\0'; + if (entry->flags & SS_OPT_DONT_LIST) + continue; + for (name = entry->command_names; *name; name++) { + register int len = strlen(*name); + strncat(buffer, *name, len); + spacing += len + 2; + if (name[1]) { + strcat(buffer, ", "); + } + } + if (spacing > 23) { + strcat(buffer, NL); + fputs(buffer, output); + spacing = 0; + buffer[0] = '\0'; + } + strncat(buffer, twentyfive_spaces, 25-spacing); + strcat(buffer, entry->info_string); + strcat(buffer, NL); + fputs(buffer, output); + } + } + fclose(output); +#ifndef NO_FORK + wait(&waitb); +#endif + (void) signal(SIGINT, func); +} diff --git a/util/ss/listen.c b/util/ss/listen.c new file mode 100644 index 0000000..dd47601 --- /dev/null +++ b/util/ss/listen.c @@ -0,0 +1,130 @@ +/* + * Listener loop for subsystem library libss.a. + * + * util/ss/listen.c + * + * Copyright 1987, 1988 by MIT Student Information Processing Board + * + * For copyright information, see copyright.h. + */ + +#include "copyright.h" +#include "ss_internal.h" +#include <stdio.h> +#include <setjmp.h> +#include <signal.h> +#include <sys/param.h> +#ifdef BSD +#include <sgtty.h> +#endif + +static ss_data *current_info; +static jmp_buf listen_jmpb; + +static RETSIGTYPE print_prompt() +{ +#ifdef BSD + /* put input into a reasonable mode */ + struct sgttyb ttyb; + if (ioctl(fileno(stdin), TIOCGETP, &ttyb) != -1) { + if (ttyb.sg_flags & (CBREAK|RAW)) { + ttyb.sg_flags &= ~(CBREAK|RAW); + (void) ioctl(0, TIOCSETP, &ttyb); + } + } +#endif + (void) fputs(current_info->prompt, stdout); + (void) fflush(stdout); +} + +static RETSIGTYPE listen_int_handler() +{ + putc('\n', stdout); + longjmp(listen_jmpb, 1); +} + +int ss_listen (sci_idx) + int sci_idx; +{ + register char *cp; + register RETSIGTYPE (*sig_cont)(); + register ss_data *info; + RETSIGTYPE (*sig_int)(), (*old_sig_cont)(); + char input[BUFSIZ]; + char buffer[BUFSIZ]; + char *end = buffer; + int mask; + int code; + jmp_buf old_jmpb; + ss_data *old_info = current_info; + + current_info = info = ss_info(sci_idx); + sig_cont = (RETSIGTYPE (*)())0; + info->abort = 0; + mask = sigblock(sigmask(SIGINT)); + memcpy(old_jmpb, listen_jmpb, sizeof(jmp_buf)); + sig_int = signal(SIGINT, listen_int_handler); + setjmp(listen_jmpb); + (void) sigsetmask(mask); + while(!info->abort) { + print_prompt(); + *end = '\0'; + old_sig_cont = sig_cont; + sig_cont = signal(SIGCONT, print_prompt); + if (sig_cont == print_prompt) + sig_cont = old_sig_cont; + if (fgets(input, BUFSIZ, stdin) != input) { + code = SS_ET_EOF; + goto egress; + } + cp = strchr(input, '\n'); + if (cp) { + *cp = '\0'; + if (cp == input) + continue; + } + (void) signal(SIGCONT, sig_cont); + for (end = input; *end; end++) + ; + + code = ss_execute_line (sci_idx, input); + if (code == SS_ET_COMMAND_NOT_FOUND) { + register char *c = input; + while (*c == ' ' || *c == '\t') + c++; + cp = strchr (c, ' '); + if (cp) + *cp = '\0'; + cp = strchr (c, '\t'); + if (cp) + *cp = '\0'; + ss_error (sci_idx, 0, + "Unknown request \"%s\". Type \"?\" for a request list.", + c); + } + } + code = 0; +egress: + (void) signal(SIGINT, sig_int); + memcpy(listen_jmpb, old_jmpb, sizeof(jmp_buf)); + current_info = old_info; + return code; +} + +void ss_abort_subsystem(sci_idx, code) + int sci_idx; + int code; +{ + ss_info(sci_idx)->abort = 1; + ss_info(sci_idx)->exit_status = code; + +} + +int ss_quit(argc, argv, sci_idx, infop) + int argc; + char **argv; + int sci_idx; + pointer infop; +{ + ss_abort_subsystem(sci_idx, 0); +} |