![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to configure.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / libg++ / etc|
Return to configure.texi CVS log | Up to [Apple XNU] / GNUtools / libg++ / etc |
1.1 ! root 1: \input texinfo @c -*-texinfo-*- ! 2: @setfilename configure.info ! 3: @settitle Cygnus configure ! 4: ! 5: @synindex ky cp ! 6: ! 7: @setchapternewpage odd ! 8: ! 9: @ifinfo ! 10: @format ! 11: START-INFO-DIR-ENTRY ! 12: * configure:: Cygnus configure. ! 13: END-INFO-DIR-ENTRY ! 14: @end format ! 15: @end ifinfo ! 16: ! 17: @ifinfo ! 18: This document describes the Cygnus Support version of @code{configure}. ! 19: ! 20: Copyright (C) 1991, 1992, 1993 Cygnus Support ! 21: Permission is granted to make and distribute verbatim copies of ! 22: this manual provided the copyright notice and this permission notice ! 23: are preserved on all copies. ! 24: ! 25: @ignore ! 26: Permission is granted to process this file through TeX and print the ! 27: results, provided the printed document carries copying permission ! 28: notice identical to this one except for the removal of this paragraph ! 29: (this paragraph not being relevant to the printed manual). ! 30: @end ignore ! 31: ! 32: Permission is granted to copy and distribute modified versions of this ! 33: manual under the conditions for verbatim copying, provided that the entire ! 34: resulting derived work is distributed under the terms of a permission ! 35: notice identical to this one. ! 36: ! 37: Permission is granted to copy and distribute translations of this manual ! 38: into another language, under the above conditions for modified versions, ! 39: except that this permission notice may be stated in a translation approved ! 40: by Cygnus Support. ! 41: @end ifinfo ! 42: ! 43: @smallbook ! 44: @finalout ! 45: @titlepage ! 46: @title Cygnus configure ! 47: @author K. Richard Pixley ! 48: @author Cygnus Support ! 49: @page ! 50: @cindex copyleft ! 51: ! 52: @vskip 0pt plus 1filll ! 53: Edited January, 1993, by Jeffrey Osier, Cygnus Support. ! 54: ! 55: Copyright @copyright{} 1991, 1992, 1993 Cygnus Support ! 56: ! 57: Permission is granted to make and distribute verbatim copies of ! 58: this manual provided the copyright notice and this permission notice ! 59: are preserved on all copies. ! 60: ! 61: Permission is granted to copy and distribute modified versions of this ! 62: manual under the conditions for verbatim copying, provided that the entire ! 63: resulting derived work is distributed under the terms of a permission ! 64: notice identical to this one. ! 65: ! 66: Permission is granted to copy and distribute translations of this manual ! 67: into another language, under the above conditions for modified versions, ! 68: except that this permission notice may be stated in a translation approved ! 69: by Cygnus Support. ! 70: @end titlepage ! 71: ! 72: @c --------------------------------------------------------------------- ! 73: @ifinfo ! 74: @node Top ! 75: @top Cygnus configure ! 76: ! 77: This file documents the configuration system used and distributed by ! 78: Cygnus Support. ! 79: ! 80: @menu ! 81: * What configure does:: What configure does ! 82: * Invoking configure:: Invoking configure---basic usage ! 83: * Using configure:: More than you ever wanted to know ! 84: * Porting:: How to use configure with new programs ! 85: * Variables Index:: ! 86: * Concept Index:: ! 87: @end menu ! 88: @end ifinfo ! 89: ! 90: @c --------------------------------------------------------------------- ! 91: @node What configure does ! 92: @chapter What @code{configure} does ! 93: @cindex Introduction ! 94: @cindex Overview ! 95: @cindex What @code{configure} does ! 96: @kindex Cygnus Support Developer's Kit ! 97: ! 98: This manual documents Cygnus @code{configure}, a program which helps to ! 99: automate much of the setup activity associated with building large suites of ! 100: programs, such the Cygnus Support Developer's Kit. This manual is therefore ! 101: geared toward readers who are likely to face the problem of configuring ! 102: software in source form before compiling and installing it. We assume you are ! 103: an experienced programmer or system administrator. ! 104: @ifinfo ! 105: For further background on this topic, see @ref{Some Basic Terms, , Apologia ! 106: Configure, cfg-paper, On Configuring Development Tools}, by K. Richard ! 107: Pixley. ! 108: @end ifinfo ! 109: @iftex ! 110: For further background on this topic, see @cite{On Configuring Development ! 111: Tools} by K. Richard Pixley. ! 112: @end iftex ! 113: ! 114: When @code{configure} runs, it does the following things: ! 115: ! 116: @table @emph ! 117: @item @bullet{} creates build directories ! 118: @vindex srcdir ! 119: @cindex @code{srcdir} ! 120: @cindex Build directories ! 121: When you run @code{configure} with the @samp{--srcdir} option, it uses the ! 122: current directory as the @dfn{build directory}, creating under it a directory ! 123: tree that parallels the directory structure of the source directory. If you ! 124: don't specify a @samp{srcdir}, @code{configure} first assumes that the source ! 125: code you wish to configure is in your current directory; if it finds no ! 126: @file{configure.in} input file there, it searches in the directory ! 127: @code{configure} itself lies in. (For details, see @ref{Build directories, , ! 128: Build directories}.) ! 129: ! 130: @item @bullet{} generates @file{Makefile} ! 131: @cindex @code{Makefile} generation ! 132: A @file{Makefile} template from the source directory, usually called ! 133: @file{Makefile.in}, is copied to an output file in the build directory which is ! 134: most often named @file{Makefile}. @code{configure} places definitions for a ! 135: number of standard @file{Makefile} macros at the beginning of the output file. ! 136: If @w{@samp{--prefix=@var{dir}}} or @w{@samp{--exec_prefix=@var{dir}}} are ! 137: specified on the @code{configure} command line, corresponding @file{Makefile} ! 138: variables are set accordingly. If host, target, or site-specific ! 139: @file{Makefile} fragments exist, these are inserted into the output file. (For ! 140: details, see @ref{Makefile generation, , @code{Makefile} generation}.) ! 141: ! 142: @item @bullet{} generates @file{.gdbinit} ! 143: @cindex @code{.gdbinit} ! 144: If the source directory contains a @file{.gdbinit} file and the build directory ! 145: is not the same as the source directory, a @file{.gdbinit} file is created in ! 146: the build directory. This @file{.gdbinit} file contains commands which allow ! 147: the source directory to be read when debugging with the @sc{gnu} debugger, ! 148: @code{gdb}. (@xref{Command Files, , Command Files, gdb, Debugging With GDB}.) ! 149: ! 150: @item @bullet{} makes symbolic links ! 151: @cindex Symbolic links ! 152: Most build directories require that some symbolic links with generic names are ! 153: built pointing to specific files in the source directory. If the system where ! 154: @code{configure} runs cannot support symbolic links, hard links are used ! 155: instead. (For details, see @ref{configure.in, , The @code{configure.in} input ! 156: file}.) ! 157: ! 158: @item @bullet{} generates @file{config.status} ! 159: @cindex @code{config.status} ! 160: @code{configure} creates a shell script named @file{config.status} in the build ! 161: directory. This shell script, when run from the build directory (usually from ! 162: within a @file{Makefile}), will reconfigure the build directory (but not its ! 163: subdirectories). This is most often used to have a @file{Makefile} update ! 164: itself automatically if a new source directory is available. ! 165: ! 166: @item @bullet{} calls itself recursively ! 167: @cindex Recursion ! 168: If the source directory has subdirectories that should also be configured, ! 169: @code{configure} is called for each. ! 170: @end table ! 171: ! 172: @c --------------------------------------------------------------------- ! 173: @node Invoking configure ! 174: @chapter Invoking @code{configure} ! 175: @cindex Invoking @code{configure} ! 176: @cindex Usage ! 177: ! 178: Cygnus @code{configure} is a shell script which resides in a source tree. The ! 179: usual way to invoke @code{configure} is from the shell, as follows: ! 180: ! 181: @cindex Example session ! 182: @example ! 183: eg$ ./configure @var{hosttype} ! 184: @end example ! 185: ! 186: @noindent ! 187: This prepares the source in the current directory (@file{.}) to be ! 188: compiled for a @var{hosttype} environment. It assumes that you wish to ! 189: build programs and files in the default @dfn{build directory} (also the ! 190: current directory, @file{.}). If you do not specify a value for ! 191: @var{hosttype}, Cygnus @code{configure} will attempt to discover this ! 192: information by itself (@pxref{config.guess, , Determining system ! 193: information}). For information on @var{hosttype} environments, ! 194: @xref{Host, , Host}. ! 195: ! 196: All @sc{gnu} software is packaged with one or more @code{configure} script(s) ! 197: (@pxref{Configuration, , How Configuration Should Work, standards, GNU Coding ! 198: Standards}). By using @code{configure} you prepare the source for your ! 199: specific environment by selecting and using @file{Makefile} fragments and ! 200: fragments of shell scripts, which are prepared in advance and stored with the ! 201: source. ! 202: ! 203: @code{configure}'s command-line options also allow you to specify other aspects ! 204: of the source configuration: ! 205: ! 206: @smallexample ! 207: configure @var{hosttype} [--target=@var{target}] [--srcdir=@var{dir}] [--rm] ! 208: [--site=@var{site}] [--prefix=@var{dir}] [--exec-prefix=@var{dir}] ! 209: [--program-prefix=@var{string}] [--tmpdir=@var{dir}] ! 210: [--with-@var{package}[=@var{yes/no}]] [--norecursion] ! 211: [--nfp] [-s] [-v] [-V | --version] [--help] ! 212: @end smallexample ! 213: ! 214: @table @code ! 215: @item --target=@var{target} ! 216: @cindex @code{--target} ! 217: @cindex @code{target} option ! 218: @vindex target ! 219: Requests that the sources be configured to target the @var{target} machine. If ! 220: no target is specified explicitly, the target is assumed to be the same as the ! 221: host (i.e., a @dfn{native} configuration). @xref{Host, , Host}, and ! 222: @ref{Target, , Target}, for ! 223: discussions of each. ! 224: ! 225: @item --srcdir=@var{dir} ! 226: @cindex @code{--srcdir} ! 227: @cindex @code{srcdir} option ! 228: @vindex srcdir ! 229: Direct each generated @file{Makefile} to use the sources located in directory ! 230: @var{dir}. Use this option whenever you wish the object code to reside in a ! 231: different place from the source code. The @dfn{build directory} is always ! 232: assumed to be the directory you call @code{configure} from. See @ref{Build ! 233: directories, , Build directories}, for an example. If the source directory is ! 234: not specified, @code{configure} assumes that the source is in your current ! 235: directory. If @code{configure} finds no @file{configure.in} there, it searches ! 236: in the same directory that the @code{configure} script itself lies in. ! 237: Pathnames specified (Values for @var{dir}) can be either absolute relative to ! 238: the @emph{build} directory. ! 239: ! 240: @item --rm ! 241: @cindex @code{--rm} ! 242: @cindex @code{rm} option ! 243: @vindex rm ! 244: @emph{Remove} the configuration specified by @var{hosttype} and the other ! 245: command-line options, rather than create it. ! 246: ! 247: @c FIXME: check @ref ! 248: @quotation ! 249: @emph{Note:} We recommend that you use @samp{make distclean} rather than ! 250: use this option; see @ref{Invoking make,,Invoking @code{make},make,GNU ! 251: Make}, for details on @samp{make distclean}. ! 252: @end quotation ! 253: ! 254: @item --site=@var{site} ! 255: @cindex @code{--site} ! 256: @cindex @code{site} option ! 257: @vindex site ! 258: Generate the @file{Makefile} using site-specific @file{Makefile} fragments for ! 259: @var{site}. @xref{Makefile fragments, , Adding information about local ! 260: conventions}. ! 261: ! 262: @item --prefix=@var{dir} ! 263: @cindex @code{--prefix} ! 264: @cindex @code{prefix} option ! 265: @vindex prefix ! 266: Configure the source to install programs and files under directory @var{dir}. ! 267: ! 268: This option sets the variable @samp{prefix}. Each generated @file{Makefile} ! 269: will have its @samp{prefix} variables set to this value. (@xref{What configure ! 270: really does, , What @code{configure} really does}.) ! 271: ! 272: @item --exec-prefix=@var{dir} ! 273: @cindex @code{--exec-prefix} ! 274: @cindex @code{exec-prefix} option ! 275: @vindex exec-prefix ! 276: Configure the source to install @dfn{host dependent} files in @var{dir}. ! 277: ! 278: This option sets the variable @samp{exec_prefix}. Each generated ! 279: @file{Makefile} will have its @samp{exec_prefix} variables set to this value. ! 280: (@xref{What configure really does, , What @code{configure} really does}.) ! 281: ! 282: @item --program-prefix=@var{string} ! 283: @cindex @code{--program-prefix} ! 284: @cindex @code{program-prefix} option ! 285: @vindex program-prefix ! 286: Configure the source to install certain programs using @var{string} as a ! 287: prefix. This applies to programs which might be used for cross-compilation, ! 288: such as the compiler and the binary utilities, and also to programs which have ! 289: the same names as common Unix programs, such as @code{make}. ! 290: ! 291: This option sets the variable @samp{program_prefix}. Each generated ! 292: @file{Makefile} will have its @samp{program_prefix} variables set to this ! 293: value. (@xref{What configure really does, , What @code{configure} really ! 294: does}.) ! 295: ! 296: @item --tmpdir=@var{tmpdir} ! 297: @cindex @code{--tmpdir} ! 298: @cindex @code{tmpdir} option ! 299: @vindex tmpdir ! 300: Use the directory @var{tmpdir} for @code{configure}'s temporary files. The ! 301: default is the value of the environment variable @w{@code{TMPDIR}}, or ! 302: @file{/tmp} if the environment variable is not set. ! 303: ! 304: @item --with-@var{package}[=@var{yes/no}] ! 305: @cindex @code{--with-@var{package}} ! 306: @cindex @code{with-@var{package}} option ! 307: @vindex with-@var{package} ! 308: Indicate that @var{package} is present, or not present, depending on ! 309: @var{yes/no}. If @var{yes/no} is nonexistent, its value is assumed to ! 310: be @code{yes}. ! 311: ! 312: For example, if you wish to configure the program @code{gcc} for a Sun ! 313: SPARCstation running SunOS 4.x, and you want @code{gcc} to use the ! 314: @sc{gnu} linker @code{ld}, you can configure @code{gcc} using ! 315: ! 316: @cindex Example session ! 317: @smallexample ! 318: eg$ configure --with-gnu-ld sun4 ! 319: @end smallexample ! 320: ! 321: @noindent ! 322: @xref{What configure really does, , What @code{configure} really does}, for ! 323: details. See the installation or release notes for your particular package for ! 324: details on which other @var{package} options are recognized. ! 325: @c FIXME - need to include info about --with-* in other dox! ! 326: ! 327: @item --norecursion ! 328: @cindex @code{--norecursion} ! 329: @cindex @code{norecursion} option ! 330: @vindex norecursion ! 331: Configure only this directory; ignore any subdirectories. This is used by the ! 332: executable shell script @file{config.status} to reconfigure only the current ! 333: directory; it is most often used non-interactively, when @code{make} is ! 334: invoked. (@xref{config.status, , @code{config.status}}.) ! 335: ! 336: @item --nfp ! 337: @cindex @code{--nfp} ! 338: @cindex @code{nfp} option ! 339: @vindex nfp ! 340: Assume that the intended @var{hosttype} has no floating point unit. ! 341: ! 342: @item -s ! 343: @cindex @code{-s} ! 344: @cindex @code{s} option ! 345: Suppress status output. This option is used internally by ! 346: @code{configure} when calling itself recursively in subdirectories. You ! 347: can override this option with the @code{--verbose} option. ! 348: ! 349: @item -v ! 350: @itemx --verbose ! 351: @cindex @code{-v} ! 352: @cindex @code{--verbose} ! 353: @cindex @code{v} option ! 354: @cindex @code{verbose} option ! 355: @cindex Verbose Output ! 356: @vindex verbose ! 357: Print status lines for each directory configured. Normally, only the ! 358: status lines for the initial working directory are printed. ! 359: ! 360: @item --version ! 361: @itemx -V ! 362: @cindex version ! 363: @cindex @code{--version} ! 364: @cindex version ! 365: Print the @code{configure} version number. ! 366: ! 367: @item --help ! 368: @cindex Usage ! 369: @cindex @code{--help} ! 370: @cindex @code{help} option ! 371: Print a short summary of how to invoke @code{configure}. ! 372: @end table ! 373: ! 374: @cindex Abbreviating option names ! 375: @cindex Truncating option names ! 376: @cartouche ! 377: @emph{Note:} You may introduce options with a single dash, @samp{-}, rather ! 378: than two dashes, @samp{--}. However, you may not be able to truncate long ! 379: option names when using a single dash. When using two dashes, options may be ! 380: abbreviated as long as each option can be uniquely identified. For example, ! 381: @smallexample ! 382: eg$ configure --s=/u/me/src @var{hosttype} ! 383: @end smallexample ! 384: @noindent ! 385: is ambiguous, as @w{@samp{--s}} could refer to either @w{@samp{--site}} or ! 386: @w{@samp{--srcdir}}. However, ! 387: @smallexample ! 388: eg$ configure --src=/u/me/src @var{hosttype} ! 389: @end smallexample ! 390: @noindent ! 391: is a valid abbreviation. ! 392: @end cartouche ! 393: ! 394: ! 395: @c ======================================================================== ! 396: @node Using configure ! 397: @chapter Using @code{configure} ! 398: @cindex Using @code{configure} ! 399: @cindex Detailed usage ! 400: @cindex Usage: detailed ! 401: ! 402: @code{configure} prepares source directories for building programs in ! 403: them. ``Configuring'' is the process of preparing software to compile ! 404: correctly on a given @dfn{host}, for a given @dfn{target}. ! 405: ! 406: @code{configure} subsequently writes a configured @file{Makefile} from a ! 407: pre-built template; @code{configure} uses variables that have been set in the ! 408: configuring process to determine the values of some variables in the ! 409: @file{Makefile}. Because of this we will refer to both @code{configure} ! 410: variables and @file{Makefile} variables. This convention allows us to ! 411: determine where the variable should be set initially, in either ! 412: @file{configure.in} or @file{Makefile.in}. ! 413: ! 414: @menu ! 415: * What configure really does:: What configure really does ! 416: * configure.in:: The configure.in input file ! 417: * Install locations:: Where to install things once they are built ! 418: * Host:: Telling configure what will source will be built ! 419: * Target:: Telling configure what the source will target ! 420: * Makefile fragments:: Adding information about local conventions ! 421: * Makefile extensions:: Extensions to the GNU coding standards ! 422: @end menu ! 423: ! 424: @c --------------------------------------------------------------------- ! 425: @node What configure really does ! 426: @section What @code{configure} really does ! 427: @cindex What @code{configure} really does ! 428: @cindex Behind the scenes ! 429: @cindex @code{configure} back end ! 430: @cindex @code{configure} details ! 431: ! 432: Cygnus @code{configure} is a shell script that sets up an environment in ! 433: which your programs will compile correctly for your machine and ! 434: operating system, and will install in proper places. @code{configure} ! 435: accomplishes this task by doing the following: ! 436: ! 437: @itemize @bullet ! 438: @item ! 439: it generates a @file{Makefile} from a custom template called ! 440: @file{Makefile.in} in each relevant source directory; ! 441: ! 442: @item ! 443: it customizes the build process to your specifications; you set certain ! 444: variables for @code{configure}, either on the command line or in the ! 445: file @file{configure.in}, which subsequently sets variables in each ! 446: generated @file{Makefile} to be used by @code{make} when actually ! 447: building the software; ! 448: ! 449: @item ! 450: it creates @dfn{build directories}, places for your code to be compiled ! 451: in before being installed; ! 452: ! 453: @item ! 454: it generates a @file{.gdbinit} in the build directory, if needed, to ! 455: communicate to @code{gdb} where to find the program's source code; ! 456: ! 457: @item ! 458: it generates a shell script called @file{config.status} ! 459: which is used most often by the @file{Makefile} to reconfigure itself; ! 460: ! 461: @item ! 462: it recurses in subdirectories, setting up entire trees so that they build ! 463: correctly; if @code{configure} finds another @code{configure} script ! 464: further down in a given source tree, it knows to use this script and not ! 465: recur. ! 466: @end itemize ! 467: ! 468: For the sake of safety (i.e., in order to prevent broken installations), the ! 469: @sc{gnu} coding standards call for software to be @dfn{configured} in such a ! 470: way that an end user trying to build a given package will be able to do so by ! 471: affecting a finite number of variables. All @sc{gnu} software comes with an ! 472: executable @code{configure} shell script which sets up an environment within a ! 473: build directory which will correctly compile your new package for your host ! 474: (or, alternatively, whatever host you specify to @code{configure}). ! 475: @ifinfo ! 476: For further background on this topic, see @ref{Some Basic Terms, , Apologia ! 477: Configure, cfg-paper, On Configuring Development Tools}, by K. Richard ! 478: Pixley. ! 479: @end ifinfo ! 480: @iftex ! 481: For further background on this topic, see @cite{On Configuring Development ! 482: Tools} by K. Richard Pixley. ! 483: @end iftex ! 484: ! 485: Use @code{configure} to set for the build process: ! 486: ! 487: @itemize @bullet ! 488: @item ! 489: correct values for certain variables; ! 490: ! 491: @item ! 492: which type of host you wish to configure a given package for ! 493: (@pxref{Host, , Host}); ! 494: ! 495: @item ! 496: where you want to install this package (by using @samp{prefix}, ! 497: @samp{exec-prefix} and @samp{program-prefix}; @pxref{Install details, , ! 498: Full descriptions of all installation directories}); ! 499: ! 500: @item ! 501: optionally, which type of machine you wish to @dfn{target} this ! 502: package's output to (@pxref{Target, , Target}); ! 503: ! 504: @item ! 505: which other @sc{gnu} packages are already installed and available to ! 506: this particular build (by using the @samp{--with-@var{package}} option; ! 507: @pxref{Invoking configure, , Invoking @code{configure}}); ! 508: ! 509: @item ! 510: where to place temporary files (by using the @samp{--tmpdir=@var{dir}} ! 511: option; @pxref{Invoking configure, , Invoking @code{configure}}); ! 512: ! 513: @item whether to recur in subdirectories (changeable through the ! 514: @w{@samp{--norecursion}} option; @pxref{Invoking configure, , Invoking ! 515: @code{configure}}). ! 516: @end itemize ! 517: ! 518: @code{configure} uses a few other files to complete its tasks. These are ! 519: discussed in detail where noted. ! 520: ! 521: @table @code ! 522: @cindex Other files ! 523: @item configure.in ! 524: @cindex @code{configure.in} definition ! 525: Input file for @code{configure}. Shell script fragments reside here. ! 526: @xref{configure.in, , The @code{configure.in} input file}. ! 527: ! 528: @item Makefile.in ! 529: @cindex @code{Makefile.in} definition ! 530: Template which @code{configure} uses to build a file called @file{Makefile} in ! 531: the @dfn{build directory}. @xref{Makefile generation, , @code{Makefile} ! 532: generation}. ! 533: ! 534: @item config.sub ! 535: @cindex @code{config.sub} definition ! 536: Shell script used by @code{configure} to expand referents to the ! 537: @var{hosttype} argument into a single specification of the form ! 538: @w{@var{cpu-vendor-os}}. For instance, on the command line you can ! 539: specify ! 540: ! 541: @cindex Example session ! 542: @example ! 543: eg$ ./configure sun4 ! 544: @end example ! 545: ! 546: @noindent ! 547: to configure for a Sun SPARCstation running SunOS 4.x. @code{configure} ! 548: consults @code{config.sub} to find that the three-part specification for this ! 549: is ! 550: ! 551: @example ! 552: sparc-sun-sunos4.1.1 ! 553: @end example ! 554: ! 555: @noindent ! 556: which notes the @var{cpu} as @samp{sparc}, the @var{manufacturer} as @samp{sun} ! 557: (Sun Microsystems), and the @var{os} (operating system) as @samp{sunos4.1.1}, ! 558: the SunOS 4.1.1 release. @xref{configure variables, , Variables available to @code{configure}}. ! 559: ! 560: @item config.guess ! 561: @cindex @code{config.guess} definition ! 562: If you do not put the @var{hosttype} argument on the command line, ! 563: @code{configure} uses the @code{config.guess} shell script to make an ! 564: analysis of your machine (it assumes that you wish to configure your ! 565: software for the type of machine on which you are running). The output ! 566: of @code{config.guess} is a three-part identifier as described above. ! 567: ! 568: @item config.status ! 569: @cindex @code{config.status} definition ! 570: The final step in configuring a directory is to create a shell script, ! 571: @code{config.status}. The main purpose of this file is to allow the ! 572: @file{Makefile} for the current directory to rebuild itself, if ! 573: necessary. @xref{config.status, , @code{config.status}}. ! 574: ! 575: @item config/* ! 576: @cindex @code{config/} subdirectory ! 577: @code{configure} uses three types of @file{Makefile} @dfn{fragments}, which ! 578: reside in the directory @file{@var{srcdir}/config/}. @xref{Makefile fragments, ! 579: , Adding information about local conventions}. ! 580: @end table ! 581: ! 582: @menu ! 583: * Build variables:: Variable-spaghetti made simple ! 584: * Build directories:: Build directories described well ! 585: * Makefile generation:: To build a Makefile ! 586: * config.guess:: Be vewwy quiet, I'm hunting system information ! 587: * config.status:: To rebuild a Makefile ! 588: @end menu ! 589: ! 590: @c --------------------------------------------------------------------- ! 591: @node Build variables ! 592: @subsection Build variables ! 593: @cindex Build variables ! 594: @cindex Cygnus Support Developer's Kit ! 595: @cindex Variables ! 596: ! 597: There are several variables in the build process which you can control through ! 598: build programs such as @code{make}. These include machine definitions, local ! 599: conventions, installation locations, locations for temporary files, etc. This ! 600: data is accessible through certain variables which are configurable in the ! 601: build process; we refer to them as @dfn{build variables}. ! 602: ! 603: For lists of build variables which you can affect by using @code{configure}, ! 604: see @ref{configure variables, , Variables available to @code{configure.in}}, ! 605: and @ref{Install details, , Full descriptions of all installation directories}. ! 606: ! 607: Generally, build variables, which are used by the @file{Makefile} to ! 608: determine various aspects of the build and installation processes, are ! 609: changeable with command-line options to @code{configure}. In most large ! 610: suites of programs, like the Cygnus Support Developer's Kit, the ! 611: individual programs reside in several subdirectories of a single source ! 612: code ``tree''. All of these subdirectories need to be configured with ! 613: information relative to the @dfn{build directory}, which is not known ! 614: until @code{configure} is run. Unless specified otherwise, ! 615: @code{configure} recursively configures every subdirectory in the source ! 616: tree. ! 617: ! 618: Build variables are passed from @code{configure} directly into the ! 619: @file{Makefile}, and use the same names (except that dashes are ! 620: transformed into underbars; for example, when you specify the option ! 621: @samp{--exec-prefix} on the command line, the @file{Makefile} variable ! 622: @samp{exec_prefix} is set). In other words, if you specify ! 623: ! 624: @cindex Example session ! 625: @example ! 626: eg$ ./configure --prefix=/usr/gnu/local @dots{} @var{hosttype} ! 627: @end example ! 628: ! 629: @noindent ! 630: on the command line, @code{configure} sets an variable called @samp{prefix} to ! 631: @samp{/usr/gnu/local}, and passes this into the @file{Makefile} in the same ! 632: manner. After this command, each @file{Makefile} generated by @code{configure} ! 633: will contain a line that reads: ! 634: ! 635: @example ! 636: prefix = /usr/gnu/local ! 637: @end example ! 638: ! 639: For a list of the @file{Makefile} variables @code{configure} can change, and ! 640: instructions on how to change them, see @ref{configure variables, , Variables ! 641: available to @code{configure.in}}, and @ref{Invoking configure, , Invoking ! 642: @code{configure}}. ! 643: ! 644: @c --------------------------------------------------------------------- ! 645: @node Build directories ! 646: @subsection Build directories ! 647: @cindex Build directories ! 648: @cindex Object directories ! 649: @cindex Building for multiple hosts ! 650: @cindex Building for multiple targets ! 651: ! 652: By default, @code{configure} builds a @file{Makefile} and symbolic links in the ! 653: same directory as the source files. This default works for many cases, but it ! 654: has limitations. For instance, using this approach, you can only build object ! 655: code for one host at a time. ! 656: ! 657: We refer to each directory where @code{configure} builds a @file{Makefile} as ! 658: a @dfn{build directory}. ! 659: ! 660: The build directory for any given build is always the directory from which you ! 661: call @code{configure}, or @file{.} relative to your prompt. The default ! 662: @dfn{source directory}, the place @code{configure} looks to find source code, ! 663: is also @file{.}. For instance, if we have a directory @file{/gnu-stuff/src/} ! 664: that is the top branch of a tree of @sc{gnu} source code we wish to configure, ! 665: then the program we will use to configure this code is ! 666: @file{/gnu-stuff/src/configure}, as follows. (Assume for the sake of argument ! 667: that our machine is a sun4.) ! 668: ! 669: @cindex Example session ! 670: @smallexample ! 671: @group ! 672: eg$ cd /gnu-stuff/src ! 673: eg$ ./configure sun4 ! 674: Created "Makefile" in /gnu-stuff/src ! 675: eg$ ! 676: @end group ! 677: @end smallexample ! 678: ! 679: We just configured the code in @file{/gnu-stuff/src} to run on a Sun ! 680: SPARCstation using SunOS 4.x by creating a @file{Makefile} in ! 681: @file{/gnu-stuff/src}. By default, we also specified that when this code is ! 682: built, the object code should reside in the same directory, ! 683: @file{/gnu-stuff/src}. ! 684: ! 685: However, if we wanted to build this code for more than one host, we would be in ! 686: trouble, because the new configuration would write over the old one, destroying ! 687: it in the process. What we can do is to make a new @dfn{build directory} and ! 688: configure from there. Running @code{configure} from the new directory will ! 689: place a correct @file{Makefile} and a @file{config.status} in this new file. ! 690: That is all @code{configure} does; we must run @code{make} to generate any ! 691: object code. ! 692: ! 693: The new @file{Makefile} in @file{/gnu-stuff/sun4-obj}, created from the ! 694: template file @file{/gnu-stuff/src/Makefile.in}, contains all the information ! 695: needed to build the program. ! 696: ! 697: @cindex Example session ! 698: @smallexample ! 699: @group ! 700: eg$ mkdir /gnu-stuff/sun4-obj ! 701: eg$ cd /gnu-stuff/sun4-obj ! 702: eg$ ../src/configure --srcdir=../src sun4 ! 703: Created "Makefile" in /gnu-stuff/sun4-obj ! 704: eg$ ls ! 705: Makefile config.status ! 706: eg$ make all info install install-info clean ! 707: @var{compilation messages@dots{}} ! 708: eg$ mkdir /gnu-stuff/solaris2 ! 709: eg$ cd /gnu-stuff/solaris2 ! 710: eg$ ../src/configure --srcdir=../src sol2 ! 711: Created "Makefile" in /gnu-stuff/solaris2 ! 712: eg$ ls ! 713: Makefile config.status ! 714: eg$ make all info install install-info clean ! 715: @var{compilation messages@dots{}} ! 716: @end group ! 717: @end smallexample ! 718: ! 719: We can repeat this for other configurations of the same software simply ! 720: by making a new build directory and reconfiguring from inside it. If ! 721: you do not specify the @var{hosttype} argument, @code{configure} ! 722: will attempt to figure out what kind of machine and operating system you ! 723: happen to be using. @xref{config.guess, , Determining system ! 724: information}. Of course, this may not always be the configuration you ! 725: wish to build. ! 726: ! 727: @emph{Caution:} If you build more than one configuration for a single program, ! 728: remember that you must also specify a different @samp{--prefix} for each ! 729: configuration at configure-time. Otherwise, both configurations will be ! 730: installed in the same default location (@file{/usr/local}); the configuration ! 731: to be installed last would overwrite previously installed configurations. ! 732: ! 733: @c --------------------------------------------------------------------- ! 734: @node Makefile generation ! 735: @subsection @code{Makefile} generation ! 736: @cindex @code{Makefile} generation ! 737: ! 738: Cygnus @code{configure} creates a file called @file{Makefile} in the build ! 739: directory which can be used with @code{make} to automatically build a given ! 740: program or package. @code{configure} also builds a @file{Makefile} for each ! 741: relevant subdirectory for a given program or package (irrelevant subdirectories ! 742: would be those which contain no code which needs configuring, and which ! 743: therefore have no @code{configure} input file @file{configure.in} and no ! 744: @file{Makefile} template @file{Makefile.in}). @xref{Running, @code{make} ! 745: Invocation, How to Run @code{make}, make, GNU Make}, for details on using ! 746: @code{make} to compile your source code. ! 747: ! 748: Each @file{Makefile} contains variables which have been configured for a ! 749: specific build. These build variables are determined when @code{configure} is ! 750: run. All build variables have defaults. By default, @code{configure} ! 751: generates a @file{Makefile} which specifies: ! 752: ! 753: @cindex Default configuration ! 754: @itemize @bullet ! 755: @item a @dfn{native} build, which is to occur ! 756: ! 757: @item in the current directory, and which will be installed ! 758: ! 759: @item in the default installation directory (@file{/usr/local}) when the code ! 760: is compiled with @code{make}. ! 761: @end itemize ! 762: ! 763: @noindent ! 764: Variables are changeable through command-line options to @code{configure} ! 765: (@pxref{Invoking configure, , Invoking @code{configure}}). ! 766: ! 767: If you are porting a new program and intend to use @code{configure}, see ! 768: @ref{Porting, , Porting with @code{configure}}, as well as @ref{Makefiles, , ! 769: Writing Makefiles, make, GNU Make}, and @ref{Makefiles, , Makefile Conventions, ! 770: standards, GNU Coding Standards}. ! 771: ! 772: @c --------------------------------------------------------------------- ! 773: @node config.guess ! 774: @subsection Determining system information ! 775: @cindex @code{config.guess} ! 776: ! 777: The shell script @code{config.guess} is called when you do not specify a ! 778: @var{hosttype} on the command line to @code{configure}. @code{config.guess} ! 779: acquires available system information from your local machine through the shell ! 780: command @code{uname}. It compares this information to a database and attempts ! 781: to determine a usable three-part system identifier (known as a @dfn{triple}) to ! 782: use as your @var{hosttype}. @xref{What configure really does, , What ! 783: @code{configure} really does}, to see how this information is used. ! 784: ! 785: @emph{Note:} If you do not specify a @var{hosttype} on the command line, ! 786: @code{configure} will attempt to configure your software to run on the machine ! 787: you happen to be using. This may not be the configuration you desire. ! 788: ! 789: @c --------------------------------------------------------------------- ! 790: @node config.status ! 791: @subsection @code{config.status} ! 792: @cindex @code{config.status} ! 793: ! 794: The final step in configuring a directory is to create an executable shell ! 795: script, @file{config.status}. The main purpose of this file is to allow the ! 796: @file{Makefile} for the current directory to rebuild itself, if necessary. It ! 797: is usually run from within the @file{Makefile}. @xref{Makefile extensions, , ! 798: Extensions to the @sc{gnu} coding standards}. ! 799: ! 800: @file{config.status} also contains a record of the @code{configure} session ! 801: which created it. ! 802: ! 803: @c --------------------------------------------------------------------- ! 804: @node configure.in ! 805: @section The @code{configure.in} input file ! 806: @cindex @code{configure.in} ! 807: ! 808: A @file{configure.in} file for Cygnus @code{configure} consists of a ! 809: @dfn{per-invocation} section, followed by a @dfn{per-host} section, followed by ! 810: a @dfn{per-target} section, optionally followed by a @dfn{post-target} section. ! 811: Each section is a shell script fragment, which is executed by the ! 812: @code{configure} shell script at an appropriate time. Values are passed among ! 813: @code{configure} and the shell fragments through a set of shell variables. ! 814: When each section is being interpreted by the shell, the shell's current ! 815: directory is the build directory, and any files created by the section (or ! 816: referred to by the section) will be relative to the build directory. To ! 817: reference files in other places (such as the source directory), prepend a shell ! 818: variable such as @samp{$(srcdir)/} to the desired file name. ! 819: ! 820: @cindex @i{per-invocation} section ! 821: The beginning of the @file{configure.in} file begins the @dfn{per-invocation} ! 822: section. ! 823: ! 824: @cindex @i{per-host} section ! 825: A line beginning with @samp{# per-host:} begins the @dfn{per-host} section. ! 826: ! 827: @cindex @i{per-target} section ! 828: A line beginning with @samp{# per-target:} begins the @dfn{per-target} section. ! 829: ! 830: @cindex @i{post-target} section ! 831: If it exists, the @dfn{post-target} section begins with @samp{# post-target:}. ! 832: ! 833: @menu ! 834: * configure variables:: Variables available to configure.in ! 835: * Minimal:: A minimal configure.in ! 836: * Declarations:: For each invocation ! 837: * per-host:: Host-specific instructions ! 838: * per-target:: Target-specific instructions ! 839: * post-target:: Instructions to be executed after target info ! 840: * Example:: An example configure.in ! 841: @end menu ! 842: ! 843: @c --------------------------------------------------------------------- ! 844: @node configure variables ! 845: @subsection Variables available to @code{configure.in} ! 846: @cindex @file{configure.in} interface ! 847: @cindex configure variables ! 848: ! 849: The following variables pass information between the standard parts of ! 850: @code{configure} and the shell-script fragments in @file{configure.in}: ! 851: ! 852: @table @code ! 853: @item srctrigger ! 854: @cindex @code{srctrigger} ! 855: @vindex srctrigger ! 856: Contains the name of a source file that is expected to live in the source ! 857: directory. You must usually set this in the @dfn{per-invocation} section of ! 858: @file{configure.in}. @code{configure} tests to see that this file exists. If ! 859: the file does not exist, @code{configure} prints an error message. This is ! 860: used as a sanity check that @file{configure.in} matches the source directory. ! 861: ! 862: @item srcname ! 863: @cindex @code{srcname} ! 864: @vindex srcname ! 865: Contains the name of the source collection contained in the source directory. ! 866: You must usually set this in the @dfn{per-invocation} section of ! 867: @file{configure.in}. If the file named in @samp{srctrigger} does not exist, ! 868: @code{configure} uses the value of @samp{srcname} when it prints the error ! 869: message. ! 870: ! 871: @item configdirs ! 872: @cindex @code{configdirs} ! 873: @vindex configdirs ! 874: Contains the names of any subdirectories in which @code{configure} should ! 875: recurse. You must usually set this in the @dfn{per-invocation} section of ! 876: @file{configure.in}. ! 877: If @file{Makefile.in} contains a line starting with @samp{SUBDIRS =}, ! 878: then it will be replaced with an assignment to @samp{SUBDIRS} using ! 879: the value of @samp{configdirs} (if @samp{subdirs} is empty). This can ! 880: be used to determine which directories to configure and build depending ! 881: on the host and target configurations. ! 882: @c Most other matching makefile/config vars use the same name. Why not ! 883: @c this? (FIXME). ! 884: @c Can we get rid of SUBDIRS-substitution? It doesn't work well with subdirs. ! 885: Use @samp{configdirs} (instead of the @samp{subdirs} variable ! 886: described below) if you want to be able to partition the ! 887: subdirectories, or use independent @file{Makefile} fragments. ! 888: Each subdirectory can be independent, and independently reconfigured. ! 889: ! 890: @item subdirs ! 891: @cindex @code{subdirs} ! 892: @vindex subdirs ! 893: Contains the names of any subdirectories where @code{configure} should create a ! 894: @file{Makefile} (in addition to the current directory), @emph{without} ! 895: recursively running @code{configure}. Use @samp{subdirs} (instead of the ! 896: @samp{configdirs} variable described above) if you want to configure all of the ! 897: directories as a unit. Since there is a single invocation of @code{configure} ! 898: that configures many directories, all the directories can use the same ! 899: @file{Makefile} fragments, and the same @code{configure.in}. ! 900: ! 901: @item host ! 902: @cindex @code{host} ! 903: @cindex Canonical ``triple'' ! 904: @vindex host ! 905: Contains the full configuration name for the host (generated by the script ! 906: @file{config.sub} from the name that you entered). This is a three-part ! 907: name (commonly referred to as a @dfn{triple}) of the form ! 908: @var{cpu}-@var{vendor}-@var{os}. ! 909: ! 910: There are separate variables @samp{host_cpu}, @samp{host_vendor}, and ! 911: @samp{host_os} that you can use to test each of the three parts; this variable ! 912: is useful, however, for error messages, and for testing combinations of the ! 913: three components. ! 914: ! 915: @item host_cpu ! 916: @vindex host_cpu ! 917: Contains the first element of the canonical triple representing the host ! 918: as returned by @file{config.sub}. This is occasionally used to ! 919: distinguish between minor variations of a particular vendor's operating ! 920: system and sometimes to determine variations in binary format between ! 921: the host and the target. ! 922: ! 923: @item host_vendor ! 924: @vindex host_vendor ! 925: Contains the second element of the canonical triple representing the host as ! 926: returned by @file{config.sub}. This is usually used to distinguish among the ! 927: numerous variations of @emph{common} operating systems. ! 928: @c "@emph{common} OS" doesn't convey much to me. Is this meant to cover ! 929: @c cases like Unix, widespread but with many variations? ! 930: ! 931: @item host_os ! 932: @vindex host_os ! 933: Contains the the third element of the canonical triple representing the ! 934: host as returned by @file{config.sub}. ! 935: ! 936: @item target ! 937: @cindex @code{target} ! 938: @cindex Canonical ``triple'' ! 939: @vindex target ! 940: Contains the full configuration name (generated by the script @file{config.sub} ! 941: from the name that you entered) for the target. Like the host, this is a ! 942: three-part name of the form @var{cpu}-@var{vendor}-@var{os}. ! 943: ! 944: There are separate variables @samp{target_cpu}, @samp{target_vendor}, and ! 945: @samp{target_os} that you can use to test each of the three parts; this ! 946: variable is useful, however, for error messages, and for testing combinations ! 947: of the three components. ! 948: ! 949: @item target_cpu ! 950: @vindex target_cpu ! 951: Contains the first element of the canonical triple representing the target as ! 952: returned by @file{config.sub}. This variable is used heavily by programs which ! 953: are involved in building other programs, like the compiler, assembler, linker, ! 954: etc. Most programs will not need the @samp{target} variables at all, but this ! 955: one could conceivably be used to build a program, for instance, that operated ! 956: on binary data files whose byte order or alignment differ from the system where ! 957: the program is running. ! 958: ! 959: @item target_vendor ! 960: @vindex target_vendor ! 961: Contains the second element of the canonical triple representing the target as ! 962: returned by @file{config.sub}. This is usually used to distinguish among the ! 963: numerous variations of @emph{common} operating systems or object file ! 964: formats. It is sometimes used to switch between different flavors of user ! 965: interfaces. ! 966: @c above query re "@emph{common} OS" applies here too ! 967: ! 968: @item target_os ! 969: @vindex target_os ! 970: Contains the the third element of the canonical triple representing the ! 971: target as returned by @file{config.sub}. This variable is used by ! 972: development tools to distinguish between subtle variations in object ! 973: file formats that some vendors use across operating system releases. It ! 974: might also be use to decide which libraries to build or what user ! 975: interface the tool should provide. ! 976: ! 977: @item floating_point ! 978: @cindex @code{floating_point} ! 979: @cindex @code{nfp} option ! 980: @vindex floating_point ! 981: Set to @samp{no} if you invoked @code{configure} with the @samp{--nfp} ! 982: command-line option, otherwise it is empty. This is a request to target ! 983: machines with @dfn{no floating point} unit, even if the targets ordinarily have ! 984: floating point units available. ! 985: ! 986: @item gas ! 987: @cindex @code{with-gnu-as} option ! 988: @vindex gas ! 989: Set to @samp{true} if you invoked @code{configure} with the ! 990: @w{@samp{--with-gnu-as}} command line option, otherwise it is empty. This is a ! 991: request to assume that the specified @var{hosttype} machine has @sc{gnu} @code{as} ! 992: available even if it ordinarily does not. ! 993: ! 994: @item srcdir ! 995: @cindex @code{srcdir} ! 996: @vindex srcdir ! 997: Set to the name of the directory containing the source for this program. ! 998: This will be different from @file{.} if you have specified the ! 999: @samp{--srcdir=@var{dir}} option. @samp{srcdir} can indicate either an ! 1000: absolute path or a path relative to the build directory. ! 1001: ! 1002: @item package_makefile_frag ! 1003: @vindex package_makefile_frag ! 1004: If set in @file{configure.in}, this variable should be the name a file relative ! 1005: to @samp{srcdir} to be included in the resulting @file{Makefile}. If the named ! 1006: file does not exist, @code{configure} will print a warning message. This ! 1007: variable is not set by @code{configure}. ! 1008: ! 1009: @item host_makefile_frag ! 1010: @vindex host_makefile_frag ! 1011: If set in @file{configure.in}, this variable should be the name a file relative ! 1012: to @samp{srcdir} to be included in the resulting @file{Makefile}. If the named ! 1013: file does not exist, @code{configure} will print a warning message. This ! 1014: variable is not set by @code{configure}. ! 1015: ! 1016: @item target_makefile_frag ! 1017: @vindex target_makefile_frag ! 1018: If set in @file{configure.in}, this variable should be the name of a file, ! 1019: relative to @samp{srcdir}, to be included in the resulting @file{Makefile}. If ! 1020: the named file does not exist, @code{configure} will print a warning message. ! 1021: This variable is not set by @code{configure}. ! 1022: ! 1023: @item site_makefile_frag ! 1024: @vindex site_makefile_frag ! 1025: Set to a file name representing to the default @file{Makefile} fragment for ! 1026: this host. It may be set in @file{configure.in} to override this default. ! 1027: Normally @samp{site_makefile_frag} is empty, but will have a value if you ! 1028: specify @samp{--site=@var{site}} on the command line. ! 1029: @ignore -- this doesn't fit ! 1030: It is probably not a good idea to override this variable from ! 1031: @file{configure.in}, since that may defeat the @code{configure} user's ! 1032: intentions. ! 1033: @end ignore ! 1034: ! 1035: @item Makefile ! 1036: @vindex Makefile ! 1037: Set to the name of the generated @file{Makefile}. Normally this value is ! 1038: precisely @file{Makefile}, but some programs may want something else. ! 1039: ! 1040: @item removing ! 1041: @cindex @code{rm} option ! 1042: @vindex removing ! 1043: Normally empty but will be set to some non-null value if you specified ! 1044: @samp{--rm} on the command line. That is, if @samp{removing} is not empty, ! 1045: then @code{configure} is @emph{removing} a configuration rather than creating ! 1046: one. ! 1047: ! 1048: @item files ! 1049: @cindex Symbolic links ! 1050: @vindex files ! 1051: If this variable is not empty following the @dfn{per-target} section, ! 1052: then each word in its value will be the target of a symbolic link named ! 1053: in the corresponding word from the @samp{links} variable. ! 1054: ! 1055: @item links ! 1056: @cindex Symbolic links ! 1057: @vindex links ! 1058: If the @samp{files} variable is not empty following the @dfn{per-target} ! 1059: section, then @code{configure} creates symbolic links with the first word of ! 1060: @samp{links} pointing to the first word of @samp{files}, the second word of ! 1061: @samp{links} pointing to the second word of @samp{files}, and so on. ! 1062: @end table ! 1063: ! 1064: @c --------------------------------------------------------------------- ! 1065: @node Minimal ! 1066: @subsection A minimal @code{configure.in} ! 1067: @cindex Minimal @file{configure.in} example ! 1068: ! 1069: A minimal @file{configure.in} consists of four lines. ! 1070: ! 1071: @example ! 1072: srctrigger=foo.c ! 1073: srcname="source for the foo program" ! 1074: # per-host: ! 1075: # per-target: ! 1076: @end example ! 1077: ! 1078: The @samp{# per-host:} and @samp{# per-target:} lines divide the file into the ! 1079: three required sections. The @samp{srctrigger} line names a file. ! 1080: @code{configure} checks to see that this file exists in the source directory ! 1081: before configuring. If the @samp{srctrigger} file does not exist, ! 1082: @code{configure} uses the value of @samp{srcname} to print an error message ! 1083: about not finding the source. ! 1084: ! 1085: This particular example uses no links, and only the default host, ! 1086: target, and site-specific @file{Makefile} fragments if they exist. ! 1087: ! 1088: @c --------------------------------------------------------------------- ! 1089: @node Declarations ! 1090: @subsection For each invocation ! 1091: @cindex For each invocation ! 1092: @cindex Declarations section ! 1093: @cindex @i{per-invocation} section ! 1094: ! 1095: @code{configure} invokes the entire shell script fragment from the start of ! 1096: @file{configure.in} up to a line beginning with @w{@samp{# per-host:}} ! 1097: immediately after parsing command line arguments. The variables ! 1098: @samp{srctrigger} and @samp{srcname} @emph{must} be set here. ! 1099: ! 1100: You might also want to set the variables @samp{configdirs} and ! 1101: @samp{package_makefile_frag} here. ! 1102: ! 1103: @c --------------------------------------------------------------------- ! 1104: @node per-host ! 1105: @subsection Host-specific instructions ! 1106: @cindex Host-specific instructions ! 1107: @cindex @i{host} shell-script fragment ! 1108: @cindex @i{per-host} section ! 1109: ! 1110: The @dfn{per-host} section of @file{configure.in} starts with the line that ! 1111: begins with @w{@samp{# per-host:}} and ends before a line beginning with ! 1112: @w{@samp{# per-target:}}. @code{configure} invokes the commands in the ! 1113: @dfn{per-host} section when determining host-specific information. ! 1114: ! 1115: This section usually contains a big @code{case} statement using the variable ! 1116: @samp{host} to determine appropriate values for @samp{host_makefile_frag} and ! 1117: @samp{files}, although @samp{files} is not usually set here. Usually, it is ! 1118: set at the end of the @dfn{per-target} section after determining the names of ! 1119: the target specific configuration files. ! 1120: ! 1121: @c --------------------------------------------------------------------- ! 1122: @node per-target ! 1123: @subsection Target-specific instructions ! 1124: @cindex Target-specific instructions ! 1125: @cindex target shell-script fragment ! 1126: @cindex @i{per-target} section ! 1127: ! 1128: The @dfn{per-target} section of @file{configure.in} starts with the line that ! 1129: begins with @w{@samp{# per-target:}} and ends before the line that begins with ! 1130: @w{@samp{# post-target:}}, if there is such a line. Otherwise the ! 1131: @dfn{per-target} section extends to the end of the file. @code{configure} ! 1132: invokes the commands in the @dfn{per-target} section when determining ! 1133: target-specific information, and before building any files, directories, or ! 1134: links. ! 1135: ! 1136: This section usually contains a big @code{case} statement using the variable ! 1137: @samp{target} to determine appropriate values for @samp{target_makefile_frag} ! 1138: and @samp{files}. The last lines in the @dfn{per-target} section normally set ! 1139: the variables @samp{files} and @samp{links}. ! 1140: ! 1141: @c --------------------------------------------------------------------- ! 1142: @node post-target ! 1143: @subsection Instructions to be executed after target info ! 1144: @cindex Post-target shell-script fragment ! 1145: @cindex @i{post-target} section ! 1146: ! 1147: The @dfn{post-target} section is optional. If it exists, the ! 1148: @samp{post-target} section starts with a line beginning with @w{@samp{# ! 1149: Post-target:}} and extends to the end of the file. If it exists, ! 1150: @code{configure} invokes this section once for each target after ! 1151: building all files, directories, or links. ! 1152: ! 1153: This section is seldom needed, but you can use it to edit the @file{Makefile} ! 1154: generated by @code{configure}. ! 1155: ! 1156: @c --------------------------------------------------------------------- ! 1157: @node Example ! 1158: @subsection An example @code{configure.in} ! 1159: @cindex Example @file{configure.in} ! 1160: @cindex Sample @file{configure.in} ! 1161: @c @cindex @code{bison} @file{configure.in} ! 1162: @c this won't be the bison configure.in for long.. need better example ! 1163: ! 1164: Here is a small example of a @file{configure.in} file. ! 1165: ! 1166: @cartouche ! 1167: @example ! 1168: @group ! 1169: # This file is a collection of shell script fragments ! 1170: # used to tailor a template configure script as ! 1171: # appropriate for this directory. For more information, ! 1172: # see configure.texi. ! 1173: ! 1174: configdirs= ! 1175: srctrigger=warshall.c ! 1176: srcname="bison" ! 1177: ! 1178: # per-host: ! 1179: case "$@{host@}" in ! 1180: m88k-motorola-*) ! 1181: host_makefile_frag=config/mh-delta88 ! 1182: ;; ! 1183: esac ! 1184: ! 1185: # per-target: ! 1186: files="bison_in.hairy" ! 1187: links="bison.hairy" ! 1188: ! 1189: # post-target: ! 1190: @end group ! 1191: @end example ! 1192: @end cartouche ! 1193: ! 1194: @c --------------------------------------------------------------------- ! 1195: @node Install locations ! 1196: @section Install locations ! 1197: @cindex Where to install ! 1198: @cindex Install locations ! 1199: ! 1200: Using the default configuration, @samp{make install} creates a single tree of ! 1201: files, some of which are programs. The location of this tree is determined by ! 1202: the value of the variable @samp{prefix}. The default value of @samp{prefix} is ! 1203: @samp{/usr/local}. This is often correct for native tools installed on only ! 1204: one host. ! 1205: ! 1206: @menu ! 1207: * prefix:: Changing the default install directory ! 1208: * exec_prefix:: How to separate host independent files ! 1209: from host dependent files when ! 1210: installing for multiple hosts ! 1211: * Install details:: Full descriptions of all installation subdirectories ! 1212: @end menu ! 1213: ! 1214: @c --------------------------------------------------------------------- ! 1215: @node prefix ! 1216: @subsection Changing the default install directory ! 1217: @cindex Changing the install directory ! 1218: @cindex @code{prefix} option ! 1219: @vindex prefix ! 1220: ! 1221: In the default configuration, all files are installed in subdirectories ! 1222: of @file{/usr/local}. The location is determined by the value of ! 1223: the @code{configure} variable @samp{prefix}; in turn, this determines the ! 1224: value of the @file{Makefile} variable of the same name (@samp{prefix}). ! 1225: ! 1226: You can also set the value of the @file{Makefile} variable @samp{prefix} ! 1227: explicitly each time you invoke @code{make} if you are so inclined. However, ! 1228: because many programs have this location compiled in, you must specify the ! 1229: @samp{prefix} value consistently on each invocation of @code{make}, or you will ! 1230: end up with a broken installation. ! 1231: ! 1232: To make this easier, the value of the @code{configure} variable ! 1233: @samp{prefix} can be set on the command line to @code{configure} ! 1234: using the option @samp{--prefix=}. ! 1235: ! 1236: @c --------------------------------------------------------------------- ! 1237: @node exec_prefix ! 1238: @subsection Installing for multiple hosts ! 1239: @cindex Configuring for multiple hosts ! 1240: @cindex Sharing host-independent files ! 1241: @cindex Installing host-independent files ! 1242: @cindex The @code{exec_prefix} directory ! 1243: @vindex exec_prefix ! 1244: ! 1245: By default, host dependent files are installed in subdirectories of ! 1246: @file{$(exec_prefix)}. The location is determined by the value of the ! 1247: @code{configure} variable @samp{exec_prefix}, which determines the value of the ! 1248: @file{Makefile} variable @samp{exec_prefix}. This makes it easier to install ! 1249: for a single host, and simplifies changing the default location for the install ! 1250: tree. The default doesn't allow for multiple hosts to effectively share ! 1251: host independent files, however. ! 1252: ! 1253: To configure so that multiple hosts can share common files, use something like: ! 1254: ! 1255: @cindex Example session ! 1256: @smallexample ! 1257: configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1 ! 1258: make all info install install-info clean ! 1259: ! 1260: configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2 ! 1261: make all info install install-info ! 1262: @end smallexample ! 1263: ! 1264: The first line configures the source for @var{host1} to place host-specific ! 1265: programs in subdirectories of @file{/usr/gnu/H-@var{host1}}. ! 1266: ! 1267: The second line builds and installs all programs for @var{host1}, ! 1268: including both host-independent and host-specific files, as well as removing ! 1269: the host-specific object files from of the build directory. ! 1270: ! 1271: The third line reconfigures the source for @var{host2} to place host ! 1272: specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}}. ! 1273: ! 1274: The fourth line builds and installs all programs for @var{host2}. Host ! 1275: specific files are installed in new directories, but the host ! 1276: independent files are installed @emph{on top of} the host ! 1277: independent files installed for @var{host1}. This results in a single ! 1278: copy of the host independent files, suitable for use by both hosts. ! 1279: ! 1280: @xref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}, for ! 1281: more information. ! 1282: ! 1283: @c --------------------------------------------------------------------- ! 1284: @node Install details ! 1285: @subsection Full descriptions of all installation subdirectories ! 1286: @cindex Install details ! 1287: @cindex Installation subdirectories ! 1288: @cindex Subdirectories ! 1289: ! 1290: During any install, a number of standard directories are created. Their names ! 1291: are determined by @file{Makefile} variables. Some of the defaults for ! 1292: @file{Makefile} variables can be changed at configuration time using command ! 1293: line options to @code{configure}. For more information on the standard ! 1294: directories or the @file{Makefile} variables, please refer to @ref{Makefiles, , ! 1295: Makefile Conventions, standards, GNU Coding Standards}. See also @ref{Makefile ! 1296: extensions, , Extensions to the @sc{gnu} coding standards}. ! 1297: ! 1298: Note that @code{configure} does not create the directory indicated by the ! 1299: variable @samp{srcdir} at any time. @code{$(srcdir)} is not an installation ! 1300: directory. ! 1301: ! 1302: You can override all @file{Makefile} variables on the command line to ! 1303: @code{make}. (@xref{Overriding, , Overriding Variables, make, GNU Make}.) If ! 1304: you do so, you will need to specify the value precisely the same way for each ! 1305: invocation of @code{make}, or you risk ending up with a broken installation. ! 1306: This is because many programs have the locations of other programs or files ! 1307: compiled into them. If you find yourself overriding any of the variables ! 1308: frequently, you should consider site dependent @file{Makefile} fragments. See ! 1309: also @ref{Sites, , Adding site info}. ! 1310: ! 1311: During @samp{make install}, a number of standard directories are created and ! 1312: populated. The following @file{Makefile} variables define them. Those whose ! 1313: defaults are set by corresponding @code{configure} variables are marked ! 1314: ``@code{Makefile} and @code{configure}''. ! 1315: ! 1316: @table @code ! 1317: @item prefix (@code{Makefile} and @code{configure}) ! 1318: @cindex @code{prefix} ! 1319: @vindex prefix ! 1320: The root of the installation tree. You can set its @file{Makefile} default ! 1321: with the @samp{--prefix=} command line option to @code{configure} ! 1322: (@pxref{Invoking configure, , Invoking @code{configure}}). The default value ! 1323: for @samp{prefix} is @samp{/usr/local}. ! 1324: ! 1325: @item bindir ! 1326: @cindex @code{bindir} ! 1327: @vindex bindir ! 1328: A directory for binary programs that users can run. The default value for ! 1329: @samp{bindir} depends on @samp{prefix}; @samp{bindir} is normally changed only ! 1330: indirectly through @samp{prefix}. The default value for @samp{bindir} is ! 1331: @samp{$(prefix)/bin}. ! 1332: ! 1333: @item exec_prefix (@code{Makefile} and @code{configure}) ! 1334: @cindex @code{exec_prefix} ! 1335: @vindex exec_prefix ! 1336: A directory for host dependent files. You can specify the @file{Makefile} ! 1337: default value by using the @samp{--exec_prefix=} option to @code{configure}. ! 1338: (@xref{Invoking configure, , Invoking @code{configure}}.) The default value ! 1339: for @samp{exec_prefix} is @samp{$(prefix)}. ! 1340: ! 1341: @item libdir ! 1342: @cindex @code{libdir} ! 1343: @vindex libdir ! 1344: A directory for libraries and support programs. The default value for ! 1345: @samp{libdir} depends on @samp{prefix}; @samp{libdir} is normally changed only ! 1346: indirectly through @samp{prefix}. The default value for @samp{libdir} is ! 1347: @samp{$(prefix)/lib}. ! 1348: ! 1349: @item mandir ! 1350: @cindex @code{mandir} ! 1351: @vindex mandir ! 1352: A directory for @code{man} format documentation (``man pages''). The default ! 1353: value for @samp{mandir} depends on @samp{prefix}; @samp{mandir} is normally ! 1354: changed only indirectly through @samp{prefix}. The default value for ! 1355: @samp{mandir} is @samp{$(prefix)/man}. ! 1356: ! 1357: @item man@var{N}dir ! 1358: @cindex @code{man@var{N}dir} ! 1359: @vindex man@var{N}dir ! 1360: These are eight variables named @samp{man1dir}, @samp{man2dir}, etc. They name ! 1361: the specific directories for each man page section. For example, ! 1362: @samp{man1dir} by default holds the filename @file{$(mandir)/man1}; this ! 1363: directory contains @file{emacs.1} (the man page for @sc{gnu} Emacs). ! 1364: Similarly, @samp{man5dir} contains the value @file{$(mandir)/man5}, indicating ! 1365: the directory which holds @file{rcsfile.5} (the man page describing the ! 1366: @code{rcs} data file format). The default value for any of the ! 1367: @samp{man@var{N}dir} variables depends indirectly on @samp{prefix}, and is ! 1368: normally changed only through @samp{prefix}. The default value for ! 1369: @samp{man@var{N}dir} is @samp{$(mandir)/man@var{N}}. ! 1370: ! 1371: @item man@var{N}ext ! 1372: @cindex @code{man@var{N}ext} ! 1373: @vindex man@var{N}ext ! 1374: @emph{Not supported by Cygnus @code{configure}}. The @cite{@sc{gnu} Coding ! 1375: Standards} do not call for @samp{man1ext}, @samp{man2ext}, so the intended use ! 1376: for @code{manext} is apparently not parallel to @samp{mandir}. Its use is not ! 1377: clear. (See also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding ! 1378: standards}.) ! 1379: ! 1380: @item infodir ! 1381: @cindex @code{infodir} ! 1382: @vindex infodir ! 1383: A directory for @code{info} format documentation. The default value for ! 1384: @samp{infodir} depends indirectly on @samp{prefix}; @samp{infodir} is ! 1385: normally changed only through @samp{prefix}. The default value for ! 1386: @samp{infodir} is @samp{$(prefix)/info}. ! 1387: ! 1388: @item docdir ! 1389: @cindex @code{docdir} ! 1390: @vindex docdir ! 1391: A directory for any documentation that is in a format other than those used by ! 1392: @code{info} or @code{man}. The default value for @samp{docdir} depends ! 1393: indirectly on @samp{prefix}; @samp{docdir} is normally changed only through ! 1394: @samp{prefix}. The default value for @samp{docdir} is @samp{$(datadir)/doc}. ! 1395: @emph{This variable is an extension to the @sc{gnu} coding standards}. (See ! 1396: also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}.) ! 1397: ! 1398: @item includedir ! 1399: @cindex @code{includedir} ! 1400: @vindex includedir ! 1401: A directory for the header files accompanying the libraries installed in ! 1402: @samp{libdir}. The default value for @samp{includedir} depends on ! 1403: @samp{prefix}; @samp{includedir} is normally changed only indirectly ! 1404: through @samp{prefix}. The default value for @samp{includedir} is ! 1405: @samp{$(prefix)/include}. ! 1406: @end table ! 1407: ! 1408: @c --------------------------------------------------------------------- ! 1409: @node Host ! 1410: @section Host ! 1411: @cindex Host ! 1412: ! 1413: The arguments to @code{configure} are @dfn{hosttypes}. By ! 1414: @dfn{hosttype} we mean the @dfn{environment} in which the source will be ! 1415: compiled. This need not necessarily be the same as the physical machine ! 1416: involved, although it usually is. ! 1417: ! 1418: For example, if some obscure machine had the @sc{gnu} @code{POSIX} emulation ! 1419: libraries available, it would be possible to configure most @sc{gnu} source for ! 1420: a @code{POSIX} system and build it on the obscure host. ! 1421: ! 1422: For more on this topic, see @ref{Host Environments, On Configuring Development ! 1423: Tools, Host Environments, cfg-paper, On Configuring Development Tools}. ! 1424: ! 1425: @c --------------------------------------------------------------------- ! 1426: @node Target ! 1427: @section Target ! 1428: @cindex Target ! 1429: ! 1430: For building native development tools, or most of the other @sc{gnu} ! 1431: tools, you need not worry about the target. The @dfn{target} of a ! 1432: configuration defaults to the same as the @dfn{host}. ! 1433: ! 1434: For building cross development tools, please see @ref{Building Development ! 1435: Environments, On Configuring Development Tools, Building Development ! 1436: Environments, cfg-paper, On Configuring Development Tools}. ! 1437: ! 1438: @c --------------------------------------------------------------------- ! 1439: @node Makefile fragments ! 1440: @section Adding information about local conventions ! 1441: @cindex @code{Makefile} fragments ! 1442: @cindex Local conventions ! 1443: @cindex Adding local info ! 1444: @cindex Adding site info ! 1445: ! 1446: If you find that a tool does not get configured to your liking, or if ! 1447: @code{configure}'s conventions differ from your local conventions, you should ! 1448: probably consider @dfn{site-specific @file{Makefile} fragments}. See also ! 1449: @ref{Sites, , Adding site info}. ! 1450: ! 1451: These are probably not the right choice for options that can be set from ! 1452: the @code{configure} command line or for differences that are host or ! 1453: target dependent. ! 1454: ! 1455: Cygnus @code{configure} uses three types of @file{Makefile} fragments. In a ! 1456: generated @file{Makefile} they appear in the order: @dfn{target fragment}, ! 1457: @dfn{host fragment}, and @dfn{site fragment}. This allows host fragments to ! 1458: override target fragments, and site fragments to override both. ! 1459: ! 1460: Host-specific @file{Makefile} fragments conventionally reside in the ! 1461: @file{./config/} subdirectory with names of the form @file{mh-@var{hosttype}}. ! 1462: They are used for hosts that require odd options to the standard compiler and ! 1463: for compile time options based on the host configuration. ! 1464: ! 1465: Target-specific @file{Makefile} fragments conventionally reside in the ! 1466: @file{./config/} subdirectory with names of the form @file{mt-@var{target}}. ! 1467: They are used for target dependent compile time options. ! 1468: ! 1469: Site specific @file{Makefile} fragments conventionally reside in the ! 1470: @file{./config/} subdirectory with names of the form @file{ms-@var{site}}. ! 1471: They are used to override host- and target-independent compile time options. ! 1472: Note that you can also override these options on the @code{make} invocation ! 1473: line. ! 1474: ! 1475: @c --------------------------------------------------------------------- ! 1476: @node Makefile extensions ! 1477: @section Extensions to the @sc{gnu} coding standards ! 1478: @cindex @code{Makefile} extensions ! 1479: @cindex Cygnus extensions ! 1480: @cindex Coding standards extensions ! 1481: ! 1482: The following additions to the @sc{gnu} coding standards are required for ! 1483: Cygnus @code{configure} to work properly. ! 1484: ! 1485: @itemize @bullet ! 1486: @item ! 1487: The @file{Makefile} must contain exactly one line starting with @samp{####}. ! 1488: This line should follow any default macro definitions but precede any rules. ! 1489: Host, target, and site-specific @file{Makefile} fragments will be inserted ! 1490: immediately after this line. If the line is missing, the fragments will not be ! 1491: inserted. ! 1492: ! 1493: @item ! 1494: Cygnus adds the following targets to each @file{Makefile}. Their existence is ! 1495: not required for Cygnus @code{configure}, but they are documented here for ! 1496: completeness. ! 1497: ! 1498: @table @code ! 1499: @kindex info ! 1500: @item info ! 1501: Build all info files from texinfo source. ! 1502: ! 1503: @kindex install-info ! 1504: @item install-info ! 1505: Install all info files. ! 1506: ! 1507: @kindex clean-info ! 1508: @item clean-info ! 1509: Remove all info files and any intermediate files that can be generated ! 1510: from texinfo source. ! 1511: ! 1512: @kindex Makefile ! 1513: @item Makefile ! 1514: Calls @code{./config.status} to rebuild the @file{Makefile} in this directory. ! 1515: @end table ! 1516: ! 1517: @item ! 1518: The following @file{Makefile} targets have revised semantics: ! 1519: ! 1520: @table @code ! 1521: @kindex install ! 1522: @item install ! 1523: Should @emph{not} depend on the target @samp{all}. If the program is not ! 1524: already built, @samp{make install} should fail. This allows you to install ! 1525: programs even when @code{make} would otherwise determine them to be out of ! 1526: date. This can happen, for example, when the result of a @samp{make all} is ! 1527: transported via tape to another machine for installation. ! 1528: ! 1529: @kindex clean ! 1530: @item clean ! 1531: Should remove any file that can be regenerated by the @file{Makefile}, ! 1532: excepting only the @file{Makefile} itself, and any links created by ! 1533: @code{configure}. That is, @code{make all clean} should return all directories ! 1534: to their original condition. If this is not done, then the command sequence ! 1535: ! 1536: @cindex Example session ! 1537: @example ! 1538: configure @var{host1} ; make all install clean ; ! 1539: configure @var{host2} ; make all install ! 1540: @end example ! 1541: ! 1542: @noindent ! 1543: will fail because of intermediate files intended for @var{host1}. ! 1544: @end table ! 1545: ! 1546: @item ! 1547: Cygnus adds the following macros to all @file{Makefile.in} files, but ! 1548: you are not required to use them to run Cygnus @code{configure}. ! 1549: ! 1550: @table @code ! 1551: @kindex docdir ! 1552: @item docdir ! 1553: The directory in which to install any documentation that is not either a ! 1554: @code{man} page or an @code{info} file. For @code{man} pages, see ! 1555: @samp{mandir}; for @code{info}, see @samp{infodir}. ! 1556: ! 1557: @kindex includedir ! 1558: @item includedir ! 1559: The directory in which to install any header files that should be made ! 1560: available to users. This is distinct from the @code{gcc} include directory, ! 1561: which is intended for @code{gcc} only. Files in @samp{includedir} may be used ! 1562: by @code{cc} as well. ! 1563: @end table ! 1564: ! 1565: @item ! 1566: The following macros have revised semantics. Most of them describe ! 1567: installation directories; see also @ref{Install details, , Full description of ! 1568: all installation subdirectories}. ! 1569: ! 1570: @table @code ! 1571: @kindex datadir ! 1572: @item datadir ! 1573: is used for host independent data files. ! 1574: ! 1575: @kindex mandir ! 1576: @item mandir ! 1577: The default path for @samp{mandir} depends on @samp{prefix}. ! 1578: ! 1579: @kindex infodir ! 1580: @item infodir ! 1581: The default path for @samp{infodir} depends on @samp{prefix}. ! 1582: ! 1583: @kindex BISON ! 1584: @item BISON ! 1585: is assumed to have a @code{yacc} calling convention. To use @sc{gnu} ! 1586: @code{bison}, use @samp{BISON=bison -y}. ! 1587: @end table ! 1588: ! 1589: @item ! 1590: Each Cygnus @file{Makefile} also conforms to one additional restriction: ! 1591: ! 1592: When libraries are installed, the line containing the call to ! 1593: @samp{INSTALL_DATA} should always be followed by a line containing a call to ! 1594: @samp{RANLIB} on the installed library. This is to accommodate systems that ! 1595: use @code{ranlib}. Systems that do not use @code{ranlib} can set @samp{RANLIB} ! 1596: to ``@code{echo}'' in a host specific @file{Makefile} fragment. ! 1597: @end itemize ! 1598: ! 1599: @c ======================================================================== ! 1600: @node Porting ! 1601: @chapter Porting with @code{configure} ! 1602: @cindex Porting with @code{configure} ! 1603: ! 1604: This section explains how to add programs, host and target configuration ! 1605: names, and site-specific information to Cygnus @code{configure}. ! 1606: ! 1607: @menu ! 1608: * Programs:: Adding configure to new programs ! 1609: * Hosts and targets:: Adding hosts and targets ! 1610: * Sites:: Adding site info ! 1611: @end menu ! 1612: ! 1613: @c --------------------------------------------------------------------- ! 1614: @node Programs ! 1615: @section Adding @code{configure} to new programs ! 1616: @cindex Adding @code{configure} to new programs ! 1617: ! 1618: If you are writing a new program, you probably shouldn't worry about porting or ! 1619: configuration issues until it is running reasonably on some host. Then refer ! 1620: back to this section. ! 1621: ! 1622: If your program currently has a @code{configure} script that meets the @sc{gnu} ! 1623: standards (@pxref{Configuration, , How Configuration Should Work, standards, ! 1624: GNU Coding Standards}, please do not add Cygnus @code{configure}. It should be ! 1625: possible to add this program without change to a Cygnus @code{configure} style ! 1626: source tree. ! 1627: ! 1628: @cindex @code{autoconf} ! 1629: If the program is not target dependent, please consider using @code{autoconf} ! 1630: instead of Cygnus @code{configure}. @code{autoconf} is available from the Free ! 1631: Software Foundation; it is a program which generates an executable shell script ! 1632: called @file{configure} by automatically finding information on the system to ! 1633: be configured on and embedding this information in the shell script. ! 1634: @file{configure} scripts generated by @code{autoconf} require no arguments, and ! 1635: accept the same options as Cygnus @code{configure}. For detailed instructions ! 1636: on using @code{autoconf}, see @ref{Making configure Scripts, , How to organize ! 1637: and produce Autoconf scripts, autoconf, Autoconf}. ! 1638: ! 1639: ! 1640: To add Cygnus @code{configure} to an existing program, do the following: ! 1641: ! 1642: @table @bullet ! 1643: @item Make sure the @file{Makefile} conforms to the @sc{gnu} standard ! 1644: The coding standard for writing a @sc{gnu} @file{Makefile} is described in ! 1645: @ref{Makefiles, , Makefile Conventions, standards, GNU Coding Standards}. For ! 1646: technical information on writing a @file{Makefile}, see @ref{Makefiles, , ! 1647: Writing Makefiles, make, GNU Make}. ! 1648: ! 1649: @item Add Cygnus extensions to the @file{Makefile} ! 1650: These are described in @ref{Makefile extensions, , Extensions to the @sc{gnu} ! 1651: coding standards}. ! 1652: ! 1653: @item Collect package specific definitions in a single file ! 1654: Many packages are best configured using a common @file{Makefile} fragment which ! 1655: is included by all of the makefiles in the different directories of the ! 1656: package. In order to accomplish this, set the variable ! 1657: @samp{package_makefile_fragment} to the name of the file. It will be inserted ! 1658: into the final @file{Makefile} before the target-specific fragment. ! 1659: ! 1660: @item Move host support from @file{Makefile} to fragments ! 1661: This usually involves finding sections of the @file{Makefile} that say things ! 1662: like ``uncomment these lines for host @var{hosttype}'' and moving them to a new ! 1663: file called @file{./config/mh-@var{hosttype}}. For more information, see @ref{Hosts ! 1664: and targets, , Adding hosts and targets}. ! 1665: ! 1666: @item Choose defaults ! 1667: If the program has compile-time options that determine the way the program ! 1668: should behave, choose reasonable defaults and make these @file{Makefile} ! 1669: variables. Be sure the variables are assigned their default values before the ! 1670: @samp{####} line so that site-specific @file{Makefile} fragments can override ! 1671: them (@pxref{Makefile extensions, , Extensions to the @sc{gnu} coding ! 1672: standards}). ! 1673: ! 1674: @item Locate configuration files ! 1675: If there is configuration information in header files or source files, separate ! 1676: it in such a way that the files have generic names. Then move the specific ! 1677: instances of those files into the @file{./config/} subdirectory. ! 1678: ! 1679: @item Separate host and target information ! 1680: Some programs already have this information separated. If yours does not, you ! 1681: will need to separate these two kinds of configuration information. @dfn{Host ! 1682: specific} information is the information needed to compile the program. ! 1683: @dfn{Target specific} information is information on the format of data files ! 1684: that the program will read or write. This information should live in separate ! 1685: files in the @file{./config/} subdirectory with names that reflect the ! 1686: configuration for which they are intended. ! 1687: ! 1688: At this point you might skip this step and simply move on. If you do, you ! 1689: should end up with a program that can be configured only to build @dfn{native} ! 1690: tools, that is, tools for which the host system is also the target system. ! 1691: Later, you could attempt to build a cross tool and separate out the ! 1692: target-specific information by figuring out what went wrong. This is often ! 1693: simpler than combing through all of the source code. ! 1694: ! 1695: @item Write @code{configure.in} ! 1696: Usually this involves writing shell script fragments to map from canonical ! 1697: configuration names into the names of the configuration files. These files ! 1698: will then be linked at configure time from the specific instances of those ! 1699: files in @file{./config} to files in the build directory with more generic ! 1700: names. (See also @ref{Build directories, , Build directories}.) The format of ! 1701: @file{configure.in} is described in @ref{configure.in, , The ! 1702: @code{configure.in} input file}. ! 1703: ! 1704: @item Rename @file{Makefile} to @file{Makefile.in} ! 1705: @end table ! 1706: ! 1707: At this point you should have a program that can be configured using ! 1708: Cygnus @code{configure}. ! 1709: ! 1710: @c --------------------------------------------------------------------- ! 1711: @node Hosts and targets ! 1712: @section Adding hosts and targets ! 1713: @cindex Adding hosts and targets ! 1714: @cindex Hosts and targets ! 1715: ! 1716: To add a host or target to a program that already uses Cygnus @code{configure}, ! 1717: do the following. ! 1718: ! 1719: @itemize @bullet ! 1720: ! 1721: @item ! 1722: Make sure the new configuration name is represented in @file{config.sub}. If ! 1723: not, add it. For more details, see the comments in the shell script ! 1724: @file{config.sub}. ! 1725: ! 1726: @item ! 1727: If you are adding a host configuration, look in @file{configure.in}, in the ! 1728: @dfn{per-host} section. Make sure that your configuration name is represented ! 1729: in the mapping from host configuration names to configuration files. If not, ! 1730: add it. Also see @ref{configure.in, , The @code{configure.in} input file}. ! 1731: ! 1732: @item ! 1733: If you are adding a target configuration, look in @file{configure.in}, in the ! 1734: @dfn{per-target} section. Make sure that your configuration name is ! 1735: represented in the mapping from target configuration names to configuration ! 1736: files. If not, add it. Also see @ref{configure.in, , The @code{configure.in} ! 1737: input file}. ! 1738: ! 1739: @item ! 1740: Look in @file{configure.in} for the variables @samp{files}, @samp{links}, ! 1741: @samp{host_makefile_frag}, and @samp{target_makefile_frag}. The values ! 1742: assigned to these variables are the names of the configuration files, (relative ! 1743: to @samp{srcdir}) that the program uses. Make sure that copies of the files ! 1744: exist for your host. If not, create them. See also @ref{configure variables, ! 1745: , Variables available to @code{configure.in}}. ! 1746: @end itemize ! 1747: ! 1748: This should be enough to @code{configure} for a new host or target ! 1749: configuration name. Getting the program to compile and run properly represents ! 1750: the hardest work of any port. ! 1751: ! 1752: @c --------------------------------------------------------------------- ! 1753: @node Sites ! 1754: @section Adding site info ! 1755: @cindex Sites ! 1756: @cindex Adding site info ! 1757: ! 1758: If some of the @file{Makefile} defaults are not right for your site, you can ! 1759: build site-specific @file{Makefile} fragments. To do this, do the following. ! 1760: ! 1761: @itemize @bullet ! 1762: ! 1763: @item ! 1764: Choose a name for your site. It must currently be less than eleven characters. ! 1765: ! 1766: @item ! 1767: If the program source does not have a @file{./config/} subdirectory, create it. ! 1768: ! 1769: @item ! 1770: Create a file called @file{./config/ms-@var{site}} where @var{site} is the name ! 1771: of your site. In it, set whatever @file{Makefile} variables you need to ! 1772: override to match your site's conventions. ! 1773: ! 1774: @item ! 1775: Configure the program with: ! 1776: ! 1777: @cindex Example session ! 1778: @example ! 1779: configure @dots{} --site=@var{site} ! 1780: @end example ! 1781: ! 1782: @end itemize ! 1783: ! 1784: @c --------------------------------------------------------------------- ! 1785: @node Variables Index ! 1786: @unnumbered Variable Index ! 1787: ! 1788: @printindex vr ! 1789: ! 1790: @page ! 1791: @c --------------------------------------------------------------------- ! 1792: @node Concept Index ! 1793: @unnumbered Concept Index ! 1794: ! 1795: @printindex cp ! 1796: @contents ! 1797: @bye ! 1798: ! 1799: @c Local Variables: ! 1800: @c fill-column: 79 ! 1801: @c outline-regexp: "@chap" ! 1802: @c End: ! 1803: @c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{") ! 1804:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.