URL
https://opencores.org/ocsvn/or1k/or1k/trunk
Subversion Repositories or1k
Compare Revisions
- This comparison shows the changes necessary to convert path
/or1k/trunk/gdb-5.3/etc
- from Rev 1181 to Rev 1765
- ↔ Reverse comparison
Rev 1181 → Rev 1765
/configure
0,0 → 1,862
#! /bin/sh |
|
# Guess values for system-dependent variables and create Makefiles. |
# Generated automatically using autoconf version 2.12.1 |
# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. |
# |
# This configure script is free software; the Free Software Foundation |
# gives unlimited permission to copy, distribute and modify it. |
|
# Defaults: |
ac_help= |
ac_default_prefix=/usr/local |
# Any additions from configure.in: |
|
# Initialize some variables set by options. |
# The variables have the same names as the options, with |
# dashes changed to underlines. |
build=NONE |
cache_file=./config.cache |
exec_prefix=NONE |
host=NONE |
no_create= |
nonopt=NONE |
no_recursion= |
prefix=NONE |
program_prefix=NONE |
program_suffix=NONE |
program_transform_name=s,x,x, |
silent= |
site= |
srcdir= |
target=NONE |
verbose= |
x_includes=NONE |
x_libraries=NONE |
bindir='${exec_prefix}/bin' |
sbindir='${exec_prefix}/sbin' |
libexecdir='${exec_prefix}/libexec' |
datadir='${prefix}/share' |
sysconfdir='${prefix}/etc' |
sharedstatedir='${prefix}/com' |
localstatedir='${prefix}/var' |
libdir='${exec_prefix}/lib' |
includedir='${prefix}/include' |
oldincludedir='/usr/include' |
infodir='${prefix}/info' |
mandir='${prefix}/man' |
|
# Initialize some other variables. |
subdirs= |
MFLAGS= MAKEFLAGS= |
SHELL=${CONFIG_SHELL-/bin/sh} |
# Maximum number of lines to put in a shell here document. |
ac_max_here_lines=12 |
|
ac_prev= |
for ac_option |
do |
|
# If the previous option needs an argument, assign it. |
if test -n "$ac_prev"; then |
eval "$ac_prev=\$ac_option" |
ac_prev= |
continue |
fi |
|
case "$ac_option" in |
-*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; |
*) ac_optarg= ;; |
esac |
|
# Accept the important Cygnus configure options, so we can diagnose typos. |
|
case "$ac_option" in |
|
-bindir | --bindir | --bindi | --bind | --bin | --bi) |
ac_prev=bindir ;; |
-bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) |
bindir="$ac_optarg" ;; |
|
-build | --build | --buil | --bui | --bu) |
ac_prev=build ;; |
-build=* | --build=* | --buil=* | --bui=* | --bu=*) |
build="$ac_optarg" ;; |
|
-cache-file | --cache-file | --cache-fil | --cache-fi \ |
| --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) |
ac_prev=cache_file ;; |
-cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ |
| --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) |
cache_file="$ac_optarg" ;; |
|
-datadir | --datadir | --datadi | --datad | --data | --dat | --da) |
ac_prev=datadir ;; |
-datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ |
| --da=*) |
datadir="$ac_optarg" ;; |
|
-disable-* | --disable-*) |
ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` |
# Reject names that are not valid shell variable names. |
if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then |
{ echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } |
fi |
ac_feature=`echo $ac_feature| sed 's/-/_/g'` |
eval "enable_${ac_feature}=no" ;; |
|
-enable-* | --enable-*) |
ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` |
# Reject names that are not valid shell variable names. |
if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then |
{ echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } |
fi |
ac_feature=`echo $ac_feature| sed 's/-/_/g'` |
case "$ac_option" in |
*=*) ;; |
*) ac_optarg=yes ;; |
esac |
eval "enable_${ac_feature}='$ac_optarg'" ;; |
|
-exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ |
| --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ |
| --exec | --exe | --ex) |
ac_prev=exec_prefix ;; |
-exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ |
| --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ |
| --exec=* | --exe=* | --ex=*) |
exec_prefix="$ac_optarg" ;; |
|
-gas | --gas | --ga | --g) |
# Obsolete; use --with-gas. |
with_gas=yes ;; |
|
-help | --help | --hel | --he) |
# Omit some internal or obsolete options to make the list less imposing. |
# This message is too long to be a string in the A/UX 3.1 sh. |
cat << EOF |
Usage: configure [options] [host] |
Options: [defaults in brackets after descriptions] |
Configuration: |
--cache-file=FILE cache test results in FILE |
--help print this message |
--no-create do not create output files |
--quiet, --silent do not print \`checking...' messages |
--version print the version of autoconf that created configure |
Directory and file names: |
--prefix=PREFIX install architecture-independent files in PREFIX |
[$ac_default_prefix] |
--exec-prefix=EPREFIX install architecture-dependent files in EPREFIX |
[same as prefix] |
--bindir=DIR user executables in DIR [EPREFIX/bin] |
--sbindir=DIR system admin executables in DIR [EPREFIX/sbin] |
--libexecdir=DIR program executables in DIR [EPREFIX/libexec] |
--datadir=DIR read-only architecture-independent data in DIR |
[PREFIX/share] |
--sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] |
--sharedstatedir=DIR modifiable architecture-independent data in DIR |
[PREFIX/com] |
--localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] |
--libdir=DIR object code libraries in DIR [EPREFIX/lib] |
--includedir=DIR C header files in DIR [PREFIX/include] |
--oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] |
--infodir=DIR info documentation in DIR [PREFIX/info] |
--mandir=DIR man documentation in DIR [PREFIX/man] |
--srcdir=DIR find the sources in DIR [configure dir or ..] |
--program-prefix=PREFIX prepend PREFIX to installed program names |
--program-suffix=SUFFIX append SUFFIX to installed program names |
--program-transform-name=PROGRAM |
run sed PROGRAM on installed program names |
EOF |
cat << EOF |
Host type: |
--build=BUILD configure for building on BUILD [BUILD=HOST] |
--host=HOST configure for HOST [guessed] |
--target=TARGET configure for TARGET [TARGET=HOST] |
Features and packages: |
--disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) |
--enable-FEATURE[=ARG] include FEATURE [ARG=yes] |
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes] |
--without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) |
--x-includes=DIR X include files are in DIR |
--x-libraries=DIR X library files are in DIR |
EOF |
if test -n "$ac_help"; then |
echo "--enable and --with options recognized:$ac_help" |
fi |
exit 0 ;; |
|
-host | --host | --hos | --ho) |
ac_prev=host ;; |
-host=* | --host=* | --hos=* | --ho=*) |
host="$ac_optarg" ;; |
|
-includedir | --includedir | --includedi | --included | --include \ |
| --includ | --inclu | --incl | --inc) |
ac_prev=includedir ;; |
-includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ |
| --includ=* | --inclu=* | --incl=* | --inc=*) |
includedir="$ac_optarg" ;; |
|
-infodir | --infodir | --infodi | --infod | --info | --inf) |
ac_prev=infodir ;; |
-infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) |
infodir="$ac_optarg" ;; |
|
-libdir | --libdir | --libdi | --libd) |
ac_prev=libdir ;; |
-libdir=* | --libdir=* | --libdi=* | --libd=*) |
libdir="$ac_optarg" ;; |
|
-libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ |
| --libexe | --libex | --libe) |
ac_prev=libexecdir ;; |
-libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ |
| --libexe=* | --libex=* | --libe=*) |
libexecdir="$ac_optarg" ;; |
|
-localstatedir | --localstatedir | --localstatedi | --localstated \ |
| --localstate | --localstat | --localsta | --localst \ |
| --locals | --local | --loca | --loc | --lo) |
ac_prev=localstatedir ;; |
-localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ |
| --localstate=* | --localstat=* | --localsta=* | --localst=* \ |
| --locals=* | --local=* | --loca=* | --loc=* | --lo=*) |
localstatedir="$ac_optarg" ;; |
|
-mandir | --mandir | --mandi | --mand | --man | --ma | --m) |
ac_prev=mandir ;; |
-mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) |
mandir="$ac_optarg" ;; |
|
-nfp | --nfp | --nf) |
# Obsolete; use --without-fp. |
with_fp=no ;; |
|
-no-create | --no-create | --no-creat | --no-crea | --no-cre \ |
| --no-cr | --no-c) |
no_create=yes ;; |
|
-no-recursion | --no-recursion | --no-recursio | --no-recursi \ |
| --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) |
no_recursion=yes ;; |
|
-oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ |
| --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ |
| --oldin | --oldi | --old | --ol | --o) |
ac_prev=oldincludedir ;; |
-oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ |
| --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ |
| --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) |
oldincludedir="$ac_optarg" ;; |
|
-prefix | --prefix | --prefi | --pref | --pre | --pr | --p) |
ac_prev=prefix ;; |
-prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) |
prefix="$ac_optarg" ;; |
|
-program-prefix | --program-prefix | --program-prefi | --program-pref \ |
| --program-pre | --program-pr | --program-p) |
ac_prev=program_prefix ;; |
-program-prefix=* | --program-prefix=* | --program-prefi=* \ |
| --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) |
program_prefix="$ac_optarg" ;; |
|
-program-suffix | --program-suffix | --program-suffi | --program-suff \ |
| --program-suf | --program-su | --program-s) |
ac_prev=program_suffix ;; |
-program-suffix=* | --program-suffix=* | --program-suffi=* \ |
| --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) |
program_suffix="$ac_optarg" ;; |
|
-program-transform-name | --program-transform-name \ |
| --program-transform-nam | --program-transform-na \ |
| --program-transform-n | --program-transform- \ |
| --program-transform | --program-transfor \ |
| --program-transfo | --program-transf \ |
| --program-trans | --program-tran \ |
| --progr-tra | --program-tr | --program-t) |
ac_prev=program_transform_name ;; |
-program-transform-name=* | --program-transform-name=* \ |
| --program-transform-nam=* | --program-transform-na=* \ |
| --program-transform-n=* | --program-transform-=* \ |
| --program-transform=* | --program-transfor=* \ |
| --program-transfo=* | --program-transf=* \ |
| --program-trans=* | --program-tran=* \ |
| --progr-tra=* | --program-tr=* | --program-t=*) |
program_transform_name="$ac_optarg" ;; |
|
-q | -quiet | --quiet | --quie | --qui | --qu | --q \ |
| -silent | --silent | --silen | --sile | --sil) |
silent=yes ;; |
|
-sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) |
ac_prev=sbindir ;; |
-sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ |
| --sbi=* | --sb=*) |
sbindir="$ac_optarg" ;; |
|
-sharedstatedir | --sharedstatedir | --sharedstatedi \ |
| --sharedstated | --sharedstate | --sharedstat | --sharedsta \ |
| --sharedst | --shareds | --shared | --share | --shar \ |
| --sha | --sh) |
ac_prev=sharedstatedir ;; |
-sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ |
| --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ |
| --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ |
| --sha=* | --sh=*) |
sharedstatedir="$ac_optarg" ;; |
|
-site | --site | --sit) |
ac_prev=site ;; |
-site=* | --site=* | --sit=*) |
site="$ac_optarg" ;; |
|
-srcdir | --srcdir | --srcdi | --srcd | --src | --sr) |
ac_prev=srcdir ;; |
-srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) |
srcdir="$ac_optarg" ;; |
|
-sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ |
| --syscon | --sysco | --sysc | --sys | --sy) |
ac_prev=sysconfdir ;; |
-sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ |
| --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) |
sysconfdir="$ac_optarg" ;; |
|
-target | --target | --targe | --targ | --tar | --ta | --t) |
ac_prev=target ;; |
-target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) |
target="$ac_optarg" ;; |
|
-v | -verbose | --verbose | --verbos | --verbo | --verb) |
verbose=yes ;; |
|
-version | --version | --versio | --versi | --vers) |
echo "configure generated by autoconf version 2.12.1" |
exit 0 ;; |
|
-with-* | --with-*) |
ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` |
# Reject names that are not valid shell variable names. |
if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then |
{ echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } |
fi |
ac_package=`echo $ac_package| sed 's/-/_/g'` |
case "$ac_option" in |
*=*) ;; |
*) ac_optarg=yes ;; |
esac |
eval "with_${ac_package}='$ac_optarg'" ;; |
|
-without-* | --without-*) |
ac_package=`echo $ac_option|sed -e 's/-*without-//'` |
# Reject names that are not valid shell variable names. |
if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then |
{ echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } |
fi |
ac_package=`echo $ac_package| sed 's/-/_/g'` |
eval "with_${ac_package}=no" ;; |
|
--x) |
# Obsolete; use --with-x. |
with_x=yes ;; |
|
-x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ |
| --x-incl | --x-inc | --x-in | --x-i) |
ac_prev=x_includes ;; |
-x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ |
| --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) |
x_includes="$ac_optarg" ;; |
|
-x-libraries | --x-libraries | --x-librarie | --x-librari \ |
| --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) |
ac_prev=x_libraries ;; |
-x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ |
| --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) |
x_libraries="$ac_optarg" ;; |
|
-*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } |
;; |
|
*) |
if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then |
echo "configure: warning: $ac_option: invalid host type" 1>&2 |
fi |
if test "x$nonopt" != xNONE; then |
{ echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } |
fi |
nonopt="$ac_option" |
;; |
|
esac |
done |
|
if test -n "$ac_prev"; then |
{ echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; } |
fi |
|
trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 |
|
# File descriptor usage: |
# 0 standard input |
# 1 file creation |
# 2 errors and warnings |
# 3 some systems may open it to /dev/tty |
# 4 used on the Kubota Titan |
# 6 checking for... messages and results |
# 5 compiler messages saved in config.log |
if test "$silent" = yes; then |
exec 6>/dev/null |
else |
exec 6>&1 |
fi |
exec 5>./config.log |
|
echo "\ |
This file contains any messages produced by compilers while |
running configure, to aid debugging if configure makes a mistake. |
" 1>&5 |
|
# Strip out --no-create and --no-recursion so they do not pile up. |
# Also quote any args containing shell metacharacters. |
ac_configure_args= |
for ac_arg |
do |
case "$ac_arg" in |
-no-create | --no-create | --no-creat | --no-crea | --no-cre \ |
| --no-cr | --no-c) ;; |
-no-recursion | --no-recursion | --no-recursio | --no-recursi \ |
| --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;; |
*" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*) |
ac_configure_args="$ac_configure_args '$ac_arg'" ;; |
*) ac_configure_args="$ac_configure_args $ac_arg" ;; |
esac |
done |
|
# NLS nuisances. |
# Only set these to C if already set. These must not be set unconditionally |
# because not all systems understand e.g. LANG=C (notably SCO). |
# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'! |
# Non-C LC_CTYPE values break the ctype check. |
if test "${LANG+set}" = set; then LANG=C; export LANG; fi |
if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi |
if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi |
if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi |
|
# confdefs.h avoids OS command line length limits that DEFS can exceed. |
rm -rf conftest* confdefs.h |
# AIX cpp loses on an empty file, so make sure it contains at least a newline. |
echo > confdefs.h |
|
# A filename unique to this package, relative to the directory that |
# configure is in, which we can look for to find out if srcdir is correct. |
ac_unique_file=Makefile.in |
|
# Find the source files, if location was not specified. |
if test -z "$srcdir"; then |
ac_srcdir_defaulted=yes |
# Try the directory containing this script, then its parent. |
ac_prog=$0 |
ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` |
test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. |
srcdir=$ac_confdir |
if test ! -r $srcdir/$ac_unique_file; then |
srcdir=.. |
fi |
else |
ac_srcdir_defaulted=no |
fi |
if test ! -r $srcdir/$ac_unique_file; then |
if test "$ac_srcdir_defaulted" = yes; then |
{ echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; } |
else |
{ echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; } |
fi |
fi |
srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` |
|
# Prefer explicitly selected file to automatically selected ones. |
if test -z "$CONFIG_SITE"; then |
if test "x$prefix" != xNONE; then |
CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" |
else |
CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" |
fi |
fi |
for ac_site_file in $CONFIG_SITE; do |
if test -r "$ac_site_file"; then |
echo "loading site script $ac_site_file" |
. "$ac_site_file" |
fi |
done |
|
if test -r "$cache_file"; then |
echo "loading cache $cache_file" |
. $cache_file |
else |
echo "creating cache $cache_file" |
> $cache_file |
fi |
|
ac_ext=c |
# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. |
ac_cpp='$CPP $CPPFLAGS' |
ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' |
ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' |
cross_compiling=$ac_cv_prog_cc_cross |
|
if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then |
# Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. |
if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then |
ac_n= ac_c=' |
' ac_t=' ' |
else |
ac_n=-n ac_c= ac_t= |
fi |
else |
ac_n= ac_c='\c' ac_t= |
fi |
|
|
|
ac_aux_dir= |
for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do |
if test -f $ac_dir/install-sh; then |
ac_aux_dir=$ac_dir |
ac_install_sh="$ac_aux_dir/install-sh -c" |
break |
elif test -f $ac_dir/install.sh; then |
ac_aux_dir=$ac_dir |
ac_install_sh="$ac_aux_dir/install.sh -c" |
break |
fi |
done |
if test -z "$ac_aux_dir"; then |
{ echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; } |
fi |
ac_config_guess=$ac_aux_dir/config.guess |
ac_config_sub=$ac_aux_dir/config.sub |
ac_configure=$ac_aux_dir/configure # This should be Cygnus configure. |
|
# Find a good install program. We prefer a C program (faster), |
# so one script is as good as another. But avoid the broken or |
# incompatible versions: |
# SysV /etc/install, /usr/sbin/install |
# SunOS /usr/etc/install |
# IRIX /sbin/install |
# AIX /bin/install |
# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag |
# AFS /usr/afsws/bin/install, which mishandles nonexistent args |
# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff" |
# ./install, which can be erroneously created by make from ./install.sh. |
echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6 |
echo "configure:555: checking for a BSD compatible install" >&5 |
if test -z "$INSTALL"; then |
if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then |
echo $ac_n "(cached) $ac_c" 1>&6 |
else |
IFS="${IFS= }"; ac_save_IFS="$IFS"; IFS="${IFS}:" |
for ac_dir in $PATH; do |
# Account for people who put trailing slashes in PATH elements. |
case "$ac_dir/" in |
/|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;; |
*) |
# OSF1 and SCO ODT 3.0 have their own names for install. |
# Don't use installbsd from OSF since it installs stuff as root |
# by default. |
for ac_prog in ginstall scoinst install; do |
if test -f $ac_dir/$ac_prog; then |
if test $ac_prog = install && |
grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then |
# AIX install. It has an incompatible calling convention. |
: |
else |
ac_cv_path_install="$ac_dir/$ac_prog -c" |
break 2 |
fi |
fi |
done |
;; |
esac |
done |
IFS="$ac_save_IFS" |
|
fi |
if test "${ac_cv_path_install+set}" = set; then |
INSTALL="$ac_cv_path_install" |
else |
# As a last resort, use the slow shell script. We don't cache a |
# path for INSTALL within a source directory, because that will |
# break other packages using the cache if that directory is |
# removed, or if the path is relative. |
INSTALL="$ac_install_sh" |
fi |
fi |
echo "$ac_t""$INSTALL" 1>&6 |
|
# Use test -z because SunOS4 sh mishandles braces in ${var-val}. |
# It thinks the first close brace ends the variable substitution. |
test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}' |
|
test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' |
|
|
trap '' 1 2 15 |
cat > confcache <<\EOF |
# This file is a shell script that caches the results of configure |
# tests run on this system so they can be shared between configure |
# scripts and configure runs. It is not useful on other systems. |
# If it contains results you don't want to keep, you may remove or edit it. |
# |
# By default, configure uses ./config.cache as the cache file, |
# creating it if it does not exist already. You can give configure |
# the --cache-file=FILE option to use a different cache file; that is |
# what configure does when it calls configure scripts in |
# subdirectories, so they share the cache. |
# Giving --cache-file=/dev/null disables caching, for debugging configure. |
# config.status only pays attention to the cache file if you give it the |
# --recheck option to rerun configure. |
# |
EOF |
# The following way of writing the cache mishandles newlines in values, |
# but we know of no workaround that is simple, portable, and efficient. |
# So, don't put newlines in cache variables' values. |
# Ultrix sh set writes to stderr and can't be redirected directly, |
# and sets the high bit in the cache file unless we assign to the vars. |
(set) 2>&1 | |
case `(ac_space=' '; set) 2>&1 | grep ac_space` in |
*ac_space=\ *) |
# `set' does not quote correctly, so add quotes (double-quote substitution |
# turns \\\\ into \\, and sed turns \\ into \). |
sed -n \ |
-e "s/'/'\\\\''/g" \ |
-e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p" |
;; |
*) |
# `set' quotes correctly as required by POSIX, so do not add quotes. |
sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p' |
;; |
esac >> confcache |
if cmp -s $cache_file confcache; then |
: |
else |
if test -w $cache_file; then |
echo "updating cache $cache_file" |
cat confcache > $cache_file |
else |
echo "not updating unwritable cache $cache_file" |
fi |
fi |
rm -f confcache |
|
trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 |
|
test "x$prefix" = xNONE && prefix=$ac_default_prefix |
# Let make expand exec_prefix. |
test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' |
|
# Any assignment to VPATH causes Sun make to only execute |
# the first set of double-colon rules, so remove it if not needed. |
# If there is a colon in the path, we need to keep it. |
if test "x$srcdir" = x.; then |
ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' |
fi |
|
trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 |
|
# Transform confdefs.h into DEFS. |
# Protect against shell expansion while executing Makefile rules. |
# Protect against Makefile macro expansion. |
cat > conftest.defs <<\EOF |
s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g |
s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g |
s%\[%\\&%g |
s%\]%\\&%g |
s%\$%$$%g |
EOF |
DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '` |
rm -f conftest.defs |
|
|
# Without the "./", some shells look in PATH for config.status. |
: ${CONFIG_STATUS=./config.status} |
|
echo creating $CONFIG_STATUS |
rm -f $CONFIG_STATUS |
cat > $CONFIG_STATUS <<EOF |
#! /bin/sh |
# Generated automatically by configure. |
# Run this file to recreate the current configuration. |
# This directory was configured as follows, |
# on host `(hostname || uname -n) 2>/dev/null | sed 1q`: |
# |
# $0 $ac_configure_args |
# |
# Compiler output produced by configure, useful for debugging |
# configure, is in ./config.log if it exists. |
|
ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]" |
for ac_option |
do |
case "\$ac_option" in |
-recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) |
echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" |
exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; |
-version | --version | --versio | --versi | --vers | --ver | --ve | --v) |
echo "$CONFIG_STATUS generated by autoconf version 2.12.1" |
exit 0 ;; |
-help | --help | --hel | --he | --h) |
echo "\$ac_cs_usage"; exit 0 ;; |
*) echo "\$ac_cs_usage"; exit 1 ;; |
esac |
done |
|
ac_given_srcdir=$srcdir |
ac_given_INSTALL="$INSTALL" |
|
trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 |
EOF |
cat >> $CONFIG_STATUS <<EOF |
|
# Protect against being on the right side of a sed subst in config.status. |
sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; |
s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF |
$ac_vpsub |
$extrasub |
s%@SHELL@%$SHELL%g |
s%@CFLAGS@%$CFLAGS%g |
s%@CPPFLAGS@%$CPPFLAGS%g |
s%@CXXFLAGS@%$CXXFLAGS%g |
s%@DEFS@%$DEFS%g |
s%@LDFLAGS@%$LDFLAGS%g |
s%@LIBS@%$LIBS%g |
s%@exec_prefix@%$exec_prefix%g |
s%@prefix@%$prefix%g |
s%@program_transform_name@%$program_transform_name%g |
s%@bindir@%$bindir%g |
s%@sbindir@%$sbindir%g |
s%@libexecdir@%$libexecdir%g |
s%@datadir@%$datadir%g |
s%@sysconfdir@%$sysconfdir%g |
s%@sharedstatedir@%$sharedstatedir%g |
s%@localstatedir@%$localstatedir%g |
s%@libdir@%$libdir%g |
s%@includedir@%$includedir%g |
s%@oldincludedir@%$oldincludedir%g |
s%@infodir@%$infodir%g |
s%@mandir@%$mandir%g |
s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g |
s%@INSTALL_DATA@%$INSTALL_DATA%g |
|
CEOF |
EOF |
|
cat >> $CONFIG_STATUS <<\EOF |
|
# Split the substitutions into bite-sized pieces for seds with |
# small command number limits, like on Digital OSF/1 and HP-UX. |
ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script. |
ac_file=1 # Number of current file. |
ac_beg=1 # First line for current file. |
ac_end=$ac_max_sed_cmds # Line after last line for current file. |
ac_more_lines=: |
ac_sed_cmds="" |
while $ac_more_lines; do |
if test $ac_beg -gt 1; then |
sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file |
else |
sed "${ac_end}q" conftest.subs > conftest.s$ac_file |
fi |
if test ! -s conftest.s$ac_file; then |
ac_more_lines=false |
rm -f conftest.s$ac_file |
else |
if test -z "$ac_sed_cmds"; then |
ac_sed_cmds="sed -f conftest.s$ac_file" |
else |
ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file" |
fi |
ac_file=`expr $ac_file + 1` |
ac_beg=$ac_end |
ac_end=`expr $ac_end + $ac_max_sed_cmds` |
fi |
done |
if test -z "$ac_sed_cmds"; then |
ac_sed_cmds=cat |
fi |
EOF |
|
cat >> $CONFIG_STATUS <<EOF |
|
CONFIG_FILES=\${CONFIG_FILES-"Makefile"} |
EOF |
cat >> $CONFIG_STATUS <<\EOF |
for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then |
# Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in". |
case "$ac_file" in |
*:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'` |
ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; |
*) ac_file_in="${ac_file}.in" ;; |
esac |
|
# Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories. |
|
# Remove last slash and all that follows it. Not all systems have dirname. |
ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` |
if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then |
# The file is in a subdirectory. |
test ! -d "$ac_dir" && mkdir "$ac_dir" |
ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`" |
# A "../" for each directory in $ac_dir_suffix. |
ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` |
else |
ac_dir_suffix= ac_dots= |
fi |
|
case "$ac_given_srcdir" in |
.) srcdir=. |
if test -z "$ac_dots"; then top_srcdir=. |
else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; |
/*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; |
*) # Relative path. |
srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" |
top_srcdir="$ac_dots$ac_given_srcdir" ;; |
esac |
|
case "$ac_given_INSTALL" in |
[/$]*) INSTALL="$ac_given_INSTALL" ;; |
*) INSTALL="$ac_dots$ac_given_INSTALL" ;; |
esac |
|
echo creating "$ac_file" |
rm -f "$ac_file" |
configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." |
case "$ac_file" in |
*Makefile*) ac_comsub="1i\\ |
# $configure_input" ;; |
*) ac_comsub= ;; |
esac |
|
ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"` |
sed -e "$ac_comsub |
s%@configure_input@%$configure_input%g |
s%@srcdir@%$srcdir%g |
s%@top_srcdir@%$top_srcdir%g |
s%@INSTALL@%$INSTALL%g |
" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file |
fi; done |
rm -f conftest.s* |
|
EOF |
cat >> $CONFIG_STATUS <<EOF |
|
EOF |
cat >> $CONFIG_STATUS <<\EOF |
|
exit 0 |
EOF |
chmod +x $CONFIG_STATUS |
rm -fr confdefs* $ac_clean_files |
test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1 |
|
configure
Property changes :
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Index: Makefile.in
===================================================================
--- Makefile.in (nonexistent)
+++ Makefile.in (revision 1765)
@@ -0,0 +1,157 @@
+#
+# Makefile.in for etc
+#
+
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+
+srcdir = @srcdir@
+VPATH = @srcdir@
+
+bindir = @bindir@
+libdir = @libdir@
+tooldir = $(libdir)
+datadir = @datadir@
+
+mandir = @mandir@
+man1dir = $(mandir)/man1
+man2dir = $(mandir)/man2
+man3dir = $(mandir)/man3
+man4dir = $(mandir)/man4
+man5dir = $(mandir)/man5
+man6dir = $(mandir)/man6
+man7dir = $(mandir)/man7
+man8dir = $(mandir)/man8
+man9dir = $(mandir)/man9
+infodir = @infodir@
+
+SHELL = /bin/sh
+
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_DATA = @INSTALL_DATA@
+
+MAKEINFO = `if [ -f ../texinfo/makeinfo/makeinfo ]; \
+ then echo ../texinfo/makeinfo/makeinfo; \
+ else echo makeinfo; fi`
+TEXI2DVI = `if [ -f ../texinfo/util/texi2dvi ]; \
+ then echo ../texinfo/util/texi2dvi; \
+ else echo texi2dvi; fi`
+TEXI2HTML = texi2html
+DVIPS = dvips
+
+# Where to find texinfo.tex to format documentation with TeX.
+TEXIDIR = $(srcdir)/../texinfo
+
+#### Host, target, and site specific Makefile fragments come in here.
+###
+
+INFOFILES = standards.info configure.info
+DVIFILES = standards.dvi configure.dvi
+
+all:
+
+# We want install to imply install-info as per GNU standards.
+install: install-info
+
+uninstall:
+
+info:
+ for f in $(INFOFILES); do \
+ if test -f $(srcdir)/`echo $$f | sed -e 's/.info$$/.texi/'`; then \
+ if $(MAKE) "MAKEINFO=$(MAKEINFO)" $$f; then \
+ true; \
+ else \
+ exit 1; \
+ fi; \
+ fi; \
+ done
+
+install-info: info
+ $(SHELL) $(srcdir)/../mkinstalldirs $(infodir)
+ if test ! -f standards.info; then cd $(srcdir); fi; \
+ if test -f standards.info; then \
+ for i in standards.info*; do \
+ $(INSTALL_DATA) $$i $(infodir)/$$i; \
+ done; \
+ fi
+ if test ! -f configure.info; then cd $(srcdir); fi; \
+ if test -f configure.info; then \
+ for i in configure.info*; do \
+ $(INSTALL_DATA) $$i $(infodir)/$$i; \
+ done; \
+ fi
+
+dvi:
+ for f in $(DVIFILES); do \
+ if test -f $(srcdir)/`echo $$f | sed -e 's/.dvi$$/.texi/'`; then \
+ if $(MAKE) "TEXI2DVI=$(TEXI2DVI)" $$f; then \
+ true; \
+ else \
+ exit 1; \
+ fi; \
+ fi; \
+ done
+
+standards.info: $(srcdir)/standards.texi $(srcdir)/make-stds.texi
+ $(MAKEINFO) --no-split -I$(srcdir) -o standards.info $(srcdir)/standards.texi
+
+standards.dvi: $(srcdir)/standards.texi
+ TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/standards.texi
+
+standards.ps: standards.dvi
+ $(DVIPS) standards.dvi -o standards.ps
+
+# makeinfo requires images to be in the current directory.
+configure.info: $(srcdir)/configure.texi $(srcdir)/configdev.tin $(srcdir)/configbuild.tin
+ rm -f configdev.txt configbuild.txt
+ cp $(srcdir)/configdev.tin configdev.txt
+ cp $(srcdir)/configbuild.tin configbuild.txt
+ $(MAKEINFO) -I$(srcdir) -o configure.info $(srcdir)/configure.texi
+ rm -f configdev.txt configbuild.txt
+
+# texi2dvi wants both the .txt and the .eps files.
+configure.dvi: $(srcdir)/configure.texi $(srcdir)/configdev.tin $(srcdir)/configbuild.tin $(srcdir)/configdev.ein $(srcdir)/configbuild.ein
+ rm -f configdev.txt configbuild.txt
+ cp $(srcdir)/configdev.tin configdev.txt
+ cp $(srcdir)/configbuild.tin configbuild.txt
+ rm -f configdev.eps configbuild.eps
+ cp $(srcdir)/configdev.ein configdev.eps
+ cp $(srcdir)/configbuild.ein configbuild.eps
+ TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/configure.texi
+ rm -f configdev.txt configbuild.txt
+ rm -f configdev.eps configbuild.eps
+
+# dvips requires images to be in the current directory
+configure.ps: configure.dvi $(srcdir)/configdev.ein $(srcdir)/configbuild.ein
+ rm -f configdev.eps configbuild.eps
+ cp $(srcdir)/configdev.ein configdev.eps
+ cp $(srcdir)/configbuild.ein configbuild.eps
+ $(DVIPS) configure.dvi -o configure.ps
+ rm -f configdev.eps configbuild.eps
+
+configure.html: $(srcdir)/configure.texi
+ $(TEXI2HTML) -split_chapter $(srcdir)/configure.texi
+
+clean:
+ rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
+ rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs
+ rm -f configdev.txt configbuild.txt configdev.eps configbuild.eps
+ rm -f configdev.jpg configbuild.jpg
+
+mostlyclean: clean
+
+distclean: clean
+ rm -f Makefile config.status config.cache
+
+maintainer-clean realclean: distclean
+ rm -f *.info*
+
+Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag)
+ $(SHELL) ./config.status
+
+## these last targets are for standards.texi conformance
+dist:
+check:
+installcheck:
+TAGS:
Index: configdev.jin
===================================================================
--- configdev.jin (nonexistent)
+++ configdev.jin (revision 1765)
@@ -0,0 +1,150 @@
+ÿØÿà JFIF ÿÛ C
+
+ $.' ",# (7),01444 '9=82<.342ÿÛ C
+
+2! !22222222222222222222222222222222222222222222222222ÿÀ x–" ÿÄ
+ ÿÄ µ } !1AQa"q2‘¡#B±ÁRÑð$3br‚
+%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyzƒ„…†‡ˆ‰Š’“”•–—˜™š¢£¤¥¦§¨©ª²³´µ¶·¸¹ºÂÃÄÅÆÇÈÉÊÒÓÔÕÖ×ØÙÚáâãäåæçèéêñòóôõö÷øùúÿÄ
+ ÿÄ µ w !1AQaq"2B‘¡±Á #3RðbrÑ
+$4á%ñ&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz‚ƒ„…†‡ˆ‰Š’“”•–—˜™š¢£¤¥¦§¨©ª²³´µ¶·¸¹ºÂÃÄÅÆÇÈÉÊÒÓÔÕÖ×ØÙÚâãäåæçèéêòóôõö÷øùúÿÚ ? ÷ú(®/AÐmµ›;»ÛÛÝe§mNý?w¬]Ä¡RêTP$
+ U ”ÚQ\ÿ ü!º_üýkŸø=½ÿ ãÔÂ¥ÿ ÏÖ¹ÿ ƒÛßþ=@ Ïÿ Â¥ÿ ÏÖ¹ÿ ƒÛßþ=Gü!º_üýkŸø=½ÿ ãÔÐQ\ÿ ü!º_üýkŸø=½ÿ ãÔÂ¥ÿ ÏÖ¹ÿ ƒÛßþ=@ Ïÿ Â¥ÿ ÏÖ¹ÿ ƒÛßþ=Xþ,ðݦ™àÝrþÎû\Žê×O¸šþܼ;]cb§\ :ÐqEPEPEPEsþ3/ÿ úG óÃçj0»Á3Dû î$` Ha•b8# ð†éóõ®àö÷ÿ PAEsÿ ð†éóõ®àö÷ÿ Qÿ n—ÿ ?Zçþoøõ tW?ÿ n—ÿ ?Zçþoøõ ð†éóõ®àö÷ÿ PAEsÿ ð†éóõ®àö÷ÿ Qÿ n—ÿ ?Zçþoøõ tW?ÿ n—ÿ ?ZçþoøõS¶ÓcѼu§[Ú]jMÆ™xòÇu¨Ïr¥’[`¤ ]€ ;ŒŒu4ÖQE QE QE QE QE QE Q\ߊâ7Wž ²k‹¸`ºÔÙ&û-Ì3¨µ¸p FÊØÜŠqžÂ¤ÿ „7Kÿ Ÿsÿ ·¿üz€:
++Ÿÿ „7Kÿ Ÿsÿ ·¿üzøCt¿ùú×?ð{{ÿ Ǩ ¢¹ÿ øCt¿ùú×?ð{{ÿ Ǩÿ „7Kÿ Ÿsÿ ·¿üz€:
++Ÿÿ „7Kÿ Ÿsÿ ·¿üzøCt¿ùú×?ð{{ÿ Ǩ ¢¹ÿ øCt¿ùú×?ð{{ÿ Ǩÿ „7Kÿ Ÿsÿ ·¿üz€:
++»ÑáÑGÛ.à·óåX!ó¤ æHßu=XààM o³þÑþÎû\ nò¼ÿ ³yƒÌòó·~Þ»sÆzf¹¿øVçÅñÁo4q£ÛÏk)2¼,‹(QæN\.Ó˜I &Fâ6-XÓô}J vk»ˆ4ÓÕÂßÈÅšI ›ìÉnc*£Lù¹†eØ3¸ l&¦Éowpš…£Adî—R,ÊVA—s…*9 ã ê6×tuû>íVÄ}§Êò3pŸ½ówy{yù·ím¸ë´ã85ÍÚøSR‡ÃéŽ4Ñ=‚XEk*nÝr¶’,‰æ¾2Êãhåîb ™ÀÏ¿ðn½qk-¬CMÙs¦jÐJíràÇ5ì¾nygr#*®âT°$íÚ@:¼e¦Üêš…Œšh{+Ø,|¨ÒLü²ª€y £«:H¸]»Ž§öîý±ý‘ý«cý§ÿ >_hO;îîû™Ý÷yéÓšæïô
+zk-Eà‡Mk»ÝbËQ1=Ûª"–ŗxˆ’KÛ>QÃê6Ö>pÖ>5Ôá1ÞÎ׫ai5Ú¤ö"Fó¥3D‘å ’TebçkÀÇ †‘â8u oWѧ6j}ÆÁn—BG’‘ºË´…*šð@ Æ£ñßü“Ïÿ Ø*ëÿ E5e^ÿ „‘õ‡M
+uuíË~Æm[#ÊÀp6¸ ä®áÇSÇòOÙw¿Ÿ*Á O2Fû¨¹êÇ rk Æ_ò¶ÿ °®›ÿ ¥°Ñ¯è×—úåšXÍ‹K‹¡¾ÇåÌb,å@>f< <³´0có®9 ÔŸVÓmn%·¸Ô-!ž+su$rLªÉ82NBÆî•—øÇGÑ´yïÿ ´,eò®ÖÇíá˜.ÇnvmÎçà•PǪsøwR_K¨[›I §TŒI+#4ßcû(„€¤ÇÏæd‘÷v ½Xúoƒuè,ì-®š¢ -"ÞGŽåÛ沺2Œdv'ï6ÖÀêpqÒ¸¿Øêúy¾Ôe¹´Ó ]v+Ëå»(T[yö†’±)ÿ y*Ùkº Χ§YÝè¶ÖYµ½”+ ×/µ…ÃÉ–û˧ Hv›_NÐØ è"Þâàëzo‘n‘<ò}©6IJ c,s€Tž¹ã5cQÔ!ÓÒÜË=¤Oqq ™ÄBFfûªpw>ÝÄ(ûÄcŽ£‡k3x~4é¶Ú”Zìú«%µìñÊÊd :ž”ÖQ\ÿ ÛÙãúhø9›ÿ ‘h ¢¹ÿ ¶xÃþ€Z þfÿ äZ>Ùãúhø9›ÿ ‘h ®~óþJ ÿ `«ÿ ýiGÛºçþ¯øÍtP?ÿ –—ÿ >ºçþ¯øÍ ð™ióë®àŠ÷ÿ Œ×AE sÿ ð™ióë®àŠ÷ÿ ŒÑÿ –—ÿ >ºçþ¯øÍtP?ÿ –—ÿ >ºçþ¯øÍ ð™ióë®àŠ÷ÿ Œ×AE sÿ ð™ióë®àŠ÷ÿ ŒÖ ]Jk/]jÚzéª÷ÖúÚÌ@Ì“,×3ÂY$7¬»\ƒ€mäc?ÅzÎ¥¬øRÓnÓMyÚËW–âVµf–Îo(lŒ¾QÉdpÅ›i^‡# ˆú%åÕäšU‹Ý]Ä`¹™Ð¼ÑGle— 8
+ GX¡ˆiV"8eIâAn˜ŽDPˆê1Ã*ª¨# @ ü~-½“ÇwºHµ€i–2Åms;͘ÞX•ãrL›¾geˆ “È~
+Q®x‡X°Ö®-^ÄCرæÛ»1û\ÆÝ9¸èÒ >u`ƒaÏ@š åäzUŠ]ZD ¶™mÐ<1€@DleWŒ95]¼'á·ó7xJo6$‚LÙFwÆ›v¡ã• Ú¾‚€<ÿ Äþ%ºÔ!ÑÖî衱Õa{‰lìçx®¥‡P ¸ŽY lwnh—9ϬU8ô6™"Óí&¸ûTª°¨6àÞcqËîU;9 ö«”Ïø{þCž,ÿ °¬úEk]sþ ÿ ç‹?ì+ þ‘Z×A@Q@yÿ Æ›[Ë…ú¤¶7ÑMm¶VKG+æÆNÉ@>ô{ ˜ŽŸ('€k¬×5)¬-í¢³XÞþöámmV@J† ³9äd$k$›r»¶mŸ?‚´ýBÞXµ[ýgP3!IÚMNhVU#1BÉã{ä’Hžµ¼³ð6‹£q}=óZ$·~å¦8ÞÊÄóò–*ä jè+Ÿÿ „7Kÿ Ÿsÿ ·¿üzøCt¿ùú×?ð{{ÿ Ǩ ¢¹ÿ øCt¿ùú×?ð{{ÿ Ǩÿ „7Kÿ Ÿsÿ ·¿üz€<ÿ á&•¬YøçÆßÚ7úäööweƒíó;$ùùYu»Ð]¶…Ë~÷“µTdö v©?á
+Òÿ çë\ÿ Áíïÿ ‚Šçÿ á°Oš ýr)‡)'öÍÔ›±Û$ŒƒÙ•”ô Ž*Æ}po/´‹ù<Û» -–b ˆ ’°_•[rH„ dÆX*«*€
+Š(¢€
+(¢€
+çüÿ ;Ÿû
+ê_ú[5tÏø7þ@w?öÔ¿ô¶j غ¿³±ò>Ùw¿Ÿ*Á O2Fû¨¹êÇ rj›ø—AÝ [ÓUÑåFSt€«D»¥ž
+)Ëá œV?ü+sâ‹xà·š8Ñíçµ”™^E”(ó'.iÌ$„“#q£ Ö?á ‡Q)b#:‚jr¨¸|¬†ÐZÍ¥O¡y¾süÖò¤+öœlâAäçÉÎïõƒ ܽÿ #ê
+š êêÛ–0ýŒÚ¶G•€àmp2AÉ]ÈPš¶›%½ÝÂj“º]H³)X\9Ψ䃌w¬¿ø®ÏÃÞ›_Ž{ãy¶Ë-à‰.¾]ác|6æe¨ îã ärú/€um3A¸Ód{‘b‚¹û]ÄvK¾!ó“öO—pýÖý&ôÚP#xU:'ØK@e·Ôlœ½Ì’˜â½t•äÞ˺GP `ÃBJ€â}[Mµ¸–ÞãP´†xÍÔ‘É2«$ àÈA9ºT–·öwÞØîà¸ò%h&òdåÈ¿y dd EqgÂÚä~.¸×’
+6g™â»%Ô.UmgâF£Ë2®Ñ)UeÞIWÚô Ñæðÿ ƒ´"â Hg³·X¤ŒZ6aÕÁ*§,~cÇV<ž¤;Ïù(z7ý‚¯ÿ ôm¥tÏÞÉCÑ¿ìÿ £m+ Š( Š( Š( ¹ÿ ÿ É<ñ/ý‚®¿ôSWA\ÿ Žÿ äžx—þÁW_ú)¨ ¢Š( ¬}{I¼ÔÛLžÂö K« ³r=±1IR¡Ðô”œçµlQ@ ÿ Øüaÿ AÝÿ ÓòU cñ‡ýt?üMÿ ÉUÐQ@ ÿ Øüaÿ AÝÿ ÓòUgÃqã |C{¤ÿ kècìÖ\ù¿Ù|ÞkÌ»qöž1äç9çwlsØW?gÿ %Yÿ °U‡þ» ì~0ÿ î‡ÿ ‚i¿ù*±øÃþƒº þ ¦ÿ äªè( ì~0ÿ î‡ÿ ‚i¿ù*±øÃþƒº þ ¦ÿ äªè( ì~0ÿ î‡ÿ ‚i¿ù*±øÃþƒº þ ¦ÿ äªè( }I¼ÓSžþö »«û±rí±GP¥Üôˆ ç½lQE W7ŠînŒíeá}fî®&·óã’ÑUÚ)6 <êØ܇¨Íøãâ&½á;N¹³ð…ð’ãPŠØÇvпœ1òãòfv £© x' €u !ÿ ç„ÿ ì+'þ‘]WA^g¥ø³WñF§á™5OêZMbUStÃkâÊã `¯“¸ÿ ß”üÙâ½2€3ÿ ·tú
+Øÿ ÇßØãá?ããþxõÿ YþÏ_j¦¾2ðËÞÙY¦¿¦¼÷È^ÕRåXL„ùH8$·ÊrHlgiÇ/aà]VÊ+•ó-ÊYl&æB²=œþr…qI¹2°íCî ji~ Ö4ëûâ–/$RÞ‰b Žîxî •¼¾Z6V@¤ ã Y Ú :®èëÒVÄG ¯®nÈŠ]ÑŽxeUf ò $ð*K-[MÔžD°Ô-.ž4Ý`™\ªºîBpx ¼ƒÜr+‡OëÖšL0[6ií“K´ŒIrñ¬ØÌÒ‰ ±W»0BõÞÝ*ÂøGZi¤›MH$Mb4±˜ª^L³Fæ&kT«FNçqÎ( —Äp½Ö„tãi§ê·Ûý® Áb’@T(!ÇîOÌ0qלh.¦³Ù"ê…ïнš‰—7
+11óó€¤ Œðs\<~ ½ºŒ[ß4q[K©›ù‚êÝH¹³{b›åLÊ2"l8ÚCº*¿<—žñ¥Xk©¥5Ñ´‚+¨Röé!†x&i"Up'\¹o*@0T ü’@=¹û?ù(zÏý‚¬?ômÝtÏÙÿ ÉCÖìaÿ £nè ¢Š( ¢Š( ®Á¿ò¹ÿ °®¥ÿ ¥³WAXw:n¥cs¨hmhæíÄ—Vwe•e"Æ ePLgj¨#cƒ±p–b¹Esÿ lñ‡ý ´?ü Íÿ È´}³Æ ôÐÿ ðs7ÿ "ÐAErz¶½âF¾Õ.4
+ ²·’âEX”±TRÄ ÛœQW>Ùãúhø9›ÿ ‘h ¢¹ÿ ¶xÃþ€Z þfÿ äZ>Ùãúhø9›ÿ ‘h ¢¹ÿ ¶xÃþ€Z þfÿ äZ>Ùãúhø9›ÿ ‘h ¼ÿ ’‡£Ø*ÿ ÿ FÚWAYzV•5¥ÅÅýýÌwZ•Ê$rËF(ÄhX¢"b .ä’ÌIsÎ6ªêPEPEPEP\ÿ Žÿ äžx—þÁW_ú)« ®ÇòOëP°QE QE QE QEÏø7þ@w?öÔ¿ô¶jè+Ÿðoü€îì+©élÕÐP?â ùxOþ²éÕtOTÓaÕ¬Òf‘t‘$Œ€ÑÈŽ d•eVÁ `‚2+/Îñ…¿î¾Ã¡ßmÿ —¶Mi¿þÙyRíÇO¾ÙÆxÎ AEsÿ lñ‡ý ´?ü Íÿ È´}³Æ ôÐÿ ðs7ÿ "ÐAEsÿ lñ‡ý ´?ü Íÿ ȵOI×¼U¬èÖ:¥¾£,¶ñÜF²k†
+ê‹b3ƒêh¬¢¹ÿ ¶xÃþ€Z þfÿ äZ>Ùãúhø9›ÿ ‘h ®~ÏþJ ³ÿ `«ýwGÚ|a'Éý•¡ÛîãÎþÓšo/ý¯/ÈMøë·rç¦áÖ´43û6)ÞY¼û˹~Ñu8]‚I6ª|«“µB¢('
+2Y²ÄBŠ( Š( Š( Š( ÇòOöÒ+@#‰ä³^Ú_5WË@Áãs„
+äù#,¡‰ îxRÃRÓt™ Õ"´Žw½¹¸Qk;J»e™åÁ,ˆr •éü ÷Àþ¿ÿ Ðסÿ àÆ þ*øNü ÿ C^‡ÿ ƒøª è+Ÿðoü€îì+©élÔÂmáùÿ w¦jPj÷GîÚé’-Ì„öÈBB.p7¹TŒ°Í\ðö›6•¢Cotѵۼ—&"JyÒ»K L€vov žqŒäó@”QE QE sþ
+ÿ Ïý…u/ý-šº
+çüÿ ;Ÿû
+ê_ú[5t QE QE W?àOù'žÿ °U¯þŠZè+Ÿð'ü“Ï
+Ø*×ÿ E- tQE QE QE QE Q\^ƒ Ûk6ww··ºËNÚú~ïX»‰B¥Ô¨ *H ª (´¢¹ÿ øCt¿ùú×?ð{{ÿ Ǩÿ „7Kÿ Ÿsÿ ·¿üz€9ÿ 6·— õIln/¢šÛl¬–ŽWÍŒ’,€}èö;1 >PO ×Aàk[Ë?h±j7Óß5¢Kp÷îZa#ì¬O?)b @ v¨çð6‹uo-½ÄºÌÐJ…$ŽMnõ•ÔŒA—Æ*OøCt¿ùú×?ð{{ÿ Ǩ ¢¹ÿ øCt¿ùú×?ð{{ÿ Ǩÿ „7Kÿ Ÿsÿ ·¿üz€:
++Ÿÿ „7Kÿ Ÿsÿ ·¿üz±üYá»M3Áºåýö¹ Õ®Ÿq4/ý¹xvºÆÅN ¸8 u âŠ( Š( Š( Š( ¹ÿ ÿ É<ñ/ý‚®¿ôSWA\ÿ Žÿ äžx—þÁW_ú)¨ ¢Š( ¢Š( ¢Š( ®~ÏþJ ³ÿ `«ýw]söòPõŸûXèÛº è(¢Š (¢Š (¢Š (¢Š çüÿ ;Ÿû
+ê_ú[5tÏø7þ@w?öÔ¿ô¶jè( ¢¹¿Än¯<9d×pÁu©²Mö[™ gQkpà•±¹ã=…Iÿ n—ÿ ?Zçþoøõ tW?ÿ n—ÿ ?Zçþoøõ ð†éóõ®àö÷ÿ Pã›[ËÏkQi×Ð_-£ËnöVc"
+êªG?1P¤H$w®àµå¿Âý.[ë‹éf¹Ý*¥Û–ò£dk?v=ˆ¬O˜‘ÁÐÂ¥ÿ ÏÖ¹ÿ ƒÛßþ=QÁàmÖÞ+{yu˜`‰G zÝêª( . ŒPIEsÿ ð†éóõ®àö÷ÿ Qÿ n—ÿ ?Zçþoøõ tW?ÿ n—ÿ ?Zçþoøõ ð†éóõ®àö÷ÿ PAEaø.y®¼ á닉dšytËg’I³;”’Iä’yÍnPEP\ÿ ƒäsÿ a]Kÿ Kf®‚¹ÿ ÿ Èçþº—þ–Í@Wöv>GÛ.à·óåX!ó¤ æHßu=XààMG>¦ÚÜKoq¨ZCîÃ÷¨æ·ã FÑç¿þб—Ê»[ ´D[†`» ¹Ù·;Ÿ‚UC b®
+MK}BîãRÓb³²¸ò$¸jV6AY ÀÃ6ݹ?Âzœ?Mðn½…µÀÓTAe¤[ÈñÜ»|ÖWFB@1Œ‡Œç¶c‘óUØêúy¾Ôe¹´Ó ]v+Ëå»(T[yö†’±)ÿ y*Ù`áõý5ì-/-5-6h/. yZíV9˜¾Ò¨Ã!Ÿð£©\qÉ,µm7RyÃP´ºxÒ7u‚erªë¹ Áà2òqÈ®L[ßë Òí´ 6Æ[ilÚ¸¾!Kià Ž#bñ°†=’ ¾²n `“@Ð5ë ^Âòú 5R7ÔÄËÛ¹ u:\!\Ä»ˆe(AÇ`„ v•ÏøïþIç‰ìuÿ ¢šº
+çüwÿ $óÄ¿ö
+ºÿ ÑM@ Q@Q@Q@Q@sþ;ÿ ’yâ_û]覮‚¹ÿ ÿ É<ñ/ý‚®¿ôSPAEPE—kCFJ¶wÓÞÜ}ž-La‹yo!$Èê »úP¥Ïÿ ÂCªÐ™®ßë/þH£þ Sþ„Ísþÿ YòE tæú?Ž,ï~3júizª]HYä·Èk‡21Ý‘ cÚØçpé‘ž£þ Sþ„Ísþÿ YòErv]õÄÝ_ÆÂ~ /e¸ŒÜXà0 9ÇŸÓlpã“É|öÀ¦Q\ÿ ü$:§ý šçýþ²ÿ äŠ?á!Õ?èL×?ïõ—ÿ $PAEsÿ ðêŸô&kŸ÷úËÿ ’(ÿ „‡Tÿ ¡3\ÿ ¿Ö_ü‘@ Ïÿ ÂCªÐ™®ßë/þHM'R‡YѬuKu‘`½·Žâ5 Á]C pHΩ ”QE sþ
+ÿ Ïý…u/ý-šº
+çüÿ ;Ÿû
+ê_ú[5tÏø‡þCžÿ °¬ŸúEu[“™–ÞV·Ž9'Li#”Vlp HïƒCX~!ÿ ç„ÿ ì+'þ‘]Väæe·•ãŽIÂHå› À{àãÐÐ7£xÞÏVð2x™gƒ÷A¤±Èi„„
+±¨ÈÜϹ6 ‰ànsAñ :®¢ÝÞ›KÍ^ßíÖjλCár±
+Al3ÜryýÁº–e£‰…£=•”BâÒ;–ò.nÓË·rL}
+ÌJ–V†
+¹òù§ µ±¦h1ÈlMÆieïe7ÚIæ&vÆ<å“
+1 ýÏÌÈ “Ã@×?µìQ®£‚ÖøËs¶IüÌù4.ÊJ©eÈ^vŒn õª÷¾1Ñíÿ ±…¶¡csý±wökG[´òßÞÁ†s»@ åÙãvFø+RK]bÂ9í¾¸š„w³;³¼ l²¼
+ÛÈ 3Œ²¨?2ò\¼š …ukY4¹¯Æ-õ¶]¯n.šgû$°3ù“|Üîˆ?uPüÌN ҉´5«;HÆâÆòÒææ Û;ß9[É™#+€€r$SÇ yÀc©¦ÜégTƒP´—OÎnÒeh‚®w àã'<`מñ%êÏi •mkqi«[<Ð^I3§Ûe†b@Û
+…ÆáœçŒ`îxkI×4M6q%žšnçq$Ê5+™¼ÉD[L†YUŸ R$ ƒ±A;œü´±e¯é·BÊ&Ô´Óyt€¤]¬›ÛËYFx.º¶p>VVÀµ+Ìì< â«}:+ymômöÖZM¼Eoå"F²¸ór߸C«0ãvÒ\äze sþÿ ’yá¯ûZÿ 襮‚¹ÿ É<ð×ý‚ôR×A@Q@pþñg†ôÍ>òÎÿ ÄU¥Ôz®£¾ïc×7“•'# ƒø×qE sÿ ðø?þ†½ÿ 0ÿ ñTÂwàÿ úô?üÃÿ ÅWAE sÿ ðø?þ†½ÿ 0ÿ ñTÂwàÿ úô?üÃÿ ÅWAE sÿ ðø?þ†½ÿ 0ÿ ñTÂwàÿ úô?üÃÿ ÅWAE sÿ ðø?þ†½ÿ 0ÿ ñU‡ãOxVëÀ¾!··ñ.4òé—) qßÄÌìb` ²IÙãúhø9›ÿ ‘h ðoü€îì+©élÕÐV?†4ûÍ3E0_ˆêK»«—X$2"ù³É(PÅTœ8 +b€9ßÙ隇…¯/îà´µU}óO 6w e$øÕøNü ÿ C^‡ÿ ƒøªè( þ¿ÿ Ðסÿ àÆ þ*øNü ÿ C^‡ÿ ƒøªè( þ¿ÿ Ðסÿ àÆ þ*øNü ÿ C^‡ÿ ƒøªè( þ¿ÿ Ðסÿ àÆ þ*øNü ÿ C^‡ÿ ƒøªè( þ¿ÿ Ðסÿ àÆ þ*øNü ÿ C^‡ÿ ƒøªè( ÀŸòO<5ÿ `«_ýµÐQE QE QE QE QE QE QE QE QE QE QE ÏøïþIç‰ìuÿ ¢šº
+çüwÿ $óÄ¿ö
+ºÿ ÑM@ Q@sþ!ÿ ç„ÿ ì+'þ‘]WAXúö“y©¶™=…ì—Vfå{c:6b’"¥C¡é)9Ïj جõдuûFÝ*Ä}§ÍóñnŸ½óvù›¸ù·í]Ùë´g8Ÿö?ÐwCÿ Á4ßü•GØüaÿ AÝÿ ÓòU h&…£Çyky •b—V‘-¦[t `UÁ#ŽM ØZ?ö?öGöUögüù}<Ÿ½»îcoÞç§^k?ì~0ÿ î‡ÿ ‚i¿ù*³á¸ñ„¾!½Òµô1ökH.|ß쉾o5æ]¸ûOòsœó»¶9 é/t7RxÞÿ O´ºxÒDFžrªëµÀÈà2ðGqÁªiá?
+ÇfÖiáý)m_;¡Q„l”'+ŒrcŒŸ÷ÐU±øÃþƒº þ ¦ÿ äª>Çãúèø&›ÿ ’¨âxkAÑÓDÓUÑâuaj€«D»b#Ž
+)Ÿá V„pC ÌñE<ϾVU »m –õ;UFO`jÃû Œ?è;¡ÿ àšoþJ£ì~0ÿ î‡ÿ ‚i¿ù*€:
+çü ÿ $óÃ_ö
+µÿ ÑKGØüaÿ AÝÿ ÓòUhhZgö'‡´Í'Îó¾Ãi·›·nýˆv2qœg4¡EPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEP\ÿ Žÿ äžx—þÁW_ú)« ®ÇòO¬kSþ Sþ„Ísþÿ YòEsþ8]SÅÞ Õ41á r9.¢ýÓ›‹ ŠC¦ã矗r®p3Œãš ë<9®Câ_Ùë6ö·vÐ]¡x㻌$›r@$FÏ ƒÞµ+“Òu íF±Òíü â‚ÊÞ;xÚIìKE
+ ÅÀÀôsþ Sþ„Ísþÿ YòE \ñ ¹†¼?y¬ÜZÝÜÁhäŽÒ0òmÈ€H î'< Ojçþëë¿t‡‚Öî³·ŽÈµÄaDj¬é‚w&ìŒú©«¶¡}¬è×Ú]ǃü@°^ÛÉo#G=ˆ`®¥I¸#8>†£øigo¢ø.ÃÃêgKí>!öÈ.«Ç+–gÆ@Ý ó W\«m8fÁ4ØQE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QEÏøÓçðÓÛ70Þ]ÚYN¿ß†kˆâ‘sÛ(ì29È à×A\ÿ Œ¿ämÿ a]7ÿ Kaª~7ñE÷†íã—O´Žéã·žöxˆË! ¿e
+>uòÌ21 ™;@:Ê+‹}^:ûéÉ6šëéÊæÑÉ
+l~Õ ÞòU¾Vé¸tÙYvÞ.ñ—ƒt›ûÉìo.¥Ñ%Öæ²´{â†8KC€ø1”þô|£ êÎx ôŠ+Ÿ·Öo.’ž#‡P±žW=#.âwv=•UY‰< <
+غ°³¾ò>ÙiÇ‘*Ï.Eû®¹èÃ'r*Ià†êÞ[{ˆ£š P¤‘È¡•ÔŒAà‚8Åaÿ dø‚Ï÷Zgˆ kQ÷WS²k™t
+$Ic, ˆrrK¶x ÐŽ²Ã(Ò¬DÄDâÝ3 hÁÑã…VU` €G"ì- þV?ñ÷öïø÷Oøøÿ žÝ?Öµ×Þ³þÇãúèø&›ÿ ’¨û Œ?è;¡ÿ àšoþJ
+°Yÿ hÿ hý’·y^GÚ|±æyyݳw]¹ç 3TçðÖƒuo-½Æ‰¦Í·êHäµFW˜Œ#ÈãwZÚãÆx†ËIþ×ÐÏÚm'¹ó²&ù|§…vãí<çÎÎsÆÞùãCì~0ÿ î‡ÿ ‚i¿ù*€5-´6ÎâK‹]>Ò äy äŠVfr¥É d–(„žûFz
+Ë×ÿ yâ
+ÄŸ4‰¨K; ä¬bÒt.G÷CI“Ó.£©}Æ ô Ðÿ ðM7ÿ %UÍ7Hk[†¾¾¼’ÿ Pt)ç:*,HH&8}Ä,ä³ (fm«€
+J(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€9ûÏù(z7ý‚¯ÿ ôm¥tÏÞÉCÑ¿ìÿ £m+ Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Š( Šâô ÛY³»½½½ÖZvÔïÓ÷zÅÜJ.¥ER@ P0 éZŸð†éóõ®àö÷ÿ PAEsÿ ð†éóõ®àö÷ÿ Qÿ n—ÿ ?Zçþoøõ yÿ ˆ4bOÚ'@òoõÅÓ'´7RyS8†?/ïÆ06ˆÙ£·Þ½ËŒýå¯`®løEk„¸iu“:#"Hu»ÝʬA`› U$wÚ=*OøCt¿ùú×?ð{{ÿ Ǩ ¢¹ÿ øCt¿ùú×?ð{{ÿ Ç«>ïG‡Dñ†¤²¼ÕÒ5 !™'ÕngGO²\>
+I#/ÞE=;PaEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEP?àßùÜÿ ØWRÿ ÒÙ«bêþÎÇÈûeÜþ|«>t<Éî¢ç« ɬÿ Èçþº—þ–ÍF¿£^_ê6·–ic6-.,f†ø —1ˆ³• ù˜ò€òÎÐÁθäR}[Mµ¸–ÞãP´†xÍÔ‘É2«$ àÈA9ºV^·ã FÑç¿þб—Ê»[ ´D[†`» ¹Ù·;Ÿ‚UC b©ÏáÝI|I.¡nm$€^R1$¬ŒÓ}ì¢ ?™’GÝØ~õcé¾
+× ³°¶¸jˆ,´‹y ;—ošÊèÈH1ñœöà r>j 쿦¥¾¡wq©i±YÙ\y\ µ+ ¬„àFá›nÜŸá=NvÞ,ðÝæß²øƒJŸt© ò¯clÈùØœ ¼Û[©ÁÇJâüOc«éæûQ–æÓLyuد,o–ì¡Qmä?ÚHJÄ4`¤ýä¨;e¬Zèw:žgw¢ÛZAfÖöP¬3\¾Ô$^[ìc,Rœ!ÚBm|9;@`|K ‹{‹ƒé¾EºDóÉö¤ÛÈŒ±Î `ARzçŒÕ?ÿ ÈsÂö“ÿ H®«›k3x~4é¶Ú”Zìú«%µìñÊÊd
+#include
+#include
+#include
+
+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
+
+#ifdef STDC_HEADERS
+#include
+#endif
+
+#include
+
+#ifdef HAVE_UTIME_H
+#include
+#endif
+
+#ifndef HAVE_UTIME_NULL
+
+#include
+
+#ifndef HAVE_STRUCT_UTIMBUF
+
+struct utimbuf
+@{
+ long actime;
+ long modtime;
+@};
+
+#endif
+
+static int
+utime_now (file)
+ char *file;
+@{
+ struct utimbuf now;
+
+ now.actime = now.modtime = time (NULL);
+ return utime (file, &now);
+@}
+
+#define utime(f, p) utime_now (f)
+
+#endif /* HAVE_UTIME_NULL */
+
+int
+main (argc, argv)
+ int argc;
+ char **argv;
+@{
+ if (argc != 2)
+ @{
+ fprintf (stderr, "Usage: poke file\n");
+ exit (1);
+ @}
+
+ if (utime (argv[1], NULL) < 0)
+ @{
+ perror ("utime");
+ exit (1);
+ @}
+
+ exit (0);
+@}
+@end example
+
+Here is the associated @file{Makefile}. We've added support for the
+preprocessor flags we use. We've also added @samp{install} and
+@samp{clean} targets.
+
+@example
+# Set this to your installation directory.
+bindir = /usr/local/bin
+
+# Uncomment this if you have the standard ANSI/ISO C header files.
+# STDC_HDRS = -DSTDC_HEADERS
+
+# Uncomment this if you have utime.h.
+# UTIME_H = -DHAVE_UTIME_H
+
+# Uncomment this if utime (FILE, NULL) works on your system.
+# UTIME_NULL = -DHAVE_UTIME_NULL
+
+# Uncomment this if struct utimbuf is defined in utime.h.
+# UTIMBUF = -DHAVE_STRUCT_UTIMBUF
+
+CC = gcc
+CFLAGS = -g -O2
+
+ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS)
+
+all: poke
+
+poke: poke.o
+ $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o
+
+.c.o:
+ $(CC) -c $(ALL_CFLAGS) poke.c
+
+install: poke
+ cp poke $(bindir)/poke
+
+clean:
+ rm poke poke.o
+@end example
+
+Some problems with this approach should be clear.
+
+Users who want to compile poke will have to know how @samp{utime} works
+on their systems, so that they can uncomment the @file{Makefile}
+correctly.
+
+The installation is done using @samp{cp}, but many systems have an
+@samp{install} program which may be used, and which supports optional
+features such as stripping debugging information out of the installed
+binary.
+
+The use of @file{Makefile} variables like @samp{CC}, @samp{CFLAGS} and
+@samp{LDFLAGS} follows the requirements of the GNU standards. This is
+convenient for all packages, since it reduces surprises for users.
+However, it is easy to get the details wrong, and wind up with a
+slightly nonstandard distribution.
+
+@node Getting Started Example 3
+@subsection Third Try
+
+For our third try at this program, we will write a @file{configure.in}
+script to discover the configuration features on the host system, rather
+than requiring the user to edit the @file{Makefile}. We will also write
+a @file{Makefile.am} rather than a @file{Makefile}.
+
+The only change to @file{poke.c} is to add a line at the start of the
+file:
+@smallexample
+#include "config.h"
+@end smallexample
+
+The new @file{configure.in} file is as follows.
+
+@example
+AC_INIT(poke.c)
+AM_INIT_AUTOMAKE(poke, 1.0)
+AM_CONFIG_HEADER(config.h:config.in)
+AC_PROG_CC
+AC_HEADER_STDC
+AC_CHECK_HEADERS(utime.h)
+AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF))
+AC_FUNC_UTIME_NULL
+AC_OUTPUT(Makefile)
+@end example
+
+The first four macros in this file, and the last one, were described
+above; see @ref{Write configure.in}. If we omit these macros, then when
+we run @samp{automake} we will get a reminder that we need them.
+
+The other macros are standard autoconf macros.
+
+@table @samp
+@item AC_HEADER_STDC
+Check for standard C headers.
+@item AC_CHECK_HEADERS
+Check whether a particular header file exists.
+@item AC_EGREP_HEADER
+Check for a particular string in a particular header file, in this case
+checking for @samp{utimbuf} in @file{utime.h}.
+@item AC_FUNC_UTIME_NULL
+Check whether @samp{utime} accepts a NULL second argument to set the
+file change time to the current time.
+@end table
+
+See the autoconf manual for a more complete description.
+
+The new @file{Makefile.am} file is as follows. Note how simple this is
+compared to our earlier @file{Makefile}.
+
+@example
+bin_PROGRAMS = poke
+
+poke_SOURCES = poke.c
+@end example
+
+This means that we should build a single program name @samp{poke}. It
+should be installed in the binary directory, which we called
+@samp{bindir} earlier. The program @samp{poke} is built from the source
+file @file{poke.c}.
+
+We must also write a @file{acconfig.h} file. Besides @samp{PACKAGE} and
+@samp{VERSION}, which must be mentioned for all packages which use
+automake, we must include @samp{HAVE_STRUCT_UTIMBUF}, since we mentioned
+it in an @samp{AC_DEFINE}.
+
+@example
+/* Name of package. */
+#undef PACKAGE
+
+/* Version of package. */
+#undef VERSION
+
+/* Whether utime.h defines struct utimbuf. */
+#undef HAVE_STRUCT_UTIMBUF
+@end example
+
+@node Generate Files in Example
+@subsection Generate Files
+
+We must now generate the other files, using the following commands.
+
+@smallexample
+aclocal
+autoconf
+autoheader
+automake
+@end smallexample
+
+When we run @samp{autoheader}, it will remind us of any macros we forgot
+to add to @file{acconfig.h}.
+
+When we run @samp{automake}, it will want to add some files to our
+distribution. It will add them automatically if we use the
+@samp{--add-missing} option.
+
+By default, @samp{automake} will run in GNU mode, which means that it
+will want us to create certain additional files; as of this writing, it
+will want @file{NEWS}, @file{README}, @file{AUTHORS}, and
+@file{ChangeLog}, all of which are files which should appear in a
+standard GNU distribution. We can either add those files, or run
+@samp{automake} with the @samp{--foreign} option.
+
+Running these tools will generate the following files, all of which are
+described in the next chapter.
+
+@itemize @bullet
+@item
+@file{aclocal.m4}
+@item
+@file{configure}
+@item
+@file{config.in}
+@item
+@file{Makefile.in}
+@item
+@file{stamp-h.in}
+@end itemize
+
+@node Files
+@chapter Files
+
+As was seen in the previous chapter, the GNU configure and build system
+uses a number of different files. The developer must write a few files.
+The others are generated by various tools.
+
+The system is rather flexible, and can be used in many different ways.
+In describing the files that it uses, I will describe the common case,
+and mention some other cases that may arise.
+
+@menu
+* Developer Files:: Developer Files.
+* Build Files:: Build Files.
+* Support Files:: Support Files.
+@end menu
+
+@node Developer Files
+@section Developer Files
+
+This section describes the files written or generated by the developer
+of a package.
+
+@menu
+* Developer Files Picture:: Developer Files Picture.
+* Written Developer Files:: Written Developer Files.
+* Generated Developer Files:: Generated Developer Files.
+@end menu
+
+@node Developer Files Picture
+@subsection Developer Files Picture
+
+Here is a picture of the files which are written by the developer, the
+generated files which would be included with a complete source
+distribution, and the tools which create those files.
+@ifinfo
+The file names are plain text and the tool names are enclosed by
+@samp{*} characters
+@end ifinfo
+@ifnotinfo
+The file names are in rectangles with square corners and the tool names
+are in rectangles with rounded corners
+@end ifnotinfo
+(e.g., @samp{autoheader} is the name of a tool, not the name of a file).
+
+@image{configdev}
+
+@node Written Developer Files
+@subsection Written Developer Files
+
+The following files would be written by the developer.
+
+@table @file
+@item configure.in
+@cindex @file{configure.in}
+This is the configuration script. This script contains invocations of
+autoconf macros. It may also contain ordinary shell script code. This
+file will contain feature tests for portability issues. The last thing
+in the file will normally be an @samp{AC_OUTPUT} macro listing which
+files to create when the builder runs the configure script. This file
+is always required when using the GNU configure system. @xref{Write
+configure.in}.
+
+@item Makefile.am
+@cindex @file{Makefile.am}
+This is the automake input file. It describes how the code should be
+built. It consists of definitions of automake variables. It may also
+contain ordinary Makefile targets. This file is only needed when using
+automake (newer tools normally use automake, but there are still older
+tools which have not been converted, in which the developer writes
+@file{Makefile.in} directly). @xref{Write Makefile.am}.
+
+@item acconfig.h
+@cindex @file{acconfig.h}
+When the configure script creates a portability header file, by using
+@samp{AM_CONFIG_HEADER} (or, if not using automake,
+@samp{AC_CONFIG_HEADER}), this file is used to describe macros which are
+not recognized by the @samp{autoheader} command. This is normally a
+fairly uninteresting file, consisting of a collection of @samp{#undef}
+lines with comments. Normally any call to @samp{AC_DEFINE} in
+@file{configure.in} will require a line in this file. @xref{Write
+acconfig.h}.
+
+@item acinclude.m4
+@cindex @file{acinclude.m4}
+This file is not always required. It defines local autoconf macros.
+These macros may then be used in @file{configure.in}. If you don't need
+any local autoconf macros, then you don't need this file at all. In
+fact, in general, you never need local autoconf macros, since you can
+put everything in @file{configure.in}, but sometimes a local macro is
+convenient.
+
+Newer tools may omit @file{acinclude.m4}, and instead use a
+subdirectory, typically named @file{m4}, and define
+@samp{ACLOCAL_AMFLAGS = -I m4} in @file{Makefile.am} to force
+@samp{aclocal} to look there for macro definitions. The macro
+definitions are then placed in separate files in that directory.
+
+The @file{acinclude.m4} file is only used when using automake; in older
+tools, the developer writes @file{aclocal.m4} directly, if it is needed.
+@end table
+
+@node Generated Developer Files
+@subsection Generated Developer Files
+
+The following files would be generated by the developer.
+
+When using automake, these files are normally not generated manually
+after the first time. Instead, the generated @file{Makefile} contains
+rules to automatically rebuild the files as required. When
+@samp{AM_MAINTAINER_MODE} is used in @file{configure.in} (the normal
+case in Cygnus code), the automatic rebuilding rules will only be
+defined if you configure using the @samp{--enable-maintainer-mode}
+option.
+
+When using automatic rebuilding, it is important to ensure that all the
+various tools have been built and installed on your @samp{PATH}. Using
+automatic rebuilding is highly recommended, so much so that I'm not
+going to explain what you have to do if you don't use it.
+
+@table @file
+@item configure
+@cindex @file{configure}
+This is the configure script which will be run when building the
+package. This is generated by @samp{autoconf} from @file{configure.in}
+and @file{aclocal.m4}. This is a shell script.
+
+@item Makefile.in
+@cindex @file{Makefile.in}
+This is the file which the configure script will turn into the
+@file{Makefile} at build time. This file is generated by
+@samp{automake} from @file{Makefile.am}. If you aren't using automake,
+you must write this file yourself. This file is pretty much a normal
+@file{Makefile}, with some configure substitutions for certain
+variables.
+
+@item aclocal.m4
+@cindex @file{aclocal.m4}
+This file is created by the @samp{aclocal} program, based on the
+contents of @file{configure.in} and @file{acinclude.m4} (or, as noted in
+the description of @file{acinclude.m4} above, on the contents of an
+@file{m4} subdirectory). This file contains definitions of autoconf
+macros which @samp{autoconf} will use when generating the file
+@file{configure}. These autoconf macros may be defined by you in
+@file{acinclude.m4} or they may be defined by other packages such as
+automake, libtool or gettext. If you aren't using automake, you will
+normally write this file yourself; in that case, if @file{configure.in}
+uses only standard autoconf macros, this file will not be needed at all.
+
+@item config.in
+@cindex @file{config.in}
+@cindex @file{config.h.in}
+This file is created by @samp{autoheader} based on @file{acconfig.h} and
+@file{configure.in}. At build time, the configure script will define
+some of the macros in it to create @file{config.h}, which may then be
+included by your program. This permits your C code to use preprocessor
+conditionals to change its behaviour based on the characteristics of the
+host system. This file may also be called @file{config.h.in}.
+
+@item stamp.h-in
+@cindex @file{stamp-h.in}
+This rather uninteresting file, which I omitted from the picture, is
+generated by @samp{automake}. It always contains the string
+@samp{timestamp}. It is used as a timestamp file indicating whether
+@file{config.in} is up to date. Using a timestamp file means that
+@file{config.in} can be marked as up to date without actually changing
+its modification time. This is useful since @file{config.in} depends
+upon @file{configure.in}, but it is easy to change @file{configure.in}
+in a way which does not affect @file{config.in}.
+@end table
+
+@node Build Files
+@section Build Files
+
+This section describes the files which are created at configure and
+build time. These are the files which somebody who builds the package
+will see.
+
+Of course, the developer will also build the package. The distinction
+between developer files and build files is not that the developer does
+not see the build files, but that somebody who only builds the package
+does not have to worry about the developer files.
+
+@menu
+* Build Files Picture:: Build Files Picture.
+* Build Files Description:: Build Files Description.
+@end menu
+
+@node Build Files Picture
+@subsection Build Files Picture
+
+Here is a picture of the files which will be created at build time.
+@file{config.status} is both a created file and a shell script which is
+run to create other files, and the picture attempts to show that.
+
+@image{configbuild}
+
+@node Build Files Description
+@subsection Build Files Description
+
+This is a description of the files which are created at build time.
+
+@table @file
+@item config.status
+@cindex @file{config.status}
+The first step in building a package is to run the @file{configure}
+script. The @file{configure} script will create the file
+@file{config.status}, which is itself a shell script. When you first
+run @file{configure}, it will automatically run @file{config.status}.
+An @file{Makefile} derived from an automake generated @file{Makefile.in}
+will contain rules to automatically run @file{config.status} again when
+necessary to recreate certain files if their inputs change.
+
+@item Makefile
+@cindex @file{Makefile}
+This is the file which make will read to build the program. The
+@file{config.status} script will transform @file{Makefile.in} into
+@file{Makefile}.
+
+@item config.h
+@cindex @file{config.h}
+This file defines C preprocessor macros which C code can use to adjust
+its behaviour on different systems. The @file{config.status} script
+will transform @file{config.in} into @file{config.h}.
+
+@item config.cache
+@cindex @file{config.cache}
+This file did not fit neatly into the picture, and I omitted it. It is
+used by the @file{configure} script to cache results between runs. This
+can be an important speedup. If you modify @file{configure.in} in such
+a way that the results of old tests should change (perhaps you have
+added a new library to @samp{LDFLAGS}), then you will have to remove
+@file{config.cache} to force the tests to be rerun.
+
+The autoconf manual explains how to set up a site specific cache file.
+This can speed up running @file{configure} scripts on your system.
+
+@item stamp.h
+@cindex @file{stamp-h}
+This file, which I omitted from the picture, is similar to
+@file{stamp-h.in}. It is used as a timestamp file indicating whether
+@file{config.h} is up to date. This is useful since @file{config.h}
+depends upon @file{config.status}, but it is easy for
+@file{config.status} to change in a way which does not affect
+@file{config.h}.
+@end table
+
+@node Support Files
+@section Support Files
+
+The GNU configure and build system requires several support files to be
+included with your distribution. You do not normally need to concern
+yourself with these. If you are using the Cygnus tree, most are already
+present. Otherwise, they will be installed with your source by
+@samp{automake} (with the @samp{--add-missing} option) and
+@samp{libtoolize}.
+
+You don't have to put the support files in the top level directory. You
+can put them in a subdirectory, and use the @samp{AC_CONFIG_AUX_DIR}
+macro in @file{configure.in} to tell @samp{automake} and the
+@file{configure} script where they are.
+
+In this section, I describe the support files, so that you can know what
+they are and why they are there.
+
+@table @file
+@item ABOUT-NLS
+Added by automake if you are using gettext. This is a documentation
+file about the gettext project.
+@item ansi2knr.c
+Used by an automake generated @file{Makefile} if you put @samp{ansi2knr}
+in @samp{AUTOMAKE_OPTIONS} in @file{Makefile.am}. This permits
+compiling ANSI C code with a K&R C compiler.
+@item ansi2knr.1
+The man page which goes with @file{ansi2knr.c}.
+@item config.guess
+A shell script which determines the configuration name for the system on
+which it is run.
+@item config.sub
+A shell script which canonicalizes a configuration name entered by a
+user.
+@item elisp-comp
+Used to compile Emacs LISP files.
+@item install-sh
+A shell script which installs a program. This is used if the configure
+script can not find an install binary.
+@item ltconfig
+Used by libtool. This is a shell script which configures libtool for
+the particular system on which it is used.
+@item ltmain.sh
+Used by libtool. This is the actual libtool script which is used, after
+it is configured by @file{ltconfig} to build a library.
+@item mdate-sh
+A shell script used by an automake generated @file{Makefile} to pretty
+print the modification time of a file. This is used to maintain version
+numbers for texinfo files.
+@item missing
+A shell script used if some tool is missing entirely. This is used by
+an automake generated @file{Makefile} to avoid certain sorts of
+timestamp problems.
+@item mkinstalldirs
+A shell script which creates a directory, including all parent
+directories. This is used by an automake generated @file{Makefile}
+during installation.
+@item texinfo.tex
+Required if you have any texinfo files. This is used when converting
+Texinfo files into DVI using @samp{texi2dvi} and @TeX{}.
+@item ylwrap
+A shell script used by an automake generated @file{Makefile} to run
+programs like @samp{bison}, @samp{yacc}, @samp{flex}, and @samp{lex}.
+These programs default to producing output files with a fixed name, and
+the @file{ylwrap} script runs them in a subdirectory to avoid file name
+conflicts when using a parallel make program.
+@end table
+
+@node Configuration Names
+@chapter Configuration Names
+@cindex configuration names
+@cindex configuration triplets
+@cindex triplets
+@cindex host names
+@cindex host triplets
+@cindex canonical system names
+@cindex system names
+@cindex system types
+
+The GNU configure system names all systems using a @dfn{configuration
+name}. All such names used to be triplets (they may now contain four
+parts in certain cases), and the term @dfn{configuration triplet} is
+still seen.
+
+@menu
+* Configuration Name Definition:: Configuration Name Definition.
+* Using Configuration Names:: Using Configuration Names.
+@end menu
+
+@node Configuration Name Definition
+@section Configuration Name Definition
+
+This is a string of the form
+@var{cpu}-@var{manufacturer}-@var{operating_system}. In some cases,
+this is extended to a four part form:
+@var{cpu}-@var{manufacturer}-@var{kernel}-@var{operating_system}.
+
+When using a configuration name in a configure option, it is normally
+not necessary to specify an entire name. In particular, the
+@var{manufacturer} field is often omitted, leading to strings such as
+@samp{i386-linux} or @samp{sparc-sunos}. The shell script
+@file{config.sub} will translate these shortened strings into the
+canonical form. autoconf will arrange for @file{config.sub} to be run
+automatically when it is needed.
+
+The fields of a configuration name are as follows:
+
+@table @var
+@item cpu
+The type of processor. This is typically something like @samp{i386} or
+@samp{sparc}. More specific variants are used as well, such as
+@samp{mipsel} to indicate a little endian MIPS processor.
+@item manufacturer
+A somewhat freeform field which indicates the manufacturer of the
+system. This is often simply @samp{unknown}. Other common strings are
+@samp{pc} for an IBM PC compatible system, or the name of a workstation
+vendor, such as @samp{sun}.
+@item operating_system
+The name of the operating system which is run on the system. This will
+be something like @samp{solaris2.5} or @samp{irix6.3}. There is no
+particular restriction on the version number, and strings like
+@samp{aix4.1.4.0} are seen. For an embedded system, which has no
+operating system, this field normally indicates the type of object file
+format, such as @samp{elf} or @samp{coff}.
+@item kernel
+This is used mainly for GNU/Linux. A typical GNU/Linux configuration
+name is @samp{i586-pc-linux-gnulibc1}. In this case the kernel,
+@samp{linux}, is separated from the operating system, @samp{gnulibc1}.
+@end table
+
+The shell script @file{config.guess} will normally print the correct
+configuration name for the system on which it is run. It does by
+running @samp{uname} and by examining other characteristics of the
+system.
+
+Because @file{config.guess} can normally determine the configuration
+name for a machine, it is normally only necessary to specify a
+configuration name when building a cross-compiler or when building using
+a cross-compiler.
+
+@node Using Configuration Names
+@section Using Configuration Names
+
+A configure script will sometimes have to make a decision based on a
+configuration name. You will need to do this if you have to compile
+code differently based on something which can not be tested using a
+standard autoconf feature test.
+
+It is normally better to test for particular features, rather than to
+test for a particular system. This is because as Unix evolves,
+different systems copy features from one another. Even if you need to
+determine whether the feature is supported based on a configuration
+name, you should define a macro which describes the feature, rather than
+defining a macro which describes the particular system you are on.
+
+Testing for a particular system is normally done using a case statement
+in @file{configure.in}. The case statement might look something like
+the following, assuming that @samp{host} is a shell variable holding a
+canonical configuration name (which will be the case if
+@file{configure.in} uses the @samp{AC_CANONICAL_HOST} or
+@samp{AC_CANONICAL_SYSTEM} macro).
+
+@smallexample
+case "$@{host@}" in
+i[3456]86-*-linux-gnu*) do something ;;
+sparc*-sun-solaris2.[56789]*) do something ;;
+sparc*-sun-solaris*) do something ;;
+mips*-*-elf*) do something ;;
+esac
+@end smallexample
+
+It is particularly important to use @samp{*} after the operating system
+field, in order to match the version number which will be generated by
+@file{config.guess}.
+
+In most cases you must be careful to match a range of processor types.
+For most processor families, a trailing @samp{*} suffices, as in
+@samp{mips*} above. For the i386 family, something along the lines of
+@samp{i[3456]86} suffices at present. For the m68k family, you will
+need something like @samp{m68*}. Of course, if you do not need to match
+on the processor, it is simpler to just replace the entire field by a
+@samp{*}, as in @samp{*-*-irix*}.
+
+@node Cross Compilation Tools
+@chapter Cross Compilation Tools
+@cindex cross tools
+
+The GNU configure and build system can be used to build @dfn{cross
+compilation} tools. A cross compilation tool is a tool which runs on
+one system and produces code which runs on another system.
+
+@menu
+* Cross Compilation Concepts:: Cross Compilation Concepts.
+* Host and Target:: Host and Target.
+* Using the Host Type:: Using the Host Type.
+* Specifying the Target:: Specifying the Target.
+* Using the Target Type:: Using the Target Type.
+* Cross Tools in the Cygnus Tree:: Cross Tools in the Cygnus Tree
+@end menu
+
+@node Cross Compilation Concepts
+@section Cross Compilation Concepts
+
+@cindex cross compiler
+A compiler which produces programs which run on a different system is a
+cross compilation compiler, or simply a @dfn{cross compiler}.
+Similarly, we speak of cross assemblers, cross linkers, etc.
+
+In the normal case, a compiler produces code which runs on the same
+system as the one on which the compiler runs. When it is necessary to
+distinguish this case from the cross compilation case, such a compiler
+is called a @dfn{native compiler}. Similarly, we speak of native
+assemblers, etc.
+
+Although the debugger is not strictly speaking a compilation tool, it is
+nevertheless meaningful to speak of a cross debugger: a debugger which
+is used to debug code which runs on another system. Everything that is
+said below about configuring cross compilation tools applies to the
+debugger as well.
+
+@node Host and Target
+@section Host and Target
+@cindex host system
+@cindex target system
+
+When building cross compilation tools, there are two different systems
+involved: the system on which the tools will run, and the system for
+which the tools generate code.
+
+The system on which the tools will run is called the @dfn{host} system.
+
+The system for which the tools generate code is called the @dfn{target}
+system.
+
+For example, suppose you have a compiler which runs on a GNU/Linux
+system and generates ELF programs for a MIPS embedded system. In this
+case the GNU/Linux system is the host, and the MIPS ELF system is the
+target. Such a compiler could be called a GNU/Linux cross MIPS ELF
+compiler, or, equivalently, a @samp{i386-linux-gnu} cross
+@samp{mips-elf} compiler.
+
+Naturally, most programs are not cross compilation tools. For those
+programs, it does not make sense to speak of a target. It only makes
+sense to speak of a target for tools like @samp{gcc} or the
+@samp{binutils} which actually produce running code. For example, it
+does not make sense to speak of the target of a tool like @samp{bison}
+or @samp{make}.
+
+Most cross compilation tools can also serve as native tools. For a
+native compilation tool, it is still meaningful to speak of a target.
+For a native tool, the target is the same as the host. For example, for
+a GNU/Linux native compiler, the host is GNU/Linux, and the target is
+also GNU/Linux.
+
+@node Using the Host Type
+@section Using the Host Type
+
+In almost all cases the host system is the system on which you run the
+@samp{configure} script, and on which you build the tools (for the case
+when they differ, @pxref{Canadian Cross}).
+
+@cindex @samp{AC_CANONICAL_HOST}
+If your configure script needs to know the configuration name of the
+host system, and the package is not a cross compilation tool and
+therefore does not have a target, put @samp{AC_CANONICAL_HOST} in
+@file{configure.in}. This macro will arrange to define a few shell
+variables when the @samp{configure} script is run.
+
+@table @samp
+@item host
+The canonical configuration name of the host. This will normally be
+determined by running the @file{config.guess} shell script, although the
+user is permitted to override this by using an explicit @samp{--host}
+option.
+@item host_alias
+In the unusual case that the user used an explicit @samp{--host} option,
+this will be the argument to @samp{--host}. In the normal case, this
+will be the same as the @samp{host} variable.
+@item host_cpu
+@itemx host_vendor
+@itemx host_os
+The first three parts of the canonical configuration name.
+@end table
+
+The shell variables may be used by putting shell code in
+@file{configure.in}. For an example, see @ref{Using Configuration
+Names}.
+
+@node Specifying the Target
+@section Specifying the Target
+
+By default, the @samp{configure} script will assume that the target is
+the same as the host. This is the more common case; for example, it
+leads to a native compiler rather than a cross compiler.
+
+@cindex @samp{--target} option
+@cindex target option
+@cindex configure target
+If you want to build a cross compilation tool, you must specify the
+target explicitly by using the @samp{--target} option when you run
+@samp{configure}. The argument to @samp{--target} is the configuration
+name of the system for which you wish to generate code.
+@xref{Configuration Names}.
+
+For example, to build tools which generate code for a MIPS ELF embedded
+system, you would use @samp{--target mips-elf}.
+
+@node Using the Target Type
+@section Using the Target Type
+
+@cindex @samp{AC_CANONICAL_SYSTEM}
+When writing @file{configure.in} for a cross compilation tool, you will
+need to use information about the target. To do this, put
+@samp{AC_CANONICAL_SYSTEM} in @file{configure.in}.
+
+@samp{AC_CANONICAL_SYSTEM} will look for a @samp{--target} option and
+canonicalize it using the @file{config.sub} shell script. It will also
+run @samp{AC_CANONICAL_HOST} (@pxref{Using the Host Type}).
+
+The target type will be recorded in the following shell variables. Note
+that the host versions of these variables will also be defined by
+@samp{AC_CANONICAL_HOST}.
+
+@table @samp
+@item target
+The canonical configuration name of the target.
+@item target_alias
+The argument to the @samp{--target} option. If the user did not specify
+a @samp{--target} option, this will be the same as @samp{host_alias}.
+@item target_cpu
+@itemx target_vendor
+@itemx target_os
+The first three parts of the canonical target configuration name.
+@end table
+
+Note that if @samp{host} and @samp{target} are the same string, you can
+assume a native configuration. If they are different, you can assume a
+cross configuration.
+
+It is arguably possible for @samp{host} and @samp{target} to represent
+the same system, but for the strings to not be identical. For example,
+if @samp{config.guess} returns @samp{sparc-sun-sunos4.1.4}, and somebody
+configures with @samp{--target sparc-sun-sunos4.1}, then the slight
+differences between the two versions of SunOS may be unimportant for
+your tool. However, in the general case it can be quite difficult to
+determine whether the differences between two configuration names are
+significant or not. Therefore, by convention, if the user specifies a
+@samp{--target} option without specifying a @samp{--host} option, it is
+assumed that the user wants to configure a cross compilation tool.
+
+The variables @samp{target} and @samp{target_alias} should be handled
+differently.
+
+In general, whenever the user may actually see a string,
+@samp{target_alias} should be used. This includes anything which may
+appear in the file system, such as a directory name or part of a tool
+name. It also includes any tool output, unless it is clearly labelled
+as the canonical target configuration name. This permits the user to
+use the @samp{--target} option to specify how the tool will appear to
+the outside world.
+
+On the other hand, when checking for characteristics of the target
+system, @samp{target} should be used. This is because a wide variety of
+@samp{--target} options may map into the same canonical configuration
+name. You should not attempt to duplicate the canonicalization done by
+@samp{config.sub} in your own code.
+
+By convention, cross tools are installed with a prefix of the argument
+used with the @samp{--target} option, also known as @samp{target_alias}
+(@pxref{Using the Target Type}). If the user does not use the
+@samp{--target} option, and thus is building a native tool, no prefix is
+used.
+
+For example, if gcc is configured with @samp{--target mips-elf}, then
+the installed binary will be named @samp{mips-elf-gcc}. If gcc is
+configured without a @samp{--target} option, then the installed binary
+will be named @samp{gcc}.
+
+The autoconf macro @samp{AC_ARG_PROGRAM} will handle this for you. If
+you are using automake, no more need be done; the programs will
+automatically be installed with the correct prefixes. Otherwise, see
+the autoconf documentation for @samp{AC_ARG_PROGRAM}.
+
+@node Cross Tools in the Cygnus Tree
+@section Cross Tools in the Cygnus Tree
+
+The Cygnus tree is used for various packages including gdb, the GNU
+binutils, and egcs. It is also, of course, used for Cygnus releases.
+
+In the Cygnus tree, the top level @file{configure} script uses the old
+Cygnus configure system, not autoconf. The top level @file{Makefile.in}
+is written to build packages based on what is in the source tree, and
+supports building a large number of tools in a single
+@samp{configure}/@samp{make} step.
+
+The Cygnus tree may be configured with a @samp{--target} option. The
+@samp{--target} option applies recursively to every subdirectory, and
+permits building an entire set of cross tools at once.
+
+@menu
+* Host and Target Libraries:: Host and Target Libraries.
+* Target Library Configure Scripts:: Target Library Configure Scripts.
+* Make Targets in Cygnus Tree:: Make Targets in Cygnus Tree.
+* Target libiberty:: Target libiberty
+@end menu
+
+@node Host and Target Libraries
+@subsection Host and Target Libraries
+
+The Cygnus tree distinguishes host libraries from target libraries.
+
+Host libraries are built with the compiler used to build the programs
+which run on the host, which is called the host compiler. This includes
+libraries such as @samp{bfd} and @samp{tcl}. These libraries are built
+with the host compiler, and are linked into programs like the binutils
+or gcc which run on the host.
+
+Target libraries are built with the target compiler. If gcc is present
+in the source tree, then the target compiler is the gcc that is built
+using the host compiler. Target libraries are libraries such as
+@samp{newlib} and @samp{libstdc++}. These libraries are not linked into
+the host programs, but are instead made available for use with programs
+built with the target compiler.
+
+For the rest of this section, assume that gcc is present in the source
+tree, so that it will be used to build the target libraries.
+
+There is a complication here. The configure process needs to know which
+compiler you are going to use to build a tool; otherwise, the feature
+tests will not work correctly. The Cygnus tree handles this by not
+configuring the target libraries until the target compiler is built. In
+order to permit everything to build using a single
+@samp{configure}/@samp{make}, the configuration of the target libraries
+is actually triggered during the make step.
+
+When the target libraries are configured, the @samp{--target} option is
+not used. Instead, the @samp{--host} option is used with the argument
+of the @samp{--target} option for the overall configuration. If no
+@samp{--target} option was used for the overall configuration, the
+@samp{--host} option will be passed with the output of the
+@file{config.guess} shell script. Any @samp{--build} option is passed
+down unchanged.
+
+This translation of configuration options is done because since the
+target libraries are compiled with the target compiler, they are being
+built in order to run on the target of the overall configuration. By
+the definition of host, this means that their host system is the same as
+the target system of the overall configuration.
+
+The same process is used for both a native configuration and a cross
+configuration. Even when using a native configuration, the target
+libraries will be configured and built using the newly built compiler.
+This is particularly important for the C++ libraries, since there is no
+reason to assume that the C++ compiler used to build the host tools (if
+there even is one) uses the same ABI as the g++ compiler which will be
+used to build the target libraries.
+
+There is one difference between a native configuration and a cross
+configuration. In a native configuration, the target libraries are
+normally configured and built as siblings of the host tools. In a cross
+configuration, the target libraries are normally built in a subdirectory
+whose name is the argument to @samp{--target}. This is mainly for
+historical reasons.
+
+To summarize, running @samp{configure} in the Cygnus tree configures all
+the host libraries and tools, but does not configure any of the target
+libraries. Running @samp{make} then does the following steps:
+
+@itemize @bullet
+@item
+Build the host libraries.
+@item
+Build the host programs, including gcc. Note that we call gcc both a
+host program (since it runs on the host) and a target compiler (since it
+generates code for the target).
+@item
+Using the newly built target compiler, configure the target libraries.
+@item
+Build the target libraries.
+@end itemize
+
+The steps need not be done in precisely this order, since they are
+actually controlled by @file{Makefile} targets.
+
+@node Target Library Configure Scripts
+@subsection Target Library Configure Scripts
+
+There are a few things you must know in order to write a configure
+script for a target library. This is just a quick sketch, and beginners
+shouldn't worry if they don't follow everything here.
+
+The target libraries are configured and built using a newly built target
+compiler. There may not be any startup files or libraries for this
+target compiler. In fact, those files will probably be built as part of
+some target library, which naturally means that they will not exist when
+your target library is configured.
+
+This means that the configure script for a target library may not use
+any test which requires doing a link. This unfortunately includes many
+useful autoconf macros, such as @samp{AC_CHECK_FUNCS}. autoconf macros
+which do a compile but not a link, such as @samp{AC_CHECK_HEADERS}, may
+be used.
+
+This is a severe restriction, but normally not a fatal one, as target
+libraries can often assume the presence of other target libraries, and
+thus know which functions will be available.
+
+As of this writing, the autoconf macro @samp{AC_PROG_CC} does a link to
+make sure that the compiler works. This may fail in a target library,
+so target libraries must use a different set of macros to locate the
+compiler. See the @file{configure.in} file in a directory like
+@file{libiberty} or @file{libgloss} for an example.
+
+As noted in the previous section, target libraries are sometimes built
+in directories which are siblings to the host tools, and are sometimes
+built in a subdirectory. The @samp{--with-target-subdir} configure
+option will be passed when the library is configured. Its value will be
+an empty string if the target library is a sibling. Its value will be
+the name of the subdirectory if the target library is in a subdirectory.
+
+If the overall build is not a native build (i.e., the overall configure
+used the @samp{--target} option), then the library will be configured
+with the @samp{--with-cross-host} option. The value of this option will
+be the host system of the overall build. Recall that the host system of
+the library will be the target of the overall build. If the overall
+build is a native build, the @samp{--with-cross-host} option will not be
+used.
+
+A library which can be built both standalone and as a target library may
+want to install itself into different directories depending upon the
+case. When built standalone, or when built native, the library should
+be installed in @samp{$(libdir)}. When built as a target library which
+is not native, the library should be installed in @samp{$(tooldir)/lib}.
+The @samp{--with-cross-host} option may be used to distinguish these
+cases.
+
+This same test of @samp{--with-cross-host} may be used to see whether it
+is OK to use link tests in the configure script. If the
+@samp{--with-cross-host} option is not used, then the library is being
+built either standalone or native, and a link should work.
+
+@node Make Targets in Cygnus Tree
+@subsection Make Targets in Cygnus Tree
+
+The top level @file{Makefile} in the Cygnus tree defines targets for
+every known subdirectory.
+
+For every subdirectory @var{dir} which holds a host library or program,
+the @file{Makefile} target @samp{all-@var{dir}} will build that library
+or program.
+
+There are dependencies among host tools. For example, building gcc
+requires first building gas, because the gcc build process invokes the
+target assembler. These dependencies are reflected in the top level
+@file{Makefile}.
+
+For every subdirectory @var{dir} which holds a target library, the
+@file{Makefile} target @samp{configure-target-@var{dir}} will configure
+that library. The @file{Makefile} target @samp{all-target-@var{dir}}
+will build that library.
+
+Every @samp{configure-target-@var{dir}} target depends upon
+@samp{all-gcc}, since gcc, the target compiler, is required to configure
+the tool. Every @samp{all-target-@var{dir}} target depends upon the
+corresponding @samp{configure-target-@var{dir}} target.
+
+There are several other targets which may be of interest for each
+directory: @samp{install-@var{dir}}, @samp{clean-@var{dir}}, and
+@samp{check-@var{dir}}. There are also corresponding @samp{target}
+versions of these for the target libraries , such as
+@samp{install-target-@var{dir}}.
+
+@node Target libiberty
+@subsection Target libiberty
+
+The @file{libiberty} subdirectory is currently a special case, in that
+it is the only directory which is built both using the host compiler and
+using the target compiler.
+
+This is because the files in @file{libiberty} are used when building the
+host tools, and they are also incorporated into the @file{libstdc++}
+target library as support code.
+
+This duality does not pose any particular difficulties. It means that
+there are targets for both @samp{all-libiberty} and
+@samp{all-target-libiberty}.
+
+In a native configuration, when target libraries are not built in a
+subdirectory, the same objects are normally used as both the host build
+and the target build. This is normally OK, since libiberty contains
+only C code, and in a native configuration the results of the host
+compiler and the target compiler are normally interoperable.
+
+Irix 6 is again an exception here, since the SGI native compiler
+defaults to using the @samp{O32} ABI, and gcc defaults to using the
+@samp{N32} ABI. On Irix 6, the target libraries are built in a
+subdirectory even for a native configuration, avoiding this problem.
+
+There are currently no other libraries built for both the host and the
+target, but there is no conceptual problem with adding more.
+
+@node Canadian Cross
+@chapter Canadian Cross
+@cindex canadian cross
+@cindex building with a cross compiler
+@cindex cross compiler, building with
+
+It is possible to use the GNU configure and build system to build a
+program which will run on a system which is different from the system on
+which the tools are built. In other words, it is possible to build
+programs using a cross compiler.
+
+This is referred to as a @dfn{Canadian Cross}.
+
+@menu
+* Canadian Cross Example:: Canadian Cross Example.
+* Canadian Cross Concepts:: Canadian Cross Concepts.
+* Build Cross Host Tools:: Build Cross Host Tools.
+* Build and Host Options:: Build and Host Options.
+* CCross not in Cygnus Tree:: Canadian Cross not in Cygnus Tree.
+* CCross in Cygnus Tree:: Canadian Cross in Cygnus Tree.
+* Supporting Canadian Cross:: Supporting Canadian Cross.
+@end menu
+
+@node Canadian Cross Example
+@section Canadian Cross Example
+
+Here is an example of a Canadian Cross.
+
+While running on a GNU/Linux, you can build a program which will run on
+a Solaris system. You would use a GNU/Linux cross Solaris compiler to
+build the program.
+
+Of course, you could not run the resulting program on your GNU/Linux
+system. You would have to copy it over to a Solaris system before you
+would run it.
+
+Of course, you could also simply build the programs on the Solaris
+system in the first place. However, perhaps the Solaris system is not
+available for some reason; perhaps you actually don't have one, but you
+want to build the tools for somebody else to use. Or perhaps your
+GNU/Linux system is much faster than your Solaris system.
+
+A Canadian Cross build is most frequently used when building programs to
+run on a non-Unix system, such as DOS or Windows. It may be simpler to
+configure and build on a Unix system than to support the configuration
+machinery on a non-Unix system.
+
+@node Canadian Cross Concepts
+@section Canadian Cross Concepts
+
+When building a Canadian Cross, there are at least two different systems
+involved: the system on which the tools are being built, and the system
+on which the tools will run.
+
+The system on which the tools are being built is called the @dfn{build}
+system.
+
+The system on which the tools will run is called the host system.
+
+For example, if you are building a Solaris program on a GNU/Linux
+system, as in the previous section, the build system would be GNU/Linux,
+and the host system would be Solaris.
+
+It is, of course, possible to build a cross compiler using a Canadian
+Cross (i.e., build a cross compiler using a cross compiler). In this
+case, the system for which the resulting cross compiler generates code
+is called the target system. (For a more complete discussion of host
+and target systems, @pxref{Host and Target}).
+
+An example of building a cross compiler using a Canadian Cross would be
+building a Windows cross MIPS ELF compiler on a GNU/Linux system. In
+this case the build system would be GNU/Linux, the host system would be
+Windows, and the target system would be MIPS ELF.
+
+The name Canadian Cross comes from the case when the build, host, and
+target systems are all different. At the time that these issues were
+all being hashed out, Canada had three national political parties.
+
+@node Build Cross Host Tools
+@section Build Cross Host Tools
+
+In order to configure a program for a Canadian Cross build, you must
+first build and install the set of cross tools you will use to build the
+program.
+
+These tools will be build cross host tools. That is, they will run on
+the build system, and will produce code that runs on the host system.
+
+It is easy to confuse the meaning of build and host here. Always
+remember that the build system is where you are doing the build, and the
+host system is where the resulting program will run. Therefore, you
+need a build cross host compiler.
+
+In general, you must have a complete cross environment in order to do
+the build. This normally means a cross compiler, cross assembler, and
+so forth, as well as libraries and include files for the host system.
+
+@node Build and Host Options
+@section Build and Host Options
+@cindex configuring a canadian cross
+@cindex canadian cross, configuring
+
+When you run @file{configure}, you must use both the @samp{--build} and
+@samp{--host} options.
+
+@cindex @samp{--build} option
+@cindex build option
+@cindex configure build system
+The @samp{--build} option is used to specify the configuration name of
+the build system. This can normally be the result of running the
+@file{config.guess} shell script, and it is reasonable to use
+@samp{--build=`config.guess`}.
+
+@cindex @samp{--host} option
+@cindex host option
+@cindex configure host
+The @samp{--host} option is used to specify the configuration name of
+the host system.
+
+As we explained earlier, @file{config.guess} is used to set the default
+value for the @samp{--host} option (@pxref{Using the Host Type}). We
+can now see that since @file{config.guess} returns the type of system on
+which it is run, it really identifies the build system. Since the host
+system is normally the same as the build system (i.e., people do not
+normally build using a cross compiler), it is reasonable to use the
+result of @file{config.guess} as the default for the host system when
+the @samp{--host} option is not used.
+
+It might seem that if the @samp{--host} option were used without the
+@samp{--build} option that the configure script could run
+@file{config.guess} to determine the build system, and presume a
+Canadian Cross if the result of @file{config.guess} differed from the
+@samp{--host} option. However, for historical reasons, some configure
+scripts are routinely run using an explicit @samp{--host} option, rather
+than using the default from @file{config.guess}. As noted earlier, it
+is difficult or impossible to reliably compare configuration names
+(@pxref{Using the Target Type}). Therefore, by convention, if the
+@samp{--host} option is used, but the @samp{--build} option is not used,
+then the build system defaults to the host system.
+
+@node CCross not in Cygnus Tree
+@section Canadian Cross not in Cygnus Tree.
+
+If you are not using the Cygnus tree, you must explicitly specify the
+cross tools which you want to use to build the program. This is done by
+setting environment variables before running the @file{configure}
+script.
+
+You must normally set at least the environment variables @samp{CC},
+@samp{AR}, and @samp{RANLIB} to the cross tools which you want to use to
+build.
+
+For some programs, you must set additional cross tools as well, such as
+@samp{AS}, @samp{LD}, or @samp{NM}.
+
+You would set these environment variables to the build cross tools which
+you are going to use.
+
+For example, if you are building a Solaris program on a GNU/Linux
+system, and your GNU/Linux cross Solaris compiler were named
+@samp{solaris-gcc}, then you would set the environment variable
+@samp{CC} to @samp{solaris-gcc}.
+
+@node CCross in Cygnus Tree
+@section Canadian Cross in Cygnus Tree
+@cindex canadian cross in cygnus tree
+
+This section describes configuring and building a Canadian Cross when
+using the Cygnus tree.
+
+@menu
+* Standard Cygnus CCross:: Building a Normal Program.
+* Cross Cygnus CCross:: Building a Cross Program.
+@end menu
+
+@node Standard Cygnus CCross
+@subsection Building a Normal Program
+
+When configuring a Canadian Cross in the Cygnus tree, all the
+appropriate environment variables are automatically set to
+@samp{@var{host}-@var{tool}}, where @var{host} is the value used for the
+@samp{--host} option, and @var{tool} is the name of the tool (e.g.,
+@samp{gcc}, @samp{as}, etc.). These tools must be on your @samp{PATH}.
+
+Adding a prefix of @var{host} will give the usual name for the build
+cross host tools. To see this, consider that when these cross tools
+were built, they were configured to run on the build system and to
+produce code for the host system. That is, they were configured with a
+@samp{--target} option that is the same as the system which we are now
+calling the host. Recall that the default name for installed cross
+tools uses the target system as a prefix (@pxref{Using the Target
+Type}). Since that is the system which we are now calling the host,
+@var{host} is the right prefix to use.
+
+For example, if you configure with @samp{--build=i386-linux-gnu} and
+@samp{--host=solaris}, then the Cygnus tree will automatically default
+to using the compiler @samp{solaris-gcc}. You must have previously
+built and installed this compiler, probably by doing a build with no
+@samp{--host} option and with a @samp{--target} option of
+@samp{solaris}.
+
+@node Cross Cygnus CCross
+@subsection Building a Cross Program
+
+There are additional considerations if you want to build a cross
+compiler, rather than a native compiler, in the Cygnus tree using a
+Canadian Cross.
+
+When you build a cross compiler using the Cygnus tree, then the target
+libraries will normally be built with the newly built target compiler
+(@pxref{Host and Target Libraries}). However, this will not work when
+building with a Canadian Cross. This is because the newly built target
+compiler will be a program which runs on the host system, and therefore
+will not be able to run on the build system.
+
+Therefore, when building a cross compiler with the Cygnus tree, you must
+first install a set of build cross target tools. These tools will be
+used when building the target libraries.
+
+Note that this is not a requirement of a Canadian Cross in general. For
+example, it would be possible to build just the host cross target tools
+on the build system, to copy the tools to the host system, and to build
+the target libraries on the host system. The requirement for build
+cross target tools is imposed by the Cygnus tree, which expects to be
+able to build both host programs and target libraries in a single
+@samp{configure}/@samp{make} step. Because it builds these in a single
+step, it expects to be able to build the target libraries on the build
+system, which means that it must use a build cross target toolchain.
+
+For example, suppose you want to build a Windows cross MIPS ELF compiler
+on a GNU/Linux system. You must have previously installed both a
+GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF
+compiler.
+
+In order to build the Windows (configuration name @samp{i386-cygwin32})
+cross MIPS ELF (configure name @samp{mips-elf}) compiler, you might
+execute the following commands (long command lines are broken across
+lines with a trailing backslash as a continuation character).
+
+@example
+mkdir linux-x-cygwin32
+cd linux-x-cygwin32
+@var{srcdir}/configure --target i386-cygwin32 --prefix=@var{installdir} \
+ --exec-prefix=@var{installdir}/H-i386-linux
+make
+make install
+cd ..
+mkdir linux-x-mips-elf
+cd linux-x-mips-elf
+@var{srcdir}/configure --target mips-elf --prefix=@var{installdir} \
+ --exec-prefix=@var{installdir}/H-i386-linux
+make
+make install
+cd ..
+mkdir cygwin32-x-mips-elf
+cd cygwin32-x-mips-elf
+@var{srcdir}/configure --build=i386-linux-gnu --host=i386-cygwin32 \
+ --target=mips-elf --prefix=@var{wininstalldir} \
+ --exec-prefix=@var{wininstalldir}/H-i386-cygwin32
+make
+make install
+@end example
+
+You would then copy the contents of @var{wininstalldir} over to the
+Windows machine, and run the resulting programs.
+
+@node Supporting Canadian Cross
+@section Supporting Canadian Cross
+
+If you want to make it possible to build a program you are developing
+using a Canadian Cross, you must take some care when writing your
+configure and make rules. Simple cases will normally work correctly.
+However, it is not hard to write configure and make tests which will
+fail in a Canadian Cross.
+
+@menu
+* CCross in Configure:: Supporting Canadian Cross in Configure Scripts.
+* CCross in Make:: Supporting Canadian Cross in Makefiles.
+@end menu
+
+@node CCross in Configure
+@subsection Supporting Canadian Cross in Configure Scripts
+@cindex canadian cross in configure
+
+In a @file{configure.in} file, after calling @samp{AC_PROG_CC}, you can
+find out whether this is a Canadian Cross configure by examining the
+shell variable @samp{cross_compiling}. In a Canadian Cross, which means
+that the compiler is a cross compiler, @samp{cross_compiling} will be
+@samp{yes}. In a normal configuration, @samp{cross_compiling} will be
+@samp{no}.
+
+You ordinarily do not need to know the type of the build system in a
+configure script. However, if you do need that information, you can get
+it by using the macro @samp{AC_CANONICAL_SYSTEM}, the same macro that is
+used to determine the target system. This macro will set the variables
+@samp{build}, @samp{build_alias}, @samp{build_cpu}, @samp{build_vendor},
+and @samp{build_os}, which correspond to the similar @samp{target} and
+@samp{host} variables, except that they describe the build system.
+
+When writing tests in @file{configure.in}, you must remember that you
+want to test the host environment, not the build environment.
+
+Macros like @samp{AC_CHECK_FUNCS} which use the compiler will test the
+host environment. That is because the tests will be done by running the
+compiler, which is actually a build cross host compiler. If the
+compiler can find the function, that means that the function is present
+in the host environment.
+
+Tests like @samp{test -f /dev/ptyp0}, on the other hand, will test the
+build environment. Remember that the configure script is running on the
+build system, not the host system. If your configure scripts examines
+files, those files will be on the build system. Whatever you determine
+based on those files may or may not be the case on the host system.
+
+Most autoconf macros will work correctly for a Canadian Cross. The main
+exception is @samp{AC_TRY_RUN}. This macro tries to compile and run a
+test program. This will fail in a Canadian Cross, because the program
+will be compiled for the host system, which means that it will not run
+on the build system.
+
+The @samp{AC_TRY_RUN} macro provides an optional argument to tell the
+configure script what to do in a Canadian Cross. If that argument is
+not present, you will get a warning when you run @samp{autoconf}:
+@smallexample
+warning: AC_TRY_RUN called without default to allow cross compiling
+@end smallexample
+@noindent
+This tells you that the resulting @file{configure} script will not work
+with a Canadian Cross.
+
+In some cases while it may better to perform a test at configure time,
+it is also possible to perform the test at run time. In such a case you
+can use the cross compiling argument to @samp{AC_TRY_RUN} to tell your
+program that the test could not be performed at configure time.
+
+There are a few other autoconf macros which will not work correctly with
+a Canadian Cross: a partial list is @samp{AC_FUNC_GETPGRP},
+@samp{AC_FUNC_SETPGRP}, @samp{AC_FUNC_SETVBUF_REVERSED}, and
+@samp{AC_SYS_RESTARTABLE_SYSCALLS}. The @samp{AC_CHECK_SIZEOF} macro is
+generally not very useful with a Canadian Cross; it permits an optional
+argument indicating the default size, but there is no way to know what
+the correct default should be.
+
+@node CCross in Make
+@subsection Supporting Canadian Cross in Makefiles.
+@cindex canadian cross in makefile
+
+The main Canadian Cross issue in a @file{Makefile} arises when you want
+to use a subsidiary program to generate code or data which you will then
+include in your real program.
+
+If you compile this subsidiary program using @samp{$(CC)} in the usual
+way, you will not be able to run it. This is because @samp{$(CC)} will
+build a program for the host system, but the program is being built on
+the build system.
+
+You must instead use a compiler for the build system, rather than the
+host system. In the Cygnus tree, this make variable
+@samp{$(CC_FOR_BUILD)} will hold a compiler for the build system.
+
+Note that you should not include @file{config.h} in a file you are
+compiling with @samp{$(CC_FOR_BUILD)}. The @file{configure} script will
+build @file{config.h} with information for the host system. However,
+you are compiling the file using a compiler for the build system (a
+native compiler). Subsidiary programs are normally simple filters which
+do no user interaction, and it is normally possible to write them in a
+highly portable fashion so that the absence of @file{config.h} is not
+crucial.
+
+@cindex @samp{HOST_CC}
+The gcc @file{Makefile.in} shows a complex situation in which certain
+files, such as @file{rtl.c}, must be compiled into both subsidiary
+programs run on the build system and into the final program. This
+approach may be of interest for advanced build system hackers. Note
+that the build system compiler is rather confusingly called
+@samp{HOST_CC}.
+
+@node Cygnus Configure
+@chapter Cygnus Configure
+@cindex cygnus configure
+
+The Cygnus configure script predates autoconf. All of its interesting
+features have been incorporated into autoconf. No new programs should
+be written to use the Cygnus configure script.
+
+However, the Cygnus configure script is still used in a few places: at
+the top of the Cygnus tree and in a few target libraries in the Cygnus
+tree. Until those uses have been replaced with autoconf, some brief
+notes are appropriate here. This is not complete documentation, but it
+should be possible to use this as a guide while examining the scripts
+themselves.
+
+@menu
+* Cygnus Configure Basics:: Cygnus Configure Basics.
+* Cygnus Configure in C++ Libraries:: Cygnus Configure in C++ Libraries.
+@end menu
+
+@node Cygnus Configure Basics
+@section Cygnus Configure Basics
+
+Cygnus configure does not use any generated files; there is no program
+corresponding to @samp{autoconf}. Instead, there is a single shell
+script named @samp{configure} which may be found at the top of the
+Cygnus tree. This shell script was written by hand; it was not
+generated by autoconf, and it is incorrect, and indeed harmful, to run
+@samp{autoconf} in the top level of a Cygnus tree.
+
+Cygnus configure works in a particular directory by examining the file
+@file{configure.in} in that directory. That file is broken into four
+separate shell scripts.
+
+The first is the contents of @file{configure.in} up to a line that
+starts with @samp{# per-host:}. This is the common part.
+
+The second is the rest of @file{configure.in} up to a line that starts
+with @samp{# per-target:}. This is the per host part.
+
+The third is the rest of @file{configure.in} up to a line that starts
+with @samp{# post-target:}. This is the per target part.
+
+The fourth is the remainder of @file{configure.in}. This is the post
+target part.
+
+If any of these comment lines are missing, the corresponding shell
+script is empty.
+
+Cygnus configure will first execute the common part. This must set the
+shell variable @samp{srctrigger} to the name of a source file, to
+confirm that Cygnus configure is looking at the right directory. This
+may set the shell variables @samp{package_makefile_frag} and
+@samp{package_makefile_rules_frag}.
+
+Cygnus configure will next set the @samp{build} and @samp{host} shell
+variables, and execute the per host part. This may set the shell
+variable @samp{host_makefile_frag}.
+
+Cygnus configure will next set the @samp{target} variable, and execute
+the per target part. This may set the shell variable
+@samp{target_makefile_frag}.
+
+Any of these scripts may set the @samp{subdirs} shell variable. This
+variable is a list of subdirectories where a @file{Makefile.in} file may
+be found. Cygnus configure will automatically look for a
+@file{Makefile.in} file in the current directory. The @samp{subdirs}
+shell variable is not normally used, and I believe that the only
+directory which uses it at present is @file{newlib}.
+
+For each @file{Makefile.in}, Cygnus configure will automatically create
+a @file{Makefile} by adding definitions for @samp{make} variables such
+as @samp{host} and @samp{target}, and automatically editing the values
+of @samp{make} variables such as @samp{prefix} if they are present.
+
+Also, if any of the @samp{makefile_frag} shell variables are set, Cygnus
+configure will interpret them as file names relative to either the
+working directory or the source directory, and will read the contents of
+the file into the generated @file{Makefile}. The file contents will be
+read in after the first line in @file{Makefile.in} which starts with
+@samp{####}.
+
+These @file{Makefile} fragments are used to customize behaviour for a
+particular host or target. They serve to select particular files to
+compile, and to define particular preprocessor macros by providing
+values for @samp{make} variables which are then used during compilation.
+Cygnus configure, unlike autoconf, normally does not do feature tests,
+and normally requires support to be added manually for each new host.
+
+The @file{Makefile} fragment support is similar to the autoconf
+@samp{AC_SUBST_FILE} macro.
+
+After creating each @file{Makefile}, the post target script will be run
+(i.e., it may be run several times). This script may further customize
+the @file{Makefile}. When it is run, the shell variable @samp{Makefile}
+will hold the name of the @file{Makefile}, including the appropriate
+directory component.
+
+Like an autoconf generated @file{configure} script, Cygnus configure
+will create a file named @file{config.status} which, when run, will
+automatically recreate the configuration. The @file{config.status} file
+will simply execute the Cygnus configure script again with the
+appropriate arguments.
+
+Any of the parts of @file{configure.in} may set the shell variables
+@samp{files} and @samp{links}. Cygnus configure will set up symlinks
+from the names in @samp{links} to the files named in @samp{files}. This
+is similar to the autoconf @samp{AC_LINK_FILES} macro.
+
+Finally, any of the parts of @file{configure.in} may set the shell
+variable @samp{configdirs} to a set of subdirectories. If it is set,
+Cygnus configure will recursively run the configure process in each
+subdirectory. If the subdirectory uses Cygnus configure, it will
+contain a @file{configure.in} file but no @file{configure} file, in
+which case Cygnus configure will invoke itself recursively. If the
+subdirectory has a @file{configure} file, Cygnus configure assumes that
+it is an autoconf generated @file{configure} script, and simply invokes
+it directly.
+
+@node Cygnus Configure in C++ Libraries
+@section Cygnus Configure in C++ Libraries
+@cindex @file{libstdc++} configure
+@cindex @file{libio} configure
+@cindex @file{libg++} configure
+
+The C++ library configure system, written by Per Bothner, deserves
+special mention. It uses Cygnus configure, but it does feature testing
+like that done by autoconf generated @file{configure} scripts. This
+approach is used in the libraries @file{libio}, @file{libstdc++}, and
+@file{libg++}.
+
+Most of the @file{Makefile} information is written out by the shell
+script @file{libio/config.shared}. Each @file{configure.in} file sets
+certain shell variables, and then invokes @file{config.shared} to create
+two package @file{Makefile} fragments. These fragments are then
+incorporated into the resulting @file{Makefile} by the Cygnus configure
+script.
+
+The file @file{_G_config.h} is created in the @file{libio} object
+directory by running the shell script @file{libio/gen-params}. This
+shell script uses feature tests to define macros and typedefs in
+@file{_G_config.h}.
+
+@node Multilibs
+@chapter Multilibs
+@cindex multilibs
+
+For some targets gcc may have different processor requirements depending
+upon command line options. An obvious example is the
+@samp{-msoft-float} option supported on several processors. This option
+means that the floating point registers are not available, which means
+that floating point operations must be done by calling an emulation
+subroutine rather than by using machine instructions.
+
+For such options, gcc is often configured to compile target libraries
+twice: once with @samp{-msoft-float} and once without. When gcc
+compiles target libraries more than once, the resulting libraries are
+called @dfn{multilibs}.
+
+Multilibs are not really part of the GNU configure and build system, but
+we discuss them here since they require support in the @file{configure}
+scripts and @file{Makefile}s used for target libraries.
+
+@menu
+* Multilibs in gcc:: Multilibs in gcc.
+* Multilibs in Target Libraries:: Multilibs in Target Libraries.
+@end menu
+
+@node Multilibs in gcc
+@section Multilibs in gcc
+
+In gcc, multilibs are defined by setting the variable
+@samp{MULTILIB_OPTIONS} in the target @file{Makefile} fragment. Several
+other @samp{MULTILIB} variables may also be defined there. @xref{Target
+Fragment, , The Target Makefile Fragment, gcc, Using and Porting GNU
+CC}.
+
+If you have built gcc, you can see what multilibs it uses by running it
+with the @samp{-print-multi-lib} option. The output @samp{.;} means
+that no multilibs are used. In general, the output is a sequence of
+lines, one per multilib. The first part of each line, up to the
+@samp{;}, is the name of the multilib directory. The second part is a
+list of compiler options separated by @samp{@@} characters.
+
+Multilibs are built in a tree of directories. The top of the tree,
+represented by @samp{.} in the list of multilib directories, is the
+default library to use when no special compiler options are used. The
+subdirectories of the tree hold versions of the library to use when
+particular compiler options are used.
+
+@node Multilibs in Target Libraries
+@section Multilibs in Target Libraries
+
+The target libraries in the Cygnus tree are automatically built with
+multilibs. That means that each library is built multiple times.
+
+This default is set in the top level @file{configure.in} file, by adding
+@samp{--enable-multilib} to the list of arguments passed to configure
+when it is run for the target libraries (@pxref{Host and Target
+Libraries}).
+
+Each target library uses the shell script @file{config-ml.in}, written
+by Doug Evans, to prepare to build target libraries. This shell script
+is invoked after the @file{Makefile} has been created by the
+@file{configure} script. If multilibs are not enabled, it does nothing,
+otherwise it modifies the @file{Makefile} to support multilibs.
+
+The @file{config-ml.in} script makes one copy of the @file{Makefile} for
+each multilib in the appropriate subdirectory. When configuring in the
+source directory (which is not recommended), it will build a symlink
+tree of the sources in each subdirectory.
+
+The @file{config-ml.in} script sets several variables in the various
+@file{Makefile}s. The @file{Makefile.in} must have definitions for
+these variables already; @file{config-ml.in} simply changes the existing
+values. The @file{Makefile} should use default values for these
+variables which will do the right thing in the subdirectories.
+
+@table @samp
+@item MULTISRCTOP
+@file{config-ml.in} will set this to a sequence of @samp{../} strings,
+where the number of strings is the number of multilib levels in the
+source tree. The default value should be the empty string.
+@item MULTIBUILDTOP
+@file{config-ml.in} will set this to a sequence of @samp{../} strings,
+where the number of strings is number of multilib levels in the object
+directory. The default value should be the empty string. This will
+differ from @samp{MULTISRCTOP} when configuring in the source tree
+(which is not recommended).
+@item MULTIDIRS
+In the top level @file{Makefile} only, @file{config-ml.in} will set this
+to the list of multilib subdirectories. The default value should be the
+empty string.
+@item MULTISUBDIR
+@file{config-ml.in} will set this to the installed subdirectory name to
+use for this subdirectory, with a leading @samp{/}. The default value
+shold be the empty string.
+@item MULTIDO
+@itemx MULTICLEAN
+In the top level @file{Makefile} only, @file{config-ml.in} will set
+these variables to commands to use when doing a recursive make. These
+variables should both default to the string @samp{true}, so that by
+default nothing happens.
+@end table
+
+All references to the parent of the source directory should use the
+variable @samp{MULTISRCTOP}. Instead of writing @samp{$(srcdir)/..},
+you must write @samp{$(srcdir)/$(MULTISRCTOP)..}.
+
+Similarly, references to the parent of the object directory should use
+the variable @samp{MULTIBUILDTOP}.
+
+In the installation target, the libraries should be installed in the
+subdirectory @samp{MULTISUBDIR}. Instead of installing
+@samp{$(libdir)/libfoo.a}, install
+@samp{$(libdir)$(MULTISUBDIR)/libfoo.a}.
+
+The @file{config-ml.in} script also modifies the top level
+@file{Makefile} to add @samp{multi-do} and @samp{multi-clean} targets
+which are used when building multilibs.
+
+The default target of the @file{Makefile} should include the following
+command:
+@smallexample
+@@$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
+@end smallexample
+@noindent
+This assumes that @samp{$(FLAGS_TO_PASS)} is defined as a set of
+variables to pass to a recursive invocation of @samp{make}. This will
+build all the multilibs. Note that the default value of @samp{MULTIDO}
+is @samp{true}, so by default this command will do nothing. It will
+only do something in the top level @file{Makefile} if multilibs were
+enabled.
+
+The @samp{install} target of the @file{Makefile} should include the
+following command:
+@smallexample
+@@$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
+@end smallexample
+
+In general, any operation, other than clean, which should be performed
+on all the multilibs should use a @samp{$(MULTIDO)} line, setting the
+variable @samp{DO} to the target of each recursive call to @samp{make}.
+
+The @samp{clean} targets (@samp{clean}, @samp{mostlyclean}, etc.) should
+use @samp{$(MULTICLEAN)}. For example, the @samp{clean} target should
+do this:
+@smallexample
+@@$(MULTICLEAN) DO=clean multi-clean
+@end smallexample
+
+@node FAQ
+@chapter Frequently Asked Questions
+
+@table @asis
+@item Which do I run first, @samp{autoconf} or @samp{automake}?
+Except when you first add autoconf or automake support to a package, you
+shouldn't run either by hand. Instead, configure with the
+@samp{--enable-maintainer-mode} option, and let @samp{make} take care of
+it.
+
+@cindex undefined macros
+@item @samp{autoconf} says something about undefined macros.
+This means that you have macros in your @file{configure.in} which are
+not defined by @samp{autoconf}. You may be using an old version of
+@samp{autoconf}; try building and installing a newer one. Make sure the
+newly installled @samp{autoconf} is first on your @samp{PATH}. Also,
+see the next question.
+
+@cindex @samp{CY_GNU_GETTEXT} in @file{configure}
+@cindex @samp{AM_PROG_LIBTOOL} in @file{configure}
+@item My @file{configure} script has stuff like @samp{CY_GNU_GETTEXT} in it.
+This means that you have macros in your @file{configure.in} which should
+be defined in your @file{aclocal.m4} file, but aren't. This usually
+means that @samp{aclocal} was not able to appropriate definitions of the
+macros. Make sure that you have installed all the packages you need.
+In particular, make sure that you have installed libtool (this is where
+@samp{AM_PROG_LIBTOOL} is defined) and gettext (this is where
+@samp{CY_GNU_GETTEXT} is defined, at least in the Cygnus version of
+gettext).
+
+@cindex @file{Makefile}, garbage characters
+@item My @file{Makefile} has @samp{@@} characters in it.
+This may mean that you tried to use an autoconf substitution in your
+@file{Makefile.in} without adding the appropriate @samp{AC_SUBST} call
+to your @file{configure} script. Or it may just mean that you need to
+rebuild @file{Makefile} in your build directory. To rebuild
+@file{Makefile} from @file{Makefile.in}, run the shell script
+@file{config.status} with no arguments. If you need to force
+@file{configure} to run again, first run @samp{config.status --recheck}.
+These runs are normally done automatically by @file{Makefile} targets,
+but if your @file{Makefile} has gotten messed up you'll need to help
+them along.
+
+@cindex @samp{config.status --recheck}
+@item Why do I have to run both @samp{config.status --recheck} and @samp{config.status}?
+Normally, you don't; they will be run automatically by @file{Makefile}
+targets. If you do need to run them, use @samp{config.status --recheck}
+to run the @file{configure} script again with the same arguments as the
+first time you ran it. Use @samp{config.status} (with no arguments) to
+regenerate all files (@file{Makefile}, @file{config.h}, etc.) based on
+the results of the configure script. The two cases are separate because
+it isn't always necessary to regenerate all the files after running
+@samp{config.status --recheck}. The @file{Makefile} targets generated
+by automake will use the environment variables @samp{CONFIG_FILES} and
+@samp{CONFIG_HEADERS} to only regenerate files as they are needed.
+
+@item What is the Cygnus tree?
+The Cygnus tree is used for various packages including gdb, the GNU
+binutils, and egcs. It is also, of course, used for Cygnus releases.
+It is the build system which was developed at Cygnus, using the Cygnus
+configure script. It permits building many different packages with a
+single configure and make. The configure scripts in the tree are being
+converted to autoconf, but the general build structure remains intact.
+
+@item Why do I have to keep rebuilding and reinstalling the tools?
+I know, it's a pain. Unfortunately, there are bugs in the tools
+themselves which need to be fixed, and each time that happens everybody
+who uses the tools need to reinstall new versions of them. I don't know
+if there is going to be a clever fix until the tools stabilize.
+
+@item Why not just have a Cygnus tree @samp{make} target to update the tools?
+The tools unfortunately need to be installed before they can be used.
+That means that they must be built using an appropriate prefix, and it
+seems unwise to assume that every configuration uses an appropriate
+prefix. It might be possible to make them work in place, or it might be
+possible to install them in some subdirectory; so far these approaches
+have not been implemented.
+@end table
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@contents
+@bye
Index: standards.texi
===================================================================
--- standards.texi (nonexistent)
+++ standards.texi (revision 1765)
@@ -0,0 +1,3742 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename standards.info
+@settitle GNU Coding Standards
+@c This date is automagically updated when you save this file:
+@set lastupdate February 14, 2002
+@c %**end of header
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@c @setchapternewpage odd
+@setchapternewpage off
+
+@c Put everything in one index (arbitrarily chosen to be the concept index).
+@syncodeindex fn cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex vr cp
+
+@c This is used by a cross ref in make-stds.texi
+@set CODESTD 1
+@iftex
+@set CHAPTER chapter
+@end iftex
+@ifinfo
+@set CHAPTER node
+@end ifinfo
+
+@ifinfo
+GNU Coding Standards
+Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no
+Front-Cover Texts, and with no Back-Cover Texts.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end ifinfo
+
+@titlepage
+@title GNU Coding Standards
+@author Richard Stallman, et al.
+@author last updated @value{lastupdate}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no
+Front-Cover Texts, and with no Back-Cover Texts.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end titlepage
+
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top Version
+
+Last updated @value{lastupdate}.
+@end ifinfo
+
+@menu
+* Preface:: About the GNU Coding Standards
+* Legal Issues:: Keeping Free Software Free
+* Design Advice:: General Program Design
+* Program Behavior:: Program Behavior for All Programs
+* Writing C:: Making The Best Use of C
+* Documentation:: Documenting Programs
+* Managing Releases:: The Release Process
+* References:: References to Non-Free Software or Documentation
+* Copying This Manual:: How to Make Copies of This Manual
+* Index::
+
+@end menu
+
+@node Preface
+@chapter About the GNU Coding Standards
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers. Their purpose is to make the GNU system clean,
+consistent, and easy to install. This document can also be read as a
+guide to writing portable, robust and reliable programs. It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language. The rules often
+state reasons for writing in a certain way.
+
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+
+@cindex where to obtain @code{standards.texi}
+@cindex downloading this manual
+If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version. You can ftp the GNU
+Coding Standards from any GNU FTP host in the directory
+@file{/pub/gnu/standards/}. The GNU Coding Standards are available
+there in several different formats: @file{standards.text},
+@file{standards.info}, and @file{standards.dvi}, as well as the
+Texinfo ``source'' which is divided in two files:
+@file{standards.texi} and @file{make-stds.texi}. The GNU Coding
+Standards are also available on the GNU World Wide Web server:
+@uref{http://www.gnu.org/prep/standards_toc.html}.
+
+Corrections or suggestions for this document should be sent to
+@email{bug-standards@@gnu.org}. If you make a suggestion, please include a
+suggested new wording for it; our time is limited. We prefer a context
+diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
+you don't have those files, please mail your suggestion anyway.
+
+These standards cover the minimum of what is important when writing a
+GNU package. Likely, the needs for additional standards will come up.
+Sometimes, you might suggest that such standards be added to this
+document. If you think your standards would be generally useful, please
+do suggest them.
+
+You should also set standards for your package on many questions not
+addressed or not firmly specified here. The most important point is to
+be self-consistent---try to stick to the conventions you pick, and try
+to document them as much as possible. That way, your program will be
+more maintainable by others.
+
+@node Legal Issues
+@chapter Keeping Free Software Free
+@cindex legal aspects
+
+This @value{CHAPTER} discusses how you can make sure that GNU software
+avoids legal difficulties, and other related issues.
+
+@menu
+* Reading Non-Free Code:: Referring to Proprietary Programs
+* Contributions:: Accepting Contributions
+* Trademarks:: How We Deal with Trademark Issues
+@end menu
+
+@node Reading Non-Free Code
+@section Referring to Proprietary Programs
+@cindex proprietary programs
+@cindex avoiding proprietary code
+
+Don't in any circumstances refer to Unix source code for or during
+your work on GNU! (Or to any other proprietary programs.)
+
+If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different. You could keep the entire input file in core and scan it
+there instead of using stdio. Use a smarter algorithm discovered more
+recently than the Unix program. Eliminate use of temporary files. Do
+it in one pass instead of two (we did this in the assembler).
+
+Or, on the contrary, emphasize simplicity instead of speed. For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+Or go for generality. For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead. Make sure your program handles NULs and
+other funny characters in the input files. Add a programming language
+for extensibility and write part of the program in that language.
+
+Or turn some parts of the program into independently usable libraries.
+Or use a simple garbage collector instead of tracking precisely when
+to free memory, or use a new GNU facility such as obstacks.
+
+@node Contributions
+@section Accepting Contributions
+@cindex legal papers
+@cindex accepting contributions
+
+If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it---just as we asked you to
+sign papers initially. @emph{Each} person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers. Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+This applies both before you release the program and afterward. If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+
+This also applies to comments and documentation files. For copyright
+law, comments and code are just text. Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+We know it is frustrating to ask for legal papers; it's frustrating for
+us as well. But if you don't wait, you are going out on a limb---for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+
+You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes. Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use. For example, if someone send you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+
+The very worst thing is if you forget to tell us about the other
+contributor. We could be very embarrassed in court some day as a
+result.
+
+We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy.
+
+@node Trademarks
+@section Trademarks
+@cindex trademarks
+
+Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so. The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, so
+we don't use them. There is no legal requirement for them.
+
+What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might read as naming or labeling
+our own programs or activities. For example, since ``Objective C'' is
+(or at least was) a trademark, we made sure to say that we provide a
+``compiler for the Objective C language'' rather than an ``Objective C
+compiler''. The latter is meant to be short for the former, but it does
+not explicitly state the relationship, so it could be misinterpreted as
+using ``Objective C'' as a label for the compiler rather than for the
+language.
+
+@node Design Advice
+@chapter General Program Design
+@cindex program design
+
+This @value{CHAPTER} discusses some of the issues you should take into
+account when designing your program.
+
+@c Standard or ANSI C
+@c
+@c In 1989 the American National Standards Institute (ANSI) standardized
+@c C as standard X3.159-1989. In December of that year the
+@c International Standards Organization ISO adopted the ANSI C standard
+@c making minor changes. In 1990 ANSI then re-adopted ISO standard
+@c C. This version of C is known as either ANSI C or Standard C.
+
+@c A major revision of the C Standard appeared in 1999.
+
+@menu
+* Source Language:: Which languges to use.
+* Compatibility:: Compatibility with other implementations
+* Using Extensions:: Using non-standard features
+* Standard C:: Using Standard C features
+* Conditional Compilation:: Compiling Code Only If A Conditional is True
+@end menu
+
+@node Source Language
+@section Which Languages to Use
+@cindex programming languges
+
+When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C. Using another language is like
+using a non-standard feature: it will cause trouble for users. Even if
+GCC supports the other language, users may find it inconvenient to have
+to install the compiler for that other language in order to build your
+program. For example, if you write your program in C++, people will
+have to install the GNU C++ compiler in order to compile your program.
+
+C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
+So in general it is much better to use C, rather than the
+comparable alternatives.
+
+But there are two exceptions to that conclusion:
+
+@itemize @bullet
+@item
+It is no problem to use another language to write a tool specifically
+intended for use with that language. That is because the only people
+who want to build the tool will be those who have installed the other
+language anyway.
+
+@item
+If an application is of interest only to a narrow part of the community,
+then the question of which language it is written in has less effect on
+other people, so you may as well please yourself.
+@end itemize
+
+Many programs are designed to be extensible: they include an interpreter
+for a language that is higher level than C. Often much of the program
+is written in that language, too. The Emacs editor pioneered this
+technique.
+
+@cindex GUILE
+The standard extensibility interpreter for GNU software is GUILE, which
+implements the language Scheme (an especially clean and simple dialect
+of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject
+programs written in other ``scripting languages'' such as Perl and
+Python, but using GUILE is very important for the overall consistency of
+the GNU system.
+
+@node Compatibility
+@section Compatibility with Other Implementations
+@cindex compatibility with C and @sc{posix} standards
+@cindex @sc{posix} compatibility
+
+With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with Standard C if Standard C specifies their
+behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
+their behavior.
+
+When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+@cindex options for compatibility
+Standard C and @sc{posix} prohibit many kinds of extensions. Feel
+free to make the extensions anyway, and include a @samp{--ansi},
+@samp{--posix}, or @samp{--compatible} option to turn them off.
+However, if the extension has a significant chance of breaking any real
+programs or scripts, then it is not really upward compatible. So you
+should try to redesign its interface to make it upward compatible.
+
+@cindex @code{POSIXLY_CORRECT}, environment variable
+Many GNU programs suppress extensions that conflict with @sc{posix} if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value). Please make your program recognize this
+variable if appropriate.
+
+When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better. (For example,
+@code{vi} is replaced with Emacs.) But it is nice to offer a compatible
+feature as well. (There is a free @code{vi} clone, so we offer it.)
+
+Additional useful features are welcome regardless of whether
+there is any precedent for them.
+
+@node Using Extensions
+@section Using Non-standard Features
+@cindex non-standard extensions
+
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities. Whether to use these
+extensions in implementing your program is a difficult question.
+
+On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program
+unless the other GNU tools are available. This might cause the
+program to work on fewer kinds of machines.
+
+With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a ``keyword'' @code{INLINE}
+and define that as a macro to expand into either @code{inline} or
+nothing, depending on the compiler.
+
+In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+An exception to this rule are the large, established programs (such as
+Emacs) which run on a great variety of systems. Using GNU extensions in
+such programs would make many users unhappy, so we don't do that.
+
+Another exception is for programs that are used as part of compilation:
+anything that must be compiled with other compilers in order to
+bootstrap the GNU compilation facilities. If these require the GNU
+compiler, then no one can compile them without having them installed
+already. That would be extremely troublesome in certain cases.
+
+@node Standard C
+@section Standard C and Pre-Standard C
+@cindex @sc{ansi} C standard
+
+1989 Standard C is widespread enough now that it is ok to use its
+features in new programs. There is one exception: do not ever use the
+``trigraph'' feature of Standard C.
+
+1999 Standard C is not widespread yet, so please do not require its
+features in programs. It is ok to use its features if they are present.
+
+However, it is easy to support pre-standard compilers in most programs,
+so if you know how to do that, feel free. If a program you are
+maintaining has such support, you should try to keep it working.
+
+@cindex function prototypes
+To support pre-standard C, instead of writing function definitions in
+standard prototype form,
+
+@example
+int
+foo (int x, int y)
+@dots{}
+@end example
+
+@noindent
+write the definition in pre-standard style like this,
+
+@example
+int
+foo (x, y)
+ int x, y;
+@dots{}
+@end example
+
+@noindent
+and use a separate declaration to specify the argument prototype:
+
+@example
+int foo (int, int);
+@end example
+
+You need such a declaration anyway, in a header file, to get the benefit
+of prototypes in all the files where the function is called. And once
+you have the declaration, you normally lose nothing by writing the
+function definition in the pre-standard style.
+
+This technique does not work for integer types narrower than @code{int}.
+If you think of an argument as being of a type narrower than @code{int},
+declare it as @code{int} instead.
+
+There are a few special cases where this technique is hard to use. For
+example, if a function argument needs to hold the system type
+@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
+@code{int} on some machines; but you cannot use @code{int} instead,
+because @code{dev_t} is wider than @code{int} on some machines. There
+is no type you can safely use on all machines in a non-standard
+definition. The only way to support non-standard C and pass such an
+argument is to check the width of @code{dev_t} using Autoconf and choose
+the argument type accordingly. This may not be worth the trouble.
+
+In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
+
+@example
+/* Declare the prototype for a general external function. */
+#if defined (__STDC__) || defined (WINDOWSNT)
+#define P_(proto) proto
+#else
+#define P_(proto) ()
+#endif
+@end example
+
+@node Conditional Compilation
+@section Conditional Compilation
+
+When supporting configuration options already known when building your
+program we prefer using @code{if (... )} over conditional compilation,
+as in the former case the compiler is able to perform more extensive
+checking of all possible code paths.
+
+For example, please write
+
+@smallexample
+ if (HAS_FOO)
+ ...
+ else
+ ...
+@end smallexample
+
+instead of:
+
+@smallexample
+ #ifdef HAS_FOO
+ ...
+ #else
+ ...
+ #endif
+@end smallexample
+
+A modern compiler such as GCC will generate exactly the same code in
+both cases, and we have been using similar techniques with good success
+in several projects.
+
+While this is not a silver bullet solving all portability problems,
+following this policy would have saved the GCC project alone many person
+hours if not days per year.
+
+In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in
+GCC which cannot be simply used in @code{if( ...)} statements, there is
+an easy workaround. Simply introduce another macro
+@code{HAS_REVERSIBLE_CC_MODE} as in the following example:
+
+@smallexample
+ #ifdef REVERSIBLE_CC_MODE
+ #define HAS_REVERSIBLE_CC_MODE 1
+ #else
+ #define HAS_REVERSIBLE_CC_MODE 0
+ #endif
+@end smallexample
+
+@node Program Behavior
+@chapter Program Behavior for All Programs
+
+This @value{CHAPTER} describes conventions for writing robust
+software. It also describes general standards for error messages, the
+command line interface, and how libraries should behave.
+
+@menu
+* Semantics:: Writing robust programs
+* Libraries:: Library behavior
+* Errors:: Formatting error messages
+* User Interfaces:: Standards about interfaces generally
+* Graphical Interfaces:: Standards for graphical interfaces
+* Command-Line Interfaces:: Standards for command line interfaces
+* Option Table:: Table of long options
+* Memory Usage:: When and how to care about memory needs
+* File Usage:: Which files to use, and where
+@end menu
+
+@node Semantics
+@section Writing Robust Programs
+
+@cindex arbitrary limits on data
+Avoid arbitrary limits on the length or number of @emph{any} data
+structure, including file names, lines, files, and symbols, by allocating
+all data structures dynamically. In most Unix utilities, ``long lines
+are silently truncated''. This is not acceptable in a GNU utility.
+
+@cindex @code{NUL} characters
+Utilities reading files should not drop NUL characters, or any other
+nonprinting characters @emph{including those with codes above 0177}.
+The only sensible exceptions would be utilities specifically intended
+for interface to certain types of terminals or printers
+that can't handle those characters.
+Whenever possible, try to make programs work properly with
+sequences of bytes that represent multibyte characters, using encodings
+such as UTF-8 and others.
+
+@cindex error messages
+Check every system call for an error return, unless you know you wish to
+ignore errors. Include the system error text (from @code{perror} or
+equivalent) in @emph{every} error message resulting from a failing
+system call, as well as the name of the file if any and the name of the
+utility. Just ``cannot open foo.c'' or ``stat failed'' is not
+sufficient.
+
+@cindex @code{malloc} return value
+@cindex memory allocation failure
+Check every call to @code{malloc} or @code{realloc} to see if it
+returned zero. Check @code{realloc} even if you are making the block
+smaller; in a system that rounds block sizes to a power of 2,
+@code{realloc} may get a different block if you ask for less space.
+
+In Unix, @code{realloc} can destroy the storage block if it returns
+zero. GNU @code{realloc} does not have this bug: if it fails, the
+original block is unchanged. Feel free to assume the bug is fixed. If
+you wish to run your program on Unix, and wish to avoid lossage in this
+case, you can use the GNU @code{malloc}.
+
+You must expect @code{free} to alter the contents of the block that was
+freed. Anything you want to fetch from the block, you must fetch before
+calling @code{free}.
+
+If @code{malloc} fails in a noninteractive program, make that a fatal
+error. In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop. This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+@cindex command-line arguments, decoding
+Use @code{getopt_long} to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+When static storage is to be written in during program execution, use
+explicit C code to initialize it. Reserve C initialized declarations
+for data that will not be changed.
+@c ADR: why?
+
+Try to avoid low-level interfaces to obscure Unix data structures (such
+as file directories, utmp, or the layout of kernel memory), since these
+are less likely to work compatibly. If you need to find all the files
+in a directory, use @code{readdir} or some other high-level interface.
+These are supported compatibly by GNU.
+
+@cindex signal handling
+The preferred signal handling facilities are the BSD variant of
+@code{signal}, and the @sc{posix} @code{sigaction} function; the
+alternative USG @code{signal} interface is an inferior design.
+
+Nowadays, using the @sc{posix} signal functions may be the easiest way
+to make a program portable. If you use @code{signal}, then on GNU/Linux
+systems running GNU libc version 1, you should include
+@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
+behavior. It is up to you whether to support systems where
+@code{signal} has only the USG behavior, or give up on them.
+
+@cindex impossible conditions
+In error checks that detect ``impossible'' conditions, just abort.
+There is usually no point in printing any message. These checks
+indicate the existence of bugs. Whoever wants to fix the bugs will have
+to read the source code and run a debugger. So explain the problem with
+comments in the source. The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+Do not use a count of errors as the exit status for a program.
+@emph{That does not work}, because exit status values are limited to 8
+bits (0 through 255). A single run of the program might have 256
+errors; if you try to return 256 as the exit status, the parent process
+will see 0 as the status, and it will appear that the program succeeded.
+
+@cindex temporary files
+@cindex @code{TMPDIR} environment variable
+If you make temporary files, check the @code{TMPDIR} environment
+variable; if that variable is defined, use the specified directory
+instead of @file{/tmp}.
+
+In addition, be aware that there is a possible security problem when
+creating temporary files in world-writable directories. In C, you can
+avoid this problem by creating temporary files in this manner:
+
+@example
+fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+@end example
+
+@noindent
+or by using the @code{mkstemps} function from libiberty.
+
+In bash, use @code{set -C} to avoid this problem.
+
+@node Libraries
+@section Library Behavior
+@cindex libraries
+
+Try to make library functions reentrant. If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of @code{malloc} itself.
+
+Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this
+prefix. In addition, there should only be one of these in any given
+library member. This usually means putting each one in a separate
+source file.
+
+An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+External symbols that are not documented entry points for the user
+should have names beginning with @samp{_}. The @samp{_} should be
+followed by the chosen name prefix for the library, to prevent
+collisions with other libraries. These can go in the same files with
+user entry points if you like.
+
+Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+@node Errors
+@section Formatting Error Messages
+@cindex formatting error messages
+@cindex error messages, formatting
+
+Error messages from compilers should look like this:
+
+@example
+@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+@noindent
+If you want to mention the column number, use this format:
+
+@example
+@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@end example
+
+@noindent
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line. (Both
+of these conventions are chosen for compatibility.) Calculate column
+numbers assuming that space and all ASCII printing characters have
+equal width, and assuming tab stops every 8 columns.
+
+Error messages from other noninteractive programs should look like this:
+
+@example
+@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+@noindent
+when there is an appropriate source file, or like this:
+
+@example
+@var{program}: @var{message}
+@end example
+
+@noindent
+when there is no relevant source file.
+
+If you want to mention the column number, use this format:
+
+@example
+@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@end example
+
+In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message. The place to indicate which program is running is in the
+prompt or with the screen layout. (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+The string @var{message} should not begin with a capital letter when
+it follows a program name and/or file name. Also, it should not end
+with a period.
+
+Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter. But they should not
+end with a period.
+
+@node User Interfaces
+@section Standards for Interfaces Generally
+
+@cindex program name and its behavior
+@cindex behavior, dependent on program's name
+Please don't make the behavior of a utility depend on the name used
+to invoke it. It is useful sometimes to make a link to a utility
+with a different name, and that should not change what it does.
+
+Instead, use a run time option or a compilation switch or both
+to select among the alternate behaviors.
+
+@cindex output device and program's behavior
+Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with. Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then. (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
+
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+Compatibility requires certain programs to depend on the type of output
+device. It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect. In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type. For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+
+@node Graphical Interfaces
+@section Standards for Graphical Interfaces
+@cindex graphical user interface
+
+@cindex gtk
+When you write a program that provides a graphical user interface,
+please make it work with X Windows and the GTK toolkit unless the
+functionality specifically requires some alternative (for example,
+``displaying jpeg images while in console mode'').
+
+In addition, please provide a command-line interface to control the
+functionality. (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.) This is
+so that the same jobs can be done from scripts.
+
+@cindex corba
+@cindex gnome
+Please also consider providing a CORBA interface (for use from GNOME), a
+library interface (for use from C), and perhaps a keyboard-driven
+console interface (for use by users from console mode). Once you are
+doing the work to provide the functionality and the graphical interface,
+these won't be much extra work.
+
+@node Command-Line Interfaces
+@section Standards for Command Line Interfaces
+@cindex command-line interface
+
+@findex getopt
+It is a good idea to follow the @sc{posix} guidelines for the
+command-line options of a program. The easiest way to do this is to use
+@code{getopt} to parse them. Note that the GNU version of @code{getopt}
+will normally permit options anywhere among the arguments unless the
+special argument @samp{--} is used. This is not what @sc{posix}
+specifies; it is a GNU extension.
+
+@cindex long-named options
+Please define long-named options that are equivalent to the
+single-letter Unix-style options. We hope to make GNU more user
+friendly this way. This is easy to do with the GNU function
+@code{getopt_long}.
+
+One of the advantages of long-named options is that they can be
+consistent from program to program. For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}. To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program (@pxref{Option Table}).
+
+It is usually a good idea for file names given as ordinary arguments to
+be input files only; any output files would be specified using options
+(preferably @samp{-o} or @samp{--output}). Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it. This will lead to more consistency
+among GNU utilities, and fewer idiosyncracies for users to remember.
+
+@cindex standard command-line options
+All programs should support two standard options: @samp{--version}
+and @samp{--help}.
+
+@table @code
+@cindex @samp{--version} option
+@item --version
+This option should direct the program to print information about its name,
+version, origin and legal status, all on standard output, and then exit
+successfully. Other options and arguments should be ignored once this
+is seen, and the program should not perform its normal function.
+
+@cindex canonical name of a program
+@cindex program's canonical name
+The first line is meant to be easy for a program to parse; the version
+number proper starts after the last space. In addition, it contains
+the canonical name for this program, in this format:
+
+@example
+GNU Emacs 19.30
+@end example
+
+@noindent
+The program's name should be a constant string; @emph{don't} compute it
+from @code{argv[0]}. The idea is to state the standard or canonical
+name for the program, not its file name. There are other ways to find
+out the precise file name where a command is found in @code{PATH}.
+
+If the program is a subsidiary part of a larger package, mention the
+package name in parentheses, like this:
+
+@example
+emacsserver (GNU Emacs) 19.30
+@end example
+
+@noindent
+If the package has a version number which is different from this
+program's version number, you can mention the package version number
+just before the close-parenthesis.
+
+If you @strong{need} to mention the version numbers of libraries which
+are distributed separately from the package which contains this program,
+you can do so by printing an additional line of version info for each
+library you want to mention. Use the same format for these lines as for
+the first line.
+
+Please do not mention all of the libraries that the program uses ``just
+for completeness''---that would produce a lot of unhelpful clutter.
+Please mention library version numbers only if you find in practice that
+they are very important to you in debugging.
+
+The following line, after the version number line or lines, should be a
+copyright notice. If more than one copyright notice is called for, put
+each on a separate line.
+
+Next should follow a brief statement that the program is free software,
+and that users are free to copy and change it on certain conditions. If
+the program is covered by the GNU GPL, say so here. Also mention that
+there is no warranty, to the extent permitted by law.
+
+It is ok to finish the output with a list of the major authors of the
+program, as a way of giving credit.
+
+Here's an example of output that follows these rules:
+
+@smallexample
+GNU Emacs 19.34.5
+Copyright (C) 1996 Free Software Foundation, Inc.
+GNU Emacs comes with NO WARRANTY,
+to the extent permitted by law.
+You may redistribute copies of GNU Emacs
+under the terms of the GNU General Public License.
+For more information about these matters,
+see the files named COPYING.
+@end smallexample
+
+You should adapt this to your program, of course, filling in the proper
+year, copyright holder, name of program, and the references to
+distribution terms, and changing the rest of the wording as necessary.
+
+This copyright notice only needs to mention the most recent year in
+which changes were made---there's no need to list the years for previous
+versions' changes. You don't have to mention the name of the program in
+these notices, if that is inconvenient, since it appeared in the first
+line.
+
+Translations of the above lines must preserve the validity of the
+copyright notices (@pxref{Internationalization}). If the translation's
+character set supports it, the @samp{(C)} should be replaced with the
+copyright symbol, as follows:
+
+@ifinfo
+(the official copyright symbol, which is the letter C in a circle);
+@end ifinfo
+@ifnotinfo
+@copyright{}
+@end ifnotinfo
+
+Write the word ``Copyright'' exactly like that, in English. Do not
+translate it into another language. International treaties recognize
+the English word ``Copyright''; translations into other languages do not
+have legal significance.
+
+
+@cindex @samp{--help} option
+@item --help
+This option should output brief documentation for how to invoke the
+program, on standard output, then exit successfully. Other options and
+arguments should be ignored once this is seen, and the program should
+not perform its normal function.
+
+@cindex address for bug reports
+@cindex bug reports
+Near the end of the @samp{--help} option's output there should be a line
+that says where to mail bug reports. It should have this format:
+
+@example
+Report bugs to @var{mailing-address}.
+@end example
+@end table
+
+@node Option Table
+@section Table of Long Options
+@cindex long option names
+@cindex table of long options
+
+Here is a table of long options used by GNU programs. It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with. If you use names not already in the table,
+please send @email{bug-standards@@gnu.org} a list of them, with their
+meanings, so we can update the table.
+
+@c Please leave newlines between items in this table; it's much easier
+@c to update when it isn't completely squashed together and unreadable.
+@c When there is more than one short option for a long option name, put
+@c a semicolon between the lists of the programs that use them, not a
+@c period. --friedman
+
+@table @samp
+@item after-date
+@samp{-N} in @code{tar}.
+
+@item all
+@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
+and @code{unexpand}.
+
+@item all-text
+@samp{-a} in @code{diff}.
+
+@item almost-all
+@samp{-A} in @code{ls}.
+
+@item append
+@samp{-a} in @code{etags}, @code{tee}, @code{time};
+@samp{-r} in @code{tar}.
+
+@item archive
+@samp{-a} in @code{cp}.
+
+@item archive-name
+@samp{-n} in @code{shar}.
+
+@item arglength
+@samp{-l} in @code{m4}.
+
+@item ascii
+@samp{-a} in @code{diff}.
+
+@item assign
+@samp{-v} in @code{gawk}.
+
+@item assume-new
+@samp{-W} in Make.
+
+@item assume-old
+@samp{-o} in Make.
+
+@item auto-check
+@samp{-a} in @code{recode}.
+
+@item auto-pager
+@samp{-a} in @code{wdiff}.
+
+@item auto-reference
+@samp{-A} in @code{ptx}.
+
+@item avoid-wraps
+@samp{-n} in @code{wdiff}.
+
+@item background
+For server programs, run in the background.
+
+@item backward-search
+@samp{-B} in @code{ctags}.
+
+@item basename
+@samp{-f} in @code{shar}.
+
+@item batch
+Used in GDB.
+
+@item baud
+Used in GDB.
+
+@item before
+@samp{-b} in @code{tac}.
+
+@item binary
+@samp{-b} in @code{cpio} and @code{diff}.
+
+@item bits-per-code
+@samp{-b} in @code{shar}.
+
+@item block-size
+Used in @code{cpio} and @code{tar}.
+
+@item blocks
+@samp{-b} in @code{head} and @code{tail}.
+
+@item break-file
+@samp{-b} in @code{ptx}.
+
+@item brief
+Used in various programs to make output shorter.
+
+@item bytes
+@samp{-c} in @code{head}, @code{split}, and @code{tail}.
+
+@item c@t{++}
+@samp{-C} in @code{etags}.
+
+@item catenate
+@samp{-A} in @code{tar}.
+
+@item cd
+Used in various programs to specify the directory to use.
+
+@item changes
+@samp{-c} in @code{chgrp} and @code{chown}.
+
+@item classify
+@samp{-F} in @code{ls}.
+
+@item colons
+@samp{-c} in @code{recode}.
+
+@item command
+@samp{-c} in @code{su};
+@samp{-x} in GDB.
+
+@item compare
+@samp{-d} in @code{tar}.
+
+@item compat
+Used in @code{gawk}.
+
+@item compress
+@samp{-Z} in @code{tar} and @code{shar}.
+
+@item concatenate
+@samp{-A} in @code{tar}.
+
+@item confirmation
+@samp{-w} in @code{tar}.
+
+@item context
+Used in @code{diff}.
+
+@item copyleft
+@samp{-W copyleft} in @code{gawk}.
+
+@item copyright
+@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
+@samp{-W copyright} in @code{gawk}.
+
+@item core
+Used in GDB.
+
+@item count
+@samp{-q} in @code{who}.
+
+@item count-links
+@samp{-l} in @code{du}.
+
+@item create
+Used in @code{tar} and @code{cpio}.
+
+@item cut-mark
+@samp{-c} in @code{shar}.
+
+@item cxref
+@samp{-x} in @code{ctags}.
+
+@item date
+@samp{-d} in @code{touch}.
+
+@item debug
+@samp{-d} in Make and @code{m4};
+@samp{-t} in Bison.
+
+@item define
+@samp{-D} in @code{m4}.
+
+@item defines
+@samp{-d} in Bison and @code{ctags}.
+
+@item delete
+@samp{-D} in @code{tar}.
+
+@item dereference
+@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
+@code{ls}, and @code{tar}.
+
+@item dereference-args
+@samp{-D} in @code{du}.
+
+@item device
+Specify an I/O device (special file name).
+
+@item diacritics
+@samp{-d} in @code{recode}.
+
+@item dictionary-order
+@samp{-d} in @code{look}.
+
+@item diff
+@samp{-d} in @code{tar}.
+
+@item digits
+@samp{-n} in @code{csplit}.
+
+@item directory
+Specify the directory to use, in various programs. In @code{ls}, it
+means to show directories themselves rather than their contents. In
+@code{rm} and @code{ln}, it means to not treat links to directories
+specially.
+
+@item discard-all
+@samp{-x} in @code{strip}.
+
+@item discard-locals
+@samp{-X} in @code{strip}.
+
+@item dry-run
+@samp{-n} in Make.
+
+@item ed
+@samp{-e} in @code{diff}.
+
+@item elide-empty-files
+@samp{-z} in @code{csplit}.
+
+@item end-delete
+@samp{-x} in @code{wdiff}.
+
+@item end-insert
+@samp{-z} in @code{wdiff}.
+
+@item entire-new-file
+@samp{-N} in @code{diff}.
+
+@item environment-overrides
+@samp{-e} in Make.
+
+@item eof
+@samp{-e} in @code{xargs}.
+
+@item epoch
+Used in GDB.
+
+@item error-limit
+Used in @code{makeinfo}.
+
+@item error-output
+@samp{-o} in @code{m4}.
+
+@item escape
+@samp{-b} in @code{ls}.
+
+@item exclude-from
+@samp{-X} in @code{tar}.
+
+@item exec
+Used in GDB.
+
+@item exit
+@samp{-x} in @code{xargs}.
+
+@item exit-0
+@samp{-e} in @code{unshar}.
+
+@item expand-tabs
+@samp{-t} in @code{diff}.
+
+@item expression
+@samp{-e} in @code{sed}.
+
+@item extern-only
+@samp{-g} in @code{nm}.
+
+@item extract
+@samp{-i} in @code{cpio};
+@samp{-x} in @code{tar}.
+
+@item faces
+@samp{-f} in @code{finger}.
+
+@item fast
+@samp{-f} in @code{su}.
+
+@item fatal-warnings
+@samp{-E} in @code{m4}.
+
+@item file
+@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar};
+@samp{-n} in @code{sed};
+@samp{-r} in @code{touch}.
+
+@item field-separator
+@samp{-F} in @code{gawk}.
+
+@item file-prefix
+@samp{-b} in Bison.
+
+@item file-type
+@samp{-F} in @code{ls}.
+
+@item files-from
+@samp{-T} in @code{tar}.
+
+@item fill-column
+Used in @code{makeinfo}.
+
+@item flag-truncation
+@samp{-F} in @code{ptx}.
+
+@item fixed-output-files
+@samp{-y} in Bison.
+
+@item follow
+@samp{-f} in @code{tail}.
+
+@item footnote-style
+Used in @code{makeinfo}.
+
+@item force
+@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
+
+@item force-prefix
+@samp{-F} in @code{shar}.
+
+@item foreground
+For server programs, run in the foreground;
+in other words, don't do anything special to run the server
+in the background.
+
+@item format
+Used in @code{ls}, @code{time}, and @code{ptx}.
+
+@item freeze-state
+@samp{-F} in @code{m4}.
+
+@item fullname
+Used in GDB.
+
+@item gap-size
+@samp{-g} in @code{ptx}.
+
+@item get
+@samp{-x} in @code{tar}.
+
+@item graphic
+@samp{-i} in @code{ul}.
+
+@item graphics
+@samp{-g} in @code{recode}.
+
+@item group
+@samp{-g} in @code{install}.
+
+@item gzip
+@samp{-z} in @code{tar} and @code{shar}.
+
+@item hashsize
+@samp{-H} in @code{m4}.
+
+@item header
+@samp{-h} in @code{objdump} and @code{recode}
+
+@item heading
+@samp{-H} in @code{who}.
+
+@item help
+Used to ask for brief usage information.
+
+@item here-delimiter
+@samp{-d} in @code{shar}.
+
+@item hide-control-chars
+@samp{-q} in @code{ls}.
+
+@item html
+In @code{makeinfo}, output HTML.
+
+@item idle
+@samp{-u} in @code{who}.
+
+@item ifdef
+@samp{-D} in @code{diff}.
+
+@item ignore
+@samp{-I} in @code{ls};
+@samp{-x} in @code{recode}.
+
+@item ignore-all-space
+@samp{-w} in @code{diff}.
+
+@item ignore-backups
+@samp{-B} in @code{ls}.
+
+@item ignore-blank-lines
+@samp{-B} in @code{diff}.
+
+@item ignore-case
+@samp{-f} in @code{look} and @code{ptx};
+@samp{-i} in @code{diff} and @code{wdiff}.
+
+@item ignore-errors
+@samp{-i} in Make.
+
+@item ignore-file
+@samp{-i} in @code{ptx}.
+
+@item ignore-indentation
+@samp{-I} in @code{etags}.
+
+@item ignore-init-file
+@samp{-f} in Oleo.
+
+@item ignore-interrupts
+@samp{-i} in @code{tee}.
+
+@item ignore-matching-lines
+@samp{-I} in @code{diff}.
+
+@item ignore-space-change
+@samp{-b} in @code{diff}.
+
+@item ignore-zeros
+@samp{-i} in @code{tar}.
+
+@item include
+@samp{-i} in @code{etags};
+@samp{-I} in @code{m4}.
+
+@item include-dir
+@samp{-I} in Make.
+
+@item incremental
+@samp{-G} in @code{tar}.
+
+@item info
+@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+
+@item init-file
+In some programs, specify the name of the file to read as the user's
+init file.
+
+@item initial
+@samp{-i} in @code{expand}.
+
+@item initial-tab
+@samp{-T} in @code{diff}.
+
+@item inode
+@samp{-i} in @code{ls}.
+
+@item interactive
+@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+@samp{-e} in @code{m4};
+@samp{-p} in @code{xargs};
+@samp{-w} in @code{tar}.
+
+@item intermix-type
+@samp{-p} in @code{shar}.
+
+@item iso-8601
+Used in @code{date}
+
+@item jobs
+@samp{-j} in Make.
+
+@item just-print
+@samp{-n} in Make.
+
+@item keep-going
+@samp{-k} in Make.
+
+@item keep-files
+@samp{-k} in @code{csplit}.
+
+@item kilobytes
+@samp{-k} in @code{du} and @code{ls}.
+
+@item language
+@samp{-l} in @code{etags}.
+
+@item less-mode
+@samp{-l} in @code{wdiff}.
+
+@item level-for-gzip
+@samp{-g} in @code{shar}.
+
+@item line-bytes
+@samp{-C} in @code{split}.
+
+@item lines
+Used in @code{split}, @code{head}, and @code{tail}.
+
+@item link
+@samp{-l} in @code{cpio}.
+
+@item lint
+@itemx lint-old
+Used in @code{gawk}.
+
+@item list
+@samp{-t} in @code{cpio};
+@samp{-l} in @code{recode}.
+
+@item list
+@samp{-t} in @code{tar}.
+
+@item literal
+@samp{-N} in @code{ls}.
+
+@item load-average
+@samp{-l} in Make.
+
+@item login
+Used in @code{su}.
+
+@item machine
+No listing of which programs already use this;
+someone should check to
+see if any actually do, and tell @email{gnu@@gnu.org}.
+
+@item macro-name
+@samp{-M} in @code{ptx}.
+
+@item mail
+@samp{-m} in @code{hello} and @code{uname}.
+
+@item make-directories
+@samp{-d} in @code{cpio}.
+
+@item makefile
+@samp{-f} in Make.
+
+@item mapped
+Used in GDB.
+
+@item max-args
+@samp{-n} in @code{xargs}.
+
+@item max-chars
+@samp{-n} in @code{xargs}.
+
+@item max-lines
+@samp{-l} in @code{xargs}.
+
+@item max-load
+@samp{-l} in Make.
+
+@item max-procs
+@samp{-P} in @code{xargs}.
+
+@item mesg
+@samp{-T} in @code{who}.
+
+@item message
+@samp{-T} in @code{who}.
+
+@item minimal
+@samp{-d} in @code{diff}.
+
+@item mixed-uuencode
+@samp{-M} in @code{shar}.
+
+@item mode
+@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+
+@item modification-time
+@samp{-m} in @code{tar}.
+
+@item multi-volume
+@samp{-M} in @code{tar}.
+
+@item name-prefix
+@samp{-a} in Bison.
+
+@item nesting-limit
+@samp{-L} in @code{m4}.
+
+@item net-headers
+@samp{-a} in @code{shar}.
+
+@item new-file
+@samp{-W} in Make.
+
+@item no-builtin-rules
+@samp{-r} in Make.
+
+@item no-character-count
+@samp{-w} in @code{shar}.
+
+@item no-check-existing
+@samp{-x} in @code{shar}.
+
+@item no-common
+@samp{-3} in @code{wdiff}.
+
+@item no-create
+@samp{-c} in @code{touch}.
+
+@item no-defines
+@samp{-D} in @code{etags}.
+
+@item no-deleted
+@samp{-1} in @code{wdiff}.
+
+@item no-dereference
+@samp{-d} in @code{cp}.
+
+@item no-inserted
+@samp{-2} in @code{wdiff}.
+
+@item no-keep-going
+@samp{-S} in Make.
+
+@item no-lines
+@samp{-l} in Bison.
+
+@item no-piping
+@samp{-P} in @code{shar}.
+
+@item no-prof
+@samp{-e} in @code{gprof}.
+
+@item no-regex
+@samp{-R} in @code{etags}.
+
+@item no-sort
+@samp{-p} in @code{nm}.
+
+@item no-split
+Used in @code{makeinfo}.
+
+@item no-static
+@samp{-a} in @code{gprof}.
+
+@item no-time
+@samp{-E} in @code{gprof}.
+
+@item no-timestamp
+@samp{-m} in @code{shar}.
+
+@item no-validate
+Used in @code{makeinfo}.
+
+@item no-wait
+Used in @code{emacsclient}.
+
+@item no-warn
+Used in various programs to inhibit warnings.
+
+@item node
+@samp{-n} in @code{info}.
+
+@item nodename
+@samp{-n} in @code{uname}.
+
+@item nonmatching
+@samp{-f} in @code{cpio}.
+
+@item nstuff
+@samp{-n} in @code{objdump}.
+
+@item null
+@samp{-0} in @code{xargs}.
+
+@item number
+@samp{-n} in @code{cat}.
+
+@item number-nonblank
+@samp{-b} in @code{cat}.
+
+@item numeric-sort
+@samp{-n} in @code{nm}.
+
+@item numeric-uid-gid
+@samp{-n} in @code{cpio} and @code{ls}.
+
+@item nx
+Used in GDB.
+
+@item old-archive
+@samp{-o} in @code{tar}.
+
+@item old-file
+@samp{-o} in Make.
+
+@item one-file-system
+@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
+
+@item only-file
+@samp{-o} in @code{ptx}.
+
+@item only-prof
+@samp{-f} in @code{gprof}.
+
+@item only-time
+@samp{-F} in @code{gprof}.
+
+@item options
+@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
+@code{fdmountd}, and @code{fdumount}.
+
+@item output
+In various programs, specify the output file name.
+
+@item output-prefix
+@samp{-o} in @code{shar}.
+
+@item override
+@samp{-o} in @code{rm}.
+
+@item overwrite
+@samp{-c} in @code{unshar}.
+
+@item owner
+@samp{-o} in @code{install}.
+
+@item paginate
+@samp{-l} in @code{diff}.
+
+@item paragraph-indent
+Used in @code{makeinfo}.
+
+@item parents
+@samp{-p} in @code{mkdir} and @code{rmdir}.
+
+@item pass-all
+@samp{-p} in @code{ul}.
+
+@item pass-through
+@samp{-p} in @code{cpio}.
+
+@item port
+@samp{-P} in @code{finger}.
+
+@item portability
+@samp{-c} in @code{cpio} and @code{tar}.
+
+@item posix
+Used in @code{gawk}.
+
+@item prefix-builtins
+@samp{-P} in @code{m4}.
+
+@item prefix
+@samp{-f} in @code{csplit}.
+
+@item preserve
+Used in @code{tar} and @code{cp}.
+
+@item preserve-environment
+@samp{-p} in @code{su}.
+
+@item preserve-modification-time
+@samp{-m} in @code{cpio}.
+
+@item preserve-order
+@samp{-s} in @code{tar}.
+
+@item preserve-permissions
+@samp{-p} in @code{tar}.
+
+@item print
+@samp{-l} in @code{diff}.
+
+@item print-chars
+@samp{-L} in @code{cmp}.
+
+@item print-data-base
+@samp{-p} in Make.
+
+@item print-directory
+@samp{-w} in Make.
+
+@item print-file-name
+@samp{-o} in @code{nm}.
+
+@item print-symdefs
+@samp{-s} in @code{nm}.
+
+@item printer
+@samp{-p} in @code{wdiff}.
+
+@item prompt
+@samp{-p} in @code{ed}.
+
+@item proxy
+Specify an HTTP proxy.
+
+@item query-user
+@samp{-X} in @code{shar}.
+
+@item question
+@samp{-q} in Make.
+
+@item quiet
+Used in many programs to inhibit the usual output. @strong{Note:} every
+program accepting @samp{--quiet} should accept @samp{--silent} as a
+synonym.
+
+@item quiet-unshar
+@samp{-Q} in @code{shar}
+
+@item quote-name
+@samp{-Q} in @code{ls}.
+
+@item rcs
+@samp{-n} in @code{diff}.
+
+@item re-interval
+Used in @code{gawk}.
+
+@item read-full-blocks
+@samp{-B} in @code{tar}.
+
+@item readnow
+Used in GDB.
+
+@item recon
+@samp{-n} in Make.
+
+@item record-number
+@samp{-R} in @code{tar}.
+
+@item recursive
+Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
+and @code{rm}.
+
+@item reference-limit
+Used in @code{makeinfo}.
+
+@item references
+@samp{-r} in @code{ptx}.
+
+@item regex
+@samp{-r} in @code{tac} and @code{etags}.
+
+@item release
+@samp{-r} in @code{uname}.
+
+@item reload-state
+@samp{-R} in @code{m4}.
+
+@item relocation
+@samp{-r} in @code{objdump}.
+
+@item rename
+@samp{-r} in @code{cpio}.
+
+@item replace
+@samp{-i} in @code{xargs}.
+
+@item report-identical-files
+@samp{-s} in @code{diff}.
+
+@item reset-access-time
+@samp{-a} in @code{cpio}.
+
+@item reverse
+@samp{-r} in @code{ls} and @code{nm}.
+
+@item reversed-ed
+@samp{-f} in @code{diff}.
+
+@item right-side-defs
+@samp{-R} in @code{ptx}.
+
+@item same-order
+@samp{-s} in @code{tar}.
+
+@item same-permissions
+@samp{-p} in @code{tar}.
+
+@item save
+@samp{-g} in @code{stty}.
+
+@item se
+Used in GDB.
+
+@item sentence-regexp
+@samp{-S} in @code{ptx}.
+
+@item separate-dirs
+@samp{-S} in @code{du}.
+
+@item separator
+@samp{-s} in @code{tac}.
+
+@item sequence
+Used by @code{recode} to chose files or pipes for sequencing passes.
+
+@item shell
+@samp{-s} in @code{su}.
+
+@item show-all
+@samp{-A} in @code{cat}.
+
+@item show-c-function
+@samp{-p} in @code{diff}.
+
+@item show-ends
+@samp{-E} in @code{cat}.
+
+@item show-function-line
+@samp{-F} in @code{diff}.
+
+@item show-tabs
+@samp{-T} in @code{cat}.
+
+@item silent
+Used in many programs to inhibit the usual output.
+@strong{Note:} every program accepting
+@samp{--silent} should accept @samp{--quiet} as a synonym.
+
+@item size
+@samp{-s} in @code{ls}.
+
+@item socket
+Specify a file descriptor for a network server to use for its socket,
+instead of opening and binding a new socket. This provides a way to
+run, in a nonpriveledged process, a server that normally needs a
+reserved port number.
+
+@item sort
+Used in @code{ls}.
+
+@item source
+@samp{-W source} in @code{gawk}.
+
+@item sparse
+@samp{-S} in @code{tar}.
+
+@item speed-large-files
+@samp{-H} in @code{diff}.
+
+@item split-at
+@samp{-E} in @code{unshar}.
+
+@item split-size-limit
+@samp{-L} in @code{shar}.
+
+@item squeeze-blank
+@samp{-s} in @code{cat}.
+
+@item start-delete
+@samp{-w} in @code{wdiff}.
+
+@item start-insert
+@samp{-y} in @code{wdiff}.
+
+@item starting-file
+Used in @code{tar} and @code{diff} to specify which file within
+a directory to start processing with.
+
+@item statistics
+@samp{-s} in @code{wdiff}.
+
+@item stdin-file-list
+@samp{-S} in @code{shar}.
+
+@item stop
+@samp{-S} in Make.
+
+@item strict
+@samp{-s} in @code{recode}.
+
+@item strip
+@samp{-s} in @code{install}.
+
+@item strip-all
+@samp{-s} in @code{strip}.
+
+@item strip-debug
+@samp{-S} in @code{strip}.
+
+@item submitter
+@samp{-s} in @code{shar}.
+
+@item suffix
+@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
+
+@item suffix-format
+@samp{-b} in @code{csplit}.
+
+@item sum
+@samp{-s} in @code{gprof}.
+
+@item summarize
+@samp{-s} in @code{du}.
+
+@item symbolic
+@samp{-s} in @code{ln}.
+
+@item symbols
+Used in GDB and @code{objdump}.
+
+@item synclines
+@samp{-s} in @code{m4}.
+
+@item sysname
+@samp{-s} in @code{uname}.
+
+@item tabs
+@samp{-t} in @code{expand} and @code{unexpand}.
+
+@item tabsize
+@samp{-T} in @code{ls}.
+
+@item terminal
+@samp{-T} in @code{tput} and @code{ul}.
+@samp{-t} in @code{wdiff}.
+
+@item text
+@samp{-a} in @code{diff}.
+
+@item text-files
+@samp{-T} in @code{shar}.
+
+@item time
+Used in @code{ls} and @code{touch}.
+
+@item timeout
+Specify how long to wait before giving up on some operation.
+
+@item to-stdout
+@samp{-O} in @code{tar}.
+
+@item total
+@samp{-c} in @code{du}.
+
+@item touch
+@samp{-t} in Make, @code{ranlib}, and @code{recode}.
+
+@item trace
+@samp{-t} in @code{m4}.
+
+@item traditional
+@samp{-t} in @code{hello};
+@samp{-W traditional} in @code{gawk};
+@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
+
+@item tty
+Used in GDB.
+
+@item typedefs
+@samp{-t} in @code{ctags}.
+
+@item typedefs-and-c++
+@samp{-T} in @code{ctags}.
+
+@item typeset-mode
+@samp{-t} in @code{ptx}.
+
+@item uncompress
+@samp{-z} in @code{tar}.
+
+@item unconditional
+@samp{-u} in @code{cpio}.
+
+@item undefine
+@samp{-U} in @code{m4}.
+
+@item undefined-only
+@samp{-u} in @code{nm}.
+
+@item update
+@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
+
+@item usage
+Used in @code{gawk}; same as @samp{--help}.
+
+@item uuencode
+@samp{-B} in @code{shar}.
+
+@item vanilla-operation
+@samp{-V} in @code{shar}.
+
+@item verbose
+Print more information about progress. Many programs support this.
+
+@item verify
+@samp{-W} in @code{tar}.
+
+@item version
+Print the version number.
+
+@item version-control
+@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
+
+@item vgrind
+@samp{-v} in @code{ctags}.
+
+@item volume
+@samp{-V} in @code{tar}.
+
+@item what-if
+@samp{-W} in Make.
+
+@item whole-size-limit
+@samp{-l} in @code{shar}.
+
+@item width
+@samp{-w} in @code{ls} and @code{ptx}.
+
+@item word-regexp
+@samp{-W} in @code{ptx}.
+
+@item writable
+@samp{-T} in @code{who}.
+
+@item zeros
+@samp{-z} in @code{gprof}.
+@end table
+
+@node Memory Usage
+@section Memory Usage
+@cindex memory usage
+
+If a program typically uses just a few meg of memory, don't bother making any
+effort to reduce memory usage. For example, if it is impractical for
+other reasons to operate on files more than a few meg long, it is
+reasonable to read entire input files into core to operate on them.
+
+However, for programs such as @code{cat} or @code{tail}, that can
+usefully operate on very large files, it is important to avoid using a
+technique that would artificially limit the size of files it can handle.
+If a program works by lines and could be applied to arbitrary
+user-supplied input files, it should keep only a line in memory, because
+this is not very hard and users will want to be able to operate on input
+files that are bigger than will fit in core all at once.
+
+If your program creates complicated data structures, just make them in
+core and give a fatal error if @code{malloc} returns zero.
+
+@node File Usage
+@section File Usage
+@cindex file usage
+
+Programs should be prepared to operate when @file{/usr} and @file{/etc}
+are read-only file systems. Thus, if the program manages log files,
+lock files, backup files, score files, or any other files which are
+modified for internal purposes, these files should not be stored in
+@file{/usr} or @file{/etc}.
+
+There are two exceptions. @file{/etc} is used to store system
+configuration information; it is reasonable for a program to modify
+files in @file{/etc} when its job is to update the system configuration.
+Also, if the user explicitly asks to modify one file in a directory, it
+is reasonable for the program to store other files in the same
+directory.
+
+@node Writing C
+@chapter Making The Best Use of C
+
+This @value{CHAPTER} provides advice on how best to use the C language
+when writing GNU software.
+
+@menu
+* Formatting:: Formatting Your Source Code
+* Comments:: Commenting Your Work
+* Syntactic Conventions:: Clean Use of C Constructs
+* Names:: Naming Variables, Functions, and Files
+* System Portability:: Portability between different operating systems
+* CPU Portability:: Supporting the range of CPU types
+* System Functions:: Portability and ``standard'' library functions
+* Internationalization:: Techniques for internationalization
+* Mmap:: How you can safely use @code{mmap}.
+@end menu
+
+@node Formatting
+@section Formatting Your Source Code
+@cindex formatting source code
+
+@cindex open brace
+@cindex braces, in C source
+It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero. Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+
+It is also important for function definitions to start the name of the
+function in column zero. This helps people to search for function
+definitions, and may also help certain tools recognize them. Thus,
+the proper format is this:
+
+@example
+static char *
+concat (s1, s2) /* Name starts in column zero here */
+ char *s1, *s2;
+@{ /* Open brace in column zero here */
+ @dots{}
+@}
+@end example
+
+@noindent
+or, if you want to use Standard C syntax, format the definition like
+this:
+
+@example
+static char *
+concat (char *s1, char *s2)
+@{
+ @dots{}
+@}
+@end example
+
+In Standard C, if the arguments don't fit nicely on one line,
+split it like this:
+
+@example
+int
+lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+@dots{}
+@end example
+
+The rest of this section gives our recommendations for other aspects of
+C formatting style, which is also the default style of the @code{indent}
+program in version 1.2 and newer. It corresponds to the options
+
+@smallexample
+-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+@end smallexample
+
+We don't think of these recommendations as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+But whatever style you use, please use it consistently, since a mixture
+of styles within one program tends to look ugly. If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+For the body of the function, our recommended style looks like this:
+
+@example
+if (x < foo (y, z))
+ haha = bar[4] + 5;
+else
+ @{
+ while (z)
+ @{
+ haha += foo (z, z);
+ z--;
+ @}
+ return ++x + bar ();
+ @}
+@end example
+
+@cindex spaces before open-paren
+We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas. Especially after the commas.
+
+When you split an expression into multiple lines, split it
+before an operator, not after one. Here is the right way:
+
+@cindex expressions, splitting
+@example
+if (foo_this_is_long && bar > win (x, y, z)
+ && remaining_condition)
+@end example
+
+Try to avoid having two operators of different precedence at the same
+level of indentation. For example, don't write this:
+
+@example
+mode = (inmode[j] == VOIDmode
+ || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+ ? outmode[j] : inmode[j]);
+@end example
+
+Instead, use extra parentheses so that the indentation shows the nesting:
+
+@example
+mode = ((inmode[j] == VOIDmode
+ || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+ ? outmode[j] : inmode[j]);
+@end example
+
+Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+@example
+v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+@end example
+
+@noindent
+but Emacs would alter it. Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+@example
+v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+@end example
+
+Format do-while statements like this:
+
+@example
+do
+ @{
+ a = foo (a);
+ @}
+while (a > 0);
+@end example
+
+@cindex formfeed
+@cindex control-L
+Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function). It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page. The formfeeds should appear alone on lines by themselves.
+
+@node Comments
+@section Commenting Your Work
+@cindex commenting
+
+Every program should start with a comment saying briefly what it is for.
+Example: @samp{fmt - filter for simple filling of text}.
+
+Please write the comments in a GNU program in English, because English
+is the one language that nearly all programmers in all countries can
+read. If you do not write English well, please write comments in
+English as well as you can, then ask other people to help rewrite them.
+If you can't write comments in English, please find someone to work with
+you and translate your comments into English.
+
+Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for. It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion. If there is anything nonstandard about
+its use (such as an argument of type @code{char *} which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+Also explain the significance of the return value, if there is one.
+
+Please put two spaces after the end of a sentence in your comments, so
+that the Emacs sentence commands will work. Also, please write
+complete sentences and capitalize the first word. If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier. If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., ``The identifier lower-case is @dots{}'').
+
+The comment on a function is much clearer if you use the argument
+names to speak about the argument values. The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself. Thus, ``the inode
+number NODE_NUM'' rather than ``an inode''.
+
+There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the function
+itself would be off the bottom of the screen.
+
+There should be a comment on each static variable as well, like this:
+
+@example
+/* Nonzero means truncate lines in the display;
+ zero means continue them. */
+int truncate_lines;
+@end example
+
+@cindex conditionals, comments for
+@cindex @code{#endif}, commenting
+Every @samp{#endif} should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested. The comment should
+state the condition of the conditional that is ending, @emph{including
+its sense}. @samp{#else} should have a comment describing the condition
+@emph{and sense} of the code that follows. For example:
+
+@example
+@group
+#ifdef foo
+ @dots{}
+#else /* not foo */
+ @dots{}
+#endif /* not foo */
+@end group
+@group
+#ifdef foo
+ @dots{}
+#endif /* foo */
+@end group
+@end example
+
+@noindent
+but, by contrast, write the comments this way for a @samp{#ifndef}:
+
+@example
+@group
+#ifndef foo
+ @dots{}
+#else /* foo */
+ @dots{}
+#endif /* foo */
+@end group
+@group
+#ifndef foo
+ @dots{}
+#endif /* not foo */
+@end group
+@end example
+
+@node Syntactic Conventions
+@section Clean Use of C Constructs
+@cindex syntactic conventions
+
+@cindex implicit @code{int}
+@cindex function argument, declaring
+Please explicitly declare the types of all objects. For example, you
+should explicitly declare all arguments to functions, and you should
+declare functions to return @code{int} rather than omitting the
+@code{int}.
+
+@cindex compiler warnings
+@cindex @samp{-Wall} compiler option
+Some programmers like to use the GCC @samp{-Wall} option, and change the
+code whenever it issues a warning. If you want to do this, then do.
+Other programmers prefer not to use @samp{-Wall}, because it gives
+warnings for valid and legitimate code which they do not want to change.
+If you want to do this, then do. The compiler should be your servant,
+not your master.
+
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file. Don't put @code{extern} declarations inside
+functions.
+
+@cindex temporary variables
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function. Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+Don't use local variables or parameters that shadow global identifiers.
+
+@cindex multiple variables in a line
+Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead. For example, instead
+of this:
+
+@example
+@group
+int foo,
+ bar;
+@end group
+@end example
+
+@noindent
+write either this:
+
+@example
+int foo, bar;
+@end example
+
+@noindent
+or this:
+
+@example
+int foo;
+int bar;
+@end example
+
+@noindent
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+When you have an @code{if}-@code{else} statement nested in another
+@code{if} statement, always put braces around the @code{if}-@code{else}.
+Thus, never write like this:
+
+@example
+if (foo)
+ if (bar)
+ win ();
+ else
+ lose ();
+@end example
+
+@noindent
+always like this:
+
+@example
+if (foo)
+ @{
+ if (bar)
+ win ();
+ else
+ lose ();
+ @}
+@end example
+
+If you have an @code{if} statement nested inside of an @code{else}
+statement, either write @code{else if} on one line, like this,
+
+@example
+if (foo)
+ @dots{}
+else if (bar)
+ @dots{}
+@end example
+
+@noindent
+with its @code{then}-part indented like the preceding @code{then}-part,
+or write the nested @code{if} within braces like this:
+
+@example
+if (foo)
+ @dots{}
+else
+ @{
+ if (bar)
+ @dots{}
+ @}
+@end example
+
+Don't declare both a structure tag and variables or typedefs in the
+same declaration. Instead, declare the structure tag separately
+and then use it to declare the variables or typedefs.
+
+Try to avoid assignments inside @code{if}-conditions. For example,
+don't write this:
+
+@example
+if ((foo = (char *) malloc (sizeof *foo)) == 0)
+ fatal ("virtual memory exhausted");
+@end example
+
+@noindent
+instead, write this:
+
+@example
+foo = (char *) malloc (sizeof *foo);
+if (foo == 0)
+ fatal ("virtual memory exhausted");
+@end example
+
+@pindex lint
+Don't make the program ugly to placate @code{lint}. Please don't insert any
+casts to @code{void}. Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+@node Names
+@section Naming Variables, Functions, and Files
+
+@cindex names of variables, functions, and files
+The names of global variables and functions in a program serve as
+comments of a sort. So don't choose terse names---instead, look for
+names that give useful information about the meaning of the variable or
+function. In a GNU program, names should be English, like other
+comments.
+
+Local variable names can be shorter, because they are used only within
+one context, where (presumably) comments explain their purpose.
+
+Try to limit your use of abbreviations in symbol names. It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
+Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them. Stick to lower case; reserve
+upper case for macros and @code{enum} constants, and for name-prefixes
+that follow a uniform convention.
+
+For example, you should use names like @code{ignore_space_change_flag};
+don't use names like @code{iCantReadThis}.
+
+Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter. A comment should state both the exact meaning of
+the option and its letter. For example,
+
+@example
+@group
+/* Ignore changes in horizontal whitespace (-b). */
+int ignore_space_change_flag;
+@end group
+@end example
+
+When you want to define names with constant integer values, use
+@code{enum} rather than @samp{#define}. GDB knows about enumeration
+constants.
+
+@cindex file-name limitations
+@pindex doschk
+You might want to make sure that none of the file names would conflict
+the files were loaded onto an MS-DOS file system which shortens the
+names. You can use the program @code{doschk} to test for this.
+
+Some GNU programs were designed to limit themselves to file names of 14
+characters or less, to avoid file name conflicts if they are read into
+older System V systems. Please preserve this feature in the existing
+GNU programs that have it, but there is no need to do this in new GNU
+programs. @code{doschk} also reports file names longer than 14
+characters.
+
+@node System Portability
+@section Portability between System Types
+@cindex portability, between system types
+
+In the Unix world, ``portability'' refers to porting to different Unix
+versions. For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+The primary purpose of GNU software is to run on top of the GNU kernel,
+compiled with the GNU C compiler, on various types of @sc{cpu}. So the
+kinds of portability that are absolutely necessary are quite limited.
+But it is important to support Linux-based GNU systems, since they
+are the form of GNU that is popular.
+
+Beyond that, it is good to support the other free operating systems
+(*BSD), and it is nice to support other Unix-like systems if you want
+to. Supporting a variety of Unix-like systems is desirable, although
+not paramount. It is usually not too hard, so you may as well do it.
+But you don't have to consider it an obligation, if it does turn out to
+be hard.
+
+@pindex autoconf
+The easiest way to achieve portability to most Unix-like systems is to
+use Autoconf. It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+Avoid using the format of semi-internal data bases (e.g., directories)
+when there is a higher-level alternative (@code{readdir}).
+
+@cindex non-@sc{posix} systems, and portability
+As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is often a lot of work. When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+
+It is a good idea to define the ``feature test macro''
+@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU
+or GNU/Linux, this will enable the declarations of GNU library extension
+functions, and that will usually give you a compiler error message if
+you define the same function names in some other way in your program.
+(You don't have to actually @emph{use} these functions, if you prefer
+to make the program more portable to other systems.)
+
+But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings. Doing so would make it hard
+to move your code into other GNU programs.
+
+@node CPU Portability
+@section Portability between @sc{cpu}s
+
+@cindex data types, and portability
+@cindex portability, and data types
+Even GNU systems will differ because of differences among @sc{cpu}
+types---for example, difference in byte ordering and alignment
+requirements. It is absolutely essential to handle these differences.
+However, don't make any effort to cater to the possibility that an
+@code{int} will be less than 32 bits. We don't support 16-bit machines
+in GNU.
+
+Similarly, don't make any effort to cater to the possibility that
+@code{long} will be smaller than predefined types like @code{size_t}.
+For example, the following code is ok:
+
+@example
+printf ("size = %lu\n", (unsigned long) sizeof array);
+printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+@end example
+
+1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows IA-64. We will
+leave it to those who want to port GNU programs to that environment
+to figure out how to do it.
+
+Predefined file-size types like @code{off_t} are an exception: they are
+longer than @code{long} on many platforms, so code like the above won't
+work with them. One way to print an @code{off_t} value portably is to
+print its digits yourself, one by one.
+
+Don't assume that the address of an @code{int} object is also the
+address of its least-significant byte. This is false on big-endian
+machines. Thus, don't make the following mistake:
+
+@example
+int c;
+@dots{}
+while ((c = getchar()) != EOF)
+ write(file_descriptor, &c, 1);
+@end example
+
+When calling functions, you need not worry about the difference between
+pointers of various types, or between pointers and integers. On most
+machines, there's no difference anyway. As for the few machines where
+there is a difference, all of them support Standard C prototypes, so you can
+use prototypes (perhaps conditionalized to be active only in Standard C)
+to make the code work on those systems.
+
+In certain cases, it is ok to pass integer and pointer arguments
+indiscriminately to the same function, and use no prototype on any
+system. For example, many GNU programs have error-reporting functions
+that pass their arguments along to @code{printf} and friends:
+
+@example
+error (s, a1, a2, a3)
+ char *s;
+ char *a1, *a2, *a3;
+@{
+ fprintf (stderr, "error: ");
+ fprintf (stderr, s, a1, a2, a3);
+@}
+@end example
+
+@noindent
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument; it is much simpler than any
+``correct'' alternative. Be sure @emph{not} to use a prototype for such
+functions.
+
+If you have decided to use Standard C, then you can instead define
+@code{error} using @file{stdarg.h}, and pass the arguments along to
+@code{vfprintf}.
+
+@cindex casting pointers to integers
+Avoid casting pointers to integers if you can. Such casts greatly
+reduce portability, and in most programs they are easy to avoid. In the
+cases where casting pointers to integers is essential---such as, a Lisp
+interpreter which stores type information as well as an address in one
+word---you'll have to make explicit provisions to handle different word
+sizes. You will also need to make provision for systems in which the
+normal range of addresses you can get from @code{malloc} starts far away
+from zero.
+
+@node System Functions
+@section Calling System Functions
+@cindex library functions, and portability
+@cindex portability, and library functions
+
+C implementations differ substantially. Standard C reduces but does
+not eliminate the incompatibilities; meanwhile, many GNU packages still
+support pre-standard compilers because this is not hard to do. This
+chapter gives recommendations for how to use the more-or-less standard C
+library functions to avoid unnecessary loss of portability.
+
+@itemize @bullet
+@item
+Don't use the return value of @code{sprintf}. It returns the number of
+characters written on some systems, but not on all systems.
+
+@item
+Be aware that @code{vfprintf} is not always available.
+
+@item
+@code{main} should be declared to return type @code{int}. It should
+terminate either by calling @code{exit} or by returning the integer
+status code; make sure it cannot ever return an undefined value.
+
+@cindex declaration for system functions
+@item
+Don't declare system functions explicitly.
+
+Almost any declaration for a system function is wrong on some system.
+To minimize conflicts, leave it to the system header files to declare
+system functions. If the headers don't declare a function, let it
+remain undeclared.
+
+While it may seem unclean to use a function without declaring it, in
+practice this works fine for most system library functions on the
+systems where this really happens; thus, the disadvantage is only
+theoretical. By contrast, actual declarations have frequently caused
+actual conflicts.
+
+@item
+If you must declare a system function, don't specify the argument types.
+Use an old-style declaration, not a Standard C prototype. The more you
+specify about the function, the more likely a conflict.
+
+@item
+In particular, don't unconditionally declare @code{malloc} or
+@code{realloc}.
+
+Most GNU programs use those functions just once, in functions
+conventionally named @code{xmalloc} and @code{xrealloc}. These
+functions call @code{malloc} and @code{realloc}, respectively, and
+check the results.
+
+Because @code{xmalloc} and @code{xrealloc} are defined in your program,
+you can declare them in other files without any risk of type conflict.
+
+On most systems, @code{int} is the same length as a pointer; thus, the
+calls to @code{malloc} and @code{realloc} work fine. For the few
+exceptional systems (mostly 64-bit machines), you can use
+@strong{conditionalized} declarations of @code{malloc} and
+@code{realloc}---or put these declarations in configuration files
+specific to those systems.
+
+@cindex string library functions
+@item
+The string functions require special treatment. Some Unix systems have
+a header file @file{string.h}; others have @file{strings.h}. Neither
+file name is portable. There are two things you can do: use Autoconf to
+figure out which file to include, or don't include either file.
+
+@item
+If you don't include either strings file, you can't get declarations for
+the string functions from the header file in the usual way.
+
+That causes less of a problem than you might think. The newer standard
+string functions should be avoided anyway because many systems still
+don't support them. The string functions you can use are these:
+
+@example
+strcpy strncpy strcat strncat
+strlen strcmp strncmp
+strchr strrchr
+@end example
+
+The copy and concatenate functions work fine without a declaration as
+long as you don't use their values. Using their values without a
+declaration fails on systems where the width of a pointer differs from
+the width of @code{int}, and perhaps in other cases. It is trivial to
+avoid using their values, so do that.
+
+The compare functions and @code{strlen} work fine without a declaration
+on most systems, possibly all the ones that GNU software runs on.
+You may find it necessary to declare them @strong{conditionally} on a
+few systems.
+
+The search functions must be declared to return @code{char *}. Luckily,
+there is no variation in the data type they return. But there is
+variation in their names. Some systems give these functions the names
+@code{index} and @code{rindex}; other systems use the names
+@code{strchr} and @code{strrchr}. Some systems support both pairs of
+names, but neither pair works on all systems.
+
+You should pick a single pair of names and use it throughout your
+program. (Nowadays, it is better to choose @code{strchr} and
+@code{strrchr} for new programs, since those are the standard
+names.) Declare both of those names as functions returning @code{char
+*}. On systems which don't support those names, define them as macros
+in terms of the other pair. For example, here is what to put at the
+beginning of your file (or in a header) if you want to use the names
+@code{strchr} and @code{strrchr} throughout:
+
+@example
+#ifndef HAVE_STRCHR
+#define strchr index
+#endif
+#ifndef HAVE_STRRCHR
+#define strrchr rindex
+#endif
+
+char *strchr ();
+char *strrchr ();
+@end example
+@end itemize
+
+Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
+macros defined in systems where the corresponding functions exist.
+One way to get them properly defined is to use Autoconf.
+
+@node Internationalization
+@section Internationalization
+@cindex internationalization
+
+@pindex gettext
+GNU has a library called GNU gettext that makes it easy to translate the
+messages in a program into various languages. You should use this
+library in every program. Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+
+Using GNU gettext involves putting a call to the @code{gettext} macro
+around each string that might need translation---like this:
+
+@example
+printf (gettext ("Processing file `%s'..."));
+@end example
+
+@noindent
+This permits GNU gettext to replace the string @code{"Processing file
+`%s'..."} with a translated version.
+
+Once a program uses gettext, please make a point of writing calls to
+@code{gettext} when you add new strings that call for translation.
+
+Using GNU gettext in a package involves specifying a @dfn{text domain
+name} for the package. The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package---for example, @samp{fileutils} for the GNU file utilities.
+
+@cindex message text, and internationalization
+To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences. When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
+
+Here is an example of what not to do:
+
+@example
+printf ("%d file%s processed", nfiles,
+ nfiles != 1 ? "s" : "");
+@end example
+
+@noindent
+The problem with that example is that it assumes that plurals are made
+by adding `s'. If you apply gettext to the format string, like this,
+
+@example
+printf (gettext ("%d file%s processed"), nfiles,
+ nfiles != 1 ? "s" : "");
+@end example
+
+@noindent
+the message can use different words, but it will still be forced to use
+`s' for the plural. Here is a better way:
+
+@example
+printf ((nfiles != 1 ? "%d files processed"
+ : "%d file processed"),
+ nfiles);
+@end example
+
+@noindent
+This way, you can apply gettext to each of the two strings
+independently:
+
+@example
+printf ((nfiles != 1 ? gettext ("%d files processed")
+ : gettext ("%d file processed")),
+ nfiles);
+@end example
+
+@noindent
+This can be any method of forming the plural of the word for ``file'', and
+also handles languages that require agreement in the word for
+``processed''.
+
+A similar problem appears at the level of sentence structure with this
+code:
+
+@example
+printf ("# Implicit rule search has%s been done.\n",
+ f->tried_implicit ? "" : " not");
+@end example
+
+@noindent
+Adding @code{gettext} calls to this code cannot give correct results for
+all languages, because negation in some languages requires adding words
+at more than one place in the sentence. By contrast, adding
+@code{gettext} calls does the job straightfowardly if the code starts
+out like this:
+
+@example
+printf (f->tried_implicit
+ ? "# Implicit rule search has been done.\n",
+ : "# Implicit rule search has not been done.\n");
+@end example
+
+@node Mmap
+@section Mmap
+@findex mmap
+
+Don't assume that @code{mmap} either works on all files or fails
+for all files. It may work on some files and fail on others.
+
+The proper way to use @code{mmap} is to try it on the specific file for
+which you want to use it---and if @code{mmap} doesn't work, fall back on
+doing the job in another way using @code{read} and @code{write}.
+
+The reason this precaution is needed is that the GNU kernel (the HURD)
+provides a user-extensible file system, in which there can be many
+different kinds of ``ordinary files.'' Many of them support
+@code{mmap}, but some do not. It is important to make programs handle
+all these kinds of files.
+
+@node Documentation
+@chapter Documenting Programs
+@cindex documentation
+
+A GNU program should ideally come with full free documentation, adequate
+for both reference and tutorial purposes. If the package can be
+programmed or extended, the documentation should cover programming or
+extending it, as well as just using it.
+
+@menu
+* GNU Manuals:: Writing proper manuals.
+* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
+* Manual Structure Details:: Specific structure conventions.
+* License for Manuals:: Writing the distribution terms for a manual.
+* Manual Credits:: Giving credit to documentation contributors.
+* Printed Manuals:: Mentioning the printed manual.
+* NEWS File:: NEWS files supplement manuals.
+* Change Logs:: Recording Changes
+* Man Pages:: Man pages are secondary.
+* Reading other Manuals:: How far you can go in learning
+ from other manuals.
+@end menu
+
+@node GNU Manuals
+@section GNU Manuals
+
+The preferred document format for the GNU system is the Texinfo
+formatting language. Every GNU package should (ideally) have
+documentation in Texinfo both for reference and for learners. Texinfo
+makes it possible to produce a good quality formatted book, using
+@TeX{}, and to generate an Info file. It is also possible to generate
+HTML output from Texinfo source. See the Texinfo manual, either the
+hardcopy, or the on-line version available through @code{info} or the
+Emacs Info subsystem (@kbd{C-h i}).
+
+Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo. It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
+
+Programmers often find it most natural to structure the documentation
+following the structure of the implementation, which they know. But
+this structure is not necessarily good for explaining how to use the
+program; it may be irrelevant and confusing for a user.
+
+At every level, from the sentences in a paragraph to the grouping of
+topics into separate manuals, the right way to structure documentation
+is according to the concepts and questions that a user will have in mind
+when reading it. Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented---but
+often they are different. Often the most important part of learning to
+write good documentation is learning to notice when you are structuring
+the documentation like the implementation, and think about better
+alternatives.
+
+For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual. That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+Instead, each manual should cover a coherent @emph{topic}. For example,
+instead of a manual for @code{diff} and a manual for @code{diff3}, we
+have one manual for ``comparison of files'' which covers both of those
+programs, as well as @code{cmp}. By documenting these programs
+together, we can make the whole subject clearer.
+
+The manual which discusses a program should certainly document all of
+the program's command-line options and all of its commands. It should
+give examples of their use. But don't organize the manual as a list of
+features. Instead, organize it logically, by subtopics. Address the
+questions that a user will ask when thinking about the job that the
+program does.
+
+In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside). A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want.
+The Bison manual is a good example of this---please take a look at it
+to see what we mean.
+
+That is not as hard as it first sounds. Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense. Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs. The watchword is, @emph{at each point, address
+the most fundamental and important issue raised by the preceding text.}
+
+If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject. These provide
+the framework for a beginner to understand the rest of the manual. The
+Bison manual provides a good example of how to do this.
+
+To serve as a reference, a manual should have an Index that list all the
+functions, variables, options, and important concepts that are part of
+the program. One combined Index should do for a short manual, but
+sometimes for a complex package it is better to use multiple indices.
+The Texinfo manual includes advice on preparing good index entries, see
+@ref{Index Entries, , Making Index Entries, texinfo, The GNU Texinfo
+Manual}, and see @ref{Indexing Commands, , Defining the Entries of an
+Index, texinfo, The GNU Texinfo manual}.
+
+Don't use Unix man pages as a model for how to write GNU documentation;
+most of them are terse, badly structured, and give inadequate
+explanation of the underlying concepts. (There are, of course, some
+exceptions.) Also, Unix man pages use a particular format which is
+different from what we use in GNU manuals.
+
+Please include an email address in the manual for where to report
+bugs @emph{in the manual}.
+
+Please do not use the term ``pathname'' that is used in Unix
+documentation; use ``file name'' (two words) instead. We use the term
+``path'' only for search paths, which are lists of directory names.
+
+Please do not use the term ``illegal'' to refer to erroneous input to a
+computer program. Please use ``invalid'' for this, and reserve the term
+``illegal'' for activities punishable by law.
+
+@node Doc Strings and Manuals
+@section Doc Strings and Manuals
+
+Some programming systems, such as Emacs, provide a documentation string
+for each function, command or variable. You may be tempted to write a
+reference manual by compiling the documentation strings and writing a
+little additional text to go around them---but you must not do it. That
+approach is a fundamental mistake. The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+A documentation string needs to stand alone---when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection. Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables. The previous descriptions of functions and variables in the
+section will also have given information about the topic. A description
+written to stand alone would repeat some of that information; this
+redundance looks bad. Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+The only good way to use documentation strings in writing a good manual
+is to use them as a source of information for writing good text.
+
+@node Manual Structure Details
+@section Manual Structure Details
+@cindex manual structure
+
+The title page of the manual should state the version of the programs or
+packages documented in the manual. The Top node of the manual should
+also contain this information. If the manual is changing more
+frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+
+Each program documented in the manual should have a node named
+@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This
+node (together with its subnodes, if any) should describe the program's
+command line arguments and how to run it (the sort of information people
+would look in a man page for). Start with an @samp{@@example}
+containing a template for all the options and arguments that the program
+uses.
+
+Alternatively, put a menu item in some menu whose item name fits one of
+the above patterns. This identifies the node which that item points to
+as the node for this purpose, regardless of the node's actual name.
+
+The @samp{--usage} feature of the Info reader looks for such a node
+or menu item in order to find the relevant text, so it is essential
+for every Texinfo file to have one.
+
+If one manual describes several programs, it should have such a node for
+each program described in the manual.
+
+@node License for Manuals
+@section License for Manuals
+@cindex license for manuals
+
+Please use the GNU Free Documentation License for all GNU manuals that
+are more than a few pages long. Likewise for a collection of short
+documents---you only need one copy of the GNU FDL for the whole
+collection. For a single short document, you can use a very permissive
+non-copyleft license, to avoid taking up space with a long license.
+
+See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation
+of how to employ the GFDL.
+
+Note that it is not obligatory to include a copy of the GNU GPL or GNU
+LGPL in a manual whose license is neither the GPL nor the LGPL. It can
+be a good idea to include the program's license in a large manual; in a
+short manual, whose size would be increased considerably by including
+the program's license, it is probably better not to include it.
+
+@node Manual Credits
+@section Manual Credits
+@cindex credits for manuals
+
+Please credit the principal human writers of the manual as the authors,
+on the title page of the manual. If a company sponsored the work, thank
+the company in a suitable place in the manual, but do not cite the
+company as an author.
+
+@node Printed Manuals
+@section Printed Manuals
+
+The FSF publishes some GNU manuals in printed form. To encourage sales
+of these manuals, the on-line versions of the manual should mention at
+the very start that the printed manual is available and should point at
+information for getting it---for instance, with a link to the page
+@url{http://www.gnu.org/order/order.html}. This should not be included
+in the printed manual, though, because there it is redundant.
+
+It is also useful to explain in the on-line forms of the manual how the
+user can print out the manual from the sources.
+
+@node NEWS File
+@section The NEWS File
+@cindex @file{NEWS} file
+
+In addition to its manual, the package should have a file named
+@file{NEWS} which contains a list of user-visible changes worth
+mentioning. In each new release, add items to the front of the file and
+identify the version they pertain to. Don't discard old items; leave
+them in the file after the newer items. This way, a user upgrading from
+any previous version can see what is new.
+
+If the @file{NEWS} file gets very long, move some of the older items
+into a file named @file{ONEWS} and put a note at the end referring the
+user to that file.
+
+@node Change Logs
+@section Change Logs
+@cindex change logs
+
+Keep a change log to describe all the changes made to program source
+files. The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+
+@menu
+* Change Log Concepts::
+* Style of Change Logs::
+* Simple Changes::
+* Conditional Changes::
+* Indicating the Part Changed::
+@end menu
+
+@node Change Log Concepts
+@subsection Change Log Concepts
+
+You can think of the change log as a conceptual ``undo list'' which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log
+to tell them what is in it. What they want from a change log is a
+clear explanation of how the earlier version differed.
+
+The change log file is normally called @file{ChangeLog} and covers an
+entire directory. Each directory can have its own change log, or a
+directory can use the change log of its parent directory--it's up to
+you.
+
+Another alternative is to record change log information with a version
+control system such as RCS or CVS. This can be converted automatically
+to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
+@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
+
+There's no need to describe the full purpose of the changes or how they
+work together. If you think that a change calls for explanation, you're
+probably right. Please do explain it---but please put the explanation
+in comments in the code, where people will see it whenever they see the
+code. For example, ``New function'' is enough for the change log when
+you add a function, because there should be a comment before the
+function definition to explain what it does.
+
+However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
+
+The easiest way to add an entry to @file{ChangeLog} is with the Emacs
+command @kbd{M-x add-change-log-entry}. An entry should have an
+asterisk, the name of the changed file, and then in parentheses the name
+of the changed functions, variables or whatever, followed by a colon.
+Then describe the changes you made to that function or variable.
+
+@node Style of Change Logs
+@subsection Style of Change Logs
+@cindex change logs, style
+
+Here are some simple examples of change log entries, starting with the
+header line that says who made the change and when, followed by
+descriptions of specific changes. (These examples are drawn from Emacs
+and GCC.)
+
+@example
+1998-08-17 Richard Stallman
+
+* register.el (insert-register): Return nil.
+(jump-to-register): Likewise.
+
+* sort.el (sort-subr): Return nil.
+
+* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+Restart the tex shell if process is gone or stopped.
+(tex-shell-running): New function.
+
+* expr.c (store_one_arg): Round size up for move_block_to_reg.
+(expand_call): Round up when emitting USE insns.
+* stmt.c (assign_parms): Round size up for move_block_from_reg.
+@end example
+
+It's important to name the changed function or variable in full. Don't
+abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
+
+For example, some people are tempted to abbreviate groups of function
+names by writing @samp{* register.el (@{insert,jump-to@}-register)};
+this is not a good idea, since searching for @code{jump-to-register} or
+@code{insert-register} would not find that entry.
+
+Separate unrelated change log entries with blank lines. When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them. Then you can omit the file
+name and the asterisk when successive entries are in the same file.
+
+Break long lists of function names by closing continued lines with
+@samp{)}, rather than @samp{,}, and opening the continuation with
+@samp{(} as in this example:
+
+@example
+* keyboard.c (menu_bar_items, tool_bar_items)
+(Fexecute_extended_command): Deal with `keymap' property.
+@end example
+
+@node Simple Changes
+@subsection Simple Changes
+
+Certain simple kinds of changes don't need much detail in the change
+log.
+
+When you change the calling sequence of a function in a simple fashion,
+and you change all the callers of the function to use the new calling
+sequence, there is no need to make individual entries for all the
+callers that you changed. Just write in the entry for the function
+being called, ``All callers changed''---like this:
+
+@example
+* keyboard.c (Fcommand_execute): New arg SPECIAL.
+All callers changed.
+@end example
+
+When you change just comments or doc strings, it is enough to write an
+entry for the file, without mentioning the functions. Just ``Doc
+fixes'' is enough for the change log.
+
+There's no need to make change log entries for documentation files.
+This is because documentation is not susceptible to bugs that are hard
+to fix. Documentation does not consist of parts that must interact in a
+precisely engineered fashion. To correct an error, you need not know
+the history of the erroneous passage; it is enough to compare what the
+documentation says with the way the program actually works.
+
+@node Conditional Changes
+@subsection Conditional Changes
+@cindex conditional changes, and change logs
+@cindex change logs, conditional changes
+
+C programs often contain compile-time @code{#if} conditionals. Many
+changes are conditional; sometimes you add a new definition which is
+entirely contained in a conditional. It is very useful to indicate in
+the change log the conditions for which the change applies.
+
+Our convention for indicating conditional changes is to use square
+brackets around the name of the condition.
+
+Here is a simple example, describing a change which is conditional but
+does not have a function or entity name associated with it:
+
+@example
+* xterm.c [SOLARIS2]: Include string.h.
+@end example
+
+Here is an entry describing a new definition which is entirely
+conditional. This new definition for the macro @code{FRAME_WINDOW_P} is
+used only when @code{HAVE_X_WINDOWS} is defined:
+
+@example
+* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+@end example
+
+Here is an entry for a change within the function @code{init_display},
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
+
+@example
+* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+@end example
+
+Here is an entry for a change that takes affect only when
+a certain macro is @emph{not} defined:
+
+@example
+(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+@end example
+
+@node Indicating the Part Changed
+@subsection Indicating the Part Changed
+
+Indicate the part of a function which changed by using angle brackets
+enclosing an indication of what the changed part does. Here is an entry
+for a change in the part of the function @code{sh-while-getopts} that
+deals with @code{sh} commands:
+
+@example
+* progmodes/sh-script.el (sh-while-getopts) : Handle case that
+user-specified option string is empty.
+@end example
+
+
+@node Man Pages
+@section Man Pages
+@cindex man pages
+
+In the GNU project, man pages are secondary. It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+
+When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed. The time
+you spend on the man page is time taken away from more useful work.
+
+For a simple program which changes little, updating the man page may be
+a small job. Then there is little reason not to include a man page, if
+you have one.
+
+For a large program that changes a great deal, updating a man page may
+be a substantial burden. If a user offers to donate a man page, you may
+find this gift costly to accept. It may be better to refuse the man
+page unless the same person agrees to take full responsibility for
+maintaining it---so that you can wash your hands of it entirely. If
+this volunteer later ceases to do the job, then don't feel obliged to
+pick it up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+
+When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating. If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative. The note should say how to access the Texinfo
+documentation.
+
+@node Reading other Manuals
+@section Reading other Manuals
+
+There may be non-free books or documentation files that describe the
+program you are documenting.
+
+It is ok to use these documents for reference, just as the author of a
+new algebra textbook can read other books on algebra. A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject. But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation. Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+
+@node Managing Releases
+@chapter The Release Process
+@cindex releasing
+
+Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP. You should set up your software so
+that it can be configured to run on a variety of systems. Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below. Doing so
+makes it easy to include your package into the larger framework of
+all GNU software.
+
+@menu
+* Configuration:: How Configuration Should Work
+* Makefile Conventions:: Makefile Conventions
+* Releases:: Making Releases
+@end menu
+
+@node Configuration
+@section How Configuration Should Work
+@cindex program configuration
+
+@pindex configure
+Each GNU distribution should come with a shell script named
+@code{configure}. This script is given arguments which describe the
+kind of machine and system you want to compile the program for.
+
+The @code{configure} script must record the configuration options so
+that they affect compilation.
+
+One way to do this is to make a link from a standard name such as
+@file{config.h} to the proper configuration file for the chosen system.
+If you use this technique, the distribution should @emph{not} contain a
+file named @file{config.h}. This is so that people won't be able to
+build the program without configuring it first.
+
+Another thing that @code{configure} can do is to edit the Makefile. If
+you do this, the distribution should @emph{not} contain a file named
+@file{Makefile}. Instead, it should include a file @file{Makefile.in} which
+contains the input used for editing. Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+If @code{configure} does write the @file{Makefile}, then @file{Makefile}
+should have a target named @file{Makefile} which causes @code{configure}
+to be rerun, setting up the same configuration that was set up last
+time. The files that @code{configure} reads should be listed as
+dependencies of @file{Makefile}.
+
+All the files which are output from the @code{configure} script should
+have comments at the beginning explaining that they were generated
+automatically using @code{configure}. This is so that users won't think
+of trying to edit them by hand.
+
+The @code{configure} script should write a file named @file{config.status}
+which describes which configuration options were specified when the
+program was last configured. This file should be a shell script which,
+if run, will recreate the same configuration.
+
+The @code{configure} script should accept an option of the form
+@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
+(if it is not the current directory). This makes it possible to build
+the program in a separate directory, so that the actual source directory
+is not modified.
+
+If the user does not specify @samp{--srcdir}, then @code{configure} should
+check both @file{.} and @file{..} to see if it can find the sources. If
+it finds the sources in one of these places, it should use them from
+there. Otherwise, it should report that it cannot find the sources, and
+should exit with nonzero status.
+
+Usually the easy way to support @samp{--srcdir} is by editing a
+definition of @code{VPATH} into the Makefile. Some rules may need to
+refer explicitly to the specified source directory. To make this
+possible, @code{configure} can add to the Makefile a variable named
+@code{srcdir} whose value is precisely the specified directory.
+
+The @code{configure} script should also take an argument which specifies the
+type of system to build the program for. This argument should look like
+this:
+
+@example
+@var{cpu}-@var{company}-@var{system}
+@end example
+
+For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.
+
+The @code{configure} script needs to be able to decode all plausible
+alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1}
+would be a valid alias. For many programs, @samp{vax-dec-ultrix} would
+be an alias for @samp{vax-dec-bsd}, simply because the differences
+between Ultrix and @sc{bsd} are rarely noticeable, but a few programs
+might need to distinguish them.
+@c Real 4.4BSD now runs on some Suns.
+
+There is a shell script called @file{config.sub} that you can use
+as a subroutine to validate system types and canonicalize aliases.
+
+@cindex optional features, configure-time
+Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+
+@table @samp
+@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}. This allows users to choose which
+optional features to include. Giving an optional @var{parameter} of
+@samp{no} should omit @var{feature}, if it is built by default.
+
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another. No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior. The only proper use for
+@samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+
+@item --with-@var{package}
+@c @r{[}=@var{parameter}@r{]}
+The package @var{package} will be installed, so configure this package
+to work with @var{package}.
+
+@c Giving an optional @var{parameter} of
+@c @samp{no} should omit @var{package}, if it is used by default.
+
+Possible values of @var{package} include
+@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
+@samp{gdb},
+@samp{x},
+and
+@samp{x-toolkit}.
+
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files. That is outside the scope of what @samp{--with}
+options are for.
+@end table
+
+All @code{configure} scripts should accept all of these ``detail''
+options, whether or not they make any difference to the particular
+package at hand. In particular, they should accept any option that
+starts with @samp{--with-} or @samp{--enable-}. This is so users will
+be able to configure an entire GNU source tree at once with a single set
+of options.
+
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
+
+Packages that perform part of the compilation process may support
+cross-compilation. In such a case, the host and target machines for the
+program may be different.
+
+The @code{configure} script should normally treat the specified type of
+system as both the host and the target, thus producing a program which
+works for the same type of machine that it runs on.
+
+To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option @samp{--target=@var{targettype}}. The syntax for
+@var{targettype} is the same as for the host type. So the command would
+look like this:
+
+@example
+./configure @var{hosttype} --target=@var{targettype}
+@end example
+
+Programs for which cross-operation is not meaningful need not accept the
+@samp{--target} option, because configuring an entire operating system for
+cross-operation is not a meaningful operation.
+
+Bootstrapping a cross-compiler requires compiling it on a machine other
+than the host it will run on. Compilation packages accept a
+configuration option @samp{--build=@var{buildtype}} for specifying the
+configuration on which you will compile them, but the configure script
+should normally guess the build machine type (using
+@file{config.guess}), so this option is probably not necessary. The
+host and target types normally default from the build type, so in
+bootstrapping a cross-compiler you must specify them both explicitly.
+
+Some programs have ways of configuring themselves automatically. If
+your program is set up to do this, your @code{configure} script can simply
+ignore most of its arguments.
+
+@comment The makefile standards are in a separate file that is also
+@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93.
+@comment For this document, turn chapters into sections, etc.
+@lowersections
+@include make-stds.texi
+@raisesections
+
+@node Releases
+@section Making Releases
+@cindex packaging
+
+Package the distribution of @code{Foo version 69.96} up in a gzipped tar
+file with the name @file{foo-69.96.tar.gz}. It should unpack into a
+subdirectory named @file{foo-69.96}.
+
+Building and installing the program should never modify any of the files
+contained in the distribution. This means that all the files that form
+part of the program in any way must be classified into @dfn{source
+files} and @dfn{non-source files}. Source files are written by humans
+and never changed automatically; non-source files are produced from
+source files by programs under the control of the Makefile.
+
+@cindex @file{README} file
+The distribution should contain a file named @file{README} which gives
+the name of the package, and a general description of what it does. It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any. The @file{README} file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+The @file{README} file should refer to the file @file{INSTALL}, which
+should contain an explanation of the installation procedure.
+
+The @file{README} file should also refer to the file which contains the
+copying conditions. The GNU GPL, if used, should be in a file called
+@file{COPYING}. If the GNU LGPL is used, it should be in a file called
+@file{COPYING.LIB}.
+
+Naturally, all the source files must be in the distribution. It is okay
+to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them. We commonly include non-source files
+produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+Non-source files that might actually be modified by building and
+installing the program should @strong{never} be included in the
+distribution. So if you do distribute non-source files, always make
+sure they are up to date when you make a new distribution.
+
+Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of @code{tar} which preserve the
+ownership and permissions of the files from the tar archive will be
+able to extract all the files even if the user is unprivileged.
+
+Make sure that all the files in the distribution are world-readable.
+
+Make sure that no file name in the distribution is more than 14
+characters long. Likewise, no file created by building the program
+should have a name longer than 14 characters. The reason for this is
+that some systems adhere to a foolish interpretation of the @sc{posix}
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+Don't include any symbolic links in the distribution itself. If the tar
+file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links. Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the
+distribution.
+
+Try to make sure that all the file names will be unique on MS-DOS. A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters. MS-DOS will truncate extra
+characters both before and after the period. Thus,
+@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
+distinct.
+
+@cindex @file{texinfo.tex}, in a distribution
+Include in your distribution a copy of the @file{texinfo.tex} you used
+to test print any @file{*.texinfo} or @file{*.texi} files.
+
+Likewise, if your program uses small GNU software packages like regex,
+getopt, obstack, or termcap, include them in the distribution file.
+Leaving them out would make the distribution file a little smaller at
+the expense of possible inconvenience to a user who doesn't know what
+other files to get.
+
+@node References
+@chapter References to Non-Free Software and Documentation
+@cindex references to non-free material
+
+A GNU program should not recommend use of any non-free program. We
+can't stop some people from writing proprietary programs, or stop
+other people from using them, but we can and should avoid helping to
+advertise them to new potential customers. Proprietary software is a
+social and ethical problem, and the point of GNU is to solve that
+problem.
+
+When a non-free program or system is well known, you can mention it in
+passing---that is harmless, since users who might want to use it
+probably already know about it. For instance, it is fine to explain
+how to build your package on top of some non-free operating system, or
+how to use it together with some widely used non-free program.
+
+However, you should give only the necessary information to help those
+who already use the non-free program to use your program with
+it---don't give, or refer to, any further information about the
+proprietary program, and don't imply that the proprietary program
+enhances your program, or that its existence is in any way a good
+thing. The goal should be that people already using the proprietary
+program will get the advice they need about how to use your free
+program, while people who don't already use the proprietary program
+will not see anything to lead them to take an interest in it.
+
+If a non-free program or system is obscure in your program's domain,
+your program should not mention or support it at all, since doing so
+would tend to popularize the non-free program more than it popularizes
+your program. (You cannot hope to find many additional users among
+the users of Foobar if the users of Foobar are few.)
+
+A GNU package should not refer the user to any non-free documentation
+for free software. Free documentation that can be included in free
+operating systems is essential for completing the GNU system, so it is
+a major focus of the GNU Project; to recommend use of documentation
+that we are not allowed to use in GNU would undermine the efforts to
+get documentation that we can include. So GNU packages should never
+recommend non-free documentation.
+
+@node Copying This Manual
+@appendix Copying This Manual
+
+@menu
+* GNU Free Documentation License:: License for copying this manual
+@end menu
+
+@include fdl.texi
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@contents
+
+@bye
+@c Local variables:
+@c eval: (add-hook 'write-file-hooks 'time-stamp)
+@c time-stamp-start: "@set lastupdate "
+@c time-stamp-end: "$"
+@c time-stamp-format: "%:b %:d, %:y"
+@c compile-command: "make just-standards"
+@c End:
Index: configdev.tin
===================================================================
--- configdev.tin (nonexistent)
+++ configdev.tin (revision 1765)
@@ -0,0 +1,17 @@
+ 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
Index: configbuild.ein
===================================================================
--- configbuild.ein (nonexistent)
+++ configbuild.ein (revision 1765)
@@ -0,0 +1,149 @@
+%!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
Index: make-stds.texi
===================================================================
--- make-stds.texi (nonexistent)
+++ make-stds.texi (revision 1765)
@@ -0,0 +1,955 @@
+@comment This file is included by both standards.texi and make.texinfo.
+@comment It was broken out of standards.texi on 1/6/93 by roland.
+
+@node Makefile Conventions
+@chapter Makefile Conventions
+@comment standards.texi does not print an index, but make.texinfo does.
+@cindex makefile, conventions for
+@cindex conventions for makefiles
+@cindex standards for makefiles
+
+@c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001 Free
+@c Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.1
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, with no
+@c Front-Cover Texts, and with no Back-Cover Texts.
+@c A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+This
+@ifinfo
+node
+@end ifinfo
+@iftex
+@ifset CODESTD
+section
+@end ifset
+@ifclear CODESTD
+chapter
+@end ifclear
+@end iftex
+describes conventions for writing the Makefiles for GNU programs.
+Using Automake will help you write a Makefile that follows these
+conventions.
+
+@menu
+* Makefile Basics:: General Conventions for Makefiles
+* Utilities in Makefiles:: Utilities in Makefiles
+* Command Variables:: Variables for Specifying Commands
+* Directory Variables:: Variables for Installation Directories
+* Standard Targets:: Standard Targets for Users
+* Install Command Categories:: Three categories of commands in the `install'
+ rule: normal, pre-install and post-install.
+@end menu
+
+@node Makefile Basics
+@section General Conventions for Makefiles
+
+Every Makefile should contain this line:
+
+@example
+SHELL = /bin/sh
+@end example
+
+@noindent
+to avoid trouble on systems where the @code{SHELL} variable might be
+inherited from the environment. (This is never a problem with GNU
+@code{make}.)
+
+Different @code{make} programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior. So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+@example
+.SUFFIXES:
+.SUFFIXES: .c .o
+@end example
+
+@noindent
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+Don't assume that @file{.} is in the path for command execution. When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses @file{./} if the program is built as
+part of the make or @file{$(srcdir)/} if the file is an unchanging part
+of the source code. Without one of these prefixes, the current search
+path is used.
+
+The distinction between @file{./} (the @dfn{build directory}) and
+@file{$(srcdir)/} (the @dfn{source directory}) is important because
+users can build in a separate directory using the @samp{--srcdir} option
+to @file{configure}. A rule of the form:
+
+@smallexample
+foo.1 : foo.man sedscript
+ sed -e sedscript foo.man > foo.1
+@end smallexample
+
+@noindent
+will fail when the build directory is not the source directory, because
+@file{foo.man} and @file{sedscript} are in the source directory.
+
+When using GNU @code{make}, relying on @samp{VPATH} to find the source
+file will work in the case where there is a single dependency file,
+since the @code{make} automatic variable @samp{$<} will represent the
+source file wherever it is. (Many versions of @code{make} set @samp{$<}
+only in implicit rules.) A Makefile target like
+
+@smallexample
+foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+@end smallexample
+
+@noindent
+should instead be written as
+
+@smallexample
+foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
+@end smallexample
+
+@noindent
+in order to allow @samp{VPATH} to work correctly. When the target has
+multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
+way to make the rule work well. For example, the target above for
+@file{foo.1} is best written as:
+
+@smallexample
+foo.1 : foo.man sedscript
+ sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
+@end smallexample
+
+GNU distributions usually contain some files which are not source
+files---for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex. Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory. So Makefile rules to update them should put the
+updated files in the source directory.
+
+However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
+Try to make the build and installation targets, at least (and all their
+subtargets) work correctly with a parallel @code{make}.
+
+@node Utilities in Makefiles
+@section Utilities in Makefiles
+
+Write the Makefile commands (and any shell scripts, such as
+@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any
+special features of @code{ksh} or @code{bash}.
+
+The @code{configure} script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+@c dd find
+@c gunzip gzip md5sum
+@c mkfifo mknod tee uname
+
+@example
+cat cmp cp diff echo egrep expr false grep install-info
+ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+@end example
+
+The compression program @code{gzip} can be used in the @code{dist} rule.
+
+Stick to the generally supported options for these programs. For
+example, don't use @samp{mkdir -p}, convenient as it may be, because
+most systems don't support it.
+
+It is a good idea to avoid creating symbolic links in makefiles, since a
+few systems don't support them.
+
+The Makefile rules for building and installation can also use compilers
+and related programs, but should do so via @code{make} variables so that the
+user can substitute alternatives. Here are some of the programs we
+mean:
+
+@example
+ar bison cc flex install ld ldconfig lex
+make makeinfo ranlib texi2dvi yacc
+@end example
+
+Use the following @code{make} variables to run those programs:
+
+@example
+$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+@end example
+
+When you use @code{ranlib} or @code{ldconfig}, you should make sure
+nothing bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
+this.)
+
+If you use symbolic links, you should implement a fallback for systems
+that don't have symbolic links.
+
+Additional utilities that can be used via Make variables are:
+
+@example
+chgrp chmod chown mknod
+@end example
+
+It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+@node Command Variables
+@section Variables for Specifying Commands
+
+Makefiles should provide variables for overriding certain commands, options,
+and so on.
+
+In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named @code{BISON} whose default
+value is set with @samp{BISON = bison}, and refer to it with
+@code{$(BISON)} whenever you need to use Bison.
+
+File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
+so on, need not be referred to through variables in this way, since users
+don't need to replace them with other programs.
+
+Each program-name variable should come with an options variable that is
+used to supply options to the program. Append @samp{FLAGS} to the
+program-name variable name to get the options variable name---for
+example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C
+compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
+exceptions to this rule, but we keep them because they are standard.)
+Use @code{CPPFLAGS} in any compilation command that runs the
+preprocessor, and use @code{LDFLAGS} in any compilation command that
+does linking as well as in any direct use of @code{ld}.
+
+If there are C compiler options that @emph{must} be used for proper
+compilation of certain files, do not include them in @code{CFLAGS}.
+Users expect to be able to specify @code{CFLAGS} freely themselves.
+Instead, arrange to pass the necessary options to the C compiler
+independently of @code{CFLAGS}, by writing them explicitly in the
+compilation commands or by defining an implicit rule, like this:
+
+@smallexample
+CFLAGS = -g
+ALL_CFLAGS = -I. $(CFLAGS)
+.c.o:
+ $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+@end smallexample
+
+Do include the @samp{-g} option in @code{CFLAGS}, because that is not
+@emph{required} for proper compilation. You can consider it a default
+that is only recommended. If the package is set up so that it is
+compiled with GCC by default, then you might as well include @samp{-O}
+in the default value of @code{CFLAGS} as well.
+
+Put @code{CFLAGS} last in the compilation command, after other variables
+containing compiler options, so the user can use @code{CFLAGS} to
+override the others.
+
+@code{CFLAGS} should be used in every invocation of the C compiler,
+both those which do compilation and those which do linking.
+
+Every Makefile should define the variable @code{INSTALL}, which is the
+basic command for installing a file into the system.
+
+Every Makefile should also define the variables @code{INSTALL_PROGRAM}
+and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should
+be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
+@code{$@{INSTALL@} -m 644}.) Then it should use those variables as the
+commands for actual installation, for executables and nonexecutables
+respectively. Use these variables as follows:
+
+@example
+$(INSTALL_PROGRAM) foo $(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+@end example
+
+Optionally, you may prepend the value of @code{DESTDIR} to the target
+filename. Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later. Do not
+set the value of @code{DESTDIR} in your Makefile, and do not include it
+in any installed files. With support for @code{DESTDIR}, the above
+examples become:
+
+@example
+$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+@end example
+
+@noindent
+Always use a file name, not a directory name, as the second argument of
+the installation commands. Use a separate command for each file to be
+installed.
+
+@node Directory Variables
+@section Variables for Installation Directories
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place. The standard names for these
+variables are described below. They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
+and other modern operating systems.
+
+These two variables set the root for the installation. All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+@table @code
+@item prefix
+@vindex prefix
+A prefix used in constructing the default values of the variables listed
+below. The default value of @code{prefix} should be @file{/usr/local}.
+When building the complete GNU system, the prefix will be empty and
+@file{/usr} will be a symbolic link to @file{/}.
+(If you are using Autoconf, write it as @samp{@@prefix@@}.)
+
+Running @samp{make install} with a different value of @code{prefix} from
+the one used to build the program should @emph{not} recompile the
+program.
+
+@item exec_prefix
+@vindex exec_prefix
+A prefix used in constructing the default values of some of the
+variables listed below. The default value of @code{exec_prefix} should
+be @code{$(prefix)}.
+(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
+
+Generally, @code{$(exec_prefix)} is used for directories that contain
+machine-specific files (such as executables and subroutine libraries),
+while @code{$(prefix)} is used directly for other directories.
+
+Running @samp{make install} with a different value of @code{exec_prefix}
+from the one used to build the program should @emph{not} recompile the
+program.
+@end table
+
+Executable programs are installed in one of the following directories.
+
+@table @code
+@item bindir
+@vindex bindir
+The directory for installing executable programs that users can run.
+This should normally be @file{/usr/local/bin}, but write it as
+@file{$(exec_prefix)/bin}.
+(If you are using Autoconf, write it as @samp{@@bindir@@}.)
+
+@item sbindir
+@vindex sbindir
+The directory for installing executable programs that can be run from
+the shell, but are only generally useful to system administrators. This
+should normally be @file{/usr/local/sbin}, but write it as
+@file{$(exec_prefix)/sbin}.
+(If you are using Autoconf, write it as @samp{@@sbindir@@}.)
+
+@item libexecdir
+@vindex libexecdir
+@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
+The directory for installing executable programs to be run by other
+programs rather than by users. This directory should normally be
+@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
+(If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
+@end table
+
+Data files used by the program during its execution are divided into
+categories in two ways.
+
+@itemize @bullet
+@item
+Some files are normally modified by programs; others are never normally
+modified (though users may edit some of these).
+
+@item
+Some files are architecture-independent and can be shared by all
+machines at a site; some are architecture-dependent and can be shared
+only by machines of the same kind and operating system; others may never
+be shared between two machines.
+@end itemize
+
+This makes for six different possibilities. However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries. It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+Therefore, here are the variables Makefiles should use to specify
+directories:
+
+@table @samp
+@item datadir
+The directory for installing read-only architecture independent data
+files. This should normally be @file{/usr/local/share}, but write it as
+@file{$(prefix)/share}.
+(If you are using Autoconf, write it as @samp{@@datadir@@}.)
+As a special exception, see @file{$(infodir)}
+and @file{$(includedir)} below.
+
+@item sysconfdir
+The directory for installing read-only data files that pertain to a
+single machine--that is to say, files for configuring a host. Mailer
+and network configuration files, @file{/etc/passwd}, and so forth belong
+here. All the files in this directory should be ordinary ASCII text
+files. This directory should normally be @file{/usr/local/etc}, but
+write it as @file{$(prefix)/etc}.
+(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
+
+Do not install executables here in this directory (they probably belong
+in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install
+files that are modified in the normal course of their use (programs
+whose purpose is to change the configuration of the system excluded).
+Those probably belong in @file{$(localstatedir)}.
+
+@item sharedstatedir
+The directory for installing architecture-independent data files which
+the programs modify while they run. This should normally be
+@file{/usr/local/com}, but write it as @file{$(prefix)/com}.
+(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
+
+@item localstatedir
+The directory for installing data files which the programs modify while
+they run, and that pertain to one specific machine. Users should never
+need to modify files in this directory to configure the package's
+operation; put such configuration information in separate files that go
+in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)}
+should normally be @file{/usr/local/var}, but write it as
+@file{$(prefix)/var}.
+(If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
+
+@item libdir
+The directory for object files and libraries of object code. Do not
+install executables here, they probably ought to go in @file{$(libexecdir)}
+instead. The value of @code{libdir} should normally be
+@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
+(If you are using Autoconf, write it as @samp{@@libdir@@}.)
+
+@item infodir
+The directory for installing the Info files for this package. By
+default, it should be @file{/usr/local/info}, but it should be written
+as @file{$(prefix)/info}.
+(If you are using Autoconf, write it as @samp{@@infodir@@}.)
+
+@item lispdir
+The directory for installing any Emacs Lisp files in this package. By
+default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
+should be written as @file{$(prefix)/share/emacs/site-lisp}.
+
+If you are using Autoconf, write the default as @samp{@@lispdir@@}.
+In order to make @samp{@@lispdir@@} work, you need the following lines
+in your @file{configure.in} file:
+
+@example
+lispdir='$@{datadir@}/emacs/site-lisp'
+AC_SUBST(lispdir)
+@end example
+
+@item includedir
+@c rewritten to avoid overfull hbox --roland
+The directory for installing header files to be included by user
+programs with the C @samp{#include} preprocessor directive. This
+should normally be @file{/usr/local/include}, but write it as
+@file{$(prefix)/include}.
+(If you are using Autoconf, write it as @samp{@@includedir@@}.)
+
+Most compilers other than GCC do not look for header files in directory
+@file{/usr/local/include}. So installing the header files this way is
+only useful with GCC. Sometimes this is not a problem because some
+libraries are only really intended to work with GCC. But some libraries
+are intended to work with other compilers. They should install their
+header files in two places, one specified by @code{includedir} and one
+specified by @code{oldincludedir}.
+
+@item oldincludedir
+The directory for installing @samp{#include} header files for use with
+compilers other than GCC. This should normally be @file{/usr/include}.
+(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
+
+The Makefile commands should check whether the value of
+@code{oldincludedir} is empty. If it is, they should not try to use
+it; they should cancel the second installation of the header files.
+
+A package should not replace an existing header in this directory unless
+the header came from the same package. Thus, if your Foo package
+provides a header file @file{foo.h}, then it should install the header
+file in the @code{oldincludedir} directory if either (1) there is no
+@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
+package.
+
+To tell whether @file{foo.h} came from the Foo package, put a magic
+string in the file---part of a comment---and @code{grep} for that string.
+@end table
+
+Unix-style man pages are installed in one of the following:
+
+@table @samp
+@item mandir
+The top-level directory for installing the man pages (if any) for this
+package. It will normally be @file{/usr/local/man}, but you should
+write it as @file{$(prefix)/man}.
+(If you are using Autoconf, write it as @samp{@@mandir@@}.)
+
+@item man1dir
+The directory for installing section 1 man pages. Write it as
+@file{$(mandir)/man1}.
+@item man2dir
+The directory for installing section 2 man pages. Write it as
+@file{$(mandir)/man2}
+@item @dots{}
+
+@strong{Don't make the primary documentation for any GNU software be a
+man page. Write a manual in Texinfo instead. Man pages are just for
+the sake of people running GNU software on Unix, which is a secondary
+application only.}
+
+@item manext
+The file name extension for the installed man page. This should contain
+a period followed by the appropriate digit; it should normally be @samp{.1}.
+
+@item man1ext
+The file name extension for installed section 1 man pages.
+@item man2ext
+The file name extension for installed section 2 man pages.
+@item @dots{}
+Use these names instead of @samp{manext} if the package needs to install man
+pages in more than one section of the manual.
+@end table
+
+And finally, you should set the following variable:
+
+@table @samp
+@item srcdir
+The directory for the sources being compiled. The value of this
+variable is normally inserted by the @code{configure} shell script.
+(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.)
+@end table
+
+For example:
+
+@smallexample
+@c I have changed some of the comments here slightly to fix an overfull
+@c hbox, so the make manual can format correctly. --roland
+# Common prefix for installation directories.
+# NOTE: This directory must exist when you start the install.
+prefix = /usr/local
+exec_prefix = $(prefix)
+# Where to put the executable for the command `gcc'.
+bindir = $(exec_prefix)/bin
+# Where to put the directories used by the compiler.
+libexecdir = $(exec_prefix)/libexec
+# Where to put the Info files.
+infodir = $(prefix)/info
+@end smallexample
+
+If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program. If you do this, you
+should write the @code{install} rule to create these subdirectories.
+
+Do not expect the user to include the subdirectory name in the value of
+any of the variables listed above. The idea of having a uniform set of
+variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages. In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+@node Standard Targets
+@section Standard Targets for Users
+
+All GNU programs should have the following targets in their Makefiles:
+
+@table @samp
+@item all
+Compile the entire program. This should be the default target. This
+target need not rebuild any documentation files; Info files should
+normally be included in the distribution, and DVI files should be made
+only when explicitly asked for.
+
+By default, the Make rules should compile and link with @samp{-g}, so
+that executable programs have debugging symbols. Users who don't mind
+being helpless can strip the executables later if they wish.
+
+@item install
+Compile the program and copy the executables, libraries, and so on to
+the file names where they should reside for actual use. If there is a
+simple test to verify that a program is properly installed, this target
+should run that test.
+
+Do not strip executables when installing them. Devil-may-care users can
+use the @code{install-strip} target to do that.
+
+If possible, write the @code{install} target rule so that it does not
+modify anything in the directory where the program was built, provided
+@samp{make all} has just been done. This is convenient for building the
+program under one user name and installing it under another.
+
+The commands should create all the directories in which files are to be
+installed, if they don't already exist. This includes the directories
+specified as the values of the variables @code{prefix} and
+@code{exec_prefix}, as well as all subdirectories that are needed.
+One way to do this is by means of an @code{installdirs} target
+as described below.
+
+Use @samp{-} before any command for installing a man page, so that
+@code{make} will ignore any errors. This is in case there are systems
+that don't have the Unix man page documentation system installed.
+
+The way to install Info files is to copy them into @file{$(infodir)}
+with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
+the @code{install-info} program if it is present. @code{install-info}
+is a program that edits the Info @file{dir} file to add or update the
+menu entry for the given Info file; it is part of the Texinfo package.
+Here is a sample rule to install an Info file:
+
+@comment This example has been carefully formatted for the Make manual.
+@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu.
+@smallexample
+$(DESTDIR)$(infodir)/foo.info: foo.info
+ $(POST_INSTALL)
+# There may be a newer info file in . than in srcdir.
+ -if test -f foo.info; then d=.; \
+ else d=$(srcdir); fi; \
+ $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \
+# Run install-info only if it exists.
+# Use `if' instead of just prepending `-' to the
+# line so we notice real errors from install-info.
+# We use `$(SHELL) -c' because some shells do not
+# fail gracefully when there is an unknown command.
+ if $(SHELL) -c 'install-info --version' \
+ >/dev/null 2>&1; then \
+ install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+ $(DESTDIR)$(infodir)/foo.info; \
+ else true; fi
+@end smallexample
+
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands. @xref{Install Command
+Categories}.
+
+@item uninstall
+Delete all the installed files---the copies that the @samp{install}
+target creates.
+
+This rule should not modify the directories where compilation is done,
+only the directories where files are installed.
+
+The uninstallation commands are divided into three categories, just like
+the installation commands. @xref{Install Command Categories}.
+
+@item install-strip
+Like @code{install}, but strip the executable files while installing
+them. In simple cases, this target can use the @code{install} target in
+a simple way:
+
+@smallexample
+install-strip:
+ $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+ install
+@end smallexample
+
+But if the package installs scripts as well as real executables, the
+@code{install-strip} target can't just refer to the @code{install}
+target; it has to strip the executables but not the scripts.
+
+@code{install-strip} should not strip the executables in the build
+directory which are being copied for installation. It should only strip
+the copies that are installed.
+
+Normally we do not recommend stripping an executable unless you are sure
+the program has no bugs. However, it can be reasonable to install a
+stripped executable for actual execution while saving the unstripped
+executable elsewhere in case there is a bug.
+
+@comment The gratuitous blank line here is to make the table look better
+@comment in the printed Make manual. Please leave it in.
+@item clean
+
+Delete all files from the current directory that are normally created by
+building the program. Don't delete the files that record the
+configuration. Also preserve files that could be made by building, but
+normally aren't because the distribution comes with them.
+
+Delete @file{.dvi} files here if they are not part of the distribution.
+
+@item distclean
+Delete all files from the current directory that are created by
+configuring or building the program. If you have unpacked the source
+and built the program without creating any other files, @samp{make
+distclean} should leave only the files that were in the distribution.
+
+@item mostlyclean
+Like @samp{clean}, but may refrain from deleting a few files that people
+normally don't want to recompile. For example, the @samp{mostlyclean}
+target for GCC does not delete @file{libgcc.a}, because recompiling it
+is rarely necessary and takes a lot of time.
+
+@item maintainer-clean
+Delete almost everything from the current directory that can be
+reconstructed with this Makefile. This typically includes everything
+deleted by @code{distclean}, plus more: C source files produced by
+Bison, tags tables, Info files, and so on.
+
+The reason we say ``almost everything'' is that running the command
+@samp{make maintainer-clean} should not delete @file{configure} even if
+@file{configure} can be remade using a rule in the Makefile. More generally,
+@samp{make maintainer-clean} should not delete anything that needs to
+exist in order to run @file{configure} and then begin to build the
+program. This is the only exception; @code{maintainer-clean} should
+delete everything else that can be rebuilt.
+
+The @samp{maintainer-clean} target is intended to be used by a maintainer of
+the package, not by ordinary users. You may need special tools to
+reconstruct some of the files that @samp{make maintainer-clean} deletes.
+Since these files are normally included in the distribution, we don't
+take care to make them easy to reconstruct. If you find you need to
+unpack the full distribution again, don't blame us.
+
+To help make users aware of this, the commands for the special
+@code{maintainer-clean} target should start with these two:
+
+@smallexample
+@@echo 'This command is intended for maintainers to use; it'
+@@echo 'deletes files that may need special tools to rebuild.'
+@end smallexample
+
+@item TAGS
+Update a tags table for this program.
+@c ADR: how?
+
+@item info
+Generate any Info files needed. The best way to write the rules is as
+follows:
+
+@smallexample
+info: foo.info
+
+foo.info: foo.texi chap1.texi chap2.texi
+ $(MAKEINFO) $(srcdir)/foo.texi
+@end smallexample
+
+@noindent
+You must define the variable @code{MAKEINFO} in the Makefile. It should
+run the @code{makeinfo} program, which is part of the Texinfo
+distribution.
+
+Normally a GNU distribution comes with Info files, and that means the
+Info files are present in the source directory. Therefore, the Make
+rule for an info file should update it in the source directory. When
+users build the package, ordinarily Make will not update the Info files
+because they will already be up to date.
+
+@item dvi
+Generate DVI files for all Texinfo documentation.
+For example:
+
+@smallexample
+dvi: foo.dvi
+
+foo.dvi: foo.texi chap1.texi chap2.texi
+ $(TEXI2DVI) $(srcdir)/foo.texi
+@end smallexample
+
+@noindent
+You must define the variable @code{TEXI2DVI} in the Makefile. It should
+run the program @code{texi2dvi}, which is part of the Texinfo
+distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work
+of formatting. @TeX{} is not distributed with Texinfo.} Alternatively,
+write just the dependencies, and allow GNU @code{make} to provide the command.
+
+@item dist
+Create a distribution tar file for this program. The tar file should be
+set up so that the file names in the tar file start with a subdirectory
+name which is the name of the package it is a distribution for. This
+name can include the version number.
+
+For example, the distribution tar file of GCC version 1.40 unpacks into
+a subdirectory named @file{gcc-1.40}.
+
+The easiest way to do this is to create a subdirectory appropriately
+named, use @code{ln} or @code{cp} to install the proper files in it, and
+then @code{tar} that subdirectory.
+
+Compress the tar file with @code{gzip}. For example, the actual
+distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
+
+The @code{dist} target should explicitly depend on all non-source files
+that are in the distribution, to make sure they are up to date in the
+distribution.
+@ifset CODESTD
+@xref{Releases, , Making Releases}.
+@end ifset
+@ifclear CODESTD
+@xref{Releases, , Making Releases, standards, GNU Coding Standards}.
+@end ifclear
+
+@item check
+Perform self-tests (if any). The user must build the program before
+running the tests, but need not install the program; you should write
+the self-tests so that they work when the program is built but not
+installed.
+@end table
+
+The following targets are suggested as conventional names, for programs
+in which they are useful.
+
+@table @code
+@item installcheck
+Perform installation tests (if any). The user must build and install
+the program before running the tests. You should not assume that
+@file{$(bindir)} is in the search path.
+
+@item installdirs
+It's useful to add a target named @samp{installdirs} to create the
+directories where files are installed, and their parent directories.
+There is a script called @file{mkinstalldirs} which is convenient for
+this; you can find it in the Texinfo package.
+@c It's in /gd/gnu/lib/mkinstalldirs.
+You can use a rule like this:
+
+@comment This has been carefully formatted to look decent in the Make manual.
+@comment Please be sure not to make it extend any further to the right.--roland
+@smallexample
+# Make sure all installation directories (e.g. $(bindir))
+# actually exist by making them if necessary.
+installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+ $(libdir) $(infodir) \
+ $(mandir)
+@end smallexample
+
+@noindent
+or, if you wish to support @env{DESTDIR},
+
+@smallexample
+# Make sure all installation directories (e.g. $(bindir))
+# actually exist by making them if necessary.
+installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs \
+ $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
+ $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
+ $(DESTDIR)$(mandir)
+@end smallexample
+
+This rule should not modify the directories where compilation is done.
+It should do nothing but create installation directories.
+@end table
+
+@node Install Command Categories
+@section Install Command Categories
+
+@cindex pre-installation commands
+@cindex post-installation commands
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands.
+
+Normal commands move files into their proper places, and set their
+modes. They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+Pre-installation and post-installation commands may alter other files;
+in particular, they can edit global configuration files or data bases.
+
+Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+The most common use for a post-installation command is to run
+@code{install-info}. This cannot be done with a normal command, since
+it alters a file (the Info directory) which does not come entirely and
+solely from the package being installed. It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+Most programs don't need any pre-installation commands, but we have the
+feature just in case it is needed.
+
+To classify the commands in the @code{install} rule into these three
+categories, insert @dfn{category lines} among them. A category line
+specifies the category for the commands that follow.
+
+A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end. There are three
+variables you can use, one for each category; the variable name
+specifies the category. Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+@emph{should not} define them in the makefile).
+
+Here are the three possible category lines, each with a comment that
+explains what it means:
+
+@smallexample
+ $(PRE_INSTALL) # @r{Pre-install commands follow.}
+ $(POST_INSTALL) # @r{Post-install commands follow.}
+ $(NORMAL_INSTALL) # @r{Normal commands follow.}
+@end smallexample
+
+If you don't use a category line at the beginning of the @code{install}
+rule, all the commands are classified as normal until the first category
+line. If you don't use any category lines, all the commands are
+classified as normal.
+
+These are the category lines for @code{uninstall}:
+
+@smallexample
+ $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.}
+ $(POST_UNINSTALL) # @r{Post-uninstall commands follow.}
+ $(NORMAL_UNINSTALL) # @r{Normal commands follow.}
+@end smallexample
+
+Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+If the @code{install} or @code{uninstall} target has any dependencies
+which act as subroutines of installation, then you should start
+@emph{each} dependency's commands with a category line, and start the
+main target's commands with a category line also. This way, you can
+ensure that each command is placed in the right category regardless of
+which of the dependencies actually run.
+
+Pre-installation and post-installation commands should not run any
+programs except for these:
+
+@example
+[ basename bash cat chgrp chmod chown cmp cp dd diff echo
+egrep expand expr false fgrep find getopt grep gunzip gzip
+hostname install install-info kill ldconfig ln ls md5sum
+mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+test touch true uname xargs yes
+@end example
+
+@cindex binary packages
+The reason for distinguishing the commands in this way is for the sake
+of making binary packages. Typically a binary package contains all the
+executables and other files that need to be installed, and has its own
+method of installing them---so it does not need to run the normal
+installation commands. But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+Programs to build binary packages work by extracting the
+pre-installation and post-installation commands. Here is one way of
+extracting the pre-installation commands:
+
+@smallexample
+make -n install -o all \
+ PRE_INSTALL=pre-install \
+ POST_INSTALL=post-install \
+ NORMAL_INSTALL=normal-install \
+ | gawk -f pre-install.awk
+@end smallexample
+
+@noindent
+where the file @file{pre-install.awk} could contain this:
+
+@smallexample
+$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@}
+on @{print $0@}
+$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@}
+@end smallexample
+
+The resulting file of pre-installation commands is executed as a shell
+script as part of installing the binary package.
Index: configbuild.jin
===================================================================
--- configbuild.jin (nonexistent)
+++ configbuild.jin (revision 1765)
@@ -0,0 +1,95 @@
+ÿØÿà JFIF ÿÛ C
+
+ $.' ",# (7),01444 '9=82<.342ÿÛ C
+
+2! !22222222222222222222222222222222222222222222222222ÿÀ Ø}" ÿÄ
+ ÿÄ µ } !1AQa"q2‘¡#B±ÁRÑð$3br‚
+%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyzƒ„…†‡ˆ‰Š’“”•–—˜™š¢£¤¥¦§¨©ª²³´µ¶·¸¹ºÂÃÄÅÆÇÈÉÊÒÓÔÕÖ×ØÙÚáâãäåæçèéêñòóôõö÷øùúÿÄ
+ ÿÄ µ w !1AQaq"2B‘¡±Á #3RðbrÑ
+$4á%ñ&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz‚ƒ„…†‡ˆ‰Š’“”•–—˜™š¢£¤¥¦§¨©ª²³´µ¶·¸¹ºÂÃÄÅÆÇÈÉÊÒÓÔÕÖ×ØÙÚâãäåæçèéêòóôõö÷øùúÿÚ ? ÷Ú(®3AÐmµ‹;»ÛÛÝa§mJù?w¬]D¡RêTP$
+ U ”„vtVü!ÚgüýkŸø=½ÿ ã´Â ¦ÏÖ¹ÿ ƒÛßþ;@ôVü!ÚgüýkŸø=½ÿ ã´Â ¦ÏÖ¹ÿ ƒÛßþ;@ôVü!ÚgüýkŸø=½ÿ ã´Â ¦ÏÖ¹ÿ ƒÛßþ;@ôVü!ÚgüýkŸø=½ÿ ãµâ¿
+Úiž×/í/µÈîm´ùæ…ÿ ¶ï×XØ©Á—´ÛÑE QE QE QX 2/ÿ úG ÓÃçj0»Á3Dû ê$`Ha•b8# ð‡iŸóõ®àö÷ÿ ŽÐýÿ v™ÿ ?Zçþoøí ð‡iŸóõ®àö÷ÿ ŽÐýÿ v™ÿ ?Zçþoøí ð‡iŸóõ®àö÷ÿ ŽÐýÿ v™ÿ ?Zçþoøí ð‡iŸóõ®àö÷ÿ ŽÐýÎxV#kyâ+%¸ºš mIR µ\É;"›[w 4ŒÍÌÇîk£ Š( Š( Š( Š( ŠÄñœóZøÄò¼3ŦܼrFÅYDÄG ƒÞ£ÿ „;Lÿ Ÿsÿ ·¿üv€7è¬øC´Ïùú×?ð{{ÿ Çhÿ „;Lÿ Ÿsÿ ·¿üv€7è¬øC´Ïùú×?ð{{ÿ Çhÿ „;Lÿ Ÿsÿ ·¿üv€7è¬øC´Ïùú×?ð{{ÿ Çhÿ „;Lÿ Ÿsÿ ·¿üv€7è¬øC´Ïùú×?ð{{ÿ Çhÿ „;Lÿ Ÿsÿ ·¿üv€7è®#Å~´Ó< ®_Ú_k‘ÜÛióÍ ÿ mÞ ®±±Sƒ. k· Š( °< ÿ KŸû
+ê?ú[5oÖƒ¿ä sÿ a]Gÿ Kf
+{«ë; #íwp[ùò¬ùÒó$oº‹ž¬pp&£ŸVÓmn%·¸Ô-až+su$rLªÉ82NBü]+3^ѯ/µ [»D±›·3Cz ˘ÄYÊ€|Ìy@ygh`Çç\sNjKâ9u sk$ôêq‰%df›ìe€˜ùüÌ’>îÃ÷¨æ·ã
+#GÒ'¾û}Œ¾]ÒØàÝ"¢Ü3ØíÎ͹ÜܪàãlkÚj[ßÝÜj:tVvw D“‹µ+ ¬„àFá›nÜŸá=N#§x;]‚ÎÂÚàiÊ ²Òmähî]¾k+£! ÆCÆsÛ 1Èùª¿‰ìum<ßj2ÜÚé¯.»å•êÝ +öo!þÐÒBV Ñ£ ?ï%AÛ,Û>½¦½…¥å®£§MÝÂAo+]ªÇ3ÁTaÏ€ØQÔ®8ä‹Z¶›©<‰c¨ZÝ›¡ÙXÉ }ž%‰"™’$^7ÌÛW ¸ãv3…Î ÈoÅöOý"¶úÀð÷ü†üWÿ aTÿ Ò+jß Š( Š( Š( Š( É>ñ/ý‚®¿ôSVý`xëþI÷‰ìuÿ ¢š·èGñ7öˆõâÓì×:t FâMésD}ÊHr‰zà…ÞŸ1Ü*¾ãK=N-júàA§éuжŽöæä(Ÿ*ær¬mæ!FÜw†ŒŒçÜxWW½¾Ö.L°XÍs¨ m®m.ßÍï vó+ ,mm‘‰TG˜±ç!2ÑÉá=W:ŠÃk§Cmý¥ ݽ½äÛ pžbFÜ€ŠÙvAhÏÊI $zæßê:mÜp[Ãm¬°Üÿ Öùï$j¤[|d grô'jÞ'Ò4m?U»¹¾¿²¢ÝC ¨dLŒ¢•$aŸ¢ƒŒ’1\Å—ƒ5}*[+ÛW±š÷LÓììmRib™ai‘ÙÆñš)AR ²1eÉBÛëËà=[þ*8c{]B-B;k©n® *]eÌ^I&8ñ!șܨ>L± ~ì‚ m¿²¯{aÊ[j[Ú ´¸@ÀþeùÑ”»Ô±ùp7oÃ}gqyqi
+Ü\ÛmóáIx· ®å ®G#=kñ…â;Ý~îêÂ×J{i³¶ï¤ÿ Ñns•°‹•êqŒóœGð®¢ø‡Q¿,nUå»–ÚionüÓ”wGï1™S9T &XÐÂM¤EöǺÕô¨a¶•£/öÔùvìWó3Œ¯"©8Ü™ ¶½q Ø^#ÿ „¯íßeÒ¾Åýµý¡»íÒyž_Ù>˾N7cçûØÏ˟⮃º}æ‘á='L¿ ›+XíœÁ!tmŠ0%Tò 8ÇÇ8É ¯ã¯ù'Þ%ÿ °U×þŠj߬ É>ñ/ý‚®¿ôSVý QE àïù\ÿ ØWQÿ ÒÙ«~¹M:ÛÅ:Ùâÿ úèø9—ÿ ‘hûg‹ÿ è¡ÿ àæ_þE
+úÀñ×ü“ïÿ Ø*ëÿ E5 lñý ô?ü Ëÿ ȵŸ®ÁâýkÃÚ–•ý“¡ÃöÛYm¼ßíi[fô+» fÆsŒŠ ë袊 (¢Š (¢Š Àñü-¿ì+§él5¿Y &Óï5=C` k˜înQg¢7•âÞk„a¬K´,m°?èÙÎe\qØþ7>Ùâÿ úèø9—ÿ ‘h~ŠÀûg‹ÿ è¡ÿ àæ_þE£íž/ÿ ‡ÿ ƒ™ù€ÈoÅöOý"¶úÄð톥k.±uªEk ÷÷¢ábµ¦TQQ`³"s=;ŠÛ Š( Š( Š( Š( É>ñ/ý‚®¿ôSQÿ ׄ?èjÐÿ ðaÿ [ôPü'^ÿ ¡«Cÿ Á„_üU ðxCþ†ÿ ñU¿E `Âuáú´?üEÿ ÅQÿ ׄ?èjÐÿ ðaÿ [õáïù
+ø¯þ©ÿ ¤VÔ Âuáú´?üEÿ ÅQÿ ׄ?èjÐÿ ðaÿ [ôPü'^ÿ ¡«Cÿ Á„_üU ðxCþ†ÿ ñU¿E pž3ñŸ…®¼
+â {èóO.›r‘Ç ôLÎÆ& $“Ú»º( Š( Š( Š( É>ñ/ý‚®¿ôSVý`xëþI÷‰ìuÿ ¢š·è ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š(óþJÿ `«ÿ ýi[õyÿ %Fÿ °Uÿ þ´ú (¢Š (¢Š (¢Š (¢Š (¢Š (¢Š (¢Š (¢Š +Ãßòñ_ý…Sÿ H«~°<=ÿ !¿ÿ ØU?ôŠÚ€7袊 (¢Š (¢Š (¢Š (¢Š (¢Š Àñ×ü“ïÿ Ø*ëÿ E5oÖŽ¿äŸx—þÁW_ú)«~€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€
+(¢€0/?ä èßö
+¿ÿ Ѷ•¿XŸòPtoû_ÿ èÛJß Š( Š( Š( Š( Š( Š( Š( Š( °<=ÿ !¿ÿ ØU?ôŠÚ·ëÃßòñ_ý…Sÿ H¨~Š( Š( Š( Š( Š+œD›Ål×·VÚM½ÃÛG ¤¦&ºd;dfbD d
+…3å±%ÕÀ ÿ v™ÿ ?Zçþoøí ð‡iŸóõ®àö÷ÿ ŽÐÆ{[ˆœ¶3ßE5¶ÙY- ¯›;$Y ûÑìvb:| žÿ ÚÞYø F‹Pžú{ÖµIn ýËL$q½•‰çå,TÈ Õ þѮ巸—Xš P¤‘ÉÞ2º‘‚2à‚;TŸð‡iŸóõ®àö÷ÿ ŽÐýÿ v™ÿ ?Zçþoøí ð‡iŸóõ®àö÷ÿ ŽÐýÿ v™ÿ ?Zçþoøí ð‡iŸóõ®àö÷ÿ ŽÐýÿ v™ÿ ?ZçþoøíFé7…î-on®t›‹„¶’;¹LjÎvÆË!ÌŽB¨UËãÌR
+*@::(¢€
+(¢€
++ŒÐtmbÎîöö÷XiÛR¾OÝëQ(Tº•I€@À¥j ¦ÏÖ¹ÿ ƒÛßþ;@ôVü!ÚgüýkŸø=½ÿ ã´Â ¦ÏÖ¹ÿ ƒÛßþ;@ ˆ4½^OÚ AòoõÅÓ'µ72yS8†?/ïÆ06ˆÙ£ƒz÷.3Õk׫œ>Ñšá.]`ΈȒ nór«XæäUr;í •'ü!ÚgüýkŸø=½ÿ ã´¿E` ¦ÏÖ¹ÿ ƒÛßþ;Gü!ÚgüýkŸø=½ÿ ã´¿E` ¦ÏÖ¹ÿ ƒÛßþ;Gü!ÚgüýkŸø=½ÿ ã´¿Eqšöƒm£ÙÚ^Ù^ë :êV)ûÍbêU*÷Q#¯!R
+± õ®Î€
+(¢€
+(¢€
+(¢€
+*½õí¾™§ÜßÝÉåÛ[DÓLûIÚŠ cÉÀ¥bA¡\ëñ^k×zŒ7 °Ú_=¼v„Žc
+ )Žff‚T m´ÑÑX ð‡iŸóõ®àö÷ÿ ŽÑÿ v™ÿ ?Zçþoøí o×ü%Òõ{O x×ûFÿ \šÞÎëìÐ}¾gdŸ'‰pÃIåÇ ŽÄWÿ v™ÿ ?ZçþoøíG ôh^WŠ]a gß+.·x ¶Ð¹oÞòvªŒžÀÔÑÑX ð‡iŸóõ®àö÷ÿ ŽÑÿ v™ÿ ?Zçþoøí oÑX ð‡iŸóõ®àö÷ÿ ŽÑÿ v™ÿ ?Zçþoøí oÑX ð‡iŸóõ®àö÷ÿ ŽÔšuÍÝŽ²Ú%ýÓÞ·76—rª,’¨`²«„r…£;€\‰@Á(Ì@6袊 +Áßò¹ÿ °®£ÿ ¥³Vý`x;þ@—?öÔô¶j ׺¾³±ò>×w¿Ÿ*Á O2Fû¨¹êÇ rj9õm6Öâ[{BÖâ·7RG$ʬƒƒ!ä ?ÅÒ³5íòûPµ»´K±kqc47 ˜ü¹ŒEœ¨ÌÇ”–v† ~uÇ4çðö¤¾#—P·6²@/N§’VFi¾ÇöQ H ŸÌÉ#îì?z€.k~0Ò4}"{ï·ØËåÝ-Ž
+Ò*-Ã0]ŽÜìÛÍÁ*¡Ž1Vƽ¦¥½ýÝÆ£§EggqäI8»R±°
+
+ÈNn¶íÉþÔàr:wƒµØ,ì-®œ¢ -&ÞFŽåÛ沺2Œd{Û+4×´çžù ڪܩ û>R -òœ’Úq ¤šç€ìtÍ.Ö;H’Ùmb–þdVÌ2RTöm^)FKnV*Æ jÚ|Ú5ãÍkww]Ev·$¬êcŒuòñ÷Ì$±(x —¾*ðþg%ÝÞ³c¼wBÊI êBNH [`ðÃ9 ýÐ 8 š}Ÿ‰4-EàK-kN¹yÝÒ‚é ÈÈ¡œ.$)Ðk‘°ð6«gÊù–¬å,¶s!W{9üä!
+â“sebÚ6‡ÉLxWÿ „‚ D¥ˆŒê ©Ê¢áò²Qjñ/îþe º@çˆ
+UAÞ :;=[MÔ..ìµ [™í eÄp̮жHÀr§*x>‡Ò³û9âób2>ò‡Éo—äl1Ër~îWå<ôÉ
+IJýŸ}œñy± yCä·Ëò6å¹?w+òžzd#Áßò¹ÿ °®£ÿ ¥³V½Õõ‘ö»¸-üùV|éy’7ÝEÏV88“Xž‘¦ðä’¼/¾¥¨3E!RÈMäß)ÚHÈéÁ#К“^ѯ/µ [»D±›·3Cz ˘ÄYÊ€|Ìy@ygh`Çç\r§>¦ÚÜKoq¨ZÃîÃ÷«#Nðv»…µÀÓ”Ae¤ÛÈÑÜ»|ÖWFB@1Œ‡Œç¶c‘óP\5í5-ïîî5 :+;;"IÅÚ•€PVBp#pÍ·nOðž§Ä:¶›s¥R
+BÖ]<#9»I•¢
+¹ÜwƒŒ œñƒ\‰ìum<ßj2ÜÚé¯.»å•êÝ +öo!þÐÒBV Ñ£ ?ï%AÛ-¯ ¤šç€ìtÍ.Ö;H’Ùmb–þdVÌ2RTöm^)FKnV*a|c᧽²³M{Nyｪʑ0³å à’ß(É!±§^ø«Ãúuœ—wzÍŒVñÝ )$3© 9 ymƒÃ äƒ÷@$àk/NÐ5m>mñæµ»».¢»
+ˆFÛ‰’Vu1ƺùxû‰æX”< ‹j¶q\¯™jÎRËa72w³ŸÎB® I701¦V-£h| :ë?hZ‹À–ZÖró»¤+Ò9‘‘C8\ HR Õ‹=[MÔ..ìµ [™í eÄp̮жHÀr§*x>‡Ò¹Ááý_þu–"3¨&§*‹‡ÊÈmE«Ä¿»ù”.éœ )Ux“Á> Ô´yP6±³Ám
+µ´:ı†ÎÙdQ!B\íËìÁÃa° .xÇþ@–ßöÓ¿ô¶ß¬ÿ ÈÛþºwþ–ÃZíq*ù˜³¶J‘®
+|êvåÇÍ÷WqÎpß#` — (ªíq*ù˜³¶J‘®
+|êvåÇÍ÷WqÎpß#` —#\J¾f,çm’¤k‚Ÿ:¹qó}ÕÜsœ7ÈØåÈŠ*»\J¾f,çm’¤k‚Ÿ:¹qó}ÕÜsœ7ÈØåÈׯ™‹9Ûd©à§Î§n\|ßuw ç
+ò6ùrbŠ®×¯™‹9Ûd©à§Î§n\|ßuw ç
+ò6ùs™âmjïE𶷪[X<“Ø[É$*å
+É„
+¿ïƒ°r
+ò6ùr Ž¿äŸx—þÁW_ú)«~¼XüHñ‰ü
+Áà]FÖ t)ä:„gl-˜±¼ „1l+;`p“^Ó@þÝgý¡ýŸö¸>Ûåyÿ fó™åçný½vçŒôÍW:î±M)ÕlDpÊðJæá1 ˆ¥Ýç†UVb O¨[è×–þ%»ºÙc-•Íоó$¦ŠAn¶ûq…á7y›³†dÙÎêçÁÚí¦“ ãNš{dÒí#\¼k$6S4¢BDlUÜ»0BõÞÝ(£»ñ†‘k«éÖ o±?lµ–ûÎ{¤T[t\ï wg9 Ô‘³ò`Ø“ÄÚEŽŸcuªêúU—Û"FZõ<¹8ùnÛw¯Ì9ÀÈ àf±ô¿êúv§öÆKû?ö¯‚áÇ›ö›˜çqòþLmelnÇnÎ!qkqá›
+Mà-g¥ZCub·aWQ{iþ˺-ò̬Œ@¦ZHT±äÔµ [MÑíÖãTÔ-l`g²]L±)l€XœÇ±ªx«Ã÷7š¤ZÍ‹\iÛÍäfu fÉû«¸ÝÈ' â¯êúô¶j–6ò,WVÏp×Æ(äd ùf3 ÊÈŸâÖ Í{N·{«µ@e¹UY"ȃŒ ñÏ̓Œí8·»¤\Eq,:Œ‘ÛD³Îép„E.õv üªWæðG=+œÑ<3ªèÓi³(µ”Û=Ünw# *êhçvó ;£)@ý`ÃBJŠø3XƒIk#r#²°±‹uìðï[I·¤›£PÑ»s…'c"s c´º²¾³Ôìã»°»‚êÚLìš £`pÂü+"óþJÿ `«ÿ ýiVü=aw¦h°Û_N“Ýï’YdDEÙÏÜU FìÚ»ˆ,@$Š©yÿ %Fÿ °Uÿ þ´
+ú(¢€
+Àðwü.ì+¨ÿ élÕ¿X—:v¥cs¢5«›§]YÝ–U–@ªÖUÆvª‚68; f tVÛ<_ÿ @=ÿ 2ÿ ò- lñý ô?ü Ëÿ È´¿Erš¶»â F¾Õ.4 ³·’âEX”±TRÄ ÛœQW>Ùâÿ úèø9—ÿ ‘h~ŠÀûg‹ÿ è¡ÿ àæ_þE£íž/ÿ ‡ÿ ƒ™ù€7謶x¿þ€z þeÿ äZ>Ùâÿ úèø9—ÿ ‘h~°:ž•síž/ÿ ‡ÿ ƒ™ù€7謶x¿þ€z þeÿ äZ>Ùâÿ úèø9—ÿ ‘h~ŠÀûg‹ÿ è¡ÿ àæ_þE£íž/ÿ ‡ÿ ƒ™ù€7謶x¿þ€z þeÿ äZ>Ùâÿ úèø9—ÿ ‘h~ŠÀûg‹ÿ è¡ÿ àæ_þE£íž/ÿ ‡ÿ ƒ™ù€ÿ ÈÛþºwþ–Ã[õÊj6Þ)Ö"¶µ¸Ó4{höÖâIcÔå•‚Å:J@Sn ’ GZêè ¢Š( ¢Š( ¢Š(Ç_òO¼Kÿ `«¯ýÕ¿EsXkº
+¼Vñ/ý‚®¿ôSVý`xëþI÷‰ìuÿ ¢š·è ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¬ÈoÅöOý"¶úÀð÷ü†üWÿ aTÿ Ò+j ߢŠ( ¢Š( ¢Š( ¢Š( ¢Šã4 ÛX³»½½½ÖvÔ¯“÷zÅÔJ.¥ER@ P0 é@ ÿ v™ÿ ?Zçþoøí ð‡iŸóõ®àö÷ÿ ŽÐÆ{[ˆœ¶3ßE5¶ÙY- ¯›;$Y ûÑìvb:| žÿ ÚÞYø F‹Pžú{ÖµIn ýËL$q½•‰çå,TÈ Õ þѮ巸—Xš P¤‘ÉÞ2º‘‚2à‚;TŸð‡iŸóõ®àö÷ÿ ŽÐýÿ v™ÿ ?Zçþoøí ð‡iŸóõ®àö÷ÿ ŽÐýÈ]éè¾ ðÜ–Wz¯úF¡$2¤ú¥Ìèéö[‡ÁY$eûȧ§jëè ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢Š( ¢± ÊñK¬#ÌûåeÖïvÚ-ûÞNÕQ“ØÚ€::+þí3þ~µÏü Þÿ ñÚ?áÓ?çë\ÿ Áíïÿ
+ú+þí3þ~µÏü Þÿ ñÚ?áÓ?çë\ÿ Áíïÿ
+ú+œð¬FÖóÄVKqu4Ú’¤?j¹’vE6¶î@i›™Ž3Ü×G@Q@`x;þ@—?öÔô¶j߬Èçþºþ–Í@÷WÖv>GÚîà·óåX!ó¤ æHßu=XààMG>¦ÚÜKoq¨ZÃc¸U} Æ–zœZÕõÀƒOÒ4ë¡m íÍÈQ>UÌäXÛÌB¸ï ϸð®¯{}¬\™`±šçPÛ\Ú]¿š-ÞíæV>XÚÛ#¨1cÎBe£“Âz®u†×N†ÛûJ;»;{{É &%¶á<ÄŒ5¹³ ì‚ÑŸ”’@:Hõ;!Ôt۸ෆÚ+Ya¸3ÿ óÞHÕH*6¶øÈ ÎåèN(Õ¼O¤hÚ~«ws}eD%º†9PÈ™E*HÃ?E$b¹‹/júT¶W¶¯c5ÙØÚ¤Ó:Å2ÂÓ#³‡c4R‚¥AdbË’…·×—Àz·üTpÆö.º„Z„v×RÝ\TºË˜¼’LqâB ‘3¹P|™b@üþ-ÙÛe^þöÂ+”¶Ô·´?ip€üËó£);w©còàn߆úÎâòâÒ¸$¹¶ÛçÂ’ñn]Ê9\ŽFz×!â
+ ÄwºýÝÕ…®”öÒÿ gl3ßIÿ ¢Ü4ç*!`7+Ôãç8h Ô4Þ^Ème·’âêX®
+ÕÃH"Ä•ó0LŠ~`€‹ Ί( ÈoÅöOý"¶úÀð÷ü†üWÿ aTÿ Ò+jß Š( ¸
+ø¯ÃšfŸyiâ
+*Öæ=WPß ÷‘£®o&#*NFAñ®ÞŠ Àÿ „ë ô5hø0‹ÿ Š£þ¯ÐÕ¡ÿ àÂ/þ*·è øN¼!ÿ CV‡ÿ ƒ¿øª?á:ð‡ý
+Z þ "ÿ â«~Š Àÿ „ë ô5hø0‹ÿ Š£þ¯ÐÕ¡ÿ àÂ/þ*·è 2ÿ Äš±â? [ézÖ}:êR;Gkt’°_±ÜŒ¤œdŽ}ÅvtQ@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@ :ÿ ’}â_û]覣þ¯ÐÕ¡ÿ àÂ/þ*·è øN¼!ÿ CV‡ÿ ƒ¿øª?á:ð‡ý
+Z þ "ÿ â«~Š Àÿ „ë ô5hø0‹ÿ Š£þ¯ÐÕ¡ÿ àÂ/þ*·è øN¼!ÿ CV‡ÿ ƒ¿øª?á:ð‡ý
+Z þ "ÿ â«~Š Àÿ „ë ô5hø0‹ÿ Š£þ¯ÐÕ¡ÿ àÂ/þ*·è cÂ7Özž¡â‹» ¸.¤ÕSdÐH vÀá‡øWOE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QEÿÙ
\ No newline at end of file
Index: configdev.fig
===================================================================
--- configdev.fig (nonexistent)
+++ configdev.fig (revision 1765)
@@ -0,0 +1,80 @@
+#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
Index: configure.info-1
===================================================================
--- configure.info-1 (nonexistent)
+++ configure.info-1 (revision 1765)
@@ -0,0 +1,1313 @@
+This is configure.info, produced by makeinfo version 4.1 from
+./configure.texi.
+
+INFO-DIR-SECTION GNU admin
+START-INFO-DIR-ENTRY
+* configure: (configure). The GNU configure and build system
+END-INFO-DIR-ENTRY
+
+ 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.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+
+File: configure.info, Node: Top, Next: Introduction, Up: (dir)
+
+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.
+
+
+File: configure.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top
+
+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.
+
+ This document draws on several sources, including the autoconf
+manual by David MacKenzie (*note autoconf overview: (autoconf)Top.),
+the automake manual by David MacKenzie and Tom Tromey (*note automake
+overview: (automake)Top.), the libtool manual by Gordon Matzigkeit
+(*note libtool overview: (libtool)Top.), and the Cygnus configure
+manual by K. Richard Pixley.
+
+* Menu:
+
+* Goals:: Goals.
+* Tools:: The tools.
+* History:: History.
+* Building:: Building.
+
+
+File: configure.info, Node: Goals, Next: Tools, Up: Introduction
+
+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.
+
+
+File: configure.info, Node: Tools, Next: History, Prev: Goals, Up: Introduction
+
+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.
+
+autoconf
+ provides a general portability framework, based on testing the
+ features of the host system at build time.
+
+automake
+ a system for describing how to build a program, permitting the
+ developer to write a simplified `Makefile'.
+
+libtool
+ a standardized approach to building shared libraries.
+
+gettext
+ provides a framework for translation of text messages into other
+ languages; not really discussed in this document.
+
+m4
+ autoconf requires the GNU version of m4; the standard Unix m4 does
+ not suffice.
+
+perl
+ automake requires perl.
+
+
+File: configure.info, Node: History, Next: Building, Prev: Tools, Up: Introduction
+
+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 `#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:
+ * The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael
+ Manfredi.
+
+ * 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.
+
+ * The autoconf program, by David MacKenzie.
+
+ 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.
+
+
+File: configure.info, Node: Building, Prev: History, Up: Introduction
+
+Building
+========
+
+ Most readers of this document should already know how to build a
+tool by running `configure' and `make'. This section may serve as a
+quick introduction or reminder.
+
+ Building a tool is normally as simple as running `configure'
+followed by `make'. You should normally run `configure' from an empty
+directory, using some path to refer to the `configure' script in the
+source directory. The directory in which you run `configure' is called
+the "object directory".
+
+ In order to use a object directory which is different from the source
+directory, you must be using the GNU version of `make', which has the
+required `VPATH' support. Despite this restriction, using a different
+object directory is highly recommended:
+ * It keeps the files generated during the build from cluttering up
+ your sources.
+
+ * It permits you to remove the built files by simply removing the
+ entire build directory.
+
+ * It permits you to build from the same sources with several sets of
+ configure options simultaneously.
+
+ If you don't have GNU `make', you will have to run `configure' in
+the source directory. All GNU packages should support this; in
+particular, GNU packages should not assume the presence of GNU `make'.
+
+ After running `configure', you can build the tools by running `make'.
+
+ To install the tools, run `make install'. Installing the tools will
+copy the programs and any required support files to the "installation
+directory". The location of the installation directory is controlled
+by `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 `make info'. To
+install them, run `make install-info'.
+
+ All `configure' scripts support a wide variety of options. The most
+interesting ones are `--with' and `--enable' options which are
+generally specific to particular tools. You can usually use the
+`--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 `--prefix'
+and `--exec-prefix' options. These options are used to specify the
+installation directory.
+
+ The directory named by the `--prefix' option will hold machine
+independent files such as info files.
+
+ The directory named by the `--exec-prefix' option, which is normally
+a subdirectory of the `--prefix' directory, will hold machine dependent
+files such as executables.
+
+ The default for `--prefix' is `/usr/local'. The default for
+`--exec-prefix' is the value used for `--prefix'.
+
+ The convention used in Cygnus releases is to use a `--prefix' option
+of `/usr/cygnus/RELEASE', where RELEASE is the name of the release, and
+to use a `--exec-prefix' option of `/usr/cygnus/RELEASE/H-HOST', where
+HOST is the configuration name of the host system (*note Configuration
+Names::).
+
+ Do not use either the source or the object directory as the
+installation directory. That will just lead to confusion.
+
+
+File: configure.info, Node: Getting Started, Next: Files, Prev: Introduction, Up: Top
+
+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.
+
+
+File: configure.info, Node: Write configure.in, Next: Write Makefile.am, Up: Getting Started
+
+Write configure.in
+==================
+
+ You must first write the 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 `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 `gettimeofday' function.
+If you want to use the `gettimeofday' function when it is available,
+and to use some other function when it is not, you would check for this
+by putting `AC_CHECK_FUNCS(gettimeofday)' in `configure.in'.
+
+ When the configure script is run at build time, this will arrange to
+define the preprocessor macro `HAVE_GETTIMEOFDAY' to the value 1 if the
+`gettimeofday' function is available, and to not define the macro at
+all if the function is not available. Your code can then use `#ifdef'
+to test whether it is safe to call `gettimeofday'.
+
+ If you have an existing body of code, the `autoscan' program may
+help identify potential portability problems, and hence configure tests
+that you will want to use. *Note Invoking autoscan: (autoconf)Invoking
+autoscan.
+
+ Another handy tool for an existing body of code is `ifnames'. This
+will show you all the preprocessor conditionals that the code already
+uses. *Note Invoking ifnames: (autoconf)Invoking ifnames.
+
+ Besides the portability tests which are specific to your particular
+package, every `configure.in' file should contain the following macros.
+
+`AC_INIT'
+ This macro takes a single argument, which is the name of a file in
+ your package. For example, `AC_INIT(foo.c)'.
+
+`AC_PREREQ(VERSION)'
+ This macro is optional. It may be used to indicate the version of
+ `autoconf' that you are using. This will prevent users from
+ running an earlier version of `autoconf' and perhaps getting an
+ invalid `configure' script. For example, `AC_PREREQ(2.12)'.
+
+`AM_INIT_AUTOMAKE'
+ This macro takes two arguments: the name of the package, and a
+ version number. For example, `AM_INIT_AUTOMAKE(foo, 1.0)'. (This
+ macro is not needed if you are not using automake).
+
+`AM_CONFIG_HEADER'
+ This macro names the header file which will hold the preprocessor
+ macro definitions at run time. Normally this should be
+ `config.h'. Your sources would then use `#include "config.h"' to
+ include it.
+
+ This macro may optionally name the input file for that header
+ file; by default, this is `config.h.in', but that file name works
+ poorly on DOS filesystems. Therefore, it is often better to name
+ it explicitly as `config.in'.
+
+ This is what you should normally put in `configure.in':
+ AM_CONFIG_HEADER(config.h:config.in)
+
+ (If you are not using automake, use `AC_CONFIG_HEADER' rather than
+ `AM_CONFIG_HEADER').
+
+`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 `--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
+ `PATH'.
+
+ (If you are not using automake, you do not need to use this macro).
+
+`AC_EXEEXT'
+ Either this macro or `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 `.exe'. This macro directs automake to use the
+ executable suffix as appropriate when creating programs. This
+ macro does not take any arguments.
+
+ The `AC_EXEEXT' form is new, and is part of a Cygnus patch to
+ autoconf to support compiling with Visual C++. Older programs use
+ `AM_EXEEXT' instead.
+
+ (Programs which do not use automake use neither `AC_EXEEXT' nor
+ `AM_EXEEXT').
+
+`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 `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 `AC_PROG_CC'. Instead, you will want to use a
+ variant which does not call the macro `AC_PROG_CC_WORKS'. Examples
+ can be found in various `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.
+
+`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 `AC_PROG_CC'.
+
+`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.
+
+ By default, this will cause all libraries to be built as shared
+ libraries. To prevent this-to change the default-use
+ `AM_DISABLE_SHARED' before `AM_PROG_LIBTOOL'. The configure
+ options `--enable-shared' and `--disable-shared' may be used to
+ override the default at build time.
+
+`AC_DEFINE(_GNU_SOURCE)'
+ GNU packages should normally include this line before any other
+ feature tests. This defines the macro `_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.
+
+`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 `Makefile'
+ files in different directories. If your package lives entirely in
+ a single directory, you would use simply `AC_OUTPUT(Makefile)'.
+ If you also have, for example, a `lib' subdirectory, you would use
+ `AC_OUTPUT(Makefile lib/Makefile)'.
+
+ If you want to use locally defined macros in your `configure.in'
+file, then you will need to write a `acinclude.m4' file which defines
+them (if not using automake, this file is called `aclocal.m4').
+Alternatively, you can put separate macros in an `m4' subdirectory, and
+put `ACLOCAL_AMFLAGS = -I m4' in your `Makefile.am' file so that the
+`aclocal' program will be able to find them.
+
+ The different macro prefixes indicate which tool defines the macro.
+Macros which start with `AC_' are part of autoconf. Macros which start
+with `AM_' are provided by automake or libtool.
+
+
+File: configure.info, Node: Write Makefile.am, Next: Write acconfig.h, Prev: Write configure.in, Up: Getting Started
+
+Write Makefile.am
+=================
+
+ You must write the 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 `Makefile.am' mostly look like variable
+assignments in a `Makefile'. automake recognizes special variable
+names, and automatically add make rules to the output as needed.
+
+ There will be one `Makefile.am' file for each directory in your
+package. For each directory with subdirectories, the `Makefile.am'
+file should contain the line
+ SUBDIRS = DIR DIR ...
+
+where each DIR is the name of a subdirectory.
+
+ For each `Makefile.am', there should be a corresponding `Makefile'
+in the `AC_OUTPUT' macro in `configure.in'.
+
+ Every `Makefile.am' written at Cygnus should contain the line
+ AUTOMAKE_OPTIONS = cygnus
+
+This puts automake into Cygnus mode. See the automake manual for
+details.
+
+ You may to include the version number of `automake' that you are
+using on the `AUTOMAKE_OPTIONS' line. For example,
+ AUTOMAKE_OPTIONS = cygnus 1.3
+
+This will prevent users from running an earlier version of `automake'
+and perhaps getting an invalid `Makefile.in'.
+
+ If your package builds a program, then in the directory where that
+program is built you will normally want a line like
+ bin_PROGRAMS = PROGRAM
+
+where PROGRAM is the name of the program. You will then want a line
+like
+ PROGRAM_SOURCES = FILE FILE ...
+
+where each FILE is the name of a source file to link into the program
+(e.g., `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
+ lib_LIBRARIES = libNAME.a
+
+where `libNAME.a' is the name of the library. You will then want a
+line like
+ libNAME_a_SOURCES = FILE FILE ...
+
+where each 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
+ lib_LTLIBRARIES = libNAME.la
+ The use of `LTLIBRARIES', and the `.la' extension, indicate a
+library to be built using libtool. As usual, you will then want a line
+like
+ libNAME_la_SOURCES = FILE FILE ...
+
+ The strings `bin' and `lib' that appear above in `bin_PROGRAMS' and
+`lib_LIBRARIES' are not arbitrary. They refer to particular
+directories, which may be set by the `--bindir' and `--libdir' options
+to `configure'. If those options are not used, the default values are
+based on the `--prefix' or `--exec-prefix' options to `configure'. It
+is possible to use other names if the program or library should be
+installed in some other directory.
+
+ The `Makefile.am' file may also contain almost anything that may
+appear in a normal `Makefile'. automake also supports many other
+special variables, as well as conditionals.
+
+ See the automake manual for more information.
+
+
+File: configure.info, Node: Write acconfig.h, Next: Generate files, Prev: Write Makefile.am, Up: Getting Started
+
+Write acconfig.h
+================
+
+ If you are generating a portability header file, (i.e., you are using
+`AM_CONFIG_HEADER' in `configure.in'), then you will have to write a
+`acconfig.h' file. It will have to contain the following lines.
+
+ /* Name of package. */
+ #undef PACKAGE
+
+ /* Version of package. */
+ #undef VERSION
+
+ This requirement is really a bug in the system, and the requirement
+may be eliminated at some later date.
+
+ The `acconfig.h' file will also similar comment and `#undef' lines
+for any unusual macros in the `configure.in' file, including any macro
+which appears in a `AC_DEFINE' macro.
+
+ In particular, if you are writing a GNU package and therefore include
+`AC_DEFINE(_GNU_SOURCE)' in `configure.in' as suggested above, you will
+need lines like this in `acconfig.h':
+ /* Enable GNU extensions. */
+ #undef _GNU_SOURCE
+
+ Normally the `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 `configure.in' file, you will
+have to make sure that the right entries appear in `acconfig.h', since
+otherwise the results of the tests may not be available in the
+`config.h' file which your code will use.
+
+ (Thee `PACKAGE' and `VERSION' lines are not required if you are not
+using automake, and in that case you may not need a `acconfig.h' file
+at all).
+
+
+File: configure.info, Node: Generate files, Next: Getting Started Example, Prev: Write acconfig.h, Up: Getting Started
+
+Generate files
+==============
+
+ Once you have written `configure.in', `Makefile.am', `acconfig.h',
+and possibly `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.
+
+ aclocal
+ autoconf
+ autoheader
+ automake
+
+ The `aclocal' and `automake' commands are part of the automake
+package, and the `autoconf' and `autoheader' commands are part of the
+autoconf package.
+
+ If you are using a `m4' subdirectory for your macros, you will need
+to use the `-I m4' option when you run `aclocal'.
+
+ If you are not using the Cygnus tree, use the `-a' option when
+running `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 `--prefix' and `--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 `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 `configure'
+script which will have been created by `autoconf' with the
+`--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 `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.
+
+
+File: configure.info, Node: Getting Started Example, Prev: Generate files, Up: Getting Started
+
+Example
+=======
+
+ Let's consider a trivial example.
+
+ Suppose we want to write a simple version of `touch'. Our program,
+which we will call `poke', will take a single file name argument, and
+use the `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.
+
+
+File: configure.info, Node: Getting Started Example 1, Next: Getting Started Example 2, Up: Getting Started Example
+
+First Try
+---------
+
+ Here is our first try at `poke.c'. Note that we've written it
+without ANSI/ISO C prototypes, since we want it to be highly portable.
+
+ #include
+ #include
+ #include
+ #include
+
+ 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);
+ }
+
+ We also write a simple `Makefile'.
+
+ CC = gcc
+ CFLAGS = -g -O2
+
+ all: poke
+
+ poke: poke.o
+ $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o
+
+ So far, so good.
+
+ Unfortunately, there are a few problems.
+
+ On older Unix systems derived from BSD 4.3, the `utime' system call
+does not accept a second argument of `NULL'. On those systems, we need
+to pass a pointer to `struct utimbuf' structure. Unfortunately, even
+older systems don't define that structure; on those systems, we need to
+pass an array of two `long' values.
+
+ The header 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 `exit'.
+
+ We can find some of these portability problems by running
+`autoscan', which will create a `configure.scan' file which we can use
+as a prototype for our `configure.in' file. I won't show the output,
+but it will notice the potential problems with `utime' and `stdlib.h'.
+
+ In our `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 `install' target. For that matter, we will also want a
+`clean' target.
+
+
+File: configure.info, Node: Getting Started Example 2, Next: Getting Started Example 3, Prev: Getting Started Example 1, Up: Getting Started Example
+
+Second Try
+----------
+
+ Here is our second try at this program.
+
+ We modify `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).
+
+ #include
+
+ #ifdef STDC_HEADERS
+ #include
+ #endif
+
+ #include
+
+ #ifdef HAVE_UTIME_H
+ #include
+ #endif
+
+ #ifndef HAVE_UTIME_NULL
+
+ #include
+
+ #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);
+ }
+
+ Here is the associated `Makefile'. We've added support for the
+preprocessor flags we use. We've also added `install' and `clean'
+targets.
+
+ # 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
+
+ Some problems with this approach should be clear.
+
+ Users who want to compile poke will have to know how `utime' works
+on their systems, so that they can uncomment the `Makefile' correctly.
+
+ The installation is done using `cp', but many systems have an
+`install' program which may be used, and which supports optional
+features such as stripping debugging information out of the installed
+binary.
+
+ The use of `Makefile' variables like `CC', `CFLAGS' and `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.
+
+
+File: configure.info, Node: Getting Started Example 3, Next: Generate Files in Example, Prev: Getting Started Example 2, Up: Getting Started Example
+
+Third Try
+---------
+
+ For our third try at this program, we will write a `configure.in'
+script to discover the configuration features on the host system, rather
+than requiring the user to edit the `Makefile'. We will also write a
+`Makefile.am' rather than a `Makefile'.
+
+ The only change to `poke.c' is to add a line at the start of the
+file:
+ #include "config.h"
+
+ The new `configure.in' file is as follows.
+
+ 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)
+
+ The first four macros in this file, and the last one, were described
+above; see *Note Write configure.in::. If we omit these macros, then
+when we run `automake' we will get a reminder that we need them.
+
+ The other macros are standard autoconf macros.
+
+`AC_HEADER_STDC'
+ Check for standard C headers.
+
+`AC_CHECK_HEADERS'
+ Check whether a particular header file exists.
+
+`AC_EGREP_HEADER'
+ Check for a particular string in a particular header file, in this
+ case checking for `utimbuf' in `utime.h'.
+
+`AC_FUNC_UTIME_NULL'
+ Check whether `utime' accepts a NULL second argument to set the
+ file change time to the current time.
+
+ See the autoconf manual for a more complete description.
+
+ The new `Makefile.am' file is as follows. Note how simple this is
+compared to our earlier `Makefile'.
+
+ bin_PROGRAMS = poke
+
+ poke_SOURCES = poke.c
+
+ This means that we should build a single program name `poke'. It
+should be installed in the binary directory, which we called `bindir'
+earlier. The program `poke' is built from the source file `poke.c'.
+
+ We must also write a `acconfig.h' file. Besides `PACKAGE' and
+`VERSION', which must be mentioned for all packages which use automake,
+we must include `HAVE_STRUCT_UTIMBUF', since we mentioned it in an
+`AC_DEFINE'.
+
+ /* Name of package. */
+ #undef PACKAGE
+
+ /* Version of package. */
+ #undef VERSION
+
+ /* Whether utime.h defines struct utimbuf. */
+ #undef HAVE_STRUCT_UTIMBUF
+
+
+File: configure.info, Node: Generate Files in Example, Prev: Getting Started Example 3, Up: Getting Started Example
+
+Generate Files
+--------------
+
+ We must now generate the other files, using the following commands.
+
+ aclocal
+ autoconf
+ autoheader
+ automake
+
+ When we run `autoheader', it will remind us of any macros we forgot
+to add to `acconfig.h'.
+
+ When we run `automake', it will want to add some files to our
+distribution. It will add them automatically if we use the
+`--add-missing' option.
+
+ By default, `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 `NEWS', `README', `AUTHORS', and `ChangeLog', all of which
+are files which should appear in a standard GNU distribution. We can
+either add those files, or run `automake' with the `--foreign' option.
+
+ Running these tools will generate the following files, all of which
+are described in the next chapter.
+
+ * `aclocal.m4'
+
+ * `configure'
+
+ * `config.in'
+
+ * `Makefile.in'
+
+ * `stamp-h.in'
+
+
+File: configure.info, Node: Files, Next: Configuration Names, Prev: Getting Started, Up: Top
+
+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.
+
+
+File: configure.info, Node: Developer Files, Next: Build Files, Up: Files
+
+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.
+
+
+File: configure.info, Node: Developer Files Picture, Next: Written Developer Files, Up: Developer Files
+
+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. The file names
+are plain text and the tool names are enclosed by `*' characters (e.g.,
+`autoheader' is the name of a tool, not the name of a file).
+
+ 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
+
+
+File: configure.info, Node: Written Developer Files, Next: Generated Developer Files, Prev: Developer Files Picture, Up: Developer Files
+
+Written Developer Files
+-----------------------
+
+ The following files would be written by the developer.
+
+`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 `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. *Note Write configure.in::.
+
+`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 `Makefile.in' directly). *Note Write
+ Makefile.am::.
+
+`acconfig.h'
+ When the configure script creates a portability header file, by
+ using `AM_CONFIG_HEADER' (or, if not using automake,
+ `AC_CONFIG_HEADER'), this file is used to describe macros which are
+ not recognized by the `autoheader' command. This is normally a
+ fairly uninteresting file, consisting of a collection of `#undef'
+ lines with comments. Normally any call to `AC_DEFINE' in
+ `configure.in' will require a line in this file. *Note Write
+ acconfig.h::.
+
+`acinclude.m4'
+ This file is not always required. It defines local autoconf
+ macros. These macros may then be used in `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 `configure.in', but
+ sometimes a local macro is convenient.
+
+ Newer tools may omit `acinclude.m4', and instead use a
+ subdirectory, typically named `m4', and define `ACLOCAL_AMFLAGS =
+ -I m4' in `Makefile.am' to force `aclocal' to look there for macro
+ definitions. The macro definitions are then placed in separate
+ files in that directory.
+
+ The `acinclude.m4' file is only used when using automake; in older
+ tools, the developer writes `aclocal.m4' directly, if it is needed.
+
+
+File: configure.info, Node: Generated Developer Files, Prev: Written Developer Files, Up: Developer Files
+
+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 `Makefile' contains rules
+to automatically rebuild the files as required. When
+`AM_MAINTAINER_MODE' is used in `configure.in' (the normal case in
+Cygnus code), the automatic rebuilding rules will only be defined if
+you configure using the `--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 `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.
+
+`configure'
+ This is the configure script which will be run when building the
+ package. This is generated by `autoconf' from `configure.in' and
+ `aclocal.m4'. This is a shell script.
+
+`Makefile.in'
+ This is the file which the configure script will turn into the
+ `Makefile' at build time. This file is generated by `automake'
+ from `Makefile.am'. If you aren't using automake, you must write
+ this file yourself. This file is pretty much a normal `Makefile',
+ with some configure substitutions for certain variables.
+
+`aclocal.m4'
+ This file is created by the `aclocal' program, based on the
+ contents of `configure.in' and `acinclude.m4' (or, as noted in the
+ description of `acinclude.m4' above, on the contents of an `m4'
+ subdirectory). This file contains definitions of autoconf macros
+ which `autoconf' will use when generating the file `configure'.
+ These autoconf macros may be defined by you in `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 `configure.in' uses only
+ standard autoconf macros, this file will not be needed at all.
+
+`config.in'
+ This file is created by `autoheader' based on `acconfig.h' and
+ `configure.in'. At build time, the configure script will define
+ some of the macros in it to create `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
+ `config.h.in'.
+
+`stamp.h-in'
+ This rather uninteresting file, which I omitted from the picture,
+ is generated by `automake'. It always contains the string
+ `timestamp'. It is used as a timestamp file indicating whether
+ `config.in' is up to date. Using a timestamp file means that
+ `config.in' can be marked as up to date without actually changing
+ its modification time. This is useful since `config.in' depends
+ upon `configure.in', but it is easy to change `configure.in' in a
+ way which does not affect `config.in'.
+
+
+File: configure.info, Node: Build Files, Next: Support Files, Prev: Developer Files, Up: Files
+
+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.
+
+
+File: configure.info, Node: Build Files Picture, Next: Build Files Description, Up: Build Files
+
+Build Files Picture
+-------------------
+
+ Here is a picture of the files which will be created at build time.
+`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.
+
+ config.in *configure* Makefile.in
+ | | |
+ | v |
+ | config.status |
+ | | |
+ *config.status*<======+==========>*config.status*
+ | |
+ v v
+ config.h Makefile
+
+
+File: configure.info, Node: Build Files Description, Prev: Build Files Picture, Up: Build Files
+
+Build Files Description
+-----------------------
+
+ This is a description of the files which are created at build time.
+
+`config.status'
+ The first step in building a package is to run the `configure'
+ script. The `configure' script will create the file
+ `config.status', which is itself a shell script. When you first
+ run `configure', it will automatically run `config.status'. An
+ `Makefile' derived from an automake generated `Makefile.in' will
+ contain rules to automatically run `config.status' again when
+ necessary to recreate certain files if their inputs change.
+
+`Makefile'
+ This is the file which make will read to build the program. The
+ `config.status' script will transform `Makefile.in' into
+ `Makefile'.
+
+`config.h'
+ This file defines C preprocessor macros which C code can use to
+ adjust its behaviour on different systems. The `config.status'
+ script will transform `config.in' into `config.h'.
+
+`config.cache'
+ This file did not fit neatly into the picture, and I omitted it.
+ It is used by the `configure' script to cache results between
+ runs. This can be an important speedup. If you modify
+ `configure.in' in such a way that the results of old tests should
+ change (perhaps you have added a new library to `LDFLAGS'), then
+ you will have to remove `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 `configure' scripts on your
+ system.
+
+`stamp.h'
+ This file, which I omitted from the picture, is similar to
+ `stamp-h.in'. It is used as a timestamp file indicating whether
+ `config.h' is up to date. This is useful since `config.h' depends
+ upon `config.status', but it is easy for `config.status' to change
+ in a way which does not affect `config.h'.
+
+
+File: configure.info, Node: Support Files, Prev: Build Files, Up: Files
+
+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
+`automake' (with the `--add-missing' option) and `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 `AC_CONFIG_AUX_DIR'
+macro in `configure.in' to tell `automake' and the `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.
+
+`ABOUT-NLS'
+ Added by automake if you are using gettext. This is a
+ documentation file about the gettext project.
+
+`ansi2knr.c'
+ Used by an automake generated `Makefile' if you put `ansi2knr' in
+ `AUTOMAKE_OPTIONS' in `Makefile.am'. This permits compiling ANSI
+ C code with a K&R C compiler.
+
+`ansi2knr.1'
+ The man page which goes with `ansi2knr.c'.
+
+`config.guess'
+ A shell script which determines the configuration name for the
+ system on which it is run.
+
+`config.sub'
+ A shell script which canonicalizes a configuration name entered by
+ a user.
+
+`elisp-comp'
+ Used to compile Emacs LISP files.
+
+`install-sh'
+ A shell script which installs a program. This is used if the
+ configure script can not find an install binary.
+
+`ltconfig'
+ Used by libtool. This is a shell script which configures libtool
+ for the particular system on which it is used.
+
+`ltmain.sh'
+ Used by libtool. This is the actual libtool script which is used,
+ after it is configured by `ltconfig' to build a library.
+
+`mdate-sh'
+ A shell script used by an automake generated `Makefile' to pretty
+ print the modification time of a file. This is used to maintain
+ version numbers for texinfo files.
+
+`missing'
+ A shell script used if some tool is missing entirely. This is
+ used by an automake generated `Makefile' to avoid certain sorts of
+ timestamp problems.
+
+`mkinstalldirs'
+ A shell script which creates a directory, including all parent
+ directories. This is used by an automake generated `Makefile'
+ during installation.
+
+`texinfo.tex'
+ Required if you have any texinfo files. This is used when
+ converting Texinfo files into DVI using `texi2dvi' and TeX.
+
+`ylwrap'
+ A shell script used by an automake generated `Makefile' to run
+ programs like `bison', `yacc', `flex', and `lex'. These programs
+ default to producing output files with a fixed name, and the
+ `ylwrap' script runs them in a subdirectory to avoid file name
+ conflicts when using a parallel make program.
+
+
+File: configure.info, Node: Configuration Names, Next: Cross Compilation Tools, Prev: Files, Up: Top
+
+Configuration Names
+*******************
+
+ The GNU configure system names all systems using a "configuration
+name". All such names used to be triplets (they may now contain four
+parts in certain cases), and the term "configuration triplet" is still
+seen.
+
+* Menu:
+
+* Configuration Name Definition:: Configuration Name Definition.
+* Using Configuration Names:: Using Configuration Names.
+
Index: configure.info-2
===================================================================
--- configure.info-2 (nonexistent)
+++ configure.info-2 (revision 1765)
@@ -0,0 +1,1137 @@
+This is configure.info, produced by makeinfo version 4.1 from
+./configure.texi.
+
+INFO-DIR-SECTION GNU admin
+START-INFO-DIR-ENTRY
+* configure: (configure). The GNU configure and build system
+END-INFO-DIR-ENTRY
+
+ 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.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+
+File: configure.info, Node: Configuration Name Definition, Next: Using Configuration Names, Up: Configuration Names
+
+Configuration Name Definition
+=============================
+
+ This is a string of the form CPU-MANUFACTURER-OPERATING_SYSTEM. In
+some cases, this is extended to a four part form:
+CPU-MANUFACTURER-KERNEL-OPERATING_SYSTEM.
+
+ When using a configuration name in a configure option, it is normally
+not necessary to specify an entire name. In particular, the
+MANUFACTURER field is often omitted, leading to strings such as
+`i386-linux' or `sparc-sunos'. The shell script `config.sub' will
+translate these shortened strings into the canonical form. autoconf
+will arrange for `config.sub' to be run automatically when it is needed.
+
+ The fields of a configuration name are as follows:
+
+CPU
+ The type of processor. This is typically something like `i386' or
+ `sparc'. More specific variants are used as well, such as
+ `mipsel' to indicate a little endian MIPS processor.
+
+MANUFACTURER
+ A somewhat freeform field which indicates the manufacturer of the
+ system. This is often simply `unknown'. Other common strings are
+ `pc' for an IBM PC compatible system, or the name of a workstation
+ vendor, such as `sun'.
+
+OPERATING_SYSTEM
+ The name of the operating system which is run on the system. This
+ will be something like `solaris2.5' or `irix6.3'. There is no
+ particular restriction on the version number, and strings like
+ `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 `elf' or `coff'.
+
+KERNEL
+ This is used mainly for GNU/Linux. A typical GNU/Linux
+ configuration name is `i586-pc-linux-gnulibc1'. In this case the
+ kernel, `linux', is separated from the operating system,
+ `gnulibc1'.
+
+ The shell script `config.guess' will normally print the correct
+configuration name for the system on which it is run. It does by
+running `uname' and by examining other characteristics of the system.
+
+ Because `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.
+
+
+File: configure.info, Node: Using Configuration Names, Prev: Configuration Name Definition, Up: Configuration Names
+
+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 `configure.in'. The case statement might look something
+like the following, assuming that `host' is a shell variable holding a
+canonical configuration name (which will be the case if `configure.in'
+uses the `AC_CANONICAL_HOST' or `AC_CANONICAL_SYSTEM' macro).
+
+ case "${host}" in
+ i[3456]86-*-linux-gnu*) do something ;;
+ sparc*-sun-solaris2.[56789]*) do something ;;
+ sparc*-sun-solaris*) do something ;;
+ mips*-*-elf*) do something ;;
+ esac
+
+ It is particularly important to use `*' after the operating system
+field, in order to match the version number which will be generated by
+`config.guess'.
+
+ In most cases you must be careful to match a range of processor
+types. For most processor families, a trailing `*' suffices, as in
+`mips*' above. For the i386 family, something along the lines of
+`i[3456]86' suffices at present. For the m68k family, you will need
+something like `m68*'. Of course, if you do not need to match on the
+processor, it is simpler to just replace the entire field by a `*', as
+in `*-*-irix*'.
+
+
+File: configure.info, Node: Cross Compilation Tools, Next: Canadian Cross, Prev: Configuration Names, Up: Top
+
+Cross Compilation Tools
+***********************
+
+ The GNU configure and build system can be used to build "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
+
+
+File: configure.info, Node: Cross Compilation Concepts, Next: Host and Target, Up: Cross Compilation Tools
+
+Cross Compilation Concepts
+==========================
+
+ A compiler which produces programs which run on a different system
+is a cross compilation compiler, or simply a "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 "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.
+
+
+File: configure.info, Node: Host and Target, Next: Using the Host Type, Prev: Cross Compilation Concepts, Up: Cross Compilation Tools
+
+Host and Target
+===============
+
+ 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 "host" system.
+
+ The system for which the tools generate code is called the "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 `i386-linux-gnu' cross `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 `gcc' or the `binutils' which
+actually produce running code. For example, it does not make sense to
+speak of the target of a tool like `bison' or `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.
+
+
+File: configure.info, Node: Using the Host Type, Next: Specifying the Target, Prev: Host and Target, Up: Cross Compilation Tools
+
+Using the Host Type
+===================
+
+ In almost all cases the host system is the system on which you run
+the `configure' script, and on which you build the tools (for the case
+when they differ, *note Canadian Cross::).
+
+ 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 `AC_CANONICAL_HOST' in
+`configure.in'. This macro will arrange to define a few shell
+variables when the `configure' script is run.
+
+`host'
+ The canonical configuration name of the host. This will normally
+ be determined by running the `config.guess' shell script, although
+ the user is permitted to override this by using an explicit
+ `--host' option.
+
+`host_alias'
+ In the unusual case that the user used an explicit `--host' option,
+ this will be the argument to `--host'. In the normal case, this
+ will be the same as the `host' variable.
+
+`host_cpu'
+`host_vendor'
+`host_os'
+ The first three parts of the canonical configuration name.
+
+ The shell variables may be used by putting shell code in
+`configure.in'. For an example, see *Note Using Configuration Names::.
+
+
+File: configure.info, Node: Specifying the Target, Next: Using the Target Type, Prev: Using the Host Type, Up: Cross Compilation Tools
+
+Specifying the Target
+=====================
+
+ By default, the `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.
+
+ If you want to build a cross compilation tool, you must specify the
+target explicitly by using the `--target' option when you run
+`configure'. The argument to `--target' is the configuration name of
+the system for which you wish to generate code. *Note Configuration
+Names::.
+
+ For example, to build tools which generate code for a MIPS ELF
+embedded system, you would use `--target mips-elf'.
+
+
+File: configure.info, Node: Using the Target Type, Next: Cross Tools in the Cygnus Tree, Prev: Specifying the Target, Up: Cross Compilation Tools
+
+Using the Target Type
+=====================
+
+ When writing `configure.in' for a cross compilation tool, you will
+need to use information about the target. To do this, put
+`AC_CANONICAL_SYSTEM' in `configure.in'.
+
+ `AC_CANONICAL_SYSTEM' will look for a `--target' option and
+canonicalize it using the `config.sub' shell script. It will also run
+`AC_CANONICAL_HOST' (*note 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
+`AC_CANONICAL_HOST'.
+
+`target'
+ The canonical configuration name of the target.
+
+`target_alias'
+ The argument to the `--target' option. If the user did not specify
+ a `--target' option, this will be the same as `host_alias'.
+
+`target_cpu'
+`target_vendor'
+`target_os'
+ The first three parts of the canonical target configuration name.
+
+ Note that if `host' and `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 `host' and `target' to represent the
+same system, but for the strings to not be identical. For example, if
+`config.guess' returns `sparc-sun-sunos4.1.4', and somebody configures
+with `--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 `--target' option
+without specifying a `--host' option, it is assumed that the user wants
+to configure a cross compilation tool.
+
+ The variables `target' and `target_alias' should be handled
+differently.
+
+ In general, whenever the user may actually see a string,
+`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
+`--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, `target' should be used. This is because a wide variety of
+`--target' options may map into the same canonical configuration name.
+You should not attempt to duplicate the canonicalization done by
+`config.sub' in your own code.
+
+ By convention, cross tools are installed with a prefix of the
+argument used with the `--target' option, also known as `target_alias'
+(*note Using the Target Type::). If the user does not use the
+`--target' option, and thus is building a native tool, no prefix is
+used.
+
+ For example, if gcc is configured with `--target mips-elf', then the
+installed binary will be named `mips-elf-gcc'. If gcc is configured
+without a `--target' option, then the installed binary will be named
+`gcc'.
+
+ The autoconf macro `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 `AC_ARG_PROGRAM'.
+
+
+File: configure.info, Node: Cross Tools in the Cygnus Tree, Prev: Using the Target Type, Up: Cross Compilation Tools
+
+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 `configure' script uses the old
+Cygnus configure system, not autoconf. The top level `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
+`configure'/`make' step.
+
+ The Cygnus tree may be configured with a `--target' option. The
+`--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
+
+
+File: configure.info, Node: Host and Target Libraries, Next: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree
+
+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 `bfd' and `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
+`newlib' and `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
+`configure'/`make', the configuration of the target libraries is
+actually triggered during the make step.
+
+ When the target libraries are configured, the `--target' option is
+not used. Instead, the `--host' option is used with the argument of
+the `--target' option for the overall configuration. If no `--target'
+option was used for the overall configuration, the `--host' option will
+be passed with the output of the `config.guess' shell script. Any
+`--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 `--target'. This is mainly for
+historical reasons.
+
+ To summarize, running `configure' in the Cygnus tree configures all
+the host libraries and tools, but does not configure any of the target
+libraries. Running `make' then does the following steps:
+
+ * Build the host libraries.
+
+ * 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).
+
+ * Using the newly built target compiler, configure the target
+ libraries.
+
+ * Build the target libraries.
+
+ The steps need not be done in precisely this order, since they are
+actually controlled by `Makefile' targets.
+
+
+File: configure.info, Node: Target Library Configure Scripts, Next: Make Targets in Cygnus Tree, Prev: Host and Target Libraries, Up: Cross Tools in the Cygnus Tree
+
+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 `AC_CHECK_FUNCS'. autoconf macros
+which do a compile but not a link, such as `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 `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 `configure.in' file in a directory like `libiberty'
+or `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 `--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 `--target' option), then the library will be
+configured with the `--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 `--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 `$(libdir)'. When built as a target library which is
+not native, the library should be installed in `$(tooldir)/lib'. The
+`--with-cross-host' option may be used to distinguish these cases.
+
+ This same test of `--with-cross-host' may be used to see whether it
+is OK to use link tests in the configure script. If the
+`--with-cross-host' option is not used, then the library is being built
+either standalone or native, and a link should work.
+
+
+File: configure.info, Node: Make Targets in Cygnus Tree, Next: Target libiberty, Prev: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree
+
+Make Targets in Cygnus Tree
+---------------------------
+
+ The top level `Makefile' in the Cygnus tree defines targets for
+every known subdirectory.
+
+ For every subdirectory DIR which holds a host library or program,
+the `Makefile' target `all-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
+`Makefile'.
+
+ For every subdirectory DIR which holds a target library, the
+`Makefile' target `configure-target-DIR' will configure that library.
+The `Makefile' target `all-target-DIR' will build that library.
+
+ Every `configure-target-DIR' target depends upon `all-gcc', since
+gcc, the target compiler, is required to configure the tool. Every
+`all-target-DIR' target depends upon the corresponding
+`configure-target-DIR' target.
+
+ There are several other targets which may be of interest for each
+directory: `install-DIR', `clean-DIR', and `check-DIR'. There are also
+corresponding `target' versions of these for the target libraries ,
+such as `install-target-DIR'.
+
+
+File: configure.info, Node: Target libiberty, Prev: Make Targets in Cygnus Tree, Up: Cross Tools in the Cygnus Tree
+
+Target libiberty
+----------------
+
+ The `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 `libiberty' are used when building the
+host tools, and they are also incorporated into the `libstdc++' target
+library as support code.
+
+ This duality does not pose any particular difficulties. It means
+that there are targets for both `all-libiberty' and
+`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 `O32' ABI, and gcc defaults to using the `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.
+
+
+File: configure.info, Node: Canadian Cross, Next: Cygnus Configure, Prev: Cross Compilation Tools, Up: Top
+
+Canadian Cross
+**************
+
+ 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 "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.
+
+
+File: configure.info, Node: Canadian Cross Example, Next: Canadian Cross Concepts, Up: Canadian Cross
+
+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.
+
+
+File: configure.info, Node: Canadian Cross Concepts, Next: Build Cross Host Tools, Prev: Canadian Cross Example, Up: Canadian Cross
+
+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 "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, *note 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.
+
+
+File: configure.info, Node: Build Cross Host Tools, Next: Build and Host Options, Prev: Canadian Cross Concepts, Up: Canadian Cross
+
+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.
+
+
+File: configure.info, Node: Build and Host Options, Next: CCross not in Cygnus Tree, Prev: Build Cross Host Tools, Up: Canadian Cross
+
+Build and Host Options
+======================
+
+ When you run `configure', you must use both the `--build' and
+`--host' options.
+
+ The `--build' option is used to specify the configuration name of
+the build system. This can normally be the result of running the
+`config.guess' shell script, and it is reasonable to use
+`--build=`config.guess`'.
+
+ The `--host' option is used to specify the configuration name of the
+host system.
+
+ As we explained earlier, `config.guess' is used to set the default
+value for the `--host' option (*note Using the Host Type::). We can
+now see that since `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 `config.guess' as the default for the host system when the
+`--host' option is not used.
+
+ It might seem that if the `--host' option were used without the
+`--build' option that the configure script could run `config.guess' to
+determine the build system, and presume a Canadian Cross if the result
+of `config.guess' differed from the `--host' option. However, for
+historical reasons, some configure scripts are routinely run using an
+explicit `--host' option, rather than using the default from
+`config.guess'. As noted earlier, it is difficult or impossible to
+reliably compare configuration names (*note Using the Target Type::).
+Therefore, by convention, if the `--host' option is used, but the
+`--build' option is not used, then the build system defaults to the
+host system.
+
+
+File: configure.info, Node: CCross not in Cygnus Tree, Next: CCross in Cygnus Tree, Prev: Build and Host Options, Up: Canadian Cross
+
+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 `configure' script.
+
+ You must normally set at least the environment variables `CC', `AR',
+and `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 `AS', `LD', or `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
+`solaris-gcc', then you would set the environment variable `CC' to
+`solaris-gcc'.
+
+
+File: configure.info, Node: CCross in Cygnus Tree, Next: Supporting Canadian Cross, Prev: CCross not in Cygnus Tree, Up: Canadian Cross
+
+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.
+
+
+File: configure.info, Node: Standard Cygnus CCross, Next: Cross Cygnus CCross, Up: CCross in Cygnus Tree
+
+Building a Normal Program
+-------------------------
+
+ When configuring a Canadian Cross in the Cygnus tree, all the
+appropriate environment variables are automatically set to `HOST-TOOL',
+where HOST is the value used for the `--host' option, and TOOL is the
+name of the tool (e.g., `gcc', `as', etc.). These tools must be on
+your `PATH'.
+
+ Adding a prefix of 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
+`--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 (*note Using the Target
+Type::). Since that is the system which we are now calling the host,
+HOST is the right prefix to use.
+
+ For example, if you configure with `--build=i386-linux-gnu' and
+`--host=solaris', then the Cygnus tree will automatically default to
+using the compiler `solaris-gcc'. You must have previously built and
+installed this compiler, probably by doing a build with no `--host'
+option and with a `--target' option of `solaris'.
+
+
+File: configure.info, Node: Cross Cygnus CCross, Prev: Standard Cygnus CCross, Up: CCross in Cygnus Tree
+
+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 (*note 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
+`configure'/`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 `i386-cygwin32')
+cross MIPS ELF (configure name `mips-elf') compiler, you might execute
+the following commands (long command lines are broken across lines with
+a trailing backslash as a continuation character).
+
+ mkdir linux-x-cygwin32
+ cd linux-x-cygwin32
+ SRCDIR/configure --target i386-cygwin32 --prefix=INSTALLDIR \
+ --exec-prefix=INSTALLDIR/H-i386-linux
+ make
+ make install
+ cd ..
+ mkdir linux-x-mips-elf
+ cd linux-x-mips-elf
+ SRCDIR/configure --target mips-elf --prefix=INSTALLDIR \
+ --exec-prefix=INSTALLDIR/H-i386-linux
+ make
+ make install
+ cd ..
+ mkdir cygwin32-x-mips-elf
+ cd cygwin32-x-mips-elf
+ SRCDIR/configure --build=i386-linux-gnu --host=i386-cygwin32 \
+ --target=mips-elf --prefix=WININSTALLDIR \
+ --exec-prefix=WININSTALLDIR/H-i386-cygwin32
+ make
+ make install
+
+ You would then copy the contents of WININSTALLDIR over to the
+Windows machine, and run the resulting programs.
+
+
+File: configure.info, Node: Supporting Canadian Cross, Prev: CCross in Cygnus Tree, Up: Canadian Cross
+
+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.
+
+
+File: configure.info, Node: CCross in Configure, Next: CCross in Make, Up: Supporting Canadian Cross
+
+Supporting Canadian Cross in Configure Scripts
+----------------------------------------------
+
+ In a `configure.in' file, after calling `AC_PROG_CC', you can find
+out whether this is a Canadian Cross configure by examining the shell
+variable `cross_compiling'. In a Canadian Cross, which means that the
+compiler is a cross compiler, `cross_compiling' will be `yes'. In a
+normal configuration, `cross_compiling' will be `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 `AC_CANONICAL_SYSTEM', the same macro that is
+used to determine the target system. This macro will set the variables
+`build', `build_alias', `build_cpu', `build_vendor', and `build_os',
+which correspond to the similar `target' and `host' variables, except
+that they describe the build system.
+
+ When writing tests in `configure.in', you must remember that you
+want to test the host environment, not the build environment.
+
+ Macros like `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 `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 `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 `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 `autoconf':
+ warning: AC_TRY_RUN called without default to allow cross compiling
+
+This tells you that the resulting `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 `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 `AC_FUNC_GETPGRP',
+`AC_FUNC_SETPGRP', `AC_FUNC_SETVBUF_REVERSED', and
+`AC_SYS_RESTARTABLE_SYSCALLS'. The `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.
+
+
+File: configure.info, Node: CCross in Make, Prev: CCross in Configure, Up: Supporting Canadian Cross
+
+Supporting Canadian Cross in Makefiles.
+---------------------------------------
+
+ The main Canadian Cross issue in a `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 `$(CC)' in the usual
+way, you will not be able to run it. This is because `$(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 `$(CC_FOR_BUILD)'
+will hold a compiler for the build system.
+
+ Note that you should not include `config.h' in a file you are
+compiling with `$(CC_FOR_BUILD)'. The `configure' script will build
+`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 `config.h' is not crucial.
+
+ The gcc `Makefile.in' shows a complex situation in which certain
+files, such as `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 `HOST_CC'.
+
+
+File: configure.info, Node: Cygnus Configure, Next: Multilibs, Prev: Canadian Cross, Up: Top
+
+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.
+
+
+File: configure.info, Node: Cygnus Configure Basics, Next: Cygnus Configure in C++ Libraries, Up: Cygnus Configure
+
+Cygnus Configure Basics
+=======================
+
+ Cygnus configure does not use any generated files; there is no
+program corresponding to `autoconf'. Instead, there is a single shell
+script named `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 `autoconf' in
+the top level of a Cygnus tree.
+
+ Cygnus configure works in a particular directory by examining the
+file `configure.in' in that directory. That file is broken into four
+separate shell scripts.
+
+ The first is the contents of `configure.in' up to a line that starts
+with `# per-host:'. This is the common part.
+
+ The second is the rest of `configure.in' up to a line that starts
+with `# per-target:'. This is the per host part.
+
+ The third is the rest of `configure.in' up to a line that starts
+with `# post-target:'. This is the per target part.
+
+ The fourth is the remainder of `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 `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 `package_makefile_frag' and
+`package_makefile_rules_frag'.
+
+ Cygnus configure will next set the `build' and `host' shell
+variables, and execute the per host part. This may set the shell
+variable `host_makefile_frag'.
+
+ Cygnus configure will next set the `target' variable, and execute
+the per target part. This may set the shell variable
+`target_makefile_frag'.
+
+ Any of these scripts may set the `subdirs' shell variable. This
+variable is a list of subdirectories where a `Makefile.in' file may be
+found. Cygnus configure will automatically look for a `Makefile.in'
+file in the current directory. The `subdirs' shell variable is not
+normally used, and I believe that the only directory which uses it at
+present is `newlib'.
+
+ For each `Makefile.in', Cygnus configure will automatically create a
+`Makefile' by adding definitions for `make' variables such as `host'
+and `target', and automatically editing the values of `make' variables
+such as `prefix' if they are present.
+
+ Also, if any of the `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 `Makefile'. The file contents will be read
+in after the first line in `Makefile.in' which starts with `####'.
+
+ These `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 `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 `Makefile' fragment support is similar to the autoconf
+`AC_SUBST_FILE' macro.
+
+ After creating each `Makefile', the post target script will be run
+(i.e., it may be run several times). This script may further customize
+the `Makefile'. When it is run, the shell variable `Makefile' will
+hold the name of the `Makefile', including the appropriate directory
+component.
+
+ Like an autoconf generated `configure' script, Cygnus configure will
+create a file named `config.status' which, when run, will automatically
+recreate the configuration. The `config.status' file will simply
+execute the Cygnus configure script again with the appropriate
+arguments.
+
+ Any of the parts of `configure.in' may set the shell variables
+`files' and `links'. Cygnus configure will set up symlinks from the
+names in `links' to the files named in `files'. This is similar to the
+autoconf `AC_LINK_FILES' macro.
+
+ Finally, any of the parts of `configure.in' may set the shell
+variable `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 `configure.in' file but no `configure' file, in which case
+Cygnus configure will invoke itself recursively. If the subdirectory
+has a `configure' file, Cygnus configure assumes that it is an autoconf
+generated `configure' script, and simply invokes it directly.
+
+
+File: configure.info, Node: Cygnus Configure in C++ Libraries, Prev: Cygnus Configure Basics, Up: Cygnus Configure
+
+Cygnus Configure in C++ Libraries
+=================================
+
+ 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 `configure' scripts. This
+approach is used in the libraries `libio', `libstdc++', and `libg++'.
+
+ Most of the `Makefile' information is written out by the shell
+script `libio/config.shared'. Each `configure.in' file sets certain
+shell variables, and then invokes `config.shared' to create two package
+`Makefile' fragments. These fragments are then incorporated into the
+resulting `Makefile' by the Cygnus configure script.
+
+ The file `_G_config.h' is created in the `libio' object directory by
+running the shell script `libio/gen-params'. This shell script uses
+feature tests to define macros and typedefs in `_G_config.h'.
+
+
+File: configure.info, Node: Multilibs, Next: FAQ, Prev: Cygnus Configure, Up: Top
+
+Multilibs
+*********
+
+ For some targets gcc may have different processor requirements
+depending upon command line options. An obvious example is the
+`-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 `-msoft-float' and once without. When gcc compiles
+target libraries more than once, the resulting libraries are called
+"multilibs".
+
+ Multilibs are not really part of the GNU configure and build system,
+but we discuss them here since they require support in the `configure'
+scripts and `Makefile's used for target libraries.
+
+* Menu:
+
+* Multilibs in gcc:: Multilibs in gcc.
+* Multilibs in Target Libraries:: Multilibs in Target Libraries.
+
+
+File: configure.info, Node: Multilibs in gcc, Next: Multilibs in Target Libraries, Up: Multilibs
+
+Multilibs in gcc
+================
+
+ In gcc, multilibs are defined by setting the variable
+`MULTILIB_OPTIONS' in the target `Makefile' fragment. Several other
+`MULTILIB' variables may also be defined there. *Note The Target
+Makefile Fragment: (gcc)Target Fragment.
+
+ If you have built gcc, you can see what multilibs it uses by running
+it with the `-print-multi-lib' option. The output `.;' 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 `;', is the name
+of the multilib directory. The second part is a list of compiler
+options separated by `@' characters.
+
+ Multilibs are built in a tree of directories. The top of the tree,
+represented by `.' 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.
+
Index: configure.info
===================================================================
--- configure.info (nonexistent)
+++ configure.info (revision 1765)
@@ -0,0 +1,95 @@
+This is configure.info, produced by makeinfo version 4.1 from
+./configure.texi.
+
+INFO-DIR-SECTION GNU admin
+START-INFO-DIR-ENTRY
+* configure: (configure). The GNU configure and build system
+END-INFO-DIR-ENTRY
+
+ 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.
+
+ 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.
+
+
+Indirect:
+configure.info-1: 971
+configure.info-2: 48782
+configure.info-3: 98073
+
+Tag Table:
+(Indirect)
+Node: Top971
+Node: Introduction1502
+Node: Goals2583
+Node: Tools3302
+Node: History4291
+Node: Building7284
+Node: Getting Started10374
+Node: Write configure.in10886
+Node: Write Makefile.am18132
+Node: Write acconfig.h21290
+Node: Generate files22827
+Node: Getting Started Example24788
+Node: Getting Started Example 125538
+Node: Getting Started Example 227475
+Node: Getting Started Example 330591
+Node: Generate Files in Example32961
+Node: Files34042
+Node: Developer Files34653
+Node: Developer Files Picture35028
+Node: Written Developer Files36320
+Node: Generated Developer Files38863
+Node: Build Files41998
+Node: Build Files Picture42654
+Node: Build Files Description43409
+Node: Support Files45406
+Node: Configuration Names48283
+Node: Configuration Name Definition48782
+Node: Using Configuration Names51100
+Node: Cross Compilation Tools53067
+Node: Cross Compilation Concepts53757
+Node: Host and Target54719
+Node: Using the Host Type56215
+Node: Specifying the Target57559
+Node: Using the Target Type58343
+Node: Cross Tools in the Cygnus Tree61769
+Node: Host and Target Libraries62821
+Node: Target Library Configure Scripts66561
+Node: Make Targets in Cygnus Tree69644
+Node: Target libiberty70983
+Node: Canadian Cross72361
+Node: Canadian Cross Example73201
+Node: Canadian Cross Concepts74315
+Node: Build Cross Host Tools75822
+Node: Build and Host Options76769
+Node: CCross not in Cygnus Tree78550
+Node: CCross in Cygnus Tree79523
+Node: Standard Cygnus CCross79939
+Node: Cross Cygnus CCross81294
+Node: Supporting Canadian Cross84085
+Node: CCross in Configure84695
+Node: CCross in Make87852
+Node: Cygnus Configure89446
+Node: Cygnus Configure Basics90280
+Node: Cygnus Configure in C++ Libraries94954
+Node: Multilibs95956
+Node: Multilibs in gcc97000
+Node: Multilibs in Target Libraries98073
+Node: FAQ102257
+Node: Index106353
+
+End Tag Table
Index: configure.info-3
===================================================================
--- configure.info-3 (nonexistent)
+++ configure.info-3 (revision 1765)
@@ -0,0 +1,285 @@
+This is configure.info, produced by makeinfo version 4.1 from
+./configure.texi.
+
+INFO-DIR-SECTION GNU admin
+START-INFO-DIR-ENTRY
+* configure: (configure). The GNU configure and build system
+END-INFO-DIR-ENTRY
+
+ 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.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+
+File: configure.info, Node: Multilibs in Target Libraries, Prev: Multilibs in gcc, Up: Multilibs
+
+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 `configure.in' file, by adding
+`--enable-multilib' to the list of arguments passed to configure when
+it is run for the target libraries (*note Host and Target Libraries::).
+
+ Each target library uses the shell script `config-ml.in', written by
+Doug Evans, to prepare to build target libraries. This shell script is
+invoked after the `Makefile' has been created by the `configure'
+script. If multilibs are not enabled, it does nothing, otherwise it
+modifies the `Makefile' to support multilibs.
+
+ The `config-ml.in' script makes one copy of the `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 `config-ml.in' script sets several variables in the various
+`Makefile's. The `Makefile.in' must have definitions for these
+variables already; `config-ml.in' simply changes the existing values.
+The `Makefile' should use default values for these variables which will
+do the right thing in the subdirectories.
+
+`MULTISRCTOP'
+ `config-ml.in' will set this to a sequence of `../' strings, where
+ the number of strings is the number of multilib levels in the
+ source tree. The default value should be the empty string.
+
+`MULTIBUILDTOP'
+ `config-ml.in' will set this to a sequence of `../' 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 `MULTISRCTOP' when configuring in the source tree
+ (which is not recommended).
+
+`MULTIDIRS'
+ In the top level `Makefile' only, `config-ml.in' will set this to
+ the list of multilib subdirectories. The default value should be
+ the empty string.
+
+`MULTISUBDIR'
+ `config-ml.in' will set this to the installed subdirectory name to
+ use for this subdirectory, with a leading `/'. The default value
+ shold be the empty string.
+
+`MULTIDO'
+`MULTICLEAN'
+ In the top level `Makefile' only, `config-ml.in' will set these
+ variables to commands to use when doing a recursive make. These
+ variables should both default to the string `true', so that by
+ default nothing happens.
+
+ All references to the parent of the source directory should use the
+variable `MULTISRCTOP'. Instead of writing `$(srcdir)/..', you must
+write `$(srcdir)/$(MULTISRCTOP)..'.
+
+ Similarly, references to the parent of the object directory should
+use the variable `MULTIBUILDTOP'.
+
+ In the installation target, the libraries should be installed in the
+subdirectory `MULTISUBDIR'. Instead of installing
+`$(libdir)/libfoo.a', install `$(libdir)$(MULTISUBDIR)/libfoo.a'.
+
+ The `config-ml.in' script also modifies the top level `Makefile' to
+add `multi-do' and `multi-clean' targets which are used when building
+multilibs.
+
+ The default target of the `Makefile' should include the following
+command:
+ @$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
+
+This assumes that `$(FLAGS_TO_PASS)' is defined as a set of variables
+to pass to a recursive invocation of `make'. This will build all the
+multilibs. Note that the default value of `MULTIDO' is `true', so by
+default this command will do nothing. It will only do something in the
+top level `Makefile' if multilibs were enabled.
+
+ The `install' target of the `Makefile' should include the following
+command:
+ @$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
+
+ In general, any operation, other than clean, which should be
+performed on all the multilibs should use a `$(MULTIDO)' line, setting
+the variable `DO' to the target of each recursive call to `make'.
+
+ The `clean' targets (`clean', `mostlyclean', etc.) should use
+`$(MULTICLEAN)'. For example, the `clean' target should do this:
+ @$(MULTICLEAN) DO=clean multi-clean
+
+
+File: configure.info, Node: FAQ, Next: Index, Prev: Multilibs, Up: Top
+
+Frequently Asked Questions
+**************************
+
+Which do I run first, `autoconf' or `automake'?
+ Except when you first add autoconf or automake support to a
+ package, you shouldn't run either by hand. Instead, configure
+ with the `--enable-maintainer-mode' option, and let `make' take
+ care of it.
+
+`autoconf' says something about undefined macros.
+ This means that you have macros in your `configure.in' which are
+ not defined by `autoconf'. You may be using an old version of
+ `autoconf'; try building and installing a newer one. Make sure the
+ newly installled `autoconf' is first on your `PATH'. Also, see
+ the next question.
+
+My `configure' script has stuff like `CY_GNU_GETTEXT' in it.
+ This means that you have macros in your `configure.in' which should
+ be defined in your `aclocal.m4' file, but aren't. This usually
+ means that `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 `AM_PROG_LIBTOOL' is defined) and gettext (this is
+ where `CY_GNU_GETTEXT' is defined, at least in the Cygnus version
+ of gettext).
+
+My `Makefile' has `@' characters in it.
+ This may mean that you tried to use an autoconf substitution in
+ your `Makefile.in' without adding the appropriate `AC_SUBST' call
+ to your `configure' script. Or it may just mean that you need to
+ rebuild `Makefile' in your build directory. To rebuild `Makefile'
+ from `Makefile.in', run the shell script `config.status' with no
+ arguments. If you need to force `configure' to run again, first
+ run `config.status --recheck'. These runs are normally done
+ automatically by `Makefile' targets, but if your `Makefile' has
+ gotten messed up you'll need to help them along.
+
+Why do I have to run both `config.status --recheck' and `config.status'?
+ Normally, you don't; they will be run automatically by `Makefile'
+ targets. If you do need to run them, use `config.status --recheck'
+ to run the `configure' script again with the same arguments as the
+ first time you ran it. Use `config.status' (with no arguments) to
+ regenerate all files (`Makefile', `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 `config.status --recheck'. The `Makefile' targets
+ generated by automake will use the environment variables
+ `CONFIG_FILES' and `CONFIG_HEADERS' to only regenerate files as
+ they are needed.
+
+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.
+
+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.
+
+Why not just have a Cygnus tree `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.
+
+
+File: configure.info, Node: Index, Prev: FAQ, Up: Top
+
+Index
+*****
+
+* Menu:
+
+* --build option: Build and Host Options.
+* --host option: Build and Host Options.
+* --target option: Specifying the Target.
+* _GNU_SOURCE: Write configure.in.
+* AC_CANONICAL_HOST: Using the Host Type.
+* AC_CANONICAL_SYSTEM: Using the Target Type.
+* AC_CONFIG_HEADER: Write configure.in.
+* AC_EXEEXT: Write configure.in.
+* AC_INIT: Write configure.in.
+* AC_OUTPUT: Write configure.in.
+* AC_PREREQ: Write configure.in.
+* AC_PROG_CC: Write configure.in.
+* AC_PROG_CXX: Write configure.in.
+* acconfig.h: Written Developer Files.
+* acconfig.h, writing: Write acconfig.h.
+* acinclude.m4: Written Developer Files.
+* aclocal.m4: Generated Developer Files.
+* AM_CONFIG_HEADER: Write configure.in.
+* AM_DISABLE_SHARED: Write configure.in.
+* AM_EXEEXT: Write configure.in.
+* AM_INIT_AUTOMAKE: Write configure.in.
+* AM_MAINTAINER_MODE: Write configure.in.
+* AM_PROG_LIBTOOL: Write configure.in.
+* AM_PROG_LIBTOOL in configure: FAQ.
+* build option: Build and Host Options.
+* building with a cross compiler: Canadian Cross.
+* canadian cross: Canadian Cross.
+* canadian cross in configure: CCross in Configure.
+* canadian cross in cygnus tree: CCross in Cygnus Tree.
+* canadian cross in makefile: CCross in Make.
+* canadian cross, configuring: Build and Host Options.
+* canonical system names: Configuration Names.
+* config.cache: Build Files Description.
+* config.h: Build Files Description.
+* config.h.in: Generated Developer Files.
+* config.in: Generated Developer Files.
+* config.status: Build Files Description.
+* config.status --recheck: FAQ.
+* configuration names: Configuration Names.
+* configuration triplets: Configuration Names.
+* configure: Generated Developer Files.
+* configure build system: Build and Host Options.
+* configure host: Build and Host Options.
+* configure target: Specifying the Target.
+* configure.in: Written Developer Files.
+* configure.in, writing: Write configure.in.
+* configuring a canadian cross: Build and Host Options.
+* cross compiler: Cross Compilation Concepts.
+* cross compiler, building with: Canadian Cross.
+* cross tools: Cross Compilation Tools.
+* CY_GNU_GETTEXT in configure: FAQ.
+* cygnus configure: Cygnus Configure.
+* goals: Goals.
+* history: History.
+* host names: Configuration Names.
+* host option: Build and Host Options.
+* host system: Host and Target.
+* host triplets: Configuration Names.
+* HOST_CC: CCross in Make.
+* libg++ configure: Cygnus Configure in C++ Libraries.
+* libio configure: Cygnus Configure in C++ Libraries.
+* libstdc++ configure: Cygnus Configure in C++ Libraries.
+* Makefile: Build Files Description.
+* Makefile, garbage characters: FAQ.
+* Makefile.am: Written Developer Files.
+* Makefile.am, writing: Write Makefile.am.
+* Makefile.in: Generated Developer Files.
+* multilibs: Multilibs.
+* stamp-h: Build Files Description.
+* stamp-h.in: Generated Developer Files.
+* system names: Configuration Names.
+* system types: Configuration Names.
+* target option: Specifying the Target.
+* target system: Host and Target.
+* triplets: Configuration Names.
+* undefined macros: FAQ.
+
+
Index: standards.info
===================================================================
--- standards.info (nonexistent)
+++ standards.info (revision 1765)
@@ -0,0 +1,4906 @@
+This is standards.info, produced by makeinfo version 4.1 from
+./standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+
+ GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
+1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+
+File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
+
+Version
+*******
+
+ Last updated February 14, 2002.
+
+* Menu:
+
+* Preface:: About the GNU Coding Standards
+* Legal Issues:: Keeping Free Software Free
+* Design Advice:: General Program Design
+* Program Behavior:: Program Behavior for All Programs
+* Writing C:: Making The Best Use of C
+* Documentation:: Documenting Programs
+* Managing Releases:: The Release Process
+* References:: References to Non-Free Software or Documentation
+* Copying This Manual:: How to Make Copies of This Manual
+* Index::
+
+
+File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
+
+About the GNU Coding Standards
+******************************
+
+ The GNU Coding Standards were written by Richard Stallman and other
+GNU Project volunteers. Their purpose is to make the GNU system clean,
+consistent, and easy to install. This document can also be read as a
+guide to writing portable, robust and reliable programs. It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language. The rules often
+state reasons for writing in a certain way.
+
+ This release of the GNU Coding Standards was last updated February
+14, 2002.
+
+ If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version. You can ftp the GNU Coding
+Standards from any GNU FTP host in the directory `/pub/gnu/standards/'.
+The GNU Coding Standards are available there in several different
+formats: `standards.text', `standards.info', and `standards.dvi', as
+well as the Texinfo "source" which is divided in two files:
+`standards.texi' and `make-stds.texi'. The GNU Coding Standards are
+also available on the GNU World Wide Web server:
+`http://www.gnu.org/prep/standards_toc.html'.
+
+ Corrections or suggestions for this document should be sent to
+. If you make a suggestion, please include a
+suggested new wording for it; our time is limited. We prefer a context
+diff to the `standards.texi' or `make-stds.texi' files, but if you
+don't have those files, please mail your suggestion anyway.
+
+ These standards cover the minimum of what is important when writing a
+GNU package. Likely, the needs for additional standards will come up.
+Sometimes, you might suggest that such standards be added to this
+document. If you think your standards would be generally useful, please
+do suggest them.
+
+ You should also set standards for your package on many questions not
+addressed or not firmly specified here. The most important point is to
+be self-consistent--try to stick to the conventions you pick, and try
+to document them as much as possible. That way, your program will be
+more maintainable by others.
+
+
+File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
+
+Keeping Free Software Free
+**************************
+
+ This node 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
+
+
+File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
+
+Referring to Proprietary Programs
+=================================
+
+ Don't in any circumstances refer to Unix source code for or during
+your work on GNU! (Or to any other proprietary programs.)
+
+ If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+ For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different. You could keep the entire input file in core and scan it
+there instead of using stdio. Use a smarter algorithm discovered more
+recently than the Unix program. Eliminate use of temporary files. Do
+it in one pass instead of two (we did this in the assembler).
+
+ Or, on the contrary, emphasize simplicity instead of speed. For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+ Or go for generality. For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead. Make sure your program handles NULs and
+other funny characters in the input files. Add a programming language
+for extensibility and write part of the program in that language.
+
+ Or turn some parts of the program into independently usable
+libraries. Or use a simple garbage collector instead of tracking
+precisely when to free memory, or use a new GNU facility such as
+obstacks.
+
+
+File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
+
+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. _Each_ person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+ So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers. Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+ This applies both before you release the program and afterward. If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+
+ This also applies to comments and documentation files. For copyright
+law, comments and code are just text. Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+ We know it is frustrating to ask for legal papers; it's frustrating
+for us as well. But if you don't wait, you are going out on a limb--for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+
+ You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes. Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use. For example, if someone send you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+
+ The very worst thing is if you forget to tell us about the other
+contributor. We could be very embarrassed in court some day as a
+result.
+
+ We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy.
+
+
+File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
+
+Trademarks
+==========
+
+ Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+ Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so. The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, so
+we don't use them. There is no legal requirement for them.
+
+ What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might read as naming or labeling
+our own programs or activities. For example, since "Objective C" is
+(or at least was) a trademark, we made sure to say that we provide a
+"compiler for the Objective C language" rather than an "Objective C
+compiler". The latter is meant to be short for the former, but it does
+not explicitly state the relationship, so it could be misinterpreted as
+using "Objective C" as a label for the compiler rather than for the
+language.
+
+
+File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
+
+General Program Design
+**********************
+
+ This node discusses some of the issues you should take into account
+when designing your program.
+
+* Menu:
+
+* Source Language:: Which languges to use.
+* Compatibility:: Compatibility with other implementations
+* Using Extensions:: Using non-standard features
+* Standard C:: Using Standard C features
+* Conditional Compilation:: Compiling Code Only If A Conditional is True
+
+
+File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
+
+Which Languages to Use
+======================
+
+ 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:
+
+ * 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.
+
+ * 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.
+
+ 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.
+
+ The standard extensibility interpreter for GNU software is GUILE,
+which implements the language Scheme (an especially clean and simple
+dialect of Lisp). `http://www.gnu.org/software/guile/'. We don't
+reject programs written in other "scripting languages" such as Perl and
+Python, but using GUILE is very important for the overall consistency of
+the GNU system.
+
+
+File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
+
+Compatibility with Other Implementations
+========================================
+
+ 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 POSIX if POSIX specifies their behavior.
+
+ When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+ Standard C and POSIX prohibit many kinds of extensions. Feel free
+to make the extensions anyway, and include a `--ansi', `--posix', or
+`--compatible' option to turn them off. However, if the extension has
+a significant chance of breaking any real programs or scripts, then it
+is not really upward compatible. So you should try to redesign its
+interface to make it upward compatible.
+
+ Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable `POSIXLY_CORRECT' is defined (even if it is
+defined with a null value). Please make your program recognize this
+variable if appropriate.
+
+ When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better. (For example,
+`vi' is replaced with Emacs.) But it is nice to offer a compatible
+feature as well. (There is a free `vi' clone, so we offer it.)
+
+ Additional useful features are welcome regardless of whether there
+is any precedent for them.
+
+
+File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
+
+Using Non-standard Features
+===========================
+
+ Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities. Whether to use these
+extensions in implementing your program is a difficult question.
+
+ On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program unless
+the other GNU tools are available. This might cause the program to
+work on fewer kinds of machines.
+
+ With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a "keyword" `INLINE' and
+define that as a macro to expand into either `inline' or nothing,
+depending on the compiler.
+
+ In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+ An exception to this rule are the large, established programs (such
+as Emacs) which run on a great variety of systems. 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.
+
+
+File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice
+
+Standard C and Pre-Standard C
+=============================
+
+ 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.
+
+ To support pre-standard C, instead of writing function definitions in
+standard prototype form,
+
+ int
+ foo (int x, int y)
+ ...
+
+write the definition in pre-standard style like this,
+
+ int
+ foo (x, y)
+ int x, y;
+ ...
+
+and use a separate declaration to specify the argument prototype:
+
+ int foo (int, int);
+
+ 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 `int'.
+If you think of an argument as being of a type narrower than `int',
+declare it as `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
+`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
+some machines; but you cannot use `int' instead, because `dev_t' is
+wider than `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
+`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:
+
+ /* Declare the prototype for a general external function. */
+ #if defined (__STDC__) || defined (WINDOWSNT)
+ #define P_(proto) proto
+ #else
+ #define P_(proto) ()
+ #endif
+
+
+File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice
+
+Conditional Compilation
+=======================
+
+ When supporting configuration options already known when building
+your program we prefer using `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
+
+ if (HAS_FOO)
+ ...
+ else
+ ...
+
+ instead of:
+
+ #ifdef HAS_FOO
+ ...
+ #else
+ ...
+ #endif
+
+ A modern compiler such as GCC will generate exactly the same code in
+both cases, and we have been using similar techniques with good success
+in several projects.
+
+ While this is not a silver bullet solving all portability problems,
+following this policy would have saved the GCC project alone many person
+hours if not days per year.
+
+ In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
+which cannot be simply used in `if( ...)' statements, there is an easy
+workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
+in the following example:
+
+ #ifdef REVERSIBLE_CC_MODE
+ #define HAS_REVERSIBLE_CC_MODE 1
+ #else
+ #define HAS_REVERSIBLE_CC_MODE 0
+ #endif
+
+
+File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
+
+Program Behavior for All Programs
+*********************************
+
+ This node describes conventions for writing robust software. It
+also describes general standards for error messages, the command line
+interface, and how libraries should behave.
+
+* Menu:
+
+* Semantics:: Writing robust programs
+* Libraries:: Library behavior
+* Errors:: Formatting error messages
+* User Interfaces:: Standards about interfaces generally
+* Graphical Interfaces:: Standards for graphical interfaces
+* Command-Line Interfaces:: Standards for command line interfaces
+* Option Table:: Table of long options
+* Memory Usage:: When and how to care about memory needs
+* File Usage:: Which files to use, and where
+
+
+File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior
+
+Writing Robust Programs
+=======================
+
+ Avoid arbitrary limits on the length or number of _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.
+
+ Utilities reading files should not drop NUL characters, or any other
+nonprinting characters _including those with codes above 0177_. The
+only sensible exceptions would be utilities specifically intended for
+interface to certain types of 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.
+
+ Check every system call for an error return, unless you know you
+wish to ignore errors. Include the system error text (from `perror' or
+equivalent) in _every_ error message resulting from a failing system
+call, as well as the name of the file if any and the name of the
+utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
+
+ Check every call to `malloc' or `realloc' to see if it returned
+zero. Check `realloc' even if you are making the block smaller; in a
+system that rounds block sizes to a power of 2, `realloc' may get a
+different block if you ask for less space.
+
+ In Unix, `realloc' can destroy the storage block if it returns zero.
+GNU `realloc' does not have this bug: if it fails, the original block
+is unchanged. Feel free to assume the bug is fixed. If you wish to
+run your program on Unix, and wish to avoid lossage in this case, you
+can use the GNU `malloc'.
+
+ You must expect `free' to alter the contents of the block that was
+freed. Anything you want to fetch from the block, you must fetch before
+calling `free'.
+
+ If `malloc' fails in a noninteractive program, make that a fatal
+error. In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop. This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+ Use `getopt_long' to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+ When static storage is to be written in during program execution, use
+explicit C code to initialize it. Reserve C initialized declarations
+for data that will not be changed.
+
+ Try to avoid low-level interfaces to obscure Unix data structures
+(such as file directories, utmp, or the layout of kernel memory), since
+these are less likely to work compatibly. If you need to find all the
+files in a directory, use `readdir' or some other high-level interface.
+These are supported compatibly by GNU.
+
+ The preferred signal handling facilities are the BSD variant of
+`signal', and the POSIX `sigaction' function; the alternative USG
+`signal' interface is an inferior design.
+
+ Nowadays, using the POSIX signal functions may be the easiest way to
+make a program portable. If you use `signal', then on GNU/Linux
+systems running GNU libc version 1, you should include `bsd/signal.h'
+instead of `signal.h', so as to get BSD behavior. It is up to you
+whether to support systems where `signal' has only the USG behavior, or
+give up on them.
+
+ 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.
+_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.
+
+ If you make temporary files, check the `TMPDIR' environment
+variable; if that variable is defined, use the specified directory
+instead of `/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:
+
+ fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+
+or by using the `mkstemps' function from libiberty.
+
+ In bash, use `set -C' to avoid this problem.
+
+
+File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
+
+Library Behavior
+================
+
+ Try to make library functions reentrant. If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of `malloc' itself.
+
+ Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+ Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this prefix.
+In addition, there should only be one of these in any given library
+member. This usually means putting each one in a separate source file.
+
+ An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+ External symbols that are not documented entry points for the user
+should have names beginning with `_'. The `_' 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.
+
+
+File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
+
+Formatting Error Messages
+=========================
+
+ Error messages from compilers should look like this:
+
+ SOURCE-FILE-NAME:LINENO: MESSAGE
+
+If you want to mention the column number, use this format:
+
+ SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line. (Both
+of these conventions are chosen for compatibility.) Calculate column
+numbers assuming that space and all ASCII printing characters have
+equal width, and assuming tab stops every 8 columns.
+
+ Error messages from other noninteractive programs should look like
+this:
+
+ PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
+
+when there is an appropriate source file, or like this:
+
+ PROGRAM: MESSAGE
+
+when there is no relevant source file.
+
+ If you want to mention the column number, use this format:
+
+ PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+ In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message. The place to indicate which program is running is in the
+prompt or with the screen layout. (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+ The string MESSAGE should not begin with a capital letter when it
+follows a program name and/or file name. Also, it should not end with
+a period.
+
+ Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter. But they should not
+end with a period.
+
+
+File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
+
+Standards for Interfaces Generally
+==================================
+
+ Please don't make the behavior of a utility depend on the name used
+to invoke it. It is useful sometimes to make a link to a utility with
+a different name, and that should not change what it does.
+
+ Instead, use a run time option or a compilation switch or both to
+select among the alternate behaviors.
+
+ Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with. Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then. (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 `ls' or `sh' did not do so in
+the way all users expect. In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type. For example, we provide a `dir' program much like
+`ls' except that its default output format is always multi-column
+format.
+
+
+File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
+
+Standards for Graphical Interfaces
+==================================
+
+ When you write a program that provides a graphical user interface,
+please make it work with X Windows and the GTK toolkit unless the
+functionality specifically requires some alternative (for example,
+"displaying jpeg images while in console mode").
+
+ In addition, please provide a command-line interface to control the
+functionality. (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.) This is so
+that the same jobs can be done from scripts.
+
+ Please also consider providing a CORBA interface (for use from
+GNOME), a library interface (for use from C), and perhaps a
+keyboard-driven console interface (for use by users from console mode).
+Once you are doing the work to provide the functionality and the
+graphical interface, these won't be much extra work.
+
+
+File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
+
+Standards for Command Line Interfaces
+=====================================
+
+ It is a good idea to follow the POSIX guidelines for the
+command-line options of a program. The easiest way to do this is to use
+`getopt' to parse them. Note that the GNU version of `getopt' will
+normally permit options anywhere among the arguments unless the special
+argument `--' is used. This is not what POSIX specifies; it is a GNU
+extension.
+
+ Please define long-named options that are equivalent to the
+single-letter Unix-style options. We hope to make GNU more user
+friendly this way. This is easy to do with the GNU function
+`getopt_long'.
+
+ One of the advantages of long-named options is that they can be
+consistent from program to program. For example, users should be able
+to expect the "verbose" option of any GNU program which has one, to be
+spelled precisely `--verbose'. To achieve this uniformity, look at the
+table of common long-option names when you choose the option names for
+your program (*note 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 `-o' or `--output'). Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it. This will lead to more consistency
+among GNU utilities, and fewer idiosyncracies for users to remember.
+
+ All programs should support two standard options: `--version' and
+`--help'.
+
+`--version'
+ This option should direct the program to print information about
+ its name, version, origin and legal status, all on standard
+ output, and then exit successfully. Other options and arguments
+ should be ignored once this is seen, and the program should not
+ perform its normal function.
+
+ 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:
+
+ GNU Emacs 19.30
+
+ The program's name should be a constant string; _don't_ compute it
+ from `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 `PATH'.
+
+ If the program is a subsidiary part of a larger package, mention
+ the package name in parentheses, like this:
+
+ emacsserver (GNU Emacs) 19.30
+
+ 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 *need* to mention the version numbers of libraries which
+ are distributed separately from the package which contains this
+ program, you can do so by printing an additional line of version
+ info for each library you want to mention. Use the same format
+ for these lines as for the first line.
+
+ Please do not mention all of the libraries that the program uses
+ "just for completeness"--that would produce a lot of unhelpful
+ clutter. Please mention library version numbers only if you find
+ in practice that they are very important to you in debugging.
+
+ The following line, after the version number line or lines, should
+ be a copyright notice. If more than one copyright notice is
+ called for, put each on a separate line.
+
+ Next should follow a brief statement that the program is free
+ software, and that users are free to copy and change it on certain
+ conditions. If the program is covered by the GNU GPL, say so
+ here. Also mention that there is no warranty, to the extent
+ permitted by law.
+
+ It is ok to finish the output with a list of the major authors of
+ the program, as a way of giving credit.
+
+ Here's an example of output that follows these rules:
+
+ GNU Emacs 19.34.5
+ Copyright (C) 1996 Free Software Foundation, Inc.
+ GNU Emacs comes with NO WARRANTY,
+ to the extent permitted by law.
+ You may redistribute copies of GNU Emacs
+ under the terms of the GNU General Public License.
+ For more information about these matters,
+ see the files named COPYING.
+
+ You should adapt this to your program, of course, filling in the
+ proper year, copyright holder, name of program, and the references
+ to distribution terms, and changing the rest of the wording as
+ necessary.
+
+ This copyright notice only needs to mention the most recent year in
+ which changes were made--there's no need to list the years for
+ previous versions' changes. You don't have to mention the name of
+ the program in these notices, if that is inconvenient, since it
+ appeared in the first line.
+
+ Translations of the above lines must preserve the validity of the
+ copyright notices (*note Internationalization::). If the
+ translation's character set supports it, the `(C)' should be
+ replaced with the copyright symbol, as follows:
+
+ (the official copyright symbol, which is the letter C in a circle);
+
+ 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.
+
+`--help'
+ This option should output brief documentation for how to invoke the
+ program, on standard output, then exit successfully. Other
+ options and arguments should be ignored once this is seen, and the
+ program should not perform its normal function.
+
+ Near the end of the `--help' option's output there should be a line
+ that says where to mail bug reports. It should have this format:
+
+ Report bugs to MAILING-ADDRESS.
+
+
+File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior
+
+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 a list of them, with their
+meanings, so we can update the table.
+
+`after-date'
+ `-N' in `tar'.
+
+`all'
+ `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
+
+`all-text'
+ `-a' in `diff'.
+
+`almost-all'
+ `-A' in `ls'.
+
+`append'
+ `-a' in `etags', `tee', `time'; `-r' in `tar'.
+
+`archive'
+ `-a' in `cp'.
+
+`archive-name'
+ `-n' in `shar'.
+
+`arglength'
+ `-l' in `m4'.
+
+`ascii'
+ `-a' in `diff'.
+
+`assign'
+ `-v' in `gawk'.
+
+`assume-new'
+ `-W' in Make.
+
+`assume-old'
+ `-o' in Make.
+
+`auto-check'
+ `-a' in `recode'.
+
+`auto-pager'
+ `-a' in `wdiff'.
+
+`auto-reference'
+ `-A' in `ptx'.
+
+`avoid-wraps'
+ `-n' in `wdiff'.
+
+`background'
+ For server programs, run in the background.
+
+`backward-search'
+ `-B' in `ctags'.
+
+`basename'
+ `-f' in `shar'.
+
+`batch'
+ Used in GDB.
+
+`baud'
+ Used in GDB.
+
+`before'
+ `-b' in `tac'.
+
+`binary'
+ `-b' in `cpio' and `diff'.
+
+`bits-per-code'
+ `-b' in `shar'.
+
+`block-size'
+ Used in `cpio' and `tar'.
+
+`blocks'
+ `-b' in `head' and `tail'.
+
+`break-file'
+ `-b' in `ptx'.
+
+`brief'
+ Used in various programs to make output shorter.
+
+`bytes'
+ `-c' in `head', `split', and `tail'.
+
+`c++'
+ `-C' in `etags'.
+
+`catenate'
+ `-A' in `tar'.
+
+`cd'
+ Used in various programs to specify the directory to use.
+
+`changes'
+ `-c' in `chgrp' and `chown'.
+
+`classify'
+ `-F' in `ls'.
+
+`colons'
+ `-c' in `recode'.
+
+`command'
+ `-c' in `su'; `-x' in GDB.
+
+`compare'
+ `-d' in `tar'.
+
+`compat'
+ Used in `gawk'.
+
+`compress'
+ `-Z' in `tar' and `shar'.
+
+`concatenate'
+ `-A' in `tar'.
+
+`confirmation'
+ `-w' in `tar'.
+
+`context'
+ Used in `diff'.
+
+`copyleft'
+ `-W copyleft' in `gawk'.
+
+`copyright'
+ `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
+
+`core'
+ Used in GDB.
+
+`count'
+ `-q' in `who'.
+
+`count-links'
+ `-l' in `du'.
+
+`create'
+ Used in `tar' and `cpio'.
+
+`cut-mark'
+ `-c' in `shar'.
+
+`cxref'
+ `-x' in `ctags'.
+
+`date'
+ `-d' in `touch'.
+
+`debug'
+ `-d' in Make and `m4'; `-t' in Bison.
+
+`define'
+ `-D' in `m4'.
+
+`defines'
+ `-d' in Bison and `ctags'.
+
+`delete'
+ `-D' in `tar'.
+
+`dereference'
+ `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
+
+`dereference-args'
+ `-D' in `du'.
+
+`device'
+ Specify an I/O device (special file name).
+
+`diacritics'
+ `-d' in `recode'.
+
+`dictionary-order'
+ `-d' in `look'.
+
+`diff'
+ `-d' in `tar'.
+
+`digits'
+ `-n' in `csplit'.
+
+`directory'
+ Specify the directory to use, in various programs. In `ls', it
+ means to show directories themselves rather than their contents.
+ In `rm' and `ln', it means to not treat links to directories
+ specially.
+
+`discard-all'
+ `-x' in `strip'.
+
+`discard-locals'
+ `-X' in `strip'.
+
+`dry-run'
+ `-n' in Make.
+
+`ed'
+ `-e' in `diff'.
+
+`elide-empty-files'
+ `-z' in `csplit'.
+
+`end-delete'
+ `-x' in `wdiff'.
+
+`end-insert'
+ `-z' in `wdiff'.
+
+`entire-new-file'
+ `-N' in `diff'.
+
+`environment-overrides'
+ `-e' in Make.
+
+`eof'
+ `-e' in `xargs'.
+
+`epoch'
+ Used in GDB.
+
+`error-limit'
+ Used in `makeinfo'.
+
+`error-output'
+ `-o' in `m4'.
+
+`escape'
+ `-b' in `ls'.
+
+`exclude-from'
+ `-X' in `tar'.
+
+`exec'
+ Used in GDB.
+
+`exit'
+ `-x' in `xargs'.
+
+`exit-0'
+ `-e' in `unshar'.
+
+`expand-tabs'
+ `-t' in `diff'.
+
+`expression'
+ `-e' in `sed'.
+
+`extern-only'
+ `-g' in `nm'.
+
+`extract'
+ `-i' in `cpio'; `-x' in `tar'.
+
+`faces'
+ `-f' in `finger'.
+
+`fast'
+ `-f' in `su'.
+
+`fatal-warnings'
+ `-E' in `m4'.
+
+`file'
+ `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
+ in `touch'.
+
+`field-separator'
+ `-F' in `gawk'.
+
+`file-prefix'
+ `-b' in Bison.
+
+`file-type'
+ `-F' in `ls'.
+
+`files-from'
+ `-T' in `tar'.
+
+`fill-column'
+ Used in `makeinfo'.
+
+`flag-truncation'
+ `-F' in `ptx'.
+
+`fixed-output-files'
+ `-y' in Bison.
+
+`follow'
+ `-f' in `tail'.
+
+`footnote-style'
+ Used in `makeinfo'.
+
+`force'
+ `-f' in `cp', `ln', `mv', and `rm'.
+
+`force-prefix'
+ `-F' in `shar'.
+
+`foreground'
+ For server programs, run in the foreground; in other words, don't
+ do anything special to run the server in the background.
+
+`format'
+ Used in `ls', `time', and `ptx'.
+
+`freeze-state'
+ `-F' in `m4'.
+
+`fullname'
+ Used in GDB.
+
+`gap-size'
+ `-g' in `ptx'.
+
+`get'
+ `-x' in `tar'.
+
+`graphic'
+ `-i' in `ul'.
+
+`graphics'
+ `-g' in `recode'.
+
+`group'
+ `-g' in `install'.
+
+`gzip'
+ `-z' in `tar' and `shar'.
+
+`hashsize'
+ `-H' in `m4'.
+
+`header'
+ `-h' in `objdump' and `recode'
+
+`heading'
+ `-H' in `who'.
+
+`help'
+ Used to ask for brief usage information.
+
+`here-delimiter'
+ `-d' in `shar'.
+
+`hide-control-chars'
+ `-q' in `ls'.
+
+`html'
+ In `makeinfo', output HTML.
+
+`idle'
+ `-u' in `who'.
+
+`ifdef'
+ `-D' in `diff'.
+
+`ignore'
+ `-I' in `ls'; `-x' in `recode'.
+
+`ignore-all-space'
+ `-w' in `diff'.
+
+`ignore-backups'
+ `-B' in `ls'.
+
+`ignore-blank-lines'
+ `-B' in `diff'.
+
+`ignore-case'
+ `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
+
+`ignore-errors'
+ `-i' in Make.
+
+`ignore-file'
+ `-i' in `ptx'.
+
+`ignore-indentation'
+ `-I' in `etags'.
+
+`ignore-init-file'
+ `-f' in Oleo.
+
+`ignore-interrupts'
+ `-i' in `tee'.
+
+`ignore-matching-lines'
+ `-I' in `diff'.
+
+`ignore-space-change'
+ `-b' in `diff'.
+
+`ignore-zeros'
+ `-i' in `tar'.
+
+`include'
+ `-i' in `etags'; `-I' in `m4'.
+
+`include-dir'
+ `-I' in Make.
+
+`incremental'
+ `-G' in `tar'.
+
+`info'
+ `-i', `-l', and `-m' in Finger.
+
+`init-file'
+ In some programs, specify the name of the file to read as the
+ user's init file.
+
+`initial'
+ `-i' in `expand'.
+
+`initial-tab'
+ `-T' in `diff'.
+
+`inode'
+ `-i' in `ls'.
+
+`interactive'
+ `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
+ `-w' in `tar'.
+
+`intermix-type'
+ `-p' in `shar'.
+
+`iso-8601'
+ Used in `date'
+
+`jobs'
+ `-j' in Make.
+
+`just-print'
+ `-n' in Make.
+
+`keep-going'
+ `-k' in Make.
+
+`keep-files'
+ `-k' in `csplit'.
+
+`kilobytes'
+ `-k' in `du' and `ls'.
+
+`language'
+ `-l' in `etags'.
+
+`less-mode'
+ `-l' in `wdiff'.
+
+`level-for-gzip'
+ `-g' in `shar'.
+
+`line-bytes'
+ `-C' in `split'.
+
+`lines'
+ Used in `split', `head', and `tail'.
+
+`link'
+ `-l' in `cpio'.
+
+`lint'
+`lint-old'
+ Used in `gawk'.
+
+`list'
+ `-t' in `cpio'; `-l' in `recode'.
+
+`list'
+ `-t' in `tar'.
+
+`literal'
+ `-N' in `ls'.
+
+`load-average'
+ `-l' in Make.
+
+`login'
+ Used in `su'.
+
+`machine'
+ No listing of which programs already use this; someone should
+ check to see if any actually do, and tell .
+
+`macro-name'
+ `-M' in `ptx'.
+
+`mail'
+ `-m' in `hello' and `uname'.
+
+`make-directories'
+ `-d' in `cpio'.
+
+`makefile'
+ `-f' in Make.
+
+`mapped'
+ Used in GDB.
+
+`max-args'
+ `-n' in `xargs'.
+
+`max-chars'
+ `-n' in `xargs'.
+
+`max-lines'
+ `-l' in `xargs'.
+
+`max-load'
+ `-l' in Make.
+
+`max-procs'
+ `-P' in `xargs'.
+
+`mesg'
+ `-T' in `who'.
+
+`message'
+ `-T' in `who'.
+
+`minimal'
+ `-d' in `diff'.
+
+`mixed-uuencode'
+ `-M' in `shar'.
+
+`mode'
+ `-m' in `install', `mkdir', and `mkfifo'.
+
+`modification-time'
+ `-m' in `tar'.
+
+`multi-volume'
+ `-M' in `tar'.
+
+`name-prefix'
+ `-a' in Bison.
+
+`nesting-limit'
+ `-L' in `m4'.
+
+`net-headers'
+ `-a' in `shar'.
+
+`new-file'
+ `-W' in Make.
+
+`no-builtin-rules'
+ `-r' in Make.
+
+`no-character-count'
+ `-w' in `shar'.
+
+`no-check-existing'
+ `-x' in `shar'.
+
+`no-common'
+ `-3' in `wdiff'.
+
+`no-create'
+ `-c' in `touch'.
+
+`no-defines'
+ `-D' in `etags'.
+
+`no-deleted'
+ `-1' in `wdiff'.
+
+`no-dereference'
+ `-d' in `cp'.
+
+`no-inserted'
+ `-2' in `wdiff'.
+
+`no-keep-going'
+ `-S' in Make.
+
+`no-lines'
+ `-l' in Bison.
+
+`no-piping'
+ `-P' in `shar'.
+
+`no-prof'
+ `-e' in `gprof'.
+
+`no-regex'
+ `-R' in `etags'.
+
+`no-sort'
+ `-p' in `nm'.
+
+`no-split'
+ Used in `makeinfo'.
+
+`no-static'
+ `-a' in `gprof'.
+
+`no-time'
+ `-E' in `gprof'.
+
+`no-timestamp'
+ `-m' in `shar'.
+
+`no-validate'
+ Used in `makeinfo'.
+
+`no-wait'
+ Used in `emacsclient'.
+
+`no-warn'
+ Used in various programs to inhibit warnings.
+
+`node'
+ `-n' in `info'.
+
+`nodename'
+ `-n' in `uname'.
+
+`nonmatching'
+ `-f' in `cpio'.
+
+`nstuff'
+ `-n' in `objdump'.
+
+`null'
+ `-0' in `xargs'.
+
+`number'
+ `-n' in `cat'.
+
+`number-nonblank'
+ `-b' in `cat'.
+
+`numeric-sort'
+ `-n' in `nm'.
+
+`numeric-uid-gid'
+ `-n' in `cpio' and `ls'.
+
+`nx'
+ Used in GDB.
+
+`old-archive'
+ `-o' in `tar'.
+
+`old-file'
+ `-o' in Make.
+
+`one-file-system'
+ `-l' in `tar', `cp', and `du'.
+
+`only-file'
+ `-o' in `ptx'.
+
+`only-prof'
+ `-f' in `gprof'.
+
+`only-time'
+ `-F' in `gprof'.
+
+`options'
+ `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
+
+`output'
+ In various programs, specify the output file name.
+
+`output-prefix'
+ `-o' in `shar'.
+
+`override'
+ `-o' in `rm'.
+
+`overwrite'
+ `-c' in `unshar'.
+
+`owner'
+ `-o' in `install'.
+
+`paginate'
+ `-l' in `diff'.
+
+`paragraph-indent'
+ Used in `makeinfo'.
+
+`parents'
+ `-p' in `mkdir' and `rmdir'.
+
+`pass-all'
+ `-p' in `ul'.
+
+`pass-through'
+ `-p' in `cpio'.
+
+`port'
+ `-P' in `finger'.
+
+`portability'
+ `-c' in `cpio' and `tar'.
+
+`posix'
+ Used in `gawk'.
+
+`prefix-builtins'
+ `-P' in `m4'.
+
+`prefix'
+ `-f' in `csplit'.
+
+`preserve'
+ Used in `tar' and `cp'.
+
+`preserve-environment'
+ `-p' in `su'.
+
+`preserve-modification-time'
+ `-m' in `cpio'.
+
+`preserve-order'
+ `-s' in `tar'.
+
+`preserve-permissions'
+ `-p' in `tar'.
+
+`print'
+ `-l' in `diff'.
+
+`print-chars'
+ `-L' in `cmp'.
+
+`print-data-base'
+ `-p' in Make.
+
+`print-directory'
+ `-w' in Make.
+
+`print-file-name'
+ `-o' in `nm'.
+
+`print-symdefs'
+ `-s' in `nm'.
+
+`printer'
+ `-p' in `wdiff'.
+
+`prompt'
+ `-p' in `ed'.
+
+`proxy'
+ Specify an HTTP proxy.
+
+`query-user'
+ `-X' in `shar'.
+
+`question'
+ `-q' in Make.
+
+`quiet'
+ Used in many programs to inhibit the usual output. *Note:* every
+ program accepting `--quiet' should accept `--silent' as a synonym.
+
+`quiet-unshar'
+ `-Q' in `shar'
+
+`quote-name'
+ `-Q' in `ls'.
+
+`rcs'
+ `-n' in `diff'.
+
+`re-interval'
+ Used in `gawk'.
+
+`read-full-blocks'
+ `-B' in `tar'.
+
+`readnow'
+ Used in GDB.
+
+`recon'
+ `-n' in Make.
+
+`record-number'
+ `-R' in `tar'.
+
+`recursive'
+ Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
+
+`reference-limit'
+ Used in `makeinfo'.
+
+`references'
+ `-r' in `ptx'.
+
+`regex'
+ `-r' in `tac' and `etags'.
+
+`release'
+ `-r' in `uname'.
+
+`reload-state'
+ `-R' in `m4'.
+
+`relocation'
+ `-r' in `objdump'.
+
+`rename'
+ `-r' in `cpio'.
+
+`replace'
+ `-i' in `xargs'.
+
+`report-identical-files'
+ `-s' in `diff'.
+
+`reset-access-time'
+ `-a' in `cpio'.
+
+`reverse'
+ `-r' in `ls' and `nm'.
+
+`reversed-ed'
+ `-f' in `diff'.
+
+`right-side-defs'
+ `-R' in `ptx'.
+
+`same-order'
+ `-s' in `tar'.
+
+`same-permissions'
+ `-p' in `tar'.
+
+`save'
+ `-g' in `stty'.
+
+`se'
+ Used in GDB.
+
+`sentence-regexp'
+ `-S' in `ptx'.
+
+`separate-dirs'
+ `-S' in `du'.
+
+`separator'
+ `-s' in `tac'.
+
+`sequence'
+ Used by `recode' to chose files or pipes for sequencing passes.
+
+`shell'
+ `-s' in `su'.
+
+`show-all'
+ `-A' in `cat'.
+
+`show-c-function'
+ `-p' in `diff'.
+
+`show-ends'
+ `-E' in `cat'.
+
+`show-function-line'
+ `-F' in `diff'.
+
+`show-tabs'
+ `-T' in `cat'.
+
+`silent'
+ Used in many programs to inhibit the usual output. *Note:* every
+ program accepting `--silent' should accept `--quiet' as a synonym.
+
+`size'
+ `-s' in `ls'.
+
+`socket'
+ Specify a file descriptor for a network server to use for its
+ socket, instead of opening and binding a new socket. This
+ provides a way to run, in a nonpriveledged process, a server that
+ normally needs a reserved port number.
+
+`sort'
+ Used in `ls'.
+
+`source'
+ `-W source' in `gawk'.
+
+`sparse'
+ `-S' in `tar'.
+
+`speed-large-files'
+ `-H' in `diff'.
+
+`split-at'
+ `-E' in `unshar'.
+
+`split-size-limit'
+ `-L' in `shar'.
+
+`squeeze-blank'
+ `-s' in `cat'.
+
+`start-delete'
+ `-w' in `wdiff'.
+
+`start-insert'
+ `-y' in `wdiff'.
+
+`starting-file'
+ Used in `tar' and `diff' to specify which file within a directory
+ to start processing with.
+
+`statistics'
+ `-s' in `wdiff'.
+
+`stdin-file-list'
+ `-S' in `shar'.
+
+`stop'
+ `-S' in Make.
+
+`strict'
+ `-s' in `recode'.
+
+`strip'
+ `-s' in `install'.
+
+`strip-all'
+ `-s' in `strip'.
+
+`strip-debug'
+ `-S' in `strip'.
+
+`submitter'
+ `-s' in `shar'.
+
+`suffix'
+ `-S' in `cp', `ln', `mv'.
+
+`suffix-format'
+ `-b' in `csplit'.
+
+`sum'
+ `-s' in `gprof'.
+
+`summarize'
+ `-s' in `du'.
+
+`symbolic'
+ `-s' in `ln'.
+
+`symbols'
+ Used in GDB and `objdump'.
+
+`synclines'
+ `-s' in `m4'.
+
+`sysname'
+ `-s' in `uname'.
+
+`tabs'
+ `-t' in `expand' and `unexpand'.
+
+`tabsize'
+ `-T' in `ls'.
+
+`terminal'
+ `-T' in `tput' and `ul'. `-t' in `wdiff'.
+
+`text'
+ `-a' in `diff'.
+
+`text-files'
+ `-T' in `shar'.
+
+`time'
+ Used in `ls' and `touch'.
+
+`timeout'
+ Specify how long to wait before giving up on some operation.
+
+`to-stdout'
+ `-O' in `tar'.
+
+`total'
+ `-c' in `du'.
+
+`touch'
+ `-t' in Make, `ranlib', and `recode'.
+
+`trace'
+ `-t' in `m4'.
+
+`traditional'
+ `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
+ and `ptx'.
+
+`tty'
+ Used in GDB.
+
+`typedefs'
+ `-t' in `ctags'.
+
+`typedefs-and-c++'
+ `-T' in `ctags'.
+
+`typeset-mode'
+ `-t' in `ptx'.
+
+`uncompress'
+ `-z' in `tar'.
+
+`unconditional'
+ `-u' in `cpio'.
+
+`undefine'
+ `-U' in `m4'.
+
+`undefined-only'
+ `-u' in `nm'.
+
+`update'
+ `-u' in `cp', `ctags', `mv', `tar'.
+
+`usage'
+ Used in `gawk'; same as `--help'.
+
+`uuencode'
+ `-B' in `shar'.
+
+`vanilla-operation'
+ `-V' in `shar'.
+
+`verbose'
+ Print more information about progress. Many programs support this.
+
+`verify'
+ `-W' in `tar'.
+
+`version'
+ Print the version number.
+
+`version-control'
+ `-V' in `cp', `ln', `mv'.
+
+`vgrind'
+ `-v' in `ctags'.
+
+`volume'
+ `-V' in `tar'.
+
+`what-if'
+ `-W' in Make.
+
+`whole-size-limit'
+ `-l' in `shar'.
+
+`width'
+ `-w' in `ls' and `ptx'.
+
+`word-regexp'
+ `-W' in `ptx'.
+
+`writable'
+ `-T' in `who'.
+
+`zeros'
+ `-z' in `gprof'.
+
+
+File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior
+
+Memory Usage
+============
+
+ If a program typically uses just a few meg of memory, don't bother
+making any effort to reduce memory usage. For example, if it is
+impractical for other reasons to operate on files more than a few meg
+long, it is reasonable to read entire input files into core to operate
+on them.
+
+ However, for programs such as `cat' or `tail', that can usefully
+operate on very large files, it is important to avoid using a technique
+that would artificially limit the size of files it can handle. If a
+program works by lines and could be applied to arbitrary user-supplied
+input files, it should keep only a line in memory, because this is not
+very hard and users will want to be able to operate on input files that
+are bigger than will fit in core all at once.
+
+ If your program creates complicated data structures, just make them
+in core and give a fatal error if `malloc' returns zero.
+
+
+File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
+
+File Usage
+==========
+
+ Programs should be prepared to operate when `/usr' and `/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 `/usr' or
+`/etc'.
+
+ There are two exceptions. `/etc' is used to store system
+configuration information; it is reasonable for a program to modify
+files in `/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.
+
+
+File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
+
+Making The Best Use of C
+************************
+
+ This node provides advice on how best to use the C language when
+writing GNU software.
+
+* Menu:
+
+* Formatting:: Formatting Your Source Code
+* Comments:: Commenting Your Work
+* Syntactic Conventions:: Clean Use of C Constructs
+* Names:: Naming Variables, Functions, and Files
+* System Portability:: Portability between different operating systems
+* CPU Portability:: Supporting the range of CPU types
+* System Functions:: Portability and ``standard'' library functions
+* Internationalization:: Techniques for internationalization
+* Mmap:: How you can safely use `mmap'.
+
+
+File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
+
+Formatting Your Source Code
+===========================
+
+ It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero. Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+
+ It is also important for function definitions to start the name of
+the function in column zero. This helps people to search for function
+definitions, and may also help certain tools recognize them. Thus, the
+proper format is this:
+
+ static char *
+ concat (s1, s2) /* Name starts in column zero here */
+ char *s1, *s2;
+ { /* Open brace in column zero here */
+ ...
+ }
+
+or, if you want to use Standard C syntax, format the definition like
+this:
+
+ static char *
+ concat (char *s1, char *s2)
+ {
+ ...
+ }
+
+ In Standard C, if the arguments don't fit nicely on one line, split
+it like this:
+
+ int
+ lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+ ...
+
+ The rest of this section gives our recommendations for other aspects
+of C formatting style, which is also the default style of the `indent'
+program in version 1.2 and newer. It corresponds to the options
+
+ -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+ -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+
+ 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:
+
+ if (x < foo (y, z))
+ haha = bar[4] + 5;
+ else
+ {
+ while (z)
+ {
+ haha += foo (z, z);
+ z--;
+ }
+ return ++x + bar ();
+ }
+
+ We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas. Especially after the commas.
+
+ When you split an expression into multiple lines, split it before an
+operator, not after one. Here is the right way:
+
+ if (foo_this_is_long && bar > win (x, y, z)
+ && remaining_condition)
+
+ Try to avoid having two operators of different precedence at the same
+level of indentation. For example, don't write this:
+
+ mode = (inmode[j] == VOIDmode
+ || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+ ? outmode[j] : inmode[j]);
+
+ Instead, use extra parentheses so that the indentation shows the
+nesting:
+
+ mode = ((inmode[j] == VOIDmode
+ || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+ ? outmode[j] : inmode[j]);
+
+ Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+ v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+
+but Emacs would alter it. Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+ v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+
+ Format do-while statements like this:
+
+ do
+ {
+ a = foo (a);
+ }
+ while (a > 0);
+
+ Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function). It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page. The formfeeds should appear alone on lines by themselves.
+
+
+File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
+
+Commenting Your Work
+====================
+
+ Every program should start with a comment saying briefly what it is
+for. Example: `fmt - filter for simple filling of text'.
+
+ Please 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 `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 ...").
+
+ The comment on a function is much clearer if you use the argument
+names to speak about the argument values. The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself. Thus, "the inode
+number NODE_NUM" rather than "an inode".
+
+ There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the
+function itself would be off the bottom of the screen.
+
+ There should be a comment on each static variable as well, like this:
+
+ /* Nonzero means truncate lines in the display;
+ zero means continue them. */
+ int truncate_lines;
+
+ Every `#endif' should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested. The comment should
+state the condition of the conditional that is ending, _including its
+sense_. `#else' should have a comment describing the condition _and
+sense_ of the code that follows. For example:
+
+ #ifdef foo
+ ...
+ #else /* not foo */
+ ...
+ #endif /* not foo */
+ #ifdef foo
+ ...
+ #endif /* foo */
+
+but, by contrast, write the comments this way for a `#ifndef':
+
+ #ifndef foo
+ ...
+ #else /* foo */
+ ...
+ #endif /* foo */
+ #ifndef foo
+ ...
+ #endif /* not foo */
+
+
+File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
+
+Clean Use of C Constructs
+=========================
+
+ 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 `int' rather than omitting the `int'.
+
+ Some programmers like to use the GCC `-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 `-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 `extern' declarations inside
+functions.
+
+ It used to be common practice to use the same local variables (with
+names like `tem') over and over for different values within one
+function. Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+ Don't use local variables or parameters that shadow global
+identifiers.
+
+ Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead. For example, instead of
+this:
+
+ int foo,
+ bar;
+
+write either this:
+
+ int foo, bar;
+
+or this:
+
+ int foo;
+ int bar;
+
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+ When you have an `if'-`else' statement nested in another `if'
+statement, always put braces around the `if'-`else'. Thus, never write
+like this:
+
+ if (foo)
+ if (bar)
+ win ();
+ else
+ lose ();
+
+always like this:
+
+ if (foo)
+ {
+ if (bar)
+ win ();
+ else
+ lose ();
+ }
+
+ If you have an `if' statement nested inside of an `else' statement,
+either write `else if' on one line, like this,
+
+ if (foo)
+ ...
+ else if (bar)
+ ...
+
+with its `then'-part indented like the preceding `then'-part, or write
+the nested `if' within braces like this:
+
+ if (foo)
+ ...
+ else
+ {
+ if (bar)
+ ...
+ }
+
+ Don't declare both a structure tag and variables or typedefs in the
+same declaration. Instead, declare the structure tag separately and
+then use it to declare the variables or typedefs.
+
+ Try to avoid assignments inside `if'-conditions. For example, don't
+write this:
+
+ if ((foo = (char *) malloc (sizeof *foo)) == 0)
+ fatal ("virtual memory exhausted");
+
+instead, write this:
+
+ foo = (char *) malloc (sizeof *foo);
+ if (foo == 0)
+ fatal ("virtual memory exhausted");
+
+ Don't make the program ugly to placate `lint'. Please don't insert
+any casts to `void'. Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+
+File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
+
+Naming 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 `enum' constants, and for name-prefixes that
+follow a uniform convention.
+
+ For example, you should use names like `ignore_space_change_flag';
+don't use names like `iCantReadThis'.
+
+ Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter. A comment should state both the exact meaning of
+the option and its letter. For example,
+
+ /* Ignore changes in horizontal whitespace (-b). */
+ int ignore_space_change_flag;
+
+ When you want to define names with constant integer values, use
+`enum' rather than `#define'. GDB knows about enumeration constants.
+
+ You might want to make sure that none of the file names would
+conflict the files were loaded onto an MS-DOS file system which
+shortens the names. You can use the program `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. `doschk' also reports file names longer than 14
+characters.
+
+
+File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
+
+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 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.
+
+ 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 (`readdir').
+
+ As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is often a lot of work. When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+
+ It is a good idea to define the "feature test macro" `_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 _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.
+
+
+File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
+
+Portability between CPUs
+========================
+
+ Even GNU systems will differ because of differences among 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
+`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
+`long' will be smaller than predefined types like `size_t'. For
+example, the following code is ok:
+
+ printf ("size = %lu\n", (unsigned long) sizeof array);
+ printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+
+ 1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows IA-64. We will
+leave it to those who want to port GNU programs to that environment to
+figure out how to do it.
+
+ Predefined file-size types like `off_t' are an exception: they are
+longer than `long' on many platforms, so code like the above won't work
+with them. One way to print an `off_t' value portably is to print its
+digits yourself, one by one.
+
+ Don't assume that the address of an `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:
+
+ int c;
+ ...
+ while ((c = getchar()) != EOF)
+ write(file_descriptor, &c, 1);
+
+ When calling functions, you need not worry about the difference
+between pointers of various types, or between pointers and integers.
+On most machines, there's no difference anyway. As for the few
+machines where there is a difference, all of them support Standard C
+prototypes, so you can use prototypes (perhaps conditionalized to be
+active only in Standard C) to make the code work on those systems.
+
+ In certain cases, it is ok to pass integer and pointer arguments
+indiscriminately to the same function, and use no prototype on any
+system. For example, many GNU programs have error-reporting functions
+that pass their arguments along to `printf' and friends:
+
+ error (s, a1, a2, a3)
+ char *s;
+ char *a1, *a2, *a3;
+ {
+ fprintf (stderr, "error: ");
+ fprintf (stderr, s, a1, a2, a3);
+ }
+
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument; it is much simpler than any
+"correct" alternative. Be sure _not_ to use a prototype for such
+functions.
+
+ If you have decided to use Standard C, then you can instead define
+`error' using `stdarg.h', and pass the arguments along to `vfprintf'.
+
+ 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 `malloc' starts far away
+from zero.
+
+
+File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
+
+Calling System 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.
+
+ * Don't use the return value of `sprintf'. It returns the number of
+ characters written on some systems, but not on all systems.
+
+ * Be aware that `vfprintf' is not always available.
+
+ * `main' should be declared to return type `int'. It should
+ terminate either by calling `exit' or by returning the integer
+ status code; make sure it cannot ever return an undefined value.
+
+ * 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.
+
+ * 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.
+
+ * In particular, don't unconditionally declare `malloc' or `realloc'.
+
+ Most GNU programs use those functions just once, in functions
+ conventionally named `xmalloc' and `xrealloc'. These functions
+ call `malloc' and `realloc', respectively, and check the results.
+
+ Because `xmalloc' and `xrealloc' are defined in your program, you
+ can declare them in other files without any risk of type conflict.
+
+ On most systems, `int' is the same length as a pointer; thus, the
+ calls to `malloc' and `realloc' work fine. For the few
+ exceptional systems (mostly 64-bit machines), you can use
+ *conditionalized* declarations of `malloc' and `realloc'--or put
+ these declarations in configuration files specific to those
+ systems.
+
+ * The string functions require special treatment. Some Unix systems
+ have a header file `string.h'; others have `strings.h'. Neither
+ file name is portable. There are two things you can do: use
+ Autoconf to figure out which file to include, or don't include
+ either file.
+
+ * If you don't include either strings file, you can't get
+ declarations for the string functions from the header file in the
+ usual way.
+
+ That causes less of a problem than you might think. The newer
+ standard string functions should be avoided anyway because many
+ systems still don't support them. The string functions you can
+ use are these:
+
+ strcpy strncpy strcat strncat
+ strlen strcmp strncmp
+ strchr strrchr
+
+ The copy and concatenate functions work fine without a declaration
+ as long as you don't use their values. Using their values without
+ a declaration fails on systems where the width of a pointer
+ differs from the width of `int', and perhaps in other cases. It
+ is trivial to avoid using their values, so do that.
+
+ The compare functions and `strlen' work fine without a declaration
+ on most systems, possibly all the ones that GNU software runs on.
+ You may find it necessary to declare them *conditionally* on a few
+ systems.
+
+ The search functions must be declared to return `char *'. Luckily,
+ there is no variation in the data type they return. But there is
+ variation in their names. Some systems give these functions the
+ names `index' and `rindex'; other systems use the names `strchr'
+ and `strrchr'. Some systems support both pairs of names, but
+ neither pair works on all systems.
+
+ You should pick a single pair of names and use it throughout your
+ program. (Nowadays, it is better to choose `strchr' and `strrchr'
+ for new programs, since those are the standard names.) Declare
+ both of those names as functions returning `char *'. On systems
+ which don't support those names, define them as macros in terms of
+ the other pair. For example, here is what to put at the beginning
+ of your file (or in a header) if you want to use the names
+ `strchr' and `strrchr' throughout:
+
+ #ifndef HAVE_STRCHR
+ #define strchr index
+ #endif
+ #ifndef HAVE_STRRCHR
+ #define strrchr rindex
+ #endif
+
+ char *strchr ();
+ char *strrchr ();
+
+ Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
+defined in systems where the corresponding functions exist. One way to
+get them properly defined is to use Autoconf.
+
+
+File: standards.info, Node: Internationalization, Next: Mmap, Prev: System Functions, Up: Writing C
+
+Internationalization
+====================
+
+ 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 `gettext' macro
+around each string that might need translation--like this:
+
+ printf (gettext ("Processing file `%s'..."));
+
+This permits GNU gettext to replace the string `"Processing file
+`%s'..."' with a translated version.
+
+ Once a program uses gettext, please make a point of writing calls to
+`gettext' when you add new strings that call for translation.
+
+ Using GNU gettext in a package involves specifying a "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, `fileutils' for the GNU file utilities.
+
+ 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:
+
+ printf ("%d file%s processed", nfiles,
+ nfiles != 1 ? "s" : "");
+
+The problem with that example is that it assumes that plurals are made
+by adding `s'. If you apply gettext to the format string, like this,
+
+ printf (gettext ("%d file%s processed"), nfiles,
+ nfiles != 1 ? "s" : "");
+
+the message can use different words, but it will still be forced to use
+`s' for the plural. Here is a better way:
+
+ printf ((nfiles != 1 ? "%d files processed"
+ : "%d file processed"),
+ nfiles);
+
+This way, you can apply gettext to each of the two strings
+independently:
+
+ printf ((nfiles != 1 ? gettext ("%d files processed")
+ : gettext ("%d file processed")),
+ nfiles);
+
+This can be any method of forming the plural of the word for "file", and
+also handles languages that require agreement in the word for
+"processed".
+
+ A similar problem appears at the level of sentence structure with
+this code:
+
+ printf ("# Implicit rule search has%s been done.\n",
+ f->tried_implicit ? "" : " not");
+
+Adding `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 `gettext'
+calls does the job straightfowardly if the code starts out like this:
+
+ printf (f->tried_implicit
+ ? "# Implicit rule search has been done.\n",
+ : "# Implicit rule search has not been done.\n");
+
+
+File: standards.info, Node: Mmap, Prev: Internationalization, Up: Writing C
+
+Mmap
+====
+
+ Don't assume that `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 `mmap' is to try it on the specific file for
+which you want to use it--and if `mmap' doesn't work, fall back on
+doing the job in another way using `read' and `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 `mmap', but
+some do not. It is important to make programs handle all these kinds
+of files.
+
+
+File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
+
+Documenting Programs
+********************
+
+ 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.
+
+
+File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
+
+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 `info' or the Emacs
+Info subsystem (`C-h i').
+
+ Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo. It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
+
+ Programmers often find it most natural to structure the documentation
+following the structure of the implementation, which they know. But
+this structure is not necessarily good for explaining how to use the
+program; it may be irrelevant and confusing for a user.
+
+ At every level, from the sentences in a paragraph to the grouping of
+topics into separate manuals, the right way to structure documentation
+is according to the concepts and questions that a user will have in mind
+when reading it. Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented--but
+often they are different. Often the most important part of learning to
+write good documentation is learning to notice when you are structuring
+the documentation like the implementation, and think about better
+alternatives.
+
+ For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual. That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+ Instead, each manual should cover a coherent _topic_. For example,
+instead of a manual for `diff' and a manual for `diff3', we have one
+manual for "comparison of files" which covers both of those programs,
+as well as `cmp'. By documenting these programs together, we can make
+the whole subject clearer.
+
+ The manual which discusses a program should certainly document all of
+the program's command-line options and all of its commands. It should
+give examples of their use. But don't organize the manual as a list of
+features. Instead, organize it logically, by subtopics. Address the
+questions that a user will ask when thinking about the job that the
+program does.
+
+ In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside). A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want. The
+Bison manual is a good example of this--please take a look at it to see
+what we mean.
+
+ That is not as hard as it first sounds. Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense. Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs. The watchword is, _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
+*Note Making Index Entries: (texinfo)Index Entries, and see *Note
+Defining the Entries of an Index: (texinfo)Indexing Commands.
+
+ 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 _in the manual_.
+
+ Please do not use the term "pathname" that is used in Unix
+documentation; use "file name" (two words) instead. We use the term
+"path" only for search paths, which are lists of directory names.
+
+ Please do not use the term "illegal" to refer to erroneous input to a
+computer program. Please use "invalid" for this, and reserve the term
+"illegal" for activities punishable by law.
+
+
+File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
+
+Doc Strings and Manuals
+=======================
+
+ Some programming systems, such as Emacs, provide a documentation
+string for each function, command or variable. You may be tempted to
+write a reference manual by compiling the documentation strings and
+writing a little additional text to go around them--but you must not do
+it. That approach is a fundamental mistake. The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+ A documentation string needs to stand alone--when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+ The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection. Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables. The previous descriptions of functions and variables in the
+section will also have given information about the topic. A description
+written to stand alone would repeat some of that information; this
+redundance looks bad. Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+ The only good way to use documentation strings in writing a good
+manual is to use them as a source of information for writing good text.
+
+
+File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
+
+Manual Structure Details
+========================
+
+ 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
+`PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
+its subnodes, if any) should describe the program's command line
+arguments and how to run it (the sort of information people would look
+in a man page for). Start with an `@example' containing a template for
+all the options and arguments that the program uses.
+
+ Alternatively, put a menu item in some menu whose item name fits one
+of the above patterns. This identifies the node which that item points
+to as the node for this purpose, regardless of the node's actual name.
+
+ The `--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.
+
+
+File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
+
+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 `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.
+
+
+File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
+
+Manual Credits
+==============
+
+ 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.
+
+
+File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
+
+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 . 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.
+
+
+File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
+
+The NEWS File
+=============
+
+ In addition to its manual, the package should have a file named
+`NEWS' which contains a list of user-visible changes worth mentioning.
+In each new release, add items to the front of the file and identify
+the version they pertain to. Don't discard old items; leave them in
+the file after the newer items. This way, a user upgrading from any
+previous version can see what is new.
+
+ If the `NEWS' file gets very long, move some of the older items into
+a file named `ONEWS' and put a note at the end referring the user to
+that file.
+
+
+File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
+
+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::
+
+
+File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
+
+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 `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 `ChangeLog' file using `rcs2log'; in Emacs, the
+command `C-x v a' (`vc-update-change-log') does the job.
+
+ There's no need to describe the full purpose of the changes or how
+they work together. If you think that a change calls for explanation,
+you're probably right. Please do explain it--but please put the
+explanation in comments in the code, where people will see it whenever
+they see the code. For example, "New function" is enough for the
+change log when you add a function, because there should be a comment
+before the function definition to explain what it does.
+
+ However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
+
+ The easiest way to add an entry to `ChangeLog' is with the Emacs
+command `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.
+
+
+File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
+
+Style of Change Logs
+--------------------
+
+ Here are some simple examples of change log entries, starting with
+the header line that says who made the change and when, followed by
+descriptions of specific changes. (These examples are drawn from Emacs
+and GCC.)
+
+ 1998-08-17 Richard Stallman
+
+ * register.el (insert-register): Return nil.
+ (jump-to-register): Likewise.
+
+ * sort.el (sort-subr): Return nil.
+
+ * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+ Restart the tex shell if process is gone or stopped.
+ (tex-shell-running): New function.
+
+ * expr.c (store_one_arg): Round size up for move_block_to_reg.
+ (expand_call): Round up when emitting USE insns.
+ * stmt.c (assign_parms): Round size up for move_block_from_reg.
+
+ It's important to name the changed function or variable in full.
+Don't abbreviate 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 `* register.el ({insert,jump-to}-register)'; this is
+not a good idea, since searching for `jump-to-register' or
+`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
+`)', rather than `,', and opening the continuation with `(' as in this
+example:
+
+ * keyboard.c (menu_bar_items, tool_bar_items)
+ (Fexecute_extended_command): Deal with `keymap' property.
+
+
+File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
+
+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:
+
+ * keyboard.c (Fcommand_execute): New arg SPECIAL.
+ All callers changed.
+
+ When you change just comments or doc strings, it is enough to write
+an entry for the file, without mentioning the functions. Just "Doc
+fixes" is enough for the change log.
+
+ There's no need to make change log entries for documentation files.
+This is because documentation is not susceptible to bugs that are hard
+to fix. Documentation does not consist of parts that must interact in a
+precisely engineered fashion. To correct an error, you need not know
+the history of the erroneous passage; it is enough to compare what the
+documentation says with the way the program actually works.
+
+
+File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
+
+Conditional Changes
+-------------------
+
+ C programs often contain compile-time `#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:
+
+ * xterm.c [SOLARIS2]: Include string.h.
+
+ Here is an entry describing a new definition which is entirely
+conditional. This new definition for the macro `FRAME_WINDOW_P' is
+used only when `HAVE_X_WINDOWS' is defined:
+
+ * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+
+ Here is an entry for a change within the function `init_display',
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
+
+ * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+
+ Here is an entry for a change that takes affect only when a certain
+macro is _not_ defined:
+
+ (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+
+
+File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
+
+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 `sh-while-getopts' that deals
+with `sh' commands:
+
+ * progmodes/sh-script.el (sh-while-getopts) : Handle case that
+ user-specified option string is empty.
+
+
+File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
+
+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.
+
+
+File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
+
+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.
+
+
+File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
+
+The Release Process
+*******************
+
+ Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP. You should set up your software so
+that it can be configured to run on a variety of systems. Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below. Doing so
+makes it easy to include your package into the larger framework of all
+GNU software.
+
+* Menu:
+
+* Configuration:: How Configuration Should Work
+* Makefile Conventions:: Makefile Conventions
+* Releases:: Making Releases
+
+
+File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
+
+How Configuration Should Work
+=============================
+
+ Each GNU distribution should come with a shell script named
+`configure'. This script is given arguments which describe the kind of
+machine and system you want to compile the program for.
+
+ The `configure' script must record the configuration options so that
+they affect compilation.
+
+ One way to do this is to make a link from a standard name such as
+`config.h' to the proper configuration file for the chosen system. If
+you use this technique, the distribution should _not_ contain a file
+named `config.h'. This is so that people won't be able to build the
+program without configuring it first.
+
+ Another thing that `configure' can do is to edit the Makefile. If
+you do this, the distribution should _not_ contain a file named
+`Makefile'. Instead, it should include a file `Makefile.in' which
+contains the input used for editing. Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+ If `configure' does write the `Makefile', then `Makefile' should
+have a target named `Makefile' which causes `configure' to be rerun,
+setting up the same configuration that was set up last time. The files
+that `configure' reads should be listed as dependencies of `Makefile'.
+
+ All the files which are output from the `configure' script should
+have comments at the beginning explaining that they were generated
+automatically using `configure'. This is so that users won't think of
+trying to edit them by hand.
+
+ The `configure' script should write a file named `config.status'
+which describes which configuration options were specified when the
+program was last configured. This file should be a shell script which,
+if run, will recreate the same configuration.
+
+ The `configure' script should accept an option of the form
+`--srcdir=DIRNAME' to specify the directory where sources are found (if
+it is not the current directory). This makes it possible to build the
+program in a separate directory, so that the actual source directory is
+not modified.
+
+ If the user does not specify `--srcdir', then `configure' should
+check both `.' and `..' to see if it can find the sources. If it finds
+the sources in one of these places, it should use them from there.
+Otherwise, it should report that it cannot find the sources, and should
+exit with nonzero status.
+
+ Usually the easy way to support `--srcdir' is by editing a
+definition of `VPATH' into the Makefile. Some rules may need to refer
+explicitly to the specified source directory. To make this possible,
+`configure' can add to the Makefile a variable named `srcdir' whose
+value is precisely the specified directory.
+
+ The `configure' script should also take an argument which specifies
+the type of system to build the program for. This argument should look
+like this:
+
+ CPU-COMPANY-SYSTEM
+
+ For example, a Sun 3 might be `m68k-sun-sunos4.1'.
+
+ The `configure' script needs to be able to decode all plausible
+alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
+would be a valid alias. For many programs, `vax-dec-ultrix' would be
+an alias for `vax-dec-bsd', simply because the differences between
+Ultrix and BSD are rarely noticeable, but a few programs might need to
+distinguish them.
+
+ There is a shell script called `config.sub' that you can use as a
+subroutine to validate system types and canonicalize aliases.
+
+ Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+
+`--enable-FEATURE[=PARAMETER]'
+ Configure the package to build and install an optional user-level
+ facility called FEATURE. This allows users to choose which
+ optional features to include. Giving an optional PARAMETER of
+ `no' should omit FEATURE, if it is built by default.
+
+ No `--enable' option should *ever* cause one feature to replace
+ another. No `--enable' option should ever substitute one useful
+ behavior for another useful behavior. The only proper use for
+ `--enable' is for questions of whether to build part of the program
+ or exclude it.
+
+`--with-PACKAGE'
+ The package PACKAGE will be installed, so configure this package
+ to work with PACKAGE.
+
+ Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
+ `gnu-libc', `gdb', `x', and `x-toolkit'.
+
+ Do not use a `--with' option to specify the file name to use to
+ find certain files. That is outside the scope of what `--with'
+ options are for.
+
+ All `configure' scripts should accept all of these "detail" options,
+whether or not they make any difference to the particular package at
+hand. In particular, they should accept any option that starts with
+`--with-' or `--enable-'. This is so users will be able to configure
+an entire GNU source tree at once with a single set of options.
+
+ You will note that the categories `--with-' and `--enable-' are
+narrow: they *do not* provide a place for any sort of option you might
+think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
+
+ Packages that perform part of the compilation process may support
+cross-compilation. In such a case, the host and target machines for the
+program may be different.
+
+ The `configure' script should normally treat the specified type of
+system as both the host and the target, thus producing a program which
+works for the same type of machine that it runs on.
+
+ To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
+for the host type. So the command would look like this:
+
+ ./configure HOSTTYPE --target=TARGETTYPE
+
+ Programs for which cross-operation is not meaningful need not accept
+the `--target' option, because configuring an entire operating system
+for cross-operation is not a meaningful operation.
+
+ Bootstrapping a cross-compiler requires compiling it on a machine
+other than the host it will run on. Compilation packages accept a
+configuration option `--build=BUILDTYPE' for specifying the
+configuration on which you will compile them, but the configure script
+should normally guess the build machine type (using `config.guess'), so
+this option is probably not necessary. The host and target types
+normally default from the build type, so in bootstrapping a
+cross-compiler you must specify them both explicitly.
+
+ Some programs have ways of configuring themselves automatically. If
+your program is set up to do this, your `configure' script can simply
+ignore most of its arguments.
+
+
+File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
+
+Makefile Conventions
+====================
+
+ This node describes conventions for writing the Makefiles for GNU
+programs. Using Automake will help you write a Makefile that follows
+these conventions.
+
+* Menu:
+
+* Makefile Basics:: General Conventions for Makefiles
+* Utilities in Makefiles:: Utilities in Makefiles
+* Command Variables:: Variables for Specifying Commands
+* Directory Variables:: Variables for Installation Directories
+* Standard Targets:: Standard Targets for Users
+* Install Command Categories:: Three categories of commands in the `install'
+ rule: normal, pre-install and post-install.
+
+
+File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
+
+General Conventions for Makefiles
+---------------------------------
+
+ Every Makefile should contain this line:
+
+ SHELL = /bin/sh
+
+to avoid trouble on systems where the `SHELL' variable might be
+inherited from the environment. (This is never a problem with GNU
+`make'.)
+
+ Different `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:
+
+ .SUFFIXES:
+ .SUFFIXES: .c .o
+
+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 `.' is in the path for command execution. When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses `./' if the program is built as
+part of the make or `$(srcdir)/' if the file is an unchanging part of
+the source code. Without one of these prefixes, the current search
+path is used.
+
+ The distinction between `./' (the "build directory") and
+`$(srcdir)/' (the "source directory") is important because users can
+build in a separate directory using the `--srcdir' option to
+`configure'. A rule of the form:
+
+ foo.1 : foo.man sedscript
+ sed -e sedscript foo.man > foo.1
+
+will fail when the build directory is not the source directory, because
+`foo.man' and `sedscript' are in the source directory.
+
+ When using GNU `make', relying on `VPATH' to find the source file
+will work in the case where there is a single dependency file, since
+the `make' automatic variable `$<' will represent the source file
+wherever it is. (Many versions of `make' set `$<' only in implicit
+rules.) A Makefile target like
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+
+should instead be written as
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
+
+in order to allow `VPATH' to work correctly. When the target has
+multiple dependencies, using an explicit `$(srcdir)' is the easiest way
+to make the rule work well. For example, the target above for `foo.1'
+is best written as:
+
+ foo.1 : foo.man sedscript
+ sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
+
+ 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 `make'.
+
+
+File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
+
+Utilities in Makefiles
+----------------------
+
+ Write the Makefile commands (and any shell scripts, such as
+`configure') to run in `sh', not in `csh'. Don't use any special
+features of `ksh' or `bash'.
+
+ The `configure' script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+ cat cmp cp diff echo egrep expr false grep install-info
+ ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+
+ The compression program `gzip' can be used in the `dist' rule.
+
+ Stick to the generally supported options for these programs. For
+example, don't use `mkdir -p', convenient as it may be, because most
+systems don't support it.
+
+ 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 `make' variables
+so that the user can substitute alternatives. Here are some of the
+programs we mean:
+
+ ar bison cc flex install ld ldconfig lex
+ make makeinfo ranlib texi2dvi yacc
+
+ Use the following `make' variables to run those programs:
+
+ $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+ $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+
+ When you use `ranlib' or `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 `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:
+
+ chgrp chmod chown mknod
+
+ It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+
+File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
+
+Variables for Specifying Commands
+---------------------------------
+
+ Makefiles should provide variables for overriding certain commands,
+options, and so on.
+
+ In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named `BISON' whose default
+value is set with `BISON = bison', and refer to it with `$(BISON)'
+whenever you need to use Bison.
+
+ File management utilities such as `ln', `rm', `mv', and so on, need
+not be referred to through variables in this way, since users don't
+need to replace them with other programs.
+
+ Each program-name variable should come with an options variable that
+is used to supply options to the program. Append `FLAGS' to the
+program-name variable name to get the options variable name--for
+example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
+`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
+but we keep them because they are standard.) Use `CPPFLAGS' in any
+compilation command that runs the preprocessor, and use `LDFLAGS' in
+any compilation command that does linking as well as in any direct use
+of `ld'.
+
+ If there are C compiler options that _must_ be used for proper
+compilation of certain files, do not include them in `CFLAGS'. Users
+expect to be able to specify `CFLAGS' freely themselves. Instead,
+arrange to pass the necessary options to the C compiler independently
+of `CFLAGS', by writing them explicitly in the compilation commands or
+by defining an implicit rule, like this:
+
+ CFLAGS = -g
+ ALL_CFLAGS = -I. $(CFLAGS)
+ .c.o:
+ $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+
+ Do include the `-g' option in `CFLAGS', because that is not
+_required_ for proper compilation. You can consider it a default that
+is only recommended. If the package is set up so that it is compiled
+with GCC by default, then you might as well include `-O' in the default
+value of `CFLAGS' as well.
+
+ Put `CFLAGS' last in the compilation command, after other variables
+containing compiler options, so the user can use `CFLAGS' to override
+the others.
+
+ `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 `INSTALL', which is the
+basic command for installing a file into the system.
+
+ Every Makefile should also define the variables `INSTALL_PROGRAM'
+and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
+`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
+644'.) Then it should use those variables as the commands for actual
+installation, for executables and nonexecutables respectively. Use
+these variables as follows:
+
+ $(INSTALL_PROGRAM) foo $(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+
+ Optionally, you may prepend the value of `DESTDIR' to the target
+filename. Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later. Do not
+set the value of `DESTDIR' in your Makefile, and do not include it in
+any installed files. With support for `DESTDIR', the above examples
+become:
+
+ $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+
+Always use a file name, not a directory name, as the second argument of
+the installation commands. Use a separate command for each file to be
+installed.
+
+
+File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
+
+Variables for Installation Directories
+--------------------------------------
+
+ Installation directories should always be named by variables, so it
+is easy to install in a nonstandard place. The standard names for these
+variables are described below. They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
+and other modern operating systems.
+
+ These two variables set the root for the installation. All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+`prefix'
+ A prefix used in constructing the default values of the variables
+ listed below. The default value of `prefix' should be
+ `/usr/local'. When building the complete GNU system, the prefix
+ will be empty and `/usr' will be a symbolic link to `/'. (If you
+ are using Autoconf, write it as `@prefix@'.)
+
+ Running `make install' with a different value of `prefix' from the
+ one used to build the program should _not_ recompile the program.
+
+`exec_prefix'
+ A prefix used in constructing the default values of some of the
+ variables listed below. The default value of `exec_prefix' should
+ be `$(prefix)'. (If you are using Autoconf, write it as
+ `@exec_prefix@'.)
+
+ Generally, `$(exec_prefix)' is used for directories that contain
+ machine-specific files (such as executables and subroutine
+ libraries), while `$(prefix)' is used directly for other
+ directories.
+
+ Running `make install' with a different value of `exec_prefix'
+ from the one used to build the program should _not_ recompile the
+ program.
+
+ Executable programs are installed in one of the following
+directories.
+
+`bindir'
+ The directory for installing executable programs that users can
+ run. This should normally be `/usr/local/bin', but write it as
+ `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
+ `@bindir@'.)
+
+`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 `/usr/local/sbin', but
+ write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
+ write it as `@sbindir@'.)
+
+`libexecdir'
+ The directory for installing executable programs to be run by other
+ programs rather than by users. This directory should normally be
+ `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
+ (If you are using Autoconf, write it as `@libexecdir@'.)
+
+ Data files used by the program during its execution are divided into
+categories in two ways.
+
+ * Some files are normally modified by programs; others are never
+ normally modified (though users may edit some of these).
+
+ * 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.
+
+ This makes for six different possibilities. However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries. It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+ Therefore, here are the variables Makefiles should use to specify
+directories:
+
+`datadir'
+ The directory for installing read-only architecture independent
+ data files. This should normally be `/usr/local/share', but write
+ it as `$(prefix)/share'. (If you are using Autoconf, write it as
+ `@datadir@'.) As a special exception, see `$(infodir)' and
+ `$(includedir)' below.
+
+`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, `/etc/passwd', and so
+ forth belong here. All the files in this directory should be
+ ordinary ASCII text files. This directory should normally be
+ `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
+ using Autoconf, write it as `@sysconfdir@'.)
+
+ Do not install executables here in this directory (they probably
+ belong in `$(libexecdir)' or `$(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 `$(localstatedir)'.
+
+`sharedstatedir'
+ The directory for installing architecture-independent data files
+ which the programs modify while they run. This should normally be
+ `/usr/local/com', but write it as `$(prefix)/com'. (If you are
+ using Autoconf, write it as `@sharedstatedir@'.)
+
+`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 `$(datadir)' or `$(sysconfdir)'.
+ `$(localstatedir)' should normally be `/usr/local/var', but write
+ it as `$(prefix)/var'. (If you are using Autoconf, write it as
+ `@localstatedir@'.)
+
+`libdir'
+ The directory for object files and libraries of object code. Do
+ not install executables here, they probably ought to go in
+ `$(libexecdir)' instead. The value of `libdir' should normally be
+ `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
+ are using Autoconf, write it as `@libdir@'.)
+
+`infodir'
+ The directory for installing the Info files for this package. By
+ default, it should be `/usr/local/info', but it should be written
+ as `$(prefix)/info'. (If you are using Autoconf, write it as
+ `@infodir@'.)
+
+`lispdir'
+ The directory for installing any Emacs Lisp files in this package.
+ By default, it should be `/usr/local/share/emacs/site-lisp', but
+ it should be written as `$(prefix)/share/emacs/site-lisp'.
+
+ If you are using Autoconf, write the default as `@lispdir@'. In
+ order to make `@lispdir@' work, you need the following lines in
+ your `configure.in' file:
+
+ lispdir='${datadir}/emacs/site-lisp'
+ AC_SUBST(lispdir)
+
+`includedir'
+ The directory for installing header files to be included by user
+ programs with the C `#include' preprocessor directive. This
+ should normally be `/usr/local/include', but write it as
+ `$(prefix)/include'. (If you are using Autoconf, write it as
+ `@includedir@'.)
+
+ Most compilers other than GCC do not look for header files in
+ directory `/usr/local/include'. So installing the header files
+ this way is only useful with GCC. Sometimes this is not a problem
+ because some libraries are only really intended to work with GCC.
+ But some libraries are intended to work with other compilers.
+ They should install their header files in two places, one
+ specified by `includedir' and one specified by `oldincludedir'.
+
+`oldincludedir'
+ The directory for installing `#include' header files for use with
+ compilers other than GCC. This should normally be `/usr/include'.
+ (If you are using Autoconf, you can write it as `@oldincludedir@'.)
+
+ The Makefile commands should check whether the value of
+ `oldincludedir' is empty. If it is, they should not try to use
+ it; they should cancel the second installation of the header files.
+
+ A package should not replace an existing header in this directory
+ unless the header came from the same package. Thus, if your Foo
+ package provides a header file `foo.h', then it should install the
+ header file in the `oldincludedir' directory if either (1) there
+ is no `foo.h' there or (2) the `foo.h' that exists came from the
+ Foo package.
+
+ To tell whether `foo.h' came from the Foo package, put a magic
+ string in the file--part of a comment--and `grep' for that string.
+
+ Unix-style man pages are installed in one of the following:
+
+`mandir'
+ The top-level directory for installing the man pages (if any) for
+ this package. It will normally be `/usr/local/man', but you should
+ write it as `$(prefix)/man'. (If you are using Autoconf, write it
+ as `@mandir@'.)
+
+`man1dir'
+ The directory for installing section 1 man pages. Write it as
+ `$(mandir)/man1'.
+
+`man2dir'
+ The directory for installing section 2 man pages. Write it as
+ `$(mandir)/man2'
+
+`...'
+ *Don't make the primary documentation for any GNU software be a
+ man page. Write a manual in Texinfo instead. Man pages are just
+ for the sake of people running GNU software on Unix, which is a
+ secondary application only.*
+
+`manext'
+ The file name extension for the installed man page. This should
+ contain a period followed by the appropriate digit; it should
+ normally be `.1'.
+
+`man1ext'
+ The file name extension for installed section 1 man pages.
+
+`man2ext'
+ The file name extension for installed section 2 man pages.
+
+`...'
+ Use these names instead of `manext' if the package needs to
+ install man pages in more than one section of the manual.
+
+ And finally, you should set the following variable:
+
+`srcdir'
+ The directory for the sources being compiled. The value of this
+ variable is normally inserted by the `configure' shell script.
+ (If you are using Autconf, use `srcdir = @srcdir@'.)
+
+ For example:
+
+ # Common prefix for installation directories.
+ # NOTE: This directory must exist when you start the install.
+ prefix = /usr/local
+ exec_prefix = $(prefix)
+ # Where to put the executable for the command `gcc'.
+ bindir = $(exec_prefix)/bin
+ # Where to put the directories used by the compiler.
+ libexecdir = $(exec_prefix)/libexec
+ # Where to put the Info files.
+ infodir = $(prefix)/info
+
+ If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program. If you do this, you
+should write the `install' rule to create these subdirectories.
+
+ Do not expect the user to include the subdirectory name in the value
+of any of the variables listed above. The idea of having a uniform set
+of variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages. In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+
+File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
+
+Standard Targets for Users
+--------------------------
+
+ All GNU programs should have the following targets in their
+Makefiles:
+
+`all'
+ Compile the entire program. This should be the default target.
+ This target need not rebuild any documentation files; Info files
+ should normally be included in the distribution, and DVI files
+ should be made only when explicitly asked for.
+
+ By default, the Make rules should compile and link with `-g', so
+ that executable programs have debugging symbols. Users who don't
+ mind being helpless can strip the executables later if they wish.
+
+`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 `install-strip' target to do that.
+
+ If possible, write the `install' target rule so that it does not
+ modify anything in the directory where the program was built,
+ provided `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 `prefix' and
+ `exec_prefix', as well as all subdirectories that are needed. One
+ way to do this is by means of an `installdirs' target as described
+ below.
+
+ Use `-' before any command for installing a man page, so that
+ `make' will ignore any errors. This is in case there are systems
+ that don't have the Unix man page documentation system installed.
+
+ The way to install Info files is to copy them into `$(infodir)'
+ with `$(INSTALL_DATA)' (*note Command Variables::), and then run
+ the `install-info' program if it is present. `install-info' is a
+ program that edits the Info `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:
+
+ $(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
+
+ When writing the `install' target, you must classify all the
+ commands into three categories: normal ones, "pre-installation"
+ commands and "post-installation" commands. *Note Install Command
+ Categories::.
+
+`uninstall'
+ Delete all the installed files--the copies that the `install'
+ target creates.
+
+ This rule should not modify the directories where compilation is
+ done, only the directories where files are installed.
+
+ The uninstallation commands are divided into three categories,
+ just like the installation commands. *Note Install Command
+ Categories::.
+
+`install-strip'
+ Like `install', but strip the executable files while installing
+ them. In simple cases, this target can use the `install' target in
+ a simple way:
+
+ install-strip:
+ $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+ install
+
+ But if the package installs scripts as well as real executables,
+ the `install-strip' target can't just refer to the `install'
+ target; it has to strip the executables but not the scripts.
+
+ `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.
+
+`clean'
+ Delete all files from the current directory that are normally
+ created by building the program. Don't delete the files that
+ record the configuration. Also preserve files that could be made
+ by building, but normally aren't because the distribution comes
+ with them.
+
+ Delete `.dvi' files here if they are not part of the distribution.
+
+`distclean'
+ Delete all files from the current directory that are created by
+ configuring or building the program. If you have unpacked the
+ source and built the program without creating any other files,
+ `make distclean' should leave only the files that were in the
+ distribution.
+
+`mostlyclean'
+ Like `clean', but may refrain from deleting a few files that people
+ normally don't want to recompile. For example, the `mostlyclean'
+ target for GCC does not delete `libgcc.a', because recompiling it
+ is rarely necessary and takes a lot of time.
+
+`maintainer-clean'
+ Delete almost everything from the current directory that can be
+ reconstructed with this Makefile. This typically includes
+ everything deleted by `distclean', plus more: C source files
+ produced by Bison, tags tables, Info files, and so on.
+
+ The reason we say "almost everything" is that running the command
+ `make maintainer-clean' should not delete `configure' even if
+ `configure' can be remade using a rule in the Makefile. More
+ generally, `make maintainer-clean' should not delete anything that
+ needs to exist in order to run `configure' and then begin to build
+ the program. This is the only exception; `maintainer-clean' should
+ delete everything else that can be rebuilt.
+
+ The `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 `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
+ `maintainer-clean' target should start with these two:
+
+ @echo 'This command is intended for maintainers to use; it'
+ @echo 'deletes files that may need special tools to rebuild.'
+
+`TAGS'
+ Update a tags table for this program.
+
+`info'
+ Generate any Info files needed. The best way to write the rules
+ is as follows:
+
+ info: foo.info
+
+ foo.info: foo.texi chap1.texi chap2.texi
+ $(MAKEINFO) $(srcdir)/foo.texi
+
+ You must define the variable `MAKEINFO' in the Makefile. It should
+ run the `makeinfo' program, which is part of the Texinfo
+ distribution.
+
+ 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.
+
+`dvi'
+ Generate DVI files for all Texinfo documentation. For example:
+
+ dvi: foo.dvi
+
+ foo.dvi: foo.texi chap1.texi chap2.texi
+ $(TEXI2DVI) $(srcdir)/foo.texi
+
+ You must define the variable `TEXI2DVI' in the Makefile. It should
+ run the program `texi2dvi', which is part of the Texinfo
+ distribution.(1) Alternatively, write just the dependencies, and
+ allow GNU `make' to provide the command.
+
+`dist'
+ Create a distribution tar file for this program. The tar file
+ should be set up so that the file names in the tar file start with
+ a subdirectory name which is the name of the package it is a
+ distribution for. This name can include the version number.
+
+ For example, the distribution tar file of GCC version 1.40 unpacks
+ into a subdirectory named `gcc-1.40'.
+
+ The easiest way to do this is to create a subdirectory
+ appropriately named, use `ln' or `cp' to install the proper files
+ in it, and then `tar' that subdirectory.
+
+ Compress the tar file with `gzip'. For example, the actual
+ distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
+
+ The `dist' target should explicitly depend on all non-source files
+ that are in the distribution, to make sure they are up to date in
+ the distribution. *Note Making Releases: Releases.
+
+`check'
+ Perform self-tests (if any). The user must build the program
+ before running the tests, but need not install the program; you
+ should write the self-tests so that they work when the program is
+ built but not installed.
+
+ The following targets are suggested as conventional names, for
+programs in which they are useful.
+
+`installcheck'
+ Perform installation tests (if any). The user must build and
+ install the program before running the tests. You should not
+ assume that `$(bindir)' is in the search path.
+
+`installdirs'
+ It's useful to add a target named `installdirs' to create the
+ directories where files are installed, and their parent
+ directories. There is a script called `mkinstalldirs' which is
+ convenient for this; you can find it in the Texinfo package. You
+ can use a rule like this:
+
+ # Make sure all installation directories (e.g. $(bindir))
+ # actually exist by making them if necessary.
+ installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+ $(libdir) $(infodir) \
+ $(mandir)
+
+ or, if you wish to support `DESTDIR',
+
+ # 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)
+
+ This rule should not modify the directories where compilation is
+ done. It should do nothing but create installation directories.
+
+ ---------- Footnotes ----------
+
+ (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
+not distributed with Texinfo.
+
+
+File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
+
+Install Command Categories
+--------------------------
+
+ When writing the `install' target, you must classify all the
+commands into three categories: normal ones, "pre-installation"
+commands and "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
+`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 `install' rule into these three
+categories, insert "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
+_should not_ define them in the makefile).
+
+ Here are the three possible category lines, each with a comment that
+explains what it means:
+
+ $(PRE_INSTALL) # Pre-install commands follow.
+ $(POST_INSTALL) # Post-install commands follow.
+ $(NORMAL_INSTALL) # Normal commands follow.
+
+ If you don't use a category line at the beginning of the `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 `uninstall':
+
+ $(PRE_UNINSTALL) # Pre-uninstall commands follow.
+ $(POST_UNINSTALL) # Post-uninstall commands follow.
+ $(NORMAL_UNINSTALL) # Normal commands follow.
+
+ Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+ If the `install' or `uninstall' target has any dependencies which
+act as subroutines of installation, then you should start _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:
+
+ [ 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
+
+ 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:
+
+ make -n install -o all \
+ PRE_INSTALL=pre-install \
+ POST_INSTALL=post-install \
+ NORMAL_INSTALL=normal-install \
+ | gawk -f pre-install.awk
+
+where the file `pre-install.awk' could contain this:
+
+ $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
+ on {print $0}
+ $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
+
+ The resulting file of pre-installation commands is executed as a
+shell script as part of installing the binary package.
+
+
+File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
+
+Making Releases
+===============
+
+ Package the distribution of `Foo version 69.96' up in a gzipped tar
+file with the name `foo-69.96.tar.gz'. It should unpack into a
+subdirectory named `foo-69.96'.
+
+ Building and installing the program should never modify any of the
+files contained in the distribution. This means that all the files
+that form part of the program in any way must be classified into "source
+files" and "non-source files". Source files are written by humans and
+never changed automatically; non-source files are produced from source
+files by programs under the control of the Makefile.
+
+ The distribution should contain a file named `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 `README' file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+ The `README' file should refer to the file `INSTALL', which should
+contain an explanation of the installation procedure.
+
+ The `README' file should also refer to the file which contains the
+copying conditions. The GNU GPL, if used, should be in a file called
+`COPYING'. If the GNU LGPL is used, it should be in a file called
+`COPYING.LIB'.
+
+ Naturally, all the source files must be in the distribution. It is
+okay to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them. We commonly include non-source files
+produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+ Non-source files that might actually be modified by building and
+installing the program should *never* be included in the distribution.
+So if you do distribute non-source files, always make sure they are up
+to date when you make a new distribution.
+
+ Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of `tar' which preserve the ownership and
+permissions of the files from the tar archive will be able to extract
+all the files even if the user is unprivileged.
+
+ Make sure that all the files in the distribution are world-readable.
+
+ Make sure that no file name in the distribution is more than 14
+characters long. Likewise, no file created by building the program
+should have a name longer than 14 characters. The reason for this is
+that some systems adhere to a foolish interpretation of the POSIX
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+ Don't include any symbolic links in the distribution itself. If the
+tar file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links. Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the distribution.
+
+ Try to make sure that all the file names will be unique on MS-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, `foobarhacker.c'
+and `foobarhacker.o' are not ambiguous; they are truncated to
+`foobarha.c' and `foobarha.o', which are distinct.
+
+ Include in your distribution a copy of the `texinfo.tex' you used to
+test print any `*.texinfo' or `*.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.
+
+
+File: standards.info, Node: References, Next: Copying This Manual, Prev: Managing Releases, Up: Top
+
+References to Non-Free Software and Documentation
+*************************************************
+
+ A GNU program should not recommend use of any non-free program. We
+can't stop some people from writing proprietary programs, or stop other
+people from using them, but we can and should avoid helping to
+advertise them to new potential customers. Proprietary software is a
+social and ethical problem, and the point of GNU is to solve that
+problem.
+
+ When a non-free program or system is well known, you can mention it
+in passing--that is harmless, since users who might want to use it
+probably already know about it. For instance, it is fine to explain
+how to build your package on top of some non-free operating system, or
+how to use it together with some widely used non-free program.
+
+ However, you should give only the necessary information to help those
+who already use the non-free program to use your program with it--don't
+give, or refer to, any further information about the proprietary
+program, and don't imply that the proprietary program enhances your
+program, or that its existence is in any way a good thing. The goal
+should be that people already using the proprietary program will get
+the advice they need about how to use your free program, while people
+who don't already use the proprietary program will not see anything to
+lead them to take an interest in it.
+
+ If a non-free program or system is obscure in your program's domain,
+your program should not mention or support it at all, since doing so
+would tend to popularize the non-free program more than it popularizes
+your program. (You cannot hope to find many additional users among the
+users of Foobar if the users of Foobar are few.)
+
+ A GNU package should not refer the user to any non-free documentation
+for free software. Free documentation that can be included in free
+operating systems is essential for completing the GNU system, so it is
+a major focus of the GNU Project; to recommend use of documentation
+that we are not allowed to use in GNU would undermine the efforts to
+get documentation that we can include. So GNU packages should never
+recommend non-free documentation.
+
+
+File: standards.info, Node: Copying This Manual, Next: Index, Prev: References, Up: Top
+
+Copying This Manual
+*******************
+
+* Menu:
+
+* GNU Free Documentation License:: License for copying this manual
+
+
+File: standards.info, Node: GNU Free Documentation License, Up: Copying This Manual
+
+GNU Free Documentation License
+******************************
+
+ Version 1.1, March 2000
+ Copyright (C) 2000 Free Software Foundation, Inc.
+ 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ written document "free" in the sense of freedom: to assure everyone
+ the effective freedom to copy and redistribute it, with or without
+ modifying it, either commercially or noncommercially. Secondarily,
+ this License preserves for the author and publisher a way to get
+ credit for their work, while not being considered responsible for
+ modifications made by others.
+
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book.
+ We recommend this License principally for works whose purpose is
+ instruction or reference.
+
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work that contains a
+ notice placed by the copyright holder saying it can be distributed
+ under the terms of this License. The "Document", below, refers to
+ any such manual or work. Any member of the public is a licensee,
+ and is addressed as "you."
+
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A "Secondary Section" is a named appendix or a front-matter
+ section of the Document that deals exclusively with the
+ relationship of the publishers or authors of the Document to the
+ Document's overall subject (or to related matters) and contains
+ nothing that could fall directly within that overall subject.
+ (For example, if the Document is in part a textbook of
+ mathematics, a Secondary Section may not explain any mathematics.)
+ The relationship could be a matter of historical connection with
+ the subject or with related matters, or of legal, commercial,
+ philosophical, ethical or political position regarding them.
+
+ The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in
+ the notice that says that the Document is released under this
+ License.
+
+ The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License.
+
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, whose contents can be viewed and edited directly
+ and straightforwardly with generic text editors or (for images
+ composed of pixels) generic paint programs or (for drawings) some
+ widely available drawing editor, and that is suitable for input to
+ text formatters or for automatic translation to a variety of
+ formats suitable for input to text formatters. A copy made in an
+ otherwise Transparent file format whose markup has been designed
+ to thwart or discourage subsequent modification by readers is not
+ Transparent. A copy that is not "Transparent" is called "Opaque."
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and
+ standard-conforming simple HTML designed for human modification.
+ Opaque formats include PostScript, PDF, proprietary formats that
+ can be read and edited only by proprietary word processors, SGML
+ or XML for which the DTD and/or processing tools are not generally
+ available, and the machine-generated HTML produced by some word
+ processors for output purposes only.
+
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, "Title
+ Page" means the text near the most prominent appearance of the
+ work's title, preceding the beginning of the body of the text.
+
+
+ 2. 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.
+
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies of the Document numbering more than
+ 100, and the Document's license notice requires Cover Texts, you
+ must enclose the copies in covers that carry, clearly and legibly,
+ all these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the
+ title equally prominent and visible. You may add other material
+ on the covers in addition. Copying with changes limited to the
+ covers, as long as they preserve the title of the Document and
+ satisfy these conditions, can be treated as verbatim copying in
+ other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a
+ machine-readable Transparent copy along with each Opaque copy, or
+ state in or with each Opaque copy a publicly-accessible
+ computer-network location containing a complete Transparent copy
+ of the Document, free of added material, which the general
+ network-using public has access to download anonymously at no
+ charge using public-standard network protocols. If you use the
+ latter option, you must take reasonably prudent steps, when you
+ begin distribution of Opaque copies in quantity, to ensure that
+ this Transparent copy will remain thus accessible at the stated
+ location until at least one year after the last time you
+ distribute an Opaque copy (directly or through your agents or
+ retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of
+ copies, to give them a chance to provide you with an updated
+ version of the Document.
+
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with
+ the Modified Version filling the role of the Document, thus
+ licensing distribution and modification of the Modified Version to
+ whoever possesses a copy of it. In addition, you must do these
+ things in the Modified Version:
+
+ A. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of previous
+ versions (which should, if there were any, be listed in the
+ History section of the Document). You may use the same title
+ as a previous version if the original publisher of that version
+ gives permission.
+ B. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in the
+ Modified Version, together with at least five of the principal
+ authors of the Document (all of its principal authors, if it
+ has less than five).
+ C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+ D. Preserve all the copyright notices of the Document.
+ E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+ F. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified Version
+ under the terms of this License, in the form shown in the
+ Addendum below.
+ G. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's
+ license notice.
+ H. Include an unaltered copy of this License.
+ I. Preserve the section entitled "History", and its title, and add
+ to it an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title Page.
+ If there is no section entitled "History" in the Document,
+ create one stating the title, year, authors, and publisher of
+ the Document as given on its Title Page, then add an item
+ describing the Modified Version as stated in the previous
+ sentence.
+ J. Preserve the network location, if any, given in the Document for
+ public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in the
+ "History" section. You may omit a network location for a work
+ that was published at least four years before the Document
+ itself, or if the original publisher of the version it refers
+ to gives permission.
+ K. In any section entitled "Acknowledgements" or "Dedications",
+ preserve the section's title, and preserve in the section all the
+ substance and tone of each of the contributor acknowledgements
+ and/or dedications given therein.
+ L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section titles.
+ M. Delete any section entitled "Endorsements." Such a section
+ may not be included in the Modified Version.
+ N. Do not retitle any existing section as "Endorsements" or to
+ conflict in title with any Invariant Section.
+
+ 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.
+
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination
+ all of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections entitled
+ "History" in the various original documents, forming one section
+ entitled "History"; likewise combine any sections entitled
+ "Acknowledgements", and any sections entitled "Dedications." You
+ must delete all sections entitled "Endorsements."
+
+
+ 6. 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.
+
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of
+ a storage or distribution medium, does not as a whole count as a
+ Modified Version of the Document, provided no compilation
+ copyright is claimed for the compilation. Such a compilation is
+ called an "aggregate", and this License does not apply to the
+ other self-contained works thus compiled with the Document, on
+ account of their being thus compiled, if they are not themselves
+ derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one
+ quarter of the entire aggregate, the Document's Cover Texts may be
+ placed on covers that surround only the Document within the
+ aggregate. Otherwise they must appear on covers around the whole
+ aggregate.
+
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License provided that you also include the
+ original English version of this License. In case of a
+ disagreement between the translation and the original English
+ version of this License, the original English version will prevail.
+
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided for under this License. Any other
+ attempt to copy, modify, sublicense or distribute the Document is
+ void, and will automatically terminate your rights under this
+ License. However, parties who have received copies, or rights,
+ from you under this License will not have their licenses
+ terminated so long as such parties remain in full compliance.
+
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ http://www.gnu.org/copyleft/.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License "or any later version" applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If
+ the Document does not specify a version number of this License,
+ you may choose any version ever published (not as a draft) by the
+ Free Software Foundation.
+
+
+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:
+
+ Copyright (C) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+ A copy of the license is included in the section entitled "GNU
+ Free Documentation License."
+
+ If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant. If you have no Front-Cover
+Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
+LIST"; likewise for Back-Cover Texts.
+
+ If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License, to
+permit their use in free software.
+
+
+File: standards.info, Node: Index, Prev: Copying This Manual, Up: Top
+
+Index
+*****
+
+* Menu:
+
+* #endif, commenting: Comments.
+* --help option: Command-Line Interfaces.
+* --version option: Command-Line Interfaces.
+* -Wall compiler option: Syntactic Conventions.
+* accepting contributions: Contributions.
+* address for bug reports: Command-Line Interfaces.
+* ANSI C standard: Standard C.
+* arbitrary limits on data: Semantics.
+* autoconf: System Portability.
+* avoiding proprietary code: Reading Non-Free Code.
+* behavior, dependent on program's name: User Interfaces.
+* binary packages: Install Command Categories.
+* bindir: Directory Variables.
+* braces, in C source: Formatting.
+* bug reports: Command-Line Interfaces.
+* canonical name of a program: Command-Line Interfaces.
+* casting pointers to integers: CPU Portability.
+* change logs: Change Logs.
+* change logs, conditional changes: Conditional Changes.
+* change logs, style: Style of Change Logs.
+* command-line arguments, decoding: Semantics.
+* command-line interface: Command-Line Interfaces.
+* commenting: Comments.
+* compatibility with C and POSIX standards: Compatibility.
+* compiler warnings: Syntactic Conventions.
+* conditional changes, and change logs: Conditional Changes.
+* conditionals, comments for: Comments.
+* configure: Configuration.
+* control-L: Formatting.
+* conventions for makefiles: Makefile Conventions.
+* corba: Graphical Interfaces.
+* credits for manuals: Manual Credits.
+* data types, and portability: CPU Portability.
+* declaration for system functions: System Functions.
+* documentation: Documentation.
+* doschk: Names.
+* downloading this manual: Preface.
+* error messages: Semantics.
+* error messages, formatting: Errors.
+* exec_prefix: Directory Variables.
+* expressions, splitting: Formatting.
+* file usage: File Usage.
+* file-name limitations: Names.
+* formatting error messages: Errors.
+* formatting source code: Formatting.
+* formfeed: Formatting.
+* function argument, declaring: Syntactic Conventions.
+* function prototypes: Standard C.
+* getopt: Command-Line Interfaces.
+* gettext: Internationalization.
+* gnome: Graphical Interfaces.
+* graphical user interface: Graphical Interfaces.
+* gtk: Graphical Interfaces.
+* GUILE: Source Language.
+* implicit int: Syntactic Conventions.
+* impossible conditions: Semantics.
+* internationalization: Internationalization.
+* legal aspects: Legal Issues.
+* legal papers: Contributions.
+* libexecdir: Directory Variables.
+* libraries: Libraries.
+* library functions, and portability: System Functions.
+* license for manuals: License for Manuals.
+* lint: Syntactic Conventions.
+* long option names: Option Table.
+* long-named options: Command-Line Interfaces.
+* makefile, conventions for: Makefile Conventions.
+* malloc return value: Semantics.
+* man pages: Man Pages.
+* manual structure: Manual Structure Details.
+* memory allocation failure: Semantics.
+* memory usage: Memory Usage.
+* message text, and internationalization: Internationalization.
+* mmap: Mmap.
+* multiple variables in a line: Syntactic Conventions.
+* names of variables, functions, and files: Names.
+* NEWS file: NEWS File.
+* non-POSIX systems, and portability: System Portability.
+* non-standard extensions: Using Extensions.
+* NUL characters: Semantics.
+* open brace: Formatting.
+* optional features, configure-time: Configuration.
+* options for compatibility: Compatibility.
+* output device and program's behavior: User Interfaces.
+* packaging: Releases.
+* portability, and data types: CPU Portability.
+* portability, and library functions: System Functions.
+* portability, between system types: System Portability.
+* POSIX compatibility: Compatibility.
+* POSIXLY_CORRECT, environment variable: Compatibility.
+* post-installation commands: Install Command Categories.
+* pre-installation commands: Install Command Categories.
+* prefix: Directory Variables.
+* program configuration: Configuration.
+* program design: Design Advice.
+* program name and its behavior: User Interfaces.
+* program's canonical name: Command-Line Interfaces.
+* programming languges: Source Language.
+* proprietary programs: Reading Non-Free Code.
+* README file: Releases.
+* references to non-free material: References.
+* releasing: Managing Releases.
+* sbindir: Directory Variables.
+* signal handling: Semantics.
+* spaces before open-paren: Formatting.
+* standard command-line options: Command-Line Interfaces.
+* standards for makefiles: Makefile Conventions.
+* string library functions: System Functions.
+* syntactic conventions: Syntactic Conventions.
+* table of long options: Option Table.
+* temporary files: Semantics.
+* temporary variables: Syntactic Conventions.
+* texinfo.tex, in a distribution: Releases.
+* TMPDIR environment variable: Semantics.
+* trademarks: Trademarks.
+* where to obtain standards.texi: Preface.
+
+
+
+Tag Table:
+Node: Top689
+Node: Preface1392
+Node: Legal Issues3611
+Node: Reading Non-Free Code4074
+Node: Contributions5797
+Node: Trademarks7946
+Node: Design Advice9004
+Node: Source Language9587
+Node: Compatibility11594
+Node: Using Extensions13217
+Node: Standard C14788
+Node: Conditional Compilation17186
+Node: Program Behavior18480
+Node: Semantics19398
+Node: Libraries24086
+Node: Errors25326
+Node: User Interfaces27102
+Node: Graphical Interfaces28702
+Node: Command-Line Interfaces29732
+Node: Option Table35798
+Node: Memory Usage50802
+Node: File Usage51822
+Node: Writing C52565
+Node: Formatting53414
+Node: Comments57472
+Node: Syntactic Conventions60770
+Node: Names64177
+Node: System Portability66381
+Node: CPU Portability68761
+Node: System Functions72012
+Node: Internationalization77214
+Node: Mmap80362
+Node: Documentation81067
+Node: GNU Manuals82171
+Node: Doc Strings and Manuals87223
+Node: Manual Structure Details88771
+Node: License for Manuals90184
+Node: Manual Credits91153
+Node: Printed Manuals91541
+Node: NEWS File92222
+Node: Change Logs92894
+Node: Change Log Concepts93643
+Node: Style of Change Logs95498
+Node: Simple Changes97544
+Node: Conditional Changes98779
+Node: Indicating the Part Changed100192
+Node: Man Pages100710
+Node: Reading other Manuals102329
+Node: Managing Releases103113
+Node: Configuration103875
+Node: Makefile Conventions110775
+Node: Makefile Basics111576
+Node: Utilities in Makefiles114741
+Node: Command Variables116877
+Node: Directory Variables120445
+Node: Standard Targets131330
+Ref: Standard Targets-Footnote-1142581
+Node: Install Command Categories142681
+Node: Releases147254
+Node: References151337
+Node: Copying This Manual153621
+Node: GNU Free Documentation License153835
+Node: Index173531
+
+End Tag Table
Index: configdev.ein
===================================================================
--- configdev.ein (nonexistent)
+++ configdev.ein (revision 1765)
@@ -0,0 +1,185 @@
+%!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
Index: configbuild.tin
===================================================================
--- configbuild.tin (nonexistent)
+++ configbuild.tin (revision 1765)
@@ -0,0 +1,9 @@
+ config.in *configure* Makefile.in
+ | | |
+ | v |
+ | config.status |
+ | | |
+ *config.status*<======+==========>*config.status*
+ | |
+ v v
+ config.h Makefile