1 \input texinfo @c -*-para-*-
3 @setfilename configure.info
4 @settitle Cygnus Configure
8 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
9 \xdef\manvers{\$Revision$} % For use in headers, footers too
11 @setchapternewpage off
14 This document attempts to describe the Cygnus Support version of
17 Copyright (C) 1991 Cygnus Support
18 Permission is granted to make and distribute verbatim copies of
19 this manual provided the copyright notice and this permission notice
20 are preserved on all copies.
23 Permission is granted to process this file through TeX and print the
24 results, provided the printed document carries copying permission
25 notice identical to this one except for the removal of this paragraph
26 (this paragraph not being relevant to the printed manual).
29 Permission is granted to copy and distribute modified versions of this
30 manual under the conditions for verbatim copying, provided that the entire
31 resulting derived work is distributed under the terms of a permission
32 notice identical to this one.
34 Permission is granted to copy and distribute translations of this manual
35 into another language, under the above conditions for modified versions,
36 except that this permission notice may be stated in a translation approved
42 @title{Cygnus Configure}
43 @subtitle @manvers, for Cygnus Configure version 1.84
44 @author{K. Richard Pixley, @code{rich@@cygnus.com}}
45 @author{Cygnus Support}
48 @vskip 0pt plus 1filll
49 Copyright @copyright{} 1991 Cygnus Support
51 Permission is granted to make and distribute verbatim copies of
52 this manual provided the copyright notice and this permission notice
53 are preserved on all copies.
55 Permission is granted to copy and distribute modified versions of this
56 manual under the conditions for verbatim copying, provided that the entire
57 resulting derived work is distributed under the terms of a permission
58 notice identical to this one.
60 Permission is granted to copy and distribute translations of this manual
61 into another language, under the above conditions for modified versions,
62 except that this permission notice may be stated in a translation approved
69 * configure: (configure.info). Cygnus configure.
73 @node top, What Configure Does, (dir), (dir)
76 This file documents the configuration system used and distributed by
79 NOTE: support for a Cygnus experimental option, @code{-subdirs} is at
80 least temporarily suspended. Most of the code is still in configure but
81 the option is disabled. This document describes that feature, but those
82 parts are prominently marked with NOTE's like this one. FIXME-soon
85 * What Configure Does:: What Configure Does
87 * Using Configure:: Using Configure
88 * Porting:: Porting with Configure
89 * Reference:: Gory details described
90 * Known Bugs:: Known Bugs
91 * Variables Index:: Variable Index
92 * Concept Index:: Concept Index
100 NOTE: support for a Cygnus experimental option, @code{-subdirs} is at
101 least temporarily suspended. Most of the code is still in configure but
102 the option is disabled. This document describes that feature, but those
103 parts are prominently marked with NOTE's like this one. FIXME-soon
106 @node What Configure Does, Invoking, top, top
107 @chapter What Configure Does
109 @code{configure} prepares source directories for building working
110 programs. A program cannot be built until its source has been
111 configured. When configure runs, it does the following things for each source
112 directory for each host and target combination.
114 NOTE: support for multiple hosts and targets is at least temporarily
118 @item Create build directories
119 (see @ref{Build Directories}). When you run @code{configure} with the
120 @code{-srcdir=} option, it uses the current directory as build
121 directory, creating under it a directory tree that parallels the
122 directory structure under the source directory. (See @ref{Invoking}).
124 NOTE: support for @code{-subdirs} is at least temporarily suspended.
126 When you run @code{configure} with the @code{-subdirs} option, it
127 creates a build subdirectory in each source directory.
129 If you use both @code{-subdirs} and @code{-srcdir=}, a tree that
130 parallels the source directory structure is created in the current
131 directory, and the subdirectories are created in this directory tree
132 rather than in the source directories.
134 @item Generate makefiles
135 A makefile template from the source directory, usually called
136 @file{Makefile.in}, is copied to an output file in the build directory.
137 The output file is usually named @file{Makefile}. @code{configure}
138 places definitions for a number of standard makefile
139 macros at the beginning of the output file. If @code{-prefix=} or
140 @code{-datadir=} were specified on the @code{configure} command line,
141 corresponding makefile variables are set accordingly. If host, target, or
142 site specific makefile fragments exist, these are inserted into the
143 output file. (See @ref{Makefiles, , , make, Makefiles}.)
145 @item Generate @file{.gdbinit}
146 If the source directory contains a @file{.gdbinit} file and the build
147 directory is not the same as the source directory, a @file{.gdbinit}
148 file is created in the build directory. This @file{.gdbinit} file
149 contains just a @code{source} command, which will cause the @file{.gdbinit}
150 file from the source directory to be read by GDB. (see
151 @ref{Command Files, , , gdb, Command Files}.)
153 @item Make symbolic links
154 Most directories have some symbolic links with generic names built
155 pointing to specific files in the source directory. If the system where
156 @code{configure} runs cannot support symbolic links, hard links are used
160 If the source directory has special needs, they are handled by shell
161 script fragments stored with the source. Usually there are no special
162 needs, but sometimes they involve changes to the output makefile.
164 @item Generate @file{config.status}
165 @code{configure} creates a shell script named @file{config.status} in
166 the build directory. This shell script, when run from the build
167 directory, will reconfigure the build directory (but not its
168 subdirectories). This is most often used to have a @code{Makefile} update
169 itself automatically if a new source directory is available.
172 If the source directory has subdirectories that should also be
173 configured, @code{configure} is called for each.
176 @node Invoking, Using Configure, What Configure Does, top
179 The usual way to invoke @code{configure} is as follows:
183 This prepares the source to be compiled in a
184 @var{host} environment with programs and files to be installed in
187 NOTE: support for multiple hosts is at least temporarily suspended.
190 If more than one host is specified on the command line, then
191 configurations are created for each and @code{-subdirs} is assumed.
193 @code{configure} prepares the source as you specify by selecting and
194 using script and Makefile fragments prepared in advance, and stored with
195 the source. @code{configure}'s command line options also allow you to
196 specify other aspects of the source configuration:
199 @item -datadir=@var{dir}
200 Configure the source to install host independent files in @var{dir}.
202 This option sets the @code{configure} variable @code{datadir}.
203 Generated Makefiles will have their @code{datadir} variables set to this
204 value. (See @ref{Install Details}.)
207 Configure to use the @sc{GNU} assembler.
210 Display a quick summary of how to invoke @code{configure}.
212 @item -host=@var{host}
213 FIXME-soon: I don't think this option should be documented.
214 @c Then why does it exist? /Pesch 7jan92
216 @item -namesubdir=@var{name}
217 NOTE: support for this @code{-namesubdir=} is at least temporarily
218 suspended. FIXME-soon
220 Name any subdirectories created by the @code{-subdirs} option
223 @emph{Warning:} Avoid using this option if you specify multiple hosts
224 simultaneously. There is no way to specify separate names for
225 subdirectories, when you configure for multiple hosts in a single
226 invocation of @code{configure}.
229 @emph{No floating point} unit available on the target; configure to
230 avoid dependencies on hardware floating point.
233 Configure only this directory; ignore any subdirectories. This is used
234 by the executable shell script @file{config.status} to reconfigure the
235 current directory. (see @ref{config.status}).
238 @c This is complicated enough without "no longer supported" entries.
239 @c Should really delete this, but for ease of discourse...
240 @item -objdir=@var{dir}
241 This option is no longer supported. Use @code{-srcdir=} instead.
244 @item -prefix=@var{dir}
245 Configure the source to install programs and files under directory
248 This option sets the @code{configure} variable @code{prefix}. Generated
249 Makefiles will have their @code{prefix} variables set to this value.
250 (See @ref{Install Details}.)
253 @c Wouldn't it make more sense to call this "-quiet"? (FIXME).
254 This option is used internally by @code{configure} when recurring on
255 subdirectories. Its sole purpose is to suppress status output. You can
256 override this effect with the @code{-verbose} option.
259 @emph{Remove} the configuration specified by @var{host} and the other
260 command-line options, rather than creating it.
262 @item -site=@var{site}
263 Generate Makefiles using site specific Makefile fragments for
264 @var{site}. See also @ref{Sites}.
266 @item -srcdir=@var{_dir}
267 Build Makefiles to use the sources located in directory @file{@var{dir}}. The
268 build directory is assumed to be @file{.}.
271 NOTE: support for this @code{-subdirs} is at least temporary suspended.
274 Place configurations in subdirectories of each build directory.
275 @code{configure} builds a separate subdirectory for each host specified,
276 and names it @file{H-@var{host}}. If a configuration is not native,
277 (@var{host} is not @var{target}), then the subdirectory is named
278 @file{X-@var{host}-@var{target}} instead. You can also name a
279 subdirectory explicitly using the @samp{-namesubdir} option, but this is
280 effective only when you specify one configuration at a time.
282 @item -target=@var{target}
283 Requests that the sources be configured to target the @var{target}
284 machine. If no target is specified explicitly, the target is assumed
285 to be the same as the host.
287 NOTE: support for multiple targets is at least temporarily suspended.
290 If multiple targets are specified, configurations for each
291 are created and @code{-subdirs} is assumed.
293 @item -tmpdir=@var{tmpdir}
294 Use the directory @var{tmpdir} for @code{configure}'s temporary files.
295 The default is the value of the environment variable TMPDIR, or
296 @file{/tmp} if the environment variable is not set.
300 Print status lines for each directory configured. Normally, only the
301 status lines for the initial working directory are printed.
304 Use @sc{MIT} style @sc{X11} header files and libraries on the host, even
305 if they are not normally available.
308 @node Using Configure, Porting, Invoking, top
309 @chapter Using Configure
311 The choices and options available at configuration time
312 generally have valid defaults, but the defaults do not cover all cases.
313 The choices available include install locations, build directories,
314 host, target, and local conventions.
317 * Install Locations:: Where to install things once they are built
318 * Build Directories:: Where to build object files
319 * Host:: Telling @code{configure} what will source will
321 * Target:: Telling @code{configure} what the source will
323 * Local Conventions:: Adding information about local conventions
326 @node Install Locations, Build Directories, Using Configure, Using Configure
327 @section Install Locations
328 @cindex Where to install
330 Using the default configuration, @code{make install} creates a
331 single tree of files, some of which are programs. The location of this
332 tree is determined by the value of the variable @code{prefix}. The
333 default value of @code{prefix} is @file{/usr/local}. This is
334 often correct for native tools installed on only one host.
337 * prefix:: Changing the default install directory
338 * datadir:: How to separate host independent files
339 from host dependent files when
340 installing for multiple hosts
341 * Install Details:: Full descriptions of all installation
345 @node prefix, datadir, Install Locations, Install Locations
346 @subsection Changing the default install directory
347 @cindex Changing the default install directory
348 @cindex Prefix directory
350 In the default configuration, all files are installed in subdirectories
351 of @file{/usr/local}. The location is determined by the value of
352 the @code{configure} variable @code{prefix}; in turn, this determines the
353 value of the Makefile variable of the same name (@code{prefix}).
355 You can also set the value of the Makefile variable @code{prefix}
356 explicitly each time you invoke @code{make} if you are so inclined; but
357 because many programs have this location compiled in, you must specify
358 the @code{prefix} value consistently on each invocation of @code{make},
359 or you will end up with a broken installation.
361 To make this easier, the value of the @code{configure} variable
362 @code{prefix} can be set on the command line to @code{configure}
363 using the option @code{-prefix=}.
366 @node datadir, Install Details, prefix, Install Locations
367 @subsection Installing for multiple hosts
368 @cindex Configuring for multiple hosts
369 @cindex Sharing host independent files
370 @cindex The @file{datadir} directory
371 @cindex Installing host independent files
373 By default, host independent files are installed in subdirectories of
374 @file{@var{prefix}/lib}. The location is determined by the value of the
375 @code{configure} variable @code{datadir}, which determines the value of
376 the Makefile variable @code{datadir}. This makes it simpler to install
377 for a single host, and simplifies changing the default location for the
378 install tree; but the default doesn't allow for multiple hosts to
379 effectively share host independent files.
381 To configure so that multiple hosts can share common files, use
385 configure @var{host1} -prefix=/usr/gnu/H-@var{host1} -datadir=/usr/gnu/H-independent
386 make all info install install-info clean
388 configure @var{host2} -prefix=/usr/gnu/H-@var{host2} -datadir=/usr/gnu/H-independent
389 make all info install install-info
392 The first line configures the source for @var{host1} to place host
393 specific programs in subdirectories of @file{/usr/gnu/H-@var{host1}},
394 and host independent files in @file{/usr/gnu/H-independent}.
396 The second line builds and installs all programs for @var{host1},
397 including both host independent and host specific files.
399 The third line reconfigures the source for @var{host2} to place host
400 specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}},
401 and host independent files (once again) in
402 @file{/usr/gnu/H-independent}.
404 The fourth line builds and installs all programs for @var{host2}. Host
405 specific files are installed in new directories, but the host
406 independent files are installed @emph{on top of} the host
407 independent files installed for @var{host1}. This results in a single
408 copy of the host independent files, suitable for use by both hosts.
410 NOTE: support for @code{-subdirs} and multiple hosts is at least
411 temporarily suspended. FIXME-soon
416 configure @var{host1} @var{host2} -prefix=/usr/gnu
420 @node Install Details, , datadir, Install Locations
421 @subsection Full descriptions of all installation subdirectories
423 During any install, a number of standard directories are created. Their
424 names are determined by Makefile variables. Some of the
425 defaults for Makefile variables can be changed at configure time using
426 command line options to @code{configure}. For more information on the
427 standard directories or the Makefile variables, please refer to
428 @cite{standards.text}.
430 Note that @code{configure} does not create the directory @code{srcdir}
431 at any time. @code{srcdir} is not an installation directory.
433 You can override all makefile variables on the command line to
434 @code{make}. (See @ref{Overriding, Overriding Variables, Overriding
435 Variables, make, Make}.) If you do so, you will need to specify the
436 value precisely the same way for each invocation of @code{make}, or you
437 risk ending up with a broken installation. This is because many
438 programs have the locations of other programs or files compiled into
439 them. If you find yourself overriding any of the variables frequently,
440 you should consider site dependent Makefile fragments. See also
443 During @code{make install}, a number of standard directories are
444 created and populated. The following Makefile variables define them.
445 Those whose defaults are set by corresponding @code{configure} variables
446 are marked ``Makefile and configure''.
449 @defvr {Makefile and configure} prefix
450 The root of the installation tree. You can set
451 its Makefile default with the @code{-prefix=} command line option to
452 @code{configure}. (@ref{Invoking}.) The default value for
453 @code{prefix} is @file{/usr/local}.
457 @defvr Makefile bindir
458 A directory for binary programs that users can run.
459 The default value for @code{bindir} depends on @code{prefix};
460 @code{bindir} is normally changed only indirectly through @code{prefix}.
461 The default value for @code{bindir} is @file{$(prefix)/bin}.
465 @defvr {Makefile and configure} datadir
466 A directory for host independent files. You can specify the Makefile
467 default value by using the @code{-datadir=} option to @code{configure}.
468 (See also @ref{Invoking}.) The default value for @code{datadir} is
469 @file{$(prefix)/lib}.
473 @defvr Makefile libdir
474 A directory for libraries and support programs. The default value for
475 @code{libdir} depends on @code{prefix}; @code{libdir} is normally
476 changed only indirectly through @code{prefix}. The default value for
477 @code{libdir} is @file{$(prefix)/lib}.
481 @defvr Makefile mandir
482 A directory for @code{man} format documentation (``man pages''). The
483 default value for @code{mandir} depends on @code{prefix};
484 @code{mandir} is normally changed only indirectly through @code{prefix}.
485 The default value for @code{mandir} is @file{$(datadir)/man}.
488 @vindex man@var{N}dir
489 @defvr Makefile man@var{N}dir
490 There are eight variables named @code{man1dir}, @code{man2dir}, etc.
491 They name the specific directories for each man page section. For
492 example, @code{man1dir} holds @file{emacs.1} (the man page for the emacs
493 program), while @code{man5dir} holds @file{rcsfile.5} (the man page
494 describing the @code{rcs} data file format). The default value for any
495 of the @code{man@var{N}dir} variables depends indirectly on
496 @code{prefix}, and is normally changed only through @code{prefix}. The
497 default value for @code{man@var{N}dir} is
498 @file{$(mandir)/man@var{N}}.
502 @defvr Makefile manext
503 @emph{Not supported by @code{configure}}. The @sc{gnu} coding standards
504 do not call for @code{man1ext}, @code{man2ext}, so the intended use for
505 @code{manext} is apparently not parallel to @code{mandir}. Its use is
506 not clear. (See also @ref{Makefile Extensions}.)
510 @defvr Makefile infodir
511 A directory for @emph{info} format documentation. The default value for
512 @code{infodir} depends indirectly on @code{prefix}; @code{infodir} is
513 normally changed only through @code{prefix}. The default value for
514 @code{infodir} is @file{$(datadir)/info}.
518 @defvr Makefile docdir
519 A directory for any documentation that is in a format other than those
520 used by @code{info} or @code{man}. The default value for @code{docdir}
521 depends indirectly on @code{prefix}; @code{docdir} is normally changed only
522 through @code{prefix}. The default value for @code{docdir}
523 is @file{$(datadir)/doc}. @emph{This variable is an extension to
524 the @sc{gnu} coding standards}. (See also @ref{Makefile Extensions}.)
528 @defvr Makefile includedir
529 A directory for the header files accompanying the libraries installed in
530 @code{libdir}. The default value for @code{includedir} depends on
531 @code{prefix}; @code{includedir} is normally changed only indirectly
532 through @code{prefix}. The default value for @code{includedir} is
533 @file{$(prefix)/include}.
536 @node Build Directories, Host, Install Locations, Using Configure
537 @section Build Directories
538 @cindex Build directories
540 @cindex Object directories
542 @cindex Building for multiple hosts
543 @cindex Building for multiple targets
545 Normally, @code{configure} builds a @file{Makefile} and symbolic links
546 in the same directory as the source files. This is the typical
547 @sc{un*x} way to build programs, but it has limitations. For instance,
548 using this approach, you can only build for one host at a time.
550 We refer to the directories where @code{configure} builds a
551 Makefile as the @emph{build directories} or sometimes as
552 @emph{objdir} because these are the directories in which @code{make}
553 will build object files, among other things.
555 The default build directory is the same as the source directory.
556 You can use a different build directory with a sequence like the following:
561 configure @var{host} -srcdir=@var{sourcedirectory}
565 where @var{builddir} is the directory where you wish to build,
566 @var{host} is the host for which you want to build, and
567 @var{sourcedirectory} is the directory containing the source files.
569 If you were to do this twice with different values for @var{builddir}
570 and @var{host}, then you could @code{make} for both at the same time.
573 @emph{NOTE:} The rest of this section describes the @code{-subdirs} feature for
574 which support is at least temporarily suspended. FIXME-soon.
577 Another way to specify the build directory is with the @samp{-subdirs}
581 configure @var{host} -subdirs
584 Using this option, @code{configure} will create a subdirectory named
585 @file{H-@var{host}} to act as the build directory for each source
588 Since building for multiple hosts is so common, @code{configure}
589 recognizes this situation as special. For example:
592 configure @var{host1} @var{host2}
595 is precisely the same as:
598 configure @var{host1} -subdirs
599 configure @var{host2} -subdirs
602 That is, configuring for multiple hosts or multiple targets implies
605 When configuring for cross tools (the converse of native tools: when the
606 host is not the target), as in:
609 configure @var{host} +target=@var{targ} -subdirs
613 the subdirectories are named @file{X-@var{host}-@var{targ}}. This is
614 especially useful when configuring for multiple targets.
616 If you use both @samp{-subdirs} and @samp{-srcdir=}, a tree that
617 parallels the source directory structure is created in the current
618 directory, and the subdirectories are created in this directory
619 tree rather than in the source directories.
621 @emph{NOTE:} previously, @samp{-subdirs} built two-level subdirectories
622 as @file{./H-@var{host}/T-@var{target}}, created
623 @file{./H-@var{host}/Makefile} for building across all targets,
624 @file{./Makefile} for building across all hosts, and
625 @file{./config.status} and @file{./H-@var{host}/config.status} for
626 rebuilding these Makefiles.
628 @node Host, Target, Build Directories, Using Configure
632 @emph{NOTE:} support for multiple hosts is at least temporarily suspended.
636 The arguments to @code{configure} are @emph{hosts}. By @emph{host} we
637 mean the environment in which the source will be compiled. This need
638 not necessarily be the same as the physical machine involved,
639 although it usually is.
641 For example, if some obscure machine running an operating system other
642 than @sc{un*x} had the @sc{gnu} @sc{posix} emulation libraries
643 available, it would be possible to configure most @sc{gnu} source for a
644 @sc{posix} system and build it on the obscure host.
646 For more on this topic, see @ref{Host Environments, , Host Environments,
647 cfg-paper, On Configuring Development Tools}.
649 @node Target, Local Conventions, Host, Using Configure
652 For building native development tools, or most of the other @sc{gnu}
653 tools, you need not worry about the target. The @emph{target} of a
654 configuration defaults to the same as the @emph{host}.
656 For building cross development tools, please see @ref{Building
657 Development Environments, , Building Development Environments,
658 cfg-paper, On Configuring Development Tools}.
660 @node Local Conventions, , Target, Using Configure
661 @section Local Conventions
663 If you find that a tool does not get configured to your liking, or if
664 @code{configure}'s conventions differ from your local conventions, you
665 should probably consider site specific Makefile fragments. See also
668 These are probably not the right choice for options that can be set from
669 the @code{configure} command line or for differences that are host or
672 @node Porting, Reference, Using Configure, top
673 @chapter Porting with Configure
676 This section explains how to add programs, host and target configuration
677 names, and site-specific information to Cygnus configure.
680 * Programs:: Adding configure to new programs
681 * Hosts and Targets:: Adding hosts and targets
682 * Sites:: Adding site info
686 @node Programs, Hosts and Targets, Porting, Porting
687 @section Adding Configure To New Programs
689 If you are writing a new program, you probably shouldn't worry about
690 porting issues or configure until it is running reasonably on some host.
691 Then refer back to this section.
693 If the program in question currently has a configure script that meets
694 the criteria set out by @cite{standards.text}, please do not add Cygnus
695 configure. It should be possible to add this program without change to
696 a Cygnus configure style source tree.
698 If the program is not target dependent, please consider using
699 @code{autoconf} instead of Cygnus configure. @code{autoconf} will
700 be available soon from the @sc{fsf}.
702 To add Cygnus configure to an existing program, do the following:
705 @item Make sure the Makefile conforms to @sc{gnu} standard
706 The coding standard for @sc{gnu} Makefiles is described in
707 @cite{standards.text}.
709 @item Add Cygnus extensions to the Makefile
710 These are described in @ref{Makefile Extensions}.
712 @item Move host support from Makefile to fragments
713 This usually involves finding sections of the Makefile that say things
714 like ``uncomment these lines for host foo'' and moving them to a new
715 file called @file{./config/mh-foo}. For more information, see @ref{Hosts
718 @item Choose defaults
719 If the program has compile time options that determine the way the
720 program should behave, chose reasonable defaults and make these Makefile
721 variables. Be sure the variables are assigned their default values
722 before the @code{####} line so that site specific Makefile fragments can
723 override them (@pxref{Makefile Extensions,,Extensions to the @sc{gnu}
726 @item Locate configuration files
727 If there is configuration information in header files or source files,
728 separate it in such a way that the files have a generic name. Then move
729 the specific instances of those files into the @file{./config}
732 @item Separate host and target information
733 Some programs already have this information separated. If yours does
734 not, you will need to separate these two kinds of configuration
735 information. @dfn{Host specific} information is the information needed to
736 compile the program. @dfn{Target specific} information is information on the
737 format of data files that the program will read or write. This
738 information should live in separate files in the @file{./config}
739 directory with names that reflect the configuration for which they are
742 At this point you might skip this step and simply move on. If you do,
743 you should end up with a program that can be configured only to build
744 native tools, that is, tools for which the host system is also the
745 target system. Later, you could attempt to build a cross tool and
746 separate out the target specific information by figuring out what went
747 wrong. This is often simpler than combing through all of the source
750 @item Write @code{configure.in}
751 Usually this involves writing shell script fragments to map from
752 canonical configuration names into the names of the configuration files.
753 These files will then be linked at configure time from the specific
754 instances of those files in @file{./config} to file in the build
755 directory with more generic names. (see also @ref{Build Directories}).
756 The format of configure.in is described in @ref{configure.in}.
758 @item Rename @file{Makefile} to @file{Makefile.in}
761 At this point you should have a program that can be configured using
762 Cygnus @code{configure}.
764 @node Hosts and Targets, Sites, Programs, Porting
765 @section Adding hosts and targets
767 To add a host or target to a program that already uses Cygnus
768 configure, do the following.
773 Make sure the new configuration name is represented in
774 @file{config.sub}. If not, add it. For more details, see the comments
775 in the shell script @file{config.sub}.
778 If you are adding a host configuration, look in @file{configure.in}, in
779 the per-host section. Make sure that your configuration name is
780 represented in the mapping from host configuration names to
781 configuration files. If not, add it. Also see @ref{configure.in}.
784 If you are adding a target configuration, look in @file{configure.in},
785 in the per-target section. Make sure that your configuration name is
786 represented in the mapping from target configuration names to
787 configuration files. If not, add it. Also see @ref{configure.in}.
790 Look in @file{configure.in} for the variables @samp{files},
791 @samp{links}, @samp{host_makefile_frag}, and
792 @samp{target_makefile_frag}. The values assigned to these variables are
793 the names of the configuration files, relative to @code{srcdir} that the
794 program uses. Make sure that copies of the files exist for your host.
795 If not, create them. See also @ref{Configure Variables}.
798 This should be enough to configure for a new host or target
799 configuration name. Getting the program to compile and run properly
800 remains the hard work of the port.
802 @node Sites, , Hosts and Targets, Porting
803 @section Adding site info
805 If some of the Makefile defaults are not right for your site, you can
806 build site specific Makefile fragments. To do this, do the following.
811 Choose a name for your site. It must be less than eleven characters for
815 If the program source does not have a @file{./config} directory, create it.
818 Create a file called @file{./config/ms-@var{site}} where @var{site} is
819 the name of your site. In it, set whatever Makefile variables you need
820 to override to match your site's conventions.
823 Configure the program with:
826 configure @dots{} +site=@var{site}
831 @node Reference, Known Bugs, Porting, top
832 @chapter Gory details described
835 Here we describe the backend support.
838 * Makefile Extensions:: Extensions to the @sc{gnu} coding standards
839 * configure.in:: The format of the configure.in file
840 * config.status:: config.status
841 * Makefile Fragments:: Makefile Fragments
844 @node Makefile Extensions, configure.in, Reference, Reference
845 @section Extensions to the @sc{gnu} coding standards
847 @cindex Makefile extensions
848 @cindex Cygnus extensions
850 The following additions to the @sc{gnu} coding standards are required
851 for Cygnus configure to work properly.
855 The Makefile must contain exactly one line starting with @code{####}.
856 This line should follow any default macro definitions but precede any
857 rules. Host, target, and site specific Makefile fragments will be
858 inserted immediately after this line. If the line is missing, the
859 fragments will not be inserted.
862 Cygnus adds the following targets to our Makefiles. Their existence is
863 not required for Cygnus configure, but they are documented here for
869 Build all info files from texinfo source.
873 Install all info files.
877 Remove all info files and any intermediate files that can be generated
902 These targets are in transition and may be removed shortly.
905 In addition, the following Makefile targets have revised semantics:
910 Should @emph{not} depend on the target @code{all}. If the program is
911 not already built, @code{make install} should fail. This allows you
912 to install programs even when @code{make} would otherwise determine
913 them to be out of date. This can happen when the result of a @code{make
914 all} is transported via tape to another machine for installation as
915 well as in a number of other cases.
919 Should remove any file that can be regenerated by the Makefile,
920 excepting only the Makefile itself, and any links created by configure.
921 That is, @code{make all clean} should return all directories to their
922 original condition. If this is not done, then:
925 configure @var{host1} ; make all clean ; configure @var{host2} ; make all
929 will fail because of intermediate files intended for @var{host1}.
932 Cygnus adds the following macros to all @file{Makefile.in} files, but
933 you are not required to use them to run Cygnus configure.
938 The directory in which to install any documentation that is not either a
939 man page or an info file. For man pages, see mandir, for info, see
944 The directory in which to install any headers files that should be made
945 available to users. This is distinct from the @code{gcc} include
946 directory which is intended for @code{gcc} only. Files in
947 @code{includedir} may be used by @code{cc} as well.
950 In addition, the following macros have revised semantics. Most of them
951 describe installation directories; see also @ref{Install Details,,Full
952 description of all installation subdirectories}.
958 is not used. The intended usage is not clear. For example, if you have a
959 @file{foo.man} and a @file{bar.man}, and @file{foo.man} is destined for
960 @file{/usr/local/lib/man/man1/foo.1} while @file{bar.man} is destined
961 for @file{/usr/local/lib/man/man5/bar.5}, then what is the desired value
966 is used for @emph{all} host independent files. This makes it possible
967 to share host independent files across multiple hosts without resorting
968 to symbolic links or to multiple mount points. This also makes it possible
969 build an install tree that contains multiple host binaries, write
970 the binaries to tape, and extract any of the hosts without extracting
975 The default path for @code{mandir} depends on @code{datadir}, since man
976 pages are host independent.
980 The default path for @code{infodir} depends on @code{datadir}, since
981 info files are host independent.
985 is assumed to have a @code{yacc} calling convention. To use
986 @code{bison}, use @code{BISON=bison -y}.
989 Cygnus Makefiles also conform to one additional restriction:
993 When libraries are installed, the line containing the call to
994 @code{INSTALL_DATA} should always be followed by a line containing a
995 call to @code{RANLIB} on the installed library. This is to accomodate
996 systems that use @code{ranlib}. Systems that do not use @code{ranlib}
997 can set @code{RANLIB} to @code{echo} in a host specific Makefile
1001 @node configure.in, config.status, Makefile Extensions, Reference
1002 @section The format of the @file{configure.in} file
1003 @kindex configure.in
1005 A @file{configure.in} file for Cygnus configure consists of a
1006 @dfn{per-invocation} section, followed by a @dfn{per-host} section,
1007 followed by a @dfn{per-target} section, optionally followed by a
1008 @dfn{post-target} section. Each section is a shell script fragment,
1009 which is sourced by the configure shell script at an appropriate time.
1010 Values are passed among configure and the shell fragments through a
1011 set of shell variables. When each section is being interpreted
1012 (sourced) by the shell, the shell's current directory is the build
1013 directory, and any files created by the section (or referred to by the
1014 section) will be relative to the build directory. To reference files
1015 in other places (such as the source directory), prepend a shell
1016 variable such as @code{srcdir} to the desired file name.
1018 @cindex Per-invocation section
1019 The beginning of the @file{configure.in} file begins the per-invocation
1022 @cindex Per-host section
1023 A line beginning with @code{# Per-host:} begins the per-host section.
1025 @cindex Per-target section
1026 A line beginning with @code{# Per-target:} begins the per-target
1029 @cindex Post-target section
1030 If it exists, the post-target section begins with @code{# Per-target:}.
1033 * Minimal:: A minimal configure.in
1034 * Configure Variables:: Variables available to configure.in
1035 * Declarations:: For each invocation
1036 * Per-host:: For each host
1037 * Per-target:: For each target
1038 * Post-target:: After each target
1039 * Example:: An example configure.in
1042 @node Minimal, Configure Variables, configure.in, configure.in
1043 @subsection A minimal @file{configure.in}
1045 @cindex Minimal @file{configure.in} example
1046 A minimal @file{configure.in} consists of four lines.
1050 srcname="source for the foo program"
1055 The @samp{Per-host} and @samp{Per-target} lines divide the file into the
1056 three required sections. The @samp{srctrigger} line names a file.
1057 @code{configure} checks to see that this file exists in the source
1058 directory before configuring. If the @samp{srctrigger} file does not
1059 exist, @code{configure} uses the value of @samp{srcname} to print an
1060 error message about not finding the source.
1062 This particular example uses no links, and only the default host,
1063 target, and site specific Makefile fragments if they exist.
1065 @node Configure Variables, Declarations, Minimal, configure.in
1066 @subsection Variables available to configure.in
1068 @cindex @file{configure.in} interface
1070 The following variables pass information between the standard parts of
1071 @code{configure} and the shell-script fragments in @file{configure.in}:
1074 Contains the name of a source file that is expected to live in the
1075 source directory. You must usually set this in the per-invocation
1076 section of @file{configure.in}. Configure tests to see that this file
1077 exists. If the file does not exist, configure prints an error message.
1078 This is used as a sanity check that configure.in matches the source
1083 Contains the name of the source collection contained in the source
1084 directory. You must usually set this in the per-invocation section of
1085 @file{configure.in}. If the file named in @code{srctrigger} does not
1086 exist, configure uses the value of this variable when it prints the
1091 Contains the names of any subdirectories where @code{configure} should
1092 recur. You must usually set this in the per-invocation section of
1093 @file{configure.in}. If @file{Makefile.in} contains a line starting
1094 with @code{SUBDIRS =}, then it will be replaced with an assignment to
1095 @code{SUBDIRS} using the value of @code{configdirs}. This can be used
1096 to determine which directories to configure and build depending on the
1097 host and target configurations.
1098 @c Most other matching makefile/config vars use the same name. Why not
1102 @defvar{target_dependent}
1103 NOTE: support for multiple targets is currently suspended.
1105 If this variable is not empty and @code{-subdirs} is in effect then
1106 configure will create separate build directories for each target. This
1107 is usually set in the declarations section of @file{configure.in}. The
1108 default is to assume that a directory is target independent, and to create
1109 only one real directory with symlinks from the other names. This means that
1110 a target independent directory will be built exactly once regardless of
1111 how many targets are being built.
1115 Contains the name that the user entered for the host. Since many things
1116 that the user could enter would map to the same output from
1117 @code{config.sub}, this variable is innappropriate to use for picking
1118 available configurations. For that, use @code{host_cpu},
1119 @code{host_vendor}, and/or @code{host_os}. This variable is useful,
1120 however, for error messages.
1124 Contains the first element of the canonical triple representing the host
1125 as returned by @file{config.sub}. This is occasionally used to
1126 distinguish between minor variations of a particular vendor's operating
1127 system and sometimes to determine variations in binary format between
1128 the host and the target.
1131 @defvar{host_vendor}
1132 Contains the second element of the canonical triple representing the
1133 host as returned by @file{config.sub}. This is usually used to
1134 distinguish betwen the numerous variations between @emph{common}
1136 @c "@emph{common} OS" doesn't convey much to me. Is this meant to cover
1137 @c cases like Unix, widespread but with many variations?
1141 Contains the the third element of the canonical triple representing the
1142 host as returned by @file{config.sub}.
1146 Contains the name that the user entered for the target. Since
1147 many things that the user could enter would map to the same canonical
1148 triple, this variable is innappropriate to use for picking available
1149 configurations. For that, use @code{target_cpu}, @code{target_vendor},
1150 and/or @code{target_os}. This variable is useful, however, for error
1155 Contains the first element of the canonical triple representing the
1156 target as returned by @file{config.sub}. This is used heavily by
1157 programs involved in building programs, like the compiler, assembler,
1158 linker, etc. Most programs will not need the @code{target} variables at
1159 all, but this one could conceivably be used to build a program, for
1160 instance, that operated on binary data files whose byte order or
1161 alignment differ from the system where the program is running.
1164 @defvar{target_vendor}
1165 Contains the second element of the canonical triple representing the
1166 target as returned by @file{config.sub}. This is usually used to
1167 distinguish betwen the numerous variations between @emph{common}
1168 operating systems or object file formats. Sometimes it is used to
1169 switch between different flavors of user interfaces.
1170 @c above query re "@emph{common} OS" applies here too
1174 Contains the the third element of the canonical triple representing the
1175 target as returned by @file{config.sub}. This variable is used by
1176 development tools to distinguish between subtle variations in object
1177 file formats that some vendors use across operating system releases. It
1178 might also be use to decide which libraries to build or what user
1179 interface the tool should provide.
1183 Is set to @code{true} if the user invoked configure with the @code{-nfp}
1184 command line option, otherwise it is empty. This is a request to target
1185 machines with @emph{no floating point} unit, even if the targets
1186 ordinarily have floating point units available. This option has no
1191 Is set to @code{true} if the user invoked configure with the @code{-gas}
1192 command line option, otherwise it is empty. This is a request to assume
1193 that all target machines have @sc{gas} available even if they ordinarily do
1194 not. The converse option @samp{-no-gas} is not available.
1198 Is set to @code{true} if the user invoked configure with the @code{-x}
1199 command line option, otherwise it is empty. This is a request to assume
1200 that @sc{mit x11} compatible headers files and libraries are available
1201 on all hosts, regardless of what is normally available on them.
1205 NOTE: support for @code{-subdirs} is at least temporarily suspended.
1207 Is set to the name of the directory containing the source for this
1208 program. This will be different from @file{.} if the user has specified
1209 either the @code{-srcdir=} or the @code{-subdirs} options. Note that
1210 @code{srcdir} is not necessarily an absolute path.
1213 @defvar{host_makefile_frag}
1214 If set by @file{configure.in}, this variable should be the name a file,
1215 relative to @code{srcdir} to be included in the resulting Makefile. If
1216 the named file does not exist, @code{configure} will print a warning
1217 message. This variable is not set by @code{configure}.
1220 @defvar{target_makefile_frag}
1221 If set by @file{configure.in}, this variable should be the name of a
1222 file, relative to @code{srcdir}, to be included in the resulting
1223 Makefile. If the named file does not exist, @code{configure} will print
1224 a warning message. This variable is not set by @code{configure}.
1227 @defvar{site_makefile_frag}
1228 Is set to a file name representing to the default Makefile fragment for
1229 this host. It may be set in @file{configure.in} to override this
1230 default. Normally @code{site_makefile_frag} is empty, but will have a
1231 value if the user specified @code{-site=} on the command line. It is
1232 probably not a good idea to override this variable from
1233 @file{configure.in}, since that may defeat the @code{configure} user's
1238 Is set to the name of the generated @file{Makefile}. Normally this
1239 value is precisely @file{Makefile} but some programs may want something
1244 Is normally empty but will be set to some non-empty value if the user
1245 specified @code{-rm} on the command line. That is, if @code{removing}
1246 is non-empty, then configure is @emph{removing} a configuration rather
1251 If this variable is non-empty following the @code{per-target:} section,
1252 then each word in its value will be the target of a symbolic link named
1253 in the corresponding word from the @code{links} variable.
1257 If the @code{files} variable is non-empty following the
1258 @code{per-target:} section, then @code{configure} creates symbolic links
1259 with the first word of @code{links} pointing to the first word of
1260 @code{files}, the second word of @code{links} pointing to the second
1261 word of @code{files}, and so on.
1264 @node Declarations, Per-host, Configure Variables, configure.in
1265 @subsection For each invocation
1267 @cindex Declarations section
1269 @code{configure} sources the entire shell script fragment from the start
1270 of @file{configure.in} up to a line beginning with @samp{# Per-host:}
1271 immediately after parsing command line arguments. The variables
1272 @code{srctrigger} and @code{srcname} @emph{must} be set here.
1274 You might also want to set the variables @code{configdirs} or
1275 @code{target_dependent} here.
1277 FIXME-soon. target_dependent isn't useful without multiple targets.
1279 @node Per-host, Per-target, Declarations, configure.in
1280 @subsection For each host
1281 @cindex per-host section
1282 @cindex host shell-script fragment
1284 The per-host section of @file{configure.in} starts with the line that begins
1285 with @samp{# Per-host:} and ends before a line beginning with
1286 @samp{# Per-target:}. @code{configure} sources the per-host section once for
1289 This section usually contains a big case statement using the variables
1290 @samp{host_cpu}, @samp{host_vendor}, and @samp{host_os} to determine
1291 appropriate values for @samp{host_makefile_frag} and @samp{files},
1292 although @samp{files} is not usually set here. Usually, it is set
1293 at the end of the per-target section after determining the names of the
1294 target specific configuration files.
1296 @node Per-target, Post-target, Per-host, configure.in
1297 @subsection For each target
1298 @cindex per-target section
1299 @cindex target shell-script fragment
1301 The per-target section of @file{configure.in} starts with the line that
1302 begins with @samp{# Per-target:} and ends before the line that begins
1303 with @samp{# Post-target:}, if there is such a line. Otherwise the
1304 per-target section extends to the end of the file. @code{configure} sources
1305 the per-target section once for each target before building any files,
1306 directories, or links.
1308 This section usually contains a big case statement using the variables called
1309 @samp{target_cpu}, @samp{target_vendor}, and @samp{target_os} to determine
1310 appropriate values for @samp{target_makefile_frag} and @samp{files}.
1311 The last lines in the per-target section normally set the variables
1312 @code{files} and @code{links}.
1314 @node Post-target, Example, Per-target, configure.in
1315 @subsection After each target
1317 The post-target section is optional. If it exists, the post-target
1318 section starts with a line beginning with @code{# Post-target:} and
1319 extends to the end of the file. If it exists, @code{configure} sources this
1320 section once for each target after building all files, directories, or
1323 This section is seldom needed, but you can use it to edit the Makefile
1324 generated by @code{configure}.
1326 @node Example, , Post-target, configure.in
1327 @subsection An example @file{configure.in}
1328 @cindex example @file{configure.in}
1329 @cindex sample @file{configure.in}
1330 @cindex Bison @file{configure.in}
1332 Here is a small example of a @file{configure.in} file.
1335 # This file is a collection of shell script fragments used to tailor
1336 # a template configure script as appropriate for this directory.
1337 # For more information, see configure.texi.
1340 srctrigger=warshall.c
1344 case "$@{host_os@}" in
1346 host_makefile_frag=config/mh-delta88
1352 files="bison_in.hairy"
1358 @node config.status, Makefile Fragments, configure.in, Reference
1359 @section @code{config.status}
1361 @kindex config.status
1363 The final step in configuring a directory is to create an executable
1364 shell script, @file{config.status}. The main purpose of this file
1365 is to allow the Makefile for the current directory to rebuild itself, if
1366 necessary. For this reason, @file{config.status} uses the
1367 @samp{-norecursion} option to @code{configure}, and is therefore
1368 probably inappropriate for reconfiguring a tree of source code.
1370 @node Makefile Fragments, , config.status, Reference
1371 @section Makefile Fragments
1373 @cindex Makefile fragments
1375 Cygnus @code{configure} uses three types of Makefile fragments. In a
1376 generated Makefile they appear in the order target fragment, host
1377 fragment, and site fragment. This allows host fragments to override
1378 target fragments, and site fragments to override both.
1380 Host specific Makefile fragments conventionally reside in the
1381 @file{./config} directory with names of the form
1382 @file{mh-@var{host}}. They are used for hosts that require
1383 odd options to the standard compiler and for compile time options based
1384 on the host configuration.
1386 Target specific Makefile fragments conventionally reside in the
1387 @file{./config} directory with names of the form @file{mt-@var{target}}.
1388 They are used for target dependent compile time options.
1390 Site specific Makefile fragments conventionally reside in the
1391 @file{./config} directory with names of the form @file{ms-@var{site}}.
1392 They are used to override host and target independent compile time
1393 options. Note that you can also overridde these options on the
1394 @code{make} invocation line.
1396 @node Known Bugs, Variables Index, Reference, top
1401 We know of the following bugs:
1406 There is no way to query about known hosts, known targets, or the
1407 porting or testing status of any configuration.
1410 The negations to the options @code{-gas}, @code{-x}, and @code{-nfp} are
1416 @node Variables Index, Concept Index, Known Bugs, top
1417 @appendix Variable Index
1422 @node Concept Index, , Variables Index, top
1423 @appendix Concept Index
1431 @c outline-regexp: "@chap"
1433 @c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")