| 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 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 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.info). 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, in the same directory |
| 218 | structure, the intermediate pieces used in the build process must be |
| 219 | kept separate. |
| 220 | |
| 221 | @example |
| 222 | ./configure sun4 -subdirs -notation=postfix |
| 223 | ./configure sun3 -subdirs -notation=infix |
| 224 | @end example |
| 225 | |
| 226 | @noindent |
| 227 | will create subdirectories for the intermediate pieces of the sun4 and |
| 228 | sun3 configurations. This is necessary as previous systems were only |
| 229 | capable of one configuration at a time. Otherwise, a second |
| 230 | configuration would write over the first. We've chosen to retain this |
| 231 | behaviour so the @code{-subdirs} configuration option is necessary to |
| 232 | get the new behaviour. The order of the arguments doesn't matter. |
| 233 | There should be exactly one argument without a leading @samp{-} sign |
| 234 | and that argument will be assumed to be the host name. |
| 235 | |
| 236 | From here on the examples will assume that you want to build the tools |
| 237 | @emph{in place} and won't show the @code{-subdirs} option, but remember |
| 238 | that it is available. |
| 239 | |
| 240 | In order to actually install the program, the configuration system needs |
| 241 | to know where you would like the program installed. The default |
| 242 | location is @file{/usr/local}. We refer to this location as |
| 243 | @code{$(prefix)}. All user visible programs will be installed in |
| 244 | @file{@code{$(prefix)}/bin}. All other programs and files will be |
| 245 | installed in a subdirectory of @file{@code{$(prefix)}/lib}. |
| 246 | |
| 247 | NOTE: @code{$(prefix)} was previously known as @code{$(destdir)}. |
| 248 | |
| 249 | You can elect to change @code{$(prefix)} only as a configuration time |
| 250 | option. |
| 251 | |
| 252 | @example |
| 253 | ./configure sun4 -notation=postfix -prefix=/local |
| 254 | @end example |
| 255 | |
| 256 | @noindent |
| 257 | Will configure the source such that: |
| 258 | |
| 259 | @example |
| 260 | make install |
| 261 | @end example |
| 262 | |
| 263 | @noindent |
| 264 | will put it's programs in @file{/local/bin} and @file{/local/lib/gcc}. |
| 265 | If you change @code{$(prefix)} after building the source, you will need |
| 266 | to: |
| 267 | |
| 268 | @example |
| 269 | make clean |
| 270 | @end example |
| 271 | |
| 272 | @noindent |
| 273 | before the change will be propogated properly. This is because some |
| 274 | tools need to know the locations of other tools. |
| 275 | |
| 276 | With these concepts in mind, we can drop the desk calculator example and |
| 277 | move on to the application that resides in these directories, namely, |
| 278 | the source to a development environment. |
| 279 | |
| 280 | @node Specifics., Building Development Environments, Some Basic Terms, top |
| 281 | @chapter Specifics |
| 282 | |
| 283 | The @sc{gnu} Development Tools can be built on a wide variety of hosts. So, |
| 284 | of course, they must be configured. Like the last example, |
| 285 | |
| 286 | @example |
| 287 | ./configure sun4 -prefix=/local |
| 288 | ./configure sun3 -prefix=/local |
| 289 | @end example |
| 290 | |
| 291 | @noindent |
| 292 | will configure the source to be built in subdirectories, in order to |
| 293 | keep the intermediate pieces separate, and to be installed in |
| 294 | @file{/local}. |
| 295 | |
| 296 | When built with suitable development environments, these will be native |
| 297 | tools. We'll explain the term @emph{native} later. |
| 298 | |
| 299 | @node Building Development Environments, A Walk Through, Specifics., top |
| 300 | @chapter Building Development Environments |
| 301 | |
| 302 | @cindex Target |
| 303 | |
| 304 | The Cygnus Support @sc{gnu} development tools can not only be built in a |
| 305 | number of host development environments, they can also be configured to |
| 306 | create a number of different development environments on each of those |
| 307 | hosts. We refer to a specific development environment created as a |
| 308 | @emph{target}. That is, the word @emph{target} refers to the development |
| 309 | environment produced by compiling this source and installing the |
| 310 | resulting programs. |
| 311 | |
| 312 | For the Cygnus Support @sc{gnu} development tools, the default target is the |
| 313 | same as the host. That is, the development environment produced is |
| 314 | intended to be compatible with the environment used to build the tools. |
| 315 | |
| 316 | In the example above, we created two configurations, one for sun4 and |
| 317 | one for sun3. The first configuration is expecting to be built in a |
| 318 | sun4 development environment, to create a sun4 development environment. |
| 319 | It doesn't necessarily need to be built on a sun4 if a sun4 development |
| 320 | environment is available elsewhere. Likewise, if the available sun4 |
| 321 | development environment produces executables intended for something |
| 322 | other than sun4, then the development environment built from this sun4 |
| 323 | configuration will run on something other than a sun4. From the point |
| 324 | of view of the configuration system and the @sc{gnu} development tools |
| 325 | source, this doesn't matter. What matters is that they will be built in |
| 326 | a sun4 environment. |
| 327 | |
| 328 | Similarly, the second configuration given above is expecting to be built |
| 329 | in a sun3 development environment, to create a sun3 development |
| 330 | environment. |
| 331 | |
| 332 | The development environment produced, is a configuration time option, |
| 333 | just like @code{$(prefix)}. |
| 334 | |
| 335 | @example |
| 336 | ./configure sun4 -prefix=/local -target=sun3 |
| 337 | ./configure sun3 -prefix=/local -target=sun4 |
| 338 | @end example |
| 339 | |
| 340 | In this example, like before, we create two configurations. The first |
| 341 | is intended to be built in a sun4 environment, in subdirectories, to be |
| 342 | installed in @file{/local}. The second is intended to be built in a |
| 343 | sun3 environment, in subdirectories, to be installed in @file{/local}. |
| 344 | |
| 345 | Unlike the previous example, the first configuration will produce a sun3 |
| 346 | development environment, perhaps even suitable for building the second |
| 347 | configuration. Likewise, the second configuration will produce a sun4 |
| 348 | development environment, perhaps even suitable for building the first |
| 349 | configuration. |
| 350 | |
| 351 | The development environment used to build these configurations will |
| 352 | determine the machines on which the resulting development environments |
| 353 | can be used. |
| 354 | |
| 355 | |
| 356 | @node A Walk Through, Final Notes, Building Development Environments, top |
| 357 | @chapter A Walk Through |
| 358 | |
| 359 | |
| 360 | @menu |
| 361 | * Native Development Environments:: Native Development Environments |
| 362 | * Emulation Environments:: Emulation Environments |
| 363 | * Simple Cross Environments:: Simple Cross Environments |
| 364 | * Crossing Into Targets:: Crossing Into Targets |
| 365 | * Canadian Cross:: Canadian Cross |
| 366 | @end menu |
| 367 | |
| 368 | @node Native Development Environments, Emulation Environments, A Walk Through, A Walk Through |
| 369 | @section Native Development Environments |
| 370 | |
| 371 | Let us assume for a moment that you have a sun4 and that with your sun4 |
| 372 | you received a development environment. This development environment is |
| 373 | intended to be run on your sun4 to build programs that can be run on |
| 374 | your sun4. You could, for instance, run this development environment on |
| 375 | your sun4 to build our example desk calculator program. You could then |
| 376 | run the desk calculator program on your sun4. |
| 377 | |
| 378 | @cindex Native |
| 379 | @cindex Foreign |
| 380 | The resulting desk calculator program is referred to as a @emph{native} |
| 381 | program. The development environment itself is composed of native |
| 382 | programs that, when run, build other native programs. Any other program |
| 383 | is referred to as @emph{foreign}. Programs intended for other machines are |
| 384 | foreign programs. |
| 385 | |
| 386 | This type of development environment, which is by far the most common, |
| 387 | is refered to as @emph{native}. That is, a native development environment |
| 388 | runs on some machine to build programs for that same machine. The |
| 389 | process of using a native development environment to build native |
| 390 | programs is called a @emph{native} build. |
| 391 | |
| 392 | @example |
| 393 | ./configure sun4 |
| 394 | @end example |
| 395 | |
| 396 | @noindent |
| 397 | will configure this source such that when built in a sun4 development |
| 398 | environment, with a development environment that builds programs |
| 399 | intended to be run on sun4 machines, the programs built will be native |
| 400 | programs and the resulting development environment will be a native |
| 401 | development environment. |
| 402 | |
| 403 | The development system that came with your sun4 is one such environment. |
| 404 | Using it to build the @sc{gnu} Development Tools is a very common activity |
| 405 | and the resulting development environment is quite popular. |
| 406 | |
| 407 | @example |
| 408 | make all |
| 409 | @end example |
| 410 | |
| 411 | @noindent |
| 412 | will build the tools as configured and will assume that you want to use |
| 413 | the native development environment that came with your machine. |
| 414 | |
| 415 | @cindex Bootstrapping |
| 416 | @cindex Stage1 |
| 417 | Using a development environment to build a development environment is |
| 418 | called @emph{bootstrapping}. The Cygnus Support release of the @sc{gnu} |
| 419 | Development Tools is capable of bootstrapping itself. This is a very |
| 420 | powerful feature that we'll return to later. For now, let's pretend |
| 421 | that you used the native development environment that came with your |
| 422 | sun4 to bootstrap the Cygnus Support release and let's call the new |
| 423 | development environment @emph{stage1}. |
| 424 | |
| 425 | Why bother? Well, most people find that the @sc{gnu} development |
| 426 | environment builds programs that run faster and take up less space than |
| 427 | the native development environments that came with their machines. Some |
| 428 | people didn't get development environments with their machines and some |
| 429 | people just like using the @sc{gnu} tools better than using other tools. |
| 430 | |
| 431 | @cindex Stage2 |
| 432 | While you're at it, if the @sc{gnu} tools produce better programs, maybe you |
| 433 | should use them to build the @sc{gnu} tools. It's a good idea, so let's |
| 434 | pretend that you do. Let's call the new development environment |
| 435 | @emph{stage2}. |
| 436 | |
| 437 | @cindex Stage3 |
| 438 | So far you've built a development environment, stage1, and you've used |
| 439 | stage1 to build a new, faster and smaller development environment, |
| 440 | stage2, but you haven't run any of the programs that the @sc{gnu} tools have |
| 441 | built. You really don't yet know if these tools work. Do you have any |
| 442 | programs built with the @sc{gnu} tools? Yes, you do. stage2. What does |
| 443 | that program do? It builds programs. Ok, do you have any source handy |
| 444 | to build into a program? Yes, you do. The @sc{gnu} tools themselves. In |
| 445 | fact, if you use stage2 to build the @sc{gnu} tools again the resulting |
| 446 | programs should be identical to stage2. Let's pretend that you do and |
| 447 | call the new development environment @emph{stage3}. |
| 448 | |
| 449 | @cindex Three stage boot |
| 450 | You've just completed what's called a @emph{three stage boot}. You now have |
| 451 | a small, fast, somewhat tested, development environment. |
| 452 | |
| 453 | @example |
| 454 | make bootstrap |
| 455 | @end example |
| 456 | |
| 457 | @noindent |
| 458 | will do a three stage boot across all tools and will compare stage2 to |
| 459 | stage3 and complain if they are not identical. |
| 460 | |
| 461 | Once built, |
| 462 | |
| 463 | @example |
| 464 | make install |
| 465 | @end example |
| 466 | |
| 467 | @noindent |
| 468 | will install the development environment in the default location or in |
| 469 | @code{$(prefix)} if you specified an alternate when you configured. |
| 470 | |
| 471 | @cindex Cross |
| 472 | Any development environment that is not a native development environment |
| 473 | is refered to as a @emph{cross} development environment. There are many |
| 474 | different types of cross development environments but most fall into one |
| 475 | of three basic categories. |
| 476 | |
| 477 | |
| 478 | @node Emulation Environments, Simple Cross Environments, Native Development Environments, A Walk Through |
| 479 | @section Emulation Environments |
| 480 | |
| 481 | @cindex Emulation |
| 482 | The first category of cross development environment is called |
| 483 | @emph{emulation}. There are two primary types of emulation, but both |
| 484 | types result in programs that run on the native host. |
| 485 | |
| 486 | @cindex Software emulation |
| 487 | @cindex Software emulator |
| 488 | The first type is @emph{software emulation}. This form of cross |
| 489 | development environment involves a native program that when run on the |
| 490 | native host, is capable of interpreting, and in most aspects running, a |
| 491 | program intended for some other machine. This technique is typically |
| 492 | used when the other machine is either too expensive, too slow, too fast, |
| 493 | or not available, perhaps because it hasn't yet been built. The native, |
| 494 | interpreting program is called a @emph{software emulator}. |
| 495 | |
| 496 | The @sc{gnu} Development Tools do not currently include any software |
| 497 | emulators. Some do exist and the @sc{gnu} Development Tools can be |
| 498 | configured to create simple cross development environments for with |
| 499 | these emulators. More on this later. |
| 500 | |
| 501 | The second type of emulation is when source intended for some other |
| 502 | development environment is built into a program intended for the native |
| 503 | host. The concepts of operating system universes and hosted operating |
| 504 | systems are two such development environments. |
| 505 | |
| 506 | The Cygnus Support Release of the @sc{gnu} Development Tools can be |
| 507 | configured for one such emulation at this time. |
| 508 | |
| 509 | @example |
| 510 | ./configure sun4 -ansi |
| 511 | @end example |
| 512 | |
| 513 | @cindex ANSI |
| 514 | @cindex X3J11 |
| 515 | @noindent |
| 516 | will configure the source such that when built in a sun4 development |
| 517 | environment the resulting development environment is capable of building |
| 518 | sun4 programs from strictly conforming @sc{ANSI X3J11 C} source. |
| 519 | Remember that the environment used to build the tools determines the |
| 520 | machine on which this tools will run, so the resulting programs aren't |
| 521 | necessarily intended to run on a sun4, although they usually are. Also |
| 522 | note that the source for the @sc{gnu} tools is not strictly conforming |
| 523 | @sc{ansi} source so this configuration cannot be used to bootstrap the |
| 524 | @sc{gnu} tools. |
| 525 | |
| 526 | |
| 527 | @node Simple Cross Environments, Crossing Into Targets, Emulation Environments, A Walk Through |
| 528 | @section Simple Cross Environments |
| 529 | |
| 530 | @example |
| 531 | ./configure sun4 -target=a29k |
| 532 | @end example |
| 533 | |
| 534 | @noindent |
| 535 | will configure the tools such that when compiled in a sun4 development |
| 536 | environment the resulting development environment can be used to create |
| 537 | programs intended for an a29k. Again, this does not necessarily mean |
| 538 | that the new development environment can be run on a sun4. That would |
| 539 | depend on the development environment used to build these tools. |
| 540 | |
| 541 | Earlier you saw how to configure the tools to build a native development |
| 542 | environment, that is, a development environment that runs on your sun4 |
| 543 | and builds programs for your sun4. Let's pretend that you use stage3 to |
| 544 | build this simple cross configuration and let's call the new development |
| 545 | environment gcc-a29k. Remember that this is a native build. Gcc-a29k |
| 546 | is a collection of native programs intended to run on your sun4. That's |
| 547 | what stage3 builds, programs for your sun4. Gcc-a29k represents an a29k |
| 548 | development environment that builds programs intended to run on an a29k. |
| 549 | But, remember, gcc-a29k runs on your sun4. Programs built with gcc-a29k |
| 550 | will run on your sun4 only with the help of an appropriate software |
| 551 | emulator. |
| 552 | |
| 553 | @cindex Simple cross |
| 554 | @cindex Crossing to |
| 555 | Building gcc-a29k is also a bootstrap but of a slightly different sort. |
| 556 | We call gcc-a29k a @emph{simple cross} environment and using gcc-a29k to |
| 557 | build a program intended for a29k is called @emph{crossing to} a29k. |
| 558 | Simple cross environments are the second category of cross development |
| 559 | environments. |
| 560 | |
| 561 | |
| 562 | @node Crossing Into Targets, Canadian Cross, Simple Cross Environments, A Walk Through |
| 563 | @section Crossing Into Targets |
| 564 | |
| 565 | @example |
| 566 | ./configure a29k -target=a29k |
| 567 | @end example |
| 568 | |
| 569 | @noindent |
| 570 | will configure the tools such that when compiled in an a29k development |
| 571 | environment, the resulting development environment can be used to create |
| 572 | programs intended for an a29k. Again, this does not necessarily mean |
| 573 | that the new development environment can be run on an a29k. That would |
| 574 | depend on the development environment used to build these tools. |
| 575 | |
| 576 | If you've been following along this walk through, then you've already |
| 577 | built an a29k environment, namely gcc-a29k. Let's pretend you use |
| 578 | gcc-a29k to build the current configuration. |
| 579 | |
| 580 | Gcc-a29k builds programs intended for the a29k so the new development |
| 581 | environment will be intended for use on an a29k. That is, this new gcc |
| 582 | consists of programs that are foreign to your sun4. They cannot be run |
| 583 | on your sun4. |
| 584 | |
| 585 | @cindex Crossing into |
| 586 | The process of building this configuration is another a bootstrap. This |
| 587 | bootstrap is also a cross to a29k. Because this type of build is both a |
| 588 | bootstrap and a cross to a29k, it is sometimes referred to as a |
| 589 | @emph{cross into} a29k. This new development environment isn't really a |
| 590 | cross development environment at all. It is intended to run on an a29k |
| 591 | to produce programs for an a29k. You'll remember that this makes it, by |
| 592 | definition, an a29k native compiler. @emph{Crossing into} has been |
| 593 | introduced here not because it is a type of cross development |
| 594 | environment, but because it is frequently mistaken as one. The process |
| 595 | is @emph{a cross} but the resulting development environment is a native |
| 596 | development environment. |
| 597 | |
| 598 | You could not have built this configuration with stage3, because stage3 |
| 599 | doesn't provide an a29k environment. Instead it provides a sun4 |
| 600 | environment. |
| 601 | |
| 602 | If you happen to have an a29k lying around, you could now use this fresh |
| 603 | development environment on the a29k to three-stage these tools all over |
| 604 | again. This process would look just like it did when we built the |
| 605 | native sun4 development environment because we would be building another |
| 606 | native development environment, this one on a29k. |
| 607 | |
| 608 | |
| 609 | @node Canadian Cross, , Crossing Into Targets, A Walk Through |
| 610 | @section Canadian Cross |
| 611 | |
| 612 | So far you've seen that our development environment source must be |
| 613 | configured for a specific host and for a specific target. You've also |
| 614 | seen that the resulting development environment depends on the |
| 615 | development environment used in the build process. |
| 616 | |
| 617 | When all four match identically, that is, the configured host, the |
| 618 | configured target, the environment presented by the development |
| 619 | environment used in the build, and the machine on which the resulting |
| 620 | development environment is intended to run, then the new development |
| 621 | environment will be a native development environment. |
| 622 | |
| 623 | When all four match except the configured host, then we can assume that |
| 624 | the development environment used in the build is some form of library |
| 625 | emulation. |
| 626 | |
| 627 | When all four match except for the configured target, then the resulting |
| 628 | development environment will be a simple cross development environment. |
| 629 | |
| 630 | When all four match except for the host on which the development |
| 631 | environment used in the build runs, the build process is a @emph{cross into} |
| 632 | and the resulting development environment will be native to some other |
| 633 | machine. |
| 634 | |
| 635 | Most of the other permutations do exist in some form, but only one more |
| 636 | is interesting to the current discussion. |
| 637 | |
| 638 | @example |
| 639 | ./configure a29k -target=sun3 |
| 640 | @end example |
| 641 | |
| 642 | @noindent |
| 643 | will configure the tools such that when compiled in an a29k development |
| 644 | environment, the resulting development environment can be used to create |
| 645 | programs intended for a sun3. Again, this does not necessarily mean |
| 646 | that the new development environment can be run on an a29k. That would |
| 647 | depend on the development environment used to build these tools. |
| 648 | |
| 649 | If you are still following along, then you have two a29k development |
| 650 | environments, the native development environment that runs on a29k, and |
| 651 | the simple cross that runs on your sun4. If you use the a29k native |
| 652 | development environment on the a29k, you will be doing the same thing we |
| 653 | did a while back, namely building a simple cross from a29k to sun3. |
| 654 | Let's pretend that instead, you use gcc-a29k, the simple cross |
| 655 | development environment that runs on sun4 but produces programs for |
| 656 | a29k. |
| 657 | |
| 658 | The resulting development environment will run on a29k because that's |
| 659 | what gcc-a29k builds, a29k programs. This development environment will |
| 660 | produce programs for a sun3 because that is how it was configured. This |
| 661 | means that the resulting development environment is a simple cross. |
| 662 | |
| 663 | @cindex Canadian Cross |
| 664 | @cindex Three party cross |
| 665 | There really isn't a common name for this process because very few |
| 666 | development environments are capable of being configured this |
| 667 | extensively. For the sake of discussion, let's call this process a |
| 668 | @emph{Canadian cross}. It's a three party cross, Canada has a three |
| 669 | party system, hence Canadian Cross. |
| 670 | |
| 671 | @node Final Notes, Index, A Walk Through, top |
| 672 | @chapter Final Notes |
| 673 | |
| 674 | By @emph{configures}, I mean that links, Makefile, .gdbinit, and |
| 675 | config.status are built. Configuration is always done from the source |
| 676 | directory. |
| 677 | |
| 678 | @table @code |
| 679 | |
| 680 | @item ./configure @var{name} |
| 681 | configures this directory, perhaps recursively, for a single host+target |
| 682 | pair where the host and target are both @var{name}. If a previous |
| 683 | configuration existed, it will be overwritten. |
| 684 | |
| 685 | @item ./configure @var{hostname} -target=@var{targetname} |
| 686 | configures this directory, perhaps recursively, for a single host+target |
| 687 | pair where the host is @var{hostname} and target is @var{targetname}. |
| 688 | If a previous configuration existed, it will be overwritten. |
| 689 | |
| 690 | @item ./configure -subdirs @var{hostname} -target=@var{targetname} |
| 691 | creates a subdirectories @file{H-@var{hostname}} if @var{hostname} is @var{targetname} or |
| 692 | @file{X-@var{hostname}-@var{targetname}} if it is not and configures the new directory. |
| 693 | |
| 694 | @end table |
| 695 | |
| 696 | @menu |
| 697 | * Hacking Configurations:: Hacking Configurations |
| 698 | @end menu |
| 699 | |
| 700 | @node Hacking Configurations, , Final Notes, Final Notes |
| 701 | @section Hacking Configurations |
| 702 | |
| 703 | The configure scripts essentially do three things, create subdirectories |
| 704 | if appropriate, build a @file{Makefile}, and create links to files, all |
| 705 | based on and tailored to, a specific host+target pair. The scripts also |
| 706 | create a @file{.gdbinit} if appropriate but this is not tailored. |
| 707 | |
| 708 | The Makefile is created by prepending some variable definitions to a |
| 709 | Makefile template called @file{Makefile.in} and then inserting host and |
| 710 | target specific Makefile fragments. The variables are set based on the |
| 711 | chosen host+target pair and build style, that is, if you use |
| 712 | subdirectories or not. The host and target specific Makefile may or may |
| 713 | not exist. |
| 714 | |
| 715 | @itemize @bullet |
| 716 | |
| 717 | @item |
| 718 | Makefiles can be edited directly, but those changes will eventually be |
| 719 | lost. Changes intended to be permanent for a specific host should be |
| 720 | made to the host specific Makefile fragment. This should be in |
| 721 | @file{./config/mh-@var{host}} if it exists. Changes intended to be |
| 722 | permanent for a specific target should be made to the target specific |
| 723 | Makefile fragment. This should be in @file{./config/mt-@var{target}} if |
| 724 | it exists. Changes intended to be permanent for the directory should be |
| 725 | made in @file{Makefile.in}. To propogate changes to any of these, |
| 726 | either use @code{make Makefile} or @code{./config.status} or |
| 727 | re-configure. |
| 728 | |
| 729 | @end itemize |
| 730 | |
| 731 | @page |
| 732 | @node Index, , Final Notes, top |
| 733 | @appendix Index |
| 734 | |
| 735 | @printindex cp |
| 736 | |
| 737 | @contents |
| 738 | @bye |
| 739 | |
| 740 | @c Local Variables: |
| 741 | @c fill-column: 72 |
| 742 | @c End: |