diff options
Diffstat (limited to 'etc')
| -rw-r--r-- | etc/ChangeLog | 552 | ||||
| -rw-r--r-- | etc/Makefile.in | 157 | ||||
| -rw-r--r-- | etc/add-log.el | 573 | ||||
| -rw-r--r-- | etc/add-log.vi | 11 | ||||
| -rw-r--r-- | etc/configbuild.ein | 149 | ||||
| -rw-r--r-- | etc/configbuild.fig | 50 | ||||
| -rw-r--r-- | etc/configbuild.jin | bin | 11123 -> 0 bytes | |||
| -rw-r--r-- | etc/configbuild.tin | 9 | ||||
| -rw-r--r-- | etc/configdev.ein | 185 | ||||
| -rw-r--r-- | etc/configdev.fig | 80 | ||||
| -rw-r--r-- | etc/configdev.jin | bin | 17967 -> 0 bytes | |||
| -rw-r--r-- | etc/configdev.tin | 17 | ||||
| -rwxr-xr-x | etc/configure | 862 | ||||
| -rw-r--r-- | etc/configure.in | 7 | ||||
| -rw-r--r-- | etc/configure.texi | 2644 | ||||
| -rw-r--r-- | etc/fdl.texi | 368 | ||||
| -rw-r--r-- | etc/make-stds.texi | 955 | ||||
| -rw-r--r-- | etc/standards.texi | 3742 | ||||
| -rw-r--r-- | etc/texi2pod.pl | 427 |
19 files changed, 0 insertions, 10788 deletions
diff --git a/etc/ChangeLog b/etc/ChangeLog deleted file mode 100644 index debe735ca..000000000 --- a/etc/ChangeLog +++ /dev/null @@ -1,552 +0,0 @@ -2002-06-11 Nick Clifton <nickc@cambridge.redhat.com> - - Import the following patches from the FSF GCC sources: - 2002-03-25 Zack Weinberg <zack@codesourcery.com> - - * texi2pod.pl: Handle @end ftable and @end vtable. - - 2001-12-12 Matthias Klose <doko@debian.org> - - * texi2pod.pl: Merge changes from binutils' texi2pod.pl. Allows - generation of more than one man page from one source. - Add '-' to set of valid chars for an identifier. - Let -D option accept flags of the form <flag>=<value>. - Use \s+ for whitespace detection in '@c man' lines. - Handle @set and @clear independent of $output. - Substitute all @value{}'s in a line. - - 2001-11-14 Joseph S. Myers <jsm28@cam.ac.uk> - - * texi2pod.pl: Handle @ifnottex, @iftex and @display. Handle @var - in verbatim blocks specially. Handle @unnumbered, @unnumberedsec - and @center. Allow [a-z] after @enumerate. Handle 0 and numbers - greater than 9 in enumerations. - - 2001-07-03 Joseph S. Myers <jsm28@cam.ac.uk> - - * texi2pod.pl: Handle @r inside @item. - -2002-02-27 Andrew Cagney <ac131313@redhat.com> - - * fdl.texi: New file. - -2002-02-24 Andrew Cagney <ac131313@redhat.com> - - * standards.texi: Import February 14, 2002 version. - * make-stds.texi: Import 2001 version. - -2002-01-26 Hans-Peter Nilsson <hp@bitrange.com> - - * Makefile.in (install): Depend on install-info. - -2001-03-25 Stephane Carrez <Stephane.Carrez@worldnet.fr> - - * texi2pod.pl: New file (from gcc/contrib). - -1999-04-01 Jim Blandy <jimb@zwingli.cygnus.com> - - * add-log.el, add-log.vi: New files. - -1999-01-20 Angela Marie Thomas (angela@cygnus.com) - - * comp-tools-verify: Remove some checks that are no longer valid. - -1998-12-03 Nick Clifton <nickc@cygnus.com> - - * targetdoc/fr30.texi: New document. - -1998-10-01 Angela Marie Thomas (angela@cygnus.com) - - * comp-tools-fix, cross-tools-fix: Replace /usr/include - with ${FIXINCDIR}. - -1998-08-11 Doug Evans <devans@canuck.cygnus.com> - - * make-rel-sym-tree (version): Update calculation. - -1998-06-12 Ian Lance Taylor <ian@cygnus.com> - - * configure.texi: Various additions. - * Makefile.in (TEXI2HTML, DVIPS): New variables. - (standards.ps): New target. - (configure.dvi): Copy .tin files in as well. - (configure.ps, configure.html): New targets. - (clean): Remove configdev.jpg and configbuild.jpg. - * configdev.fig: New file. - * configdev.ein: New file (EPS version of configdev.fig). - * configdev.jin: New file (JPEG version of configdev.fig). - * configbuild.fig: New file. - * configbuild.ein: New file (EPS version of configbuild.fig). - * configbuild.jin: New file (JPEG version of configbuild.fig). - -1998-06-10 Ian Lance Taylor <ian@cygnus.com> - - * configure.texi: New file. - * configdev.tin: New file. - * configbuild.tin: New file. - * Makefile.in (MAKEINFO): Use makeinfo from texinfo directory if - it exists. - (TEXI2DVI): Likewise for texi2dvi. - (INFOFILES): Add configure.info. - (DVIFILES): Add configure.dvi. - (info): Only build info files if the source files exist. - (install-info): Only install info files if they exist. - (dvi): Only build DVI files if the sources files exist. - (configure.info): New target. - (configure.dvi): New target. - (clean): Remove configdev and configbuild derived files. - - Remove obsolete documentation. - * intro.texi: Remove. - * install.texi: Remove. - * config-names.texi: Remove. - * screen1.eps: Remove. - * screen1.obj: Remove. - * screen2.eps: Remove. - * screen2.obj: Remove. - * Makefile.in: Remove references to the above. - -Thu May 21 14:34:51 1998 Nick Clifton <nickc@cygnus.com> - - * targetdoc/arm-interwork.texi: Add note about ignoring linker - warning message when using --support-old-code. - -Mon May 18 14:27:37 1998 Angela Marie Thomas (angela@cygnus.com) - - * Install.in, comp-tools-fix, comp-tools-verify, cross-tools-fix: - Use $GCCvn rather than substitute everywhere. - -Thu May 14 14:43:10 1998 Nick Clifton <nickc@cygnus.com> - - * targetdoc/arm-interwork.texi: Document dlltool support of - interworking. - -Thu May 7 16:49:38 1998 Jason Molenda (crash@bugshack.cygnus.com) - - * Install.in: Remove references to TCL_LIBRARY, TK_LIBRARY, - and GDBTK_FILENAME. - -Wed Apr 1 17:11:44 1998 Nick Clifton <nickc@cygnus.com> - - * targetdoc/arm-interwork.texi: Document ARM/thumb interworking. - -Tue Mar 31 15:28:20 1998 Ian Lance Taylor <ian@cygnus.com> - - * standards.texi, make-stds.texi: Update to current FSF versions. - * Makefile.in (standards.info): Depend upon make-std.texi. - -Tue Mar 24 16:13:26 1998 Stu Grossman <grossman@bhuna.cygnus.co.uk> - - * configure: Regenerate with autoconf 2.12.1 to fix shell issues - for NT native builds. - -Mon Mar 9 16:41:04 1998 Doug Evans <devans@canuck.cygnus.com> - - * make-rel-sym-tree (binprogs): Add objcopy. - -Tue Feb 24 18:11:58 1998 Doug Evans <devans@canuck.cygnus.com> - - * make-rel-sym-tree: as.new -> as-new, ld.new -> ld-new - nm.new -> nm-new. Make symlinks to crt*.o. - -Fri Nov 21 12:54:58 1997 Manfred Hollstein <manfred@s-direktnet.de> - - * Makefile.in: Add --no-split argument to avoid creating files - with names longer than 14 characters. - -Thu Sep 25 13:13:11 1997 Jason Molenda (crash@pern.cygnus.com) - - * intro.texi: Add closing ifset. - -Mon Sep 1 10:31:32 1997 Angela Marie Thomas (angela@cygnus.com) - - * Install.in: Move setting HOST and TARGET to the beginning - of the file for editing convenience. - -Mon Sep 1 10:28:37 1997 Angela Marie Thomas (angela@cygnus.com) - - * Install.in.: More friendly options/messages when extracting - from a file instead of a tape device. - -Tue Jun 17 15:50:23 1997 Angela Marie Thomas (angela@cygnus.com) - - * Install.in: Add /usr/bsd to PATH for Irix (home of compress) - -Thu Jun 12 13:47:00 1997 Angela Marie Thomas (angela@cygnus.com) - - * Install.in (show_exec_prefix_msg): fix quoting - -Wed Jun 4 15:31:43 1997 Jason Molenda (crash@godzilla.cygnus.co.jp) - - * rebuilding.texi: Removed. - -Sat May 24 18:02:20 1997 Angela Marie Thomas (angela@cygnus.com) - - * cross-tools-fix: Remove host check since it doesn't matter - for this case. - * Install.in (guess_system): clean up more unused hosts. - * Install.in, cross-tools-fix, comp-tools-fix, comp-tools-verify: - Hack for host check to not warn the user for certain cases. - -Fri May 23 23:46:10 1997 Angela Marie Thomas (angela@cygnus.com) - - * subst-strings: Remove a lot of unused code - * Install.in: Remove reference to TAPEdflt, use variables instead of - string substitution when able. - -Fri Apr 11 17:25:52 1997 Ian Lance Taylor <ian@cygnus.com> - - * configure.in: Change file named in AC_INIT to Makefile.in. - * configure: Rebuild. - -Fri Apr 11 18:12:42 1997 Jason Molenda (crash@godzilla.cygnus.co.jp) - - * Install.in (guess_system): Back out change to INSTALLHOST to - call all IRIX systems "mips-sgi-irix4" - - * Makefile.in: Remove references to configure.texi and cfg-paper.texi. - -Thu Apr 10 23:26:45 1997 Jason Molenda (crash@godzilla.cygnus.co.jp) - - * srctree.texi, emacs-relnotes.texi, cfg-paper.texi: Remove. - * Install.in: Remove Ultrix-specific hacks. - Update Cygnus phone numbers. - (guess_system): Remove some old systems (Ultrix, OSF1 v1 & 2, - m68k-HPUX, m68k SunOS, etc.) - (show_gnu_root_msg): Remove. - Removed all the remove option code. - -Thu Apr 10 23:23:33 1997 Jason Molenda (crash@godzilla.cygnus.co.jp) - - * configure.man, configure.texi: Remote. - -Mon Apr 7 18:15:00 1997 Brendan Kehoe <brendan@cygnus.com> - - * Fix the version string for OSF1 4.0 to recognize either - V4.* or X4.* - -Mon Apr 7 15:34:47 1997 Ian Lance Taylor <ian@cygnus.com> - - * standards.texi, make-stds.texi: Update to current FSF versions. - -Tue Nov 19 15:36:14 1996 Doug Evans <dje@canuck.cygnus.com> - - * make-rel-sym-tree: New file. - -Wed Oct 23 00:34:07 1996 Angela Marie Thomas (angela@cygnus.com) - - * Lots of patches from progressive... - * Install.in: restore DDOPTS for AIX 4.x - * Install.in, subst-strings: add case for DG Aviion - * subst-strings: fix typo in INSTALLdir var setting - * comp-tools-verify: set SHLIB_PATH for shared libs - * Install.in, subst-strings: add case for solaris2.5 - * Install.in: fix regression for hppa1.1 check - * comp-tools-fix: set LD_LIBRARY_PATH - * comp-tools-fix: If fixincludes fixes /usr/include/limits.h, - install it as syslimits.h. - -Wed Oct 16 19:20:42 1996 Michael Meissner <meissner@tiktok.cygnus.com> - - * Install.in (guess_system): Treat powerpc-ibm-aix4.1 the same as - rs6000-ibm-aix4.1, since the compiler now uses common mode by - default. - -Wed Oct 2 15:39:07 1996 Jason Molenda (crash@godzilla.cygnus.co.jp) - - * configure.in (AC_PROG_INSTALL): Added. - * Makefile.in (distclean): Remove config.cache. - -Wed Oct 2 14:33:58 1996 Jason Molenda (crash@godzilla.cygnus.co.jp) - - * configure.in: Switch to autoconf configure.in. - * configure: New. - * Makefile.in: Use autoconf-substituted values. - -Tue Jun 25 18:56:08 1996 Jason Molenda (crash@godzilla.cygnus.co.jp) - - * Makefile.in (datadir): Changed to $(prefix)/share. - -Fri Mar 29 11:38:01 1996 J.T. Conklin (jtc@lisa.cygnus.com) - - * configure.man: Changed to be recognized by catman -w on Solaris. - -Wed Dec 6 15:40:28 1995 Doug Evans <dje@canuck.cygnus.com> - - * comp-tools-fix (fixincludes): Define FIXPROTO_DEFINES from - .../install-tools/fixproto-defines. - -Sun Nov 12 19:31:27 1995 Jason Molenda (crash@phydeaux.cygnus.com) - - * comp-tools-verify (verify_cxx_initializers): delete argv, - argc declarations, add -static to compile line. - (verify_cxx_hello_world): delete argv, argc declarations, add - -static to compile line. - -Wed Sep 20 13:21:52 1995 Ian Lance Taylor <ian@cygnus.com> - - * Makefile.in (maintainer-clean): New target, synonym for - realclean. - -Mon Aug 28 17:25:49 1995 Jason Molenda (crash@phydeaux.cygnus.com) - - * Install.in (PATH): add /usr/ucb to $PATH (for SunOS 4.1.x). - -Tue Aug 15 21:51:58 1995 Jason Molenda (crash@phydeaux.cygnus.com) - - * Install.in (guess_system): Match OSF/1 v3.x as the same as - v2.x--v2.x binaries are upward compatible. - -Tue Aug 15 21:46:54 1995 Jason Molenda (crash@phydeaux.cygnus.com) - - * Install.in (guess_system): recognize HP 9000/800 systems as the - same as HP 9000/700 systems. - -Tue Aug 8 13:11:56 1995 Brendan Kehoe <brendan@lisa.cygnus.com> - - * Install.in: For emacs, run show_emacs_alternate_msg and exit. - (show_emacs_alternate_msg): New message saying how emacs can't be - installed in an alternate prefix. - -Thu Jun 8 00:42:56 1995 Angela Marie Thomas <angela@cirdan.cygnus.com> - - * subst-strings: change du commands to $BINDIR/. & $SRCDIR/. just - in case they are symlinks. - -Tue Apr 18 14:23:10 1995 J.T. Conklin <jtc@rtl.cygnus.com> - - * cdk-fix: Extracted table of targets that don't need their - headers fixed from gcc's configure script. - - * cdk-fix, cdk-verify: Use ${HOST} instead of ||HOSTstr|| - - * cdk-fix, cdk-verify: New files, install script fragments used - for Cygnus Developer's Kit. - - * Install.in (do_mkdir): New function. - - * Install.in: Added support for --with and --without options. - Changed so that tape commands are not run when extracting - from a file. - (do_mt): Changed to take only one argument. - -Wed Mar 29 11:16:38 1995 Jason Molenda (crash@phydeaux.cygnus.com) - - * Install.in: catch UNAME==alpha-dec-osf2.x and correct entry for - alpha-dec-osf1.x - -Fri Jan 27 12:04:29 1995 J.T. Conklin <jtc@rtl.cygnus.com> - - * subst-strings (mips-sgi-irix5): New entry in table. - -Thu Jan 19 12:15:44 1995 J.T. Conklin <jtc@rtl.cygnus.com> - - * Install.in: Major rewrite, bundle dependent code (for example, - fixincludes for comp-tools) will be inserted into the Install - script when it is generated. - -Tue Jan 17 16:51:32 1995 Ian Lance Taylor <ian@sanguine.cygnus.com> - - * Makefile.in (Makefile): Rebuild using $(SHELL). - -Thu Nov 3 19:30:33 1994 Ken Raeburn <raeburn@cujo.cygnus.com> - - * Makefile.in (install-info): Depend on info. - -Fri Aug 19 16:16:38 1994 Jason Molenda (crash@phydeaux.cygnus.com) - - * Install.in: set $FIX_HEADER so fixproto can find fix-header. - -Fri May 6 16:18:58 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Makefile.in (install-info): add a semicolon in the if statement. - -Fri Apr 29 16:56:07 1994 David J. Mackenzie (djm@rtl.cygnus.com) - - * cfg-paper.texi: Update some outdated information. - - * Makefile.in (install-info): Pass file, not directory, as last - arg to INSTALL_DATA. - (uninstall): New target. - -Thu Apr 28 14:42:22 1994 David J. Mackenzie (djm@rtl.cygnus.com) - - * configure.texi: Comment out @smallbook. - - * Makefile.in: Define TEXI2DVI and TEXIDIR, and use the latter. - Remove info files in realclean, not clean, per coding standards. - Remove TeX output in clean. - -Tue Apr 26 17:18:03 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in: fixincludes output is actually put in fixincludes.log, - but echo'ed messages claim it is fixinc.log. This is the same - messages as I logged in March 4 1994, but for some reason we found - the change hadn't been done. I'll have to dig through the logs - and find out what I really did do that day. :) - -Mon Apr 25 20:28:19 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in: use eval to call do_mt() for Ultrix brokenness. - -Mon Apr 25 20:00:00 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in(do_mt): exit with error status 1 if # of parameters - != 3. - -Mon Apr 25 19:42:36 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in: lose TAPE_FORWARD and TAPE_REWIND, add do_mt() - to do all tape movement operations. Currently untested. Addresses - PR # 4886 from bull. - - * Install.in: add 1994 to the copyright thing. - -Fri Apr 22 19:05:13 1994 David J. Mackenzie (djm@rtl.cygnus.com) - - * standards.texi: Update from FSF. - -Fri Apr 22 15:46:10 1994 Jason Molenda (crash@cygnus.com) - - * Install.in: Add $DDOPTS, has ``bs=124b'' for all systems except - AIX (some versions of AIX don't understand bs=124b. Silly OS). - -Mon Apr 4 22:55:05 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in: null out $TOOLS before adding stuff to it - non-destructively. - -Wed Mar 30 21:45:35 1994 David J. Mackenzie (djm@rtl.cygnus.com) - - * standards.texi: Fix typo. - - * configure.texi, configure.man: Document --disable-. - -Mon Mar 28 13:22:15 1994 David J. Mackenzie (djm@rtl.cygnus.com) - - * standards.texi: Update from FSF. - -Sat Mar 26 09:21:44 1994 David J. Mackenzie (djm@rtl.cygnus.com) - - * standards.texi, make-stds.texi: Update from FSF. - -Fri Mar 25 22:59:45 1994 David J. Mackenzie (djm@rtl.cygnus.com) - - * configure.texi, configure.man: Document --enable-* options. - -Wed Mar 23 23:38:24 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in: set CPP to be gcc -E for fixincludes. - -Wed Mar 23 13:42:48 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in: set PATH to $PATH:/bin:/usr/bin so we can pick - up native tools even if the user doesn't have them in his - path. - - * Install.in: ``hppa-1.1-hp-hpux'' -> ``hppa1.1-hp-hpux''. - -Tue Mar 15 22:09:20 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in: TAPE_REWIND and TAPE_FORWARD variables for Unixunaware, - added switch statement to detect if system is Unixunaware. - -Fri Mar 4 12:10:30 1994 Jason Molenda (crash@sendai.cygnus.com) - - * Install.in: fixincludes output is actually put in fixincludes.log, - but echo'ed messages claim it is fixinc.log. - -Wed Nov 3 02:58:02 1993 Jeffrey Osier (jeffrey@thepub.cygnus.com) - - * subst-strings: output TEXBUNDLE for more install notes matching - * install-texi.in: PRMS info now exists - -Tue Oct 26 16:57:12 1993 K. Richard Pixley (rich@sendai.cygnus.com) - - * subst-strings: match solaris*. Also, add default case to catch - and error out for unrecognized systems. - -Thu Aug 19 18:21:31 1993 david d `zoo' zuhn (zoo@rtl.cygnus.com) - - * Install.in: handle the new fixproto work - -Mon Jul 19 12:05:41 1993 david d `zoo' zuhn (zoo@cirdan.cygnus.com) - - * Install.in: remove "MT=tctl" for AIX (not needed, and barely - worked anyway) - -Mon Jun 14 19:09:22 1993 Jeffrey Osier (jeffrey@cygnus.com) - - * subst-strings: changed HOST to recognize Solaris for install notes - -Thu Jun 10 16:01:25 1993 Jeffrey Osier (jeffrey@cygnus.com) - - * dos-inst.texi: new file. - -Wed Jun 9 19:23:59 1993 Jeffrey Osier (jeffrey@rtl.cygnus.com) - - * install-texi.in: added conditionals (nearly complete) - cleaned up - added support for other releases (not done) - -Wed Jun 9 15:53:58 1993 Jim Kingdon (kingdon@cygnus.com) - - * Makefile.in (install-info): Use INSTALL_DATA. - ({dist,real}clean): Also delete Makefile and config.status. - -Fri Jun 4 17:09:56 1993 Jeffrey Osier (jeffrey@cygnus.com) - - * subst-strings: added data for OS_STRING - - * subst-strings: added support for OS_STRING - -Thu Jun 3 00:37:01 1993 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * Install.in: pull COPYING and COPYING.LIB off of the tape - -Tue Jun 1 16:52:08 1993 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * subst-strings: replace RELEASE_DIR too - -Mon Mar 22 23:55:27 1993 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * Makefile.in: add installcheck target - -Wed Mar 17 02:21:15 1993 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * Install.in: fix 'source only' extraction bug where it looked for - the src dir under H-<host>/src instead of src; also remove stray - reference to EMACSHIBIN - -Mon Mar 15 01:25:45 1993 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * make-stds.texi: added 'installcheck' to the standard targets - -Tue Mar 9 19:48:28 1993 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * standards.texi: added INFO-DIR-ENTRY, updated version from the FSF - -Tue Feb 9 12:40:23 1993 Ian Lance Taylor (ian@cygnus.com) - - * Makefile.in (standards.info): Added -I$(srcdir) to find - make-stds.texi. - -Mon Feb 1 16:32:56 1993 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * standards.texi: updated to latest FSF version, which includes: - - * make-stds.texi: new file - -Mon Nov 30 01:31:40 1992 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * install-texi.in, relnotes.texi, intro.texi: changed Cygnus phone - numbers from the old Palo Alto ones to the new Mtn. View numbers - -Mon Nov 16 16:50:43 1992 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * Makefile.in: define $(RM) to "rm -f" - -Sun Oct 11 16:05:48 1992 david d `zoo' zuhn (zoo at cirdan.cygnus.com) - - * intro.texi: added INFO-DIR-ENTRY - diff --git a/etc/Makefile.in b/etc/Makefile.in deleted file mode 100644 index 2bc345745..000000000 --- a/etc/Makefile.in +++ /dev/null @@ -1,157 +0,0 @@ -# -# Makefile.in for etc -# - -prefix = @prefix@ -exec_prefix = @exec_prefix@ - -srcdir = @srcdir@ -VPATH = @srcdir@ - -bindir = @bindir@ -libdir = @libdir@ -tooldir = $(libdir) -datadir = @datadir@ - -mandir = @mandir@ -man1dir = $(mandir)/man1 -man2dir = $(mandir)/man2 -man3dir = $(mandir)/man3 -man4dir = $(mandir)/man4 -man5dir = $(mandir)/man5 -man6dir = $(mandir)/man6 -man7dir = $(mandir)/man7 -man8dir = $(mandir)/man8 -man9dir = $(mandir)/man9 -infodir = @infodir@ - -SHELL = /bin/sh - -INSTALL = @INSTALL@ -INSTALL_PROGRAM = @INSTALL_PROGRAM@ -INSTALL_DATA = @INSTALL_DATA@ - -MAKEINFO = `if [ -f ../texinfo/makeinfo/makeinfo ]; \ - then echo ../texinfo/makeinfo/makeinfo; \ - else echo makeinfo; fi` -TEXI2DVI = `if [ -f ../texinfo/util/texi2dvi ]; \ - then echo ../texinfo/util/texi2dvi; \ - else echo texi2dvi; fi` -TEXI2HTML = texi2html -DVIPS = dvips - -# Where to find texinfo.tex to format documentation with TeX. -TEXIDIR = $(srcdir)/../texinfo - -#### Host, target, and site specific Makefile fragments come in here. -### - -INFOFILES = standards.info configure.info -DVIFILES = standards.dvi configure.dvi - -all: - -# We want install to imply install-info as per GNU standards. -install: install-info - -uninstall: - -info: - for f in $(INFOFILES); do \ - if test -f $(srcdir)/`echo $$f | sed -e 's/.info$$/.texi/'`; then \ - if $(MAKE) "MAKEINFO=$(MAKEINFO)" $$f; then \ - true; \ - else \ - exit 1; \ - fi; \ - fi; \ - done - -install-info: info - $(SHELL) $(srcdir)/../mkinstalldirs $(infodir) - if test ! -f standards.info; then cd $(srcdir); fi; \ - if test -f standards.info; then \ - for i in standards.info*; do \ - $(INSTALL_DATA) $$i $(infodir)/$$i; \ - done; \ - fi - if test ! -f configure.info; then cd $(srcdir); fi; \ - if test -f configure.info; then \ - for i in configure.info*; do \ - $(INSTALL_DATA) $$i $(infodir)/$$i; \ - done; \ - fi - -dvi: - for f in $(DVIFILES); do \ - if test -f $(srcdir)/`echo $$f | sed -e 's/.dvi$$/.texi/'`; then \ - if $(MAKE) "TEXI2DVI=$(TEXI2DVI)" $$f; then \ - true; \ - else \ - exit 1; \ - fi; \ - fi; \ - done - -standards.info: $(srcdir)/standards.texi $(srcdir)/make-stds.texi - $(MAKEINFO) --no-split -I$(srcdir) -o standards.info $(srcdir)/standards.texi - -standards.dvi: $(srcdir)/standards.texi - TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/standards.texi - -standards.ps: standards.dvi - $(DVIPS) standards.dvi -o standards.ps - -# makeinfo requires images to be in the current directory. -configure.info: $(srcdir)/configure.texi $(srcdir)/configdev.tin $(srcdir)/configbuild.tin - rm -f configdev.txt configbuild.txt - cp $(srcdir)/configdev.tin configdev.txt - cp $(srcdir)/configbuild.tin configbuild.txt - $(MAKEINFO) -I$(srcdir) -o configure.info $(srcdir)/configure.texi - rm -f configdev.txt configbuild.txt - -# texi2dvi wants both the .txt and the .eps files. -configure.dvi: $(srcdir)/configure.texi $(srcdir)/configdev.tin $(srcdir)/configbuild.tin $(srcdir)/configdev.ein $(srcdir)/configbuild.ein - rm -f configdev.txt configbuild.txt - cp $(srcdir)/configdev.tin configdev.txt - cp $(srcdir)/configbuild.tin configbuild.txt - rm -f configdev.eps configbuild.eps - cp $(srcdir)/configdev.ein configdev.eps - cp $(srcdir)/configbuild.ein configbuild.eps - TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/configure.texi - rm -f configdev.txt configbuild.txt - rm -f configdev.eps configbuild.eps - -# dvips requires images to be in the current directory -configure.ps: configure.dvi $(srcdir)/configdev.ein $(srcdir)/configbuild.ein - rm -f configdev.eps configbuild.eps - cp $(srcdir)/configdev.ein configdev.eps - cp $(srcdir)/configbuild.ein configbuild.eps - $(DVIPS) configure.dvi -o configure.ps - rm -f configdev.eps configbuild.eps - -configure.html: $(srcdir)/configure.texi - $(TEXI2HTML) -split_chapter $(srcdir)/configure.texi - -clean: - rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log - rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs - rm -f configdev.txt configbuild.txt configdev.eps configbuild.eps - rm -f configdev.jpg configbuild.jpg - -mostlyclean: clean - -distclean: clean - rm -f Makefile config.status config.cache - -maintainer-clean realclean: distclean - rm -f *.info* - -Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag) - $(SHELL) ./config.status - -## these last targets are for standards.texi conformance -dist: -check: -installcheck: -TAGS: diff --git a/etc/add-log.el b/etc/add-log.el deleted file mode 100644 index 60c88e8c9..000000000 --- a/etc/add-log.el +++ /dev/null @@ -1,573 +0,0 @@ -;;; ============ NOTE WELL! ============= -;;; -;;; You only need to use this file if you're using a version of Emacs -;;; prior to 20.1 to work on GDB. The only difference between this -;;; and the standard add-log.el provided with 19.34 is that it -;;; generates dates using the terser format used by Emacs 20. This is -;;; the format recommended for use in GDB ChangeLogs. -;;; -;;; To use this code, you should create a directory `~/elisp', save the code -;;; below in `~/elisp/add-log.el', and then put something like this in -;;; your `~/.emacs' file, to tell Emacs where to find it: -;;; -;;; (setq load-path -;;; (cons (expand-file-name "~/elisp") -;;; load-path)) -;;; -;;; If you want, you can also byte-compile it --- it'll run a little -;;; faster, and use a little less memory. (Not that those matter much for -;;; this file.) To do that, after you've saved the text as -;;; ~/elisp/add-log.el, bring it up in Emacs, and type -;;; -;;; C-u M-x byte-compile-file -;;; -;;; --- Jim Blandy - -;;; add-log.el --- change log maintenance commands for Emacs - -;; Copyright (C) 1985, 1986, 1988, 1993, 1994 Free Software Foundation, Inc. - -;; Keywords: maint - -;; This file is part of GNU Emacs. - -;; GNU Emacs 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. - -;; GNU Emacs 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 GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, -;; Boston, MA 02111-1307, USA. - -;;; Commentary: - -;; This facility is documented in the Emacs Manual. - -;;; Code: - -(defvar change-log-default-name nil - "*Name of a change log file for \\[add-change-log-entry].") - -(defvar add-log-current-defun-function nil - "\ -*If non-nil, function to guess name of current function from surrounding text. -\\[add-change-log-entry] calls this function (if nil, `add-log-current-defun' -instead) with no arguments. It returns a string or nil if it cannot guess.") - -;;;###autoload -(defvar add-log-full-name nil - "*Full name of user, for inclusion in ChangeLog daily headers. -This defaults to the value returned by the `user-full-name' function.") - -;;;###autoload -(defvar add-log-mailing-address nil - "*Electronic mail address of user, for inclusion in ChangeLog daily headers. -This defaults to the value of `user-mail-address'.") - -(defvar change-log-font-lock-keywords - '(("^[SMTWF].+" . font-lock-function-name-face) ; Date line. - ("^\t\\* \\([^ :\n]+\\)" 1 font-lock-comment-face) ; File name. - ("(\\([^)\n]+\\)):" 1 font-lock-keyword-face)) ; Function name. - "Additional expressions to highlight in Change Log mode.") - -(defvar change-log-mode-map nil - "Keymap for Change Log major mode.") -(if change-log-mode-map - nil - (setq change-log-mode-map (make-sparse-keymap)) - (define-key change-log-mode-map "\M-q" 'change-log-fill-paragraph)) - -(defun change-log-name () - (or change-log-default-name - (if (eq system-type 'vax-vms) - "$CHANGE_LOG$.TXT" - (if (or (eq system-type 'ms-dos) (eq system-type 'windows-nt)) - "changelo" - "ChangeLog")))) - -;;;###autoload -(defun prompt-for-change-log-name () - "Prompt for a change log name." - (let* ((default (change-log-name)) - (name (expand-file-name - (read-file-name (format "Log file (default %s): " default) - nil default)))) - ;; Handle something that is syntactically a directory name. - ;; Look for ChangeLog or whatever in that directory. - (if (string= (file-name-nondirectory name) "") - (expand-file-name (file-name-nondirectory default) - name) - ;; Handle specifying a file that is a directory. - (if (file-directory-p name) - (expand-file-name (file-name-nondirectory default) - (file-name-as-directory name)) - name)))) - -;;;###autoload -(defun find-change-log (&optional file-name) - "Find a change log file for \\[add-change-log-entry] and return the name. - -Optional arg FILE-NAME specifies the file to use. -If FILE-NAME is nil, use the value of `change-log-default-name'. -If 'change-log-default-name' is nil, behave as though it were 'ChangeLog' -\(or whatever we use on this operating system). - -If 'change-log-default-name' contains a leading directory component, then -simply find it in the current directory. Otherwise, search in the current -directory and its successive parents for a file so named. - -Once a file is found, `change-log-default-name' is set locally in the -current buffer to the complete file name." - ;; If user specified a file name or if this buffer knows which one to use, - ;; just use that. - (or file-name - (setq file-name (and change-log-default-name - (file-name-directory change-log-default-name) - change-log-default-name)) - (progn - ;; Chase links in the source file - ;; and use the change log in the dir where it points. - (setq file-name (or (and buffer-file-name - (file-name-directory - (file-chase-links buffer-file-name))) - default-directory)) - (if (file-directory-p file-name) - (setq file-name (expand-file-name (change-log-name) file-name))) - ;; Chase links before visiting the file. - ;; This makes it easier to use a single change log file - ;; for several related directories. - (setq file-name (file-chase-links file-name)) - (setq file-name (expand-file-name file-name)) - ;; Move up in the dir hierarchy till we find a change log file. - (let ((file1 file-name) - parent-dir) - (while (and (not (or (get-file-buffer file1) (file-exists-p file1))) - (progn (setq parent-dir - (file-name-directory - (directory-file-name - (file-name-directory file1)))) - ;; Give up if we are already at the root dir. - (not (string= (file-name-directory file1) - parent-dir)))) - ;; Move up to the parent dir and try again. - (setq file1 (expand-file-name - (file-name-nondirectory (change-log-name)) - parent-dir))) - ;; If we found a change log in a parent, use that. - (if (or (get-file-buffer file1) (file-exists-p file1)) - (setq file-name file1))))) - ;; Make a local variable in this buffer so we needn't search again. - (set (make-local-variable 'change-log-default-name) file-name) - file-name) - -;;;###autoload -(defun add-change-log-entry (&optional whoami file-name other-window new-entry) - "Find change log file and add an entry for today. -Optional arg (interactive prefix) non-nil means prompt for user name and site. -Second arg is file name of change log. If nil, uses `change-log-default-name'. -Third arg OTHER-WINDOW non-nil means visit in other window. -Fourth arg NEW-ENTRY non-nil means always create a new entry at the front; -never append to an existing entry." - (interactive (list current-prefix-arg - (prompt-for-change-log-name))) - (or add-log-full-name - (setq add-log-full-name (user-full-name))) - (or add-log-mailing-address - (setq add-log-mailing-address user-mail-address)) - (if whoami - (progn - (setq add-log-full-name (read-input "Full name: " add-log-full-name)) - ;; Note that some sites have room and phone number fields in - ;; full name which look silly when inserted. Rather than do - ;; anything about that here, let user give prefix argument so that - ;; s/he can edit the full name field in prompter if s/he wants. - (setq add-log-mailing-address - (read-input "Mailing address: " add-log-mailing-address)))) - (let ((defun (funcall (or add-log-current-defun-function - 'add-log-current-defun))) - paragraph-end entry) - - (setq file-name (expand-file-name (find-change-log file-name))) - - ;; Set ENTRY to the file name to use in the new entry. - (and buffer-file-name - ;; Never want to add a change log entry for the ChangeLog file itself. - (not (string= buffer-file-name file-name)) - (setq entry (if (string-match - (concat "^" (regexp-quote (file-name-directory - file-name))) - buffer-file-name) - (substring buffer-file-name (match-end 0)) - (file-name-nondirectory buffer-file-name)))) - - (if (and other-window (not (equal file-name buffer-file-name))) - (find-file-other-window file-name) - (find-file file-name)) - (or (eq major-mode 'change-log-mode) - (change-log-mode)) - (undo-boundary) - (goto-char (point-min)) - (let ((heading (format "%s %s <%s>" - (format-time-string "%Y-%m-%d") - add-log-full-name - add-log-mailing-address))) - (if (looking-at (regexp-quote heading)) - (forward-line 1) - (insert heading "\n\n"))) - - ;; Search only within the first paragraph. - (if (looking-at "\n*[^\n* \t]") - (skip-chars-forward "\n") - (forward-paragraph 1)) - (setq paragraph-end (point)) - (goto-char (point-min)) - - ;; Now insert the new line for this entry. - (cond ((re-search-forward "^\\s *\\*\\s *$" paragraph-end t) - ;; Put this file name into the existing empty entry. - (if entry - (insert entry))) - ((and (not new-entry) - (let (case-fold-search) - (re-search-forward - (concat (regexp-quote (concat "* " entry)) - ;; Don't accept `foo.bar' when - ;; looking for `foo': - "\\(\\s \\|[(),:]\\)") - paragraph-end t))) - ;; Add to the existing entry for the same file. - (re-search-forward "^\\s *$\\|^\\s \\*") - (goto-char (match-beginning 0)) - ;; Delete excess empty lines; make just 2. - (while (and (not (eobp)) (looking-at "^\\s *$")) - (delete-region (point) (save-excursion (forward-line 1) (point)))) - (insert "\n\n") - (forward-line -2) - (indent-relative-maybe)) - (t - ;; Make a new entry. - (forward-line 1) - (while (looking-at "\\sW") - (forward-line 1)) - (while (and (not (eobp)) (looking-at "^\\s *$")) - (delete-region (point) (save-excursion (forward-line 1) (point)))) - (insert "\n\n\n") - (forward-line -2) - (indent-to left-margin) - (insert "* " (or entry "")))) - ;; Now insert the function name, if we have one. - ;; Point is at the entry for this file, - ;; either at the end of the line or at the first blank line. - (if defun - (progn - ;; Make it easy to get rid of the function name. - (undo-boundary) - (insert (if (save-excursion - (beginning-of-line 1) - (looking-at "\\s *$")) - "" - " ") - "(" defun "): ")) - ;; No function name, so put in a colon unless we have just a star. - (if (not (save-excursion - (beginning-of-line 1) - (looking-at "\\s *\\(\\*\\s *\\)?$"))) - (insert ": "))))) - -;;;###autoload -(defun add-change-log-entry-other-window (&optional whoami file-name) - "Find change log file in other window and add an entry for today. -Optional arg (interactive prefix) non-nil means prompt for user name and site. -Second arg is file name of change log. \ -If nil, uses `change-log-default-name'." - (interactive (if current-prefix-arg - (list current-prefix-arg - (prompt-for-change-log-name)))) - (add-change-log-entry whoami file-name t)) -;;;###autoload (define-key ctl-x-4-map "a" 'add-change-log-entry-other-window) - -;;;###autoload -(defun change-log-mode () - "Major mode for editing change logs; like Indented Text Mode. -Prevents numeric backups and sets `left-margin' to 8 and `fill-column' to 74. -New log entries are usually made with \\[add-change-log-entry] or \\[add-change-log-entry-other-window]. -Each entry behaves as a paragraph, and the entries for one day as a page. -Runs `change-log-mode-hook'." - (interactive) - (kill-all-local-variables) - (indented-text-mode) - (setq major-mode 'change-log-mode - mode-name "Change Log" - left-margin 8 - fill-column 74 - indent-tabs-mode t - tab-width 8) - (use-local-map change-log-mode-map) - ;; Let each entry behave as one paragraph: - ;; We really do want "^" in paragraph-start below: it is only the lines that - ;; begin at column 0 (despite the left-margin of 8) that we are looking for. - (set (make-local-variable 'paragraph-start) "\\s *$\\|\f\\|^\\sw") - (set (make-local-variable 'paragraph-separate) "\\s *$\\|\f\\|^\\sw") - ;; Let all entries for one day behave as one page. - ;; Match null string on the date-line so that the date-line - ;; is grouped with what follows. - (set (make-local-variable 'page-delimiter) "^\\<\\|^\f") - (set (make-local-variable 'version-control) 'never) - (set (make-local-variable 'adaptive-fill-regexp) "\\s *") - (set (make-local-variable 'font-lock-defaults) - '(change-log-font-lock-keywords t)) - (run-hooks 'change-log-mode-hook)) - -;; It might be nice to have a general feature to replace this. The idea I -;; have is a variable giving a regexp matching text which should not be -;; moved from bol by filling. change-log-mode would set this to "^\\s *\\s(". -;; But I don't feel up to implementing that today. -(defun change-log-fill-paragraph (&optional justify) - "Fill the paragraph, but preserve open parentheses at beginning of lines. -Prefix arg means justify as well." - (interactive "P") - (let ((end (save-excursion (forward-paragraph) (point))) - (beg (save-excursion (backward-paragraph)(point))) - (paragraph-start (concat paragraph-start "\\|\\s *\\s("))) - (fill-region beg end justify))) - -(defvar add-log-current-defun-header-regexp - "^\\([A-Z][A-Z_ ]*[A-Z_]\\|[-_a-zA-Z]+\\)[ \t]*[:=]" - "*Heuristic regexp used by `add-log-current-defun' for unknown major modes.") - -;;;###autoload -(defun add-log-current-defun () - "Return name of function definition point is in, or nil. - -Understands C, Lisp, LaTeX (\"functions\" are chapters, sections, ...), -Texinfo (@node titles), Perl, and Fortran. - -Other modes are handled by a heuristic that looks in the 10K before -point for uppercase headings starting in the first column or -identifiers followed by `:' or `=', see variable -`add-log-current-defun-header-regexp'. - -Has a preference of looking backwards." - (condition-case nil - (save-excursion - (let ((location (point))) - (cond ((memq major-mode '(emacs-lisp-mode lisp-mode scheme-mode - lisp-interaction-mode)) - ;; If we are now precisely at the beginning of a defun, - ;; make sure beginning-of-defun finds that one - ;; rather than the previous one. - (or (eobp) (forward-char 1)) - (beginning-of-defun) - ;; Make sure we are really inside the defun found, not after it. - (if (and (looking-at "\\s(") - (progn (end-of-defun) - (< location (point))) - (progn (forward-sexp -1) - (>= location (point)))) - (progn - (if (looking-at "\\s(") - (forward-char 1)) - (forward-sexp 1) - (skip-chars-forward " '") - (buffer-substring (point) - (progn (forward-sexp 1) (point)))))) - ((and (memq major-mode '(c-mode c++-mode c++-c-mode objc-mode)) - (save-excursion (beginning-of-line) - ;; Use eq instead of = here to avoid - ;; error when at bob and char-after - ;; returns nil. - (while (eq (char-after (- (point) 2)) ?\\) - (forward-line -1)) - (looking-at "[ \t]*#[ \t]*define[ \t]"))) - ;; Handle a C macro definition. - (beginning-of-line) - (while (eq (char-after (- (point) 2)) ?\\) ;not =; note above - (forward-line -1)) - (search-forward "define") - (skip-chars-forward " \t") - (buffer-substring (point) - (progn (forward-sexp 1) (point)))) - ((memq major-mode '(c-mode c++-mode c++-c-mode objc-mode)) - (beginning-of-line) - ;; See if we are in the beginning part of a function, - ;; before the open brace. If so, advance forward. - (while (not (looking-at "{\\|\\(\\s *$\\)")) - (forward-line 1)) - (or (eobp) - (forward-char 1)) - (beginning-of-defun) - (if (progn (end-of-defun) - (< location (point))) - (progn - (backward-sexp 1) - (let (beg tem) - - (forward-line -1) - ;; Skip back over typedefs of arglist. - (while (and (not (bobp)) - (looking-at "[ \t\n]")) - (forward-line -1)) - ;; See if this is using the DEFUN macro used in Emacs, - ;; or the DEFUN macro used by the C library. - (if (condition-case nil - (and (save-excursion - (end-of-line) - (while (= (preceding-char) ?\\) - (end-of-line 2)) - (backward-sexp 1) - (beginning-of-line) - (setq tem (point)) - (looking-at "DEFUN\\b")) - (>= location tem)) - (error nil)) - (progn - (goto-char tem) - (down-list 1) - (if (= (char-after (point)) ?\") - (progn - (forward-sexp 1) - (skip-chars-forward " ,"))) - (buffer-substring (point) - (progn (forward-sexp 1) (point)))) - (if (looking-at "^[+-]") - (get-method-definition) - ;; Ordinary C function syntax. - (setq beg (point)) - (if (and (condition-case nil - ;; Protect against "Unbalanced parens" error. - (progn - (down-list 1) ; into arglist - (backward-up-list 1) - (skip-chars-backward " \t") - t) - (error nil)) - ;; Verify initial pos was after - ;; real start of function. - (save-excursion - (goto-char beg) - ;; For this purpose, include the line - ;; that has the decl keywords. This - ;; may also include some of the - ;; comments before the function. - (while (and (not (bobp)) - (save-excursion - (forward-line -1) - (looking-at "[^\n\f]"))) - (forward-line -1)) - (>= location (point))) - ;; Consistency check: going down and up - ;; shouldn't take us back before BEG. - (> (point) beg)) - (let (end middle) - ;; Don't include any final newline - ;; in the name we use. - (if (= (preceding-char) ?\n) - (forward-char -1)) - (setq end (point)) - (backward-sexp 1) - ;; Now find the right beginning of the name. - ;; Include certain keywords if they - ;; precede the name. - (setq middle (point)) - (forward-word -1) - ;; Ignore these subparts of a class decl - ;; and move back to the class name itself. - (while (looking-at "public \\|private ") - (skip-chars-backward " \t:") - (setq end (point)) - (backward-sexp 1) - (setq middle (point)) - (forward-word -1)) - (and (bolp) - (looking-at "struct \\|union \\|class ") - (setq middle (point))) - (buffer-substring middle end))))))))) - ((memq major-mode - '(TeX-mode plain-TeX-mode LaTeX-mode;; tex-mode.el - plain-tex-mode latex-mode;; cmutex.el - )) - (if (re-search-backward - "\\\\\\(sub\\)*\\(section\\|paragraph\\|chapter\\)" nil t) - (progn - (goto-char (match-beginning 0)) - (buffer-substring (1+ (point));; without initial backslash - (progn - (end-of-line) - (point)))))) - ((eq major-mode 'texinfo-mode) - (if (re-search-backward "^@node[ \t]+\\([^,\n]+\\)" nil t) - (buffer-substring (match-beginning 1) - (match-end 1)))) - ((eq major-mode 'perl-mode) - (if (re-search-backward "^sub[ \t]+\\([^ \t\n]+\\)" nil t) - (buffer-substring (match-beginning 1) - (match-end 1)))) - ((eq major-mode 'fortran-mode) - ;; must be inside function body for this to work - (beginning-of-fortran-subprogram) - (let ((case-fold-search t)) ; case-insensitive - ;; search for fortran subprogram start - (if (re-search-forward - "^[ \t]*\\(program\\|subroutine\\|function\ -\\|[ \ta-z0-9*]*[ \t]+function\\)" - nil t) - (progn - ;; move to EOL or before first left paren - (if (re-search-forward "[(\n]" nil t) - (progn (forward-char -1) - (skip-chars-backward " \t")) - (end-of-line)) - ;; Use the name preceding that. - (buffer-substring (point) - (progn (forward-sexp -1) - (point))))))) - (t - ;; If all else fails, try heuristics - (let (case-fold-search) - (end-of-line) - (if (re-search-backward add-log-current-defun-header-regexp - (- (point) 10000) - t) - (buffer-substring (match-beginning 1) - (match-end 1)))))))) - (error nil))) - -(defvar get-method-definition-md) - -;; Subroutine used within get-method-definition. -;; Add the last match in the buffer to the end of `md', -;; followed by the string END; move to the end of that match. -(defun get-method-definition-1 (end) - (setq get-method-definition-md - (concat get-method-definition-md - (buffer-substring (match-beginning 1) (match-end 1)) - end)) - (goto-char (match-end 0))) - -;; For objective C, return the method name if we are in a method. -(defun get-method-definition () - (let ((get-method-definition-md "[")) - (save-excursion - (if (re-search-backward "^@implementation\\s-*\\([A-Za-z_]*\\)" nil t) - (get-method-definition-1 " "))) - (save-excursion - (cond - ((re-search-forward "^\\([-+]\\)[ \t\n\f\r]*\\(([^)]*)\\)?\\s-*" nil t) - (get-method-definition-1 "") - (while (not (looking-at "[{;]")) - (looking-at - "\\([A-Za-z_]*:?\\)\\s-*\\(([^)]*)\\)?[A-Za-z_]*[ \t\n\f\r]*") - (get-method-definition-1 "")) - (concat get-method-definition-md "]")))))) - - -(provide 'add-log) - -;;; add-log.el ends here diff --git a/etc/add-log.vi b/etc/add-log.vi deleted file mode 100644 index efb8c77aa..000000000 --- a/etc/add-log.vi +++ /dev/null @@ -1,11 +0,0 @@ -Here is a vi macro to create entries in the recommended format for -GDB's ChangeLogs. - -map 1GO:r !date '+\%Y-\%m-\%d'2GA Jason Molenda (:r !whoamikJxA@:r !hostnameA)kJxkddjO
*
k$ - -It contains control and escape sequences, so don't just cut and paste it. -You'll need to change the "Jason Molenda" bit, of course. :-) Put this -in your $HOME/.exrc and when you type control-X in move-around-mode, -you'll have a changelog template inserted. - ---- Jason Molenda diff --git a/etc/configbuild.ein b/etc/configbuild.ein deleted file mode 100644 index 7a0e214f2..000000000 --- a/etc/configbuild.ein +++ /dev/null @@ -1,149 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: configbuild.fig -%%Creator: fig2dev Version 3.1 Patchlevel 1 -%%CreationDate: Fri Jun 12 20:13:16 1998 -%%For: ian@tito.cygnus.com (Ian Lance Taylor) -%%Orientation: Portrait -%%BoundingBox: 0 0 322 173 -%%Pages: 0 -%%BeginSetup -%%IncludeFeature: *PageSize Letter -%%EndSetup -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {} def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save --62.0 226.0 translate -1 -1 scale - -/clp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/l {lineto} bind def -/m {moveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def -%%EndProlog - -$F2psBegin -10 setmiterlimit - 0.06000 0.06000 sc -7.500 slw -% Polyline -n 1050 900 m 2100 900 l 2100 1425 l 1050 1425 l clp gs col-1 s gr -% Polyline -n 1500 1425 m 1500 2100 l gs col-1 s gr -n 1530.00 1980.00 m 1500.00 2100.00 l 1470.00 1980.00 l 1500.50 1980.50 l 1530.00 1980.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 1500 2625 m 1500 3300 l gs col-1 s gr -n 1530.00 3180.00 m 1500.00 3300.00 l 1470.00 3180.00 l 1500.50 3180.50 l 1530.00 3180.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 2925 900 m 3825 900 l 3825 1425 l 2925 1425 l clp gs col-1 s gr -% Polyline -n 1155 2100 m 1050 2100 1050 2520 105 arcto 4 {pop} repeat 1050 2625 2220 2625 105 arcto 4 {pop} repeat 2325 2625 2325 2205 105 arcto 4 {pop} repeat 2325 2100 1155 2100 105 arcto 4 {pop} repeat clp gs col-1 s gr -% Polyline -n 2850 2100 m 4125 2100 l 4125 2625 l 2850 2625 l clp gs col-1 s gr -% Polyline -n 3375 1425 m 3375 2100 l gs col-1 s gr -n 3405.00 1980.00 m 3375.00 2100.00 l 3345.00 1980.00 l 3375.50 1980.50 l 3405.00 1980.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 5100 900 m 6300 900 l 6300 1350 l 5100 1350 l clp gs col-1 s gr -% Polyline -n 5625 1350 m 5625 2100 l gs col-1 s gr -n 5655.00 1980.00 m 5625.00 2100.00 l 5595.00 1980.00 l 5625.50 1980.50 l 5655.00 1980.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 5205 2100 m 5100 2100 5100 2520 105 arcto 4 {pop} repeat 5100 2625 6270 2625 105 arcto 4 {pop} repeat 6375 2625 6375 2205 105 arcto 4 {pop} repeat 6375 2100 5205 2100 105 arcto 4 {pop} repeat clp gs col-1 s gr -% Polyline -n 5625 2625 m 5625 3300 l gs col-1 s gr -n 5655.00 3180.00 m 5625.00 3300.00 l 5595.00 3180.00 l 5625.50 3180.50 l 5655.00 3180.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 5100 3300 m 6225 3300 l 6225 3750 l 5100 3750 l clp gs col-1 s gr -% Polyline - [1 50.0] 50.000000 setdash -n 2850 2400 m 2325 2400 l gs col-1 s gr [] 0 setdash -n 2445.00 2430.00 m 2325.00 2400.00 l 2445.00 2370.00 l 2445.50 2400.50 l 2445.00 2430.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline - [1 50.0] 50.000000 setdash -n 4125 2400 m 5100 2400 l gs col-1 s gr [] 0 setdash -n 4980.00 2370.00 m 5100.00 2400.00 l 4980.00 2430.00 l 4980.50 2400.50 l 4980.00 2370.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 1050 3300 m 1950 3300 l 1950 3750 l 1050 3750 l clp gs col-1 s gr -/Times-Roman findfont 180.00 scalefont setfont -1200 1200 m -gs 1 -1 sc (config.in) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -3000 1200 m -gs 1 -1 sc (configure) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -3000 2400 m -gs 1 -1 sc (config.status) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -1200 2400 m -gs 1 -1 sc (config.status) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -1200 3600 m -gs 1 -1 sc (config.h) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -5250 1200 m -gs 1 -1 sc (Makefile.in) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -5250 2400 m -gs 1 -1 sc (config.status) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -5250 3600 m -gs 1 -1 sc (Makefile) col-1 show gr -$F2psEnd -restore diff --git a/etc/configbuild.fig b/etc/configbuild.fig deleted file mode 100644 index 747592d3d..000000000 --- a/etc/configbuild.fig +++ /dev/null @@ -1,50 +0,0 @@ -#FIG 3.1 -Portrait -Center -Inches -1200 2 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 1050 900 2100 900 2100 1425 1050 1425 1050 900 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1500 1425 1500 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1500 2625 1500 3300 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 2925 900 3825 900 3825 1425 2925 1425 2925 900 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 2325 2625 2325 2100 1050 2100 1050 2625 2325 2625 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 2850 2100 4125 2100 4125 2625 2850 2625 2850 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3375 1425 3375 2100 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 5100 900 6300 900 6300 1350 5100 1350 5100 900 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 5625 1350 5625 2100 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 6375 2625 6375 2100 5100 2100 5100 2625 6375 2625 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 5625 2625 5625 3300 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 5100 3300 6225 3300 6225 3750 5100 3750 5100 3300 -2 1 2 1 -1 7 0 0 -1 3.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 2850 2400 2325 2400 -2 1 2 1 -1 7 0 0 -1 3.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4125 2400 5100 2400 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 1050 3300 1950 3300 1950 3750 1050 3750 1050 3300 -4 0 -1 0 0 0 12 0.0000000 4 180 645 1200 1200 config.in\001 -4 0 -1 0 0 0 12 0.0000000 4 180 705 3000 1200 configure\001 -4 0 -1 0 0 0 12 0.0000000 4 180 990 3000 2400 config.status\001 -4 0 -1 0 0 0 12 0.0000000 4 180 990 1200 2400 config.status\001 -4 0 -1 0 0 0 12 0.0000000 4 180 600 1200 3600 config.h\001 -4 0 -1 0 0 0 12 0.0000000 4 135 855 5250 1200 Makefile.in\001 -4 0 -1 0 0 0 12 0.0000000 4 180 990 5250 2400 config.status\001 -4 0 -1 0 0 0 12 0.0000000 4 135 675 5250 3600 Makefile\001 diff --git a/etc/configbuild.jin b/etc/configbuild.jin Binary files differdeleted file mode 100644 index 44cd9397a..000000000 --- a/etc/configbuild.jin +++ /dev/null diff --git a/etc/configbuild.tin b/etc/configbuild.tin deleted file mode 100644 index cfdd6fe07..000000000 --- a/etc/configbuild.tin +++ /dev/null @@ -1,9 +0,0 @@ - config.in *configure* Makefile.in - | | | - | v | - | config.status | - | | | - *config.status*<======+==========>*config.status* - | | - v v - config.h Makefile diff --git a/etc/configdev.ein b/etc/configdev.ein deleted file mode 100644 index 7f837850d..000000000 --- a/etc/configdev.ein +++ /dev/null @@ -1,185 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: configdev.fig -%%Creator: fig2dev Version 3.1 Patchlevel 1 -%%CreationDate: Mon Jun 15 17:35:19 1998 -%%For: ian@tito.cygnus.com (Ian Lance Taylor) -%%Orientation: Portrait -%%BoundingBox: 0 0 344 317 -%%Pages: 0 -%%BeginSetup -%%IncludeFeature: *PageSize Letter -%%EndSetup -%%EndComments -/$F2psDict 200 dict def -$F2psDict begin -$F2psDict /mtrx matrix put -/col-1 {} def -/col0 {0.000 0.000 0.000 srgb} bind def -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def - -end -save --62.0 370.0 translate -1 -1 scale - -/clp {closepath} bind def -/ef {eofill} bind def -/gr {grestore} bind def -/gs {gsave} bind def -/l {lineto} bind def -/m {moveto} bind def -/n {newpath} bind def -/s {stroke} bind def -/slc {setlinecap} bind def -/slj {setlinejoin} bind def -/slw {setlinewidth} bind def -/srgb {setrgbcolor} bind def -/rot {rotate} bind def -/sc {scale} bind def -/tr {translate} bind def -/tnt {dup dup currentrgbcolor - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add - 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} - bind def -/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul - 4 -2 roll mul srgb} bind def -/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def -/$F2psEnd {$F2psEnteredState restore end} def -%%EndProlog - -$F2psBegin -10 setmiterlimit - 0.06000 0.06000 sc -7.500 slw -% Polyline -n 1050 900 m 2100 900 l 2100 1425 l 1050 1425 l clp gs col-1 s gr -% Polyline -n 2925 900 m 3975 900 l 3975 1425 l 2925 1425 l clp gs col-1 s gr -% Polyline -n 5550 900 m 6750 900 l 6750 1350 l 5550 1350 l clp gs col-1 s gr -% Polyline -n 3750 1800 m 5025 1800 l 5025 2250 l 3750 2250 l clp gs col-1 s gr -% Polyline -n 1155 2100 m 1050 2100 1050 2520 105 arcto 4 {pop} repeat 1050 2625 2070 2625 105 arcto 4 {pop} repeat 2175 2625 2175 2205 105 arcto 4 {pop} repeat 2175 2100 1155 2100 105 arcto 4 {pop} repeat clp gs col-1 s gr -% Polyline -n 5550 3300 m 6675 3300 l 6675 3750 l 5550 3750 l clp gs col-1 s gr -% Polyline -n 5655 2100 m 5550 2100 5550 2520 105 arcto 4 {pop} repeat 5550 2625 6495 2625 105 arcto 4 {pop} repeat 6600 2625 6600 2205 105 arcto 4 {pop} repeat 6600 2100 5655 2100 105 arcto 4 {pop} repeat clp gs col-1 s gr -% Polyline -n 3750 3600 m 4875 3600 l 4875 4050 l 3750 4050 l clp gs col-1 s gr -% Polyline -n 3855 2700 m 3750 2700 3750 3045 105 arcto 4 {pop} repeat 3750 3150 4545 3150 105 arcto 4 {pop} repeat 4650 3150 4650 2805 105 arcto 4 {pop} repeat 4650 2700 3855 2700 105 arcto 4 {pop} repeat clp gs col-1 s gr -% Polyline -n 2850 5700 m 3750 5700 l 3750 6150 l 2850 6150 l clp gs col-1 s gr -% Polyline -n 3030 4800 m 2925 4800 2925 5145 105 arcto 4 {pop} repeat 2925 5250 3645 5250 105 arcto 4 {pop} repeat 3750 5250 3750 4905 105 arcto 4 {pop} repeat 3750 4800 3030 4800 105 arcto 4 {pop} repeat clp gs col-1 s gr -% Polyline -n 1500 1425 m 1500 2100 l gs col-1 s gr -n 1530.00 1980.00 m 1500.00 2100.00 l 1470.00 1980.00 l 1500.50 1980.50 l 1530.00 1980.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 3300 1425 m 3300 4800 l gs col-1 s gr -n 3330.00 4680.00 m 3300.00 4800.00 l 3270.00 4680.00 l 3300.50 4680.50 l 3330.00 4680.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 3300 1575 m 1875 1575 l 1875 2100 l gs col-1 s gr -n 1905.00 1980.00 m 1875.00 2100.00 l 1845.00 1980.00 l 1875.50 1980.50 l 1905.00 1980.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 3300 1575 m 5700 1575 l 5700 2100 l gs col-1 s gr -n 5730.00 1980.00 m 5700.00 2100.00 l 5670.00 1980.00 l 5700.50 1980.50 l 5730.00 1980.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 6225 1350 m 6225 2100 l gs col-1 s gr -n 6255.00 1980.00 m 6225.00 2100.00 l 6195.00 1980.00 l 6225.50 1980.50 l 6255.00 1980.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 6075 2625 m 6075 3300 l gs col-1 s gr -n 6105.00 3180.00 m 6075.00 3300.00 l 6045.00 3180.00 l 6075.50 3180.50 l 6105.00 3180.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 4200 2250 m 4200 2700 l gs col-1 s gr -n 4230.00 2580.00 m 4200.00 2700.00 l 4170.00 2580.00 l 4200.50 2580.50 l 4230.00 2580.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 4200 3150 m 4200 3600 l gs col-1 s gr -n 4230.00 3480.00 m 4200.00 3600.00 l 4170.00 3480.00 l 4200.50 3480.50 l 4230.00 3480.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 4200 4050 m 4200 4500 l 3675 4500 l 3675 4800 l gs col-1 s gr -n 3705.00 4680.00 m 3675.00 4800.00 l 3645.00 4680.00 l 3675.50 4680.50 l 3705.00 4680.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 3375 5250 m 3375 5700 l gs col-1 s gr -n 3405.00 5580.00 m 3375.00 5700.00 l 3345.00 5580.00 l 3375.50 5580.50 l 3405.00 5580.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 3300 2925 m 3750 2925 l gs col-1 s gr -n 3630.00 2895.00 m 3750.00 2925.00 l 3630.00 2955.00 l 3630.50 2925.50 l 3630.00 2895.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 1500 2625 m 1500 3300 l gs col-1 s gr -n 1530.00 3180.00 m 1500.00 3300.00 l 1470.00 3180.00 l 1500.50 3180.50 l 1530.00 3180.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -% Polyline -n 1050 3300 m 2100 3300 l 2100 3750 l 1050 3750 l clp gs col-1 s gr -% Polyline -n 4875 3825 m 5250 3825 l 5250 2400 l 5550 2400 l gs col-1 s gr -n 5430.00 2370.00 m 5550.00 2400.00 l 5430.00 2430.00 l 5430.50 2400.50 l 5430.00 2370.00 l clp gs 0.00 setgray ef gr gs col-1 s gr -/Times-Roman findfont 180.00 scalefont setfont -1200 1200 m -gs 1 -1 sc (acconfig.h) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -3000 1200 m -gs 1 -1 sc (configure.in) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -5700 1200 m -gs 1 -1 sc (Makefile.am) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -3900 2100 m -gs 1 -1 sc (acinclude.m4) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -1200 2400 m -gs 1 -1 sc (autoheader) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -1200 3600 m -gs 1 -1 sc (config.in) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -5700 3600 m -gs 1 -1 sc (Makefile.in) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -5700 2400 m -gs 1 -1 sc (automake) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -3900 3900 m -gs 1 -1 sc (aclocal.m4) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -3900 3000 m -gs 1 -1 sc (aclocal) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -3000 6000 m -gs 1 -1 sc (configure) col-1 show gr -/Times-Roman findfont 180.00 scalefont setfont -3000 5100 m -gs 1 -1 sc (autoconf) col-1 show gr -$F2psEnd -restore diff --git a/etc/configdev.fig b/etc/configdev.fig deleted file mode 100644 index 4d386ec4f..000000000 --- a/etc/configdev.fig +++ /dev/null @@ -1,80 +0,0 @@ -#FIG 3.1 -Portrait -Center -Inches -1200 2 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 1050 900 2100 900 2100 1425 1050 1425 1050 900 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 2925 900 3975 900 3975 1425 2925 1425 2925 900 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 5550 900 6750 900 6750 1350 5550 1350 5550 900 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 3750 1800 5025 1800 5025 2250 3750 2250 3750 1800 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 2175 2625 2175 2100 1050 2100 1050 2625 2175 2625 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 5550 3300 6675 3300 6675 3750 5550 3750 5550 3300 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 6600 2625 6600 2100 5550 2100 5550 2625 6600 2625 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 3750 3600 4875 3600 4875 4050 3750 4050 3750 3600 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 4650 3150 4650 2700 3750 2700 3750 3150 4650 3150 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 2850 5700 3750 5700 3750 6150 2850 6150 2850 5700 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 3750 5250 3750 4800 2925 4800 2925 5250 3750 5250 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1500 1425 1500 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3300 1425 3300 4800 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 3 - 1 1 1.00 60.00 120.00 - 3300 1575 1875 1575 1875 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 3 - 1 1 1.00 60.00 120.00 - 3300 1575 5700 1575 5700 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 6225 1350 6225 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 6075 2625 6075 3300 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4200 2250 4200 2700 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4200 3150 4200 3600 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 4 - 1 1 1.00 60.00 120.00 - 4200 4050 4200 4500 3675 4500 3675 4800 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3375 5250 3375 5700 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3300 2925 3750 2925 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1500 2625 1500 3300 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 1050 3300 2100 3300 2100 3750 1050 3750 1050 3300 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 4 - 1 1 1.00 60.00 120.00 - 4875 3825 5250 3825 5250 2400 5550 2400 -4 0 -1 0 0 0 12 0.0000000 4 180 780 1200 1200 acconfig.h\001 -4 0 -1 0 0 0 12 0.0000000 4 180 885 3000 1200 configure.in\001 -4 0 -1 0 0 0 12 0.0000000 4 135 945 5700 1200 Makefile.am\001 -4 0 -1 0 0 0 12 0.0000000 4 135 990 3900 2100 acinclude.m4\001 -4 0 -1 0 0 0 12 0.0000000 4 135 840 1200 2400 autoheader\001 -4 0 -1 0 0 0 12 0.0000000 4 180 645 1200 3600 config.in\001 -4 0 -1 0 0 0 12 0.0000000 4 135 855 5700 3600 Makefile.in\001 -4 0 -1 0 0 0 12 0.0000000 4 135 735 5700 2400 automake\001 -4 0 -1 0 0 0 12 0.0000000 4 135 810 3900 3900 aclocal.m4\001 -4 0 -1 0 0 0 12 0.0000000 4 135 540 3900 3000 aclocal\001 -4 0 -1 0 0 0 12 0.0000000 4 180 705 3000 6000 configure\001 -4 0 -1 0 0 0 12 0.0000000 4 135 660 3000 5100 autoconf\001 diff --git a/etc/configdev.jin b/etc/configdev.jin Binary files differdeleted file mode 100644 index 9b11a71ac..000000000 --- a/etc/configdev.jin +++ /dev/null diff --git a/etc/configdev.tin b/etc/configdev.tin deleted file mode 100644 index c9b6f34f4..000000000 --- a/etc/configdev.tin +++ /dev/null @@ -1,17 +0,0 @@ - acconfig.h configure.in Makefile.am - | | | - | --------------+---------------------- | - | | | | | - v v | acinclude.m4 | | - *autoheader* | | v v - | | v --->*automake* - v |--->*aclocal* | | - config.in | | | v - | v | Makefile.in - | aclocal.m4--- - | | - v v - *autoconf* - | - v - configure diff --git a/etc/configure b/etc/configure deleted file mode 100755 index 101fcefec..000000000 --- a/etc/configure +++ /dev/null @@ -1,862 +0,0 @@ -#! /bin/sh - -# Guess values for system-dependent variables and create Makefiles. -# Generated automatically using autoconf version 2.12.1 -# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. -# -# This configure script is free software; the Free Software Foundation -# gives unlimited permission to copy, distribute and modify it. - -# Defaults: -ac_help= -ac_default_prefix=/usr/local -# Any additions from configure.in: - -# Initialize some variables set by options. -# The variables have the same names as the options, with -# dashes changed to underlines. -build=NONE -cache_file=./config.cache -exec_prefix=NONE -host=NONE -no_create= -nonopt=NONE -no_recursion= -prefix=NONE -program_prefix=NONE -program_suffix=NONE -program_transform_name=s,x,x, -silent= -site= -srcdir= -target=NONE -verbose= -x_includes=NONE -x_libraries=NONE -bindir='${exec_prefix}/bin' -sbindir='${exec_prefix}/sbin' -libexecdir='${exec_prefix}/libexec' -datadir='${prefix}/share' -sysconfdir='${prefix}/etc' -sharedstatedir='${prefix}/com' -localstatedir='${prefix}/var' -libdir='${exec_prefix}/lib' -includedir='${prefix}/include' -oldincludedir='/usr/include' -infodir='${prefix}/info' -mandir='${prefix}/man' - -# Initialize some other variables. -subdirs= -MFLAGS= MAKEFLAGS= -SHELL=${CONFIG_SHELL-/bin/sh} -# Maximum number of lines to put in a shell here document. -ac_max_here_lines=12 - -ac_prev= -for ac_option -do - - # If the previous option needs an argument, assign it. - if test -n "$ac_prev"; then - eval "$ac_prev=\$ac_option" - ac_prev= - continue - fi - - case "$ac_option" in - -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; - *) ac_optarg= ;; - esac - - # Accept the important Cygnus configure options, so we can diagnose typos. - - case "$ac_option" in - - -bindir | --bindir | --bindi | --bind | --bin | --bi) - ac_prev=bindir ;; - -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) - bindir="$ac_optarg" ;; - - -build | --build | --buil | --bui | --bu) - ac_prev=build ;; - -build=* | --build=* | --buil=* | --bui=* | --bu=*) - build="$ac_optarg" ;; - - -cache-file | --cache-file | --cache-fil | --cache-fi \ - | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) - ac_prev=cache_file ;; - -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ - | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) - cache_file="$ac_optarg" ;; - - -datadir | --datadir | --datadi | --datad | --data | --dat | --da) - ac_prev=datadir ;; - -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ - | --da=*) - datadir="$ac_optarg" ;; - - -disable-* | --disable-*) - ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then - { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } - fi - ac_feature=`echo $ac_feature| sed 's/-/_/g'` - eval "enable_${ac_feature}=no" ;; - - -enable-* | --enable-*) - ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then - { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } - fi - ac_feature=`echo $ac_feature| sed 's/-/_/g'` - case "$ac_option" in - *=*) ;; - *) ac_optarg=yes ;; - esac - eval "enable_${ac_feature}='$ac_optarg'" ;; - - -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ - | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ - | --exec | --exe | --ex) - ac_prev=exec_prefix ;; - -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ - | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ - | --exec=* | --exe=* | --ex=*) - exec_prefix="$ac_optarg" ;; - - -gas | --gas | --ga | --g) - # Obsolete; use --with-gas. - with_gas=yes ;; - - -help | --help | --hel | --he) - # Omit some internal or obsolete options to make the list less imposing. - # This message is too long to be a string in the A/UX 3.1 sh. - cat << EOF -Usage: configure [options] [host] -Options: [defaults in brackets after descriptions] -Configuration: - --cache-file=FILE cache test results in FILE - --help print this message - --no-create do not create output files - --quiet, --silent do not print \`checking...' messages - --version print the version of autoconf that created configure -Directory and file names: - --prefix=PREFIX install architecture-independent files in PREFIX - [$ac_default_prefix] - --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX - [same as prefix] - --bindir=DIR user executables in DIR [EPREFIX/bin] - --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] - --libexecdir=DIR program executables in DIR [EPREFIX/libexec] - --datadir=DIR read-only architecture-independent data in DIR - [PREFIX/share] - --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] - --sharedstatedir=DIR modifiable architecture-independent data in DIR - [PREFIX/com] - --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] - --libdir=DIR object code libraries in DIR [EPREFIX/lib] - --includedir=DIR C header files in DIR [PREFIX/include] - --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] - --infodir=DIR info documentation in DIR [PREFIX/info] - --mandir=DIR man documentation in DIR [PREFIX/man] - --srcdir=DIR find the sources in DIR [configure dir or ..] - --program-prefix=PREFIX prepend PREFIX to installed program names - --program-suffix=SUFFIX append SUFFIX to installed program names - --program-transform-name=PROGRAM - run sed PROGRAM on installed program names -EOF - cat << EOF -Host type: - --build=BUILD configure for building on BUILD [BUILD=HOST] - --host=HOST configure for HOST [guessed] - --target=TARGET configure for TARGET [TARGET=HOST] -Features and packages: - --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) - --enable-FEATURE[=ARG] include FEATURE [ARG=yes] - --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] - --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) - --x-includes=DIR X include files are in DIR - --x-libraries=DIR X library files are in DIR -EOF - if test -n "$ac_help"; then - echo "--enable and --with options recognized:$ac_help" - fi - exit 0 ;; - - -host | --host | --hos | --ho) - ac_prev=host ;; - -host=* | --host=* | --hos=* | --ho=*) - host="$ac_optarg" ;; - - -includedir | --includedir | --includedi | --included | --include \ - | --includ | --inclu | --incl | --inc) - ac_prev=includedir ;; - -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ - | --includ=* | --inclu=* | --incl=* | --inc=*) - includedir="$ac_optarg" ;; - - -infodir | --infodir | --infodi | --infod | --info | --inf) - ac_prev=infodir ;; - -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) - infodir="$ac_optarg" ;; - - -libdir | --libdir | --libdi | --libd) - ac_prev=libdir ;; - -libdir=* | --libdir=* | --libdi=* | --libd=*) - libdir="$ac_optarg" ;; - - -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ - | --libexe | --libex | --libe) - ac_prev=libexecdir ;; - -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ - | --libexe=* | --libex=* | --libe=*) - libexecdir="$ac_optarg" ;; - - -localstatedir | --localstatedir | --localstatedi | --localstated \ - | --localstate | --localstat | --localsta | --localst \ - | --locals | --local | --loca | --loc | --lo) - ac_prev=localstatedir ;; - -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ - | --localstate=* | --localstat=* | --localsta=* | --localst=* \ - | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) - localstatedir="$ac_optarg" ;; - - -mandir | --mandir | --mandi | --mand | --man | --ma | --m) - ac_prev=mandir ;; - -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) - mandir="$ac_optarg" ;; - - -nfp | --nfp | --nf) - # Obsolete; use --without-fp. - with_fp=no ;; - - -no-create | --no-create | --no-creat | --no-crea | --no-cre \ - | --no-cr | --no-c) - no_create=yes ;; - - -no-recursion | --no-recursion | --no-recursio | --no-recursi \ - | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) - no_recursion=yes ;; - - -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ - | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ - | --oldin | --oldi | --old | --ol | --o) - ac_prev=oldincludedir ;; - -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ - | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ - | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) - oldincludedir="$ac_optarg" ;; - - -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) - ac_prev=prefix ;; - -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) - prefix="$ac_optarg" ;; - - -program-prefix | --program-prefix | --program-prefi | --program-pref \ - | --program-pre | --program-pr | --program-p) - ac_prev=program_prefix ;; - -program-prefix=* | --program-prefix=* | --program-prefi=* \ - | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) - program_prefix="$ac_optarg" ;; - - -program-suffix | --program-suffix | --program-suffi | --program-suff \ - | --program-suf | --program-su | --program-s) - ac_prev=program_suffix ;; - -program-suffix=* | --program-suffix=* | --program-suffi=* \ - | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) - program_suffix="$ac_optarg" ;; - - -program-transform-name | --program-transform-name \ - | --program-transform-nam | --program-transform-na \ - | --program-transform-n | --program-transform- \ - | --program-transform | --program-transfor \ - | --program-transfo | --program-transf \ - | --program-trans | --program-tran \ - | --progr-tra | --program-tr | --program-t) - ac_prev=program_transform_name ;; - -program-transform-name=* | --program-transform-name=* \ - | --program-transform-nam=* | --program-transform-na=* \ - | --program-transform-n=* | --program-transform-=* \ - | --program-transform=* | --program-transfor=* \ - | --program-transfo=* | --program-transf=* \ - | --program-trans=* | --program-tran=* \ - | --progr-tra=* | --program-tr=* | --program-t=*) - program_transform_name="$ac_optarg" ;; - - -q | -quiet | --quiet | --quie | --qui | --qu | --q \ - | -silent | --silent | --silen | --sile | --sil) - silent=yes ;; - - -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) - ac_prev=sbindir ;; - -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ - | --sbi=* | --sb=*) - sbindir="$ac_optarg" ;; - - -sharedstatedir | --sharedstatedir | --sharedstatedi \ - | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ - | --sharedst | --shareds | --shared | --share | --shar \ - | --sha | --sh) - ac_prev=sharedstatedir ;; - -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ - | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ - | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ - | --sha=* | --sh=*) - sharedstatedir="$ac_optarg" ;; - - -site | --site | --sit) - ac_prev=site ;; - -site=* | --site=* | --sit=*) - site="$ac_optarg" ;; - - -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) - ac_prev=srcdir ;; - -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) - srcdir="$ac_optarg" ;; - - -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ - | --syscon | --sysco | --sysc | --sys | --sy) - ac_prev=sysconfdir ;; - -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ - | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) - sysconfdir="$ac_optarg" ;; - - -target | --target | --targe | --targ | --tar | --ta | --t) - ac_prev=target ;; - -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) - target="$ac_optarg" ;; - - -v | -verbose | --verbose | --verbos | --verbo | --verb) - verbose=yes ;; - - -version | --version | --versio | --versi | --vers) - echo "configure generated by autoconf version 2.12.1" - exit 0 ;; - - -with-* | --with-*) - ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then - { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } - fi - ac_package=`echo $ac_package| sed 's/-/_/g'` - case "$ac_option" in - *=*) ;; - *) ac_optarg=yes ;; - esac - eval "with_${ac_package}='$ac_optarg'" ;; - - -without-* | --without-*) - ac_package=`echo $ac_option|sed -e 's/-*without-//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then - { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } - fi - ac_package=`echo $ac_package| sed 's/-/_/g'` - eval "with_${ac_package}=no" ;; - - --x) - # Obsolete; use --with-x. - with_x=yes ;; - - -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ - | --x-incl | --x-inc | --x-in | --x-i) - ac_prev=x_includes ;; - -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ - | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) - x_includes="$ac_optarg" ;; - - -x-libraries | --x-libraries | --x-librarie | --x-librari \ - | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) - ac_prev=x_libraries ;; - -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ - | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) - x_libraries="$ac_optarg" ;; - - -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } - ;; - - *) - if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then - echo "configure: warning: $ac_option: invalid host type" 1>&2 - fi - if test "x$nonopt" != xNONE; then - { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } - fi - nonopt="$ac_option" - ;; - - esac -done - -if test -n "$ac_prev"; then - { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; } -fi - -trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 - -# File descriptor usage: -# 0 standard input -# 1 file creation -# 2 errors and warnings -# 3 some systems may open it to /dev/tty -# 4 used on the Kubota Titan -# 6 checking for... messages and results -# 5 compiler messages saved in config.log -if test "$silent" = yes; then - exec 6>/dev/null -else - exec 6>&1 -fi -exec 5>./config.log - -echo "\ -This file contains any messages produced by compilers while -running configure, to aid debugging if configure makes a mistake. -" 1>&5 - -# Strip out --no-create and --no-recursion so they do not pile up. -# Also quote any args containing shell metacharacters. -ac_configure_args= -for ac_arg -do - case "$ac_arg" in - -no-create | --no-create | --no-creat | --no-crea | --no-cre \ - | --no-cr | --no-c) ;; - -no-recursion | --no-recursion | --no-recursio | --no-recursi \ - | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;; - *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*) - ac_configure_args="$ac_configure_args '$ac_arg'" ;; - *) ac_configure_args="$ac_configure_args $ac_arg" ;; - esac -done - -# NLS nuisances. -# Only set these to C if already set. These must not be set unconditionally -# because not all systems understand e.g. LANG=C (notably SCO). -# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'! -# Non-C LC_CTYPE values break the ctype check. -if test "${LANG+set}" = set; then LANG=C; export LANG; fi -if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi -if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi -if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi - -# confdefs.h avoids OS command line length limits that DEFS can exceed. -rm -rf conftest* confdefs.h -# AIX cpp loses on an empty file, so make sure it contains at least a newline. -echo > confdefs.h - -# A filename unique to this package, relative to the directory that -# configure is in, which we can look for to find out if srcdir is correct. -ac_unique_file=Makefile.in - -# Find the source files, if location was not specified. -if test -z "$srcdir"; then - ac_srcdir_defaulted=yes - # Try the directory containing this script, then its parent. - ac_prog=$0 - ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` - test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. - srcdir=$ac_confdir - if test ! -r $srcdir/$ac_unique_file; then - srcdir=.. - fi -else - ac_srcdir_defaulted=no -fi -if test ! -r $srcdir/$ac_unique_file; then - if test "$ac_srcdir_defaulted" = yes; then - { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; } - else - { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; } - fi -fi -srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` - -# Prefer explicitly selected file to automatically selected ones. -if test -z "$CONFIG_SITE"; then - if test "x$prefix" != xNONE; then - CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" - else - CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" - fi -fi -for ac_site_file in $CONFIG_SITE; do - if test -r "$ac_site_file"; then - echo "loading site script $ac_site_file" - . "$ac_site_file" - fi -done - -if test -r "$cache_file"; then - echo "loading cache $cache_file" - . $cache_file -else - echo "creating cache $cache_file" - > $cache_file -fi - -ac_ext=c -# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. -ac_cpp='$CPP $CPPFLAGS' -ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' -ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' -cross_compiling=$ac_cv_prog_cc_cross - -if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then - # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. - if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then - ac_n= ac_c=' -' ac_t=' ' - else - ac_n=-n ac_c= ac_t= - fi -else - ac_n= ac_c='\c' ac_t= -fi - - - -ac_aux_dir= -for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do - if test -f $ac_dir/install-sh; then - ac_aux_dir=$ac_dir - ac_install_sh="$ac_aux_dir/install-sh -c" - break - elif test -f $ac_dir/install.sh; then - ac_aux_dir=$ac_dir - ac_install_sh="$ac_aux_dir/install.sh -c" - break - fi -done -if test -z "$ac_aux_dir"; then - { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; } -fi -ac_config_guess=$ac_aux_dir/config.guess -ac_config_sub=$ac_aux_dir/config.sub -ac_configure=$ac_aux_dir/configure # This should be Cygnus configure. - -# Find a good install program. We prefer a C program (faster), -# so one script is as good as another. But avoid the broken or -# incompatible versions: -# SysV /etc/install, /usr/sbin/install -# SunOS /usr/etc/install -# IRIX /sbin/install -# AIX /bin/install -# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag -# AFS /usr/afsws/bin/install, which mishandles nonexistent args -# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff" -# ./install, which can be erroneously created by make from ./install.sh. -echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6 -echo "configure:555: checking for a BSD compatible install" >&5 -if test -z "$INSTALL"; then -if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - IFS="${IFS= }"; ac_save_IFS="$IFS"; IFS="${IFS}:" - for ac_dir in $PATH; do - # Account for people who put trailing slashes in PATH elements. - case "$ac_dir/" in - /|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;; - *) - # OSF1 and SCO ODT 3.0 have their own names for install. - # Don't use installbsd from OSF since it installs stuff as root - # by default. - for ac_prog in ginstall scoinst install; do - if test -f $ac_dir/$ac_prog; then - if test $ac_prog = install && - grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then - # AIX install. It has an incompatible calling convention. - : - else - ac_cv_path_install="$ac_dir/$ac_prog -c" - break 2 - fi - fi - done - ;; - esac - done - IFS="$ac_save_IFS" - -fi - if test "${ac_cv_path_install+set}" = set; then - INSTALL="$ac_cv_path_install" - else - # As a last resort, use the slow shell script. We don't cache a - # path for INSTALL within a source directory, because that will - # break other packages using the cache if that directory is - # removed, or if the path is relative. - INSTALL="$ac_install_sh" - fi -fi -echo "$ac_t""$INSTALL" 1>&6 - -# Use test -z because SunOS4 sh mishandles braces in ${var-val}. -# It thinks the first close brace ends the variable substitution. -test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}' - -test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' - - -trap '' 1 2 15 -cat > confcache <<\EOF -# This file is a shell script that caches the results of configure -# tests run on this system so they can be shared between configure -# scripts and configure runs. It is not useful on other systems. -# If it contains results you don't want to keep, you may remove or edit it. -# -# By default, configure uses ./config.cache as the cache file, -# creating it if it does not exist already. You can give configure -# the --cache-file=FILE option to use a different cache file; that is -# what configure does when it calls configure scripts in -# subdirectories, so they share the cache. -# Giving --cache-file=/dev/null disables caching, for debugging configure. -# config.status only pays attention to the cache file if you give it the -# --recheck option to rerun configure. -# -EOF -# The following way of writing the cache mishandles newlines in values, -# but we know of no workaround that is simple, portable, and efficient. -# So, don't put newlines in cache variables' values. -# Ultrix sh set writes to stderr and can't be redirected directly, -# and sets the high bit in the cache file unless we assign to the vars. -(set) 2>&1 | - case `(ac_space=' '; set) 2>&1 | grep ac_space` in - *ac_space=\ *) - # `set' does not quote correctly, so add quotes (double-quote substitution - # turns \\\\ into \\, and sed turns \\ into \). - sed -n \ - -e "s/'/'\\\\''/g" \ - -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p" - ;; - *) - # `set' quotes correctly as required by POSIX, so do not add quotes. - sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p' - ;; - esac >> confcache -if cmp -s $cache_file confcache; then - : -else - if test -w $cache_file; then - echo "updating cache $cache_file" - cat confcache > $cache_file - else - echo "not updating unwritable cache $cache_file" - fi -fi -rm -f confcache - -trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 - -test "x$prefix" = xNONE && prefix=$ac_default_prefix -# Let make expand exec_prefix. -test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' - -# Any assignment to VPATH causes Sun make to only execute -# the first set of double-colon rules, so remove it if not needed. -# If there is a colon in the path, we need to keep it. -if test "x$srcdir" = x.; then - ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' -fi - -trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 - -# Transform confdefs.h into DEFS. -# Protect against shell expansion while executing Makefile rules. -# Protect against Makefile macro expansion. -cat > conftest.defs <<\EOF -s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g -s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g -s%\[%\\&%g -s%\]%\\&%g -s%\$%$$%g -EOF -DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '` -rm -f conftest.defs - - -# Without the "./", some shells look in PATH for config.status. -: ${CONFIG_STATUS=./config.status} - -echo creating $CONFIG_STATUS -rm -f $CONFIG_STATUS -cat > $CONFIG_STATUS <<EOF -#! /bin/sh -# Generated automatically by configure. -# Run this file to recreate the current configuration. -# This directory was configured as follows, -# on host `(hostname || uname -n) 2>/dev/null | sed 1q`: -# -# $0 $ac_configure_args -# -# Compiler output produced by configure, useful for debugging -# configure, is in ./config.log if it exists. - -ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]" -for ac_option -do - case "\$ac_option" in - -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) - echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" - exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; - -version | --version | --versio | --versi | --vers | --ver | --ve | --v) - echo "$CONFIG_STATUS generated by autoconf version 2.12.1" - exit 0 ;; - -help | --help | --hel | --he | --h) - echo "\$ac_cs_usage"; exit 0 ;; - *) echo "\$ac_cs_usage"; exit 1 ;; - esac -done - -ac_given_srcdir=$srcdir -ac_given_INSTALL="$INSTALL" - -trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 -EOF -cat >> $CONFIG_STATUS <<EOF - -# Protect against being on the right side of a sed subst in config.status. -sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; - s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF -$ac_vpsub -$extrasub -s%@SHELL@%$SHELL%g -s%@CFLAGS@%$CFLAGS%g -s%@CPPFLAGS@%$CPPFLAGS%g -s%@CXXFLAGS@%$CXXFLAGS%g -s%@DEFS@%$DEFS%g -s%@LDFLAGS@%$LDFLAGS%g -s%@LIBS@%$LIBS%g -s%@exec_prefix@%$exec_prefix%g -s%@prefix@%$prefix%g -s%@program_transform_name@%$program_transform_name%g -s%@bindir@%$bindir%g -s%@sbindir@%$sbindir%g -s%@libexecdir@%$libexecdir%g -s%@datadir@%$datadir%g -s%@sysconfdir@%$sysconfdir%g -s%@sharedstatedir@%$sharedstatedir%g -s%@localstatedir@%$localstatedir%g -s%@libdir@%$libdir%g -s%@includedir@%$includedir%g -s%@oldincludedir@%$oldincludedir%g -s%@infodir@%$infodir%g -s%@mandir@%$mandir%g -s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g -s%@INSTALL_DATA@%$INSTALL_DATA%g - -CEOF -EOF - -cat >> $CONFIG_STATUS <<\EOF - -# Split the substitutions into bite-sized pieces for seds with -# small command number limits, like on Digital OSF/1 and HP-UX. -ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script. -ac_file=1 # Number of current file. -ac_beg=1 # First line for current file. -ac_end=$ac_max_sed_cmds # Line after last line for current file. -ac_more_lines=: -ac_sed_cmds="" -while $ac_more_lines; do - if test $ac_beg -gt 1; then - sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file - else - sed "${ac_end}q" conftest.subs > conftest.s$ac_file - fi - if test ! -s conftest.s$ac_file; then - ac_more_lines=false - rm -f conftest.s$ac_file - else - if test -z "$ac_sed_cmds"; then - ac_sed_cmds="sed -f conftest.s$ac_file" - else - ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file" - fi - ac_file=`expr $ac_file + 1` - ac_beg=$ac_end - ac_end=`expr $ac_end + $ac_max_sed_cmds` - fi -done -if test -z "$ac_sed_cmds"; then - ac_sed_cmds=cat -fi -EOF - -cat >> $CONFIG_STATUS <<EOF - -CONFIG_FILES=\${CONFIG_FILES-"Makefile"} -EOF -cat >> $CONFIG_STATUS <<\EOF -for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then - # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in". - case "$ac_file" in - *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'` - ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; - *) ac_file_in="${ac_file}.in" ;; - esac - - # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories. - - # Remove last slash and all that follows it. Not all systems have dirname. - ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` - if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then - # The file is in a subdirectory. - test ! -d "$ac_dir" && mkdir "$ac_dir" - ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`" - # A "../" for each directory in $ac_dir_suffix. - ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` - else - ac_dir_suffix= ac_dots= - fi - - case "$ac_given_srcdir" in - .) srcdir=. - if test -z "$ac_dots"; then top_srcdir=. - else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; - /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; - *) # Relative path. - srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" - top_srcdir="$ac_dots$ac_given_srcdir" ;; - esac - - case "$ac_given_INSTALL" in - [/$]*) INSTALL="$ac_given_INSTALL" ;; - *) INSTALL="$ac_dots$ac_given_INSTALL" ;; - esac - - echo creating "$ac_file" - rm -f "$ac_file" - configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." - case "$ac_file" in - *Makefile*) ac_comsub="1i\\ -# $configure_input" ;; - *) ac_comsub= ;; - esac - - ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"` - sed -e "$ac_comsub -s%@configure_input@%$configure_input%g -s%@srcdir@%$srcdir%g -s%@top_srcdir@%$top_srcdir%g -s%@INSTALL@%$INSTALL%g -" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file -fi; done -rm -f conftest.s* - -EOF -cat >> $CONFIG_STATUS <<EOF - -EOF -cat >> $CONFIG_STATUS <<\EOF - -exit 0 -EOF -chmod +x $CONFIG_STATUS -rm -fr confdefs* $ac_clean_files -test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1 - diff --git a/etc/configure.in b/etc/configure.in deleted file mode 100644 index b78506800..000000000 --- a/etc/configure.in +++ /dev/null @@ -1,7 +0,0 @@ -dnl Process this file with autoconf to produce a configure script. -AC_PREREQ(2.5) -AC_INIT(Makefile.in) - -AC_PROG_INSTALL - -AC_OUTPUT(Makefile) diff --git a/etc/configure.texi b/etc/configure.texi deleted file mode 100644 index 91401671f..000000000 --- a/etc/configure.texi +++ /dev/null @@ -1,2644 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename configure.info -@settitle The GNU configure and build system -@setchapternewpage off -@c %**end of header - -@dircategory GNU admin -@direntry -* configure: (configure). The GNU configure and build system -@end direntry - -@ifinfo -This file documents the GNU configure and build system. - -Copyright (C) 1998 Cygnus Solutions. - -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 - - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Foundation. -@end ifinfo - -@titlepage -@title The GNU configure and build system -@author Ian Lance Taylor - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1998 Cygnus Solutions - -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 -@top GNU configure and build system - -The GNU configure and build system. - -@menu -* Introduction:: Introduction. -* Getting Started:: Getting Started. -* Files:: Files. -* Configuration Names:: Configuration Names. -* Cross Compilation Tools:: Cross Compilation Tools. -* Canadian Cross:: Canadian Cross. -* Cygnus Configure:: Cygnus Configure. -* Multilibs:: Multilibs. -* FAQ:: Frequently Asked Questions. -* Index:: Index. -@end menu - -@end ifinfo - -@node Introduction -@chapter Introduction - -This document describes the GNU configure and build systems. It -describes how autoconf, automake, libtool, and make fit together. It -also includes a discussion of the older Cygnus configure system. - -This document does not describe in detail how to use each of the tools; -see the respective manuals for that. Instead, it describes which files -the developer must write, which files are machine generated and how they -are generated, and where certain common problems should be addressed. - -@ifnothtml -This document draws on several sources, including the autoconf manual by -David MacKenzie (@pxref{Top, , autoconf overview, autoconf, Autoconf}), -the automake manual by David MacKenzie and Tom Tromey (@pxref{Top, , -automake overview, automake, GNU Automake}), the libtool manual by -Gordon Matzigkeit (@pxref{Top, , libtool overview, libtool, GNU -libtool}), and the Cygnus configure manual by K. Richard Pixley. -@end ifnothtml -@ifhtml -This document draws on several sources, including -@uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_toc.html, the -autoconf manual} by David MacKenzie, -@uref{http://www.delorie.com/gnu/docs/automake/automake_toc.html, the -automake manual} by David MacKenzie and Tom Tromey, -@uref{http://www.delorie.com/gnu/docs/libtool/libtool_toc.html, the -libtool manual} by Gordon Matzigkeit, and the Cygnus configure manual by -K. Richard Pixley. -@end ifhtml - -@menu -* Goals:: Goals. -* Tools:: The tools. -* History:: History. -* Building:: Building. -@end menu - -@node Goals -@section Goals -@cindex goals - -The GNU configure and build system has two main goals. - -The first is to simplify the development of portable programs. The -system permits the developer to concentrate on writing the program, -simplifying many details of portability across Unix and even Windows -systems, and permitting the developer to describe how to build the -program using simple rules rather than complex Makefiles. - -The second is to simplify the building of programs distributed as source -code. All programs are built using a simple, standardized, two step -process. The program builder need not install any special tools in -order to build the program. - -@node Tools -@section Tools - -The GNU configure and build system is comprised of several different -tools. Program developers must build and install all of these tools. - -People who just want to build programs from distributed sources normally -do not need any special tools beyond a Unix shell, a make program, and a -C compiler. - -@table @asis -@item autoconf -provides a general portability framework, based on testing the features -of the host system at build time. -@item automake -a system for describing how to build a program, permitting the developer -to write a simplified @file{Makefile}. -@item libtool -a standardized approach to building shared libraries. -@item gettext -provides a framework for translation of text messages into other -languages; not really discussed in this document. -@item m4 -autoconf requires the GNU version of m4; the standard Unix m4 does not -suffice. -@item perl -automake requires perl. -@end table - -@node History -@section History -@cindex history - -This is a very brief and probably inaccurate history. - -As the number of Unix variants increased during the 1980s, it became -harder to write programs which could run on all variants. While it was -often possible to use @code{#ifdef} to identify particular systems, -developers frequently did not have access to every system, and the -characteristics of some systems changed from version to version. - -By 1992, at least three different approaches had been developed: -@itemize @bullet -@item -The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael -Manfredi. -@item -The Cygnus configure script, by K. Richard Pixley, and the gcc configure -script, by Richard Stallman. These use essentially the same approach, -and the developers communicated regularly. -@item -The autoconf program, by David MacKenzie. -@end itemize - -The Metaconfig program is still used for Perl and a few other programs. -It is part of the Dist package. I do not know if it is being developed. - -In 1994, David MacKenzie and others modified autoconf to incorporate all -the features of Cygnus configure. Since then, there has been a slow but -steady conversion of GNU programs from Cygnus configure to autoconf. gcc -has been converted, eliminating the gcc configure script. - -GNU autoconf was regularly maintained until late 1996. As of this -writing in June, 1998, it has no public maintainer. - -Most programs are built using the make program, which requires the -developer to write Makefiles describing how to build the programs. -Since most programs are built in pretty much the same way, this led to a -lot of duplication. - -The X Window system is built using the imake tool, which uses a database -of rules to eliminate the duplication. However, building a tool which -was developed using imake requires that the builder have imake -installed, violating one of the goals of the GNU system. - -The new BSD make provides a standard library of Makefile fragments, -which permits developers to write very simple Makefiles. However, this -requires that the builder install the new BSD make program. - -In 1994, David MacKenzie wrote the first version of automake, which -permitted writing a simple build description which was converted into a -Makefile which could be used by the standard make program. In 1995, Tom -Tromey completely rewrote automake in Perl, and he continues to enhance -it. - -Various free packages built libraries, and by around 1995 several -included support to build shared libraries on various platforms. -However, there was no consistent approach. In early 1996, Gordon -Matzigkeit began working on libtool, which provided a standardized -approach to building shared libraries. This was integrated into -automake from the start. - -The development of automake and libtool was driven by the GNITS project, -a group of GNU maintainers who designed standardized tools to help meet -the GNU coding standards. - -@node Building -@section Building - -Most readers of this document should already know how to build a tool by -running @samp{configure} and @samp{make}. This section may serve as a -quick introduction or reminder. - -Building a tool is normally as simple as running @samp{configure} -followed by @samp{make}. You should normally run @samp{configure} from -an empty directory, using some path to refer to the @samp{configure} -script in the source directory. The directory in which you run -@samp{configure} is called the @dfn{object directory}. - -In order to use a object directory which is different from the source -directory, you must be using the GNU version of @samp{make}, which has -the required @samp{VPATH} support. Despite this restriction, using a -different object directory is highly recommended: -@itemize @bullet -@item -It keeps the files generated during the build from cluttering up your -sources. -@item -It permits you to remove the built files by simply removing the entire -build directory. -@item -It permits you to build from the same sources with several sets of -configure options simultaneously. -@end itemize - -If you don't have GNU @samp{make}, you will have to run @samp{configure} -in the source directory. All GNU packages should support this; in -particular, GNU packages should not assume the presence of GNU -@samp{make}. - -After running @samp{configure}, you can build the tools by running -@samp{make}. - -To install the tools, run @samp{make install}. Installing the tools -will copy the programs and any required support files to the -@dfn{installation directory}. The location of the installation -directory is controlled by @samp{configure} options, as described below. - -In the Cygnus tree at present, the info files are built and installed as -a separate step. To build them, run @samp{make info}. To install them, -run @samp{make install-info}. - -All @samp{configure} scripts support a wide variety of options. The -most interesting ones are @samp{--with} and @samp{--enable} options -which are generally specific to particular tools. You can usually use -the @samp{--help} option to get a list of interesting options for a -particular configure script. - -The only generic options you are likely to use are the @samp{--prefix} -and @samp{--exec-prefix} options. These options are used to specify the -installation directory. - -The directory named by the @samp{--prefix} option will hold machine -independent files such as info files. - -The directory named by the @samp{--exec-prefix} option, which is -normally a subdirectory of the @samp{--prefix} directory, will hold -machine dependent files such as executables. - -The default for @samp{--prefix} is @file{/usr/local}. The default for -@samp{--exec-prefix} is the value used for @samp{--prefix}. - -The convention used in Cygnus releases is to use a @samp{--prefix} -option of @file{/usr/cygnus/@var{release}}, where @var{release} is the -name of the release, and to use a @samp{--exec-prefix} option of -@file{/usr/cygnus/@var{release}/H-@var{host}}, where @var{host} is the -configuration name of the host system (@pxref{Configuration Names}). - -Do not use either the source or the object directory as the installation -directory. That will just lead to confusion. - -@node Getting Started -@chapter Getting Started - -To start using the GNU configure and build system with your software -package, you must write three files, and you must run some tools to -manually generate additional files. - -@menu -* Write configure.in:: Write configure.in. -* Write Makefile.am:: Write Makefile.am. -* Write acconfig.h:: Write acconfig.h. -* Generate files:: Generate files. -* Getting Started Example:: Example. -@end menu - -@node Write configure.in -@section Write configure.in -@cindex @file{configure.in}, writing - -You must first write the file @file{configure.in}. This is an autoconf -input file, and the autoconf manual describes in detail what this file -should look like. - -You will write tests in your @file{configure.in} file to check for -conditions that may change from one system to another, such as the -presence of particular header files or functions. - -For example, not all systems support the @samp{gettimeofday} function. -If you want to use the @samp{gettimeofday} function when it is -available, and to use some other function when it is not, you would -check for this by putting @samp{AC_CHECK_FUNCS(gettimeofday)} in -@file{configure.in}. - -When the configure script is run at build time, this will arrange to -define the preprocessor macro @samp{HAVE_GETTIMEOFDAY} to the value 1 if -the @samp{gettimeofday} function is available, and to not define the -macro at all if the function is not available. Your code can then use -@samp{#ifdef} to test whether it is safe to call @samp{gettimeofday}. - -If you have an existing body of code, the @samp{autoscan} program may -help identify potential portability problems, and hence configure tests -that you will want to use. -@ifnothtml -@xref{Invoking autoscan, , , autoconf, the autoconf manual}. -@end ifnothtml -@ifhtml -See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_4.html, the -autoscan documentation}. -@end ifhtml - -Another handy tool for an existing body of code is @samp{ifnames}. This -will show you all the preprocessor conditionals that the code already -uses. -@ifnothtml -@xref{Invoking ifnames, , , autoconf, the autoconf manual}. -@end ifnothtml -@ifhtml -See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_5.html, the -ifnames documentation}. -@end ifhtml - -Besides the portability tests which are specific to your particular -package, every @file{configure.in} file should contain the following -macros. - -@table @samp -@item AC_INIT -@cindex @samp{AC_INIT} -This macro takes a single argument, which is the name of a file in your -package. For example, @samp{AC_INIT(foo.c)}. - -@item AC_PREREQ(@var{VERSION}) -@cindex @samp{AC_PREREQ} -This macro is optional. It may be used to indicate the version of -@samp{autoconf} that you are using. This will prevent users from -running an earlier version of @samp{autoconf} and perhaps getting an -invalid @file{configure} script. For example, @samp{AC_PREREQ(2.12)}. - -@item AM_INIT_AUTOMAKE -@cindex @samp{AM_INIT_AUTOMAKE} -This macro takes two arguments: the name of the package, and a version -number. For example, @samp{AM_INIT_AUTOMAKE(foo, 1.0)}. (This macro is -not needed if you are not using automake). - -@item AM_CONFIG_HEADER -@cindex @samp{AM_CONFIG_HEADER} -This macro names the header file which will hold the preprocessor macro -definitions at run time. Normally this should be @file{config.h}. Your -sources would then use @samp{#include "config.h"} to include it. - -This macro may optionally name the input file for that header file; by -default, this is @file{config.h.in}, but that file name works poorly on -DOS filesystems. Therefore, it is often better to name it explicitly as -@file{config.in}. - -This is what you should normally put in @file{configure.in}: -@example -AM_CONFIG_HEADER(config.h:config.in) -@end example - -@cindex @samp{AC_CONFIG_HEADER} -(If you are not using automake, use @samp{AC_CONFIG_HEADER} rather than -@samp{AM_CONFIG_HEADER}). - -@item AM_MAINTAINER_MODE -@cindex @samp{AM_MAINTAINER_MODE} -This macro always appears in Cygnus configure scripts. Other programs -may or may not use it. - -If this macro is used, the @samp{--enable-maintainer-mode} option is -required to enable automatic rebuilding of generated files used by the -configure system. This of course requires that developers be aware of, -and use, that option. - -If this macro is not used, then the generated files will always be -rebuilt automatically. This will cause problems if the wrong versions -of autoconf, automake, or others are in the builder's @samp{PATH}. - -(If you are not using automake, you do not need to use this macro). - -@item AC_EXEEXT -@cindex @samp{AC_EXEEXT} -@cindex @samp{AM_EXEEXT} -Either this macro or @samp{AM_EXEEXT} always appears in Cygnus configure -files. Other programs may or may not use one of them. - -This macro looks for the executable suffix used on the host system. On -Unix systems, this is the empty string. On Windows systems, this is -@samp{.exe}. This macro directs automake to use the executable suffix -as appropriate when creating programs. This macro does not take any -arguments. - -The @samp{AC_EXEEXT} form is new, and is part of a Cygnus patch to -autoconf to support compiling with Visual C++. Older programs use -@samp{AM_EXEEXT} instead. - -(Programs which do not use automake use neither @samp{AC_EXEEXT} nor -@samp{AM_EXEEXT}). - -@item AC_PROG_CC -@cindex @samp{AC_PROG_CC} -If you are writing C code, you will normally want to use this macro. It -locates the C compiler to use. It does not take any arguments. - -However, if this @file{configure.in} file is for a library which is to -be compiled by a cross compiler which may not fully work, then you will -not want to use @samp{AC_PROG_CC}. Instead, you will want to use a -variant which does not call the macro @samp{AC_PROG_CC_WORKS}. Examples -can be found in various @file{configure.in} files for libraries that are -compiled with cross compilers, such as libiberty or libgloss. This is -essentially a bug in autoconf, and there will probably be a better -workaround at some point. - -@item AC_PROG_CXX -@cindex @samp{AC_PROG_CXX} -If you are writing C++ code, you will want to use this macro. It -locates the C++ compiler to use. It does not take any arguments. The -same cross compiler comments apply as for @samp{AC_PROG_CC}. - -@item AM_PROG_LIBTOOL -@cindex @samp{AM_PROG_LIBTOOL} -If you want to build libraries, and you want to permit them to be -shared, or you want to link against libraries which were built using -libtool, then you will need this macro. This macro is required in order -to use libtool. - -@cindex @samp{AM_DISABLE_SHARED} -By default, this will cause all libraries to be built as shared -libraries. To prevent this--to change the default--use -@samp{AM_DISABLE_SHARED} before @samp{AM_PROG_LIBTOOL}. The configure -options @samp{--enable-shared} and @samp{--disable-shared} may be used -to override the default at build time. - -@item AC_DEFINE(_GNU_SOURCE) -@cindex @samp{_GNU_SOURCE} -GNU packages should normally include this line before any other feature -tests. This defines the macro @samp{_GNU_SOURCE} when compiling, which -directs the libc header files to provide the standard GNU system -interfaces including all GNU extensions. If this macro is not defined, -certain GNU extensions may not be available. - -@item AC_OUTPUT -@cindex @samp{AC_OUTPUT} -This macro takes a list of file names which the configure process should -produce. This is normally a list of one or more @file{Makefile} files -in different directories. If your package lives entirely in a single -directory, you would use simply @samp{AC_OUTPUT(Makefile)}. If you also -have, for example, a @file{lib} subdirectory, you would use -@samp{AC_OUTPUT(Makefile lib/Makefile)}. -@end table - -If you want to use locally defined macros in your @file{configure.in} -file, then you will need to write a @file{acinclude.m4} file which -defines them (if not using automake, this file is called -@file{aclocal.m4}). Alternatively, you can put separate macros in an -@file{m4} subdirectory, and put @samp{ACLOCAL_AMFLAGS = -I m4} in your -@file{Makefile.am} file so that the @samp{aclocal} program will be able -to find them. - -The different macro prefixes indicate which tool defines the macro. -Macros which start with @samp{AC_} are part of autoconf. Macros which -start with @samp{AM_} are provided by automake or libtool. - -@node Write Makefile.am -@section Write Makefile.am -@cindex @file{Makefile.am}, writing - -You must write the file @file{Makefile.am}. This is an automake input -file, and the automake manual describes in detail what this file should -look like. - -The automake commands in @file{Makefile.am} mostly look like variable -assignments in a @file{Makefile}. automake recognizes special variable -names, and automatically add make rules to the output as needed. - -There will be one @file{Makefile.am} file for each directory in your -package. For each directory with subdirectories, the @file{Makefile.am} -file should contain the line -@smallexample -SUBDIRS = @var{dir} @var{dir} @dots{} -@end smallexample -@noindent -where each @var{dir} is the name of a subdirectory. - -For each @file{Makefile.am}, there should be a corresponding -@file{Makefile} in the @samp{AC_OUTPUT} macro in @file{configure.in}. - -Every @file{Makefile.am} written at Cygnus should contain the line -@smallexample -AUTOMAKE_OPTIONS = cygnus -@end smallexample -@noindent -This puts automake into Cygnus mode. See the automake manual for -details. - -You may to include the version number of @samp{automake} that you are -using on the @samp{AUTOMAKE_OPTIONS} line. For example, -@smallexample -AUTOMAKE_OPTIONS = cygnus 1.3 -@end smallexample -@noindent -This will prevent users from running an earlier version of -@samp{automake} and perhaps getting an invalid @file{Makefile.in}. - -If your package builds a program, then in the directory where that -program is built you will normally want a line like -@smallexample -bin_PROGRAMS = @var{program} -@end smallexample -@noindent -where @var{program} is the name of the program. You will then want a -line like -@smallexample -@var{program}_SOURCES = @var{file} @var{file} @dots{} -@end smallexample -@noindent -where each @var{file} is the name of a source file to link into the -program (e.g., @samp{foo.c}). - -If your package builds a library, and you do not want the library to -ever be built as a shared library, then in the directory where that -library is built you will normally want a line like -@smallexample -lib_LIBRARIES = lib@var{name}.a -@end smallexample -@noindent -where @samp{lib@var{name}.a} is the name of the library. You will then -want a line like -@smallexample -lib@var{name}_a_SOURCES = @var{file} @var{file} @dots{} -@end smallexample -@noindent -where each @var{file} is the name of a source file to add to the -library. - -If your package builds a library, and you want to permit building the -library as a shared library, then in the directory where that library is -built you will normally want a line like -@smallexample -lib_LTLIBRARIES = lib@var{name}.la -@end smallexample -The use of @samp{LTLIBRARIES}, and the @samp{.la} extension, indicate a -library to be built using libtool. As usual, you will then want a line -like -@smallexample -lib@var{name}_la_SOURCES = @var{file} @var{file} @dots{} -@end smallexample - -The strings @samp{bin} and @samp{lib} that appear above in -@samp{bin_PROGRAMS} and @samp{lib_LIBRARIES} are not arbitrary. They -refer to particular directories, which may be set by the @samp{--bindir} -and @samp{--libdir} options to @file{configure}. If those options are -not used, the default values are based on the @samp{--prefix} or -@samp{--exec-prefix} options to @file{configure}. It is possible to use -other names if the program or library should be installed in some other -directory. - -The @file{Makefile.am} file may also contain almost anything that may -appear in a normal @file{Makefile}. automake also supports many other -special variables, as well as conditionals. - -See the automake manual for more information. - -@node Write acconfig.h -@section Write acconfig.h -@cindex @file{acconfig.h}, writing - -If you are generating a portability header file, (i.e., you are using -@samp{AM_CONFIG_HEADER} in @file{configure.in}), then you will have to -write a @file{acconfig.h} file. It will have to contain the following -lines. - -@smallexample -/* Name of package. */ -#undef PACKAGE - -/* Version of package. */ -#undef VERSION -@end smallexample - -This requirement is really a bug in the system, and the requirement may -be eliminated at some later date. - -The @file{acconfig.h} file will also similar comment and @samp{#undef} -lines for any unusual macros in the @file{configure.in} file, including -any macro which appears in a @samp{AC_DEFINE} macro. - -In particular, if you are writing a GNU package and therefore include -@samp{AC_DEFINE(_GNU_SOURCE)} in @file{configure.in} as suggested above, -you will need lines like this in @file{acconfig.h}: -@smallexample -/* Enable GNU extensions. */ -#undef _GNU_SOURCE -@end smallexample - -Normally the @samp{autoheader} program will inform you of any such -requirements by printing an error message when it is run. However, if -you do anything particular odd in your @file{configure.in} file, you -will have to make sure that the right entries appear in -@file{acconfig.h}, since otherwise the results of the tests may not be -available in the @file{config.h} file which your code will use. - -(Thee @samp{PACKAGE} and @samp{VERSION} lines are not required if you -are not using automake, and in that case you may not need a -@file{acconfig.h} file at all). - -@node Generate files -@section Generate files - -Once you have written @file{configure.in}, @file{Makefile.am}, -@file{acconfig.h}, and possibly @file{acinclude.m4}, you must use -autoconf and automake programs to produce the first versions of the -generated files. This is done by executing the following sequence of -commands. - -@smallexample -aclocal -autoconf -autoheader -automake -@end smallexample - -The @samp{aclocal} and @samp{automake} commands are part of the automake -package, and the @samp{autoconf} and @samp{autoheader} commands are part -of the autoconf package. - -If you are using a @file{m4} subdirectory for your macros, you will need -to use the @samp{-I m4} option when you run @samp{aclocal}. - -If you are not using the Cygnus tree, use the @samp{-a} option when -running @samp{automake} command in order to copy the required support -files into your source directory. - -If you are using libtool, you must build and install the libtool package -with the same @samp{--prefix} and @samp{--exec-prefix} options as you -used with the autoconf and automake packages. You must do this before -running any of the above commands. If you are not using the Cygnus -tree, you will need to run the @samp{libtoolize} program to copy the -libtool support files into your directory. - -Once you have managed to run these commands without getting any errors, -you should create a new empty directory, and run the @samp{configure} -script which will have been created by @samp{autoconf} with the -@samp{--enable-maintainer-mode} option. This will give you a set of -Makefiles which will include rules to automatically rebuild all the -generated files. - -After doing that, whenever you have changed some of the input files and -want to regenerated the other files, go to your object directory and run -@samp{make}. Doing this is more reliable than trying to rebuild the -files manually, because there are complex order dependencies and it is -easy to forget something. - -@node Getting Started Example -@section Example - -Let's consider a trivial example. - -Suppose we want to write a simple version of @samp{touch}. Our program, -which we will call @samp{poke}, will take a single file name argument, -and use the @samp{utime} system call to set the modification and access -times of the file to the current time. We want this program to be -highly portable. - -We'll first see what this looks like without using autoconf and -automake, and then see what it looks like with them. - -@menu -* Getting Started Example 1:: First Try. -* Getting Started Example 2:: Second Try. -* Getting Started Example 3:: Third Try. -* Generate Files in Example:: Generate Files. -@end menu - -@node Getting Started Example 1 -@subsection First Try - -Here is our first try at @samp{poke.c}. Note that we've written it -without ANSI/ISO C prototypes, since we want it to be highly portable. - -@example -#include <stdio.h> -#include <stdlib.h> -#include <sys/types.h> -#include <utime.h> - -int -main (argc, argv) - int argc; - char **argv; -@{ - if (argc != 2) - @{ - fprintf (stderr, "Usage: poke file\n"); - exit (1); - @} - - if (utime (argv[1], NULL) < 0) - @{ - perror ("utime"); - exit (1); - @} - - exit (0); -@} -@end example - -We also write a simple @file{Makefile}. - -@example -CC = gcc -CFLAGS = -g -O2 - -all: poke - -poke: poke.o - $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o -@end example - -So far, so good. - -Unfortunately, there are a few problems. - -On older Unix systems derived from BSD 4.3, the @samp{utime} system call -does not accept a second argument of @samp{NULL}. On those systems, we -need to pass a pointer to @samp{struct utimbuf} structure. -Unfortunately, even older systems don't define that structure; on those -systems, we need to pass an array of two @samp{long} values. - -The header file @file{stdlib.h} was invented by ANSI C, and older -systems don't have a copy. We included it above to get a declaration of -@samp{exit}. - -We can find some of these portability problems by running -@samp{autoscan}, which will create a @file{configure.scan} file which we -can use as a prototype for our @file{configure.in} file. I won't show -the output, but it will notice the potential problems with @samp{utime} -and @file{stdlib.h}. - -In our @file{Makefile}, we don't provide any way to install the program. -This doesn't matter much for such a simple example, but a real program -will need an @samp{install} target. For that matter, we will also want -a @samp{clean} target. - -@node Getting Started Example 2 -@subsection Second Try - -Here is our second try at this program. - -We modify @file{poke.c} to use preprocessor macros to control what -features are available. (I've cheated a bit by using the same macro -names which autoconf will use). - -@example -#include <stdio.h> - -#ifdef STDC_HEADERS -#include <stdlib.h> -#endif - -#include <sys/types.h> - -#ifdef HAVE_UTIME_H -#include <utime.h> -#endif - -#ifndef HAVE_UTIME_NULL - -#include <time.h> - -#ifndef HAVE_STRUCT_UTIMBUF - -struct utimbuf -@{ - long actime; - long modtime; -@}; - -#endif - -static int -utime_now (file) - char *file; -@{ - struct utimbuf now; - - now.actime = now.modtime = time (NULL); - return utime (file, &now); -@} - -#define utime(f, p) utime_now (f) - -#endif /* HAVE_UTIME_NULL */ - -int -main (argc, argv) - int argc; - char **argv; -@{ - if (argc != 2) - @{ - fprintf (stderr, "Usage: poke file\n"); - exit (1); - @} - - if (utime (argv[1], NULL) < 0) - @{ - perror ("utime"); - exit (1); - @} - - exit (0); -@} -@end example - -Here is the associated @file{Makefile}. We've added support for the -preprocessor flags we use. We've also added @samp{install} and -@samp{clean} targets. - -@example -# Set this to your installation directory. -bindir = /usr/local/bin - -# Uncomment this if you have the standard ANSI/ISO C header files. -# STDC_HDRS = -DSTDC_HEADERS - -# Uncomment this if you have utime.h. -# UTIME_H = -DHAVE_UTIME_H - -# Uncomment this if utime (FILE, NULL) works on your system. -# UTIME_NULL = -DHAVE_UTIME_NULL - -# Uncomment this if struct utimbuf is defined in utime.h. -# UTIMBUF = -DHAVE_STRUCT_UTIMBUF - -CC = gcc -CFLAGS = -g -O2 - -ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS) - -all: poke - -poke: poke.o - $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o - -.c.o: - $(CC) -c $(ALL_CFLAGS) poke.c - -install: poke - cp poke $(bindir)/poke - -clean: - rm poke poke.o -@end example - -Some problems with this approach should be clear. - -Users who want to compile poke will have to know how @samp{utime} works -on their systems, so that they can uncomment the @file{Makefile} -correctly. - -The installation is done using @samp{cp}, but many systems have an -@samp{install} program which may be used, and which supports optional -features such as stripping debugging information out of the installed -binary. - -The use of @file{Makefile} variables like @samp{CC}, @samp{CFLAGS} and -@samp{LDFLAGS} follows the requirements of the GNU standards. This is -convenient for all packages, since it reduces surprises for users. -However, it is easy to get the details wrong, and wind up with a -slightly nonstandard distribution. - -@node Getting Started Example 3 -@subsection Third Try - -For our third try at this program, we will write a @file{configure.in} -script to discover the configuration features on the host system, rather -than requiring the user to edit the @file{Makefile}. We will also write -a @file{Makefile.am} rather than a @file{Makefile}. - -The only change to @file{poke.c} is to add a line at the start of the -file: -@smallexample -#include "config.h" -@end smallexample - -The new @file{configure.in} file is as follows. - -@example -AC_INIT(poke.c) -AM_INIT_AUTOMAKE(poke, 1.0) -AM_CONFIG_HEADER(config.h:config.in) -AC_PROG_CC -AC_HEADER_STDC -AC_CHECK_HEADERS(utime.h) -AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF)) -AC_FUNC_UTIME_NULL -AC_OUTPUT(Makefile) -@end example - -The first four macros in this file, and the last one, were described -above; see @ref{Write configure.in}. If we omit these macros, then when -we run @samp{automake} we will get a reminder that we need them. - -The other macros are standard autoconf macros. - -@table @samp -@item AC_HEADER_STDC -Check for standard C headers. -@item AC_CHECK_HEADERS -Check whether a particular header file exists. -@item AC_EGREP_HEADER -Check for a particular string in a particular header file, in this case -checking for @samp{utimbuf} in @file{utime.h}. -@item AC_FUNC_UTIME_NULL -Check whether @samp{utime} accepts a NULL second argument to set the -file change time to the current time. -@end table - -See the autoconf manual for a more complete description. - -The new @file{Makefile.am} file is as follows. Note how simple this is -compared to our earlier @file{Makefile}. - -@example -bin_PROGRAMS = poke - -poke_SOURCES = poke.c -@end example - -This means that we should build a single program name @samp{poke}. It -should be installed in the binary directory, which we called -@samp{bindir} earlier. The program @samp{poke} is built from the source -file @file{poke.c}. - -We must also write a @file{acconfig.h} file. Besides @samp{PACKAGE} and -@samp{VERSION}, which must be mentioned for all packages which use -automake, we must include @samp{HAVE_STRUCT_UTIMBUF}, since we mentioned -it in an @samp{AC_DEFINE}. - -@example -/* Name of package. */ -#undef PACKAGE - -/* Version of package. */ -#undef VERSION - -/* Whether utime.h defines struct utimbuf. */ -#undef HAVE_STRUCT_UTIMBUF -@end example - -@node Generate Files in Example -@subsection Generate Files - -We must now generate the other files, using the following commands. - -@smallexample -aclocal -autoconf -autoheader -automake -@end smallexample - -When we run @samp{autoheader}, it will remind us of any macros we forgot -to add to @file{acconfig.h}. - -When we run @samp{automake}, it will want to add some files to our -distribution. It will add them automatically if we use the -@samp{--add-missing} option. - -By default, @samp{automake} will run in GNU mode, which means that it -will want us to create certain additional files; as of this writing, it -will want @file{NEWS}, @file{README}, @file{AUTHORS}, and -@file{ChangeLog}, all of which are files which should appear in a -standard GNU distribution. We can either add those files, or run -@samp{automake} with the @samp{--foreign} option. - -Running these tools will generate the following files, all of which are -described in the next chapter. - -@itemize @bullet -@item -@file{aclocal.m4} -@item -@file{configure} -@item -@file{config.in} -@item -@file{Makefile.in} -@item -@file{stamp-h.in} -@end itemize - -@node Files -@chapter Files - -As was seen in the previous chapter, the GNU configure and build system -uses a number of different files. The developer must write a few files. -The others are generated by various tools. - -The system is rather flexible, and can be used in many different ways. -In describing the files that it uses, I will describe the common case, -and mention some other cases that may arise. - -@menu -* Developer Files:: Developer Files. -* Build Files:: Build Files. -* Support Files:: Support Files. -@end menu - -@node Developer Files -@section Developer Files - -This section describes the files written or generated by the developer -of a package. - -@menu -* Developer Files Picture:: Developer Files Picture. -* Written Developer Files:: Written Developer Files. -* Generated Developer Files:: Generated Developer Files. -@end menu - -@node Developer Files Picture -@subsection Developer Files Picture - -Here is a picture of the files which are written by the developer, the -generated files which would be included with a complete source -distribution, and the tools which create those files. -@ifinfo -The file names are plain text and the tool names are enclosed by -@samp{*} characters -@end ifinfo -@ifnotinfo -The file names are in rectangles with square corners and the tool names -are in rectangles with rounded corners -@end ifnotinfo -(e.g., @samp{autoheader} is the name of a tool, not the name of a file). - -@image{configdev} - -@node Written Developer Files -@subsection Written Developer Files - -The following files would be written by the developer. - -@table @file -@item configure.in -@cindex @file{configure.in} -This is the configuration script. This script contains invocations of -autoconf macros. It may also contain ordinary shell script code. This -file will contain feature tests for portability issues. The last thing -in the file will normally be an @samp{AC_OUTPUT} macro listing which -files to create when the builder runs the configure script. This file -is always required when using the GNU configure system. @xref{Write -configure.in}. - -@item Makefile.am -@cindex @file{Makefile.am} -This is the automake input file. It describes how the code should be -built. It consists of definitions of automake variables. It may also -contain ordinary Makefile targets. This file is only needed when using -automake (newer tools normally use automake, but there are still older -tools which have not been converted, in which the developer writes -@file{Makefile.in} directly). @xref{Write Makefile.am}. - -@item acconfig.h -@cindex @file{acconfig.h} -When the configure script creates a portability header file, by using -@samp{AM_CONFIG_HEADER} (or, if not using automake, -@samp{AC_CONFIG_HEADER}), this file is used to describe macros which are -not recognized by the @samp{autoheader} command. This is normally a -fairly uninteresting file, consisting of a collection of @samp{#undef} -lines with comments. Normally any call to @samp{AC_DEFINE} in -@file{configure.in} will require a line in this file. @xref{Write -acconfig.h}. - -@item acinclude.m4 -@cindex @file{acinclude.m4} -This file is not always required. It defines local autoconf macros. -These macros may then be used in @file{configure.in}. If you don't need -any local autoconf macros, then you don't need this file at all. In -fact, in general, you never need local autoconf macros, since you can -put everything in @file{configure.in}, but sometimes a local macro is -convenient. - -Newer tools may omit @file{acinclude.m4}, and instead use a -subdirectory, typically named @file{m4}, and define -@samp{ACLOCAL_AMFLAGS = -I m4} in @file{Makefile.am} to force -@samp{aclocal} to look there for macro definitions. The macro -definitions are then placed in separate files in that directory. - -The @file{acinclude.m4} file is only used when using automake; in older -tools, the developer writes @file{aclocal.m4} directly, if it is needed. -@end table - -@node Generated Developer Files -@subsection Generated Developer Files - -The following files would be generated by the developer. - -When using automake, these files are normally not generated manually -after the first time. Instead, the generated @file{Makefile} contains -rules to automatically rebuild the files as required. When -@samp{AM_MAINTAINER_MODE} is used in @file{configure.in} (the normal -case in Cygnus code), the automatic rebuilding rules will only be -defined if you configure using the @samp{--enable-maintainer-mode} -option. - -When using automatic rebuilding, it is important to ensure that all the -various tools have been built and installed on your @samp{PATH}. Using -automatic rebuilding is highly recommended, so much so that I'm not -going to explain what you have to do if you don't use it. - -@table @file -@item configure -@cindex @file{configure} -This is the configure script which will be run when building the -package. This is generated by @samp{autoconf} from @file{configure.in} -and @file{aclocal.m4}. This is a shell script. - -@item Makefile.in -@cindex @file{Makefile.in} -This is the file which the configure script will turn into the -@file{Makefile} at build time. This file is generated by -@samp{automake} from @file{Makefile.am}. If you aren't using automake, -you must write this file yourself. This file is pretty much a normal -@file{Makefile}, with some configure substitutions for certain -variables. - -@item aclocal.m4 -@cindex @file{aclocal.m4} -This file is created by the @samp{aclocal} program, based on the -contents of @file{configure.in} and @file{acinclude.m4} (or, as noted in -the description of @file{acinclude.m4} above, on the contents of an -@file{m4} subdirectory). This file contains definitions of autoconf -macros which @samp{autoconf} will use when generating the file -@file{configure}. These autoconf macros may be defined by you in -@file{acinclude.m4} or they may be defined by other packages such as -automake, libtool or gettext. If you aren't using automake, you will -normally write this file yourself; in that case, if @file{configure.in} -uses only standard autoconf macros, this file will not be needed at all. - -@item config.in -@cindex @file{config.in} -@cindex @file{config.h.in} -This file is created by @samp{autoheader} based on @file{acconfig.h} and -@file{configure.in}. At build time, the configure script will define -some of the macros in it to create @file{config.h}, which may then be -included by your program. This permits your C code to use preprocessor -conditionals to change its behaviour based on the characteristics of the -host system. This file may also be called @file{config.h.in}. - -@item stamp.h-in -@cindex @file{stamp-h.in} -This rather uninteresting file, which I omitted from the picture, is -generated by @samp{automake}. It always contains the string -@samp{timestamp}. It is used as a timestamp file indicating whether -@file{config.in} is up to date. Using a timestamp file means that -@file{config.in} can be marked as up to date without actually changing -its modification time. This is useful since @file{config.in} depends -upon @file{configure.in}, but it is easy to change @file{configure.in} -in a way which does not affect @file{config.in}. -@end table - -@node Build Files -@section Build Files - -This section describes the files which are created at configure and -build time. These are the files which somebody who builds the package -will see. - -Of course, the developer will also build the package. The distinction -between developer files and build files is not that the developer does -not see the build files, but that somebody who only builds the package -does not have to worry about the developer files. - -@menu -* Build Files Picture:: Build Files Picture. -* Build Files Description:: Build Files Description. -@end menu - -@node Build Files Picture -@subsection Build Files Picture - -Here is a picture of the files which will be created at build time. -@file{config.status} is both a created file and a shell script which is -run to create other files, and the picture attempts to show that. - -@image{configbuild} - -@node Build Files Description -@subsection Build Files Description - -This is a description of the files which are created at build time. - -@table @file -@item config.status -@cindex @file{config.status} -The first step in building a package is to run the @file{configure} -script. The @file{configure} script will create the file -@file{config.status}, which is itself a shell script. When you first -run @file{configure}, it will automatically run @file{config.status}. -An @file{Makefile} derived from an automake generated @file{Makefile.in} -will contain rules to automatically run @file{config.status} again when -necessary to recreate certain files if their inputs change. - -@item Makefile -@cindex @file{Makefile} -This is the file which make will read to build the program. The -@file{config.status} script will transform @file{Makefile.in} into -@file{Makefile}. - -@item config.h -@cindex @file{config.h} -This file defines C preprocessor macros which C code can use to adjust -its behaviour on different systems. The @file{config.status} script -will transform @file{config.in} into @file{config.h}. - -@item config.cache -@cindex @file{config.cache} -This file did not fit neatly into the picture, and I omitted it. It is -used by the @file{configure} script to cache results between runs. This -can be an important speedup. If you modify @file{configure.in} in such -a way that the results of old tests should change (perhaps you have -added a new library to @samp{LDFLAGS}), then you will have to remove -@file{config.cache} to force the tests to be rerun. - -The autoconf manual explains how to set up a site specific cache file. -This can speed up running @file{configure} scripts on your system. - -@item stamp.h -@cindex @file{stamp-h} -This file, which I omitted from the picture, is similar to -@file{stamp-h.in}. It is used as a timestamp file indicating whether -@file{config.h} is up to date. This is useful since @file{config.h} -depends upon @file{config.status}, but it is easy for -@file{config.status} to change in a way which does not affect -@file{config.h}. -@end table - -@node Support Files -@section Support Files - -The GNU configure and build system requires several support files to be -included with your distribution. You do not normally need to concern -yourself with these. If you are using the Cygnus tree, most are already -present. Otherwise, they will be installed with your source by -@samp{automake} (with the @samp{--add-missing} option) and -@samp{libtoolize}. - -You don't have to put the support files in the top level directory. You -can put them in a subdirectory, and use the @samp{AC_CONFIG_AUX_DIR} -macro in @file{configure.in} to tell @samp{automake} and the -@file{configure} script where they are. - -In this section, I describe the support files, so that you can know what -they are and why they are there. - -@table @file -@item ABOUT-NLS -Added by automake if you are using gettext. This is a documentation -file about the gettext project. -@item ansi2knr.c -Used by an automake generated @file{Makefile} if you put @samp{ansi2knr} -in @samp{AUTOMAKE_OPTIONS} in @file{Makefile.am}. This permits -compiling ANSI C code with a K&R C compiler. -@item ansi2knr.1 -The man page which goes with @file{ansi2knr.c}. -@item config.guess -A shell script which determines the configuration name for the system on -which it is run. -@item config.sub -A shell script which canonicalizes a configuration name entered by a -user. -@item elisp-comp -Used to compile Emacs LISP files. -@item install-sh -A shell script which installs a program. This is used if the configure -script can not find an install binary. -@item ltconfig -Used by libtool. This is a shell script which configures libtool for -the particular system on which it is used. -@item ltmain.sh -Used by libtool. This is the actual libtool script which is used, after -it is configured by @file{ltconfig} to build a library. -@item mdate-sh -A shell script used by an automake generated @file{Makefile} to pretty -print the modification time of a file. This is used to maintain version -numbers for texinfo files. -@item missing -A shell script used if some tool is missing entirely. This is used by -an automake generated @file{Makefile} to avoid certain sorts of -timestamp problems. -@item mkinstalldirs -A shell script which creates a directory, including all parent -directories. This is used by an automake generated @file{Makefile} -during installation. -@item texinfo.tex -Required if you have any texinfo files. This is used when converting -Texinfo files into DVI using @samp{texi2dvi} and @TeX{}. -@item ylwrap -A shell script used by an automake generated @file{Makefile} to run -programs like @samp{bison}, @samp{yacc}, @samp{flex}, and @samp{lex}. -These programs default to producing output files with a fixed name, and -the @file{ylwrap} script runs them in a subdirectory to avoid file name -conflicts when using a parallel make program. -@end table - -@node Configuration Names -@chapter Configuration Names -@cindex configuration names -@cindex configuration triplets -@cindex triplets -@cindex host names -@cindex host triplets -@cindex canonical system names -@cindex system names -@cindex system types - -The GNU configure system names all systems using a @dfn{configuration -name}. All such names used to be triplets (they may now contain four -parts in certain cases), and the term @dfn{configuration triplet} is -still seen. - -@menu -* Configuration Name Definition:: Configuration Name Definition. -* Using Configuration Names:: Using Configuration Names. -@end menu - -@node Configuration Name Definition -@section Configuration Name Definition - -This is a string of the form -@var{cpu}-@var{manufacturer}-@var{operating_system}. In some cases, -this is extended to a four part form: -@var{cpu}-@var{manufacturer}-@var{kernel}-@var{operating_system}. - -When using a configuration name in a configure option, it is normally -not necessary to specify an entire name. In particular, the -@var{manufacturer} field is often omitted, leading to strings such as -@samp{i386-linux} or @samp{sparc-sunos}. The shell script -@file{config.sub} will translate these shortened strings into the -canonical form. autoconf will arrange for @file{config.sub} to be run -automatically when it is needed. - -The fields of a configuration name are as follows: - -@table @var -@item cpu -The type of processor. This is typically something like @samp{i386} or -@samp{sparc}. More specific variants are used as well, such as -@samp{mipsel} to indicate a little endian MIPS processor. -@item manufacturer -A somewhat freeform field which indicates the manufacturer of the -system. This is often simply @samp{unknown}. Other common strings are -@samp{pc} for an IBM PC compatible system, or the name of a workstation -vendor, such as @samp{sun}. -@item operating_system -The name of the operating system which is run on the system. This will -be something like @samp{solaris2.5} or @samp{irix6.3}. There is no -particular restriction on the version number, and strings like -@samp{aix4.1.4.0} are seen. For an embedded system, which has no -operating system, this field normally indicates the type of object file -format, such as @samp{elf} or @samp{coff}. -@item kernel -This is used mainly for GNU/Linux. A typical GNU/Linux configuration -name is @samp{i586-pc-linux-gnulibc1}. In this case the kernel, -@samp{linux}, is separated from the operating system, @samp{gnulibc1}. -@end table - -The shell script @file{config.guess} will normally print the correct -configuration name for the system on which it is run. It does by -running @samp{uname} and by examining other characteristics of the -system. - -Because @file{config.guess} can normally determine the configuration -name for a machine, it is normally only necessary to specify a -configuration name when building a cross-compiler or when building using -a cross-compiler. - -@node Using Configuration Names -@section Using Configuration Names - -A configure script will sometimes have to make a decision based on a -configuration name. You will need to do this if you have to compile -code differently based on something which can not be tested using a -standard autoconf feature test. - -It is normally better to test for particular features, rather than to -test for a particular system. This is because as Unix evolves, -different systems copy features from one another. Even if you need to -determine whether the feature is supported based on a configuration -name, you should define a macro which describes the feature, rather than -defining a macro which describes the particular system you are on. - -Testing for a particular system is normally done using a case statement -in @file{configure.in}. The case statement might look something like -the following, assuming that @samp{host} is a shell variable holding a -canonical configuration name (which will be the case if -@file{configure.in} uses the @samp{AC_CANONICAL_HOST} or -@samp{AC_CANONICAL_SYSTEM} macro). - -@smallexample -case "$@{host@}" in -i[3456]86-*-linux-gnu*) do something ;; -sparc*-sun-solaris2.[56789]*) do something ;; -sparc*-sun-solaris*) do something ;; -mips*-*-elf*) do something ;; -esac -@end smallexample - -It is particularly important to use @samp{*} after the operating system -field, in order to match the version number which will be generated by -@file{config.guess}. - -In most cases you must be careful to match a range of processor types. -For most processor families, a trailing @samp{*} suffices, as in -@samp{mips*} above. For the i386 family, something along the lines of -@samp{i[3456]86} suffices at present. For the m68k family, you will -need something like @samp{m68*}. Of course, if you do not need to match -on the processor, it is simpler to just replace the entire field by a -@samp{*}, as in @samp{*-*-irix*}. - -@node Cross Compilation Tools -@chapter Cross Compilation Tools -@cindex cross tools - -The GNU configure and build system can be used to build @dfn{cross -compilation} tools. A cross compilation tool is a tool which runs on -one system and produces code which runs on another system. - -@menu -* Cross Compilation Concepts:: Cross Compilation Concepts. -* Host and Target:: Host and Target. -* Using the Host Type:: Using the Host Type. -* Specifying the Target:: Specifying the Target. -* Using the Target Type:: Using the Target Type. -* Cross Tools in the Cygnus Tree:: Cross Tools in the Cygnus Tree -@end menu - -@node Cross Compilation Concepts -@section Cross Compilation Concepts - -@cindex cross compiler -A compiler which produces programs which run on a different system is a -cross compilation compiler, or simply a @dfn{cross compiler}. -Similarly, we speak of cross assemblers, cross linkers, etc. - -In the normal case, a compiler produces code which runs on the same -system as the one on which the compiler runs. When it is necessary to -distinguish this case from the cross compilation case, such a compiler -is called a @dfn{native compiler}. Similarly, we speak of native -assemblers, etc. - -Although the debugger is not strictly speaking a compilation tool, it is -nevertheless meaningful to speak of a cross debugger: a debugger which -is used to debug code which runs on another system. Everything that is -said below about configuring cross compilation tools applies to the -debugger as well. - -@node Host and Target -@section Host and Target -@cindex host system -@cindex target system - -When building cross compilation tools, there are two different systems -involved: the system on which the tools will run, and the system for -which the tools generate code. - -The system on which the tools will run is called the @dfn{host} system. - -The system for which the tools generate code is called the @dfn{target} -system. - -For example, suppose you have a compiler which runs on a GNU/Linux -system and generates ELF programs for a MIPS embedded system. In this -case the GNU/Linux system is the host, and the MIPS ELF system is the -target. Such a compiler could be called a GNU/Linux cross MIPS ELF -compiler, or, equivalently, a @samp{i386-linux-gnu} cross -@samp{mips-elf} compiler. - -Naturally, most programs are not cross compilation tools. For those -programs, it does not make sense to speak of a target. It only makes -sense to speak of a target for tools like @samp{gcc} or the -@samp{binutils} which actually produce running code. For example, it -does not make sense to speak of the target of a tool like @samp{bison} -or @samp{make}. - -Most cross compilation tools can also serve as native tools. For a -native compilation tool, it is still meaningful to speak of a target. -For a native tool, the target is the same as the host. For example, for -a GNU/Linux native compiler, the host is GNU/Linux, and the target is -also GNU/Linux. - -@node Using the Host Type -@section Using the Host Type - -In almost all cases the host system is the system on which you run the -@samp{configure} script, and on which you build the tools (for the case -when they differ, @pxref{Canadian Cross}). - -@cindex @samp{AC_CANONICAL_HOST} -If your configure script needs to know the configuration name of the -host system, and the package is not a cross compilation tool and -therefore does not have a target, put @samp{AC_CANONICAL_HOST} in -@file{configure.in}. This macro will arrange to define a few shell -variables when the @samp{configure} script is run. - -@table @samp -@item host -The canonical configuration name of the host. This will normally be -determined by running the @file{config.guess} shell script, although the -user is permitted to override this by using an explicit @samp{--host} -option. -@item host_alias -In the unusual case that the user used an explicit @samp{--host} option, -this will be the argument to @samp{--host}. In the normal case, this -will be the same as the @samp{host} variable. -@item host_cpu -@itemx host_vendor -@itemx host_os -The first three parts of the canonical configuration name. -@end table - -The shell variables may be used by putting shell code in -@file{configure.in}. For an example, see @ref{Using Configuration -Names}. - -@node Specifying the Target -@section Specifying the Target - -By default, the @samp{configure} script will assume that the target is -the same as the host. This is the more common case; for example, it -leads to a native compiler rather than a cross compiler. - -@cindex @samp{--target} option -@cindex target option -@cindex configure target -If you want to build a cross compilation tool, you must specify the -target explicitly by using the @samp{--target} option when you run -@samp{configure}. The argument to @samp{--target} is the configuration -name of the system for which you wish to generate code. -@xref{Configuration Names}. - -For example, to build tools which generate code for a MIPS ELF embedded -system, you would use @samp{--target mips-elf}. - -@node Using the Target Type -@section Using the Target Type - -@cindex @samp{AC_CANONICAL_SYSTEM} -When writing @file{configure.in} for a cross compilation tool, you will -need to use information about the target. To do this, put -@samp{AC_CANONICAL_SYSTEM} in @file{configure.in}. - -@samp{AC_CANONICAL_SYSTEM} will look for a @samp{--target} option and -canonicalize it using the @file{config.sub} shell script. It will also -run @samp{AC_CANONICAL_HOST} (@pxref{Using the Host Type}). - -The target type will be recorded in the following shell variables. Note -that the host versions of these variables will also be defined by -@samp{AC_CANONICAL_HOST}. - -@table @samp -@item target -The canonical configuration name of the target. -@item target_alias -The argument to the @samp{--target} option. If the user did not specify -a @samp{--target} option, this will be the same as @samp{host_alias}. -@item target_cpu -@itemx target_vendor -@itemx target_os -The first three parts of the canonical target configuration name. -@end table - -Note that if @samp{host} and @samp{target} are the same string, you can -assume a native configuration. If they are different, you can assume a -cross configuration. - -It is arguably possible for @samp{host} and @samp{target} to represent -the same system, but for the strings to not be identical. For example, -if @samp{config.guess} returns @samp{sparc-sun-sunos4.1.4}, and somebody -configures with @samp{--target sparc-sun-sunos4.1}, then the slight -differences between the two versions of SunOS may be unimportant for -your tool. However, in the general case it can be quite difficult to -determine whether the differences between two configuration names are -significant or not. Therefore, by convention, if the user specifies a -@samp{--target} option without specifying a @samp{--host} option, it is -assumed that the user wants to configure a cross compilation tool. - -The variables @samp{target} and @samp{target_alias} should be handled -differently. - -In general, whenever the user may actually see a string, -@samp{target_alias} should be used. This includes anything which may -appear in the file system, such as a directory name or part of a tool -name. It also includes any tool output, unless it is clearly labelled -as the canonical target configuration name. This permits the user to -use the @samp{--target} option to specify how the tool will appear to -the outside world. - -On the other hand, when checking for characteristics of the target -system, @samp{target} should be used. This is because a wide variety of -@samp{--target} options may map into the same canonical configuration -name. You should not attempt to duplicate the canonicalization done by -@samp{config.sub} in your own code. - -By convention, cross tools are installed with a prefix of the argument -used with the @samp{--target} option, also known as @samp{target_alias} -(@pxref{Using the Target Type}). If the user does not use the -@samp{--target} option, and thus is building a native tool, no prefix is -used. - -For example, if gcc is configured with @samp{--target mips-elf}, then -the installed binary will be named @samp{mips-elf-gcc}. If gcc is -configured without a @samp{--target} option, then the installed binary -will be named @samp{gcc}. - -The autoconf macro @samp{AC_ARG_PROGRAM} will handle this for you. If -you are using automake, no more need be done; the programs will -automatically be installed with the correct prefixes. Otherwise, see -the autoconf documentation for @samp{AC_ARG_PROGRAM}. - -@node Cross Tools in the Cygnus Tree -@section Cross Tools in the Cygnus Tree - -The Cygnus tree is used for various packages including gdb, the GNU -binutils, and egcs. It is also, of course, used for Cygnus releases. - -In the Cygnus tree, the top level @file{configure} script uses the old -Cygnus configure system, not autoconf. The top level @file{Makefile.in} -is written to build packages based on what is in the source tree, and -supports building a large number of tools in a single -@samp{configure}/@samp{make} step. - -The Cygnus tree may be configured with a @samp{--target} option. The -@samp{--target} option applies recursively to every subdirectory, and -permits building an entire set of cross tools at once. - -@menu -* Host and Target Libraries:: Host and Target Libraries. -* Target Library Configure Scripts:: Target Library Configure Scripts. -* Make Targets in Cygnus Tree:: Make Targets in Cygnus Tree. -* Target libiberty:: Target libiberty -@end menu - -@node Host and Target Libraries -@subsection Host and Target Libraries - -The Cygnus tree distinguishes host libraries from target libraries. - -Host libraries are built with the compiler used to build the programs -which run on the host, which is called the host compiler. This includes -libraries such as @samp{bfd} and @samp{tcl}. These libraries are built -with the host compiler, and are linked into programs like the binutils -or gcc which run on the host. - -Target libraries are built with the target compiler. If gcc is present -in the source tree, then the target compiler is the gcc that is built -using the host compiler. Target libraries are libraries such as -@samp{newlib} and @samp{libstdc++}. These libraries are not linked into -the host programs, but are instead made available for use with programs -built with the target compiler. - -For the rest of this section, assume that gcc is present in the source -tree, so that it will be used to build the target libraries. - -There is a complication here. The configure process needs to know which -compiler you are going to use to build a tool; otherwise, the feature -tests will not work correctly. The Cygnus tree handles this by not -configuring the target libraries until the target compiler is built. In -order to permit everything to build using a single -@samp{configure}/@samp{make}, the configuration of the target libraries -is actually triggered during the make step. - -When the target libraries are configured, the @samp{--target} option is -not used. Instead, the @samp{--host} option is used with the argument -of the @samp{--target} option for the overall configuration. If no -@samp{--target} option was used for the overall configuration, the -@samp{--host} option will be passed with the output of the -@file{config.guess} shell script. Any @samp{--build} option is passed -down unchanged. - -This translation of configuration options is done because since the -target libraries are compiled with the target compiler, they are being -built in order to run on the target of the overall configuration. By -the definition of host, this means that their host system is the same as -the target system of the overall configuration. - -The same process is used for both a native configuration and a cross -configuration. Even when using a native configuration, the target -libraries will be configured and built using the newly built compiler. -This is particularly important for the C++ libraries, since there is no -reason to assume that the C++ compiler used to build the host tools (if -there even is one) uses the same ABI as the g++ compiler which will be -used to build the target libraries. - -There is one difference between a native configuration and a cross -configuration. In a native configuration, the target libraries are -normally configured and built as siblings of the host tools. In a cross -configuration, the target libraries are normally built in a subdirectory -whose name is the argument to @samp{--target}. This is mainly for -historical reasons. - -To summarize, running @samp{configure} in the Cygnus tree configures all -the host libraries and tools, but does not configure any of the target -libraries. Running @samp{make} then does the following steps: - -@itemize @bullet -@item -Build the host libraries. -@item -Build the host programs, including gcc. Note that we call gcc both a -host program (since it runs on the host) and a target compiler (since it -generates code for the target). -@item -Using the newly built target compiler, configure the target libraries. -@item -Build the target libraries. -@end itemize - -The steps need not be done in precisely this order, since they are -actually controlled by @file{Makefile} targets. - -@node Target Library Configure Scripts -@subsection Target Library Configure Scripts - -There are a few things you must know in order to write a configure -script for a target library. This is just a quick sketch, and beginners -shouldn't worry if they don't follow everything here. - -The target libraries are configured and built using a newly built target -compiler. There may not be any startup files or libraries for this -target compiler. In fact, those files will probably be built as part of -some target library, which naturally means that they will not exist when -your target library is configured. - -This means that the configure script for a target library may not use -any test which requires doing a link. This unfortunately includes many -useful autoconf macros, such as @samp{AC_CHECK_FUNCS}. autoconf macros -which do a compile but not a link, such as @samp{AC_CHECK_HEADERS}, may -be used. - -This is a severe restriction, but normally not a fatal one, as target -libraries can often assume the presence of other target libraries, and -thus know which functions will be available. - -As of this writing, the autoconf macro @samp{AC_PROG_CC} does a link to -make sure that the compiler works. This may fail in a target library, -so target libraries must use a different set of macros to locate the -compiler. See the @file{configure.in} file in a directory like -@file{libiberty} or @file{libgloss} for an example. - -As noted in the previous section, target libraries are sometimes built -in directories which are siblings to the host tools, and are sometimes -built in a subdirectory. The @samp{--with-target-subdir} configure -option will be passed when the library is configured. Its value will be -an empty string if the target library is a sibling. Its value will be -the name of the subdirectory if the target library is in a subdirectory. - -If the overall build is not a native build (i.e., the overall configure -used the @samp{--target} option), then the library will be configured -with the @samp{--with-cross-host} option. The value of this option will -be the host system of the overall build. Recall that the host system of -the library will be the target of the overall build. If the overall -build is a native build, the @samp{--with-cross-host} option will not be -used. - -A library which can be built both standalone and as a target library may -want to install itself into different directories depending upon the -case. When built standalone, or when built native, the library should -be installed in @samp{$(libdir)}. When built as a target library which -is not native, the library should be installed in @samp{$(tooldir)/lib}. -The @samp{--with-cross-host} option may be used to distinguish these -cases. - -This same test of @samp{--with-cross-host} may be used to see whether it -is OK to use link tests in the configure script. If the -@samp{--with-cross-host} option is not used, then the library is being -built either standalone or native, and a link should work. - -@node Make Targets in Cygnus Tree -@subsection Make Targets in Cygnus Tree - -The top level @file{Makefile} in the Cygnus tree defines targets for -every known subdirectory. - -For every subdirectory @var{dir} which holds a host library or program, -the @file{Makefile} target @samp{all-@var{dir}} will build that library -or program. - -There are dependencies among host tools. For example, building gcc -requires first building gas, because the gcc build process invokes the -target assembler. These dependencies are reflected in the top level -@file{Makefile}. - -For every subdirectory @var{dir} which holds a target library, the -@file{Makefile} target @samp{configure-target-@var{dir}} will configure -that library. The @file{Makefile} target @samp{all-target-@var{dir}} -will build that library. - -Every @samp{configure-target-@var{dir}} target depends upon -@samp{all-gcc}, since gcc, the target compiler, is required to configure -the tool. Every @samp{all-target-@var{dir}} target depends upon the -corresponding @samp{configure-target-@var{dir}} target. - -There are several other targets which may be of interest for each -directory: @samp{install-@var{dir}}, @samp{clean-@var{dir}}, and -@samp{check-@var{dir}}. There are also corresponding @samp{target} -versions of these for the target libraries , such as -@samp{install-target-@var{dir}}. - -@node Target libiberty -@subsection Target libiberty - -The @file{libiberty} subdirectory is currently a special case, in that -it is the only directory which is built both using the host compiler and -using the target compiler. - -This is because the files in @file{libiberty} are used when building the -host tools, and they are also incorporated into the @file{libstdc++} -target library as support code. - -This duality does not pose any particular difficulties. It means that -there are targets for both @samp{all-libiberty} and -@samp{all-target-libiberty}. - -In a native configuration, when target libraries are not built in a -subdirectory, the same objects are normally used as both the host build -and the target build. This is normally OK, since libiberty contains -only C code, and in a native configuration the results of the host -compiler and the target compiler are normally interoperable. - -Irix 6 is again an exception here, since the SGI native compiler -defaults to using the @samp{O32} ABI, and gcc defaults to using the -@samp{N32} ABI. On Irix 6, the target libraries are built in a -subdirectory even for a native configuration, avoiding this problem. - -There are currently no other libraries built for both the host and the -target, but there is no conceptual problem with adding more. - -@node Canadian Cross -@chapter Canadian Cross -@cindex canadian cross -@cindex building with a cross compiler -@cindex cross compiler, building with - -It is possible to use the GNU configure and build system to build a -program which will run on a system which is different from the system on -which the tools are built. In other words, it is possible to build -programs using a cross compiler. - -This is referred to as a @dfn{Canadian Cross}. - -@menu -* Canadian Cross Example:: Canadian Cross Example. -* Canadian Cross Concepts:: Canadian Cross Concepts. -* Build Cross Host Tools:: Build Cross Host Tools. -* Build and Host Options:: Build and Host Options. -* CCross not in Cygnus Tree:: Canadian Cross not in Cygnus Tree. -* CCross in Cygnus Tree:: Canadian Cross in Cygnus Tree. -* Supporting Canadian Cross:: Supporting Canadian Cross. -@end menu - -@node Canadian Cross Example -@section Canadian Cross Example - -Here is an example of a Canadian Cross. - -While running on a GNU/Linux, you can build a program which will run on -a Solaris system. You would use a GNU/Linux cross Solaris compiler to -build the program. - -Of course, you could not run the resulting program on your GNU/Linux -system. You would have to copy it over to a Solaris system before you -would run it. - -Of course, you could also simply build the programs on the Solaris -system in the first place. However, perhaps the Solaris system is not -available for some reason; perhaps you actually don't have one, but you -want to build the tools for somebody else to use. Or perhaps your -GNU/Linux system is much faster than your Solaris system. - -A Canadian Cross build is most frequently used when building programs to -run on a non-Unix system, such as DOS or Windows. It may be simpler to -configure and build on a Unix system than to support the configuration -machinery on a non-Unix system. - -@node Canadian Cross Concepts -@section Canadian Cross Concepts - -When building a Canadian Cross, there are at least two different systems -involved: the system on which the tools are being built, and the system -on which the tools will run. - -The system on which the tools are being built is called the @dfn{build} -system. - -The system on which the tools will run is called the host system. - -For example, if you are building a Solaris program on a GNU/Linux -system, as in the previous section, the build system would be GNU/Linux, -and the host system would be Solaris. - -It is, of course, possible to build a cross compiler using a Canadian -Cross (i.e., build a cross compiler using a cross compiler). In this -case, the system for which the resulting cross compiler generates code -is called the target system. (For a more complete discussion of host -and target systems, @pxref{Host and Target}). - -An example of building a cross compiler using a Canadian Cross would be -building a Windows cross MIPS ELF compiler on a GNU/Linux system. In -this case the build system would be GNU/Linux, the host system would be -Windows, and the target system would be MIPS ELF. - -The name Canadian Cross comes from the case when the build, host, and -target systems are all different. At the time that these issues were -all being hashed out, Canada had three national political parties. - -@node Build Cross Host Tools -@section Build Cross Host Tools - -In order to configure a program for a Canadian Cross build, you must -first build and install the set of cross tools you will use to build the -program. - -These tools will be build cross host tools. That is, they will run on -the build system, and will produce code that runs on the host system. - -It is easy to confuse the meaning of build and host here. Always -remember that the build system is where you are doing the build, and the -host system is where the resulting program will run. Therefore, you -need a build cross host compiler. - -In general, you must have a complete cross environment in order to do -the build. This normally means a cross compiler, cross assembler, and -so forth, as well as libraries and include files for the host system. - -@node Build and Host Options -@section Build and Host Options -@cindex configuring a canadian cross -@cindex canadian cross, configuring - -When you run @file{configure}, you must use both the @samp{--build} and -@samp{--host} options. - -@cindex @samp{--build} option -@cindex build option -@cindex configure build system -The @samp{--build} option is used to specify the configuration name of -the build system. This can normally be the result of running the -@file{config.guess} shell script, and it is reasonable to use -@samp{--build=`config.guess`}. - -@cindex @samp{--host} option -@cindex host option -@cindex configure host -The @samp{--host} option is used to specify the configuration name of -the host system. - -As we explained earlier, @file{config.guess} is used to set the default -value for the @samp{--host} option (@pxref{Using the Host Type}). We -can now see that since @file{config.guess} returns the type of system on -which it is run, it really identifies the build system. Since the host -system is normally the same as the build system (i.e., people do not -normally build using a cross compiler), it is reasonable to use the -result of @file{config.guess} as the default for the host system when -the @samp{--host} option is not used. - -It might seem that if the @samp{--host} option were used without the -@samp{--build} option that the configure script could run -@file{config.guess} to determine the build system, and presume a -Canadian Cross if the result of @file{config.guess} differed from the -@samp{--host} option. However, for historical reasons, some configure -scripts are routinely run using an explicit @samp{--host} option, rather -than using the default from @file{config.guess}. As noted earlier, it -is difficult or impossible to reliably compare configuration names -(@pxref{Using the Target Type}). Therefore, by convention, if the -@samp{--host} option is used, but the @samp{--build} option is not used, -then the build system defaults to the host system. - -@node CCross not in Cygnus Tree -@section Canadian Cross not in Cygnus Tree. - -If you are not using the Cygnus tree, you must explicitly specify the -cross tools which you want to use to build the program. This is done by -setting environment variables before running the @file{configure} -script. - -You must normally set at least the environment variables @samp{CC}, -@samp{AR}, and @samp{RANLIB} to the cross tools which you want to use to -build. - -For some programs, you must set additional cross tools as well, such as -@samp{AS}, @samp{LD}, or @samp{NM}. - -You would set these environment variables to the build cross tools which -you are going to use. - -For example, if you are building a Solaris program on a GNU/Linux -system, and your GNU/Linux cross Solaris compiler were named -@samp{solaris-gcc}, then you would set the environment variable -@samp{CC} to @samp{solaris-gcc}. - -@node CCross in Cygnus Tree -@section Canadian Cross in Cygnus Tree -@cindex canadian cross in cygnus tree - -This section describes configuring and building a Canadian Cross when -using the Cygnus tree. - -@menu -* Standard Cygnus CCross:: Building a Normal Program. -* Cross Cygnus CCross:: Building a Cross Program. -@end menu - -@node Standard Cygnus CCross -@subsection Building a Normal Program - -When configuring a Canadian Cross in the Cygnus tree, all the -appropriate environment variables are automatically set to -@samp{@var{host}-@var{tool}}, where @var{host} is the value used for the -@samp{--host} option, and @var{tool} is the name of the tool (e.g., -@samp{gcc}, @samp{as}, etc.). These tools must be on your @samp{PATH}. - -Adding a prefix of @var{host} will give the usual name for the build -cross host tools. To see this, consider that when these cross tools -were built, they were configured to run on the build system and to -produce code for the host system. That is, they were configured with a -@samp{--target} option that is the same as the system which we are now -calling the host. Recall that the default name for installed cross -tools uses the target system as a prefix (@pxref{Using the Target -Type}). Since that is the system which we are now calling the host, -@var{host} is the right prefix to use. - -For example, if you configure with @samp{--build=i386-linux-gnu} and -@samp{--host=solaris}, then the Cygnus tree will automatically default -to using the compiler @samp{solaris-gcc}. You must have previously -built and installed this compiler, probably by doing a build with no -@samp{--host} option and with a @samp{--target} option of -@samp{solaris}. - -@node Cross Cygnus CCross -@subsection Building a Cross Program - -There are additional considerations if you want to build a cross -compiler, rather than a native compiler, in the Cygnus tree using a -Canadian Cross. - -When you build a cross compiler using the Cygnus tree, then the target -libraries will normally be built with the newly built target compiler -(@pxref{Host and Target Libraries}). However, this will not work when -building with a Canadian Cross. This is because the newly built target -compiler will be a program which runs on the host system, and therefore -will not be able to run on the build system. - -Therefore, when building a cross compiler with the Cygnus tree, you must -first install a set of build cross target tools. These tools will be -used when building the target libraries. - -Note that this is not a requirement of a Canadian Cross in general. For -example, it would be possible to build just the host cross target tools -on the build system, to copy the tools to the host system, and to build -the target libraries on the host system. The requirement for build -cross target tools is imposed by the Cygnus tree, which expects to be -able to build both host programs and target libraries in a single -@samp{configure}/@samp{make} step. Because it builds these in a single -step, it expects to be able to build the target libraries on the build -system, which means that it must use a build cross target toolchain. - -For example, suppose you want to build a Windows cross MIPS ELF compiler -on a GNU/Linux system. You must have previously installed both a -GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF -compiler. - -In order to build the Windows (configuration name @samp{i386-cygwin32}) -cross MIPS ELF (configure name @samp{mips-elf}) compiler, you might -execute the following commands (long command lines are broken across -lines with a trailing backslash as a continuation character). - -@example -mkdir linux-x-cygwin32 -cd linux-x-cygwin32 -@var{srcdir}/configure --target i386-cygwin32 --prefix=@var{installdir} \ - --exec-prefix=@var{installdir}/H-i386-linux -make -make install -cd .. -mkdir linux-x-mips-elf -cd linux-x-mips-elf -@var{srcdir}/configure --target mips-elf --prefix=@var{installdir} \ - --exec-prefix=@var{installdir}/H-i386-linux -make -make install -cd .. -mkdir cygwin32-x-mips-elf -cd cygwin32-x-mips-elf -@var{srcdir}/configure --build=i386-linux-gnu --host=i386-cygwin32 \ - --target=mips-elf --prefix=@var{wininstalldir} \ - --exec-prefix=@var{wininstalldir}/H-i386-cygwin32 -make -make install -@end example - -You would then copy the contents of @var{wininstalldir} over to the -Windows machine, and run the resulting programs. - -@node Supporting Canadian Cross -@section Supporting Canadian Cross - -If you want to make it possible to build a program you are developing -using a Canadian Cross, you must take some care when writing your -configure and make rules. Simple cases will normally work correctly. -However, it is not hard to write configure and make tests which will -fail in a Canadian Cross. - -@menu -* CCross in Configure:: Supporting Canadian Cross in Configure Scripts. -* CCross in Make:: Supporting Canadian Cross in Makefiles. -@end menu - -@node CCross in Configure -@subsection Supporting Canadian Cross in Configure Scripts -@cindex canadian cross in configure - -In a @file{configure.in} file, after calling @samp{AC_PROG_CC}, you can -find out whether this is a Canadian Cross configure by examining the -shell variable @samp{cross_compiling}. In a Canadian Cross, which means -that the compiler is a cross compiler, @samp{cross_compiling} will be -@samp{yes}. In a normal configuration, @samp{cross_compiling} will be -@samp{no}. - -You ordinarily do not need to know the type of the build system in a -configure script. However, if you do need that information, you can get -it by using the macro @samp{AC_CANONICAL_SYSTEM}, the same macro that is -used to determine the target system. This macro will set the variables -@samp{build}, @samp{build_alias}, @samp{build_cpu}, @samp{build_vendor}, -and @samp{build_os}, which correspond to the similar @samp{target} and -@samp{host} variables, except that they describe the build system. - -When writing tests in @file{configure.in}, you must remember that you -want to test the host environment, not the build environment. - -Macros like @samp{AC_CHECK_FUNCS} which use the compiler will test the -host environment. That is because the tests will be done by running the -compiler, which is actually a build cross host compiler. If the -compiler can find the function, that means that the function is present -in the host environment. - -Tests like @samp{test -f /dev/ptyp0}, on the other hand, will test the -build environment. Remember that the configure script is running on the -build system, not the host system. If your configure scripts examines -files, those files will be on the build system. Whatever you determine -based on those files may or may not be the case on the host system. - -Most autoconf macros will work correctly for a Canadian Cross. The main -exception is @samp{AC_TRY_RUN}. This macro tries to compile and run a -test program. This will fail in a Canadian Cross, because the program -will be compiled for the host system, which means that it will not run -on the build system. - -The @samp{AC_TRY_RUN} macro provides an optional argument to tell the -configure script what to do in a Canadian Cross. If that argument is -not present, you will get a warning when you run @samp{autoconf}: -@smallexample -warning: AC_TRY_RUN called without default to allow cross compiling -@end smallexample -@noindent -This tells you that the resulting @file{configure} script will not work -with a Canadian Cross. - -In some cases while it may better to perform a test at configure time, -it is also possible to perform the test at run time. In such a case you -can use the cross compiling argument to @samp{AC_TRY_RUN} to tell your -program that the test could not be performed at configure time. - -There are a few other autoconf macros which will not work correctly with -a Canadian Cross: a partial list is @samp{AC_FUNC_GETPGRP}, -@samp{AC_FUNC_SETPGRP}, @samp{AC_FUNC_SETVBUF_REVERSED}, and -@samp{AC_SYS_RESTARTABLE_SYSCALLS}. The @samp{AC_CHECK_SIZEOF} macro is -generally not very useful with a Canadian Cross; it permits an optional -argument indicating the default size, but there is no way to know what -the correct default should be. - -@node CCross in Make -@subsection Supporting Canadian Cross in Makefiles. -@cindex canadian cross in makefile - -The main Canadian Cross issue in a @file{Makefile} arises when you want -to use a subsidiary program to generate code or data which you will then -include in your real program. - -If you compile this subsidiary program using @samp{$(CC)} in the usual -way, you will not be able to run it. This is because @samp{$(CC)} will -build a program for the host system, but the program is being built on -the build system. - -You must instead use a compiler for the build system, rather than the -host system. In the Cygnus tree, this make variable -@samp{$(CC_FOR_BUILD)} will hold a compiler for the build system. - -Note that you should not include @file{config.h} in a file you are -compiling with @samp{$(CC_FOR_BUILD)}. The @file{configure} script will -build @file{config.h} with information for the host system. However, -you are compiling the file using a compiler for the build system (a -native compiler). Subsidiary programs are normally simple filters which -do no user interaction, and it is normally possible to write them in a -highly portable fashion so that the absence of @file{config.h} is not -crucial. - -@cindex @samp{HOST_CC} -The gcc @file{Makefile.in} shows a complex situation in which certain -files, such as @file{rtl.c}, must be compiled into both subsidiary -programs run on the build system and into the final program. This -approach may be of interest for advanced build system hackers. Note -that the build system compiler is rather confusingly called -@samp{HOST_CC}. - -@node Cygnus Configure -@chapter Cygnus Configure -@cindex cygnus configure - -The Cygnus configure script predates autoconf. All of its interesting -features have been incorporated into autoconf. No new programs should -be written to use the Cygnus configure script. - -However, the Cygnus configure script is still used in a few places: at -the top of the Cygnus tree and in a few target libraries in the Cygnus -tree. Until those uses have been replaced with autoconf, some brief -notes are appropriate here. This is not complete documentation, but it -should be possible to use this as a guide while examining the scripts -themselves. - -@menu -* Cygnus Configure Basics:: Cygnus Configure Basics. -* Cygnus Configure in C++ Libraries:: Cygnus Configure in C++ Libraries. -@end menu - -@node Cygnus Configure Basics -@section Cygnus Configure Basics - -Cygnus configure does not use any generated files; there is no program -corresponding to @samp{autoconf}. Instead, there is a single shell -script named @samp{configure} which may be found at the top of the -Cygnus tree. This shell script was written by hand; it was not -generated by autoconf, and it is incorrect, and indeed harmful, to run -@samp{autoconf} in the top level of a Cygnus tree. - -Cygnus configure works in a particular directory by examining the file -@file{configure.in} in that directory. That file is broken into four -separate shell scripts. - -The first is the contents of @file{configure.in} up to a line that -starts with @samp{# per-host:}. This is the common part. - -The second is the rest of @file{configure.in} up to a line that starts -with @samp{# per-target:}. This is the per host part. - -The third is the rest of @file{configure.in} up to a line that starts -with @samp{# post-target:}. This is the per target part. - -The fourth is the remainder of @file{configure.in}. This is the post -target part. - -If any of these comment lines are missing, the corresponding shell -script is empty. - -Cygnus configure will first execute the common part. This must set the -shell variable @samp{srctrigger} to the name of a source file, to -confirm that Cygnus configure is looking at the right directory. This -may set the shell variables @samp{package_makefile_frag} and -@samp{package_makefile_rules_frag}. - -Cygnus configure will next set the @samp{build} and @samp{host} shell -variables, and execute the per host part. This may set the shell -variable @samp{host_makefile_frag}. - -Cygnus configure will next set the @samp{target} variable, and execute -the per target part. This may set the shell variable -@samp{target_makefile_frag}. - -Any of these scripts may set the @samp{subdirs} shell variable. This -variable is a list of subdirectories where a @file{Makefile.in} file may -be found. Cygnus configure will automatically look for a -@file{Makefile.in} file in the current directory. The @samp{subdirs} -shell variable is not normally used, and I believe that the only -directory which uses it at present is @file{newlib}. - -For each @file{Makefile.in}, Cygnus configure will automatically create -a @file{Makefile} by adding definitions for @samp{make} variables such -as @samp{host} and @samp{target}, and automatically editing the values -of @samp{make} variables such as @samp{prefix} if they are present. - -Also, if any of the @samp{makefile_frag} shell variables are set, Cygnus -configure will interpret them as file names relative to either the -working directory or the source directory, and will read the contents of -the file into the generated @file{Makefile}. The file contents will be -read in after the first line in @file{Makefile.in} which starts with -@samp{####}. - -These @file{Makefile} fragments are used to customize behaviour for a -particular host or target. They serve to select particular files to -compile, and to define particular preprocessor macros by providing -values for @samp{make} variables which are then used during compilation. -Cygnus configure, unlike autoconf, normally does not do feature tests, -and normally requires support to be added manually for each new host. - -The @file{Makefile} fragment support is similar to the autoconf -@samp{AC_SUBST_FILE} macro. - -After creating each @file{Makefile}, the post target script will be run -(i.e., it may be run several times). This script may further customize -the @file{Makefile}. When it is run, the shell variable @samp{Makefile} -will hold the name of the @file{Makefile}, including the appropriate -directory component. - -Like an autoconf generated @file{configure} script, Cygnus configure -will create a file named @file{config.status} which, when run, will -automatically recreate the configuration. The @file{config.status} file -will simply execute the Cygnus configure script again with the -appropriate arguments. - -Any of the parts of @file{configure.in} may set the shell variables -@samp{files} and @samp{links}. Cygnus configure will set up symlinks -from the names in @samp{links} to the files named in @samp{files}. This -is similar to the autoconf @samp{AC_LINK_FILES} macro. - -Finally, any of the parts of @file{configure.in} may set the shell -variable @samp{configdirs} to a set of subdirectories. If it is set, -Cygnus configure will recursively run the configure process in each -subdirectory. If the subdirectory uses Cygnus configure, it will -contain a @file{configure.in} file but no @file{configure} file, in -which case Cygnus configure will invoke itself recursively. If the -subdirectory has a @file{configure} file, Cygnus configure assumes that -it is an autoconf generated @file{configure} script, and simply invokes -it directly. - -@node Cygnus Configure in C++ Libraries -@section Cygnus Configure in C++ Libraries -@cindex @file{libstdc++} configure -@cindex @file{libio} configure -@cindex @file{libg++} configure - -The C++ library configure system, written by Per Bothner, deserves -special mention. It uses Cygnus configure, but it does feature testing -like that done by autoconf generated @file{configure} scripts. This -approach is used in the libraries @file{libio}, @file{libstdc++}, and -@file{libg++}. - -Most of the @file{Makefile} information is written out by the shell -script @file{libio/config.shared}. Each @file{configure.in} file sets -certain shell variables, and then invokes @file{config.shared} to create -two package @file{Makefile} fragments. These fragments are then -incorporated into the resulting @file{Makefile} by the Cygnus configure -script. - -The file @file{_G_config.h} is created in the @file{libio} object -directory by running the shell script @file{libio/gen-params}. This -shell script uses feature tests to define macros and typedefs in -@file{_G_config.h}. - -@node Multilibs -@chapter Multilibs -@cindex multilibs - -For some targets gcc may have different processor requirements depending -upon command line options. An obvious example is the -@samp{-msoft-float} option supported on several processors. This option -means that the floating point registers are not available, which means -that floating point operations must be done by calling an emulation -subroutine rather than by using machine instructions. - -For such options, gcc is often configured to compile target libraries -twice: once with @samp{-msoft-float} and once without. When gcc -compiles target libraries more than once, the resulting libraries are -called @dfn{multilibs}. - -Multilibs are not really part of the GNU configure and build system, but -we discuss them here since they require support in the @file{configure} -scripts and @file{Makefile}s used for target libraries. - -@menu -* Multilibs in gcc:: Multilibs in gcc. -* Multilibs in Target Libraries:: Multilibs in Target Libraries. -@end menu - -@node Multilibs in gcc -@section Multilibs in gcc - -In gcc, multilibs are defined by setting the variable -@samp{MULTILIB_OPTIONS} in the target @file{Makefile} fragment. Several -other @samp{MULTILIB} variables may also be defined there. @xref{Target -Fragment, , The Target Makefile Fragment, gcc, Using and Porting GNU -CC}. - -If you have built gcc, you can see what multilibs it uses by running it -with the @samp{-print-multi-lib} option. The output @samp{.;} means -that no multilibs are used. In general, the output is a sequence of -lines, one per multilib. The first part of each line, up to the -@samp{;}, is the name of the multilib directory. The second part is a -list of compiler options separated by @samp{@@} characters. - -Multilibs are built in a tree of directories. The top of the tree, -represented by @samp{.} in the list of multilib directories, is the -default library to use when no special compiler options are used. The -subdirectories of the tree hold versions of the library to use when -particular compiler options are used. - -@node Multilibs in Target Libraries -@section Multilibs in Target Libraries - -The target libraries in the Cygnus tree are automatically built with -multilibs. That means that each library is built multiple times. - -This default is set in the top level @file{configure.in} file, by adding -@samp{--enable-multilib} to the list of arguments passed to configure -when it is run for the target libraries (@pxref{Host and Target -Libraries}). - -Each target library uses the shell script @file{config-ml.in}, written -by Doug Evans, to prepare to build target libraries. This shell script -is invoked after the @file{Makefile} has been created by the -@file{configure} script. If multilibs are not enabled, it does nothing, -otherwise it modifies the @file{Makefile} to support multilibs. - -The @file{config-ml.in} script makes one copy of the @file{Makefile} for -each multilib in the appropriate subdirectory. When configuring in the -source directory (which is not recommended), it will build a symlink -tree of the sources in each subdirectory. - -The @file{config-ml.in} script sets several variables in the various -@file{Makefile}s. The @file{Makefile.in} must have definitions for -these variables already; @file{config-ml.in} simply changes the existing -values. The @file{Makefile} should use default values for these -variables which will do the right thing in the subdirectories. - -@table @samp -@item MULTISRCTOP -@file{config-ml.in} will set this to a sequence of @samp{../} strings, -where the number of strings is the number of multilib levels in the -source tree. The default value should be the empty string. -@item MULTIBUILDTOP -@file{config-ml.in} will set this to a sequence of @samp{../} strings, -where the number of strings is number of multilib levels in the object -directory. The default value should be the empty string. This will -differ from @samp{MULTISRCTOP} when configuring in the source tree -(which is not recommended). -@item MULTIDIRS -In the top level @file{Makefile} only, @file{config-ml.in} will set this -to the list of multilib subdirectories. The default value should be the -empty string. -@item MULTISUBDIR -@file{config-ml.in} will set this to the installed subdirectory name to -use for this subdirectory, with a leading @samp{/}. The default value -shold be the empty string. -@item MULTIDO -@itemx MULTICLEAN -In the top level @file{Makefile} only, @file{config-ml.in} will set -these variables to commands to use when doing a recursive make. These -variables should both default to the string @samp{true}, so that by -default nothing happens. -@end table - -All references to the parent of the source directory should use the -variable @samp{MULTISRCTOP}. Instead of writing @samp{$(srcdir)/..}, -you must write @samp{$(srcdir)/$(MULTISRCTOP)..}. - -Similarly, references to the parent of the object directory should use -the variable @samp{MULTIBUILDTOP}. - -In the installation target, the libraries should be installed in the -subdirectory @samp{MULTISUBDIR}. Instead of installing -@samp{$(libdir)/libfoo.a}, install -@samp{$(libdir)$(MULTISUBDIR)/libfoo.a}. - -The @file{config-ml.in} script also modifies the top level -@file{Makefile} to add @samp{multi-do} and @samp{multi-clean} targets -which are used when building multilibs. - -The default target of the @file{Makefile} should include the following -command: -@smallexample -@@$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do -@end smallexample -@noindent -This assumes that @samp{$(FLAGS_TO_PASS)} is defined as a set of -variables to pass to a recursive invocation of @samp{make}. This will -build all the multilibs. Note that the default value of @samp{MULTIDO} -is @samp{true}, so by default this command will do nothing. It will -only do something in the top level @file{Makefile} if multilibs were -enabled. - -The @samp{install} target of the @file{Makefile} should include the -following command: -@smallexample -@@$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do -@end smallexample - -In general, any operation, other than clean, which should be performed -on all the multilibs should use a @samp{$(MULTIDO)} line, setting the -variable @samp{DO} to the target of each recursive call to @samp{make}. - -The @samp{clean} targets (@samp{clean}, @samp{mostlyclean}, etc.) should -use @samp{$(MULTICLEAN)}. For example, the @samp{clean} target should -do this: -@smallexample -@@$(MULTICLEAN) DO=clean multi-clean -@end smallexample - -@node FAQ -@chapter Frequently Asked Questions - -@table @asis -@item Which do I run first, @samp{autoconf} or @samp{automake}? -Except when you first add autoconf or automake support to a package, you -shouldn't run either by hand. Instead, configure with the -@samp{--enable-maintainer-mode} option, and let @samp{make} take care of -it. - -@cindex undefined macros -@item @samp{autoconf} says something about undefined macros. -This means that you have macros in your @file{configure.in} which are -not defined by @samp{autoconf}. You may be using an old version of -@samp{autoconf}; try building and installing a newer one. Make sure the -newly installled @samp{autoconf} is first on your @samp{PATH}. Also, -see the next question. - -@cindex @samp{CY_GNU_GETTEXT} in @file{configure} -@cindex @samp{AM_PROG_LIBTOOL} in @file{configure} -@item My @file{configure} script has stuff like @samp{CY_GNU_GETTEXT} in it. -This means that you have macros in your @file{configure.in} which should -be defined in your @file{aclocal.m4} file, but aren't. This usually -means that @samp{aclocal} was not able to appropriate definitions of the -macros. Make sure that you have installed all the packages you need. -In particular, make sure that you have installed libtool (this is where -@samp{AM_PROG_LIBTOOL} is defined) and gettext (this is where -@samp{CY_GNU_GETTEXT} is defined, at least in the Cygnus version of -gettext). - -@cindex @file{Makefile}, garbage characters -@item My @file{Makefile} has @samp{@@} characters in it. -This may mean that you tried to use an autoconf substitution in your -@file{Makefile.in} without adding the appropriate @samp{AC_SUBST} call -to your @file{configure} script. Or it may just mean that you need to -rebuild @file{Makefile} in your build directory. To rebuild -@file{Makefile} from @file{Makefile.in}, run the shell script -@file{config.status} with no arguments. If you need to force -@file{configure} to run again, first run @samp{config.status --recheck}. -These runs are normally done automatically by @file{Makefile} targets, -but if your @file{Makefile} has gotten messed up you'll need to help -them along. - -@cindex @samp{config.status --recheck} -@item Why do I have to run both @samp{config.status --recheck} and @samp{config.status}? -Normally, you don't; they will be run automatically by @file{Makefile} -targets. If you do need to run them, use @samp{config.status --recheck} -to run the @file{configure} script again with the same arguments as the -first time you ran it. Use @samp{config.status} (with no arguments) to -regenerate all files (@file{Makefile}, @file{config.h}, etc.) based on -the results of the configure script. The two cases are separate because -it isn't always necessary to regenerate all the files after running -@samp{config.status --recheck}. The @file{Makefile} targets generated -by automake will use the environment variables @samp{CONFIG_FILES} and -@samp{CONFIG_HEADERS} to only regenerate files as they are needed. - -@item What is the Cygnus tree? -The Cygnus tree is used for various packages including gdb, the GNU -binutils, and egcs. It is also, of course, used for Cygnus releases. -It is the build system which was developed at Cygnus, using the Cygnus -configure script. It permits building many different packages with a -single configure and make. The configure scripts in the tree are being -converted to autoconf, but the general build structure remains intact. - -@item Why do I have to keep rebuilding and reinstalling the tools? -I know, it's a pain. Unfortunately, there are bugs in the tools -themselves which need to be fixed, and each time that happens everybody -who uses the tools need to reinstall new versions of them. I don't know -if there is going to be a clever fix until the tools stabilize. - -@item Why not just have a Cygnus tree @samp{make} target to update the tools? -The tools unfortunately need to be installed before they can be used. -That means that they must be built using an appropriate prefix, and it -seems unwise to assume that every configuration uses an appropriate -prefix. It might be possible to make them work in place, or it might be -possible to install them in some subdirectory; so far these approaches -have not been implemented. -@end table - -@node Index -@unnumbered Index - -@printindex cp - -@contents -@bye diff --git a/etc/fdl.texi b/etc/fdl.texi deleted file mode 100644 index 138705678..000000000 --- a/etc/fdl.texi +++ /dev/null @@ -1,368 +0,0 @@ -@c -*-texinfo-*- -@node GNU Free Documentation License, , , Copying This Manual - -@appendix GNU Free Documentation License -@center Version 1.1, March 2000 - -@display -Copyright (C) 2000 Free Software Foundation, Inc. -59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display -@sp 1 -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -written document ``free'' in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@sp 1 -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The ``Document'', below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as ``you.'' - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not ``Transparent'' is called ``Opaque.'' - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML designed for human modification. Opaque formats include -PostScript, PDF, proprietary formats that can be read and edited only -by proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML produced by some word processors for output -purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. -@sp 1 -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. -@sp 1 -@item -COPYING IN QUANTITY - -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. -@sp 1 -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -A. Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission.@* -B. List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has less than five).@* -C. State on the Title page the name of the publisher of the - Modified Version, as the publisher.@* -D. Preserve all the copyright notices of the Document.@* -E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices.@* -F. Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below.@* -G. Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice.@* -H. Include an unaltered copy of this License.@* -I. Preserve the section entitled ``History'', and its title, and add to - it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled ``History'' in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence.@* -J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the ``History'' section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission.@* -K. In any section entitled ``Acknowledgements'' or ``Dedications'', - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein.@* -L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles.@* -M. Delete any section entitled ``Endorsements.'' Such a section - may not be included in the Modified Version.@* -N. Do not retitle any existing section as ``Endorsements'' - or to conflict in title with any Invariant Section.@* -@sp 1 -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. -@sp 1 -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections entitled ``History'' -in the various original documents, forming one section entitled -``History''; likewise combine any sections entitled ``Acknowledgements'', -and any sections entitled ``Dedications.'' You must delete all sections -entitled ``Endorsements.'' -@sp 1 -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. -@sp 1 -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an ``aggregate'', and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. -@sp 1 -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. -@sp 1 -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. -@sp 1 -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -http://www.gnu.org/copyleft/. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. - -@end enumerate - -@unnumberedsec ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group -Copyright (C) @var{year} @var{your name}. -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 -or any later version published by the Free Software Foundation; -with the Invariant Sections being @var{list their titles}, with the -Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. -A copy of the license is included in the section entitled "GNU -Free Documentation License." -@end group -@end smallexample - -If you have no Invariant Sections, write ``with no Invariant Sections'' -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write ``no Front-Cover Texts'' instead of -``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. diff --git a/etc/make-stds.texi b/etc/make-stds.texi deleted file mode 100644 index 250867adf..000000000 --- a/etc/make-stds.texi +++ /dev/null @@ -1,955 +0,0 @@ -@comment This file is included by both standards.texi and make.texinfo. -@comment It was broken out of standards.texi on 1/6/93 by roland. - -@node Makefile Conventions -@chapter Makefile Conventions -@comment standards.texi does not print an index, but make.texinfo does. -@cindex makefile, conventions for -@cindex conventions for makefiles -@cindex standards for makefiles - -@c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001 Free -@c Software Foundation, Inc. - -@c Permission is granted to copy, distribute and/or modify this document -@c under the terms of the GNU Free Documentation License, Version 1.1 -@c or any later version published by the Free Software Foundation; -@c with no Invariant Sections, with no -@c Front-Cover Texts, and with no Back-Cover Texts. -@c A copy of the license is included in the section entitled ``GNU -@c Free Documentation License''. - -This -@ifinfo -node -@end ifinfo -@iftex -@ifset CODESTD -section -@end ifset -@ifclear CODESTD -chapter -@end ifclear -@end iftex -describes conventions for writing the Makefiles for GNU programs. -Using Automake will help you write a Makefile that follows these -conventions. - -@menu -* Makefile Basics:: General Conventions for Makefiles -* Utilities in Makefiles:: Utilities in Makefiles -* Command Variables:: Variables for Specifying Commands -* Directory Variables:: Variables for Installation Directories -* Standard Targets:: Standard Targets for Users -* Install Command Categories:: Three categories of commands in the `install' - rule: normal, pre-install and post-install. -@end menu - -@node Makefile Basics -@section General Conventions for Makefiles - -Every Makefile should contain this line: - -@example -SHELL = /bin/sh -@end example - -@noindent -to avoid trouble on systems where the @code{SHELL} variable might be -inherited from the environment. (This is never a problem with GNU -@code{make}.) - -Different @code{make} programs have incompatible suffix lists and -implicit rules, and this sometimes creates confusion or misbehavior. So -it is a good idea to set the suffix list explicitly using only the -suffixes you need in the particular Makefile, like this: - -@example -.SUFFIXES: -.SUFFIXES: .c .o -@end example - -@noindent -The first line clears out the suffix list, the second introduces all -suffixes which may be subject to implicit rules in this Makefile. - -Don't assume that @file{.} is in the path for command execution. When -you need to run programs that are a part of your package during the -make, please make sure that it uses @file{./} if the program is built as -part of the make or @file{$(srcdir)/} if the file is an unchanging part -of the source code. Without one of these prefixes, the current search -path is used. - -The distinction between @file{./} (the @dfn{build directory}) and -@file{$(srcdir)/} (the @dfn{source directory}) is important because -users can build in a separate directory using the @samp{--srcdir} option -to @file{configure}. A rule of the form: - -@smallexample -foo.1 : foo.man sedscript - sed -e sedscript foo.man > foo.1 -@end smallexample - -@noindent -will fail when the build directory is not the source directory, because -@file{foo.man} and @file{sedscript} are in the source directory. - -When using GNU @code{make}, relying on @samp{VPATH} to find the source -file will work in the case where there is a single dependency file, -since the @code{make} automatic variable @samp{$<} will represent the -source file wherever it is. (Many versions of @code{make} set @samp{$<} -only in implicit rules.) A Makefile target like - -@smallexample -foo.o : bar.c - $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o -@end smallexample - -@noindent -should instead be written as - -@smallexample -foo.o : bar.c - $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@ -@end smallexample - -@noindent -in order to allow @samp{VPATH} to work correctly. When the target has -multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest -way to make the rule work well. For example, the target above for -@file{foo.1} is best written as: - -@smallexample -foo.1 : foo.man sedscript - sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ -@end smallexample - -GNU distributions usually contain some files which are not source -files---for example, Info files, and the output from Autoconf, Automake, -Bison or Flex. Since these files normally appear in the source -directory, they should always appear in the source directory, not in the -build directory. So Makefile rules to update them should put the -updated files in the source directory. - -However, if a file does not appear in the distribution, then the -Makefile should not put it in the source directory, because building a -program in ordinary circumstances should not modify the source directory -in any way. - -Try to make the build and installation targets, at least (and all their -subtargets) work correctly with a parallel @code{make}. - -@node Utilities in Makefiles -@section Utilities in Makefiles - -Write the Makefile commands (and any shell scripts, such as -@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any -special features of @code{ksh} or @code{bash}. - -The @code{configure} script and the Makefile rules for building and -installation should not use any utilities directly except these: - -@c dd find -@c gunzip gzip md5sum -@c mkfifo mknod tee uname - -@example -cat cmp cp diff echo egrep expr false grep install-info -ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true -@end example - -The compression program @code{gzip} can be used in the @code{dist} rule. - -Stick to the generally supported options for these programs. For -example, don't use @samp{mkdir -p}, convenient as it may be, because -most systems don't support it. - -It is a good idea to avoid creating symbolic links in makefiles, since a -few systems don't support them. - -The Makefile rules for building and installation can also use compilers -and related programs, but should do so via @code{make} variables so that the -user can substitute alternatives. Here are some of the programs we -mean: - -@example -ar bison cc flex install ld ldconfig lex -make makeinfo ranlib texi2dvi yacc -@end example - -Use the following @code{make} variables to run those programs: - -@example -$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) -$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) -@end example - -When you use @code{ranlib} or @code{ldconfig}, you should make sure -nothing bad happens if the system does not have the program in question. -Arrange to ignore an error from that command, and print a message before -the command to tell the user that failure of this command does not mean -a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with -this.) - -If you use symbolic links, you should implement a fallback for systems -that don't have symbolic links. - -Additional utilities that can be used via Make variables are: - -@example -chgrp chmod chown mknod -@end example - -It is ok to use other utilities in Makefile portions (or scripts) -intended only for particular systems where you know those utilities -exist. - -@node Command Variables -@section Variables for Specifying Commands - -Makefiles should provide variables for overriding certain commands, options, -and so on. - -In particular, you should run most utility programs via variables. -Thus, if you use Bison, have a variable named @code{BISON} whose default -value is set with @samp{BISON = bison}, and refer to it with -@code{$(BISON)} whenever you need to use Bison. - -File management utilities such as @code{ln}, @code{rm}, @code{mv}, and -so on, need not be referred to through variables in this way, since users -don't need to replace them with other programs. - -Each program-name variable should come with an options variable that is -used to supply options to the program. Append @samp{FLAGS} to the -program-name variable name to get the options variable name---for -example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C -compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are -exceptions to this rule, but we keep them because they are standard.) -Use @code{CPPFLAGS} in any compilation command that runs the -preprocessor, and use @code{LDFLAGS} in any compilation command that -does linking as well as in any direct use of @code{ld}. - -If there are C compiler options that @emph{must} be used for proper -compilation of certain files, do not include them in @code{CFLAGS}. -Users expect to be able to specify @code{CFLAGS} freely themselves. -Instead, arrange to pass the necessary options to the C compiler -independently of @code{CFLAGS}, by writing them explicitly in the -compilation commands or by defining an implicit rule, like this: - -@smallexample -CFLAGS = -g -ALL_CFLAGS = -I. $(CFLAGS) -.c.o: - $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< -@end smallexample - -Do include the @samp{-g} option in @code{CFLAGS}, because that is not -@emph{required} for proper compilation. You can consider it a default -that is only recommended. If the package is set up so that it is -compiled with GCC by default, then you might as well include @samp{-O} -in the default value of @code{CFLAGS} as well. - -Put @code{CFLAGS} last in the compilation command, after other variables -containing compiler options, so the user can use @code{CFLAGS} to -override the others. - -@code{CFLAGS} should be used in every invocation of the C compiler, -both those which do compilation and those which do linking. - -Every Makefile should define the variable @code{INSTALL}, which is the -basic command for installing a file into the system. - -Every Makefile should also define the variables @code{INSTALL_PROGRAM} -and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should -be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be -@code{$@{INSTALL@} -m 644}.) Then it should use those variables as the -commands for actual installation, for executables and nonexecutables -respectively. Use these variables as follows: - -@example -$(INSTALL_PROGRAM) foo $(bindir)/foo -$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a -@end example - -Optionally, you may prepend the value of @code{DESTDIR} to the target -filename. Doing this allows the installer to create a snapshot of the -installation to be copied onto the real target filesystem later. Do not -set the value of @code{DESTDIR} in your Makefile, and do not include it -in any installed files. With support for @code{DESTDIR}, the above -examples become: - -@example -$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo -$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a -@end example - -@noindent -Always use a file name, not a directory name, as the second argument of -the installation commands. Use a separate command for each file to be -installed. - -@node Directory Variables -@section Variables for Installation Directories - -Installation directories should always be named by variables, so it is -easy to install in a nonstandard place. The standard names for these -variables are described below. They are based on a standard filesystem -layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4, -and other modern operating systems. - -These two variables set the root for the installation. All the other -installation directories should be subdirectories of one of these two, -and nothing should be directly installed into these two directories. - -@table @code -@item prefix -@vindex prefix -A prefix used in constructing the default values of the variables listed -below. The default value of @code{prefix} should be @file{/usr/local}. -When building the complete GNU system, the prefix will be empty and -@file{/usr} will be a symbolic link to @file{/}. -(If you are using Autoconf, write it as @samp{@@prefix@@}.) - -Running @samp{make install} with a different value of @code{prefix} from -the one used to build the program should @emph{not} recompile the -program. - -@item exec_prefix -@vindex exec_prefix -A prefix used in constructing the default values of some of the -variables listed below. The default value of @code{exec_prefix} should -be @code{$(prefix)}. -(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.) - -Generally, @code{$(exec_prefix)} is used for directories that contain -machine-specific files (such as executables and subroutine libraries), -while @code{$(prefix)} is used directly for other directories. - -Running @samp{make install} with a different value of @code{exec_prefix} -from the one used to build the program should @emph{not} recompile the -program. -@end table - -Executable programs are installed in one of the following directories. - -@table @code -@item bindir -@vindex bindir -The directory for installing executable programs that users can run. -This should normally be @file{/usr/local/bin}, but write it as -@file{$(exec_prefix)/bin}. -(If you are using Autoconf, write it as @samp{@@bindir@@}.) - -@item sbindir -@vindex sbindir -The directory for installing executable programs that can be run from -the shell, but are only generally useful to system administrators. This -should normally be @file{/usr/local/sbin}, but write it as -@file{$(exec_prefix)/sbin}. -(If you are using Autoconf, write it as @samp{@@sbindir@@}.) - -@item libexecdir -@vindex libexecdir -@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 -The directory for installing executable programs to be run by other -programs rather than by users. This directory should normally be -@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. -(If you are using Autoconf, write it as @samp{@@libexecdir@@}.) -@end table - -Data files used by the program during its execution are divided into -categories in two ways. - -@itemize @bullet -@item -Some files are normally modified by programs; others are never normally -modified (though users may edit some of these). - -@item -Some files are architecture-independent and can be shared by all -machines at a site; some are architecture-dependent and can be shared -only by machines of the same kind and operating system; others may never -be shared between two machines. -@end itemize - -This makes for six different possibilities. However, we want to -discourage the use of architecture-dependent files, aside from object -files and libraries. It is much cleaner to make other data files -architecture-independent, and it is generally not hard. - -Therefore, here are the variables Makefiles should use to specify -directories: - -@table @samp -@item datadir -The directory for installing read-only architecture independent data -files. This should normally be @file{/usr/local/share}, but write it as -@file{$(prefix)/share}. -(If you are using Autoconf, write it as @samp{@@datadir@@}.) -As a special exception, see @file{$(infodir)} -and @file{$(includedir)} below. - -@item sysconfdir -The directory for installing read-only data files that pertain to a -single machine--that is to say, files for configuring a host. Mailer -and network configuration files, @file{/etc/passwd}, and so forth belong -here. All the files in this directory should be ordinary ASCII text -files. This directory should normally be @file{/usr/local/etc}, but -write it as @file{$(prefix)/etc}. -(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.) - -Do not install executables here in this directory (they probably belong -in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install -files that are modified in the normal course of their use (programs -whose purpose is to change the configuration of the system excluded). -Those probably belong in @file{$(localstatedir)}. - -@item sharedstatedir -The directory for installing architecture-independent data files which -the programs modify while they run. This should normally be -@file{/usr/local/com}, but write it as @file{$(prefix)/com}. -(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.) - -@item localstatedir -The directory for installing data files which the programs modify while -they run, and that pertain to one specific machine. Users should never -need to modify files in this directory to configure the package's -operation; put such configuration information in separate files that go -in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)} -should normally be @file{/usr/local/var}, but write it as -@file{$(prefix)/var}. -(If you are using Autoconf, write it as @samp{@@localstatedir@@}.) - -@item libdir -The directory for object files and libraries of object code. Do not -install executables here, they probably ought to go in @file{$(libexecdir)} -instead. The value of @code{libdir} should normally be -@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. -(If you are using Autoconf, write it as @samp{@@libdir@@}.) - -@item infodir -The directory for installing the Info files for this package. By -default, it should be @file{/usr/local/info}, but it should be written -as @file{$(prefix)/info}. -(If you are using Autoconf, write it as @samp{@@infodir@@}.) - -@item lispdir -The directory for installing any Emacs Lisp files in this package. By -default, it should be @file{/usr/local/share/emacs/site-lisp}, but it -should be written as @file{$(prefix)/share/emacs/site-lisp}. - -If you are using Autoconf, write the default as @samp{@@lispdir@@}. -In order to make @samp{@@lispdir@@} work, you need the following lines -in your @file{configure.in} file: - -@example -lispdir='$@{datadir@}/emacs/site-lisp' -AC_SUBST(lispdir) -@end example - -@item includedir -@c rewritten to avoid overfull hbox --roland -The directory for installing header files to be included by user -programs with the C @samp{#include} preprocessor directive. This -should normally be @file{/usr/local/include}, but write it as -@file{$(prefix)/include}. -(If you are using Autoconf, write it as @samp{@@includedir@@}.) - -Most compilers other than GCC do not look for header files in directory -@file{/usr/local/include}. So installing the header files this way is -only useful with GCC. Sometimes this is not a problem because some -libraries are only really intended to work with GCC. But some libraries -are intended to work with other compilers. They should install their -header files in two places, one specified by @code{includedir} and one -specified by @code{oldincludedir}. - -@item oldincludedir -The directory for installing @samp{#include} header files for use with -compilers other than GCC. This should normally be @file{/usr/include}. -(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.) - -The Makefile commands should check whether the value of -@code{oldincludedir} is empty. If it is, they should not try to use -it; they should cancel the second installation of the header files. - -A package should not replace an existing header in this directory unless -the header came from the same package. Thus, if your Foo package -provides a header file @file{foo.h}, then it should install the header -file in the @code{oldincludedir} directory if either (1) there is no -@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo -package. - -To tell whether @file{foo.h} came from the Foo package, put a magic -string in the file---part of a comment---and @code{grep} for that string. -@end table - -Unix-style man pages are installed in one of the following: - -@table @samp -@item mandir -The top-level directory for installing the man pages (if any) for this -package. It will normally be @file{/usr/local/man}, but you should -write it as @file{$(prefix)/man}. -(If you are using Autoconf, write it as @samp{@@mandir@@}.) - -@item man1dir -The directory for installing section 1 man pages. Write it as -@file{$(mandir)/man1}. -@item man2dir -The directory for installing section 2 man pages. Write it as -@file{$(mandir)/man2} -@item @dots{} - -@strong{Don't make the primary documentation for any GNU software be a -man page. Write a manual in Texinfo instead. Man pages are just for -the sake of people running GNU software on Unix, which is a secondary -application only.} - -@item manext -The file name extension for the installed man page. This should contain -a period followed by the appropriate digit; it should normally be @samp{.1}. - -@item man1ext -The file name extension for installed section 1 man pages. -@item man2ext -The file name extension for installed section 2 man pages. -@item @dots{} -Use these names instead of @samp{manext} if the package needs to install man -pages in more than one section of the manual. -@end table - -And finally, you should set the following variable: - -@table @samp -@item srcdir -The directory for the sources being compiled. The value of this -variable is normally inserted by the @code{configure} shell script. -(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.) -@end table - -For example: - -@smallexample -@c I have changed some of the comments here slightly to fix an overfull -@c hbox, so the make manual can format correctly. --roland -# Common prefix for installation directories. -# NOTE: This directory must exist when you start the install. -prefix = /usr/local -exec_prefix = $(prefix) -# Where to put the executable for the command `gcc'. -bindir = $(exec_prefix)/bin -# Where to put the directories used by the compiler. -libexecdir = $(exec_prefix)/libexec -# Where to put the Info files. -infodir = $(prefix)/info -@end smallexample - -If your program installs a large number of files into one of the -standard user-specified directories, it might be useful to group them -into a subdirectory particular to that program. If you do this, you -should write the @code{install} rule to create these subdirectories. - -Do not expect the user to include the subdirectory name in the value of -any of the variables listed above. The idea of having a uniform set of -variable names for installation directories is to enable the user to -specify the exact same values for several different GNU packages. In -order for this to be useful, all the packages must be designed so that -they will work sensibly when the user does so. - -@node Standard Targets -@section Standard Targets for Users - -All GNU programs should have the following targets in their Makefiles: - -@table @samp -@item all -Compile the entire program. This should be the default target. This -target need not rebuild any documentation files; Info files should -normally be included in the distribution, and DVI files should be made -only when explicitly asked for. - -By default, the Make rules should compile and link with @samp{-g}, so -that executable programs have debugging symbols. Users who don't mind -being helpless can strip the executables later if they wish. - -@item install -Compile the program and copy the executables, libraries, and so on to -the file names where they should reside for actual use. If there is a -simple test to verify that a program is properly installed, this target -should run that test. - -Do not strip executables when installing them. Devil-may-care users can -use the @code{install-strip} target to do that. - -If possible, write the @code{install} target rule so that it does not -modify anything in the directory where the program was built, provided -@samp{make all} has just been done. This is convenient for building the -program under one user name and installing it under another. - -The commands should create all the directories in which files are to be -installed, if they don't already exist. This includes the directories -specified as the values of the variables @code{prefix} and -@code{exec_prefix}, as well as all subdirectories that are needed. -One way to do this is by means of an @code{installdirs} target -as described below. - -Use @samp{-} before any command for installing a man page, so that -@code{make} will ignore any errors. This is in case there are systems -that don't have the Unix man page documentation system installed. - -The way to install Info files is to copy them into @file{$(infodir)} -with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run -the @code{install-info} program if it is present. @code{install-info} -is a program that edits the Info @file{dir} file to add or update the -menu entry for the given Info file; it is part of the Texinfo package. -Here is a sample rule to install an Info file: - -@comment This example has been carefully formatted for the Make manual. -@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. -@smallexample -$(DESTDIR)$(infodir)/foo.info: foo.info - $(POST_INSTALL) -# There may be a newer info file in . than in srcdir. - -if test -f foo.info; then d=.; \ - else d=$(srcdir); fi; \ - $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \ -# Run install-info only if it exists. -# Use `if' instead of just prepending `-' to the -# line so we notice real errors from install-info. -# We use `$(SHELL) -c' because some shells do not -# fail gracefully when there is an unknown command. - if $(SHELL) -c 'install-info --version' \ - >/dev/null 2>&1; then \ - install-info --dir-file=$(DESTDIR)$(infodir)/dir \ - $(DESTDIR)$(infodir)/foo.info; \ - else true; fi -@end smallexample - -When writing the @code{install} target, you must classify all the -commands into three categories: normal ones, @dfn{pre-installation} -commands and @dfn{post-installation} commands. @xref{Install Command -Categories}. - -@item uninstall -Delete all the installed files---the copies that the @samp{install} -target creates. - -This rule should not modify the directories where compilation is done, -only the directories where files are installed. - -The uninstallation commands are divided into three categories, just like -the installation commands. @xref{Install Command Categories}. - -@item install-strip -Like @code{install}, but strip the executable files while installing -them. In simple cases, this target can use the @code{install} target in -a simple way: - -@smallexample -install-strip: - $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ - install -@end smallexample - -But if the package installs scripts as well as real executables, the -@code{install-strip} target can't just refer to the @code{install} -target; it has to strip the executables but not the scripts. - -@code{install-strip} should not strip the executables in the build -directory which are being copied for installation. It should only strip -the copies that are installed. - -Normally we do not recommend stripping an executable unless you are sure -the program has no bugs. However, it can be reasonable to install a -stripped executable for actual execution while saving the unstripped -executable elsewhere in case there is a bug. - -@comment The gratuitous blank line here is to make the table look better -@comment in the printed Make manual. Please leave it in. -@item clean - -Delete all files from the current directory that are normally created by -building the program. Don't delete the files that record the -configuration. Also preserve files that could be made by building, but -normally aren't because the distribution comes with them. - -Delete @file{.dvi} files here if they are not part of the distribution. - -@item distclean -Delete all files from the current directory that are created by -configuring or building the program. If you have unpacked the source -and built the program without creating any other files, @samp{make -distclean} should leave only the files that were in the distribution. - -@item mostlyclean -Like @samp{clean}, but may refrain from deleting a few files that people -normally don't want to recompile. For example, the @samp{mostlyclean} -target for GCC does not delete @file{libgcc.a}, because recompiling it -is rarely necessary and takes a lot of time. - -@item maintainer-clean -Delete almost everything from the current directory that can be -reconstructed with this Makefile. This typically includes everything -deleted by @code{distclean}, plus more: C source files produced by -Bison, tags tables, Info files, and so on. - -The reason we say ``almost everything'' is that running the command -@samp{make maintainer-clean} should not delete @file{configure} even if -@file{configure} can be remade using a rule in the Makefile. More generally, -@samp{make maintainer-clean} should not delete anything that needs to -exist in order to run @file{configure} and then begin to build the -program. This is the only exception; @code{maintainer-clean} should -delete everything else that can be rebuilt. - -The @samp{maintainer-clean} target is intended to be used by a maintainer of -the package, not by ordinary users. You may need special tools to -reconstruct some of the files that @samp{make maintainer-clean} deletes. -Since these files are normally included in the distribution, we don't -take care to make them easy to reconstruct. If you find you need to -unpack the full distribution again, don't blame us. - -To help make users aware of this, the commands for the special -@code{maintainer-clean} target should start with these two: - -@smallexample -@@echo 'This command is intended for maintainers to use; it' -@@echo 'deletes files that may need special tools to rebuild.' -@end smallexample - -@item TAGS -Update a tags table for this program. -@c ADR: how? - -@item info -Generate any Info files needed. The best way to write the rules is as -follows: - -@smallexample -info: foo.info - -foo.info: foo.texi chap1.texi chap2.texi - $(MAKEINFO) $(srcdir)/foo.texi -@end smallexample - -@noindent -You must define the variable @code{MAKEINFO} in the Makefile. It should -run the @code{makeinfo} program, which is part of the Texinfo -distribution. - -Normally a GNU distribution comes with Info files, and that means the -Info files are present in the source directory. Therefore, the Make -rule for an info file should update it in the source directory. When -users build the package, ordinarily Make will not update the Info files -because they will already be up to date. - -@item dvi -Generate DVI files for all Texinfo documentation. -For example: - -@smallexample -dvi: foo.dvi - -foo.dvi: foo.texi chap1.texi chap2.texi - $(TEXI2DVI) $(srcdir)/foo.texi -@end smallexample - -@noindent -You must define the variable @code{TEXI2DVI} in the Makefile. It should -run the program @code{texi2dvi}, which is part of the Texinfo -distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work -of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, -write just the dependencies, and allow GNU @code{make} to provide the command. - -@item dist -Create a distribution tar file for this program. The tar file should be -set up so that the file names in the tar file start with a subdirectory -name which is the name of the package it is a distribution for. This -name can include the version number. - -For example, the distribution tar file of GCC version 1.40 unpacks into -a subdirectory named @file{gcc-1.40}. - -The easiest way to do this is to create a subdirectory appropriately -named, use @code{ln} or @code{cp} to install the proper files in it, and -then @code{tar} that subdirectory. - -Compress the tar file with @code{gzip}. For example, the actual -distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}. - -The @code{dist} target should explicitly depend on all non-source files -that are in the distribution, to make sure they are up to date in the -distribution. -@ifset CODESTD -@xref{Releases, , Making Releases}. -@end ifset -@ifclear CODESTD -@xref{Releases, , Making Releases, standards, GNU Coding Standards}. -@end ifclear - -@item check -Perform self-tests (if any). The user must build the program before -running the tests, but need not install the program; you should write -the self-tests so that they work when the program is built but not -installed. -@end table - -The following targets are suggested as conventional names, for programs -in which they are useful. - -@table @code -@item installcheck -Perform installation tests (if any). The user must build and install -the program before running the tests. You should not assume that -@file{$(bindir)} is in the search path. - -@item installdirs -It's useful to add a target named @samp{installdirs} to create the -directories where files are installed, and their parent directories. -There is a script called @file{mkinstalldirs} which is convenient for -this; you can find it in the Texinfo package. -@c It's in /gd/gnu/lib/mkinstalldirs. -You can use a rule like this: - -@comment This has been carefully formatted to look decent in the Make manual. -@comment Please be sure not to make it extend any further to the right.--roland -@smallexample -# Make sure all installation directories (e.g. $(bindir)) -# actually exist by making them if necessary. -installdirs: mkinstalldirs - $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ - $(libdir) $(infodir) \ - $(mandir) -@end smallexample - -@noindent -or, if you wish to support @env{DESTDIR}, - -@smallexample -# Make sure all installation directories (e.g. $(bindir)) -# actually exist by making them if necessary. -installdirs: mkinstalldirs - $(srcdir)/mkinstalldirs \ - $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ - $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ - $(DESTDIR)$(mandir) -@end smallexample - -This rule should not modify the directories where compilation is done. -It should do nothing but create installation directories. -@end table - -@node Install Command Categories -@section Install Command Categories - -@cindex pre-installation commands -@cindex post-installation commands -When writing the @code{install} target, you must classify all the -commands into three categories: normal ones, @dfn{pre-installation} -commands and @dfn{post-installation} commands. - -Normal commands move files into their proper places, and set their -modes. They may not alter any files except the ones that come entirely -from the package they belong to. - -Pre-installation and post-installation commands may alter other files; -in particular, they can edit global configuration files or data bases. - -Pre-installation commands are typically executed before the normal -commands, and post-installation commands are typically run after the -normal commands. - -The most common use for a post-installation command is to run -@code{install-info}. This cannot be done with a normal command, since -it alters a file (the Info directory) which does not come entirely and -solely from the package being installed. It is a post-installation -command because it needs to be done after the normal command which -installs the package's Info files. - -Most programs don't need any pre-installation commands, but we have the -feature just in case it is needed. - -To classify the commands in the @code{install} rule into these three -categories, insert @dfn{category lines} among them. A category line -specifies the category for the commands that follow. - -A category line consists of a tab and a reference to a special Make -variable, plus an optional comment at the end. There are three -variables you can use, one for each category; the variable name -specifies the category. Category lines are no-ops in ordinary execution -because these three Make variables are normally undefined (and you -@emph{should not} define them in the makefile). - -Here are the three possible category lines, each with a comment that -explains what it means: - -@smallexample - $(PRE_INSTALL) # @r{Pre-install commands follow.} - $(POST_INSTALL) # @r{Post-install commands follow.} - $(NORMAL_INSTALL) # @r{Normal commands follow.} -@end smallexample - -If you don't use a category line at the beginning of the @code{install} -rule, all the commands are classified as normal until the first category -line. If you don't use any category lines, all the commands are -classified as normal. - -These are the category lines for @code{uninstall}: - -@smallexample - $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.} - $(POST_UNINSTALL) # @r{Post-uninstall commands follow.} - $(NORMAL_UNINSTALL) # @r{Normal commands follow.} -@end smallexample - -Typically, a pre-uninstall command would be used for deleting entries -from the Info directory. - -If the @code{install} or @code{uninstall} target has any dependencies -which act as subroutines of installation, then you should start -@emph{each} dependency's commands with a category line, and start the -main target's commands with a category line also. This way, you can -ensure that each command is placed in the right category regardless of -which of the dependencies actually run. - -Pre-installation and post-installation commands should not run any -programs except for these: - -@example -[ basename bash cat chgrp chmod chown cmp cp dd diff echo -egrep expand expr false fgrep find getopt grep gunzip gzip -hostname install install-info kill ldconfig ln ls md5sum -mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee -test touch true uname xargs yes -@end example - -@cindex binary packages -The reason for distinguishing the commands in this way is for the sake -of making binary packages. Typically a binary package contains all the -executables and other files that need to be installed, and has its own -method of installing them---so it does not need to run the normal -installation commands. But installing the binary package does need to -execute the pre-installation and post-installation commands. - -Programs to build binary packages work by extracting the -pre-installation and post-installation commands. Here is one way of -extracting the pre-installation commands: - -@smallexample -make -n install -o all \ - PRE_INSTALL=pre-install \ - POST_INSTALL=post-install \ - NORMAL_INSTALL=normal-install \ - | gawk -f pre-install.awk -@end smallexample - -@noindent -where the file @file{pre-install.awk} could contain this: - -@smallexample -$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@} -on @{print $0@} -$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@} -@end smallexample - -The resulting file of pre-installation commands is executed as a shell -script as part of installing the binary package. diff --git a/etc/standards.texi b/etc/standards.texi deleted file mode 100644 index 5aa508e01..000000000 --- a/etc/standards.texi +++ /dev/null @@ -1,3742 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename standards.info -@settitle GNU Coding Standards -@c This date is automagically updated when you save this file: -@set lastupdate February 14, 2002 -@c %**end of header - -@ifinfo -@format -START-INFO-DIR-ENTRY -* Standards: (standards). GNU coding standards. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@c @setchapternewpage odd -@setchapternewpage off - -@c Put everything in one index (arbitrarily chosen to be the concept index). -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex pg cp -@syncodeindex vr cp - -@c This is used by a cross ref in make-stds.texi -@set CODESTD 1 -@iftex -@set CHAPTER chapter -@end iftex -@ifinfo -@set CHAPTER node -@end ifinfo - -@ifinfo -GNU Coding Standards -Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 -or any later version published by the Free Software Foundation; -with no Invariant Sections, with no -Front-Cover Texts, and with no Back-Cover Texts. -A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end ifinfo - -@titlepage -@title GNU Coding Standards -@author Richard Stallman, et al. -@author last updated @value{lastupdate} -@page - -@vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 -or any later version published by the Free Software Foundation; -with no Invariant Sections, with no -Front-Cover Texts, and with no Back-Cover Texts. -A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end titlepage - -@ifinfo -@node Top, Preface, (dir), (dir) -@top Version - -Last updated @value{lastupdate}. -@end ifinfo - -@menu -* Preface:: About the GNU Coding Standards -* Legal Issues:: Keeping Free Software Free -* Design Advice:: General Program Design -* Program Behavior:: Program Behavior for All Programs -* Writing C:: Making The Best Use of C -* Documentation:: Documenting Programs -* Managing Releases:: The Release Process -* References:: References to Non-Free Software or Documentation -* Copying This Manual:: How to Make Copies of This Manual -* Index:: - -@end menu - -@node Preface -@chapter About the GNU Coding Standards - -The GNU Coding Standards were written by Richard Stallman and other GNU -Project volunteers. Their purpose is to make the GNU system clean, -consistent, and easy to install. This document can also be read as a -guide to writing portable, robust and reliable programs. It focuses on -programs written in C, but many of the rules and principles are useful -even if you write in another programming language. The rules often -state reasons for writing in a certain way. - -This release of the GNU Coding Standards was last updated -@value{lastupdate}. - -@cindex where to obtain @code{standards.texi} -@cindex downloading this manual -If you did not obtain this file directly from the GNU project and -recently, please check for a newer version. You can ftp the GNU -Coding Standards from any GNU FTP host in the directory -@file{/pub/gnu/standards/}. The GNU Coding Standards are available -there in several different formats: @file{standards.text}, -@file{standards.info}, and @file{standards.dvi}, as well as the -Texinfo ``source'' which is divided in two files: -@file{standards.texi} and @file{make-stds.texi}. The GNU Coding -Standards are also available on the GNU World Wide Web server: -@uref{http://www.gnu.org/prep/standards_toc.html}. - -Corrections or suggestions for this document should be sent to -@email{bug-standards@@gnu.org}. If you make a suggestion, please include a -suggested new wording for it; our time is limited. We prefer a context -diff to the @file{standards.texi} or @file{make-stds.texi} files, but if -you don't have those files, please mail your suggestion anyway. - -These standards cover the minimum of what is important when writing a -GNU package. Likely, the needs for additional standards will come up. -Sometimes, you might suggest that such standards be added to this -document. If you think your standards would be generally useful, please -do suggest them. - -You should also set standards for your package on many questions not -addressed or not firmly specified here. The most important point is to -be self-consistent---try to stick to the conventions you pick, and try -to document them as much as possible. That way, your program will be -more maintainable by others. - -@node Legal Issues -@chapter Keeping Free Software Free -@cindex legal aspects - -This @value{CHAPTER} discusses how you can make sure that GNU software -avoids legal difficulties, and other related issues. - -@menu -* Reading Non-Free Code:: Referring to Proprietary Programs -* Contributions:: Accepting Contributions -* Trademarks:: How We Deal with Trademark Issues -@end menu - -@node Reading Non-Free Code -@section Referring to Proprietary Programs -@cindex proprietary programs -@cindex avoiding proprietary code - -Don't in any circumstances refer to Unix source code for or during -your work on GNU! (Or to any other proprietary programs.) - -If you have a vague recollection of the internals of a Unix program, -this does not absolutely mean you can't write an imitation of it, but -do try to organize the imitation internally along different lines, -because this is likely to make the details of the Unix version -irrelevant and dissimilar to your results. - -For example, Unix utilities were generally optimized to minimize -memory use; if you go for speed instead, your program will be very -different. You could keep the entire input file in core and scan it -there instead of using stdio. Use a smarter algorithm discovered more -recently than the Unix program. Eliminate use of temporary files. Do -it in one pass instead of two (we did this in the assembler). - -Or, on the contrary, emphasize simplicity instead of speed. For some -applications, the speed of today's computers makes simpler algorithms -adequate. - -Or go for generality. For example, Unix programs often have static -tables or fixed-size strings, which make for arbitrary limits; use -dynamic allocation instead. Make sure your program handles NULs and -other funny characters in the input files. Add a programming language -for extensibility and write part of the program in that language. - -Or turn some parts of the program into independently usable libraries. -Or use a simple garbage collector instead of tracking precisely when -to free memory, or use a new GNU facility such as obstacks. - -@node Contributions -@section Accepting Contributions -@cindex legal papers -@cindex accepting contributions - -If the program you are working on is copyrighted by the Free Software -Foundation, then when someone else sends you a piece of code to add to -the program, we need legal papers to use it---just as we asked you to -sign papers initially. @emph{Each} person who makes a nontrivial -contribution to a program must sign some sort of legal papers in order -for us to have clear title to the program; the main author alone is not -enough. - -So, before adding in any contributions from other people, please tell -us, so we can arrange to get the papers. Then wait until we tell you -that we have received the signed papers, before you actually use the -contribution. - -This applies both before you release the program and afterward. If -you receive diffs to fix a bug, and they make significant changes, we -need legal papers for that change. - -This also applies to comments and documentation files. For copyright -law, comments and code are just text. Copyright applies to all kinds of -text, so we need legal papers for all kinds. - -We know it is frustrating to ask for legal papers; it's frustrating for -us as well. But if you don't wait, you are going out on a limb---for -example, what if the contributor's employer won't sign a disclaimer? -You might have to take that code out again! - -You don't need papers for changes of a few lines here or there, since -they are not significant for copyright purposes. Also, you don't need -papers if all you get from the suggestion is some ideas, not actual code -which you use. For example, if someone send you one implementation, but -you write a different implementation of the same idea, you don't need to -get papers. - -The very worst thing is if you forget to tell us about the other -contributor. We could be very embarrassed in court some day as a -result. - -We have more detailed advice for maintainers of programs; if you have -reached the stage of actually maintaining a program for GNU (whether -released or not), please ask us for a copy. - -@node Trademarks -@section Trademarks -@cindex trademarks - -Please do not include any trademark acknowledgements in GNU software -packages or documentation. - -Trademark acknowledgements are the statements that such-and-such is a -trademark of so-and-so. The GNU Project has no objection to the basic -idea of trademarks, but these acknowledgements feel like kowtowing, so -we don't use them. There is no legal requirement for them. - -What is legally required, as regards other people's trademarks, is to -avoid using them in ways which a reader might read as naming or labeling -our own programs or activities. For example, since ``Objective C'' is -(or at least was) a trademark, we made sure to say that we provide a -``compiler for the Objective C language'' rather than an ``Objective C -compiler''. The latter is meant to be short for the former, but it does -not explicitly state the relationship, so it could be misinterpreted as -using ``Objective C'' as a label for the compiler rather than for the -language. - -@node Design Advice -@chapter General Program Design -@cindex program design - -This @value{CHAPTER} discusses some of the issues you should take into -account when designing your program. - -@c Standard or ANSI C -@c -@c In 1989 the American National Standards Institute (ANSI) standardized -@c C as standard X3.159-1989. In December of that year the -@c International Standards Organization ISO adopted the ANSI C standard -@c making minor changes. In 1990 ANSI then re-adopted ISO standard -@c C. This version of C is known as either ANSI C or Standard C. - -@c A major revision of the C Standard appeared in 1999. - -@menu -* Source Language:: Which languges to use. -* Compatibility:: Compatibility with other implementations -* Using Extensions:: Using non-standard features -* Standard C:: Using Standard C features -* Conditional Compilation:: Compiling Code Only If A Conditional is True -@end menu - -@node Source Language -@section Which Languages to Use -@cindex programming languges - -When you want to use a language that gets compiled and runs at high -speed, the best language to use is C. Using another language is like -using a non-standard feature: it will cause trouble for users. Even if -GCC supports the other language, users may find it inconvenient to have -to install the compiler for that other language in order to build your -program. For example, if you write your program in C++, people will -have to install the GNU C++ compiler in order to compile your program. - -C has one other advantage over C++ and other compiled languages: more -people know C, so more people will find it easy to read and modify the -program if it is written in C. - -So in general it is much better to use C, rather than the -comparable alternatives. - -But there are two exceptions to that conclusion: - -@itemize @bullet -@item -It is no problem to use another language to write a tool specifically -intended for use with that language. That is because the only people -who want to build the tool will be those who have installed the other -language anyway. - -@item -If an application is of interest only to a narrow part of the community, -then the question of which language it is written in has less effect on -other people, so you may as well please yourself. -@end itemize - -Many programs are designed to be extensible: they include an interpreter -for a language that is higher level than C. Often much of the program -is written in that language, too. The Emacs editor pioneered this -technique. - -@cindex GUILE -The standard extensibility interpreter for GNU software is GUILE, which -implements the language Scheme (an especially clean and simple dialect -of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject -programs written in other ``scripting languages'' such as Perl and -Python, but using GUILE is very important for the overall consistency of -the GNU system. - -@node Compatibility -@section Compatibility with Other Implementations -@cindex compatibility with C and @sc{posix} standards -@cindex @sc{posix} compatibility - -With occasional exceptions, utility programs and libraries for GNU -should be upward compatible with those in Berkeley Unix, and upward -compatible with Standard C if Standard C specifies their -behavior, and upward compatible with @sc{posix} if @sc{posix} specifies -their behavior. - -When these standards conflict, it is useful to offer compatibility -modes for each of them. - -@cindex options for compatibility -Standard C and @sc{posix} prohibit many kinds of extensions. Feel -free to make the extensions anyway, and include a @samp{--ansi}, -@samp{--posix}, or @samp{--compatible} option to turn them off. -However, if the extension has a significant chance of breaking any real -programs or scripts, then it is not really upward compatible. So you -should try to redesign its interface to make it upward compatible. - -@cindex @code{POSIXLY_CORRECT}, environment variable -Many GNU programs suppress extensions that conflict with @sc{posix} if the -environment variable @code{POSIXLY_CORRECT} is defined (even if it is -defined with a null value). Please make your program recognize this -variable if appropriate. - -When a feature is used only by users (not by programs or command -files), and it is done poorly in Unix, feel free to replace it -completely with something totally different and better. (For example, -@code{vi} is replaced with Emacs.) But it is nice to offer a compatible -feature as well. (There is a free @code{vi} clone, so we offer it.) - -Additional useful features are welcome regardless of whether -there is any precedent for them. - -@node Using Extensions -@section Using Non-standard Features -@cindex non-standard extensions - -Many GNU facilities that already exist support a number of convenient -extensions over the comparable Unix facilities. Whether to use these -extensions in implementing your program is a difficult question. - -On the one hand, using the extensions can make a cleaner program. -On the other hand, people will not be able to build the program -unless the other GNU tools are available. This might cause the -program to work on fewer kinds of machines. - -With some extensions, it might be easy to provide both alternatives. -For example, you can define functions with a ``keyword'' @code{INLINE} -and define that as a macro to expand into either @code{inline} or -nothing, depending on the compiler. - -In general, perhaps it is best not to use the extensions if you can -straightforwardly do without them, but to use the extensions if they -are a big improvement. - -An exception to this rule are the large, established programs (such as -Emacs) which run on a great variety of systems. Using GNU extensions in -such programs would make many users unhappy, so we don't do that. - -Another exception is for programs that are used as part of compilation: -anything that must be compiled with other compilers in order to -bootstrap the GNU compilation facilities. If these require the GNU -compiler, then no one can compile them without having them installed -already. That would be extremely troublesome in certain cases. - -@node Standard C -@section Standard C and Pre-Standard C -@cindex @sc{ansi} C standard - -1989 Standard C is widespread enough now that it is ok to use its -features in new programs. There is one exception: do not ever use the -``trigraph'' feature of Standard C. - -1999 Standard C is not widespread yet, so please do not require its -features in programs. It is ok to use its features if they are present. - -However, it is easy to support pre-standard compilers in most programs, -so if you know how to do that, feel free. If a program you are -maintaining has such support, you should try to keep it working. - -@cindex function prototypes -To support pre-standard C, instead of writing function definitions in -standard prototype form, - -@example -int -foo (int x, int y) -@dots{} -@end example - -@noindent -write the definition in pre-standard style like this, - -@example -int -foo (x, y) - int x, y; -@dots{} -@end example - -@noindent -and use a separate declaration to specify the argument prototype: - -@example -int foo (int, int); -@end example - -You need such a declaration anyway, in a header file, to get the benefit -of prototypes in all the files where the function is called. And once -you have the declaration, you normally lose nothing by writing the -function definition in the pre-standard style. - -This technique does not work for integer types narrower than @code{int}. -If you think of an argument as being of a type narrower than @code{int}, -declare it as @code{int} instead. - -There are a few special cases where this technique is hard to use. For -example, if a function argument needs to hold the system type -@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than -@code{int} on some machines; but you cannot use @code{int} instead, -because @code{dev_t} is wider than @code{int} on some machines. There -is no type you can safely use on all machines in a non-standard -definition. The only way to support non-standard C and pass such an -argument is to check the width of @code{dev_t} using Autoconf and choose -the argument type accordingly. This may not be worth the trouble. - -In order to support pre-standard compilers that do not recognize -prototypes, you may want to use a preprocessor macro like this: - -@example -/* Declare the prototype for a general external function. */ -#if defined (__STDC__) || defined (WINDOWSNT) -#define P_(proto) proto -#else -#define P_(proto) () -#endif -@end example - -@node Conditional Compilation -@section Conditional Compilation - -When supporting configuration options already known when building your -program we prefer using @code{if (... )} over conditional compilation, -as in the former case the compiler is able to perform more extensive -checking of all possible code paths. - -For example, please write - -@smallexample - if (HAS_FOO) - ... - else - ... -@end smallexample - -instead of: - -@smallexample - #ifdef HAS_FOO - ... - #else - ... - #endif -@end smallexample - -A modern compiler such as GCC will generate exactly the same code in -both cases, and we have been using similar techniques with good success -in several projects. - -While this is not a silver bullet solving all portability problems, -following this policy would have saved the GCC project alone many person -hours if not days per year. - -In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in -GCC which cannot be simply used in @code{if( ...)} statements, there is -an easy workaround. Simply introduce another macro -@code{HAS_REVERSIBLE_CC_MODE} as in the following example: - -@smallexample - #ifdef REVERSIBLE_CC_MODE - #define HAS_REVERSIBLE_CC_MODE 1 - #else - #define HAS_REVERSIBLE_CC_MODE 0 - #endif -@end smallexample - -@node Program Behavior -@chapter Program Behavior for All Programs - -This @value{CHAPTER} describes conventions for writing robust -software. It also describes general standards for error messages, the -command line interface, and how libraries should behave. - -@menu -* Semantics:: Writing robust programs -* Libraries:: Library behavior -* Errors:: Formatting error messages -* User Interfaces:: Standards about interfaces generally -* Graphical Interfaces:: Standards for graphical interfaces -* Command-Line Interfaces:: Standards for command line interfaces -* Option Table:: Table of long options -* Memory Usage:: When and how to care about memory needs -* File Usage:: Which files to use, and where -@end menu - -@node Semantics -@section Writing Robust Programs - -@cindex arbitrary limits on data -Avoid arbitrary limits on the length or number of @emph{any} data -structure, including file names, lines, files, and symbols, by allocating -all data structures dynamically. In most Unix utilities, ``long lines -are silently truncated''. This is not acceptable in a GNU utility. - -@cindex @code{NUL} characters -Utilities reading files should not drop NUL characters, or any other -nonprinting characters @emph{including those with codes above 0177}. -The only sensible exceptions would be utilities specifically intended -for interface to certain types of terminals or printers -that can't handle those characters. -Whenever possible, try to make programs work properly with -sequences of bytes that represent multibyte characters, using encodings -such as UTF-8 and others. - -@cindex error messages -Check every system call for an error return, unless you know you wish to -ignore errors. Include the system error text (from @code{perror} or -equivalent) in @emph{every} error message resulting from a failing -system call, as well as the name of the file if any and the name of the -utility. Just ``cannot open foo.c'' or ``stat failed'' is not -sufficient. - -@cindex @code{malloc} return value -@cindex memory allocation failure -Check every call to @code{malloc} or @code{realloc} to see if it -returned zero. Check @code{realloc} even if you are making the block -smaller; in a system that rounds block sizes to a power of 2, -@code{realloc} may get a different block if you ask for less space. - -In Unix, @code{realloc} can destroy the storage block if it returns -zero. GNU @code{realloc} does not have this bug: if it fails, the -original block is unchanged. Feel free to assume the bug is fixed. If -you wish to run your program on Unix, and wish to avoid lossage in this -case, you can use the GNU @code{malloc}. - -You must expect @code{free} to alter the contents of the block that was -freed. Anything you want to fetch from the block, you must fetch before -calling @code{free}. - -If @code{malloc} fails in a noninteractive program, make that a fatal -error. In an interactive program (one that reads commands from the -user), it is better to abort the command and return to the command -reader loop. This allows the user to kill other processes to free up -virtual memory, and then try the command again. - -@cindex command-line arguments, decoding -Use @code{getopt_long} to decode arguments, unless the argument syntax -makes this unreasonable. - -When static storage is to be written in during program execution, use -explicit C code to initialize it. Reserve C initialized declarations -for data that will not be changed. -@c ADR: why? - -Try to avoid low-level interfaces to obscure Unix data structures (such -as file directories, utmp, or the layout of kernel memory), since these -are less likely to work compatibly. If you need to find all the files -in a directory, use @code{readdir} or some other high-level interface. -These are supported compatibly by GNU. - -@cindex signal handling -The preferred signal handling facilities are the BSD variant of -@code{signal}, and the @sc{posix} @code{sigaction} function; the -alternative USG @code{signal} interface is an inferior design. - -Nowadays, using the @sc{posix} signal functions may be the easiest way -to make a program portable. If you use @code{signal}, then on GNU/Linux -systems running GNU libc version 1, you should include -@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD -behavior. It is up to you whether to support systems where -@code{signal} has only the USG behavior, or give up on them. - -@cindex impossible conditions -In error checks that detect ``impossible'' conditions, just abort. -There is usually no point in printing any message. These checks -indicate the existence of bugs. Whoever wants to fix the bugs will have -to read the source code and run a debugger. So explain the problem with -comments in the source. The relevant data will be in variables, which -are easy to examine with the debugger, so there is no point moving them -elsewhere. - -Do not use a count of errors as the exit status for a program. -@emph{That does not work}, because exit status values are limited to 8 -bits (0 through 255). A single run of the program might have 256 -errors; if you try to return 256 as the exit status, the parent process -will see 0 as the status, and it will appear that the program succeeded. - -@cindex temporary files -@cindex @code{TMPDIR} environment variable -If you make temporary files, check the @code{TMPDIR} environment -variable; if that variable is defined, use the specified directory -instead of @file{/tmp}. - -In addition, be aware that there is a possible security problem when -creating temporary files in world-writable directories. In C, you can -avoid this problem by creating temporary files in this manner: - -@example -fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600); -@end example - -@noindent -or by using the @code{mkstemps} function from libiberty. - -In bash, use @code{set -C} to avoid this problem. - -@node Libraries -@section Library Behavior -@cindex libraries - -Try to make library functions reentrant. If they need to do dynamic -storage allocation, at least try to avoid any nonreentrancy aside from -that of @code{malloc} itself. - -Here are certain name conventions for libraries, to avoid name -conflicts. - -Choose a name prefix for the library, more than two characters long. -All external function and variable names should start with this -prefix. In addition, there should only be one of these in any given -library member. This usually means putting each one in a separate -source file. - -An exception can be made when two external symbols are always used -together, so that no reasonable program could use one without the -other; then they can both go in the same file. - -External symbols that are not documented entry points for the user -should have names beginning with @samp{_}. The @samp{_} should be -followed by the chosen name prefix for the library, to prevent -collisions with other libraries. These can go in the same files with -user entry points if you like. - -Static functions and variables can be used as you like and need not -fit any naming convention. - -@node Errors -@section Formatting Error Messages -@cindex formatting error messages -@cindex error messages, formatting - -Error messages from compilers should look like this: - -@example -@var{source-file-name}:@var{lineno}: @var{message} -@end example - -@noindent -If you want to mention the column number, use this format: - -@example -@var{source-file-name}:@var{lineno}:@var{column}: @var{message} -@end example - -@noindent -Line numbers should start from 1 at the beginning of the file, and -column numbers should start from 1 at the beginning of the line. (Both -of these conventions are chosen for compatibility.) Calculate column -numbers assuming that space and all ASCII printing characters have -equal width, and assuming tab stops every 8 columns. - -Error messages from other noninteractive programs should look like this: - -@example -@var{program}:@var{source-file-name}:@var{lineno}: @var{message} -@end example - -@noindent -when there is an appropriate source file, or like this: - -@example -@var{program}: @var{message} -@end example - -@noindent -when there is no relevant source file. - -If you want to mention the column number, use this format: - -@example -@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message} -@end example - -In an interactive program (one that is reading commands from a -terminal), it is better not to include the program name in an error -message. The place to indicate which program is running is in the -prompt or with the screen layout. (When the same program runs with -input from a source other than a terminal, it is not interactive and -would do best to print error messages using the noninteractive style.) - -The string @var{message} should not begin with a capital letter when -it follows a program name and/or file name. Also, it should not end -with a period. - -Error messages from interactive programs, and other messages such as -usage messages, should start with a capital letter. But they should not -end with a period. - -@node User Interfaces -@section Standards for Interfaces Generally - -@cindex program name and its behavior -@cindex behavior, dependent on program's name -Please don't make the behavior of a utility depend on the name used -to invoke it. It is useful sometimes to make a link to a utility -with a different name, and that should not change what it does. - -Instead, use a run time option or a compilation switch or both -to select among the alternate behaviors. - -@cindex output device and program's behavior -Likewise, please don't make the behavior of the program depend on the -type of output device it is used with. Device independence is an -important principle of the system's design; do not compromise it merely -to save someone from typing an option now and then. (Variation in error -message syntax when using a terminal is ok, because that is a side issue -that people do not depend on.) - -If you think one behavior is most useful when the output is to a -terminal, and another is most useful when the output is a file or a -pipe, then it is usually best to make the default behavior the one that -is useful with output to a terminal, and have an option for the other -behavior. - -Compatibility requires certain programs to depend on the type of output -device. It would be disastrous if @code{ls} or @code{sh} did not do so -in the way all users expect. In some of these cases, we supplement the -program with a preferred alternate version that does not depend on the -output device type. For example, we provide a @code{dir} program much -like @code{ls} except that its default output format is always -multi-column format. - -@node Graphical Interfaces -@section Standards for Graphical Interfaces -@cindex graphical user interface - -@cindex gtk -When you write a program that provides a graphical user interface, -please make it work with X Windows and the GTK toolkit unless the -functionality specifically requires some alternative (for example, -``displaying jpeg images while in console mode''). - -In addition, please provide a command-line interface to control the -functionality. (In many cases, the graphical user interface can be a -separate program which invokes the command-line program.) This is -so that the same jobs can be done from scripts. - -@cindex corba -@cindex gnome -Please also consider providing a CORBA interface (for use from GNOME), a -library interface (for use from C), and perhaps a keyboard-driven -console interface (for use by users from console mode). Once you are -doing the work to provide the functionality and the graphical interface, -these won't be much extra work. - -@node Command-Line Interfaces -@section Standards for Command Line Interfaces -@cindex command-line interface - -@findex getopt -It is a good idea to follow the @sc{posix} guidelines for the -command-line options of a program. The easiest way to do this is to use -@code{getopt} to parse them. Note that the GNU version of @code{getopt} -will normally permit options anywhere among the arguments unless the -special argument @samp{--} is used. This is not what @sc{posix} -specifies; it is a GNU extension. - -@cindex long-named options -Please define long-named options that are equivalent to the -single-letter Unix-style options. We hope to make GNU more user -friendly this way. This is easy to do with the GNU function -@code{getopt_long}. - -One of the advantages of long-named options is that they can be -consistent from program to program. For example, users should be able -to expect the ``verbose'' option of any GNU program which has one, to be -spelled precisely @samp{--verbose}. To achieve this uniformity, look at -the table of common long-option names when you choose the option names -for your program (@pxref{Option Table}). - -It is usually a good idea for file names given as ordinary arguments to -be input files only; any output files would be specified using options -(preferably @samp{-o} or @samp{--output}). Even if you allow an output -file name as an ordinary argument for compatibility, try to provide an -option as another way to specify it. This will lead to more consistency -among GNU utilities, and fewer idiosyncracies for users to remember. - -@cindex standard command-line options -All programs should support two standard options: @samp{--version} -and @samp{--help}. - -@table @code -@cindex @samp{--version} option -@item --version -This option should direct the program to print information about its name, -version, origin and legal status, all on standard output, and then exit -successfully. Other options and arguments should be ignored once this -is seen, and the program should not perform its normal function. - -@cindex canonical name of a program -@cindex program's canonical name -The first line is meant to be easy for a program to parse; the version -number proper starts after the last space. In addition, it contains -the canonical name for this program, in this format: - -@example -GNU Emacs 19.30 -@end example - -@noindent -The program's name should be a constant string; @emph{don't} compute it -from @code{argv[0]}. The idea is to state the standard or canonical -name for the program, not its file name. There are other ways to find -out the precise file name where a command is found in @code{PATH}. - -If the program is a subsidiary part of a larger package, mention the -package name in parentheses, like this: - -@example -emacsserver (GNU Emacs) 19.30 -@end example - -@noindent -If the package has a version number which is different from this -program's version number, you can mention the package version number -just before the close-parenthesis. - -If you @strong{need} to mention the version numbers of libraries which -are distributed separately from the package which contains this program, -you can do so by printing an additional line of version info for each -library you want to mention. Use the same format for these lines as for -the first line. - -Please do not mention all of the libraries that the program uses ``just -for completeness''---that would produce a lot of unhelpful clutter. -Please mention library version numbers only if you find in practice that -they are very important to you in debugging. - -The following line, after the version number line or lines, should be a -copyright notice. If more than one copyright notice is called for, put -each on a separate line. - -Next should follow a brief statement that the program is free software, -and that users are free to copy and change it on certain conditions. If -the program is covered by the GNU GPL, say so here. Also mention that -there is no warranty, to the extent permitted by law. - -It is ok to finish the output with a list of the major authors of the -program, as a way of giving credit. - -Here's an example of output that follows these rules: - -@smallexample -GNU Emacs 19.34.5 -Copyright (C) 1996 Free Software Foundation, Inc. -GNU Emacs comes with NO WARRANTY, -to the extent permitted by law. -You may redistribute copies of GNU Emacs -under the terms of the GNU General Public License. -For more information about these matters, -see the files named COPYING. -@end smallexample - -You should adapt this to your program, of course, filling in the proper -year, copyright holder, name of program, and the references to -distribution terms, and changing the rest of the wording as necessary. - -This copyright notice only needs to mention the most recent year in -which changes were made---there's no need to list the years for previous -versions' changes. You don't have to mention the name of the program in -these notices, if that is inconvenient, since it appeared in the first -line. - -Translations of the above lines must preserve the validity of the -copyright notices (@pxref{Internationalization}). If the translation's -character set supports it, the @samp{(C)} should be replaced with the -copyright symbol, as follows: - -@ifinfo -(the official copyright symbol, which is the letter C in a circle); -@end ifinfo -@ifnotinfo -@copyright{} -@end ifnotinfo - -Write the word ``Copyright'' exactly like that, in English. Do not -translate it into another language. International treaties recognize -the English word ``Copyright''; translations into other languages do not -have legal significance. - - -@cindex @samp{--help} option -@item --help -This option should output brief documentation for how to invoke the -program, on standard output, then exit successfully. Other options and -arguments should be ignored once this is seen, and the program should -not perform its normal function. - -@cindex address for bug reports -@cindex bug reports -Near the end of the @samp{--help} option's output there should be a line -that says where to mail bug reports. It should have this format: - -@example -Report bugs to @var{mailing-address}. -@end example -@end table - -@node Option Table -@section Table of Long Options -@cindex long option names -@cindex table of long options - -Here is a table of long options used by GNU programs. It is surely -incomplete, but we aim to list all the options that a new program might -want to be compatible with. If you use names not already in the table, -please send @email{bug-standards@@gnu.org} a list of them, with their -meanings, so we can update the table. - -@c Please leave newlines between items in this table; it's much easier -@c to update when it isn't completely squashed together and unreadable. -@c When there is more than one short option for a long option name, put -@c a semicolon between the lists of the programs that use them, not a -@c period. --friedman - -@table @samp -@item after-date -@samp{-N} in @code{tar}. - -@item all -@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, -and @code{unexpand}. - -@item all-text -@samp{-a} in @code{diff}. - -@item almost-all -@samp{-A} in @code{ls}. - -@item append -@samp{-a} in @code{etags}, @code{tee}, @code{time}; -@samp{-r} in @code{tar}. - -@item archive -@samp{-a} in @code{cp}. - -@item archive-name -@samp{-n} in @code{shar}. - -@item arglength -@samp{-l} in @code{m4}. - -@item ascii -@samp{-a} in @code{diff}. - -@item assign -@samp{-v} in @code{gawk}. - -@item assume-new -@samp{-W} in Make. - -@item assume-old -@samp{-o} in Make. - -@item auto-check -@samp{-a} in @code{recode}. - -@item auto-pager -@samp{-a} in @code{wdiff}. - -@item auto-reference -@samp{-A} in @code{ptx}. - -@item avoid-wraps -@samp{-n} in @code{wdiff}. - -@item background -For server programs, run in the background. - -@item backward-search -@samp{-B} in @code{ctags}. - -@item basename -@samp{-f} in @code{shar}. - -@item batch -Used in GDB. - -@item baud -Used in GDB. - -@item before -@samp{-b} in @code{tac}. - -@item binary -@samp{-b} in @code{cpio} and @code{diff}. - -@item bits-per-code -@samp{-b} in @code{shar}. - -@item block-size -Used in @code{cpio} and @code{tar}. - -@item blocks -@samp{-b} in @code{head} and @code{tail}. - -@item break-file -@samp{-b} in @code{ptx}. - -@item brief -Used in various programs to make output shorter. - -@item bytes -@samp{-c} in @code{head}, @code{split}, and @code{tail}. - -@item c@t{++} -@samp{-C} in @code{etags}. - -@item catenate -@samp{-A} in @code{tar}. - -@item cd -Used in various programs to specify the directory to use. - -@item changes -@samp{-c} in @code{chgrp} and @code{chown}. - -@item classify -@samp{-F} in @code{ls}. - -@item colons -@samp{-c} in @code{recode}. - -@item command -@samp{-c} in @code{su}; -@samp{-x} in GDB. - -@item compare -@samp{-d} in @code{tar}. - -@item compat -Used in @code{gawk}. - -@item compress -@samp{-Z} in @code{tar} and @code{shar}. - -@item concatenate -@samp{-A} in @code{tar}. - -@item confirmation -@samp{-w} in @code{tar}. - -@item context -Used in @code{diff}. - -@item copyleft -@samp{-W copyleft} in @code{gawk}. - -@item copyright -@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}; -@samp{-W copyright} in @code{gawk}. - -@item core -Used in GDB. - -@item count -@samp{-q} in @code{who}. - -@item count-links -@samp{-l} in @code{du}. - -@item create -Used in @code{tar} and @code{cpio}. - -@item cut-mark -@samp{-c} in @code{shar}. - -@item cxref -@samp{-x} in @code{ctags}. - -@item date -@samp{-d} in @code{touch}. - -@item debug -@samp{-d} in Make and @code{m4}; -@samp{-t} in Bison. - -@item define -@samp{-D} in @code{m4}. - -@item defines -@samp{-d} in Bison and @code{ctags}. - -@item delete -@samp{-D} in @code{tar}. - -@item dereference -@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, -@code{ls}, and @code{tar}. - -@item dereference-args -@samp{-D} in @code{du}. - -@item device -Specify an I/O device (special file name). - -@item diacritics -@samp{-d} in @code{recode}. - -@item dictionary-order -@samp{-d} in @code{look}. - -@item diff -@samp{-d} in @code{tar}. - -@item digits -@samp{-n} in @code{csplit}. - -@item directory -Specify the directory to use, in various programs. In @code{ls}, it -means to show directories themselves rather than their contents. In -@code{rm} and @code{ln}, it means to not treat links to directories -specially. - -@item discard-all -@samp{-x} in @code{strip}. - -@item discard-locals -@samp{-X} in @code{strip}. - -@item dry-run -@samp{-n} in Make. - -@item ed -@samp{-e} in @code{diff}. - -@item elide-empty-files -@samp{-z} in @code{csplit}. - -@item end-delete -@samp{-x} in @code{wdiff}. - -@item end-insert -@samp{-z} in @code{wdiff}. - -@item entire-new-file -@samp{-N} in @code{diff}. - -@item environment-overrides -@samp{-e} in Make. - -@item eof -@samp{-e} in @code{xargs}. - -@item epoch -Used in GDB. - -@item error-limit -Used in @code{makeinfo}. - -@item error-output -@samp{-o} in @code{m4}. - -@item escape -@samp{-b} in @code{ls}. - -@item exclude-from -@samp{-X} in @code{tar}. - -@item exec -Used in GDB. - -@item exit -@samp{-x} in @code{xargs}. - -@item exit-0 -@samp{-e} in @code{unshar}. - -@item expand-tabs -@samp{-t} in @code{diff}. - -@item expression -@samp{-e} in @code{sed}. - -@item extern-only -@samp{-g} in @code{nm}. - -@item extract -@samp{-i} in @code{cpio}; -@samp{-x} in @code{tar}. - -@item faces -@samp{-f} in @code{finger}. - -@item fast -@samp{-f} in @code{su}. - -@item fatal-warnings -@samp{-E} in @code{m4}. - -@item file -@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar}; -@samp{-n} in @code{sed}; -@samp{-r} in @code{touch}. - -@item field-separator -@samp{-F} in @code{gawk}. - -@item file-prefix -@samp{-b} in Bison. - -@item file-type -@samp{-F} in @code{ls}. - -@item files-from -@samp{-T} in @code{tar}. - -@item fill-column -Used in @code{makeinfo}. - -@item flag-truncation -@samp{-F} in @code{ptx}. - -@item fixed-output-files -@samp{-y} in Bison. - -@item follow -@samp{-f} in @code{tail}. - -@item footnote-style -Used in @code{makeinfo}. - -@item force -@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. - -@item force-prefix -@samp{-F} in @code{shar}. - -@item foreground -For server programs, run in the foreground; -in other words, don't do anything special to run the server -in the background. - -@item format -Used in @code{ls}, @code{time}, and @code{ptx}. - -@item freeze-state -@samp{-F} in @code{m4}. - -@item fullname -Used in GDB. - -@item gap-size -@samp{-g} in @code{ptx}. - -@item get -@samp{-x} in @code{tar}. - -@item graphic -@samp{-i} in @code{ul}. - -@item graphics -@samp{-g} in @code{recode}. - -@item group -@samp{-g} in @code{install}. - -@item gzip -@samp{-z} in @code{tar} and @code{shar}. - -@item hashsize -@samp{-H} in @code{m4}. - -@item header -@samp{-h} in @code{objdump} and @code{recode} - -@item heading -@samp{-H} in @code{who}. - -@item help -Used to ask for brief usage information. - -@item here-delimiter -@samp{-d} in @code{shar}. - -@item hide-control-chars -@samp{-q} in @code{ls}. - -@item html -In @code{makeinfo}, output HTML. - -@item idle -@samp{-u} in @code{who}. - -@item ifdef -@samp{-D} in @code{diff}. - -@item ignore -@samp{-I} in @code{ls}; -@samp{-x} in @code{recode}. - -@item ignore-all-space -@samp{-w} in @code{diff}. - -@item ignore-backups -@samp{-B} in @code{ls}. - -@item ignore-blank-lines -@samp{-B} in @code{diff}. - -@item ignore-case -@samp{-f} in @code{look} and @code{ptx}; -@samp{-i} in @code{diff} and @code{wdiff}. - -@item ignore-errors -@samp{-i} in Make. - -@item ignore-file -@samp{-i} in @code{ptx}. - -@item ignore-indentation -@samp{-I} in @code{etags}. - -@item ignore-init-file -@samp{-f} in Oleo. - -@item ignore-interrupts -@samp{-i} in @code{tee}. - -@item ignore-matching-lines -@samp{-I} in @code{diff}. - -@item ignore-space-change -@samp{-b} in @code{diff}. - -@item ignore-zeros -@samp{-i} in @code{tar}. - -@item include -@samp{-i} in @code{etags}; -@samp{-I} in @code{m4}. - -@item include-dir -@samp{-I} in Make. - -@item incremental -@samp{-G} in @code{tar}. - -@item info -@samp{-i}, @samp{-l}, and @samp{-m} in Finger. - -@item init-file -In some programs, specify the name of the file to read as the user's -init file. - -@item initial -@samp{-i} in @code{expand}. - -@item initial-tab -@samp{-T} in @code{diff}. - -@item inode -@samp{-i} in @code{ls}. - -@item interactive -@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; -@samp{-e} in @code{m4}; -@samp{-p} in @code{xargs}; -@samp{-w} in @code{tar}. - -@item intermix-type -@samp{-p} in @code{shar}. - -@item iso-8601 -Used in @code{date} - -@item jobs -@samp{-j} in Make. - -@item just-print -@samp{-n} in Make. - -@item keep-going -@samp{-k} in Make. - -@item keep-files -@samp{-k} in @code{csplit}. - -@item kilobytes -@samp{-k} in @code{du} and @code{ls}. - -@item language -@samp{-l} in @code{etags}. - -@item less-mode -@samp{-l} in @code{wdiff}. - -@item level-for-gzip -@samp{-g} in @code{shar}. - -@item line-bytes -@samp{-C} in @code{split}. - -@item lines -Used in @code{split}, @code{head}, and @code{tail}. - -@item link -@samp{-l} in @code{cpio}. - -@item lint -@itemx lint-old -Used in @code{gawk}. - -@item list -@samp{-t} in @code{cpio}; -@samp{-l} in @code{recode}. - -@item list -@samp{-t} in @code{tar}. - -@item literal -@samp{-N} in @code{ls}. - -@item load-average -@samp{-l} in Make. - -@item login -Used in @code{su}. - -@item machine -No listing of which programs already use this; -someone should check to -see if any actually do, and tell @email{gnu@@gnu.org}. - -@item macro-name -@samp{-M} in @code{ptx}. - -@item mail -@samp{-m} in @code{hello} and @code{uname}. - -@item make-directories -@samp{-d} in @code{cpio}. - -@item makefile -@samp{-f} in Make. - -@item mapped -Used in GDB. - -@item max-args -@samp{-n} in @code{xargs}. - -@item max-chars -@samp{-n} in @code{xargs}. - -@item max-lines -@samp{-l} in @code{xargs}. - -@item max-load -@samp{-l} in Make. - -@item max-procs -@samp{-P} in @code{xargs}. - -@item mesg -@samp{-T} in @code{who}. - -@item message -@samp{-T} in @code{who}. - -@item minimal -@samp{-d} in @code{diff}. - -@item mixed-uuencode -@samp{-M} in @code{shar}. - -@item mode -@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. - -@item modification-time -@samp{-m} in @code{tar}. - -@item multi-volume -@samp{-M} in @code{tar}. - -@item name-prefix -@samp{-a} in Bison. - -@item nesting-limit -@samp{-L} in @code{m4}. - -@item net-headers -@samp{-a} in @code{shar}. - -@item new-file -@samp{-W} in Make. - -@item no-builtin-rules -@samp{-r} in Make. - -@item no-character-count -@samp{-w} in @code{shar}. - -@item no-check-existing -@samp{-x} in @code{shar}. - -@item no-common -@samp{-3} in @code{wdiff}. - -@item no-create -@samp{-c} in @code{touch}. - -@item no-defines -@samp{-D} in @code{etags}. - -@item no-deleted -@samp{-1} in @code{wdiff}. - -@item no-dereference -@samp{-d} in @code{cp}. - -@item no-inserted -@samp{-2} in @code{wdiff}. - -@item no-keep-going -@samp{-S} in Make. - -@item no-lines -@samp{-l} in Bison. - -@item no-piping -@samp{-P} in @code{shar}. - -@item no-prof -@samp{-e} in @code{gprof}. - -@item no-regex -@samp{-R} in @code{etags}. - -@item no-sort -@samp{-p} in @code{nm}. - -@item no-split -Used in @code{makeinfo}. - -@item no-static -@samp{-a} in @code{gprof}. - -@item no-time -@samp{-E} in @code{gprof}. - -@item no-timestamp -@samp{-m} in @code{shar}. - -@item no-validate -Used in @code{makeinfo}. - -@item no-wait -Used in @code{emacsclient}. - -@item no-warn -Used in various programs to inhibit warnings. - -@item node -@samp{-n} in @code{info}. - -@item nodename -@samp{-n} in @code{uname}. - -@item nonmatching -@samp{-f} in @code{cpio}. - -@item nstuff -@samp{-n} in @code{objdump}. - -@item null -@samp{-0} in @code{xargs}. - -@item number -@samp{-n} in @code{cat}. - -@item number-nonblank -@samp{-b} in @code{cat}. - -@item numeric-sort -@samp{-n} in @code{nm}. - -@item numeric-uid-gid -@samp{-n} in @code{cpio} and @code{ls}. - -@item nx -Used in GDB. - -@item old-archive -@samp{-o} in @code{tar}. - -@item old-file -@samp{-o} in Make. - -@item one-file-system -@samp{-l} in @code{tar}, @code{cp}, and @code{du}. - -@item only-file -@samp{-o} in @code{ptx}. - -@item only-prof -@samp{-f} in @code{gprof}. - -@item only-time -@samp{-F} in @code{gprof}. - -@item options -@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount}, -@code{fdmountd}, and @code{fdumount}. - -@item output -In various programs, specify the output file name. - -@item output-prefix -@samp{-o} in @code{shar}. - -@item override -@samp{-o} in @code{rm}. - -@item overwrite -@samp{-c} in @code{unshar}. - -@item owner -@samp{-o} in @code{install}. - -@item paginate -@samp{-l} in @code{diff}. - -@item paragraph-indent -Used in @code{makeinfo}. - -@item parents -@samp{-p} in @code{mkdir} and @code{rmdir}. - -@item pass-all -@samp{-p} in @code{ul}. - -@item pass-through -@samp{-p} in @code{cpio}. - -@item port -@samp{-P} in @code{finger}. - -@item portability -@samp{-c} in @code{cpio} and @code{tar}. - -@item posix -Used in @code{gawk}. - -@item prefix-builtins -@samp{-P} in @code{m4}. - -@item prefix -@samp{-f} in @code{csplit}. - -@item preserve -Used in @code{tar} and @code{cp}. - -@item preserve-environment -@samp{-p} in @code{su}. - -@item preserve-modification-time -@samp{-m} in @code{cpio}. - -@item preserve-order -@samp{-s} in @code{tar}. - -@item preserve-permissions -@samp{-p} in @code{tar}. - -@item print -@samp{-l} in @code{diff}. - -@item print-chars -@samp{-L} in @code{cmp}. - -@item print-data-base -@samp{-p} in Make. - -@item print-directory -@samp{-w} in Make. - -@item print-file-name -@samp{-o} in @code{nm}. - -@item print-symdefs -@samp{-s} in @code{nm}. - -@item printer -@samp{-p} in @code{wdiff}. - -@item prompt -@samp{-p} in @code{ed}. - -@item proxy -Specify an HTTP proxy. - -@item query-user -@samp{-X} in @code{shar}. - -@item question -@samp{-q} in Make. - -@item quiet -Used in many programs to inhibit the usual output. @strong{Note:} every -program accepting @samp{--quiet} should accept @samp{--silent} as a -synonym. - -@item quiet-unshar -@samp{-Q} in @code{shar} - -@item quote-name -@samp{-Q} in @code{ls}. - -@item rcs -@samp{-n} in @code{diff}. - -@item re-interval -Used in @code{gawk}. - -@item read-full-blocks -@samp{-B} in @code{tar}. - -@item readnow -Used in GDB. - -@item recon -@samp{-n} in Make. - -@item record-number -@samp{-R} in @code{tar}. - -@item recursive -Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, -and @code{rm}. - -@item reference-limit -Used in @code{makeinfo}. - -@item references -@samp{-r} in @code{ptx}. - -@item regex -@samp{-r} in @code{tac} and @code{etags}. - -@item release -@samp{-r} in @code{uname}. - -@item reload-state -@samp{-R} in @code{m4}. - -@item relocation -@samp{-r} in @code{objdump}. - -@item rename -@samp{-r} in @code{cpio}. - -@item replace -@samp{-i} in @code{xargs}. - -@item report-identical-files -@samp{-s} in @code{diff}. - -@item reset-access-time -@samp{-a} in @code{cpio}. - -@item reverse -@samp{-r} in @code{ls} and @code{nm}. - -@item reversed-ed -@samp{-f} in @code{diff}. - -@item right-side-defs -@samp{-R} in @code{ptx}. - -@item same-order -@samp{-s} in @code{tar}. - -@item same-permissions -@samp{-p} in @code{tar}. - -@item save -@samp{-g} in @code{stty}. - -@item se -Used in GDB. - -@item sentence-regexp -@samp{-S} in @code{ptx}. - -@item separate-dirs -@samp{-S} in @code{du}. - -@item separator -@samp{-s} in @code{tac}. - -@item sequence -Used by @code{recode} to chose files or pipes for sequencing passes. - -@item shell -@samp{-s} in @code{su}. - -@item show-all -@samp{-A} in @code{cat}. - -@item show-c-function -@samp{-p} in @code{diff}. - -@item show-ends -@samp{-E} in @code{cat}. - -@item show-function-line -@samp{-F} in @code{diff}. - -@item show-tabs -@samp{-T} in @code{cat}. - -@item silent -Used in many programs to inhibit the usual output. -@strong{Note:} every program accepting -@samp{--silent} should accept @samp{--quiet} as a synonym. - -@item size -@samp{-s} in @code{ls}. - -@item socket -Specify a file descriptor for a network server to use for its socket, -instead of opening and binding a new socket. This provides a way to -run, in a nonpriveledged process, a server that normally needs a -reserved port number. - -@item sort -Used in @code{ls}. - -@item source -@samp{-W source} in @code{gawk}. - -@item sparse -@samp{-S} in @code{tar}. - -@item speed-large-files -@samp{-H} in @code{diff}. - -@item split-at -@samp{-E} in @code{unshar}. - -@item split-size-limit -@samp{-L} in @code{shar}. - -@item squeeze-blank -@samp{-s} in @code{cat}. - -@item start-delete -@samp{-w} in @code{wdiff}. - -@item start-insert -@samp{-y} in @code{wdiff}. - -@item starting-file -Used in @code{tar} and @code{diff} to specify which file within -a directory to start processing with. - -@item statistics -@samp{-s} in @code{wdiff}. - -@item stdin-file-list -@samp{-S} in @code{shar}. - -@item stop -@samp{-S} in Make. - -@item strict -@samp{-s} in @code{recode}. - -@item strip -@samp{-s} in @code{install}. - -@item strip-all -@samp{-s} in @code{strip}. - -@item strip-debug -@samp{-S} in @code{strip}. - -@item submitter -@samp{-s} in @code{shar}. - -@item suffix -@samp{-S} in @code{cp}, @code{ln}, @code{mv}. - -@item suffix-format -@samp{-b} in @code{csplit}. - -@item sum -@samp{-s} in @code{gprof}. - -@item summarize -@samp{-s} in @code{du}. - -@item symbolic -@samp{-s} in @code{ln}. - -@item symbols -Used in GDB and @code{objdump}. - -@item synclines -@samp{-s} in @code{m4}. - -@item sysname -@samp{-s} in @code{uname}. - -@item tabs -@samp{-t} in @code{expand} and @code{unexpand}. - -@item tabsize -@samp{-T} in @code{ls}. - -@item terminal -@samp{-T} in @code{tput} and @code{ul}. -@samp{-t} in @code{wdiff}. - -@item text -@samp{-a} in @code{diff}. - -@item text-files -@samp{-T} in @code{shar}. - -@item time -Used in @code{ls} and @code{touch}. - -@item timeout -Specify how long to wait before giving up on some operation. - -@item to-stdout -@samp{-O} in @code{tar}. - -@item total -@samp{-c} in @code{du}. - -@item touch -@samp{-t} in Make, @code{ranlib}, and @code{recode}. - -@item trace -@samp{-t} in @code{m4}. - -@item traditional -@samp{-t} in @code{hello}; -@samp{-W traditional} in @code{gawk}; -@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. - -@item tty -Used in GDB. - -@item typedefs -@samp{-t} in @code{ctags}. - -@item typedefs-and-c++ -@samp{-T} in @code{ctags}. - -@item typeset-mode -@samp{-t} in @code{ptx}. - -@item uncompress -@samp{-z} in @code{tar}. - -@item unconditional -@samp{-u} in @code{cpio}. - -@item undefine -@samp{-U} in @code{m4}. - -@item undefined-only -@samp{-u} in @code{nm}. - -@item update -@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. - -@item usage -Used in @code{gawk}; same as @samp{--help}. - -@item uuencode -@samp{-B} in @code{shar}. - -@item vanilla-operation -@samp{-V} in @code{shar}. - -@item verbose -Print more information about progress. Many programs support this. - -@item verify -@samp{-W} in @code{tar}. - -@item version -Print the version number. - -@item version-control -@samp{-V} in @code{cp}, @code{ln}, @code{mv}. - -@item vgrind -@samp{-v} in @code{ctags}. - -@item volume -@samp{-V} in @code{tar}. - -@item what-if -@samp{-W} in Make. - -@item whole-size-limit -@samp{-l} in @code{shar}. - -@item width -@samp{-w} in @code{ls} and @code{ptx}. - -@item word-regexp -@samp{-W} in @code{ptx}. - -@item writable -@samp{-T} in @code{who}. - -@item zeros -@samp{-z} in @code{gprof}. -@end table - -@node Memory Usage -@section Memory Usage -@cindex memory usage - -If a program typically uses just a few meg of memory, don't bother making any -effort to reduce memory usage. For example, if it is impractical for -other reasons to operate on files more than a few meg long, it is -reasonable to read entire input files into core to operate on them. - -However, for programs such as @code{cat} or @code{tail}, that can -usefully operate on very large files, it is important to avoid using a -technique that would artificially limit the size of files it can handle. -If a program works by lines and could be applied to arbitrary -user-supplied input files, it should keep only a line in memory, because -this is not very hard and users will want to be able to operate on input -files that are bigger than will fit in core all at once. - -If your program creates complicated data structures, just make them in -core and give a fatal error if @code{malloc} returns zero. - -@node File Usage -@section File Usage -@cindex file usage - -Programs should be prepared to operate when @file{/usr} and @file{/etc} -are read-only file systems. Thus, if the program manages log files, -lock files, backup files, score files, or any other files which are -modified for internal purposes, these files should not be stored in -@file{/usr} or @file{/etc}. - -There are two exceptions. @file{/etc} is used to store system -configuration information; it is reasonable for a program to modify -files in @file{/etc} when its job is to update the system configuration. -Also, if the user explicitly asks to modify one file in a directory, it -is reasonable for the program to store other files in the same -directory. - -@node Writing C -@chapter Making The Best Use of C - -This @value{CHAPTER} provides advice on how best to use the C language -when writing GNU software. - -@menu -* Formatting:: Formatting Your Source Code -* Comments:: Commenting Your Work -* Syntactic Conventions:: Clean Use of C Constructs -* Names:: Naming Variables, Functions, and Files -* System Portability:: Portability between different operating systems -* CPU Portability:: Supporting the range of CPU types -* System Functions:: Portability and ``standard'' library functions -* Internationalization:: Techniques for internationalization -* Mmap:: How you can safely use @code{mmap}. -@end menu - -@node Formatting -@section Formatting Your Source Code -@cindex formatting source code - -@cindex open brace -@cindex braces, in C source -It is important to put the open-brace that starts the body of a C -function in column zero, and avoid putting any other open-brace or -open-parenthesis or open-bracket in column zero. Several tools look -for open-braces in column zero to find the beginnings of C functions. -These tools will not work on code not formatted that way. - -It is also important for function definitions to start the name of the -function in column zero. This helps people to search for function -definitions, and may also help certain tools recognize them. Thus, -the proper format is this: - -@example -static char * -concat (s1, s2) /* Name starts in column zero here */ - char *s1, *s2; -@{ /* Open brace in column zero here */ - @dots{} -@} -@end example - -@noindent -or, if you want to use Standard C syntax, format the definition like -this: - -@example -static char * -concat (char *s1, char *s2) -@{ - @dots{} -@} -@end example - -In Standard C, if the arguments don't fit nicely on one line, -split it like this: - -@example -int -lots_of_args (int an_integer, long a_long, short a_short, - double a_double, float a_float) -@dots{} -@end example - -The rest of this section gives our recommendations for other aspects of -C formatting style, which is also the default style of the @code{indent} -program in version 1.2 and newer. It corresponds to the options - -@smallexample --nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 --ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob -@end smallexample - -We don't think of these recommendations as requirements, because it -causes no problems for users if two different programs have different -formatting styles. - -But whatever style you use, please use it consistently, since a mixture -of styles within one program tends to look ugly. If you are -contributing changes to an existing program, please follow the style of -that program. - -For the body of the function, our recommended style looks like this: - -@example -if (x < foo (y, z)) - haha = bar[4] + 5; -else - @{ - while (z) - @{ - haha += foo (z, z); - z--; - @} - return ++x + bar (); - @} -@end example - -@cindex spaces before open-paren -We find it easier to read a program when it has spaces before the -open-parentheses and after the commas. Especially after the commas. - -When you split an expression into multiple lines, split it -before an operator, not after one. Here is the right way: - -@cindex expressions, splitting -@example -if (foo_this_is_long && bar > win (x, y, z) - && remaining_condition) -@end example - -Try to avoid having two operators of different precedence at the same -level of indentation. For example, don't write this: - -@example -mode = (inmode[j] == VOIDmode - || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) - ? outmode[j] : inmode[j]); -@end example - -Instead, use extra parentheses so that the indentation shows the nesting: - -@example -mode = ((inmode[j] == VOIDmode - || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) - ? outmode[j] : inmode[j]); -@end example - -Insert extra parentheses so that Emacs will indent the code properly. -For example, the following indentation looks nice if you do it by hand, - -@example -v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 - + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; -@end example - -@noindent -but Emacs would alter it. Adding a set of parentheses produces -something that looks equally nice, and which Emacs will preserve: - -@example -v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 - + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); -@end example - -Format do-while statements like this: - -@example -do - @{ - a = foo (a); - @} -while (a > 0); -@end example - -@cindex formfeed -@cindex control-L -Please use formfeed characters (control-L) to divide the program into -pages at logical places (but not within a function). It does not matter -just how long the pages are, since they do not have to fit on a printed -page. The formfeeds should appear alone on lines by themselves. - -@node Comments -@section Commenting Your Work -@cindex commenting - -Every program should start with a comment saying briefly what it is for. -Example: @samp{fmt - filter for simple filling of text}. - -Please write the comments in a GNU program in English, because English -is the one language that nearly all programmers in all countries can -read. If you do not write English well, please write comments in -English as well as you can, then ask other people to help rewrite them. -If you can't write comments in English, please find someone to work with -you and translate your comments into English. - -Please put a comment on each function saying what the function does, -what sorts of arguments it gets, and what the possible values of -arguments mean and are used for. It is not necessary to duplicate in -words the meaning of the C argument declarations, if a C type is being -used in its customary fashion. If there is anything nonstandard about -its use (such as an argument of type @code{char *} which is really the -address of the second character of a string, not the first), or any -possible values that would not work the way one would expect (such as, -that strings containing newlines are not guaranteed to work), be sure -to say so. - -Also explain the significance of the return value, if there is one. - -Please put two spaces after the end of a sentence in your comments, so -that the Emacs sentence commands will work. Also, please write -complete sentences and capitalize the first word. If a lower-case -identifier comes at the beginning of a sentence, don't capitalize it! -Changing the spelling makes it a different identifier. If you don't -like starting a sentence with a lower case letter, write the sentence -differently (e.g., ``The identifier lower-case is @dots{}''). - -The comment on a function is much clearer if you use the argument -names to speak about the argument values. The variable name itself -should be lower case, but write it in upper case when you are speaking -about the value rather than the variable itself. Thus, ``the inode -number NODE_NUM'' rather than ``an inode''. - -There is usually no purpose in restating the name of the function in -the comment before it, because the reader can see that for himself. -There might be an exception when the comment is so long that the function -itself would be off the bottom of the screen. - -There should be a comment on each static variable as well, like this: - -@example -/* Nonzero means truncate lines in the display; - zero means continue them. */ -int truncate_lines; -@end example - -@cindex conditionals, comments for -@cindex @code{#endif}, commenting -Every @samp{#endif} should have a comment, except in the case of short -conditionals (just a few lines) that are not nested. The comment should -state the condition of the conditional that is ending, @emph{including -its sense}. @samp{#else} should have a comment describing the condition -@emph{and sense} of the code that follows. For example: - -@example -@group -#ifdef foo - @dots{} -#else /* not foo */ - @dots{} -#endif /* not foo */ -@end group -@group -#ifdef foo - @dots{} -#endif /* foo */ -@end group -@end example - -@noindent -but, by contrast, write the comments this way for a @samp{#ifndef}: - -@example -@group -#ifndef foo - @dots{} -#else /* foo */ - @dots{} -#endif /* foo */ -@end group -@group -#ifndef foo - @dots{} -#endif /* not foo */ -@end group -@end example - -@node Syntactic Conventions -@section Clean Use of C Constructs -@cindex syntactic conventions - -@cindex implicit @code{int} -@cindex function argument, declaring -Please explicitly declare the types of all objects. For example, you -should explicitly declare all arguments to functions, and you should -declare functions to return @code{int} rather than omitting the -@code{int}. - -@cindex compiler warnings -@cindex @samp{-Wall} compiler option -Some programmers like to use the GCC @samp{-Wall} option, and change the -code whenever it issues a warning. If you want to do this, then do. -Other programmers prefer not to use @samp{-Wall}, because it gives -warnings for valid and legitimate code which they do not want to change. -If you want to do this, then do. The compiler should be your servant, -not your master. - -Declarations of external functions and functions to appear later in the -source file should all go in one place near the beginning of the file -(somewhere before the first function definition in the file), or else -should go in a header file. Don't put @code{extern} declarations inside -functions. - -@cindex temporary variables -It used to be common practice to use the same local variables (with -names like @code{tem}) over and over for different values within one -function. Instead of doing this, it is better declare a separate local -variable for each distinct purpose, and give it a name which is -meaningful. This not only makes programs easier to understand, it also -facilitates optimization by good compilers. You can also move the -declaration of each local variable into the smallest scope that includes -all its uses. This makes the program even cleaner. - -Don't use local variables or parameters that shadow global identifiers. - -@cindex multiple variables in a line -Don't declare multiple variables in one declaration that spans lines. -Start a new declaration on each line, instead. For example, instead -of this: - -@example -@group -int foo, - bar; -@end group -@end example - -@noindent -write either this: - -@example -int foo, bar; -@end example - -@noindent -or this: - -@example -int foo; -int bar; -@end example - -@noindent -(If they are global variables, each should have a comment preceding it -anyway.) - -When you have an @code{if}-@code{else} statement nested in another -@code{if} statement, always put braces around the @code{if}-@code{else}. -Thus, never write like this: - -@example -if (foo) - if (bar) - win (); - else - lose (); -@end example - -@noindent -always like this: - -@example -if (foo) - @{ - if (bar) - win (); - else - lose (); - @} -@end example - -If you have an @code{if} statement nested inside of an @code{else} -statement, either write @code{else if} on one line, like this, - -@example -if (foo) - @dots{} -else if (bar) - @dots{} -@end example - -@noindent -with its @code{then}-part indented like the preceding @code{then}-part, -or write the nested @code{if} within braces like this: - -@example -if (foo) - @dots{} -else - @{ - if (bar) - @dots{} - @} -@end example - -Don't declare both a structure tag and variables or typedefs in the -same declaration. Instead, declare the structure tag separately -and then use it to declare the variables or typedefs. - -Try to avoid assignments inside @code{if}-conditions. For example, -don't write this: - -@example -if ((foo = (char *) malloc (sizeof *foo)) == 0) - fatal ("virtual memory exhausted"); -@end example - -@noindent -instead, write this: - -@example -foo = (char *) malloc (sizeof *foo); -if (foo == 0) - fatal ("virtual memory exhausted"); -@end example - -@pindex lint -Don't make the program ugly to placate @code{lint}. Please don't insert any -casts to @code{void}. Zero without a cast is perfectly fine as a null -pointer constant, except when calling a varargs function. - -@node Names -@section Naming Variables, Functions, and Files - -@cindex names of variables, functions, and files -The names of global variables and functions in a program serve as -comments of a sort. So don't choose terse names---instead, look for -names that give useful information about the meaning of the variable or -function. In a GNU program, names should be English, like other -comments. - -Local variable names can be shorter, because they are used only within -one context, where (presumably) comments explain their purpose. - -Try to limit your use of abbreviations in symbol names. It is ok to -make a few abbreviations, explain what they mean, and then use them -frequently, but don't use lots of obscure abbreviations. - -Please use underscores to separate words in a name, so that the Emacs -word commands can be useful within them. Stick to lower case; reserve -upper case for macros and @code{enum} constants, and for name-prefixes -that follow a uniform convention. - -For example, you should use names like @code{ignore_space_change_flag}; -don't use names like @code{iCantReadThis}. - -Variables that indicate whether command-line options have been -specified should be named after the meaning of the option, not after -the option-letter. A comment should state both the exact meaning of -the option and its letter. For example, - -@example -@group -/* Ignore changes in horizontal whitespace (-b). */ -int ignore_space_change_flag; -@end group -@end example - -When you want to define names with constant integer values, use -@code{enum} rather than @samp{#define}. GDB knows about enumeration -constants. - -@cindex file-name limitations -@pindex doschk -You might want to make sure that none of the file names would conflict -the files were loaded onto an MS-DOS file system which shortens the -names. You can use the program @code{doschk} to test for this. - -Some GNU programs were designed to limit themselves to file names of 14 -characters or less, to avoid file name conflicts if they are read into -older System V systems. Please preserve this feature in the existing -GNU programs that have it, but there is no need to do this in new GNU -programs. @code{doschk} also reports file names longer than 14 -characters. - -@node System Portability -@section Portability between System Types -@cindex portability, between system types - -In the Unix world, ``portability'' refers to porting to different Unix -versions. For a GNU program, this kind of portability is desirable, but -not paramount. - -The primary purpose of GNU software is to run on top of the GNU kernel, -compiled with the GNU C compiler, on various types of @sc{cpu}. So the -kinds of portability that are absolutely necessary are quite limited. -But it is important to support Linux-based GNU systems, since they -are the form of GNU that is popular. - -Beyond that, it is good to support the other free operating systems -(*BSD), and it is nice to support other Unix-like systems if you want -to. Supporting a variety of Unix-like systems is desirable, although -not paramount. It is usually not too hard, so you may as well do it. -But you don't have to consider it an obligation, if it does turn out to -be hard. - -@pindex autoconf -The easiest way to achieve portability to most Unix-like systems is to -use Autoconf. It's unlikely that your program needs to know more -information about the host platform than Autoconf can provide, simply -because most of the programs that need such knowledge have already been -written. - -Avoid using the format of semi-internal data bases (e.g., directories) -when there is a higher-level alternative (@code{readdir}). - -@cindex non-@sc{posix} systems, and portability -As for systems that are not like Unix, such as MSDOS, Windows, the -Macintosh, VMS, and MVS, supporting them is often a lot of work. When -that is the case, it is better to spend your time adding features that -will be useful on GNU and GNU/Linux, rather than on supporting other -incompatible systems. - -It is a good idea to define the ``feature test macro'' -@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU -or GNU/Linux, this will enable the declarations of GNU library extension -functions, and that will usually give you a compiler error message if -you define the same function names in some other way in your program. -(You don't have to actually @emph{use} these functions, if you prefer -to make the program more portable to other systems.) - -But whether or not you use these GNU extensions, you should avoid -using their names for any other meanings. Doing so would make it hard -to move your code into other GNU programs. - -@node CPU Portability -@section Portability between @sc{cpu}s - -@cindex data types, and portability -@cindex portability, and data types -Even GNU systems will differ because of differences among @sc{cpu} -types---for example, difference in byte ordering and alignment -requirements. It is absolutely essential to handle these differences. -However, don't make any effort to cater to the possibility that an -@code{int} will be less than 32 bits. We don't support 16-bit machines -in GNU. - -Similarly, don't make any effort to cater to the possibility that -@code{long} will be smaller than predefined types like @code{size_t}. -For example, the following code is ok: - -@example -printf ("size = %lu\n", (unsigned long) sizeof array); -printf ("diff = %ld\n", (long) (pointer2 - pointer1)); -@end example - -1989 Standard C requires this to work, and we know of only one -counterexample: 64-bit programs on Microsoft Windows IA-64. We will -leave it to those who want to port GNU programs to that environment -to figure out how to do it. - -Predefined file-size types like @code{off_t} are an exception: they are -longer than @code{long} on many platforms, so code like the above won't -work with them. One way to print an @code{off_t} value portably is to -print its digits yourself, one by one. - -Don't assume that the address of an @code{int} object is also the -address of its least-significant byte. This is false on big-endian -machines. Thus, don't make the following mistake: - -@example -int c; -@dots{} -while ((c = getchar()) != EOF) - write(file_descriptor, &c, 1); -@end example - -When calling functions, you need not worry about the difference between -pointers of various types, or between pointers and integers. On most -machines, there's no difference anyway. As for the few machines where -there is a difference, all of them support Standard C prototypes, so you can -use prototypes (perhaps conditionalized to be active only in Standard C) -to make the code work on those systems. - -In certain cases, it is ok to pass integer and pointer arguments -indiscriminately to the same function, and use no prototype on any -system. For example, many GNU programs have error-reporting functions -that pass their arguments along to @code{printf} and friends: - -@example -error (s, a1, a2, a3) - char *s; - char *a1, *a2, *a3; -@{ - fprintf (stderr, "error: "); - fprintf (stderr, s, a1, a2, a3); -@} -@end example - -@noindent -In practice, this works on all machines, since a pointer is generally -the widest possible kind of argument; it is much simpler than any -``correct'' alternative. Be sure @emph{not} to use a prototype for such -functions. - -If you have decided to use Standard C, then you can instead define -@code{error} using @file{stdarg.h}, and pass the arguments along to -@code{vfprintf}. - -@cindex casting pointers to integers -Avoid casting pointers to integers if you can. Such casts greatly -reduce portability, and in most programs they are easy to avoid. In the -cases where casting pointers to integers is essential---such as, a Lisp -interpreter which stores type information as well as an address in one -word---you'll have to make explicit provisions to handle different word -sizes. You will also need to make provision for systems in which the -normal range of addresses you can get from @code{malloc} starts far away -from zero. - -@node System Functions -@section Calling System Functions -@cindex library functions, and portability -@cindex portability, and library functions - -C implementations differ substantially. Standard C reduces but does -not eliminate the incompatibilities; meanwhile, many GNU packages still -support pre-standard compilers because this is not hard to do. This -chapter gives recommendations for how to use the more-or-less standard C -library functions to avoid unnecessary loss of portability. - -@itemize @bullet -@item -Don't use the return value of @code{sprintf}. It returns the number of -characters written on some systems, but not on all systems. - -@item -Be aware that @code{vfprintf} is not always available. - -@item -@code{main} should be declared to return type @code{int}. It should -terminate either by calling @code{exit} or by returning the integer -status code; make sure it cannot ever return an undefined value. - -@cindex declaration for system functions -@item -Don't declare system functions explicitly. - -Almost any declaration for a system function is wrong on some system. -To minimize conflicts, leave it to the system header files to declare -system functions. If the headers don't declare a function, let it -remain undeclared. - -While it may seem unclean to use a function without declaring it, in -practice this works fine for most system library functions on the -systems where this really happens; thus, the disadvantage is only -theoretical. By contrast, actual declarations have frequently caused -actual conflicts. - -@item -If you must declare a system function, don't specify the argument types. -Use an old-style declaration, not a Standard C prototype. The more you -specify about the function, the more likely a conflict. - -@item -In particular, don't unconditionally declare @code{malloc} or -@code{realloc}. - -Most GNU programs use those functions just once, in functions -conventionally named @code{xmalloc} and @code{xrealloc}. These -functions call @code{malloc} and @code{realloc}, respectively, and -check the results. - -Because @code{xmalloc} and @code{xrealloc} are defined in your program, -you can declare them in other files without any risk of type conflict. - -On most systems, @code{int} is the same length as a pointer; thus, the -calls to @code{malloc} and @code{realloc} work fine. For the few -exceptional systems (mostly 64-bit machines), you can use -@strong{conditionalized} declarations of @code{malloc} and -@code{realloc}---or put these declarations in configuration files -specific to those systems. - -@cindex string library functions -@item -The string functions require special treatment. Some Unix systems have -a header file @file{string.h}; others have @file{strings.h}. Neither -file name is portable. There are two things you can do: use Autoconf to -figure out which file to include, or don't include either file. - -@item -If you don't include either strings file, you can't get declarations for -the string functions from the header file in the usual way. - -That causes less of a problem than you might think. The newer standard -string functions should be avoided anyway because many systems still -don't support them. The string functions you can use are these: - -@example -strcpy strncpy strcat strncat -strlen strcmp strncmp -strchr strrchr -@end example - -The copy and concatenate functions work fine without a declaration as -long as you don't use their values. Using their values without a -declaration fails on systems where the width of a pointer differs from -the width of @code{int}, and perhaps in other cases. It is trivial to -avoid using their values, so do that. - -The compare functions and @code{strlen} work fine without a declaration -on most systems, possibly all the ones that GNU software runs on. -You may find it necessary to declare them @strong{conditionally} on a -few systems. - -The search functions must be declared to return @code{char *}. Luckily, -there is no variation in the data type they return. But there is -variation in their names. Some systems give these functions the names -@code{index} and @code{rindex}; other systems use the names -@code{strchr} and @code{strrchr}. Some systems support both pairs of -names, but neither pair works on all systems. - -You should pick a single pair of names and use it throughout your -program. (Nowadays, it is better to choose @code{strchr} and -@code{strrchr} for new programs, since those are the standard -names.) Declare both of those names as functions returning @code{char -*}. On systems which don't support those names, define them as macros -in terms of the other pair. For example, here is what to put at the -beginning of your file (or in a header) if you want to use the names -@code{strchr} and @code{strrchr} throughout: - -@example -#ifndef HAVE_STRCHR -#define strchr index -#endif -#ifndef HAVE_STRRCHR -#define strrchr rindex -#endif - -char *strchr (); -char *strrchr (); -@end example -@end itemize - -Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are -macros defined in systems where the corresponding functions exist. -One way to get them properly defined is to use Autoconf. - -@node Internationalization -@section Internationalization -@cindex internationalization - -@pindex gettext -GNU has a library called GNU gettext that makes it easy to translate the -messages in a program into various languages. You should use this -library in every program. Use English for the messages as they appear -in the program, and let gettext provide the way to translate them into -other languages. - -Using GNU gettext involves putting a call to the @code{gettext} macro -around each string that might need translation---like this: - -@example -printf (gettext ("Processing file `%s'...")); -@end example - -@noindent -This permits GNU gettext to replace the string @code{"Processing file -`%s'..."} with a translated version. - -Once a program uses gettext, please make a point of writing calls to -@code{gettext} when you add new strings that call for translation. - -Using GNU gettext in a package involves specifying a @dfn{text domain -name} for the package. The text domain name is used to separate the -translations for this package from the translations for other packages. -Normally, the text domain name should be the same as the name of the -package---for example, @samp{fileutils} for the GNU file utilities. - -@cindex message text, and internationalization -To enable gettext to work well, avoid writing code that makes -assumptions about the structure of words or sentences. When you want -the precise text of a sentence to vary depending on the data, use two or -more alternative string constants each containing a complete sentences, -rather than inserting conditionalized words or phrases into a single -sentence framework. - -Here is an example of what not to do: - -@example -printf ("%d file%s processed", nfiles, - nfiles != 1 ? "s" : ""); -@end example - -@noindent -The problem with that example is that it assumes that plurals are made -by adding `s'. If you apply gettext to the format string, like this, - -@example -printf (gettext ("%d file%s processed"), nfiles, - nfiles != 1 ? "s" : ""); -@end example - -@noindent -the message can use different words, but it will still be forced to use -`s' for the plural. Here is a better way: - -@example -printf ((nfiles != 1 ? "%d files processed" - : "%d file processed"), - nfiles); -@end example - -@noindent -This way, you can apply gettext to each of the two strings -independently: - -@example -printf ((nfiles != 1 ? gettext ("%d files processed") - : gettext ("%d file processed")), - nfiles); -@end example - -@noindent -This can be any method of forming the plural of the word for ``file'', and -also handles languages that require agreement in the word for -``processed''. - -A similar problem appears at the level of sentence structure with this -code: - -@example -printf ("# Implicit rule search has%s been done.\n", - f->tried_implicit ? "" : " not"); -@end example - -@noindent -Adding @code{gettext} calls to this code cannot give correct results for -all languages, because negation in some languages requires adding words -at more than one place in the sentence. By contrast, adding -@code{gettext} calls does the job straightfowardly if the code starts -out like this: - -@example -printf (f->tried_implicit - ? "# Implicit rule search has been done.\n", - : "# Implicit rule search has not been done.\n"); -@end example - -@node Mmap -@section Mmap -@findex mmap - -Don't assume that @code{mmap} either works on all files or fails -for all files. It may work on some files and fail on others. - -The proper way to use @code{mmap} is to try it on the specific file for -which you want to use it---and if @code{mmap} doesn't work, fall back on -doing the job in another way using @code{read} and @code{write}. - -The reason this precaution is needed is that the GNU kernel (the HURD) -provides a user-extensible file system, in which there can be many -different kinds of ``ordinary files.'' Many of them support -@code{mmap}, but some do not. It is important to make programs handle -all these kinds of files. - -@node Documentation -@chapter Documenting Programs -@cindex documentation - -A GNU program should ideally come with full free documentation, adequate -for both reference and tutorial purposes. If the package can be -programmed or extended, the documentation should cover programming or -extending it, as well as just using it. - -@menu -* GNU Manuals:: Writing proper manuals. -* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual. -* Manual Structure Details:: Specific structure conventions. -* License for Manuals:: Writing the distribution terms for a manual. -* Manual Credits:: Giving credit to documentation contributors. -* Printed Manuals:: Mentioning the printed manual. -* NEWS File:: NEWS files supplement manuals. -* Change Logs:: Recording Changes -* Man Pages:: Man pages are secondary. -* Reading other Manuals:: How far you can go in learning - from other manuals. -@end menu - -@node GNU Manuals -@section GNU Manuals - -The preferred document format for the GNU system is the Texinfo -formatting language. Every GNU package should (ideally) have -documentation in Texinfo both for reference and for learners. Texinfo -makes it possible to produce a good quality formatted book, using -@TeX{}, and to generate an Info file. It is also possible to generate -HTML output from Texinfo source. See the Texinfo manual, either the -hardcopy, or the on-line version available through @code{info} or the -Emacs Info subsystem (@kbd{C-h i}). - -Nowadays some other formats such as Docbook and Sgmltexi can be -converted automatically into Texinfo. It is ok to produce the Texinfo -documentation by conversion this way, as long as it gives good results. - -Programmers often find it most natural to structure the documentation -following the structure of the implementation, which they know. But -this structure is not necessarily good for explaining how to use the -program; it may be irrelevant and confusing for a user. - -At every level, from the sentences in a paragraph to the grouping of -topics into separate manuals, the right way to structure documentation -is according to the concepts and questions that a user will have in mind -when reading it. Sometimes this structure of ideas matches the -structure of the implementation of the software being documented---but -often they are different. Often the most important part of learning to -write good documentation is learning to notice when you are structuring -the documentation like the implementation, and think about better -alternatives. - -For example, each program in the GNU system probably ought to be -documented in one manual; but this does not mean each program should -have its own manual. That would be following the structure of the -implementation, rather than the structure that helps the user -understand. - -Instead, each manual should cover a coherent @emph{topic}. For example, -instead of a manual for @code{diff} and a manual for @code{diff3}, we -have one manual for ``comparison of files'' which covers both of those -programs, as well as @code{cmp}. By documenting these programs -together, we can make the whole subject clearer. - -The manual which discusses a program should certainly document all of -the program's command-line options and all of its commands. It should -give examples of their use. But don't organize the manual as a list of -features. Instead, organize it logically, by subtopics. Address the -questions that a user will ask when thinking about the job that the -program does. - -In general, a GNU manual should serve both as tutorial and reference. -It should be set up for convenient access to each topic through Info, -and for reading straight through (appendixes aside). A GNU manual -should give a good introduction to a beginner reading through from the -start, and should also provide all the details that hackers want. -The Bison manual is a good example of this---please take a look at it -to see what we mean. - -That is not as hard as it first sounds. Arrange each chapter as a -logical breakdown of its topic, but order the sections, and write their -text, so that reading the chapter straight through makes sense. Do -likewise when structuring the book into chapters, and when structuring a -section into paragraphs. The watchword is, @emph{at each point, address -the most fundamental and important issue raised by the preceding text.} - -If necessary, add extra chapters at the beginning of the manual which -are purely tutorial and cover the basics of the subject. These provide -the framework for a beginner to understand the rest of the manual. The -Bison manual provides a good example of how to do this. - -To serve as a reference, a manual should have an Index that list all the -functions, variables, options, and important concepts that are part of -the program. One combined Index should do for a short manual, but -sometimes for a complex package it is better to use multiple indices. -The Texinfo manual includes advice on preparing good index entries, see -@ref{Index Entries, , Making Index Entries, texinfo, The GNU Texinfo -Manual}, and see @ref{Indexing Commands, , Defining the Entries of an -Index, texinfo, The GNU Texinfo manual}. - -Don't use Unix man pages as a model for how to write GNU documentation; -most of them are terse, badly structured, and give inadequate -explanation of the underlying concepts. (There are, of course, some -exceptions.) Also, Unix man pages use a particular format which is -different from what we use in GNU manuals. - -Please include an email address in the manual for where to report -bugs @emph{in the manual}. - -Please do not use the term ``pathname'' that is used in Unix -documentation; use ``file name'' (two words) instead. We use the term -``path'' only for search paths, which are lists of directory names. - -Please do not use the term ``illegal'' to refer to erroneous input to a -computer program. Please use ``invalid'' for this, and reserve the term -``illegal'' for activities punishable by law. - -@node Doc Strings and Manuals -@section Doc Strings and Manuals - -Some programming systems, such as Emacs, provide a documentation string -for each function, command or variable. You may be tempted to write a -reference manual by compiling the documentation strings and writing a -little additional text to go around them---but you must not do it. That -approach is a fundamental mistake. The text of well-written -documentation strings will be entirely wrong for a manual. - -A documentation string needs to stand alone---when it appears on the -screen, there will be no other text to introduce or explain it. -Meanwhile, it can be rather informal in style. - -The text describing a function or variable in a manual must not stand -alone; it appears in the context of a section or subsection. Other text -at the beginning of the section should explain some of the concepts, and -should often make some general points that apply to several functions or -variables. The previous descriptions of functions and variables in the -section will also have given information about the topic. A description -written to stand alone would repeat some of that information; this -redundance looks bad. Meanwhile, the informality that is acceptable in -a documentation string is totally unacceptable in a manual. - -The only good way to use documentation strings in writing a good manual -is to use them as a source of information for writing good text. - -@node Manual Structure Details -@section Manual Structure Details -@cindex manual structure - -The title page of the manual should state the version of the programs or -packages documented in the manual. The Top node of the manual should -also contain this information. If the manual is changing more -frequently than or independent of the program, also state a version -number for the manual in both of these places. - -Each program documented in the manual should have a node named -@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This -node (together with its subnodes, if any) should describe the program's -command line arguments and how to run it (the sort of information people -would look in a man page for). Start with an @samp{@@example} -containing a template for all the options and arguments that the program -uses. - -Alternatively, put a menu item in some menu whose item name fits one of -the above patterns. This identifies the node which that item points to -as the node for this purpose, regardless of the node's actual name. - -The @samp{--usage} feature of the Info reader looks for such a node -or menu item in order to find the relevant text, so it is essential -for every Texinfo file to have one. - -If one manual describes several programs, it should have such a node for -each program described in the manual. - -@node License for Manuals -@section License for Manuals -@cindex license for manuals - -Please use the GNU Free Documentation License for all GNU manuals that -are more than a few pages long. Likewise for a collection of short -documents---you only need one copy of the GNU FDL for the whole -collection. For a single short document, you can use a very permissive -non-copyleft license, to avoid taking up space with a long license. - -See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation -of how to employ the GFDL. - -Note that it is not obligatory to include a copy of the GNU GPL or GNU -LGPL in a manual whose license is neither the GPL nor the LGPL. It can -be a good idea to include the program's license in a large manual; in a -short manual, whose size would be increased considerably by including -the program's license, it is probably better not to include it. - -@node Manual Credits -@section Manual Credits -@cindex credits for manuals - -Please credit the principal human writers of the manual as the authors, -on the title page of the manual. If a company sponsored the work, thank -the company in a suitable place in the manual, but do not cite the -company as an author. - -@node Printed Manuals -@section Printed Manuals - -The FSF publishes some GNU manuals in printed form. To encourage sales -of these manuals, the on-line versions of the manual should mention at -the very start that the printed manual is available and should point at -information for getting it---for instance, with a link to the page -@url{http://www.gnu.org/order/order.html}. This should not be included -in the printed manual, though, because there it is redundant. - -It is also useful to explain in the on-line forms of the manual how the -user can print out the manual from the sources. - -@node NEWS File -@section The NEWS File -@cindex @file{NEWS} file - -In addition to its manual, the package should have a file named -@file{NEWS} which contains a list of user-visible changes worth -mentioning. In each new release, add items to the front of the file and -identify the version they pertain to. Don't discard old items; leave -them in the file after the newer items. This way, a user upgrading from -any previous version can see what is new. - -If the @file{NEWS} file gets very long, move some of the older items -into a file named @file{ONEWS} and put a note at the end referring the -user to that file. - -@node Change Logs -@section Change Logs -@cindex change logs - -Keep a change log to describe all the changes made to program source -files. The purpose of this is so that people investigating bugs in the -future will know about the changes that might have introduced the bug. -Often a new bug can be found by looking at what was recently changed. -More importantly, change logs can help you eliminate conceptual -inconsistencies between different parts of a program, by giving you a -history of how the conflicting concepts arose and who they came from. - -@menu -* Change Log Concepts:: -* Style of Change Logs:: -* Simple Changes:: -* Conditional Changes:: -* Indicating the Part Changed:: -@end menu - -@node Change Log Concepts -@subsection Change Log Concepts - -You can think of the change log as a conceptual ``undo list'' which -explains how earlier versions were different from the current version. -People can see the current version; they don't need the change log -to tell them what is in it. What they want from a change log is a -clear explanation of how the earlier version differed. - -The change log file is normally called @file{ChangeLog} and covers an -entire directory. Each directory can have its own change log, or a -directory can use the change log of its parent directory--it's up to -you. - -Another alternative is to record change log information with a version -control system such as RCS or CVS. This can be converted automatically -to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command -@kbd{C-x v a} (@code{vc-update-change-log}) does the job. - -There's no need to describe the full purpose of the changes or how they -work together. If you think that a change calls for explanation, you're -probably right. Please do explain it---but please put the explanation -in comments in the code, where people will see it whenever they see the -code. For example, ``New function'' is enough for the change log when -you add a function, because there should be a comment before the -function definition to explain what it does. - -However, sometimes it is useful to write one line to describe the -overall purpose of a batch of changes. - -The easiest way to add an entry to @file{ChangeLog} is with the Emacs -command @kbd{M-x add-change-log-entry}. An entry should have an -asterisk, the name of the changed file, and then in parentheses the name -of the changed functions, variables or whatever, followed by a colon. -Then describe the changes you made to that function or variable. - -@node Style of Change Logs -@subsection Style of Change Logs -@cindex change logs, style - -Here are some simple examples of change log entries, starting with the -header line that says who made the change and when, followed by -descriptions of specific changes. (These examples are drawn from Emacs -and GCC.) - -@example -1998-08-17 Richard Stallman <rms@@gnu.org> - -* register.el (insert-register): Return nil. -(jump-to-register): Likewise. - -* sort.el (sort-subr): Return nil. - -* tex-mode.el (tex-bibtex-file, tex-file, tex-region): -Restart the tex shell if process is gone or stopped. -(tex-shell-running): New function. - -* expr.c (store_one_arg): Round size up for move_block_to_reg. -(expand_call): Round up when emitting USE insns. -* stmt.c (assign_parms): Round size up for move_block_from_reg. -@end example - -It's important to name the changed function or variable in full. Don't -abbreviate function or variable names, and don't combine them. -Subsequent maintainers will often search for a function name to find all -the change log entries that pertain to it; if you abbreviate the name, -they won't find it when they search. - -For example, some people are tempted to abbreviate groups of function -names by writing @samp{* register.el (@{insert,jump-to@}-register)}; -this is not a good idea, since searching for @code{jump-to-register} or -@code{insert-register} would not find that entry. - -Separate unrelated change log entries with blank lines. When two -entries represent parts of the same change, so that they work together, -then don't put blank lines between them. Then you can omit the file -name and the asterisk when successive entries are in the same file. - -Break long lists of function names by closing continued lines with -@samp{)}, rather than @samp{,}, and opening the continuation with -@samp{(} as in this example: - -@example -* keyboard.c (menu_bar_items, tool_bar_items) -(Fexecute_extended_command): Deal with `keymap' property. -@end example - -@node Simple Changes -@subsection Simple Changes - -Certain simple kinds of changes don't need much detail in the change -log. - -When you change the calling sequence of a function in a simple fashion, -and you change all the callers of the function to use the new calling -sequence, there is no need to make individual entries for all the -callers that you changed. Just write in the entry for the function -being called, ``All callers changed''---like this: - -@example -* keyboard.c (Fcommand_execute): New arg SPECIAL. -All callers changed. -@end example - -When you change just comments or doc strings, it is enough to write an -entry for the file, without mentioning the functions. Just ``Doc -fixes'' is enough for the change log. - -There's no need to make change log entries for documentation files. -This is because documentation is not susceptible to bugs that are hard -to fix. Documentation does not consist of parts that must interact in a -precisely engineered fashion. To correct an error, you need not know -the history of the erroneous passage; it is enough to compare what the -documentation says with the way the program actually works. - -@node Conditional Changes -@subsection Conditional Changes -@cindex conditional changes, and change logs -@cindex change logs, conditional changes - -C programs often contain compile-time @code{#if} conditionals. Many -changes are conditional; sometimes you add a new definition which is -entirely contained in a conditional. It is very useful to indicate in -the change log the conditions for which the change applies. - -Our convention for indicating conditional changes is to use square -brackets around the name of the condition. - -Here is a simple example, describing a change which is conditional but -does not have a function or entity name associated with it: - -@example -* xterm.c [SOLARIS2]: Include string.h. -@end example - -Here is an entry describing a new definition which is entirely -conditional. This new definition for the macro @code{FRAME_WINDOW_P} is -used only when @code{HAVE_X_WINDOWS} is defined: - -@example -* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. -@end example - -Here is an entry for a change within the function @code{init_display}, -whose definition as a whole is unconditional, but the changes themselves -are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional: - -@example -* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. -@end example - -Here is an entry for a change that takes affect only when -a certain macro is @emph{not} defined: - -@example -(gethostname) [!HAVE_SOCKETS]: Replace with winsock version. -@end example - -@node Indicating the Part Changed -@subsection Indicating the Part Changed - -Indicate the part of a function which changed by using angle brackets -enclosing an indication of what the changed part does. Here is an entry -for a change in the part of the function @code{sh-while-getopts} that -deals with @code{sh} commands: - -@example -* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that -user-specified option string is empty. -@end example - - -@node Man Pages -@section Man Pages -@cindex man pages - -In the GNU project, man pages are secondary. It is not necessary or -expected for every GNU program to have a man page, but some of them do. -It's your choice whether to include a man page in your program. - -When you make this decision, consider that supporting a man page -requires continual effort each time the program is changed. The time -you spend on the man page is time taken away from more useful work. - -For a simple program which changes little, updating the man page may be -a small job. Then there is little reason not to include a man page, if -you have one. - -For a large program that changes a great deal, updating a man page may -be a substantial burden. If a user offers to donate a man page, you may -find this gift costly to accept. It may be better to refuse the man -page unless the same person agrees to take full responsibility for -maintaining it---so that you can wash your hands of it entirely. If -this volunteer later ceases to do the job, then don't feel obliged to -pick it up yourself; it may be better to withdraw the man page from the -distribution until someone else agrees to update it. - -When a program changes only a little, you may feel that the -discrepancies are small enough that the man page remains useful without -updating. If so, put a prominent note near the beginning of the man -page explaining that you don't maintain it and that the Texinfo manual -is more authoritative. The note should say how to access the Texinfo -documentation. - -@node Reading other Manuals -@section Reading other Manuals - -There may be non-free books or documentation files that describe the -program you are documenting. - -It is ok to use these documents for reference, just as the author of a -new algebra textbook can read other books on algebra. A large portion -of any non-fiction book consists of facts, in this case facts about how -a certain program works, and these facts are necessarily the same for -everyone who writes about the subject. But be careful not to copy your -outline structure, wording, tables or examples from preexisting non-free -documentation. Copying from free documentation may be ok; please check -with the FSF about the individual case. - -@node Managing Releases -@chapter The Release Process -@cindex releasing - -Making a release is more than just bundling up your source files in a -tar file and putting it up for FTP. You should set up your software so -that it can be configured to run on a variety of systems. Your Makefile -should conform to the GNU standards described below, and your directory -layout should also conform to the standards discussed below. Doing so -makes it easy to include your package into the larger framework of -all GNU software. - -@menu -* Configuration:: How Configuration Should Work -* Makefile Conventions:: Makefile Conventions -* Releases:: Making Releases -@end menu - -@node Configuration -@section How Configuration Should Work -@cindex program configuration - -@pindex configure -Each GNU distribution should come with a shell script named -@code{configure}. This script is given arguments which describe the -kind of machine and system you want to compile the program for. - -The @code{configure} script must record the configuration options so -that they affect compilation. - -One way to do this is to make a link from a standard name such as -@file{config.h} to the proper configuration file for the chosen system. -If you use this technique, the distribution should @emph{not} contain a -file named @file{config.h}. This is so that people won't be able to -build the program without configuring it first. - -Another thing that @code{configure} can do is to edit the Makefile. If -you do this, the distribution should @emph{not} contain a file named -@file{Makefile}. Instead, it should include a file @file{Makefile.in} which -contains the input used for editing. Once again, this is so that people -won't be able to build the program without configuring it first. - -If @code{configure} does write the @file{Makefile}, then @file{Makefile} -should have a target named @file{Makefile} which causes @code{configure} -to be rerun, setting up the same configuration that was set up last -time. The files that @code{configure} reads should be listed as -dependencies of @file{Makefile}. - -All the files which are output from the @code{configure} script should -have comments at the beginning explaining that they were generated -automatically using @code{configure}. This is so that users won't think -of trying to edit them by hand. - -The @code{configure} script should write a file named @file{config.status} -which describes which configuration options were specified when the -program was last configured. This file should be a shell script which, -if run, will recreate the same configuration. - -The @code{configure} script should accept an option of the form -@samp{--srcdir=@var{dirname}} to specify the directory where sources are found -(if it is not the current directory). This makes it possible to build -the program in a separate directory, so that the actual source directory -is not modified. - -If the user does not specify @samp{--srcdir}, then @code{configure} should -check both @file{.} and @file{..} to see if it can find the sources. If -it finds the sources in one of these places, it should use them from -there. Otherwise, it should report that it cannot find the sources, and -should exit with nonzero status. - -Usually the easy way to support @samp{--srcdir} is by editing a -definition of @code{VPATH} into the Makefile. Some rules may need to -refer explicitly to the specified source directory. To make this -possible, @code{configure} can add to the Makefile a variable named -@code{srcdir} whose value is precisely the specified directory. - -The @code{configure} script should also take an argument which specifies the -type of system to build the program for. This argument should look like -this: - -@example -@var{cpu}-@var{company}-@var{system} -@end example - -For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. - -The @code{configure} script needs to be able to decode all plausible -alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} -would be a valid alias. For many programs, @samp{vax-dec-ultrix} would -be an alias for @samp{vax-dec-bsd}, simply because the differences -between Ultrix and @sc{bsd} are rarely noticeable, but a few programs -might need to distinguish them. -@c Real 4.4BSD now runs on some Suns. - -There is a shell script called @file{config.sub} that you can use -as a subroutine to validate system types and canonicalize aliases. - -@cindex optional features, configure-time -Other options are permitted to specify in more detail the software -or hardware present on the machine, and include or exclude optional -parts of the package: - -@table @samp -@item --enable-@var{feature}@r{[}=@var{parameter}@r{]} -Configure the package to build and install an optional user-level -facility called @var{feature}. This allows users to choose which -optional features to include. Giving an optional @var{parameter} of -@samp{no} should omit @var{feature}, if it is built by default. - -No @samp{--enable} option should @strong{ever} cause one feature to -replace another. No @samp{--enable} option should ever substitute one -useful behavior for another useful behavior. The only proper use for -@samp{--enable} is for questions of whether to build part of the program -or exclude it. - -@item --with-@var{package} -@c @r{[}=@var{parameter}@r{]} -The package @var{package} will be installed, so configure this package -to work with @var{package}. - -@c Giving an optional @var{parameter} of -@c @samp{no} should omit @var{package}, if it is used by default. - -Possible values of @var{package} include -@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, -@samp{gdb}, -@samp{x}, -and -@samp{x-toolkit}. - -Do not use a @samp{--with} option to specify the file name to use to -find certain files. That is outside the scope of what @samp{--with} -options are for. -@end table - -All @code{configure} scripts should accept all of these ``detail'' -options, whether or not they make any difference to the particular -package at hand. In particular, they should accept any option that -starts with @samp{--with-} or @samp{--enable-}. This is so users will -be able to configure an entire GNU source tree at once with a single set -of options. - -You will note that the categories @samp{--with-} and @samp{--enable-} -are narrow: they @strong{do not} provide a place for any sort of option -you might think of. That is deliberate. We want to limit the possible -configuration options in GNU software. We do not want GNU programs to -have idiosyncratic configuration options. - -Packages that perform part of the compilation process may support -cross-compilation. In such a case, the host and target machines for the -program may be different. - -The @code{configure} script should normally treat the specified type of -system as both the host and the target, thus producing a program which -works for the same type of machine that it runs on. - -To configure a cross-compiler, cross-assembler, or what have you, you -should specify a target different from the host, using the configure -option @samp{--target=@var{targettype}}. The syntax for -@var{targettype} is the same as for the host type. So the command would -look like this: - -@example -./configure @var{hosttype} --target=@var{targettype} -@end example - -Programs for which cross-operation is not meaningful need not accept the -@samp{--target} option, because configuring an entire operating system for -cross-operation is not a meaningful operation. - -Bootstrapping a cross-compiler requires compiling it on a machine other -than the host it will run on. Compilation packages accept a -configuration option @samp{--build=@var{buildtype}} for specifying the -configuration on which you will compile them, but the configure script -should normally guess the build machine type (using -@file{config.guess}), so this option is probably not necessary. The -host and target types normally default from the build type, so in -bootstrapping a cross-compiler you must specify them both explicitly. - -Some programs have ways of configuring themselves automatically. If -your program is set up to do this, your @code{configure} script can simply -ignore most of its arguments. - -@comment The makefile standards are in a separate file that is also -@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. -@comment For this document, turn chapters into sections, etc. -@lowersections -@include make-stds.texi -@raisesections - -@node Releases -@section Making Releases -@cindex packaging - -Package the distribution of @code{Foo version 69.96} up in a gzipped tar -file with the name @file{foo-69.96.tar.gz}. It should unpack into a -subdirectory named @file{foo-69.96}. - -Building and installing the program should never modify any of the files -contained in the distribution. This means that all the files that form -part of the program in any way must be classified into @dfn{source -files} and @dfn{non-source files}. Source files are written by humans -and never changed automatically; non-source files are produced from -source files by programs under the control of the Makefile. - -@cindex @file{README} file -The distribution should contain a file named @file{README} which gives -the name of the package, and a general description of what it does. It -is also good to explain the purpose of each of the first-level -subdirectories in the package, if there are any. The @file{README} file -should either state the version number of the package, or refer to where -in the package it can be found. - -The @file{README} file should refer to the file @file{INSTALL}, which -should contain an explanation of the installation procedure. - -The @file{README} file should also refer to the file which contains the -copying conditions. The GNU GPL, if used, should be in a file called -@file{COPYING}. If the GNU LGPL is used, it should be in a file called -@file{COPYING.LIB}. - -Naturally, all the source files must be in the distribution. It is okay -to include non-source files in the distribution, provided they are -up-to-date and machine-independent, so that building the distribution -normally will never modify them. We commonly include non-source files -produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid -unnecessary dependencies between our distributions, so that users can -install whichever packages they want to install. - -Non-source files that might actually be modified by building and -installing the program should @strong{never} be included in the -distribution. So if you do distribute non-source files, always make -sure they are up to date when you make a new distribution. - -Make sure that the directory into which the distribution unpacks (as -well as any subdirectories) are all world-writable (octal mode 777). -This is so that old versions of @code{tar} which preserve the -ownership and permissions of the files from the tar archive will be -able to extract all the files even if the user is unprivileged. - -Make sure that all the files in the distribution are world-readable. - -Make sure that no file name in the distribution is more than 14 -characters long. Likewise, no file created by building the program -should have a name longer than 14 characters. The reason for this is -that some systems adhere to a foolish interpretation of the @sc{posix} -standard, and refuse to open a longer name, rather than truncating as -they did in the past. - -Don't include any symbolic links in the distribution itself. If the tar -file contains symbolic links, then people cannot even unpack it on -systems that don't support symbolic links. Also, don't use multiple -names for one file in different directories, because certain file -systems cannot handle this and that prevents unpacking the -distribution. - -Try to make sure that all the file names will be unique on MS-DOS. A -name on MS-DOS consists of up to 8 characters, optionally followed by a -period and up to three characters. MS-DOS will truncate extra -characters both before and after the period. Thus, -@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they -are truncated to @file{foobarha.c} and @file{foobarha.o}, which are -distinct. - -@cindex @file{texinfo.tex}, in a distribution -Include in your distribution a copy of the @file{texinfo.tex} you used -to test print any @file{*.texinfo} or @file{*.texi} files. - -Likewise, if your program uses small GNU software packages like regex, -getopt, obstack, or termcap, include them in the distribution file. -Leaving them out would make the distribution file a little smaller at -the expense of possible inconvenience to a user who doesn't know what -other files to get. - -@node References -@chapter References to Non-Free Software and Documentation -@cindex references to non-free material - -A GNU program should not recommend use of any non-free program. We -can't stop some people from writing proprietary programs, or stop -other people from using them, but we can and should avoid helping to -advertise them to new potential customers. Proprietary software is a -social and ethical problem, and the point of GNU is to solve that -problem. - -When a non-free program or system is well known, you can mention it in -passing---that is harmless, since users who might want to use it -probably already know about it. For instance, it is fine to explain -how to build your package on top of some non-free operating system, or -how to use it together with some widely used non-free program. - -However, you should give only the necessary information to help those -who already use the non-free program to use your program with -it---don't give, or refer to, any further information about the -proprietary program, and don't imply that the proprietary program -enhances your program, or that its existence is in any way a good -thing. The goal should be that people already using the proprietary -program will get the advice they need about how to use your free -program, while people who don't already use the proprietary program -will not see anything to lead them to take an interest in it. - -If a non-free program or system is obscure in your program's domain, -your program should not mention or support it at all, since doing so -would tend to popularize the non-free program more than it popularizes -your program. (You cannot hope to find many additional users among -the users of Foobar if the users of Foobar are few.) - -A GNU package should not refer the user to any non-free documentation -for free software. Free documentation that can be included in free -operating systems is essential for completing the GNU system, so it is -a major focus of the GNU Project; to recommend use of documentation -that we are not allowed to use in GNU would undermine the efforts to -get documentation that we can include. So GNU packages should never -recommend non-free documentation. - -@node Copying This Manual -@appendix Copying This Manual - -@menu -* GNU Free Documentation License:: License for copying this manual -@end menu - -@include fdl.texi - -@node Index -@unnumbered Index -@printindex cp - -@contents - -@bye -@c Local variables: -@c eval: (add-hook 'write-file-hooks 'time-stamp) -@c time-stamp-start: "@set lastupdate " -@c time-stamp-end: "$" -@c time-stamp-format: "%:b %:d, %:y" -@c compile-command: "make just-standards" -@c End: diff --git a/etc/texi2pod.pl b/etc/texi2pod.pl deleted file mode 100644 index bdc20e811..000000000 --- a/etc/texi2pod.pl +++ /dev/null @@ -1,427 +0,0 @@ -#! /usr/bin/perl -w - -# Copyright (C) 1999, 2000, 2001, 200 Free Software Foundation, Inc. - -# This file is part of GNU CC. - -# GNU CC 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. - -# GNU CC 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 GNU CC; see the file COPYING. If not, write to -# the Free Software Foundation, 59 Temple Place - Suite 330, -# Boston MA 02111-1307, USA. - -# This does trivial (and I mean _trivial_) conversion of Texinfo -# markup to Perl POD format. It's intended to be used to extract -# something suitable for a manpage from a Texinfo document. - -$output = 0; -$skipping = 0; -%sects = (); -$section = ""; -@icstack = (); -@endwstack = (); -@skstack = (); -@instack = (); -$shift = ""; -%defs = (); -$fnno = 1; -$inf = ""; -$ibase = ""; - -while ($_ = shift) { - if (/^-D(.*)$/) { - if ($1 ne "") { - $flag = $1; - } else { - $flag = shift; - } - $value = ""; - ($flag, $value) = ($flag =~ /^([^=]+)(?:=(.+))?/); - die "no flag specified for -D\n" - unless $flag ne ""; - die "flags may only contain letters, digits, hyphens, dashes and underscores\n" - unless $flag =~ /^[a-zA-Z0-9_-]+$/; - $defs{$flag} = $value; - } elsif (/^-/) { - usage(); - } else { - $in = $_, next unless defined $in; - $out = $_, next unless defined $out; - usage(); - } -} - -if (defined $in) { - $inf = gensym(); - open($inf, "<$in") or die "opening \"$in\": $!\n"; - $ibase = $1 if $in =~ m|^(.+)/[^/]+$|; -} else { - $inf = \*STDIN; -} - -if (defined $out) { - open(STDOUT, ">$out") or die "opening \"$out\": $!\n"; -} - -while(defined $inf) { -while(<$inf>) { - # Certain commands are discarded without further processing. - /^\@(?: - [a-z]+index # @*index: useful only in complete manual - |need # @need: useful only in printed manual - |(?:end\s+)?group # @group .. @end group: ditto - |page # @page: ditto - |node # @node: useful only in .info file - |(?:end\s+)?ifnottex # @ifnottex .. @end ifnottex: use contents - )\b/x and next; - - chomp; - - # Look for filename and title markers. - /^\@setfilename\s+([^.]+)/ and $fn = $1, next; - /^\@settitle\s+([^.]+)/ and $tl = postprocess($1), next; - - # Identify a man title but keep only the one we are interested in. - /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do { - if (exists $defs{$1}) { - $fn = $1; - $tl = postprocess($2); - } - next; - }; - - # Look for blocks surrounded by @c man begin SECTION ... @c man end. - # This really oughta be @ifman ... @end ifman and the like, but such - # would require rev'ing all other Texinfo translators. - /^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do { - $output = 1 if exists $defs{$2}; - $sect = $1; - next; - }; - /^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect = $1, $output = 1, next; - /^\@c\s+man\s+end/ and do { - $sects{$sect} = "" unless exists $sects{$sect}; - $sects{$sect} .= postprocess($section); - $section = ""; - $output = 0; - next; - }; - - # handle variables - /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do { - $defs{$1} = $2; - next; - }; - /^\@clear\s+([a-zA-Z0-9_-]+)/ and do { - delete $defs{$1}; - next; - }; - - next unless $output; - - # Discard comments. (Can't do it above, because then we'd never see - # @c man lines.) - /^\@c\b/ and next; - - # End-block handler goes up here because it needs to operate even - # if we are skipping. - /^\@end\s+([a-z]+)/ and do { - # Ignore @end foo, where foo is not an operation which may - # cause us to skip, if we are presently skipping. - my $ended = $1; - next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex)$/; - - die "\@end $ended without \@$ended at line $.\n" unless defined $endw; - die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw; - - $endw = pop @endwstack; - - if ($ended =~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) { - $skipping = pop @skstack; - next; - } elsif ($ended =~ /^(?:example|smallexample|display)$/) { - $shift = ""; - $_ = ""; # need a paragraph break - } elsif ($ended =~ /^(?:itemize|enumerate|[fv]?table)$/) { - $_ = "\n=back\n"; - $ic = pop @icstack; - } else { - die "unknown command \@end $ended at line $.\n"; - } - }; - - # We must handle commands which can cause skipping even while we - # are skipping, otherwise we will not process nested conditionals - # correctly. - /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = "ifset"; - $skipping = 1 unless exists $defs{$1}; - next; - }; - - /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = "ifclear"; - $skipping = 1 if exists $defs{$1}; - next; - }; - - /^\@(ignore|menu|iftex)\b/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = $1; - $skipping = 1; - next; - }; - - next if $skipping; - - # Character entities. First the ones that can be replaced by raw text - # or discarded outright: - s/\@copyright\{\}/(c)/g; - s/\@dots\{\}/.../g; - s/\@enddots\{\}/..../g; - s/\@([.!? ])/$1/g; - s/\@[:-]//g; - s/\@bullet(?:\{\})?/*/g; - s/\@TeX\{\}/TeX/g; - s/\@pounds\{\}/\#/g; - s/\@minus(?:\{\})?/-/g; - s/\\,/,/g; - - # Now the ones that have to be replaced by special escapes - # (which will be turned back into text by unmunge()) - s/&/&/g; - s/\@\{/{/g; - s/\@\}/}/g; - s/\@\@/&at;/g; - - # Inside a verbatim block, handle @var specially. - if ($shift ne "") { - s/\@var\{([^\}]*)\}/<$1>/g; - } - - # POD doesn't interpret E<> inside a verbatim block. - if ($shift eq "") { - s/</</g; - s/>/>/g; - } else { - s/</</g; - s/>/>/g; - } - - # Single line command handlers. - - /^\@include\s+(.+)$/ and do { - push @instack, $inf; - $inf = gensym(); - - # Try cwd and $ibase. - open($inf, "<" . $1) - or open($inf, "<" . $ibase . "/" . $1) - or die "cannot open $1 or $ibase/$1: $!\n"; - next; - }; - - /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/ - and $_ = "\n=head2 $1\n"; - /^\@subsection\s+(.+)$/ - and $_ = "\n=head3 $1\n"; - - # Block command handlers: - /^\@itemize\s+(\@[a-z]+|\*|-)/ and do { - push @endwstack, $endw; - push @icstack, $ic; - $ic = $1; - $_ = "\n=over 4\n"; - $endw = "itemize"; - }; - - /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic = $1 . "."; - } else { - $ic = "1."; - } - $_ = "\n=over 4\n"; - $endw = "enumerate"; - }; - - /^\@([fv]?table)\s+(\@[a-z]+)/ and do { - push @endwstack, $endw; - push @icstack, $ic; - $endw = $1; - $ic = $2; - $ic =~ s/\@(?:samp|strong|key|gcctabopt|env)/B/; - $ic =~ s/\@(?:code|kbd)/C/; - $ic =~ s/\@(?:dfn|var|emph|cite|i)/I/; - $ic =~ s/\@(?:file)/F/; - $_ = "\n=over 4\n"; - }; - - /^\@((?:small)?example|display)/ and do { - push @endwstack, $endw; - $endw = $1; - $shift = "\t"; - $_ = ""; # need a paragraph break - }; - - /^\@itemx?\s*(.+)?$/ and do { - if (defined $1) { - # Entity escapes prevent munging by the <> processing below. - $_ = "\n=item $ic\<$1\>\n"; - } else { - $_ = "\n=item $ic\n"; - $ic =~ y/A-Ya-y/B-Zb-z/; - $ic =~ s/(\d+)/$1 + 1/eg; - } - }; - - $section .= $shift.$_."\n"; -} -# End of current file. -close($inf); -$inf = pop @instack; -} - -die "No filename or title\n" unless defined $fn && defined $tl; - -$sects{NAME} = "$fn \- $tl\n"; -$sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES}; - -for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES - BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) { - if(exists $sects{$sect}) { - $head = $sect; - $head =~ s/SEEALSO/SEE ALSO/; - print "=head1 $head\n\n"; - print scalar unmunge ($sects{$sect}); - print "\n"; - } -} - -sub usage -{ - die "usage: $0 [-D toggle...] [infile [outfile]]\n"; -} - -sub postprocess -{ - local $_ = $_[0]; - - # @value{foo} is replaced by whatever 'foo' is defined as. - while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) { - if (! exists $defs{$2}) { - print STDERR "Option $2 not defined\n"; - s/\Q$1\E//; - } else { - $value = $defs{$2}; - s/\Q$1\E/$value/; - } - } - - # Formatting commands. - # Temporary escape for @r. - s/\@r\{([^\}]*)\}/R<$1>/g; - s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g; - s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g; - s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g; - s/\@sc\{([^\}]*)\}/\U$1/g; - s/\@file\{([^\}]*)\}/F<$1>/g; - s/\@w\{([^\}]*)\}/S<$1>/g; - s/\@(?:dmn|math)\{([^\}]*)\}/$1/g; - - # Cross references are thrown away, as are @noindent and @refill. - # (@noindent is impossible in .pod, and @refill is unnecessary.) - # @* is also impossible in .pod; we discard it and any newline that - # follows it. Similarly, our macro @gol must be discarded. - - s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g; - s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g; - s/;\s+\@pxref\{(?:[^\}]*)\}//g; - s/\@noindent\s*//g; - s/\@refill//g; - s/\@gol//g; - s/\@\*\s*\n?//g; - - # @uref can take one, two, or three arguments, with different - # semantics each time. @url and @email are just like @uref with - # one argument, for our purposes. - s/\@(?:uref|url|email)\{([^\},]*)\}/<B<$1>>/g; - s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g; - s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g; - - # Turn B<blah I<blah> blah> into B<blah> I<blah> B<blah> to - # match Texinfo semantics of @emph inside @samp. Also handle @r - # inside bold. - s/</</g; - s/>/>/g; - 1 while s/B<((?:[^<>]|I<[^<>]*>)*)R<([^>]*)>/B<$1>${2}B</g; - 1 while (s/B<([^<>]*)I<([^>]+)>/B<$1>I<$2>B</g); - 1 while (s/I<([^<>]*)B<([^>]+)>/I<$1>B<$2>I</g); - s/[BI]<>//g; - s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g; - s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g; - - # Extract footnotes. This has to be done after all other - # processing because otherwise the regexp will choke on formatting - # inside @footnote. - while (/\@footnote/g) { - s/\@footnote\{([^\}]+)\}/[$fnno]/; - add_footnote($1, $fnno); - $fnno++; - } - - return $_; -} - -sub unmunge -{ - # Replace escaped symbols with their equivalents. - local $_ = $_[0]; - - s/</E<lt>/g; - s/>/E<gt>/g; - s/{/\{/g; - s/}/\}/g; - s/&at;/\@/g; - s/&/&/g; - return $_; -} - -sub add_footnote -{ - unless (exists $sects{FOOTNOTES}) { - $sects{FOOTNOTES} = "\n=over 4\n\n"; - } - - $sects{FOOTNOTES} .= "=item $fnno.\n\n"; $fnno++; - $sects{FOOTNOTES} .= $_[0]; - $sects{FOOTNOTES} .= "\n\n"; -} - -# stolen from Symbol.pm -{ - my $genseq = 0; - sub gensym - { - my $name = "GEN" . $genseq++; - my $ref = \*{$name}; - delete $::{$name}; - return $ref; - } -} |