From e7a8768db643c2003230f4be997ee2c63c98f1da Mon Sep 17 00:00:00 2001 From: "K. Richard Pixley" Date: Tue, 8 Dec 1992 05:27:22 +0000 Subject: [PATCH] recording file death --- DOC.configure | 573 ----------------- README.configure | 573 ----------------- cfg-paper.texi | 740 ---------------------- config.subr | 575 ----------------- configdj.bat | 14 - configure.man | 118 ---- configure.texi | 1367 ---------------------------------------- solaris-inst.texinfo | 1709 -------------------------------------------------- standards.texi | 1446 ------------------------------------------ 9 files changed, 7115 deletions(-) delete mode 100755 DOC.configure delete mode 100755 README.configure delete mode 100644 cfg-paper.texi delete mode 100755 config.subr delete mode 100755 configdj.bat delete mode 100644 configure.man delete mode 100644 configure.texi delete mode 100755 solaris-inst.texinfo delete mode 100644 standards.texi diff --git a/DOC.configure b/DOC.configure deleted file mode 100755 index c77813d..0000000 --- a/DOC.configure +++ /dev/null @@ -1,573 +0,0 @@ - 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. diff --git a/README.configure b/README.configure deleted file mode 100755 index c77813d..0000000 --- a/README.configure +++ /dev/null @@ -1,573 +0,0 @@ - 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. diff --git a/cfg-paper.texi b/cfg-paper.texi deleted file mode 100644 index b39d8f8..0000000 --- a/cfg-paper.texi +++ /dev/null @@ -1,740 +0,0 @@ -\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: diff --git a/config.subr b/config.subr deleted file mode 100755 index def198a..0000000 --- a/config.subr +++ /dev/null @@ -1,575 +0,0 @@ -#!/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 diff --git a/configdj.bat b/configdj.bat deleted file mode 100755 index a2bc8a2..0000000 --- a/configdj.bat +++ /dev/null @@ -1,14 +0,0 @@ -@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 .. diff --git a/configure.man b/configure.man deleted file mode 100644 index 87d27d7..0000000 --- a/configure.man +++ /dev/null @@ -1,118 +0,0 @@ -.\" -*- 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). diff --git a/configure.texi b/configure.texi deleted file mode 100644 index b99c519..0000000 --- a/configure.texi +++ /dev/null @@ -1,1367 +0,0 @@ -\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{") diff --git a/solaris-inst.texinfo b/solaris-inst.texinfo deleted file mode 100755 index 45b24a9..0000000 --- a/solaris-inst.texinfo +++ /dev/null @@ -1,1709 +0,0 @@ -\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 diff --git a/standards.texi b/standards.texi deleted file mode 100644 index 69eaa53..0000000 --- a/standards.texi +++ /dev/null @@ -1,1446 +0,0 @@ -\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 -- 2.7.4