From: K. Richard Pixley Date: Mon, 15 Apr 1991 01:58:16 +0000 (+0000) Subject: Personal checkpoint. X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=14825ce9fa772c7024798c83291c822ee86797ea;p=binutils-gdb.git Personal checkpoint. --- diff --git a/README.configure b/README.configure index 4b1ca106640..a1e53a7ce48 100755 --- a/README.configure +++ b/README.configure @@ -1,44 +1,460 @@ - Configuration + On Configuring Development Tools - Last Mod Fri Apr 12 13:32:56 PDT 1991, by rich@sendai + Last Mod Sat Apr 13 19:45:44 PDT 1991, by rich@sendai -"Theory": +INTRO +----- -In this document, the word "host" refers to the environment in which -this source will be compiled. "host" and "host name" have nothing to -do with the proper name of your host, like "ucbvax", "prep.ai.mit.edu" -or "att.com". Instead they refer to things like "sun4" and "dec3100". + This document attempts to describe the general concepts behind + configuration of the Cygnus Support release of the GNU Development + Tools. It also discusses common usage. For a more in succint + description, please refer to the man page on "configure" which you + should have received {FIXME: ALONG WITH LOTS OF OTHER VERY PRETTY + HARD COPY OR IN A DIFFERENT DISTRIBUTION OR ON THIS TAPE OR SHRINK + BOX OR SOMETHING}. -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. +BASICS +------ -The word "target" refers to the environment produced by compiling this -source and installing the resulting binaries. +Some Basic Terms: -For example, if configured for host sun4 and target sun4, this implies -that we will compile on a sun4 to create a sun4 compilation -environment. If configured for host sun3 and target a29k, this -implies that we will compile on a sun3 to create an a29k compilation -environment. + There are a lot of terms that are frequently used when discussing + development tools. Most of the common terms have been used for + several 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. -Host sun3 only implies that the source will be compiled on a sun3. In -fact, it need not be actually compiled on a sun3. If the appropriate -native development tools, header files, libraries, and operating -system support were available on a foobox, then source configured for -a sun3 could be compiled on a foobox, resulting in a development -environment for, using the previous example host+target pair, "a29k" -on the foobox. Similarly, if the appropriate cross development tools, -header files, and libraries were available on a dec3100, then source -configured for host sun3 could be cross compiled to create an a29k -development environment intended to be run on a sun3. + 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. + + "Programs" run on "machines". Programs are very nearly always + written in "source". Programs are "built" from source. + "Compilation" is a process that is frequently, but not always, + used when building programs. + + +Host Environments: + + In this document, the word "host" refers to the environment in + which this source will be compiled. "host" and "host name" have + nothing to do with the proper name of your host, like "ucbvax", + "prep.ai.mit.edu" or "att.com". Instead they refer to things like + "sun4" and "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: + + cd desk-calculator ; configure sun4 + + does the trick. "configure" is a shell script that sets up + Makefiles, subdirectories, and symbolic links appropriate for + compiling the source on a sun4. + + The "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. + + cd desk-calculator ; configure sun3 + + 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. + + Host environment simply refers to the environment in which the + program will be built from the source. + + +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 "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, chosing + infix might be: + + configure sun3 +notation=infix + + while a sun4 with postfix might be: + + configure sun4 +notation=postfix + + 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. + + configure sun4 +forcesubdirs +notation=postfix + configure sun3 +forcesubdirs +notation=infix + + 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. A second + configuration overwrote the first. We've chosen to retain this + behaviour so the "+forcesubdirs" 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 + '+' 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 "in place" and won't show the "+forcesubdirs" 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 /usr/local. We refer to this location as + $(destdir). All user visible programs will be installed in + $(destdir)/bin. All other programs and files will be installed in + a subdirectory of $(destdir)/lib. For the tools in this + directory, the files not normally user visible will be installed + in $(destdir)/lib/gcc. + + You can elect to change $(destdir) only as a configuration time + option. + + configure sun4 +notation=postfix +destdir=/local + + Will configure the source such that: + + make install + + will put it's programs in /local/bin and /local/lib/gcc. If you + change $(destdir) after building the source, you will need to: + + make clean + + 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 and + move on to the application that resides in these directories, + namely, the source to a development environment. + + +SPECIFICS +--------- + + The GNU Development Tools can be built on a wide variety of hosts. + So, of course, they must be configured. Like the last example, + + configure sun4 +destdir=/local + configure sun3 +destdir=/local + + will configure the source to be built in subdirectories, in order + to keep the intermediate pieces separate, and to be installed in + /local. + + When built with suitable development environments, these will be + native tools. We'll explain the term "native" later. + + +BUILDING DEVELOPMENT ENVIRONMENTS +--------------------------------- + + The Cygnus Support GNU development tools can not only be built + with 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 "target". That is, the word + "target" refers to the development environment produced by + compiling this source and installing the resulting programs. + + For the Cygnus Support 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 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 $(destdir). + + configure sun4 +destdir=/local +target=sun3 + configure sun3 +destdir=/local +target=sun4 + + 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 /local. The second is also + intended to be build in a sun4 environment, in subdirectories, to + be installed in /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. + + +A WALK THROUGH +-------------- + +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. + + The resulting desk calculator program is referred to as a "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 "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 "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 "native" build. + + configure sun4 + + 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 GNU Development Tools is a + very common activity and the resulting development environment is + very popular. + + make all + + will build the tools as configured and will assume that you want + to use the native development environment that came with your + machine. + + Using a development environment to build a development environment + is called "bootstrapping". The Cygnus Support release of the 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 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 GNU tools + better than using other tools. + + While you're at it, if the GNU tools produce better programs, maybe + you should use them to build the GNU tools. It's a good idea, so + let's pretend that you do. Let's call the new development + environment stage2. + + 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 GNU tools have built. You really don't yet know if these + tools work. Do you have any programs built with the 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 GNU tools themselves. In fact, if you + use stage2 to build the GNU tools again the resulting programs + should be identical to stage2. Let's pretend that you do and call + the new development environment stage3. + + You've just completed what's called a "three stage boot". You now + have a small, fast, somewhat tested, development environment. + + make bootstrap + + will do a three stage boot across all tools and will compare + stage2 to stage3 and complain if they are not identical. + + Once built, + + make install + + will install the development environment in the default location + or in $(destdir) if you specified an alternate when you + configured. In fact, you can skip the "make all" part and just + "make install" which will make sure that the development + environment is built before attempting to install anything. Even + better, for configurations where host is the same as target, like + this one, "make install" will make sure that a "make bootstrap" is + done before installing anything. + + Any development environment that is not a native development + environment is refered to as a "cross" development environment. + There are many different types of cross development environments + but most fall into one of FIXME basic categories. + + +Emulation Environments: + + The first category of cross development environment is called + "emulation". There are two primary types of emulation, but both + types result in programs that run on the native host. + + The first type is "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 "software emulator". + + The GNU Development Tools do not currently include any software + emulators. Some do exist and the 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 concept of universes in operating systems + and hosted operating systems are two such development + environments. + + The Cygnus Support Release of the GNU Development Tools can be + configured for one such emulation at this time. + + configure sun4 +ansi + + 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 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 GNU + tools is not strictly conforming ANSI source so this configuration + cannot be used to bootstrap the GNU tools. + + +Simple Cross Environments: + + configure sun4 +target=a29k + + 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 a sun3. 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 + presents an a29k development environment that builds programs + intended to run on an a29k. But, remember, gcc-a29k runs on your + sun4. + + Building gcc-a29k is also a bootstrap but of a slightly different + sort. We call gcc-a29k a simple cross environment and using + gcc-a29k to build a program intended for a29k is called "crossing + to" a29k. Simple cross environments are the second category of + cross development environments. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + if configured for host sun4 and target sun4, this implies that we + will compile on a sun4 to create a sun4 compilation environment. + If configured for host sun3 and target a29k, this implies that we + will compile on a sun3 to create an a29k compilation environment. + + Host sun3 only implies that the source will be compiled on a sun3. + In fact, it need not be actually compiled on a sun3. If the + appropriate native development tools, header files, libraries, and + operating system support were available on a foobox, then source + configured for a sun3 could be compiled on a foobox, resulting in + a development environment for, using the previous example + host+target pair, "a29k" on the foobox. Similarly, if the + appropriate cross development tools, header files, and libraries + were available on a dec3100, then source configured for host sun3 + could be cross compiled to create an a29k development environment + intended to be run on a sun3. Usage: