Initial import of GNU binutils version 2.8.1. Believe it or not,

this is heavily stripped down.

8 files changed, 7570 insertions, 0 deletions

diff --git a/contrib/binutils/etc/Makefile.in b/contrib/binutils/etc/Makefile.in
new file mode 100644
index 0000000..1a7eb4c
--- /dev/null
+++ b/contrib/binutils/etc/Makefile.in
@@ -0,0 +1,102 @@
+# 
+# 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 = makeinfo
+TEXI2DVI = texi2dvi
+
+# Where to find texinfo.tex to format documentation with TeX.
+TEXIDIR = $(srcdir)/../texinfo
+
+#### Host, target, and site specific Makefile fragments come in here.
+###
+
+INFOFILES = configure.info standards.info cfg-paper.info
+DVIFILES = configure.dvi standards.dvi cfg-paper.dvi
+
+all:
+
+install:  $(srcdir)/configure.man
+	$(INSTALL_DATA) $(srcdir)/configure.man $(man1dir)/configure.1
+
+uninstall:
+	cd $(infodir) && rm -f configure.info* standards.info* cfg-paper.info*
+
+info: $(INFOFILES)
+
+install-info: info
+	if test ! -f configure.info ; then cd $(srcdir); fi; \
+	for i in configure.info* standards.info* cfg-paper.info*; do \
+	  $(INSTALL_DATA) $$i $(infodir)/$$i; \
+	done
+
+dvi: $(DVIFILES)
+
+configure.info: $(srcdir)/configure.texi
+	$(MAKEINFO) -o configure.info $(srcdir)/configure.texi
+
+configure.dvi: $(srcdir)/configure.texi
+	TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/configure.texi
+
+standards.info: $(srcdir)/standards.texi
+	$(MAKEINFO) -I$(srcdir) -o standards.info $(srcdir)/standards.texi
+
+standards.dvi: $(srcdir)/standards.texi
+	TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/standards.texi
+
+cfg-paper.info : $(srcdir)/cfg-paper.texi
+	$(MAKEINFO) -o cfg-paper.info $(srcdir)/cfg-paper.texi
+
+cfg-paper.dvi: $(srcdir)/cfg-paper.texi
+	TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/cfg-paper.texi
+
+
+clean:
+	rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
+	rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs
+
+mostlyclean: clean
+
+distclean:   clean
+	rm -f Makefile config.status config.cache
+
+maintainer-clean realclean:   distclean
+	rm -f *.info*
+
+Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag)
+	$(SHELL) ./config.status
+
+## these last targets are for standards.texi conformance
+dist:
+check:
+installcheck:
+TAGS:
diff --git a/contrib/binutils/etc/cfg-paper.texi b/contrib/binutils/etc/cfg-paper.texi
new file mode 100644
index 0000000..bcfbb31
--- /dev/null
+++ b/contrib/binutils/etc/cfg-paper.texi
@@ -0,0 +1,717 @@
+\input texinfo
+@c %**start of header
+@setfilename cfg-paper.info
+@settitle On Configuring Development Tools
+@c %**end of header
+@setchapternewpage off
+
+@ifinfo
+This document attempts to describe the general concepts behind
+configuration of the @sc{gnu} Development Tools.
+It also discusses common usage.
+
+Copyright (C) 1991, 1992, 1994 Cygnus Support
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by Cygnus Support.
+@end ifinfo
+
+@titlepage
+@sp 10
+@title{On Configuring Development Tools}
+@author{K. Richard Pixley, @code{rich@@cygnus.com}}
+@author{Cygnus Support}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991, 1992, 1994 Cygnus Support
+
+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 Cygnus Support.
+@end titlepage
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* configuration: (cfg-paper).	Some theory on configuring source.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@node top, Some Basic Terms, (dir), (dir)
+
+@ifinfo
+This document attempts to describe the general concepts behind
+configuration of the @sc{gnu} Development Tools.
+It also discusses common usage.
+@end ifinfo
+
+@menu
+* Some Basic Terms::		Some Basic Terms
+* Specifics.::			Specifics
+* Building Development Environments::  Building Development Environments
+* A Walk Through::		A Walk Through
+* Final Notes::			Final Notes
+* Index::			Index
+
+ --- The Detailed Node Listing ---
+
+Some Basic Terms
+
+* Host Environments::		Host Environments
+* Configuration Time Options::	Configuration Time Options
+
+A Walk Through
+
+* Native Development Environments::  Native Development Environments
+* Emulation Environments::	Emulation Environments
+* Simple Cross Environments::	Simple Cross Environments
+* Crossing Into Targets::	Crossing Into Targets
+* Canadian Cross::		Canadian Cross
+
+Final Notes
+
+* Hacking Configurations::	Hacking Configurations
+@end menu
+
+@node Some Basic Terms, Specifics., top, top
+@chapter Some Basic Terms
+
+There are a lot of terms that are frequently used when discussing
+development tools.  Most of the common terms have been used for many
+different concepts such that their meanings have become ambiguous to the
+point of being confusing.  Typically, we only guess at their meanings
+from context and we frequently guess wrong.
+
+This document uses very few terms by comparison.  The intent is to make
+the concepts as clear as possible in order to convey the usage and
+intent of these tools.
+
+@emph{Programs} run on @emph{machines}.  Programs are very nearly always
+written in @emph{source}.  Programs are @emph{built} from source.
+@emph{Compilation} is a process that is frequently, but not always, used
+when building programs.
+@cindex Programs
+@cindex Machines
+@cindex Source
+@cindex Building
+@cindex Compilation
+
+@menu
+* Host Environments::		Host Environments
+* Configuration Time Options::	Configuration Time Options
+@end menu
+
+@node Host Environments, Configuration Time Options, Some Basic Terms, Some Basic Terms
+@section Host Environments
+
+@cindex host
+In this document, the word @emph{host} refers to the environment in
+which the source in question will be compiled.  @emph{host} and
+@emph{host name} have nothing to do with the proper name of your host,
+like @emph{ucbvax}, @emph{prep.ai.mit.edu} or @emph{att.com}.  Instead
+they refer to things like @emph{sun4} and @emph{dec3100}.
+
+Forget for a moment that this particular directory of source is the
+source for a development environment.  Instead, pretend that it is the
+source for a simpler, more mundane, application, say, a desk calculator.
+
+Source that can be compiled in more than one environment, generally
+needs to be set up for each environment explicitly.  Here we refer to
+that process as configuration.  That is, we configure the source for a
+host.
+
+For example, if we wanted to configure our mythical desk calculator to
+compile on a SparcStation, we might configure for host sun4.  With our
+configuration system:
+
+@example
+cd desk-calculator ; ./configure sun4
+@end example
+
+@noindent
+does the trick.  @code{configure} is a shell script that sets up Makefiles,
+subdirectories, and symbolic links appropriate for compiling the source
+on a sun4.
+
+The @emph{host} environment does not necessarily refer to the machine on
+which the tools are built.  It is possible to provide a sun3 development
+environment on a sun4.  If we wanted to use a cross compiler on the sun4
+to build a program intended to be run on a sun3, we would configure the
+source for sun3.
+
+@example
+cd desk-calculator ; ./configure sun3
+@end example
+
+@noindent
+The fact that we are actually building the program on a sun4 makes no
+difference if the sun3 cross compiler presents an environment that looks
+like a sun3 from the point of view of the desk calculator source code.
+Specifically, the environment is a sun3 environment if the header files,
+predefined symbols, and libraries appear as they do on a sun3.
+
+Nor does the host environment refer to the the machine on which the
+program to be built will run.  It is possible to provide a sun3
+emulation environment on a sun4 such that programs built in a sun3
+development environment actually run on the sun4.  This technique is
+often used within individual programs to remedy deficiencies in the host
+operating system.  For example, some operating systems do not provide
+the @code{bcopy} function and so it is emulated using the
+@code{memcpy} funtion.
+
+Host environment simply refers to the environment in which the program
+will be built from the source.
+
+
+@node  Configuration Time Options,  , Host Environments, Some Basic Terms
+@section Configuration Time Options
+
+Many programs have compile time options.  That is, features of the
+program that are either compiled into the program or not based on a
+choice made by the person who builds the program.  We refer to these as
+@emph{configuration options}.  For example, our desk calculator might be
+capable of being compiled into a program that either uses infix notation
+or postfix as a configuration option.  For a sun3, to choose infix you
+might use:
+
+@example
+./configure sun3 --enable-notation=infix
+@end example
+
+@noindent
+while for a sun4 with postfix you might use:
+
+@example
+./configure sun4 --enable-notation=postfix
+@end example
+
+If we wanted to build both at the same time, the intermediate pieces
+used in the build process must be kept separate.
+
+@example
+mkdir ../objdir.sun4
+(cd ../objdir.sun4 ; ../configure sun4 --enable-notation=postfix --srcdir=../src)
+mkdir ../objdir.sun3
+(cd ../objdir.sun3 ; ../configure sun3 --enable-notation=infix --srcdir=../src)
+@end example
+
+@noindent
+will create subdirectories for the intermediate pieces of the sun4 and
+sun3 configurations.  This is necessary as previous systems were only
+capable of one configuration at a time.  Otherwise, a second
+configuration would write over the first.  We've chosen to retain this
+behaviour so the obj directories and the @code{--srcdir} configuration
+option are necessary to get the new behaviour.  The order of the
+arguments doesn't matter.  There should be exactly one argument without
+a leading @samp{-} and that argument will be assumed to be the host
+name.
+
+From here on the examples will assume that you want to build the tools
+@emph{in place} and won't show the @code{--srcdir} option, but remember
+that it is available.
+
+In order to actually install the program, the configuration system needs
+to know where you would like the program installed.  The default
+location is @file{/usr/local}.  We refer to this location as
+@code{$(prefix)}.  All user visible programs will be installed in
+@file{@code{$(prefix)}/bin}.  All other programs and files will be
+installed in a subdirectory of @file{@code{$(prefix)}/lib}.
+
+You can only change @code{$(prefix)} as a configuration time
+option.
+
+@example
+./configure sun4 --enable-notation=postfix --prefix=/local
+@end example
+
+@noindent
+Will configure the source such that:
+
+@example
+make install
+@end example
+
+@noindent
+will put its programs in @file{/local/bin} and @file{/local/lib/gcc}.
+If you change @code{$(prefix)} after building the source, you will need
+to:
+
+@example
+make clean
+@end example
+
+@noindent
+before the change will be propogated properly.  This is because some
+tools need to know the locations of other tools.
+
+With these concepts in mind, we can drop the desk calculator example and
+move on to the application that resides in these directories, namely,
+the source to a development environment.
+
+@node Specifics., Building Development Environments, Some Basic Terms, top
+@chapter Specifics
+
+The @sc{gnu} Development Tools can be built on a wide variety of hosts.  So,
+of course, they must be configured.  Like the last example,
+
+@example
+./configure sun4 --prefix=/local
+./configure sun3 --prefix=/local
+@end example
+
+@noindent
+will configure the source to be built in subdirectories, in order to
+keep the intermediate pieces separate, and to be installed in
+@file{/local}.
+
+When built with suitable development environments, these will be native
+tools.  We'll explain the term @emph{native} later.
+
+@node Building Development Environments, A Walk Through, Specifics., top
+@chapter Building Development Environments
+
+@cindex Target
+
+The @sc{gnu} development tools can not only be built in a
+number of host development environments, they can also be configured to
+create a number of different development environments on each of those
+hosts.  We refer to a specific development environment created as a
+@emph{target}.  That is, the word @emph{target} refers to the development
+environment produced by compiling this source and installing the
+resulting programs.
+
+For the @sc{gnu} development tools, the default target is the
+same as the host.  That is, the development environment produced is
+intended to be compatible with the environment used to build the tools.
+
+In the example above, we created two configurations, one for sun4 and
+one for sun3.  The first configuration is expecting to be built in a
+sun4 development environment, to create a sun4 development environment.
+It doesn't necessarily need to be built on a sun4 if a sun4 development
+environment is available elsewhere.  Likewise, if the available sun4
+development environment produces executables intended for something
+other than sun4, then the development environment built from this sun4
+configuration will run on something other than a sun4.  From the point
+of view of the configuration system and the @sc{gnu} development tools
+source, this doesn't matter.  What matters is that they will be built in
+a sun4 environment.
+
+Similarly, the second configuration given above is expecting to be built
+in a sun3 development environment, to create a sun3 development
+environment.
+
+The development environment produced is a configuration time option,
+just like @code{$(prefix)}.
+
+@example
+./configure sun4 --prefix=/local --target=sun3
+./configure sun3 --prefix=/local --target=sun4
+@end example
+
+In this example, like before, we create two configurations.  The first
+is intended to be built in a sun4 environment, in subdirectories, to be
+installed in @file{/local}.  The second is intended to be built in a
+sun3 environment, in subdirectories, to be installed in @file{/local}.
+
+Unlike the previous example, the first configuration will produce a sun3
+development environment, perhaps even suitable for building the second
+configuration.  Likewise, the second configuration will produce a sun4
+development environment, perhaps even suitable for building the first
+configuration.
+
+The development environment used to build these configurations will
+determine the machines on which the resulting development environments
+can be used.
+
+
+@node A Walk Through, Final Notes, Building Development Environments, top
+@chapter A Walk Through
+
+
+@menu
+* Native Development Environments::  Native Development Environments
+* Emulation Environments::	Emulation Environments
+* Simple Cross Environments::	Simple Cross Environments
+* Crossing Into Targets::	Crossing Into Targets
+* Canadian Cross::		Canadian Cross
+@end menu
+
+@node Native Development Environments, Emulation Environments, A Walk Through, A Walk Through
+@section Native Development Environments
+
+Let us assume for a moment that you have a sun4 and that with your sun4
+you received a development environment.  This development environment is
+intended to be run on your sun4 to build programs that can be run on
+your sun4.  You could, for instance, run this development environment on
+your sun4 to build our example desk calculator program.  You could then
+run the desk calculator program on your sun4.
+
+@cindex Native
+@cindex Foreign
+The resulting desk calculator program is referred to as a @emph{native}
+program.  The development environment itself is composed of native
+programs that, when run, build other native programs.  Any other program
+is referred to as @emph{foreign}.  Programs intended for other machines are
+foreign programs.
+
+This type of development environment, which is by far the most common,
+is refered to as @emph{native}.  That is, a native development environment
+runs on some machine to build programs for that same machine.  The
+process of using a native development environment to build native
+programs is called a @emph{native} build.
+
+@example
+./configure sun4
+@end example
+
+@noindent
+will configure this source such that when built in a sun4 development
+environment, with a development environment that builds programs
+intended to be run on sun4 machines, the programs built will be native
+programs and the resulting development environment will be a native
+development environment.
+
+The development system that came with your sun4 is one such environment.
+Using it to build the @sc{gnu} Development Tools is a very common activity
+and the resulting development environment is quite popular.
+
+@example
+make all
+@end example
+
+@noindent
+will build the tools as configured and will assume that you want to use
+the native development environment that came with your machine.
+
+@cindex Bootstrapping
+@cindex Stage1
+Using a development environment to build a development environment is
+called @emph{bootstrapping}.  The release of the @sc{gnu}
+Development Tools is capable of bootstrapping itself.  This is a very
+powerful feature that we'll return to later.  For now, let's pretend
+that you used the native development environment that came with your
+sun4 to bootstrap the release and let's call the new
+development environment @emph{stage1}.
+
+Why bother?  Well, most people find that the @sc{gnu} development
+environment builds programs that run faster and take up less space than
+the native development environments that came with their machines.  Some
+people didn't get development environments with their machines and some
+people just like using the @sc{gnu} tools better than using other tools.
+
+@cindex Stage2
+While you're at it, if the @sc{gnu} tools produce better programs, maybe you
+should use them to build the @sc{gnu} tools.  So let's
+pretend that you do.  Let's call the new development environment
+@emph{stage2}.
+
+@cindex Stage3
+So far you've built a development environment, stage1, and you've used
+stage1 to build a new, faster and smaller development environment,
+stage2, but you haven't run any of the programs that the @sc{gnu} tools have
+built.  You really don't yet know if these tools work.  Do you have any
+programs built with the @sc{gnu} tools?  Yes, you do.  stage2.  What does
+that program do?  It builds programs.  Ok, do you have any source handy
+to build into a program?  Yes, you do.  The @sc{gnu} tools themselves.  In
+fact, if you use stage2 to build the @sc{gnu} tools again the resulting
+programs should be identical to stage2.  Let's pretend that you do and
+call the new development environment @emph{stage3}.
+
+@cindex Three stage boot
+You've just completed what's called a @emph{three stage boot}.  You now have
+a small, fast, somewhat tested, development environment.
+
+@example
+make bootstrap
+@end example
+
+@noindent
+will do a three stage boot across all tools and will compare stage2 to
+stage3 and complain if they are not identical.
+
+Once built,
+
+@example
+make install
+@end example
+
+@noindent
+will install the development environment in the default location, or in
+@code{$(prefix)} if you specified an alternate when you configured.
+
+@cindex Cross
+Any development environment that is not a native development environment
+is refered to as a @emph{cross} development environment.  There are many
+different types of cross development environments but most fall into one
+of three basic categories.
+
+
+@node Emulation Environments, Simple Cross Environments, Native Development Environments, A Walk Through
+@section Emulation Environments
+
+@cindex Emulation
+The first category of cross development environment is called
+@emph{emulation}.  There are two primary types of emulation, but both
+types result in programs that run on the native host.
+
+@cindex Software emulation
+@cindex Software emulator
+The first type is @emph{software emulation}.  This form of cross
+development environment involves a native program that when run on the
+native host, is capable of interpreting, and in most aspects running, a
+program intended for some other machine.  This technique is typically
+used when the other machine is either too expensive, too slow, too fast,
+or not available, perhaps because it hasn't yet been built.  The native,
+interpreting program is called a @emph{software emulator}.
+
+The @sc{gnu} Development Tools do not currently include any software
+emulators.  Some do exist and the @sc{gnu} Development Tools can be
+configured to create simple cross development environments for with
+these emulators.  More on this later.
+
+The second type of emulation is when source intended for some other
+development environment is built into a program intended for the native
+host.  The concepts of operating system universes and hosted operating
+systems are two such development environments.
+
+@node Simple Cross Environments, Crossing Into Targets, Emulation Environments, A Walk Through
+@section Simple Cross Environments
+
+@example
+./configure sun4 --target=a29k
+@end example
+
+@noindent
+will configure the tools such that when compiled in a sun4 development
+environment the resulting development environment can be used to create
+programs intended for an a29k.  Again, this does not necessarily mean
+that the new development environment can be run on a sun4.  That would
+depend on the development environment used to build these tools.
+
+Earlier you saw how to configure the tools to build a native development
+environment, that is, a development environment that runs on your sun4
+and builds programs for your sun4.  Let's pretend that you use stage3 to
+build this simple cross configuration and let's call the new development
+environment gcc-a29k.  Remember that this is a native build.  Gcc-a29k
+is a collection of native programs intended to run on your sun4.  That's
+what stage3 builds, programs for your sun4.  Gcc-a29k represents an a29k
+development environment that builds programs intended to run on an a29k.
+But, remember, gcc-a29k runs on your sun4.  Programs built with gcc-a29k
+will run on your sun4 only with the help of an appropriate software
+emulator.
+
+@cindex Simple cross
+@cindex Crossing to
+Building gcc-a29k is also a bootstrap but of a slightly different sort.
+We call gcc-a29k a @emph{simple cross} environment and using gcc-a29k to
+build a program intended for a29k is called @emph{crossing to} a29k.
+Simple cross environments are the second category of cross development
+environments.
+
+
+@node Crossing Into Targets, Canadian Cross, Simple Cross Environments, A Walk Through
+@section Crossing Into Targets
+
+@example
+./configure a29k --target=a29k
+@end example
+
+@noindent
+will configure the tools such that when compiled in an a29k development
+environment, the resulting development environment can be used to create
+programs intended for an a29k.  Again, this does not necessarily mean
+that the new development environment can be run on an a29k.  That would
+depend on the development environment used to build these tools.
+
+If you've been following along this walk through, then you've already
+built an a29k environment, namely gcc-a29k.  Let's pretend you use
+gcc-a29k to build the current configuration.
+
+Gcc-a29k builds programs intended for the a29k so the new development
+environment will be intended for use on an a29k.  That is, this new gcc
+consists of programs that are foreign to your sun4.  They cannot be run
+on your sun4.
+
+@cindex Crossing into
+The process of building this configuration is a another bootstrap.  This
+bootstrap is also a cross to a29k.  Because this type of build is both a
+bootstrap and a cross to a29k, it is sometimes referred to as a
+@emph{cross into} a29k.  This new development environment isn't really a
+cross development environment at all.  It is intended to run on an a29k
+to produce programs for an a29k.  You'll remember that this makes it, by
+definition, an a29k native compiler.  @emph{Crossing into} has been
+introduced here not because it is a type of cross development
+environment, but because it is frequently mistaken as one.  The process
+is @emph{a cross} but the resulting development environment is a native
+development environment.
+
+You could not have built this configuration with stage3, because stage3
+doesn't provide an a29k environment.  Instead it provides a sun4
+environment.
+
+If you happen to have an a29k lying around, you could now use this fresh
+development environment on the a29k to three-stage these tools all over
+again.  This process would look just like it did when we built the
+native sun4 development environment because we would be building another
+native development environment, this one on a29k.
+
+
+@node Canadian Cross,  , Crossing Into Targets, A Walk Through
+@section Canadian Cross
+
+So far you've seen that our development environment source must be
+configured for a specific host and for a specific target.  You've also
+seen that the resulting development environment depends on the
+development environment used in the build process.
+
+When all four match identically, that is, the configured host, the
+configured target, the environment presented by the development
+environment used in the build, and the machine on which the resulting
+development environment is intended to run, then the new development
+environment will be a native development environment.
+
+When all four match except the configured host, then we can assume that
+the development environment used in the build is some form of library
+emulation.
+
+When all four match except for the configured target, then the resulting
+development environment will be a simple cross development environment.
+
+When all four match except for the host on which the development
+environment used in the build runs, the build process is a @emph{cross into}
+and the resulting development environment will be native to some other
+machine.
+
+Most of the other permutations do exist in some form, but only one more
+is interesting to the current discussion.
+
+@example
+./configure a29k --target=sun3
+@end example
+
+@noindent
+will configure the tools such that when compiled in an a29k development
+environment, the resulting development environment can be used to create
+programs intended for a sun3.  Again, this does not necessarily mean
+that the new development environment can be run on an a29k.  That would
+depend on the development environment used to build these tools.
+
+If you are still following along, then you have two a29k development
+environments, the native development environment that runs on a29k, and
+the simple cross that runs on your sun4.  If you use the a29k native
+development environment on the a29k, you will be doing the same thing we
+did a while back, namely building a simple cross from a29k to sun3.
+Let's pretend that instead, you use gcc-a29k, the simple cross
+development environment that runs on sun4 but produces programs for
+a29k.
+
+The resulting development environment will run on a29k because that's
+what gcc-a29k builds, a29k programs.  This development environment will
+produce programs for a sun3 because that is how it was configured.  This
+means that the resulting development environment is a simple cross.
+
+@cindex Canadian Cross
+@cindex Three party cross
+There really isn't a common name for this process because very few
+development environments are capable of being configured this
+extensively.  For the sake of discussion, let's call this process a
+@emph{Canadian cross}.  It's a three party cross, Canada has a three
+party system, hence Canadian Cross.
+
+@node Final Notes, Index, A Walk Through, top
+@chapter Final Notes
+
+By @emph{configures}, I mean that links, Makefile, .gdbinit, and
+config.status are built.  Configuration is always done from the source
+directory.
+
+@table @code
+
+@item ./configure @var{name}
+configures this directory, perhaps recursively, for a single host+target
+pair where the host and target are both @var{name}.  If a previous
+configuration existed, it will be overwritten.
+
+@item ./configure @var{hostname} --target=@var{targetname}
+configures this directory, perhaps recursively, for a single host+target
+pair where the host is @var{hostname} and target is @var{targetname}.
+If a previous configuration existed, it will be overwritten.
+
+@end table
+
+@menu
+* Hacking Configurations::	Hacking Configurations
+@end menu
+
+@node Hacking Configurations,  , Final Notes, Final Notes
+@section Hacking Configurations
+
+The configure scripts essentially do three things, create subdirectories
+if appropriate, build a @file{Makefile}, and create links to files, all
+based on and tailored to, a specific host+target pair.  The scripts also
+create a @file{.gdbinit} if appropriate but this is not tailored.
+
+The Makefile is created by prepending some variable definitions to a
+Makefile template called @file{Makefile.in} and then inserting host and
+target specific Makefile fragments.  The variables are set based on the
+chosen host+target pair and build style, that is, if you use
+@code{--srcdir} or not.  The host and target specific Makefile may or may
+not exist.
+
+@itemize @bullet
+
+@item
+Makefiles can be edited directly, but those changes will eventually be
+lost.  Changes intended to be permanent for a specific host should be
+made to the host specific Makefile fragment.  This should be in
+@file{./config/mh-@var{host}} if it exists.  Changes intended to be
+permanent for a specific target should be made to the target specific
+Makefile fragment.  This should be in @file{./config/mt-@var{target}} if
+it exists.  Changes intended to be permanent for the directory should be
+made in @file{Makefile.in}.  To propogate changes to any of these,
+either use @code{make Makefile} or @code{./config.status} or
+re-configure.
+
+@end itemize
+
+@page
+@node Index,  , Final Notes, top
+@appendix Index
+
+@printindex cp
+
+@contents
+@bye
+
+@c Local Variables:
+@c fill-column: 72
+@c End:
diff --git a/contrib/binutils/etc/configure b/contrib/binutils/etc/configure
new file mode 100755
index 0000000..74c33ae
--- /dev/null
+++ b/contrib/binutils/etc/configure
@@ -0,0 +1,794 @@
+#! /bin/sh
+
+# Guess values for system-dependent variables and create Makefiles.
+# Generated automatically using autoconf version 2.10 
+# 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=
+
+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.10"
+    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 LANG and LC_ALL to C if already set.
+# These must not be set unconditionally because not all systems understand
+# e.g. LANG=C (notably SCO).
+if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi
+if test "${LANG+set}"   = set; then LANG=C;   export LANG;   fi
+
+# 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=configure.texi
+
+# 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'
+
+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
+# 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
+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.
+      for ac_prog in ginstall installbsd 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.
+	    # OSF/1 installbsd also uses dspmsg, but is usable.
+	    :
+	  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
+# 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 |
+  sed -n "s/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=\${\1='\2'}/p" \
+  >> 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.10"
+    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%@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
+
+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]", 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 relative srcdir, etc. 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
+  sed -e "$ac_comsub
+s%@configure_input@%$configure_input%g
+s%@srcdir@%$srcdir%g
+s%@top_srcdir@%$top_srcdir%g
+s%@INSTALL@%$INSTALL%g
+" -f conftest.subs $ac_given_srcdir/$ac_file_in > $ac_file
+fi; done
+rm -f conftest.subs
+
+
+
+exit 0
+EOF
+chmod +x $CONFIG_STATUS
+rm -fr confdefs* $ac_clean_files
+test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1
+
diff --git a/contrib/binutils/etc/configure.in b/contrib/binutils/etc/configure.in
new file mode 100644
index 0000000..a29f993
--- /dev/null
+++ b/contrib/binutils/etc/configure.in
@@ -0,0 +1,7 @@
+dnl Process this file with autoconf to produce a configure script.
+AC_PREREQ(2.5)
+AC_INIT(configure.texi)
+
+AC_PROG_INSTALL
+
+AC_OUTPUT(Makefile)
diff --git a/contrib/binutils/etc/configure.man b/contrib/binutils/etc/configure.man
new file mode 100644
index 0000000..a769904
--- /dev/null
+++ b/contrib/binutils/etc/configure.man
@@ -0,0 +1,166 @@
+.\" -*- nroff -*-
+.\" Copyright (c) 1991, 1992, 1996 Cygnus Support
+.\" written by K. Richard Pixley
+.TH configure 1 "29 March 1996" "cygnus support" "Cygnus Support"
+.de BP
+.sp
+.ti \-.2i
+\(**
+..
+
+.SH NAME
+configure \- prepare source code to be built
+
+.SH SYNOPSIS
+configure HOST [--target=TARGET] [--srcdir=DIR] [--rm]
+            [--site=SITE] [--prefix=DIR] [--exec_prefix=DIR]
+            [--program_prefix=DIR] [--tmpdir=DIR]
+            [--with-PACKAGE[=YES/NO]] [--without-PACKAGE]
+            [--enable-FEATURE[=YES/NO]] [--disable-FEATURE]
+            [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help]
+
+.SH DESCRIPTION
+.I configure
+is a program used to prepare souce code to be built.  It does this by
+generating Makefiles and .gdbinit files, creating symlinks, recursing
+in subdirectories, and some other miscellaneous file editing.
+
+.SH OPTIONS
+.I configure
+accepts the following options:
+
+.TP
+.I \--target=TARGET
+Requests that the sources be configured to target the
+.I TARGET
+machine.  If no target is specified explicitly, the target is assumed
+to be the same as the host.
+
+.TP
+.I \--srcdir=DIR
+tells configure to find the source in 
+.I DIR.
+Object code is always built in the current directory,
+.I `.'.
+
+.TP
+.I \--rm
+asks configure to remove a configuration rather than create one.
+
+.TP
+.I \--site=SITE
+asks configure to use any site-specific Makefile fragments for
+.I SITE
+when building Makefiles.
+
+.TP
+.I \--prefix=DIR
+sets the location in which to install files to
+.I DIR.
+The default is "/usr/local".
+
+.TP
+.I \--exec_prefix=DIR
+sets the root directory for host-dependent files to
+.I DIR.
+The default location is the value of
+.I prefix.
+
+.TP
+.I \--program_prefix=DIR
+configures the source to install programs which have the same names as
+common Unix programs, such as "make", in
+.I DIR.
+Also applies to programs which might be used for cross-compilation.
+
+.TP
+.I \--tmpdir=DIR
+sets the directory in which configure creates temporary files to
+.I DIR.
+
+.TP
+.I \--with-PACKAGE[=YES/NO]
+sets a flag for the build to recognize that
+.I PACKAGE
+is explicitly present or not present.  If
+.I \=YES/NO
+is nonexistent, the default is
+.I YES.
+.I \--without-PACKAGE
+is equivalent to 
+.IR \--with-PACKAGE=no .
+
+.TP
+.I \--enable-FEATURE[=YES/NO]
+sets a flag for the build to recognize that
+.I FEATURE
+should be included or not included.  If
+.I \=YES/NO
+is nonexistent, the default is
+.I YES.
+.I \--disable-FEATURE
+is equivalent to
+.IR --enable-FEATURE=no .
+
+.TP
+.I \--norecursion
+asks that only the current directory be configured.  Normally
+.I configure
+recurs on subdirectories.
+
+.TP
+.I \-nfp
+Notifies
+.I configure
+that all of the specified hosts have
+.I no floating point
+units.
+
+.TP
+.I \-s
+used internally by configure to supress status messages on
+subdirectory recursions.  Override with
+.I \-v
+
+.TP
+.I \-v
+verbose output.  Asks that configure print status lines for each
+directory configured.  Normally, only the status lines for the current
+directory are printed.
+
+.TP
+.I \--version
+.I \-V
+prints
+.I configure
+version number.
+
+.TP
+.I \-help
+displays a brief usage summary.
+
+
+.SH FILES
+configure.in	for each directory's individual needs
+.br
+Makefile.in	Makefile template
+.br
+config.sub	for parsing configuration names
+.br
+config.guess	for guessing HOST when not specified
+.br
+config.status	non-recursively rebuilds current directory
+
+.SH FILES
+.ta \w'gmon.sum 'u
+a.out	the namelist and text space.
+.br
+gmon.out	dynamic call graph and profile.
+.br
+gmon.sum summarized dynamic call graph and profile.
+
+.SH "SEE ALSO"
+.RB "`\|" configure "\|'"
+entry in 
+.B
+info.
diff --git a/contrib/binutils/etc/configure.texi b/contrib/binutils/etc/configure.texi
new file mode 100644
index 0000000..4457774
--- /dev/null
+++ b/contrib/binutils/etc/configure.texi
@@ -0,0 +1,1830 @@
+\input texinfo    @c -*-texinfo-*-
+@setfilename configure.info
+@settitle Cygnus configure
+
+@synindex ky cp
+
+@setchapternewpage odd
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* configure: (configure).        Cygnus configure.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@ifinfo
+This document describes the Cygnus Support version of @code{configure}.
+
+Copyright (C) 1991, 1992, 1993 Cygnus Support
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by Cygnus Support.
+@end ifinfo
+
+@c We should not distribute texinfo files with smallbook enabled.
+@c @smallbook
+@finalout
+@titlepage
+@title Cygnus configure
+@author K. Richard Pixley
+@author Cygnus Support
+@page
+@cindex copyleft
+
+@vskip 0pt plus 1filll
+Edited January, 1993, by Jeffrey Osier, Cygnus Support.
+
+Copyright @copyright{} 1991, 1992, 1993 Cygnus Support
+
+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 Cygnus Support.
+@end titlepage
+
+@c ---------------------------------------------------------------------
+@ifinfo
+@node Top
+@top Cygnus configure
+
+This file documents the configuration system used and distributed by
+Cygnus Support.
+
+@menu
+* What configure does::    What configure does
+* Invoking configure::     Invoking configure---basic usage
+* Using configure::        More than you ever wanted to know
+* Porting::                How to use configure with new programs
+* Variables Index::
+* Concept Index::
+@end menu
+@end ifinfo
+
+@c ---------------------------------------------------------------------
+@node What configure does
+@chapter What @code{configure} does
+@cindex Introduction
+@cindex Overview
+@cindex What @code{configure} does
+@kindex Cygnus Support Developer's Kit
+
+This manual documents Cygnus @code{configure}, a program which helps to
+automate much of the setup activity associated with building large suites of
+programs, such the Cygnus Support Developer's Kit.  This manual is therefore
+geared toward readers who are likely to face the problem of configuring
+software in source form before compiling and installing it.  We assume you are
+an experienced programmer or system administrator.
+@ifinfo
+For further background on this topic, see @ref{Some Basic Terms, , Apologia
+Configure, cfg-paper, On Configuring Development Tools}, by K. Richard
+Pixley.
+@end ifinfo
+@iftex
+For further background on this topic, see @cite{On Configuring Development
+Tools} by K. Richard Pixley.
+@end iftex
+
+When @code{configure} runs, it does the following things:
+
+@table @emph
+@item @bullet{} creates build directories
+@vindex srcdir
+@cindex @code{srcdir}
+@cindex Build directories
+When you run @code{configure} with the @samp{--srcdir} option, it uses the
+current directory as the @dfn{build directory}, creating under it a directory
+tree that parallels the directory structure of the source directory.  If you
+don't specify a @samp{srcdir}, @code{configure} first assumes that the source
+code you wish to configure is in your current directory; if it finds no
+@file{configure.in} input file there, it searches in the directory
+@code{configure} itself lies in.  (For details, see @ref{Build directories, ,
+Build directories}.)
+
+@item @bullet{} generates @file{Makefile}
+@cindex @code{Makefile} generation
+A @file{Makefile} template from the source directory, usually called
+@file{Makefile.in}, is copied to an output file in the build directory which is
+most often named @file{Makefile}.  @code{configure} places definitions for a
+number of standard @file{Makefile} macros at the beginning of the output file.
+If @w{@samp{--prefix=@var{dir}}} or @w{@samp{--exec_prefix=@var{dir}}} are
+specified on the @code{configure} command line, corresponding @file{Makefile}
+variables are set accordingly.  If host, target, or site-specific
+@file{Makefile} fragments exist, these are inserted into the output file.  (For
+details, see @ref{Makefile generation, , @code{Makefile} generation}.)
+
+@item @bullet{} generates @file{.gdbinit}
+@cindex @code{.gdbinit}
+If the source directory contains a @file{.gdbinit} file and the build directory
+is not the same as the source directory, a @file{.gdbinit} file is created in
+the build directory.  This @file{.gdbinit} file contains commands which allow
+the source directory to be read when debugging with the @sc{gnu} debugger,
+@code{gdb}.  (@xref{Command Files, , Command Files, gdb, Debugging With GDB}.)
+
+@item @bullet{} makes symbolic links
+@cindex Symbolic links
+Most build directories require that some symbolic links with generic names are
+built pointing to specific files in the source directory.  If the system where
+@code{configure} runs cannot support symbolic links, hard links are used
+instead.  (For details, see @ref{configure.in, , The @code{configure.in} input
+file}.)
+
+@item @bullet{} generates @file{config.status}
+@cindex @code{config.status}
+@code{configure} creates a shell script named @file{config.status} in the build
+directory.  This shell script, when run from the build directory (usually from
+within a @file{Makefile}), will reconfigure the build directory (but not its
+subdirectories).  This is most often used to have a @file{Makefile} update
+itself automatically if a new source directory is available.
+
+@item @bullet{} calls itself recursively
+@cindex Recursion
+If the source directory has subdirectories that should also be configured,
+@code{configure} is called for each.  
+@end table
+
+@c ---------------------------------------------------------------------
+@node Invoking configure
+@chapter Invoking @code{configure}
+@cindex Invoking @code{configure}
+@cindex Usage
+
+Cygnus @code{configure} is a shell script which resides in a source tree.  The
+usual way to invoke @code{configure} is from the shell, as follows:
+
+@cindex Example session
+@example
+eg$ ./configure @var{hosttype}
+@end example
+
+@noindent
+This prepares the source in the current directory (@file{.}) to be
+compiled for a @var{hosttype} environment.  It assumes that you wish to
+build programs and files in the default @dfn{build directory} (also the
+current directory, @file{.}).  If you do not specify a value for
+@var{hosttype}, Cygnus @code{configure} will attempt to discover this
+information by itself (@pxref{config.guess, , Determining system
+information}).  For information on @var{hosttype} environments,
+@xref{Host, , Host}.
+
+All @sc{gnu} software is packaged with one or more @code{configure} script(s)
+(@pxref{Configuration, , How Configuration Should Work, standards, GNU Coding
+Standards}).  By using @code{configure} you prepare the source for your
+specific environment by selecting and using @file{Makefile} fragments and
+fragments of shell scripts, which are prepared in advance and stored with the
+source.
+
+@code{configure}'s command-line options also allow you to specify other aspects
+of the source configuration:
+
+@smallexample
+  configure @var{hosttype}  [--target=@var{target}] [--srcdir=@var{dir}] [--rm]
+            [--site=@var{site}] [--prefix=@var{dir}] [--exec-prefix=@var{dir}]
+            [--program-prefix=@var{string}] [--tmpdir=@var{dir}]
+            [--with-@var{package}[=@var{yes/no}]] [--without-@var{package}]
+            [--enable-@var{feature}[=@var{yes/no}]] [--disable-@var{feature}]
+            [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help]
+@end smallexample
+
+@table @code
+@item --target=@var{target}
+@cindex @code{--target}
+@cindex @code{target} option
+@vindex target
+Requests that the sources be configured to target the @var{target} machine.  If
+no target is specified explicitly, the target is assumed to be the same as the
+host (i.e., a @dfn{native} configuration).  @xref{Host, , Host}, and
+@ref{Target, , Target}, for
+discussions of each.
+
+@item --srcdir=@var{dir}
+@cindex @code{--srcdir}
+@cindex @code{srcdir} option
+@vindex srcdir
+Direct each generated @file{Makefile} to use the sources located in directory
+@var{dir}.  Use this option whenever you wish the object code to reside in a
+different place from the source code.  The @dfn{build directory} is always
+assumed to be the directory you call @code{configure} from.  See @ref{Build
+directories, , Build directories}, for an example.  If the source directory is
+not specified, @code{configure} assumes that the source is in your current
+directory.  If @code{configure} finds no @file{configure.in} there, it searches
+in the same directory that the @code{configure} script itself lies in.
+Pathnames specified (Values for @var{dir}) can be either absolute relative to
+the @emph{build} directory.
+
+@item --rm
+@cindex @code{--rm}
+@cindex @code{rm} option
+@vindex rm
+@emph{Remove} the configuration specified by @var{hosttype} and the other
+command-line options, rather than create it.
+
+@c FIXME: check @ref
+@quotation
+@emph{Note:} We recommend that you use @samp{make distclean} rather than
+use this option; see @ref{Invoking make,,Invoking @code{make},make,GNU
+Make}, for details on @samp{make distclean}.
+@end quotation
+
+@item --site=@var{site}
+@cindex @code{--site}
+@cindex @code{site} option
+@vindex site
+Generate the @file{Makefile} using site-specific @file{Makefile} fragments for
+@var{site}.  @xref{Makefile fragments, , Adding information about local
+conventions}.
+
+@item --prefix=@var{dir}
+@cindex @code{--prefix}
+@cindex @code{prefix} option
+@vindex prefix
+Configure the source to install programs and files under directory @var{dir}.
+
+This option sets the variable @samp{prefix}.  Each generated @file{Makefile}
+will have its @samp{prefix} variables set to this value.  (@xref{What configure
+really does, , What @code{configure} really does}.)
+
+@item --exec-prefix=@var{dir}
+@cindex @code{--exec-prefix}
+@cindex @code{exec-prefix} option
+@vindex exec-prefix
+Configure the source to install @dfn{host dependent} files in @var{dir}.
+
+This option sets the variable @samp{exec_prefix}.  Each generated
+@file{Makefile} will have its @samp{exec_prefix} variables set to this value.
+(@xref{What configure really does, , What @code{configure} really does}.)
+
+@item --program-prefix=@var{string}
+@cindex @code{--program-prefix}
+@cindex @code{program-prefix} option
+@vindex program-prefix
+Configure the source to install certain programs using @var{string} as a
+prefix.  This applies to programs which might be used for cross-compilation,
+such as the compiler and the binary utilities, and also to programs which have
+the same names as common Unix programs, such as @code{make}.
+
+This option sets the variable @samp{program_prefix}.  Each generated
+@file{Makefile} will have its @samp{program_prefix} variables set to this
+value.  (@xref{What configure really does, , What @code{configure} really
+does}.)
+
+@item --tmpdir=@var{tmpdir}
+@cindex @code{--tmpdir}
+@cindex @code{tmpdir} option
+@vindex tmpdir
+Use the directory @var{tmpdir} for @code{configure}'s temporary files.  The
+default is the value of the environment variable @w{@code{TMPDIR}}, or
+@file{/tmp} if the environment variable is not set.
+
+@item --with-@var{package}[=@var{yes/no}]
+@itemx --without-@var{package}
+@cindex @code{--with-@var{package}}
+@cindex @code{with-@var{package}} option
+@vindex with-@var{package}
+@cindex @code{--without-@var{package}}
+@cindex @code{without-@var{package}} option
+@vindex without-@var{package}
+Indicate that @var{package} is present, or not present, depending on
+@var{yes/no}.  If @var{yes/no} is nonexistent, its value is assumed to be
+@code{yes}.  @samp{--without-@var{package}} is equivalent to
+@samp{--with-@var{package}=no}.
+
+For example, if you wish to configure the program @code{gcc} for a Sun
+SPARCstation running SunOS 4.x, and you want @code{gcc} to use the
+@sc{gnu} linker @code{ld}, you can configure @code{gcc} using
+
+@cindex Example session
+@smallexample
+eg$ configure --with-gnu-ld sun4
+@end smallexample
+
+@noindent
+@xref{What configure really does, , What @code{configure} really does}, for
+details.  See the installation or release notes for your particular package for
+details on which other @var{package} options are recognized.
+@c FIXME - need to include info about --with-* in other dox!
+
+@item --enable-@var{feature}[=@var{yes/no}]
+@itemx --disable-@var{feature}
+@cindex @code{--enable-@var{feature}}
+@cindex @code{enable-@var{feature}} option
+@vindex enable-@var{feature}
+@cindex @code{--disable-@var{feature}}
+@cindex @code{disable-@var{feature}} option
+@vindex disable-@var{feature}
+Include @var{feature}, or not, depending on @var{yes/no}.  If @var{yes/no} is
+nonexistent, its value is assumed to be @code{yes}.
+@samp{--disable-@var{feature}} is equivalent to
+@samp{--enable-@var{feature}=no}.
+
+@noindent
+@xref{What configure really does, , What @code{configure} really does}, for
+details.  See the installation or release notes for your particular package for
+details on which other @var{feature} options are recognized.
+@c FIXME - need to include info about --enable-* in other dox!
+
+@item --norecursion
+@cindex @code{--norecursion}
+@cindex @code{norecursion} option
+@vindex norecursion
+Configure only this directory; ignore any subdirectories.  This is used by the
+executable shell script @file{config.status} to reconfigure only the current
+directory; it is most often used non-interactively, when @code{make} is
+invoked.  (@xref{config.status, , @code{config.status}}.)
+
+@item --nfp
+@cindex @code{--nfp}
+@cindex @code{nfp} option
+@vindex nfp
+Assume that the intended @var{hosttype} has no floating point unit.
+
+@item -s
+@cindex @code{-s}
+@cindex @code{s} option
+Suppress status output.  This option is used internally by
+@code{configure} when calling itself recursively in subdirectories.  You
+can override this option with the @code{--verbose} option.
+
+@item -v
+@itemx --verbose
+@cindex @code{-v}
+@cindex @code{--verbose}
+@cindex @code{v} option
+@cindex @code{verbose} option
+@cindex Verbose Output
+@vindex verbose
+Print status lines for each directory configured.  Normally, only the
+status lines for the initial working directory are printed.
+
+@item --version
+@itemx -V
+@cindex version
+@cindex @code{--version}
+@cindex version
+Print the @code{configure} version number.
+
+@item --help
+@cindex Usage
+@cindex @code{--help}
+@cindex @code{help} option
+Print a short summary of how to invoke @code{configure}.
+@end table
+
+@cindex Abbreviating option names
+@cindex Truncating option names
+@cartouche
+@emph{Note:} You may introduce options with a single dash, @samp{-}, rather
+than two dashes, @samp{--}.  However, you may not be able to truncate long
+option names when using a single dash.  When using two dashes, options may be
+abbreviated as long as each option can be uniquely identified.  For example,
+@smallexample
+eg$ configure --s=/u/me/src @var{hosttype}
+@end smallexample
+@noindent
+is ambiguous, as @w{@samp{--s}} could refer to either @w{@samp{--site}} or
+@w{@samp{--srcdir}}.  However,
+@smallexample
+eg$ configure --src=/u/me/src @var{hosttype}
+@end smallexample
+@noindent
+is a valid abbreviation.
+@end cartouche
+
+
+@c ========================================================================
+@node Using configure
+@chapter Using @code{configure}
+@cindex Using @code{configure}
+@cindex Detailed usage
+@cindex Usage: detailed
+
+@code{configure} prepares source directories for building programs in
+them.  ``Configuring'' is the process of preparing software to compile
+correctly on a given @dfn{host}, for a given @dfn{target}.
+
+@code{configure} subsequently writes a configured @file{Makefile} from a
+pre-built template; @code{configure} uses variables that have been set in the
+configuring process to determine the values of some variables in the
+@file{Makefile}.  Because of this we will refer to both @code{configure}
+variables and @file{Makefile} variables.  This convention allows us to
+determine where the variable should be set initially, in either
+@file{configure.in} or @file{Makefile.in}.
+
+@menu
+* What configure really does:: What configure really does
+* configure.in::               The configure.in input file
+* Install locations::          Where to install things once they are built
+* Host::                       Telling configure what will source will be built
+* Target::                     Telling configure what the source will target
+* Makefile fragments::         Adding information about local conventions
+* Makefile extensions::        Extensions to the GNU coding standards
+@end menu
+
+@c ---------------------------------------------------------------------
+@node What configure really does
+@section What @code{configure} really does
+@cindex What @code{configure} really does
+@cindex Behind the scenes
+@cindex @code{configure} back end
+@cindex @code{configure} details
+
+Cygnus @code{configure} is a shell script that sets up an environment in
+which your programs will compile correctly for your machine and
+operating system, and will install in proper places.  @code{configure}
+accomplishes this task by doing the following:
+
+@itemize @bullet
+@item 
+it generates a @file{Makefile} from a custom template called
+@file{Makefile.in} in each relevant source directory;
+
+@item 
+it customizes the build process to your specifications; you set certain
+variables for @code{configure}, either on the command line or in the
+file @file{configure.in}, which subsequently sets variables in each
+generated @file{Makefile} to be used by @code{make} when actually
+building the software;
+
+@item 
+it creates @dfn{build directories}, places for your code to be compiled
+in before being installed;
+
+@item 
+it generates a @file{.gdbinit} in the build directory, if needed, to
+communicate to @code{gdb} where to find the program's source code;
+
+@item 
+it generates a shell script called @file{config.status}
+which is used most often by the @file{Makefile} to reconfigure itself;
+
+@item 
+it recurses in subdirectories, setting up entire trees so that they build
+correctly; if @code{configure} finds another @code{configure} script
+further down in a given source tree, it knows to use this script and not
+recur.
+@end itemize
+
+For the sake of safety (i.e., in order to prevent broken installations), the
+@sc{gnu} coding standards call for software to be @dfn{configured} in such a
+way that an end user trying to build a given package will be able to do so by
+affecting a finite number of variables.  All @sc{gnu} software comes with an
+executable @code{configure} shell script which sets up an environment within a
+build directory which will correctly compile your new package for your host
+(or, alternatively, whatever host you specify to @code{configure}).
+@ifinfo
+For further background on this topic, see @ref{Some Basic Terms, , Apologia
+Configure, cfg-paper, On Configuring Development Tools}, by K. Richard
+Pixley.
+@end ifinfo
+@iftex
+For further background on this topic, see @cite{On Configuring Development
+Tools} by K. Richard Pixley.
+@end iftex
+
+Use @code{configure} to set for the build process:
+
+@itemize @bullet
+@item 
+correct values for certain variables;
+
+@item 
+which type of host you wish to configure a given package for
+(@pxref{Host, , Host});
+
+@item 
+where you want to install this package (by using @samp{prefix},
+@samp{exec-prefix} and @samp{program-prefix}; @pxref{Install details, ,
+Full descriptions of all installation directories});
+
+@item 
+optionally, which type of machine you wish to @dfn{target} this
+package's output to (@pxref{Target, , Target});
+
+@item 
+which other @sc{gnu} packages are already installed and available to
+this particular build (by using the @samp{--with-@var{package}} option;
+@pxref{Invoking configure, , Invoking @code{configure}});
+
+@item 
+where to place temporary files (by using the @samp{--tmpdir=@var{dir}}
+option; @pxref{Invoking configure, , Invoking @code{configure}});
+
+@item whether to recur in subdirectories (changeable through the
+@w{@samp{--norecursion}} option; @pxref{Invoking configure, , Invoking
+@code{configure}}).
+@end itemize
+
+@code{configure} uses a few other files to complete its tasks.  These are
+discussed in detail where noted.
+
+@table @code
+@cindex Other files
+@item configure.in
+@cindex @code{configure.in} definition
+Input file for @code{configure}.  Shell script fragments reside here.
+@xref{configure.in, , The @code{configure.in} input file}.
+
+@item Makefile.in
+@cindex @code{Makefile.in} definition
+Template which @code{configure} uses to build a file called @file{Makefile} in
+the @dfn{build directory}.  @xref{Makefile generation, , @code{Makefile}
+generation}.
+
+@item config.sub
+@cindex @code{config.sub} definition
+Shell script used by @code{configure} to expand referents to the
+@var{hosttype} argument into a single specification of the form
+@w{@var{cpu-vendor-os}}.  For instance, on the command line you can
+specify
+
+@cindex Example session
+@example
+eg$ ./configure sun4
+@end example
+
+@noindent
+to configure for a Sun SPARCstation running SunOS 4.x.  @code{configure}
+consults @code{config.sub} to find that the three-part specification for this
+is
+
+@example
+sparc-sun-sunos4.1.1
+@end example
+
+@noindent
+which notes the @var{cpu} as @samp{sparc}, the @var{manufacturer} as @samp{sun}
+(Sun Microsystems), and the @var{os} (operating system) as @samp{sunos4.1.1},
+the SunOS 4.1.1 release.  @xref{configure variables, , Variables available to @code{configure}}.
+
+@item config.guess
+@cindex @code{config.guess} definition
+If you do not put the @var{hosttype} argument on the command line,
+@code{configure} uses the @code{config.guess} shell script to make an
+analysis of your machine (it assumes that you wish to configure your
+software for the type of machine on which you are running).  The output
+of @code{config.guess} is a three-part identifier as described above.
+
+@item config.status
+@cindex @code{config.status} definition
+The final step in configuring a directory is to create a shell script,
+@code{config.status}.  The main purpose of this file is to allow the
+@file{Makefile} for the current directory to rebuild itself, if
+necessary.  @xref{config.status, , @code{config.status}}.
+
+@item config/*
+@cindex @code{config/} subdirectory
+@code{configure} uses three types of @file{Makefile} @dfn{fragments}, which
+reside in the directory @file{@var{srcdir}/config/}.  @xref{Makefile fragments,
+, Adding information about local conventions}.
+@end table
+
+@menu
+* Build variables::         Variable-spaghetti made simple 
+* Build directories::       Build directories described well
+* Makefile generation::     To build a Makefile
+* config.guess::            Be vewwy quiet, I'm hunting system information
+* config.status::           To rebuild a Makefile
+@end menu
+
+@c ---------------------------------------------------------------------
+@node Build variables
+@subsection Build variables
+@cindex Build variables
+@cindex Cygnus Support Developer's Kit
+@cindex Variables
+
+There are several variables in the build process which you can control through
+build programs such as @code{make}.  These include machine definitions, local
+conventions, installation locations, locations for temporary files, etc.  This
+data is accessible through certain variables which are configurable in the
+build process; we refer to them as @dfn{build variables}.
+
+For lists of build variables which you can affect by using @code{configure},
+see @ref{configure variables, , Variables available to @code{configure.in}},
+and @ref{Install details, , Full descriptions of all installation directories}.
+
+Generally, build variables, which are used by the @file{Makefile} to
+determine various aspects of the build and installation processes, are
+changeable with command-line options to @code{configure}.  In most large
+suites of programs, like the Cygnus Support Developer's Kit, the
+individual programs reside in several subdirectories of a single source
+code ``tree''.  All of these subdirectories need to be configured with
+information relative to the @dfn{build directory}, which is not known
+until @code{configure} is run.  Unless specified otherwise,
+@code{configure} recursively configures every subdirectory in the source
+tree.
+
+Build variables are passed from @code{configure} directly into the
+@file{Makefile}, and use the same names (except that dashes are
+transformed into underbars; for example, when you specify the option
+@samp{--exec-prefix} on the command line, the @file{Makefile} variable
+@samp{exec_prefix} is set).  In other words, if you specify
+
+@cindex Example session
+@example
+eg$ ./configure --prefix=/usr/gnu/local @dots{} @var{hosttype}
+@end example
+
+@noindent
+on the command line, @code{configure} sets an variable called @samp{prefix} to
+@samp{/usr/gnu/local}, and passes this into the @file{Makefile} in the same
+manner.  After this command, each @file{Makefile} generated by @code{configure}
+will contain a line that reads:
+
+@example
+prefix = /usr/gnu/local
+@end example
+
+For a list of the @file{Makefile} variables @code{configure} can change, and
+instructions on how to change them, see @ref{configure variables, , Variables
+available to @code{configure.in}}, and @ref{Invoking configure, , Invoking
+@code{configure}}.
+
+@c ---------------------------------------------------------------------
+@node Build directories
+@subsection Build directories
+@cindex Build directories
+@cindex Object directories
+@cindex Building for multiple hosts
+@cindex Building for multiple targets
+
+By default, @code{configure} builds a @file{Makefile} and symbolic links in the
+same directory as the source files.  This default works for many cases, but it
+has limitations.  For instance, using this approach, you can only build object
+code for one host at a time.
+
+We refer to each directory where @code{configure} builds a @file{Makefile} as
+a @dfn{build directory}.
+
+The build directory for any given build is always the directory from which you
+call @code{configure}, or @file{.} relative to your prompt.  The default
+@dfn{source directory}, the place @code{configure} looks to find source code,
+is also @file{.}.  For instance, if we have a directory @file{/gnu-stuff/src/}
+that is the top branch of a tree of @sc{gnu} source code we wish to configure,
+then the program we will use to configure this code is
+@file{/gnu-stuff/src/configure}, as follows.  (Assume for the sake of argument
+that our machine is a sun4.)
+
+@cindex Example session
+@smallexample
+@group
+eg$ cd /gnu-stuff/src
+eg$ ./configure sun4
+Created "Makefile" in /gnu-stuff/src
+eg$
+@end group
+@end smallexample
+
+We just configured the code in @file{/gnu-stuff/src} to run on a Sun
+SPARCstation using SunOS 4.x by creating a @file{Makefile} in
+@file{/gnu-stuff/src}.  By default, we also specified that when this code is
+built, the object code should reside in the same directory,
+@file{/gnu-stuff/src}.
+
+However, if we wanted to build this code for more than one host, we would be in
+trouble, because the new configuration would write over the old one, destroying
+it in the process.  What we can do is to make a new @dfn{build directory} and
+configure from there.  Running @code{configure} from the new directory will
+place a correct @file{Makefile} and a @file{config.status} in this new file.
+That is all @code{configure} does; we must run @code{make} to generate any
+object code.  
+
+The new @file{Makefile} in @file{/gnu-stuff/sun4-obj}, created from the
+template file @file{/gnu-stuff/src/Makefile.in}, contains all the information
+needed to build the program.
+
+@cindex Example session
+@smallexample
+@group
+eg$ mkdir /gnu-stuff/sun4-obj
+eg$ cd /gnu-stuff/sun4-obj
+eg$ ../src/configure --srcdir=../src sun4
+Created "Makefile" in /gnu-stuff/sun4-obj
+eg$ ls
+Makefile       config.status
+eg$ make all info install install-info clean
+@var{compilation messages@dots{}}
+eg$ mkdir /gnu-stuff/solaris2
+eg$ cd /gnu-stuff/solaris2
+eg$ ../src/configure --srcdir=../src sol2
+Created "Makefile" in /gnu-stuff/solaris2
+eg$ ls
+Makefile       config.status
+eg$ make all info install install-info clean
+@var{compilation messages@dots{}}
+@end group
+@end smallexample
+
+We can repeat this for other configurations of the same software simply
+by making a new build directory and reconfiguring from inside it.  If
+you do not specify the @var{hosttype} argument, @code{configure}
+will attempt to figure out what kind of machine and operating system you
+happen to be using.  @xref{config.guess, , Determining system
+information}.  Of course, this may not always be the configuration you
+wish to build.
+
+@emph{Caution:} If you build more than one configuration for a single program,
+remember that you must also specify a different @samp{--prefix} for each
+configuration at configure-time.  Otherwise, both configurations will be
+installed in the same default location (@file{/usr/local}); the configuration
+to be installed last would overwrite previously installed configurations.
+
+@c ---------------------------------------------------------------------
+@node Makefile generation
+@subsection @code{Makefile} generation
+@cindex @code{Makefile} generation
+
+Cygnus @code{configure} creates a file called @file{Makefile} in the build
+directory which can be used with @code{make} to automatically build a given
+program or package.  @code{configure} also builds a @file{Makefile} for each
+relevant subdirectory for a given program or package (irrelevant subdirectories
+would be those which contain no code which needs configuring, and which
+therefore have no @code{configure} input file @file{configure.in} and no
+@file{Makefile} template @file{Makefile.in}).  @xref{Running, @code{make}
+Invocation, How to Run @code{make}, make, GNU Make}, for details on using
+@code{make} to compile your source code.
+
+Each @file{Makefile} contains variables which have been configured for a
+specific build.  These build variables are determined when @code{configure} is
+run.  All build variables have defaults.  By default, @code{configure}
+generates a @file{Makefile} which specifies: 
+
+@cindex Default configuration
+@itemize @bullet
+@item a @dfn{native} build, which is to occur 
+
+@item in the current directory, and which will be installed 
+
+@item in the default installation directory (@file{/usr/local}) when the code
+is compiled with @code{make}.  
+@end itemize
+
+@noindent
+Variables are changeable through command-line options to @code{configure}
+(@pxref{Invoking configure, , Invoking @code{configure}}).
+
+If you are porting a new program and intend to use @code{configure}, see
+@ref{Porting, , Porting with @code{configure}}, as well as @ref{Makefiles, ,
+Writing Makefiles, make, GNU Make}, and @ref{Makefiles, , Makefile Conventions,
+standards, GNU Coding Standards}.
+
+@c ---------------------------------------------------------------------
+@node config.guess
+@subsection Determining system information
+@cindex @code{config.guess}
+
+The shell script @code{config.guess} is called when you do not specify a
+@var{hosttype} on the command line to @code{configure}.  @code{config.guess}
+acquires available system information from your local machine through the shell
+command @code{uname}.  It compares this information to a database and attempts
+to determine a usable three-part system identifier (known as a @dfn{triple}) to
+use as your @var{hosttype}.  @xref{What configure really does, , What
+@code{configure} really does}, to see how this information is used.
+
+@emph{Note:}  If you do not specify a @var{hosttype} on the command line,
+@code{configure} will attempt to configure your software to run on the machine
+you happen to be using.  This may not be the configuration you desire.
+
+@c ---------------------------------------------------------------------
+@node config.status
+@subsection @code{config.status}
+@cindex @code{config.status}
+
+The final step in configuring a directory is to create an executable shell
+script, @file{config.status}.  The main purpose of this file is to allow the
+@file{Makefile} for the current directory to rebuild itself, if necessary.  It
+is usually run from within the @file{Makefile}.  @xref{Makefile extensions, ,
+Extensions to the @sc{gnu} coding standards}.
+
+@file{config.status} also contains a record of the @code{configure} session
+which created it.  
+
+@c ---------------------------------------------------------------------
+@node configure.in
+@section The @code{configure.in} input file
+@cindex @code{configure.in}
+
+A @file{configure.in} file for Cygnus @code{configure} consists of a
+@dfn{per-invocation} section, followed by a @dfn{per-host} section, followed by
+a @dfn{per-target} section, optionally followed by a @dfn{post-target} section.
+Each section is a shell script fragment, which is executed by the
+@code{configure} shell script at an appropriate time.  Values are passed among
+@code{configure} and the shell fragments through a set of shell variables.
+When each section is being interpreted by the shell, the shell's current
+directory is the build directory, and any files created by the section (or
+referred to by the section) will be relative to the build directory.  To
+reference files in other places (such as the source directory), prepend a shell
+variable such as @samp{$(srcdir)/} to the desired file name.
+
+@cindex @i{per-invocation} section
+The beginning of the @file{configure.in} file begins the @dfn{per-invocation}
+section.
+
+@cindex @i{per-host} section
+A line beginning with @samp{# per-host:} begins the @dfn{per-host} section.
+
+@cindex @i{per-target} section
+A line beginning with @samp{# per-target:} begins the @dfn{per-target} section.
+
+@cindex @i{post-target} section
+If it exists, the @dfn{post-target} section begins with @samp{# post-target:}.
+
+@menu
+* configure variables::    Variables available to configure.in
+* Minimal::                A minimal configure.in
+* Declarations::           For each invocation
+* per-host::               Host-specific instructions
+* per-target::             Target-specific instructions
+* post-target::            Instructions to be executed after target info
+* Example::                An example configure.in
+@end menu
+
+@c ---------------------------------------------------------------------
+@node configure variables
+@subsection Variables available to @code{configure.in}
+@cindex @file{configure.in} interface
+@cindex configure variables
+
+The following variables pass information between the standard parts of
+@code{configure} and the shell-script fragments in @file{configure.in}:
+
+@table @code
+@item srctrigger
+@cindex @code{srctrigger}
+@vindex srctrigger
+Contains the name of a source file that is expected to live in the source
+directory.  You must usually set this in the @dfn{per-invocation} section of
+@file{configure.in}.  @code{configure} tests to see that this file exists.  If
+the file does not exist, @code{configure} prints an error message.  This is
+used as a sanity check that @file{configure.in} matches the source directory.
+
+@item srcname
+@cindex @code{srcname}
+@vindex srcname
+Contains the name of the source collection contained in the source directory.
+You must usually set this in the @dfn{per-invocation} section of
+@file{configure.in}.  If the file named in @samp{srctrigger} does not exist,
+@code{configure} uses the value of @samp{srcname} when it prints the error
+message.
+
+@item configdirs
+@cindex @code{configdirs}
+@vindex configdirs
+Contains the names of any subdirectories in which @code{configure} should
+recurse.  You must usually set this in the @dfn{per-invocation} section of
+@file{configure.in}.
+If @file{Makefile.in} contains a line starting with @samp{SUBDIRS =},
+then it will be replaced with an assignment to @samp{SUBDIRS} using
+the value of @samp{configdirs} (if @samp{subdirs} is empty).  This can
+be used to determine which directories to configure and build depending
+on the host and target configurations.
+@c Most other matching makefile/config vars use the same name.  Why not
+@c this? (FIXME).
+@c Can we get rid of SUBDIRS-substitution?  It doesn't work well with subdirs.
+Use @samp{configdirs} (instead of the @samp{subdirs} variable
+described below) if you want to be able to partition the
+subdirectories, or use independent @file{Makefile} fragments.
+Each subdirectory can be independent, and independently reconfigured.
+
+@item subdirs
+@cindex @code{subdirs}
+@vindex subdirs
+Contains the names of any subdirectories where @code{configure} should create a
+@file{Makefile} (in addition to the current directory), @emph{without}
+recursively running @code{configure}.  Use @samp{subdirs} (instead of the
+@samp{configdirs} variable described above) if you want to configure all of the
+directories as a unit.  Since there is a single invocation of @code{configure}
+that configures many directories, all the directories can use the same
+@file{Makefile} fragments, and the same @code{configure.in}.
+
+@item host
+@cindex @code{host}
+@cindex Canonical ``triple''
+@vindex host
+Contains the full configuration name for the host (generated by the script
+@file{config.sub} from the name that you entered).  This is a three-part
+name (commonly referred to as a @dfn{triple}) of the form
+@var{cpu}-@var{vendor}-@var{os}.
+
+There are separate variables @samp{host_cpu}, @samp{host_vendor}, and
+@samp{host_os} that you can use to test each of the three parts; this variable
+is useful, however, for error messages, and for testing combinations of the
+three components.
+
+@item host_cpu
+@vindex host_cpu
+Contains the first element of the canonical triple representing the host
+as returned by @file{config.sub}.  This is occasionally used to
+distinguish between minor variations of a particular vendor's operating
+system and sometimes to determine variations in binary format between
+the host and the target.
+
+@item host_vendor
+@vindex host_vendor
+Contains the second element of the canonical triple representing the host as
+returned by @file{config.sub}.  This is usually used to distinguish among the
+numerous variations of @emph{common} operating systems.
+@c "@emph{common} OS" doesn't convey much to me.  Is this meant to cover 
+@c cases like Unix, widespread but with many variations?
+
+@item host_os
+@vindex host_os
+Contains the the third element of the canonical triple representing the
+host as returned by @file{config.sub}.
+
+@item target
+@cindex @code{target}
+@cindex Canonical ``triple''
+@vindex target
+Contains the full configuration name (generated by the script @file{config.sub}
+from the name that you entered) for the target.  Like the host, this is a
+three-part name of the form @var{cpu}-@var{vendor}-@var{os}.
+
+There are separate variables @samp{target_cpu}, @samp{target_vendor}, and
+@samp{target_os} that you can use to test each of the three parts; this
+variable is useful, however, for error messages, and for testing combinations
+of the three components.
+
+@item target_cpu
+@vindex target_cpu
+Contains the first element of the canonical triple representing the target as
+returned by @file{config.sub}.  This variable is used heavily by programs which
+are involved in building other programs, like the compiler, assembler, linker,
+etc.  Most programs will not need the @samp{target} variables at all, but this
+one could conceivably be used to build a program, for instance, that operated
+on binary data files whose byte order or alignment differ from the system where
+the program is running.
+
+@item target_vendor
+@vindex target_vendor
+Contains the second element of the canonical triple representing the target as
+returned by @file{config.sub}.  This is usually used to distinguish among the
+numerous variations of @emph{common} operating systems or object file
+formats.  It is sometimes used to switch between different flavors of user
+interfaces.
+@c above query re "@emph{common} OS" applies here too
+
+@item target_os
+@vindex target_os
+Contains the the third element of the canonical triple representing the
+target as returned by @file{config.sub}.  This variable is used by
+development tools to distinguish between subtle variations in object
+file formats that some vendors use across operating system releases.  It
+might also be use to decide which libraries to build or what user
+interface the tool should provide.
+
+@item floating_point
+@cindex @code{floating_point}
+@cindex @code{nfp} option
+@vindex floating_point
+Set to @samp{no} if you invoked @code{configure} with the @samp{--nfp}
+command-line option, otherwise it is empty.  This is a request to target
+machines with @dfn{no floating point} unit, even if the targets ordinarily have
+floating point units available.
+
+@item gas
+@cindex @code{with-gnu-as} option
+@vindex gas
+Set to @samp{true} if you invoked @code{configure} with the
+@w{@samp{--with-gnu-as}} command line option, otherwise it is empty.  This is a
+request to assume that the specified @var{hosttype} machine has @sc{gnu} @code{as}
+available even if it ordinarily does not.
+
+@item srcdir
+@cindex @code{srcdir}
+@vindex srcdir
+Set to the name of the directory containing the source for this program.
+This will be different from @file{.} if you have specified the
+@samp{--srcdir=@var{dir}} option.  @samp{srcdir} can indicate either an
+absolute path or a path relative to the build directory.
+
+@item package_makefile_frag
+@vindex package_makefile_frag
+If set in @file{configure.in}, this variable should be the name a file relative
+to @samp{srcdir} to be included in the resulting @file{Makefile}.  If the named
+file does not exist, @code{configure} will print a warning message.  This
+variable is not set by @code{configure}.
+
+@item host_makefile_frag
+@vindex host_makefile_frag
+If set in @file{configure.in}, this variable should be the name a file relative
+to @samp{srcdir} to be included in the resulting @file{Makefile}.  If the named
+file does not exist, @code{configure} will print a warning message.  This
+variable is not set by @code{configure}.
+
+@item target_makefile_frag
+@vindex target_makefile_frag
+If set in @file{configure.in}, this variable should be the name of a file,
+relative to @samp{srcdir}, to be included in the resulting @file{Makefile}.  If
+the named file does not exist, @code{configure} will print a warning message.
+This variable is not set by @code{configure}.
+
+@item site_makefile_frag
+@vindex site_makefile_frag
+Set to a file name representing to the default @file{Makefile} fragment for
+this host.  It may be set in @file{configure.in} to override this default.
+Normally @samp{site_makefile_frag} is empty, but will have a value if you
+specify @samp{--site=@var{site}} on the command line.
+@ignore -- this doesn't fit
+It is probably not a good idea to override this variable from
+@file{configure.in}, since that may defeat the @code{configure} user's
+intentions.
+@end ignore
+
+@item Makefile
+@vindex Makefile
+Set to the name of the generated @file{Makefile}.  Normally this value is
+precisely @file{Makefile}, but some programs may want something else.
+
+@item removing
+@cindex @code{rm} option
+@vindex removing
+Normally empty but will be set to some non-null value if you specified
+@samp{--rm} on the command line.  That is, if @samp{removing} is not empty,
+then @code{configure} is @emph{removing} a configuration rather than creating
+one.
+
+@item files
+@cindex Symbolic links
+@vindex files
+If this variable is not empty following the @dfn{per-target} section,
+then each word in its value will be the target of a symbolic link named
+in the corresponding word from the @samp{links} variable.
+
+@item links
+@cindex Symbolic links
+@vindex links
+If the @samp{files} variable is not empty following the @dfn{per-target}
+section, then @code{configure} creates symbolic links with the first word of
+@samp{links} pointing to the first word of @samp{files}, the second word of
+@samp{links} pointing to the second word of @samp{files}, and so on.
+@end table
+
+@c ---------------------------------------------------------------------
+@node Minimal
+@subsection A minimal @code{configure.in}
+@cindex Minimal @file{configure.in} example
+
+A minimal @file{configure.in} consists of four lines.
+
+@example
+srctrigger=foo.c
+srcname="source for the foo program"
+# per-host:
+# per-target:
+@end example
+
+The @samp{# per-host:} and @samp{# per-target:} lines divide the file into the
+three required sections.  The @samp{srctrigger} line names a file.
+@code{configure} checks to see that this file exists in the source directory
+before configuring.  If the @samp{srctrigger} file does not exist,
+@code{configure} uses the value of @samp{srcname} to print an error message
+about not finding the source.
+
+This particular example uses no links, and only the default host,
+target, and site-specific @file{Makefile} fragments if they exist.
+
+@c ---------------------------------------------------------------------
+@node Declarations
+@subsection For each invocation
+@cindex For each invocation
+@cindex Declarations section
+@cindex @i{per-invocation} section
+
+@code{configure} invokes the entire shell script fragment from the start of
+@file{configure.in} up to a line beginning with @w{@samp{# per-host:}}
+immediately after parsing command line arguments.  The variables
+@samp{srctrigger} and @samp{srcname} @emph{must} be set here.
+
+You might also want to set the variables @samp{configdirs} and
+@samp{package_makefile_frag} here.
+
+@c ---------------------------------------------------------------------
+@node per-host
+@subsection Host-specific instructions
+@cindex Host-specific instructions
+@cindex @i{host} shell-script fragment
+@cindex @i{per-host} section
+
+The @dfn{per-host} section of @file{configure.in} starts with the line that
+begins with @w{@samp{# per-host:}} and ends before a line beginning with
+@w{@samp{# per-target:}}.  @code{configure} invokes the commands in the
+@dfn{per-host} section when determining host-specific information.
+
+This section usually contains a big @code{case} statement using the variable
+@samp{host} to determine appropriate values for @samp{host_makefile_frag} and
+@samp{files}, although @samp{files} is not usually set here.  Usually, it is
+set at the end of the @dfn{per-target} section after determining the names of
+the target specific configuration files.
+
+@c ---------------------------------------------------------------------
+@node per-target
+@subsection Target-specific instructions
+@cindex Target-specific instructions
+@cindex target shell-script fragment
+@cindex @i{per-target} section
+
+The @dfn{per-target} section of @file{configure.in} starts with the line that
+begins with @w{@samp{# per-target:}} and ends before the line that begins with
+@w{@samp{# post-target:}}, if there is such a line.  Otherwise the
+@dfn{per-target} section extends to the end of the file.  @code{configure}
+invokes the commands in the @dfn{per-target} section when determining
+target-specific information, and before building any files, directories, or
+links.
+
+This section usually contains a big @code{case} statement using the variable
+@samp{target} to determine appropriate values for @samp{target_makefile_frag}
+and @samp{files}.  The last lines in the @dfn{per-target} section normally set
+the variables @samp{files} and @samp{links}.
+
+@c ---------------------------------------------------------------------
+@node post-target
+@subsection Instructions to be executed after target info
+@cindex Post-target shell-script fragment
+@cindex @i{post-target} section
+
+The @dfn{post-target} section is optional.  If it exists, the
+@samp{post-target} section starts with a line beginning with @w{@samp{#
+Post-target:}} and extends to the end of the file.  If it exists,
+@code{configure} invokes this section once for each target after
+building all files, directories, or links.
+
+This section is seldom needed, but you can use it to edit the @file{Makefile}
+generated by @code{configure}.
+
+@c ---------------------------------------------------------------------
+@node Example
+@subsection An example @code{configure.in}
+@cindex Example @file{configure.in}
+@cindex Sample @file{configure.in}
+@c @cindex @code{bison} @file{configure.in}
+@c this won't be the bison configure.in for long.. need better example
+
+Here is a small example of a @file{configure.in} file.
+
+@cartouche
+@example
+@group
+# This file is a collection of shell script fragments
+# used to tailor a template configure script as
+# appropriate for this directory.  For more information,
+# see configure.texi.
+
+configdirs=
+srctrigger=warshall.c
+srcname="bison"
+
+# per-host:
+case "$@{host@}" in
+m88k-motorola-*)
+        host_makefile_frag=config/mh-delta88
+        ;;
+esac
+
+# per-target:
+files="bison_in.hairy"
+links="bison.hairy"
+
+# post-target:
+@end group
+@end example
+@end cartouche
+
+@c ---------------------------------------------------------------------
+@node Install locations
+@section Install locations
+@cindex Where to install
+@cindex Install locations
+
+Using the default configuration, @samp{make install} creates a single tree of
+files, some of which are programs.  The location of this tree is determined by
+the value of the variable @samp{prefix}.  The default value of @samp{prefix} is
+@samp{/usr/local}.  This is often correct for native tools installed on only
+one host.
+
+@menu
+* prefix::            Changing the default install directory
+* exec_prefix::       How to separate host independent files
+                                         from host dependent files when
+                                         installing for multiple hosts
+* Install details::   Full descriptions of all installation subdirectories
+@end menu
+
+@c ---------------------------------------------------------------------
+@node prefix
+@subsection Changing the default install directory
+@cindex Changing the install directory
+@cindex @code{prefix} option
+@vindex prefix
+
+In the default configuration, all files are installed in subdirectories
+of @file{/usr/local}.  The location is determined by the value of
+the @code{configure} variable @samp{prefix}; in turn, this determines the
+value of the @file{Makefile} variable of the same name (@samp{prefix}).
+
+You can also set the value of the @file{Makefile} variable @samp{prefix}
+explicitly each time you invoke @code{make} if you are so inclined.  However,
+because many programs have this location compiled in, you must specify the
+@samp{prefix} value consistently on each invocation of @code{make}, or you will
+end up with a broken installation.
+
+To make this easier, the value of the @code{configure} variable
+@samp{prefix} can be set on the command line to @code{configure}
+using the option @samp{--prefix=}.  
+
+@c ---------------------------------------------------------------------
+@node exec_prefix
+@subsection Installing for multiple hosts
+@cindex Configuring for multiple hosts
+@cindex Sharing host-independent files
+@cindex Installing host-independent files
+@cindex The @code{exec_prefix} directory
+@vindex exec_prefix
+
+By default, host dependent files are installed in subdirectories of
+@file{$(exec_prefix)}.  The location is determined by the value of the
+@code{configure} variable @samp{exec_prefix}, which determines the value of the
+@file{Makefile} variable @samp{exec_prefix}.  This makes it easier to install
+for a single host, and simplifies changing the default location for the install
+tree.  The default doesn't allow for multiple hosts to effectively share
+host independent files, however.
+
+To configure so that multiple hosts can share common files, use something like:
+
+@cindex Example session
+@smallexample
+configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
+make all info install install-info clean
+
+configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
+make all info install install-info
+@end smallexample
+
+The first line configures the source for @var{host1} to place host-specific
+programs in subdirectories of @file{/usr/gnu/H-@var{host1}}.
+
+The second line builds and installs all programs for @var{host1},
+including both host-independent and host-specific files, as well as removing
+the host-specific object files from of the build directory.
+
+The third line reconfigures the source for @var{host2} to place host
+specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}}.
+
+The fourth line builds and installs all programs for @var{host2}.  Host
+specific files are installed in new directories, but the host
+independent files are installed @emph{on top of} the host
+independent files installed for @var{host1}.  This results in a single
+copy of the host independent files, suitable for use by both hosts.
+
+@xref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}, for
+more information.
+
+@c ---------------------------------------------------------------------
+@node Install details
+@subsection Full descriptions of all installation subdirectories
+@cindex Install details
+@cindex Installation subdirectories
+@cindex Subdirectories
+
+During any install, a number of standard directories are created.  Their names
+are determined by @file{Makefile} variables.  Some of the defaults for
+@file{Makefile} variables can be changed at configuration time using command
+line options to @code{configure}.  For more information on the standard
+directories or the @file{Makefile} variables, please refer to @ref{Makefiles, ,
+Makefile Conventions, standards, GNU Coding Standards}.  See also @ref{Makefile
+extensions, , Extensions to the @sc{gnu} coding standards}.
+
+Note that @code{configure} does not create the directory indicated by the
+variable @samp{srcdir} at any time.  @code{$(srcdir)} is not an installation
+directory.
+
+You can override all @file{Makefile} variables on the command line to
+@code{make}.  (@xref{Overriding, , Overriding Variables, make, GNU Make}.)  If
+you do so, you will need to specify the value precisely the same way for each
+invocation of @code{make}, or you risk ending up with a broken installation.
+This is because many programs have the locations of other programs or files
+compiled into them.  If you find yourself overriding any of the variables
+frequently, you should consider site dependent @file{Makefile} fragments.  See
+also @ref{Sites, , Adding site info}.
+
+During @samp{make install}, a number of standard directories are created and
+populated.  The following @file{Makefile} variables define them.  Those whose
+defaults are set by corresponding @code{configure} variables are marked
+``@code{Makefile} and @code{configure}''.
+
+@table @code
+@item prefix (@code{Makefile} and @code{configure})
+@cindex @code{prefix}
+@vindex prefix
+The root of the installation tree.  You can set its @file{Makefile} default
+with the @samp{--prefix=} command line option to @code{configure}
+(@pxref{Invoking configure, , Invoking @code{configure}}).  The default value
+for @samp{prefix} is @samp{/usr/local}.
+
+@item bindir
+@cindex @code{bindir}
+@vindex bindir
+A directory for binary programs that users can run.  The default value for
+@samp{bindir} depends on @samp{prefix}; @samp{bindir} is normally changed only
+indirectly through @samp{prefix}.  The default value for @samp{bindir} is
+@samp{$(prefix)/bin}.
+
+@item exec_prefix (@code{Makefile} and @code{configure})
+@cindex @code{exec_prefix}
+@vindex exec_prefix
+A directory for host dependent files.  You can specify the @file{Makefile}
+default value by using the @samp{--exec_prefix=} option to @code{configure}.
+(@xref{Invoking configure, , Invoking @code{configure}}.)  The default value
+for @samp{exec_prefix} is @samp{$(prefix)}.
+
+@item libdir
+@cindex @code{libdir}
+@vindex libdir
+A directory for libraries and support programs.  The default value for
+@samp{libdir} depends on @samp{prefix}; @samp{libdir} is normally changed only
+indirectly through @samp{prefix}.  The default value for @samp{libdir} is
+@samp{$(prefix)/lib}.
+
+@item mandir
+@cindex @code{mandir}
+@vindex mandir
+A directory for @code{man} format documentation (``man pages'').  The default
+value for @samp{mandir} depends on @samp{prefix}; @samp{mandir} is normally
+changed only indirectly through @samp{prefix}.  The default value for
+@samp{mandir} is @samp{$(prefix)/man}.
+
+@item man@var{N}dir
+@cindex @code{man@var{N}dir}
+@vindex man@var{N}dir
+These are eight variables named @samp{man1dir}, @samp{man2dir}, etc.  They name
+the specific directories for each man page section.  For example,
+@samp{man1dir} by default holds the filename @file{$(mandir)/man1}; this
+directory contains @file{emacs.1} (the man page for @sc{gnu} Emacs).
+Similarly, @samp{man5dir} contains the value @file{$(mandir)/man5}, indicating
+the directory which holds @file{rcsfile.5} (the man page describing the
+@code{rcs} data file format).  The default value for any of the
+@samp{man@var{N}dir} variables depends indirectly on @samp{prefix}, and is
+normally changed only through @samp{prefix}.  The default value for
+@samp{man@var{N}dir} is @samp{$(mandir)/man@var{N}}.
+
+@item man@var{N}ext
+@cindex @code{man@var{N}ext}
+@vindex man@var{N}ext
+@emph{Not supported by Cygnus @code{configure}}.  The @cite{@sc{gnu} Coding
+Standards} do not call for @samp{man1ext}, @samp{man2ext}, so the intended use
+for @code{manext} is apparently not parallel to @samp{mandir}.  Its use is not
+clear.  (See also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding
+standards}.)
+
+@item infodir
+@cindex @code{infodir}
+@vindex infodir
+A directory for @code{info} format documentation.  The default value for
+@samp{infodir} depends indirectly on @samp{prefix}; @samp{infodir} is
+normally changed only through @samp{prefix}.  The default value for
+@samp{infodir} is @samp{$(prefix)/info}.
+
+@item docdir
+@cindex @code{docdir}
+@vindex docdir
+A directory for any documentation that is in a format other than those used by
+@code{info} or @code{man}.  The default value for @samp{docdir} depends
+indirectly on @samp{prefix}; @samp{docdir} is normally changed only through
+@samp{prefix}.  The default value for @samp{docdir} is @samp{$(datadir)/doc}.
+@emph{This variable is an extension to the @sc{gnu} coding standards}.  (See
+also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}.)
+
+@item includedir
+@cindex @code{includedir}
+@vindex includedir
+A directory for the header files accompanying the libraries installed in
+@samp{libdir}.  The default value for @samp{includedir} depends on
+@samp{prefix}; @samp{includedir} is normally changed only indirectly
+through @samp{prefix}.  The default value for @samp{includedir} is
+@samp{$(prefix)/include}.
+@end table
+
+@c ---------------------------------------------------------------------
+@node Host
+@section Host
+@cindex Host
+
+The arguments to @code{configure} are @dfn{hosttypes}.  By
+@dfn{hosttype} we mean the @dfn{environment} in which the source will be
+compiled.  This need not necessarily be the same as the physical machine
+involved, although it usually is.
+
+For example, if some obscure machine had the @sc{gnu} @code{POSIX} emulation
+libraries available, it would be possible to configure most @sc{gnu} source for
+a @code{POSIX} system and build it on the obscure host.
+
+For more on this topic, see @ref{Host Environments, On Configuring Development
+Tools, Host Environments, cfg-paper, On Configuring Development Tools}.
+
+@c ---------------------------------------------------------------------
+@node Target
+@section Target
+@cindex Target
+
+For building native development tools, or most of the other @sc{gnu}
+tools, you need not worry about the target.  The @dfn{target} of a
+configuration defaults to the same as the @dfn{host}.
+
+For building cross development tools, please see @ref{Building Development
+Environments, On Configuring Development Tools, Building Development
+Environments, cfg-paper, On Configuring Development Tools}.
+
+@c ---------------------------------------------------------------------
+@node Makefile fragments
+@section Adding information about local conventions
+@cindex @code{Makefile} fragments
+@cindex Local conventions
+@cindex Adding local info
+@cindex Adding site info
+
+If you find that a tool does not get configured to your liking, or if
+@code{configure}'s conventions differ from your local conventions, you should
+probably consider @dfn{site-specific @file{Makefile} fragments}.  See also
+@ref{Sites, , Adding site info}.
+
+These are probably not the right choice for options that can be set from
+the @code{configure} command line or for differences that are host or
+target dependent.
+
+Cygnus @code{configure} uses three types of @file{Makefile} fragments.  In a
+generated @file{Makefile} they appear in the order: @dfn{target fragment},
+@dfn{host fragment}, and @dfn{site fragment}.  This allows host fragments to
+override target fragments, and site fragments to override both.
+
+Host-specific @file{Makefile} fragments conventionally reside in the
+@file{./config/} subdirectory with names of the form @file{mh-@var{hosttype}}.
+They are used for hosts that require odd options to the standard compiler and
+for compile time options based on the host configuration.
+
+Target-specific @file{Makefile} fragments conventionally reside in the
+@file{./config/} subdirectory with names of the form @file{mt-@var{target}}.
+They are used for target dependent compile time options.
+
+Site specific @file{Makefile} fragments conventionally reside in the
+@file{./config/} subdirectory with names of the form @file{ms-@var{site}}.
+They are used to override host- and target-independent compile time options.
+Note that you can also override these options on the @code{make} invocation
+line.
+
+@c ---------------------------------------------------------------------
+@node Makefile extensions
+@section Extensions to the @sc{gnu} coding standards
+@cindex @code{Makefile} extensions
+@cindex Cygnus extensions
+@cindex Coding standards extensions
+
+The following additions to the @sc{gnu} coding standards are required for
+Cygnus @code{configure} to work properly.
+
+@itemize @bullet
+@item
+The @file{Makefile} must contain exactly one line starting with @samp{####}.
+This line should follow any default macro definitions but precede any rules.
+Host, target, and site-specific @file{Makefile} fragments will be inserted
+immediately after this line.  If the line is missing, the fragments will not be
+inserted.
+
+@item
+Cygnus adds the following targets to each @file{Makefile}.  Their existence is
+not required for Cygnus @code{configure}, but they are documented here for
+completeness.
+
+@table @code
+@kindex info
+@item info
+Build all info files from texinfo source.
+
+@kindex install-info
+@item install-info
+Install all info files.
+
+@kindex clean-info
+@item clean-info
+Remove all info files and any intermediate files that can be generated
+from texinfo source.
+
+@kindex Makefile
+@item Makefile
+Calls @code{./config.status} to rebuild the @file{Makefile} in this directory.
+@end table
+
+@item
+The following @file{Makefile} targets have revised semantics:
+
+@table @code
+@kindex install
+@item install
+Should @emph{not} depend on the target @samp{all}.  If the program is not
+already built, @samp{make install} should fail.  This allows you to install
+programs even when @code{make} would otherwise determine them to be out of
+date.  This can happen, for example, when the result of a @samp{make all} is
+transported via tape to another machine for installation.
+
+@kindex clean
+@item clean
+Should remove any file that can be regenerated by the @file{Makefile},
+excepting only the @file{Makefile} itself, and any links created by
+@code{configure}.  That is, @code{make all clean} should return all directories
+to their original condition.  If this is not done, then the command sequence
+
+@cindex Example session
+@example
+configure @var{host1} ; make all install clean ; 
+configure @var{host2} ; make all install
+@end example
+
+@noindent
+will fail because of intermediate files intended for @var{host1}.
+@end table
+
+@item
+Cygnus adds the following macros to all @file{Makefile.in} files, but
+you are not required to use them to run Cygnus @code{configure}.
+
+@table @code
+@kindex docdir
+@item docdir
+The directory in which to install any documentation that is not either a
+@code{man} page or an @code{info} file.  For @code{man} pages, see
+@samp{mandir}; for @code{info}, see @samp{infodir}.
+
+@kindex includedir
+@item includedir
+The directory in which to install any header files that should be made
+available to users.  This is distinct from the @code{gcc} include directory,
+which is intended for @code{gcc} only.  Files in @samp{includedir} may be used
+by @code{cc} as well.
+@end table
+
+@item
+The following macros have revised semantics.  Most of them describe
+installation directories; see also @ref{Install details, , Full description of
+all installation subdirectories}.
+
+@table @code
+@kindex datadir
+@item datadir
+is used for host independent data files.
+
+@kindex mandir
+@item mandir
+The default path for @samp{mandir} depends on @samp{prefix}.
+
+@kindex infodir
+@item infodir
+The default path for @samp{infodir} depends on @samp{prefix}.
+
+@kindex BISON
+@item BISON
+is assumed to have a @code{yacc} calling convention.  To use @sc{gnu}
+@code{bison}, use @samp{BISON=bison -y}.
+@end table
+
+@item
+Each Cygnus @file{Makefile} also conforms to one additional restriction:
+
+When libraries are installed, the line containing the call to
+@samp{INSTALL_DATA} should always be followed by a line containing a call to
+@samp{RANLIB} on the installed library.  This is to accommodate systems that
+use @code{ranlib}.  Systems that do not use @code{ranlib} can set @samp{RANLIB}
+to ``@code{echo}'' in a host specific @file{Makefile} fragment.
+@end itemize
+
+@c ========================================================================
+@node Porting
+@chapter Porting with @code{configure}
+@cindex Porting with @code{configure}
+
+This section explains how to add programs, host and target configuration
+names, and site-specific information to Cygnus @code{configure}.
+
+@menu
+* Programs::               Adding configure to new programs
+* Hosts and targets::      Adding hosts and targets
+* Sites::                  Adding site info
+@end menu
+
+@c ---------------------------------------------------------------------
+@node Programs
+@section Adding @code{configure} to new programs
+@cindex Adding @code{configure} to new programs
+
+If you are writing a new program, you probably shouldn't worry about porting or
+configuration issues until it is running reasonably on some host.  Then refer
+back to this section.
+
+If your program currently has a @code{configure} script that meets the @sc{gnu}
+standards (@pxref{Configuration, , How Configuration Should Work, standards,
+GNU Coding Standards}, please do not add Cygnus @code{configure}.  It should be
+possible to add this program without change to a Cygnus @code{configure} style
+source tree.
+
+@cindex @code{autoconf}
+If the program is not target dependent, please consider using @code{autoconf}
+instead of Cygnus @code{configure}.  @code{autoconf} is available from the Free
+Software Foundation; it is a program which generates an executable shell script
+called @file{configure} by automatically finding information on the system to
+be configured on and embedding this information in the shell script.
+@file{configure} scripts generated by @code{autoconf} require no arguments, and
+accept the same options as Cygnus @code{configure}.  For detailed instructions
+on using @code{autoconf}, see @ref{Making configure Scripts, , How to organize
+and produce Autoconf scripts, autoconf, Autoconf}.
+
+
+To add Cygnus @code{configure} to an existing program, do the following:
+
+@table @bullet
+@item Make sure the @file{Makefile} conforms to the @sc{gnu} standard
+The coding standard for writing a @sc{gnu} @file{Makefile} is described in
+@ref{Makefiles, , Makefile Conventions, standards, GNU Coding Standards}.  For
+technical information on writing a @file{Makefile}, see @ref{Makefiles, ,
+Writing Makefiles, make, GNU Make}.
+
+@item Add Cygnus extensions to the @file{Makefile}
+These are described in @ref{Makefile extensions, , Extensions to the @sc{gnu}
+coding standards}.
+
+@item Collect package specific definitions in a single file
+Many packages are best configured using a common @file{Makefile} fragment which
+is included by all of the makefiles in the different directories of the
+package.  In order to accomplish this, set the variable
+@samp{package_makefile_fragment} to the name of the file.  It will be inserted
+into the final @file{Makefile} before the target-specific fragment.
+
+@item Move host support from @file{Makefile} to fragments
+This usually involves finding sections of the @file{Makefile} that say things
+like ``uncomment these lines for host @var{hosttype}'' and moving them to a new
+file called @file{./config/mh-@var{hosttype}}. For more information, see @ref{Hosts
+and targets, , Adding hosts and targets}.
+
+@item Choose defaults
+If the program has compile-time options that determine the way the program
+should behave, choose reasonable defaults and make these @file{Makefile}
+variables.  Be sure the variables are assigned their default values before the
+@samp{####} line so that site-specific @file{Makefile} fragments can override
+them (@pxref{Makefile extensions, , Extensions to the @sc{gnu} coding
+standards}).
+
+@item Locate configuration files
+If there is configuration information in header files or source files, separate
+it in such a way that the files have generic names.  Then move the specific
+instances of those files into the @file{./config/} subdirectory.
+
+@item Separate host and target information
+Some programs already have this information separated.  If yours does not, you
+will need to separate these two kinds of configuration information.  @dfn{Host
+specific} information is the information needed to compile the program.
+@dfn{Target specific} information is information on the format of data files
+that the program will read or write.  This information should live in separate
+files in the @file{./config/} subdirectory with names that reflect the
+configuration for which they are intended.
+
+At this point you might skip this step and simply move on.  If you do, you
+should end up with a program that can be configured only to build @dfn{native}
+tools, that is, tools for which the host system is also the target system.
+Later, you could attempt to build a cross tool and separate out the
+target-specific information by figuring out what went wrong.  This is often
+simpler than combing through all of the source code.
+
+@item Write @code{configure.in}
+Usually this involves writing shell script fragments to map from canonical
+configuration names into the names of the configuration files.  These files
+will then be linked at configure time from the specific instances of those
+files in @file{./config} to files in the build directory with more generic
+names.  (See also @ref{Build directories, , Build directories}.)  The format of
+@file{configure.in} is described in @ref{configure.in, , The
+@code{configure.in} input file}.
+
+@item Rename @file{Makefile} to @file{Makefile.in}
+@end table
+
+At this point you should have a program that can be configured using
+Cygnus @code{configure}.
+
+@c ---------------------------------------------------------------------
+@node Hosts and targets
+@section Adding hosts and targets
+@cindex Adding hosts and targets
+@cindex Hosts and targets
+
+To add a host or target to a program that already uses Cygnus @code{configure},
+do the following.
+
+@itemize @bullet
+
+@item
+Make sure the new configuration name is represented in @file{config.sub}.  If
+not, add it.  For more details, see the comments in the shell script
+@file{config.sub}.
+
+@item
+If you are adding a host configuration, look in @file{configure.in}, in the
+@dfn{per-host} section.  Make sure that your configuration name is represented
+in the mapping from host configuration names to configuration files.  If not,
+add it.  Also see @ref{configure.in, , The @code{configure.in} input file}.
+
+@item
+If you are adding a target configuration, look in @file{configure.in}, in the
+@dfn{per-target} section.  Make sure that your configuration name is
+represented in the mapping from target configuration names to configuration
+files.  If not, add it.  Also see @ref{configure.in, , The @code{configure.in}
+input file}.
+
+@item
+Look in @file{configure.in} for the variables @samp{files}, @samp{links},
+@samp{host_makefile_frag}, and @samp{target_makefile_frag}.  The values
+assigned to these variables are the names of the configuration files, (relative
+to @samp{srcdir}) that the program uses.  Make sure that copies of the files
+exist for your host.  If not, create them.  See also @ref{configure variables,
+, Variables available to @code{configure.in}}.
+@end itemize
+
+This should be enough to @code{configure} for a new host or target
+configuration name.  Getting the program to compile and run properly represents
+the hardest work of any port.
+
+@c ---------------------------------------------------------------------
+@node Sites
+@section Adding site info
+@cindex Sites
+@cindex Adding site info
+
+If some of the @file{Makefile} defaults are not right for your site, you can
+build site-specific @file{Makefile} fragments.  To do this, do the following.
+
+@itemize @bullet
+
+@item
+Choose a name for your site.  It must currently be less than eleven characters.
+
+@item
+If the program source does not have a @file{./config/} subdirectory, create it.
+
+@item
+Create a file called @file{./config/ms-@var{site}} where @var{site} is the name
+of your site.  In it, set whatever @file{Makefile} variables you need to
+override to match your site's conventions.
+
+@item
+Configure the program with:
+
+@cindex Example session
+@example
+configure @dots{} --site=@var{site}
+@end example
+
+@end itemize
+
+@c ---------------------------------------------------------------------
+@node Variables Index
+@unnumbered Variable Index
+
+@printindex vr
+
+@page
+@c ---------------------------------------------------------------------
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+@contents
+@bye
+
+@c Local Variables:
+@c fill-column: 79
+@c outline-regexp: "@chap"
+@c End:
+@c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")
+
diff --git a/contrib/binutils/etc/make-stds.texi b/contrib/binutils/etc/make-stds.texi
new file mode 100644
index 0000000..e7c9cf9
--- /dev/null
+++ b/contrib/binutils/etc/make-stds.texi
@@ -0,0 +1,893 @@
+@comment This file is included by both standards.texi and make.texinfo.
+@comment It was broken out of standards.texi on 1/6/93 by roland.
+
+@node Makefile Conventions
+@chapter Makefile Conventions
+@comment standards.texi does not print an index, but make.texinfo does.
+@cindex makefile, conventions for
+@cindex conventions for makefiles
+@cindex standards for makefiles
+
+This
+@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.
+
+@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 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 name @code{CFLAGS} is an exception to
+this rule, but we keep it because it is standard.)  Use @code{CPPFLAGS}
+in any compilation command that runs the preprocessor, and use
+@code{LDFLAGS} in any compilation command that does linking as well as
+in any direct use of @code{ld}.
+
+If there are C compiler options that @emph{must} be used for proper
+compilation of certain files, do not include them in @code{CFLAGS}.
+Users expect to be able to specify @code{CFLAGS} freely themselves.
+Instead, arrange to pass the necessary options to the C compiler
+independently of @code{CFLAGS}, by writing them explicitly in the
+compilation commands or by defining an implicit rule, like this:
+
+@smallexample
+CFLAGS = -g
+ALL_CFLAGS = -I. $(CFLAGS)
+.c.o:
+        $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+@end smallexample
+
+Do include the @samp{-g} option in @code{CFLAGS}, because that is not
+@emph{required} for proper compilation.  You can consider it a default
+that is only recommended.  If the package is set up so that it is
+compiled with GCC by default, then you might as well include @samp{-O}
+in the default value of @code{CFLAGS} as well.
+
+Put @code{CFLAGS} last in the compilation command, after other variables
+containing compiler options, so the user can use @code{CFLAGS} to
+override the others.
+
+Every Makefile should define the variable @code{INSTALL}, which is the
+basic command for installing a file into the system.
+
+Every Makefile should also define the variables @code{INSTALL_PROGRAM}
+and @code{INSTALL_DATA}.  (The default for each of these should be
+@code{$(INSTALL)}.)  Then it should use those variables as the commands
+for actual installation, for executables and nonexecutables
+respectively.  Use these variables as follows:
+
+@example
+$(INSTALL_PROGRAM) foo $(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+@end example
+
+@noindent
+Always use a file name, not a directory name, as the second argument of
+the installation commands.  Use a separate command for each file to be
+installed.
+
+@node Directory Variables
+@section Variables for Installation Directories
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place.  The standard names for these
+variables are described below.  They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, 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 @samp
+@item prefix
+A prefix used in constructing the default values of the variables listed
+below.  The default value of @code{prefix} should be @file{/usr/local}.
+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@@}.)
+
+@item exec_prefix
+A prefix used in constructing the default values of some of the
+variables listed below.  The default value of @code{exec_prefix} should
+be @code{$(prefix)}.
+(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.
+@end table
+
+Executable programs are installed in one of the following directories.
+
+@table @samp
+@item bindir
+The directory for installing executable programs that users can run.
+This should normally be @file{/usr/local/bin}, but write it as
+@file{$(exec_prefix)/bin}.
+(If you are using Autoconf, write it as @samp{@@bindir@@}.)
+
+@item sbindir
+The directory for installing executable programs that can be run from
+the shell, but are only generally useful to system administrators.  This
+should normally be @file{/usr/local/sbin}, but write it as
+@file{$(exec_prefix)/sbin}.
+(If you are using Autoconf, write it as @samp{@@sbindir@@}.)
+
+@item libexecdir
+@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
+The directory for installing executable programs to be run by other
+programs rather than by users.  This directory should normally be
+@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
+(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@@}.)
+
+@c rewritten to avoid overfull hbox --tower
+Do not install executables
+@c here
+in this directory (they probably
+belong in @file{$(libexecdir)} or @file{$(sbindir)}).  Also do not
+install files that are modified in the normal course of their use
+(programs whose purpose is to change the configuration of the system
+excluded).  Those probably belong in @file{$(localstatedir)}.
+
+@item sharedstatedir
+The directory for installing architecture-independent data files which
+the programs modify while they run.  This should normally be
+@file{/usr/local/com}, but write it as @file{$(prefix)/com}.
+(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
+@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
+$(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 $@@; \
+# 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=$(infodir)/dir \
+                       $(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 many cases, the definition of this target can be very simple:
+
+@smallexample
+install-strip:
+        $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+                install
+@end smallexample
+
+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 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
+
+This rule should not modify the directories where compilation is done.
+It should do nothing but create installation directories.
+@end table
+
+@node Install Command Categories
+@section Install Command Categories
+
+@cindex pre-installation commands
+@cindex post-installation commands
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands.
+
+Normal commands move files into their proper places, and set their
+modes.  They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+Pre-installation and post-installation commands may alter other files;
+in particular, they can edit global configuration files or data bases.
+
+Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+The most common use for a post-installation command is to run
+@code{install-info}.  This cannot be done with a normal command, since
+it alters a file (the Info directory) which does not come entirely and
+solely from the package being installed.  It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+Most programs don't need any pre-installation commands, but we have the
+feature just in case it is needed.
+
+To classify the commands in the @code{install} rule into these three
+categories, insert @dfn{category lines} among them.  A category line
+specifies the category for the commands that follow.
+
+A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end.  There are three
+variables you can use, one for each category; the variable name
+specifies the category.  Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+@emph{should not} define them in the makefile).
+
+Here are the three possible category lines, each with a comment that
+explains what it means:
+
+@smallexample
+        $(PRE_INSTALL)     # @r{Pre-install commands follow.}
+        $(POST_INSTALL)    # @r{Post-install commands follow.}
+        $(NORMAL_INSTALL)  # @r{Normal commands follow.}
+@end smallexample
+
+If you don't use a category line at the beginning of the @code{install}
+rule, all the commands are classified as normal until the first category
+line.  If you don't use any category lines, all the commands are
+classified as normal.
+
+These are the category lines for @code{uninstall}:
+
+@smallexample
+        $(PRE_UNINSTALL)     # @r{Pre-uninstall commands follow.}
+        $(POST_UNINSTALL)    # @r{Post-uninstall commands follow.}
+        $(NORMAL_UNINSTALL)  # @r{Normal commands follow.}
+@end smallexample
+
+Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+If the @code{install} or @code{uninstall} target has any dependencies
+which act as subroutines of installation, then you should start
+@emph{each} dependency's commands with a category line, and start the
+main target's commands with a category line also.  This way, you can
+ensure that each command is placed in the right category regardless of
+which of the dependencies actually run.
+
+Pre-installation and post-installation commands should not run any
+programs except for these:
+
+@example
+[ basename bash cat chgrp chmod chown cmp cp dd diff echo
+egrep expand expr false fgrep find getopt grep gunzip gzip
+hostname install install-info kill ldconfig ln ls md5sum
+mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+test touch true uname xargs yes
+@end example
+
+@cindex binary packages
+The reason for distinguishing the commands in this way is for the sake
+of making binary packages.  Typically a binary package contains all the
+executables and other files that need to be installed, and has its own
+method of installing them---so it does not need to run the normal
+installation commands.  But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+Programs to build binary packages work by extracting the
+pre-installation and post-installation commands.  Here is one way of
+extracting the pre-installation commands:
+
+@smallexample
+make -n install -o all \
+      PRE_INSTALL=pre-install \
+      POST_INSTALL=post-install \
+      NORMAL_INSTALL=normal-install \
+  | gawk -f pre-install.awk
+@end smallexample
+
+@noindent
+where the file @file{pre-install.awk} could contain this:
+
+@smallexample
+$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@}
+on @{print $0@}
+$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@}
+@end smallexample
+
+The resulting file of pre-installation commands is executed as a shell
+script as part of installing the binary package.
diff --git a/contrib/binutils/etc/standards.texi b/contrib/binutils/etc/standards.texi
new file mode 100644
index 0000000..4170093
--- /dev/null
+++ b/contrib/binutils/etc/standards.texi
@@ -0,0 +1,3061 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename standards.info
+@settitle GNU Coding Standards
+@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES!
+@set lastupdate 16 January 1997
+@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 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 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title GNU Coding Standards
+@author Richard Stallman
+@author last updated @value{lastupdate}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end titlepage
+
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top Version
+
+Last updated @value{lastupdate}.
+@end ifinfo
+
+@menu
+* Preface::                     About the GNU Coding Standards
+* Intellectual Property::       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
+@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.
+
+Corrections or suggestions regarding this document should be sent to
+@code{gnu@@prep.ai.mit.edu}.  If you make a suggestion, please include a
+suggested new wording for it; our time is limited.  We prefer a context
+diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
+you don't have those files, please mail your suggestion anyway.
+
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+
+@node Intellectual Property
+@chapter Keeping Free Software Free
+
+This @value{CHAPTER} discusses how you can make sure that GNU software
+remains unencumbered.
+
+@menu
+* Reading Non-Free Code::       Referring to Proprietary Programs
+* Contributions::               Accepting Contributions
+@end menu
+
+@node Reading Non-Free Code
+@section Referring to Proprietary Programs
+
+Don't in any circumstances refer to Unix source code for or during
+your work on GNU!  (Or to any other proprietary programs.)
+
+If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different.  You could keep the entire input file in core and scan it
+there instead of using stdio.  Use a smarter algorithm discovered more
+recently than the Unix program.  Eliminate use of temporary files.  Do
+it in one pass instead of two (we did this in the assembler).
+
+Or, on the contrary, emphasize simplicity instead of speed.  For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+Or go for generality.  For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead.  Make sure your program handles NULs and
+other funny characters in the input files.  Add a programming language
+for extensibility and write part of the program in that language.
+
+Or turn some parts of the program into independently usable libraries.
+Or use a simple garbage collector instead of tracking precisely when
+to free memory, or use a new GNU facility such as obstacks.
+
+
+@node Contributions
+@section Accepting Contributions
+
+If someone else sends you a piece of code to add to the program you are
+working on, we need legal papers to use it---the same sort of legal
+papers we will need to get from you.  @emph{Each} significant
+contributor to a program must sign some sort of legal papers in order
+for us to have clear title to the program.  The main author alone is not
+enough.
+
+So, before adding in any contributions from other people, tell us
+so we can arrange to get the papers.  Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+This applies both before you release the program and afterward.  If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for it.
+
+You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes.  Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use.  For example, if you write a different solution to the
+problem, you don't need to get papers.
+
+We know this is frustrating; it's frustrating for us as well.  But if
+you don't wait, you are going out on a limb---for example, what if the
+contributor's employer won't sign a disclaimer?  You might have to take
+that code out again!
+
+The very worst thing is if you forget to tell us about the other
+contributor.  We could be very embarrassed in court some day as a
+result.
+
+@node Design Advice
+@chapter General Program Design
+
+This @value{CHAPTER} discusses some of the issues you should take into
+account when designing your program.
+
+@menu
+* Compatibility::               Compatibility with other implementations
+* Using Extensions::            Using non-standard features
+* ANSI C::                      Using ANSI C features
+* Source Language::             Using languages other than C
+@end menu
+
+@node Compatibility
+@section 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 @sc{ansi} C if @sc{ansi} C specifies their behavior, and
+upward compatible with @sc{POSIX} if @sc{POSIX} specifies their
+behavior.
+
+When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+@sc{ansi} C and @sc{POSIX} prohibit many kinds of extensions.  Feel free
+to make the extensions anyway, and include a @samp{--ansi},
+@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.  Try to
+redesign its interface.
+
+Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value).  Please make your program recognize this
+variable if appropriate.
+
+When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better.  (For example,
+@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 not in Berkeley Unix are welcome.
+Additional programs with no counterpart in Unix may be useful,
+but our first priority is usually to duplicate what Unix already
+has.
+
+@node Using Extensions
+@section Using Non-standard Features
+
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities.  Whether to use these
+extensions in implementing your program is a difficult question.
+
+On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program
+unless the other GNU tools are available.  This might cause the
+program to work on fewer kinds of machines.
+
+With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a ``keyword'' @code{INLINE}
+and define that as a macro to expand into either @code{inline} or
+nothing, depending on the compiler.
+
+In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+An exception to this rule are the large, established programs (such as
+Emacs) which run on a great variety of systems.  Such programs would
+be broken by use of GNU extensions.
+
+Another exception is for programs that are used as part of
+compilation: anything that must be compiled with other compilers in
+order to bootstrap the GNU compilation facilities.  If these require
+the GNU compiler, then no one can compile them without having them
+installed already.  That would be no good.
+
+@node ANSI C
+@section @sc{ansi} C and pre-@sc{ansi} C
+
+Do not ever use the ``trigraph'' feature of @sc{ansi} C.
+
+@sc{ansi} C is widespread enough now that it is ok to write new programs
+that use @sc{ansi} C features (and therefore will not work in
+non-@sc{ansi} compilers).  And if a program is already written in
+@sc{ansi} C, there's no need to convert it to support non-@sc{ansi}
+compilers.
+
+However, it is easy to support non-@sc{ansi} compilers in most programs,
+so you might still consider doing so when you write a program.  Instead
+of writing function definitions in @sc{ansi} prototype form,
+
+@example
+int
+foo (int x, int y)
+@dots{}
+@end example
+
+@noindent
+write the definition in pre-@sc{ansi} 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 @sc{ansi} C prototypes in all the files where the function is called.
+And once you have it, you lose nothing by writing the function
+definition in the pre-@sc{ansi} style.
+
+If you don't know non-@sc{ansi} C, there's no need to learn it; just
+write in @sc{ansi} C.
+
+@node Source Language
+@section Using Languages Other Than C
+
+Using a language other than C is like using a non-standard feature: it
+will cause trouble for users.  Even if GCC supports the other language,
+users may find it inconvenient to have to install the compiler for that
+other language in order to build your program.  So please write in C.
+
+There are three exceptions for this rule:
+
+@itemize @bullet
+@item
+It is okay to use a special language if the same program contains an
+interpreter for that language.
+
+For example, if your program links with GUILE, it is ok to write part of
+the program in Scheme or another language supported by GUILE.
+
+@item
+It is okay to use another language in a tool specifically intended for
+use with that language.
+
+This is okay because the only people who want to build the tool will be
+those who have installed the other language anyway.
+
+@item
+If an application is not of extremely widespread interest, then perhaps
+it's not important if the application is inconvenient to install.
+@end itemize
+
+@node Program Behavior
+@chapter Program Behavior for All Programs
+
+This @value{CHAPTER} describes how to write 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 for command line interfaces
+* Option Table::                Table of long options.
+* Memory Usage::                When and how to care about memory needs
+@end menu
+
+@node Semantics
+@section Writing Robust Programs
+
+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.
+
+Utilities reading files should not drop NUL characters, or any other
+nonprinting characters @emph{including those with codes above 0177}.  The
+only sensible exceptions would be utilities specifically intended for
+interface to certain types of printers that can't handle those characters.
+
+Check every system call for an error return, unless you know you wish to
+ignore errors.  Include the system error text (from @code{perror} or
+equivalent) in @emph{every} error message resulting from a failing
+system call, as well as the name of the file if any and the name of the
+utility.  Just ``cannot open foo.c'' or ``stat failed'' is not
+sufficient.
+
+Check every call to @code{malloc} or @code{realloc} to see if it
+returned zero.  Check @code{realloc} even if you are making the block
+smaller; in a system that rounds block sizes to a power of 2,
+@code{realloc} may get a different block if you ask for less space.
+
+In Unix, @code{realloc} can destroy the storage block if it returns
+zero.  GNU @code{realloc} does not have this bug: if it fails, the
+original block is unchanged.  Feel free to assume the bug is fixed.  If
+you wish to run your program on Unix, and wish to avoid lossage in this
+case, you can use the GNU @code{malloc}.
+
+You must expect @code{free} to alter the contents of the block that was
+freed.  Anything you want to fetch from the block, you must fetch before
+calling @code{free}.
+
+If @code{malloc} fails in a noninteractive program, make that a fatal
+error.  In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop.  This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+Use @code{getopt_long} to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+When static storage is to be written in during program execution, use
+explicit C code to initialize it.  Reserve C initialized declarations
+for data that will not be changed.
+@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 will be supported compatibly by GNU.
+
+By default, the GNU system will provide the signal handling functions of
+@sc{BSD} and of @sc{POSIX}.  So GNU software should be written to use
+these.
+
+In error checks that detect ``impossible'' conditions, just abort.
+There is usually no point in printing any message.  These checks
+indicate the existence of bugs.  Whoever wants to fix the bugs will have
+to read the source code and run a debugger.  So explain the problem with
+comments in the source.  The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+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.
+
+If you make temporary files, check the @code{TMPDIR} environment
+variable; if that variable is defined, use the specified directory
+instead of @file{/tmp}.
+
+@node Libraries
+@section Library Behavior
+
+Try to make library functions reentrant.  If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of @code{malloc} itself.
+
+Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this
+prefix.  In addition, there should only be one of these in any given
+library member.  This usually means putting each one in a separate
+source file.
+
+An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+External symbols that are not documented entry points for the user
+should have names beginning with @samp{_}.  They should also contain
+the chosen name prefix for the library, to prevent collisions with
+other libraries.  These can go in the same files with user entry
+points if you like.
+
+Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+@node Errors
+@section Formatting Error Messages
+
+Error messages from compilers should look like this:
+
+@example
+@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+Error messages from other noninteractive programs should look like this:
+
+@example
+@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+@noindent
+when there is an appropriate source file, or like this:
+
+@example
+@var{program}: @var{message}
+@end example
+
+@noindent
+when there is no relevant source file.
+
+In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message.  The place to indicate which program is running is in the
+prompt or with the screen layout.  (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+The string @var{message} should not begin with a capital letter when
+it follows a program name and/or 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 Command Line Interfaces
+
+Please don't make the behavior of a utility depend on the name used
+to invoke it.  It is useful sometimes to make a link to a utility
+with a different name, and that should not change what it does.
+
+Instead, use a run time option or a compilation switch or both
+to select among the alternate behaviors.
+
+Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with.  Device independence is an
+important principle of the system's design; do not compromise it
+merely to save someone from typing an option now and then.
+
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+Compatibility requires certain programs to depend on the type of output
+device.  It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect.  In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type.  For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+
+It is a good idea to follow the @sc{POSIX} guidelines for the
+command-line options of a program.  The easiest way to do this is to use
+@code{getopt} to parse them.  Note that the GNU version of @code{getopt}
+will normally permit options anywhere among the arguments unless the
+special argument @samp{--} is used.  This is not what @sc{POSIX}
+specifies; it is a GNU extension.
+
+Please define long-named options that are equivalent to the
+single-letter Unix-style options.  We hope to make GNU more user
+friendly this way.  This is easy to do with the GNU function
+@code{getopt_long}.
+
+One of the advantages of long-named options is that they can be
+consistent from program to program.  For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}.  To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program (@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.
+
+All programs should support two standard options: @samp{--version}
+and @samp{--help}.
+
+@table @code
+@item --version
+This option should direct the program to 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:
+
+@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 don't mention all 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.
+
+@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.
+
+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
+
+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 @samp{gnu@@prep.ai.mit.edu} 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 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 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 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 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 initial
+@samp{-i} in @code{expand}.
+
+@item initial-tab
+@samp{-T} in @code{diff}.
+
+@item inode
+@samp{-i} in @code{ls}.
+
+@item interactive
+@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+@samp{-e} in @code{m4};
+@samp{-p} in @code{xargs};
+@samp{-w} in @code{tar}.
+
+@item intermix-type
+@samp{-p} in @code{shar}.
+
+@item jobs
+@samp{-j} in Make.
+
+@item just-print
+@samp{-n} in Make.
+
+@item keep-going
+@samp{-k} in Make.
+
+@item keep-files
+@samp{-k} in @code{csplit}.
+
+@item kilobytes
+@samp{-k} in @code{du} and @code{ls}.
+
+@item 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 @code{gnu@@prep.ai.mit.edu}.
+
+@item macro-name
+@samp{-M} in @code{ptx}.
+
+@item mail
+@samp{-m} in @code{hello} and @code{uname}.
+
+@item make-directories
+@samp{-d} in @code{cpio}.
+
+@item makefile
+@samp{-f} in Make.
+
+@item mapped
+Used in GDB.
+
+@item max-args
+@samp{-n} in @code{xargs}.
+
+@item max-chars
+@samp{-n} in @code{xargs}.
+
+@item max-lines
+@samp{-l} in @code{xargs}.
+
+@item max-load
+@samp{-l} in Make.
+
+@item max-procs
+@samp{-P} in @code{xargs}.
+
+@item mesg
+@samp{-T} in @code{who}.
+
+@item message
+@samp{-T} in @code{who}.
+
+@item minimal
+@samp{-d} in @code{diff}.
+
+@item mixed-uuencode
+@samp{-M} in @code{shar}.
+
+@item mode
+@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+
+@item modification-time
+@samp{-m} in @code{tar}.
+
+@item multi-volume
+@samp{-M} in @code{tar}.
+
+@item name-prefix
+@samp{-a} in Bison.
+
+@item nesting-limit
+@samp{-L} in @code{m4}.
+
+@item net-headers
+@samp{-a} in @code{shar}.
+
+@item new-file
+@samp{-W} in Make.
+
+@item no-builtin-rules
+@samp{-r} in Make.
+
+@item no-character-count
+@samp{-w} in @code{shar}.
+
+@item no-check-existing
+@samp{-x} in @code{shar}.
+
+@item no-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 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 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 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 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
+
+If it 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 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 and Functions
+* 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
+
+It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero.  Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+
+It is also important for function definitions to start the name of the
+function in column zero.  This helps people to search for function
+definitions, and may also help certain tools recognize them.  Thus,
+the proper format is this:
+
+@example
+static char *
+concat (s1, s2)        /* Name starts in column zero here */
+     char *s1, *s2;
+@{                     /* Open brace in column zero here */
+  @dots{}
+@}
+@end example
+
+@noindent
+or, if you want to use @sc{ansi} C, format the definition like this:
+
+@example
+static char *
+concat (char *s1, char *s2)
+@{
+  @dots{}
+@}
+@end example
+
+In @sc{ansi} C, if the arguments don't fit nicely on one line,
+split it like this:
+
+@example
+int
+lots_of_args (int an_integer, long a_long, short a_short,
+              double a_double, float a_float)
+@dots{}
+@end example
+
+For the body of the function, we prefer code formatted like this:
+
+@example
+if (x < foo (y, z))
+  haha = bar[4] + 5;
+else
+  @{
+    while (z)
+      @{
+        haha += foo (z, z);
+        z--;
+      @}
+    return ++x + bar ();
+  @}
+@end example
+
+We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas.  Especially after the commas.
+
+When you split an expression into multiple lines, split it
+before an operator, not after one.  Here is the right way:
+
+@example
+if (foo_this_is_long && bar > win (x, y, z)
+    && remaining_condition)
+@end example
+
+Try to avoid having two operators of different precedence at the same
+level of indentation.  For example, don't write this:
+
+@example
+mode = (inmode[j] == VOIDmode
+        || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+        ? outmode[j] : inmode[j]);
+@end example
+
+Instead, use extra parentheses so that the indentation shows the nesting:
+
+@example
+mode = ((inmode[j] == VOIDmode
+         || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+        ? outmode[j] : inmode[j]);
+@end example
+
+Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+but Emacs would mess it up:
+
+@example
+v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+    + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+@end example
+
+But adding a set of parentheses solves the problem:
+
+@example
+v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+     + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+@end example
+
+Format do-while statements like this:
+
+@example
+do
+  @{
+    a = foo (a);
+  @}
+while (a > 0);
+@end example
+
+Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function).  It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page.  The formfeeds should appear alone on lines by themselves.
+
+
+@node Comments
+@section Commenting Your Work
+
+Every program should start with a comment saying briefly what it is for.
+Example: @samp{fmt - filter for simple filling of text}.
+
+Please 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
+
+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
+@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
+@end example
+
+
+@node Syntactic Conventions
+@section Clean Use of C Constructs
+
+Please explicitly declare all arguments to functions.
+Don't omit them just because they are @code{int}s.
+
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file.  Don't put @code{extern} declarations inside
+functions.
+
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function.  Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful.  This not only makes programs easier to understand, it also
+facilitates optimization by good compilers.  You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses.  This makes the program even cleaner.
+
+Don't use local variables or parameters that shadow global identifiers.
+
+Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead.  For example, instead
+of this:
+
+@example
+@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
+
+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 and Functions
+
+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.
+
+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.
+
+Use file names of 14 characters or less, to avoid creating gratuitous
+problems on older System V systems.  You can use the program
+@code{doschk} to test for this.  @code{doschk} also tests for potential
+name conflicts if the files were loaded onto an MS-DOS file
+system---something you may or may not care about.
+
+@node System Portability
+@section 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}.  The
+amount and kinds of variation among GNU systems on different @sc{cpu}s
+will be comparable to the variation among Linux-based GNU systems or
+among BSD systems today.  So the kinds of portability that are absolutely
+necessary are quite limited.
+
+But many users do run GNU software on non-GNU Unix or Unix-like systems.
+So supporting a variety of Unix-like systems is desirable, although not
+paramount.
+
+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}).
+
+As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is usually so much work that it
+is better if you don't.
+
+The planned GNU kernel is not finished yet, but you can tell which
+facilities it will provide by looking at the GNU C Library Manual.  The
+GNU kernel is based on Mach, so the features of Mach will also be
+available.  However, if you use Mach features, you'll probably have
+trouble debugging your program today.
+
+@node CPU Portability
+@section Portability between @sc{cpu}s
+
+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.
+
+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 @sc{ansi} C, so you can use
+prototypes (conditionalized to be active only in @sc{ansi} 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;
+     int a1, a2, a3;
+@{
+  fprintf (stderr, "error: ");
+  fprintf (stderr, s, a1, a2, a3);
+@}
+@end example
+
+@noindent
+In practice, this works on all machines, and it is much simpler than any
+``correct'' alternative.  Be sure @emph{not} to use a prototype
+for such functions.
+
+However, avoid casting pointers to integers unless you really need to.
+These assumptions really 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---it is ok to do so, but you'll have to
+make explicit provisions to handle different word sizes.
+
+@node System Functions
+@section Calling System Functions
+
+C implementations differ substantially.  @sc{ansi} C reduces but does not
+eliminate the incompatibilities; meanwhile, many users wish to compile
+GNU software with pre-@sc{ansi} compilers.  This chapter gives
+recommendations for how to use the more or less standard C library
+functions to avoid unnecessary loss of portability.
+
+@itemize @bullet
+@item
+Don't use the value of @code{sprintf}.  It returns the number of
+characters written on some systems, but not on all systems.
+
+@item
+@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.
+
+@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 an @sc{ansi} prototype.  The more you
+specify about the function, the more likely a conflict.
+
+@item
+In particular, don't unconditionally declare @code{malloc} or
+@code{realloc}.
+
+Most GNU programs use those functions just once, in functions
+conventionally named @code{xmalloc} and @code{xrealloc}.  These
+functions call @code{malloc} and @code{realloc}, respectively, and
+check the results.
+
+Because @code{xmalloc} and @code{xrealloc} are defined in your program,
+you can declare them in other files without any risk of type conflict.
+
+On most systems, @code{int} is the same length as a pointer; thus, the
+calls to @code{malloc} and @code{realloc} work fine.  For the few
+exceptional systems (mostly 64-bit machines), you can use
+@strong{conditionalized} declarations of @code{malloc} and
+@code{realloc}---or put these declarations in configuration files
+specific to those systems.
+
+@item
+The string functions require special treatment.  Some Unix systems have
+a header file @file{string.h}; 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 @sc{ansi}
+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 @sc{ansi}
+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
+
+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.
+
+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 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
+
+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
+
+@menu
+* GNU Manuals::                 Writing proper manuals.
+* Manual Structure Details::    Specific structure conventions.
+* 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 way to document part of the GNU system is to write a
+manual in the Texinfo formatting language.  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}).
+
+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 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.
+
+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.
+
+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
+exceptions.)  Also Unix man pages use a particular format which is
+different from what we use in GNU manuals.
+
+Please do not use the term ``pathname'' that is used in Unix
+documentation; use ``file name'' (two words) instead.  We use the term
+``path'' only for search paths, which are lists of file names.
+
+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 violations of law.
+
+@node Manual Structure Details
+@section 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 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.
+
+There will be automatic features for specifying a program name and
+quickly reading just this part of its manual.
+
+If one manual describes several programs, it should have such a node for
+each program described.
+
+@node NEWS File
+@section The 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
+
+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::         
+@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.
+
+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
+
+Here are some examples of change log entries:
+
+@example
+* register.el (insert-register): Return nil.
+(jump-to-register): Likewise.
+
+* sort.el (sort-subr): Return nil.
+
+* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+Restart the tex shell if process is gone or stopped.
+(tex-shell-running): New function.
+
+* expr.c (store_one_arg): Round size up for move_block_to_reg.
+(expand_call): Round up when emitting USE insns.
+* stmt.c (assign_parms): Round size up for move_block_from_reg.
+@end example
+
+It's important to name the changed function or variable in full.  Don't
+abbreviate 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.
+
+@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, 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.''
+
+@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
+
+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 Man Pages
+@section 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
+
+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
+
+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.
+
+Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+
+@table @samp
+@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}.  This allows users to choose which
+optional features to include.  Giving an optional @var{parameter} of
+@samp{no} should omit @var{feature}, if it is built by default.
+
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another.  No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior.  The only proper use for
+@samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+
+@item --with-@var{package}
+@c @r{[}=@var{parameter}@r{]}
+The package @var{package} will be installed, so configure this package
+to work with @var{package}.
+
+@c  Giving an optional @var{parameter} of
+@c @samp{no} should omit @var{package}, if it is used by default.
+
+Possible values of @var{package} include @samp{x}, @samp{x-toolkit},
+@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and
+@samp{gdb}.
+
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files.  That is outside the scope of what @samp{--with}
+options are for.
+
+@item --nfp
+The target machine has no floating point processor.
+
+@item --gas
+The target machine assembler is GAS, the GNU assembler.
+This is obsolete; users should use @samp{--with-gnu-as} instead.
+
+@item --x
+The target machine has the X Window System installed.
+This is obsolete; users should use @samp{--with-x} instead.
+@end table
+
+All @code{configure} scripts should accept all of these ``detail''
+options, whether or not they make any difference to the particular
+package at hand.  In particular, they should accept any option that
+starts with @samp{--with-} or @samp{--enable-}.  This is so users will
+be able to configure an entire GNU source tree at once with a single set
+of options.
+
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of.  That is deliberate.  We want to limit the possible
+configuration options in GNU software.  We do not want GNU programs to
+have idiosyncratic configuration options.
+
+Packages that perform part of 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.
+
+The way to build a cross-compiler, cross-assembler, or what have you, is
+to specify the option @samp{--host=@var{hosttype}} when running
+@code{configure}.  This specifies the host system without changing the
+type of target system.  The syntax for @var{hosttype} is the same as
+described above.
+
+Bootstrapping a cross-compiler requires compiling it on a machine other
+than the host it will run on.  Compilation packages accept a
+configuration option @samp{--build=@var{hosttype}} for specifying the
+configuration on which you will compile them, in case that is different
+from the host.
+
+Programs for which cross-operation is not meaningful need not accept the
+@samp{--host} option, because configuring an entire operating system for
+cross-operation is not a meaningful thing.
+
+Some programs have ways of configuring themselves automatically.  If
+your program is set up to do this, your @code{configure} script can simply
+ignore most of its arguments.
+
+@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
+
+Package the distribution of Foo version 69.96 in a gzipped tar file
+named @file{foo-69.96.tar.gz}.  It should unpack into a subdirectory
+named @file{foo-69.96}.
+
+Building and installing the program should never modify any of the files
+contained in the distribution.  This means that all the files that form
+part of the program in any way must be classified into @dfn{source
+files} and @dfn{non-source files}.  Source files are written by humans
+and never changed automatically; non-source files are produced from
+source files by programs under the control of the Makefile.
+
+Naturally, all the source files must be in the distribution.  It is okay
+to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them.  We commonly include non-source files
+produced by Bison, @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 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.
+
+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.
+
+@contents
+
+@bye