| 1 | \input texinfo |
| 2 | @c %**start of header |
| 3 | @setfilename configure.info |
| 4 | @settitle The GNU configure and build system |
| 5 | @setchapternewpage off |
| 6 | @c %**end of header |
| 7 | |
| 8 | @dircategory GNU admin |
| 9 | @direntry |
| 10 | * configure: (configure). The GNU configure and build system |
| 11 | @end direntry |
| 12 | |
| 13 | @ifnottex |
| 14 | This file documents the GNU configure and build system. |
| 15 | |
| 16 | Copyright (C) 1998 Cygnus Solutions. |
| 17 | |
| 18 | Permission is granted to make and distribute verbatim copies of |
| 19 | this manual provided the copyright notice and this permission notice |
| 20 | are preserved on all copies. |
| 21 | |
| 22 | @ignore |
| 23 | Permission is granted to process this file through TeX and print the |
| 24 | results, provided the printed document carries copying permission |
| 25 | notice identical to this one except for the removal of this paragraph |
| 26 | |
| 27 | |
| 28 | @end ignore |
| 29 | Permission is granted to copy and distribute modified versions of this |
| 30 | manual under the conditions for verbatim copying, provided that the entire |
| 31 | resulting derived work is distributed under the terms of a permission |
| 32 | notice identical to this one. |
| 33 | |
| 34 | Permission is granted to copy and distribute translations of this manual |
| 35 | into another language, under the above conditions for modified versions, |
| 36 | except that this permission notice may be stated in a translation approved |
| 37 | by the Foundation. |
| 38 | @end ifnottex |
| 39 | |
| 40 | @titlepage |
| 41 | @title The GNU configure and build system |
| 42 | @author Ian Lance Taylor |
| 43 | |
| 44 | @page |
| 45 | @vskip 0pt plus 1filll |
| 46 | Copyright @copyright{} 1998 Cygnus Solutions |
| 47 | |
| 48 | Permission is granted to make and distribute verbatim copies of |
| 49 | this manual provided the copyright notice and this permission notice |
| 50 | are preserved on all copies. |
| 51 | |
| 52 | Permission is granted to copy and distribute modified versions of this |
| 53 | manual under the conditions for verbatim copying, provided that the entire |
| 54 | resulting derived work is distributed under the terms of a permission |
| 55 | notice identical to this one. |
| 56 | |
| 57 | Permission is granted to copy and distribute translations of this manual |
| 58 | into another language, under the above conditions for modified versions, |
| 59 | except that this permission notice may be stated in a translation |
| 60 | approved by the Free Software Foundation. |
| 61 | @end titlepage |
| 62 | |
| 63 | @ifnottex |
| 64 | @node Top |
| 65 | @top GNU configure and build system |
| 66 | |
| 67 | The GNU configure and build system. |
| 68 | |
| 69 | @menu |
| 70 | * Introduction:: Introduction. |
| 71 | * Getting Started:: Getting Started. |
| 72 | * Files:: Files. |
| 73 | * Configuration Names:: Configuration Names. |
| 74 | * Cross Compilation Tools:: Cross Compilation Tools. |
| 75 | * Canadian Cross:: Canadian Cross. |
| 76 | * Cygnus Configure:: Cygnus Configure. |
| 77 | * Multilibs:: Multilibs. |
| 78 | * FAQ:: Frequently Asked Questions. |
| 79 | * Index:: Index. |
| 80 | @end menu |
| 81 | |
| 82 | @end ifnottex |
| 83 | |
| 84 | @node Introduction |
| 85 | @chapter Introduction |
| 86 | |
| 87 | This document describes the GNU configure and build systems. It |
| 88 | describes how autoconf, automake, libtool, and make fit together. It |
| 89 | also includes a discussion of the older Cygnus configure system. |
| 90 | |
| 91 | This document does not describe in detail how to use each of the tools; |
| 92 | see the respective manuals for that. Instead, it describes which files |
| 93 | the developer must write, which files are machine generated and how they |
| 94 | are generated, and where certain common problems should be addressed. |
| 95 | |
| 96 | @ifnothtml |
| 97 | This document draws on several sources, including the autoconf manual by |
| 98 | David MacKenzie (@pxref{Top, , autoconf overview, autoconf, Autoconf}), |
| 99 | the automake manual by David MacKenzie and Tom Tromey (@pxref{Top, , |
| 100 | automake overview, automake, GNU Automake}), the libtool manual by |
| 101 | Gordon Matzigkeit (@pxref{Top, , libtool overview, libtool, GNU |
| 102 | libtool}), and the Cygnus configure manual by K. Richard Pixley. |
| 103 | @end ifnothtml |
| 104 | @ifhtml |
| 105 | This document draws on several sources, including |
| 106 | @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_toc.html, the |
| 107 | autoconf manual} by David MacKenzie, |
| 108 | @uref{http://www.delorie.com/gnu/docs/automake/automake_toc.html, the |
| 109 | automake manual} by David MacKenzie and Tom Tromey, |
| 110 | @uref{http://www.delorie.com/gnu/docs/libtool/libtool_toc.html, the |
| 111 | libtool manual} by Gordon Matzigkeit, and the Cygnus configure manual by |
| 112 | K. Richard Pixley. |
| 113 | @end ifhtml |
| 114 | |
| 115 | @menu |
| 116 | * Goals:: Goals. |
| 117 | * Tools:: The tools. |
| 118 | * History:: History. |
| 119 | * Building:: Building. |
| 120 | @end menu |
| 121 | |
| 122 | @node Goals |
| 123 | @section Goals |
| 124 | @cindex goals |
| 125 | |
| 126 | The GNU configure and build system has two main goals. |
| 127 | |
| 128 | The first is to simplify the development of portable programs. The |
| 129 | system permits the developer to concentrate on writing the program, |
| 130 | simplifying many details of portability across Unix and even Windows |
| 131 | systems, and permitting the developer to describe how to build the |
| 132 | program using simple rules rather than complex Makefiles. |
| 133 | |
| 134 | The second is to simplify the building of programs distributed as source |
| 135 | code. All programs are built using a simple, standardized, two step |
| 136 | process. The program builder need not install any special tools in |
| 137 | order to build the program. |
| 138 | |
| 139 | @node Tools |
| 140 | @section Tools |
| 141 | |
| 142 | The GNU configure and build system is comprised of several different |
| 143 | tools. Program developers must build and install all of these tools. |
| 144 | |
| 145 | People who just want to build programs from distributed sources normally |
| 146 | do not need any special tools beyond a Unix shell, a make program, and a |
| 147 | C compiler. |
| 148 | |
| 149 | @table @asis |
| 150 | @item autoconf |
| 151 | provides a general portability framework, based on testing the features |
| 152 | of the host system at build time. |
| 153 | @item automake |
| 154 | a system for describing how to build a program, permitting the developer |
| 155 | to write a simplified @file{Makefile}. |
| 156 | @item libtool |
| 157 | a standardized approach to building shared libraries. |
| 158 | @item gettext |
| 159 | provides a framework for translation of text messages into other |
| 160 | languages; not really discussed in this document. |
| 161 | @item m4 |
| 162 | autoconf requires the GNU version of m4; the standard Unix m4 does not |
| 163 | suffice. |
| 164 | @item perl |
| 165 | automake requires perl. |
| 166 | @end table |
| 167 | |
| 168 | @node History |
| 169 | @section History |
| 170 | @cindex history |
| 171 | |
| 172 | This is a very brief and probably inaccurate history. |
| 173 | |
| 174 | As the number of Unix variants increased during the 1980s, it became |
| 175 | harder to write programs which could run on all variants. While it was |
| 176 | often possible to use @code{#ifdef} to identify particular systems, |
| 177 | developers frequently did not have access to every system, and the |
| 178 | characteristics of some systems changed from version to version. |
| 179 | |
| 180 | By 1992, at least three different approaches had been developed: |
| 181 | @itemize @bullet |
| 182 | @item |
| 183 | The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael |
| 184 | Manfredi. |
| 185 | @item |
| 186 | The Cygnus configure script, by K. Richard Pixley, and the gcc configure |
| 187 | script, by Richard Stallman. These use essentially the same approach, |
| 188 | and the developers communicated regularly. |
| 189 | @item |
| 190 | The autoconf program, by David MacKenzie. |
| 191 | @end itemize |
| 192 | |
| 193 | The Metaconfig program is still used for Perl and a few other programs. |
| 194 | It is part of the Dist package. I do not know if it is being developed. |
| 195 | |
| 196 | In 1994, David MacKenzie and others modified autoconf to incorporate all |
| 197 | the features of Cygnus configure. Since then, there has been a slow but |
| 198 | steady conversion of GNU programs from Cygnus configure to autoconf. gcc |
| 199 | has been converted, eliminating the gcc configure script. |
| 200 | |
| 201 | GNU autoconf was regularly maintained until late 1996. As of this |
| 202 | writing in June, 1998, it has no public maintainer. |
| 203 | |
| 204 | Most programs are built using the make program, which requires the |
| 205 | developer to write Makefiles describing how to build the programs. |
| 206 | Since most programs are built in pretty much the same way, this led to a |
| 207 | lot of duplication. |
| 208 | |
| 209 | The X Window system is built using the imake tool, which uses a database |
| 210 | of rules to eliminate the duplication. However, building a tool which |
| 211 | was developed using imake requires that the builder have imake |
| 212 | installed, violating one of the goals of the GNU system. |
| 213 | |
| 214 | The new BSD make provides a standard library of Makefile fragments, |
| 215 | which permits developers to write very simple Makefiles. However, this |
| 216 | requires that the builder install the new BSD make program. |
| 217 | |
| 218 | In 1994, David MacKenzie wrote the first version of automake, which |
| 219 | permitted writing a simple build description which was converted into a |
| 220 | Makefile which could be used by the standard make program. In 1995, Tom |
| 221 | Tromey completely rewrote automake in Perl, and he continues to enhance |
| 222 | it. |
| 223 | |
| 224 | Various free packages built libraries, and by around 1995 several |
| 225 | included support to build shared libraries on various platforms. |
| 226 | However, there was no consistent approach. In early 1996, Gordon |
| 227 | Matzigkeit began working on libtool, which provided a standardized |
| 228 | approach to building shared libraries. This was integrated into |
| 229 | automake from the start. |
| 230 | |
| 231 | The development of automake and libtool was driven by the GNITS project, |
| 232 | a group of GNU maintainers who designed standardized tools to help meet |
| 233 | the GNU coding standards. |
| 234 | |
| 235 | @node Building |
| 236 | @section Building |
| 237 | |
| 238 | Most readers of this document should already know how to build a tool by |
| 239 | running @samp{configure} and @samp{make}. This section may serve as a |
| 240 | quick introduction or reminder. |
| 241 | |
| 242 | Building a tool is normally as simple as running @samp{configure} |
| 243 | followed by @samp{make}. You should normally run @samp{configure} from |
| 244 | an empty directory, using some path to refer to the @samp{configure} |
| 245 | script in the source directory. The directory in which you run |
| 246 | @samp{configure} is called the @dfn{object directory}. |
| 247 | |
| 248 | In order to use a object directory which is different from the source |
| 249 | directory, you must be using the GNU version of @samp{make}, which has |
| 250 | the required @samp{VPATH} support. Despite this restriction, using a |
| 251 | different object directory is highly recommended: |
| 252 | @itemize @bullet |
| 253 | @item |
| 254 | It keeps the files generated during the build from cluttering up your |
| 255 | sources. |
| 256 | @item |
| 257 | It permits you to remove the built files by simply removing the entire |
| 258 | build directory. |
| 259 | @item |
| 260 | It permits you to build from the same sources with several sets of |
| 261 | configure options simultaneously. |
| 262 | @end itemize |
| 263 | |
| 264 | If you don't have GNU @samp{make}, you will have to run @samp{configure} |
| 265 | in the source directory. All GNU packages should support this; in |
| 266 | particular, GNU packages should not assume the presence of GNU |
| 267 | @samp{make}. |
| 268 | |
| 269 | After running @samp{configure}, you can build the tools by running |
| 270 | @samp{make}. |
| 271 | |
| 272 | To install the tools, run @samp{make install}. Installing the tools |
| 273 | will copy the programs and any required support files to the |
| 274 | @dfn{installation directory}. The location of the installation |
| 275 | directory is controlled by @samp{configure} options, as described below. |
| 276 | |
| 277 | In the Cygnus tree at present, the info files are built and installed as |
| 278 | a separate step. To build them, run @samp{make info}. To install them, |
| 279 | run @samp{make install-info}. The equivalent html files are also built |
| 280 | and installed in a separate step. To build the html files, run |
| 281 | @samp{make html}. To install the html files run @samp{make install-html}. |
| 282 | |
| 283 | All @samp{configure} scripts support a wide variety of options. The |
| 284 | most interesting ones are @samp{--with} and @samp{--enable} options |
| 285 | which are generally specific to particular tools. You can usually use |
| 286 | the @samp{--help} option to get a list of interesting options for a |
| 287 | particular configure script. |
| 288 | |
| 289 | The only generic options you are likely to use are the @samp{--prefix} |
| 290 | and @samp{--exec-prefix} options. These options are used to specify the |
| 291 | installation directory. |
| 292 | |
| 293 | The directory named by the @samp{--prefix} option will hold machine |
| 294 | independent files such as info files. |
| 295 | |
| 296 | The directory named by the @samp{--exec-prefix} option, which is |
| 297 | normally a subdirectory of the @samp{--prefix} directory, will hold |
| 298 | machine dependent files such as executables. |
| 299 | |
| 300 | The default for @samp{--prefix} is @file{/usr/local}. The default for |
| 301 | @samp{--exec-prefix} is the value used for @samp{--prefix}. |
| 302 | |
| 303 | The convention used in Cygnus releases is to use a @samp{--prefix} |
| 304 | option of @file{/usr/cygnus/@var{release}}, where @var{release} is the |
| 305 | name of the release, and to use a @samp{--exec-prefix} option of |
| 306 | @file{/usr/cygnus/@var{release}/H-@var{host}}, where @var{host} is the |
| 307 | configuration name of the host system (@pxref{Configuration Names}). |
| 308 | |
| 309 | Do not use either the source or the object directory as the installation |
| 310 | directory. That will just lead to confusion. |
| 311 | |
| 312 | @node Getting Started |
| 313 | @chapter Getting Started |
| 314 | |
| 315 | To start using the GNU configure and build system with your software |
| 316 | package, you must write three files, and you must run some tools to |
| 317 | manually generate additional files. |
| 318 | |
| 319 | @menu |
| 320 | * Write configure.in:: Write configure.in. |
| 321 | * Write Makefile.am:: Write Makefile.am. |
| 322 | * Write acconfig.h:: Write acconfig.h. |
| 323 | * Generate files:: Generate files. |
| 324 | * Getting Started Example:: Example. |
| 325 | @end menu |
| 326 | |
| 327 | @node Write configure.in |
| 328 | @section Write configure.in |
| 329 | @cindex @file{configure.in}, writing |
| 330 | |
| 331 | You must first write the file @file{configure.in}. This is an autoconf |
| 332 | input file, and the autoconf manual describes in detail what this file |
| 333 | should look like. |
| 334 | |
| 335 | You will write tests in your @file{configure.in} file to check for |
| 336 | conditions that may change from one system to another, such as the |
| 337 | presence of particular header files or functions. |
| 338 | |
| 339 | For example, not all systems support the @samp{gettimeofday} function. |
| 340 | If you want to use the @samp{gettimeofday} function when it is |
| 341 | available, and to use some other function when it is not, you would |
| 342 | check for this by putting @samp{AC_CHECK_FUNCS(gettimeofday)} in |
| 343 | @file{configure.in}. |
| 344 | |
| 345 | When the configure script is run at build time, this will arrange to |
| 346 | define the preprocessor macro @samp{HAVE_GETTIMEOFDAY} to the value 1 if |
| 347 | the @samp{gettimeofday} function is available, and to not define the |
| 348 | macro at all if the function is not available. Your code can then use |
| 349 | @samp{#ifdef} to test whether it is safe to call @samp{gettimeofday}. |
| 350 | |
| 351 | If you have an existing body of code, the @samp{autoscan} program may |
| 352 | help identify potential portability problems, and hence configure tests |
| 353 | that you will want to use. |
| 354 | @ifnothtml |
| 355 | @xref{Invoking autoscan, , , autoconf, the autoconf manual}. |
| 356 | @end ifnothtml |
| 357 | @ifhtml |
| 358 | See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_4.html, the |
| 359 | autoscan documentation}. |
| 360 | @end ifhtml |
| 361 | |
| 362 | Another handy tool for an existing body of code is @samp{ifnames}. This |
| 363 | will show you all the preprocessor conditionals that the code already |
| 364 | uses. |
| 365 | @ifnothtml |
| 366 | @xref{Invoking ifnames, , , autoconf, the autoconf manual}. |
| 367 | @end ifnothtml |
| 368 | @ifhtml |
| 369 | See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_5.html, the |
| 370 | ifnames documentation}. |
| 371 | @end ifhtml |
| 372 | |
| 373 | Besides the portability tests which are specific to your particular |
| 374 | package, every @file{configure.in} file should contain the following |
| 375 | macros. |
| 376 | |
| 377 | @table @samp |
| 378 | @item AC_INIT |
| 379 | @cindex @samp{AC_INIT} |
| 380 | This macro takes a single argument, which is the name of a file in your |
| 381 | package. For example, @samp{AC_INIT(foo.c)}. |
| 382 | |
| 383 | @item AC_PREREQ(@var{VERSION}) |
| 384 | @cindex @samp{AC_PREREQ} |
| 385 | This macro is optional. It may be used to indicate the version of |
| 386 | @samp{autoconf} that you are using. This will prevent users from |
| 387 | running an earlier version of @samp{autoconf} and perhaps getting an |
| 388 | invalid @file{configure} script. For example, @samp{AC_PREREQ(2.12)}. |
| 389 | |
| 390 | @item AM_INIT_AUTOMAKE |
| 391 | @cindex @samp{AM_INIT_AUTOMAKE} |
| 392 | This macro takes two arguments: the name of the package, and a version |
| 393 | number. For example, @samp{AM_INIT_AUTOMAKE(foo, 1.0)}. (This macro is |
| 394 | not needed if you are not using automake). |
| 395 | |
| 396 | @item AM_CONFIG_HEADER |
| 397 | @cindex @samp{AM_CONFIG_HEADER} |
| 398 | This macro names the header file which will hold the preprocessor macro |
| 399 | definitions at run time. Normally this should be @file{config.h}. Your |
| 400 | sources would then use @samp{#include "config.h"} to include it. |
| 401 | |
| 402 | This macro may optionally name the input file for that header file; by |
| 403 | default, this is @file{config.h.in}, but that file name works poorly on |
| 404 | DOS filesystems. Therefore, it is often better to name it explicitly as |
| 405 | @file{config.in}. |
| 406 | |
| 407 | This is what you should normally put in @file{configure.in}: |
| 408 | @example |
| 409 | AM_CONFIG_HEADER(config.h:config.in) |
| 410 | @end example |
| 411 | |
| 412 | @cindex @samp{AC_CONFIG_HEADER} |
| 413 | (If you are not using automake, use @samp{AC_CONFIG_HEADER} rather than |
| 414 | @samp{AM_CONFIG_HEADER}). |
| 415 | |
| 416 | @item AM_MAINTAINER_MODE |
| 417 | @cindex @samp{AM_MAINTAINER_MODE} |
| 418 | This macro always appears in Cygnus configure scripts. Other programs |
| 419 | may or may not use it. |
| 420 | |
| 421 | If this macro is used, the @samp{--enable-maintainer-mode} option is |
| 422 | required to enable automatic rebuilding of generated files used by the |
| 423 | configure system. This of course requires that developers be aware of, |
| 424 | and use, that option. |
| 425 | |
| 426 | If this macro is not used, then the generated files will always be |
| 427 | rebuilt automatically. This will cause problems if the wrong versions |
| 428 | of autoconf, automake, or others are in the builder's @samp{PATH}. |
| 429 | |
| 430 | (If you are not using automake, you do not need to use this macro). |
| 431 | |
| 432 | @item AC_EXEEXT |
| 433 | @cindex @samp{AC_EXEEXT} |
| 434 | @cindex @samp{AM_EXEEXT} |
| 435 | Either this macro or @samp{AM_EXEEXT} always appears in Cygnus configure |
| 436 | files. Other programs may or may not use one of them. |
| 437 | |
| 438 | This macro looks for the executable suffix used on the host system. On |
| 439 | Unix systems, this is the empty string. On Windows systems, this is |
| 440 | @samp{.exe}. This macro directs automake to use the executable suffix |
| 441 | as appropriate when creating programs. This macro does not take any |
| 442 | arguments. |
| 443 | |
| 444 | The @samp{AC_EXEEXT} form is new, and is part of a Cygnus patch to |
| 445 | autoconf to support compiling with Visual C++. Older programs use |
| 446 | @samp{AM_EXEEXT} instead. |
| 447 | |
| 448 | (Programs which do not use automake use neither @samp{AC_EXEEXT} nor |
| 449 | @samp{AM_EXEEXT}). |
| 450 | |
| 451 | @item AC_PROG_CC |
| 452 | @cindex @samp{AC_PROG_CC} |
| 453 | If you are writing C code, you will normally want to use this macro. It |
| 454 | locates the C compiler to use. It does not take any arguments. |
| 455 | |
| 456 | However, if this @file{configure.in} file is for a library which is to |
| 457 | be compiled by a cross compiler which may not fully work, then you will |
| 458 | not want to use @samp{AC_PROG_CC}. Instead, you will want to use a |
| 459 | variant which does not call the macro @samp{AC_PROG_CC_WORKS}. Examples |
| 460 | can be found in various @file{configure.in} files for libraries that are |
| 461 | compiled with cross compilers, such as libiberty or libgloss. This is |
| 462 | essentially a bug in autoconf, and there will probably be a better |
| 463 | workaround at some point. |
| 464 | |
| 465 | @item AC_PROG_CXX |
| 466 | @cindex @samp{AC_PROG_CXX} |
| 467 | If you are writing C++ code, you will want to use this macro. It |
| 468 | locates the C++ compiler to use. It does not take any arguments. The |
| 469 | same cross compiler comments apply as for @samp{AC_PROG_CC}. |
| 470 | |
| 471 | @item AM_PROG_LIBTOOL |
| 472 | @cindex @samp{AM_PROG_LIBTOOL} |
| 473 | If you want to build libraries, and you want to permit them to be |
| 474 | shared, or you want to link against libraries which were built using |
| 475 | libtool, then you will need this macro. This macro is required in order |
| 476 | to use libtool. |
| 477 | |
| 478 | @cindex @samp{AM_DISABLE_SHARED} |
| 479 | By default, this will cause all libraries to be built as shared |
| 480 | libraries. To prevent this--to change the default--use |
| 481 | @samp{AM_DISABLE_SHARED} before @samp{AM_PROG_LIBTOOL}. The configure |
| 482 | options @samp{--enable-shared} and @samp{--disable-shared} may be used |
| 483 | to override the default at build time. |
| 484 | |
| 485 | @item AC_DEFINE(_GNU_SOURCE) |
| 486 | @cindex @samp{_GNU_SOURCE} |
| 487 | GNU packages should normally include this line before any other feature |
| 488 | tests. This defines the macro @samp{_GNU_SOURCE} when compiling, which |
| 489 | directs the libc header files to provide the standard GNU system |
| 490 | interfaces including all GNU extensions. If this macro is not defined, |
| 491 | certain GNU extensions may not be available. |
| 492 | |
| 493 | @item AC_OUTPUT |
| 494 | @cindex @samp{AC_OUTPUT} |
| 495 | This macro takes a list of file names which the configure process should |
| 496 | produce. This is normally a list of one or more @file{Makefile} files |
| 497 | in different directories. If your package lives entirely in a single |
| 498 | directory, you would use simply @samp{AC_OUTPUT(Makefile)}. If you also |
| 499 | have, for example, a @file{lib} subdirectory, you would use |
| 500 | @samp{AC_OUTPUT(Makefile lib/Makefile)}. |
| 501 | @end table |
| 502 | |
| 503 | If you want to use locally defined macros in your @file{configure.in} |
| 504 | file, then you will need to write a @file{acinclude.m4} file which |
| 505 | defines them (if not using automake, this file is called |
| 506 | @file{aclocal.m4}). Alternatively, you can put separate macros in an |
| 507 | @file{m4} subdirectory, and put @samp{ACLOCAL_AMFLAGS = -I m4} in your |
| 508 | @file{Makefile.am} file so that the @samp{aclocal} program will be able |
| 509 | to find them. |
| 510 | |
| 511 | The different macro prefixes indicate which tool defines the macro. |
| 512 | Macros which start with @samp{AC_} are part of autoconf. Macros which |
| 513 | start with @samp{AM_} are provided by automake or libtool. |
| 514 | |
| 515 | @node Write Makefile.am |
| 516 | @section Write Makefile.am |
| 517 | @cindex @file{Makefile.am}, writing |
| 518 | |
| 519 | You must write the file @file{Makefile.am}. This is an automake input |
| 520 | file, and the automake manual describes in detail what this file should |
| 521 | look like. |
| 522 | |
| 523 | The automake commands in @file{Makefile.am} mostly look like variable |
| 524 | assignments in a @file{Makefile}. automake recognizes special variable |
| 525 | names, and automatically add make rules to the output as needed. |
| 526 | |
| 527 | There will be one @file{Makefile.am} file for each directory in your |
| 528 | package. For each directory with subdirectories, the @file{Makefile.am} |
| 529 | file should contain the line |
| 530 | @smallexample |
| 531 | SUBDIRS = @var{dir} @var{dir} @dots{} |
| 532 | @end smallexample |
| 533 | @noindent |
| 534 | where each @var{dir} is the name of a subdirectory. |
| 535 | |
| 536 | For each @file{Makefile.am}, there should be a corresponding |
| 537 | @file{Makefile} in the @samp{AC_OUTPUT} macro in @file{configure.in}. |
| 538 | |
| 539 | Every @file{Makefile.am} written at Cygnus should contain the line |
| 540 | @smallexample |
| 541 | AUTOMAKE_OPTIONS = cygnus |
| 542 | @end smallexample |
| 543 | @noindent |
| 544 | This puts automake into Cygnus mode. See the automake manual for |
| 545 | details. |
| 546 | |
| 547 | You may to include the version number of @samp{automake} that you are |
| 548 | using on the @samp{AUTOMAKE_OPTIONS} line. For example, |
| 549 | @smallexample |
| 550 | AUTOMAKE_OPTIONS = cygnus 1.3 |
| 551 | @end smallexample |
| 552 | @noindent |
| 553 | This will prevent users from running an earlier version of |
| 554 | @samp{automake} and perhaps getting an invalid @file{Makefile.in}. |
| 555 | |
| 556 | If your package builds a program, then in the directory where that |
| 557 | program is built you will normally want a line like |
| 558 | @smallexample |
| 559 | bin_PROGRAMS = @var{program} |
| 560 | @end smallexample |
| 561 | @noindent |
| 562 | where @var{program} is the name of the program. You will then want a |
| 563 | line like |
| 564 | @smallexample |
| 565 | @var{program}_SOURCES = @var{file} @var{file} @dots{} |
| 566 | @end smallexample |
| 567 | @noindent |
| 568 | where each @var{file} is the name of a source file to link into the |
| 569 | program (e.g., @samp{foo.c}). |
| 570 | |
| 571 | If your package builds a library, and you do not want the library to |
| 572 | ever be built as a shared library, then in the directory where that |
| 573 | library is built you will normally want a line like |
| 574 | @smallexample |
| 575 | lib_LIBRARIES = lib@var{name}.a |
| 576 | @end smallexample |
| 577 | @noindent |
| 578 | where @samp{lib@var{name}.a} is the name of the library. You will then |
| 579 | want a line like |
| 580 | @smallexample |
| 581 | lib@var{name}_a_SOURCES = @var{file} @var{file} @dots{} |
| 582 | @end smallexample |
| 583 | @noindent |
| 584 | where each @var{file} is the name of a source file to add to the |
| 585 | library. |
| 586 | |
| 587 | If your package builds a library, and you want to permit building the |
| 588 | library as a shared library, then in the directory where that library is |
| 589 | built you will normally want a line like |
| 590 | @smallexample |
| 591 | lib_LTLIBRARIES = lib@var{name}.la |
| 592 | @end smallexample |
| 593 | The use of @samp{LTLIBRARIES}, and the @samp{.la} extension, indicate a |
| 594 | library to be built using libtool. As usual, you will then want a line |
| 595 | like |
| 596 | @smallexample |
| 597 | lib@var{name}_la_SOURCES = @var{file} @var{file} @dots{} |
| 598 | @end smallexample |
| 599 | |
| 600 | The strings @samp{bin} and @samp{lib} that appear above in |
| 601 | @samp{bin_PROGRAMS} and @samp{lib_LIBRARIES} are not arbitrary. They |
| 602 | refer to particular directories, which may be set by the @samp{--bindir} |
| 603 | and @samp{--libdir} options to @file{configure}. If those options are |
| 604 | not used, the default values are based on the @samp{--prefix} or |
| 605 | @samp{--exec-prefix} options to @file{configure}. It is possible to use |
| 606 | other names if the program or library should be installed in some other |
| 607 | directory. |
| 608 | |
| 609 | The @file{Makefile.am} file may also contain almost anything that may |
| 610 | appear in a normal @file{Makefile}. automake also supports many other |
| 611 | special variables, as well as conditionals. |
| 612 | |
| 613 | See the automake manual for more information. |
| 614 | |
| 615 | @node Write acconfig.h |
| 616 | @section Write acconfig.h |
| 617 | @cindex @file{acconfig.h}, writing |
| 618 | |
| 619 | If you are generating a portability header file, (i.e., you are using |
| 620 | @samp{AM_CONFIG_HEADER} in @file{configure.in}), then you will have to |
| 621 | write a @file{acconfig.h} file. It will have to contain the following |
| 622 | lines. |
| 623 | |
| 624 | @smallexample |
| 625 | /* Name of package. */ |
| 626 | #undef PACKAGE |
| 627 | |
| 628 | /* Version of package. */ |
| 629 | #undef VERSION |
| 630 | @end smallexample |
| 631 | |
| 632 | This requirement is really a bug in the system, and the requirement may |
| 633 | be eliminated at some later date. |
| 634 | |
| 635 | The @file{acconfig.h} file will also similar comment and @samp{#undef} |
| 636 | lines for any unusual macros in the @file{configure.in} file, including |
| 637 | any macro which appears in a @samp{AC_DEFINE} macro. |
| 638 | |
| 639 | In particular, if you are writing a GNU package and therefore include |
| 640 | @samp{AC_DEFINE(_GNU_SOURCE)} in @file{configure.in} as suggested above, |
| 641 | you will need lines like this in @file{acconfig.h}: |
| 642 | @smallexample |
| 643 | /* Enable GNU extensions. */ |
| 644 | #undef _GNU_SOURCE |
| 645 | @end smallexample |
| 646 | |
| 647 | Normally the @samp{autoheader} program will inform you of any such |
| 648 | requirements by printing an error message when it is run. However, if |
| 649 | you do anything particular odd in your @file{configure.in} file, you |
| 650 | will have to make sure that the right entries appear in |
| 651 | @file{acconfig.h}, since otherwise the results of the tests may not be |
| 652 | available in the @file{config.h} file which your code will use. |
| 653 | |
| 654 | (Thee @samp{PACKAGE} and @samp{VERSION} lines are not required if you |
| 655 | are not using automake, and in that case you may not need a |
| 656 | @file{acconfig.h} file at all). |
| 657 | |
| 658 | @node Generate files |
| 659 | @section Generate files |
| 660 | |
| 661 | Once you have written @file{configure.in}, @file{Makefile.am}, |
| 662 | @file{acconfig.h}, and possibly @file{acinclude.m4}, you must use |
| 663 | autoconf and automake programs to produce the first versions of the |
| 664 | generated files. This is done by executing the following sequence of |
| 665 | commands. |
| 666 | |
| 667 | @smallexample |
| 668 | aclocal |
| 669 | autoconf |
| 670 | autoheader |
| 671 | automake |
| 672 | @end smallexample |
| 673 | |
| 674 | The @samp{aclocal} and @samp{automake} commands are part of the automake |
| 675 | package, and the @samp{autoconf} and @samp{autoheader} commands are part |
| 676 | of the autoconf package. |
| 677 | |
| 678 | If you are using a @file{m4} subdirectory for your macros, you will need |
| 679 | to use the @samp{-I m4} option when you run @samp{aclocal}. |
| 680 | |
| 681 | If you are not using the Cygnus tree, use the @samp{-a} option when |
| 682 | running @samp{automake} command in order to copy the required support |
| 683 | files into your source directory. |
| 684 | |
| 685 | If you are using libtool, you must build and install the libtool package |
| 686 | with the same @samp{--prefix} and @samp{--exec-prefix} options as you |
| 687 | used with the autoconf and automake packages. You must do this before |
| 688 | running any of the above commands. If you are not using the Cygnus |
| 689 | tree, you will need to run the @samp{libtoolize} program to copy the |
| 690 | libtool support files into your directory. |
| 691 | |
| 692 | Once you have managed to run these commands without getting any errors, |
| 693 | you should create a new empty directory, and run the @samp{configure} |
| 694 | script which will have been created by @samp{autoconf} with the |
| 695 | @samp{--enable-maintainer-mode} option. This will give you a set of |
| 696 | Makefiles which will include rules to automatically rebuild all the |
| 697 | generated files. |
| 698 | |
| 699 | After doing that, whenever you have changed some of the input files and |
| 700 | want to regenerated the other files, go to your object directory and run |
| 701 | @samp{make}. Doing this is more reliable than trying to rebuild the |
| 702 | files manually, because there are complex order dependencies and it is |
| 703 | easy to forget something. |
| 704 | |
| 705 | @node Getting Started Example |
| 706 | @section Example |
| 707 | |
| 708 | Let's consider a trivial example. |
| 709 | |
| 710 | Suppose we want to write a simple version of @samp{touch}. Our program, |
| 711 | which we will call @samp{poke}, will take a single file name argument, |
| 712 | and use the @samp{utime} system call to set the modification and access |
| 713 | times of the file to the current time. We want this program to be |
| 714 | highly portable. |
| 715 | |
| 716 | We'll first see what this looks like without using autoconf and |
| 717 | automake, and then see what it looks like with them. |
| 718 | |
| 719 | @menu |
| 720 | * Getting Started Example 1:: First Try. |
| 721 | * Getting Started Example 2:: Second Try. |
| 722 | * Getting Started Example 3:: Third Try. |
| 723 | * Generate Files in Example:: Generate Files. |
| 724 | @end menu |
| 725 | |
| 726 | @node Getting Started Example 1 |
| 727 | @subsection First Try |
| 728 | |
| 729 | Here is our first try at @samp{poke.c}. Note that we've written it |
| 730 | without ANSI/ISO C prototypes, since we want it to be highly portable. |
| 731 | |
| 732 | @example |
| 733 | #include <stdio.h> |
| 734 | #include <stdlib.h> |
| 735 | #include <sys/types.h> |
| 736 | #include <utime.h> |
| 737 | |
| 738 | int |
| 739 | main (argc, argv) |
| 740 | int argc; |
| 741 | char **argv; |
| 742 | @{ |
| 743 | if (argc != 2) |
| 744 | @{ |
| 745 | fprintf (stderr, "Usage: poke file\n"); |
| 746 | exit (1); |
| 747 | @} |
| 748 | |
| 749 | if (utime (argv[1], NULL) < 0) |
| 750 | @{ |
| 751 | perror ("utime"); |
| 752 | exit (1); |
| 753 | @} |
| 754 | |
| 755 | exit (0); |
| 756 | @} |
| 757 | @end example |
| 758 | |
| 759 | We also write a simple @file{Makefile}. |
| 760 | |
| 761 | @example |
| 762 | CC = gcc |
| 763 | CFLAGS = -g -O2 |
| 764 | |
| 765 | all: poke |
| 766 | |
| 767 | poke: poke.o |
| 768 | $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o |
| 769 | @end example |
| 770 | |
| 771 | So far, so good. |
| 772 | |
| 773 | Unfortunately, there are a few problems. |
| 774 | |
| 775 | On older Unix systems derived from BSD 4.3, the @samp{utime} system call |
| 776 | does not accept a second argument of @samp{NULL}. On those systems, we |
| 777 | need to pass a pointer to @samp{struct utimbuf} structure. |
| 778 | Unfortunately, even older systems don't define that structure; on those |
| 779 | systems, we need to pass an array of two @samp{long} values. |
| 780 | |
| 781 | The header file @file{stdlib.h} was invented by ANSI C, and older |
| 782 | systems don't have a copy. We included it above to get a declaration of |
| 783 | @samp{exit}. |
| 784 | |
| 785 | We can find some of these portability problems by running |
| 786 | @samp{autoscan}, which will create a @file{configure.scan} file which we |
| 787 | can use as a prototype for our @file{configure.in} file. I won't show |
| 788 | the output, but it will notice the potential problems with @samp{utime} |
| 789 | and @file{stdlib.h}. |
| 790 | |
| 791 | In our @file{Makefile}, we don't provide any way to install the program. |
| 792 | This doesn't matter much for such a simple example, but a real program |
| 793 | will need an @samp{install} target. For that matter, we will also want |
| 794 | a @samp{clean} target. |
| 795 | |
| 796 | @node Getting Started Example 2 |
| 797 | @subsection Second Try |
| 798 | |
| 799 | Here is our second try at this program. |
| 800 | |
| 801 | We modify @file{poke.c} to use preprocessor macros to control what |
| 802 | features are available. (I've cheated a bit by using the same macro |
| 803 | names which autoconf will use). |
| 804 | |
| 805 | @example |
| 806 | #include <stdio.h> |
| 807 | |
| 808 | #ifdef STDC_HEADERS |
| 809 | #include <stdlib.h> |
| 810 | #endif |
| 811 | |
| 812 | #include <sys/types.h> |
| 813 | |
| 814 | #ifdef HAVE_UTIME_H |
| 815 | #include <utime.h> |
| 816 | #endif |
| 817 | |
| 818 | #ifndef HAVE_UTIME_NULL |
| 819 | |
| 820 | #include <time.h> |
| 821 | |
| 822 | #ifndef HAVE_STRUCT_UTIMBUF |
| 823 | |
| 824 | struct utimbuf |
| 825 | @{ |
| 826 | long actime; |
| 827 | long modtime; |
| 828 | @}; |
| 829 | |
| 830 | #endif |
| 831 | |
| 832 | static int |
| 833 | utime_now (file) |
| 834 | char *file; |
| 835 | @{ |
| 836 | struct utimbuf now; |
| 837 | |
| 838 | now.actime = now.modtime = time (NULL); |
| 839 | return utime (file, &now); |
| 840 | @} |
| 841 | |
| 842 | #define utime(f, p) utime_now (f) |
| 843 | |
| 844 | #endif /* HAVE_UTIME_NULL */ |
| 845 | |
| 846 | int |
| 847 | main (argc, argv) |
| 848 | int argc; |
| 849 | char **argv; |
| 850 | @{ |
| 851 | if (argc != 2) |
| 852 | @{ |
| 853 | fprintf (stderr, "Usage: poke file\n"); |
| 854 | exit (1); |
| 855 | @} |
| 856 | |
| 857 | if (utime (argv[1], NULL) < 0) |
| 858 | @{ |
| 859 | perror ("utime"); |
| 860 | exit (1); |
| 861 | @} |
| 862 | |
| 863 | exit (0); |
| 864 | @} |
| 865 | @end example |
| 866 | |
| 867 | Here is the associated @file{Makefile}. We've added support for the |
| 868 | preprocessor flags we use. We've also added @samp{install} and |
| 869 | @samp{clean} targets. |
| 870 | |
| 871 | @example |
| 872 | # Set this to your installation directory. |
| 873 | bindir = /usr/local/bin |
| 874 | |
| 875 | # Uncomment this if you have the standard ANSI/ISO C header files. |
| 876 | # STDC_HDRS = -DSTDC_HEADERS |
| 877 | |
| 878 | # Uncomment this if you have utime.h. |
| 879 | # UTIME_H = -DHAVE_UTIME_H |
| 880 | |
| 881 | # Uncomment this if utime (FILE, NULL) works on your system. |
| 882 | # UTIME_NULL = -DHAVE_UTIME_NULL |
| 883 | |
| 884 | # Uncomment this if struct utimbuf is defined in utime.h. |
| 885 | # UTIMBUF = -DHAVE_STRUCT_UTIMBUF |
| 886 | |
| 887 | CC = gcc |
| 888 | CFLAGS = -g -O2 |
| 889 | |
| 890 | ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS) |
| 891 | |
| 892 | all: poke |
| 893 | |
| 894 | poke: poke.o |
| 895 | $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o |
| 896 | |
| 897 | .c.o: |
| 898 | $(CC) -c $(ALL_CFLAGS) poke.c |
| 899 | |
| 900 | install: poke |
| 901 | cp poke $(bindir)/poke |
| 902 | |
| 903 | clean: |
| 904 | rm poke poke.o |
| 905 | @end example |
| 906 | |
| 907 | Some problems with this approach should be clear. |
| 908 | |
| 909 | Users who want to compile poke will have to know how @samp{utime} works |
| 910 | on their systems, so that they can uncomment the @file{Makefile} |
| 911 | correctly. |
| 912 | |
| 913 | The installation is done using @samp{cp}, but many systems have an |
| 914 | @samp{install} program which may be used, and which supports optional |
| 915 | features such as stripping debugging information out of the installed |
| 916 | binary. |
| 917 | |
| 918 | The use of @file{Makefile} variables like @samp{CC}, @samp{CFLAGS} and |
| 919 | @samp{LDFLAGS} follows the requirements of the GNU standards. This is |
| 920 | convenient for all packages, since it reduces surprises for users. |
| 921 | However, it is easy to get the details wrong, and wind up with a |
| 922 | slightly nonstandard distribution. |
| 923 | |
| 924 | @node Getting Started Example 3 |
| 925 | @subsection Third Try |
| 926 | |
| 927 | For our third try at this program, we will write a @file{configure.in} |
| 928 | script to discover the configuration features on the host system, rather |
| 929 | than requiring the user to edit the @file{Makefile}. We will also write |
| 930 | a @file{Makefile.am} rather than a @file{Makefile}. |
| 931 | |
| 932 | The only change to @file{poke.c} is to add a line at the start of the |
| 933 | file: |
| 934 | @smallexample |
| 935 | #include "config.h" |
| 936 | @end smallexample |
| 937 | |
| 938 | The new @file{configure.in} file is as follows. |
| 939 | |
| 940 | @example |
| 941 | AC_INIT(poke.c) |
| 942 | AM_INIT_AUTOMAKE(poke, 1.0) |
| 943 | AM_CONFIG_HEADER(config.h:config.in) |
| 944 | AC_PROG_CC |
| 945 | AC_HEADER_STDC |
| 946 | AC_CHECK_HEADERS(utime.h) |
| 947 | AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF)) |
| 948 | AC_FUNC_UTIME_NULL |
| 949 | AC_OUTPUT(Makefile) |
| 950 | @end example |
| 951 | |
| 952 | The first four macros in this file, and the last one, were described |
| 953 | above; see @ref{Write configure.in}. If we omit these macros, then when |
| 954 | we run @samp{automake} we will get a reminder that we need them. |
| 955 | |
| 956 | The other macros are standard autoconf macros. |
| 957 | |
| 958 | @table @samp |
| 959 | @item AC_HEADER_STDC |
| 960 | Check for standard C headers. |
| 961 | @item AC_CHECK_HEADERS |
| 962 | Check whether a particular header file exists. |
| 963 | @item AC_EGREP_HEADER |
| 964 | Check for a particular string in a particular header file, in this case |
| 965 | checking for @samp{utimbuf} in @file{utime.h}. |
| 966 | @item AC_FUNC_UTIME_NULL |
| 967 | Check whether @samp{utime} accepts a NULL second argument to set the |
| 968 | file change time to the current time. |
| 969 | @end table |
| 970 | |
| 971 | See the autoconf manual for a more complete description. |
| 972 | |
| 973 | The new @file{Makefile.am} file is as follows. Note how simple this is |
| 974 | compared to our earlier @file{Makefile}. |
| 975 | |
| 976 | @example |
| 977 | bin_PROGRAMS = poke |
| 978 | |
| 979 | poke_SOURCES = poke.c |
| 980 | @end example |
| 981 | |
| 982 | This means that we should build a single program name @samp{poke}. It |
| 983 | should be installed in the binary directory, which we called |
| 984 | @samp{bindir} earlier. The program @samp{poke} is built from the source |
| 985 | file @file{poke.c}. |
| 986 | |
| 987 | We must also write a @file{acconfig.h} file. Besides @samp{PACKAGE} and |
| 988 | @samp{VERSION}, which must be mentioned for all packages which use |
| 989 | automake, we must include @samp{HAVE_STRUCT_UTIMBUF}, since we mentioned |
| 990 | it in an @samp{AC_DEFINE}. |
| 991 | |
| 992 | @example |
| 993 | /* Name of package. */ |
| 994 | #undef PACKAGE |
| 995 | |
| 996 | /* Version of package. */ |
| 997 | #undef VERSION |
| 998 | |
| 999 | /* Whether utime.h defines struct utimbuf. */ |
| 1000 | #undef HAVE_STRUCT_UTIMBUF |
| 1001 | @end example |
| 1002 | |
| 1003 | @node Generate Files in Example |
| 1004 | @subsection Generate Files |
| 1005 | |
| 1006 | We must now generate the other files, using the following commands. |
| 1007 | |
| 1008 | @smallexample |
| 1009 | aclocal |
| 1010 | autoconf |
| 1011 | autoheader |
| 1012 | automake |
| 1013 | @end smallexample |
| 1014 | |
| 1015 | When we run @samp{autoheader}, it will remind us of any macros we forgot |
| 1016 | to add to @file{acconfig.h}. |
| 1017 | |
| 1018 | When we run @samp{automake}, it will want to add some files to our |
| 1019 | distribution. It will add them automatically if we use the |
| 1020 | @samp{--add-missing} option. |
| 1021 | |
| 1022 | By default, @samp{automake} will run in GNU mode, which means that it |
| 1023 | will want us to create certain additional files; as of this writing, it |
| 1024 | will want @file{NEWS}, @file{README}, @file{AUTHORS}, and |
| 1025 | @file{ChangeLog}, all of which are files which should appear in a |
| 1026 | standard GNU distribution. We can either add those files, or run |
| 1027 | @samp{automake} with the @samp{--foreign} option. |
| 1028 | |
| 1029 | Running these tools will generate the following files, all of which are |
| 1030 | described in the next chapter. |
| 1031 | |
| 1032 | @itemize @bullet |
| 1033 | @item |
| 1034 | @file{aclocal.m4} |
| 1035 | @item |
| 1036 | @file{configure} |
| 1037 | @item |
| 1038 | @file{config.in} |
| 1039 | @item |
| 1040 | @file{Makefile.in} |
| 1041 | @item |
| 1042 | @file{stamp-h.in} |
| 1043 | @end itemize |
| 1044 | |
| 1045 | @node Files |
| 1046 | @chapter Files |
| 1047 | |
| 1048 | As was seen in the previous chapter, the GNU configure and build system |
| 1049 | uses a number of different files. The developer must write a few files. |
| 1050 | The others are generated by various tools. |
| 1051 | |
| 1052 | The system is rather flexible, and can be used in many different ways. |
| 1053 | In describing the files that it uses, I will describe the common case, |
| 1054 | and mention some other cases that may arise. |
| 1055 | |
| 1056 | @menu |
| 1057 | * Developer Files:: Developer Files. |
| 1058 | * Build Files:: Build Files. |
| 1059 | * Support Files:: Support Files. |
| 1060 | @end menu |
| 1061 | |
| 1062 | @node Developer Files |
| 1063 | @section Developer Files |
| 1064 | |
| 1065 | This section describes the files written or generated by the developer |
| 1066 | of a package. |
| 1067 | |
| 1068 | @menu |
| 1069 | * Developer Files Picture:: Developer Files Picture. |
| 1070 | * Written Developer Files:: Written Developer Files. |
| 1071 | * Generated Developer Files:: Generated Developer Files. |
| 1072 | @end menu |
| 1073 | |
| 1074 | @node Developer Files Picture |
| 1075 | @subsection Developer Files Picture |
| 1076 | |
| 1077 | Here is a picture of the files which are written by the developer, the |
| 1078 | generated files which would be included with a complete source |
| 1079 | distribution, and the tools which create those files. |
| 1080 | @ifinfo |
| 1081 | The file names are plain text and the tool names are enclosed by |
| 1082 | @samp{*} characters |
| 1083 | @end ifinfo |
| 1084 | @ifnotinfo |
| 1085 | The file names are in rectangles with square corners and the tool names |
| 1086 | are in rectangles with rounded corners |
| 1087 | @end ifnotinfo |
| 1088 | (e.g., @samp{autoheader} is the name of a tool, not the name of a file). |
| 1089 | |
| 1090 | @image{configdev,,,,jpg} |
| 1091 | |
| 1092 | @node Written Developer Files |
| 1093 | @subsection Written Developer Files |
| 1094 | |
| 1095 | The following files would be written by the developer. |
| 1096 | |
| 1097 | @table @file |
| 1098 | @item configure.in |
| 1099 | @cindex @file{configure.in} |
| 1100 | This is the configuration script. This script contains invocations of |
| 1101 | autoconf macros. It may also contain ordinary shell script code. This |
| 1102 | file will contain feature tests for portability issues. The last thing |
| 1103 | in the file will normally be an @samp{AC_OUTPUT} macro listing which |
| 1104 | files to create when the builder runs the configure script. This file |
| 1105 | is always required when using the GNU configure system. @xref{Write |
| 1106 | configure.in}. |
| 1107 | |
| 1108 | @item Makefile.am |
| 1109 | @cindex @file{Makefile.am} |
| 1110 | This is the automake input file. It describes how the code should be |
| 1111 | built. It consists of definitions of automake variables. It may also |
| 1112 | contain ordinary Makefile targets. This file is only needed when using |
| 1113 | automake (newer tools normally use automake, but there are still older |
| 1114 | tools which have not been converted, in which the developer writes |
| 1115 | @file{Makefile.in} directly). @xref{Write Makefile.am}. |
| 1116 | |
| 1117 | @item acconfig.h |
| 1118 | @cindex @file{acconfig.h} |
| 1119 | When the configure script creates a portability header file, by using |
| 1120 | @samp{AM_CONFIG_HEADER} (or, if not using automake, |
| 1121 | @samp{AC_CONFIG_HEADER}), this file is used to describe macros which are |
| 1122 | not recognized by the @samp{autoheader} command. This is normally a |
| 1123 | fairly uninteresting file, consisting of a collection of @samp{#undef} |
| 1124 | lines with comments. Normally any call to @samp{AC_DEFINE} in |
| 1125 | @file{configure.in} will require a line in this file. @xref{Write |
| 1126 | acconfig.h}. |
| 1127 | |
| 1128 | @item acinclude.m4 |
| 1129 | @cindex @file{acinclude.m4} |
| 1130 | This file is not always required. It defines local autoconf macros. |
| 1131 | These macros may then be used in @file{configure.in}. If you don't need |
| 1132 | any local autoconf macros, then you don't need this file at all. In |
| 1133 | fact, in general, you never need local autoconf macros, since you can |
| 1134 | put everything in @file{configure.in}, but sometimes a local macro is |
| 1135 | convenient. |
| 1136 | |
| 1137 | Newer tools may omit @file{acinclude.m4}, and instead use a |
| 1138 | subdirectory, typically named @file{m4}, and define |
| 1139 | @samp{ACLOCAL_AMFLAGS = -I m4} in @file{Makefile.am} to force |
| 1140 | @samp{aclocal} to look there for macro definitions. The macro |
| 1141 | definitions are then placed in separate files in that directory. |
| 1142 | |
| 1143 | The @file{acinclude.m4} file is only used when using automake; in older |
| 1144 | tools, the developer writes @file{aclocal.m4} directly, if it is needed. |
| 1145 | @end table |
| 1146 | |
| 1147 | @node Generated Developer Files |
| 1148 | @subsection Generated Developer Files |
| 1149 | |
| 1150 | The following files would be generated by the developer. |
| 1151 | |
| 1152 | When using automake, these files are normally not generated manually |
| 1153 | after the first time. Instead, the generated @file{Makefile} contains |
| 1154 | rules to automatically rebuild the files as required. When |
| 1155 | @samp{AM_MAINTAINER_MODE} is used in @file{configure.in} (the normal |
| 1156 | case in Cygnus code), the automatic rebuilding rules will only be |
| 1157 | defined if you configure using the @samp{--enable-maintainer-mode} |
| 1158 | option. |
| 1159 | |
| 1160 | When using automatic rebuilding, it is important to ensure that all the |
| 1161 | various tools have been built and installed on your @samp{PATH}. Using |
| 1162 | automatic rebuilding is highly recommended, so much so that I'm not |
| 1163 | going to explain what you have to do if you don't use it. |
| 1164 | |
| 1165 | @table @file |
| 1166 | @item configure |
| 1167 | @cindex @file{configure} |
| 1168 | This is the configure script which will be run when building the |
| 1169 | package. This is generated by @samp{autoconf} from @file{configure.in} |
| 1170 | and @file{aclocal.m4}. This is a shell script. |
| 1171 | |
| 1172 | @item Makefile.in |
| 1173 | @cindex @file{Makefile.in} |
| 1174 | This is the file which the configure script will turn into the |
| 1175 | @file{Makefile} at build time. This file is generated by |
| 1176 | @samp{automake} from @file{Makefile.am}. If you aren't using automake, |
| 1177 | you must write this file yourself. This file is pretty much a normal |
| 1178 | @file{Makefile}, with some configure substitutions for certain |
| 1179 | variables. |
| 1180 | |
| 1181 | @item aclocal.m4 |
| 1182 | @cindex @file{aclocal.m4} |
| 1183 | This file is created by the @samp{aclocal} program, based on the |
| 1184 | contents of @file{configure.in} and @file{acinclude.m4} (or, as noted in |
| 1185 | the description of @file{acinclude.m4} above, on the contents of an |
| 1186 | @file{m4} subdirectory). This file contains definitions of autoconf |
| 1187 | macros which @samp{autoconf} will use when generating the file |
| 1188 | @file{configure}. These autoconf macros may be defined by you in |
| 1189 | @file{acinclude.m4} or they may be defined by other packages such as |
| 1190 | automake, libtool or gettext. If you aren't using automake, you will |
| 1191 | normally write this file yourself; in that case, if @file{configure.in} |
| 1192 | uses only standard autoconf macros, this file will not be needed at all. |
| 1193 | |
| 1194 | @item config.in |
| 1195 | @cindex @file{config.in} |
| 1196 | @cindex @file{config.h.in} |
| 1197 | This file is created by @samp{autoheader} based on @file{acconfig.h} and |
| 1198 | @file{configure.in}. At build time, the configure script will define |
| 1199 | some of the macros in it to create @file{config.h}, which may then be |
| 1200 | included by your program. This permits your C code to use preprocessor |
| 1201 | conditionals to change its behaviour based on the characteristics of the |
| 1202 | host system. This file may also be called @file{config.h.in}. |
| 1203 | |
| 1204 | @item stamp.h-in |
| 1205 | @cindex @file{stamp-h.in} |
| 1206 | This rather uninteresting file, which I omitted from the picture, is |
| 1207 | generated by @samp{automake}. It always contains the string |
| 1208 | @samp{timestamp}. It is used as a timestamp file indicating whether |
| 1209 | @file{config.in} is up to date. Using a timestamp file means that |
| 1210 | @file{config.in} can be marked as up to date without actually changing |
| 1211 | its modification time. This is useful since @file{config.in} depends |
| 1212 | upon @file{configure.in}, but it is easy to change @file{configure.in} |
| 1213 | in a way which does not affect @file{config.in}. |
| 1214 | @end table |
| 1215 | |
| 1216 | @node Build Files |
| 1217 | @section Build Files |
| 1218 | |
| 1219 | This section describes the files which are created at configure and |
| 1220 | build time. These are the files which somebody who builds the package |
| 1221 | will see. |
| 1222 | |
| 1223 | Of course, the developer will also build the package. The distinction |
| 1224 | between developer files and build files is not that the developer does |
| 1225 | not see the build files, but that somebody who only builds the package |
| 1226 | does not have to worry about the developer files. |
| 1227 | |
| 1228 | @menu |
| 1229 | * Build Files Picture:: Build Files Picture. |
| 1230 | * Build Files Description:: Build Files Description. |
| 1231 | @end menu |
| 1232 | |
| 1233 | @node Build Files Picture |
| 1234 | @subsection Build Files Picture |
| 1235 | |
| 1236 | Here is a picture of the files which will be created at build time. |
| 1237 | @file{config.status} is both a created file and a shell script which is |
| 1238 | run to create other files, and the picture attempts to show that. |
| 1239 | |
| 1240 | @image{configbuild,,,,jpg} |
| 1241 | |
| 1242 | @node Build Files Description |
| 1243 | @subsection Build Files Description |
| 1244 | |
| 1245 | This is a description of the files which are created at build time. |
| 1246 | |
| 1247 | @table @file |
| 1248 | @item config.status |
| 1249 | @cindex @file{config.status} |
| 1250 | The first step in building a package is to run the @file{configure} |
| 1251 | script. The @file{configure} script will create the file |
| 1252 | @file{config.status}, which is itself a shell script. When you first |
| 1253 | run @file{configure}, it will automatically run @file{config.status}. |
| 1254 | An @file{Makefile} derived from an automake generated @file{Makefile.in} |
| 1255 | will contain rules to automatically run @file{config.status} again when |
| 1256 | necessary to recreate certain files if their inputs change. |
| 1257 | |
| 1258 | @item Makefile |
| 1259 | @cindex @file{Makefile} |
| 1260 | This is the file which make will read to build the program. The |
| 1261 | @file{config.status} script will transform @file{Makefile.in} into |
| 1262 | @file{Makefile}. |
| 1263 | |
| 1264 | @item config.h |
| 1265 | @cindex @file{config.h} |
| 1266 | This file defines C preprocessor macros which C code can use to adjust |
| 1267 | its behaviour on different systems. The @file{config.status} script |
| 1268 | will transform @file{config.in} into @file{config.h}. |
| 1269 | |
| 1270 | @item config.cache |
| 1271 | @cindex @file{config.cache} |
| 1272 | This file did not fit neatly into the picture, and I omitted it. It is |
| 1273 | used by the @file{configure} script to cache results between runs. This |
| 1274 | can be an important speedup. If you modify @file{configure.in} in such |
| 1275 | a way that the results of old tests should change (perhaps you have |
| 1276 | added a new library to @samp{LDFLAGS}), then you will have to remove |
| 1277 | @file{config.cache} to force the tests to be rerun. |
| 1278 | |
| 1279 | The autoconf manual explains how to set up a site specific cache file. |
| 1280 | This can speed up running @file{configure} scripts on your system. |
| 1281 | |
| 1282 | @item stamp.h |
| 1283 | @cindex @file{stamp-h} |
| 1284 | This file, which I omitted from the picture, is similar to |
| 1285 | @file{stamp-h.in}. It is used as a timestamp file indicating whether |
| 1286 | @file{config.h} is up to date. This is useful since @file{config.h} |
| 1287 | depends upon @file{config.status}, but it is easy for |
| 1288 | @file{config.status} to change in a way which does not affect |
| 1289 | @file{config.h}. |
| 1290 | @end table |
| 1291 | |
| 1292 | @node Support Files |
| 1293 | @section Support Files |
| 1294 | |
| 1295 | The GNU configure and build system requires several support files to be |
| 1296 | included with your distribution. You do not normally need to concern |
| 1297 | yourself with these. If you are using the Cygnus tree, most are already |
| 1298 | present. Otherwise, they will be installed with your source by |
| 1299 | @samp{automake} (with the @samp{--add-missing} option) and |
| 1300 | @samp{libtoolize}. |
| 1301 | |
| 1302 | You don't have to put the support files in the top level directory. You |
| 1303 | can put them in a subdirectory, and use the @samp{AC_CONFIG_AUX_DIR} |
| 1304 | macro in @file{configure.in} to tell @samp{automake} and the |
| 1305 | @file{configure} script where they are. |
| 1306 | |
| 1307 | In this section, I describe the support files, so that you can know what |
| 1308 | they are and why they are there. |
| 1309 | |
| 1310 | @table @file |
| 1311 | @item ABOUT-NLS |
| 1312 | Added by automake if you are using gettext. This is a documentation |
| 1313 | file about the gettext project. |
| 1314 | @item ansi2knr.c |
| 1315 | Used by an automake generated @file{Makefile} if you put @samp{ansi2knr} |
| 1316 | in @samp{AUTOMAKE_OPTIONS} in @file{Makefile.am}. This permits |
| 1317 | compiling ANSI C code with a K&R C compiler. |
| 1318 | @item ansi2knr.1 |
| 1319 | The man page which goes with @file{ansi2knr.c}. |
| 1320 | @item config.guess |
| 1321 | A shell script which determines the configuration name for the system on |
| 1322 | which it is run. |
| 1323 | @item config.sub |
| 1324 | A shell script which canonicalizes a configuration name entered by a |
| 1325 | user. |
| 1326 | @item elisp-comp |
| 1327 | Used to compile Emacs LISP files. |
| 1328 | @item install-sh |
| 1329 | A shell script which installs a program. This is used if the configure |
| 1330 | script can not find an install binary. |
| 1331 | @item ltconfig |
| 1332 | Used by libtool. This is a shell script which configures libtool for |
| 1333 | the particular system on which it is used. |
| 1334 | @item ltmain.sh |
| 1335 | Used by libtool. This is the actual libtool script which is used, after |
| 1336 | it is configured by @file{ltconfig} to build a library. |
| 1337 | @item mdate-sh |
| 1338 | A shell script used by an automake generated @file{Makefile} to pretty |
| 1339 | print the modification time of a file. This is used to maintain version |
| 1340 | numbers for texinfo files. |
| 1341 | @item missing |
| 1342 | A shell script used if some tool is missing entirely. This is used by |
| 1343 | an automake generated @file{Makefile} to avoid certain sorts of |
| 1344 | timestamp problems. |
| 1345 | @item mkinstalldirs |
| 1346 | A shell script which creates a directory, including all parent |
| 1347 | directories. This is used by an automake generated @file{Makefile} |
| 1348 | during installation. |
| 1349 | @item texinfo.tex |
| 1350 | Required if you have any texinfo files. This is used when converting |
| 1351 | Texinfo files into DVI using @samp{texi2dvi} and @TeX{}. |
| 1352 | @item ylwrap |
| 1353 | A shell script used by an automake generated @file{Makefile} to run |
| 1354 | programs like @samp{bison}, @samp{yacc}, @samp{flex}, and @samp{lex}. |
| 1355 | These programs default to producing output files with a fixed name, and |
| 1356 | the @file{ylwrap} script runs them in a subdirectory to avoid file name |
| 1357 | conflicts when using a parallel make program. |
| 1358 | @end table |
| 1359 | |
| 1360 | @node Configuration Names |
| 1361 | @chapter Configuration Names |
| 1362 | @cindex configuration names |
| 1363 | @cindex configuration triplets |
| 1364 | @cindex triplets |
| 1365 | @cindex host names |
| 1366 | @cindex host triplets |
| 1367 | @cindex canonical system names |
| 1368 | @cindex system names |
| 1369 | @cindex system types |
| 1370 | |
| 1371 | The GNU configure system names all systems using a @dfn{configuration |
| 1372 | name}. All such names used to be triplets (they may now contain four |
| 1373 | parts in certain cases), and the term @dfn{configuration triplet} is |
| 1374 | still seen. |
| 1375 | |
| 1376 | @menu |
| 1377 | * Configuration Name Definition:: Configuration Name Definition. |
| 1378 | * Using Configuration Names:: Using Configuration Names. |
| 1379 | @end menu |
| 1380 | |
| 1381 | @node Configuration Name Definition |
| 1382 | @section Configuration Name Definition |
| 1383 | |
| 1384 | This is a string of the form |
| 1385 | @var{cpu}-@var{manufacturer}-@var{operating_system}. In some cases, |
| 1386 | this is extended to a four part form: |
| 1387 | @var{cpu}-@var{manufacturer}-@var{kernel}-@var{operating_system}. |
| 1388 | |
| 1389 | When using a configuration name in a configure option, it is normally |
| 1390 | not necessary to specify an entire name. In particular, the |
| 1391 | @var{manufacturer} field is often omitted, leading to strings such as |
| 1392 | @samp{i386-linux} or @samp{sparc-sunos}. The shell script |
| 1393 | @file{config.sub} will translate these shortened strings into the |
| 1394 | canonical form. autoconf will arrange for @file{config.sub} to be run |
| 1395 | automatically when it is needed. |
| 1396 | |
| 1397 | The fields of a configuration name are as follows: |
| 1398 | |
| 1399 | @table @var |
| 1400 | @item cpu |
| 1401 | The type of processor. This is typically something like @samp{i386} or |
| 1402 | @samp{sparc}. More specific variants are used as well, such as |
| 1403 | @samp{mipsel} to indicate a little endian MIPS processor. |
| 1404 | @item manufacturer |
| 1405 | A somewhat freeform field which indicates the manufacturer of the |
| 1406 | system. This is often simply @samp{unknown}. Other common strings are |
| 1407 | @samp{pc} for an IBM PC compatible system, or the name of a workstation |
| 1408 | vendor, such as @samp{sun}. |
| 1409 | @item operating_system |
| 1410 | The name of the operating system which is run on the system. This will |
| 1411 | be something like @samp{solaris2.5} or @samp{irix6.3}. There is no |
| 1412 | particular restriction on the version number, and strings like |
| 1413 | @samp{aix4.1.4.0} are seen. For an embedded system, which has no |
| 1414 | operating system, this field normally indicates the type of object file |
| 1415 | format, such as @samp{elf} or @samp{coff}. |
| 1416 | @item kernel |
| 1417 | This is used mainly for GNU/Linux. A typical GNU/Linux configuration |
| 1418 | name is @samp{i586-pc-linux-gnulibc1}. In this case the kernel, |
| 1419 | @samp{linux}, is separated from the operating system, @samp{gnulibc1}. |
| 1420 | @end table |
| 1421 | |
| 1422 | The shell script @file{config.guess} will normally print the correct |
| 1423 | configuration name for the system on which it is run. It does by |
| 1424 | running @samp{uname} and by examining other characteristics of the |
| 1425 | system. |
| 1426 | |
| 1427 | Because @file{config.guess} can normally determine the configuration |
| 1428 | name for a machine, it is normally only necessary to specify a |
| 1429 | configuration name when building a cross-compiler or when building using |
| 1430 | a cross-compiler. |
| 1431 | |
| 1432 | @node Using Configuration Names |
| 1433 | @section Using Configuration Names |
| 1434 | |
| 1435 | A configure script will sometimes have to make a decision based on a |
| 1436 | configuration name. You will need to do this if you have to compile |
| 1437 | code differently based on something which can not be tested using a |
| 1438 | standard autoconf feature test. |
| 1439 | |
| 1440 | It is normally better to test for particular features, rather than to |
| 1441 | test for a particular system. This is because as Unix evolves, |
| 1442 | different systems copy features from one another. Even if you need to |
| 1443 | determine whether the feature is supported based on a configuration |
| 1444 | name, you should define a macro which describes the feature, rather than |
| 1445 | defining a macro which describes the particular system you are on. |
| 1446 | |
| 1447 | Testing for a particular system is normally done using a case statement |
| 1448 | in @file{configure.in}. The case statement might look something like |
| 1449 | the following, assuming that @samp{host} is a shell variable holding a |
| 1450 | canonical configuration name (which will be the case if |
| 1451 | @file{configure.in} uses the @samp{AC_CANONICAL_HOST} or |
| 1452 | @samp{AC_CANONICAL_SYSTEM} macro). |
| 1453 | |
| 1454 | @smallexample |
| 1455 | case "$@{host@}" in |
| 1456 | i[3-7]86-*-linux-gnu*) do something ;; |
| 1457 | sparc*-sun-solaris2.[56789]*) do something ;; |
| 1458 | sparc*-sun-solaris*) do something ;; |
| 1459 | mips*-*-elf*) do something ;; |
| 1460 | esac |
| 1461 | @end smallexample |
| 1462 | |
| 1463 | It is particularly important to use @samp{*} after the operating system |
| 1464 | field, in order to match the version number which will be generated by |
| 1465 | @file{config.guess}. |
| 1466 | |
| 1467 | In most cases you must be careful to match a range of processor types. |
| 1468 | For most processor families, a trailing @samp{*} suffices, as in |
| 1469 | @samp{mips*} above. For the i386 family, something along the lines of |
| 1470 | @samp{i[3-7]86} suffices at present. For the m68k family, you will |
| 1471 | need something like @samp{m68*}. Of course, if you do not need to match |
| 1472 | on the processor, it is simpler to just replace the entire field by a |
| 1473 | @samp{*}, as in @samp{*-*-irix*}. |
| 1474 | |
| 1475 | @node Cross Compilation Tools |
| 1476 | @chapter Cross Compilation Tools |
| 1477 | @cindex cross tools |
| 1478 | |
| 1479 | The GNU configure and build system can be used to build @dfn{cross |
| 1480 | compilation} tools. A cross compilation tool is a tool which runs on |
| 1481 | one system and produces code which runs on another system. |
| 1482 | |
| 1483 | @menu |
| 1484 | * Cross Compilation Concepts:: Cross Compilation Concepts. |
| 1485 | * Host and Target:: Host and Target. |
| 1486 | * Using the Host Type:: Using the Host Type. |
| 1487 | * Specifying the Target:: Specifying the Target. |
| 1488 | * Using the Target Type:: Using the Target Type. |
| 1489 | * Cross Tools in the Cygnus Tree:: Cross Tools in the Cygnus Tree |
| 1490 | @end menu |
| 1491 | |
| 1492 | @node Cross Compilation Concepts |
| 1493 | @section Cross Compilation Concepts |
| 1494 | |
| 1495 | @cindex cross compiler |
| 1496 | A compiler which produces programs which run on a different system is a |
| 1497 | cross compilation compiler, or simply a @dfn{cross compiler}. |
| 1498 | Similarly, we speak of cross assemblers, cross linkers, etc. |
| 1499 | |
| 1500 | In the normal case, a compiler produces code which runs on the same |
| 1501 | system as the one on which the compiler runs. When it is necessary to |
| 1502 | distinguish this case from the cross compilation case, such a compiler |
| 1503 | is called a @dfn{native compiler}. Similarly, we speak of native |
| 1504 | assemblers, etc. |
| 1505 | |
| 1506 | Although the debugger is not strictly speaking a compilation tool, it is |
| 1507 | nevertheless meaningful to speak of a cross debugger: a debugger which |
| 1508 | is used to debug code which runs on another system. Everything that is |
| 1509 | said below about configuring cross compilation tools applies to the |
| 1510 | debugger as well. |
| 1511 | |
| 1512 | @node Host and Target |
| 1513 | @section Host and Target |
| 1514 | @cindex host system |
| 1515 | @cindex target system |
| 1516 | |
| 1517 | When building cross compilation tools, there are two different systems |
| 1518 | involved: the system on which the tools will run, and the system for |
| 1519 | which the tools generate code. |
| 1520 | |
| 1521 | The system on which the tools will run is called the @dfn{host} system. |
| 1522 | |
| 1523 | The system for which the tools generate code is called the @dfn{target} |
| 1524 | system. |
| 1525 | |
| 1526 | For example, suppose you have a compiler which runs on a GNU/Linux |
| 1527 | system and generates ELF programs for a MIPS embedded system. In this |
| 1528 | case the GNU/Linux system is the host, and the MIPS ELF system is the |
| 1529 | target. Such a compiler could be called a GNU/Linux cross MIPS ELF |
| 1530 | compiler, or, equivalently, a @samp{i386-linux-gnu} cross |
| 1531 | @samp{mips-elf} compiler. |
| 1532 | |
| 1533 | Naturally, most programs are not cross compilation tools. For those |
| 1534 | programs, it does not make sense to speak of a target. It only makes |
| 1535 | sense to speak of a target for tools like @samp{gcc} or the |
| 1536 | @samp{binutils} which actually produce running code. For example, it |
| 1537 | does not make sense to speak of the target of a tool like @samp{bison} |
| 1538 | or @samp{make}. |
| 1539 | |
| 1540 | Most cross compilation tools can also serve as native tools. For a |
| 1541 | native compilation tool, it is still meaningful to speak of a target. |
| 1542 | For a native tool, the target is the same as the host. For example, for |
| 1543 | a GNU/Linux native compiler, the host is GNU/Linux, and the target is |
| 1544 | also GNU/Linux. |
| 1545 | |
| 1546 | @node Using the Host Type |
| 1547 | @section Using the Host Type |
| 1548 | |
| 1549 | In almost all cases the host system is the system on which you run the |
| 1550 | @samp{configure} script, and on which you build the tools (for the case |
| 1551 | when they differ, @pxref{Canadian Cross}). |
| 1552 | |
| 1553 | @cindex @samp{AC_CANONICAL_HOST} |
| 1554 | If your configure script needs to know the configuration name of the |
| 1555 | host system, and the package is not a cross compilation tool and |
| 1556 | therefore does not have a target, put @samp{AC_CANONICAL_HOST} in |
| 1557 | @file{configure.in}. This macro will arrange to define a few shell |
| 1558 | variables when the @samp{configure} script is run. |
| 1559 | |
| 1560 | @table @samp |
| 1561 | @item host |
| 1562 | The canonical configuration name of the host. This will normally be |
| 1563 | determined by running the @file{config.guess} shell script, although the |
| 1564 | user is permitted to override this by using an explicit @samp{--host} |
| 1565 | option. |
| 1566 | @item host_alias |
| 1567 | In the unusual case that the user used an explicit @samp{--host} option, |
| 1568 | this will be the argument to @samp{--host}. In the normal case, this |
| 1569 | will be the same as the @samp{host} variable. |
| 1570 | @item host_cpu |
| 1571 | @itemx host_vendor |
| 1572 | @itemx host_os |
| 1573 | The first three parts of the canonical configuration name. |
| 1574 | @end table |
| 1575 | |
| 1576 | The shell variables may be used by putting shell code in |
| 1577 | @file{configure.in}. For an example, see @ref{Using Configuration |
| 1578 | Names}. |
| 1579 | |
| 1580 | @node Specifying the Target |
| 1581 | @section Specifying the Target |
| 1582 | |
| 1583 | By default, the @samp{configure} script will assume that the target is |
| 1584 | the same as the host. This is the more common case; for example, it |
| 1585 | leads to a native compiler rather than a cross compiler. |
| 1586 | |
| 1587 | @cindex @samp{--target} option |
| 1588 | @cindex target option |
| 1589 | @cindex configure target |
| 1590 | If you want to build a cross compilation tool, you must specify the |
| 1591 | target explicitly by using the @samp{--target} option when you run |
| 1592 | @samp{configure}. The argument to @samp{--target} is the configuration |
| 1593 | name of the system for which you wish to generate code. |
| 1594 | @xref{Configuration Names}. |
| 1595 | |
| 1596 | For example, to build tools which generate code for a MIPS ELF embedded |
| 1597 | system, you would use @samp{--target mips-elf}. |
| 1598 | |
| 1599 | @node Using the Target Type |
| 1600 | @section Using the Target Type |
| 1601 | |
| 1602 | @cindex @samp{AC_CANONICAL_SYSTEM} |
| 1603 | When writing @file{configure.in} for a cross compilation tool, you will |
| 1604 | need to use information about the target. To do this, put |
| 1605 | @samp{AC_CANONICAL_SYSTEM} in @file{configure.in}. |
| 1606 | |
| 1607 | @samp{AC_CANONICAL_SYSTEM} will look for a @samp{--target} option and |
| 1608 | canonicalize it using the @file{config.sub} shell script. It will also |
| 1609 | run @samp{AC_CANONICAL_HOST} (@pxref{Using the Host Type}). |
| 1610 | |
| 1611 | The target type will be recorded in the following shell variables. Note |
| 1612 | that the host versions of these variables will also be defined by |
| 1613 | @samp{AC_CANONICAL_HOST}. |
| 1614 | |
| 1615 | @table @samp |
| 1616 | @item target |
| 1617 | The canonical configuration name of the target. |
| 1618 | @item target_alias |
| 1619 | The argument to the @samp{--target} option. If the user did not specify |
| 1620 | a @samp{--target} option, this will be the same as @samp{host_alias}. |
| 1621 | @item target_cpu |
| 1622 | @itemx target_vendor |
| 1623 | @itemx target_os |
| 1624 | The first three parts of the canonical target configuration name. |
| 1625 | @end table |
| 1626 | |
| 1627 | Note that if @samp{host} and @samp{target} are the same string, you can |
| 1628 | assume a native configuration. If they are different, you can assume a |
| 1629 | cross configuration. |
| 1630 | |
| 1631 | It is arguably possible for @samp{host} and @samp{target} to represent |
| 1632 | the same system, but for the strings to not be identical. For example, |
| 1633 | if @samp{config.guess} returns @samp{sparc-sun-sunos4.1.4}, and somebody |
| 1634 | configures with @samp{--target sparc-sun-sunos4.1}, then the slight |
| 1635 | differences between the two versions of SunOS may be unimportant for |
| 1636 | your tool. However, in the general case it can be quite difficult to |
| 1637 | determine whether the differences between two configuration names are |
| 1638 | significant or not. Therefore, by convention, if the user specifies a |
| 1639 | @samp{--target} option without specifying a @samp{--host} option, it is |
| 1640 | assumed that the user wants to configure a cross compilation tool. |
| 1641 | |
| 1642 | The variables @samp{target} and @samp{target_alias} should be handled |
| 1643 | differently. |
| 1644 | |
| 1645 | In general, whenever the user may actually see a string, |
| 1646 | @samp{target_alias} should be used. This includes anything which may |
| 1647 | appear in the file system, such as a directory name or part of a tool |
| 1648 | name. It also includes any tool output, unless it is clearly labelled |
| 1649 | as the canonical target configuration name. This permits the user to |
| 1650 | use the @samp{--target} option to specify how the tool will appear to |
| 1651 | the outside world. |
| 1652 | |
| 1653 | On the other hand, when checking for characteristics of the target |
| 1654 | system, @samp{target} should be used. This is because a wide variety of |
| 1655 | @samp{--target} options may map into the same canonical configuration |
| 1656 | name. You should not attempt to duplicate the canonicalization done by |
| 1657 | @samp{config.sub} in your own code. |
| 1658 | |
| 1659 | By convention, cross tools are installed with a prefix of the argument |
| 1660 | used with the @samp{--target} option, also known as @samp{target_alias} |
| 1661 | (@pxref{Using the Target Type}). If the user does not use the |
| 1662 | @samp{--target} option, and thus is building a native tool, no prefix is |
| 1663 | used. |
| 1664 | |
| 1665 | For example, if gcc is configured with @samp{--target mips-elf}, then |
| 1666 | the installed binary will be named @samp{mips-elf-gcc}. If gcc is |
| 1667 | configured without a @samp{--target} option, then the installed binary |
| 1668 | will be named @samp{gcc}. |
| 1669 | |
| 1670 | The autoconf macro @samp{AC_ARG_PROGRAM} will handle this for you. If |
| 1671 | you are using automake, no more need be done; the programs will |
| 1672 | automatically be installed with the correct prefixes. Otherwise, see |
| 1673 | the autoconf documentation for @samp{AC_ARG_PROGRAM}. |
| 1674 | |
| 1675 | @node Cross Tools in the Cygnus Tree |
| 1676 | @section Cross Tools in the Cygnus Tree |
| 1677 | |
| 1678 | The Cygnus tree is used for various packages including gdb, the GNU |
| 1679 | binutils, and egcs. It is also, of course, used for Cygnus releases. |
| 1680 | |
| 1681 | In the Cygnus tree, the top level @file{configure} script uses the old |
| 1682 | Cygnus configure system, not autoconf. The top level @file{Makefile.in} |
| 1683 | is written to build packages based on what is in the source tree, and |
| 1684 | supports building a large number of tools in a single |
| 1685 | @samp{configure}/@samp{make} step. |
| 1686 | |
| 1687 | The Cygnus tree may be configured with a @samp{--target} option. The |
| 1688 | @samp{--target} option applies recursively to every subdirectory, and |
| 1689 | permits building an entire set of cross tools at once. |
| 1690 | |
| 1691 | @menu |
| 1692 | * Host and Target Libraries:: Host and Target Libraries. |
| 1693 | * Target Library Configure Scripts:: Target Library Configure Scripts. |
| 1694 | * Make Targets in Cygnus Tree:: Make Targets in Cygnus Tree. |
| 1695 | * Target libiberty:: Target libiberty |
| 1696 | @end menu |
| 1697 | |
| 1698 | @node Host and Target Libraries |
| 1699 | @subsection Host and Target Libraries |
| 1700 | |
| 1701 | The Cygnus tree distinguishes host libraries from target libraries. |
| 1702 | |
| 1703 | Host libraries are built with the compiler used to build the programs |
| 1704 | which run on the host, which is called the host compiler. This includes |
| 1705 | libraries such as @samp{bfd} and @samp{tcl}. These libraries are built |
| 1706 | with the host compiler, and are linked into programs like the binutils |
| 1707 | or gcc which run on the host. |
| 1708 | |
| 1709 | Target libraries are built with the target compiler. If gcc is present |
| 1710 | in the source tree, then the target compiler is the gcc that is built |
| 1711 | using the host compiler. Target libraries are libraries such as |
| 1712 | @samp{newlib} and @samp{libstdc++}. These libraries are not linked into |
| 1713 | the host programs, but are instead made available for use with programs |
| 1714 | built with the target compiler. |
| 1715 | |
| 1716 | For the rest of this section, assume that gcc is present in the source |
| 1717 | tree, so that it will be used to build the target libraries. |
| 1718 | |
| 1719 | There is a complication here. The configure process needs to know which |
| 1720 | compiler you are going to use to build a tool; otherwise, the feature |
| 1721 | tests will not work correctly. The Cygnus tree handles this by not |
| 1722 | configuring the target libraries until the target compiler is built. In |
| 1723 | order to permit everything to build using a single |
| 1724 | @samp{configure}/@samp{make}, the configuration of the target libraries |
| 1725 | is actually triggered during the make step. |
| 1726 | |
| 1727 | When the target libraries are configured, the @samp{--target} option is |
| 1728 | not used. Instead, the @samp{--host} option is used with the argument |
| 1729 | of the @samp{--target} option for the overall configuration. If no |
| 1730 | @samp{--target} option was used for the overall configuration, the |
| 1731 | @samp{--host} option will be passed with the output of the |
| 1732 | @file{config.guess} shell script. Any @samp{--build} option is passed |
| 1733 | down unchanged. |
| 1734 | |
| 1735 | This translation of configuration options is done because since the |
| 1736 | target libraries are compiled with the target compiler, they are being |
| 1737 | built in order to run on the target of the overall configuration. By |
| 1738 | the definition of host, this means that their host system is the same as |
| 1739 | the target system of the overall configuration. |
| 1740 | |
| 1741 | The same process is used for both a native configuration and a cross |
| 1742 | configuration. Even when using a native configuration, the target |
| 1743 | libraries will be configured and built using the newly built compiler. |
| 1744 | This is particularly important for the C++ libraries, since there is no |
| 1745 | reason to assume that the C++ compiler used to build the host tools (if |
| 1746 | there even is one) uses the same ABI as the g++ compiler which will be |
| 1747 | used to build the target libraries. |
| 1748 | |
| 1749 | There is one difference between a native configuration and a cross |
| 1750 | configuration. In a native configuration, the target libraries are |
| 1751 | normally configured and built as siblings of the host tools. In a cross |
| 1752 | configuration, the target libraries are normally built in a subdirectory |
| 1753 | whose name is the argument to @samp{--target}. This is mainly for |
| 1754 | historical reasons. |
| 1755 | |
| 1756 | To summarize, running @samp{configure} in the Cygnus tree configures all |
| 1757 | the host libraries and tools, but does not configure any of the target |
| 1758 | libraries. Running @samp{make} then does the following steps: |
| 1759 | |
| 1760 | @itemize @bullet |
| 1761 | @item |
| 1762 | Build the host libraries. |
| 1763 | @item |
| 1764 | Build the host programs, including gcc. Note that we call gcc both a |
| 1765 | host program (since it runs on the host) and a target compiler (since it |
| 1766 | generates code for the target). |
| 1767 | @item |
| 1768 | Using the newly built target compiler, configure the target libraries. |
| 1769 | @item |
| 1770 | Build the target libraries. |
| 1771 | @end itemize |
| 1772 | |
| 1773 | The steps need not be done in precisely this order, since they are |
| 1774 | actually controlled by @file{Makefile} targets. |
| 1775 | |
| 1776 | @node Target Library Configure Scripts |
| 1777 | @subsection Target Library Configure Scripts |
| 1778 | |
| 1779 | There are a few things you must know in order to write a configure |
| 1780 | script for a target library. This is just a quick sketch, and beginners |
| 1781 | shouldn't worry if they don't follow everything here. |
| 1782 | |
| 1783 | The target libraries are configured and built using a newly built target |
| 1784 | compiler. There may not be any startup files or libraries for this |
| 1785 | target compiler. In fact, those files will probably be built as part of |
| 1786 | some target library, which naturally means that they will not exist when |
| 1787 | your target library is configured. |
| 1788 | |
| 1789 | This means that the configure script for a target library may not use |
| 1790 | any test which requires doing a link. This unfortunately includes many |
| 1791 | useful autoconf macros, such as @samp{AC_CHECK_FUNCS}. autoconf macros |
| 1792 | which do a compile but not a link, such as @samp{AC_CHECK_HEADERS}, may |
| 1793 | be used. |
| 1794 | |
| 1795 | This is a severe restriction, but normally not a fatal one, as target |
| 1796 | libraries can often assume the presence of other target libraries, and |
| 1797 | thus know which functions will be available. |
| 1798 | |
| 1799 | As of this writing, the autoconf macro @samp{AC_PROG_CC} does a link to |
| 1800 | make sure that the compiler works. This may fail in a target library, |
| 1801 | so target libraries must use a different set of macros to locate the |
| 1802 | compiler. See the @file{configure.in} file in a directory like |
| 1803 | @file{libiberty} or @file{libgloss} for an example. |
| 1804 | |
| 1805 | As noted in the previous section, target libraries are sometimes built |
| 1806 | in directories which are siblings to the host tools, and are sometimes |
| 1807 | built in a subdirectory. The @samp{--with-target-subdir} configure |
| 1808 | option will be passed when the library is configured. Its value will be |
| 1809 | an empty string if the target library is a sibling. Its value will be |
| 1810 | the name of the subdirectory if the target library is in a subdirectory. |
| 1811 | |
| 1812 | If the overall build is not a native build (i.e., the overall configure |
| 1813 | used the @samp{--target} option), then the library will be configured |
| 1814 | with the @samp{--with-cross-host} option. The value of this option will |
| 1815 | be the host system of the overall build. Recall that the host system of |
| 1816 | the library will be the target of the overall build. If the overall |
| 1817 | build is a native build, the @samp{--with-cross-host} option will not be |
| 1818 | used. |
| 1819 | |
| 1820 | A library which can be built both standalone and as a target library may |
| 1821 | want to install itself into different directories depending upon the |
| 1822 | case. When built standalone, or when built native, the library should |
| 1823 | be installed in @samp{$(libdir)}. When built as a target library which |
| 1824 | is not native, the library should be installed in @samp{$(tooldir)/lib}. |
| 1825 | The @samp{--with-cross-host} option may be used to distinguish these |
| 1826 | cases. |
| 1827 | |
| 1828 | This same test of @samp{--with-cross-host} may be used to see whether it |
| 1829 | is OK to use link tests in the configure script. If the |
| 1830 | @samp{--with-cross-host} option is not used, then the library is being |
| 1831 | built either standalone or native, and a link should work. |
| 1832 | |
| 1833 | @node Make Targets in Cygnus Tree |
| 1834 | @subsection Make Targets in Cygnus Tree |
| 1835 | |
| 1836 | The top level @file{Makefile} in the Cygnus tree defines targets for |
| 1837 | every known subdirectory. |
| 1838 | |
| 1839 | For every subdirectory @var{dir} which holds a host library or program, |
| 1840 | the @file{Makefile} target @samp{all-@var{dir}} will build that library |
| 1841 | or program. |
| 1842 | |
| 1843 | There are dependencies among host tools. For example, building gcc |
| 1844 | requires first building gas, because the gcc build process invokes the |
| 1845 | target assembler. These dependencies are reflected in the top level |
| 1846 | @file{Makefile}. |
| 1847 | |
| 1848 | For every subdirectory @var{dir} which holds a target library, the |
| 1849 | @file{Makefile} target @samp{configure-target-@var{dir}} will configure |
| 1850 | that library. The @file{Makefile} target @samp{all-target-@var{dir}} |
| 1851 | will build that library. |
| 1852 | |
| 1853 | Every @samp{configure-target-@var{dir}} target depends upon |
| 1854 | @samp{all-gcc}, since gcc, the target compiler, is required to configure |
| 1855 | the tool. Every @samp{all-target-@var{dir}} target depends upon the |
| 1856 | corresponding @samp{configure-target-@var{dir}} target. |
| 1857 | |
| 1858 | There are several other targets which may be of interest for each |
| 1859 | directory: @samp{install-@var{dir}}, @samp{clean-@var{dir}}, and |
| 1860 | @samp{check-@var{dir}}. There are also corresponding @samp{target} |
| 1861 | versions of these for the target libraries , such as |
| 1862 | @samp{install-target-@var{dir}}. |
| 1863 | |
| 1864 | @node Target libiberty |
| 1865 | @subsection Target libiberty |
| 1866 | |
| 1867 | The @file{libiberty} subdirectory is currently a special case, in that |
| 1868 | it is the only directory which is built both using the host compiler and |
| 1869 | using the target compiler. |
| 1870 | |
| 1871 | This is because the files in @file{libiberty} are used when building the |
| 1872 | host tools, and they are also incorporated into the @file{libstdc++} |
| 1873 | target library as support code. |
| 1874 | |
| 1875 | This duality does not pose any particular difficulties. It means that |
| 1876 | there are targets for both @samp{all-libiberty} and |
| 1877 | @samp{all-target-libiberty}. |
| 1878 | |
| 1879 | In a native configuration, when target libraries are not built in a |
| 1880 | subdirectory, the same objects are normally used as both the host build |
| 1881 | and the target build. This is normally OK, since libiberty contains |
| 1882 | only C code, and in a native configuration the results of the host |
| 1883 | compiler and the target compiler are normally interoperable. |
| 1884 | |
| 1885 | Irix 6 is again an exception here, since the SGI native compiler |
| 1886 | defaults to using the @samp{O32} ABI, and gcc defaults to using the |
| 1887 | @samp{N32} ABI. On Irix 6, the target libraries are built in a |
| 1888 | subdirectory even for a native configuration, avoiding this problem. |
| 1889 | |
| 1890 | There are currently no other libraries built for both the host and the |
| 1891 | target, but there is no conceptual problem with adding more. |
| 1892 | |
| 1893 | @node Canadian Cross |
| 1894 | @chapter Canadian Cross |
| 1895 | @cindex canadian cross |
| 1896 | @cindex building with a cross compiler |
| 1897 | @cindex cross compiler, building with |
| 1898 | |
| 1899 | It is possible to use the GNU configure and build system to build a |
| 1900 | program which will run on a system which is different from the system on |
| 1901 | which the tools are built. In other words, it is possible to build |
| 1902 | programs using a cross compiler. |
| 1903 | |
| 1904 | This is referred to as a @dfn{Canadian Cross}. |
| 1905 | |
| 1906 | @menu |
| 1907 | * Canadian Cross Example:: Canadian Cross Example. |
| 1908 | * Canadian Cross Concepts:: Canadian Cross Concepts. |
| 1909 | * Build Cross Host Tools:: Build Cross Host Tools. |
| 1910 | * Build and Host Options:: Build and Host Options. |
| 1911 | * CCross not in Cygnus Tree:: Canadian Cross not in Cygnus Tree. |
| 1912 | * CCross in Cygnus Tree:: Canadian Cross in Cygnus Tree. |
| 1913 | * Supporting Canadian Cross:: Supporting Canadian Cross. |
| 1914 | @end menu |
| 1915 | |
| 1916 | @node Canadian Cross Example |
| 1917 | @section Canadian Cross Example |
| 1918 | |
| 1919 | Here is an example of a Canadian Cross. |
| 1920 | |
| 1921 | While running on a GNU/Linux, you can build a program which will run on |
| 1922 | a Solaris system. You would use a GNU/Linux cross Solaris compiler to |
| 1923 | build the program. |
| 1924 | |
| 1925 | Of course, you could not run the resulting program on your GNU/Linux |
| 1926 | system. You would have to copy it over to a Solaris system before you |
| 1927 | would run it. |
| 1928 | |
| 1929 | Of course, you could also simply build the programs on the Solaris |
| 1930 | system in the first place. However, perhaps the Solaris system is not |
| 1931 | available for some reason; perhaps you actually don't have one, but you |
| 1932 | want to build the tools for somebody else to use. Or perhaps your |
| 1933 | GNU/Linux system is much faster than your Solaris system. |
| 1934 | |
| 1935 | A Canadian Cross build is most frequently used when building programs to |
| 1936 | run on a non-Unix system, such as DOS or Windows. It may be simpler to |
| 1937 | configure and build on a Unix system than to support the configuration |
| 1938 | machinery on a non-Unix system. |
| 1939 | |
| 1940 | @node Canadian Cross Concepts |
| 1941 | @section Canadian Cross Concepts |
| 1942 | |
| 1943 | When building a Canadian Cross, there are at least two different systems |
| 1944 | involved: the system on which the tools are being built, and the system |
| 1945 | on which the tools will run. |
| 1946 | |
| 1947 | The system on which the tools are being built is called the @dfn{build} |
| 1948 | system. |
| 1949 | |
| 1950 | The system on which the tools will run is called the host system. |
| 1951 | |
| 1952 | For example, if you are building a Solaris program on a GNU/Linux |
| 1953 | system, as in the previous section, the build system would be GNU/Linux, |
| 1954 | and the host system would be Solaris. |
| 1955 | |
| 1956 | It is, of course, possible to build a cross compiler using a Canadian |
| 1957 | Cross (i.e., build a cross compiler using a cross compiler). In this |
| 1958 | case, the system for which the resulting cross compiler generates code |
| 1959 | is called the target system. (For a more complete discussion of host |
| 1960 | and target systems, @pxref{Host and Target}). |
| 1961 | |
| 1962 | An example of building a cross compiler using a Canadian Cross would be |
| 1963 | building a Windows cross MIPS ELF compiler on a GNU/Linux system. In |
| 1964 | this case the build system would be GNU/Linux, the host system would be |
| 1965 | Windows, and the target system would be MIPS ELF. |
| 1966 | |
| 1967 | The name Canadian Cross comes from the case when the build, host, and |
| 1968 | target systems are all different. At the time that these issues were |
| 1969 | all being hashed out, Canada had three national political parties. |
| 1970 | |
| 1971 | @node Build Cross Host Tools |
| 1972 | @section Build Cross Host Tools |
| 1973 | |
| 1974 | In order to configure a program for a Canadian Cross build, you must |
| 1975 | first build and install the set of cross tools you will use to build the |
| 1976 | program. |
| 1977 | |
| 1978 | These tools will be build cross host tools. That is, they will run on |
| 1979 | the build system, and will produce code that runs on the host system. |
| 1980 | |
| 1981 | It is easy to confuse the meaning of build and host here. Always |
| 1982 | remember that the build system is where you are doing the build, and the |
| 1983 | host system is where the resulting program will run. Therefore, you |
| 1984 | need a build cross host compiler. |
| 1985 | |
| 1986 | In general, you must have a complete cross environment in order to do |
| 1987 | the build. This normally means a cross compiler, cross assembler, and |
| 1988 | so forth, as well as libraries and include files for the host system. |
| 1989 | |
| 1990 | @node Build and Host Options |
| 1991 | @section Build and Host Options |
| 1992 | @cindex configuring a canadian cross |
| 1993 | @cindex canadian cross, configuring |
| 1994 | |
| 1995 | When you run @file{configure}, you must use both the @samp{--build} and |
| 1996 | @samp{--host} options. |
| 1997 | |
| 1998 | @cindex @samp{--build} option |
| 1999 | @cindex build option |
| 2000 | @cindex configure build system |
| 2001 | The @samp{--build} option is used to specify the configuration name of |
| 2002 | the build system. This can normally be the result of running the |
| 2003 | @file{config.guess} shell script, and it is reasonable to use |
| 2004 | @samp{--build=`config.guess`}. |
| 2005 | |
| 2006 | @cindex @samp{--host} option |
| 2007 | @cindex host option |
| 2008 | @cindex configure host |
| 2009 | The @samp{--host} option is used to specify the configuration name of |
| 2010 | the host system. |
| 2011 | |
| 2012 | As we explained earlier, @file{config.guess} is used to set the default |
| 2013 | value for the @samp{--host} option (@pxref{Using the Host Type}). We |
| 2014 | can now see that since @file{config.guess} returns the type of system on |
| 2015 | which it is run, it really identifies the build system. Since the host |
| 2016 | system is normally the same as the build system (i.e., people do not |
| 2017 | normally build using a cross compiler), it is reasonable to use the |
| 2018 | result of @file{config.guess} as the default for the host system when |
| 2019 | the @samp{--host} option is not used. |
| 2020 | |
| 2021 | It might seem that if the @samp{--host} option were used without the |
| 2022 | @samp{--build} option that the configure script could run |
| 2023 | @file{config.guess} to determine the build system, and presume a |
| 2024 | Canadian Cross if the result of @file{config.guess} differed from the |
| 2025 | @samp{--host} option. However, for historical reasons, some configure |
| 2026 | scripts are routinely run using an explicit @samp{--host} option, rather |
| 2027 | than using the default from @file{config.guess}. As noted earlier, it |
| 2028 | is difficult or impossible to reliably compare configuration names |
| 2029 | (@pxref{Using the Target Type}). Therefore, by convention, if the |
| 2030 | @samp{--host} option is used, but the @samp{--build} option is not used, |
| 2031 | then the build system defaults to the host system. |
| 2032 | |
| 2033 | @node CCross not in Cygnus Tree |
| 2034 | @section Canadian Cross not in Cygnus Tree. |
| 2035 | |
| 2036 | If you are not using the Cygnus tree, you must explicitly specify the |
| 2037 | cross tools which you want to use to build the program. This is done by |
| 2038 | setting environment variables before running the @file{configure} |
| 2039 | script. |
| 2040 | |
| 2041 | You must normally set at least the environment variables @samp{CC}, |
| 2042 | @samp{AR}, and @samp{RANLIB} to the cross tools which you want to use to |
| 2043 | build. |
| 2044 | |
| 2045 | For some programs, you must set additional cross tools as well, such as |
| 2046 | @samp{AS}, @samp{LD}, or @samp{NM}. |
| 2047 | |
| 2048 | You would set these environment variables to the build cross tools which |
| 2049 | you are going to use. |
| 2050 | |
| 2051 | For example, if you are building a Solaris program on a GNU/Linux |
| 2052 | system, and your GNU/Linux cross Solaris compiler were named |
| 2053 | @samp{solaris-gcc}, then you would set the environment variable |
| 2054 | @samp{CC} to @samp{solaris-gcc}. |
| 2055 | |
| 2056 | @node CCross in Cygnus Tree |
| 2057 | @section Canadian Cross in Cygnus Tree |
| 2058 | @cindex canadian cross in cygnus tree |
| 2059 | |
| 2060 | This section describes configuring and building a Canadian Cross when |
| 2061 | using the Cygnus tree. |
| 2062 | |
| 2063 | @menu |
| 2064 | * Standard Cygnus CCross:: Building a Normal Program. |
| 2065 | * Cross Cygnus CCross:: Building a Cross Program. |
| 2066 | @end menu |
| 2067 | |
| 2068 | @node Standard Cygnus CCross |
| 2069 | @subsection Building a Normal Program |
| 2070 | |
| 2071 | When configuring a Canadian Cross in the Cygnus tree, all the |
| 2072 | appropriate environment variables are automatically set to |
| 2073 | @samp{@var{host}-@var{tool}}, where @var{host} is the value used for the |
| 2074 | @samp{--host} option, and @var{tool} is the name of the tool (e.g., |
| 2075 | @samp{gcc}, @samp{as}, etc.). These tools must be on your @samp{PATH}. |
| 2076 | |
| 2077 | Adding a prefix of @var{host} will give the usual name for the build |
| 2078 | cross host tools. To see this, consider that when these cross tools |
| 2079 | were built, they were configured to run on the build system and to |
| 2080 | produce code for the host system. That is, they were configured with a |
| 2081 | @samp{--target} option that is the same as the system which we are now |
| 2082 | calling the host. Recall that the default name for installed cross |
| 2083 | tools uses the target system as a prefix (@pxref{Using the Target |
| 2084 | Type}). Since that is the system which we are now calling the host, |
| 2085 | @var{host} is the right prefix to use. |
| 2086 | |
| 2087 | For example, if you configure with @samp{--build=i386-linux-gnu} and |
| 2088 | @samp{--host=solaris}, then the Cygnus tree will automatically default |
| 2089 | to using the compiler @samp{solaris-gcc}. You must have previously |
| 2090 | built and installed this compiler, probably by doing a build with no |
| 2091 | @samp{--host} option and with a @samp{--target} option of |
| 2092 | @samp{solaris}. |
| 2093 | |
| 2094 | @node Cross Cygnus CCross |
| 2095 | @subsection Building a Cross Program |
| 2096 | |
| 2097 | There are additional considerations if you want to build a cross |
| 2098 | compiler, rather than a native compiler, in the Cygnus tree using a |
| 2099 | Canadian Cross. |
| 2100 | |
| 2101 | When you build a cross compiler using the Cygnus tree, then the target |
| 2102 | libraries will normally be built with the newly built target compiler |
| 2103 | (@pxref{Host and Target Libraries}). However, this will not work when |
| 2104 | building with a Canadian Cross. This is because the newly built target |
| 2105 | compiler will be a program which runs on the host system, and therefore |
| 2106 | will not be able to run on the build system. |
| 2107 | |
| 2108 | Therefore, when building a cross compiler with the Cygnus tree, you must |
| 2109 | first install a set of build cross target tools. These tools will be |
| 2110 | used when building the target libraries. |
| 2111 | |
| 2112 | Note that this is not a requirement of a Canadian Cross in general. For |
| 2113 | example, it would be possible to build just the host cross target tools |
| 2114 | on the build system, to copy the tools to the host system, and to build |
| 2115 | the target libraries on the host system. The requirement for build |
| 2116 | cross target tools is imposed by the Cygnus tree, which expects to be |
| 2117 | able to build both host programs and target libraries in a single |
| 2118 | @samp{configure}/@samp{make} step. Because it builds these in a single |
| 2119 | step, it expects to be able to build the target libraries on the build |
| 2120 | system, which means that it must use a build cross target toolchain. |
| 2121 | |
| 2122 | For example, suppose you want to build a Windows cross MIPS ELF compiler |
| 2123 | on a GNU/Linux system. You must have previously installed both a |
| 2124 | GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF |
| 2125 | compiler. |
| 2126 | |
| 2127 | In order to build the Windows (configuration name @samp{i386-cygwin32}) |
| 2128 | cross MIPS ELF (configure name @samp{mips-elf}) compiler, you might |
| 2129 | execute the following commands (long command lines are broken across |
| 2130 | lines with a trailing backslash as a continuation character). |
| 2131 | |
| 2132 | @example |
| 2133 | mkdir linux-x-cygwin32 |
| 2134 | cd linux-x-cygwin32 |
| 2135 | @var{srcdir}/configure --target i386-cygwin32 --prefix=@var{installdir} \ |
| 2136 | --exec-prefix=@var{installdir}/H-i386-linux |
| 2137 | make |
| 2138 | make install |
| 2139 | cd .. |
| 2140 | mkdir linux-x-mips-elf |
| 2141 | cd linux-x-mips-elf |
| 2142 | @var{srcdir}/configure --target mips-elf --prefix=@var{installdir} \ |
| 2143 | --exec-prefix=@var{installdir}/H-i386-linux |
| 2144 | make |
| 2145 | make install |
| 2146 | cd .. |
| 2147 | mkdir cygwin32-x-mips-elf |
| 2148 | cd cygwin32-x-mips-elf |
| 2149 | @var{srcdir}/configure --build=i386-linux-gnu --host=i386-cygwin32 \ |
| 2150 | --target=mips-elf --prefix=@var{wininstalldir} \ |
| 2151 | --exec-prefix=@var{wininstalldir}/H-i386-cygwin32 |
| 2152 | make |
| 2153 | make install |
| 2154 | @end example |
| 2155 | |
| 2156 | You would then copy the contents of @var{wininstalldir} over to the |
| 2157 | Windows machine, and run the resulting programs. |
| 2158 | |
| 2159 | @node Supporting Canadian Cross |
| 2160 | @section Supporting Canadian Cross |
| 2161 | |
| 2162 | If you want to make it possible to build a program you are developing |
| 2163 | using a Canadian Cross, you must take some care when writing your |
| 2164 | configure and make rules. Simple cases will normally work correctly. |
| 2165 | However, it is not hard to write configure and make tests which will |
| 2166 | fail in a Canadian Cross. |
| 2167 | |
| 2168 | @menu |
| 2169 | * CCross in Configure:: Supporting Canadian Cross in Configure Scripts. |
| 2170 | * CCross in Make:: Supporting Canadian Cross in Makefiles. |
| 2171 | @end menu |
| 2172 | |
| 2173 | @node CCross in Configure |
| 2174 | @subsection Supporting Canadian Cross in Configure Scripts |
| 2175 | @cindex canadian cross in configure |
| 2176 | |
| 2177 | In a @file{configure.in} file, after calling @samp{AC_PROG_CC}, you can |
| 2178 | find out whether this is a Canadian Cross configure by examining the |
| 2179 | shell variable @samp{cross_compiling}. In a Canadian Cross, which means |
| 2180 | that the compiler is a cross compiler, @samp{cross_compiling} will be |
| 2181 | @samp{yes}. In a normal configuration, @samp{cross_compiling} will be |
| 2182 | @samp{no}. |
| 2183 | |
| 2184 | You ordinarily do not need to know the type of the build system in a |
| 2185 | configure script. However, if you do need that information, you can get |
| 2186 | it by using the macro @samp{AC_CANONICAL_SYSTEM}, the same macro that is |
| 2187 | used to determine the target system. This macro will set the variables |
| 2188 | @samp{build}, @samp{build_alias}, @samp{build_cpu}, @samp{build_vendor}, |
| 2189 | and @samp{build_os}, which correspond to the similar @samp{target} and |
| 2190 | @samp{host} variables, except that they describe the build system. |
| 2191 | |
| 2192 | When writing tests in @file{configure.in}, you must remember that you |
| 2193 | want to test the host environment, not the build environment. |
| 2194 | |
| 2195 | Macros like @samp{AC_CHECK_FUNCS} which use the compiler will test the |
| 2196 | host environment. That is because the tests will be done by running the |
| 2197 | compiler, which is actually a build cross host compiler. If the |
| 2198 | compiler can find the function, that means that the function is present |
| 2199 | in the host environment. |
| 2200 | |
| 2201 | Tests like @samp{test -f /dev/ptyp0}, on the other hand, will test the |
| 2202 | build environment. Remember that the configure script is running on the |
| 2203 | build system, not the host system. If your configure scripts examines |
| 2204 | files, those files will be on the build system. Whatever you determine |
| 2205 | based on those files may or may not be the case on the host system. |
| 2206 | |
| 2207 | Most autoconf macros will work correctly for a Canadian Cross. The main |
| 2208 | exception is @samp{AC_TRY_RUN}. This macro tries to compile and run a |
| 2209 | test program. This will fail in a Canadian Cross, because the program |
| 2210 | will be compiled for the host system, which means that it will not run |
| 2211 | on the build system. |
| 2212 | |
| 2213 | The @samp{AC_TRY_RUN} macro provides an optional argument to tell the |
| 2214 | configure script what to do in a Canadian Cross. If that argument is |
| 2215 | not present, you will get a warning when you run @samp{autoconf}: |
| 2216 | @smallexample |
| 2217 | warning: AC_TRY_RUN called without default to allow cross compiling |
| 2218 | @end smallexample |
| 2219 | @noindent |
| 2220 | This tells you that the resulting @file{configure} script will not work |
| 2221 | with a Canadian Cross. |
| 2222 | |
| 2223 | In some cases while it may better to perform a test at configure time, |
| 2224 | it is also possible to perform the test at run time. In such a case you |
| 2225 | can use the cross compiling argument to @samp{AC_TRY_RUN} to tell your |
| 2226 | program that the test could not be performed at configure time. |
| 2227 | |
| 2228 | There are a few other autoconf macros which will not work correctly with |
| 2229 | a Canadian Cross: a partial list is @samp{AC_FUNC_GETPGRP}, |
| 2230 | @samp{AC_FUNC_SETPGRP}, @samp{AC_FUNC_SETVBUF_REVERSED}, and |
| 2231 | @samp{AC_SYS_RESTARTABLE_SYSCALLS}. The @samp{AC_CHECK_SIZEOF} macro is |
| 2232 | generally not very useful with a Canadian Cross; it permits an optional |
| 2233 | argument indicating the default size, but there is no way to know what |
| 2234 | the correct default should be. |
| 2235 | |
| 2236 | @node CCross in Make |
| 2237 | @subsection Supporting Canadian Cross in Makefiles. |
| 2238 | @cindex canadian cross in makefile |
| 2239 | |
| 2240 | The main Canadian Cross issue in a @file{Makefile} arises when you want |
| 2241 | to use a subsidiary program to generate code or data which you will then |
| 2242 | include in your real program. |
| 2243 | |
| 2244 | If you compile this subsidiary program using @samp{$(CC)} in the usual |
| 2245 | way, you will not be able to run it. This is because @samp{$(CC)} will |
| 2246 | build a program for the host system, but the program is being built on |
| 2247 | the build system. |
| 2248 | |
| 2249 | You must instead use a compiler for the build system, rather than the |
| 2250 | host system. In the Cygnus tree, this make variable |
| 2251 | @samp{$(CC_FOR_BUILD)} will hold a compiler for the build system. |
| 2252 | |
| 2253 | Note that you should not include @file{config.h} in a file you are |
| 2254 | compiling with @samp{$(CC_FOR_BUILD)}. The @file{configure} script will |
| 2255 | build @file{config.h} with information for the host system. However, |
| 2256 | you are compiling the file using a compiler for the build system (a |
| 2257 | native compiler). Subsidiary programs are normally simple filters which |
| 2258 | do no user interaction, and it is normally possible to write them in a |
| 2259 | highly portable fashion so that the absence of @file{config.h} is not |
| 2260 | crucial. |
| 2261 | |
| 2262 | @cindex @samp{HOST_CC} |
| 2263 | The gcc @file{Makefile.in} shows a complex situation in which certain |
| 2264 | files, such as @file{rtl.c}, must be compiled into both subsidiary |
| 2265 | programs run on the build system and into the final program. This |
| 2266 | approach may be of interest for advanced build system hackers. Note |
| 2267 | that the build system compiler is rather confusingly called |
| 2268 | @samp{HOST_CC}. |
| 2269 | |
| 2270 | @node Cygnus Configure |
| 2271 | @chapter Cygnus Configure |
| 2272 | @cindex cygnus configure |
| 2273 | |
| 2274 | The Cygnus configure script predates autoconf. All of its interesting |
| 2275 | features have been incorporated into autoconf. No new programs should |
| 2276 | be written to use the Cygnus configure script. |
| 2277 | |
| 2278 | However, the Cygnus configure script is still used in a few places: at |
| 2279 | the top of the Cygnus tree and in a few target libraries in the Cygnus |
| 2280 | tree. Until those uses have been replaced with autoconf, some brief |
| 2281 | notes are appropriate here. This is not complete documentation, but it |
| 2282 | should be possible to use this as a guide while examining the scripts |
| 2283 | themselves. |
| 2284 | |
| 2285 | @menu |
| 2286 | * Cygnus Configure Basics:: Cygnus Configure Basics. |
| 2287 | * Cygnus Configure in C++ Libraries:: Cygnus Configure in C++ Libraries. |
| 2288 | @end menu |
| 2289 | |
| 2290 | @node Cygnus Configure Basics |
| 2291 | @section Cygnus Configure Basics |
| 2292 | |
| 2293 | Cygnus configure does not use any generated files; there is no program |
| 2294 | corresponding to @samp{autoconf}. Instead, there is a single shell |
| 2295 | script named @samp{configure} which may be found at the top of the |
| 2296 | Cygnus tree. This shell script was written by hand; it was not |
| 2297 | generated by autoconf, and it is incorrect, and indeed harmful, to run |
| 2298 | @samp{autoconf} in the top level of a Cygnus tree. |
| 2299 | |
| 2300 | Cygnus configure works in a particular directory by examining the file |
| 2301 | @file{configure.in} in that directory. That file is broken into four |
| 2302 | separate shell scripts. |
| 2303 | |
| 2304 | The first is the contents of @file{configure.in} up to a line that |
| 2305 | starts with @samp{# per-host:}. This is the common part. |
| 2306 | |
| 2307 | The second is the rest of @file{configure.in} up to a line that starts |
| 2308 | with @samp{# per-target:}. This is the per host part. |
| 2309 | |
| 2310 | The third is the rest of @file{configure.in} up to a line that starts |
| 2311 | with @samp{# post-target:}. This is the per target part. |
| 2312 | |
| 2313 | The fourth is the remainder of @file{configure.in}. This is the post |
| 2314 | target part. |
| 2315 | |
| 2316 | If any of these comment lines are missing, the corresponding shell |
| 2317 | script is empty. |
| 2318 | |
| 2319 | Cygnus configure will first execute the common part. This must set the |
| 2320 | shell variable @samp{srctrigger} to the name of a source file, to |
| 2321 | confirm that Cygnus configure is looking at the right directory. This |
| 2322 | may set the shell variables @samp{package_makefile_frag} and |
| 2323 | @samp{package_makefile_rules_frag}. |
| 2324 | |
| 2325 | Cygnus configure will next set the @samp{build} and @samp{host} shell |
| 2326 | variables, and execute the per host part. This may set the shell |
| 2327 | variable @samp{host_makefile_frag}. |
| 2328 | |
| 2329 | Cygnus configure will next set the @samp{target} variable, and execute |
| 2330 | the per target part. This may set the shell variable |
| 2331 | @samp{target_makefile_frag}. |
| 2332 | |
| 2333 | Any of these scripts may set the @samp{subdirs} shell variable. This |
| 2334 | variable is a list of subdirectories where a @file{Makefile.in} file may |
| 2335 | be found. Cygnus configure will automatically look for a |
| 2336 | @file{Makefile.in} file in the current directory. The @samp{subdirs} |
| 2337 | shell variable is not normally used, and I believe that the only |
| 2338 | directory which uses it at present is @file{newlib}. |
| 2339 | |
| 2340 | For each @file{Makefile.in}, Cygnus configure will automatically create |
| 2341 | a @file{Makefile} by adding definitions for @samp{make} variables such |
| 2342 | as @samp{host} and @samp{target}, and automatically editing the values |
| 2343 | of @samp{make} variables such as @samp{prefix} if they are present. |
| 2344 | |
| 2345 | Also, if any of the @samp{makefile_frag} shell variables are set, Cygnus |
| 2346 | configure will interpret them as file names relative to either the |
| 2347 | working directory or the source directory, and will read the contents of |
| 2348 | the file into the generated @file{Makefile}. The file contents will be |
| 2349 | read in after the first line in @file{Makefile.in} which starts with |
| 2350 | @samp{####}. |
| 2351 | |
| 2352 | These @file{Makefile} fragments are used to customize behaviour for a |
| 2353 | particular host or target. They serve to select particular files to |
| 2354 | compile, and to define particular preprocessor macros by providing |
| 2355 | values for @samp{make} variables which are then used during compilation. |
| 2356 | Cygnus configure, unlike autoconf, normally does not do feature tests, |
| 2357 | and normally requires support to be added manually for each new host. |
| 2358 | |
| 2359 | The @file{Makefile} fragment support is similar to the autoconf |
| 2360 | @samp{AC_SUBST_FILE} macro. |
| 2361 | |
| 2362 | After creating each @file{Makefile}, the post target script will be run |
| 2363 | (i.e., it may be run several times). This script may further customize |
| 2364 | the @file{Makefile}. When it is run, the shell variable @samp{Makefile} |
| 2365 | will hold the name of the @file{Makefile}, including the appropriate |
| 2366 | directory component. |
| 2367 | |
| 2368 | Like an autoconf generated @file{configure} script, Cygnus configure |
| 2369 | will create a file named @file{config.status} which, when run, will |
| 2370 | automatically recreate the configuration. The @file{config.status} file |
| 2371 | will simply execute the Cygnus configure script again with the |
| 2372 | appropriate arguments. |
| 2373 | |
| 2374 | Any of the parts of @file{configure.in} may set the shell variables |
| 2375 | @samp{files} and @samp{links}. Cygnus configure will set up symlinks |
| 2376 | from the names in @samp{links} to the files named in @samp{files}. This |
| 2377 | is similar to the autoconf @samp{AC_LINK_FILES} macro. |
| 2378 | |
| 2379 | Finally, any of the parts of @file{configure.in} may set the shell |
| 2380 | variable @samp{configdirs} to a set of subdirectories. If it is set, |
| 2381 | Cygnus configure will recursively run the configure process in each |
| 2382 | subdirectory. If the subdirectory uses Cygnus configure, it will |
| 2383 | contain a @file{configure.in} file but no @file{configure} file, in |
| 2384 | which case Cygnus configure will invoke itself recursively. If the |
| 2385 | subdirectory has a @file{configure} file, Cygnus configure assumes that |
| 2386 | it is an autoconf generated @file{configure} script, and simply invokes |
| 2387 | it directly. |
| 2388 | |
| 2389 | @node Cygnus Configure in C++ Libraries |
| 2390 | @section Cygnus Configure in C++ Libraries |
| 2391 | @cindex @file{libstdc++} configure |
| 2392 | @cindex @file{libio} configure |
| 2393 | @cindex @file{libg++} configure |
| 2394 | |
| 2395 | The C++ library configure system, written by Per Bothner, deserves |
| 2396 | special mention. It uses Cygnus configure, but it does feature testing |
| 2397 | like that done by autoconf generated @file{configure} scripts. This |
| 2398 | approach is used in the libraries @file{libio}, @file{libstdc++}, and |
| 2399 | @file{libg++}. |
| 2400 | |
| 2401 | Most of the @file{Makefile} information is written out by the shell |
| 2402 | script @file{libio/config.shared}. Each @file{configure.in} file sets |
| 2403 | certain shell variables, and then invokes @file{config.shared} to create |
| 2404 | two package @file{Makefile} fragments. These fragments are then |
| 2405 | incorporated into the resulting @file{Makefile} by the Cygnus configure |
| 2406 | script. |
| 2407 | |
| 2408 | The file @file{_G_config.h} is created in the @file{libio} object |
| 2409 | directory by running the shell script @file{libio/gen-params}. This |
| 2410 | shell script uses feature tests to define macros and typedefs in |
| 2411 | @file{_G_config.h}. |
| 2412 | |
| 2413 | @node Multilibs |
| 2414 | @chapter Multilibs |
| 2415 | @cindex multilibs |
| 2416 | |
| 2417 | For some targets gcc may have different processor requirements depending |
| 2418 | upon command line options. An obvious example is the |
| 2419 | @samp{-msoft-float} option supported on several processors. This option |
| 2420 | means that the floating point registers are not available, which means |
| 2421 | that floating point operations must be done by calling an emulation |
| 2422 | subroutine rather than by using machine instructions. |
| 2423 | |
| 2424 | For such options, gcc is often configured to compile target libraries |
| 2425 | twice: once with @samp{-msoft-float} and once without. When gcc |
| 2426 | compiles target libraries more than once, the resulting libraries are |
| 2427 | called @dfn{multilibs}. |
| 2428 | |
| 2429 | Multilibs are not really part of the GNU configure and build system, but |
| 2430 | we discuss them here since they require support in the @file{configure} |
| 2431 | scripts and @file{Makefile}s used for target libraries. |
| 2432 | |
| 2433 | @menu |
| 2434 | * Multilibs in gcc:: Multilibs in gcc. |
| 2435 | * Multilibs in Target Libraries:: Multilibs in Target Libraries. |
| 2436 | @end menu |
| 2437 | |
| 2438 | @node Multilibs in gcc |
| 2439 | @section Multilibs in gcc |
| 2440 | |
| 2441 | In gcc, multilibs are defined by setting the variable |
| 2442 | @samp{MULTILIB_OPTIONS} in the target @file{Makefile} fragment. Several |
| 2443 | other @samp{MULTILIB} variables may also be defined there. @xref{Target |
| 2444 | Fragment, , The Target Makefile Fragment, gcc, Using and Porting GNU |
| 2445 | CC}. |
| 2446 | |
| 2447 | If you have built gcc, you can see what multilibs it uses by running it |
| 2448 | with the @samp{-print-multi-lib} option. The output @samp{.;} means |
| 2449 | that no multilibs are used. In general, the output is a sequence of |
| 2450 | lines, one per multilib. The first part of each line, up to the |
| 2451 | @samp{;}, is the name of the multilib directory. The second part is a |
| 2452 | list of compiler options separated by @samp{@@} characters. |
| 2453 | |
| 2454 | Multilibs are built in a tree of directories. The top of the tree, |
| 2455 | represented by @samp{.} in the list of multilib directories, is the |
| 2456 | default library to use when no special compiler options are used. The |
| 2457 | subdirectories of the tree hold versions of the library to use when |
| 2458 | particular compiler options are used. |
| 2459 | |
| 2460 | @node Multilibs in Target Libraries |
| 2461 | @section Multilibs in Target Libraries |
| 2462 | |
| 2463 | The target libraries in the Cygnus tree are automatically built with |
| 2464 | multilibs. That means that each library is built multiple times. |
| 2465 | |
| 2466 | This default is set in the top level @file{configure.in} file, by adding |
| 2467 | @samp{--enable-multilib} to the list of arguments passed to configure |
| 2468 | when it is run for the target libraries (@pxref{Host and Target |
| 2469 | Libraries}). |
| 2470 | |
| 2471 | Each target library uses the shell script @file{config-ml.in}, written |
| 2472 | by Doug Evans, to prepare to build target libraries. This shell script |
| 2473 | is invoked after the @file{Makefile} has been created by the |
| 2474 | @file{configure} script. If multilibs are not enabled, it does nothing, |
| 2475 | otherwise it modifies the @file{Makefile} to support multilibs. |
| 2476 | |
| 2477 | The @file{config-ml.in} script makes one copy of the @file{Makefile} for |
| 2478 | each multilib in the appropriate subdirectory. When configuring in the |
| 2479 | source directory (which is not recommended), it will build a symlink |
| 2480 | tree of the sources in each subdirectory. |
| 2481 | |
| 2482 | The @file{config-ml.in} script sets several variables in the various |
| 2483 | @file{Makefile}s. The @file{Makefile.in} must have definitions for |
| 2484 | these variables already; @file{config-ml.in} simply changes the existing |
| 2485 | values. The @file{Makefile} should use default values for these |
| 2486 | variables which will do the right thing in the subdirectories. |
| 2487 | |
| 2488 | @table @samp |
| 2489 | @item MULTISRCTOP |
| 2490 | @file{config-ml.in} will set this to a sequence of @samp{../} strings, |
| 2491 | where the number of strings is the number of multilib levels in the |
| 2492 | source tree. The default value should be the empty string. |
| 2493 | @item MULTIBUILDTOP |
| 2494 | @file{config-ml.in} will set this to a sequence of @samp{../} strings, |
| 2495 | where the number of strings is number of multilib levels in the object |
| 2496 | directory. The default value should be the empty string. This will |
| 2497 | differ from @samp{MULTISRCTOP} when configuring in the source tree |
| 2498 | (which is not recommended). |
| 2499 | @item MULTIDIRS |
| 2500 | In the top level @file{Makefile} only, @file{config-ml.in} will set this |
| 2501 | to the list of multilib subdirectories. The default value should be the |
| 2502 | empty string. |
| 2503 | @item MULTISUBDIR |
| 2504 | @file{config-ml.in} will set this to the installed subdirectory name to |
| 2505 | use for this subdirectory, with a leading @samp{/}. The default value |
| 2506 | shold be the empty string. |
| 2507 | @item MULTIDO |
| 2508 | @itemx MULTICLEAN |
| 2509 | In the top level @file{Makefile} only, @file{config-ml.in} will set |
| 2510 | these variables to commands to use when doing a recursive make. These |
| 2511 | variables should both default to the string @samp{true}, so that by |
| 2512 | default nothing happens. |
| 2513 | @end table |
| 2514 | |
| 2515 | All references to the parent of the source directory should use the |
| 2516 | variable @samp{MULTISRCTOP}. Instead of writing @samp{$(srcdir)/..}, |
| 2517 | you must write @samp{$(srcdir)/$(MULTISRCTOP)..}. |
| 2518 | |
| 2519 | Similarly, references to the parent of the object directory should use |
| 2520 | the variable @samp{MULTIBUILDTOP}. |
| 2521 | |
| 2522 | In the installation target, the libraries should be installed in the |
| 2523 | subdirectory @samp{MULTISUBDIR}. Instead of installing |
| 2524 | @samp{$(libdir)/libfoo.a}, install |
| 2525 | @samp{$(libdir)$(MULTISUBDIR)/libfoo.a}. |
| 2526 | |
| 2527 | The @file{config-ml.in} script also modifies the top level |
| 2528 | @file{Makefile} to add @samp{multi-do} and @samp{multi-clean} targets |
| 2529 | which are used when building multilibs. |
| 2530 | |
| 2531 | The default target of the @file{Makefile} should include the following |
| 2532 | command: |
| 2533 | @smallexample |
| 2534 | @@$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do |
| 2535 | @end smallexample |
| 2536 | @noindent |
| 2537 | This assumes that @samp{$(FLAGS_TO_PASS)} is defined as a set of |
| 2538 | variables to pass to a recursive invocation of @samp{make}. This will |
| 2539 | build all the multilibs. Note that the default value of @samp{MULTIDO} |
| 2540 | is @samp{true}, so by default this command will do nothing. It will |
| 2541 | only do something in the top level @file{Makefile} if multilibs were |
| 2542 | enabled. |
| 2543 | |
| 2544 | The @samp{install} target of the @file{Makefile} should include the |
| 2545 | following command: |
| 2546 | @smallexample |
| 2547 | @@$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do |
| 2548 | @end smallexample |
| 2549 | |
| 2550 | In general, any operation, other than clean, which should be performed |
| 2551 | on all the multilibs should use a @samp{$(MULTIDO)} line, setting the |
| 2552 | variable @samp{DO} to the target of each recursive call to @samp{make}. |
| 2553 | |
| 2554 | The @samp{clean} targets (@samp{clean}, @samp{mostlyclean}, etc.) should |
| 2555 | use @samp{$(MULTICLEAN)}. For example, the @samp{clean} target should |
| 2556 | do this: |
| 2557 | @smallexample |
| 2558 | @@$(MULTICLEAN) DO=clean multi-clean |
| 2559 | @end smallexample |
| 2560 | |
| 2561 | @node FAQ |
| 2562 | @chapter Frequently Asked Questions |
| 2563 | |
| 2564 | @table @asis |
| 2565 | @item Which do I run first, @samp{autoconf} or @samp{automake}? |
| 2566 | Except when you first add autoconf or automake support to a package, you |
| 2567 | shouldn't run either by hand. Instead, configure with the |
| 2568 | @samp{--enable-maintainer-mode} option, and let @samp{make} take care of |
| 2569 | it. |
| 2570 | |
| 2571 | @cindex undefined macros |
| 2572 | @item @samp{autoconf} says something about undefined macros. |
| 2573 | This means that you have macros in your @file{configure.in} which are |
| 2574 | not defined by @samp{autoconf}. You may be using an old version of |
| 2575 | @samp{autoconf}; try building and installing a newer one. Make sure the |
| 2576 | newly installled @samp{autoconf} is first on your @samp{PATH}. Also, |
| 2577 | see the next question. |
| 2578 | |
| 2579 | @cindex @samp{CY_GNU_GETTEXT} in @file{configure} |
| 2580 | @cindex @samp{AM_PROG_LIBTOOL} in @file{configure} |
| 2581 | @item My @file{configure} script has stuff like @samp{CY_GNU_GETTEXT} in it. |
| 2582 | This means that you have macros in your @file{configure.in} which should |
| 2583 | be defined in your @file{aclocal.m4} file, but aren't. This usually |
| 2584 | means that @samp{aclocal} was not able to appropriate definitions of the |
| 2585 | macros. Make sure that you have installed all the packages you need. |
| 2586 | In particular, make sure that you have installed libtool (this is where |
| 2587 | @samp{AM_PROG_LIBTOOL} is defined) and gettext (this is where |
| 2588 | @samp{CY_GNU_GETTEXT} is defined, at least in the Cygnus version of |
| 2589 | gettext). |
| 2590 | |
| 2591 | @cindex @file{Makefile}, garbage characters |
| 2592 | @item My @file{Makefile} has @samp{@@} characters in it. |
| 2593 | This may mean that you tried to use an autoconf substitution in your |
| 2594 | @file{Makefile.in} without adding the appropriate @samp{AC_SUBST} call |
| 2595 | to your @file{configure} script. Or it may just mean that you need to |
| 2596 | rebuild @file{Makefile} in your build directory. To rebuild |
| 2597 | @file{Makefile} from @file{Makefile.in}, run the shell script |
| 2598 | @file{config.status} with no arguments. If you need to force |
| 2599 | @file{configure} to run again, first run @samp{config.status --recheck}. |
| 2600 | These runs are normally done automatically by @file{Makefile} targets, |
| 2601 | but if your @file{Makefile} has gotten messed up you'll need to help |
| 2602 | them along. |
| 2603 | |
| 2604 | @cindex @samp{config.status --recheck} |
| 2605 | @item Why do I have to run both @samp{config.status --recheck} and @samp{config.status}? |
| 2606 | Normally, you don't; they will be run automatically by @file{Makefile} |
| 2607 | targets. If you do need to run them, use @samp{config.status --recheck} |
| 2608 | to run the @file{configure} script again with the same arguments as the |
| 2609 | first time you ran it. Use @samp{config.status} (with no arguments) to |
| 2610 | regenerate all files (@file{Makefile}, @file{config.h}, etc.) based on |
| 2611 | the results of the configure script. The two cases are separate because |
| 2612 | it isn't always necessary to regenerate all the files after running |
| 2613 | @samp{config.status --recheck}. The @file{Makefile} targets generated |
| 2614 | by automake will use the environment variables @samp{CONFIG_FILES} and |
| 2615 | @samp{CONFIG_HEADERS} to only regenerate files as they are needed. |
| 2616 | |
| 2617 | @item What is the Cygnus tree? |
| 2618 | The Cygnus tree is used for various packages including gdb, the GNU |
| 2619 | binutils, and egcs. It is also, of course, used for Cygnus releases. |
| 2620 | It is the build system which was developed at Cygnus, using the Cygnus |
| 2621 | configure script. It permits building many different packages with a |
| 2622 | single configure and make. The configure scripts in the tree are being |
| 2623 | converted to autoconf, but the general build structure remains intact. |
| 2624 | |
| 2625 | @item Why do I have to keep rebuilding and reinstalling the tools? |
| 2626 | I know, it's a pain. Unfortunately, there are bugs in the tools |
| 2627 | themselves which need to be fixed, and each time that happens everybody |
| 2628 | who uses the tools need to reinstall new versions of them. I don't know |
| 2629 | if there is going to be a clever fix until the tools stabilize. |
| 2630 | |
| 2631 | @item Why not just have a Cygnus tree @samp{make} target to update the tools? |
| 2632 | The tools unfortunately need to be installed before they can be used. |
| 2633 | That means that they must be built using an appropriate prefix, and it |
| 2634 | seems unwise to assume that every configuration uses an appropriate |
| 2635 | prefix. It might be possible to make them work in place, or it might be |
| 2636 | possible to install them in some subdirectory; so far these approaches |
| 2637 | have not been implemented. |
| 2638 | @end table |
| 2639 | |
| 2640 | @node Index |
| 2641 | @unnumbered Index |
| 2642 | |
| 2643 | @printindex cp |
| 2644 | |
| 2645 | @contents |
| 2646 | @bye |