diff options
| -rw-r--r-- | etc/ChangeLog | 19 | ||||
| -rw-r--r-- | etc/Makefile.in | 182 | ||||
| -rw-r--r-- | etc/configbuild.ein | 149 | ||||
| -rw-r--r-- | etc/configbuild.fig | 50 | ||||
| -rw-r--r-- | etc/configbuild.jin | bin | 11123 -> 0 bytes | |||
| -rw-r--r-- | etc/configbuild.tin | 9 | ||||
| -rw-r--r-- | etc/configdev.ein | 185 | ||||
| -rw-r--r-- | etc/configdev.fig | 80 | ||||
| -rw-r--r-- | etc/configdev.jin | bin | 17967 -> 0 bytes | |||
| -rw-r--r-- | etc/configdev.tin | 17 | ||||
| -rw-r--r-- | etc/configure.texi | 2646 | ||||
| -rw-r--r-- | etc/fdl.texi | 505 | ||||
| -rw-r--r-- | etc/gnu-oids.texi | 52 | ||||
| -rw-r--r-- | etc/make-stds.texi | 1135 | ||||
| -rw-r--r-- | etc/standards.texi | 4235 |
15 files changed, 23 insertions, 9241 deletions
diff --git a/etc/ChangeLog b/etc/ChangeLog index d3b6a0b..516e6a9 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 0d19c13..4aa64c1 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 7a0e214..0000000 --- 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 747592d..0000000 --- a/etc/configbuild.fig +++ /dev/null @@ -1,50 +0,0 @@ -#FIG 3.1 -Portrait -Center -Inches -1200 2 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 1050 900 2100 900 2100 1425 1050 1425 1050 900 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1500 1425 1500 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1500 2625 1500 3300 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 2925 900 3825 900 3825 1425 2925 1425 2925 900 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 2325 2625 2325 2100 1050 2100 1050 2625 2325 2625 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 2850 2100 4125 2100 4125 2625 2850 2625 2850 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3375 1425 3375 2100 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 5100 900 6300 900 6300 1350 5100 1350 5100 900 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 5625 1350 5625 2100 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 6375 2625 6375 2100 5100 2100 5100 2625 6375 2625 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 5625 2625 5625 3300 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 5100 3300 6225 3300 6225 3750 5100 3750 5100 3300 -2 1 2 1 -1 7 0 0 -1 3.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 2850 2400 2325 2400 -2 1 2 1 -1 7 0 0 -1 3.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4125 2400 5100 2400 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 1050 3300 1950 3300 1950 3750 1050 3750 1050 3300 -4 0 -1 0 0 0 12 0.0000000 4 180 645 1200 1200 config.in\001 -4 0 -1 0 0 0 12 0.0000000 4 180 705 3000 1200 configure\001 -4 0 -1 0 0 0 12 0.0000000 4 180 990 3000 2400 config.status\001 -4 0 -1 0 0 0 12 0.0000000 4 180 990 1200 2400 config.status\001 -4 0 -1 0 0 0 12 0.0000000 4 180 600 1200 3600 config.h\001 -4 0 -1 0 0 0 12 0.0000000 4 135 855 5250 1200 Makefile.in\001 -4 0 -1 0 0 0 12 0.0000000 4 180 990 5250 2400 config.status\001 -4 0 -1 0 0 0 12 0.0000000 4 135 675 5250 3600 Makefile\001 diff --git a/etc/configbuild.jin b/etc/configbuild.jin Binary files differdeleted file mode 100644 index 44cd939..0000000 --- a/etc/configbuild.jin +++ /dev/null diff --git a/etc/configbuild.tin b/etc/configbuild.tin deleted file mode 100644 index cfdd6fe..0000000 --- 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 7f83785..0000000 --- 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 4d386ec..0000000 --- a/etc/configdev.fig +++ /dev/null @@ -1,80 +0,0 @@ -#FIG 3.1 -Portrait -Center -Inches -1200 2 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 1050 900 2100 900 2100 1425 1050 1425 1050 900 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 2925 900 3975 900 3975 1425 2925 1425 2925 900 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 5550 900 6750 900 6750 1350 5550 1350 5550 900 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 3750 1800 5025 1800 5025 2250 3750 2250 3750 1800 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 2175 2625 2175 2100 1050 2100 1050 2625 2175 2625 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 5550 3300 6675 3300 6675 3750 5550 3750 5550 3300 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 6600 2625 6600 2100 5550 2100 5550 2625 6600 2625 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 3750 3600 4875 3600 4875 4050 3750 4050 3750 3600 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 4650 3150 4650 2700 3750 2700 3750 3150 4650 3150 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 2850 5700 3750 5700 3750 6150 2850 6150 2850 5700 -2 4 0 1 -1 7 0 0 -1 0.000 0 0 7 0 0 5 - 3750 5250 3750 4800 2925 4800 2925 5250 3750 5250 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1500 1425 1500 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3300 1425 3300 4800 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 3 - 1 1 1.00 60.00 120.00 - 3300 1575 1875 1575 1875 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 3 - 1 1 1.00 60.00 120.00 - 3300 1575 5700 1575 5700 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 6225 1350 6225 2100 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 6075 2625 6075 3300 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4200 2250 4200 2700 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4200 3150 4200 3600 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 4 - 1 1 1.00 60.00 120.00 - 4200 4050 4200 4500 3675 4500 3675 4800 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3375 5250 3375 5700 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3300 2925 3750 2925 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1500 2625 1500 3300 -2 2 0 1 -1 7 0 0 -1 0.000 0 0 0 0 0 5 - 1050 3300 2100 3300 2100 3750 1050 3750 1050 3300 -2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 1 0 4 - 1 1 1.00 60.00 120.00 - 4875 3825 5250 3825 5250 2400 5550 2400 -4 0 -1 0 0 0 12 0.0000000 4 180 780 1200 1200 acconfig.h\001 -4 0 -1 0 0 0 12 0.0000000 4 180 885 3000 1200 configure.in\001 -4 0 -1 0 0 0 12 0.0000000 4 135 945 5700 1200 Makefile.am\001 -4 0 -1 0 0 0 12 0.0000000 4 135 990 3900 2100 acinclude.m4\001 -4 0 -1 0 0 0 12 0.0000000 4 135 840 1200 2400 autoheader\001 -4 0 -1 0 0 0 12 0.0000000 4 180 645 1200 3600 config.in\001 -4 0 -1 0 0 0 12 0.0000000 4 135 855 5700 3600 Makefile.in\001 -4 0 -1 0 0 0 12 0.0000000 4 135 735 5700 2400 automake\001 -4 0 -1 0 0 0 12 0.0000000 4 135 810 3900 3900 aclocal.m4\001 -4 0 -1 0 0 0 12 0.0000000 4 135 540 3900 3000 aclocal\001 -4 0 -1 0 0 0 12 0.0000000 4 180 705 3000 6000 configure\001 -4 0 -1 0 0 0 12 0.0000000 4 135 660 3000 5100 autoconf\001 diff --git a/etc/configdev.jin b/etc/configdev.jin Binary files differdeleted file mode 100644 index 9b11a71..0000000 --- a/etc/configdev.jin +++ /dev/null diff --git a/etc/configdev.tin b/etc/configdev.tin deleted file mode 100644 index c9b6f34..0000000 --- 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 58c5285..0000000 --- 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 7c26c34..0000000 --- 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 da9146c..0000000 --- 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 91a1ed0..0000000 --- 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 4b1c03d..0000000 --- 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: |