diff options
Diffstat (limited to 'contrib/binutils/etc/cfg-paper.texi')
| -rw-r--r-- | contrib/binutils/etc/cfg-paper.texi | 717 |
1 files changed, 0 insertions, 717 deletions
diff --git a/contrib/binutils/etc/cfg-paper.texi b/contrib/binutils/etc/cfg-paper.texi deleted file mode 100644 index bcfbb31e13f8..000000000000 --- a/contrib/binutils/etc/cfg-paper.texi +++ /dev/null @@ -1,717 +0,0 @@ -\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: |