summaryrefslogtreecommitdiff
path: root/etc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2014-05-05 17:33:16 +0200
committerLudovic Courtès <ludo@gnu.org>2014-06-27 11:33:25 +0200
commit9393ab1c00601a01ec25bbe0d8dc8430f62c9c13 (patch)
tree371314db97cf6e95487ce090d477d124010d0103 /etc
parent7b5490456670ef187c1b7c07ba2e9e09512a6d70 (diff)
downloadbinutils-9393ab1c00601a01ec25bbe0d8dc8430f62c9c13.tar.gz
binutils-9393ab1c00601a01ec25bbe0d8dc8430f62c9c13.tar.bz2
binutils-9393ab1c00601a01ec25bbe0d8dc8430f62c9c13.zip
PR external/{16327,16328}: Remove etc/configure.texi and etc/standards.texi.
etc/ChangeLog 2014-06-27 Ludovic Courtès <ludo@gnu.org> PR external/16327 PR external/16328 * Makefile.in (MAKEINFO, TEXI2DVI, TEXI2PDF, TEXI2HTML, DVIPS) (TEXIDIR, INFOFILES, DVIFILES, PDFFILES, HTMLFILES): Remove. (all): Remove dependency on 'info'. (install): Remove dependency on 'install-info'. (standards.info, standards.html, standards.dvi, standards.ps) (standards.pdf, configure.info, configure.dvi, configure.ps) (configure.pdf, configure.pdf): Remove. (info, install-info, html, install-html, dvi, pdf, install-pdf) clean, maintainer-clean, realclean): Remove body. * etc/configbuild.ein, etc/configbuild.fig, etc/configbuild.jin, etc/configbuild.tin, etc/configdev.ein, etc/configdev.fig, etc/configdev.jin, etc/configdev.tin, etc/configure.texi, etc/fdl.texi, etc/gnu-oids.texi, etc/make-stds.texi, etc/standards.texi: Remove.
Diffstat (limited to 'etc')
-rw-r--r--etc/ChangeLog19
-rw-r--r--etc/Makefile.in182
-rw-r--r--etc/configbuild.ein149
-rw-r--r--etc/configbuild.fig50
-rw-r--r--etc/configbuild.jinbin11123 -> 0 bytes
-rw-r--r--etc/configbuild.tin9
-rw-r--r--etc/configdev.ein185
-rw-r--r--etc/configdev.fig80
-rw-r--r--etc/configdev.jinbin17967 -> 0 bytes
-rw-r--r--etc/configdev.tin17
-rw-r--r--etc/configure.texi2646
-rw-r--r--etc/fdl.texi505
-rw-r--r--etc/gnu-oids.texi52
-rw-r--r--etc/make-stds.texi1135
-rw-r--r--etc/standards.texi4235
15 files changed, 23 insertions, 9241 deletions
diff --git a/etc/ChangeLog b/etc/ChangeLog
index d3b6a0bf380..516e6a98dae 100644
--- a/etc/ChangeLog
+++ b/etc/ChangeLog
@@ -1,3 +1,22 @@
+2014-06-27 Ludovic Courtès <ludo@gnu.org>
+
+ PR external/16327
+ PR external/16328
+ * Makefile.in (MAKEINFO, TEXI2DVI, TEXI2PDF, TEXI2HTML, DVIPS)
+ (TEXIDIR, INFOFILES, DVIFILES, PDFFILES, HTMLFILES): Remove.
+ (all): Remove dependency on 'info'.
+ (install): Remove dependency on 'install-info'.
+ (standards.info, standards.html, standards.dvi, standards.ps)
+ (standards.pdf, configure.info, configure.dvi, configure.ps)
+ (configure.pdf, configure.pdf): Remove.
+ (info, install-info, html, install-html, dvi, pdf, install-pdf)
+ clean, maintainer-clean, realclean): Remove body.
+ * etc/configbuild.ein, etc/configbuild.fig, etc/configbuild.jin,
+ etc/configbuild.tin, etc/configdev.ein, etc/configdev.fig,
+ etc/configdev.jin, etc/configdev.tin, etc/configure.texi,
+ etc/fdl.texi, etc/gnu-oids.texi, etc/make-stds.texi,
+ etc/standards.texi: Remove.
+
2010-11-20 Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
* Makefile.in (install-strip): New target.
diff --git a/etc/Makefile.in b/etc/Makefile.in
index 0d19c13e6e5..4aa64c11488 100644
--- a/etc/Makefile.in
+++ b/etc/Makefile.in
@@ -37,187 +37,12 @@ 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`
-TEXI2PDF = `if [ -f ../texinfo/util/texi2dvi ]; \
- then echo "../texinfo/util/texi2dvi --pdf"; \
- else echo "texi2dvi --pdf"; fi`
-TEXI2HTML = `if [ -f ../texinfo/makeinfo/makeinfo ]; \
- then echo "../texinfo/makeinfo/makeinfo --html"; \
- else echo "makeinfo --html"; fi`
-
-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
-PDFFILES = standards.pdf configure.pdf
-HTMLFILES = standards.html configure.html
-
-all: info
-install install-strip: 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 $(DESTDIR)$(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 $(DESTDIR)$(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 $(DESTDIR)$(infodir)/$$i; \
- done; \
- fi
-
-html:
- for f in $(HTMLFILES); do \
- if test -f $(srcdir)/`echo $$f | sed -e 's/.html$$/.texi/'`; then \
- if $(MAKE) "TEXI2HTML=$(TEXI2HTML)" $$f; then \
- true; \
- else \
- exit 1; \
- fi; \
- fi; \
- done
-
-install-html: html
- $(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(htmldir)
- if test ! -f standards.html; then cd $(srcdir); fi; \
- if test -f standards.html; then \
- for i in standards.html*; do \
- $(INSTALL_DATA) $$i $(DESTDIR)$(htmldir)/$$i; \
- done; \
- fi
- if test ! -f configure.html; then cd $(srcdir); fi; \
- if test -f configure.html; then \
- for i in configure.html*; do \
- $(INSTALL_DATA) $$i $(DESTDIR)$(htmldir)/$$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
-
-pdf:
- for f in $(PDFFILES); do \
- if test -f $(srcdir)/`echo $$f | sed -e 's/.pdf$$/.texi/'`; then \
- if $(MAKE) "TEXI2PDF=$(TEXI2PDF)" $$f; then \
- true; \
- else \
- exit 1; \
- fi; \
- fi; \
- done
-
-install-pdf: pdf
- $(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(pdfdir)/etc
- if test ! -f standards.pdf; then cd $(srcdir); fi; \
- if test -f standards.pdf; then \
- for i in standards.pdf*; do \
- $(INSTALL_DATA) $$i $(DESTDIR)$(pdfdir)/etc/$$i; \
- done; \
- fi
- if test ! -f configure.pdf; then cd $(srcdir); fi; \
- if test -f configure.pdf; then \
- for i in configure.pdf*; do \
- $(INSTALL_DATA) $$i $(DESTDIR)$(pdfdir)/etc/$$i; \
- done; \
- fi
-
-standards.info: $(srcdir)/standards.texi $(srcdir)/make-stds.texi
- $(MAKEINFO) --no-split -I$(srcdir) -o standards.info $(srcdir)/standards.texi
-
-standards.html: $(srcdir)/standards.texi $(srcdir)/make-stds.texi
- $(TEXI2HTML) --no-split -I$(srcdir) -o standards.html $(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
-
-standards.pdf: $(srcdir)/standards.texi
- TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2PDF) $(srcdir)/standards.texi
-
-# 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.pdf: $(srcdir)/configure.texi $(srcdir)/configdev.tin $(srcdir)/configbuild.tin $(srcdir)/configdev.ein $(srcdir)/configbuild.ein
- rm -f configdev.pdf configbuild.pdf
- epstopdf $(srcdir)/configdev.ein -outfile=configdev.pdf
- epstopdf $(srcdir)/configbuild.ein -outfile=configbuild.pdf
- TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2PDF) $(srcdir)/configure.texi
- rm -f configdev.pdf configbuild.pdf
-
-configure.html: $(srcdir)/configure.texi
- cp $(srcdir)/configdev.jin configdev.jpg
- cp $(srcdir)/configbuild.jin configbuild.jpg
- $(TEXI2HTML) --no-split -I$(srcdir) -o configure.html $(srcdir)/configure.texi
+all:
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
- rm -f configdev.eps configbuild.eps
- rm -f configdev.jpg configbuild.jpg
mostlyclean: clean
@@ -225,8 +50,6 @@ distclean: clean
rm -f Makefile config.status config.cache
maintainer-clean realclean: distclean
- rm -f *.html*
- rm -f *.info*
Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag) \
config.status
@@ -244,5 +67,8 @@ config.status: $(srcdir)/configure
## these last targets are for standards.texi conformance
dist:
check:
+info html dvi ps pdf:
+install install-strip install-info install-html install-pdf:
installcheck:
+uninstall:
TAGS:
diff --git a/etc/configbuild.ein b/etc/configbuild.ein
deleted file mode 100644
index 7a0e214f2d5..00000000000
--- 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 747592d3d62..00000000000
--- 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
deleted file mode 100644
index 44cd9397aa1..00000000000
--- a/etc/configbuild.jin
+++ /dev/null
Binary files differ
diff --git a/etc/configbuild.tin b/etc/configbuild.tin
deleted file mode 100644
index cfdd6fe0743..00000000000
--- 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 7f837850d69..00000000000
--- 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 4d386ec4ff7..00000000000
--- 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
deleted file mode 100644
index 9b11a71acd7..00000000000
--- a/etc/configdev.jin
+++ /dev/null
Binary files differ
diff --git a/etc/configdev.tin b/etc/configdev.tin
deleted file mode 100644
index c9b6f34f4d7..00000000000
--- 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.texi b/etc/configure.texi
deleted file mode 100644
index 58c5285488f..00000000000
--- a/etc/configure.texi
+++ /dev/null
@@ -1,2646 +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
-
-@ifnottex
-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 ifnottex
-
-@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
-
-@ifnottex
-@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 ifnottex
-
-@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}. The equivalent html files are also built
-and installed in a separate step. To build the html files, run
-@samp{make html}. To install the html files run @samp{make install-html}.
-
-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,,,,jpg}
-
-@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,,,,jpg}
-
-@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[3-7]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[3-7]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 7c26c34b074..00000000000
--- a/etc/fdl.texi
+++ /dev/null
@@ -1,505 +0,0 @@
-@c The GNU Free Documentation License.
-@center Version 1.3, 3 November 2008
-
-@c This file is intended to be included within another document,
-@c hence no sectioning command or @node.
-
-@display
-Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
-@uref{http://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
-
-@enumerate 0
-@item
-PREAMBLE
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document @dfn{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.
-
-@item
-APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License. Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein. The ``Document'', below,
-refers to any such manual or work. Any member of the public is a
-licensee, and is addressed as ``you''. You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-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. (Thus, 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. If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant. The Document may contain zero
-Invariant Sections. If the Document does not identify any Invariant
-Sections then there are none.
-
-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 Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A ``Transparent'' copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-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, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text. A copy that is not ``Transparent'' is called ``Opaque''.
-
-Examples of suitable formats for Transparent copies include plain
-@sc{ascii} without markup, Texinfo input format, La@TeX{} input
-format, @acronym{SGML} or @acronym{XML} using a publicly available
-@acronym{DTD}, and standard-conforming simple @acronym{HTML},
-PostScript or @acronym{PDF} designed for human modification. Examples
-of transparent image formats include @acronym{PNG}, @acronym{XCF} and
-@acronym{JPG}. Opaque formats include proprietary formats that can be
-read and edited only by proprietary word processors, @acronym{SGML} or
-@acronym{XML} for which the @acronym{DTD} and/or processing tools are
-not generally available, and the machine-generated @acronym{HTML},
-PostScript or @acronym{PDF} 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.
-
-The ``publisher'' means any person or entity that distributes copies
-of the Document to the public.
-
-A section ``Entitled XYZ'' means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language. (Here XYZ stands for a
-specific section name mentioned below, such as ``Acknowledgements'',
-``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
-of such a section when you modify the Document means that it remains a
-section ``Entitled XYZ'' according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document. These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-@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.
-
-@item
-COPYING IN QUANTITY
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) 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 computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-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.
-
-@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:
-
-@enumerate A
-@item
-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.
-
-@item
-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 fewer than five),
-unless they release you from this requirement.
-
-@item
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
-@item
-Preserve all the copyright notices of the Document.
-
-@item
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
-@item
-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.
-
-@item
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document's license notice.
-
-@item
-Include an unaltered copy of this License.
-
-@item
-Preserve the section Entitled ``History'', Preserve 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.
-
-@item
-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.
-
-@item
-For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
-the Title of the section, and preserve in the section all the
-substance and tone of each of the contributor acknowledgements and/or
-dedications given therein.
-
-@item
-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.
-
-@item
-Delete any section Entitled ``Endorsements''. Such a section
-may not be included in the Modified Version.
-
-@item
-Do not retitle any existing section to be Entitled ``Endorsements'' or
-to conflict in title with any Invariant Section.
-
-@item
-Preserve any Warranty Disclaimers.
-@end enumerate
-
-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.
-
-@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, and that you preserve all their Warranty Disclaimers.
-
-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.''
-
-@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.
-
-@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, is called an ``aggregate'' if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation's users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which 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 half of
-the entire aggregate, the Document's Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-@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, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers. In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled ``Acknowledgements'',
-``Dedications'', or ``History'', the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-@item
-TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense, or distribute it is void, and
-will automatically terminate your rights under this License.
-
-However, if you cease all violation of this License, then your license
-from a particular copyright holder is reinstated (a) provisionally,
-unless and until the copyright holder explicitly and finally
-terminates your license, and (b) permanently, if the copyright holder
-fails to notify you of the violation by some reasonable means prior to
-60 days after the cessation.
-
-Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License. If your rights have been terminated and not permanently
-reinstated, receipt of a copy of some or all of the same material does
-not give you any rights to use it.
-
-@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
-@uref{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. If the Document
-specifies that a proxy can decide which future versions of this
-License can be used, that proxy's public statement of acceptance of a
-version permanently authorizes you to choose that version for the
-Document.
-
-@item
-RELICENSING
-
-``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
-World Wide Web server that publishes copyrightable works and also
-provides prominent facilities for anybody to edit those works. A
-public wiki that anybody can edit is an example of such a server. A
-``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
-site means any set of copyrightable works thus published on the MMC
-site.
-
-``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
-license published by Creative Commons Corporation, a not-for-profit
-corporation with a principal place of business in San Francisco,
-California, as well as future copyleft versions of that license
-published by that same organization.
-
-``Incorporate'' means to publish or republish a Document, in whole or
-in part, as part of another Document.
-
-An MMC is ``eligible for relicensing'' if it is licensed under this
-License, and if all works that were first published under this License
-somewhere other than this MMC, and subsequently incorporated in whole
-or in part into the MMC, (1) had no cover texts or invariant sections,
-and (2) were thus incorporated prior to November 1, 2008.
-
-The operator of an MMC Site may republish an MMC contained in the site
-under CC-BY-SA on the same site at any time before August 1, 2009,
-provided the MMC is eligible for relicensing.
-
-@end enumerate
-
-@page
-@heading 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.3
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
- Texts. A copy of the license is included in the section entitled ``GNU
- Free Documentation License''.
-@end group
-@end smallexample
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the ``with@dots{}Texts.'' line with this:
-
-@smallexample
-@group
- 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}.
-@end group
-@end smallexample
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-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.
-
-@c Local Variables:
-@c ispell-local-pdict: "ispell-dict"
-@c End:
diff --git a/etc/gnu-oids.texi b/etc/gnu-oids.texi
deleted file mode 100644
index da9146cc134..00000000000
--- a/etc/gnu-oids.texi
+++ /dev/null
@@ -1,52 +0,0 @@
-@c This table of OID's is included in the GNU Coding Standards.
-@c
-@c Copyright 2008, 2009, 2010 Free Software Foundation, Inc.
-@c
-@c Copying and distribution of this file, with or without modification,
-@c are permitted in any medium without royalty provided the copyright
-@c notice and this notice are preserved.
-@c
-@c When adding new OIDs, please add them also to
-@c http://www.alvestrand.no/objectid/ (except it gets an internal
-@c server error, so never mind)
-@c (Our page is http://www.alvestrand.no/objectid/1.3.6.1.4.1.11591.html.)
-
-1.3.6.1.4.1.11591 GNU
-
-1.3.6.1.4.1.11591.1 GNU Radius
-
-1.3.6.1.4.1.11591.2 GnuPG
- 1.3.6.1.4.1.11591.2.1 notation
- 1.3.6.1.4.1.11591.2.1.1 pkaAddress
-
-1.3.6.1.4.1.11591.3 GNU Radar
-
-1.3.6.1.4.1.11591.4 GNU GSS
-
-@c Added 2008-10-24 on request from Sergey Poznyakoff <gray@gnu.org.ua>
-1.3.6.1.4.1.11591.5 GNU Mailutils
-
-@c Added 2009-03-03 on request from Simon Josefsson <simon@josefsson.org>
-1.3.6.1.4.1.11591.6 GNU Shishi
-
-@c Added 2010-05-17 on request from Eric Blossom <eb@comsec.com>
-1.3.6.1.4.1.11591.7 GNU Radio
-
-1.3.6.1.4.1.11591.12 digestAlgorithm
- 1.3.6.1.4.1.11591.12.2 TIGER/192
- 1.3.6.1.4.1.11591.13 encryptionAlgorithm
- 1.3.6.1.4.1.11591.13.2 Serpent
- 1.3.6.1.4.1.11591.13.2.1 Serpent-128-ECB
- 1.3.6.1.4.1.11591.13.2.2 Serpent-128-CBC
- 1.3.6.1.4.1.11591.13.2.3 Serpent-128-OFB
- 1.3.6.1.4.1.11591.13.2.4 Serpent-128-CFB
- 1.3.6.1.4.1.11591.13.2.21 Serpent-192-ECB
- 1.3.6.1.4.1.11591.13.2.22 Serpent-192-CBC
- 1.3.6.1.4.1.11591.13.2.23 Serpent-192-OFB
- 1.3.6.1.4.1.11591.13.2.24 Serpent-192-CFB
- 1.3.6.1.4.1.11591.13.2.41 Serpent-256-ECB
- 1.3.6.1.4.1.11591.13.2.42 Serpent-256-CBC
- 1.3.6.1.4.1.11591.13.2.43 Serpent-256-OFB
- 1.3.6.1.4.1.11591.13.2.44 Serpent-256-CFB
- 1.3.6.1.4.1.11591.14 CRC algorithms
- 1.3.6.1.4.1.11591.14.1 CRC 32
diff --git a/etc/make-stds.texi b/etc/make-stds.texi
deleted file mode 100644
index 91a1ed0302b..00000000000
--- a/etc/make-stds.texi
+++ /dev/null
@@ -1,1135 +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 (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
-@c 2004, 2005, 2006 Free 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.2
-@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 to be used in Makefiles.
-* Command Variables:: Variables for specifying commands.
-* DESTDIR:: Supporting staged installs.
-* 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 non-executables
-respectively. Minimal use of these variables is as follows:
-
-@example
-$(INSTALL_PROGRAM) foo $(bindir)/foo
-$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
-@end example
-
-However, it is preferable to support a @code{DESTDIR} prefix on the
-target files, as explained in the next section.
-
-@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 DESTDIR
-@section @code{DESTDIR}: support for staged installs
-
-@vindex DESTDIR
-@cindex staged installs
-@cindex installations, staged
-
-@code{DESTDIR} is a variable prepended to each installed target file,
-like this:
-
-@example
-$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
-$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
-@end example
-
-The @code{DESTDIR} variable is specified by the user on the @code{make}
-command line. For example:
-
-@example
-make DESTDIR=/tmp/stage install
-@end example
-
-@noindent
-@code{DESTDIR} should be supported only in the @code{install*} and
-@code{uninstall*} targets, as those are the only targets where it is
-useful.
-
-If your installation step would normally install
-@file{/usr/local/bin/foo} and @file{/usr/local/lib/libfoo.a}, then an
-installation invoked as in the example above would install
-@file{/tmp/stage/usr/local/bin/foo} and
-@file{/tmp/stage/usr/local/lib/libfoo.a} instead.
-
-Prepending the variable @code{DESTDIR} to each target in this way
-provides for @dfn{staged installs}, where the installed files are not
-placed directly into their expected location but are instead copied
-into a temporary location (@code{DESTDIR}). However, installed files
-maintain their relative directory structure and any embedded file names
-will not be modified.
-
-You should not set the value of @code{DESTDIR} in your @file{Makefile}
-at all; then the files are installed into their expected locations by
-default. Also, specifying @code{DESTDIR} should not change the
-operation of the software in any way, so its value should not be
-included in any file contents.
-
-@code{DESTDIR} support is commonly used in package creation. It is
-also helpful to users who want to understand what a given package will
-install where, and to allow users who don't normally have permissions
-to install into protected areas to build and install before gaining
-those permissions. Finally, it can be useful with tools such as
-@code{stow}, where code is installed in one place but made to appear
-to be installed somewhere else using symbolic links or special mount
-operations. So, we strongly recommend GNU packages support
-@code{DESTDIR}, though it is not an absolute requirement.
-
-
-@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 and the values they should have in GNU packages are
-described below. They are based on a standard file system layout;
-variants of it are used in GNU/Linux and other modern operating
-systems.
-
-Installers are expected to override these values when calling
-@command{make} (e.g., @kbd{make prefix=/usr install} or
-@command{configure} (e.g., @kbd{configure --prefix=/usr}). GNU
-packages should not try to guess which value should be appropriate for
-these variables on the system they are being installed onto: use the
-default settings specified here so that all GNU packages behave
-identically, allowing the installer to achieve any desired layout.
-
-These first 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@@}.)
-
-The definition of @samp{libexecdir} is the same for all packages, so
-you should install your data in a subdirectory thereof. Most packages
-install their data under @file{$(libexecdir)/@var{package-name}/},
-possibly within additional subdirectories thereof, such as
-@file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}.
-@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.
-
-Here are the variables Makefiles should use to specify directories
-to put these various kinds of files in:
-
-@table @samp
-@item datarootdir
-The root of the directory tree for 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{@@datarootdir@@}.) @samp{datadir}'s default value is
-based on this variable; so are @samp{infodir}, @samp{mandir}, and
-others.
-
-@item datadir
-The directory for installing idiosyncratic read-only
-architecture-independent data files for this program. This is usually
-the same place as @samp{datarootdir}, but we use the two separate
-variables so that you can move these program-specific files without
-altering the location for Info files, man pages, etc.
-
-This should normally be @file{/usr/local/share}, but write it as
-@file{$(datarootdir)}. (If you are using Autoconf, write it as
-@samp{@@datadir@@}.)
-
-The definition of @samp{datadir} is the same for all packages, so you
-should install your data in a subdirectory thereof. Most packages
-install their data under @file{$(datadir)/@var{package-name}/}.
-
-@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@@}.)
-@end table
-
-These variables specify the directory for installing certain specific
-types of files, if your program has them. Every GNU package should
-have Info files, so every program needs @samp{infodir}, but not all
-need @samp{libdir} or @samp{lispdir}.
-
-@table @samp
-@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.
-
-@item docdir
-The directory for installing documentation files (other than Info) for
-this package. By default, it should be
-@file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as
-@file{$(datarootdir)/doc/@var{yourpkg}}. (If you are using Autoconf,
-write it as @samp{@@docdir@@}.) The @var{yourpkg} subdirectory, which
-may include a version number, prevents collisions among files with
-common names, such as @file{README}.
-
-@item infodir
-The directory for installing the Info files for this package. By
-default, it should be @file{/usr/local/share/info}, but it should be
-written as @file{$(datarootdir)/info}. (If you are using Autoconf,
-write it as @samp{@@infodir@@}.) @code{infodir} is separate from
-@code{docdir} for compatibility with existing practice.
-
-@item htmldir
-@itemx dvidir
-@itemx pdfdir
-@itemx psdir
-Directories for installing documentation files in the particular
-format. They should all be set to @code{$(docdir)} by default. (If
-you are using Autoconf, write them as @samp{@@htmldir@@},
-@samp{@@dvidir@@}, etc.) Packages which supply several translations
-of their documentation should install them in
-@samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where
-@var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}.
-
-@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 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{$(datarootdir)/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='$@{datarootdir@}/emacs/site-lisp'
-AC_SUBST(lispdir)
-@end example
-
-@item localedir
-The directory for installing locale-specific message catalogs for this
-package. By default, it should be @file{/usr/local/share/locale}, but
-it should be written as @file{$(datarootdir)/locale}. (If you are
-using Autoconf, write it as @samp{@@localedir@@}.) This directory
-usually has a subdirectory per locale.
-@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/share/man}, but you
-should write it as @file{$(datarootdir)/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 Autoconf, 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
-datarootdir = $(prefix)/share
-datadir = $(datarootdir)
-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 = $(datarootdir)/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.
-
-At times, not all of these variables may be implemented in the current
-release of Autoconf and/or Automake; but as of Autoconf@tie{}2.60, we
-believe all of them are. When any are missing, the descriptions here
-serve as specifications for what Autoconf will implement. As a
-programmer, you can either use a development version of Autoconf or
-avoid using these variables until a stable release is made which
-supports them.
-
-
-@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 (and other
-documentation format) 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 bug-make@gnu.org.
-@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 install-html
-@itemx install-dvi
-@itemx install-pdf
-@itemx install-ps
-These targets install documentation in formats other than Info;
-they're intended to be called explicitly by the person installing the
-package, if that format is desired. GNU prefers Info files, so these
-must be installed by the @code{install} target.
-
-When you have many documentation files to install, we recommend that
-you avoid collisions and clutter by arranging for these targets to
-install in subdirectories of the appropriate installation directory,
-such as @code{htmldir}. As one example, if your package has multiple
-manuals, and you wish to install HTML documentation with many files
-(such as the ``split'' mode output by @code{makeinfo --html}), you'll
-certainly want to use subdirectories, or two nodes with the same name
-in different manuals will overwrite each other.
-
-Please make these @code{install-@var{format}} targets invoke the
-commands for the @var{format} target, for example, by making
-@var{format} a dependency.
-
-@item uninstall
-Delete all the installed files---the copies that the @samp{install}
-and @samp{install-*} targets create.
-
-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 in the current directory that are normally created by
-building the program. Also delete files in other directories if they
-are created by this makefile. However, 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. There is no need to delete parent directories that were created
-with @samp{mkdir -p}, since they could have existed anyway.
-
-Delete @file{.dvi} files here if they are not part of the distribution.
-
-@item distclean
-Delete all files in the current directory (or created by this
-makefile) 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. However, there is no need to delete
-parent directories that were created with @samp{mkdir -p}, since they
-could have existed anyway.
-
-@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 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. Also, there is no need to delete parent
-directories that were created with @samp{mkdir -p}, since they could
-have existed anyway. These are the only exceptions;
-@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
-@itemx html
-@itemx pdf
-@itemx ps
-Generate documentation files in the given format. These targets
-should always exist, but any or all can be a no-op if the given output
-format cannot be generated. These targets should not be dependencies
-of the @code{all} target; the user must manually invoke them.
-
-Here's an example rule for generating DVI files from Texinfo:
-
-@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.
-
-Here's another example, this one for generating HTML from Texinfo:
-
-@smallexample
-html: foo.html
-
-foo.html: foo.texi chap1.texi chap2.texi
- $(TEXI2HTML) $(srcdir)/foo.texi
-@end smallexample
-
-@noindent
-Again, you would define the variable @code{TEXI2HTML} in the Makefile;
-for example, it might run @code{makeinfo --no-split --html}
-(@command{makeinfo} is part of the Texinfo distribution).
-
-@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 (the @option{-s} option to
-@command{make} is needed to silence messages about entering
-subdirectories):
-
-@smallexample
-make -s -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 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@}
-on @{print $0@}
-$0 ~ /^pre-install[ \t]*$/ @{on = 1@}
-@end smallexample
diff --git a/etc/standards.texi b/etc/standards.texi
deleted file mode 100644
index 4b1c03dd27d..00000000000
--- a/etc/standards.texi
+++ /dev/null
@@ -1,4235 +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 April 12, 2010
-@c %**end of header
-
-@dircategory GNU organization
-@direntry
-* Standards: (standards). GNU coding standards.
-@end direntry
-
-@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
-
-@copying
-The GNU coding standards, last updated @value{lastupdate}.
-
-Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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.3 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 copying
-
-@titlepage
-@title GNU Coding Standards
-@author Richard Stallman, et al.
-@author last updated @value{lastupdate}
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@contents
-
-@ifnottex
-@node Top, Preface, (dir), (dir)
-@top Version
-
-@insertcopying
-@end ifnottex
-
-@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:: Mentioning non-free software or documentation.
-* GNU Free Documentation License:: Copying and sharing 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.
-
-@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 get the GNU
-Coding Standards from the GNU web server in many
-different formats, including the Texinfo source, PDF, HTML, DVI, plain
-text, and more, at: @uref{http://www.gnu.org/prep/standards/}.
-
-If you are maintaining an official GNU package, in addition to this
-document, please read and follow the GNU maintainer information
-(@pxref{Top, , Contents, maintain, Information for Maintainers of GNU
-Software}).
-
-@cindex @code{gnustandards-commit@@gnu.org} mailing list
-If you want to receive diffs for every change to these GNU documents,
-join the mailing list @code{gnustandards-commit@@gnu.org}, via the web
-interface at
-@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
-Archives are also available there.
-
-@cindex @code{bug-standards@@gnu.org} email address
-@cindex Savannah repository for gnustandards
-@cindex gnustandards project repository
-Please send corrections or suggestions for this document to
-@email{bug-standards@@gnu.org}. If you make a suggestion, please
-include a suggested new wording for it, to help us consider the
-suggestion efficiently. We prefer a context diff to the Texinfo
-source, but if that's difficult for you, you can make a context diff
-for some other version of this document, or propose it in any way that
-makes it clear. The source repository for this document can be found
-at @url{http://savannah.gnu.org/projects/gnustandards}.
-
-These standards cover the minimum of what is important when writing a
-GNU package. Likely, the need 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.
-
-The GNU Hello program serves as an example of how to follow the GNU
-coding standards for a trivial program.
-@uref{http://www.gnu.org/software/hello/hello.html}.
-
-This release of the GNU Coding Standards was last updated
-@value{lastupdate}.
-
-
-@node Legal Issues
-@chapter Keeping Free Software Free
-@cindex legal aspects
-
-This 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 memory 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 sent 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. It is also available
-online for your perusal: @uref{http://www.gnu.org/prep/maintain/}.
-
-@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,
-and there is no legal requirement for them, so we don't use them.
-
-What is legally required, as regards other people's trademarks, is to
-avoid using them in ways which a reader might reasonably understand 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 would have been meant as
-a shorter way of saying 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.
-
-Please don't use ``win'' as an abbreviation for Microsoft Windows in
-GNU software or documentation. In hacker terminology, calling
-something a ``win'' is a form of praise. If you wish to praise
-Microsoft Windows when speaking on your own, by all means do so, but
-not in GNU software. Usually we write the name ``Windows'' in full,
-but when brevity is very important (as in file names and sometimes
-symbol names), we abbreviate it to ``w''. For instance, the files and
-functions in Emacs that deal with Windows start with @samp{w32}.
-
-@node Design Advice
-@chapter General Program Design
-@cindex program design
-
-This 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 languages 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 languages
-
-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
-@cindex GNOME and Guile
-The standard extensibility interpreter for GNU software is Guile
-(@uref{http://www.gnu.org/@/software/@/guile/}), which implements the
-language Scheme (an especially clean and simple dialect of Lisp).
-Guile also includes bindings for GTK+/GNOME, making it practical to
-write modern GUI functionality within 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
-
-@noindent
-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. Of course, the former method assumes that
-@code{HAS_FOO} is defined as either 0 or 1.
-
-While this is not a silver bullet solving all portability problems,
-and is not always appropriate, following this policy would have saved
-GCC developers many hours, or even 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 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
-* Non-GNU Standards:: We consider standards such as POSIX;
- we don't "obey" them.
-* 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.
-* OID Allocations:: Table of OID slots for GNU.
-* Memory Usage:: When and how to care about memory needs.
-* File Usage:: Which files to use, and where.
-@end menu
-
-@node Non-GNU Standards
-@section Non-GNU Standards
-
-The GNU Project regards standards published by other organizations as
-suggestions, not orders. We consider those standards, but we do not
-``obey'' them. In developing a GNU program, you should implement
-an outside standard's specifications when that makes the GNU system
-better overall in an objective sense. When it doesn't, you shouldn't.
-
-In most cases, following published standards is convenient for
-users---it means that their programs or scripts will work more
-portably. For instance, GCC implements nearly all the features of
-Standard C as specified by that standard. C program developers would
-be unhappy if it did not. And GNU utilities mostly follow
-specifications of POSIX.2; shell script writers and users would be
-unhappy if our programs were incompatible.
-
-But we do not follow either of these specifications rigidly, and there
-are specific points on which we decided not to follow them, so as to
-make the GNU system better for users.
-
-For instance, Standard C says that nearly all extensions to C are
-prohibited. How silly! GCC implements many extensions, some of which
-were later adopted as part of the standard. If you want these
-constructs to give an error message as ``required'' by the standard,
-you must specify @samp{--pedantic}, which was implemented only so that
-we can say ``GCC is a 100% implementation of the standard,'' not
-because there is any reason to actually use it.
-
-POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by
-default in units of 512 bytes. What users want is units of 1k, so
-that is what we do by default. If you want the ridiculous behavior
-``required'' by POSIX, you must set the environment variable
-@samp{POSIXLY_CORRECT} (which was originally going to be named
-@samp{POSIX_ME_HARDER}).
-
-GNU utilities also depart from the letter of the POSIX.2 specification
-when they support long-named command-line options, and intermixing
-options with ordinary arguments. This minor incompatibility with
-POSIX is never a problem in practice, and it is very useful.
-
-In particular, don't reject a new feature, or remove an old one,
-merely because a standard says it is ``forbidden'' or ``deprecated.''
-
-@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 one of these formats:
-
-@example
-@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
-@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.
-
-The error message can also give both the starting and ending positions
-of the erroneous text. There are several formats so that you can
-avoid redundant information such as a duplicate line number.
-Here are the possible formats:
-
-@example
-@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}
-@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}
-@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}
-@end example
-
-@noindent
-When an error is spread over several files, you can use this format:
-
-@example
-@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
-@end example
-
-Error messages from other noninteractive programs should look like this:
-
-@example
-@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
-@end example
-
-@noindent
-when there is an appropriate source file, or like this:
-
-@example
-@var{program}: @var{message}
-@end example
-
-@noindent
-when there is no relevant source file.
-
-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, because that isn't the
-beginning of a sentence. (The sentence conceptually starts at the
-beginning of the line.) 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 interface styles
-@cindex user interface styles
-
-@cindex GTK+
-When you write a program that provides a graphical user interface,
-please make it work with the X Window System 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
-@cindex D-bus
-@cindex keyboard interface
-@cindex library interface
-Please also consider providing a D-bus interface for use from other
-running programs, such as within GNOME. (GNOME used to use CORBA
-for this, but that is being phased out.) In addition, consider
-providing 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 idiosyncrasies for users to remember.
-
-@cindex standard command-line options
-@cindex options, standard command-line
-@cindex CGI programs, standard options for
-@cindex PATH_INFO, specifying standard options as
-All programs should support two standard options: @samp{--version}
-and @samp{--help}. CGI programs should accept these as command-line
-options, and also if given as the @env{PATH_INFO}; for instance,
-visiting @url{http://example.org/p.cgi/--help} in a browser should
-output the same information as invoking @samp{p.cgi --help} from the
-command line.
-
-@menu
-* --version:: The standard output for --version.
-* --help:: The standard output for --help.
-@end menu
-
-@node --version
-@subsection @option{--version}
-
-@cindex @samp{--version} output
-
-The standard @code{--version} 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 @emph{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 line stating the license, preferably using one of
-abbrevations below, and a brief statement that the program is free
-software, and that users are free to copy and change it. Also mention
-that there is no warranty, to the extent permitted by law. See
-recommended wording below.
-
-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 hello 2.3
-Copyright (C) 2007 Free Software Foundation, Inc.
-License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-@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. (The rules are different for copyright notices in source files;
-@pxref{Copyright Notices,,,maintain,Information for GNU Maintainers}.)
-
-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.
-
-Finally, here is the table of our suggested license abbreviations.
-Any abbreviation can be followed by @samp{v@var{version}[+]}, meaning
-that particular version, or later versions with the @samp{+}, as shown
-above.
-
-In the case of exceptions for extra permissions with the GPL, we use
-@samp{/} for a separator; the version number can follow the license
-abbreviation as usual, as in the examples below.
-
-@table @asis
-@item GPL
-GNU General Public License, @url{http://www.gnu.org/@/licenses/@/gpl.html}.
-
-@item LGPL
-GNU Lesser General Public License, @url{http://www.gnu.org/@/licenses/@/lgpl.html}.
-
-@item GPL/Ada
-GNU GPL with the exception for Ada.
-
-@item Apache
-The Apache Software Foundation license,
-@url{http://www.apache.org/@/licenses}.
-
-@item Artistic
-The Artistic license used for Perl, @url{http://www.perlfoundation.org/@/legal}.
-
-@item Expat
-The Expat license, @url{http://www.jclark.com/@/xml/@/copying.txt}.
-
-@item MPL
-The Mozilla Public License, @url{http://www.mozilla.org/@/MPL/}.
-
-@item OBSD
-The original (4-clause) BSD license, incompatible with the GNU GPL
-@url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#6}.
-
-@item PHP
-The license used for PHP, @url{http://www.php.net/@/license/}.
-
-@item public domain
-The non-license that is being in the public domain,
-@url{http://www.gnu.org/@/licenses/@/license-list.html#PublicDomain}.
-
-@item Python
-The license for Python, @url{http://www.python.org/@/2.0.1/@/license.html}.
-
-@item RBSD
-The revised (3-clause) BSD, compatible with the GNU GPL,@*
-@url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#5}.
-
-@item X11
-The simple non-copyleft license used for most versions of the X Window
-System, @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#3}.
-
-@item Zlib
-The license for Zlib, @url{http://www.gzip.org/@/zlib/@/zlib_license.html}.
-
-@end table
-
-More information about these licenses and many more are on the GNU
-licensing web pages,
-@url{http://www.gnu.org/@/licenses/@/license-list.html}.
-
-
-@node --help
-@subsection @option{--help}
-
-@cindex @samp{--help} output
-
-The standard @code{--help} 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, please place lines
-giving the email address for bug reports, the package's home page
-(normally @indicateurl{http://www.gnu.org/software/@var{pkg}}, and the
-general page for help using GNU programs. The format should be like this:
-
-@example
-Report bugs to: @var{mailing-address}
-@var{pkg} home page: <http://www.gnu.org/software/@var{pkg}/>
-General help using GNU software: <http://www.gnu.org/gethelp/>
-@end example
-
-It is ok to mention other appropriate mailing lists and web pages.
-
-
-@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 @code{make}.
-
-@item assume-old
-@samp{-o} in @code{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 @code{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 @code{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 @code{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{gawk}, @code{info}, @code{make}, @code{mt},
-@code{sed}, and @code{tar}.
-
-@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 @code{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 @code{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 @code{make}.
-
-@item just-print
-@samp{-n} in @code{make}.
-
-@item keep-going
-@samp{-k} in @code{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 @code{make}.
-
-@item login
-Used in @code{su}.
-
-@item machine
-Used in @code{uname}.
-
-@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 @code{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 @code{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 @code{make}.
-
-@item no-builtin-rules
-@samp{-r} in @code{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 @code{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-splash
-Don't print a startup splash screen.
-
-@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 @code{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 @code{make}.
-
-@item print-directory
-@samp{-w} in @code{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 @code{make}.
-
-@item quiet
-Used in many programs to inhibit the usual output. 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 @code{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
-@samp{-r} in @code{touch}.
-
-@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.
-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 non-privileged 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 @code{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 @code{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 @code{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 OID Allocations
-@section OID Allocations
-@cindex OID allocations for GNU
-@cindex SNMP
-@cindex LDAP
-@cindex X.509
-
-The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the
-GNU Project (thanks to Werner Koch). These are used for SNMP, LDAP,
-X.509 certificates, and so on. The web site
-@url{http://www.alvestrand.no/objectid} has a (voluntary) listing of
-many OID assignments.
-
-If you need a new slot for your GNU package, write
-@email{maintainers@@gnu.org}. Here is a list of arcs currently
-assigned:
-
-@example
-@include gnu-oids.texi
-@end example
-
-
-@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 memory 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 memory all at once.
-
-If your program creates complicated data structures, just make them in
-memory 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 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 among different operating systems.
-* CPU Portability:: Supporting the range of CPU types.
-* System Functions:: Portability and ``standard'' library functions.
-* Internationalization:: Techniques for internationalization.
-* Character Set:: Use ASCII by default.
-* Quote Characters:: Use `...' in the C locale.
-* 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 one, so that they will start a defun. Several
-tools look for open-braces in column one to find the beginnings of C
-functions. These tools will not work on code not formatted that way.
-
-Avoid putting open-brace, open-parenthesis or open-bracket in column
-one when they are inside a function, so that they won't start a defun.
-The open-brace that starts a @code{struct} body can go in column one
-if you find it useful to treat that definition as a defun.
-
-It is also important for function definitions to start the name of the
-function in column one. This helps people to search for function
-definitions, and may also help certain tools recognize them. Thus,
-using Standard C syntax, the format is this:
-
-@example
-static char *
-concat (char *s1, char *s2)
-@{
- @dots{}
-@}
-@end example
-
-@noindent
-or, if you want to use traditional C syntax, format the definition like
-this:
-
-@example
-static char *
-concat (s1, s2) /* Name starts in column one here */
- char *s1, *s2;
-@{ /* Open brace in column one here */
- @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}. This comment
-should be at the top of the source file containing the @samp{main}
-function of the program.
-
-Also, please write a brief comment at the start of each source file,
-with the file name and a line or two about the overall purpose of the
-file.
-
-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 to 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 (assignments
-inside @code{while}-conditions are ok). 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
-if 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, VMS, MVS,
-and older Macintosh systems, 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.
-
-If you do support Windows, please do not abbreviate it as ``win''. In
-hacker terminology, calling something a ``win'' is a form of praise.
-You're free to praise Microsoft Windows on your own if you want, but
-please don't do this in GNU packages. Instead of abbreviating
-``Windows'' to ``win'', you can write it in full or abbreviate it to
-``woe'' or ``w''. In GNU Emacs, for instance, we use @samp{w32} in
-file names of Windows-specific files, but the macro for Windows
-conditionals is called @code{WINDOWSNT}.
-
-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. 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
-
-@noindent Instead, use @code{unsigned char} as follows. (The @code{unsigned}
-is for portability to unusual systems where @code{char} is signed and
-where there is integer overflow checking.)
-
-@example
-int c;
-while ((c = getchar ()) != EOF)
- @{
- unsigned char u = c;
- write (file_descriptor, &u, 1);
- @}
-@end example
-
-It used to be ok to not worry about the difference between pointers
-and integers when passing arguments to functions. However, on most
-modern 64-bit machines pointers are wider than @code{int}.
-Conversely, integer types like @code{long long int} and @code{off_t}
-are wider than pointers on most modern 32-bit machines. Hence it's
-often better nowadays to use prototypes to define functions whose
-argument types are not trivial.
-
-In particular, if functions accept varying argument counts or types
-they should be declared using prototypes containing @samp{...} and
-defined using @file{stdarg.h}. For an example of this, please see the
-@uref{http://www.gnu.org/software/gnulib/, Gnulib} error module, which
-declares and defines the following function:
-
-@example
-/* Print a message with `fprintf (stderr, FORMAT, ...)';
- if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
- If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
-
-void error (int status, int errnum, const char *format, ...);
-@end example
-
-A simple way to use the Gnulib error module is to obtain the two
-source files @file{error.c} and @file{error.h} from the Gnulib library
-source code repository at
-@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=gnulib.git}.
-Here's a sample use:
-
-@example
-#include "error.h"
-#include <errno.h>
-#include <stdio.h>
-
-char *program_name = "myprogram";
-
-FILE *
-xfopen (char const *name)
-@{
- FILE *fp = fopen (name, "r");
- if (! fp)
- error (1, errno, "cannot read %s", name);
- return fp;
-@}
-@end example
-
-@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{coreutils} for the GNU core 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:
-
-@smallexample
-printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
-@end smallexample
-
-If you apply gettext to all strings, like this,
-
-@smallexample
-printf (gettext ("%s is full"),
- capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
-@end smallexample
-
-@noindent
-the translator will hardly know that "disk" and "floppy disk" are meant to
-be substituted in the other string. Worse, in some languages (like French)
-the construction will not work: the translation of the word "full" depends
-on the gender of the first part of the sentence; it happens to be not the
-same for "disk" as for "floppy disk".
-
-Complete sentences can be translated without problems:
-
-@example
-printf (capacity > 5000000 ? gettext ("disk is full")
- : gettext ("floppy disk is full"));
-@end example
-
-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 straightforwardly 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
-
-Another example is this one:
-
-@example
-printf ("%d file%s processed", nfiles,
- nfiles != 1 ? "s" : "");
-@end example
-
-@noindent
-The problem with this 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, with gettext being applied to
-the two strings independently:
-
-@example
-printf ((nfiles != 1 ? gettext ("%d files processed")
- : gettext ("%d file processed")),
- nfiles);
-@end example
-
-@noindent
-But this still doesn't work for languages like Polish, which has three
-plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, 24, ...
-and one for the rest. The GNU @code{ngettext} function solves this problem:
-
-@example
-printf (ngettext ("%d files processed", "%d file processed", nfiles),
- nfiles);
-@end example
-
-
-@node Character Set
-@section Character Set
-@cindex character set
-@cindex encodings
-@cindex ASCII characters
-@cindex non-ASCII characters
-
-Sticking to the ASCII character set (plain text, 7-bit characters) is
-preferred in GNU source code comments, text documents, and other
-contexts, unless there is good reason to do something else because of
-the application domain. For example, if source code deals with the
-French Revolutionary calendar, it is OK if its literal strings contain
-accented characters in month names like ``Flor@'eal''. Also, it is OK
-to use non-ASCII characters to represent proper names of contributors in
-change logs (@pxref{Change Logs}).
-
-If you need to use non-ASCII characters, you should normally stick with
-one encoding, as one cannot in general mix encodings reliably.
-
-
-@node Quote Characters
-@section Quote Characters
-@cindex quote characters
-@cindex locale-specific quote characters
-@cindex left quote
-@cindex grave accent
-
-In the C locale, GNU programs should stick to plain ASCII for quotation
-characters in messages to users: preferably 0x60 (@samp{`}) for left
-quotes and 0x27 (@samp{'}) for right quotes. It is ok, but not
-required, to use locale-specific quotes in other locales.
-
-The @uref{http://www.gnu.org/software/gnulib/, Gnulib} @code{quote} and
-@code{quotearg} modules provide a reasonably straightforward way to
-support locale-specific quote characters, as well as taking care of
-other issues, such as quoting a filename that itself contains a quote
-character. See the Gnulib documentation for usage details.
-
-In any case, the documentation for your program should clearly specify
-how it does quoting, if different than the preferred method of @samp{`}
-and @samp{'}. This is especially important if the output of your
-program is ever likely to be parsed by another program.
-
-Quotation characters are a difficult area in the computing world at
-this time: there are no true left or right quote characters in Latin1;
-the @samp{`} character we use was standardized there as a grave
-accent. Moreover, Latin1 is still not universally usable.
-
-Unicode contains the unambiguous quote characters required, and its
-common encoding UTF-8 is upward compatible with Latin1. However,
-Unicode and UTF-8 are not universally well-supported, either.
-
-This may change over the next few years, and then we will revisit
-this.
-
-
-@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.
-
-Make sure your manual is clear to a reader who knows nothing about the
-topic and reads it straight through. This means covering basic topics
-at the beginning, and advanced topics only later. This also means
-defining every specialized term when it is first used.
-
-Programmers tend to carry over the structure of the program as the
-structure for its documentation. But this structure is not
-necessarily good for explaining how to use the program; it may be
-irrelevant and confusing for a user.
-
-Instead, the right way to structure documentation is according to the
-concepts and questions that a user will have in mind when reading it.
-This principle applies at every level, from the lowest (ordering
-sentences in a paragraph) to the highest (ordering of chapter topics
-within the manual). Sometimes this structure of ideas matches the
-structure of the implementation of the software being documented---but
-often they are different. An important part of learning to write good
-documentation is to learn to notice when you have unthinkingly
-structured the documentation like the implementation, stop yourself,
-and look for 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. Don't just tell the reader what each feature can
-do---say what jobs it is good for, and show how to use it for those
-jobs. Explain what is recommended usage, and what kinds of usage
-users should avoid.
-
-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, GNU Texinfo}, and
-see @ref{Indexing Commands, , Defining the Entries of an
-Index, texinfo, GNU Texinfo}.
-
-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 text of 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 prohibited by law.
-
-Please do not write @samp{()} after a function name just to indicate
-it is a function. @code{foo ()} is not a function, it is a function
-call with no arguments.
-
-@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
-redundancy 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 for in a man page). 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. However, sometimes it is useful to write one line
-to describe the overall purpose of a change or a batch of changes. If
-you think that a change calls for explanation, you're probably right.
-Please do explain it---but please put the full 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.
-
-In the past, we recommended not mentioning changes in non-software
-files (manuals, help files, etc.) in change logs. However, we've been
-advised that it is a good idea to include them, for the sake of
-copyright records.
-
-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 it was installed,
-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
-
-When you install someone else's changes, put the contributor's name in
-the change log entry rather than in the text of the entry. In other
-words, write this:
-
-@example
-2002-07-14 John Doe <jdoe@@gnu.org>
-
- * sewing.c: Make it sew.
-@end example
-
-@noindent
-rather than this:
-
-@example
-2002-07-14 Usual Maintainer <usual@@gnu.org>
-
- * sewing.c: Make it sew. Patch by jdoe@@gnu.org.
-@end example
-
-As for the date, that should be the date you applied the change.
-
-@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 technical 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.
-
-However, you should keep change logs for documentation files when the
-project gets copyright assignments from its contributors, so as to
-make the records of authorship more accurate.
-
-@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.
-
-Be sure that man pages include a copyright statement and free license.
-The simple all-permissive license is appropriate for simple man pages
-(@pxref{License Notices for Other Files,,,maintain,Information for GNU
-Maintainers}).
-
-For long man pages, with enough explanation and documentation that
-they can be considered true manuals, use the GFDL (@pxref{License for
-Manuals}).
-
-Finally, the GNU help2man program
-(@uref{http://www.gnu.org/software/help2man/}) is one way to automate
-generation of a man page, in this case from @option{--help} output.
-This is sufficient in many cases.
-
-@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 of GNU packages 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.
-
-The description here is the specification of the interface for the
-@code{configure} script in GNU packages. Many packages implement it
-using GNU Autoconf (@pxref{Top,, Introduction, autoconf, Autoconf})
-and/or GNU Automake (@pxref{Top,, Introduction, automake, Automake}),
-but you do not have to use these tools. You can implement it any way
-you like; for instance, by making @code{configure} be a wrapper around
-a completely different configuration system.
-
-Another way for the @code{configure} script to operate 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.
-
-In addition, the @samp{configure} script should take options
-corresponding to most of the standard directory variables
-(@pxref{Directory Variables}). Here is the list:
-
-@example
---prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir
---sharedstatedir --localstatedir --libdir --includedir --oldincludedir
---datarootdir --datadir --infodir --localedir --mandir --docdir
---htmldir --dvidir --pdfdir --psdir
-@end example
-
-The @code{configure} script should also take an argument which specifies the
-type of system to build the program for. This argument should look like
-this:
-
-@example
-@var{cpu}-@var{company}-@var{system}
-@end example
-
-For example, an Athlon-based GNU/Linux system might be
-@samp{i686-pc-linux-gnu}.
-
-The @code{configure} script needs to be able to decode all plausible
-alternatives for how to describe a machine. Thus,
-@samp{athlon-pc-gnu/linux} would be a valid alias. There is a shell
-script called
-@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD,
-@file{config.sub}} that you can use as a subroutine to validate system
-types and canonicalize aliases.
-
-The @code{configure} script should also take the option
-@option{--build=@var{buildtype}}, which should be equivalent to a
-plain @var{buildtype} argument. For example, @samp{configure
---build=i686-pc-linux-gnu} is equivalent to @samp{configure
-i686-pc-linux-gnu}. When the build type is not specified by an option
-or argument, the @code{configure} script should normally guess it using
-the shell script
-@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD,
-@file{config.guess}}.
-
-@cindex optional features, configure-time
-Other options are permitted to specify in more detail the software
-or hardware present on the machine, to include or exclude optional parts
-of the package, or to adjust the name of some tools or arguments to them:
-
-@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.
-
-@item @var{variable}=@var{value}
-Set the value of the variable @var{variable} to @var{value}. This is
-used to override the default values of commands or arguments in the
-build process. For example, the user could issue @samp{configure
-CFLAGS=-g CXXFLAGS=-g} to build with debugging information and without
-the default optimization.
-
-Specifying variables as arguments to @code{configure}, like this:
-@example
-./configure CC=gcc
-@end example
-is preferable to setting them in environment variables:
-@example
-CC=gcc ./configure
-@end example
-as it helps to recreate the same configuration later with
-@file{config.status}. However, both methods should be supported.
-@end table
-
-All @code{configure} scripts should accept all of the ``detail''
-options and the variable settings, 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 compile a program to run on a host type that differs from the build
-type, use the configure option @option{--host=@var{hosttype}}, where
-@var{hosttype} uses the same syntax as @var{buildtype}. The host type
-normally defaults to the build type.
-
-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 --host=@var{hosttype} --target=@var{targettype}
-@end example
-
-The target type normally defaults to the host type.
-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.
-
-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
-
-You should identify each release with a pair of version numbers, a
-major version and a minor. We have no objection to using more than
-two numbers, but it is very unlikely that you really need them.
-
-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.LESSER}.
-
-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 all the files in the distribution are world-readable, and
-that directories are world-readable and world-searchable (octal mode 755).
-We used to recommend that all directories in the distribution also be
-world-writable (octal mode 777), because ancient versions of @code{tar}
-would otherwise not cope when extracting the archive as an unprivileged
-user. That can easily lead to security issues when creating the archive,
-however, so now we recommend against that.
-
-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, promote, or grant legitimacy to
-the use of any non-free program. Proprietary software is a social and
-ethical problem, and our aim is to put an end to that problem. We
-can't stop some people from writing proprietary programs, or stop
-other people from using them, but we can and should refuse to
-advertise them to new potential customers, or to give the public the
-idea that their existence is ethical.
-
-The GNU definition of free software is found on the GNU web site at
-@url{http://www.gnu.org/@/philosophy/@/free-sw.html}, and the definition
-of free documentation is found at
-@url{http://www.gnu.org/@/philosophy/@/free-doc.html}. The terms ``free''
-and ``non-free'', used in this document, refer to those definitions.
-
-A list of important licenses and whether they qualify as free is in
-@url{http://www.gnu.org/@/licenses/@/license-list.html}. If it is not
-clear whether a license qualifies as free, please ask the GNU Project
-by writing to @email{licensing@@gnu.org}. We will answer, and if the
-license is an important one, we will add it to the list.
-
-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 widely used 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 with it, while people who don't already use the proprietary
-program will not see anything likely 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 for your
-program among the users of Foobar, if the existence of Foobar is not
-generally known among people who might want to use your program.)
-
-Sometimes a program is free software in itself but depends on a
-non-free platform in order to run. For instance, many Java programs
-depend on some non-free Java libraries. To recommend or promote such
-a program is to promote the other programs it needs. This is why we
-are careful about listing Java programs in the Free Software
-Directory: we don't want to promote the non-free Java libraries.
-
-We hope this particular problem with Java will be gone by and by, as
-we replace the remaining non-free standard Java libraries with free
-software, but the general principle will remain the same: don't
-recommend, promote or legitimize programs that depend on non-free
-software to run.
-
-Some free programs strongly encourage the use of non-free software. A
-typical example is @command{mplayer}. It is free software in itself,
-and the free code can handle some kinds of files. However,
-@command{mplayer} recommends use of non-free codecs for other kinds of
-files, and users that install @command{mplayer} are very likely to
-install those codecs along with it. To recommend @command{mplayer}
-is, in effect, to promote use of the non-free codecs.
-
-Thus, you should not recommend programs that strongly encourage the
-use of non-free software. This is why we do not list
-@command{mplayer} in the Free Software Directory.
-
-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, or any
-free operating system, so encouraging it is a priority; to recommend
-use of documentation that we are not allowed to include undermines the
-impetus for the community to produce documentation that we can
-include. So GNU packages should never recommend non-free
-documentation.
-
-By contrast, it is ok to refer to journal articles and textbooks in
-the comments of a program for explanation of how it functions, even
-though they are non-free. This is because we don't include such
-things in the GNU system even they are free---they are outside the
-scope of what a software distribution needs to include.
-
-Referring to a web site that describes or recommends a non-free
-program is promoting that program, so please do not make links (or
-mention by name) web sites that contain such material. This policy is
-relevant particularly for the web pages for a GNU package.
-
-Following links from nearly any web site can lead eventually to
-non-free software; this is inherent in the nature of the web. So it
-makes no sense to criticize a site for having such links. As long as
-the site does not itself recommend a non-free program, there is no
-need to consider the question of the sites that it links to for other
-reasons.
-
-Thus, for example, you should not refer to AT&T's web site if that
-recommends AT&T's non-free software packages; you should not refer to
-a site that links to AT&T's site presenting it as a place to get some
-non-free program, because that link recommends and legitimizes the
-non-free program. However, that a site contains a link to AT&T's web
-site for some other purpose (such as long-distance telephone service)
-is not an objection against it.
-
-@node GNU Free Documentation License
-@appendix GNU Free Documentation License
-
-@cindex FDL, GNU Free Documentation License
-@include fdl.texi
-
-@node Index
-@unnumbered Index
-@printindex cp
-
-@bye
-
-Local variables:
-eval: (add-hook 'write-file-hooks 'time-stamp)
-time-stamp-start: "@set lastupdate "
-time-stamp-end: "$"
-time-stamp-format: "%:b %:d, %:y"
-compile-command: "cd work.s && make"
-End:
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-15 14:36:16 +0000