configure.texi

   1 \input texinfo    @c -*-para-*-
   2 @c %**start of header
   3 @setfilename configure.info
   4 @settitle Cygnus Configure
   5 @c %**end of header
   6 @c @setchapternewpage odd
   7
   8 @titlepage
   9 @sp 10
  10 @title{Cygnus Configure}
  11 @author{K. Richard Pixley}
  12 @page
  13 @vskip 0pt plus 1filll
  14 Copyright @copyright{} 1991 Cygnus Support
  15 @end titlepage
  16
  17 @ifinfo
  18 This document attempts to describe the configuration system used and
  19 distributed by Cygnus Support.
  20
  21 Copyright @copyright{} 1991 Cygnus Support
  22 @end ifinfo
  23
  24 @ifinfo
  25 @node top, Invoking, (dir), (dir)
  26 @top top
  27
  28 This file documents the configuration system used and distributed by
  29 Cygnus Support.
  30
  31 NOTE: support for a Cygnus experimental option, @code{-subdirs} is at
  32 least temporarily suspended.  Most of the code is still in configure but
  33 the option is disabled.  This document describes that feature, but those
  34 parts are prominently marked with NOTE's like this one. FIXME-soon
  35
  36 @menu
  37 * Invoking::                    Invoking
  38 * Using Configure::             Using Configure
  39 * What Configure Does::         What Configure Does
  40 * Porting::                     Porting with Configure
  41 * Known Bugs::                  Known Bugs
  42 * Variables Index::             Variable Index
  43 * Concept Index::               Concept Index
  44
  45  --- The Detailed Node Listing ---
  46
  47 Using Configure
  48
  49 * Install Locations::           Where to install things once they are built
  50 * Build Directories::           Where to build object files
  51 * Host::                        Telling @code{configure} what will source will
  52                           be built
  53 * Target::                      Telling @code{configure} what the source will
  54                           target
  55 * Local Conventions::           Adding information about local conventions
  56
  57 Install Locations
  58
  59 * prefix::                      Changing the default install directory
  60 * datadir::                     How to separate host independent files
  61                           from host dependent files when
  62                           installing for multiple hosts
  63 * Install Details::             Full descriptions of all installation
  64                           subdirectories
  65
  66 Porting with Configure
  67
  68 * Native Ports::                Native Ports
  69 * Adding Hosts Or Targets::     Adding Hosts Or Targets
  70 * Reference::                   Reference
  71
  72 Native Ports
  73
  74 * Add A Host::                  Add A Host
  75 * Port An Existing Target::     Port An Existing Target
  76 * Add A Target::                Add A Target
  77 * Build Host & Target::         Build Host & Target
  78 * Build New Target On Some Other Host::  Build New Target On Some Other Host
  79
  80 Adding Hosts Or Targets
  81
  82 * Add Canonical Triple To Config.Subr (Cf Config.Subr)::  Add Canonical Triple To Config.Subr (Cf Config.Subr)
  83 * (Optional) Add Alias (Cf Config.Subr)::
  84 * Monte Carlo - Configure ; Make::  Monte Carlo - Configure ; Make
  85 * Remedies::                    Remedies
  86 * Adding Configure To Existing Programs::  Adding Configure To Existing Programs
  87
  88 Remedies
  89
  90 * Automagic Config::            Automagic Config
  91 * Symlinked Files::             Symlinked Files
  92 * Makefile Fragments (Cf Configure.In)::  Makefile Fragments (Cf Configure.In)
  93
  94 Adding Configure To Existing Programs
  95
  96 * Makefile Support::            Makefile Support
  97 * Add Standard Macros (Template Follows)::  Add Standard Macros (Template Follows)
  98
  99 Adding Configure To Existing Programs
 100
 101 * Makefile Host Support - Move It To Host Fragments::  Makefile Host Support - Move It To Host Fragments
 102 @end menu
 103 @end ifinfo
 104
 105 @node Invoking, Using Configure, top, top
 106 @chapter Invoking
 107
 108 The usual way to invoke @code{configure} is as follows:
 109 @example
 110 configure @var{host}
 111 @end example
 112 This asks @code{configure} to prepare the source to be compiled in a
 113 @var{host} environment with programs and files to be installed in
 114 @file{/usr/local}.
 115
 116 NOTE: support for multiple hosts is at least temporarily suspended.
 117 FIXME-soon
 118
 119 If more than one host is specified on the command line, then
 120 configurations are created for each and @code{-subdirs} is assumed.
 121
 122 @table @code
 123
 124 @item -datadir=@var{dir}
 125 This option requests that the source be configured so that host
 126 independent files will be installed in @var{dir}.
 127
 128 This option sets the @code{configure} variable @code{datadir}.  If
 129 @code{datadir} is not empty, generated Makefiles will have their
 130 @code{datadir} variables set to this value. (See @xref{Install Details}.)
 131
 132 @item -gas
 133 Notifies @code{configure} that the @sc{GNU} assembler is available on
 134 all specified hosts.
 135
 136 @item -help
 137 Displays a quick summary of how to invoke @code{configure}.
 138
 139 @item -host=@var{host}
 140 FIXME-soon: I don't think this option should be documented.
 141
 142 NOTE: support for this @code{-namesubdir=} is at least temporary
 143 suspended. FIXME-soon
 144
 145 @item -namesubdir=@var{name}
 146 Asks that any subdirectories created by the @code{-subdirs} option be
 147 named @var{name}.  Note that using multiple hosts with
 148 @code{-namesubdir=} isn't terribly useful.
 149
 150 @item -nfp
 151 Notifies @code{configure} that all of the specified hosts have @emph{no
 152 floating point} units.
 153
 154 @item -norecursion
 155 Asks @code{configure} to configure only this directory.  Any
 156 subdirectories are ignored.  This is used by the executable shell script
 157 @file{config.status} to reconfigure the current directory.
 158 (@xref{FIXME-now:config.status}.
 159
 160 @item -objdir=@var{dir}
 161 This option is no longer supported.  Use @code{-srcdir=} instead.
 162
 163 @item -prefix=@var{dir}
 164 This option requests that the source be configured so that programs and
 165 files will be installed in @var{dir}.
 166
 167 This option sets the @code{configure} variable @code{prefix}.  If
 168 @code{prefix} is not empty, generated Makefiles will have their
 169 @code{prefix} variables set to this value. (See @xref{Install Details}.)
 170
 171 @item -recurring
 172 This option is used internally by @code{configure} when recurring on
 173 subdirectories.  It's sole purpose is to supress status output.  It can
 174 be overriden with the @code{-verbose} option.
 175
 176 @item -rm
 177 Asks @code{configure} to @emph{remove} a configuration rather than
 178 create one.
 179
 180 @item -site=@var{site}
 181 Asks that Makefiles be generated using site specific Makefiles for
 182 @var{site}.  (@xref{FIXME-now: site specific Makefiles}.)
 183
 184 @item -srcdir=@var{_dir}
 185 Tells @code{configure} that the sources are located in @var{dir}.  The
 186 build directory is assumed to be @file{.}.
 187
 188 NOTE: support for this @code{-subdirs} is at least temporary suspended.
 189 FIXME-soon
 190
 191 @item -subdirs
 192 Asks that configurations be placed in subdirectories named
 193 @file{H-@var{host}} of each build directory, for each host specified.
 194 If this configuration is not native, (@var{host} is not @var{target}),
 195 then he subdir will be named @file{X-@var{host}-@var{target}} instead.
 196
 197 NOTE: support for multiple targets is at least temporarily suspended.
 198 FIXME-soon
 199
 200 @item -target=@var{target}
 201 Requests that the sources be configured to target the @var{target}
 202 machine.  If no targets are specified explicitly, the target is assumed
 203 to be the same as the host.  If multiple targets are specified,
 204 configurations for each are created and @code{-subdirs} is assumed.
 205
 206 @item -tmpdir=@var{tmpdir}
 207 Sets the directory in which @code{configure} creates temporary files to
 208 @var{tmpdir}.
 209
 210 @item -verbose
 211 @item -v
 212 Asks that @code{configure} print status lines for each directory
 213 configured.  Normally, only the status lines for the current directory
 214 are printed.
 215
 216 @item -x
 217 Tells @code{configure} that @sc{MIT} style @sc{X11} header files and
 218 libraries are available on this machine, even if they are not normally
 219 available.
 220
 221 @end table
 222
 223 @node Using Configure, What Configure Does, Invoking, top
 224 @chapter Using Configure
 225
 226 Configure prepares source directories in anticipation of building.
 227 Source cannot be built until it has been configured.  The choices
 228 and options available at configuration time generally have valid
 229 defaults, but the defaults do not cover all cases.  The choices
 230 available include:
 231
 232 @menu
 233 * Install Locations::           Where to install things once they are built
 234 * Build Directories::           Where to build object files
 235 * Host::                        Telling @code{configure} what will source will
 236                           be built
 237 * Target::                      Telling @code{configure} what the source will
 238                           target
 239 * Local Conventions::           Adding information about local conventions
 240 @end menu
 241
 242 @node Install Locations, Build Directories, Using Configure, Using Configure
 243 @section Install Locations
 244
 245 @cindex Where to install
 246
 247 Using the default configuration, @code{make install} will create a
 248 single tree of files, some of which are programs.  The location of this
 249 tree is determined by the value of the variable @code{$(prefix)}.  The
 250 default value of @code{$(prefix)} is @file{/usr/local}.  This is
 251 probably correct for native tools installed on only one host.
 252
 253 @menu
 254 * prefix::                      Changing the default install directory
 255 * datadir::                     How to separate host independent files
 256                           from host dependent files when
 257                           installing for multiple hosts
 258 * Install Details::             Full descriptions of all installation
 259                           subdirectories
 260 @end menu
 261
 262 @node prefix, datadir, Install Locations, Install Locations
 263 @subsection Changing the default install directory
 264
 265 @cindex Changing the default install directory
 266 @cindex Prefix directory
 267
 268 In the default configuration, all files are installed in subdirectories
 269 of @file{/usr/local}.  The actual location is determined by the value of
 270 the @code{configure} variable @code{$@{prefix@}} which determines the
 271 value of the Makefile variable @code{$(prefix)}.
 272
 273 You can also set the value of the Makefile variable @code{$(prefix)}
 274 explicitly each time you invoke @code{make} if you are so inclined, but
 275 because many programs have this location compiled in, you must specify
 276 the @code{$(prefix)} value precisely on each invocation of @code{make}
 277 or you will end up with a broken installation.
 278
 279 To make this easier, the value of the @code{configure} variable
 280 @code{$@{prefix@}} can be set on the command line to @code{configure}
 281 using the option @code{-prefix=}.  (See @xref{prefix}).
 282
 283
 284 @node datadir, Install Details, prefix, Install Locations
 285 @subsection Installing for multiple hosts
 286
 287 @cindex Configuring for multiple hosts
 288 @cindex Sharing host independent files
 289 @cindex The datadir directory
 290 @cindex Installing host independent files
 291
 292 Host independent files are installed in subdirectories of
 293 @file{/usr/local/lib}.  The actual location is determined by the value
 294 of the @code{configure} variable @code{$@{datadir@}} which determines
 295 the value of the Makefile variable @code{$(datadir)}.  By default, the
 296 value of @code{$@{datadir@}} is @code{$@{prefix@}/lib}.  This makes
 297 single host installs simple, and simplifies changing the default
 298 location for the install tree, but doesn't allow for multiple hosts to
 299 effectively share host independent files.
 300
 301 To configure so that multiple hosts can share common files, use
 302 something like:
 303
 304 @example
 305 configure @var{host1} -prefix=/usr/gnu/H-@var{host1} -datadir=/usr/gnu/H-independent
 306 make all info install install-info clean
 307 configure @var{host2} -prefix=/usr/gnu/H-@var{host2} -datadir=/usr/gnu/H-independent
 308 make all info install install-info
 309 @end example
 310
 311 The first line configures the source for @var{host1} in such a way that
 312 host specific programs will be placed in subdirectories of
 313 @file{/usr/gnu/H-@var{host1}} and host independent files will be placed
 314 in @file{/usr/gnu/H-independent}.  (See @xref{datadir}.)
 315
 316 The second line builds and installs all programs for @var{host1},
 317 including both host independent and host dependent files.
 318
 319 The third line reconfigures the source for @var{host2} in such a way
 320 that host specific programs will be placed in subdirectories of
 321 @file{/usr/gnu/H-@var{host2}} and host independent files will again be
 322 placed in @file{/usr/gnu/H-independent}.
 323
 324 The fourth line builds and installs all programs for @var{host2}.  Host
 325 dependent files will be installed in new directories but the host
 326 independent files will be installed @emph{on top of} the host
 327 independent files installed for @var{host1}.  This results in a single
 328 copy of the host independent files suitable for use by both hosts.
 329
 330 NOTE: support for -subdirsa and multiple hosts is at least temporarily
 331 suspended. FIXME-soon
 332
 333 Previously this was:
 334
 335 @example
 336 configure @var{host1} @var{host2} -prefix=/usr/gnu
 337 @end example
 338
 339 @node Install Details,  , datadir, Install Locations
 340 @subsection Full descriptions of all installation subdirectories
 341
 342 In any install, a number of standard directories are created.  Their
 343 actual names are determined by Makefile variables.  Some of the
 344 defaults for Makefile variables can be changed at configure time using
 345 command line options to @code{configure}.  For more information on the
 346 standard directories or the Makefile variables, please refer to
 347 @cite{standards.text}.
 348
 349 Note that @code{configure} does not create @code{srcdir} at any time.
 350 The directory @code{srcdir} is not an installation directory.
 351 (@xref{FIXME-now}.)
 352
 353 All makefile variables can be overridden on the command line to
 354 @code{make}.  (See @xref{Overriding, Overriding Variables, Overriding
 355 Variables, make, Make}.)  If you do so, you will need to specify the
 356 value precisely the same way for each invocation of @code{make} or you
 357 risk ending up with a broken installation.  This is because many
 358 programs have the locations of other programs or files compiled into
 359 them.  If you find yourself overriding any of the variables frequently,
 360 you should consider site depedent Makefile fragments.  (See @xref{FIXME-now}.)
 361
 362 During @code{make install}, the following standard directories will be
 363 created and populated:
 364
 365 @vindex prefix
 366 @defvr {Makefile and configure} prefix
 367 By default, the value of this variable determines the root of the
 368 installation tree.  It may be overridden with the @code{-srcdir=}
 369 command line option to @code{configure}.  (@xref{Invoking}.)  The
 370 default value for @code{prefix} is @file{/usr/local}.
 371 @end defvr
 372
 373 @vindex bindir
 374 @defvr Makefile bindir
 375 The value of this variable names a directory intended to contain binary
 376 programs that users can run.  The default value for @code{bindir}
 377 depends on @code{prefix} so @code{bindir} is normally changed
 378 only indirectly through @code{prefix}.  The default value for
 379 @code{$(bindir)} is @code{prefix}@file{/bin}.
 380 @end defvr
 381
 382 @vindex datadir
 383 @defvr {Makefile and configure} datadir
 384 The value of this variable names a directory intended to contain host
 385 independent files.  The @code{configure} variable, which is used to set
 386 the default value of the Makefile variable, can be set at configure time
 387 using the @code{-datadir=} option to @code{configure}.
 388 (@xref{Invoking}.)  The default value for @code{datadir} is
 389 @code{prefix}@file{/lib}.
 390 @end defvr
 391
 392 @vindex libdir
 393 @defvr Makefile libdir
 394 The value of this variable names a directory intended to hold libraries
 395 and support programs.  The default value for @code{libdir}
 396 depends on @code{prefix} so @code{libdir} is normally changed
 397 only indirectly through @code{prefix}.  The default value for
 398 @code{libdir} is @code{prefix}@file{/lib}.
 399 @end defvr
 400
 401 @vindex mandir
 402 @defvr Makefile mandir
 403 The value of this variable names a directory intended to hold @emph{man}
 404 format man pages.  The default value for @code{mandir}
 405 depends on @code{prefix} so @code{mandir} is normally changed
 406 only indirectly through @code{prefix}.  The default value for
 407 @code{mandir} is @code{datadir}@file{/man}.
 408 @end defvr
 409
 410 @vindex man@var{N}dir
 411 @defvr Makefile man@var{N}dir
 412 There are eight of these variables named @code{man1dir}, @code{man2dir},
 413 etc.  They are intended to name the specific directories which hold the
 414 man pages of their respective sections.  That is, @code{man1dir} holds
 415 @file{emacs.1}, the man page for the emacs program while @code{man5dir}
 416 holds the man page describing the @code{rcs} data file format, called
 417 @file{rcsfile.5}.  The default value for @code{man@var{N}dir}
 418 depends on @code{prefix} so @code{man@var{N}dir} is normally changed
 419 only indirectly through @code{prefix}.  The default value for
 420 @code{man@var{N}dir} is @code{mandir}@file{/man@var{N}}.
 421 @end defvr
 422
 423 @vindex manext
 424 @defvr Makefile manext
 425 The makefile variable manext is not supported by the @code{configure}.
 426 The @sc{gnu} coding standards do not call for @code{man1ext},
 427 @code{man2ext}, so the intended use for @code{manext} is not clear.
 428 (See also @xref{FIXME-now:extensions}.)
 429 @end defvr
 430
 431 @vindex infodir
 432 @defvr Makefile infodir
 433 The value of this variable names a directory intended to hold
 434 @emph{info} format documentation.  The default value for @code{infodir}
 435 depends on @code{prefix} so @code{infodir} is normally changed
 436 only indirectly through @code{prefix}.  The default value for
 437 @code{infodir} is @code{datadir}@file{/info}.
 438 @end defvr
 439
 440 @vindex docdir
 441 @defvr Makefile docdir
 442 The value of this variable names a directory intended to hold any
 443 documentation that is in a format other than @emph{info} or @emph{man}.
 444 The default value for @code{docdir} depends on @code{prefix} so
 445 @code{docdir} is normally changed only indirectly through @code{prefix}.
 446 The default value for @code{docdir} is @code{datadir}@file{/doc}.  Note
 447 that this variable is an extension to the @sc{gnu} coding standards.
 448 (See also @xref{FIXME-now:extensions}.)
 449 @end defvr
 450
 451 @vindex includedir
 452 @defvr Makefile includedir
 453 The value of this variable names a directory intended to hold the
 454 headers files that accompany the libraries installed in @code{libdir}.
 455 The default value for @code{includedir} depends on @code{prefix} so
 456 @code{includedir} is normally changed only indirectly through @code{prefix}.  The default value for
 457 @code{includedir} is @code{prefix}@file{/include}.
 458 @end defvr
 459
 460
 461 @node Build Directories, Host, Install Locations, Using Configure
 462 @section Build Directories
 463
 464 @cindex Build directories
 465 @cindex objdir
 466 @cindex Object directories
 467 @cindex subdirs
 468 @cindex Building for multiple hosts
 469 @cindex Building for multiple targets
 470
 471 Normally, @code{configure} builds @file{Makefile}'s and symbolic links
 472 in the same directory as the source files.  This is the typical
 473 @sc{un*x} way to build programs but it has limitations.  For instance,
 474 using this approach, you can only build for one host at a time.
 475
 476 We refer to the directories in which @code{configure} builds
 477 @file{Makefile}'s as the @emph{build directories} or sometimes as
 478 @emph{objdir} because these are the directories in which @code{make}
 479 will build object files, among other things.
 480
 481 The default build directory is the same as the source directory.
 482
 483 You can change the build directory with a sequence like the following:
 484
 485 @example
 486 mkdir @var{builddir}
 487 cd @var{builddir}
 488 configure @var{host} -srcdir=@var{sourcedirectory}
 489 @example
 490
 491 where @var{builddir} is the directory in which you wish to build,
 492 @var{host} is the host for which you want to build, and
 493 @var{sourcedirectory} is the directory containing the source files.
 494
 495 If you were to do this twice with different values for @var{builddir}
 496 and @vr{host}, then you could @code{make} for both at the same time.
 497
 498 NOTE: The rest of this section describes the @code{-subdirs} feature for
 499 which support is at least temporarily suspended.  FIXME-soon.
 500
 501 Another way to specify the build directory is with the @code{-subdirs}
 502 option.  For example:
 503
 504 @example
 505 configure @var{host} -subdirs
 506 @end example
 507
 508 Using this option, @code{configure} will create a subdirectory named
 509 @file{H-@var{host}} to act as the build directory for each source
 510 directory.
 511
 512 Since building for multiple hosts is so common, @code{configure}
 513 recognizes this situation as special.  For example:
 514
 515 @example
 516 configure @var{host1} @var{host2}
 517 @end example
 518
 519 is precisely the same as:
 520
 521 @example
 522 configure @var{host1} -subdirs
 523 configure @var{host2} -subdirs
 524 #end example
 525
 526 That is, when configuring for multiple hosts or multiple targets,
 527 @code{-subdir} is assumed.
 528
 529 When configuring for cross tools, that is, the host is not the target,
 530 as in:
 531
 532 @example
 533 configure @var{host} +target=@var{targ} -subdirs
 534 @end example
 535
 536 the subdirectories are named @file{X-@var{host}-@var{targ}}.  This is
 537 especially useful when configuring for multiple targets.
 538
 539 If both @code{-subdirs} and @code{-srcdir=} are given, a tree that
 540 parallels the source directory structure is created in the current
 541 directory, except that the current directory represents the source
 542 directory itself, and the subdirectories are created in this directory
 543 tree rather than in the source directories.
 544
 545 NOTE: previously, -subdirs built two level subdirectories as
 546 ./H-host/T-target, created ./H-host/Makefile for building across all
 547 targets, ./Makefile for building across all hosts, and ./config.status
 548 and ./H-host/config.status for rebuilding these Makefiles.
 549
 550 @node Host, Target, Build Directories, Using Configure
 551 @section Host
 552
 553 NOTE: support for multiple hosts is at least temporarily suspended.
 554 FIXME-soon.
 555
 556 The arguments to @code{configure} are @emph{hosts}.  By @emph{host} we
 557 mean the environment in which the source will be compiled.  This need
 558 not necessarily be the same as the actual physical machine involved,
 559 although it usually is.
 560
 561 For example, if some obscure machine running an operating system other
 562 than @sc{un*x} actually had the @sc{gnu} @sc{posix} emulation libraries
 563 available, it would be possible to configure most @sc{gnu} source for a
 564 @sc{posix} system and build it on the obscure host.
 565
 566 For more on this topic, see @xref{Host Environments, , cfg-paper, On
 567 Configuring Development Tools}.
 568
 569 @node Target, Local Conventions, Host, Using Configure
 570 @section Target
 571
 572 For building native development tools, or most of the other tools in the
 573 @sc{gnu} collection, you need not worry about the target.  The
 574 @emph{target} of a configuration defaults to the same as the
 575 @emph{host}.
 576
 577 For building cross development tools, please see @xref{Building
 578 Development Environments, , cfg-paper, On Configuring Development
 579 Tools}.
 580
 581 @node Local Conventions,  , Target, Using Configure
 582 @section Local Conventions
 583
 584 If you find that a tool does not get configured to your liking or that
 585 @code{configure}'s conventions are not your local conventions, you
 586 should probably consider site specific Makefile fragments.  (see
 587 @xref{FIXME-now: site specific makefile fragments})
 588
 589 These are probably not the right choice for options that can be set from
 590 the @code{configure} command line or for differences that are host or
 591 target dependent.
 592
 593
 594 @node What Configure Does, Porting, Using Configure, top
 595 @chapter What Configure Does
 596
 597 When configure runs, it does the following things for each source
 598 directory for each host and target combination.
 599
 600 NOTE: support for multiple hosts and targets is at least temporarily
 601 suspended.
 602
 603 @itemize @bullet
 604
 605 @item Create Build Directories
 606 (see @xref{Build Directories}) When @code{configure} is run with the
 607 @code{-srcdir=} option, a directory tree is created that parallels the
 608 directory structure of the source directory except that the current
 609 directory is treated as the build directory for the source directory
 610 proper.  (see @xref{Invoking}).
 611
 612 NOTE: support for @code{-subdirs} is at least temporarily suspended.
 613
 614 When @code{configure} is run with the @code{-subdirs} option, a build
 615 directory is created in each source directory.
 616
 617 If both @code{-subdirs} and @code{-srcdir=} are given, a tree that
 618 parallels the source directory structure is created in the current
 619 directory, except that the current directory represents the source
 620 directory itself, and the subdirectories are created in this directory
 621 tree rather than in the source directories.
 622
 623 @item Generate Makefiles
 624 A makefile template, usually called @file{Makefile.in} from the source
 625 directory is copied to an output file in the build directory.  The
 626 output file is usually named @file{Makefile}.  A number of makefile
 627 macros are prepended to the output file.  If @code{-prefix=} or
 628 @code{-datadir=} were specified on the @code{configure} command line,
 629 then the makefile variables are set accordingly.  If host, target, or
 630 site, specific makefile fragments exist, they are inserted into the
 631 output file.  (see @xref{Makefiles, , , make, Makefiles})
 632
 633 @item Generate .gdbinit
 634 If the source directory contains a .gdbinit file and the build directory
 635 is different from the source directory, a .gdbinit file is created in
 636 the build directory.  (see @xref{Command Files, , , gdb, Command Files})
 637
 638 @item Make Symbolic Links
 639 Most directories have some symbolic links with generic names built
 640 pointing to specific files in the source directory.  If the system on
 641 which @code{configure} is run cannot support symbolic links, then hard
 642 links are used instead.
 643
 644 @item Miscellaneous
 645 If the source directory has special needs, they are handled.  Usually
 646 there are none, but sometimes they involve changes to the output
 647 makefile.
 648
 649 @item Generate config.status
 650 A shell script named @file{config.status} is created in the build
 651 directory.  This shell script, when run from the build directory, will
 652 reconfigure the build directory except that subdirectories are not
 653 reconfigured.  This is most often used by @code{make} to rebuild the
 654 output makefile.  (see @xref{Top, , , bash})
 655
 656 @item Recursion
 657 If the source directory has subdirectories that should also be
 658 configured, then @code{configure} is called for each.
 659
 660 @end itemize
 661
 662 @node Porting, Known Bugs, What Configure Does, top
 663 @chapter Porting with Configure
 664
 665 This section explains briefly how to port configure for:
 666
 667 @menu
 668 * Programs::    Adding configure to existing programs
 669 * Hosts::       Adding new hosts to existing programs
 670 * Targets::     Adding new targets to existing programs
 671 * Reference::   Reference
 672 @end menu
 673
 674 @node Programs,  , Remedies, Adding Hosts Or Targets
 675 @subsection Adding Configure To Existing Programs
 676
 677 If you are writing a new program, don't worry about porting issues or
 678 configure until it is running reasonably on some host.  Then refer
 679 back to this section.
 680
 681 If your
 682
 683 @c marker
 684
 685 @menu
 686 * Makefile Support::            Makefile Support
 687 * Add Standard Macros (Template Follows)::  Add Standard Macros (Template Follows)
 688 @end menu
 689
 690 @node Makefile Support, Add Standard Macros (Template Follows), Adding Configure To Existing Programs, Adding Configure To Existing Programs
 691 @subsubsection Makefile Support
 692
 693
 694 @menu
 695 * Makefile Host Support - Move It To Host Fragments::  Makefile Host Support - Move It To Host Fragments
 696 @end menu
 697
 698
 699 @node Add Standard Macros (Template Follows),  , Makefile Support, Adding Configure To Existing Programs
 700 @subsubsection Add Standard Macros (Template Follows)
 701
 702 @itemize @bullet
 703 @item as defined in standards.text
 704 @item also add
 705
 706 @itemize @minus
 707 @item includedir
 708 This macro defines the directory in which to install any headers files that should be made available to users.
 709 @item docdir
 710 This macro defines where to install any documentation that is not either a man page or an info file.  For man pages, see mandir,
 711 for info, see infodir.
 712 @end itemize
 713
 714 @item template
 715
 716 @example
 717
 718 # Makefile for GNU tar program.
 719
 720 #
 721 # Makefile
 722 #   Copyright (C) 1990, 1991 Cygnus Support
 723 #
 724 # This file is free software; you can redistribute it and/or modify
 725 # it under the terms of the GNU General Public License as published by
 726 # the Free Software Foundation; either version 2 of the License, or
 727 # (at your option) any later version.
 728 #
 729 # This program is distributed in the hope that it will be useful,
 730 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 731 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 732 # GNU General Public License for more details.
 733 #
 734 # You should have received a copy of the GNU General Public License
 735 # along with this program; if not, write to the Free Software
 736 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 737 #
 738
 739 srcdir = .
 740
 741 prefix = /usr/local
 742
 743 bindir = $(prefix)/bin
 744 datadir = $(prefix)/lib
 745 libdir = $(prefix)/lib
 746 mandir = $(datadir)/man
 747 man1dir = $(mandir)/man1
 748 man2dir = $(mandir)/man2
 749 man3dir = $(mandir)/man3
 750 man4dir = $(mandir)/man4
 751 man5dir = $(mandir)/man5
 752 man6dir = $(mandir)/man6
 753 man7dir = $(mandir)/man7
 754 man8dir = $(mandir)/man8
 755 man9dir = $(mandir)/man9
 756 infodir = $(datadir)/info
 757 includedir = $(prefix)/include
 758 docdir = $(datadir)/doc
 759
 760 SHELL = /bin/sh
 761
 762 INSTALL = install -c
 763 INSTALL_PROGRAM = $(INSTALL)
 764 INSTALL_DATA = $(INSTALL)
 765
 766 AR = ar
 767 AR_FLAGS = qv
 768 BISON = bison
 769 MAKEINFO = makeinfo
 770 RANLIB = ranlib
 771
 772 # In order to disable remote-tape support, add -DNO_REMOTE to the
 773 # appropriate DEFS line, and remove rtape_lib.* from LOCAL_@{SRC,OBJ@}
 774 # For Ultrix 3.1, you will have to compile rtape_lib.c with -DUSG.
 775 # Add -DUSE_REXEC to use rexec for remote tape operations
 776 # instead of forking rsh or remsh.
 777 #
 778 # If tar fails to properly print error msgs, or core-dumps doing same,
 779 # you may need to change which version of msg...() you are using.
 780 # To do so, add one of the following to your DEFS= line
 781 # -DSTDC_MSG            If you are using an ANSI compiler, and have vfprintf().
 782 # -DVARARGS_MSG         If you have varargs.h and vfprintf()
 783 # -DDOPRNT_MSG          If you have _doprnt(), and no useful varargs support
 784 # -DLOSING_MSG          If nothing else works.
 785 #
 786 # Some non-BSD systems may have to add -DNEED_TZSET in order to have getdate.y
 787 # compile correctly.
 788 #
 789 # If you have a system V system which defines size_t, add -DHAVE_SIZE_T.
 790 # If you have a system which defines strstr, add -DHAVE_STRSTR.
 791 #
 792 # If you can't use remote tar with the rmt library, you can still get
 793 # some stuff to work right by adding -DUSE_REXEC.
 794 #
 795 # Some people's systems define a prototype for signal handlers which
 796 # require them to be declared as void.  If you get such problems in
 797 # rtape_lib, function command, then define -DSIGNAL_VOID.
 798 #
 799 # getdate.y has 8 shift/reduce conflicts.
 800 #
 801 # In addition to setting DEFS appropriately for your system, you might
 802 # have to hand edit the #defines and #undefs in port.c.
 803 #
 804
 805 ## GNU version
 806 DEFS = -DBSD42
 807 LOCAL_SRC =
 808 LOCAL_OBJ =
 809 LDFLAGS =
 810 LIBS =  -lutils
 811 LINT = lint
 812 LINTFLAGS = -abchx
 813 DEF_AR_FILE = \"-\"
 814 DEFBLOCKING = 20
 815 O = o
 816 @end example
 817
 818 #### Host, target, and site specific Makefile fragments come in here.
 819 ###
 820
 821 @itemize @bullet
 822 @item           Identify Nonstandard Macros
 823 @itemize @minus
 824 @item                           Put Defaults Before The Fragment Hook (Cf)
 825 @item                           Move Non-Defaults To Makefile Fragments (Cf)
 826 @item                           Map To Those Fragments In Configure.In (Cf)
 827 @end itemize
 828
 829 @item           Fragment Hook
 830
 831 @itemize @minus
 832 @item                           Should Follow Standard And Non-Standard Macros
 833 @item                           Should Preceed All Targets
 834 @item                           Looks Like
 835 #### Host, target, and site specific Makefile fragments come in here.
 836 ###
 837
 838 The line beginning with four hashes is the important part.  The comment and the line beginning with three hashes are only
 839 a conventional convenience.
 840 @end itemize
 841
 842 @item           Makefile Fragments
 843 @item                           Host
 844 @item                           Target
 845 @item                           Site
 846 @item Mv Makefile Makefile.In
 847 @item           Standard Targets
 848 @item                           All (Should Be The Default)
 849 @item                           Install
 850 @item                           Clean
 851 @item                           Info
 852 @item                           Install-Info
 853 @item                           Clean-Info
 854 @item The Config Subdirectory
 855 @item Configure.In
 856 @item           Declarations
 857 @item                           Srctrigger
 858 @item                           Srcname
 859 @item                           Configdirs
 860 @item                           Target_Dependent
 861 @item           Per-Host
 862 @item           Per-Target
 863 @item           Post-Target
 864 @item           Available Variables
 865
 866 @defvar{host}
 867 Contains the actual name that the user entered for the host.  Since many
 868 things that the user could enter would map to the same canonical triple,
 869 this variable is innappropriate to use for picking available
 870 configurations.  For that, use @code{host_cpu}, @code{host_vendor},
 871 and/or @code{host_os}.  This variable is useful, however, for error
 872 messages.
 873 @end defvar
 874
 875 @defvar{host_cpu}
 876 Contains the first element of the canonical triple representing the host
 877 as returned by @file{config.subr}.  This is occasionally used to
 878 distinguish between minor variations of a particular vendor's operating
 879 system and sometimes to determine variations in binary format between
 880 the host and the target.
 881 @end defvar
 882
 883 @defvar{host_vendor}
 884 Contains the second element of the canonical triple representing the
 885 host as returned by @file{config.subr}.  This is usually used to
 886 distinguish betwen the numerous variations between @emph{common}
 887 operating systems.
 888 @end defvar
 889
 890 @defvar{host_os}
 891 Contains the the third element of the canonical triple representing the
 892 host as returned by @file{config.subr}.
 893 @end defvar
 894
 895 @defvar{target}
 896 Contains the actual name that the user entered for the target.  Since many
 897 things that the user could enter would map to the same canonical triple,
 898 this variable is innappropriate to use for picking available
 899 configurations.  For that, use @code{target_cpu}, @code{target_vendor},
 900 and/or @code{target_os}.  This variable is useful, however, for error
 901 messages.
 902 @end defvar
 903
 904 @defvar{target_cpu}
 905 Contains the first element of the canonical triple representing the
 906 target as returned by @file{config.subr}.  This is used heavily by
 907 programs involved in building programs, like the compiler, assembler,
 908 linker, etc.  Most programs will not need the @code{target} variables at
 909 all, but this one could conceivably be used to build a program, for
 910 instance, that operated on binary data files whose byte order or
 911 alignment are other than that of the system on which the program is
 912 running.
 913 @end defvar
 914
 915 @defvar{target_vendor}
 916 Contains the second element of the canonical triple representing the
 917 target as returned by @file{config.subr}.  This is usually used to
 918 distinguish betwen the numerous variations between @emph{common}
 919 operating systems or object file formats.  Sometimes it is used to
 920 switch between different flavors of users interfaces.
 921 @end defvar
 922
 923 @defvar{target_os}
 924 Contains the the third element of the canonical triple representing the
 925 target as returned by @file{config.subr}.  This variable is used by
 926 development tools to distinguish between subtle variations in object
 927 file formats that some vendors use across operating system releases.  It
 928 might also be use to decide which libraries to build or what user
 929 interface the tool should provide.
 930 @end defvar
 931
 932 @defvar{nfp}
 933 Is set to @code{true} if the user invoked configure with the @code{-nfp}
 934 command line option, otherwise it is empty.  This is a request to target
 935 a machine with @emph{no floating point} unit, even if the machine ordinarily
 936 has a floating point unit available.  This option has no negation.
 937 @end defvar
 938
 939 @defvar{gas}
 940 Is set to @code{true} if the user invoked configure with the @code{-gas}
 941 command line option, otherwise it is empty.  This is a request to assume
 942 that the target machine has gas available even if it ordinarily does
 943 not.  The converse option, @code{-no-gas} is not available.
 944 @end defvar
 945
 946 @defvar{x}
 947 Is set to @code{true} if the user invoked configure with the @code{-x}
 948 command line option, otherwise it is empty.  This is a request to assume
 949 that @sc{mit x11} compatible headers files and libraries are available,
 950 regardless of what is normally available on this host.
 951 @end defvar
 952
 953 @defvar{srcdir}
 954 Is set to the name of the directory containing the source for this
 955 program.  This will be different from @file{.} if the user has
 956 specified either the @code{-srcdir=} or the @code{-subdirs} options.
 957 Note that @code{srcdir} is not necessarily an absolute path.
 958 @end defvar
 959
 960 @defvar{host_makefile_frag}
 961 Is set to a file name representing to the default Makefile fragment for
 962 this host.  It may be set in @file{configure.in} to overide this
 963 default.
 964 @end defvar
 965
 966 @defvar{target_makefile_frag}
 967 Is set to a file name representing to the default Makefile fragment for
 968 this target.  It may be set in @file{configure.in} to overide this
 969 default.
 970 @end defvar
 971
 972 @defvar{site_makefile_frag}
 973 Is set to a file name representing to the default Makefile fragment for
 974 this host.  It may be set in @file{configure.in} to overide this
 975 default.  Normally @code{site_makefile_frag} is empty, but will have a
 976 value if the user specified @code{-site=} on the command line.  This
 977 variable should probably not be overridden.
 978 @end defvar
 979
 980 @defvar{Makefile}
 981 Is set to the name of the generated @file{Makefile}.  Normally this
 982 value is precisely @file{Makefile} but some programs may want something
 983 else.
 984 @end defvar
 985
 986 @defvar{removing}
 987 Is normally empty but will be set to some non-empty value if the user
 988 specified @code{-rm} on the command line.  That is, if @code{removing}
 989 is non-empty, then configure is @emph{removing} a configuration rather
 990 than creating one.
 991 @end defvar
 992
 993 @defvar{files}
 994 If this variable is non-empty following the @code{per-target:} section,
 995 then each word in it's value will be the target of a symbolic link
 996 named in the @code{links} variable.
 997 @end defvar
 998
 999 @defvar{links}
1000 If the @code{files} variable is non-empty following the
1001 @code{per-target:} section, then symbolic links will be created with the
1002 first word of links pointing to the first word of files, the second word of
1003 links pointing to the second word of files, and so on.
1004 @end defvar
1005
1006 @end itemize
1007 @end itemize
1008
1009 @node Native Ports, Adding Hosts Or Targets, Porting, Porting
1010 @section Native Ports
1011
1012 To port a GNU tool that uses the Cygnus Configure system, do the
1013 following.
1014
1015 @itemize @asis
1016
1017 @item Add A Host
1018 @item Port An Existing Target
1019 @item Add A Target
1020 @item Build Host & Target
1021 @item Build New Target On Some Other Host
1022
1023 @end table
1024
1025 @node Adding Hosts Or Targets, Reference, Native Ports, Porting
1026 @section Adding Hosts Or Targets
1027
1028
1029
1030 @menu
1031 * Add Canonical Triple To Config.Subr (Cf Config.Subr)::  Add Canonical Triple To Config.Subr (Cf Config.Subr)
1032 * (Optional) Add Alias (Cf Config.Subr)::
1033 * Monte Carlo - Configure ; Make::  Monte Carlo - Configure ; Make
1034 * Remedies::                    Remedies
1035 * Adding Configure To Existing Programs::  Adding Configure To Existing Programs
1036 @end menu
1037
1038 @node Add Canonical Triple To Config.Subr (Cf Config.Subr), (Optional) Add Alias (Cf Config.Subr), Adding Hosts Or Targets, Adding Hosts Or Targets
1039 @subsection Add Canonical Triple To Config.Subr (Cf Config.Subr)
1040
1041
1042 @node (Optional) Add Alias (Cf Config.Subr), Monte Carlo - Configure ; Make, Add Canonical Triple To Config.Subr (Cf Config.Subr), Adding Hosts Or Targets
1043 @subsection (Optional) Add Alias (Cf Config.Subr)
1044
1045
1046 @node Monte Carlo - Configure ; Make, Remedies, (Optional) Add Alias (Cf Config.Subr), Adding Hosts Or Targets
1047 @subsection Monte Carlo - Configure ; Make
1048
1049
1050 @node Remedies, Adding Configure To Existing Programs, Monte Carlo - Configure ; Make, Adding Hosts Or Targets
1051 @subsection Remedies
1052
1053
1054 @menu
1055 * Automagic Config::            Automagic Config
1056 * Symlinked Files::             Symlinked Files
1057 * Makefile Fragments (Cf Configure.In)::  Makefile Fragments (Cf Configure.In)
1058 @end menu
1059
1060 @node Automagic Config, Symlinked Files, Remedies, Remedies
1061 @subsubsection Automagic Config
1062
1063
1064 @node Symlinked Files, Makefile Fragments (Cf Configure.In), Automagic Config, Remedies
1065 @subsubsection Symlinked Files
1066
1067
1068 @node Makefile Fragments (Cf Configure.In),  , Symlinked Files, Remedies
1069 @subsubsection Makefile Fragments (Cf Configure.In)
1070
1071 @node Reference,  , Adding Hosts Or Targets, Porting
1072 @section Reference
1073
1074
1075
1076 Automagic Configuration Should Be Used If Prep'D Files Don'T Exist.
1077
1078 @node Known Bugs, Variables Index, Porting, top
1079 @chapter Known Bugs
1080
1081 The following bugs are known to exist.
1082
1083 @itemize @bullet
1084
1085 @item
1086 There is no way to query about known hosts, known targets, or the
1087 porting or testing status of any configuration.
1088
1089 @item
1090 The negations to the options @code{-gas}, @code{-x}, and @code{-nfp} are
1091 not available.
1092
1093 @end itemize
1094
1095 @node Variables Index, Concept Index, Known Bugs, top
1096 @appendix Variable Index
1097
1098 @printindex vr
1099
1100 @node     Concept Index,  , Variables Index, top
1101 @appendix Concept Index
1102
1103 @printindex cp
1104 @contents
1105 @bye
1106
1107 @c Local Variables:
1108 @c fill-column: 79
1109 @c outline-regexp: "@chap"
1110 @c End:
1111 @c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")