+++ /dev/null
- On Configuring Development Tools
-
- K. Richard Pixley
- Cygnus Support
-
- Last Mod Tue Oct 1 21:20:21 PDT 1991, by rich@cygnus.com
-
-INTRO
------
-
- 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. Eventually, FIXME, there
- will also be a man page for "configure", an "info" tree, etc.
-
-
-BASICS
-------
-
-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
- 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.
-
- 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 +subdirs +notation=postfix
- ./configure sun3 +subdirs +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 "+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
- '+' 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 "+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 /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.
-
- 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 intended
- to be built in a sun3 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 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.
-
- 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.
-
-
-Crossing Into Targets:
-
- ./configure a29k +target=a29k
-
- 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.
-
- 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 "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. "Crossing into" has been introduced here not because it
- is a type of cross development environment, but because it is
- frequently confused one. The process is "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.
-
-
-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 "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.
-
- ./configure a29k +target=sun3
-
- 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.
-
- 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 "three party cross".
-
-
-FINAL NOTES
------------
-
-By "configures", I mean that links, Makefile, .gdbinit, and
-config.status are built. Configuration is always done from the source
-directory.
-
-* "./configure name" configures this directory, perhaps recursively,
- for a single host+target pair where the host and target are both
- "name". If a previous configuration existed, it will be
- overwritten.
-
-* "./configure hostname +target=targetname" configures this directory,
- perhaps recursively, for a single host+target pair where the host is
- hostname and target is targetname. If a previous configuration
- existed, it will be overwritten.
-
-* "./configure +subdirs hostname +target=targetname" creates a
- subdirectories H-hostname and H-hostname/T-targetname and
- configures H-hostname/T-targetname. For now, makes should
- be done from H-hostname/T-targetname. "./configure +sub name"
- works as expected. That is, it creates H-name and
- H-name/T-name and configures the latter.
-
-
-Hacking configurations:
-
-The configure scripts essentially do three things, create
-subdirectories if appropriate, build a Makefile, and create links to
-files, all based on and tailored to, a specific host+target pair. The
-scripts also create a .gdbinit if appropriate but this is not
-tailored.
-
-The Makefile is created by prepending some variable definitions to a
-Makefile template called 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. If fragments
-
-* 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 ./config/hmake-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 ./config/tmake-target
- if it exists. Changes intended to be permanent for the directory
- should be made in Makefile.in. To propogate changes to any of
- these, either use "make Makefile" or re-configure from the source
- directory.
-
-* configure can be edited directly, but those changes will eventually
- be lost. Changes intended to be permanent for a specific directory
- should be made to configure.in. Changes intended to be permanent
- for all configure scripts should be made to configure.template.
- Propogating changes to configure.in requires the presence of
- configure.template which normally resides in the uppermost directory
- you received. To propogate changes to either configure.template or
- a configure.in, use "configure +template=pathtothetemplate".
- This will configure the configure scripts themselves, recursively if
- appropriate.
-
-* "./configure -srcdir=foo" is not supported yet. At the moment, things
- will probably be configured correctly only for leaf directories, and
- even they will not have paths to libraries set properly.
+++ /dev/null
- On Configuring Development Tools
-
- K. Richard Pixley
- Cygnus Support
-
- Last Mod Tue Oct 1 21:20:21 PDT 1991, by rich@cygnus.com
-
-INTRO
------
-
- 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. Eventually, FIXME, there
- will also be a man page for "configure", an "info" tree, etc.
-
-
-BASICS
-------
-
-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
- 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.
-
- 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 +subdirs +notation=postfix
- ./configure sun3 +subdirs +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 "+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
- '+' 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 "+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 /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.
-
- 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 intended
- to be built in a sun3 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 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.
-
- 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.
-
-
-Crossing Into Targets:
-
- ./configure a29k +target=a29k
-
- 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.
-
- 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 "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. "Crossing into" has been introduced here not because it
- is a type of cross development environment, but because it is
- frequently confused one. The process is "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.
-
-
-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 "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.
-
- ./configure a29k +target=sun3
-
- 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.
-
- 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 "three party cross".
-
-
-FINAL NOTES
------------
-
-By "configures", I mean that links, Makefile, .gdbinit, and
-config.status are built. Configuration is always done from the source
-directory.
-
-* "./configure name" configures this directory, perhaps recursively,
- for a single host+target pair where the host and target are both
- "name". If a previous configuration existed, it will be
- overwritten.
-
-* "./configure hostname +target=targetname" configures this directory,
- perhaps recursively, for a single host+target pair where the host is
- hostname and target is targetname. If a previous configuration
- existed, it will be overwritten.
-
-* "./configure +subdirs hostname +target=targetname" creates a
- subdirectories H-hostname and H-hostname/T-targetname and
- configures H-hostname/T-targetname. For now, makes should
- be done from H-hostname/T-targetname. "./configure +sub name"
- works as expected. That is, it creates H-name and
- H-name/T-name and configures the latter.
-
-
-Hacking configurations:
-
-The configure scripts essentially do three things, create
-subdirectories if appropriate, build a Makefile, and create links to
-files, all based on and tailored to, a specific host+target pair. The
-scripts also create a .gdbinit if appropriate but this is not
-tailored.
-
-The Makefile is created by prepending some variable definitions to a
-Makefile template called 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. If fragments
-
-* 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 ./config/hmake-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 ./config/tmake-target
- if it exists. Changes intended to be permanent for the directory
- should be made in Makefile.in. To propogate changes to any of
- these, either use "make Makefile" or re-configure from the source
- directory.
-
-* configure can be edited directly, but those changes will eventually
- be lost. Changes intended to be permanent for a specific directory
- should be made to configure.in. Changes intended to be permanent
- for all configure scripts should be made to configure.template.
- Propogating changes to configure.in requires the presence of
- configure.template which normally resides in the uppermost directory
- you received. To propogate changes to either configure.template or
- a configure.in, use "configure +template=pathtothetemplate".
- This will configure the configure scripts themselves, recursively if
- appropriate.
-
-* "./configure -srcdir=foo" is not supported yet. At the moment, things
- will probably be configured correctly only for leaf directories, and
- even they will not have paths to libraries set properly.
+++ /dev/null
-\input texinfo @c -*-para-*-
-@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 Cygnus Support release of the @sc{gnu} Development
-Tools. It also discusses common usage..
-
-Copyright 1991, 1992 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by 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 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by 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 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
-
- --- 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 -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, the intermediate pieces
-used in the build process must be kept separate.
-
-@example
-mkdir ../objdir.sun4
-(cd ../objdir.sun4 ; ./configure sun4 -notation=postfix -srcdir=../src)
-mkdir ../objdir.sun3
-(cd ../objdir.sun3 ; ./configure sun3 -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{-} 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{-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}.
-
-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
-* 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 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 @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. 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, 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 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 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:
+++ /dev/null
-#!/bin/sh
-# Configuration validation subroutine script, version 1.0.
-# Copyright (C) 1991 Free Software Foundation, Inc.
-
-#This file is free software; you can redistribute it and/or modify
-#it under the terms of the GNU General Public License as published by
-#the Free Software Foundation; either version 2 of the License, or
-#(at your option) any later version.
-
-#This program is distributed in the hope that it will be useful,
-#but WITHOUT ANY WARRANTY; without even the implied warranty of
-#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-#GNU General Public License for more details.
-
-#You should have received a copy of the GNU General Public License
-#along with this program; if not, write to the Free Software
-#Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-
-
-# Configuration subroutine to validate and canonicalize a configuration type.
-# Supply the specified configuration type as an argument.
-# If it is invalid, we print an error message on stderr and exit with code 1.
-# Otherwise, we print the canonical config type on stdout and succeed.
-
-# This file is supposed to be the same for all GNU packages
-# and recognize all the CPU types, system types and aliases
-# that are meaningful with *any* GNU software.
-# Each package is responsible for reporting which valid configurations
-# it does not support. The user should be able to distinguish
-# a failure to support a valid configuration from a meaningless
-# configuration.
-
-# The goal of this file is to map all the various variations of a given
-# machine specification into a single specification in the form:
-# CPU_TYPE-MANUFACTURER-OPERATING_SYSTEM
-# it is wrong to echo any other type of specification
-
-# First pass through any local machine types.
-case $1 in
- *local*)
- echo $1
- exit 0
- ;;
- *)
- ;;
-esac
-
-# Separate what the user gave into CPU-COMPANY and OS (if any).
-basic_machine=`echo $1 | sed 's/-[^-]*$//'`
-if [ $basic_machine != $1 ]
-then os=`echo $1 | sed 's/.*-/-/'`
-else os=; fi
-
-# Lets recognize common machines as not being OS so that things like
-# config.subr decstation-3100 as legal.
-case $os in
- -dec* | -mips* | -sequent* | -encore* | -pc532* | -sgi* | -sony* | \
- -att* | -7300* | -3300* | -delta* | -motorola* | -sun[234]* | \
- -unicom* | -ibm* | -next* | -hp | -isi* | -apollo | -altos* | \
- -convergent* | -ncr* | -news | -32* | -3600* | -3100* | -osf* | \
- -c[123]* | -convex* | -sun | -crds | -omron* | -dg | -ultra | -tti* | \
- -harris)
- os=
- basic_machine=$1
- ;;
- -sco*)
- os=-scosysv322
- basic_machine=i386-unknown
- ;;
- -isc*)
- os=-iscsysv
- basic_machine=i386-unknown
- ;;
-# start-sanitize-v9
- -32)
- basic_machine=sparc64-hal
- os=-hal32
- ;;
- -64)
- basic_machine=sparc64-hal
- os=-hal64
- ;;
- -v7)
- basic_machine=sparc64-hal
- os=-v7
- ;;
-# end-sanitize-v9
-esac
-
-# Decode aliases for certain CPU-COMPANY combinations.
-case $basic_machine in
- # Recognize the basic CPU types with without company name.
- tahoe | i386 | i860 | m68k | m68000 | m88k | ns32k | arm | pyramid \
- | tron | a29k | 580 | i960 | h8300)
- basic_machine=$basic_machine-unknown
- ;;
- # Recognize the basic CPU types with with company name.
- vax-* | tahoe-* | i386-* | i860-* | m68k-* | m68000-* | m88k-* \
- | sparc-* | ns32k-* | alliant-* | arm-* | c[123]* \
- | mips-* | pyramid-* | tron-* | a29k-* | romp-* | rs6000-* \
- | none-* | 580-* | cray2-* | h8300-* | i960-* | xmp-* | ymp-* \
- | hppa-*)
- ;;
- # Recognize the various machine names and aliases which stand
- # for a CPU type and a company and sometimes even an OS.
-# start-sanitize-life
- life-*) ;;
- life)
- basic_machine=life-philips
- os=-none
- ;;
-# end-sanitize-life
-
-# start-sanitize-v9
- sparc64-*) ;;
- hal-32 | hal32)
- basic_machine=sparc64-hal
- os=-hal32
- ;;
- hal-64 | hal64)
- basic_machine=sparc64-hal
- os=-hal64
- ;;
- sparc64)
- basic_machine=sparc64-sun
- os=-v9
- ;;
- sparc64-v7 | sparc64v7)
- basic_machine=sparc64-sun
- os=-v7
- ;;
-# end-sanitize-v9
-
- vaxv)
- basic_machine=vax-dec
- os=-sysv
- ;;
- vms)
- basic_machine=vax-dec
- os=-vms
- ;;
- i386v32)
- basic_machine=i386-unknown
- os=-sysv32
- ;;
- i386-sco* | i386sco | sco)
- basic_machine=i386-unknown
- os=-scosysv322
- ;;
- i386-isc* | isc)
- basic_machine=i386-unknown
- os=-iscsysv
- ;;
- i386v4*)
- basic_machine=i386-unknown
- os=-sysv4
- ;;
- i386v)
- basic_machine=i386-unknown
- os=-sysv
- ;;
- spur)
- basic_machine=spur-unknown
- ;;
- alliant)
- basic_machine=alliant-alliant
- ;;
- convex-c1)
- basic_machine=c1-convex
- os=-sysv
- ;;
- convex-c2)
- basic_machine=c2-convex
- os=-sysv
- ;;
- convex-c32)
- basic_machine=c32-convex
- os=-sysv
- ;;
- convex-c34)
- basic_machine=c34-convex
- os=-sysv
- ;;
- convex-c38)
- basic_machine=c38-convex
- os=-sysv
- ;;
- m88k-omron*)
- basic_machine=m88k-omron
- ;;
- merlin)
- basic_machine=ns32k-utek
- os=-sysv
- ;;
- crds | unos)
- basic_machine=m68k-crds
- ;;
- encore | umax | mmax)
- basic_machine=ns32k-encore
- os=-sysv
- ;;
- genix)
- basic_machine=ns32k-ns
- ;;
- iris | iris4d)
- basic_machine=mips-sgi
- os=-irix
- ;;
- news | news700 | news800 | news900)
- basic_machine=m68k-sony
- os=-newsos
- ;;
- 3b1 | 7300 | 7300-att | att-7300 | pc7300 | safari | unixpc)
- basic_machine=m68k-att
- ;;
- delta | 3300 | motorola-3300 | motorola-delta \
- | 3300-motorola | delta-motorola)
- basic_machine=m68k-motorola
- ;;
- balance)
- basic_machine=ns32k-sequent
- os=-dynix
- ;;
- pc532)
- basic_machine=ns32k-pc532
- ;;
- symmetry)
- basic_machine=i386-sequent
- os=-dynix
- ;;
- sun2)
- basic_machine=m68000-sun
- ;;
- sun2os3)
- basic_machine=m68000-sun
- os=-sunos3
- ;;
- sun2os4)
- basic_machine=m68000-sun
- os=-sunos4
- ;;
- sun3os3)
- basic_machine=m68k-sun
- os=-sunos3
- ;;
- sun3os4)
- basic_machine=m68k-sun
- os=-sunos4
- ;;
- sun4os3)
- basic_machine=sparc-sun
- os=-sunos3
- ;;
- sun4os4)
- basic_machine=sparc-sun
- os=-sunos4
- ;;
- sun3)
- basic_machine=m68k-sun
- ;;
- sun4)
- basic_machine=sparc-sun
- ;;
- pbd)
- basic_machine=sparc-unicom
- ;;
- sun386 | sun386i | roadrunner)
- basic_machine=i386-sun
- ;;
- ps2)
- basic_machine=i386-ibm
- ;;
- next)
- basic_machine=m68k-next
- os=-sysv
- ;;
- hp9k3[2-9][0-9])
- basic_machine=m68k-hp
- ;;
- hp9k31[0-9] | hp9k2[0-9][0-9])
- basic_machine=m68000-hp
- ;;
- hp9k8[0-9][0-9] | hp9k7[0-9][0-9] | hp8[0-9][0-9] | hp7[0-9][0-9])
- basic_machine=hp800-hp
- ;;
- isi68 | isi)
- basic_machine=m68k-isi
- os=-sysv
- ;;
- apollo68)
- basic_machine=m68k-apollo
- os=-sysv
- ;;
- altos | altos3068)
- basic_machine=m68k-altos
- ;;
- miniframe)
- basic_machine=m68000-convergent
- ;;
- tower | tower-32)
- basic_machine=m68k-ncr
- ;;
- news-3600 | risc-news)
- basic_machine=mips-sony
- os=-newsos
- ;;
- decstation-dec | decstation | decstation-3100 | pmax | pmin | dec3100 | decstatn)
- basic_machine=mips-dec
- ;;
- magnum | m3230)
- basic_machine=mips-mips
- os=-sysv
- ;;
- gmicro)
- basic_machine=tron-gmicro
- os=-sysv
- ;;
- rtpc | rtpc-*)
- basic_machine=romp-ibm
- ;;
- am29k)
- basic_machine=a29k-none
- os=-bsd
- ;;
- amdahl)
- basic_machine=580-amdahl
- os=-sysv
- ;;
- amigados)
- basic_machine=m68k-cbm
- os=-amigados
- ;;
- amigaunix | amix)
- basic_machine=m68k-cbm
- os=-sysv4
- ;;
- cray | ymp)
- basic_machine=ymp-cray
- os=-unicos
- ;;
- cray2)
- basic_machine=cray2-cray
- os=-unicos
- ;;
- xmp)
- basic_machine=xmp-cray
- os=-unicos
- ;;
- delta88)
- basic_machine=m88k-motorola
- os=-m88kbcs
- ;;
- dpx2)
- basic_machine=m68k-bull
- os=-sysv
- ;;
- ebmon29k)
- basic_machine=a29k-amd
- os=-ebmon
- ;;
- h8300hds)
- basic_machine=h8300-hitachi
- os=-hds
- ;;
- harris)
- basic_machine=m88k-harris
- os=-m88kbcs
- ;;
- hp300bsd)
- basic_machine=m68k-hp
- os=-bsd
- ;;
- hp300hpux)
- basic_machine=m68k-hp
- os=-hpux
- ;;
- hp9k2[0-9][0-9] | hp9k31[0-9])
- basic_machine=m68000-hp
- os=-hpux
- ;;
- hp9k3[2-9][0-9])
- basic_machine=m68k-hp
- os=-hpux
- ;;
- ncr3000)
- basic_machine=i386-ncr
- os=-sysv4
- ;;
- news1000)
- basic_machine=m68030-sony
- os=-newsos
- ;;
- nindy960)
- basic_machine=i960-intel
- os=-nindy
- ;;
- pn)
- basic_machine=pn-gould
- os=-sysv
- ;;
- np1)
- basic_machine=np1-gould
- os=-sysv
- ;;
- ultra3)
- basic_machine=a29k-nyu
-# Is sym1 really a different system, or is it really sysv?
-# os=-sym1
- ;;
- vxworks960)
- basic_machine=i960-wrs
- os=-vxworks
- ;;
- vxworks68)
- basic_machine=m68k-wrs
- os=-vxworks
- ;;
- none)
- basic_machine=none-none
- os=-none
- ;;
-
-# Here we handle the default manufacturer of certain CPU types. It is in
-# some cases the only manufacturer, in others, it is the most popular.
- mips)
- basic_machine=mips-mips
- ;;
- romp)
- basic_machine=romp-ibm
- ;;
- rs6000)
- basic_machine=rs6000-ibm
- ;;
- vax)
- basic_machine=vax-dec
- ;;
- sparc)
- basic_machine=sparc-sun
- ;;
- *)
- echo Invalid configuration \`$1\': machine \`$basic_machine\' not recognized 1>&2
- exit 1
- ;;
-esac
-
-# Decode manufacturer-specific aliases for certain operating systems.
-
-if [ "$os" ]
-then
-case $os in
- # First accept the basic system types.
- # The portable systems comes first.
- # Each alternative must end in a *, to match a version number.
- -bsd* | -sysv* | -mach* | -minix* | -genix* | -ultrix* \
- | -vms* | -sco* | -esix* | -isc* | -aix* | -sunos* | -hpux* \
- | -unos* | -osf* | -v88r* | -luna* | -dgux* | -solari* \
- | -amigados* | -msdos* \
- | -nindy* | -vxworks* | -ebmon* | -hds* | -m88kbcs*)
- ;;
-# start-sanitize-v9
- -v7 | -v9 | -hal32 | -hal64) ;;
-# end-sanitize-v9
-
- -newsos*)
- os=-bsd
- ;;
- -osfrose*)
- os=-osf
- ;;
- -osf*)
- os=-bsd
- ;;
- -dynix*)
- os=-bsd
- ;;
- -aos*)
- os=-bsd
- ;;
- -ctix* | -irix* | -uts*)
- os=-sysv
- ;;
- *)
- # Get rid of the `-' at the beginning of $os.
- os=`echo $1 | sed 's/[^-]*-//'`
- echo Invalid configuration \`$1\': system \`$os\' not recognized 1>&2
- exit 1
- ;;
-esac
-else
-
-# Here we handle the default operating systems that come with various machines.
-# The value should be what the vendor currently ships out the door with their
-# machine or put another way, the most popular os provided with the machine.
-case $basic_machine in
- *-dec | vax-*)
- os=-ultrix42
- ;;
- i386-sun)
- os=-sunos402
- ;;
- m68000-sun)
- os=-sunos3
- # This also exists in the configure program, but was not the
- # default.
- # os=-sunos4
- ;;
- sparc-* | *-sun)
- os=-sunos411
- ;;
- romp-*)
- os=-bsd
- ;;
- *-ibm)
- os=-aix
- ;;
- *-hp)
- os=-hpux
- ;;
- *-sgi | i860-* | *-att | *-ncr | *-altos | *-motorola | *-convergent)
- os=-sysv
- ;;
- *-dg)
- os=-dgux
- ;;
- m88k-omron*)
- os=-luna
- ;;
- *-crds)
- os=-unos
- ;;
- *-ns)
- os=-genix
- ;;
- i386-*)
- os=-scosysv322
- ;;
- *)
- os=-none
- ;;
-esac
-fi
-
-# Here we handle the case where we know the os, and the CPU type, but not the
-# manufacturer. We pick the logical manufacturer.
-vendor=unknown
-case $basic_machine in
- *-unknown)
- case $os in
- -sunos*)
- vendor=sun
- ;;
- -aix*)
- vendor=ibm
- ;;
- -hpux*)
- vendor=hp
- ;;
- -unos*)
- vendor=crds
- ;;
- -dgux*)
- vendor=dg
- ;;
- -luna*)
- vendor=omron
- ;;
- -genix*)
- vendor=ns
- ;;
- esac
- basic_machine=`echo $basic_machine | sed "s/unknown/$vendor/"`
- ;;
-esac
-
-echo $basic_machine$os
+++ /dev/null
-@echo off
-cd bfd
-call configdj
-cd ..\binutils
-call configdj
-cd ..\bison
-call configdj
-cd ..\gas
-call configdj
-cd ..\gcc
-call configdj
-cd ..\libiberty
-call configdj
-cd ..
+++ /dev/null
-.\" -*- nroff -*-
-.\" Copyright 1991, 1992 Free Software Foundation, Inc.
-.\" written by K. Richard Pixley
-.TH configure 1 "13 December 1991" "cygnus support" "Cygnus Support"
-.de BP
-.sp
-.ti \-.2i
-\(**
-..
-
-.SH NAME
-configure \(em\& prepare source code to be built
-
-.SH SYNOPSIS
-configure host1 [host2 [host3 ...]] [-exec_prefix=dir] [-gas] [-help]
-[-host=h] [-nfp] [-norecursion]
-[-prefix=dir] [-s] [-rm] [-site=s] [-srcdir=dir]
-[-target=t] [-v] [-x]
-
-.SH DESCRIPTION
-.I Configure
-is a program used to prepare souce code to be built. It does this by
-generating Makefiles and .gdbinit files, creating symlinks, digging
-directories, and some other miscellaneous file editting.
-
-.SH OPTIONS
-.I Configure
-accepts the following options:
-
-.TP
-.I \-exec_prefix=dir
-sets the root directory for host dependent files to
-.I dir.
-The default location is the same as
-.I prefix.
-
-.TP
-.I \-gas
-tells configure that the GNU assembler is available on this machine
-even if it is not ordinarily.
-
-.TP
-.I \-help
-displays a brief summary of the calling convention.
-
-.TP
-.I \-host=h
-asks configure to prepare the source to be compiled in an environment
-called
-.I h.
-This option is very confusing and is best ignored. FIXME: I don't
-think it should even be documented.
-
-.TP
-.I \-nfp
-Notifies configure that all of the specified hosts have
-.I no floating point
-units.
-
-.TP
-.I \-norecursion
-asks that only the current directory be configured. Normally
-configure recurs on subdirectories.
-
-.TP
-.I \-prefix=dir
-sets the default location in which to install files to dir. The
-default is "/usr/local".
-
-.TP
-.I \-s
-used internally by configure to supress status messages on
-subdirectory recursions.
-
-.TP
-.I \-rm
-asks configure to remove a configuration rather than creating one.
-
-.TP
-.I \-site=s
-asks configure to use any site specific Makefile fragments for s when
-building Makefiles.
-
-.TP
-.I \-srcdir=dir
-tells configure to find the source in srcdir.
-
-.TP
-.I \-target=t
-Requests that the sources be configured to target the t machine. If
-no targets are specified explicitly, the target is assumed to be the
-same as the host.
-
-.TP
-.I \-tmpdir=dir
-Sets the directory in which configure creates temporary files to
-tmpdir.
-
-.TP
-.I \-verbose
-.I \-v
-Asks that configure print status lines for each directory configured.
-Normally, only the status lines for the current directory are printed.
-
-.TP
-.I \-x
-Tells configure that MIT style X11 header files and libraries are
-available on this machine, even if they are not normally available.
-
-.SH FILES
-configure.in for each directory's individual needs
-config.sub for parsing configuration names
-
-.SH "SEE ALSO"
-.RB "`\|" configure "\|'"
-entry in
-.B
-info. (not yet available).
+++ /dev/null
-\input texinfo @c -*-para-*-
-@c %**start of header
-@setfilename configure.info
-@settitle Cygnus Configure
-@c %**end of header
-@synindex ky cp
-@tex
-\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
-\xdef\manvers{\$Revision$} % For use in headers, footers too
-@end tex
-@setchapternewpage off
-
-@ifinfo
-@format
-START-INFO-DIR-ENTRY
-* configure: (configure). Cygnus configure.
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
-
-@ifinfo
-This document attempts to describe the Cygnus Support version of
-@code{configure}.
-
-Copyright 1991, 1992 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by Cygnus Support.
-@end ifinfo
-
-@titlepage
-@sp 10
-@title{Cygnus Configure}
-@subtitle @manvers, for Cygnus Configure version 1.84
-@author{K. Richard Pixley, @code{rich@@cygnus.com}}
-@author{Cygnus Support}
-@page
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 1992 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by Cygnus Support.
-@end titlepage
-
-@ifinfo
-
-@node top, What Configure Does, (dir), (dir)
-@top top
-
-This file documents the configuration system used and distributed by
-Cygnus Support.
-
-@menu
-* What Configure Does:: What Configure Does
-* Invoking:: Invoking
-* Using Configure:: Using Configure
-* Porting:: Porting with Configure
-* Reference:: Gory details described
-* Known Bugs:: Known Bugs
-* Variables Index:: Variable Index
-* Concept Index:: Concept Index
-
- --- The Detailed Node Listing ---
-
-Using Configure
-
-* Install Locations:: Where to install things once they are built
-* Build Directories:: Where to build object files
-* Host:: Telling @code{configure} what will source will
- be built
-* Target:: Telling @code{configure} what the source will
- target
-* Local Conventions:: Adding information about local conventions
-
-Install Locations
-
-* prefix:: Changing the default install directory
-* exec_prefix:: How to separate host independent files
- from host dependent files when
- installing for multiple hosts
-* Install Details:: Full descriptions of all installation
- subdirectories
-
-Porting with Configure
-
-* Programs:: Adding configure to new programs
-* Hosts and Targets:: Adding hosts and targets
-* Sites:: Adding site info
-
-Gory details described
-
-* Makefile Extensions:: Extensions to the @sc{gnu} coding standards
-* configure.in:: The format of the configure.in file
-* config.status:: config.status
-* Makefile Fragments:: Makefile Fragments
-
-The format of the @file{configure.in} file
-
-* Minimal:: A minimal configure.in
-* Configure Variables:: Variables available to configure.in
-* Declarations:: For each invocation
-* Per-host:: For each host
-* Per-target:: For each target
-* Post-target:: After each target
-* Example:: An example configure.in
-@end menu
-
-@end ifinfo
-
-@node What Configure Does, Invoking, top, top
-@chapter What Configure Does
-
-@code{configure} prepares source directories for building working
-programs. A program cannot be built until its source has been
-configured. When configure runs, it does the following things.
-
-@table @emph
-@item Create build directories
-(see @ref{Build Directories}). When you run @code{configure} with the
-@code{-srcdir=} option, it uses the current directory as build
-directory, creating under it a directory tree that parallels the
-directory structure under the source directory. (See @ref{Invoking}).
-
-@item Generate makefiles
-A makefile template from the source directory, usually called
-@file{Makefile.in}, is copied to an output file in the build directory.
-The output file is usually named @file{Makefile}. @code{configure}
-places definitions for a number of standard makefile macros at the
-beginning of the output file. If @code{-prefix=} or @code{-exec_prefix}
-were specified on the @code{configure} command line, corresponding
-makefile variables are set accordingly. If host, target, or site
-specific makefile fragments exist, these are inserted into the output
-file. (See @ref{Makefiles, , , make, Makefiles}.)
-
-@item Generate @file{.gdbinit} If the source directory contains a
-@file{.gdbinit} file and the build directory is not the same as the
-source directory, a @file{.gdbinit} file is created in the build
-directory. This @file{.gdbinit} file contains @code{dir} commands and
-a @code{source} command, which will cause the @file{.gdbinit} file from
-the source directory to be read by GDB, and will allow GDB to find
-source files in either the source directory or the build directory.
-(see @ref{Command Files, , , gdb, Command Files}.)
-
-@item Make symbolic links
-Most directories have some symbolic links with generic names built
-pointing to specific files in the source directory. If the system where
-@code{configure} runs cannot support symbolic links, hard links are used
-instead.
-
-@item Miscellaneous
-If the source directory has special needs, they are handled by shell
-script fragments stored with the source. Usually there are no special
-needs, but sometimes they involve changes to the output makefile.
-
-@item Generate @file{config.status}
-@code{configure} creates a shell script named @file{config.status} in
-the build directory. This shell script, when run from the build
-directory, will reconfigure the build directory (but not its
-subdirectories). This is most often used to have a @code{Makefile} update
-itself automatically if a new source directory is available.
-
-@item Recursion
-If the source directory has subdirectories that should also be
-configured, @code{configure} is called for each.
-@end table
-
-@node Invoking, Using Configure, What Configure Does, top
-@chapter Invoking
-
-The usual way to invoke @code{configure} is as follows:
-@example
-configure @var{host}
-@end example
-This prepares the source to be compiled in a
-@var{host} environment with programs and files to be installed in
-@file{/usr/local}.
-
-@code{configure} prepares the source as you specify by selecting and
-using script and Makefile fragments prepared in advance, and stored with
-the source. @code{configure}'s command line options also allow you to
-specify other aspects of the source configuration:
-
-@table @code
-@item -exec_prefix=@var{dir}
-Configure the source to install host dependent files in @var{dir}.
-
-This option sets the @code{configure} variable @code{exec_prefix}.
-Generated Makefiles will have their @code{exec_prefix} variables set to
-this value. (See @ref{Install Details}.)
-
-@item -gas
-Configure to use the @sc{GNU} assembler.
-
-@item -help
-Display a quick summary of how to invoke @code{configure}.
-
-@item -host=@var{host}
-FIXME-soon: I don't think this option should be documented.
-@c Then why does it exist? /Pesch 7jan92
-
-@item -nfp
-@emph{No floating point} unit available on the target; configure to
-avoid dependencies on hardware floating point.
-
-@item -norecursion
-Configure only this directory; ignore any subdirectories. This is used
-by the executable shell script @file{config.status} to reconfigure the
-current directory. (see @ref{config.status}).
-
-@item -prefix=@var{dir}
-Configure the source to install programs and files under directory
-@file{@var{dir}}.
-
-This option sets the @code{configure} variable @code{prefix}. Generated
-Makefiles will have their @code{prefix} variables set to this value.
-(See @ref{Install Details}.)
-
-@item -program_prefix=@var{string}
-Configure the source to install certain programs using @var{string} as a
-prefix. This applies to programs which might be used for cross-compilation,
-such as the compiler and the binutils, and also to programs which have the same
-name as a common Unix program, such as make.
-
-This option sets the @code{configure} variable @code{program_prefix}.
-Generated Makefiles will have their @code{program_prefix} variables set to this
-value. (See @ref{Install Details}.)
-
-@item -program_suffix=@var{string}
-Configure the source to install certain programs using @var{string} as a
-suffix. This applies to programs which might be used for cross-compilation.
-
-@item -program_transform_name=@var{sed-pattern}
-Configure the source to install certain programs using the names that result
-from passing the usual name through @code{sed} invoked with @var{sed-pattern}.
-This option may be given multiple times; each @var{sed-pattern} will be applied
-in turn. This applies to programs which might be used for cross-compilation.
-
-This option sets the @code{configure} variable @code{program_transform_name}.
-Generated Makefiles will have their @code{program_transform_name} variables set
-to this value. (See @ref{Install Details}.)
-
-@item -recurring
-@c Wouldn't it make more sense to call this "-quiet"? (FIXME).
-This option is used internally by @code{configure} when recurring on
-subdirectories. Its sole purpose is to suppress status output. You can
-override this effect with the @code{-verbose} option.
-
-@item -rm
-@emph{Remove} the configuration specified by @var{host} and the other
-command-line options, rather than creating it.
-
-@item -site=@var{site}
-Generate Makefiles using site specific Makefile fragments for
-@var{site}. See also @ref{Sites}.
-
-@item -srcdir=@var{_dir}
-Build Makefiles to use the sources located in directory @file{@var{dir}}. The
-build directory is assumed to be @file{.}.
-
-@item -target=@var{target}
-Requests that the sources be configured to target the @var{target}
-machine. If no target is specified explicitly, the target is assumed
-to be the same as the host.
-
-@item -tmpdir=@var{tmpdir}
-Use the directory @var{tmpdir} for @code{configure}'s temporary files.
-The default is the value of the environment variable TMPDIR, or
-@file{/tmp} if the environment variable is not set.
-
-@item -verbose
-@itemx -v
-Print status lines for each directory configured. Normally, only the
-status lines for the initial working directory are printed.
-
-@item -x
-Use @sc{MIT} style @sc{X11} header files and libraries on the host, even
-if they are not normally available.
-@end table
-
-@node Using Configure, Porting, Invoking, top
-@chapter Using Configure
-
-The choices and options available at configuration time
-generally have valid defaults, but the defaults do not cover all cases.
-The choices available include install locations, build directories,
-host, target, and local conventions.
-
-@menu
-* Install Locations:: Where to install things once they are built
-* Build Directories:: Where to build object files
-* Host:: Telling @code{configure} what will source will
- be built
-* Target:: Telling @code{configure} what the source will
- target
-* Local Conventions:: Adding information about local conventions
-@end menu
-
-@node Install Locations, Build Directories, Using Configure, Using Configure
-@section Install Locations
-@cindex Where to install
-
-Using the default configuration, @code{make install} creates a
-single tree of files, some of which are programs. The location of this
-tree is determined by the value of the variable @code{prefix}. The
-default value of @code{prefix} is @file{/usr/local}. This is
-often correct for native tools installed on only one host.
-
-@menu
-* prefix:: Changing the default install directory
-* exec_prefix:: How to separate host independent files
- from host dependent files when
- installing for multiple hosts
-* Install Details:: Full descriptions of all installation
- subdirectories
-@end menu
-
-@node prefix, exec_prefix, Install Locations, Install Locations
-@subsection Changing the default install directory
-@cindex Changing the default install directory
-@cindex Prefix directory
-
-In the default configuration, all files are installed in subdirectories
-of @file{/usr/local}. The location is determined by the value of
-the @code{configure} variable @code{prefix}; in turn, this determines the
-value of the Makefile variable of the same name (@code{prefix}).
-
-You can also set the value of the Makefile variable @code{prefix}
-explicitly each time you invoke @code{make} if you are so inclined; but
-because many programs have this location compiled in, you must specify
-the @code{prefix} value consistently on each invocation of @code{make},
-or you will end up with a broken installation.
-
-To make this easier, the value of the @code{configure} variable
-@code{prefix} can be set on the command line to @code{configure}
-using the option @code{-prefix=}.
-
-
-@node exec_prefix, Install Details, prefix, Install Locations
-@subsection Installing for multiple hosts
-@cindex Configuring for multiple hosts
-@cindex Sharing host independent files
-@cindex The @file{exec_prefix} directory
-@cindex Installing host independent files
-
-By default, host dependent files are installed in subdirectories of
-@file{@var{exec_prefix}}. The location is determined by the value of the
-@code{configure} variable @code{exec_prefix}, which determines the value of
-the Makefile variable @code{exec_prefix}. This makes it simpler to install
-for a single host, and simplifies changing the default location for the
-install tree; but the default doesn't allow for multiple hosts to
-effectively share host independent files.
-
-To configure so that multiple hosts can share common files, use
-something like:
-
-@example
-configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
-make all info install install-info clean
-
-configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
-make all info install install-info
-@end example
-
-The first line configures the source for @var{host1} to place host
-specific programs in subdirectories of @file{/usr/gnu/H-@var{host1}}.
-
-The second line builds and installs all programs for @var{host1},
-including both host independent and host specific files.
-
-The third line reconfigures the source for @var{host2} to place host
-specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}}.
-
-The fourth line builds and installs all programs for @var{host2}. Host
-specific files are installed in new directories, but the host
-independent files are installed @emph{on top of} the host
-independent files installed for @var{host1}. This results in a single
-copy of the host independent files, suitable for use by both hosts.
-
-@node Install Details, , exec_prefix, Install Locations
-@subsection Full descriptions of all installation subdirectories
-
-During any install, a number of standard directories are created. Their
-names are determined by Makefile variables. Some of the
-defaults for Makefile variables can be changed at configure time using
-command line options to @code{configure}. For more information on the
-standard directories or the Makefile variables, please refer to
-@cite{standards.text}.
-
-Note that @code{configure} does not create the directory @code{srcdir}
-at any time. @code{srcdir} is not an installation directory.
-
-You can override all makefile variables on the command line to
-@code{make}. (See @ref{Overriding, Overriding Variables, Overriding
-Variables, make, Make}.) If you do so, you will need to specify the
-value precisely the same way for each invocation of @code{make}, or you
-risk ending up with a broken installation. This is because many
-programs have the locations of other programs or files compiled into
-them. If you find yourself overriding any of the variables frequently,
-you should consider site dependent Makefile fragments. See also
-@ref{Sites}.
-
-During @code{make install}, a number of standard directories are
-created and populated. The following Makefile variables define them.
-Those whose defaults are set by corresponding @code{configure} variables
-are marked ``Makefile and configure''.
-
-@vindex prefix
-@defvr {Makefile and configure} prefix
-The root of the installation tree. You can set
-its Makefile default with the @code{-prefix=} command line option to
-@code{configure}. (@ref{Invoking}.) The default value for
-@code{prefix} is @file{/usr/local}.
-@end defvr
-
-@vindex bindir
-@defvr Makefile bindir
-A directory for binary programs that users can run.
-The default value for @code{bindir} depends on @code{prefix};
-@code{bindir} is normally changed only indirectly through @code{prefix}.
-The default value for @code{bindir} is @file{$(prefix)/bin}.
-@end defvr
-
-@vindex exec_prefix
-@defvr {Makefile and configure} exec_prefix
-A directory for host dependent files. You can specify the Makefile
-default value by using the @code{-exec_prefix=} option to @code{configure}.
-(See also @ref{Invoking}.) The default value for @code{exec_prefix} is
-@file{$(prefix)}.
-@end defvr
-
-@vindex libdir
-@defvr Makefile libdir
-A directory for libraries and support programs. The default value for
-@code{libdir} depends on @code{prefix}; @code{libdir} is normally
-changed only indirectly through @code{prefix}. The default value for
-@code{libdir} is @file{$(prefix)/lib}.
-@end defvr
-
-@vindex mandir
-@defvr Makefile mandir
-A directory for @code{man} format documentation (``man pages''). The
-default value for @code{mandir} depends on @code{prefix};
-@code{mandir} is normally changed only indirectly through @code{prefix}.
-The default value for @code{mandir} is @file{$(prefix)/man}.
-@end defvr
-
-@vindex man@var{N}dir
-@defvr Makefile man@var{N}dir
-There are eight variables named @code{man1dir}, @code{man2dir}, etc.
-They name the specific directories for each man page section. For
-example, @code{man1dir} holds @file{emacs.1} (the man page for the emacs
-program), while @code{man5dir} holds @file{rcsfile.5} (the man page
-describing the @code{rcs} data file format). The default value for any
-of the @code{man@var{N}dir} variables depends indirectly on
-@code{prefix}, and is normally changed only through @code{prefix}. The
-default value for @code{man@var{N}dir} is
-@file{$(mandir)/man@var{N}}.
-@end defvr
-
-@vindex manext
-@defvr Makefile manext
-@emph{Not supported by @code{configure}}. The @sc{gnu} coding standards
-do not call for @code{man1ext}, @code{man2ext}, so the intended use for
-@code{manext} is apparently not parallel to @code{mandir}. Its use is
-not clear. (See also @ref{Makefile Extensions}.)
-@end defvr
-
-@vindex infodir
-@defvr Makefile infodir
-A directory for @emph{info} format documentation. The default value for
-@code{infodir} depends indirectly on @code{prefix}; @code{infodir} is
-normally changed only through @code{prefix}. The default value for
-@code{infodir} is @file{$(prefix)/info}.
-@end defvr
-
-@vindex docdir
-@defvr Makefile docdir
-A directory for any documentation that is in a format other than those
-used by @code{info} or @code{man}. The default value for @code{docdir}
-depends indirectly on @code{prefix}; @code{docdir} is normally changed only
-through @code{prefix}. The default value for @code{docdir}
-is @file{$(datadir)/doc}. @emph{This variable is an extension to
-the @sc{gnu} coding standards}. (See also @ref{Makefile Extensions}.)
-@end defvr
-
-@vindex includedir
-@defvr Makefile includedir
-A directory for the header files accompanying the libraries installed in
-@code{libdir}. The default value for @code{includedir} depends on
-@code{prefix}; @code{includedir} is normally changed only indirectly
-through @code{prefix}. The default value for @code{includedir} is
-@file{$(prefix)/include}.
-@end defvr
-
-@node Build Directories, Host, Install Locations, Using Configure
-@section Build Directories
-@cindex Build directories
-@kindex objdir
-@cindex Object directories
-@kindex subdirs
-@cindex Building for multiple hosts
-@cindex Building for multiple targets
-
-Normally, @code{configure} builds a @file{Makefile} and symbolic links
-in the same directory as the source files. This is the typical
-@sc{un*x} way to build programs, but it has limitations. For instance,
-using this approach, you can only build for one host at a time.
-
-We refer to the directories where @code{configure} builds a
-Makefile as the @emph{build directories} or sometimes as
-@emph{objdir} because these are the directories in which @code{make}
-will build object files, among other things.
-
-The default build directory is the same as the source directory.
-You can use a different build directory with a sequence like the following:
-
-@example
-mkdir @var{builddir}
-cd @var{builddir}
-configure @var{host} -srcdir=@var{sourcedirectory}
-@end example
-
-@noindent
-where @var{builddir} is the directory where you wish to build,
-@var{host} is the host for which you want to build, and
-@var{sourcedirectory} is the directory containing the source files.
-
-If you were to do this twice with different values for @var{builddir}
-and @var{host}, then you could @code{make} for both at the same time.
-
-@node Host, Target, Build Directories, Using Configure
-@section Host
-
-The arguments to @code{configure} are @emph{hosts}. By @emph{host} we
-mean the environment in which the source will be compiled. This need
-not necessarily be the same as the physical machine involved,
-although it usually is.
-
-For example, if some obscure machine running an operating system other
-than @sc{un*x} had the @sc{gnu} @sc{posix} emulation libraries
-available, it would be possible to configure most @sc{gnu} source for a
-@sc{posix} system and build it on the obscure host.
-
-For more on this topic, see @ref{Host Environments, , Host Environments,
-cfg-paper, On Configuring Development Tools}.
-
-@node Target, Local Conventions, Host, Using Configure
-@section Target
-
-For building native development tools, or most of the other @sc{gnu}
-tools, you need not worry about the target. The @emph{target} of a
-configuration defaults to the same as the @emph{host}.
-
-For building cross development tools, please see @ref{Building
-Development Environments, , Building Development Environments,
-cfg-paper, On Configuring Development Tools}.
-
-@node Local Conventions, , Target, Using Configure
-@section Local Conventions
-
-If you find that a tool does not get configured to your liking, or if
-@code{configure}'s conventions differ from your local conventions, you
-should probably consider site specific Makefile fragments. See also
-@ref{Sites}.
-
-These are probably not the right choice for options that can be set from
-the @code{configure} command line or for differences that are host or
-target dependent.
-
-@node Porting, Reference, Using Configure, top
-@chapter Porting with Configure
-@cindex Porting
-
-This section explains how to add programs, host and target configuration
-names, and site-specific information to Cygnus configure.
-
-@menu
-* Programs:: Adding configure to new programs
-* Hosts and Targets:: Adding hosts and targets
-* Sites:: Adding site info
-@end menu
-
-
-@node Programs, Hosts and Targets, Porting, Porting
-@section Adding Configure To New Programs
-
-If you are writing a new program, you probably shouldn't worry about
-porting issues or configure until it is running reasonably on some host.
-Then refer back to this section.
-
-If the program in question currently has a configure script that meets
-the criteria set out by @cite{standards.text}, please do not add Cygnus
-configure. It should be possible to add this program without change to
-a Cygnus configure style source tree.
-
-If the program is not target dependent, please consider using
-@code{autoconf} instead of Cygnus configure. @code{autoconf} will
-be available soon from the @sc{fsf}.
-
-To add Cygnus configure to an existing program, do the following:
-
-@table @asis
-@item Make sure the Makefile conforms to @sc{gnu} standard
-The coding standard for @sc{gnu} Makefiles is described in
-@cite{standards.text}.
-
-@item Add Cygnus extensions to the Makefile
-These are described in @ref{Makefile Extensions}.
-
-@item Move host support from Makefile to fragments
-This usually involves finding sections of the Makefile that say things
-like ``uncomment these lines for host foo'' and moving them to a new
-file called @file{./config/mh-foo}. For more information, see @ref{Hosts
-and Targets}.
-
-@item Choose defaults
-If the program has compile time options that determine the way the
-program should behave, chose reasonable defaults and make these Makefile
-variables. Be sure the variables are assigned their default values
-before the @code{####} line so that site specific Makefile fragments can
-override them (@pxref{Makefile Extensions,,Extensions to the @sc{gnu}
-coding standards}).
-
-@item Locate configuration files
-If there is configuration information in header files or source files,
-separate it in such a way that the files have a generic name. Then move
-the specific instances of those files into the @file{./config}
-directory.
-
-@item Separate host and target information
-Some programs already have this information separated. If yours does
-not, you will need to separate these two kinds of configuration
-information. @dfn{Host specific} information is the information needed to
-compile the program. @dfn{Target specific} information is information on the
-format of data files that the program will read or write. This
-information should live in separate files in the @file{./config}
-directory with names that reflect the configuration for which they are
-intended.
-
-At this point you might skip this step and simply move on. If you do,
-you should end up with a program that can be configured only to build
-native tools, that is, tools for which the host system is also the
-target system. Later, you could attempt to build a cross tool and
-separate out the target specific information by figuring out what went
-wrong. This is often simpler than combing through all of the source
-code.
-
-@item Write @code{configure.in}
-Usually this involves writing shell script fragments to map from
-canonical configuration names into the names of the configuration files.
-These files will then be linked at configure time from the specific
-instances of those files in @file{./config} to file in the build
-directory with more generic names. (see also @ref{Build Directories}).
-The format of configure.in is described in @ref{configure.in}.
-
-@item Rename @file{Makefile} to @file{Makefile.in}
-@end table
-
-At this point you should have a program that can be configured using
-Cygnus @code{configure}.
-
-@node Hosts and Targets, Sites, Programs, Porting
-@section Adding hosts and targets
-
-To add a host or target to a program that already uses Cygnus
-configure, do the following.
-
-@itemize @bullet
-
-@item
-Make sure the new configuration name is represented in
-@file{config.sub}. If not, add it. For more details, see the comments
-in the shell script @file{config.sub}.
-
-@item
-If you are adding a host configuration, look in @file{configure.in}, in
-the per-host section. Make sure that your configuration name is
-represented in the mapping from host configuration names to
-configuration files. If not, add it. Also see @ref{configure.in}.
-
-@item
-If you are adding a target configuration, look in @file{configure.in},
-in the per-target section. Make sure that your configuration name is
-represented in the mapping from target configuration names to
-configuration files. If not, add it. Also see @ref{configure.in}.
-
-@item
-Look in @file{configure.in} for the variables @samp{files},
-@samp{links}, @samp{host_makefile_frag}, and
-@samp{target_makefile_frag}. The values assigned to these variables are
-the names of the configuration files, relative to @code{srcdir} that the
-program uses. Make sure that copies of the files exist for your host.
-If not, create them. See also @ref{Configure Variables}.
-@end itemize
-
-This should be enough to configure for a new host or target
-configuration name. Getting the program to compile and run properly
-remains the hard work of the port.
-
-@node Sites, , Hosts and Targets, Porting
-@section Adding site info
-
-If some of the Makefile defaults are not right for your site, you can
-build site specific Makefile fragments. To do this, do the following.
-
-@itemize @bullet
-
-@item
-Choose a name for your site. It must be less than eleven characters for
-now.
-
-@item
-If the program source does not have a @file{./config} directory, create it.
-
-@item
-Create a file called @file{./config/ms-@var{site}} where @var{site} is
-the name of your site. In it, set whatever Makefile variables you need
-to override to match your site's conventions.
-
-@item
-Configure the program with:
-
-@example
-configure @dots{} +site=@var{site}
-@end example
-
-@end itemize
-
-@node Reference, Known Bugs, Porting, top
-@chapter Gory details described
-
-@cindex Backends
-Here we describe the backend support.
-
-@menu
-* Makefile Extensions:: Extensions to the @sc{gnu} coding standards
-* configure.in:: The format of the configure.in file
-* config.status:: config.status
-* Makefile Fragments:: Makefile Fragments
-@end menu
-
-@node Makefile Extensions, configure.in, Reference, Reference
-@section Extensions to the @sc{gnu} coding standards
-
-@cindex Makefile extensions
-@cindex Cygnus extensions
-
-The following additions to the @sc{gnu} coding standards are required
-for Cygnus configure to work properly.
-
-@itemize @bullet
-@item
-The Makefile must contain exactly one line starting with @code{####}.
-This line should follow any default macro definitions but precede any
-rules. Host, target, and site specific Makefile fragments will be
-inserted immediately after this line. If the line is missing, the
-fragments will not be inserted.
-@end itemize
-
-Cygnus adds the following targets to our Makefiles. Their existence is
-not required for Cygnus configure, but they are documented here for
-completeness.
-
-@table @code
-@kindex info
-@item info
-Build all info files from texinfo source.
-
-@kindex install-info
-@item install-info
-Install all info files.
-
-@kindex clean-info
-@item clean-info
-Remove all info files and any intermediate files that can be generated
-from texinfo source.
-
-@kindex stage1
-@item stage1
-@kindex stage2
-@itemx stage2
-@kindex stage3
-@itemx stage3
-@kindex stage4
-@itemx stage4
-@kindex de-stage1
-@itemx de-stage1
-@kindex de-stage2
-@itemx de-stage2
-@kindex de-stage3
-@itemx de-stage3
-@kindex de-stage4
-@itemx de-stage4
-@kindex bootstrap
-@itemx bootstrap
-@kindex comparison
-@itemx comparison
-@kindex Makefile
-@itemx Makefile
-These targets are in transition and may be removed shortly.
-@end table
-
-In addition, the following Makefile targets have revised semantics:
-
-@table @code
-@kindex install
-@item install
-Should @emph{not} depend on the target @code{all}. If the program is
-not already built, @code{make install} should fail. This allows you
-to install programs even when @code{make} would otherwise determine
-them to be out of date. This can happen when the result of a @code{make
-all} is transported via tape to another machine for installation as
-well as in a number of other cases.
-
-@kindex clean
-@item clean
-Should remove any file that can be regenerated by the Makefile,
-excepting only the Makefile itself, and any links created by configure.
-That is, @code{make all clean} should return all directories to their
-original condition. If this is not done, then:
-
-@example
-configure @var{host1} ; make all clean ; configure @var{host2} ; make all
-@end example
-
-@noindent
-will fail because of intermediate files intended for @var{host1}.
-@end table
-
-Cygnus adds the following macros to all @file{Makefile.in} files, but
-you are not required to use them to run Cygnus configure.
-
-@table @code
-@kindex docdir
-@item docdir
-The directory in which to install any documentation that is not either a
-man page or an info file. For man pages, see mandir, for info, see
-infodir.
-
-@kindex includedir
-@item includedir
-The directory in which to install any headers files that should be made
-available to users. This is distinct from the @code{gcc} include
-directory which is intended for @code{gcc} only. Files in
-@code{includedir} may be used by @code{cc} as well.
-@end table
-
-In addition, the following macros have revised semantics. Most of them
-describe installation directories; see also @ref{Install Details,,Full
-description of all installation subdirectories}.
-
-@table @code
-
-@kindex manext
-@item manext
-is not used. The intended usage is not clear. For example, if you have a
-@file{foo.man} and a @file{bar.man}, and @file{foo.man} is destined for
-@file{/usr/local/lib/man/man1/foo.1} while @file{bar.man} is destined
-for @file{/usr/local/lib/man/man5/bar.5}, then what is the desired value
-of @code{manext}?
-
-@kindex datadir
-@item datadir
-is used for host independent data files.
-
-@kindex mandir
-@item mandir
-The default path for @code{mandir} depends on @code{prefix}.
-
-@kindex infodir
-@item infodir
-The default path for @code{infodir} depends on @code{prefix}.
-
-@kindex BISON
-@item BISON
-is assumed to have a @code{yacc} calling convention. To use
-@code{bison}, use @code{BISON=bison -y}.
-@end table
-
-Cygnus Makefiles also conform to one additional restriction:
-
-@itemize @bullet
-@item
-When libraries are installed, the line containing the call to
-@code{INSTALL_DATA} should always be followed by a line containing a
-call to @code{RANLIB} on the installed library. This is to accomodate
-systems that use @code{ranlib}. Systems that do not use @code{ranlib}
-can set @code{RANLIB} to @code{echo} in a host specific Makefile
-fragment.
-@end itemize
-
-@node configure.in, config.status, Makefile Extensions, Reference
-@section The format of the @file{configure.in} file
-@kindex configure.in
-
-A @file{configure.in} file for Cygnus configure consists of a
-@dfn{per-invocation} section, followed by a @dfn{per-host} section,
-followed by a @dfn{per-target} section, optionally followed by a
-@dfn{post-target} section. Each section is a shell script fragment,
-which is sourced by the configure shell script at an appropriate time.
-Values are passed among configure and the shell fragments through a
-set of shell variables. When each section is being interpreted
-(sourced) by the shell, the shell's current directory is the build
-directory, and any files created by the section (or referred to by the
-section) will be relative to the build directory. To reference files
-in other places (such as the source directory), prepend a shell
-variable such as @code{srcdir} to the desired file name.
-
-@cindex Per-invocation section
-The beginning of the @file{configure.in} file begins the per-invocation
-section.
-
-@cindex Per-host section
-A line beginning with @code{# Per-host:} begins the per-host section.
-
-@cindex Per-target section
-A line beginning with @code{# Per-target:} begins the per-target
-section.
-
-@cindex Post-target section
-If it exists, the post-target section begins with @code{# Per-target:}.
-
-@menu
-* Minimal:: A minimal configure.in
-* Configure Variables:: Variables available to configure.in
-* Declarations:: For each invocation
-* Per-host:: For each host
-* Per-target:: For each target
-* Post-target:: After each target
-* Example:: An example configure.in
-@end menu
-
-@node Minimal, Configure Variables, configure.in, configure.in
-@subsection A minimal @file{configure.in}
-
-@cindex Minimal @file{configure.in} example
-A minimal @file{configure.in} consists of four lines.
-
-@example
-srctrigger=foo.c
-srcname="source for the foo program"
-# Per-host:
-# Per-target:
-@end example
-
-The @samp{Per-host} and @samp{Per-target} lines divide the file into the
-three required sections. The @samp{srctrigger} line names a file.
-@code{configure} checks to see that this file exists in the source
-directory before configuring. If the @samp{srctrigger} file does not
-exist, @code{configure} uses the value of @samp{srcname} to print an
-error message about not finding the source.
-
-This particular example uses no links, and only the default host,
-target, and site specific Makefile fragments if they exist.
-
-@node Configure Variables, Declarations, Minimal, configure.in
-@subsection Variables available to configure.in
-
-@cindex @file{configure.in} interface
-
-The following variables pass information between the standard parts of
-@code{configure} and the shell-script fragments in @file{configure.in}:
-
-@defvar{srctrigger}
-Contains the name of a source file that is expected to live in the
-source directory. You must usually set this in the per-invocation
-section of @file{configure.in}. Configure tests to see that this file
-exists. If the file does not exist, configure prints an error message.
-This is used as a sanity check that configure.in matches the source
-directory.
-@end defvar
-
-@defvar{srcname}
-Contains the name of the source collection contained in the source
-directory. You must usually set this in the per-invocation section of
-@file{configure.in}. If the file named in @code{srctrigger} does not
-exist, configure uses the value of this variable when it prints the
-error message.
-@end defvar
-
-@defvar{configdirs}
-Contains the names of any subdirectories where @code{configure} should
-recur. You must usually set this in the per-invocation section of
-@file{configure.in}.
-If @file{Makefile.in} contains a line starting with @code{SUBDIRS =},
-then it will be replaced with an assignment to @code{SUBDIRS} using
-the value of @code{configdirs} (if @code{subdirs} is empty). This can
-be used to determine which directories to configure and build depending
-on the host and target configurations.
-@c Most other matching makefile/config vars use the same name. Why not
-@c this? (FIXME).
-@c Can we get rid of SUBDIRS-substitution? It doesn't work well with subdirs.
-Use @code{configdirs} (instead of the @code{subdirs} variable
-described below) if you want to be able to partition the
-sub-directories, or use independent Makefile fragments.
-Each sub-directory can be independent, and independently re-configured.
-@end defvar
-
-@defvar{subdirs}
-Contains the names of any subdirectories where @code{configure} should
-create a @code{Makefile} (in addition to the current directory),
-@emph{without} recursively running @code{configure}.
-Use @code{subdirs} (instead of the @code{configdirs} variable
-described above) if you want to configure all of the directories
-as a unit. Since there is a single invocation of @code{configure}
-that configures many directories, all the directories can use the
-same Makefile fragments, and the same @code{configure.in}.
-@end defvar
-
-@defvar{host}
-Contains the full configuration name (generated by the script
-@file{config.sub} from the name that the user entered) for the host.
-This is a three-part name of the form
-
-@example
-@var{cpu}-@var{vendor}-@var{os}
-@end example
-
-@noindent
-There are separate variables @code{host_cpu}, @code{host_vendor}, and
-@code{host_os} that you can use to test each of the three parts; this
-variable is useful, however, for error messages, and for testing
-combinations of the three components.
-@end defvar
-
-@defvar{host_cpu}
-Contains the first element of the canonical triple representing the host
-as returned by @file{config.sub}. This is occasionally used to
-distinguish between minor variations of a particular vendor's operating
-system and sometimes to determine variations in binary format between
-the host and the target.
-@end defvar
-
-@defvar{host_vendor}
-Contains the second element of the canonical triple representing the
-host as returned by @file{config.sub}. This is usually used to
-distinguish betwen the numerous variations between @emph{common}
-operating systems.
-@c "@emph{common} OS" doesn't convey much to me. Is this meant to cover
-@c cases like Unix, widespread but with many variations?
-@end defvar
-
-@defvar{host_os}
-Contains the the third element of the canonical triple representing the
-host as returned by @file{config.sub}.
-@end defvar
-
-@defvar{target}
-Contains the full configuration name (generated by the script
-@file{config.sub} from the name that the user entered) for the target.
-This is a three-part name of the form
-
-@example
-@var{cpu}-@var{vendor}-@var{os}
-@end example
-
-@noindent
-There are separate variables @code{target_cpu}, @code{target_vendor}, and
-@code{target_os} that you can use to test each of the three parts; this
-variable is useful, however, for error messages, and for testing
-combinations of the three components.
-@end defvar
-
-@defvar{target_cpu}
-Contains the first element of the canonical triple representing the
-target as returned by @file{config.sub}. This is used heavily by
-programs involved in building programs, like the compiler, assembler,
-linker, etc. Most programs will not need the @code{target} variables at
-all, but this one could conceivably be used to build a program, for
-instance, that operated on binary data files whose byte order or
-alignment differ from the system where the program is running.
-@end defvar
-
-@defvar{target_vendor}
-Contains the second element of the canonical triple representing the
-target as returned by @file{config.sub}. This is usually used to
-distinguish betwen the numerous variations between @emph{common}
-operating systems or object file formats. Sometimes it is used to
-switch between different flavors of user interfaces.
-@c above query re "@emph{common} OS" applies here too
-@end defvar
-
-@defvar{target_os}
-Contains the the third element of the canonical triple representing the
-target as returned by @file{config.sub}. This variable is used by
-development tools to distinguish between subtle variations in object
-file formats that some vendors use across operating system releases. It
-might also be use to decide which libraries to build or what user
-interface the tool should provide.
-@end defvar
-
-@defvar{floating_point}
-Is set to @code{no} if the user invoked configure with the @code{-nfp}
-command line option, otherwise it is empty. This is a request to target
-machines with @emph{no floating point} unit, even if the targets
-ordinarily have floating point units available. This option has no
-negation.
-@end defvar
-
-@defvar{gas}
-Is set to @code{true} if the user invoked configure with the @code{-gas}
-command line option, otherwise it is empty. This is a request to assume
-that all target machines have @sc{gas} available even if they ordinarily do
-not. The converse option @samp{-no-gas} is not available.
-@end defvar
-
-@defvar{x}
-Is set to @code{true} if the user invoked configure with the @code{-x}
-command line option, otherwise it is empty. This is a request to assume
-that @sc{mit x11} compatible headers files and libraries are available
-on all hosts, regardless of what is normally available on them.
-@end defvar
-
-@defvar{srcdir}
-Is set to the name of the directory containing the source for this
-program. This will be different from @file{.} if the user has specified
-the @code{-srcdir=} option. Note that @code{srcdir} is not necessarily
-an absolute path.
-@end defvar
-
-@defvar{host_makefile_frag}
-If set by @file{configure.in}, this variable should be the name a file,
-relative to @code{srcdir} to be included in the resulting Makefile. If
-the named file does not exist, @code{configure} will print a warning
-message. This variable is not set by @code{configure}.
-@end defvar
-
-@defvar{target_makefile_frag}
-If set by @file{configure.in}, this variable should be the name of a
-file, relative to @code{srcdir}, to be included in the resulting
-Makefile. If the named file does not exist, @code{configure} will print
-a warning message. This variable is not set by @code{configure}.
-@end defvar
-
-@defvar{site_makefile_frag}
-Is set to a file name representing to the default Makefile fragment for
-this host. It may be set in @file{configure.in} to override this
-default. Normally @code{site_makefile_frag} is empty, but will have a
-value if the user specified @code{-site=} on the command line. It is
-probably not a good idea to override this variable from
-@file{configure.in}, since that may defeat the @code{configure} user's
-intentions.
-@end defvar
-
-@defvar{Makefile}
-Is set to the name of the generated @file{Makefile}. Normally this
-value is precisely @file{Makefile} but some programs may want something
-else.
-@end defvar
-
-@defvar{removing}
-Is normally empty but will be set to some non-empty value if the user
-specified @code{-rm} on the command line. That is, if @code{removing}
-is non-empty, then configure is @emph{removing} a configuration rather
-than creating one.
-@end defvar
-
-@defvar{files}
-If this variable is non-empty following the @code{per-target:} section,
-then each word in its value will be the target of a symbolic link named
-in the corresponding word from the @code{links} variable.
-@end defvar
-
-@defvar{links}
-If the @code{files} variable is non-empty following the
-@code{per-target:} section, then @code{configure} creates symbolic links
-with the first word of @code{links} pointing to the first word of
-@code{files}, the second word of @code{links} pointing to the second
-word of @code{files}, and so on.
-@end defvar
-
-@node Declarations, Per-host, Configure Variables, configure.in
-@subsection For each invocation
-
-@cindex Declarations section
-
-@code{configure} sources the entire shell script fragment from the start
-of @file{configure.in} up to a line beginning with @samp{# Per-host:}
-immediately after parsing command line arguments. The variables
-@code{srctrigger} and @code{srcname} @emph{must} be set here.
-
-You might also want to set the variable @code{configdirs} here.
-
-@node Per-host, Per-target, Declarations, configure.in
-@subsection For each host
-@cindex per-host section
-@cindex host shell-script fragment
-
-The per-host section of @file{configure.in} starts with the line that begins
-with @samp{# Per-host:} and ends before a line beginning with
-@samp{# Per-target:}. @code{configure} sources the per-host section once for
-each host.
-
-This section usually contains a big case statement using the variables
-@samp{host_cpu}, @samp{host_vendor}, and @samp{host_os} to determine
-appropriate values for @samp{host_makefile_frag} and @samp{files},
-although @samp{files} is not usually set here. Usually, it is set
-at the end of the per-target section after determining the names of the
-target specific configuration files.
-
-@node Per-target, Post-target, Per-host, configure.in
-@subsection For each target
-@cindex per-target section
-@cindex target shell-script fragment
-
-The per-target section of @file{configure.in} starts with the line that
-begins with @samp{# Per-target:} and ends before the line that begins
-with @samp{# Post-target:}, if there is such a line. Otherwise the
-per-target section extends to the end of the file. @code{configure} sources
-the per-target section once for each target before building any files,
-directories, or links.
-
-This section usually contains a big case statement using the variables called
-@samp{target_cpu}, @samp{target_vendor}, and @samp{target_os} to determine
-appropriate values for @samp{target_makefile_frag} and @samp{files}.
-The last lines in the per-target section normally set the variables
-@code{files} and @code{links}.
-
-@node Post-target, Example, Per-target, configure.in
-@subsection After each target
-
-The post-target section is optional. If it exists, the post-target
-section starts with a line beginning with @code{# Post-target:} and
-extends to the end of the file. If it exists, @code{configure} sources this
-section once for each target after building all files, directories, or
-links.
-
-This section is seldom needed, but you can use it to edit the Makefile
-generated by @code{configure}.
-
-@node Example, , Post-target, configure.in
-@subsection An example @file{configure.in}
-@cindex example @file{configure.in}
-@cindex sample @file{configure.in}
-@cindex Bison @file{configure.in}
-
-Here is a small example of a @file{configure.in} file.
-
-@example
-# This file is a collection of shell script fragments used to tailor
-# a template configure script as appropriate for this directory.
-# For more information, see configure.texi.
-
-configdirs=
-srctrigger=warshall.c
-srcname="bison"
-
-# per-host:
-case "$@{host_os@}" in
-m88kbcs)
- host_makefile_frag=config/mh-delta88
- ;;
-esac
-
-# per-target:
-
-files="bison_in.hairy"
-links="bison.hairy"
-
-# post-target:
-@end example
-
-@node config.status, Makefile Fragments, configure.in, Reference
-@section @code{config.status}
-
-@kindex config.status
-
-The final step in configuring a directory is to create an executable
-shell script, @file{config.status}. The main purpose of this file
-is to allow the Makefile for the current directory to rebuild itself, if
-necessary. For this reason, @file{config.status} uses the
-@samp{-norecursion} option to @code{configure}, and is therefore
-probably inappropriate for reconfiguring a tree of source code.
-
-@node Makefile Fragments, , config.status, Reference
-@section Makefile Fragments
-
-@cindex Makefile fragments
-
-Cygnus @code{configure} uses three types of Makefile fragments. In a
-generated Makefile they appear in the order target fragment, host
-fragment, and site fragment. This allows host fragments to override
-target fragments, and site fragments to override both.
-
-Host specific Makefile fragments conventionally reside in the
-@file{./config} directory with names of the form
-@file{mh-@var{host}}. They are used for hosts that require
-odd options to the standard compiler and for compile time options based
-on the host configuration.
-
-Target specific Makefile fragments conventionally reside in the
-@file{./config} directory with names of the form @file{mt-@var{target}}.
-They are used for target dependent compile time options.
-
-Site specific Makefile fragments conventionally reside in the
-@file{./config} directory with names of the form @file{ms-@var{site}}.
-They are used to override host and target independent compile time
-options. Note that you can also override these options on the
-@code{make} invocation line.
-
-@node Known Bugs, Variables Index, Reference, top
-@chapter Known Bugs
-
-@cindex bugs
-
-We know of the following bugs:
-
-@itemize @bullet
-
-@item
-There is no way to query about known hosts, known targets, or the
-porting or testing status of any configuration.
-
-@item
-The negations to the options @code{-gas}, @code{-x}, and @code{-nfp} are
-not available.
-
-@end itemize
-
-@page
-@node Variables Index, Concept Index, Known Bugs, top
-@appendix Variable Index
-
-@printindex vr
-
-@page
-@node Concept Index, , Variables Index, top
-@appendix Concept Index
-
-@printindex cp
-@contents
-@bye
-
-@c Local Variables:
-@c fill-column: 79
-@c outline-regexp: "@chap"
-@c End:
-@c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")
+++ /dev/null
-\input texinfo
-@c
-@c search for "UPDATE!" for items that will need examination on future
-@c releases
-@c
-@c This file may require a nonstandard texinfo.tex to format; if you
-@c need it, please contact Cygnus Support (email editor-in-chief@cygnus.com)
-@setfilename README.info
-@c
-@c This file describes how to install a Cygnus Progressive Release.
-@c
-@c Copyright (C) 1991, 1992 Cygnus Support
-@c This text may be freely distributed under the terms of the GNU
-@c General Public License.
-@c
-@c $Id$
-@set CDROMinst
-@clear CUSTOMER
-@clear FIXMES
-@c
-@iftex
-@c The include file "texiplus.tex" is in the texinfo/cygnus dir, and
-@c implements Cygnus modifications to the texinfo manual style.
-@input texiplus
-@c The include file "smpklug.texi" is a kluge to deal with local
-@c document production issues at Cygnus; it's safe to comment out this
-@c line if you don't have (or don't want) the file.
-@input smpklug.texi
-@smallbook
-@cropmarks
-@setchapternewpage on
-@finalout
-@end iftex
-@settitle Solaris--||RELNO|| Installation
-@tex
-% override-override: the following \font lines are redundant if you're
-% using an unmodified FSF texinfo.
-\globaldefs=1
-\font\texttt=cmtt10 scaled \magstephalf\let\tentt=\texttt
-\font\textsl=cmsl10 scaled \magstephalf\let\tensl=\textsl
-\font\textsf=cmss10 scaled \magstephalf\let\tensf=\textsf
-\globaldefs=0
-%end override-override
-% WARNING: NONSTANDARD USAGE we need \tensf for print, without
-% upsetting info. We weren't using @b in this note, so I redefine it:
-%
-\global\def\b#1{{\tensf #1}}
-\global\parindent=0pt
-@end tex
-@titlepage
-@title Installation Notes
-@sp 3
-@table @strong
-@item Cygnus Support Developer's Kit
-@item Progressive Release ||RELNO|| for Solaris
-@item {}
-@item Contents
-@end table
-@c TOGGLE XREF DISPLAY TO AVOID SQUARE BRACKETS OR QUOTES:
-@c (Cygnus "texiplus.tex" hack. If you want standard texinfo remove
-@c or comment-out instances of @altref).
-@altref
-@format
-@ref{Brief,,Installing in Brief}
-@ref{Contents,,Release Contents}.
-@ref{Platforms,,Supported Platforms}.
-
-@ref{Installing,,Installing the Developer's Kit}.
-@ref{local-install,,Installing with local ||MEDIUM|| drive}.
-@ref{cross-install,,Installing with another machine's ||MEDIUM|| drive}.
-@ref{Examples,,Installation Examples}.
-
-@ref{Paths,,Changing the Paths}
-@ref{Trouble,,Some Things that Might go Wrong}
-@ref{Rebuilding,,Rebuilding From Source}.
-@ref{Removing,,Removing the Developer's Kit}.
-
-@ref{Cygnus-FSF,,Cygnus Progressive Releases and the FSF}.
-@ref{Cygnus-Support,,About Cygnus Support}.
-@end format
-@c TOGGLE XREF DISPLAY BACK, TO RESTORE MARKERS AROUND SECNAMES:
-
-@altref
-@author Cygnus Support @hfill hotline: +1 415 322 7836
-@page
-
-@tex
-\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
-\xdef\Rmanvers{{\it Installation Notes (Solaris Developer's Kit)}, \$Revision$} % *NOT* for use in headers, footers
-{\parskip=0pt \hfill Cygnus Support\par \hfill \Rmanvers\par \hfill
-\TeX{}info \texinfoversion\par }
-\global\def\manvers{Progressive ||RELNO|| for Solaris}
-@end tex
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 1992 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 also 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.
-
-@end titlepage
-
-@ifinfo
-@node Top, Brief, (dir), (dir)
-@top Overview
-
-This file is about the Cygnus Developer's Kit for Solaris: what's in it,
-how to install it, and how to reconfigure it.
-
-@menu
-* Brief:: Installing in Brief
-* Contents:: Release Contents
-* Requirements:: System Requirements
-* Installing:: Installing the Developer's Kit
-* Running:: Running the Programs
-* Paths:: Changing the Paths
-* Trouble:: Some Things that Might go Wrong
-* Rebuilding:: Rebuilding From Source
-* Removing:: Removing Parts of the Developer's Kit
-* Cygnus-FSF:: Cygnus Releases and the FSF
-* Cygnus-Support:: About Cygnus Support
-
-@end menu
-
-@end ifinfo
-
-@node Brief, Contents, Top, Top
-@unnumbered Installing in Brief
-@strong{You can run the brief installation procedure if:}
-@itemize @bullet
-@item
-Your Solaris computer has its own ||MEDIUM|| drive
-@item
-You use the default installation directory @file{/opt/gnu}, and
-@item
-You have at least ||DF|| MB available in @code{/opt} (try @samp{df /opt})
-@end itemize
-Otherwise, see @ref{Installing,,Installing the Developer's Kit}.
-
-@strong{Steps for Brief Install:}
-
-The whole procedure takes between ?? minutes and ???.
-
-@enumerate
-@item
-Make sure you have root access to the computer.
-
-@cartouche
-@example
-eg$ @b{su} @b{root}
-password: @i{(enter root password)}
-@end example
-@end cartouche
-
-@item
-Load the Progressive--||RELNO|| ||MEDIUM|| into your ||MEDIUM|| drive.
-
-@ifset CDROMinst
-@item
-Mount the @sc{cd-rom}:
-
-@cartouche
-@example
-eg# @b{mkdir} @b{/cdrom} @i{(ignore any errors)}
-eg# @b{mount} @b{-F} @b{hsfs} @b{-o} @b{ro} @b{/dev/dsk/c0t6d0s0} @b{/cdrom}
-@end example
-@end cartouche
-@end ifset
-
-@item
-Run the @code{pkgadd} command like this:
-
-@cartouche
-@example
-eg# @b{/usr/sbin/pkgadd} @b{-n} @b{-d} @b{||MEDstr||} @b{GNUDEVTkit} @b{GNUDEVTsrc}
-@end example
-@end cartouche
-
-You will see messages about installation activity, ending with
-
-@cartouche
-@example
-Cygnus Support software distribution installed!
-@end example
-@end cartouche
-
-@item
-Build a symbolic link to make execution paths easy:
-
-@cartouche
-@example
-eg# @b{cd} @b{/opt/gnu}
-eg# @b{ln} @b{-s} @b{progressive-||RELNO||} @b{progressive}
-@end example
-@end cartouche
-
-@ifset CUSTOMER
-@item
-Use your Cygnus customer-ID (see cover letter) to tag your copy of our
-problem-report form:
-
-@cartouche
-@example
-eg# @b{/opt/progressive/bin/install@t{_}cid} @var{customerID}
-@end example
-@end cartouche
-@end ifset
-
-@end enumerate
-
-You're done! Anyone who puts @samp{/opt/progressive/bin} in her or his
-@code{PATH} can use the Developer's Kit.
-
-@node Contents, Requirements, Brief, Top
-@unnumbered Release Contents
-
-This Developer's Kit is a Cygnus Support @dfn{Progressive Release}: the
-programs in it are recent versions, which have been tested and certified
-both individually and as a coordinated suite of tools.
-The kit includes both source and binaries for:
-
-@c UPDATE! Anything new shoveled in?
-@table @r
-@item @sc{gcc}
-C compiler
-
-@item @sc{gdb}
-debugger
-
-@item @sc{make}
-compilation control program
-
-@item Documentation Tools
-@code{info}, @code{makeinfo}
-
-@item Support Utilities
-@code{patch}, the source-code update utility; @sc{gnu} @code{diff}; and
-@code{send_pr}, the Cygnus problem-reporting utility
-@end table
-
-@menu
-* Platforms:: Supported Platforms
-@end menu
-
-@node Platforms, , Contents, Contents
-@unnumberedsec Supported Platforms
-
-@table @strong
-@item ||HOST||s
-All programs in your Developer's Kit are for ||HOST||s running
-Solaris; we ship binaries (configured to install and run under
-@file{/opt/gnu}) as well as all source code.
-
-@item Other Platforms
-For information on other platforms or other programs
-that we may support, please contact Cygnus Support at:
-
-@table @strong
-@item voice
-+1 415 322 3811
-@item hotline
-+1 415 322 7836
-@item fax
-+1 415 322 3270
-@item email
-@code{info@@cygnus.com}
-@end table
-@end table
-
-@menu
-* Requirements:: System Requirements
-@end menu
-
-@node Requirements, Installing, Contents, Top
-@unnumbered System Requirements
-
-@table @strong
-@item OS Level
-Progressive Release ||RELNO|| for ||HOST||s requires Solaris 2.0 or
-later.
-
-@item A ||MEDIUM|| Drive
-You need access to a ||MEDIUM|| drive. The ||MEDIUM|| drive need not be
-on the computer where you want to run the software; but it is best if
-the machine with a ||MEDIUM|| drive and your computer can mount a common
-file system. At the very least, you need some sort of file transfer
-capability between the machine with a ||MEDIUM|| drive and your
-computer.
-
-@item Disk Space
-The total space required to extract and install
-binaries and source for all programs is
-||DF|| megabytes.
-
-The software is configured to go into @file{/opt/gnu}. If you have
-space available, but not in the same file system as @file{/opt}, you can
-use @samp{ln -s} to create @file{/opt/gnu} as a symbolic link to the
-file system where you do have the space available.
-
-If you don't have enough space, you may be able to install binaries only;
-see @ref{Limited Space,,Not Enough Space}. The space required for
-installing the binaries is ||BD|| megabytes.
-
-@item Root Access
-The standard Solaris installation procedures for optional packages
-require you to run the installation with root privileges. We deplore
-this requirement, but consider it valuable nevertheless to conform to
-the standard Solaris installation procedure.
-@end table
-
-@node Installing, Running, Requirements, Top
-@unnumbered Installing the Developer's Kit
-
-@iftex
-This note shows the different parts of examples like this:
-@table @asis
-@item Computer output is shown in @code{typewriter font.}
-@item Your input is indicated by @b{a sans-serif font.}
-@item Text to replace, rather than typing verbatim, is in @var{this font}.
-@item Comments appear in @i{italic font}.
-@end table
-@end iftex
-In examples, we show the system prompt as @samp{eg#}.
-
-The Cygnus Progressive--||RELNO|| ||MEDIUM|| is designed to work with
-the Solaris administration command @code{pkgadd}.
-
-Two checklists follow. The first checklist shows what to do if you have
-a ||MEDIUM|| drive on the computer where you want to install the
-Developer's Kit; the second shows how to use another networked machine
-to read the ||MEDIUM||, then finish the installation on your computer.
-
-Both checklists suggest installing the Developer's Kit binaries under
-@file{/opt/gnu} (which can be a symbolic link from somewhere else, if
-you like). We recommend you use this location for the software, because
-the precompiled, ready-to-run versions of the tools are configured this
-way. If you want to install elsewhere, see @ref{Paths,,Changing
-the Paths}.)
-
-Both checklists are very similar to @ref{Brief,,Installing in Brief},
-but provide more discussion of each step, and offer alternatives for
-systems whose available disk space is not in @code{/opt} and for
-installing only portions of the Developer's Kit.
-
-@menu
-* local-install:: Installing with a local ||MEDIUM|| drive
-* cross-install:: Installing with another machine's ||MEDIUM|| drive
-* Examples:: Installation Examples
-* Why-fixincludes:: Why Convert System Header Files?
-* Link:: Easy Access and Updating
-@end menu
-
-@node local-install, cross-install, Installing, Installing
-@unnumberedsubsec Installing with a local ||MEDIUM|| drive
-
-This procedure is for a ||HOST|| that has its own ||MEDIUM|| drive. The
-complete procedure takes at least ?? minutes on a fast, unloaded
-machine; it may take up to ??? in other situations.
-
-@enumerate
-@item
-Make sure you have root access to the computer. The standard Solaris
-installation procedures for optional packages require @code{root} to run
-the complete installation.
-
-@cartouche
-@example
-eg$ @b{su root}
-password: @i{Enter root password.}
-@end example
-@end cartouche
-
-@item
-Check that you have enough space available in @file{/opt}
-(@pxref{Requirements,,System Requirements}). You can use @samp{df /opt}
-to check.
-@ifset FIXMES
-@quotation
-@emph{FIXME!} Does @code{pkgadd} check for this and issue an error? If
-so, recast in those terms?
-@end quotation
-@end ifset
-
-@ifset CDROMinst
-@item
-Load the Catalyst CDWARE disk into a disk caddy, and put the caddy in
-your CD-ROM drive.
-
-@item
-Mount the @sc{cd-rom}. This note assumes your mount point for a
-@code{cd-rom} is a directory called @file{/cdrom}; substitute to match
-your site's conventions if necessary.
-
-@c makeinfo seems unable to cope with nested ifset's when outer is off,
-@c inner is on.
-@c @ifset FIXMES
-@quotation
-@emph{FIXME!} @file{/dev/dsk/c0t6d0s0} for @sc{cd-rom} cribbed from
-Sun's generic optional-package install notes. Is it really this cut and
-dried? What about systems with more than one @sc{cd-rom} drive?
-@end quotation
-@c @end ifset
-
-@cartouche
-@example
-eg# @b{mkdir} @b{/cdrom} @i{(ignore any errors)}
-eg# @b{mount} @b{-F} @b{hsfs} @b{-o} @b{ro} @b{/dev/dsk/c0t6d0s0} @b{/cdrom}
-@end example
-@end cartouche
-@end ifset
-
-@ifclear CDROMinst
-@item
-Load the Cygnus Support release tape (labelled
-``Progressive--||RELNO||'') into your system's tape drive.
-
-@item
-find out the name of the tape device on your machine that can read the
-release tape. Cygnus release tapes are labelled to identify the kind of
-tape used. You should use one of the following devices:
-
-@ifset FIXMES
-@quotation
-@emph{FIXME!} Does SVr4 specify device names enough that we can be more
-explicit here?
-@end quotation
-
-@quotation
-@emph{FIXME!} For our own @code{Install}, we asked for
-@emph{non-rewinding} tape device. @code{pkgadd} doesn't say what kind
-of tape devices it wants. Does it matter?
-@end quotation
-@end ifset
-
-@table @emph
-@item ||TAPdflt|| tape
-Use @file{||DEVdflt||} where the examples show @code{||MEDstr||}.
-
-@item Exabyte ||MEDIUM||
-The device name depends on how your Exabyte tape drive was installed;
-ask your system administrator. You will probably use something like
-@file{/dev/???/a0b1c2d3} where we show @code{||MEDstr||}.
-@end table
-@end ifclear
-
-@item
-Now you can install ready-to-run binaries; or source; or both.
-
-@itemize @bullet
-@item
-Choose source or binaries by running @code{pkgadd} with either or
-both of the arguments @samp{GNUDEVTkit} (to install binaries) or
-@code{GNUDEVTsrc} (for the source).
-
-@item
-Run @code{pkgadd} interactively (that is, @emph{without} the @w{@samp{-n}}
-option) to choose the installation directory.
-
-@item
-Use the @w{@samp{-d}} option to identify your ||MEDIUM||.
-@end itemize
-
-For instance, typing this command line starts installation of both
-the source package and the binary package:
-
-@cartouche
-@example
-eg# @b{/usr/sbin/pkgadd} @b{-d} @b{||MEDstr||} @b{GNUDEVTkit} @b{GNUDEVTsrc}
-@end example
-@end cartouche
-
-@item
-For each of the packages, @code{pkgadd} will ask for confirmation of the
-install directory @file{/opt/gnu}, or an alternative.
-
-For the source package @code{GNUDEVTsrc}, place the package wherever
-it's convenient; the only advantage of using the default location
-@file{/opt/gnu} is to keep the source near the binaries.
-
-For the @code{GNUDEVTkit} binaries, we recommend using the default location
-@file{/opt/gnu}, since this location is configured and compiled into all
-the tools.
-
-@quotation
-@emph{Warning!} If you choose an alternate location for
-@code{GNUDEVTkit} binaries, you will need to override the compiled-in
-paths to run the programs. @xref{Paths,,Changing the Paths}.
-@end quotation
-
-This example shows the interaction to accept @file{/opt/gnu} for the
-binaries:
-
-@cartouche
-@example
-Extracting Solaris GNU Developer's Kit binaries.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{y}
-@end example
-@end cartouche
-
-This example shows the interaction to place the source in
-@file{/usr/local/src} instead of the default location. After you type
-the location, the installation script asks you to confirm. You can use
-this opportunity to avoid typographical errors in the install directory
-name.
-
-@cartouche
-@example
-Extracting Solaris GNU Developer's Kit source.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{n}
- >>Where do you want to install? > @b{/usr/local/src}
- >>Installing in "/usr/local/src". OK? [y/n]> @b{y}
-@end example
-@end cartouche
-
-@item
-Installing the Developer's Kit binaries is a time-consuming step
-(between ?? minutes and ???, depending on the speed of your machine).
-@code{pkgadd} will display informative messages about its progress.
-After the initial extraction step, it prepares copies of your system
-header files, converted to comply better with @sc{ansi} C
-(@pxref{Why-fixincludes,,Why Convert System Header Files?}). A log for
-this step goes in @file{/opt/gnu/progressive-||RELNO||/fixincludes.log}.
-@emph{Your system's original header files are not changed;}
-@code{pkgadd} writes the converted copies in a separate,
-@sc{gcc}-specific directory.
-
-When installation is complete, @code{pkgadd} displays the message
-
-@cartouche
-@example
-Cygnus Support software distribution installed!
-@end example
-@end cartouche
-
-@item
-Now that the software is on your system, you should arrange for users
-to run it conveniently. We recommend the following symbolic link; see
-@ref{Link,,Easy Access and Updating}, for a discussion.
-
-@cartouche
-@example
-eg# @b{cd} @b{/opt/gnu}
-eg# @b{ln} @b{-s} @b{progressive-||RELNO||} @b{progressive}
-@end example
-@end cartouche
-
-@ifset CUSTOMER
-@item
-Finally, in case you need to send problem reports to Cygnus, we've
-included a script @code{send_pr} (and a supporting online template) to
-structure and transmit your reports. Please use the small utility
-script @code{install_cid} to record your Cygnus customer ID in your copy
-of the problem report form. (You can find your customer ID in the cover
-letter that came with this release; or call the Cygnus hotline,
-@w{+1 415 322 7836}.) This will enable us to respond as quickly as
-possible to any problem reports you send.
-
-@cartouche
-@example
-eg# @b{/opt/progressive/bin/install@t{_}cid @var{customerID}}
-install_cid: `@var{customerID}' is now the default customer ID
- for send_pr
-@end example
-@end cartouche
-@end ifset
-
-@end enumerate
-
-You're done! Anyone who puts @samp{/opt/progressive/bin} in her or his
-@code{PATH} can use the Developer's Kit.
-
-@node cross-install, Examples, local-install, Installing
-@unnumberedsubsec Installing with another machine's ||MEDIUM|| drive
-This checklist is for a ||HOST|| that does not have its own ||MEDIUM|| drive,
-but can share a file system with another machine that does have a ||MEDIUM||
-drive. The other machine need not be a ||HOST||, @emph{but it must be
-running some version of UNIX System V release 4}. The complete
-procedure takes between ?? and ???, depending on the speed of
-each machine.
-
-We show the other computer's prompt as @samp{other#}, and your
-computer's prompt as @samp{eg#}.
-
-@ifset FIXMES
-@quotation
-@emph{FIXME!} SVr4 required simply for presence of @code{pkgadd}
-command. If we care enough to relax this, we simply need to provide an
-alternative extraction command-line. @code{dd}? @code{tar}?
-@end quotation
-@end ifset
-
-@enumerate
-@item
-find a machine with a suitable ||MEDIUM|| drive on the same network as your
-||HOST||, and sign on to it. If the only machine with a ||MEDIUM||
-drive isn't on the network, @pxref{No Drive,,No Local ||MEDIUM|| Drive}.
-
-@item
-Make sure you have root access to @emph{both} computers. The standard
-Solaris installation procedures for optional packages require
-@code{root} to run all installation steps.
-
-@cartouche
-@example
-other$ @b{su} @b{root}
-password: @i{(enter root password)}
-@end example
-@end cartouche
-
-@item
-Choose a directory where you will extract the Developer's Kit. The
-directory must be accessible from both machines (the one with the
-||MEDIUM|| drive, and the ||HOST|| where you want to use the software).
-If possible, use @file{/var/spool/pkg}; this is the default package
-spooling directory for Solaris (and System V release 4 in general).
-
-@ifset FIXMES
-@quotation
-@emph{FIXME!} Do SVr4 systems expect to export things like
-@file{/var/spool/pkg}, or is this a nonsensical suggestion for
-cross-install?
-@end quotation
-@end ifset
-
-Wherever this note uses @var{shr}, substitute the name of the
-directory you chose.
-
-@item
-Check that you have enough space available (@pxref{Requirements,,System
-Requirements}) in @var{shr}. You can use @samp{df @var{shr}} to check.
-@ifset FIXMES
-@quotation
-@emph{FIXME!} Does @code{pkgadd} check for this and issue an error? If
-so, recast in those terms?
-@end quotation
-@end ifset
-
-@ifset CDROMinst
-@item
-Load the Catalyst CDWARE disk into a disk caddy, and put the caddy in
-your CD-ROM drive.
-
-@item
-Mount the @sc{cd-rom}. This note assumes your mount point for a
-@code{cd-rom} is a directory called @file{/cdrom}; substitute to match
-your site's conventions if necessary.
-
-@c makeinfo seems unable to cope with nested ifsets when outer is off,
-@c inner is on.
-@c @ifset FIXMES
-@quotation
-@emph{FIXME!} @file{/dev/dsk/c0t6d0s0} for @sc{cd-rom} cribbed from
-Sun's generic optional-package install notes. Is it really this
-definite on @emph{all} SVr4 systems? What about systems with more than
-one @sc{cd-rom} drive?
-@end quotation
-@c @end ifset
-
-@cartouche
-@example
-other# @b{mkdir} @b{/cdrom} @i{(ignore any errors)}
-other# @b{mount} @b{-F} @b{hsfs} @b{-o} @b{ro} @b{/dev/dsk/c0t6d0s0} @b{/cdrom}
-@end example
-@end cartouche
-@end ifset
-
-@ifclear CDROMinst
-@item
-Load the Cygnus Support release ||MEDIUM|| (labelled
-``Progressive--||RELNO||'') into the tape drive. In these examples,
-@var{||MEDstr||} stands for the device name for the appropriate
-tape drive on your system.
-
-@item
-find out the name of the tape device on the machine
-that can read the release tape. Cygnus release tapes are labelled to
-identify the kind of tape used. You should use one of the following
-devices:
-@ifset FIXMES
-@quotation
-@emph{FIXME!} Does SVr4 specify device names enough that we can be more
-explicit here?
-@end quotation
-
-@quotation
-@emph{FIXME!} For our own @code{Install}, we asked for
-@emph{non-rewinding} tape device. @code{pkgadd} doesn't say what kind
-of tape devices it wants. Does it matter?
-@end quotation
-@end ifset
-
-@table @emph
-@item ||TAPdflt|| ||MEDIUM||
-Use @file{||DEVdflt||} where the examples show @code{||MEDstr||}.
-
-@item Exabyte ||MEDIUM||
-The device name depends on how your Exabyte ||MEDIUM|| drive was installed;
-check with your system administrator. You will probably use something like
-@file{/dev/???/a0b1c2d3} where the example shows @code{||MEDstr||}.
-@end table
-@end ifclear
-
-@item
-Now you can extract either the ready-to-run binary package, the source
-package, or both.
-
-@itemize @bullet
-@item
-Choose source or binaries by running @code{pkgadd} with either or
-both of the arguments @samp{GNUDEVTkit} (to install binaries) or
-@code{GNUDEVTsrc} (for the source).
-
-@emph{Warning:} later, when installing on your ||HOST||, only the
-packages you extract now will be available. We recommend you extract
-both packages at this point.
-
-@item
-Use @samp{-s @var{shr}} to copy the packages to @var{shr}, where you
-will be able to install them from your ||HOST||.
-
-@item
-Use the @w{@samp{-d}} option to identify your ||MEDIUM||.
-@end itemize
-
-This is the command line to extract both packages into @var{shr}:
-
-@cartouche
-@example
-other# @b{/usr/sbin/pkgadd} @b{-s} @var{shr} @b{-d} @b{||MEDstr||} \
- @b{GNUDEVTkit} @b{GNUDEVTsrc}
-@end example
-@end cartouche
-
-@item
-Log off the computer with the ||MEDIUM|| drive, and log on to the
-||HOST|| where you want to use the software.
-
-@item
-Make sure you have root access to this computer, too. The standard
-Solaris installation procedures for optional packages require
-@code{root} to run the complete installation.
-
-@cartouche
-@example
-eg$ @b{su root}
-password: @i{(enter root password)}
-@end example
-@end cartouche
-
-@item
-Check that you have enough space available in @file{/opt}
-(@pxref{Requirements,,System Requirements}). You can use @samp{df /opt}
-to check.
-@ifset FIXMES
-@quotation
-@emph{FIXME!} Does @code{pkgadd} check for this and issue an error? If
-so, recast in those terms?
-@end quotation
-@end ifset
-
-@item
-Now you can install ready-to-run binaries; or source; or both.
-
-@itemize @bullet
-@item
-Choose source or binaries by running @code{pkgadd} with either or
-both of the arguments @samp{GNUDEVTkit} (to install binaries) or
-@code{GNUDEVTsrc} (for the source).
-
-@emph{Warning:} if you extracted only one of these packages when reading
-the ||MEDIUM|| from another machine, you no longer have a choice---you
-can only specify that package name to complete the installation.
-
-@item
-Run @code{pkgadd} interactively (that is, @emph{without} the @w{@samp{-n}}
-option) to choose the installation directory.
-
-@item
-Use the @w{@samp{-d} @var{shr}} option to identify the shared directory
-where you extracted the packages earlier. (If you used
-@file{/var/spool/pkg} as @var{shr}, you can leave off this option;
-@code{pkgadd} uses that directory as the default location for packages
-to install.)
-@end itemize
-
-For instance, typing this command line starts installation of both
-the source package and the binary package:
-
-@cartouche
-@example
-eg# @b{/usr/sbin/pkgadd} @b{-d} @var{shr} @b{GNUDEVTkit} @b{GNUDEVTsrc}
-@end example
-@end cartouche
-
-@item
-For each of the packages, @code{pkgadd} will ask for confirmation of the
-install directory @file{/opt/gnu}, or an alternative.
-
-For the source package @code{GNUDEVTsrc}, place the package wherever
-it's convenient; the only advantage of using the default location
-@file{/opt/gnu} is to keep the source near the binaries.
-
-For the @code{GNUDEVTkit} binaries, we recommend using the default location
-@file{/opt/gnu}, since this location is configured and compiled into all
-the tools.
-
-@quotation
-@emph{Warning!} If you choose an alternate location for
-@code{GNUDEVTkit} binaries, you will need to override the compiled-in
-paths to run the programs. @xref{Paths,,Changing the Paths}.
-@end quotation
-
-This example shows the interaction to accept @file{/opt/gnu} for the
-binaries:
-
-@cartouche
-@example
-Extracting Solaris GNU Developer's Kit binaries.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{y}
-@end example
-@end cartouche
-
-This example shows the interaction to place the source in
-@file{/usr/local/src} instead of the default location. After you type
-the location, the installation script asks you to confirm. You can use
-this opportunity to avoid typographical errors in the install directory
-name.
-
-@cartouche
-@example
-Extracting Solaris GNU Developer's Kit source.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{n}
- >>Where do you want to install? > @b{/usr/local/src}
- >>Installing in "/usr/local/src". OK? [y/n]> @b{y}
-@end example
-@end cartouche
-
-@item
-Installing the Developer's Kit binaries is a time-consuming step (at
-least ?? minutes on a fast, unloaded machine; it may take as much as ???
-under other circumstances). @code{pkgadd} will display informative
-messages about its progress. After copying the binaries into their
-installed locations, @code{pkgadd} prepares copies of your system header
-files, converted to comply better with @sc{ansi} C
-(@pxref{Why-fixincludes,,Why Convert System Header Files?}). A log for
-this step goes in @file{/opt/gnu/progressive-||RELNO||/fixincludes.log}.
-@emph{Your system's original header files are not changed;}
-@code{Install} writes the converted copies in a separate,
-@sc{gcc}-specific directory.
-
-When installation is complete, @code{pkgadd} displays the message
-
-@cartouche
-@example
-Cygnus Support software distribution installed!
-@end example
-@end cartouche
-
-@item
-Now that the software is on your system, you need to arrange for users
-to run it conveniently. We recommend the following link; see
-@ref{Link,,Easy Access and Updating}, for a discussion.
-
-@cartouche
-@example
-eg# @b{cd} @b{/opt/gnu}
-eg# @b{ln} @b{-s} @b{progressive-||RELNO||} @b{progressive}
-@end example
-@end cartouche
-
-@ifset CUSTOMER
-@item
-Finally, in case you need to send problem reports to Cygnus, we've
-included a script @code{send_pr} (and a supporting online form) to
-structure and transmit your reports. Please use the small utility
-script @code{install_cid} to record your Cygnus customer ID in your copy
-of the problem report form. (You can find your customer ID in the cover
-letter that came with this release; or call the Cygnus hotline,
-@w{+1 415 322 7836}.) This will enable us to respond as quickly as
-possible to any problem reports you send.
-
-@cartouche
-@example
-eg# @b{/opt/progressive/bin/install@t{_}cid @var{customerID}}
-install_cid: `@var{customerID}' is now the default customer ID
- for send_pr
-@end example
-@end cartouche
-@end ifset
-
-@end enumerate
-
-You're done! Anyone who puts @samp{/opt/progressive/bin} in her or his
-@code{PATH} can use the Developer's Kit.
-
-@node Examples, Why-fixincludes, cross-install, Installing
-@unnumbered Installation Examples
-
-Here are some examples covering common situations.
-
-@menu
-* binaries:: Installing binaries only
-* ||HOSTstr||-remote:: Reading ||MEDIUM|| on any machine, finishing on ||HOST||
-* source-remove:: Removing Source
-@end menu
-
-@node binaries, ||HOSTstr||-remote, Examples, Examples
-@unnumberedsubsec Installing binaries only
-
-@c FIXME for texinfo?? The "ifsets" were originally only around the
-@c portions of this example that depend on cdrom, but texinfo kept
-@c not-finding the end-ifsets. Does ifset break inside example?
-@ifset CDROMinst
-@cartouche
-@example
-eg$ @b{su} @b{root}
-password:
-
-@i{Insert ||MEDIUM|| into drive.}
-
-eg# @b{mkdir} @b{/cdrom}
-eg# @b{mount} @b{-F} @b{hsfs} @b{-o} @b{ro} @b{/dev/dsk/c0t6d0s0} @b{/cdrom}
-eg# @b{/usr/sbin/pkgadd} @b{-n} @b{-d} @b{||MEDstr||} @b{GNUDEVTkit}
-
-Extracting Solaris GNU Developer's Kit binaries.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{y}
-
-@i{Installation progress messages, ending with:}
-
-Cygnus Support software distribution installed!
-
-eg# @b{cd} @b{/opt/gnu}
-eg# @b{ln} @b{-s} @b{progressive-||RELNO||} @b{progressive}
-@end example
-@end cartouche
-@end ifset
-
-@ifclear CDROMINST
-@cartouche
-@example
-eg$ @b{su} @b{root}
-password:
-
-@i{Insert ||MEDIUM|| into drive.}
-
-eg# @b{/usr/sbin/pkgadd} @b{-n} @b{-d} @b{||MEDstr||} @b{GNUDEVTkit}
-
-Extracting Solaris GNU Developer's Kit binaries.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{y}
-
-@i{Installation progress messages, ending with:}
-
-Cygnus Support software distribution installed!
-
-eg# @b{cd} @b{/opt/gnu}
-eg# @b{ln} @b{-s} @b{progressive-||RELNO||} @b{progressive}
-@end example
-@end cartouche
-@end ifclear
-
-If you don't want the source---for instance, to save space---you can use
-the argument @samp{GNUDEVTbin} and omit @samp{GNUDEVTsrc}.
-
-@node ||HOSTstr||-remote, source-remove, binaries, Examples
-@unnumberedsubsec Reading ||MEDIUM|| on other machine, finishing on ||HOST||
-
-@ifset CDROMinst
-@cartouche
-@example
-@emph{On another SVr4 machine on your network with a ||MEDIUM|| drive:}
-other$ @b{su} @b{root}
-password:
-
-@i{Insert ||MEDIUM|| into drive.}
-
-other# @b{mkdir} @b{/cdrom} @i{(ignore any errors)}
-other# @b{mount} @b{-F} @b{hsfs} @b{-o} @b{ro} @b{/dev/dsk/c0t6d0s0} @b{/cdrom}
-other# @b{/usr/sbin/pkgadd} @b{-s} @var{/var/spool/pkg} @b{-d} @b{||MEDstr||} \
- @b{GNUDEVTkit} @b{GNUDEVTsrc}
-other# exit
-
-@emph{On your ||HOST||}
-eg$ @b{su} @b{root}
-password:
-eg# @b{/usr/sbin/pkgadd} @b{GNUDEVTkit} @b{GNUDEVTsrc}
-
-Extracting Solaris GNU Developer's Kit binaries.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{y}
-
-Extracting Solaris GNU Developer's Kit source.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{y}
-
-@i{Installation progress messages, ending with:}
-
-Cygnus Support software distribution installed!
-
-eg# @b{cd} @b{/opt/gnu}
-eg# @b{ln} @b{-s} @b{progressive-||RELNO||} @b{progressive}
-@end example
-@end cartouche
-@end ifset
-
-@ifclear CDROMinst
-@cartouche
-@example
-@emph{On another SVr4 machine on your network with a ||MEDIUM|| drive:}
-other$ @b{su} @b{root}
-password:
-
-@i{Insert ||MEDIUM|| into drive.}
-
-other# @b{/usr/sbin/pkgadd} @b{-s} @var{/var/spool/pkg} @b{-d} @b{||MEDstr||} \
- @b{GNUDEVTkit} @b{GNUDEVTsrc}
-other# exit
-
-@emph{On your ||HOST||}
-eg$ @b{su} @b{root}
-password:
-eg# @b{/usr/sbin/pkgadd} @b{GNUDEVTkit} @b{GNUDEVTsrc}
-
-Extracting Solaris GNU Developer's Kit binaries.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{y}
-
-Extracting Solaris GNU Developer's Kit source.
- >>Installing in "/opt/gnu". OK? [y/n]> @b{y}
-
-@i{Installation progress messages, ending with:}
-
-Cygnus Support software distribution installed!
-
-eg# @b{cd} @b{/opt/gnu}
-eg# @b{ln} @b{-s} @b{progressive-||RELNO||} @b{progressive}
-@end example
-@end cartouche
-@end ifclear
-
-@noindent
-If your ||HOST|| doesn't have a ||MEDIUM|| drive, but another SVr4
-machine that can mount a shared directory (here the default
-package-spooling directory, @samp{/var/spool/pkg}) does have one, you
-can carry out the first step of the installation from the machine with a
-||MEDIUM|| drive, as shown. Note that you have to use @samp{-s} on
-the @code{pkgadd} command line. This alerts @code{pkgadd} to stop the
-install procedure after it reads the ||MEDIUM||. You still have to
-finish the installation, but the last two steps have to run on your
-||HOST||.
-
-@node source-remove, , ||HOSTstr||-remote, Examples
-@unnumberedsubsec Removing Source
-The @code{pkgrm} command can remove any package installed by
-@code{pkgadd}. For example, if after installing the complete
-Developer's Kit on your machine you decide to remove the source files:
-
-@cartouche
-@example
-eg$ @b{su} @b{root}
-password:
-eg# @b{/usr/sbin/pkgrm GNUDEVTsrc}
-@end example
-@end cartouche
-
-@node Why-fixincludes, Link, Examples, Installing
-@unnumberedsec Why Convert System Header Files?
-
-@ifset FIXMES
-@quotation
-@emph{FIXME!} This is pretty much the standard progressive blurb about
-fixincludes. Surely it's bogus here, since Solaris is a nice modern
-system? Doesn't it have ANSI header files?
-
-Someone, please confirm or deny! I seem to recall there's at least some
-bullshit about how @code{__ANSIC__} or some such thing is defined.
-Specifics, anyone?
-@end quotation
-@end ifset
-
-You may notice messages about running @samp{fixincludes} during your
-Developer's Kit installation. When the @sc{ansi x3j11} committee
-finished developing a standard for the C language, a few things that had
-worked one way in many traditional C compilers ended up working
-differently in @sc{ansi} C. Most of these changes are improvements.
-But some Unix header files still rely on the old C meanings, in cases
-where the Unix vendor has not yet converted to using an @sc{ansi} C
-compiler for the operating system itself. The @samp{fixincludes}
-portion of installation is a mechanical translation that writes
-@sc{ansi} C versions of some system header files into a new,
-@sc{gcc}-specific include directory---@emph{your system's original
-header files are not affected.}
-
-The particular problems fixed include:
-@itemize @bullet
-@item
-@code{_IOR}, @code{_IOW}, and @code{_IORW} macros use obsolete
-preprocessor facilities
-@item
-@code{#endif} no longer ignores its argument
-@end itemize
-
-If you don't run @code{fixincludes}, the GNU C compiler can only use the
-original system header files when you compile new C programs. @emph{In
-some cases, the resulting programs will fail at run-time}.
-
-@node Link, , Why-fixincludes, Installing
-@unnumbered Easy Access and Updating
-Once you've extracted them from the ||MEDIUM||, the Developer's Kit
-tools are installed under a directory named
-@file{progressive-||RELNO||}. We put the release number in the
-directory name so that you can keep several releases installed at the
-same time, if you wish. In order to simplify administrative procedures
-(such as upgrades to future Cygnus Progressive releases), we recommend
-that you establish a symbolic link @file{/opt/gnu/progressive} to this
-directory. For example, assuming you've used the default installation
-path:
-
-@cartouche
-@example
-eg# @b{cd /opt/gnu}
-eg# @b{ln -s progressive-||RELNO|| progressive}
-@end example
-@end cartouche
-
-We recommend building this link as the very last step in the
-installation process. That way, users at your site will only see
-software in @file{/opt/gnu/progressive} when you're satisfied that the
-installation is complete and successful.
-
-@node Running, Paths, Installing, Top
-@unnumbered Running the Programs
-Any users who wish to run the Cygnus development tools will need to make
-sure the @code{PATH} environment variable will find them. If you create
-the symbolic link we recommend above, users who want to run the
-Developer's Kit---regardless of whether they need binaries for a ||HOST||,
-or for some other platform---can use settings like one of the following
-in their initialization files.
-
-@example
-@exdent For shells compatible with Bourne shell (e.g. @code{/bin/sh}, @code{bash}, or Korn shell):
-@cartouche
-@b{PATH=/opt/gnu/progressive/bin:$PATH}
-@b{export PATH}
-@end cartouche
-@end example
-
-@example
-@exdent For C shell:
-@cartouche
-@b{set path=(/opt/gnu/progressive/bin $path)}
-@end cartouche
-@end example
-
-@noindent
-You should also ensure that your @code{man} command can pick up the
-manual pages for these tools. Some @code{man} programs recognize a
-@code{MANPATH} environment variable. If your @code{man} program is one
-of these, users at your site can also include in their initialization
-file lines like
-
-@example
-@exdent For Bourne-compatible shells:
-@cartouche
-@b{MANPATH=/opt/gnu/progressive/man:$MANPATH:/opt/man}
-@b{export MANPATH}
-@end cartouche
-@end example
-
-@example
-@exdent For C shell:
-@cartouche
-@b{setenv MANPATH /opt/gnu/progressive/man:$MANPATH:/opt/man}
-@end cartouche
-@end example
-
-If your @code{man} program doesn't recognize @samp{MANPATH}, you may
-want to copy or link the files from
-@file{progressive/man/man1} into your system's
-@file{man/man1}. @refill
-
-@node Paths, Trouble, Running, Top
-@unnumbered Changing the Paths
-The binaries shipped by Cygnus are configured for installation under the
-directory @file{/opt/gnu}. If you wish to run the tools in another
-location, the best solution---and, to date, the only complete one---is
-to rebuild them from source. @xref{Rebuilding,,Rebuilding from Source}.
-
-In particular, @code{gcc} and the documentation browser @code{info} need
-to know the location of the distribution.
-
-@subheading GCC Paths
-@ifset FIXMES
-@quotation
-@emph{FIXME!} Add something about specs file?
-@end quotation
-@end ifset
-You can run the compiler @sc{gcc} without recompiling, even if you
-install the distribution in an alternate location, by first setting the
-environment variable @samp{GCC_EXEC_PREFIX}. This variable specifies
-where to find the executables, libraries, and data files used by the
-compiler. Its value will be different depending on which set of
-binaries you need to run. For example, if you install the Developer's Kit
-binaries under @file{/local} (instead of the default
-@file{/opt/gnu}), and you wish to run @sc{gcc} from there,
-you could set @samp{GCC_EXEC_PREFIX} as follows. (You can
-type the first two lines as a single line, if you like; the example
-is split using the line continuation character @samp{\} only
-to make it fit on the printed page.)
-
-@cartouche
-@example
-@b{GCC@t{_}EXEC@t{_}PREFIX=/local/progressive-||RELNO||/@t{\}
-lib/gcc/||TARGET||/||GCCvn||/}
-@b{export GCC@t{_}EXEC@t{_}PREFIX}
-@end example
-@end cartouche
-
-@noindent
-The example assumes you use a shell compatible with the Bourne shell; if
-you run the C shell, use the following instead. (Again, the line
-continuation character @samp{\} is only used for convenience in the
-example; feel free to use a single line.)
-
-@cartouche
-@example
-@b{setenv GCC@t{_}EXEC@t{_}PREFIX /local/progressive-||RELNO||/@t{\}
-lib/gcc/||TARGET||/||GCCvn||/}
-@end example
-@end cartouche
-
-@quotation
-@emph{Warning: The trailing slash @samp{/} is important}. The @code{gcc}
-program uses @samp{GCC_EXEC_PREFIX} simply as a prefix. If you omit the
-slash (or make any other mistakes in specifying the prefix), @code{gcc}
-will fail with a message beginning @samp{installation problem, cannot
-exec@dots{}}.
-@end quotation
-
-@subheading @code{info} Paths
-You can use the @w{@samp{--directory}} option, each time you run @code{info},
-to specify a non-default location for the documentation files. For
-example, if you read the distribution ||MEDIUM||s into @file{/local},
-you could run @code{info} as follows:
-
-@cartouche
-@example
-@b{info --directory /local/progressive-||RELNO||/info}
-@end example
-@end cartouche
-
-@quotation
-@emph{Warning:} the directory you specify with @code{--directory}
-@emph{must} contain at least the structured file called @code{dir},
-which specifies the menu structure that leads to the other documentation
-files.
-@end quotation
-
-You can also run @code{info} on a specific documentation file,
-regardless of its location, by giving the option @code{-file} followed
-by a pathname to the desired file; or you can use the command
-@code{g(@var{filename})} to the same effect, after entering the
-@code{info} program.
-
-@node Trouble, Rebuilding, Paths, Top
-@unnumbered Some Things that Might go Wrong
-
-We've tried to make the installation of your Developer's Kit as painless
-as possible. Still, some complications may arise. Here are suggestions
-for dealing with some of them.
-
-@menu
-* No Drive:: No Local ||MEDIUM|| Drive
-* Limited Space:: Not Enough Space
-* Install errors:: Error Messages from @code{Install}
-@end menu
-
-@node No Drive, Limited Space, Trouble, Trouble
-@unnumberedsec No Local ||MEDIUM|| Drive
-If your ||HOST|| doesn't have an appropriate ||MEDIUM|| drive, you may
-still be able to install your software. Check with your system
-administrator to see if another machine that runs Unix SVr4 at your site
-has a ||MEDIUM|| drive you can use. If so:
-
-@emph{If a shared filesystem is available} between the two machines, and
-it has enough space, see @ref{cross-install,,Installing with another
-machine's ||MEDIUM|| drive}.
-
-@node Limited Space, Install errors, No Drive, Trouble
-@unnumberedsec Not Enough Space
-If you don't have enough space to install all of the ||MEDIUM||
-distribution, you can instead extract only the compiled code, or only
-the source.
-
-The following table summarizes the approximate space (rounded up to the
-next megabyte) needed for source and binaries.
-There is a little overlap between the partial installations: the
-documentation, and documentation tools, are always installed.
-
-@table @r
-@item ||BD|| MB
-||HOST|| binaries
-
-@item ||SD|| MB
-source code for all programs
-
-@item ||DF|| MB
-total
-@end table
-
-You can easily extract these components independently of one another, by
-using the @samp{GNUDEVTsrc} or @samp{GNUDEVTbin} arguments to @code{pkgadd}.
-
-@node Install errors, , Limited Space, Trouble
-@unnumberedsec Error Messages from @code{Install}
-The @code{Install} script checks for many errors and inconsistencies in
-the way its arguments are used. The messages are meant to be
-self-explanatory. Here is a list of a few messages where further
-information might be useful:
-
-@ifset FIXMES
-@quotation
-@emph{FIXME!} These are probably bogus, they're basically from Cygnus
-@code{Install}.
-@end quotation
-@end ifset
-@table @code
-@item Cannot read from device @var{||MEDstr||}
-The error message ends with the ||MEDIUM|| device or directory that
-@code{pkgadd} was trying to use. Please check that it is the device you
-intended; possible causes of trouble might include leaving off the
-@samp{/dev/} prefix at the front of a device name. A typo in the
-device name might also cause this problem.
-
-If the problem is neither of these things, perhaps your ||MEDIUM||
-device can't read our ||MEDIUM||; @pxref{No Drive,,No Local ||MEDIUM||
-Drive}, for a discussion of how to use another machine's ||MEDIUM||
-drive.
-
-@item @dots{} This is a problem.
-@itemx Cannot cd to @var{installdir}
-@itemx I do not know why I cannot create @var{installdir}
-@itemx hello.c fails to run
-@itemx test-ioctl.c fails to run
-@itemx I do not know how to remove an arch called @dots{}
-These errors (the first covers anything that ends in @samp{This is a
-problem}) are from paranoia checks; they are issued for situations that
-other checks should have covered, or for unlikely situations that
-require further diagnosis.
-
-If you get one of these messages, please
-@itemize @bullet
-@item
-@strong{call the Cygnus hotline, +1 415 322 7836}, or
-@item
-send electronic mail to @samp{help@@cygnus.com}.
-@end itemize
-@end table
-
-@node Rebuilding, Removing, Trouble, Top
-@unnumbered Rebuilding From Source
-
-All Cygnus products are free software; your Developer's Kit includes
-complete source code for all programs.
-
-Cygnus Support has implemented an automatic configuration scheme to
-adapt the programs to different environments.
-
-Rebuilding the programs from source requires these steps:
-@enumerate
-@item
-configuration
-@item
-compilation
-@item
-installation
-@end enumerate
-
-For example, executing the following commands in sequence will rebuild
-and install a native version of all the tools in a nonstandard
-directory:
-
-@cartouche
-@example
-@b{cd progressive/src}
-@b{./configure ||HOSTstr|| -prefix=/local/gnu}
-@b{make clean all install}
-@end example
-@end cartouche
-
-@noindent
-We discuss each step in detail in the following sections.
-
-@menu
-* Configuration:: Configuration
-* Config Names:: Specifying Names for Hosts and Targets
-* configure Options:: @code{configure} Options
-* Compilation:: Compilation
-* Installation:: Installation
-@end menu
-
-@node Configuration, Config Names, Rebuilding, Rebuilding
-@unnumberedsec Configuration
-
-You can configure the software in this release by using the shell
-script called @code{configure}. The shell script requires one argument:
-the host type. There are also several possible options, including a
-@w{@samp{-target=}} option to configure for cross-system development.
-
-@node Config Names, configure Options, Configuration, Rebuilding
-@section Specifying Names for Hosts and Targets
-
-The specifications used for hosts and targets in the @code{configure}
-script are based on a three-part naming scheme, but some short predefined
-aliases are also supported. The full naming scheme encodes three pieces
-of information in the following pattern:
-
-@example
-@var{architecture}-@var{vendor}-@var{os}
-@end example
-
-@ifset FIXMES
-@quotation
-@emph{FIXME!} What is real alias for Solaris/SPARC?
-@end quotation
-@end ifset
-For example, you can use the alias @code{solar} as a @var{host} argument
-or in a @w{@samp{-target=@var{target}}} option, but the equivalent full name
-is @samp{sparc-sun-solaris2}.
-
-@quotation
-@emph{Warning:} @code{configure} can represent a very large number of
-combinations of architecture, vendor, and OS. There is by no means
-support for all possible combinations!
-@end quotation
-
-@node configure Options, Compilation, Config Names, Rebuilding
-@section @code{configure} Options
-
-This section summarizes the @code{configure} options and arguments.
-Your Developer's Kit contains full online documentation for the Cygnus
-configure system. @inforef{Using Configure,,configure.info}, to read
-about @code{configure} in more detail, including information on how the
-@code{configure} options relate to @file{Makefile} variables.
-
-@example
-configure @r{[}-prefix=@var{dest}@r{]}
- @r{[}-exec-prefix=@var{bindest}@r{]}
- @r{[}-srcdir=@var{path}@r{]}
- @r{[}-norecursion@r{]}
- @r{[}-target=@var{target}@r{]}
- @var{host}
-@end example
-
-@ifset FIXMES
-@quotation
-@emph{FIXME!} Show complete configure option list used for release?
-@end quotation
-@end ifset
-@table @code
-@item -prefix=@var{dest}
-@var{dest} is an installation directory @emph{path prefix},
-the root for the directories where @code{make install} will
-place things. After you configure with this option, @code{make install}
-will install info files in @file{@var{dest}/info}, man pages in
-@file{@var{dest}/man}, and---unless you also use
-@w{@samp{-exec-prefix}}---compiled programs in @file{@var{dest}/bin},
-and libraries in @file{@var{dest}/lib}.
-If you specify @w{@samp{-prefix=/local}}, for example, @code{make
-install} puts the development tools in @file{/local/bin}.
-
-@emph{WARNING:} the default @var{dest} path prefix in the source is not
-the same as the prefix for the preconfigured binaries distributed by Cygnus.
-
-@w{@samp{-prefix=/opt/gnu/progressive-||RELNO||}} was used to build this
-Cygnus Progressive Release. If you do not use @w{@samp{-prefix}}, the
-installation directory is @file{/usr/local}.
-
-@item -exec-prefix=@var{bindest}
-@w{@samp{-exec-prefix}} serves the same purpose as @w{@samp{-prefix}}, but
-affects only machine-dependent targets (compiled programs and
-libraries). Specifying both @w{@samp{-prefix}} and @w{@samp{-exec-prefix}}
-allows you to segregate machine-dependent files, so that
-machine-independent files can be shared.
-
-@emph{WARNING:} the default @var{bindest} path prefix in the source is not
-the same as the prefix for the preconfigured binaries distributed by Cygnus.
-
-@w{@samp{-exec-prefix=/opt/gnu/progressive-||RELNO||}} was
-used to build this Cygnus Progressive Release.
-If you do not use @w{@samp{-exec-prefix}}, the default directory for
-machine-dependent targets is whatever was specified with @file{-prefix}
-(by default, @file{/usr/local}).
-
-@item -srcdir=@var{path}
-@emph{Warning: This option is only supported if you use @sc{gnu}
-@code{make}} (which is included in this Cygnus Progressive--||RELNO|| release).
-Use this option to make configurations in directories separate from the
-source directories. @code{configure} writes configuration specific files
-in the current directory, but arranges for them to use the source in the
-directory @var{path}. @code{configure} will create directories under
-the working directory in parallel to the source directories below
-@var{path}. Among other things, you can use this to build (or maintain)
-several configurations simultaneously, in separate directories.
-
-@item -norecursion
-Configure only the directory level where @code{configure} is executed; do not
-propagate configuration to subdirectories.
-
-@item -target=@var{target}
-Configure the development tools for cross-development (compiling,
-debugging, or other processing) of programs running on the specified
-@var{target}. Without this option, programs are configured ``native'',
-that is, for managing programs that run on the same machine (@var{host})
-as the development tools themselves.
-
-There is no convenient way to generate a list of all available targets.
-
-@item @var{host} @dots{}
-Configure the development tools to run on the specified @var{host}.
-
-There is no convenient way to generate a list of all available hosts.
-@end table
-
-The @w{@samp{-prefix=@var{dest}}} and @w{@samp{-exec-prefix=@var{bindest}}}
-options are particularly important. If you don't specify a @var{dest}
-or @var{bindest} directory, the @file{Makefile} installs binaries in
-subdirectories of @file{/usr/local}. These options are important
-because the @var{dest} and @var{bindest} directories are used for
-several purposes:
-
-@enumerate
-@item
-@var{bindest} is the directory where binaries are installed.
-
-@item
-@var{bindest} is built into the compiler itself for the
-locations of @sc{gcc} specific include files, the locations of @sc{gcc}
-subprograms, and the location of the @sc{gcc} specific library
-@file{libgcc.a}.
-
-@item
-@var{dest} is compiled into @code{info} as the default directory
-for the documentation.
-
-@end enumerate
-
-@node Compilation, Installation, configure Options, Rebuilding
-@unnumberedsec Compilation
-
-After you've run @code{configure} (which writes the final
-@file{Makefile} in each directory), compilation is straightforward.
-To compile all the programs in the Developer's Kit, run:
-
-@cartouche
-@example
-@b{make}
-@end example
-@end cartouche
-
-The overall @file{Makefile} propagates the value of the @code{CC}
-variable explicitly, so that you can easily control the compiler used in
-this step. @code{CFLAGS} is treated the same way. For instance, to
-build the compiler a second time, using @sc{gcc} to compile itself
-(after building and installing it in the alternate directory
-@file{/local/gnu}), you might use
-
-@cartouche
-@example
-@b{make CC=/local/gnu/H-sun4/bin/gcc CFLAGS=-O}
-@end example
-@end cartouche
-
-The conventional targets @samp{all}, @samp{install}, and @samp{clean}
-are supported at all levels of @file{Makefile}. Other targets are
-supported as well, as appropriate in each directory; please read the
-individual @file{Makefile} for details. Each @file{Makefile} in the
-source directories includes ample comments to help you read it. If you
-are not familiar with @code{make}, refer to @ref{Overview,,Overview of
-@code{make}, make.info, GNU Make: A Program for Directing
-Recompilation}.
-
-@node Installation, , Compilation, Rebuilding
-@unnumberedsec Installation
-
-Whether you configure an alternative path using @code{-prefix}, or you
-use the default installation path @file{/usr/local}, you can install the
-software by executing:
-
-@cartouche
-@example
-@b{make install}
-@end example
-@end cartouche
-
-@node Removing, Cygnus-FSF, Rebuilding, Top
-@unnumbered Removing Parts of the Developer's Kit
-You can use the @code{pkgrm} command to remove either part of this
-release from where @code{pkgadd} installed it.
-
-To do this, call @code{pkgrm} with either or both of the arguments
-@samp{GNUDEVTkit} (to remove binaries) or @samp{GNUDEVTsrc} (to remove
-source). For example, suppose you never look at the source, and are
-running short of disk space; you can remove the source, while leaving
-the rest of the Progressive Release undisturbed, as follows:
-
-@cartouche
-@example
-eg# @b{/usr/sbin/pkgrm GNUDEVTsrc}
-@end example
-@end cartouche
-
-To remove the complete Progressive Release of the Developer's Kit from
-your system (if, eventually, you no longer want it), specify both
-package names as arguments to @code{pkgrm}
-
-@node Cygnus-FSF, Cygnus-Support, Removing, Top
-@unnumbered Cygnus Releases and the FSF
-
-Most of the tools in this Developer's Kit are originally from the Free
-Software Foundation (FSF). You can get versions of all these tools
-from the FSF as well as from Cygnus. In general, Cygnus Progressive
-Releases add to FSF software in the following ways:
-@c UPDATE! more differences bet Cygnus/FSF releases?
-
-@itemize @bullet
-@item
-Commercial support is available. Cygnus adds value to FSF releases in
-large measure by offering outstanding support services.
-@item
-Coordination. The tools in your Developer's Kit are certified to work
-together; you need not worry about tools being out of step with each other.
-@item
-Bug fixes. A Progressive Release includes many fixes, already integrated
-into the programs. Cygnus repairs bugs discovered during testing, and
-also tracks and includes bug fixes developed for other Cygnus customers
-or distributed over the Internet.
-@item
-Bug reporting. Cygnus releases include the tool @code{send_pr}, which
-you can use to make sure your problem reports receive prompt attention,
-and are also incorporated in our future tests.
-@item
-Documentation. Cygnus revises and adds to available FSF
-documentation to give you better descriptions of all the software tools.
-@item
-Stability. Cygnus tests (and uses) all the programs it releases.
-@end itemize
-
-@c FIXME! If we can say something about this, remove @ignore/@end ignore
-@c and fill in below:
-@ignore
-This particular Cygnus Progressive release differs from the nearest
-corresponding FSF distributions in these important details:
-
-FILL IN HERE!
-
-@end ignore
-
-@node Cygnus-Support, , Cygnus-FSF, Top
-@unnumbered About Cygnus Support
-
-Cygnus Support was founded in 1989 to provide commercial support for
-free software. Cygnus supplies products and services that benefit
-advanced development groups by allowing them to use state-of-the-art
-tools without having to maintain them. With Cygnus Support, sites that
-once were forced to do their own tool support can recover that valuable
-staff time. Former users of proprietary software now may choose
-supported free software, combining the advantages of both worlds.
-
-Free software is faster, more powerful, and more portable than its
-proprietary counterparts. It evolves faster because users who want to
-make improvements are free to do so. Cygnus tracks these
-improvements and integrates them into tested, stable versions ready
-for commercial use, then backs this software with comprehensive
-support.
-
-With Cygnus Support as your partner, you will have the software and
-the support you need to meet your business objectives. Cygnus
-is intimately familiar with this software from extensive experience
-using, debugging, and implementing it. You get direct access to the
-most qualified support people: the authors of the software.
-
-We provide ``vintage'' releases---the most stable versions, which have
-been though even more extensive use and testing---or up-to-the minute
-``progressive'' releases, for those who need the very latest version.
-
-Because all our improvements are also free software, you can
-distribute them widely within your organization, or to your customers,
-without extra cost.
-
-@sp 4
-
-@display
-Cygnus Support
-814 University Avenue
-Palo Alto, CA 94301, USA
-
-+1 415 322 3811
-hotline: +1 415 322 7836
-email: @code{info@@cygnus.com}
-fax: +1 415 322 3270
-@end display
-
-@bye
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename standards.info
-@settitle GNU Coding Standards
-@c %**end of header
-
-@ifinfo
-@format
-START-INFO-DIR-ENTRY
-* standards: (standards). GNU Project Coding Standards
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
-
-
-@setchapternewpage off
-
-@ifinfo
-Copyright (C) 1992 Free Software Foundation
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Free Software Foundation.
-@end ifinfo
-
-@titlepage
-@sp 10
-@titlefont{GNU Coding Standards}
-@author{Richard Stallman}
-@author{last updated 16 Jul 1992}
-@c Note date also appears below.
-@page
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1992 Free Software Foundation
-
-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 Free Software Foundation.
-@end titlepage
-
-@ifinfo
-@node Top, Reading Non-Free Code, (dir), (dir)
-@top Version
-
-Last updated 16 Jul 1992.
-@c Note date also appears above.
-@end ifinfo
-
-@menu
-* Reading Non-Free Code:: Referring to Proprietary Programs
-* Contributions:: Accepting Contributions
-* Change Logs:: Recording Changes
-* Compatibility:: Compatibility with Other Implementations
-* Makefiles:: Makefile Conventions
-* Configuration:: How Configuration Should Work
-* Source Language:: Using Languages Other Than C
-* Formatting:: Formatting Your Source Code
-* Comments:: Commenting Your Work
-* Syntactic Conventions:: Clean Use of C Constructs
-* Names:: Naming Variables and Functions
-* Using Extensions:: Using Non-standard Features
-* Semantics:: Program Behaviour for All Programs
-* Errors:: Formatting Error Messages
-* Libraries:: Library Behaviour
-* Portability:: Portability As It Applies to GNU
-* User Interfaces:: Standards for Command Line Interfaces
-* Documentation:: Documenting Programs
-* Releases:: Making Releases
-@end menu
-
-@node Reading Non-Free Code
-@chapter Referring to Proprietary Programs
-
-Don't in any circumstances refer to Unix source code for or during
-your work on GNU! (Or to any other proprietary programs.)
-
-If you have a vague recollection of the internals of a Unix program,
-this does not absolutely mean you can't write an imitation of it, but
-do try to organize the imitation internally along different lines,
-because this is likely to make the details of the Unix version
-irrelevant and dissimilar to your results.
-
-For example, Unix utilities were generally optimized to minimize
-memory use; if you go for speed instead, your program will be very
-different. You could keep the entire input file in core and scan it
-there instead of using stdio. Use a smarter algorithm discovered more
-recently than the Unix program. Eliminate use of temporary files. Do
-it in one pass instead of two (we did this in the assembler).
-
-Or, on the contrary, emphasize simplicity instead of speed. For some
-applications, the speed of today's computers makes simpler algorithms
-adequate.
-
-Or go for generality. For example, Unix programs often have static
-tables or fixed-size strings, which make for arbitrary limits; use
-dynamic allocation instead. Make sure your program handles NULs and
-other funny characters in the input files. Add a programming language
-for extensibility and write part of the program in that language.
-
-Or turn some parts of the program into independently usable libraries.
-Or use a simple garbage collector instead of tracking precisely when
-to free memory, or use a new GNU facility such as obstacks.
-
-
-@node Contributions
-@chapter Accepting Contributions
-
-If someone else sends you a piece of code to add to the program you are
-working on, we need legal papers to use it---the same sort of legal
-papers we will need to get from you. @emph{Each} significant
-contributor to a program must sign some sort of legal papers in order
-for us to have clear title to the program. The main author alone is not
-enough.
-
-So, before adding in any contributions from other people, tell us
-so we can arrange to get the papers. Then wait until we tell you
-that we have received the signed papers, before you actually use the
-contribution.
-
-This applies both before you release the program and afterward. If
-you receive diffs to fix a bug, and they make significant change, we
-need legal papers for it.
-
-You don't need papers for changes of a few lines here or there, since
-they are not significant for copyright purposes. Also, you don't need
-papers if all you get from the suggestion is some ideas, not actual code
-which you use. For example, if you write a different solution to the
-problem, you don't need to get papers.
-
-I know this is frustrating; it's frustrating for us as well. But if
-you don't wait, you are going out on a limb---for example, what if the
-contributor's employer won't sign a disclaimer? You might have to take
-that code out again!
-
-The very worst thing is if you forget to tell us about the other
-contributor. We could be very embarrassed in court some day as a
-result.
-
-@node Change Logs
-@chapter Change Logs
-
-Keep a change log for each directory, describing the changes made to
-source files in that directory. The purpose of this is so that people
-investigating bugs in the future will know about the changes that
-might have introduced the bug. Often a new bug can be found by
-looking at what was recently changed. More importantly, change logs
-can help eliminate conceptual inconsistencies between different parts
-of a program; they can give you a history of how the conflicting
-concepts arose.
-
-Use the Emacs command @kbd{M-x add-change} to start a new entry in the
-change log. An entry should have an asterisk, the name of the changed
-file, and then in parentheses the name of the changed functions,
-variables or whatever, followed by a colon. Then describe the changes
-you made to that function or variable.
-
-Separate unrelated entries with blank lines. When two entries
-represent parts of the same change, so that they work together, then
-don't put blank lines between them. Then you can omit the file name
-and the asterisk when successive entries are in the same file.
-
-Here are some examples:
-
-@example
-* register.el (insert-register): Return nil.
-(jump-to-register): Likewise.
-
-* sort.el (sort-subr): Return nil.
-
-* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
-Restart the tex shell if process is gone or stopped.
-(tex-shell-running): New function.
-
-* expr.c (store_one_arg): Round size up for move_block_to_reg.
-(expand_call): Round up when emitting USE insns.
-* stmt.c (assign_parms): Round size up for move_block_from_reg.
-@end example
-
-There's no need to describe here the full purpose of the changes or how
-they work together. It is better to put this explanation in comments in
-the code. That's why just ``New function'' is enough; there is a
-comment with the function in the source to explain what it does.
-
-However, sometimes it is useful to write one line to describe the
-overall purpose of a large batch of changes.
-
-You can think of the change log as a conceptual ``undo list'' which
-explains how earlier versions were different from the current version.
-People can see the current version; they don't need the change log
-to tell them what is in it. What they want from a change log is a
-clear explanation of how the earlier version differed.
-
-When you change the calling sequence of a function in a simple
-fashion, and you change all the callers of the function, there is no
-need to make individual entries for all the callers. Just write in
-the entry for the function being called, ``All callers changed.''
-
-When you change just comments or doc strings, it is enough to write an
-entry for the file, without mentioning the functions. Write just,
-``Doc fix.'' There's no need to keep a change log for documentation
-files. This is because documentation is not susceptible to bugs that
-are hard to fix. Documentation does not consist of parts that must
-interact in a precisely engineered fashion; to correct an error, you
-need not know the history of the erroneous passage.
-
-
-@node Compatibility
-@chapter Compatibility with Other Implementations
-
-With certain exceptions, utility programs and libraries for GNU should
-be upward compatible with those in Berkeley Unix, and upward compatible
-with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward
-compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior.
-
-When these standards conflict, it is useful to offer compatibility
-modes for each of them.
-
-@sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions. Feel
-free to make the extensions anyway, and include a @samp{--ansi} or
-@samp{--compatible} option to turn them off. However, if the extension
-has a significant chance of breaking any real programs or scripts,
-then it is not really upward compatible. Try to redesign its
-interface.
-
-When a feature is used only by users (not by programs or command
-files), and it is done poorly in Unix, feel free to replace it
-completely with something totally different and better. (For example,
-vi is replaced with Emacs.) But it is nice to offer a compatible
-feature as well. (There is a free vi clone, so we offer it.)
-
-Additional useful features not in Berkeley Unix are welcome.
-Additional programs with no counterpart in Unix may be useful,
-but our first priority is usually to duplicate what Unix already
-has.
-
-
-@node Makefiles
-@chapter Makefile Conventions
-
-This chapter describes conventions for writing Makefiles.
-
-@menu
-* Makefile Basics::
-* Standard Targets::
-* Command Variables::
-* Directory Variables::
-@end menu
-
-@node Makefile Basics
-@section General Conventions for Makefiles
-
-Every Makefile should contain this line:
-
-@example
-SHELL = /bin/sh
-@end example
-
-@noindent
-to avoid trouble on systems where the @code{SHELL} variable might be
-inherited from the environment.
-
-Don't assume that @file{.} is in the path for command execution. When
-you need to run programs that are a part of your package during the
-make, please make sure that it uses @file{./} if the program is built as
-part of the make or @file{$(srcdir)/} if the file is an unchanging part
-of the source code. Without one of these prefixes, the current search
-path is used.
-
-The distinction between @file{./} and @file{$(srcdir)/} is important
-when using the @samp{--srcdir} option to @file{configure}. A rule of
-the form:
-
-@example
-foo.1 : foo.man sedscript
- sed -e sedscript foo.man > foo.1
-@end example
-
-@noindent
-will fail when the current directory is not the source directory,
-because @file{foo.man} and @file{sedscript} are not in the current
-directory.
-
-Relying on @samp{VPATH} to find the source file will work in the case
-where there is a single dependency file, since the @file{make} automatic
-variable @samp{$<} will represent the source file wherever it is. A
-makefile target like
-
-@example
-foo.o : bar.c
- $(CC) $(CFLAGS) -I. -I$(srcdir) -c bar.c -o foo.o
-@end example
-
-@noindent
-should instead be written as
-
-@example
-foo.o : bar.c
- $(CC) $(CFLAGS) $< -o $@
-@end example
-
-@noindent
-in order to allow @samp{VPATH} to work correctly. When the target has
-multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
-way to make the rule work well. For example, the target above for
-@file{foo.1} is best written as:
-
-@example
-foo.1 : foo.man sedscript
- sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
-@end example
-
-@node Standard Targets
-@section Standard Targets for Users
-
-All GNU programs should have the following targets in their Makefiles:
-
-@table @samp
-@item all
-Compile the entire program.
-
-@item install
-Compile the program and copy the executables, libraries, and so on to
-the file names where they should reside for actual use. If there is a
-simple test to verify that a program is properly installed then run that
-test.
-
-Use @samp{-} before any command for installing a man page, so that
-@code{make} will ignore any errors. This is in case there are systems
-that don't have the Unix man page documentation system installed.
-
-@item clean
-Delete all files from the current directory that are normally created by
-building the program. Don't delete the files that record the
-configuration. Also preserve files that could be made by building, but
-normally aren't because the distribution comes with them.
-
-Delete @file{.dvi} files here if they are not part of the distribution.
-
-@item distclean
-Delete all files from the current directory that are created by
-configuring or building the program. If you have unpacked the source
-and built the program without creating any other files, @samp{make
-distclean} should leave only the files that were in the distribution.
-
-@item mostlyclean
-Like @samp{clean}, but may refrain from deleting a few files that people
-normally don't want to recompile. For example, the @samp{mostlyclean}
-target for GCC does not delete @file{libgcc.a}, because recompiling it
-is rarely necessary and takes a lot of time.
-
-@item realclean
-Delete everything from the current directory that can be reconstructed
-with this Makefile. This typically includes everything deleted by
-distclean, plus more: C source files produced by Bison, tags tables,
-info files, and so on.
-
-@item TAGS
-Update a tags table for this program.
-
-@item dist
-Create a distribution tar file for this program. The tar file should be
-set up so that the file names in the tar file start with a subdirectory
-name which is the name of the package it is a distribution for. This
-name can include the version number.
-
-For example, the distribution tar file of GCC version 1.40 unpacks into
-a subdirectory named @file{gcc-1.40}.
-
-The easiest way to do this is to create a subdirectory appropriately
-named, use @code{ln} or @code{cp} to install the proper files in it, and
-then @code{tar} that subdirectory.
-
-The @code{dist} target should explicitly depend on all non-source files
-that are in the distribution, to make sure they are up to date in the
-distribution. @xref{Releases}.
-
-@item check
-Perform self-tests (if any). The user must build the program before
-running the tests, but need not install the program; you should write
-the self-tests so that they work when the program is built but not
-installed.
-@end table
-
-@node Command Variables
-@section Variables for Specifying Commands
-
-Makefiles should provide variables for overriding certain commands, options,
-and so on.
-
-In particular, you should run most utility programs via variables.
-Thus, if you use Bison, have a variable named @code{BISON} whose default
-value is set with @samp{BISON = bison}, and refer to it with
-@code{$(BISON)} whenever you need to use Bison.
-
-File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
-so on, need not be referred to through variables in this way, since users
-don't need to replace them with other programs.
-
-Each program-name variable should come with an options variable that is
-used to supply options to the program. Append @samp{FLAGS} to the
-program-name variable name to get the options variable name---for
-example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to
-this rule, but we keep it because it is standard.) Use @code{CPPFLAGS}
-in any compilation command that runs the preprocessor, and use
-@code{LDFLAGS} in any compilation command that does linking as well as
-in any direct use of @code{ld}.
-
-If there are C compiler options that @emph{must} be used for proper
-compilation of certain files, do not include them in @code{CFLAGS}.
-Users expect to be able to specify @code{CFLAGS} freely themselves.
-Instead, arrange to pass the necessary options to the C compiler
-independently of @code{CFLAGS}, by writing them explicitly in the
-compilation commands or by defining an implicit rule, like this:
-
-@example
-CFLAGS = -g
-ALL_CFLAGS = $(CFLAGS) -I.
-.c.o:
- $(CC) -c $(ALL_CFLAGS) $(CPPFLAGS) $<
-@end example
-
-Do include the @samp{-g} option in @code{CFLAGS}, because that is not
-@emph{required} for proper compilation. You can consider it a default
-that is only recommended. If the package is set up so that it is
-compiled with GCC by default, then you might as well include @samp{-O}
-in the default value of @code{CFLAGS} as well.
-
-Every Makefile should define the variable @code{INSTALL}, which is the
-basic command for installing a file into the system.
-
-Every Makefile should also define variables @code{INSTALL_PROGRAM} and
-@code{INSTALL_DATA}. (The default for each of these should be
-@code{$(INSTALL)}.) Then it should use those variables as the commands
-for actual installation, for executables and nonexecutables
-respectively. Use these variables as follows:
-
-@example
-$(INSTALL_PROGRAM) foo $(bindir)/foo
-$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
-@end example
-
-@noindent
-Always use a file name, not a directory name, as the second argument of
-the installation commands. Use a separate command for each file to be
-installed.
-
-@node Directory Variables
-@section Variables for Installation Directories
-
-Installation directories should always be named by variables, so it is
-easy to install in a nonstandard place. The standard names for these
-variables are:
-
-@table @samp
-@item prefix
-A prefix used in constructing the default values of the variables listed
-below. The default value of @code{prefix} should be @file{/usr/local}
-(at least for now).
-
-@item exec_prefix
-A prefix used in constructing the default values of the some of the
-variables listed below. The default value of @code{exec_prefix} should
-be @code{$(prefix)}.
-
-Generally, @code{$(exec_prefix)} is used for directories that contain
-machine-specific files (such as executables and subroutine libraries),
-while @code{$(prefix)} is used directly for other directories.
-
-@item bindir
-The directory for installing executable programs that users can run.
-This should normally be @file{/usr/local/bin}, but it should be written
-as @file{$(exec_prefix)/bin}.
-
-@item libdir
-The directory for installing executable files to be run by the program
-rather than by users. Object files and libraries of object code should
-also go in this directory. The idea is that this directory is used for
-files that pertain to a specific machine architecture, but need not be
-in the path for commands. The value of @code{libdir} should normally be
-@file{/usr/local/lib}, but it should be written as
-@file{$(exec_prefix)/lib}.
-
-@item datadir
-The directory for installing read-only data files which the programs
-refer to while they run. This directory is used for files which are
-independent of the type of machine being used. This should normally be
-@file{/usr/local/lib}, but it should be written as
-@file{$(prefix)/lib}.
-
-@item statedir
-The directory for installing data files which the programs modify while
-they run. These files should be independent of the type of machine
-being used, and it should be possible to share them among machines at a
-network installation. This should normally be @file{/usr/local/lib},
-but it should be written as @file{$(prefix)/lib}.
-
-@item includedir
-The directory for installing @samp{#include} header files to be included
-by user programs. This should normally be @file{/usr/local/include},
-but it should be written as @file{$(prefix)/include}.
-
-Most compilers other than GCC do not look for header files in
-@file{/usr/local/include}. So installing the header files this way is
-only useful with GCC. Sometimes this is not a problem because some
-libraries are only really intended to work with GCC. But some libraries
-are intended to work with other compilers. They should install their
-header files in two places, one specified by @code{includedir} and one
-specified by @code{oldincludedir}.
-
-@item oldincludedir
-The directory for installing @samp{#include} header files for use with
-compilers other than GCC. This should normally be @file{/usr/include}.
-
-The Makefile commands should check whether the value of
-@code{oldincludedir} is empty. If it is, they should not try to use
-it; they should cancel the second installation of the header files.
-
-@item mandir
-The directory for installing the man pages (if any) for this package.
-It should include the suffix for the proper section of the
-manual---usually @samp{1} for a utility.
-
-@item man1dir
-The directory for installing section 1 man pages.
-@item man2dir
-The directory for installing section 2 man pages.
-@item @dots{}
-Use these names instead of @samp{mandir} if the package needs to install man
-pages in more than one section of the manual.
-
-@strong{Don't make the primary documentation for any GNU software be a
-man page. Write a manual in Texinfo instead. Man pages are just for
-the sake of people running GNU software on Unix, which is a secondary
-application only.}
-
-@item manext
-The file name extension for the installed man page. This should contain
-a period followed by the appropriate digit.
-
-@item infodir
-The directory for installing the info files for this package. By
-default, it should be @file{/usr/local/info}, but it should be written
-as @file{$(prefix)/info}.
-
-@item srcdir
-The directory for the sources being compiled. The value of this
-variable is normally inserted by the @code{configure} shell script.
-@end table
-
-For example:
-
-@example
-# Common prefix for installation directories.
-# NOTE: This directory must exist when you start installation.
-prefix = /usr/local
-exec_prefix = $(prefix)
-# Directory in which to put the executable for the command `gcc'
-bindir = $(exec_prefix)/bin
-# Directory in which to put the directories used by the compiler.
-libdir = $(exec_prefix)/lib
-# Directory in which to put the Info files.
-infodir = $(prefix)/info
-@end example
-
-If your program installs a large number of files into one of the
-standard user-specified directories, it might be useful to group them
-into a subdirectory particular to that program. If you do this, you
-should write the @code{install} rule to create these subdirectories.
-
-Do not expect the user to include the subdirectory name in the value of
-any of the variables listed above. The idea of having a uniform set of
-variable names for installation directories is to enable the user to
-specify the exact same values for several different GNU packages. In
-order for this to be useful, all the packages must be designed so that
-they will work sensibly when the user does so.
-
-@node Configuration
-@chapter How Configuration Should Work
-
-Each GNU distribution should come with a shell script named
-@code{configure}. This script is given arguments which describe the
-kind of machine and system you want to compile the program for.
-
-The @code{configure} script must record the configuration options so
-that they affect compilation.
-
-One way to do this is to make a link from a standard name such as
-@file{config.h} to the proper configuration file for the chosen system.
-If you use this technique, the distribution should @emph{not} contain a
-file named @file{config.h}. This is so that people won't be able to
-build the program without configuring it first.
-
-Another thing that @code{configure} can do is to edit the Makefile. If
-you do this, the distribution should @emph{not} contain a file named
-@file{Makefile}. Instead, include a file @file{Makefile.in} which
-contains the input used for editing. Once again, this is so that people
-won't be able to build the program without configuring it first.
-
-If @code{configure} does write the @file{Makefile}, then @file{Makefile}
-should have a target named @file{Makefile} which causes @code{configure}
-to be rerun, setting up the same configuration that was set up last
-time. The files that @code{configure} reads should be listed as
-dependencies of @file{Makefile}.
-
-All the files which are output from the @code{configure} script should
-have comments at the beginning explaining that they were generated
-automatically using @code{configure}. This is so that users won't think
-of trying to edit them by hand.
-
-The @code{configure} script should write a file named @file{config.status}
-which describes which configuration options were specified when the
-program was last configured. This file should be a shell script which,
-if run, will recreate the same configuration.
-
-The @code{configure} script should accept an option of the form
-@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
-(if it is not the current directory). This makes it possible to build
-the program in a separate directory, so that the actual source directory
-is not modified.
-
-If the user does not specify @samp{--srcdir}, then @code{configure} should
-check both @file{.} and @file{..} to see if it can find the sources. If
-it finds the sources in one of these places, it should use them from
-there. Otherwise, it should report that it cannot find the sources, and
-should exit with nonzero status.
-
-Usually the easy way to support @samp{--srcdir} is by editing a
-definition of @code{VPATH} into the Makefile. Some rules may need to
-refer explicitly to the specified source directory. To make this
-possible, @code{configure} can add to the Makefile a variable named
-@code{srcdir} whose value is precisely the specified directory.
-
-The @code{configure} script should also take an argument which specifies the
-type of system to build the program for. This argument should look like
-this:
-
-@example
-@var{cpu}-@var{company}-@var{system}
-@end example
-
-For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.
-
-The @code{configure} script needs to be able to decode all plausible
-alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1}
-would be a valid alias. So would @samp{sun3-bsd4.2}, since SunOS is
-basically @sc{BSD} and no other @sc{BSD} system is used on a Sun. For many
-programs, @samp{vax-dec-ultrix} would be an alias for
-@samp{vax-dec-bsd}, simply because the differences between Ultrix and
-@sc{BSD} are rarely noticeable, but a few programs might need to distinguish
-them.
-
-There is a shell script called @file{config.sub} that you can use
-as a subroutine to validate system types and canonicalize aliases.
-
-Other options are permitted to specify in more detail the software
-or hardware are present on the machine:
-
-@table @samp
-@item --with-@var{package}
-The package @var{package} will be installed, so configure this package
-to work with @var{package}.
-
-Possible values of @var{package} include @samp{x}, @samp{gnu-as} (or
-@samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and @samp{gdb}.
-
-@item --nfp
-The target machine has no floating point processor.
-
-@item --gas
-The target machine assembler is GAS, the GNU assembler.
-This is obsolete; use @samp{--with-gnu-as} instead.
-
-@item --x
-The target machine has the X Window system installed.
-This is obsolete; use @samp{--with-x} instead.
-@end table
-
-All @code{configure} scripts should accept all of these ``detail''
-options, whether or not they make any difference to the particular
-package at hand. In particular, they should accept any option that
-starts with @samp{--with-}. This is so users will be able to configure
-an entire GNU source tree at once with a single set of options.
-
-Packages that perform part of compilation may support cross-compilation.
-In such a case, the host and target machines for the program may be
-different. The @code{configure} script should normally treat the
-specified type of system as both the host and the target, thus producing
-a program which works for the same type of machine that it runs on.
-
-The way to build a cross-compiler, cross-assembler, or what have you, is
-to specify the option @samp{--host=@var{hosttype}} when running
-@code{configure}. This specifies the host system without changing the
-type of target system. The syntax for @var{hosttype} is the same as
-described above.
-
-Programs for which cross-operation is not meaningful need not accept the
-@samp{--host} option, because configuring an entire operating system for
-cross-operation is not a meaningful thing.
-
-Some programs have ways of configuring themselves automatically. If
-your program is set up to do this, your @code{configure} script can simply
-ignore most of its arguments.
-
-
-@node Source Language
-@chapter Using Languages Other Than C
-
-Using a language other than C is like using a non-standard feature: it
-will cause trouble for users. Even if GCC supports the other language,
-users may find it inconvenient to have to install the compiler for that
-other language in order to build your program. So please write in C.
-
-There are three exceptions for this rule:
-
-@itemize @bullet
-@item
-It is okay to use a special language if the same program contains an
-interpreter for that language.
-
-Thus, it is not a problem that GNU Emacs contains code written in Emacs
-Lisp, because it comes with a Lisp interpreter.
-
-@item
-It is okay to use another language in a tool specifically intended for
-use with that language.
-
-This is okay because the only people who want to build the tool will be
-those who have installed the other language anyway.
-
-@item
-If an application is not of extremely widespread interest, then perhaps
-it's not important if the application is inconvenient to install.
-@end itemize
-
-@node Formatting
-@chapter Formatting Your Source Code
-
-It is important to put the open-brace that starts the body of a C
-function in column zero, and avoid putting any other open-brace or
-open-parenthesis or open-bracket in column zero. Several tools look
-for open-braces in column zero to find the beginnings of C functions.
-These tools will not work on code not formatted that way.
-
-It is also important for function definitions to start the name of the
-function in column zero. This helps people to search for function
-definitions, and may also help certain tools recognize them. Thus,
-the proper format is this:
-
-@example
-static char *
-concat (s1, s2) /* Name starts in column zero here */
- char *s1, *s2;
-@{ /* Open brace in column zero here */
- @dots{}
-@}
-@end example
-
-@noindent
-or, if you want to use @sc{ANSI} C, format the definition like this:
-
-@example
-static char *
-concat (char *s1, char *s2)
-@{
- @dots{}
-@}
-@end example
-
-In @sc{ANSI} C, if the arguments don't fit nicely on one line,
-split it like this:
-
-@example
-int
-lots_of_args (int an_integer, long a_long, short a_short,
- double a_double, float a_float)
-@dots{}
-@end example
-
-For the body of the function, we prefer code formatted like this:
-
-@example
-if (x < foo (y, z))
- haha = bar[4] + 5;
-else
- @{
- while (z)
- @{
- haha += foo (z, z);
- z--;
- @}
- return ++x + bar ();
- @}
-@end example
-
-We find it easier to read a program when it has spaces before the
-open-parentheses and after the commas. Especially after the commas.
-
-When you split an expression into multiple lines, split it
-before an operator, not after one. Here is the right way:
-
-@example
-if (foo_this_is_long && bar > win (x, y, z)
- && remaining_condition)
-@end example
-
-Try to avoid having two operators of different precedence at the same
-level of indentation. For example, don't write this:
-
-@example
-mode = (inmode[j] == VOIDmode
- || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
- ? outmode[j] : inmode[j]);
-@end example
-
-Instead, use extra parentheses so that the indentation shows the nesting:
-
-@example
-mode = ((inmode[j] == VOIDmode
- || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
- ? outmode[j] : inmode[j]);
-@end example
-
-Insert extra parentheses so that Emacs will indent the code properly.
-For example, the following indentation looks nice if you do it by hand,
-but Emacs would mess it up:
-
-@example
-v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
- + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
-@end example
-
-But adding a set of parentheses solves the problem:
-
-@example
-v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
- + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
-@end example
-
-Format do-while statements like this:
-
-@example
-do
- @{
- a = foo (a);
- @}
-while (a > 0);
-@end example
-
-Please use formfeed characters (control-L) to divide the program into
-pages at logical places (but not within a function). It does not matter
-just how long the pages are, since they do not have to fit on a printed
-page. The formfeeds should appear alone on lines by themselves.
-
-
-@node Comments
-@chapter Commenting Your Work
-
-Every program should start with a comment saying briefly what it is for.
-Example: @samp{fmt - filter for simple filling of text}.
-
-Please put a comment on each function saying what the function does,
-what sorts of arguments it gets, and what the possible values of
-arguments mean and are used for. It is not necessary to duplicate in
-words the meaning of the C argument declarations, if a C type is being
-used in its customary fashion. If there is anything nonstandard about
-its use (such as an argument of type @code{char *} which is really the
-address of the second character of a string, not the first), or any
-possible values that would not work the way one would expect (such as,
-that strings containing newlines are not guaranteed to work), be sure
-to say so.
-
-Also explain the significance of the return value, if there is one.
-
-Please put two spaces after the end of a sentence in your comments, so
-that the Emacs sentence commands will work. Also, please write
-complete sentences and capitalize the first word. If a lower-case
-identifer comes at the beginning of a sentence, don't capitalize it!
-Changing the spelling makes it a different identifier. If you don't
-like starting a sentence with a lower case letter, write the sentence
-differently (e.g. ``The identifier lower-case is @dots{}'').
-
-The comment on a function is much clearer if you use the argument
-names to speak about the argument values. The variable name itself
-should be lower case, but write it in upper case when you are speaking
-about the value rather than the variable itself. Thus, ``the inode
-number @var{node_num}'' rather than ``an inode''.
-
-There is usually no purpose in restating the name of the function in
-the comment before it, because the reader can see that for himself.
-There might be an exception when the comment is so long that the function
-itself would be off the bottom of the screen.
-
-There should be a comment on each static variable as well, like this:
-
-@example
-/* Nonzero means truncate lines in the display;
- zero means continue them. */
-
-int truncate_lines;
-@end example
-
-Every @samp{#endif} should have a comment, except in the case of short
-conditionals (just a few lines) that are not nested. The comment should
-state the condition of the conditional that is ending, @emph{including
-its sense}. @samp{#else} should have a comment describing the condition
-@emph{and sense} of the code that follows. For example:
-
-@example
-#ifdef foo
- @dots{}
-#else /* not foo */
- @dots{}
-#endif /* not foo */
-@end example
-
-@noindent
-but, by contrast, write the comments this way for a @samp{#ifndef}:
-
-@example
-#ifndef foo
- @dots{}
-#else /* foo */
- @dots{}
-#endif /* foo */
-@end example
-
-
-@node Syntactic Conventions
-@chapter Clean Use of C Constructs
-
-Please explicitly declare all arguments to functions.
-Don't omit them just because they are ints.
-
-Declarations of external functions and functions to appear later
-in the source file should all go in one place near the beginning of
-the file (somewhere before the first function definition in the file),
-or else should go in a header file. Don't put extern declarations
-inside functions.
-
-Don't declare multiple variables in one declaration that spans lines.
-Start a new declaration on each line, instead. For example, instead
-of this:
-
-@example
-int foo,
- bar;
-@end example
-
-@noindent
-write either this:
-
-@example
-int foo, bar;
-@end example
-
-@noindent
-or this:
-
-@example
-int foo;
-int bar;
-@end example
-
-@noindent
-(If they are global variables, each should have a comment preceding it
-anyway.)
-
-When you have an if-else statement nested in another if statement,
-always put braces around the if-else. Thus, never write like this:
-
-@example
-if (foo)
- if (bar)
- win ();
- else
- lose ();
-@end example
-
-@noindent
-always like this:
-
-@example
-if (foo)
- @{
- if (bar)
- win ();
- else
- lose ();
- @}
-@end example
-
-If you have an if statement nested inside of an else statement,
-either write @code{else if} on one line, like this,
-
-@example
-if (foo)
- @dots{}
-else if (bar)
- @dots{}
-@end example
-
-@noindent
-with its then-part indented like the preceding then-part, or write the
-nested if within braces like this:
-
-@example
-if (foo)
- @dots{}
-else
- @{
- if (bar)
- @dots{}
- @}
-@end example
-
-Don't declare both a structure tag and variables or typedefs in the
-same declaration. Instead, declare the structure tag separately
-and then use it to declare the variables or typedefs.
-
-Try to avoid assignments inside if-conditions. For example, don't
-write this:
-
-@example
-if ((foo = (char *) malloc (sizeof *foo)) == 0)
- fatal ("virtual memory exhausted");
-@end example
-
-@noindent
-instead, write this:
-
-@example
-foo = (char *) malloc (sizeof *foo);
-if (foo == 0)
- fatal ("virtual memory exhausted");
-@end example
-
-Don't make the program ugly to placate lint. Please don't insert any
-casts to void. Zero without a cast is perfectly fine as a null
-pointer constant.
-
-
-@node Names
-@chapter Naming Variables and Functions
-
-Please use underscores to separate words in a name, so that the Emacs
-word commands can be useful within them. Stick to lower case; reserve
-upper case for macros and enum constants, and for name-prefixes that
-follow a uniform convention.
-
-For example, you should use names like @code{ignore_space_change_flag};
-don't use names like @code{iCantReadThis}.
-
-Variables that indicate whether command-line options have been
-specified should be named after the meaning of the option, not after
-the option-letter. A comment should state both the exact meaning of
-the option and its letter. For example,
-
-@example
-/* Ignore changes in horizontal whitespace (-b). */
-int ignore_space_change_flag;
-@end example
-
-When you want to define names with constant integer values, use
-@code{enum} rather than @samp{#define}. GDB knows about enumeration
-constants.
-
-Use file names of 14 characters or less, to avoid creating gratuitous
-problems on System V.
-
-
-@node Using Extensions
-@chapter Using Non-standard Features
-
-Many GNU facilities that already exist support a number of convenient
-extensions over the comparable Unix facilities. Whether to use these
-extensions in implementing your program is a difficult question.
-
-On the one hand, using the extensions can make a cleaner program.
-On the other hand, people will not be able to build the program
-unless the other GNU tools are available. This might cause the
-program to work on fewer kinds of machines.
-
-With some extensions, it might be easy to provide both alternatives.
-For example, you can define functions with a ``keyword'' @code{INLINE}
-and define that as a macro to expand into either @code{inline} or
-nothing, depending on the compiler.
-
-In general, perhaps it is best not to use the extensions if you can
-straightforwardly do without them, but to use the extensions if they
-are a big improvement.
-
-An exception to this rule are the large, established programs (such as
-Emacs) which run on a great variety of systems. Such programs would
-be broken by use of GNU extensions.
-
-Another exception is for programs that are used as part of
-compilation: anything that must be compiled with other compilers in
-order to bootstrap the GNU compilation facilities. If these require
-the GNU compiler, then no one can compile them without having them
-installed already. That would be no good.
-
-Since most computer systems do not yet implement @sc{ANSI} C, using the
-@sc{ANSI} C features is effectively using a GNU extension, so the
-same considerations apply. (Except for @sc{ANSI} features that we
-discourage, such as trigraphs---don't ever use them.)
-
-@node Semantics
-@chapter Program Behaviour for All Programs
-
-Avoid arbitrary limits on the length or number of @emph{any} data
-structure, including filenames, lines, files, and symbols, by allocating
-all data structures dynamically. In most Unix utilities, ``long lines
-are silently truncated''. This is not acceptable in a GNU utility.
-
-Utilities reading files should not drop NUL characters, or any other
-nonprinting characters @emph{including those with codes above 0177}. The
-only sensible exceptions would be utilities specifically intended for
-interface to certain types of printers that can't handle those characters.
-
-Check every system call for an error return, unless you know you wish to
-ignore errors. Include the system error text (from @code{perror} or
-equivalent) in @emph{every} error message resulting from a failing
-system call, as well as the name of the file if any and the name of the
-utility. Just ``cannot open foo.c'' or ``stat failed'' is not
-sufficient.
-
-Check every call to @code{malloc} or @code{realloc} to see if it
-returned zero. Check @code{realloc} even if you are making the block
-smaller; in a system that rounds block sizes to a power of 2,
-@code{realloc} may get a different block if you ask for less space.
-
-In Unix, @code{realloc} can destroy the storage block if it returns
-zero. GNU @code{realloc} does not have this bug: if it fails, the
-original block is unchanged. Feel free to assume the bug is fixed. If
-you wish to run your program on Unix, and wish to avoid lossage in this
-case, you can use the GNU @code{malloc}.
-
-You must expect @code{free} to alter the contents of the block that was
-freed. Anything you want to fetch from the block, you must fetch before
-calling @code{free}.
-
-Use @code{getopt_long} to decode arguments, unless the argument syntax
-makes this unreasonable.
-
-When static storage is to be written in during program execution, use
-explicit C code to initialize it. Reserve C initialized declarations
-for data that will not be changed.
-
-Try to avoid low-level interfaces to obscure Unix data structures (such
-as file directories, utmp, or the layout of kernel memory), since these
-are less likely to work compatibly. If you need to find all the files
-in a directory, use @code{readdir} or some other high-level interface.
-These will be supported compatibly by GNU.
-
-By default, the GNU system will provide the signal handling functions of
-@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use
-these.
-
-In error checks that detect ``impossible'' conditions, just abort.
-There is usually no point in printing any message. These checks
-indicate the existence of bugs. Whoever wants to fix the bugs will have
-to read the source code and run a debugger. So explain the problem with
-comments in the source. The relevant data will be in variables, which
-are easy to examine with the debugger, so there is no point moving them
-elsewhere.
-
-
-@node Errors
-@chapter Formatting Error Messages
-
-Error messages from compilers should look like this:
-
-@example
-@var{source-file-name}:@var{lineno}: @var{message}
-@end example
-
-Error messages from other noninteractive programs should look like this:
-
-@example
-@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
-@end example
-
-@noindent
-when there is an appropriate source file, or like this:
-
-@example
-@var{program}: @var{message}
-@end example
-
-@noindent
-when there is no relevant source file.
-
-In an interactive program (one that is reading commands from a
-terminal), it is better not to include the program name in an error
-message. The place to indicate which program is running is in the
-prompt or with the screen layout. (When the same program runs with
-input from a source other than a terminal, it is not interactive and
-would do best to print error messages using the noninteractive style.)
-
-The string @var{message} should not begin with a capital letter when
-it follows a program name and/or filename. Also, it should not end
-with a period.
-
-Error messages from interactive programs, and other messages such as
-usage messages, should start with a capital letter. But they should not
-end with a period.
-
-
-@node Libraries
-@chapter Library Behaviour
-
-Try to make library functions reentrant. If they need to do dynamic
-storage allocation, at least try to avoid any nonreentrancy aside from
-that of @code{malloc} itself.
-
-Here are certain name conventions for libraries, to avoid name
-conflicts.
-
-Choose a name prefix for the library, more than two characters long.
-All external function and variable names should start with this
-prefix. In addition, there should only be one of these in any given
-library member. This usually means putting each one in a separate
-source file.
-
-An exception can be made when two external symbols are always used
-together, so that no reasonable program could use one without the
-other; then they can both go in the same file.
-
-External symbols that are not documented entry points for the user
-should have names beginning with @samp{_}. They should also contain
-the chosen name prefix for the library, to prevent collisions with
-other libraries. These can go in the same files with user entry
-points if you like.
-
-Static functions and variables can be used as you like and need not
-fit any naming convention.
-
-
-@node Portability
-@chapter Portability As It Applies to GNU
-
-Much of what is called ``portability'' in the Unix world refers to
-porting to different Unix versions. This is a secondary consideration
-for GNU software, because its primary purpose is to run on top of one
-and only one kernel, the GNU kernel, compiled with one and only one C
-compiler, the GNU C compiler. The amount and kinds of variation among
-GNU systems on different cpu's will be like the variation among Berkeley
-4.3 systems on different cpu's.
-
-All users today run GNU software on non-GNU systems. So supporting a
-variety of non-GNU systems is desirable; simply not paramount.
-The easiest way to achieve portability to a reasonable range of systems
-is to use Autoconf. It's unlikely that your program needs to know more
-information about the host machine than Autoconf can provide, simply
-because most of the programs that need such knowledge have already been
-written.
-
-It is difficult to be sure exactly what facilities the GNU kernel
-will provide, since it isn't finished yet. Therefore, assume you can
-use anything in 4.3; just avoid using the format of semi-internal data
-bases (e.g., directories) when there is a higher-level alternative
-(readdir).
-
-You can freely assume any reasonably standard facilities in the C
-language, libraries or kernel, because we will find it necessary to
-support these facilities in the full GNU system, whether or not we
-have already done so. The fact that there may exist kernels or C
-compilers that lack these facilities is irrelevant as long as the GNU
-kernel and C compiler support them.
-
-It remains necessary to worry about differences among cpu types, such
-as the difference in byte ordering and alignment restrictions. It's
-unlikely that 16-bit machines will ever be supported by GNU, so there
-is no point in spending any time to consider the possibility that an
-int will be less than 32 bits.
-
-You can assume that all pointers have the same format, regardless
-of the type they point to, and that this is really an integer.
-There are some weird machines where this isn't true, but they aren't
-important; don't waste time catering to them. Besides, eventually
-we will put function prototypes into all GNU programs, and that will
-probably make your program work even on weird machines.
-
-Since some important machines (including the 68000) are big-endian,
-it is important not to assume that the address of an int object
-is also the address of its least-significant byte. Thus, don't
-make the following mistake:
-
-@example
-int c;
-@dots{}
-while ((c = getchar()) != EOF)
- write(file_descriptor, &c, 1);
-@end example
-
-You can assume that it is reasonable to use a meg of memory. Don't
-strain to reduce memory usage unless it can get to that level. If
-your program creates complicated data structures, just make them in
-core and give a fatal error if malloc returns zero.
-
-If a program works by lines and could be applied to arbitrary
-user-supplied input files, it should keep only a line in memory, because
-this is not very hard and users will want to be able to operate on input
-files that are bigger than will fit in core all at once.
-
-
-@node User Interfaces
-@chapter Standards for Command Line Interfaces
-
-Please don't make the behavior of a utility depend on the name used
-to invoke it. It is useful sometimes to make a link to a utility
-with a different name, and that should not change what it does.
-
-Instead, use a run time option or a compilation switch or both
-to select among the alternate behaviors.
-
-It is a good idea to follow the @sc{POSIX} guidelines for the
-command-line options of a program. The easiest way to do this is to use
-@code{getopt} to parse them. Note that the GNU version of @code{getopt}
-will normally permit options anywhere among the arguments unless the
-special argument @samp{--} is used. This is not what @sc{POSIX}
-specifies; it is a GNU extension.
-
-Please define long-named options that are equivalent to the
-single-letter Unix-style options. We hope to make GNU more user
-friendly this way. This is easy to do with the GNU function
-@code{getopt_long}.
-
-It is usually a good idea for file names given as ordinary arguments
-to be input files only; any output files would be specified using
-options (preferably @samp{-o}). Even if you allow an output file name
-as an ordinary argument for compatibility, try to provide a suitable
-option as well. This will lead to more consistency among GNU
-utilities, so that there are fewer idiosyncracies for users to
-remember.
-
-Programs should support an option @samp{--version} which prints the
-program's version number, and an option @samp{--help} which prints
-option usage information.
-
-
-@node Documentation
-@chapter Documenting Programs
-
-Please use Texinfo for documenting GNU programs. See the Texinfo
-manual, either the hardcopy or the version in the GNU Emacs Info
-subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g. those
-under the @file{man/} directory in the GNU Emacs Distribution) for
-examples.
-
-The title page of the manual should state the version of the program
-which the manual applies to. The Top node of the manual should also
-contain this information. If the manual is changing more frequently
-than or independent of the program, also state a version number for
-the manual in both of these places.
-
-The manual should document all command-line arguments and all
-commands. It should give examples of their use. But don't organize
-the manual as a list of features. Instead, organize it by the
-concepts a user will have before reaching that point in the manual.
-Address the goals that a user will have in mind, and explain how to
-accomplish them.
-
-In addition to its manual, the package should have a file named
-@file{NEWS} which contains a list of user-visible changes worth
-mentioning. In each new release, add items to the front of the file,
-and identify the version they pertain to. Don't discard old items.
-This way, a user upgrading from any previous version can see what
-is new.
-
-@node Releases
-@chapter Making Releases
-
-Package the distribution of Foo version 69.96 in a tar file named
-@file{foo-69.96.tar}. It should unpack into a subdirectory named
-@file{foo-69.96}.
-
-Building and installing the program should never modify any of the files
-contained in the distribution. This means that all the files that form
-part of the program in any way must be classified into @dfn{source
-files} and @dfn{non-source files}. Source files are written by humans
-and never changed automatically; non-source files are produced from
-source files by programs under the control of the Makefile.
-
-Naturally, all the source files must be in the distribution. It is okay
-to include non-source files in the distribution, provided they are
-up-to-date and machine-independent, so that building the distribution
-normally will never modify them. We commonly included non-source files
-produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid
-unnecessary dependencies between our distributions, so that users can
-install whichever packages they want to install.
-
-Non-source files that might actually be modified by building and
-installing the program should @strong{never} be included in the
-distribution. So if you do distribute non-source files, always make
-sure they are up to date when you make a new distribution.
-
-Make sure that no file name in the distribution is no more than 14
-characters long. Nowadays, there are systems that adhere to a foolish
-interpretation of the POSIX standard which holds that they should refuse
-to open a longer name, rather than truncating as they did in the past.
-
-Try to make sure that all the file names will be unique on MS-DOG. A
-name on MS-DOG consists of up to 8 characters, optionally followed by a
-period and up to three characters. MS-DOG will truncate extra
-characters both before and after the period. Thus,
-@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
-are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
-distinct.
-
-Include in your distribution a copy of the @file{texinfo.tex} you used
-to test print any @file{*.texinfo} files.
-
-Likewise, if your program uses small GNU software packages like regex,
-getopt, obstack, or termcap, include them in the distribution file.
-Leaving them out would make the distribution file a little smaller at
-the expense of possible inconvenience to a user who doesn't know what
-other files to get.
-@bye
projects / external / binutils.git / commitdiff