revised, updated, texinfo'd and renamed

1 files changed, 677 insertions, 0 deletions

diff --git a/cfg-paper.texi b/cfg-paper.texi
new file mode 100644
index 0000000..a57d36d
--- /dev/null
+++ b/cfg-paper.texi
@@ -0,0 +1,677 @@
+\input texinfo    @c -*-para-*-
+@c %**start of header
+@setfilename cfg-paper.info
+@settitle On Configuring Development Tools
+@c %**end of header
+@setchapternewpage off
+
+@titlepage
+@sp 10
+@title{On Configuring Development Tools}
+@author{K. Richard Pixley}
+@author{Cygnus Support}
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991 Cygnus Support
+@end titlepage
+
+@ifinfo
+This document attempts to describe the general concepts behind
+configuration of the Cygnus Support release of the @sc{gnu} Development
+Tools.  It also discusses common usage..
+
+Copyright @copyright{} 1991 Cygnus Support
+@end ifinfo
+
+@node top, Some Basic Terms, (dir), (dir)
+
+@ifinfo
+This document attempts to describe the general concepts behind
+configuration of the Cygnus Support release 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
+@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{memset()} 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 -notation=infix
+@end example
+
+@noindent
+while for a sun4 with postfix you might use:
+
+@example
+./configure sun4 -notation=postfix
+@end example
+
+If we wanted to build both at the same time, in the same directory
+structure, the intermediate pieces used in the build process must be
+kept separate.
+
+@example
+./configure sun4 -subdirs -notation=postfix
+./configure sun3 -subdirs -notation=infix
+@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 @code{-subdirs} configuration option is necessary to
+get the new behaviour.  The order of the arguments doesn't matter.
+There should be exactly one argument without a leading '@minus{}' sign
+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{-subdirs} 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}.
+
+NOTE: @code{$(prefix)} was previously known as @code{$(destdir)}.
+
+You can elect to change @code{$(prefix)} only as a configuration time
+option.
+
+@example
+./configure sun4 -notation=postfix -prefix=/local
+@end example
+
+@noindent
+Will configure the source such that:
+
+@example
+make install
+@end example
+
+@noindent
+will put it's 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 Cygnus Support @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 Cygnus Support @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
+* The Three Party Cross::	The Three Party 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 Cygnus Support 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 Cygnus Support release and let's call the new
+development environment @emph{stage1}.
+
+Why bother?  Well, most people find that the Cygnus Support release
+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.  It's a good idea, 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.
+
+The Cygnus Support Release of the @sc{gnu} Development Tools can be
+configured for one such emulation at this time.
+
+@example
+./configure sun4 -ansi
+@end example
+
+@cindex ANSI
+@cindex X3J11
+@noindent
+will configure the source such that when built in a sun4 development
+environment the resulting development environment is capable of building
+sun4 programs from strictly conforming @sc{ANSI X3J11 C} source.
+Remember that the environment used to build the tools determines the
+machine on which this tools will run, so the resulting programs aren't
+necessarily intended to run on a sun4, although they usually are.  Also
+note that the source for the @sc{gnu} tools is not strictly conforming
+@sc{ansi} source so this configuration cannot be used to bootstrap the
+@sc{gnu} tools.
+
+
+@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, The Three Party 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 another a 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 The Three Party Cross,  , Crossing Into Targets, A Walk Through
+@section The Three Party 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 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{three party 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.
+
+@item ./configure -subdirs @var{hostname} -target=@var{targetname}
+creates a subdirectories @file{H-@var{hostname}} if @var{hostname} is @var{targetname} or
+@file{X-@var{hostname}-@var{targetname}} if it is not and configures the new directory.
+
+@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
+subdirectories 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: