Return to cfg-paper.texi CVS log

Up to [Apple XNU] / GNUtools / libg++ / etc

Annotation of GNUtools/libg++/etc/cfg-paper.texi, revision 1.1

1.1     ! root        1: \input texinfo    @c -*-para-*-
        !             2: @c %**start of header
        !             3: @setfilename cfg-paper.info
        !             4: @settitle On Configuring Development Tools
        !             5: @c %**end of header
        !             6: @setchapternewpage off
        !             7: 
        !             8: @ifinfo
        !             9: This document attempts to describe the general concepts behind
        !            10: configuration of the Cygnus Support release of the @sc{gnu} Development
        !            11: Tools.  It also discusses common usage..
        !            12: 
        !            13: Copyright (C) 1991, 1992 Cygnus Support
        !            14: Permission is granted to make and distribute verbatim copies of
        !            15: this manual provided the copyright notice and this permission notice
        !            16: are preserved on all copies.
        !            17: 
        !            18: @ignore
        !            19: Permission is granted to process this file through TeX and print the
        !            20: results, provided the printed document carries copying permission
        !            21: notice identical to this one except for the removal of this paragraph
        !            22: (this paragraph not being relevant to the printed manual).
        !            23: 
        !            24: @end ignore
        !            25: Permission is granted to copy and distribute modified versions of this
        !            26: manual under the conditions for verbatim copying, provided that the entire
        !            27: resulting derived work is distributed under the terms of a permission
        !            28: notice identical to this one.
        !            29: 
        !            30: Permission is granted to copy and distribute translations of this manual
        !            31: into another language, under the above conditions for modified versions,
        !            32: except that this permission notice may be stated in a translation approved
        !            33: by Cygnus Support.
        !            34: @end ifinfo
        !            35: 
        !            36: @titlepage
        !            37: @sp 10
        !            38: @title{On Configuring Development Tools}
        !            39: @author{K. Richard Pixley, @code{rich@@cygnus.com}}
        !            40: @author{Cygnus Support}
        !            41: @page
        !            42: 
        !            43: @vskip 0pt plus 1filll
        !            44: Copyright @copyright{} 1991, 1992 Cygnus Support
        !            45: 
        !            46: Permission is granted to make and distribute verbatim copies of
        !            47: this manual provided the copyright notice and this permission notice
        !            48: are preserved on all copies.
        !            49: 
        !            50: Permission is granted to copy and distribute modified versions of this
        !            51: manual under the conditions for verbatim copying, provided that the entire
        !            52: resulting derived work is distributed under the terms of a permission
        !            53: notice identical to this one.
        !            54: 
        !            55: Permission is granted to copy and distribute translations of this manual
        !            56: into another language, under the above conditions for modified versions,
        !            57: except that this permission notice may be stated in a translation approved
        !            58: by Cygnus Support.
        !            59: @end titlepage
        !            60: 
        !            61: @ifinfo
        !            62: @format
        !            63: START-INFO-DIR-ENTRY
        !            64: * configuration: (cfg-paper).  Some theory on configuring source.
        !            65: END-INFO-DIR-ENTRY
        !            66: @end format
        !            67: @end ifinfo
        !            68: 
        !            69: @node top, Some Basic Terms, (dir), (dir)
        !            70: 
        !            71: @ifinfo
        !            72: This document attempts to describe the general concepts behind
        !            73: configuration of the Cygnus Support release of the @sc{gnu} Development
        !            74: Tools.  It also discusses common usage.
        !            75: @end ifinfo
        !            76: 
        !            77: @menu
        !            78: * Some Basic Terms::           Some Basic Terms
        !            79: * Specifics.::                 Specifics
        !            80: * Building Development Environments::  Building Development Environments
        !            81: * A Walk Through::             A Walk Through
        !            82: * Final Notes::                        Final Notes
        !            83: * Index::                      Index
        !            84: 
        !            85:  --- The Detailed Node Listing ---
        !            86: 
        !            87: Some Basic Terms
        !            88: 
        !            89: * Host Environments::          Host Environments
        !            90: * Configuration Time Options:: Configuration Time Options
        !            91: 
        !            92: A Walk Through
        !            93: 
        !            94: * Native Development Environments::  Native Development Environments
        !            95: * Emulation Environments::     Emulation Environments
        !            96: * Simple Cross Environments::  Simple Cross Environments
        !            97: * Crossing Into Targets::      Crossing Into Targets
        !            98: * Canadian Cross::             Canadian Cross
        !            99: 
        !           100: Final Notes
        !           101: 
        !           102: * Hacking Configurations::     Hacking Configurations
        !           103: @end menu
        !           104: 
        !           105: @node Some Basic Terms, Specifics., top, top
        !           106: @chapter Some Basic Terms
        !           107: 
        !           108: There are a lot of terms that are frequently used when discussing
        !           109: development tools.  Most of the common terms have been used for many
        !           110: different concepts such that their meanings have become ambiguous to the
        !           111: point of being confusing.  Typically, we only guess at their meanings
        !           112: from context and we frequently guess wrong.
        !           113: 
        !           114: This document uses very few terms by comparison.  The intent is to make
        !           115: the concepts as clear as possible in order to convey the usage and
        !           116: intent of these tools.
        !           117: 
        !           118: @emph{Programs} run on @emph{machines}.  Programs are very nearly always
        !           119: written in @emph{source}.  Programs are @emph{built} from source.
        !           120: @emph{Compilation} is a process that is frequently, but not always, used
        !           121: when building programs.
        !           122: @cindex Programs
        !           123: @cindex Machines
        !           124: @cindex Source
        !           125: @cindex Building
        !           126: @cindex Compilation
        !           127: 
        !           128: @menu
        !           129: * Host Environments::          Host Environments
        !           130: * Configuration Time Options:: Configuration Time Options
        !           131: @end menu
        !           132: 
        !           133: @node Host Environments, Configuration Time Options, Some Basic Terms, Some Basic Terms
        !           134: @section Host Environments
        !           135: 
        !           136: @cindex host
        !           137: In this document, the word @emph{host} refers to the environment in
        !           138: which the source in question will be compiled.  @emph{host} and
        !           139: @emph{host name} have nothing to do with the proper name of your host,
        !           140: like @emph{ucbvax}, @emph{prep.ai.mit.edu} or @emph{att.com}.  Instead
        !           141: they refer to things like @emph{sun4} and @emph{dec3100}.
        !           142: 
        !           143: Forget for a moment that this particular directory of source is the
        !           144: source for a development environment.  Instead, pretend that it is the
        !           145: source for a simpler, more mundane, application, say, a desk calculator.
        !           146: 
        !           147: Source that can be compiled in more than one environment, generally
        !           148: needs to be set up for each environment explicitly.  Here we refer to
        !           149: that process as configuration.  That is, we configure the source for a
        !           150: host.
        !           151: 
        !           152: For example, if we wanted to configure our mythical desk calculator to
        !           153: compile on a SparcStation, we might configure for host sun4.  With our
        !           154: configuration system:
        !           155: 
        !           156: @example
        !           157: cd desk-calculator ; ./configure sun4
        !           158: @end example
        !           159: 
        !           160: @noindent
        !           161: does the trick.  @code{configure} is a shell script that sets up Makefiles,
        !           162: subdirectories, and symbolic links appropriate for compiling the source
        !           163: on a sun4.
        !           164: 
        !           165: The @emph{host} environment does not necessarily refer to the machine on
        !           166: which the tools are built.  It is possible to provide a sun3 development
        !           167: environment on a sun4.  If we wanted to use a cross compiler on the sun4
        !           168: to build a program intended to be run on a sun3, we would configure the
        !           169: source for sun3.
        !           170: 
        !           171: @example
        !           172: cd desk-calculator ; ./configure sun3
        !           173: @end example
        !           174: 
        !           175: @noindent
        !           176: The fact that we are actually building the program on a sun4 makes no
        !           177: difference if the sun3 cross compiler presents an environment that looks
        !           178: like a sun3 from the point of view of the desk calculator source code.
        !           179: Specifically, the environment is a sun3 environment if the header files,
        !           180: predefined symbols, and libraries appear as they do on a sun3.
        !           181: 
        !           182: Nor does the host environment refer to the the machine on which the
        !           183: program to be built will run.  It is possible to provide a sun3
        !           184: emulation environment on a sun4 such that programs built in a sun3
        !           185: development environment actually run on the sun4.  This technique is
        !           186: often used within individual programs to remedy deficiencies in the host
        !           187: operating system.  For example, some operating systems do not provide
        !           188: the @code{bcopy} function and so it is emulated using the
        !           189: @code{memcpy} funtion.
        !           190: 
        !           191: Host environment simply refers to the environment in which the program
        !           192: will be built from the source.
        !           193: 
        !           194: 
        !           195: @node  Configuration Time Options,  , Host Environments, Some Basic Terms
        !           196: @section Configuration Time Options
        !           197: 
        !           198: Many programs have compile time options.  That is, features of the
        !           199: program that are either compiled into the program or not based on a
        !           200: choice made by the person who builds the program.  We refer to these as
        !           201: @emph{configuration options}.  For example, our desk calculator might be
        !           202: capable of being compiled into a program that either uses infix notation
        !           203: or postfix as a configuration option.  For a sun3, to choose infix you
        !           204: might use:
        !           205: 
        !           206: @example
        !           207: ./configure sun3 -notation=infix
        !           208: @end example
        !           209: 
        !           210: @noindent
        !           211: while for a sun4 with postfix you might use:
        !           212: 
        !           213: @example
        !           214: ./configure sun4 -notation=postfix
        !           215: @end example
        !           216: 
        !           217: If we wanted to build both at the same time, the intermediate pieces
        !           218: used in the build process must be kept separate.
        !           219: 
        !           220: @example
        !           221: mkdir ../objdir.sun4
        !           222: (cd ../objdir.sun4 ; ./configure sun4 -notation=postfix -srcdir=../src)
        !           223: mkdir ../objdir.sun3
        !           224: (cd ../objdir.sun3 ; ./configure sun3 -notation=infix -srcdir=../src)
        !           225: @end example
        !           226: 
        !           227: @noindent
        !           228: will create subdirectories for the intermediate pieces of the sun4 and
        !           229: sun3 configurations.  This is necessary as previous systems were only
        !           230: capable of one configuration at a time.  Otherwise, a second
        !           231: configuration would write over the first.  We've chosen to retain this
        !           232: behaviour so the obj directories and the @code{-srcdir} configuration
        !           233: option are necessary to get the new behaviour.  The order of the
        !           234: arguments doesn't matter.  There should be exactly one argument without
        !           235: a leading @samp{-} sign and that argument will be assumed to be the host
        !           236: name.
        !           237: 
        !           238: From here on the examples will assume that you want to build the tools
        !           239: @emph{in place} and won't show the @code{-srcdir} option, but remember
        !           240: that it is available.
        !           241: 
        !           242: In order to actually install the program, the configuration system needs
        !           243: to know where you would like the program installed.  The default
        !           244: location is @file{/usr/local}.  We refer to this location as
        !           245: @code{$(prefix)}.  All user visible programs will be installed in
        !           246: @file{@code{$(prefix)}/bin}.  All other programs and files will be
        !           247: installed in a subdirectory of @file{@code{$(prefix)}/lib}.
        !           248: 
        !           249: NOTE: @code{$(prefix)} was previously known as @code{$(destdir)}.
        !           250: 
        !           251: You can elect to change @code{$(prefix)} only as a configuration time
        !           252: option.
        !           253: 
        !           254: @example
        !           255: ./configure sun4 -notation=postfix -prefix=/local
        !           256: @end example
        !           257: 
        !           258: @noindent
        !           259: Will configure the source such that:
        !           260: 
        !           261: @example
        !           262: make install
        !           263: @end example
        !           264: 
        !           265: @noindent
        !           266: will put it's programs in @file{/local/bin} and @file{/local/lib/gcc}.
        !           267: If you change @code{$(prefix)} after building the source, you will need
        !           268: to:
        !           269: 
        !           270: @example
        !           271: make clean
        !           272: @end example
        !           273: 
        !           274: @noindent
        !           275: before the change will be propogated properly.  This is because some
        !           276: tools need to know the locations of other tools.
        !           277: 
        !           278: With these concepts in mind, we can drop the desk calculator example and
        !           279: move on to the application that resides in these directories, namely,
        !           280: the source to a development environment.
        !           281: 
        !           282: @node Specifics., Building Development Environments, Some Basic Terms, top
        !           283: @chapter Specifics
        !           284: 
        !           285: The @sc{gnu} Development Tools can be built on a wide variety of hosts.  So,
        !           286: of course, they must be configured.  Like the last example,
        !           287: 
        !           288: @example
        !           289: ./configure sun4 -prefix=/local
        !           290: ./configure sun3 -prefix=/local
        !           291: @end example
        !           292: 
        !           293: @noindent
        !           294: will configure the source to be built in subdirectories, in order to
        !           295: keep the intermediate pieces separate, and to be installed in
        !           296: @file{/local}.
        !           297: 
        !           298: When built with suitable development environments, these will be native
        !           299: tools.  We'll explain the term @emph{native} later.
        !           300: 
        !           301: @node Building Development Environments, A Walk Through, Specifics., top
        !           302: @chapter Building Development Environments
        !           303: 
        !           304: @cindex Target
        !           305: 
        !           306: The Cygnus Support @sc{gnu} development tools can not only be built in a
        !           307: number of host development environments, they can also be configured to
        !           308: create a number of different development environments on each of those
        !           309: hosts.  We refer to a specific development environment created as a
        !           310: @emph{target}.  That is, the word @emph{target} refers to the development
        !           311: environment produced by compiling this source and installing the
        !           312: resulting programs.
        !           313: 
        !           314: For the Cygnus Support @sc{gnu} development tools, the default target is the
        !           315: same as the host.  That is, the development environment produced is
        !           316: intended to be compatible with the environment used to build the tools.
        !           317: 
        !           318: In the example above, we created two configurations, one for sun4 and
        !           319: one for sun3.  The first configuration is expecting to be built in a
        !           320: sun4 development environment, to create a sun4 development environment.
        !           321: It doesn't necessarily need to be built on a sun4 if a sun4 development
        !           322: environment is available elsewhere.  Likewise, if the available sun4
        !           323: development environment produces executables intended for something
        !           324: other than sun4, then the development environment built from this sun4
        !           325: configuration will run on something other than a sun4.  From the point
        !           326: of view of the configuration system and the @sc{gnu} development tools
        !           327: source, this doesn't matter.  What matters is that they will be built in
        !           328: a sun4 environment.
        !           329: 
        !           330: Similarly, the second configuration given above is expecting to be built
        !           331: in a sun3 development environment, to create a sun3 development
        !           332: environment.
        !           333: 
        !           334: The development environment produced, is a configuration time option,
        !           335: just like @code{$(prefix)}.
        !           336: 
        !           337: @example
        !           338: ./configure sun4 -prefix=/local -target=sun3
        !           339: ./configure sun3 -prefix=/local -target=sun4
        !           340: @end example
        !           341: 
        !           342: In this example, like before, we create two configurations.  The first
        !           343: is intended to be built in a sun4 environment, in subdirectories, to be
        !           344: installed in @file{/local}.  The second is intended to be built in a
        !           345: sun3 environment, in subdirectories, to be installed in @file{/local}.
        !           346: 
        !           347: Unlike the previous example, the first configuration will produce a sun3
        !           348: development environment, perhaps even suitable for building the second
        !           349: configuration.  Likewise, the second configuration will produce a sun4
        !           350: development environment, perhaps even suitable for building the first
        !           351: configuration.
        !           352: 
        !           353: The development environment used to build these configurations will
        !           354: determine the machines on which the resulting development environments
        !           355: can be used.
        !           356: 
        !           357: 
        !           358: @node A Walk Through, Final Notes, Building Development Environments, top
        !           359: @chapter A Walk Through
        !           360: 
        !           361: 
        !           362: @menu
        !           363: * Native Development Environments::  Native Development Environments
        !           364: * Emulation Environments::     Emulation Environments
        !           365: * Simple Cross Environments::  Simple Cross Environments
        !           366: * Crossing Into Targets::      Crossing Into Targets
        !           367: * Canadian Cross::             Canadian Cross
        !           368: @end menu
        !           369: 
        !           370: @node Native Development Environments, Emulation Environments, A Walk Through, A Walk Through
        !           371: @section Native Development Environments
        !           372: 
        !           373: Let us assume for a moment that you have a sun4 and that with your sun4
        !           374: you received a development environment.  This development environment is
        !           375: intended to be run on your sun4 to build programs that can be run on
        !           376: your sun4.  You could, for instance, run this development environment on
        !           377: your sun4 to build our example desk calculator program.  You could then
        !           378: run the desk calculator program on your sun4.
        !           379: 
        !           380: @cindex Native
        !           381: @cindex Foreign
        !           382: The resulting desk calculator program is referred to as a @emph{native}
        !           383: program.  The development environment itself is composed of native
        !           384: programs that, when run, build other native programs.  Any other program
        !           385: is referred to as @emph{foreign}.  Programs intended for other machines are
        !           386: foreign programs.
        !           387: 
        !           388: This type of development environment, which is by far the most common,
        !           389: is refered to as @emph{native}.  That is, a native development environment
        !           390: runs on some machine to build programs for that same machine.  The
        !           391: process of using a native development environment to build native
        !           392: programs is called a @emph{native} build.
        !           393: 
        !           394: @example
        !           395: ./configure sun4
        !           396: @end example
        !           397: 
        !           398: @noindent
        !           399: will configure this source such that when built in a sun4 development
        !           400: environment, with a development environment that builds programs
        !           401: intended to be run on sun4 machines, the programs built will be native
        !           402: programs and the resulting development environment will be a native
        !           403: development environment.
        !           404: 
        !           405: The development system that came with your sun4 is one such environment.
        !           406: Using it to build the @sc{gnu} Development Tools is a very common activity
        !           407: and the resulting development environment is quite popular.
        !           408: 
        !           409: @example
        !           410: make all
        !           411: @end example
        !           412: 
        !           413: @noindent
        !           414: will build the tools as configured and will assume that you want to use
        !           415: the native development environment that came with your machine.
        !           416: 
        !           417: @cindex Bootstrapping
        !           418: @cindex Stage1
        !           419: Using a development environment to build a development environment is
        !           420: called @emph{bootstrapping}.  The Cygnus Support release of the @sc{gnu}
        !           421: Development Tools is capable of bootstrapping itself.  This is a very
        !           422: powerful feature that we'll return to later.  For now, let's pretend
        !           423: that you used the native development environment that came with your
        !           424: sun4 to bootstrap the Cygnus Support release and let's call the new
        !           425: development environment @emph{stage1}.
        !           426: 
        !           427: Why bother?  Well, most people find that the @sc{gnu} development
        !           428: environment builds programs that run faster and take up less space than
        !           429: the native development environments that came with their machines.  Some
        !           430: people didn't get development environments with their machines and some
        !           431: people just like using the @sc{gnu} tools better than using other tools.
        !           432: 
        !           433: @cindex Stage2
        !           434: While you're at it, if the @sc{gnu} tools produce better programs, maybe you
        !           435: should use them to build the @sc{gnu} tools.  It's a good idea, so let's
        !           436: pretend that you do.  Let's call the new development environment
        !           437: @emph{stage2}.
        !           438: 
        !           439: @cindex Stage3
        !           440: So far you've built a development environment, stage1, and you've used
        !           441: stage1 to build a new, faster and smaller development environment,
        !           442: stage2, but you haven't run any of the programs that the @sc{gnu} tools have
        !           443: built.  You really don't yet know if these tools work.  Do you have any
        !           444: programs built with the @sc{gnu} tools?  Yes, you do.  stage2.  What does
        !           445: that program do?  It builds programs.  Ok, do you have any source handy
        !           446: to build into a program?  Yes, you do.  The @sc{gnu} tools themselves.  In
        !           447: fact, if you use stage2 to build the @sc{gnu} tools again the resulting
        !           448: programs should be identical to stage2.  Let's pretend that you do and
        !           449: call the new development environment @emph{stage3}.
        !           450: 
        !           451: @cindex Three stage boot
        !           452: You've just completed what's called a @emph{three stage boot}.  You now have
        !           453: a small, fast, somewhat tested, development environment.
        !           454: 
        !           455: @example
        !           456: make bootstrap
        !           457: @end example
        !           458: 
        !           459: @noindent
        !           460: will do a three stage boot across all tools and will compare stage2 to
        !           461: stage3 and complain if they are not identical.
        !           462: 
        !           463: Once built,
        !           464: 
        !           465: @example
        !           466: make install
        !           467: @end example
        !           468: 
        !           469: @noindent
        !           470: will install the development environment in the default location or in
        !           471: @code{$(prefix)} if you specified an alternate when you configured.
        !           472: 
        !           473: @cindex Cross
        !           474: Any development environment that is not a native development environment
        !           475: is refered to as a @emph{cross} development environment.  There are many
        !           476: different types of cross development environments but most fall into one
        !           477: of three basic categories.
        !           478: 
        !           479: 
        !           480: @node Emulation Environments, Simple Cross Environments, Native Development Environments, A Walk Through
        !           481: @section Emulation Environments
        !           482: 
        !           483: @cindex Emulation
        !           484: The first category of cross development environment is called
        !           485: @emph{emulation}.  There are two primary types of emulation, but both
        !           486: types result in programs that run on the native host.
        !           487: 
        !           488: @cindex Software emulation
        !           489: @cindex Software emulator
        !           490: The first type is @emph{software emulation}.  This form of cross
        !           491: development environment involves a native program that when run on the
        !           492: native host, is capable of interpreting, and in most aspects running, a
        !           493: program intended for some other machine.  This technique is typically
        !           494: used when the other machine is either too expensive, too slow, too fast,
        !           495: or not available, perhaps because it hasn't yet been built.  The native,
        !           496: interpreting program is called a @emph{software emulator}.
        !           497: 
        !           498: The @sc{gnu} Development Tools do not currently include any software
        !           499: emulators.  Some do exist and the @sc{gnu} Development Tools can be
        !           500: configured to create simple cross development environments for with
        !           501: these emulators.  More on this later.
        !           502: 
        !           503: The second type of emulation is when source intended for some other
        !           504: development environment is built into a program intended for the native
        !           505: host.  The concepts of operating system universes and hosted operating
        !           506: systems are two such development environments.
        !           507: 
        !           508: The Cygnus Support Release of the @sc{gnu} Development Tools can be
        !           509: configured for one such emulation at this time.
        !           510: 
        !           511: @example
        !           512: ./configure sun4 -ansi
        !           513: @end example
        !           514: 
        !           515: @cindex ANSI
        !           516: @cindex X3J11
        !           517: @noindent
        !           518: will configure the source such that when built in a sun4 development
        !           519: environment the resulting development environment is capable of building
        !           520: sun4 programs from strictly conforming @sc{ANSI X3J11 C} source.
        !           521: Remember that the environment used to build the tools determines the
        !           522: machine on which this tools will run, so the resulting programs aren't
        !           523: necessarily intended to run on a sun4, although they usually are.  Also
        !           524: note that the source for the @sc{gnu} tools is not strictly conforming
        !           525: @sc{ansi} source so this configuration cannot be used to bootstrap the
        !           526: @sc{gnu} tools.
        !           527: 
        !           528: 
        !           529: @node Simple Cross Environments, Crossing Into Targets, Emulation Environments, A Walk Through
        !           530: @section Simple Cross Environments
        !           531: 
        !           532: @example
        !           533: ./configure sun4 -target=a29k
        !           534: @end example
        !           535: 
        !           536: @noindent
        !           537: will configure the tools such that when compiled in a sun4 development
        !           538: environment the resulting development environment can be used to create
        !           539: programs intended for an a29k.  Again, this does not necessarily mean
        !           540: that the new development environment can be run on a sun4.  That would
        !           541: depend on the development environment used to build these tools.
        !           542: 
        !           543: Earlier you saw how to configure the tools to build a native development
        !           544: environment, that is, a development environment that runs on your sun4
        !           545: and builds programs for your sun4.  Let's pretend that you use stage3 to
        !           546: build this simple cross configuration and let's call the new development
        !           547: environment gcc-a29k.  Remember that this is a native build.  Gcc-a29k
        !           548: is a collection of native programs intended to run on your sun4.  That's
        !           549: what stage3 builds, programs for your sun4.  Gcc-a29k represents an a29k
        !           550: development environment that builds programs intended to run on an a29k.
        !           551: But, remember, gcc-a29k runs on your sun4.  Programs built with gcc-a29k
        !           552: will run on your sun4 only with the help of an appropriate software
        !           553: emulator.
        !           554: 
        !           555: @cindex Simple cross
        !           556: @cindex Crossing to
        !           557: Building gcc-a29k is also a bootstrap but of a slightly different sort.
        !           558: We call gcc-a29k a @emph{simple cross} environment and using gcc-a29k to
        !           559: build a program intended for a29k is called @emph{crossing to} a29k.
        !           560: Simple cross environments are the second category of cross development
        !           561: environments.
        !           562: 
        !           563: 
        !           564: @node Crossing Into Targets, Canadian Cross, Simple Cross Environments, A Walk Through
        !           565: @section Crossing Into Targets
        !           566: 
        !           567: @example
        !           568: ./configure a29k -target=a29k
        !           569: @end example
        !           570: 
        !           571: @noindent
        !           572: will configure the tools such that when compiled in an a29k development
        !           573: environment, the resulting development environment can be used to create
        !           574: programs intended for an a29k.  Again, this does not necessarily mean
        !           575: that the new development environment can be run on an a29k.  That would
        !           576: depend on the development environment used to build these tools.
        !           577: 
        !           578: If you've been following along this walk through, then you've already
        !           579: built an a29k environment, namely gcc-a29k.  Let's pretend you use
        !           580: gcc-a29k to build the current configuration.
        !           581: 
        !           582: Gcc-a29k builds programs intended for the a29k so the new development
        !           583: environment will be intended for use on an a29k.  That is, this new gcc
        !           584: consists of programs that are foreign to your sun4.  They cannot be run
        !           585: on your sun4.
        !           586: 
        !           587: @cindex Crossing into
        !           588: The process of building this configuration is another a bootstrap.  This
        !           589: bootstrap is also a cross to a29k.  Because this type of build is both a
        !           590: bootstrap and a cross to a29k, it is sometimes referred to as a
        !           591: @emph{cross into} a29k.  This new development environment isn't really a
        !           592: cross development environment at all.  It is intended to run on an a29k
        !           593: to produce programs for an a29k.  You'll remember that this makes it, by
        !           594: definition, an a29k native compiler.  @emph{Crossing into} has been
        !           595: introduced here not because it is a type of cross development
        !           596: environment, but because it is frequently mistaken as one.  The process
        !           597: is @emph{a cross} but the resulting development environment is a native
        !           598: development environment.
        !           599: 
        !           600: You could not have built this configuration with stage3, because stage3
        !           601: doesn't provide an a29k environment.  Instead it provides a sun4
        !           602: environment.
        !           603: 
        !           604: If you happen to have an a29k lying around, you could now use this fresh
        !           605: development environment on the a29k to three-stage these tools all over
        !           606: again.  This process would look just like it did when we built the
        !           607: native sun4 development environment because we would be building another
        !           608: native development environment, this one on a29k.
        !           609: 
        !           610: 
        !           611: @node Canadian Cross,  , Crossing Into Targets, A Walk Through
        !           612: @section Canadian Cross
        !           613: 
        !           614: So far you've seen that our development environment source must be
        !           615: configured for a specific host and for a specific target.  You've also
        !           616: seen that the resulting development environment depends on the
        !           617: development environment used in the build process.
        !           618: 
        !           619: When all four match identically, that is, the configured host, the
        !           620: configured target, the environment presented by the development
        !           621: environment used in the build, and the machine on which the resulting
        !           622: development environment is intended to run, then the new development
        !           623: environment will be a native development environment.
        !           624: 
        !           625: When all four match except the configured host, then we can assume that
        !           626: the development environment used in the build is some form of library
        !           627: emulation.
        !           628: 
        !           629: When all four match except for the configured target, then the resulting
        !           630: development environment will be a simple cross development environment.
        !           631: 
        !           632: When all four match except for the host on which the development
        !           633: environment used in the build runs, the build process is a @emph{cross into}
        !           634: and the resulting development environment will be native to some other
        !           635: machine.
        !           636: 
        !           637: Most of the other permutations do exist in some form, but only one more
        !           638: is interesting to the current discussion.
        !           639: 
        !           640: @example
        !           641: ./configure a29k -target=sun3
        !           642: @end example
        !           643: 
        !           644: @noindent
        !           645: will configure the tools such that when compiled in an a29k development
        !           646: environment, the resulting development environment can be used to create
        !           647: programs intended for a sun3.  Again, this does not necessarily mean
        !           648: that the new development environment can be run on an a29k.  That would
        !           649: depend on the development environment used to build these tools.
        !           650: 
        !           651: If you are still following along, then you have two a29k development
        !           652: environments, the native development environment that runs on a29k, and
        !           653: the simple cross that runs on your sun4.  If you use the a29k native
        !           654: development environment on the a29k, you will be doing the same thing we
        !           655: did a while back, namely building a simple cross from a29k to sun3.
        !           656: Let's pretend that instead, you use gcc-a29k, the simple cross
        !           657: development environment that runs on sun4 but produces programs for
        !           658: a29k.
        !           659: 
        !           660: The resulting development environment will run on a29k because that's
        !           661: what gcc-a29k builds, a29k programs.  This development environment will
        !           662: produce programs for a sun3 because that is how it was configured.  This
        !           663: means that the resulting development environment is a simple cross.
        !           664: 
        !           665: @cindex Canadian Cross
        !           666: @cindex Three party cross
        !           667: There really isn't a common name for this process because very few
        !           668: development environments are capable of being configured this
        !           669: extensively.  For the sake of discussion, let's call this process a
        !           670: @emph{Canadian cross}.  It's a three party cross, Canada has a three
        !           671: party system, hence Canadian Cross.
        !           672: 
        !           673: @node Final Notes, Index, A Walk Through, top
        !           674: @chapter Final Notes
        !           675: 
        !           676: By @emph{configures}, I mean that links, Makefile, .gdbinit, and
        !           677: config.status are built.  Configuration is always done from the source
        !           678: directory.
        !           679: 
        !           680: @table @code
        !           681: 
        !           682: @item ./configure @var{name}
        !           683: configures this directory, perhaps recursively, for a single host+target
        !           684: pair where the host and target are both @var{name}.  If a previous
        !           685: configuration existed, it will be overwritten.
        !           686: 
        !           687: @item ./configure @var{hostname} -target=@var{targetname}
        !           688: configures this directory, perhaps recursively, for a single host+target
        !           689: pair where the host is @var{hostname} and target is @var{targetname}.
        !           690: If a previous configuration existed, it will be overwritten.
        !           691: 
        !           692: @end table
        !           693: 
        !           694: @menu
        !           695: * Hacking Configurations::     Hacking Configurations
        !           696: @end menu
        !           697: 
        !           698: @node Hacking Configurations,  , Final Notes, Final Notes
        !           699: @section Hacking Configurations
        !           700: 
        !           701: The configure scripts essentially do three things, create subdirectories
        !           702: if appropriate, build a @file{Makefile}, and create links to files, all
        !           703: based on and tailored to, a specific host+target pair.  The scripts also
        !           704: create a @file{.gdbinit} if appropriate but this is not tailored.
        !           705: 
        !           706: The Makefile is created by prepending some variable definitions to a
        !           707: Makefile template called @file{Makefile.in} and then inserting host and
        !           708: target specific Makefile fragments.  The variables are set based on the
        !           709: chosen host+target pair and build style, that is, if you use
        !           710: @code{-srcdir} or not.  The host and target specific Makefile may or may
        !           711: not exist.
        !           712: 
        !           713: @itemize @bullet
        !           714: 
        !           715: @item
        !           716: Makefiles can be edited directly, but those changes will eventually be
        !           717: lost.  Changes intended to be permanent for a specific host should be
        !           718: made to the host specific Makefile fragment.  This should be in
        !           719: @file{./config/mh-@var{host}} if it exists.  Changes intended to be
        !           720: permanent for a specific target should be made to the target specific
        !           721: Makefile fragment.  This should be in @file{./config/mt-@var{target}} if
        !           722: it exists.  Changes intended to be permanent for the directory should be
        !           723: made in @file{Makefile.in}.  To propogate changes to any of these,
        !           724: either use @code{make Makefile} or @code{./config.status} or
        !           725: re-configure.
        !           726: 
        !           727: @end itemize
        !           728: 
        !           729: @page
        !           730: @node Index,  , Final Notes, top
        !           731: @appendix Index
        !           732: 
        !           733: @printindex cp
        !           734: 
        !           735: @contents
        !           736: @bye
        !           737: 
        !           738: @c Local Variables:
        !           739: @c fill-column: 72
        !           740: @c End:

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.