diff options
| -rw-r--r-- | .Sanitize | 2 | ||||
| -rw-r--r-- | ChangeLog | 20 | ||||
| -rw-r--r-- | cfg-paper.texi | 677 |
3 files changed, 697 insertions, 2 deletions
@@ -27,10 +27,10 @@ Things-to-keep: Makefile.in README -DOC.configure bison bfd binutils +cfg-paper.texi clib config config.sub @@ -1,7 +1,25 @@ +Wed Dec 18 15:39:34 1991 K. Richard Pixley (rich at cygnus.com) + + * DOC.configure, cfg-paper.texi: revised, updated, and texinfo'd. + renamed from DOC.configure to cfg-paper.texi. + +Mon Dec 16 23:05:19 1991 K. Richard Pixley (rich at rtl.cygnus.com) + + * configure, config.subr, config.sub: config.subr is now + config.sub again. + Fri Dec 13 01:17:06 1991 K. Richard Pixley (rich at cygnus.com) + * configure.texi: new file, in progress. + + * Makefile.in: build info file and install the man page for + configure. + + * configure.man: new file, first cut. + * configure: find config.subr again now that configuration "none" - has gone. + has gone. removed all traces of the -ansi option. removed all + traces of the -languages option. * config.subr: resync from rms. 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: |