1 \input texinfo @c -*-para-*-
3 @setfilename configure.info
4 @settitle Cygnus Configure
9 This document attempts to describe the Cygnus Support version of
12 Copyright (C) 1991 Cygnus Support
13 Permission is granted to make and distribute verbatim copies of
14 this manual provided the copyright notice and this permission notice
15 are preserved on all copies.
18 Permission is granted to process this file through TeX and print the
19 results, provided the printed document carries copying permission
20 notice identical to this one except for the removal of this paragraph
21 (this paragraph not being relevant to the printed manual).
24 Permission is granted to copy and distribute modified versions of this
25 manual under the conditions for verbatim copying, provided that the entire
26 resulting derived work is distributed under the terms of a permission
27 notice identical to this one.
29 Permission is granted to copy and distribute translations of this manual
30 into another language, under the above conditions for modified versions,
31 except that this permission notice may be stated in a translation approved
37 @title{Cygnus Configure}
38 @subtitle Edition ``$Revision$'' for Cygnus Configure version 1.84
39 @author{K. Richard Pixley, @code{rich@@cygnus.com}}
40 @author{Cygnus Support}
43 @vskip 0pt plus 1filll
44 Copyright @copyright{} 1991 Cygnus Support
46 Permission is granted to make and distribute verbatim copies of
47 this manual provided the copyright notice and this permission notice
48 are preserved on all copies.
50 Permission is granted to copy and distribute modified versions of this
51 manual under the conditions for verbatim copying, provided that the entire
52 resulting derived work is distributed under the terms of a permission
53 notice identical to this one.
55 Permission is granted to copy and distribute translations of this manual
56 into another language, under the above conditions for modified versions,
57 except that this permission notice may be stated in a translation approved
64 * configure: (configure.info). Cygnus configure.
68 @node top, Invoking, (dir), (dir)
71 This file documents the configuration system used and distributed by
74 NOTE: support for a Cygnus experimental option, @code{-subdirs} is at
75 least temporarily suspended. Most of the code is still in configure but
76 the option is disabled. This document describes that feature, but those
77 parts are prominently marked with NOTE's like this one. FIXME-soon
81 * Using Configure:: Using Configure
82 * What Configure Does:: What Configure Does
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
95 NOTE: support for a Cygnus experimental option, @code{-subdirs} is at
96 least temporarily suspended. Most of the code is still in configure but
97 the option is disabled. This document describes that feature, but those
98 parts are prominently marked with NOTE's like this one. FIXME-soon
101 @node Invoking, Using Configure, top, top
104 The usual way to invoke @code{configure} is as follows:
108 This asks @code{configure} to prepare the source to be compiled in a
109 @var{host} environment with programs and files to be installed in
112 NOTE: support for multiple hosts is at least temporarily suspended.
115 If more than one host is specified on the command line, then
116 configurations are created for each and @code{-subdirs} is assumed.
120 @item -datadir=@var{dir}
121 This option requests that the source be configured so that host
122 independent files will be installed in @var{dir}.
124 This option sets the @code{configure} variable @code{datadir}. If
125 @code{datadir} is not empty, generated Makefiles will have their
126 @code{datadir} variables set to this value. (See @xref{Install Details}.)
129 Notifies @code{configure} that the @sc{GNU} assembler is available on
133 Displays a quick summary of how to invoke @code{configure}.
135 @item -host=@var{host}
136 FIXME-soon: I don't think this option should be documented.
138 NOTE: support for this @code{-namesubdir=} is at least temporary
139 suspended. FIXME-soon
141 @item -namesubdir=@var{name}
142 Asks that any subdirectories created by the @code{-subdirs} option be
143 named @var{name}. Note that using multiple hosts with
144 @code{-namesubdir=} isn't terribly useful.
147 Notifies @code{configure} that all of the specified targets have
148 @emph{no floating point} units.
151 Asks @code{configure} to configure only this directory. Any
152 subdirectories are ignored. This is used by the executable shell script
153 @file{config.status} to reconfigure the current directory.
154 (see @xref{config.status}).
156 @item -objdir=@var{dir}
157 This option is no longer supported. Use @code{-srcdir=} instead.
159 @item -prefix=@var{dir}
160 This option requests that the source be configured so that programs and
161 files will be installed in @var{dir}.
163 This option sets the @code{configure} variable @code{prefix}. If
164 @code{prefix} is not empty, generated Makefiles will have their
165 @code{prefix} variables set to this value. (See @xref{Install Details}.)
168 This option is used internally by @code{configure} when recurring on
169 subdirectories. It's sole purpose is to supress status output. It can
170 be overriden with the @code{-verbose} option.
173 Asks @code{configure} to @emph{remove} a configuration rather than
176 @item -site=@var{site}
177 Asks that Makefiles be generated using site specific Makefiles for
178 @var{site}. See also @xref{Sites}.
180 @item -srcdir=@var{_dir}
181 Tells @code{configure} that the sources are located in @var{dir}. The
182 build directory is assumed to be @file{.}.
184 NOTE: support for this @code{-subdirs} is at least temporary suspended.
188 Asks that configurations be placed in subdirectories named
189 @file{H-@var{host}} of each build directory, for each host specified.
190 If this configuration is not native, (@var{host} is not @var{target}),
191 then he subdir will be named @file{X-@var{host}-@var{target}} instead.
193 NOTE: support for multiple targets is at least temporarily suspended.
196 @item -target=@var{target}
197 Requests that the sources be configured to target the @var{target}
198 machine. If no targets are specified explicitly, the target is assumed
199 to be the same as the host. If multiple targets are specified,
200 configurations for each are created and @code{-subdirs} is assumed.
202 @item -tmpdir=@var{tmpdir}
203 Sets the directory in which @code{configure} creates temporary files to
208 Asks that @code{configure} print status lines for each directory
209 configured. Normally, only the status lines for the current directory
213 Tells @code{configure} that @sc{MIT} style @sc{X11} header files and
214 libraries are available on the host, even if they are not normally
219 @node Using Configure, What Configure Does, Invoking, top
220 @chapter Using Configure
222 Configure prepares source directories in anticipation of building.
223 Source cannot be built until it has been configured. The choices
224 and options available at configuration time generally have valid
225 defaults, but the defaults do not cover all cases. The choices
226 available include install locations, build directories, host, target,
227 and local conventions.
230 * Install Locations:: Where to install things once they are built
231 * Build Directories:: Where to build object files
232 * Host:: Telling @code{configure} what will source will
234 * Target:: Telling @code{configure} what the source will
236 * Local Conventions:: Adding information about local conventions
239 @node Install Locations, Build Directories, Using Configure, Using Configure
240 @section Install Locations
242 @cindex Where to install
244 Using the default configuration, @code{make install} will create a
245 single tree of files, some of which are programs. The location of this
246 tree is determined by the value of the variable @code{prefix}. The
247 default value of @code{prefix} is @file{/usr/local}. This is
248 probably correct for native tools installed on only one host.
251 * prefix:: Changing the default install directory
252 * datadir:: How to separate host independent files
253 from host dependent files when
254 installing for multiple hosts
255 * Install Details:: Full descriptions of all installation
259 @node prefix, datadir, Install Locations, Install Locations
260 @subsection Changing the default install directory
262 @cindex Changing the default install directory
263 @cindex Prefix directory
265 In the default configuration, all files are installed in subdirectories
266 of @file{/usr/local}. The actual location is determined by the value of
267 the @code{configure} variable @code{prefix} which determines the
268 value of the Makefile variable @code{prefix}.
270 You can also set the value of the Makefile variable @code{prefix}
271 explicitly each time you invoke @code{make} if you are so inclined, but
272 because many programs have this location compiled in, you must specify
273 the @code{prefix} value precisely on each invocation of @code{make}
274 or you will end up with a broken installation.
276 To make this easier, the value of the @code{configure} variable
277 @code{prefix} can be set on the command line to @code{configure}
278 using the option @code{-prefix=}. (See @xref{prefix}).
281 @node datadir, Install Details, prefix, Install Locations
282 @subsection Installing for multiple hosts
284 @cindex Configuring for multiple hosts
285 @cindex Sharing host independent files
286 @cindex The datadir directory
287 @cindex Installing host independent files
289 Host independent files are installed in subdirectories of
290 @file{/usr/local/lib}. The actual location is determined by the value
291 of the @code{configure} variable @code{datadir} which determines
292 the value of the Makefile variable @code{datadir}. By default, the
293 value of @code{datadir} is @file{@var{prefix}/lib}. This makes
294 single host installs simple, and simplifies changing the default
295 location for the install tree, but doesn't allow for multiple hosts to
296 effectively share host independent files.
298 To configure so that multiple hosts can share common files, use
302 configure @var{host1} -prefix=/usr/gnu/H-@var{host1} -datadir=/usr/gnu/H-independent
303 make all info install install-info clean
304 configure @var{host2} -prefix=/usr/gnu/H-@var{host2} -datadir=/usr/gnu/H-independent
305 make all info install install-info
308 The first line configures the source for @var{host1} in such a way that
309 host specific programs will be placed in subdirectories of
310 @file{/usr/gnu/H-@var{host1}} and host independent files will be placed
311 in @file{/usr/gnu/H-independent}. (See @xref{datadir}.)
313 The second line builds and installs all programs for @var{host1},
314 including both host independent and host dependent files.
316 The third line reconfigures the source for @var{host2} in such a way
317 that host specific programs will be placed in subdirectories of
318 @file{/usr/gnu/H-@var{host2}} and host independent files will again be
319 placed in @file{/usr/gnu/H-independent}.
321 The fourth line builds and installs all programs for @var{host2}. Host
322 dependent files will be installed in new directories but the host
323 independent files will be installed @emph{on top of} the host
324 independent files installed for @var{host1}. This results in a single
325 copy of the host independent files suitable for use by both hosts.
327 NOTE: support for @code{-subdirs} and multiple hosts is at least
328 temporarily suspended. FIXME-soon
333 configure @var{host1} @var{host2} -prefix=/usr/gnu
336 @node Install Details, , datadir, Install Locations
337 @subsection Full descriptions of all installation subdirectories
339 In any install, a number of standard directories are created. Their
340 actual names are determined by Makefile variables. Some of the
341 defaults for Makefile variables can be changed at configure time using
342 command line options to @code{configure}. For more information on the
343 standard directories or the Makefile variables, please refer to
344 @cite{standards.text}.
346 Note that @code{configure} does not create @code{srcdir} at any time.
347 The directory @code{srcdir} is not an installation directory.
349 All makefile variables can be overridden on the command line to
350 @code{make}. (See @xref{Overriding, Overriding Variables, Overriding
351 Variables, make, Make}.) If you do so, you will need to specify the
352 value precisely the same way for each invocation of @code{make} or you
353 risk ending up with a broken installation. This is because many
354 programs have the locations of other programs or files compiled into
355 them. If you find yourself overriding any of the variables frequently,
356 you should consider site dependent Makefile fragments. See also
359 During @code{make install}, the following standard directories will be
360 created and populated:
363 @defvr {Makefile and configure} prefix
364 By default, the value of this variable determines the root of the
365 installation tree. It may be overridden with the @code{-srcdir=}
366 command line option to @code{configure}. (@xref{Invoking}.) The
367 default value for @code{prefix} is @file{/usr/local}.
371 @defvr Makefile bindir
372 The value of this variable names a directory intended to contain binary
373 programs that users can run. The default value for @code{bindir}
374 depends on @code{prefix} so @code{bindir} is normally changed
375 only indirectly through @code{prefix}. The default value for
376 @code{bindir} is @file{@var{prefix}/bin}.
380 @defvr {Makefile and configure} datadir
381 The value of this variable names a directory intended to contain host
382 independent files. The @code{configure} variable, which is used to set
383 the default value of the Makefile variable, can be set at configure time
384 using the @code{-datadir=} option to @code{configure}. (See also
385 @xref{Invoking}.) The default value for @code{datadir} is
386 @file{@var{prefix}/lib}.
390 @defvr Makefile libdir
391 The value of this variable names a directory intended to hold libraries
392 and support programs. The default value for @code{libdir}
393 depends on @code{prefix} so @code{libdir} is normally changed
394 only indirectly through @code{prefix}. The default value for
395 @code{libdir} is @file{@var{prefix}/lib}.
399 @defvr Makefile mandir
400 The value of this variable names a directory intended to hold @emph{man}
401 format man pages. The default value for @code{mandir}
402 depends on @code{prefix} so @code{mandir} is normally changed
403 only indirectly through @code{prefix}. The default value for
404 @code{mandir} is @file{@var{datadir}/man}.
407 @vindex man@var{N}dir
408 @defvr Makefile man@var{N}dir
409 There are eight of these variables named @code{man1dir}, @code{man2dir},
410 etc. They are intended to name the specific directories which hold the
411 man pages of their respective sections. That is, @code{man1dir} holds
412 @file{emacs.1}, the man page for the emacs program while @code{man5dir}
413 holds the man page describing the @code{rcs} data file format, called
414 @file{rcsfile.5}. The default value for @code{man@var{N}dir}
415 depends on @code{prefix} so @code{man@var{N}dir} is normally changed
416 only indirectly through @code{prefix}. The default value for
417 @code{man@var{N}dir} is @file{@var{mandir}/man@var{N}}.
421 @defvr Makefile manext
422 The makefile variable manext is not supported by the @code{configure}.
423 The @sc{gnu} coding standards do not call for @code{man1ext},
424 @code{man2ext}, so the intended use for @code{manext} is not clear.
425 (See also @xref{Makefile Extensions}.)
429 @defvr Makefile infodir
430 The value of this variable names a directory intended to hold
431 @emph{info} format documentation. The default value for @code{infodir}
432 depends on @code{prefix} so @code{infodir} is normally changed
433 only indirectly through @code{prefix}. The default value for
434 @code{infodir} is @file{@var{datadir}/info}.
438 @defvr Makefile docdir
439 The value of this variable names a directory intended to hold any
440 documentation that is in a format other than @emph{info} or @emph{man}.
441 The default value for @code{docdir} depends on @code{prefix} so
442 @code{docdir} is normally changed only indirectly through @code{prefix}.
443 The default value for @code{docdir} is @file{@var{datadir}/doc}. Note
444 that this variable is an extension to the @sc{gnu} coding standards.
445 (See also @xref{Makefile Extensions}.)
449 @defvr Makefile includedir
450 The value of this variable names a directory intended to hold the
451 headers files that accompany the libraries installed in @code{libdir}.
452 The default value for @code{includedir} depends on @code{prefix} so
453 @code{includedir} is normally changed only indirectly through @code{prefix}. The default value for
454 @code{includedir} is @file{@var{prefix}/include}.
458 @node Build Directories, Host, Install Locations, Using Configure
459 @section Build Directories
461 @cindex Build directories
463 @cindex Object directories
465 @cindex Building for multiple hosts
466 @cindex Building for multiple targets
468 Normally, @code{configure} builds a @file{Makefile} and symbolic links
469 in the same directory as the source files. This is the typical
470 @sc{un*x} way to build programs but it has limitations. For instance,
471 using this approach, you can only build for one host at a time.
473 We refer to the directories in which @code{configure} builds a
474 @file{Makefile} as the @emph{build directories} or sometimes as
475 @emph{objdir} because these are the directories in which @code{make}
476 will build object files, among other things.
478 The default build directory is the same as the source directory.
480 You can change the build directory with a sequence like the following:
485 configure @var{host} -srcdir=@var{sourcedirectory}
488 where @var{builddir} is the directory in which you wish to build,
489 @var{host} is the host for which you want to build, and
490 @var{sourcedirectory} is the directory containing the source files.
492 If you were to do this twice with different values for @var{builddir}
493 and @var{host}, then you could @code{make} for both at the same time.
495 NOTE: The rest of this section describes the @code{-subdirs} feature for
496 which support is at least temporarily suspended. FIXME-soon.
498 Another way to specify the build directory is with the @code{-subdirs}
502 configure @var{host} -subdirs
505 Using this option, @code{configure} will create a subdirectory named
506 @file{H-@var{host}} to act as the build directory for each source
509 Since building for multiple hosts is so common, @code{configure}
510 recognizes this situation as special. For example:
513 configure @var{host1} @var{host2}
516 is precisely the same as:
519 configure @var{host1} -subdirs
520 configure @var{host2} -subdirs
523 That is, when configuring for multiple hosts or multiple targets,
524 @code{-subdir} is assumed.
526 When configuring for cross tools, that is, the host is not the target,
530 configure @var{host} +target=@var{targ} -subdirs
533 the subdirectories are named @file{X-@var{host}-@var{targ}}. This is
534 especially useful when configuring for multiple targets.
536 If both @code{-subdirs} and @code{-srcdir=} are given, a tree that
537 parallels the source directory structure is created in the current
538 directory, except that the current directory represents the source
539 directory itself, and the subdirectories are created in this directory
540 tree rather than in the source directories.
542 NOTE: previously, -subdirs built two level subdirectories as
543 ./H-host/T-target, created ./H-host/Makefile for building across all
544 targets, ./Makefile for building across all hosts, and ./config.status
545 and ./H-host/config.status for rebuilding these Makefiles.
547 @node Host, Target, Build Directories, Using Configure
550 NOTE: support for multiple hosts is at least temporarily suspended.
553 The arguments to @code{configure} are @emph{hosts}. By @emph{host} we
554 mean the environment in which the source will be compiled. This need
555 not necessarily be the same as the actual physical machine involved,
556 although it usually is.
558 For example, if some obscure machine running an operating system other
559 than @sc{un*x} actually had the @sc{gnu} @sc{posix} emulation libraries
560 available, it would be possible to configure most @sc{gnu} source for a
561 @sc{posix} system and build it on the obscure host.
563 For more on this topic, see @xref{Host Environments, , cfg-paper, On
564 Configuring Development Tools}.
566 @node Target, Local Conventions, Host, Using Configure
569 For building native development tools, or most of the other tools in the
570 @sc{gnu} collection, you need not worry about the target. The
571 @emph{target} of a configuration defaults to the same as the
574 For building cross development tools, please see @xref{Building
575 Development Environments, , cfg-paper, On Configuring Development
578 @node Local Conventions, , Target, Using Configure
579 @section Local Conventions
581 If you find that a tool does not get configured to your liking or that
582 @code{configure}'s conventions are not your local conventions, you
583 should probably consider site specific Makefile fragments. See also
587 These are probably not the right choice for options that can be set from
588 the @code{configure} command line or for differences that are host or
592 @node What Configure Does, Porting, Using Configure, top
593 @chapter What Configure Does
595 When configure runs, it does the following things for each source
596 directory for each host and target combination.
598 NOTE: support for multiple hosts and targets is at least temporarily
603 @item Create Build Directories
604 (see @xref{Build Directories}) When @code{configure} is run with the
605 @code{-srcdir=} option, a directory tree is created that parallels the
606 directory structure of the source directory except that the current
607 directory is treated as the build directory for the source directory
608 proper. (see @xref{Invoking}).
610 NOTE: support for @code{-subdirs} is at least temporarily suspended.
612 When @code{configure} is run with the @code{-subdirs} option, a build
613 directory is created in each source directory.
615 If both @code{-subdirs} and @code{-srcdir=} are given, a tree that
616 parallels the source directory structure is created in the current
617 directory, except that the current directory represents the source
618 directory itself, and the subdirectories are created in this directory
619 tree rather than in the source directories.
621 @item Generate Makefiles
622 A makefile template, usually called @file{Makefile.in} from the source
623 directory is copied to an output file in the build directory. The
624 output file is usually named @file{Makefile}. A number of makefile
625 macros are prepended to the output file. If @code{-prefix=} or
626 @code{-datadir=} were specified on the @code{configure} command line,
627 then the makefile variables are set accordingly. If host, target, or
628 site, specific makefile fragments exist, they are inserted into the
629 output file. (see @xref{Makefiles, , , make, Makefiles}.)
631 @item Generate .gdbinit
632 If the source directory contains a .gdbinit file and the build directory
633 is different from the source directory, a .gdbinit file is created in
634 the build directory. (see @xref{Command Files, , , gdb, Command Files}.)
636 @item Make Symbolic Links
637 Most directories have some symbolic links with generic names built
638 pointing to specific files in the source directory. If the system on
639 which @code{configure} is run cannot support symbolic links, then hard
640 links are used instead.
643 If the source directory has special needs, they are handled. Usually
644 there are none, but sometimes they involve changes to the output
647 @item Generate config.status
648 A shell script named @file{config.status} is created in the build
649 directory. This shell script, when run from the build directory, will
650 reconfigure the build directory except that subdirectories are not
651 reconfigured. This is most often used by @code{make} to rebuild the
652 output makefile. (see @xref{Top, , , bash}.)
655 If the source directory has subdirectories that should also be
656 configured, then @code{configure} is called for each.
660 @node Porting, Reference, What Configure Does, top
661 @chapter Porting with Configure
664 This section explains briefly how to add programs, host and target
665 configuration names, and sites to Cygnus configure.
668 * Programs:: Adding configure to new programs
669 * Hosts and Targets:: Adding hosts and targets
670 * Sites:: Adding site info
674 @node Programs, Hosts and Targets, Porting, Porting
675 @section Adding Configure To New Programs
677 If you are writing a new program, you probably shouldn't worry about
678 porting issues or configure until it is running reasonably on some host.
679 Then refer back to this section.
681 If the program in question currently has a configure script that meets
682 the criterion set out by @cite{standards.text}, please do not add Cygnus
683 configure. It should be possible to add this program without change to
684 a Cygnus configure style source tree.
686 If the program is not target dependent, please consider using
687 @code{autoconf} instead of Cygnus configure. Autoconf will soon be
688 available from the @sc{fsf}.
690 To add Cygnus configure to an existing program, do the following.
694 @item Bring the Makefile up to the standard
695 The coding standard for @sc{gnu} Makefiles is described in
696 @cite{standards.text}.
698 @item Add Cygnus extensions to the Makefile
699 There are described in @xref{Makefile Extensions}.
701 @item Move host support from Makefile to fragments
702 This usually involves finding sections of the Makefile that say things
703 like ``uncomment these lines for host foo'' and moving them to a new
704 file call @file{./config/mh-foo}. For more on this, see @xref{Hosts and
707 @item Choose defaults
708 If the program has compile time options that determine the way the
709 program should behave, chose reasonable defaults and make these Makefile
710 variables. Be sure the variables are assigned their default values
711 before the @code{####} line so that they can be overridden with site
712 specific Makefile fragments.
714 @item Locate configuration files
715 If there is configuration information in header files or source files,
716 separate it in such a way that the files have a generic name. Then move
717 the specific instances of those files into the @file{./config}
720 @item Separate host and target information
721 Some programs already have this information separated. If not, you will
722 need to do so. Host specific information is the information needed to
723 compile the program. Target specific information it information on the
724 format of data files that the program will read or write. This
725 information should live in separate files in the @file{./config}
726 directory with names that reflect the configuration for which they are
729 At this point you might skip this step and simply move on. If you do,
730 you should end up with a program that can be configured only to build
731 native tools, that is, tools for which the host system is also the
732 target system. Later, you could attempt to build a cross tool and
733 separate out the target specific information by figuring out what went
734 wrong. This is often simpler than combing through all of the source
737 @item Write configure.in
738 Usually this involves writing shell script fragments to map from
739 canonical configuration names into the names of the configuration files.
740 These files will then be linked at configure time from the specific
741 instances of those files in @file{./config} to file in the build
742 directory with more generic names. (see also @xref{Build Directories}).
743 The format of configure.in is described in @xref{configure.in}.
745 @item Rename the Makefile to Makefile.in
749 At this point you should have a program that can be configured by Cygnus
752 @node Hosts and Targets, Sites, Programs, Porting
753 @section Adding hosts and targets
755 To add a host or target to a program that currently uses Cygnus
756 configure, do the following.
761 Make sure the new configuration name is represented in
762 @file{config.sub}. If not, add it. For more details, see the comments
763 in the shell script @file{config.sub}.
766 If you are adding a host configuration, look in @file{configure.in}, in
767 the per-host section. Make sure that your configuration name is
768 represented in the mapping from host configuration names to
769 configuration files. If not, add it. Also see @xref{configure.in}.
772 If you are adding a target configuration, look in @file{configure.in},
773 in the per-target section. Make sure that your configuration name is
774 represented in the mapping from target configuration names to
775 configuration files. If not, add it. Also see @xref{configure.in}.
778 Look in @file{configure.in} for the assignments to the variables
779 @code{files}, @code{links}, @code{host_makefile_frag}, and
780 @code{target_makefile_frag}. These are the names of the configuration
781 files that the program uses. Make sure that copies of the files exist
782 for your host. If not, create them. See also @xref{Configure
787 This should be enough to configure for a new host or target
788 configuration name. Getting the program to compile and run properly now
789 is the hard work of the port.
792 @node Sites, , Hosts and Targets, Porting
793 @section Adding site info
795 If some of the Makefile defaults are not right for your site, you can
796 build site specific Makefile fragments. To do this, do the following.
801 Choose a name for your site. It must be less than eleven characters for
805 If the program does not have a @file{./config} directory, create it.
808 Create a file called @file{./config/ms-@var{site}} where @var{site} is
809 the name of your site. In it, set the Makefile variables of your
813 Configure the program with:
816 configure @dots{} +site=@var{site}
820 @node Reference, Known Bugs, Porting, top
821 @chapter Gory details described
824 Here we describe the backend support.
827 * Makefile Extensions:: Extensions to the @sc{gnu} coding standards
828 * configure.in:: The format of the configure.in file
829 * config.status:: config.status
830 * Makefile Fragments:: Makefile Fragments
833 @node Makefile Extensions, configure.in, Reference, Reference
834 @section Extensions to the @sc{gnu} coding standards
836 @cindex Makefile extensions
837 @cindex Cygnus extensions
839 The following additions to the @sc{gnu} coding standards are required
840 for Cygnus configure to work properly.
845 The Makefile must contain exactly one line starting with @code{####}.
846 This line should follow any default macro definitions but precede any
847 rules. Host, target, and site specific Makefile fragments will be
848 inserted immediately after this line. If the line is missing, the
849 fragments will not be inserted.
853 Cygnus adds the following targets to our Makefiles. Their existence is
854 not required for Cygnus configure but are documented here for
861 Build all info files from texinfo source.
865 Install all info files.
869 Remove all info files and any intermediate files that can be generated
894 These targets are in transition and may be removed shortly.
898 In addition, the following Makefile targets have revised semantics:
904 Should @emph{not} depend on the target @code{all}. If the program is
905 not already built, @code{make install} should fail. This allows
906 programs to be installed even when @code{make} would otherwise determine
907 them to be out of date. This can happen when the result of a @code{make
908 all} is transported via tape to another machine for installation as
909 well as in a number of other cases.
913 Should remove any file that can be regenerated by the Makefile,
914 excepting only the Makefile itself, and any links created by configure.
915 That is, @code{make all clean} should return all directories to their
916 original condition. If this is not done, then:
919 configure @var{host1} ; make all clean ; configure @var{host2} ; make all
923 will fail because of intermediate files intended for @var{host1}.
927 Cygnus adds the following macros to all Makefile.in's. Their presence
928 is not required for Cygnus configure.
934 The directory in which to install any documentation that is not either a
935 man page or an info file. For man pages, see mandir, for info, see
940 The directory in which to install any headers files that should be made
941 available to users. This is distinct from the @code{gcc} include
942 directory which is intended for @code{gcc} only. Files in
943 @code{includedir} may be used by @code{cc} as well.
947 In addition, the following macros have revised semantics.
953 is not used. The intended usage is not clear. For example, if I have a
954 @file{foo.man} and a @file{bar.man}, and @file{foo.man} is destined for
955 @file{/usr/local/lib/man/man1/foo.1} while @file{bar.man} is destined
956 for @file{/usr/local/lib/man/man5/bar.5}, then to what should the value
957 of @code{manext} be set? See also @xref{Install Details}.
961 is used for @emph{all} host independent files. This makes it possible
962 to share host independent files across multiple hosts without ersorting
963 to symlinks or multiple mount points. This also makes it possible
964 build an install tree that contains multiple host binaries, write
965 the binaries to tape, and extract any of the hosts without extracting
970 man pages are host independent so the default path for @code{mandir}
971 depends on @code{datadir}.
975 info files are host independent so the default path for @code{infodir}
976 depends on @code{datadir}.
980 is assumed to have a yacc calling convention. To actually use
981 @code{bison}, use @code{BISON=bison -y}.
985 Cygnus also adds the following restrictions on our Makefiles.
990 When libraries are installed, the line containing the call to
991 @code{INSTALL_DATA} should always be followed by a line containing a
992 call to @code{RANLIB} on the installed library. This is to accomodate
993 systems that use @code{ranlib}. Systems that do not use ranlib can set
994 @code{RANLIB} to @code{echo} in a host specific Makefile fragment.
998 @node configure.in, config.status, Makefile Extensions, Reference
999 @section The format of the configure.in file
1001 @cindex configure.in
1003 A configure.in file for Cygnus configure consists of a declarations
1004 section, followed by a per-host section, followed by a per-target
1005 section, optionally followed by a post-target section. Each section is
1006 a shell script fragment sourced by configure at the appropriate time.
1007 The interface between configure and the shell fragments is through a set
1008 of shell variables. All sections are sourced in the build directory.
1010 @cindex Per-host section
1011 A line beginning with @code{# Per-host:} begins the per-host section.
1013 @cindex Per-target section
1014 A line beginning with @code{# Per-target:} begins the per-target
1017 @cindex Post-target section
1018 If it exists, the post-target section begins with @code{# Per-target:}.
1021 * Minimal:: A minimal configure.in
1022 * Configure Variables:: Variables available to configure.in
1023 * Declarations:: Per invocation
1024 * Per-host:: On a host basis
1025 * Per-target:: On a target basis
1026 * Post-target:: After each target
1027 * Example:: An example configure.in
1030 @node Minimal, Configure Variables, configure.in, configure.in
1031 @subsection A minimal configure.in
1033 @cindex Minimal configure.in example
1034 A minimal @file{configure.in} consists of four lines.
1038 srcname="source for the foo program"
1043 The per-host and per-target lines divide the file into the three
1044 required sections. The srctrigger line names a file. configure checks
1045 to see that this file exists in the source directory before
1046 configuring. If the srctrigger file does not exist, configure
1047 uses the value of srcname to print an error message about not finding
1050 This particular example uses no links, and only the default host,
1051 target, and site specific Makefile fragments if they exist.
1053 @node Configure Variables, Declarations, Minimal, configure.in
1054 @subsection Variables available to configure.in
1056 @cindex Configure.in interface
1058 The following variables are available to the shell fragments in
1059 @file{configure.in}.
1062 Contains the name of a source file that is expected to live in the
1063 source directory. This is usually set in the declations section of
1064 @file{configure.in}. Configure tests to see that this file exists. If
1065 the file does not exist, configure prints an error message. This is
1066 used as a sanity check that configure.in matches the source directory.
1070 Contains the name of the source contained in the source directory. This
1071 is usually set in the declarations section of @file{configure.in}. If
1072 the file named in @code{srctrigger} does not exist, configure uses the
1073 value of this variable when it prints the error message.
1077 Contains the names of any subdirectories on which configure should
1078 recur. This is usually set in the declarations section of
1079 @file{configure.in}. If @file{Makefile.in} contains a line starting
1080 with @code{SUBDIRS =}, then it will be replaced with an assignment to
1081 @code{SUBDIRS} using the value of @code{configdirs}. This can be used
1082 to determine which directories to configure and build depending on the
1083 host and target configurations.
1086 NOTE: support for multiple targets is currently suspended.
1088 @defvar{target_dependent}
1089 If this variable is not empty and @code{-subdirs} is in effect then
1090 configure will create separate build directories for each target. This
1091 is usually set in the declarations section of @file{configure.in}. The
1092 default is to assume that a directory is target independent, create only
1093 one real directory with symlinks from the other names. This means that
1094 a target independent directory will be built exactly once regardless of
1095 how many targets are being built.
1099 Contains the actual name that the user entered for the host. Since many
1100 things that the user could enter would map to the same canonical triple,
1101 this variable is innappropriate to use for picking available
1102 configurations. For that, use @code{host_cpu}, @code{host_vendor},
1103 and/or @code{host_os}. This variable is useful, however, for error
1108 Contains the first element of the canonical triple representing the host
1109 as returned by @file{config.sub}. This is occasionally used to
1110 distinguish between minor variations of a particular vendor's operating
1111 system and sometimes to determine variations in binary format between
1112 the host and the target.
1115 @defvar{host_vendor}
1116 Contains the second element of the canonical triple representing the
1117 host as returned by @file{config.sub}. This is usually used to
1118 distinguish betwen the numerous variations between @emph{common}
1123 Contains the the third element of the canonical triple representing the
1124 host as returned by @file{config.sub}.
1128 Contains the actual name that the user entered for the target. Since
1129 many things that the user could enter would map to the same canonical
1130 triple, this variable is innappropriate to use for picking available
1131 configurations. For that, use @code{target_cpu}, @code{target_vendor},
1132 and/or @code{target_os}. This variable is useful, however, for error
1137 Contains the first element of the canonical triple representing the
1138 target as returned by @file{config.sub}. This is used heavily by
1139 programs involved in building programs, like the compiler, assembler,
1140 linker, etc. Most programs will not need the @code{target} variables at
1141 all, but this one could conceivably be used to build a program, for
1142 instance, that operated on binary data files whose byte order or
1143 alignment are other than that of the system on which the program is
1147 @defvar{target_vendor}
1148 Contains the second element of the canonical triple representing the
1149 target as returned by @file{config.sub}. This is usually used to
1150 distinguish betwen the numerous variations between @emph{common}
1151 operating systems or object file formats. Sometimes it is used to
1152 switch between different flavors of user interfaces.
1156 Contains the the third element of the canonical triple representing the
1157 target as returned by @file{config.sub}. This variable is used by
1158 development tools to distinguish between subtle variations in object
1159 file formats that some vendors use across operating system releases. It
1160 might also be use to decide which libraries to build or what user
1161 interface the tool should provide.
1165 Is set to @code{true} if the user invoked configure with the @code{-nfp}
1166 command line option, otherwise it is empty. This is a request to target
1167 machines with @emph{no floating point} unit, even if the targets
1168 ordinarily have floating point units available. This option has no
1173 Is set to @code{true} if the user invoked configure with the @code{-gas}
1174 command line option, otherwise it is empty. This is a request to assume
1175 that all target machines have gas available even if they ordinarily do
1176 not. The converse option, @code{-no-gas} is not available.
1180 Is set to @code{true} if the user invoked configure with the @code{-x}
1181 command line option, otherwise it is empty. This is a request to assume
1182 that @sc{mit x11} compatible headers files and libraries are available
1183 on all hosts, regardless of what is normally available on them.
1186 NOTE: support for @code{-subdirs} is at least temporarily suspended.
1189 Is set to the name of the directory containing the source for this
1190 program. This will be different from @file{.} if the user has specified
1191 either the @code{-srcdir=} or the @code{-subdirs} options. Note that
1192 @code{srcdir} is not necessarily an absolute path.
1195 @defvar{host_makefile_frag}
1196 Is set to a file name representing to the default Makefile fragment for
1197 this host. It may be set in @file{configure.in} to overide this
1201 @defvar{target_makefile_frag}
1202 Is set to a file name representing to the default Makefile fragment for
1203 this target. It may be set in @file{configure.in} to overide this
1207 @defvar{site_makefile_frag}
1208 Is set to a file name representing to the default Makefile fragment for
1209 this host. It may be set in @file{configure.in} to overide this
1210 default. Normally @code{site_makefile_frag} is empty, but will have a
1211 value if the user specified @code{-site=} on the command line. This
1212 variable should probably not be overridden.
1216 Is set to the name of the generated @file{Makefile}. Normally this
1217 value is precisely @file{Makefile} but some programs may want something
1222 Is normally empty but will be set to some non-empty value if the user
1223 specified @code{-rm} on the command line. That is, if @code{removing}
1224 is non-empty, then configure is @emph{removing} a configuration rather
1229 If this variable is non-empty following the @code{per-target:} section,
1230 then each word in it's value will be the target of a symbolic link named
1231 in the @code{links} variable.
1235 If the @code{files} variable is non-empty following the
1236 @code{per-target:} section, then symbolic links will be created with the
1237 first word of links pointing to the first word of files, the second word
1238 of links pointing to the second word of files, and so on.
1242 @node Declarations, Per-host, Configure Variables, configure.in
1243 @subsection Per invocation
1245 @cindex Declarations section
1247 Everything from the start of @file{configure.in} up to a line beginning
1248 with @code{# Per-host:} is sourced by configure as a shell script
1249 fragment immediately after parsing command line arguments. The
1250 variables @code{srctrigger} and @code{srcname} @emph{must} be set here.
1252 Some other things you might want to set here are the variables
1253 @code{configdirs} or @code{target_dependent}. FIXME-soon.
1254 target_dependent isn't useful without multiple targets.
1256 @node Per-host, Per-target, Declarations, configure.in
1257 @subsection On a host basis
1259 @cindex Per-host section
1261 The per-host section of @file{configure.in} starts with a line beginning
1262 with @code{# Per-host:} and ends before a line beginning with with
1263 @code{# Per-target:}. Configure sources the per-host section once for
1266 This section usually contains a big case statement using the variables
1267 @code{host_cpu}, @code{host_vendor}, and @code{host_os} to determine
1268 appropriate values for @code{host_makefile_frag} and @code{files},
1269 although @code{files} is not usually set here. Usually, it is set
1270 at the end of the per-target section after determining the names of the
1271 target specific configuration files.
1273 @node Per-target, Post-target, Per-host, configure.in
1274 @subsection On a target basis
1276 @cindex Per-target section
1277 @cindex Target basis
1279 The per-target section of @file{configure.in} starts with a line
1280 beginning with @code{# Per-target:} and ends before a line beginning
1281 with @code{# Post-target:} if it exists. Otherwise the per-target
1282 section extends to the end of the file. Configure sources the
1283 per-target section once for each target before building any files,
1284 directories, or links.
1286 This section usually contains a big case statement using the variables
1287 @code{target_cpu}, @code{target_vendor}, and @code{target_os} to determine
1288 appropriate values for @code{target_makefile_frag} and @code{files}.
1289 The last lines in the per-target section normally set the variables
1290 @code{files} and @code{links}.
1292 @node Post-target, Example, Per-target, configure.in
1293 @subsection After each target
1295 The post-target section is optional. If it exists, the post-target
1296 section starts with a line beginning with @code{# Post-target:} and
1297 extends to the end of the file. If it exists, configure sources this
1298 section once for each target after building all files, directories, or
1301 This section seldom exists but can be used to munge the configure
1304 @node Example, , Post-target, configure.in
1305 @subsection An example configure.in
1307 @cindex Example configure.in
1308 @cindex Bison configure.in
1309 Here is a small example configure.in.
1312 # This file is a shell script fragment that supplies the information
1313 # necessary to tailor a template configure script into the configure
1314 # script appropriate for this directory. For more information, check
1315 # any existing configure script.
1318 srctrigger=warshall.c
1322 case "$@{host_os@}" in
1324 host_makefile_frag=config/mh-delta88
1330 files="bison_in.hairy"
1336 @node config.status, Makefile Fragments, configure.in, Reference
1337 @section config.status
1339 @cindex config.status
1341 The final step in configuring a directory is to create an executable
1342 shell script call @file{config.status}. This file is typically used to
1343 rebuild the Makefile for the current directory. For this reason,
1344 @file{config.status} uses the @code{-norecursion} option to configure
1345 and is therefor probably inappropriate for actually reconfiguring a tree
1348 @node Makefile Fragments, , config.status, Reference
1349 @section Makefile Fragments
1351 @cindex Makefile fragments
1353 Cygnus configure uses three types of Makefile fragments. In a
1354 generated Makefile they occur in the order target fragment, host
1355 fragment, and site fragment. This is so host fragments can override
1356 target fragments etc.
1358 Host specific Makefile fragments conventionally reside in the
1359 @file{./config} directory with names of the form
1360 @file{mh-@var{host}}. They are used for hosts that require
1361 odd options to the standard compiler and for compile time options based
1362 on the host configuration.
1364 Target specific Makefile fragments conventionally reside in the
1365 @file{./config} directory with names of the form @file{mt-@var{target}}.
1366 They are used for target dependent compile time options.
1368 Site specific Makefile fragments conventionally reside in the
1369 @file{./config} directory with names of the form @file{ms-@var{site}}.
1370 They are used to override host and target independent compile time
1371 options. Note that these options can also be overridden on the
1372 @code{make} invocation line.
1374 @node Known Bugs, Variables Index, Reference, top
1379 The following bugs are known to exist.
1384 There is no way to query about known hosts, known targets, or the
1385 porting or testing status of any configuration.
1388 The negations to the options @code{-gas}, @code{-x}, and @code{-nfp} are
1394 @node Variables Index, Concept Index, Known Bugs, top
1395 @appendix Variable Index
1400 @node Concept Index, , Variables Index, top
1401 @appendix Concept Index
1409 @c outline-regexp: "@chap"
1411 @c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")