diff options
Diffstat (limited to 'contrib/binutils/etc')
| -rw-r--r-- | contrib/binutils/etc/cfg-paper.texi | 717 | ||||
| -rw-r--r-- | contrib/binutils/etc/configure.man | 166 | ||||
| -rw-r--r-- | contrib/binutils/etc/configure.texi | 1830 |
3 files changed, 0 insertions, 2713 deletions
diff --git a/contrib/binutils/etc/cfg-paper.texi b/contrib/binutils/etc/cfg-paper.texi deleted file mode 100644 index bcfbb31e13f8..000000000000 --- a/contrib/binutils/etc/cfg-paper.texi +++ /dev/null @@ -1,717 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename cfg-paper.info -@settitle On Configuring Development Tools -@c %**end of header -@setchapternewpage off - -@ifinfo -This document attempts to describe the general concepts behind -configuration of the @sc{gnu} Development Tools. -It also discusses common usage. - -Copyright (C) 1991, 1992, 1994 Cygnus Support -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by Cygnus Support. -@end ifinfo - -@titlepage -@sp 10 -@title{On Configuring Development Tools} -@author{K. Richard Pixley, @code{rich@@cygnus.com}} -@author{Cygnus Support} -@page - -@vskip 0pt plus 1filll -Copyright @copyright{} 1991, 1992, 1994 Cygnus Support - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by Cygnus Support. -@end titlepage - -@ifinfo -@format -START-INFO-DIR-ENTRY -* configuration: (cfg-paper). Some theory on configuring source. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@node top, Some Basic Terms, (dir), (dir) - -@ifinfo -This document attempts to describe the general concepts behind -configuration of the @sc{gnu} Development Tools. -It also discusses common usage. -@end ifinfo - -@menu -* Some Basic Terms:: Some Basic Terms -* Specifics.:: Specifics -* Building Development Environments:: Building Development Environments -* A Walk Through:: A Walk Through -* Final Notes:: Final Notes -* Index:: Index - - --- The Detailed Node Listing --- - -Some Basic Terms - -* Host Environments:: Host Environments -* Configuration Time Options:: Configuration Time Options - -A Walk Through - -* Native Development Environments:: Native Development Environments -* Emulation Environments:: Emulation Environments -* Simple Cross Environments:: Simple Cross Environments -* Crossing Into Targets:: Crossing Into Targets -* Canadian Cross:: Canadian Cross - -Final Notes - -* Hacking Configurations:: Hacking Configurations -@end menu - -@node Some Basic Terms, Specifics., top, top -@chapter Some Basic Terms - -There are a lot of terms that are frequently used when discussing -development tools. Most of the common terms have been used for many -different concepts such that their meanings have become ambiguous to the -point of being confusing. Typically, we only guess at their meanings -from context and we frequently guess wrong. - -This document uses very few terms by comparison. The intent is to make -the concepts as clear as possible in order to convey the usage and -intent of these tools. - -@emph{Programs} run on @emph{machines}. Programs are very nearly always -written in @emph{source}. Programs are @emph{built} from source. -@emph{Compilation} is a process that is frequently, but not always, used -when building programs. -@cindex Programs -@cindex Machines -@cindex Source -@cindex Building -@cindex Compilation - -@menu -* Host Environments:: Host Environments -* Configuration Time Options:: Configuration Time Options -@end menu - -@node Host Environments, Configuration Time Options, Some Basic Terms, Some Basic Terms -@section Host Environments - -@cindex host -In this document, the word @emph{host} refers to the environment in -which the source in question will be compiled. @emph{host} and -@emph{host name} have nothing to do with the proper name of your host, -like @emph{ucbvax}, @emph{prep.ai.mit.edu} or @emph{att.com}. Instead -they refer to things like @emph{sun4} and @emph{dec3100}. - -Forget for a moment that this particular directory of source is the -source for a development environment. Instead, pretend that it is the -source for a simpler, more mundane, application, say, a desk calculator. - -Source that can be compiled in more than one environment, generally -needs to be set up for each environment explicitly. Here we refer to -that process as configuration. That is, we configure the source for a -host. - -For example, if we wanted to configure our mythical desk calculator to -compile on a SparcStation, we might configure for host sun4. With our -configuration system: - -@example -cd desk-calculator ; ./configure sun4 -@end example - -@noindent -does the trick. @code{configure} is a shell script that sets up Makefiles, -subdirectories, and symbolic links appropriate for compiling the source -on a sun4. - -The @emph{host} environment does not necessarily refer to the machine on -which the tools are built. It is possible to provide a sun3 development -environment on a sun4. If we wanted to use a cross compiler on the sun4 -to build a program intended to be run on a sun3, we would configure the -source for sun3. - -@example -cd desk-calculator ; ./configure sun3 -@end example - -@noindent -The fact that we are actually building the program on a sun4 makes no -difference if the sun3 cross compiler presents an environment that looks -like a sun3 from the point of view of the desk calculator source code. -Specifically, the environment is a sun3 environment if the header files, -predefined symbols, and libraries appear as they do on a sun3. - -Nor does the host environment refer to the the machine on which the -program to be built will run. It is possible to provide a sun3 -emulation environment on a sun4 such that programs built in a sun3 -development environment actually run on the sun4. This technique is -often used within individual programs to remedy deficiencies in the host -operating system. For example, some operating systems do not provide -the @code{bcopy} function and so it is emulated using the -@code{memcpy} funtion. - -Host environment simply refers to the environment in which the program -will be built from the source. - - -@node Configuration Time Options, , Host Environments, Some Basic Terms -@section Configuration Time Options - -Many programs have compile time options. That is, features of the -program that are either compiled into the program or not based on a -choice made by the person who builds the program. We refer to these as -@emph{configuration options}. For example, our desk calculator might be -capable of being compiled into a program that either uses infix notation -or postfix as a configuration option. For a sun3, to choose infix you -might use: - -@example -./configure sun3 --enable-notation=infix -@end example - -@noindent -while for a sun4 with postfix you might use: - -@example -./configure sun4 --enable-notation=postfix -@end example - -If we wanted to build both at the same time, the intermediate pieces -used in the build process must be kept separate. - -@example -mkdir ../objdir.sun4 -(cd ../objdir.sun4 ; ../configure sun4 --enable-notation=postfix --srcdir=../src) -mkdir ../objdir.sun3 -(cd ../objdir.sun3 ; ../configure sun3 --enable-notation=infix --srcdir=../src) -@end example - -@noindent -will create subdirectories for the intermediate pieces of the sun4 and -sun3 configurations. This is necessary as previous systems were only -capable of one configuration at a time. Otherwise, a second -configuration would write over the first. We've chosen to retain this -behaviour so the obj directories and the @code{--srcdir} configuration -option are necessary to get the new behaviour. The order of the -arguments doesn't matter. There should be exactly one argument without -a leading @samp{-} and that argument will be assumed to be the host -name. - -From here on the examples will assume that you want to build the tools -@emph{in place} and won't show the @code{--srcdir} option, but remember -that it is available. - -In order to actually install the program, the configuration system needs -to know where you would like the program installed. The default -location is @file{/usr/local}. We refer to this location as -@code{$(prefix)}. All user visible programs will be installed in -@file{@code{$(prefix)}/bin}. All other programs and files will be -installed in a subdirectory of @file{@code{$(prefix)}/lib}. - -You can only change @code{$(prefix)} as a configuration time -option. - -@example -./configure sun4 --enable-notation=postfix --prefix=/local -@end example - -@noindent -Will configure the source such that: - -@example -make install -@end example - -@noindent -will put its programs in @file{/local/bin} and @file{/local/lib/gcc}. -If you change @code{$(prefix)} after building the source, you will need -to: - -@example -make clean -@end example - -@noindent -before the change will be propogated properly. This is because some -tools need to know the locations of other tools. - -With these concepts in mind, we can drop the desk calculator example and -move on to the application that resides in these directories, namely, -the source to a development environment. - -@node Specifics., Building Development Environments, Some Basic Terms, top -@chapter Specifics - -The @sc{gnu} Development Tools can be built on a wide variety of hosts. So, -of course, they must be configured. Like the last example, - -@example -./configure sun4 --prefix=/local -./configure sun3 --prefix=/local -@end example - -@noindent -will configure the source to be built in subdirectories, in order to -keep the intermediate pieces separate, and to be installed in -@file{/local}. - -When built with suitable development environments, these will be native -tools. We'll explain the term @emph{native} later. - -@node Building Development Environments, A Walk Through, Specifics., top -@chapter Building Development Environments - -@cindex Target - -The @sc{gnu} development tools can not only be built in a -number of host development environments, they can also be configured to -create a number of different development environments on each of those -hosts. We refer to a specific development environment created as a -@emph{target}. That is, the word @emph{target} refers to the development -environment produced by compiling this source and installing the -resulting programs. - -For the @sc{gnu} development tools, the default target is the -same as the host. That is, the development environment produced is -intended to be compatible with the environment used to build the tools. - -In the example above, we created two configurations, one for sun4 and -one for sun3. The first configuration is expecting to be built in a -sun4 development environment, to create a sun4 development environment. -It doesn't necessarily need to be built on a sun4 if a sun4 development -environment is available elsewhere. Likewise, if the available sun4 -development environment produces executables intended for something -other than sun4, then the development environment built from this sun4 -configuration will run on something other than a sun4. From the point -of view of the configuration system and the @sc{gnu} development tools -source, this doesn't matter. What matters is that they will be built in -a sun4 environment. - -Similarly, the second configuration given above is expecting to be built -in a sun3 development environment, to create a sun3 development -environment. - -The development environment produced is a configuration time option, -just like @code{$(prefix)}. - -@example -./configure sun4 --prefix=/local --target=sun3 -./configure sun3 --prefix=/local --target=sun4 -@end example - -In this example, like before, we create two configurations. The first -is intended to be built in a sun4 environment, in subdirectories, to be -installed in @file{/local}. The second is intended to be built in a -sun3 environment, in subdirectories, to be installed in @file{/local}. - -Unlike the previous example, the first configuration will produce a sun3 -development environment, perhaps even suitable for building the second -configuration. Likewise, the second configuration will produce a sun4 -development environment, perhaps even suitable for building the first -configuration. - -The development environment used to build these configurations will -determine the machines on which the resulting development environments -can be used. - - -@node A Walk Through, Final Notes, Building Development Environments, top -@chapter A Walk Through - - -@menu -* Native Development Environments:: Native Development Environments -* Emulation Environments:: Emulation Environments -* Simple Cross Environments:: Simple Cross Environments -* Crossing Into Targets:: Crossing Into Targets -* Canadian Cross:: Canadian Cross -@end menu - -@node Native Development Environments, Emulation Environments, A Walk Through, A Walk Through -@section Native Development Environments - -Let us assume for a moment that you have a sun4 and that with your sun4 -you received a development environment. This development environment is -intended to be run on your sun4 to build programs that can be run on -your sun4. You could, for instance, run this development environment on -your sun4 to build our example desk calculator program. You could then -run the desk calculator program on your sun4. - -@cindex Native -@cindex Foreign -The resulting desk calculator program is referred to as a @emph{native} -program. The development environment itself is composed of native -programs that, when run, build other native programs. Any other program -is referred to as @emph{foreign}. Programs intended for other machines are -foreign programs. - -This type of development environment, which is by far the most common, -is refered to as @emph{native}. That is, a native development environment -runs on some machine to build programs for that same machine. The -process of using a native development environment to build native -programs is called a @emph{native} build. - -@example -./configure sun4 -@end example - -@noindent -will configure this source such that when built in a sun4 development -environment, with a development environment that builds programs -intended to be run on sun4 machines, the programs built will be native -programs and the resulting development environment will be a native -development environment. - -The development system that came with your sun4 is one such environment. -Using it to build the @sc{gnu} Development Tools is a very common activity -and the resulting development environment is quite popular. - -@example -make all -@end example - -@noindent -will build the tools as configured and will assume that you want to use -the native development environment that came with your machine. - -@cindex Bootstrapping -@cindex Stage1 -Using a development environment to build a development environment is -called @emph{bootstrapping}. The release of the @sc{gnu} -Development Tools is capable of bootstrapping itself. This is a very -powerful feature that we'll return to later. For now, let's pretend -that you used the native development environment that came with your -sun4 to bootstrap the release and let's call the new -development environment @emph{stage1}. - -Why bother? Well, most people find that the @sc{gnu} development -environment builds programs that run faster and take up less space than -the native development environments that came with their machines. Some -people didn't get development environments with their machines and some -people just like using the @sc{gnu} tools better than using other tools. - -@cindex Stage2 -While you're at it, if the @sc{gnu} tools produce better programs, maybe you -should use them to build the @sc{gnu} tools. So let's -pretend that you do. Let's call the new development environment -@emph{stage2}. - -@cindex Stage3 -So far you've built a development environment, stage1, and you've used -stage1 to build a new, faster and smaller development environment, -stage2, but you haven't run any of the programs that the @sc{gnu} tools have -built. You really don't yet know if these tools work. Do you have any -programs built with the @sc{gnu} tools? Yes, you do. stage2. What does -that program do? It builds programs. Ok, do you have any source handy -to build into a program? Yes, you do. The @sc{gnu} tools themselves. In -fact, if you use stage2 to build the @sc{gnu} tools again the resulting -programs should be identical to stage2. Let's pretend that you do and -call the new development environment @emph{stage3}. - -@cindex Three stage boot -You've just completed what's called a @emph{three stage boot}. You now have -a small, fast, somewhat tested, development environment. - -@example -make bootstrap -@end example - -@noindent -will do a three stage boot across all tools and will compare stage2 to -stage3 and complain if they are not identical. - -Once built, - -@example -make install -@end example - -@noindent -will install the development environment in the default location, or in -@code{$(prefix)} if you specified an alternate when you configured. - -@cindex Cross -Any development environment that is not a native development environment -is refered to as a @emph{cross} development environment. There are many -different types of cross development environments but most fall into one -of three basic categories. - - -@node Emulation Environments, Simple Cross Environments, Native Development Environments, A Walk Through -@section Emulation Environments - -@cindex Emulation -The first category of cross development environment is called -@emph{emulation}. There are two primary types of emulation, but both -types result in programs that run on the native host. - -@cindex Software emulation -@cindex Software emulator -The first type is @emph{software emulation}. This form of cross -development environment involves a native program that when run on the -native host, is capable of interpreting, and in most aspects running, a -program intended for some other machine. This technique is typically -used when the other machine is either too expensive, too slow, too fast, -or not available, perhaps because it hasn't yet been built. The native, -interpreting program is called a @emph{software emulator}. - -The @sc{gnu} Development Tools do not currently include any software -emulators. Some do exist and the @sc{gnu} Development Tools can be -configured to create simple cross development environments for with -these emulators. More on this later. - -The second type of emulation is when source intended for some other -development environment is built into a program intended for the native -host. The concepts of operating system universes and hosted operating -systems are two such development environments. - -@node Simple Cross Environments, Crossing Into Targets, Emulation Environments, A Walk Through -@section Simple Cross Environments - -@example -./configure sun4 --target=a29k -@end example - -@noindent -will configure the tools such that when compiled in a sun4 development -environment the resulting development environment can be used to create -programs intended for an a29k. Again, this does not necessarily mean -that the new development environment can be run on a sun4. That would -depend on the development environment used to build these tools. - -Earlier you saw how to configure the tools to build a native development -environment, that is, a development environment that runs on your sun4 -and builds programs for your sun4. Let's pretend that you use stage3 to -build this simple cross configuration and let's call the new development -environment gcc-a29k. Remember that this is a native build. Gcc-a29k -is a collection of native programs intended to run on your sun4. That's -what stage3 builds, programs for your sun4. Gcc-a29k represents an a29k -development environment that builds programs intended to run on an a29k. -But, remember, gcc-a29k runs on your sun4. Programs built with gcc-a29k -will run on your sun4 only with the help of an appropriate software -emulator. - -@cindex Simple cross -@cindex Crossing to -Building gcc-a29k is also a bootstrap but of a slightly different sort. -We call gcc-a29k a @emph{simple cross} environment and using gcc-a29k to -build a program intended for a29k is called @emph{crossing to} a29k. -Simple cross environments are the second category of cross development -environments. - - -@node Crossing Into Targets, Canadian Cross, Simple Cross Environments, A Walk Through -@section Crossing Into Targets - -@example -./configure a29k --target=a29k -@end example - -@noindent -will configure the tools such that when compiled in an a29k development -environment, the resulting development environment can be used to create -programs intended for an a29k. Again, this does not necessarily mean -that the new development environment can be run on an a29k. That would -depend on the development environment used to build these tools. - -If you've been following along this walk through, then you've already -built an a29k environment, namely gcc-a29k. Let's pretend you use -gcc-a29k to build the current configuration. - -Gcc-a29k builds programs intended for the a29k so the new development -environment will be intended for use on an a29k. That is, this new gcc -consists of programs that are foreign to your sun4. They cannot be run -on your sun4. - -@cindex Crossing into -The process of building this configuration is a another bootstrap. This -bootstrap is also a cross to a29k. Because this type of build is both a -bootstrap and a cross to a29k, it is sometimes referred to as a -@emph{cross into} a29k. This new development environment isn't really a -cross development environment at all. It is intended to run on an a29k -to produce programs for an a29k. You'll remember that this makes it, by -definition, an a29k native compiler. @emph{Crossing into} has been -introduced here not because it is a type of cross development -environment, but because it is frequently mistaken as one. The process -is @emph{a cross} but the resulting development environment is a native -development environment. - -You could not have built this configuration with stage3, because stage3 -doesn't provide an a29k environment. Instead it provides a sun4 -environment. - -If you happen to have an a29k lying around, you could now use this fresh -development environment on the a29k to three-stage these tools all over -again. This process would look just like it did when we built the -native sun4 development environment because we would be building another -native development environment, this one on a29k. - - -@node Canadian Cross, , Crossing Into Targets, A Walk Through -@section Canadian Cross - -So far you've seen that our development environment source must be -configured for a specific host and for a specific target. You've also -seen that the resulting development environment depends on the -development environment used in the build process. - -When all four match identically, that is, the configured host, the -configured target, the environment presented by the development -environment used in the build, and the machine on which the resulting -development environment is intended to run, then the new development -environment will be a native development environment. - -When all four match except the configured host, then we can assume that -the development environment used in the build is some form of library -emulation. - -When all four match except for the configured target, then the resulting -development environment will be a simple cross development environment. - -When all four match except for the host on which the development -environment used in the build runs, the build process is a @emph{cross into} -and the resulting development environment will be native to some other -machine. - -Most of the other permutations do exist in some form, but only one more -is interesting to the current discussion. - -@example -./configure a29k --target=sun3 -@end example - -@noindent -will configure the tools such that when compiled in an a29k development -environment, the resulting development environment can be used to create -programs intended for a sun3. Again, this does not necessarily mean -that the new development environment can be run on an a29k. That would -depend on the development environment used to build these tools. - -If you are still following along, then you have two a29k development -environments, the native development environment that runs on a29k, and -the simple cross that runs on your sun4. If you use the a29k native -development environment on the a29k, you will be doing the same thing we -did a while back, namely building a simple cross from a29k to sun3. -Let's pretend that instead, you use gcc-a29k, the simple cross -development environment that runs on sun4 but produces programs for -a29k. - -The resulting development environment will run on a29k because that's -what gcc-a29k builds, a29k programs. This development environment will -produce programs for a sun3 because that is how it was configured. This -means that the resulting development environment is a simple cross. - -@cindex Canadian Cross -@cindex Three party cross -There really isn't a common name for this process because very few -development environments are capable of being configured this -extensively. For the sake of discussion, let's call this process a -@emph{Canadian cross}. It's a three party cross, Canada has a three -party system, hence Canadian Cross. - -@node Final Notes, Index, A Walk Through, top -@chapter Final Notes - -By @emph{configures}, I mean that links, Makefile, .gdbinit, and -config.status are built. Configuration is always done from the source -directory. - -@table @code - -@item ./configure @var{name} -configures this directory, perhaps recursively, for a single host+target -pair where the host and target are both @var{name}. If a previous -configuration existed, it will be overwritten. - -@item ./configure @var{hostname} --target=@var{targetname} -configures this directory, perhaps recursively, for a single host+target -pair where the host is @var{hostname} and target is @var{targetname}. -If a previous configuration existed, it will be overwritten. - -@end table - -@menu -* Hacking Configurations:: Hacking Configurations -@end menu - -@node Hacking Configurations, , Final Notes, Final Notes -@section Hacking Configurations - -The configure scripts essentially do three things, create subdirectories -if appropriate, build a @file{Makefile}, and create links to files, all -based on and tailored to, a specific host+target pair. The scripts also -create a @file{.gdbinit} if appropriate but this is not tailored. - -The Makefile is created by prepending some variable definitions to a -Makefile template called @file{Makefile.in} and then inserting host and -target specific Makefile fragments. The variables are set based on the -chosen host+target pair and build style, that is, if you use -@code{--srcdir} or not. The host and target specific Makefile may or may -not exist. - -@itemize @bullet - -@item -Makefiles can be edited directly, but those changes will eventually be -lost. Changes intended to be permanent for a specific host should be -made to the host specific Makefile fragment. This should be in -@file{./config/mh-@var{host}} if it exists. Changes intended to be -permanent for a specific target should be made to the target specific -Makefile fragment. This should be in @file{./config/mt-@var{target}} if -it exists. Changes intended to be permanent for the directory should be -made in @file{Makefile.in}. To propogate changes to any of these, -either use @code{make Makefile} or @code{./config.status} or -re-configure. - -@end itemize - -@page -@node Index, , Final Notes, top -@appendix Index - -@printindex cp - -@contents -@bye - -@c Local Variables: -@c fill-column: 72 -@c End: diff --git a/contrib/binutils/etc/configure.man b/contrib/binutils/etc/configure.man deleted file mode 100644 index a7699041a711..000000000000 --- a/contrib/binutils/etc/configure.man +++ /dev/null @@ -1,166 +0,0 @@ -.\" -*- nroff -*- -.\" Copyright (c) 1991, 1992, 1996 Cygnus Support -.\" written by K. Richard Pixley -.TH configure 1 "29 March 1996" "cygnus support" "Cygnus Support" -.de BP -.sp -.ti \-.2i -\(** -.. - -.SH NAME -configure \- prepare source code to be built - -.SH SYNOPSIS -configure HOST [--target=TARGET] [--srcdir=DIR] [--rm] - [--site=SITE] [--prefix=DIR] [--exec_prefix=DIR] - [--program_prefix=DIR] [--tmpdir=DIR] - [--with-PACKAGE[=YES/NO]] [--without-PACKAGE] - [--enable-FEATURE[=YES/NO]] [--disable-FEATURE] - [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help] - -.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, recursing -in subdirectories, and some other miscellaneous file editing. - -.SH OPTIONS -.I configure -accepts the following options: - -.TP -.I \--target=TARGET -Requests that the sources be configured to target the -.I TARGET -machine. If no target is specified explicitly, the target is assumed -to be the same as the host. - -.TP -.I \--srcdir=DIR -tells configure to find the source in -.I DIR. -Object code is always built in the current directory, -.I `.'. - -.TP -.I \--rm -asks configure to remove a configuration rather than create one. - -.TP -.I \--site=SITE -asks configure to use any site-specific Makefile fragments for -.I SITE -when building Makefiles. - -.TP -.I \--prefix=DIR -sets the location in which to install files to -.I DIR. -The default is "/usr/local". - -.TP -.I \--exec_prefix=DIR -sets the root directory for host-dependent files to -.I DIR. -The default location is the value of -.I prefix. - -.TP -.I \--program_prefix=DIR -configures the source to install programs which have the same names as -common Unix programs, such as "make", in -.I DIR. -Also applies to programs which might be used for cross-compilation. - -.TP -.I \--tmpdir=DIR -sets the directory in which configure creates temporary files to -.I DIR. - -.TP -.I \--with-PACKAGE[=YES/NO] -sets a flag for the build to recognize that -.I PACKAGE -is explicitly present or not present. If -.I \=YES/NO -is nonexistent, the default is -.I YES. -.I \--without-PACKAGE -is equivalent to -.IR \--with-PACKAGE=no . - -.TP -.I \--enable-FEATURE[=YES/NO] -sets a flag for the build to recognize that -.I FEATURE -should be included or not included. If -.I \=YES/NO -is nonexistent, the default is -.I YES. -.I \--disable-FEATURE -is equivalent to -.IR --enable-FEATURE=no . - -.TP -.I \--norecursion -asks that only the current directory be configured. Normally -.I configure -recurs on subdirectories. - -.TP -.I \-nfp -Notifies -.I configure -that all of the specified hosts have -.I no floating point -units. - -.TP -.I \-s -used internally by configure to supress status messages on -subdirectory recursions. Override with -.I \-v - -.TP -.I \-v -verbose output. Asks that configure print status lines for each -directory configured. Normally, only the status lines for the current -directory are printed. - -.TP -.I \--version -.I \-V -prints -.I configure -version number. - -.TP -.I \-help -displays a brief usage summary. - - -.SH FILES -configure.in for each directory's individual needs -.br -Makefile.in Makefile template -.br -config.sub for parsing configuration names -.br -config.guess for guessing HOST when not specified -.br -config.status non-recursively rebuilds current directory - -.SH FILES -.ta \w'gmon.sum 'u -a.out the namelist and text space. -.br -gmon.out dynamic call graph and profile. -.br -gmon.sum summarized dynamic call graph and profile. - -.SH "SEE ALSO" -.RB "`\|" configure "\|'" -entry in -.B -info. diff --git a/contrib/binutils/etc/configure.texi b/contrib/binutils/etc/configure.texi deleted file mode 100644 index 445777491fb4..000000000000 --- a/contrib/binutils/etc/configure.texi +++ /dev/null @@ -1,1830 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename configure.info -@settitle Cygnus configure - -@synindex ky cp - -@setchapternewpage odd - -@ifinfo -@format -START-INFO-DIR-ENTRY -* configure: (configure). Cygnus configure. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@ifinfo -This document describes the Cygnus Support version of @code{configure}. - -Copyright (C) 1991, 1992, 1993 Cygnus Support -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). -@end ignore - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by Cygnus Support. -@end ifinfo - -@c We should not distribute texinfo files with smallbook enabled. -@c @smallbook -@finalout -@titlepage -@title Cygnus configure -@author K. Richard Pixley -@author Cygnus Support -@page -@cindex copyleft - -@vskip 0pt plus 1filll -Edited January, 1993, by Jeffrey Osier, Cygnus Support. - -Copyright @copyright{} 1991, 1992, 1993 Cygnus Support - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by Cygnus Support. -@end titlepage - -@c --------------------------------------------------------------------- -@ifinfo -@node Top -@top Cygnus configure - -This file documents the configuration system used and distributed by -Cygnus Support. - -@menu -* What configure does:: What configure does -* Invoking configure:: Invoking configure---basic usage -* Using configure:: More than you ever wanted to know -* Porting:: How to use configure with new programs -* Variables Index:: -* Concept Index:: -@end menu -@end ifinfo - -@c --------------------------------------------------------------------- -@node What configure does -@chapter What @code{configure} does -@cindex Introduction -@cindex Overview -@cindex What @code{configure} does -@kindex Cygnus Support Developer's Kit - -This manual documents Cygnus @code{configure}, a program which helps to -automate much of the setup activity associated with building large suites of -programs, such the Cygnus Support Developer's Kit. This manual is therefore -geared toward readers who are likely to face the problem of configuring -software in source form before compiling and installing it. We assume you are -an experienced programmer or system administrator. -@ifinfo -For further background on this topic, see @ref{Some Basic Terms, , Apologia -Configure, cfg-paper, On Configuring Development Tools}, by K. Richard -Pixley. -@end ifinfo -@iftex -For further background on this topic, see @cite{On Configuring Development -Tools} by K. Richard Pixley. -@end iftex - -When @code{configure} runs, it does the following things: - -@table @emph -@item @bullet{} creates build directories -@vindex srcdir -@cindex @code{srcdir} -@cindex Build directories -When you run @code{configure} with the @samp{--srcdir} option, it uses the -current directory as the @dfn{build directory}, creating under it a directory -tree that parallels the directory structure of the source directory. If you -don't specify a @samp{srcdir}, @code{configure} first assumes that the source -code you wish to configure is in your current directory; if it finds no -@file{configure.in} input file there, it searches in the directory -@code{configure} itself lies in. (For details, see @ref{Build directories, , -Build directories}.) - -@item @bullet{} generates @file{Makefile} -@cindex @code{Makefile} generation -A @file{Makefile} template from the source directory, usually called -@file{Makefile.in}, is copied to an output file in the build directory which is -most often named @file{Makefile}. @code{configure} places definitions for a -number of standard @file{Makefile} macros at the beginning of the output file. -If @w{@samp{--prefix=@var{dir}}} or @w{@samp{--exec_prefix=@var{dir}}} are -specified on the @code{configure} command line, corresponding @file{Makefile} -variables are set accordingly. If host, target, or site-specific -@file{Makefile} fragments exist, these are inserted into the output file. (For -details, see @ref{Makefile generation, , @code{Makefile} generation}.) - -@item @bullet{} generates @file{.gdbinit} -@cindex @code{.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 commands which allow -the source directory to be read when debugging with the @sc{gnu} debugger, -@code{gdb}. (@xref{Command Files, , Command Files, gdb, Debugging With GDB}.) - -@item @bullet{} makes symbolic links -@cindex Symbolic links -Most build directories require that some symbolic links with generic names are -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. (For details, see @ref{configure.in, , The @code{configure.in} input -file}.) - -@item @bullet{} generates @file{config.status} -@cindex @code{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 (usually from -within a @file{Makefile}), will reconfigure the build directory (but not its -subdirectories). This is most often used to have a @file{Makefile} update -itself automatically if a new source directory is available. - -@item @bullet{} calls itself recursively -@cindex Recursion -If the source directory has subdirectories that should also be configured, -@code{configure} is called for each. -@end table - -@c --------------------------------------------------------------------- -@node Invoking configure -@chapter Invoking @code{configure} -@cindex Invoking @code{configure} -@cindex Usage - -Cygnus @code{configure} is a shell script which resides in a source tree. The -usual way to invoke @code{configure} is from the shell, as follows: - -@cindex Example session -@example -eg$ ./configure @var{hosttype} -@end example - -@noindent -This prepares the source in the current directory (@file{.}) to be -compiled for a @var{hosttype} environment. It assumes that you wish to -build programs and files in the default @dfn{build directory} (also the -current directory, @file{.}). If you do not specify a value for -@var{hosttype}, Cygnus @code{configure} will attempt to discover this -information by itself (@pxref{config.guess, , Determining system -information}). For information on @var{hosttype} environments, -@xref{Host, , Host}. - -All @sc{gnu} software is packaged with one or more @code{configure} script(s) -(@pxref{Configuration, , How Configuration Should Work, standards, GNU Coding -Standards}). By using @code{configure} you prepare the source for your -specific environment by selecting and using @file{Makefile} fragments and -fragments of shell scripts, which are 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: - -@smallexample - configure @var{hosttype} [--target=@var{target}] [--srcdir=@var{dir}] [--rm] - [--site=@var{site}] [--prefix=@var{dir}] [--exec-prefix=@var{dir}] - [--program-prefix=@var{string}] [--tmpdir=@var{dir}] - [--with-@var{package}[=@var{yes/no}]] [--without-@var{package}] - [--enable-@var{feature}[=@var{yes/no}]] [--disable-@var{feature}] - [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help] -@end smallexample - -@table @code -@item --target=@var{target} -@cindex @code{--target} -@cindex @code{target} option -@vindex 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 (i.e., a @dfn{native} configuration). @xref{Host, , Host}, and -@ref{Target, , Target}, for -discussions of each. - -@item --srcdir=@var{dir} -@cindex @code{--srcdir} -@cindex @code{srcdir} option -@vindex srcdir -Direct each generated @file{Makefile} to use the sources located in directory -@var{dir}. Use this option whenever you wish the object code to reside in a -different place from the source code. The @dfn{build directory} is always -assumed to be the directory you call @code{configure} from. See @ref{Build -directories, , Build directories}, for an example. If the source directory is -not specified, @code{configure} assumes that the source is in your current -directory. If @code{configure} finds no @file{configure.in} there, it searches -in the same directory that the @code{configure} script itself lies in. -Pathnames specified (Values for @var{dir}) can be either absolute relative to -the @emph{build} directory. - -@item --rm -@cindex @code{--rm} -@cindex @code{rm} option -@vindex rm -@emph{Remove} the configuration specified by @var{hosttype} and the other -command-line options, rather than create it. - -@c FIXME: check @ref -@quotation -@emph{Note:} We recommend that you use @samp{make distclean} rather than -use this option; see @ref{Invoking make,,Invoking @code{make},make,GNU -Make}, for details on @samp{make distclean}. -@end quotation - -@item --site=@var{site} -@cindex @code{--site} -@cindex @code{site} option -@vindex site -Generate the @file{Makefile} using site-specific @file{Makefile} fragments for -@var{site}. @xref{Makefile fragments, , Adding information about local -conventions}. - -@item --prefix=@var{dir} -@cindex @code{--prefix} -@cindex @code{prefix} option -@vindex prefix -Configure the source to install programs and files under directory @var{dir}. - -This option sets the variable @samp{prefix}. Each generated @file{Makefile} -will have its @samp{prefix} variables set to this value. (@xref{What configure -really does, , What @code{configure} really does}.) - -@item --exec-prefix=@var{dir} -@cindex @code{--exec-prefix} -@cindex @code{exec-prefix} option -@vindex exec-prefix -Configure the source to install @dfn{host dependent} files in @var{dir}. - -This option sets the variable @samp{exec_prefix}. Each generated -@file{Makefile} will have its @samp{exec_prefix} variables set to this value. -(@xref{What configure really does, , What @code{configure} really does}.) - -@item --program-prefix=@var{string} -@cindex @code{--program-prefix} -@cindex @code{program-prefix} option -@vindex program-prefix -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 binary utilities, and also to programs which have -the same names as common Unix programs, such as @code{make}. - -This option sets the variable @samp{program_prefix}. Each generated -@file{Makefile} will have its @samp{program_prefix} variables set to this -value. (@xref{What configure really does, , What @code{configure} really -does}.) - -@item --tmpdir=@var{tmpdir} -@cindex @code{--tmpdir} -@cindex @code{tmpdir} option -@vindex tmpdir -Use the directory @var{tmpdir} for @code{configure}'s temporary files. The -default is the value of the environment variable @w{@code{TMPDIR}}, or -@file{/tmp} if the environment variable is not set. - -@item --with-@var{package}[=@var{yes/no}] -@itemx --without-@var{package} -@cindex @code{--with-@var{package}} -@cindex @code{with-@var{package}} option -@vindex with-@var{package} -@cindex @code{--without-@var{package}} -@cindex @code{without-@var{package}} option -@vindex without-@var{package} -Indicate that @var{package} is present, or not present, depending on -@var{yes/no}. If @var{yes/no} is nonexistent, its value is assumed to be -@code{yes}. @samp{--without-@var{package}} is equivalent to -@samp{--with-@var{package}=no}. - -For example, if you wish to configure the program @code{gcc} for a Sun -SPARCstation running SunOS 4.x, and you want @code{gcc} to use the -@sc{gnu} linker @code{ld}, you can configure @code{gcc} using - -@cindex Example session -@smallexample -eg$ configure --with-gnu-ld sun4 -@end smallexample - -@noindent -@xref{What configure really does, , What @code{configure} really does}, for -details. See the installation or release notes for your particular package for -details on which other @var{package} options are recognized. -@c FIXME - need to include info about --with-* in other dox! - -@item --enable-@var{feature}[=@var{yes/no}] -@itemx --disable-@var{feature} -@cindex @code{--enable-@var{feature}} -@cindex @code{enable-@var{feature}} option -@vindex enable-@var{feature} -@cindex @code{--disable-@var{feature}} -@cindex @code{disable-@var{feature}} option -@vindex disable-@var{feature} -Include @var{feature}, or not, depending on @var{yes/no}. If @var{yes/no} is -nonexistent, its value is assumed to be @code{yes}. -@samp{--disable-@var{feature}} is equivalent to -@samp{--enable-@var{feature}=no}. - -@noindent -@xref{What configure really does, , What @code{configure} really does}, for -details. See the installation or release notes for your particular package for -details on which other @var{feature} options are recognized. -@c FIXME - need to include info about --enable-* in other dox! - -@item --norecursion -@cindex @code{--norecursion} -@cindex @code{norecursion} option -@vindex norecursion -Configure only this directory; ignore any subdirectories. This is used by the -executable shell script @file{config.status} to reconfigure only the current -directory; it is most often used non-interactively, when @code{make} is -invoked. (@xref{config.status, , @code{config.status}}.) - -@item --nfp -@cindex @code{--nfp} -@cindex @code{nfp} option -@vindex nfp -Assume that the intended @var{hosttype} has no floating point unit. - -@item -s -@cindex @code{-s} -@cindex @code{s} option -Suppress status output. This option is used internally by -@code{configure} when calling itself recursively in subdirectories. You -can override this option with the @code{--verbose} option. - -@item -v -@itemx --verbose -@cindex @code{-v} -@cindex @code{--verbose} -@cindex @code{v} option -@cindex @code{verbose} option -@cindex Verbose Output -@vindex verbose -Print status lines for each directory configured. Normally, only the -status lines for the initial working directory are printed. - -@item --version -@itemx -V -@cindex version -@cindex @code{--version} -@cindex version -Print the @code{configure} version number. - -@item --help -@cindex Usage -@cindex @code{--help} -@cindex @code{help} option -Print a short summary of how to invoke @code{configure}. -@end table - -@cindex Abbreviating option names -@cindex Truncating option names -@cartouche -@emph{Note:} You may introduce options with a single dash, @samp{-}, rather -than two dashes, @samp{--}. However, you may not be able to truncate long -option names when using a single dash. When using two dashes, options may be -abbreviated as long as each option can be uniquely identified. For example, -@smallexample -eg$ configure --s=/u/me/src @var{hosttype} -@end smallexample -@noindent -is ambiguous, as @w{@samp{--s}} could refer to either @w{@samp{--site}} or -@w{@samp{--srcdir}}. However, -@smallexample -eg$ configure --src=/u/me/src @var{hosttype} -@end smallexample -@noindent -is a valid abbreviation. -@end cartouche - - -@c ======================================================================== -@node Using configure -@chapter Using @code{configure} -@cindex Using @code{configure} -@cindex Detailed usage -@cindex Usage: detailed - -@code{configure} prepares source directories for building programs in -them. ``Configuring'' is the process of preparing software to compile -correctly on a given @dfn{host}, for a given @dfn{target}. - -@code{configure} subsequently writes a configured @file{Makefile} from a -pre-built template; @code{configure} uses variables that have been set in the -configuring process to determine the values of some variables in the -@file{Makefile}. Because of this we will refer to both @code{configure} -variables and @file{Makefile} variables. This convention allows us to -determine where the variable should be set initially, in either -@file{configure.in} or @file{Makefile.in}. - -@menu -* What configure really does:: What configure really does -* configure.in:: The configure.in input file -* Install locations:: Where to install things once they are built -* Host:: Telling configure what will source will be built -* Target:: Telling configure what the source will target -* Makefile fragments:: Adding information about local conventions -* Makefile extensions:: Extensions to the GNU coding standards -@end menu - -@c --------------------------------------------------------------------- -@node What configure really does -@section What @code{configure} really does -@cindex What @code{configure} really does -@cindex Behind the scenes -@cindex @code{configure} back end -@cindex @code{configure} details - -Cygnus @code{configure} is a shell script that sets up an environment in -which your programs will compile correctly for your machine and -operating system, and will install in proper places. @code{configure} -accomplishes this task by doing the following: - -@itemize @bullet -@item -it generates a @file{Makefile} from a custom template called -@file{Makefile.in} in each relevant source directory; - -@item -it customizes the build process to your specifications; you set certain -variables for @code{configure}, either on the command line or in the -file @file{configure.in}, which subsequently sets variables in each -generated @file{Makefile} to be used by @code{make} when actually -building the software; - -@item -it creates @dfn{build directories}, places for your code to be compiled -in before being installed; - -@item -it generates a @file{.gdbinit} in the build directory, if needed, to -communicate to @code{gdb} where to find the program's source code; - -@item -it generates a shell script called @file{config.status} -which is used most often by the @file{Makefile} to reconfigure itself; - -@item -it recurses in subdirectories, setting up entire trees so that they build -correctly; if @code{configure} finds another @code{configure} script -further down in a given source tree, it knows to use this script and not -recur. -@end itemize - -For the sake of safety (i.e., in order to prevent broken installations), the -@sc{gnu} coding standards call for software to be @dfn{configured} in such a -way that an end user trying to build a given package will be able to do so by -affecting a finite number of variables. All @sc{gnu} software comes with an -executable @code{configure} shell script which sets up an environment within a -build directory which will correctly compile your new package for your host -(or, alternatively, whatever host you specify to @code{configure}). -@ifinfo -For further background on this topic, see @ref{Some Basic Terms, , Apologia -Configure, cfg-paper, On Configuring Development Tools}, by K. Richard -Pixley. -@end ifinfo -@iftex -For further background on this topic, see @cite{On Configuring Development -Tools} by K. Richard Pixley. -@end iftex - -Use @code{configure} to set for the build process: - -@itemize @bullet -@item -correct values for certain variables; - -@item -which type of host you wish to configure a given package for -(@pxref{Host, , Host}); - -@item -where you want to install this package (by using @samp{prefix}, -@samp{exec-prefix} and @samp{program-prefix}; @pxref{Install details, , -Full descriptions of all installation directories}); - -@item -optionally, which type of machine you wish to @dfn{target} this -package's output to (@pxref{Target, , Target}); - -@item -which other @sc{gnu} packages are already installed and available to -this particular build (by using the @samp{--with-@var{package}} option; -@pxref{Invoking configure, , Invoking @code{configure}}); - -@item -where to place temporary files (by using the @samp{--tmpdir=@var{dir}} -option; @pxref{Invoking configure, , Invoking @code{configure}}); - -@item whether to recur in subdirectories (changeable through the -@w{@samp{--norecursion}} option; @pxref{Invoking configure, , Invoking -@code{configure}}). -@end itemize - -@code{configure} uses a few other files to complete its tasks. These are -discussed in detail where noted. - -@table @code -@cindex Other files -@item configure.in -@cindex @code{configure.in} definition -Input file for @code{configure}. Shell script fragments reside here. -@xref{configure.in, , The @code{configure.in} input file}. - -@item Makefile.in -@cindex @code{Makefile.in} definition -Template which @code{configure} uses to build a file called @file{Makefile} in -the @dfn{build directory}. @xref{Makefile generation, , @code{Makefile} -generation}. - -@item config.sub -@cindex @code{config.sub} definition -Shell script used by @code{configure} to expand referents to the -@var{hosttype} argument into a single specification of the form -@w{@var{cpu-vendor-os}}. For instance, on the command line you can -specify - -@cindex Example session -@example -eg$ ./configure sun4 -@end example - -@noindent -to configure for a Sun SPARCstation running SunOS 4.x. @code{configure} -consults @code{config.sub} to find that the three-part specification for this -is - -@example -sparc-sun-sunos4.1.1 -@end example - -@noindent -which notes the @var{cpu} as @samp{sparc}, the @var{manufacturer} as @samp{sun} -(Sun Microsystems), and the @var{os} (operating system) as @samp{sunos4.1.1}, -the SunOS 4.1.1 release. @xref{configure variables, , Variables available to @code{configure}}. - -@item config.guess -@cindex @code{config.guess} definition -If you do not put the @var{hosttype} argument on the command line, -@code{configure} uses the @code{config.guess} shell script to make an -analysis of your machine (it assumes that you wish to configure your -software for the type of machine on which you are running). The output -of @code{config.guess} is a three-part identifier as described above. - -@item config.status -@cindex @code{config.status} definition -The final step in configuring a directory is to create a shell script, -@code{config.status}. The main purpose of this file is to allow the -@file{Makefile} for the current directory to rebuild itself, if -necessary. @xref{config.status, , @code{config.status}}. - -@item config/* -@cindex @code{config/} subdirectory -@code{configure} uses three types of @file{Makefile} @dfn{fragments}, which -reside in the directory @file{@var{srcdir}/config/}. @xref{Makefile fragments, -, Adding information about local conventions}. -@end table - -@menu -* Build variables:: Variable-spaghetti made simple -* Build directories:: Build directories described well -* Makefile generation:: To build a Makefile -* config.guess:: Be vewwy quiet, I'm hunting system information -* config.status:: To rebuild a Makefile -@end menu - -@c --------------------------------------------------------------------- -@node Build variables -@subsection Build variables -@cindex Build variables -@cindex Cygnus Support Developer's Kit -@cindex Variables - -There are several variables in the build process which you can control through -build programs such as @code{make}. These include machine definitions, local -conventions, installation locations, locations for temporary files, etc. This -data is accessible through certain variables which are configurable in the -build process; we refer to them as @dfn{build variables}. - -For lists of build variables which you can affect by using @code{configure}, -see @ref{configure variables, , Variables available to @code{configure.in}}, -and @ref{Install details, , Full descriptions of all installation directories}. - -Generally, build variables, which are used by the @file{Makefile} to -determine various aspects of the build and installation processes, are -changeable with command-line options to @code{configure}. In most large -suites of programs, like the Cygnus Support Developer's Kit, the -individual programs reside in several subdirectories of a single source -code ``tree''. All of these subdirectories need to be configured with -information relative to the @dfn{build directory}, which is not known -until @code{configure} is run. Unless specified otherwise, -@code{configure} recursively configures every subdirectory in the source -tree. - -Build variables are passed from @code{configure} directly into the -@file{Makefile}, and use the same names (except that dashes are -transformed into underbars; for example, when you specify the option -@samp{--exec-prefix} on the command line, the @file{Makefile} variable -@samp{exec_prefix} is set). In other words, if you specify - -@cindex Example session -@example -eg$ ./configure --prefix=/usr/gnu/local @dots{} @var{hosttype} -@end example - -@noindent -on the command line, @code{configure} sets an variable called @samp{prefix} to -@samp{/usr/gnu/local}, and passes this into the @file{Makefile} in the same -manner. After this command, each @file{Makefile} generated by @code{configure} -will contain a line that reads: - -@example -prefix = /usr/gnu/local -@end example - -For a list of the @file{Makefile} variables @code{configure} can change, and -instructions on how to change them, see @ref{configure variables, , Variables -available to @code{configure.in}}, and @ref{Invoking configure, , Invoking -@code{configure}}. - -@c --------------------------------------------------------------------- -@node Build directories -@subsection Build directories -@cindex Build directories -@cindex Object directories -@cindex Building for multiple hosts -@cindex Building for multiple targets - -By default, @code{configure} builds a @file{Makefile} and symbolic links in the -same directory as the source files. This default works for many cases, but it -has limitations. For instance, using this approach, you can only build object -code for one host at a time. - -We refer to each directory where @code{configure} builds a @file{Makefile} as -a @dfn{build directory}. - -The build directory for any given build is always the directory from which you -call @code{configure}, or @file{.} relative to your prompt. The default -@dfn{source directory}, the place @code{configure} looks to find source code, -is also @file{.}. For instance, if we have a directory @file{/gnu-stuff/src/} -that is the top branch of a tree of @sc{gnu} source code we wish to configure, -then the program we will use to configure this code is -@file{/gnu-stuff/src/configure}, as follows. (Assume for the sake of argument -that our machine is a sun4.) - -@cindex Example session -@smallexample -@group -eg$ cd /gnu-stuff/src -eg$ ./configure sun4 -Created "Makefile" in /gnu-stuff/src -eg$ -@end group -@end smallexample - -We just configured the code in @file{/gnu-stuff/src} to run on a Sun -SPARCstation using SunOS 4.x by creating a @file{Makefile} in -@file{/gnu-stuff/src}. By default, we also specified that when this code is -built, the object code should reside in the same directory, -@file{/gnu-stuff/src}. - -However, if we wanted to build this code for more than one host, we would be in -trouble, because the new configuration would write over the old one, destroying -it in the process. What we can do is to make a new @dfn{build directory} and -configure from there. Running @code{configure} from the new directory will -place a correct @file{Makefile} and a @file{config.status} in this new file. -That is all @code{configure} does; we must run @code{make} to generate any -object code. - -The new @file{Makefile} in @file{/gnu-stuff/sun4-obj}, created from the -template file @file{/gnu-stuff/src/Makefile.in}, contains all the information -needed to build the program. - -@cindex Example session -@smallexample -@group -eg$ mkdir /gnu-stuff/sun4-obj -eg$ cd /gnu-stuff/sun4-obj -eg$ ../src/configure --srcdir=../src sun4 -Created "Makefile" in /gnu-stuff/sun4-obj -eg$ ls -Makefile config.status -eg$ make all info install install-info clean -@var{compilation messages@dots{}} -eg$ mkdir /gnu-stuff/solaris2 -eg$ cd /gnu-stuff/solaris2 -eg$ ../src/configure --srcdir=../src sol2 -Created "Makefile" in /gnu-stuff/solaris2 -eg$ ls -Makefile config.status -eg$ make all info install install-info clean -@var{compilation messages@dots{}} -@end group -@end smallexample - -We can repeat this for other configurations of the same software simply -by making a new build directory and reconfiguring from inside it. If -you do not specify the @var{hosttype} argument, @code{configure} -will attempt to figure out what kind of machine and operating system you -happen to be using. @xref{config.guess, , Determining system -information}. Of course, this may not always be the configuration you -wish to build. - -@emph{Caution:} If you build more than one configuration for a single program, -remember that you must also specify a different @samp{--prefix} for each -configuration at configure-time. Otherwise, both configurations will be -installed in the same default location (@file{/usr/local}); the configuration -to be installed last would overwrite previously installed configurations. - -@c --------------------------------------------------------------------- -@node Makefile generation -@subsection @code{Makefile} generation -@cindex @code{Makefile} generation - -Cygnus @code{configure} creates a file called @file{Makefile} in the build -directory which can be used with @code{make} to automatically build a given -program or package. @code{configure} also builds a @file{Makefile} for each -relevant subdirectory for a given program or package (irrelevant subdirectories -would be those which contain no code which needs configuring, and which -therefore have no @code{configure} input file @file{configure.in} and no -@file{Makefile} template @file{Makefile.in}). @xref{Running, @code{make} -Invocation, How to Run @code{make}, make, GNU Make}, for details on using -@code{make} to compile your source code. - -Each @file{Makefile} contains variables which have been configured for a -specific build. These build variables are determined when @code{configure} is -run. All build variables have defaults. By default, @code{configure} -generates a @file{Makefile} which specifies: - -@cindex Default configuration -@itemize @bullet -@item a @dfn{native} build, which is to occur - -@item in the current directory, and which will be installed - -@item in the default installation directory (@file{/usr/local}) when the code -is compiled with @code{make}. -@end itemize - -@noindent -Variables are changeable through command-line options to @code{configure} -(@pxref{Invoking configure, , Invoking @code{configure}}). - -If you are porting a new program and intend to use @code{configure}, see -@ref{Porting, , Porting with @code{configure}}, as well as @ref{Makefiles, , -Writing Makefiles, make, GNU Make}, and @ref{Makefiles, , Makefile Conventions, -standards, GNU Coding Standards}. - -@c --------------------------------------------------------------------- -@node config.guess -@subsection Determining system information -@cindex @code{config.guess} - -The shell script @code{config.guess} is called when you do not specify a -@var{hosttype} on the command line to @code{configure}. @code{config.guess} -acquires available system information from your local machine through the shell -command @code{uname}. It compares this information to a database and attempts -to determine a usable three-part system identifier (known as a @dfn{triple}) to -use as your @var{hosttype}. @xref{What configure really does, , What -@code{configure} really does}, to see how this information is used. - -@emph{Note:} If you do not specify a @var{hosttype} on the command line, -@code{configure} will attempt to configure your software to run on the machine -you happen to be using. This may not be the configuration you desire. - -@c --------------------------------------------------------------------- -@node config.status -@subsection @code{config.status} -@cindex @code{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 -@file{Makefile} for the current directory to rebuild itself, if necessary. It -is usually run from within the @file{Makefile}. @xref{Makefile extensions, , -Extensions to the @sc{gnu} coding standards}. - -@file{config.status} also contains a record of the @code{configure} session -which created it. - -@c --------------------------------------------------------------------- -@node configure.in -@section The @code{configure.in} input file -@cindex @code{configure.in} - -A @file{configure.in} file for Cygnus @code{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 executed by the -@code{configure} shell script at an appropriate time. Values are passed among -@code{configure} and the shell fragments through a set of shell variables. -When each section is being interpreted 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 @samp{$(srcdir)/} to the desired file name. - -@cindex @i{per-invocation} section -The beginning of the @file{configure.in} file begins the @dfn{per-invocation} -section. - -@cindex @i{per-host} section -A line beginning with @samp{# per-host:} begins the @dfn{per-host} section. - -@cindex @i{per-target} section -A line beginning with @samp{# per-target:} begins the @dfn{per-target} section. - -@cindex @i{post-target} section -If it exists, the @dfn{post-target} section begins with @samp{# post-target:}. - -@menu -* configure variables:: Variables available to configure.in -* Minimal:: A minimal configure.in -* Declarations:: For each invocation -* per-host:: Host-specific instructions -* per-target:: Target-specific instructions -* post-target:: Instructions to be executed after target info -* Example:: An example configure.in -@end menu - -@c --------------------------------------------------------------------- -@node configure variables -@subsection Variables available to @code{configure.in} -@cindex @file{configure.in} interface -@cindex configure variables - -The following variables pass information between the standard parts of -@code{configure} and the shell-script fragments in @file{configure.in}: - -@table @code -@item srctrigger -@cindex @code{srctrigger} -@vindex srctrigger -Contains the name of a source file that is expected to live in the source -directory. You must usually set this in the @dfn{per-invocation} section of -@file{configure.in}. @code{configure} tests to see that this file exists. If -the file does not exist, @code{configure} prints an error message. This is -used as a sanity check that @file{configure.in} matches the source directory. - -@item srcname -@cindex @code{srcname} -@vindex srcname -Contains the name of the source collection contained in the source directory. -You must usually set this in the @dfn{per-invocation} section of -@file{configure.in}. If the file named in @samp{srctrigger} does not exist, -@code{configure} uses the value of @samp{srcname} when it prints the error -message. - -@item configdirs -@cindex @code{configdirs} -@vindex configdirs -Contains the names of any subdirectories in which @code{configure} should -recurse. You must usually set this in the @dfn{per-invocation} section of -@file{configure.in}. -If @file{Makefile.in} contains a line starting with @samp{SUBDIRS =}, -then it will be replaced with an assignment to @samp{SUBDIRS} using -the value of @samp{configdirs} (if @samp{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 @samp{configdirs} (instead of the @samp{subdirs} variable -described below) if you want to be able to partition the -subdirectories, or use independent @file{Makefile} fragments. -Each subdirectory can be independent, and independently reconfigured. - -@item subdirs -@cindex @code{subdirs} -@vindex subdirs -Contains the names of any subdirectories where @code{configure} should create a -@file{Makefile} (in addition to the current directory), @emph{without} -recursively running @code{configure}. Use @samp{subdirs} (instead of the -@samp{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 -@file{Makefile} fragments, and the same @code{configure.in}. - -@item host -@cindex @code{host} -@cindex Canonical ``triple'' -@vindex host -Contains the full configuration name for the host (generated by the script -@file{config.sub} from the name that you entered). This is a three-part -name (commonly referred to as a @dfn{triple}) of the form -@var{cpu}-@var{vendor}-@var{os}. - -There are separate variables @samp{host_cpu}, @samp{host_vendor}, and -@samp{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. - -@item host_cpu -@vindex 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. - -@item host_vendor -@vindex 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 among the -numerous variations of @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? - -@item host_os -@vindex host_os -Contains the the third element of the canonical triple representing the -host as returned by @file{config.sub}. - -@item target -@cindex @code{target} -@cindex Canonical ``triple'' -@vindex target -Contains the full configuration name (generated by the script @file{config.sub} -from the name that you entered) for the target. Like the host, this is a -three-part name of the form @var{cpu}-@var{vendor}-@var{os}. - -There are separate variables @samp{target_cpu}, @samp{target_vendor}, and -@samp{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. - -@item target_cpu -@vindex target_cpu -Contains the first element of the canonical triple representing the target as -returned by @file{config.sub}. This variable is used heavily by programs which -are involved in building other programs, like the compiler, assembler, linker, -etc. Most programs will not need the @samp{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. - -@item target_vendor -@vindex 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 among the -numerous variations of @emph{common} operating systems or object file -formats. It is sometimes used to switch between different flavors of user -interfaces. -@c above query re "@emph{common} OS" applies here too - -@item target_os -@vindex 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. - -@item floating_point -@cindex @code{floating_point} -@cindex @code{nfp} option -@vindex floating_point -Set to @samp{no} if you invoked @code{configure} with the @samp{--nfp} -command-line option, otherwise it is empty. This is a request to target -machines with @dfn{no floating point} unit, even if the targets ordinarily have -floating point units available. - -@item gas -@cindex @code{with-gnu-as} option -@vindex gas -Set to @samp{true} if you invoked @code{configure} with the -@w{@samp{--with-gnu-as}} command line option, otherwise it is empty. This is a -request to assume that the specified @var{hosttype} machine has @sc{gnu} @code{as} -available even if it ordinarily does not. - -@item srcdir -@cindex @code{srcdir} -@vindex srcdir -Set to the name of the directory containing the source for this program. -This will be different from @file{.} if you have specified the -@samp{--srcdir=@var{dir}} option. @samp{srcdir} can indicate either an -absolute path or a path relative to the build directory. - -@item package_makefile_frag -@vindex package_makefile_frag -If set in @file{configure.in}, this variable should be the name a file relative -to @samp{srcdir} to be included in the resulting @file{Makefile}. If the named -file does not exist, @code{configure} will print a warning message. This -variable is not set by @code{configure}. - -@item host_makefile_frag -@vindex host_makefile_frag -If set in @file{configure.in}, this variable should be the name a file relative -to @samp{srcdir} to be included in the resulting @file{Makefile}. If the named -file does not exist, @code{configure} will print a warning message. This -variable is not set by @code{configure}. - -@item target_makefile_frag -@vindex target_makefile_frag -If set in @file{configure.in}, this variable should be the name of a file, -relative to @samp{srcdir}, to be included in the resulting @file{Makefile}. If -the named file does not exist, @code{configure} will print a warning message. -This variable is not set by @code{configure}. - -@item site_makefile_frag -@vindex site_makefile_frag -Set to a file name representing to the default @file{Makefile} fragment for -this host. It may be set in @file{configure.in} to override this default. -Normally @samp{site_makefile_frag} is empty, but will have a value if you -specify @samp{--site=@var{site}} on the command line. -@ignore -- this doesn't fit -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 ignore - -@item Makefile -@vindex Makefile -Set to the name of the generated @file{Makefile}. Normally this value is -precisely @file{Makefile}, but some programs may want something else. - -@item removing -@cindex @code{rm} option -@vindex removing -Normally empty but will be set to some non-null value if you specified -@samp{--rm} on the command line. That is, if @samp{removing} is not empty, -then @code{configure} is @emph{removing} a configuration rather than creating -one. - -@item files -@cindex Symbolic links -@vindex files -If this variable is not empty following the @dfn{per-target} section, -then each word in its value will be the target of a symbolic link named -in the corresponding word from the @samp{links} variable. - -@item links -@cindex Symbolic links -@vindex links -If the @samp{files} variable is not empty following the @dfn{per-target} -section, then @code{configure} creates symbolic links with the first word of -@samp{links} pointing to the first word of @samp{files}, the second word of -@samp{links} pointing to the second word of @samp{files}, and so on. -@end table - -@c --------------------------------------------------------------------- -@node Minimal -@subsection A minimal @code{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 @file{Makefile} fragments if they exist. - -@c --------------------------------------------------------------------- -@node Declarations -@subsection For each invocation -@cindex For each invocation -@cindex Declarations section -@cindex @i{per-invocation} section - -@code{configure} invokes the entire shell script fragment from the start of -@file{configure.in} up to a line beginning with @w{@samp{# per-host:}} -immediately after parsing command line arguments. The variables -@samp{srctrigger} and @samp{srcname} @emph{must} be set here. - -You might also want to set the variables @samp{configdirs} and -@samp{package_makefile_frag} here. - -@c --------------------------------------------------------------------- -@node per-host -@subsection Host-specific instructions -@cindex Host-specific instructions -@cindex @i{host} shell-script fragment -@cindex @i{per-host} section - -The @dfn{per-host} section of @file{configure.in} starts with the line that -begins with @w{@samp{# per-host:}} and ends before a line beginning with -@w{@samp{# per-target:}}. @code{configure} invokes the commands in the -@dfn{per-host} section when determining host-specific information. - -This section usually contains a big @code{case} statement using the variable -@samp{host} 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 @dfn{per-target} section after determining the names of -the target specific configuration files. - -@c --------------------------------------------------------------------- -@node per-target -@subsection Target-specific instructions -@cindex Target-specific instructions -@cindex target shell-script fragment -@cindex @i{per-target} section - -The @dfn{per-target} section of @file{configure.in} starts with the line that -begins with @w{@samp{# per-target:}} and ends before the line that begins with -@w{@samp{# post-target:}}, if there is such a line. Otherwise the -@dfn{per-target} section extends to the end of the file. @code{configure} -invokes the commands in the @dfn{per-target} section when determining -target-specific information, and before building any files, directories, or -links. - -This section usually contains a big @code{case} statement using the variable -@samp{target} to determine appropriate values for @samp{target_makefile_frag} -and @samp{files}. The last lines in the @dfn{per-target} section normally set -the variables @samp{files} and @samp{links}. - -@c --------------------------------------------------------------------- -@node post-target -@subsection Instructions to be executed after target info -@cindex Post-target shell-script fragment -@cindex @i{post-target} section - -The @dfn{post-target} section is optional. If it exists, the -@samp{post-target} section starts with a line beginning with @w{@samp{# -Post-target:}} and extends to the end of the file. If it exists, -@code{configure} invokes 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 @file{Makefile} -generated by @code{configure}. - -@c --------------------------------------------------------------------- -@node Example -@subsection An example @code{configure.in} -@cindex Example @file{configure.in} -@cindex Sample @file{configure.in} -@c @cindex @code{bison} @file{configure.in} -@c this won't be the bison configure.in for long.. need better example - -Here is a small example of a @file{configure.in} file. - -@cartouche -@example -@group -# 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@}" in -m88k-motorola-*) - host_makefile_frag=config/mh-delta88 - ;; -esac - -# per-target: -files="bison_in.hairy" -links="bison.hairy" - -# post-target: -@end group -@end example -@end cartouche - -@c --------------------------------------------------------------------- -@node Install locations -@section Install locations -@cindex Where to install -@cindex Install locations - -Using the default configuration, @samp{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 @samp{prefix}. The default value of @samp{prefix} is -@samp{/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 - -@c --------------------------------------------------------------------- -@node prefix -@subsection Changing the default install directory -@cindex Changing the install directory -@cindex @code{prefix} option -@vindex prefix - -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 @samp{prefix}; in turn, this determines the -value of the @file{Makefile} variable of the same name (@samp{prefix}). - -You can also set the value of the @file{Makefile} variable @samp{prefix} -explicitly each time you invoke @code{make} if you are so inclined. However, -because many programs have this location compiled in, you must specify the -@samp{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 -@samp{prefix} can be set on the command line to @code{configure} -using the option @samp{--prefix=}. - -@c --------------------------------------------------------------------- -@node exec_prefix -@subsection Installing for multiple hosts -@cindex Configuring for multiple hosts -@cindex Sharing host-independent files -@cindex Installing host-independent files -@cindex The @code{exec_prefix} directory -@vindex exec_prefix - -By default, host dependent files are installed in subdirectories of -@file{$(exec_prefix)}. The location is determined by the value of the -@code{configure} variable @samp{exec_prefix}, which determines the value of the -@file{Makefile} variable @samp{exec_prefix}. This makes it easier to install -for a single host, and simplifies changing the default location for the install -tree. The default doesn't allow for multiple hosts to effectively share -host independent files, however. - -To configure so that multiple hosts can share common files, use something like: - -@cindex Example session -@smallexample -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 smallexample - -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, as well as removing -the host-specific object files from of the build directory. - -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. - -@xref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}, for -more information. - -@c --------------------------------------------------------------------- -@node Install details -@subsection Full descriptions of all installation subdirectories -@cindex Install details -@cindex Installation subdirectories -@cindex Subdirectories - -During any install, a number of standard directories are created. Their names -are determined by @file{Makefile} variables. Some of the defaults for -@file{Makefile} variables can be changed at configuration time using command -line options to @code{configure}. For more information on the standard -directories or the @file{Makefile} variables, please refer to @ref{Makefiles, , -Makefile Conventions, standards, GNU Coding Standards}. See also @ref{Makefile -extensions, , Extensions to the @sc{gnu} coding standards}. - -Note that @code{configure} does not create the directory indicated by the -variable @samp{srcdir} at any time. @code{$(srcdir)} is not an installation -directory. - -You can override all @file{Makefile} variables on the command line to -@code{make}. (@xref{Overriding, , Overriding Variables, make, GNU 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 @file{Makefile} fragments. See -also @ref{Sites, , Adding site info}. - -During @samp{make install}, a number of standard directories are created and -populated. The following @file{Makefile} variables define them. Those whose -defaults are set by corresponding @code{configure} variables are marked -``@code{Makefile} and @code{configure}''. - -@table @code -@item prefix (@code{Makefile} and @code{configure}) -@cindex @code{prefix} -@vindex prefix -The root of the installation tree. You can set its @file{Makefile} default -with the @samp{--prefix=} command line option to @code{configure} -(@pxref{Invoking configure, , Invoking @code{configure}}). The default value -for @samp{prefix} is @samp{/usr/local}. - -@item bindir -@cindex @code{bindir} -@vindex bindir -A directory for binary programs that users can run. The default value for -@samp{bindir} depends on @samp{prefix}; @samp{bindir} is normally changed only -indirectly through @samp{prefix}. The default value for @samp{bindir} is -@samp{$(prefix)/bin}. - -@item exec_prefix (@code{Makefile} and @code{configure}) -@cindex @code{exec_prefix} -@vindex exec_prefix -A directory for host dependent files. You can specify the @file{Makefile} -default value by using the @samp{--exec_prefix=} option to @code{configure}. -(@xref{Invoking configure, , Invoking @code{configure}}.) The default value -for @samp{exec_prefix} is @samp{$(prefix)}. - -@item libdir -@cindex @code{libdir} -@vindex libdir -A directory for libraries and support programs. The default value for -@samp{libdir} depends on @samp{prefix}; @samp{libdir} is normally changed only -indirectly through @samp{prefix}. The default value for @samp{libdir} is -@samp{$(prefix)/lib}. - -@item mandir -@cindex @code{mandir} -@vindex mandir -A directory for @code{man} format documentation (``man pages''). The default -value for @samp{mandir} depends on @samp{prefix}; @samp{mandir} is normally -changed only indirectly through @samp{prefix}. The default value for -@samp{mandir} is @samp{$(prefix)/man}. - -@item man@var{N}dir -@cindex @code{man@var{N}dir} -@vindex man@var{N}dir -These are eight variables named @samp{man1dir}, @samp{man2dir}, etc. They name -the specific directories for each man page section. For example, -@samp{man1dir} by default holds the filename @file{$(mandir)/man1}; this -directory contains @file{emacs.1} (the man page for @sc{gnu} Emacs). -Similarly, @samp{man5dir} contains the value @file{$(mandir)/man5}, indicating -the directory which holds @file{rcsfile.5} (the man page describing the -@code{rcs} data file format). The default value for any of the -@samp{man@var{N}dir} variables depends indirectly on @samp{prefix}, and is -normally changed only through @samp{prefix}. The default value for -@samp{man@var{N}dir} is @samp{$(mandir)/man@var{N}}. - -@item man@var{N}ext -@cindex @code{man@var{N}ext} -@vindex man@var{N}ext -@emph{Not supported by Cygnus @code{configure}}. The @cite{@sc{gnu} Coding -Standards} do not call for @samp{man1ext}, @samp{man2ext}, so the intended use -for @code{manext} is apparently not parallel to @samp{mandir}. Its use is not -clear. (See also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding -standards}.) - -@item infodir -@cindex @code{infodir} -@vindex infodir -A directory for @code{info} format documentation. The default value for -@samp{infodir} depends indirectly on @samp{prefix}; @samp{infodir} is -normally changed only through @samp{prefix}. The default value for -@samp{infodir} is @samp{$(prefix)/info}. - -@item docdir -@cindex @code{docdir} -@vindex 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 @samp{docdir} depends -indirectly on @samp{prefix}; @samp{docdir} is normally changed only through -@samp{prefix}. The default value for @samp{docdir} is @samp{$(datadir)/doc}. -@emph{This variable is an extension to the @sc{gnu} coding standards}. (See -also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}.) - -@item includedir -@cindex @code{includedir} -@vindex includedir -A directory for the header files accompanying the libraries installed in -@samp{libdir}. The default value for @samp{includedir} depends on -@samp{prefix}; @samp{includedir} is normally changed only indirectly -through @samp{prefix}. The default value for @samp{includedir} is -@samp{$(prefix)/include}. -@end table - -@c --------------------------------------------------------------------- -@node Host -@section Host -@cindex Host - -The arguments to @code{configure} are @dfn{hosttypes}. By -@dfn{hosttype} we mean the @dfn{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 had the @sc{gnu} @code{POSIX} emulation -libraries available, it would be possible to configure most @sc{gnu} source for -a @code{POSIX} system and build it on the obscure host. - -For more on this topic, see @ref{Host Environments, On Configuring Development -Tools, Host Environments, cfg-paper, On Configuring Development Tools}. - -@c --------------------------------------------------------------------- -@node Target -@section Target -@cindex Target - -For building native development tools, or most of the other @sc{gnu} -tools, you need not worry about the target. The @dfn{target} of a -configuration defaults to the same as the @dfn{host}. - -For building cross development tools, please see @ref{Building Development -Environments, On Configuring Development Tools, Building Development -Environments, cfg-paper, On Configuring Development Tools}. - -@c --------------------------------------------------------------------- -@node Makefile fragments -@section Adding information about local conventions -@cindex @code{Makefile} fragments -@cindex Local conventions -@cindex Adding local info -@cindex Adding site info - -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 @dfn{site-specific @file{Makefile} fragments}. See also -@ref{Sites, , Adding site info}. - -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. - -Cygnus @code{configure} uses three types of @file{Makefile} fragments. In a -generated @file{Makefile} they appear in the order: @dfn{target fragment}, -@dfn{host fragment}, and @dfn{site fragment}. This allows host fragments to -override target fragments, and site fragments to override both. - -Host-specific @file{Makefile} fragments conventionally reside in the -@file{./config/} subdirectory with names of the form @file{mh-@var{hosttype}}. -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 @file{Makefile} fragments conventionally reside in the -@file{./config/} subdirectory with names of the form @file{mt-@var{target}}. -They are used for target dependent compile time options. - -Site specific @file{Makefile} fragments conventionally reside in the -@file{./config/} subdirectory 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. - -@c --------------------------------------------------------------------- -@node Makefile extensions -@section Extensions to the @sc{gnu} coding standards -@cindex @code{Makefile} extensions -@cindex Cygnus extensions -@cindex Coding standards extensions - -The following additions to the @sc{gnu} coding standards are required for -Cygnus @code{configure} to work properly. - -@itemize @bullet -@item -The @file{Makefile} must contain exactly one line starting with @samp{####}. -This line should follow any default macro definitions but precede any rules. -Host, target, and site-specific @file{Makefile} fragments will be inserted -immediately after this line. If the line is missing, the fragments will not be -inserted. - -@item -Cygnus adds the following targets to each @file{Makefile}. Their existence is -not required for Cygnus @code{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 Makefile -@item Makefile -Calls @code{./config.status} to rebuild the @file{Makefile} in this directory. -@end table - -@item -The following @file{Makefile} targets have revised semantics: - -@table @code -@kindex install -@item install -Should @emph{not} depend on the target @samp{all}. If the program is not -already built, @samp{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, for example, when the result of a @samp{make all} is -transported via tape to another machine for installation. - -@kindex clean -@item clean -Should remove any file that can be regenerated by the @file{Makefile}, -excepting only the @file{Makefile} itself, and any links created by -@code{configure}. That is, @code{make all clean} should return all directories -to their original condition. If this is not done, then the command sequence - -@cindex Example session -@example -configure @var{host1} ; make all install clean ; -configure @var{host2} ; make all install -@end example - -@noindent -will fail because of intermediate files intended for @var{host1}. -@end table - -@item -Cygnus adds the following macros to all @file{Makefile.in} files, but -you are not required to use them to run Cygnus @code{configure}. - -@table @code -@kindex docdir -@item docdir -The directory in which to install any documentation that is not either a -@code{man} page or an @code{info} file. For @code{man} pages, see -@samp{mandir}; for @code{info}, see @samp{infodir}. - -@kindex includedir -@item includedir -The directory in which to install any header 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 @samp{includedir} may be used -by @code{cc} as well. -@end table - -@item -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 datadir -@item datadir -is used for host independent data files. - -@kindex mandir -@item mandir -The default path for @samp{mandir} depends on @samp{prefix}. - -@kindex infodir -@item infodir -The default path for @samp{infodir} depends on @samp{prefix}. - -@kindex BISON -@item BISON -is assumed to have a @code{yacc} calling convention. To use @sc{gnu} -@code{bison}, use @samp{BISON=bison -y}. -@end table - -@item -Each Cygnus @file{Makefile} also conforms to one additional restriction: - -When libraries are installed, the line containing the call to -@samp{INSTALL_DATA} should always be followed by a line containing a call to -@samp{RANLIB} on the installed library. This is to accommodate systems that -use @code{ranlib}. Systems that do not use @code{ranlib} can set @samp{RANLIB} -to ``@code{echo}'' in a host specific @file{Makefile} fragment. -@end itemize - -@c ======================================================================== -@node Porting -@chapter Porting with @code{configure} -@cindex Porting with @code{configure} - -This section explains how to add programs, host and target configuration -names, and site-specific information to Cygnus @code{configure}. - -@menu -* Programs:: Adding configure to new programs -* Hosts and targets:: Adding hosts and targets -* Sites:: Adding site info -@end menu - -@c --------------------------------------------------------------------- -@node Programs -@section Adding @code{configure} to new programs -@cindex Adding @code{configure} to new programs - -If you are writing a new program, you probably shouldn't worry about porting or -configuration issues until it is running reasonably on some host. Then refer -back to this section. - -If your program currently has a @code{configure} script that meets the @sc{gnu} -standards (@pxref{Configuration, , How Configuration Should Work, standards, -GNU Coding Standards}, please do not add Cygnus @code{configure}. It should be -possible to add this program without change to a Cygnus @code{configure} style -source tree. - -@cindex @code{autoconf} -If the program is not target dependent, please consider using @code{autoconf} -instead of Cygnus @code{configure}. @code{autoconf} is available from the Free -Software Foundation; it is a program which generates an executable shell script -called @file{configure} by automatically finding information on the system to -be configured on and embedding this information in the shell script. -@file{configure} scripts generated by @code{autoconf} require no arguments, and -accept the same options as Cygnus @code{configure}. For detailed instructions -on using @code{autoconf}, see @ref{Making configure Scripts, , How to organize -and produce Autoconf scripts, autoconf, Autoconf}. - - -To add Cygnus @code{configure} to an existing program, do the following: - -@table @bullet -@item Make sure the @file{Makefile} conforms to the @sc{gnu} standard -The coding standard for writing a @sc{gnu} @file{Makefile} is described in -@ref{Makefiles, , Makefile Conventions, standards, GNU Coding Standards}. For -technical information on writing a @file{Makefile}, see @ref{Makefiles, , -Writing Makefiles, make, GNU Make}. - -@item Add Cygnus extensions to the @file{Makefile} -These are described in @ref{Makefile extensions, , Extensions to the @sc{gnu} -coding standards}. - -@item Collect package specific definitions in a single file -Many packages are best configured using a common @file{Makefile} fragment which -is included by all of the makefiles in the different directories of the -package. In order to accomplish this, set the variable -@samp{package_makefile_fragment} to the name of the file. It will be inserted -into the final @file{Makefile} before the target-specific fragment. - -@item Move host support from @file{Makefile} to fragments -This usually involves finding sections of the @file{Makefile} that say things -like ``uncomment these lines for host @var{hosttype}'' and moving them to a new -file called @file{./config/mh-@var{hosttype}}. For more information, see @ref{Hosts -and targets, , Adding hosts and targets}. - -@item Choose defaults -If the program has compile-time options that determine the way the program -should behave, choose reasonable defaults and make these @file{Makefile} -variables. Be sure the variables are assigned their default values before the -@samp{####} line so that site-specific @file{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 generic names. Then move the specific -instances of those files into the @file{./config/} subdirectory. - -@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/} subdirectory 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 @dfn{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 files in the build directory with more generic -names. (See also @ref{Build directories, , Build directories}.) The format of -@file{configure.in} is described in @ref{configure.in, , The -@code{configure.in} input file}. - -@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}. - -@c --------------------------------------------------------------------- -@node Hosts and targets -@section Adding hosts and targets -@cindex Adding hosts and targets -@cindex Hosts and targets - -To add a host or target to a program that already uses Cygnus @code{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 -@dfn{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, , The @code{configure.in} input file}. - -@item -If you are adding a target configuration, look in @file{configure.in}, in the -@dfn{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, , The @code{configure.in} -input file}. - -@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 @samp{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, -, Variables available to @code{configure.in}}. -@end itemize - -This should be enough to @code{configure} for a new host or target -configuration name. Getting the program to compile and run properly represents -the hardest work of any port. - -@c --------------------------------------------------------------------- -@node Sites -@section Adding site info -@cindex Sites -@cindex Adding site info - -If some of the @file{Makefile} defaults are not right for your site, you can -build site-specific @file{Makefile} fragments. To do this, do the following. - -@itemize @bullet - -@item -Choose a name for your site. It must currently be less than eleven characters. - -@item -If the program source does not have a @file{./config/} subdirectory, 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 @file{Makefile} variables you need to -override to match your site's conventions. - -@item -Configure the program with: - -@cindex Example session -@example -configure @dots{} --site=@var{site} -@end example - -@end itemize - -@c --------------------------------------------------------------------- -@node Variables Index -@unnumbered Variable Index - -@printindex vr - -@page -@c --------------------------------------------------------------------- -@node Concept Index -@unnumbered 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{") - |