\input texinfo    @c -*-para-*-@c %**start of header@setfilename cfg-paper.info@settitle On Configuring Development Tools@c %**end of header@setchapternewpage off@ifinfoThis document attempts to describe the general concepts behindconfiguration of the Cygnus Support release of the @sc{gnu} DevelopmentTools.  It also discusses common usage..Copyright 1991, 1992 Free Software Foundation, Inc.Permission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies.@ignorePermission is granted to process this file through TeX and print theresults, provided the printed document carries copying permissionnotice identical to this one except for the removal of this paragraph(this paragraph not being relevant to the printed manual).@end ignorePermission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that the entireresulting derived work is distributed under the terms of a permissionnotice identical to this one.Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions,except that this permission notice may be stated in a translation approvedby 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 1filllCopyright @copyright{} 1991, 1992 Free Software Foundation, Inc.Permission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies.Permission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that the entireresulting derived work is distributed under the terms of a permissionnotice identical to this one.Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions,except that this permission notice may be stated in a translation approvedby Cygnus Support.@end titlepage@ifinfo@formatSTART-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)@ifinfoThis document attempts to describe the general concepts behindconfiguration of the Cygnus Support release of the @sc{gnu} DevelopmentTools.  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 OptionsA 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 CrossFinal Notes* Hacking Configurations::	Hacking Configurations@end menu@node Some Basic Terms, Specifics., top, top@chapter Some Basic TermsThere are a lot of terms that are frequently used when discussingdevelopment tools.  Most of the common terms have been used for manydifferent concepts such that their meanings have become ambiguous to thepoint of being confusing.  Typically, we only guess at their meaningsfrom context and we frequently guess wrong.This document uses very few terms by comparison.  The intent is to makethe concepts as clear as possible in order to convey the usage andintent of these tools.@emph{Programs} run on @emph{machines}.  Programs are very nearly alwayswritten in @emph{source}.  Programs are @emph{built} from source.@emph{Compilation} is a process that is frequently, but not always, usedwhen 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 hostIn this document, the word @emph{host} refers to the environment inwhich 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}.  Insteadthey refer to things like @emph{sun4} and @emph{dec3100}.Forget for a moment that this particular directory of source is thesource for a development environment.  Instead, pretend that it is thesource for a simpler, more mundane, application, say, a desk calculator.Source that can be compiled in more than one environment, generallyneeds to be set up for each environment explicitly.  Here we refer tothat process as configuration.  That is, we configure the source for ahost.For example, if we wanted to configure our mythical desk calculator tocompile on a SparcStation, we might configure for host sun4.  With ourconfiguration system:@examplecd desk-calculator ; ./configure sun4@end example@noindentdoes the trick.  @code{configure} is a shell script that sets up Makefiles,subdirectories, and symbolic links appropriate for compiling the sourceon a sun4.The @emph{host} environment does not necessarily refer to the machine onwhich the tools are built.  It is possible to provide a sun3 developmentenvironment on a sun4.  If we wanted to use a cross compiler on the sun4to build a program intended to be run on a sun3, we would configure thesource for sun3.@examplecd desk-calculator ; ./configure sun3@end example@noindentThe fact that we are actually building the program on a sun4 makes nodifference if the sun3 cross compiler presents an environment that lookslike 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 theprogram to be built will run.  It is possible to provide a sun3emulation environment on a sun4 such that programs built in a sun3development environment actually run on the sun4.  This technique isoften used within individual programs to remedy deficiencies in the hostoperating system.  For example, some operating systems do not providethe @code{bcopy} function and so it is emulated using the@code{memcpy} funtion.Host environment simply refers to the environment in which the programwill be built from the source.@node  Configuration Time Options,  , Host Environments, Some Basic Terms@section Configuration Time OptionsMany programs have compile time options.  That is, features of theprogram that are either compiled into the program or not based on achoice made by the person who builds the program.  We refer to these as@emph{configuration options}.  For example, our desk calculator might becapable of being compiled into a program that either uses infix notationor postfix as a configuration option.  For a sun3, to choose infix youmight use:@example./configure sun3 -notation=infix@end example@noindentwhile for a sun4 with postfix you might use:@example./configure sun4 -notation=postfix@end exampleIf we wanted to build both at the same time, the intermediate piecesused in the build process must be kept separate.@examplemkdir ../objdir.sun4(cd ../objdir.sun4 ; ./configure sun4 -notation=postfix -srcdir=../src)mkdir ../objdir.sun3(cd ../objdir.sun3 ; ./configure sun3 -notation=infix -srcdir=../src)@end example@noindentwill create subdirectories for the intermediate pieces of the sun4 andsun3 configurations.  This is necessary as previous systems were onlycapable of one configuration at a time.  Otherwise, a secondconfiguration would write over the first.  We've chosen to retain thisbehaviour so the obj directories and the @code{-srcdir} configurationoption are necessary to get the new behaviour.  The order of thearguments doesn't matter.  There should be exactly one argument withouta leading @samp{-} sign and that argument will be assumed to be the hostname.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 rememberthat it is available.In order to actually install the program, the configuration system needsto know where you would like the program installed.  The defaultlocation 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 beinstalled in a subdirectory of @file{@code{$(prefix)}/lib}.NOTE: @code{$(prefix)} was previously known as @code{$(destdir)}.You can elect to change @code{$(prefix)} only as a configuration timeoption.@example./configure sun4 -notation=postfix -prefix=/local@end example@noindentWill configure the source such that:@examplemake install@end example@noindentwill put it's programs in @file{/local/bin} and @file{/local/lib/gcc}.If you change @code{$(prefix)} after building the source, you will needto:@examplemake clean@end example@noindentbefore the change will be propogated properly.  This is because sometools need to know the locations of other tools.With these concepts in mind, we can drop the desk calculator example andmove 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 SpecificsThe @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@noindentwill configure the source to be built in subdirectories, in order tokeep the intermediate pieces separate, and to be installed in@file{/local}.When built with suitable development environments, these will be nativetools.  We'll explain the term @emph{native} later.@node Building Development Environments, A Walk Through, Specifics., top@chapter Building Development Environments@cindex TargetThe Cygnus Support @sc{gnu} development tools can not only be built in anumber of host development environments, they can also be configured tocreate a number of different development environments on each of thosehosts.  We refer to a specific development environment created as a@emph{target}.  That is, the word @emph{target} refers to the developmentenvironment produced by compiling this source and installing theresulting programs.For the Cygnus Support @sc{gnu} development tools, the default target is thesame as the host.  That is, the development environment produced isintended to be compatible with the environment used to build the tools.In the example above, we created two configurations, one for sun4 andone for sun3.  The first configuration is expecting to be built in asun4 development environment, to create a sun4 development environment.It doesn't necessarily need to be built on a sun4 if a sun4 developmentenvironment is available elsewhere.  Likewise, if the available sun4development environment produces executables intended for somethingother than sun4, then the development environment built from this sun4configuration will run on something other than a sun4.  From the pointof view of the configuration system and the @sc{gnu} development toolssource, this doesn't matter.  What matters is that they will be built ina sun4 environment.Similarly, the second configuration given above is expecting to be builtin a sun3 development environment, to create a sun3 developmentenvironment.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 exampleIn this example, like before, we create two configurations.  The firstis intended to be built in a sun4 environment, in subdirectories, to beinstalled in @file{/local}.  The second is intended to be built in asun3 environment, in subdirectories, to be installed in @file{/local}.Unlike the previous example, the first configuration will produce a sun3development environment, perhaps even suitable for building the secondconfiguration.  Likewise, the second configuration will produce a sun4development environment, perhaps even suitable for building the firstconfiguration.The development environment used to build these configurations willdetermine the machines on which the resulting development environmentscan 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