| 1 | \input texinfo @c -*-para-*- |
| 2 | @c %**start of header |
| 3 | @setfilename configure.info |
| 4 | @settitle Cygnus Configure |
| 5 | @c %**end of header |
| 6 | @synindex ky cp |
| 7 | @tex |
| 8 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ |
| 9 | \xdef\manvers{\$Revision$} % For use in headers, footers too |
| 10 | @end tex |
| 11 | @setchapternewpage off |
| 12 | |
| 13 | @ifinfo |
| 14 | This document attempts to describe the Cygnus Support version of |
| 15 | @code{configure}. |
| 16 | |
| 17 | Copyright (C) 1991, 1992 Cygnus Support |
| 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 | (this paragraph not being relevant to the printed manual). |
| 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 Cygnus Support. |
| 38 | @end ifinfo |
| 39 | |
| 40 | @titlepage |
| 41 | @sp 10 |
| 42 | @title{Cygnus Configure} |
| 43 | @subtitle @manvers, for Cygnus Configure version 1.84 |
| 44 | @author{K. Richard Pixley, @code{rich@@cygnus.com}} |
| 45 | @author{Cygnus Support} |
| 46 | @page |
| 47 | |
| 48 | @vskip 0pt plus 1filll |
| 49 | Copyright @copyright{} 1991, 1992 Cygnus Support |
| 50 | |
| 51 | Permission is granted to make and distribute verbatim copies of |
| 52 | this manual provided the copyright notice and this permission notice |
| 53 | are preserved on all copies. |
| 54 | |
| 55 | Permission is granted to copy and distribute modified versions of this |
| 56 | manual under the conditions for verbatim copying, provided that the entire |
| 57 | resulting derived work is distributed under the terms of a permission |
| 58 | notice identical to this one. |
| 59 | |
| 60 | Permission is granted to copy and distribute translations of this manual |
| 61 | into another language, under the above conditions for modified versions, |
| 62 | except that this permission notice may be stated in a translation approved |
| 63 | by Cygnus Support. |
| 64 | @end titlepage |
| 65 | |
| 66 | @ifinfo |
| 67 | @format |
| 68 | START-INFO-DIR-ENTRY |
| 69 | * configure: (configure.info). Cygnus configure. |
| 70 | END-INFO-DIR-ENTRY |
| 71 | @end format |
| 72 | |
| 73 | @node top, What Configure Does, (dir), (dir) |
| 74 | @top top |
| 75 | |
| 76 | This file documents the configuration system used and distributed by |
| 77 | Cygnus Support. |
| 78 | |
| 79 | @menu |
| 80 | * What Configure Does:: What Configure Does |
| 81 | * Invoking:: Invoking |
| 82 | * Using Configure:: Using Configure |
| 83 | * Porting:: Porting with Configure |
| 84 | * Reference:: Gory details described |
| 85 | * Known Bugs:: Known Bugs |
| 86 | * Variables Index:: Variable Index |
| 87 | * Concept Index:: Concept Index |
| 88 | |
| 89 | --- The Detailed Node Listing --- |
| 90 | |
| 91 | Using Configure |
| 92 | |
| 93 | * Install Locations:: Where to install things once they are built |
| 94 | * Build Directories:: Where to build object files |
| 95 | * Host:: Telling @code{configure} what will source will |
| 96 | be built |
| 97 | * Target:: Telling @code{configure} what the source will |
| 98 | target |
| 99 | * Local Conventions:: Adding information about local conventions |
| 100 | |
| 101 | Install Locations |
| 102 | |
| 103 | * prefix:: Changing the default install directory |
| 104 | * exec_prefix:: How to separate host independent files |
| 105 | from host dependent files when |
| 106 | installing for multiple hosts |
| 107 | * Install Details:: Full descriptions of all installation |
| 108 | subdirectories |
| 109 | |
| 110 | Porting with Configure |
| 111 | |
| 112 | * Programs:: Adding configure to new programs |
| 113 | * Hosts and Targets:: Adding hosts and targets |
| 114 | * Sites:: Adding site info |
| 115 | |
| 116 | Gory details described |
| 117 | |
| 118 | * Makefile Extensions:: Extensions to the @sc{gnu} coding standards |
| 119 | * configure.in:: The format of the configure.in file |
| 120 | * config.status:: config.status |
| 121 | * Makefile Fragments:: Makefile Fragments |
| 122 | |
| 123 | The format of the @file{configure.in} file |
| 124 | |
| 125 | * Minimal:: A minimal configure.in |
| 126 | * Configure Variables:: Variables available to configure.in |
| 127 | * Declarations:: For each invocation |
| 128 | * Per-host:: For each host |
| 129 | * Per-target:: For each target |
| 130 | * Post-target:: After each target |
| 131 | * Example:: An example configure.in |
| 132 | @end menu |
| 133 | |
| 134 | @end ifinfo |
| 135 | |
| 136 | @node What Configure Does, Invoking, top, top |
| 137 | @chapter What Configure Does |
| 138 | |
| 139 | @code{configure} prepares source directories for building working |
| 140 | programs. A program cannot be built until its source has been |
| 141 | configured. When configure runs, it does the following things. |
| 142 | |
| 143 | @table @emph |
| 144 | @item Create build directories |
| 145 | (see @ref{Build Directories}). When you run @code{configure} with the |
| 146 | @code{-srcdir=} option, it uses the current directory as build |
| 147 | directory, creating under it a directory tree that parallels the |
| 148 | directory structure under the source directory. (See @ref{Invoking}). |
| 149 | |
| 150 | @item Generate makefiles |
| 151 | A makefile template from the source directory, usually called |
| 152 | @file{Makefile.in}, is copied to an output file in the build directory. |
| 153 | The output file is usually named @file{Makefile}. @code{configure} |
| 154 | places definitions for a number of standard makefile macros at the |
| 155 | beginning of the output file. If @code{-prefix=} or @code{-exec_prefix} |
| 156 | were specified on the @code{configure} command line, corresponding |
| 157 | makefile variables are set accordingly. If host, target, or site |
| 158 | specific makefile fragments exist, these are inserted into the output |
| 159 | file. (See @ref{Makefiles, , , make, Makefiles}.) |
| 160 | |
| 161 | @item Generate @file{.gdbinit} If the source directory contains a |
| 162 | @file{.gdbinit} file and the build directory is not the same as the |
| 163 | source directory, a @file{.gdbinit} file is created in the build |
| 164 | directory. This @file{.gdbinit} file contains @code{dir} commands and |
| 165 | a @code{source} command, which will cause the @file{.gdbinit} file from |
| 166 | the source directory to be read by GDB, and will allow GDB to find |
| 167 | source files in either the source directory or the build directory. |
| 168 | (see @ref{Command Files, , , gdb, Command Files}.) |
| 169 | |
| 170 | @item Make symbolic links |
| 171 | Most directories have some symbolic links with generic names built |
| 172 | pointing to specific files in the source directory. If the system where |
| 173 | @code{configure} runs cannot support symbolic links, hard links are used |
| 174 | instead. |
| 175 | |
| 176 | @item Miscellaneous |
| 177 | If the source directory has special needs, they are handled by shell |
| 178 | script fragments stored with the source. Usually there are no special |
| 179 | needs, but sometimes they involve changes to the output makefile. |
| 180 | |
| 181 | @item Generate @file{config.status} |
| 182 | @code{configure} creates a shell script named @file{config.status} in |
| 183 | the build directory. This shell script, when run from the build |
| 184 | directory, will reconfigure the build directory (but not its |
| 185 | subdirectories). This is most often used to have a @code{Makefile} update |
| 186 | itself automatically if a new source directory is available. |
| 187 | |
| 188 | @item Recursion |
| 189 | If the source directory has subdirectories that should also be |
| 190 | configured, @code{configure} is called for each. |
| 191 | @end table |
| 192 | |
| 193 | @node Invoking, Using Configure, What Configure Does, top |
| 194 | @chapter Invoking |
| 195 | |
| 196 | The usual way to invoke @code{configure} is as follows: |
| 197 | @example |
| 198 | configure @var{host} |
| 199 | @end example |
| 200 | This prepares the source to be compiled in a |
| 201 | @var{host} environment with programs and files to be installed in |
| 202 | @file{/usr/local}. |
| 203 | |
| 204 | @code{configure} prepares the source as you specify by selecting and |
| 205 | using script and Makefile fragments prepared in advance, and stored with |
| 206 | the source. @code{configure}'s command line options also allow you to |
| 207 | specify other aspects of the source configuration: |
| 208 | |
| 209 | @table @code |
| 210 | @item -exec_prefix=@var{dir} |
| 211 | Configure the source to install host dependent files in @var{dir}. |
| 212 | |
| 213 | This option sets the @code{configure} variable @code{exec_prefix}. |
| 214 | Generated Makefiles will have their @code{exec_prefix} variables set to |
| 215 | this value. (See @ref{Install Details}.) |
| 216 | |
| 217 | @item -gas |
| 218 | Configure to use the @sc{GNU} assembler. |
| 219 | |
| 220 | @item -help |
| 221 | Display a quick summary of how to invoke @code{configure}. |
| 222 | |
| 223 | @item -host=@var{host} |
| 224 | FIXME-soon: I don't think this option should be documented. |
| 225 | @c Then why does it exist? /Pesch 7jan92 |
| 226 | |
| 227 | @item -nfp |
| 228 | @emph{No floating point} unit available on the target; configure to |
| 229 | avoid dependencies on hardware floating point. |
| 230 | |
| 231 | @item -norecursion |
| 232 | Configure only this directory; ignore any subdirectories. This is used |
| 233 | by the executable shell script @file{config.status} to reconfigure the |
| 234 | current directory. (see @ref{config.status}). |
| 235 | |
| 236 | @item -prefix=@var{dir} |
| 237 | Configure the source to install programs and files under directory |
| 238 | @file{@var{dir}}. |
| 239 | |
| 240 | This option sets the @code{configure} variable @code{prefix}. Generated |
| 241 | Makefiles will have their @code{prefix} variables set to this value. |
| 242 | (See @ref{Install Details}.) |
| 243 | |
| 244 | @item -recurring |
| 245 | @c Wouldn't it make more sense to call this "-quiet"? (FIXME). |
| 246 | This option is used internally by @code{configure} when recurring on |
| 247 | subdirectories. Its sole purpose is to suppress status output. You can |
| 248 | override this effect with the @code{-verbose} option. |
| 249 | |
| 250 | @item -rm |
| 251 | @emph{Remove} the configuration specified by @var{host} and the other |
| 252 | command-line options, rather than creating it. |
| 253 | |
| 254 | @item -site=@var{site} |
| 255 | Generate Makefiles using site specific Makefile fragments for |
| 256 | @var{site}. See also @ref{Sites}. |
| 257 | |
| 258 | @item -srcdir=@var{_dir} |
| 259 | Build Makefiles to use the sources located in directory @file{@var{dir}}. The |
| 260 | build directory is assumed to be @file{.}. |
| 261 | |
| 262 | @item -target=@var{target} |
| 263 | Requests that the sources be configured to target the @var{target} |
| 264 | machine. If no target is specified explicitly, the target is assumed |
| 265 | to be the same as the host. |
| 266 | |
| 267 | @item -tmpdir=@var{tmpdir} |
| 268 | Use the directory @var{tmpdir} for @code{configure}'s temporary files. |
| 269 | The default is the value of the environment variable TMPDIR, or |
| 270 | @file{/tmp} if the environment variable is not set. |
| 271 | |
| 272 | @item -verbose |
| 273 | @itemx -v |
| 274 | Print status lines for each directory configured. Normally, only the |
| 275 | status lines for the initial working directory are printed. |
| 276 | |
| 277 | @item -x |
| 278 | Use @sc{MIT} style @sc{X11} header files and libraries on the host, even |
| 279 | if they are not normally available. |
| 280 | @end table |
| 281 | |
| 282 | @node Using Configure, Porting, Invoking, top |
| 283 | @chapter Using Configure |
| 284 | |
| 285 | The choices and options available at configuration time |
| 286 | generally have valid defaults, but the defaults do not cover all cases. |
| 287 | The choices available include install locations, build directories, |
| 288 | host, target, and local conventions. |
| 289 | |
| 290 | @menu |
| 291 | * Install Locations:: Where to install things once they are built |
| 292 | * Build Directories:: Where to build object files |
| 293 | * Host:: Telling @code{configure} what will source will |
| 294 | be built |
| 295 | * Target:: Telling @code{configure} what the source will |
| 296 | target |
| 297 | * Local Conventions:: Adding information about local conventions |
| 298 | @end menu |
| 299 | |
| 300 | @node Install Locations, Build Directories, Using Configure, Using Configure |
| 301 | @section Install Locations |
| 302 | @cindex Where to install |
| 303 | |
| 304 | Using the default configuration, @code{make install} creates a |
| 305 | single tree of files, some of which are programs. The location of this |
| 306 | tree is determined by the value of the variable @code{prefix}. The |
| 307 | default value of @code{prefix} is @file{/usr/local}. This is |
| 308 | often correct for native tools installed on only one host. |
| 309 | |
| 310 | @menu |
| 311 | * prefix:: Changing the default install directory |
| 312 | * exec_prefix:: How to separate host independent files |
| 313 | from host dependent files when |
| 314 | installing for multiple hosts |
| 315 | * Install Details:: Full descriptions of all installation |
| 316 | subdirectories |
| 317 | @end menu |
| 318 | |
| 319 | @node prefix, exec_prefix, Install Locations, Install Locations |
| 320 | @subsection Changing the default install directory |
| 321 | @cindex Changing the default install directory |
| 322 | @cindex Prefix directory |
| 323 | |
| 324 | In the default configuration, all files are installed in subdirectories |
| 325 | of @file{/usr/local}. The location is determined by the value of |
| 326 | the @code{configure} variable @code{prefix}; in turn, this determines the |
| 327 | value of the Makefile variable of the same name (@code{prefix}). |
| 328 | |
| 329 | You can also set the value of the Makefile variable @code{prefix} |
| 330 | explicitly each time you invoke @code{make} if you are so inclined; but |
| 331 | because many programs have this location compiled in, you must specify |
| 332 | the @code{prefix} value consistently on each invocation of @code{make}, |
| 333 | or you will end up with a broken installation. |
| 334 | |
| 335 | To make this easier, the value of the @code{configure} variable |
| 336 | @code{prefix} can be set on the command line to @code{configure} |
| 337 | using the option @code{-prefix=}. |
| 338 | |
| 339 | |
| 340 | @node exec_prefix, Install Details, prefix, Install Locations |
| 341 | @subsection Installing for multiple hosts |
| 342 | @cindex Configuring for multiple hosts |
| 343 | @cindex Sharing host independent files |
| 344 | @cindex The @file{exec_prefix} directory |
| 345 | @cindex Installing host independent files |
| 346 | |
| 347 | By default, host dependent files are installed in subdirectories of |
| 348 | @file{@var{exec_prefix}}. The location is determined by the value of the |
| 349 | @code{configure} variable @code{exec_prefix}, which determines the value of |
| 350 | the Makefile variable @code{exec_prefix}. This makes it simpler to install |
| 351 | for a single host, and simplifies changing the default location for the |
| 352 | install tree; but the default doesn't allow for multiple hosts to |
| 353 | effectively share host independent files. |
| 354 | |
| 355 | To configure so that multiple hosts can share common files, use |
| 356 | something like: |
| 357 | |
| 358 | @example |
| 359 | configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1 |
| 360 | make all info install install-info clean |
| 361 | |
| 362 | configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2 |
| 363 | make all info install install-info |
| 364 | @end example |
| 365 | |
| 366 | The first line configures the source for @var{host1} to place host |
| 367 | specific programs in subdirectories of @file{/usr/gnu/H-@var{host1}}. |
| 368 | |
| 369 | The second line builds and installs all programs for @var{host1}, |
| 370 | including both host independent and host specific files. |
| 371 | |
| 372 | The third line reconfigures the source for @var{host2} to place host |
| 373 | specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}}. |
| 374 | |
| 375 | The fourth line builds and installs all programs for @var{host2}. Host |
| 376 | specific files are installed in new directories, but the host |
| 377 | independent files are installed @emph{on top of} the host |
| 378 | independent files installed for @var{host1}. This results in a single |
| 379 | copy of the host independent files, suitable for use by both hosts. |
| 380 | |
| 381 | @node Install Details, , exec_prefix, Install Locations |
| 382 | @subsection Full descriptions of all installation subdirectories |
| 383 | |
| 384 | During any install, a number of standard directories are created. Their |
| 385 | names are determined by Makefile variables. Some of the |
| 386 | defaults for Makefile variables can be changed at configure time using |
| 387 | command line options to @code{configure}. For more information on the |
| 388 | standard directories or the Makefile variables, please refer to |
| 389 | @cite{standards.text}. |
| 390 | |
| 391 | Note that @code{configure} does not create the directory @code{srcdir} |
| 392 | at any time. @code{srcdir} is not an installation directory. |
| 393 | |
| 394 | You can override all makefile variables on the command line to |
| 395 | @code{make}. (See @ref{Overriding, Overriding Variables, Overriding |
| 396 | Variables, make, Make}.) If you do so, you will need to specify the |
| 397 | value precisely the same way for each invocation of @code{make}, or you |
| 398 | risk ending up with a broken installation. This is because many |
| 399 | programs have the locations of other programs or files compiled into |
| 400 | them. If you find yourself overriding any of the variables frequently, |
| 401 | you should consider site dependent Makefile fragments. See also |
| 402 | @ref{Sites}. |
| 403 | |
| 404 | During @code{make install}, a number of standard directories are |
| 405 | created and populated. The following Makefile variables define them. |
| 406 | Those whose defaults are set by corresponding @code{configure} variables |
| 407 | are marked ``Makefile and configure''. |
| 408 | |
| 409 | @vindex prefix |
| 410 | @defvr {Makefile and configure} prefix |
| 411 | The root of the installation tree. You can set |
| 412 | its Makefile default with the @code{-prefix=} command line option to |
| 413 | @code{configure}. (@ref{Invoking}.) The default value for |
| 414 | @code{prefix} is @file{/usr/local}. |
| 415 | @end defvr |
| 416 | |
| 417 | @vindex bindir |
| 418 | @defvr Makefile bindir |
| 419 | A directory for binary programs that users can run. |
| 420 | The default value for @code{bindir} depends on @code{prefix}; |
| 421 | @code{bindir} is normally changed only indirectly through @code{prefix}. |
| 422 | The default value for @code{bindir} is @file{$(prefix)/bin}. |
| 423 | @end defvr |
| 424 | |
| 425 | @vindex exec_prefix |
| 426 | @defvr {Makefile and configure} exec_prefix |
| 427 | A directory for host dependent files. You can specify the Makefile |
| 428 | default value by using the @code{-exec_prefix=} option to @code{configure}. |
| 429 | (See also @ref{Invoking}.) The default value for @code{exec_prefix} is |
| 430 | @file{$(prefix)}. |
| 431 | @end defvr |
| 432 | |
| 433 | @vindex libdir |
| 434 | @defvr Makefile libdir |
| 435 | A directory for libraries and support programs. The default value for |
| 436 | @code{libdir} depends on @code{prefix}; @code{libdir} is normally |
| 437 | changed only indirectly through @code{prefix}. The default value for |
| 438 | @code{libdir} is @file{$(prefix)/lib}. |
| 439 | @end defvr |
| 440 | |
| 441 | @vindex mandir |
| 442 | @defvr Makefile mandir |
| 443 | A directory for @code{man} format documentation (``man pages''). The |
| 444 | default value for @code{mandir} depends on @code{prefix}; |
| 445 | @code{mandir} is normally changed only indirectly through @code{prefix}. |
| 446 | The default value for @code{mandir} is @file{$(prefix)/man}. |
| 447 | @end defvr |
| 448 | |
| 449 | @vindex man@var{N}dir |
| 450 | @defvr Makefile man@var{N}dir |
| 451 | There are eight variables named @code{man1dir}, @code{man2dir}, etc. |
| 452 | They name the specific directories for each man page section. For |
| 453 | example, @code{man1dir} holds @file{emacs.1} (the man page for the emacs |
| 454 | program), while @code{man5dir} holds @file{rcsfile.5} (the man page |
| 455 | describing the @code{rcs} data file format). The default value for any |
| 456 | of the @code{man@var{N}dir} variables depends indirectly on |
| 457 | @code{prefix}, and is normally changed only through @code{prefix}. The |
| 458 | default value for @code{man@var{N}dir} is |
| 459 | @file{$(mandir)/man@var{N}}. |
| 460 | @end defvr |
| 461 | |
| 462 | @vindex manext |
| 463 | @defvr Makefile manext |
| 464 | @emph{Not supported by @code{configure}}. The @sc{gnu} coding standards |
| 465 | do not call for @code{man1ext}, @code{man2ext}, so the intended use for |
| 466 | @code{manext} is apparently not parallel to @code{mandir}. Its use is |
| 467 | not clear. (See also @ref{Makefile Extensions}.) |
| 468 | @end defvr |
| 469 | |
| 470 | @vindex infodir |
| 471 | @defvr Makefile infodir |
| 472 | A directory for @emph{info} format documentation. The default value for |
| 473 | @code{infodir} depends indirectly on @code{prefix}; @code{infodir} is |
| 474 | normally changed only through @code{prefix}. The default value for |
| 475 | @code{infodir} is @file{$(prefix)/info}. |
| 476 | @end defvr |
| 477 | |
| 478 | @vindex docdir |
| 479 | @defvr Makefile docdir |
| 480 | A directory for any documentation that is in a format other than those |
| 481 | used by @code{info} or @code{man}. The default value for @code{docdir} |
| 482 | depends indirectly on @code{prefix}; @code{docdir} is normally changed only |
| 483 | through @code{prefix}. The default value for @code{docdir} |
| 484 | is @file{$(datadir)/doc}. @emph{This variable is an extension to |
| 485 | the @sc{gnu} coding standards}. (See also @ref{Makefile Extensions}.) |
| 486 | @end defvr |
| 487 | |
| 488 | @vindex includedir |
| 489 | @defvr Makefile includedir |
| 490 | A directory for the header files accompanying the libraries installed in |
| 491 | @code{libdir}. The default value for @code{includedir} depends on |
| 492 | @code{prefix}; @code{includedir} is normally changed only indirectly |
| 493 | through @code{prefix}. The default value for @code{includedir} is |
| 494 | @file{$(prefix)/include}. |
| 495 | @end defvr |
| 496 | |
| 497 | @node Build Directories, Host, Install Locations, Using Configure |
| 498 | @section Build Directories |
| 499 | @cindex Build directories |
| 500 | @kindex objdir |
| 501 | @cindex Object directories |
| 502 | @kindex subdirs |
| 503 | @cindex Building for multiple hosts |
| 504 | @cindex Building for multiple targets |
| 505 | |
| 506 | Normally, @code{configure} builds a @file{Makefile} and symbolic links |
| 507 | in the same directory as the source files. This is the typical |
| 508 | @sc{un*x} way to build programs, but it has limitations. For instance, |
| 509 | using this approach, you can only build for one host at a time. |
| 510 | |
| 511 | We refer to the directories where @code{configure} builds a |
| 512 | Makefile as the @emph{build directories} or sometimes as |
| 513 | @emph{objdir} because these are the directories in which @code{make} |
| 514 | will build object files, among other things. |
| 515 | |
| 516 | The default build directory is the same as the source directory. |
| 517 | You can use a different build directory with a sequence like the following: |
| 518 | |
| 519 | @example |
| 520 | mkdir @var{builddir} |
| 521 | cd @var{builddir} |
| 522 | configure @var{host} -srcdir=@var{sourcedirectory} |
| 523 | @end example |
| 524 | |
| 525 | @noindent |
| 526 | where @var{builddir} is the directory where you wish to build, |
| 527 | @var{host} is the host for which you want to build, and |
| 528 | @var{sourcedirectory} is the directory containing the source files. |
| 529 | |
| 530 | If you were to do this twice with different values for @var{builddir} |
| 531 | and @var{host}, then you could @code{make} for both at the same time. |
| 532 | |
| 533 | @node Host, Target, Build Directories, Using Configure |
| 534 | @section Host |
| 535 | |
| 536 | The arguments to @code{configure} are @emph{hosts}. By @emph{host} we |
| 537 | mean the environment in which the source will be compiled. This need |
| 538 | not necessarily be the same as the physical machine involved, |
| 539 | although it usually is. |
| 540 | |
| 541 | For example, if some obscure machine running an operating system other |
| 542 | than @sc{un*x} had the @sc{gnu} @sc{posix} emulation libraries |
| 543 | available, it would be possible to configure most @sc{gnu} source for a |
| 544 | @sc{posix} system and build it on the obscure host. |
| 545 | |
| 546 | For more on this topic, see @ref{Host Environments, , Host Environments, |
| 547 | cfg-paper, On Configuring Development Tools}. |
| 548 | |
| 549 | @node Target, Local Conventions, Host, Using Configure |
| 550 | @section Target |
| 551 | |
| 552 | For building native development tools, or most of the other @sc{gnu} |
| 553 | tools, you need not worry about the target. The @emph{target} of a |
| 554 | configuration defaults to the same as the @emph{host}. |
| 555 | |
| 556 | For building cross development tools, please see @ref{Building |
| 557 | Development Environments, , Building Development Environments, |
| 558 | cfg-paper, On Configuring Development Tools}. |
| 559 | |
| 560 | @node Local Conventions, , Target, Using Configure |
| 561 | @section Local Conventions |
| 562 | |
| 563 | If you find that a tool does not get configured to your liking, or if |
| 564 | @code{configure}'s conventions differ from your local conventions, you |
| 565 | should probably consider site specific Makefile fragments. See also |
| 566 | @ref{Sites}. |
| 567 | |
| 568 | These are probably not the right choice for options that can be set from |
| 569 | the @code{configure} command line or for differences that are host or |
| 570 | target dependent. |
| 571 | |
| 572 | @node Porting, Reference, Using Configure, top |
| 573 | @chapter Porting with Configure |
| 574 | @cindex Porting |
| 575 | |
| 576 | This section explains how to add programs, host and target configuration |
| 577 | names, and site-specific information to Cygnus configure. |
| 578 | |
| 579 | @menu |
| 580 | * Programs:: Adding configure to new programs |
| 581 | * Hosts and Targets:: Adding hosts and targets |
| 582 | * Sites:: Adding site info |
| 583 | @end menu |
| 584 | |
| 585 | |
| 586 | @node Programs, Hosts and Targets, Porting, Porting |
| 587 | @section Adding Configure To New Programs |
| 588 | |
| 589 | If you are writing a new program, you probably shouldn't worry about |
| 590 | porting issues or configure until it is running reasonably on some host. |
| 591 | Then refer back to this section. |
| 592 | |
| 593 | If the program in question currently has a configure script that meets |
| 594 | the criteria set out by @cite{standards.text}, please do not add Cygnus |
| 595 | configure. It should be possible to add this program without change to |
| 596 | a Cygnus configure style source tree. |
| 597 | |
| 598 | If the program is not target dependent, please consider using |
| 599 | @code{autoconf} instead of Cygnus configure. @code{autoconf} will |
| 600 | be available soon from the @sc{fsf}. |
| 601 | |
| 602 | To add Cygnus configure to an existing program, do the following: |
| 603 | |
| 604 | @table @asis |
| 605 | @item Make sure the Makefile conforms to @sc{gnu} standard |
| 606 | The coding standard for @sc{gnu} Makefiles is described in |
| 607 | @cite{standards.text}. |
| 608 | |
| 609 | @item Add Cygnus extensions to the Makefile |
| 610 | These are described in @ref{Makefile Extensions}. |
| 611 | |
| 612 | @item Move host support from Makefile to fragments |
| 613 | This usually involves finding sections of the Makefile that say things |
| 614 | like ``uncomment these lines for host foo'' and moving them to a new |
| 615 | file called @file{./config/mh-foo}. For more information, see @ref{Hosts |
| 616 | and Targets}. |
| 617 | |
| 618 | @item Choose defaults |
| 619 | If the program has compile time options that determine the way the |
| 620 | program should behave, chose reasonable defaults and make these Makefile |
| 621 | variables. Be sure the variables are assigned their default values |
| 622 | before the @code{####} line so that site specific Makefile fragments can |
| 623 | override them (@pxref{Makefile Extensions,,Extensions to the @sc{gnu} |
| 624 | coding standards}). |
| 625 | |
| 626 | @item Locate configuration files |
| 627 | If there is configuration information in header files or source files, |
| 628 | separate it in such a way that the files have a generic name. Then move |
| 629 | the specific instances of those files into the @file{./config} |
| 630 | directory. |
| 631 | |
| 632 | @item Separate host and target information |
| 633 | Some programs already have this information separated. If yours does |
| 634 | not, you will need to separate these two kinds of configuration |
| 635 | information. @dfn{Host specific} information is the information needed to |
| 636 | compile the program. @dfn{Target specific} information is information on the |
| 637 | format of data files that the program will read or write. This |
| 638 | information should live in separate files in the @file{./config} |
| 639 | directory with names that reflect the configuration for which they are |
| 640 | intended. |
| 641 | |
| 642 | At this point you might skip this step and simply move on. If you do, |
| 643 | you should end up with a program that can be configured only to build |
| 644 | native tools, that is, tools for which the host system is also the |
| 645 | target system. Later, you could attempt to build a cross tool and |
| 646 | separate out the target specific information by figuring out what went |
| 647 | wrong. This is often simpler than combing through all of the source |
| 648 | code. |
| 649 | |
| 650 | @item Write @code{configure.in} |
| 651 | Usually this involves writing shell script fragments to map from |
| 652 | canonical configuration names into the names of the configuration files. |
| 653 | These files will then be linked at configure time from the specific |
| 654 | instances of those files in @file{./config} to file in the build |
| 655 | directory with more generic names. (see also @ref{Build Directories}). |
| 656 | The format of configure.in is described in @ref{configure.in}. |
| 657 | |
| 658 | @item Rename @file{Makefile} to @file{Makefile.in} |
| 659 | @end table |
| 660 | |
| 661 | At this point you should have a program that can be configured using |
| 662 | Cygnus @code{configure}. |
| 663 | |
| 664 | @node Hosts and Targets, Sites, Programs, Porting |
| 665 | @section Adding hosts and targets |
| 666 | |
| 667 | To add a host or target to a program that already uses Cygnus |
| 668 | configure, do the following. |
| 669 | |
| 670 | @itemize @bullet |
| 671 | |
| 672 | @item |
| 673 | Make sure the new configuration name is represented in |
| 674 | @file{config.sub}. If not, add it. For more details, see the comments |
| 675 | in the shell script @file{config.sub}. |
| 676 | |
| 677 | @item |
| 678 | If you are adding a host configuration, look in @file{configure.in}, in |
| 679 | the per-host section. Make sure that your configuration name is |
| 680 | represented in the mapping from host configuration names to |
| 681 | configuration files. If not, add it. Also see @ref{configure.in}. |
| 682 | |
| 683 | @item |
| 684 | If you are adding a target configuration, look in @file{configure.in}, |
| 685 | in the per-target section. Make sure that your configuration name is |
| 686 | represented in the mapping from target configuration names to |
| 687 | configuration files. If not, add it. Also see @ref{configure.in}. |
| 688 | |
| 689 | @item |
| 690 | Look in @file{configure.in} for the variables @samp{files}, |
| 691 | @samp{links}, @samp{host_makefile_frag}, and |
| 692 | @samp{target_makefile_frag}. The values assigned to these variables are |
| 693 | the names of the configuration files, relative to @code{srcdir} that the |
| 694 | program uses. Make sure that copies of the files exist for your host. |
| 695 | If not, create them. See also @ref{Configure Variables}. |
| 696 | @end itemize |
| 697 | |
| 698 | This should be enough to configure for a new host or target |
| 699 | configuration name. Getting the program to compile and run properly |
| 700 | remains the hard work of the port. |
| 701 | |
| 702 | @node Sites, , Hosts and Targets, Porting |
| 703 | @section Adding site info |
| 704 | |
| 705 | If some of the Makefile defaults are not right for your site, you can |
| 706 | build site specific Makefile fragments. To do this, do the following. |
| 707 | |
| 708 | @itemize @bullet |
| 709 | |
| 710 | @item |
| 711 | Choose a name for your site. It must be less than eleven characters for |
| 712 | now. |
| 713 | |
| 714 | @item |
| 715 | If the program source does not have a @file{./config} directory, create it. |
| 716 | |
| 717 | @item |
| 718 | Create a file called @file{./config/ms-@var{site}} where @var{site} is |
| 719 | the name of your site. In it, set whatever Makefile variables you need |
| 720 | to override to match your site's conventions. |
| 721 | |
| 722 | @item |
| 723 | Configure the program with: |
| 724 | |
| 725 | @example |
| 726 | configure @dots{} +site=@var{site} |
| 727 | @end example |
| 728 | |
| 729 | @end itemize |
| 730 | |
| 731 | @node Reference, Known Bugs, Porting, top |
| 732 | @chapter Gory details described |
| 733 | |
| 734 | @cindex Backends |
| 735 | Here we describe the backend support. |
| 736 | |
| 737 | @menu |
| 738 | * Makefile Extensions:: Extensions to the @sc{gnu} coding standards |
| 739 | * configure.in:: The format of the configure.in file |
| 740 | * config.status:: config.status |
| 741 | * Makefile Fragments:: Makefile Fragments |
| 742 | @end menu |
| 743 | |
| 744 | @node Makefile Extensions, configure.in, Reference, Reference |
| 745 | @section Extensions to the @sc{gnu} coding standards |
| 746 | |
| 747 | @cindex Makefile extensions |
| 748 | @cindex Cygnus extensions |
| 749 | |
| 750 | The following additions to the @sc{gnu} coding standards are required |
| 751 | for Cygnus configure to work properly. |
| 752 | |
| 753 | @itemize @bullet |
| 754 | @item |
| 755 | The Makefile must contain exactly one line starting with @code{####}. |
| 756 | This line should follow any default macro definitions but precede any |
| 757 | rules. Host, target, and site specific Makefile fragments will be |
| 758 | inserted immediately after this line. If the line is missing, the |
| 759 | fragments will not be inserted. |
| 760 | @end itemize |
| 761 | |
| 762 | Cygnus adds the following targets to our Makefiles. Their existence is |
| 763 | not required for Cygnus configure, but they are documented here for |
| 764 | completeness. |
| 765 | |
| 766 | @table @code |
| 767 | @kindex info |
| 768 | @item info |
| 769 | Build all info files from texinfo source. |
| 770 | |
| 771 | @kindex install-info |
| 772 | @item install-info |
| 773 | Install all info files. |
| 774 | |
| 775 | @kindex clean-info |
| 776 | @item clean-info |
| 777 | Remove all info files and any intermediate files that can be generated |
| 778 | from texinfo source. |
| 779 | |
| 780 | @kindex stage1 |
| 781 | @item stage1 |
| 782 | @kindex stage2 |
| 783 | @itemx stage2 |
| 784 | @kindex stage3 |
| 785 | @itemx stage3 |
| 786 | @kindex stage4 |
| 787 | @itemx stage4 |
| 788 | @kindex de-stage1 |
| 789 | @itemx de-stage1 |
| 790 | @kindex de-stage2 |
| 791 | @itemx de-stage2 |
| 792 | @kindex de-stage3 |
| 793 | @itemx de-stage3 |
| 794 | @kindex de-stage4 |
| 795 | @itemx de-stage4 |
| 796 | @kindex bootstrap |
| 797 | @itemx bootstrap |
| 798 | @kindex comparison |
| 799 | @itemx comparison |
| 800 | @kindex Makefile |
| 801 | @itemx Makefile |
| 802 | These targets are in transition and may be removed shortly. |
| 803 | @end table |
| 804 | |
| 805 | In addition, the following Makefile targets have revised semantics: |
| 806 | |
| 807 | @table @code |
| 808 | @kindex install |
| 809 | @item install |
| 810 | Should @emph{not} depend on the target @code{all}. If the program is |
| 811 | not already built, @code{make install} should fail. This allows you |
| 812 | to install programs even when @code{make} would otherwise determine |
| 813 | them to be out of date. This can happen when the result of a @code{make |
| 814 | all} is transported via tape to another machine for installation as |
| 815 | well as in a number of other cases. |
| 816 | |
| 817 | @kindex clean |
| 818 | @item clean |
| 819 | Should remove any file that can be regenerated by the Makefile, |
| 820 | excepting only the Makefile itself, and any links created by configure. |
| 821 | That is, @code{make all clean} should return all directories to their |
| 822 | original condition. If this is not done, then: |
| 823 | |
| 824 | @example |
| 825 | configure @var{host1} ; make all clean ; configure @var{host2} ; make all |
| 826 | @end example |
| 827 | |
| 828 | @noindent |
| 829 | will fail because of intermediate files intended for @var{host1}. |
| 830 | @end table |
| 831 | |
| 832 | Cygnus adds the following macros to all @file{Makefile.in} files, but |
| 833 | you are not required to use them to run Cygnus configure. |
| 834 | |
| 835 | @table @code |
| 836 | @kindex docdir |
| 837 | @item docdir |
| 838 | The directory in which to install any documentation that is not either a |
| 839 | man page or an info file. For man pages, see mandir, for info, see |
| 840 | infodir. |
| 841 | |
| 842 | @kindex includedir |
| 843 | @item includedir |
| 844 | The directory in which to install any headers files that should be made |
| 845 | available to users. This is distinct from the @code{gcc} include |
| 846 | directory which is intended for @code{gcc} only. Files in |
| 847 | @code{includedir} may be used by @code{cc} as well. |
| 848 | @end table |
| 849 | |
| 850 | In addition, the following macros have revised semantics. Most of them |
| 851 | describe installation directories; see also @ref{Install Details,,Full |
| 852 | description of all installation subdirectories}. |
| 853 | |
| 854 | @table @code |
| 855 | |
| 856 | @kindex manext |
| 857 | @item manext |
| 858 | is not used. The intended usage is not clear. For example, if you have a |
| 859 | @file{foo.man} and a @file{bar.man}, and @file{foo.man} is destined for |
| 860 | @file{/usr/local/lib/man/man1/foo.1} while @file{bar.man} is destined |
| 861 | for @file{/usr/local/lib/man/man5/bar.5}, then what is the desired value |
| 862 | of @code{manext}? |
| 863 | |
| 864 | @kindex datadir |
| 865 | @item datadir |
| 866 | is used for host independent data files. |
| 867 | |
| 868 | @kindex mandir |
| 869 | @item mandir |
| 870 | The default path for @code{mandir} depends on @code{prefix}. |
| 871 | |
| 872 | @kindex infodir |
| 873 | @item infodir |
| 874 | The default path for @code{infodir} depends on @code{prefix}. |
| 875 | |
| 876 | @kindex BISON |
| 877 | @item BISON |
| 878 | is assumed to have a @code{yacc} calling convention. To use |
| 879 | @code{bison}, use @code{BISON=bison -y}. |
| 880 | @end table |
| 881 | |
| 882 | Cygnus Makefiles also conform to one additional restriction: |
| 883 | |
| 884 | @itemize @bullet |
| 885 | @item |
| 886 | When libraries are installed, the line containing the call to |
| 887 | @code{INSTALL_DATA} should always be followed by a line containing a |
| 888 | call to @code{RANLIB} on the installed library. This is to accomodate |
| 889 | systems that use @code{ranlib}. Systems that do not use @code{ranlib} |
| 890 | can set @code{RANLIB} to @code{echo} in a host specific Makefile |
| 891 | fragment. |
| 892 | @end itemize |
| 893 | |
| 894 | @node configure.in, config.status, Makefile Extensions, Reference |
| 895 | @section The format of the @file{configure.in} file |
| 896 | @kindex configure.in |
| 897 | |
| 898 | A @file{configure.in} file for Cygnus configure consists of a |
| 899 | @dfn{per-invocation} section, followed by a @dfn{per-host} section, |
| 900 | followed by a @dfn{per-target} section, optionally followed by a |
| 901 | @dfn{post-target} section. Each section is a shell script fragment, |
| 902 | which is sourced by the configure shell script at an appropriate time. |
| 903 | Values are passed among configure and the shell fragments through a |
| 904 | set of shell variables. When each section is being interpreted |
| 905 | (sourced) by the shell, the shell's current directory is the build |
| 906 | directory, and any files created by the section (or referred to by the |
| 907 | section) will be relative to the build directory. To reference files |
| 908 | in other places (such as the source directory), prepend a shell |
| 909 | variable such as @code{srcdir} to the desired file name. |
| 910 | |
| 911 | @cindex Per-invocation section |
| 912 | The beginning of the @file{configure.in} file begins the per-invocation |
| 913 | section. |
| 914 | |
| 915 | @cindex Per-host section |
| 916 | A line beginning with @code{# Per-host:} begins the per-host section. |
| 917 | |
| 918 | @cindex Per-target section |
| 919 | A line beginning with @code{# Per-target:} begins the per-target |
| 920 | section. |
| 921 | |
| 922 | @cindex Post-target section |
| 923 | If it exists, the post-target section begins with @code{# Per-target:}. |
| 924 | |
| 925 | @menu |
| 926 | * Minimal:: A minimal configure.in |
| 927 | * Configure Variables:: Variables available to configure.in |
| 928 | * Declarations:: For each invocation |
| 929 | * Per-host:: For each host |
| 930 | * Per-target:: For each target |
| 931 | * Post-target:: After each target |
| 932 | * Example:: An example configure.in |
| 933 | @end menu |
| 934 | |
| 935 | @node Minimal, Configure Variables, configure.in, configure.in |
| 936 | @subsection A minimal @file{configure.in} |
| 937 | |
| 938 | @cindex Minimal @file{configure.in} example |
| 939 | A minimal @file{configure.in} consists of four lines. |
| 940 | |
| 941 | @example |
| 942 | srctrigger=foo.c |
| 943 | srcname="source for the foo program" |
| 944 | # Per-host: |
| 945 | # Per-target: |
| 946 | @end example |
| 947 | |
| 948 | The @samp{Per-host} and @samp{Per-target} lines divide the file into the |
| 949 | three required sections. The @samp{srctrigger} line names a file. |
| 950 | @code{configure} checks to see that this file exists in the source |
| 951 | directory before configuring. If the @samp{srctrigger} file does not |
| 952 | exist, @code{configure} uses the value of @samp{srcname} to print an |
| 953 | error message about not finding the source. |
| 954 | |
| 955 | This particular example uses no links, and only the default host, |
| 956 | target, and site specific Makefile fragments if they exist. |
| 957 | |
| 958 | @node Configure Variables, Declarations, Minimal, configure.in |
| 959 | @subsection Variables available to configure.in |
| 960 | |
| 961 | @cindex @file{configure.in} interface |
| 962 | |
| 963 | The following variables pass information between the standard parts of |
| 964 | @code{configure} and the shell-script fragments in @file{configure.in}: |
| 965 | |
| 966 | @defvar{srctrigger} |
| 967 | Contains the name of a source file that is expected to live in the |
| 968 | source directory. You must usually set this in the per-invocation |
| 969 | section of @file{configure.in}. Configure tests to see that this file |
| 970 | exists. If the file does not exist, configure prints an error message. |
| 971 | This is used as a sanity check that configure.in matches the source |
| 972 | directory. |
| 973 | @end defvar |
| 974 | |
| 975 | @defvar{srcname} |
| 976 | Contains the name of the source collection contained in the source |
| 977 | directory. You must usually set this in the per-invocation section of |
| 978 | @file{configure.in}. If the file named in @code{srctrigger} does not |
| 979 | exist, configure uses the value of this variable when it prints the |
| 980 | error message. |
| 981 | @end defvar |
| 982 | |
| 983 | @defvar{configdirs} |
| 984 | Contains the names of any subdirectories where @code{configure} should |
| 985 | recur. You must usually set this in the per-invocation section of |
| 986 | @file{configure.in}. |
| 987 | If @file{Makefile.in} contains a line starting with @code{SUBDIRS =}, |
| 988 | then it will be replaced with an assignment to @code{SUBDIRS} using |
| 989 | the value of @code{configdirs} (if @code{subdirs} is empty). This can |
| 990 | be used to determine which directories to configure and build depending |
| 991 | on the host and target configurations. |
| 992 | @c Most other matching makefile/config vars use the same name. Why not |
| 993 | @c this? (FIXME). |
| 994 | @c Can we get rid of SUBDIRS-substitution? It doesn't work well with subdirs. |
| 995 | Use @code{configdirs} (instead of the @code{subdirs} variable |
| 996 | described below) if you want to be able to partition the |
| 997 | sub-directories, or use independent Makefile fragments. |
| 998 | Each sub-directory can be independent, and independently re-configured. |
| 999 | @end defvar |
| 1000 | |
| 1001 | @defvar{subdirs} |
| 1002 | Contains the names of any subdirectories where @code{configure} should |
| 1003 | create a @code{Makefile} (in addition to the current directory), |
| 1004 | @emph{without} recursively running @code{configure}. |
| 1005 | Use @code{subdirs} (instead of the @code{configdirs} variable |
| 1006 | described above) if you want to configure all of the directories |
| 1007 | as a unit. Since there is a single invocation of @code{configure} |
| 1008 | that configures many directories, all the directories can use the |
| 1009 | same Makefile fragments, and the same @code{configure.in}. |
| 1010 | @end defvar |
| 1011 | |
| 1012 | @defvar{host} |
| 1013 | Contains the name that the user entered for the host. Since many things |
| 1014 | that the user could enter would map to the same output from |
| 1015 | @code{config.sub}, this variable is innappropriate to use for picking |
| 1016 | available configurations. For that, use @code{host_cpu}, |
| 1017 | @code{host_vendor}, and/or @code{host_os}. This variable is useful, |
| 1018 | however, for error messages. |
| 1019 | @end defvar |
| 1020 | |
| 1021 | @defvar{host_cpu} |
| 1022 | Contains the first element of the canonical triple representing the host |
| 1023 | as returned by @file{config.sub}. This is occasionally used to |
| 1024 | distinguish between minor variations of a particular vendor's operating |
| 1025 | system and sometimes to determine variations in binary format between |
| 1026 | the host and the target. |
| 1027 | @end defvar |
| 1028 | |
| 1029 | @defvar{host_vendor} |
| 1030 | Contains the second element of the canonical triple representing the |
| 1031 | host as returned by @file{config.sub}. This is usually used to |
| 1032 | distinguish betwen the numerous variations between @emph{common} |
| 1033 | operating systems. |
| 1034 | @c "@emph{common} OS" doesn't convey much to me. Is this meant to cover |
| 1035 | @c cases like Unix, widespread but with many variations? |
| 1036 | @end defvar |
| 1037 | |
| 1038 | @defvar{host_os} |
| 1039 | Contains the the third element of the canonical triple representing the |
| 1040 | host as returned by @file{config.sub}. |
| 1041 | @end defvar |
| 1042 | |
| 1043 | @defvar{target} |
| 1044 | Contains the name that the user entered for the target. Since |
| 1045 | many things that the user could enter would map to the same canonical |
| 1046 | triple, this variable is innappropriate to use for picking available |
| 1047 | configurations. For that, use @code{target_cpu}, @code{target_vendor}, |
| 1048 | and/or @code{target_os}. This variable is useful, however, for error |
| 1049 | messages. |
| 1050 | @end defvar |
| 1051 | |
| 1052 | @defvar{target_cpu} |
| 1053 | Contains the first element of the canonical triple representing the |
| 1054 | target as returned by @file{config.sub}. This is used heavily by |
| 1055 | programs involved in building programs, like the compiler, assembler, |
| 1056 | linker, etc. Most programs will not need the @code{target} variables at |
| 1057 | all, but this one could conceivably be used to build a program, for |
| 1058 | instance, that operated on binary data files whose byte order or |
| 1059 | alignment differ from the system where the program is running. |
| 1060 | @end defvar |
| 1061 | |
| 1062 | @defvar{target_vendor} |
| 1063 | Contains the second element of the canonical triple representing the |
| 1064 | target as returned by @file{config.sub}. This is usually used to |
| 1065 | distinguish betwen the numerous variations between @emph{common} |
| 1066 | operating systems or object file formats. Sometimes it is used to |
| 1067 | switch between different flavors of user interfaces. |
| 1068 | @c above query re "@emph{common} OS" applies here too |
| 1069 | @end defvar |
| 1070 | |
| 1071 | @defvar{target_os} |
| 1072 | Contains the the third element of the canonical triple representing the |
| 1073 | target as returned by @file{config.sub}. This variable is used by |
| 1074 | development tools to distinguish between subtle variations in object |
| 1075 | file formats that some vendors use across operating system releases. It |
| 1076 | might also be use to decide which libraries to build or what user |
| 1077 | interface the tool should provide. |
| 1078 | @end defvar |
| 1079 | |
| 1080 | @defvar{nfp} |
| 1081 | Is set to @code{true} if the user invoked configure with the @code{-nfp} |
| 1082 | command line option, otherwise it is empty. This is a request to target |
| 1083 | machines with @emph{no floating point} unit, even if the targets |
| 1084 | ordinarily have floating point units available. This option has no |
| 1085 | negation. |
| 1086 | @end defvar |
| 1087 | |
| 1088 | @defvar{gas} |
| 1089 | Is set to @code{true} if the user invoked configure with the @code{-gas} |
| 1090 | command line option, otherwise it is empty. This is a request to assume |
| 1091 | that all target machines have @sc{gas} available even if they ordinarily do |
| 1092 | not. The converse option @samp{-no-gas} is not available. |
| 1093 | @end defvar |
| 1094 | |
| 1095 | @defvar{x} |
| 1096 | Is set to @code{true} if the user invoked configure with the @code{-x} |
| 1097 | command line option, otherwise it is empty. This is a request to assume |
| 1098 | that @sc{mit x11} compatible headers files and libraries are available |
| 1099 | on all hosts, regardless of what is normally available on them. |
| 1100 | @end defvar |
| 1101 | |
| 1102 | @defvar{srcdir} |
| 1103 | Is set to the name of the directory containing the source for this |
| 1104 | program. This will be different from @file{.} if the user has specified |
| 1105 | the @code{-srcdir=} option. Note that @code{srcdir} is not necessarily |
| 1106 | an absolute path. |
| 1107 | @end defvar |
| 1108 | |
| 1109 | @defvar{host_makefile_frag} |
| 1110 | If set by @file{configure.in}, this variable should be the name a file, |
| 1111 | relative to @code{srcdir} to be included in the resulting Makefile. If |
| 1112 | the named file does not exist, @code{configure} will print a warning |
| 1113 | message. This variable is not set by @code{configure}. |
| 1114 | @end defvar |
| 1115 | |
| 1116 | @defvar{target_makefile_frag} |
| 1117 | If set by @file{configure.in}, this variable should be the name of a |
| 1118 | file, relative to @code{srcdir}, to be included in the resulting |
| 1119 | Makefile. If the named file does not exist, @code{configure} will print |
| 1120 | a warning message. This variable is not set by @code{configure}. |
| 1121 | @end defvar |
| 1122 | |
| 1123 | @defvar{site_makefile_frag} |
| 1124 | Is set to a file name representing to the default Makefile fragment for |
| 1125 | this host. It may be set in @file{configure.in} to override this |
| 1126 | default. Normally @code{site_makefile_frag} is empty, but will have a |
| 1127 | value if the user specified @code{-site=} on the command line. It is |
| 1128 | probably not a good idea to override this variable from |
| 1129 | @file{configure.in}, since that may defeat the @code{configure} user's |
| 1130 | intentions. |
| 1131 | @end defvar |
| 1132 | |
| 1133 | @defvar{Makefile} |
| 1134 | Is set to the name of the generated @file{Makefile}. Normally this |
| 1135 | value is precisely @file{Makefile} but some programs may want something |
| 1136 | else. |
| 1137 | @end defvar |
| 1138 | |
| 1139 | @defvar{removing} |
| 1140 | Is normally empty but will be set to some non-empty value if the user |
| 1141 | specified @code{-rm} on the command line. That is, if @code{removing} |
| 1142 | is non-empty, then configure is @emph{removing} a configuration rather |
| 1143 | than creating one. |
| 1144 | @end defvar |
| 1145 | |
| 1146 | @defvar{files} |
| 1147 | If this variable is non-empty following the @code{per-target:} section, |
| 1148 | then each word in its value will be the target of a symbolic link named |
| 1149 | in the corresponding word from the @code{links} variable. |
| 1150 | @end defvar |
| 1151 | |
| 1152 | @defvar{links} |
| 1153 | If the @code{files} variable is non-empty following the |
| 1154 | @code{per-target:} section, then @code{configure} creates symbolic links |
| 1155 | with the first word of @code{links} pointing to the first word of |
| 1156 | @code{files}, the second word of @code{links} pointing to the second |
| 1157 | word of @code{files}, and so on. |
| 1158 | @end defvar |
| 1159 | |
| 1160 | @node Declarations, Per-host, Configure Variables, configure.in |
| 1161 | @subsection For each invocation |
| 1162 | |
| 1163 | @cindex Declarations section |
| 1164 | |
| 1165 | @code{configure} sources the entire shell script fragment from the start |
| 1166 | of @file{configure.in} up to a line beginning with @samp{# Per-host:} |
| 1167 | immediately after parsing command line arguments. The variables |
| 1168 | @code{srctrigger} and @code{srcname} @emph{must} be set here. |
| 1169 | |
| 1170 | You might also want to set the variable @code{configdirs} here. |
| 1171 | |
| 1172 | @node Per-host, Per-target, Declarations, configure.in |
| 1173 | @subsection For each host |
| 1174 | @cindex per-host section |
| 1175 | @cindex host shell-script fragment |
| 1176 | |
| 1177 | The per-host section of @file{configure.in} starts with the line that begins |
| 1178 | with @samp{# Per-host:} and ends before a line beginning with |
| 1179 | @samp{# Per-target:}. @code{configure} sources the per-host section once for |
| 1180 | each host. |
| 1181 | |
| 1182 | This section usually contains a big case statement using the variables |
| 1183 | @samp{host_cpu}, @samp{host_vendor}, and @samp{host_os} to determine |
| 1184 | appropriate values for @samp{host_makefile_frag} and @samp{files}, |
| 1185 | although @samp{files} is not usually set here. Usually, it is set |
| 1186 | at the end of the per-target section after determining the names of the |
| 1187 | target specific configuration files. |
| 1188 | |
| 1189 | @node Per-target, Post-target, Per-host, configure.in |
| 1190 | @subsection For each target |
| 1191 | @cindex per-target section |
| 1192 | @cindex target shell-script fragment |
| 1193 | |
| 1194 | The per-target section of @file{configure.in} starts with the line that |
| 1195 | begins with @samp{# Per-target:} and ends before the line that begins |
| 1196 | with @samp{# Post-target:}, if there is such a line. Otherwise the |
| 1197 | per-target section extends to the end of the file. @code{configure} sources |
| 1198 | the per-target section once for each target before building any files, |
| 1199 | directories, or links. |
| 1200 | |
| 1201 | This section usually contains a big case statement using the variables called |
| 1202 | @samp{target_cpu}, @samp{target_vendor}, and @samp{target_os} to determine |
| 1203 | appropriate values for @samp{target_makefile_frag} and @samp{files}. |
| 1204 | The last lines in the per-target section normally set the variables |
| 1205 | @code{files} and @code{links}. |
| 1206 | |
| 1207 | @node Post-target, Example, Per-target, configure.in |
| 1208 | @subsection After each target |
| 1209 | |
| 1210 | The post-target section is optional. If it exists, the post-target |
| 1211 | section starts with a line beginning with @code{# Post-target:} and |
| 1212 | extends to the end of the file. If it exists, @code{configure} sources this |
| 1213 | section once for each target after building all files, directories, or |
| 1214 | links. |
| 1215 | |
| 1216 | This section is seldom needed, but you can use it to edit the Makefile |
| 1217 | generated by @code{configure}. |
| 1218 | |
| 1219 | @node Example, , Post-target, configure.in |
| 1220 | @subsection An example @file{configure.in} |
| 1221 | @cindex example @file{configure.in} |
| 1222 | @cindex sample @file{configure.in} |
| 1223 | @cindex Bison @file{configure.in} |
| 1224 | |
| 1225 | Here is a small example of a @file{configure.in} file. |
| 1226 | |
| 1227 | @example |
| 1228 | # This file is a collection of shell script fragments used to tailor |
| 1229 | # a template configure script as appropriate for this directory. |
| 1230 | # For more information, see configure.texi. |
| 1231 | |
| 1232 | configdirs= |
| 1233 | srctrigger=warshall.c |
| 1234 | srcname="bison" |
| 1235 | |
| 1236 | # per-host: |
| 1237 | case "$@{host_os@}" in |
| 1238 | m88kbcs) |
| 1239 | host_makefile_frag=config/mh-delta88 |
| 1240 | ;; |
| 1241 | esac |
| 1242 | |
| 1243 | # per-target: |
| 1244 | |
| 1245 | files="bison_in.hairy" |
| 1246 | links="bison.hairy" |
| 1247 | |
| 1248 | # post-target: |
| 1249 | @end example |
| 1250 | |
| 1251 | @node config.status, Makefile Fragments, configure.in, Reference |
| 1252 | @section @code{config.status} |
| 1253 | |
| 1254 | @kindex config.status |
| 1255 | |
| 1256 | The final step in configuring a directory is to create an executable |
| 1257 | shell script, @file{config.status}. The main purpose of this file |
| 1258 | is to allow the Makefile for the current directory to rebuild itself, if |
| 1259 | necessary. For this reason, @file{config.status} uses the |
| 1260 | @samp{-norecursion} option to @code{configure}, and is therefore |
| 1261 | probably inappropriate for reconfiguring a tree of source code. |
| 1262 | |
| 1263 | @node Makefile Fragments, , config.status, Reference |
| 1264 | @section Makefile Fragments |
| 1265 | |
| 1266 | @cindex Makefile fragments |
| 1267 | |
| 1268 | Cygnus @code{configure} uses three types of Makefile fragments. In a |
| 1269 | generated Makefile they appear in the order target fragment, host |
| 1270 | fragment, and site fragment. This allows host fragments to override |
| 1271 | target fragments, and site fragments to override both. |
| 1272 | |
| 1273 | Host specific Makefile fragments conventionally reside in the |
| 1274 | @file{./config} directory with names of the form |
| 1275 | @file{mh-@var{host}}. They are used for hosts that require |
| 1276 | odd options to the standard compiler and for compile time options based |
| 1277 | on the host configuration. |
| 1278 | |
| 1279 | Target specific Makefile fragments conventionally reside in the |
| 1280 | @file{./config} directory with names of the form @file{mt-@var{target}}. |
| 1281 | They are used for target dependent compile time options. |
| 1282 | |
| 1283 | Site specific Makefile fragments conventionally reside in the |
| 1284 | @file{./config} directory with names of the form @file{ms-@var{site}}. |
| 1285 | They are used to override host and target independent compile time |
| 1286 | options. Note that you can also override these options on the |
| 1287 | @code{make} invocation line. |
| 1288 | |
| 1289 | @node Known Bugs, Variables Index, Reference, top |
| 1290 | @chapter Known Bugs |
| 1291 | |
| 1292 | @cindex bugs |
| 1293 | |
| 1294 | We know of the following bugs: |
| 1295 | |
| 1296 | @itemize @bullet |
| 1297 | |
| 1298 | @item |
| 1299 | There is no way to query about known hosts, known targets, or the |
| 1300 | porting or testing status of any configuration. |
| 1301 | |
| 1302 | @item |
| 1303 | The negations to the options @code{-gas}, @code{-x}, and @code{-nfp} are |
| 1304 | not available. |
| 1305 | |
| 1306 | @end itemize |
| 1307 | |
| 1308 | @page |
| 1309 | @node Variables Index, Concept Index, Known Bugs, top |
| 1310 | @appendix Variable Index |
| 1311 | |
| 1312 | @printindex vr |
| 1313 | |
| 1314 | @page |
| 1315 | @node Concept Index, , Variables Index, top |
| 1316 | @appendix Concept Index |
| 1317 | |
| 1318 | @printindex cp |
| 1319 | @contents |
| 1320 | @bye |
| 1321 | |
| 1322 | @c Local Variables: |
| 1323 | @c fill-column: 79 |
| 1324 | @c outline-regexp: "@chap" |
| 1325 | @c End: |
| 1326 | @c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{") |