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
16 * configure: (configure). Cygnus configure.
22 This document attempts to describe the Cygnus Support version of
25 Copyright 1991, 1992 Free Software Foundation, Inc.
26 Permission is granted to make and distribute verbatim copies of
27 this manual provided the copyright notice and this permission notice
28 are preserved on all copies.
31 Permission is granted to process this file through TeX and print the
32 results, provided the printed document carries copying permission
33 notice identical to this one except for the removal of this paragraph
34 (this paragraph not being relevant to the printed manual).
37 Permission is granted to copy and distribute modified versions of this
38 manual under the conditions for verbatim copying, provided that the entire
39 resulting derived work is distributed under the terms of a permission
40 notice identical to this one.
42 Permission is granted to copy and distribute translations of this manual
43 into another language, under the above conditions for modified versions,
44 except that this permission notice may be stated in a translation approved
50 @title{Cygnus Configure}
51 @subtitle @manvers, for Cygnus Configure version 1.84
52 @author{K. Richard Pixley, @code{rich@@cygnus.com}}
53 @author{Cygnus Support}
56 @vskip 0pt plus 1filll
57 Copyright @copyright{} 1991, 1992 Free Software Foundation, Inc.
59 Permission is granted to make and distribute verbatim copies of
60 this manual provided the copyright notice and this permission notice
61 are preserved on all copies.
63 Permission is granted to copy and distribute modified versions of this
64 manual under the conditions for verbatim copying, provided that the entire
65 resulting derived work is distributed under the terms of a permission
66 notice identical to this one.
68 Permission is granted to copy and distribute translations of this manual
69 into another language, under the above conditions for modified versions,
70 except that this permission notice may be stated in a translation approved
76 @node top, What Configure Does, (dir), (dir)
79 This file documents the configuration system used and distributed by
83 * What Configure Does:: What Configure Does
85 * Using Configure:: Using Configure
86 * Porting:: Porting with Configure
87 * Reference:: Gory details described
88 * Known Bugs:: Known Bugs
89 * Variables Index:: Variable Index
90 * Concept Index:: Concept Index
92 --- The Detailed Node Listing ---
96 * Install Locations:: Where to install things once they are built
97 * Build Directories:: Where to build object files
98 * Host:: Telling @code{configure} what will source will
100 * Target:: Telling @code{configure} what the source will
102 * Local Conventions:: Adding information about local conventions
106 * prefix:: Changing the default install directory
107 * exec_prefix:: How to separate host independent files
108 from host dependent files when
109 installing for multiple hosts
110 * Install Details:: Full descriptions of all installation
113 Porting with Configure
115 * Programs:: Adding configure to new programs
116 * Hosts and Targets:: Adding hosts and targets
117 * Sites:: Adding site info
119 Gory details described
121 * Makefile Extensions:: Extensions to the @sc{gnu} coding standards
122 * configure.in:: The format of the configure.in file
123 * config.status:: config.status
124 * Makefile Fragments:: Makefile Fragments
126 The format of the @file{configure.in} file
128 * Minimal:: A minimal configure.in
129 * Configure Variables:: Variables available to configure.in
130 * Declarations:: For each invocation
131 * Per-host:: For each host
132 * Per-target:: For each target
133 * Post-target:: After each target
134 * Example:: An example configure.in
139 @node What Configure Does, Invoking, top, top
140 @chapter What Configure Does
142 @code{configure} prepares source directories for building working
143 programs. A program cannot be built until its source has been
144 configured. When configure runs, it does the following things.
147 @item Create build directories
148 (see @ref{Build Directories}). When you run @code{configure} with the
149 @code{-srcdir=} option, it uses the current directory as build
150 directory, creating under it a directory tree that parallels the
151 directory structure under the source directory. (See @ref{Invoking}).
153 @item Generate makefiles
154 A makefile template from the source directory, usually called
155 @file{Makefile.in}, is copied to an output file in the build directory.
156 The output file is usually named @file{Makefile}. @code{configure}
157 places definitions for a number of standard makefile macros at the
158 beginning of the output file. If @code{-prefix=} or @code{-exec_prefix}
159 were specified on the @code{configure} command line, corresponding
160 makefile variables are set accordingly. If host, target, or site
161 specific makefile fragments exist, these are inserted into the output
162 file. (See @ref{Makefiles, , , make, Makefiles}.)
164 @item Generate @file{.gdbinit} If the source directory contains a
165 @file{.gdbinit} file and the build directory is not the same as the
166 source directory, a @file{.gdbinit} file is created in the build
167 directory. This @file{.gdbinit} file contains @code{dir} commands and
168 a @code{source} command, which will cause the @file{.gdbinit} file from
169 the source directory to be read by GDB, and will allow GDB to find
170 source files in either the source directory or the build directory.
171 (see @ref{Command Files, , , gdb, Command Files}.)
173 @item Make symbolic links
174 Most directories have some symbolic links with generic names built
175 pointing to specific files in the source directory. If the system where
176 @code{configure} runs cannot support symbolic links, hard links are used
180 If the source directory has special needs, they are handled by shell
181 script fragments stored with the source. Usually there are no special
182 needs, but sometimes they involve changes to the output makefile.
184 @item Generate @file{config.status}
185 @code{configure} creates a shell script named @file{config.status} in
186 the build directory. This shell script, when run from the build
187 directory, will reconfigure the build directory (but not its
188 subdirectories). This is most often used to have a @code{Makefile} update
189 itself automatically if a new source directory is available.
192 If the source directory has subdirectories that should also be
193 configured, @code{configure} is called for each.
196 @node Invoking, Using Configure, What Configure Does, top
199 The usual way to invoke @code{configure} is as follows:
203 This prepares the source to be compiled in a
204 @var{host} environment with programs and files to be installed in
207 @code{configure} prepares the source as you specify by selecting and
208 using script and Makefile fragments prepared in advance, and stored with
209 the source. @code{configure}'s command line options also allow you to
210 specify other aspects of the source configuration:
213 @item -exec_prefix=@var{dir}
214 Configure the source to install host dependent files in @var{dir}.
216 This option sets the @code{configure} variable @code{exec_prefix}.
217 Generated Makefiles will have their @code{exec_prefix} variables set to
218 this value. (See @ref{Install Details}.)
221 Configure to use the @sc{GNU} assembler.
224 Display a quick summary of how to invoke @code{configure}.
226 @item -host=@var{host}
227 FIXME-soon: I don't think this option should be documented.
228 @c Then why does it exist? /Pesch 7jan92
231 @emph{No floating point} unit available on the target; configure to
232 avoid dependencies on hardware floating point.
235 Configure only this directory; ignore any subdirectories. This is used
236 by the executable shell script @file{config.status} to reconfigure the
237 current directory. (see @ref{config.status}).
239 @item -prefix=@var{dir}
240 Configure the source to install programs and files under directory
243 This option sets the @code{configure} variable @code{prefix}. Generated
244 Makefiles will have their @code{prefix} variables set to this value.
245 (See @ref{Install Details}.)
247 @item -program_prefix=@var{string}
248 Configure the source to install certain programs using @var{string} as a
249 prefix. This applies to programs which might be used for cross-compilation,
250 such as the compiler and the binutils, and also to programs which have the same
251 name as a common Unix program, such as make.
253 This option sets the @code{configure} variable @code{program_prefix}.
254 Generated Makefiles will have their @code{program_prefix} variables set to this
255 value. (See @ref{Install Details}.)
257 @item -program_suffix=@var{string}
258 Configure the source to install certain programs using @var{string} as a
259 suffix. This applies to programs which might be used for cross-compilation.
261 @item -program_transform_name=@var{sed-pattern}
262 Configure the source to install certain programs using the names that result
263 from passing the usual name through @code{sed} invoked with @var{sed-pattern}.
264 This option may be given multiple times; each @var{sed-pattern} will be applied
265 in turn. This applies to programs which might be used for cross-compilation.
267 This option sets the @code{configure} variable @code{program_transform_name}.
268 Generated Makefiles will have their @code{program_transform_name} variables set
269 to this value. (See @ref{Install Details}.)
272 @c Wouldn't it make more sense to call this "-quiet"? (FIXME).
273 This option is used internally by @code{configure} when recurring on
274 subdirectories. Its sole purpose is to suppress status output. You can
275 override this effect with the @code{-verbose} option.
278 @emph{Remove} the configuration specified by @var{host} and the other
279 command-line options, rather than creating it.
281 @item -site=@var{site}
282 Generate Makefiles using site specific Makefile fragments for
283 @var{site}. See also @ref{Sites}.
285 @item -srcdir=@var{_dir}
286 Build Makefiles to use the sources located in directory @file{@var{dir}}. The
287 build directory is assumed to be @file{.}.
289 @item -target=@var{target}
290 Requests that the sources be configured to target the @var{target}
291 machine. If no target is specified explicitly, the target is assumed
292 to be the same as the host.
294 @item -tmpdir=@var{tmpdir}
295 Use the directory @var{tmpdir} for @code{configure}'s temporary files.
296 The default is the value of the environment variable TMPDIR, or
297 @file{/tmp} if the environment variable is not set.
301 Print status lines for each directory configured. Normally, only the
302 status lines for the initial working directory are printed.
305 Use @sc{MIT} style @sc{X11} header files and libraries on the host, even
306 if they are not normally available.
309 @node Using Configure, Porting, Invoking, top
310 @chapter Using Configure
312 The choices and options available at configuration time
313 generally have valid defaults, but the defaults do not cover all cases.
314 The choices available include install locations, build directories,
315 host, target, and local conventions.
318 * Install Locations:: Where to install things once they are built
319 * Build Directories:: Where to build object files
320 * Host:: Telling @code{configure} what will source will
322 * Target:: Telling @code{configure} what the source will
324 * Local Conventions:: Adding information about local conventions
327 @node Install Locations, Build Directories, Using Configure, Using Configure
328 @section Install Locations
329 @cindex Where to install
331 Using the default configuration, @code{make install} creates a
332 single tree of files, some of which are programs. The location of this
333 tree is determined by the value of the variable @code{prefix}. The
334 default value of @code{prefix} is @file{/usr/local}. This is
335 often correct for native tools installed on only one host.
338 * prefix:: Changing the default install directory
339 * exec_prefix:: How to separate host independent files
340 from host dependent files when
341 installing for multiple hosts
342 * Install Details:: Full descriptions of all installation
346 @node prefix, exec_prefix, Install Locations, Install Locations
347 @subsection Changing the default install directory
348 @cindex Changing the default install directory
349 @cindex Prefix directory
351 In the default configuration, all files are installed in subdirectories
352 of @file{/usr/local}. The location is determined by the value of
353 the @code{configure} variable @code{prefix}; in turn, this determines the
354 value of the Makefile variable of the same name (@code{prefix}).
356 You can also set the value of the Makefile variable @code{prefix}
357 explicitly each time you invoke @code{make} if you are so inclined; but
358 because many programs have this location compiled in, you must specify
359 the @code{prefix} value consistently on each invocation of @code{make},
360 or you will end up with a broken installation.
362 To make this easier, the value of the @code{configure} variable
363 @code{prefix} can be set on the command line to @code{configure}
364 using the option @code{-prefix=}.
367 @node exec_prefix, Install Details, prefix, Install Locations
368 @subsection Installing for multiple hosts
369 @cindex Configuring for multiple hosts
370 @cindex Sharing host independent files
371 @cindex The @file{exec_prefix} directory
372 @cindex Installing host independent files
374 By default, host dependent files are installed in subdirectories of
375 @file{@var{exec_prefix}}. The location is determined by the value of the
376 @code{configure} variable @code{exec_prefix}, which determines the value of
377 the Makefile variable @code{exec_prefix}. This makes it simpler to install
378 for a single host, and simplifies changing the default location for the
379 install tree; but the default doesn't allow for multiple hosts to
380 effectively share host independent files.
382 To configure so that multiple hosts can share common files, use
386 configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
387 make all info install install-info clean
389 configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
390 make all info install install-info
393 The first line configures the source for @var{host1} to place host
394 specific programs in subdirectories of @file{/usr/gnu/H-@var{host1}}.
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}}.
402 The fourth line builds and installs all programs for @var{host2}. Host
403 specific files are installed in new directories, but the host
404 independent files are installed @emph{on top of} the host
405 independent files installed for @var{host1}. This results in a single
406 copy of the host independent files, suitable for use by both hosts.
408 @node Install Details, , exec_prefix, Install Locations
409 @subsection Full descriptions of all installation subdirectories
411 During any install, a number of standard directories are created. Their
412 names are determined by Makefile variables. Some of the
413 defaults for Makefile variables can be changed at configure time using
414 command line options to @code{configure}. For more information on the
415 standard directories or the Makefile variables, please refer to
416 @cite{standards.text}.
418 Note that @code{configure} does not create the directory @code{srcdir}
419 at any time. @code{srcdir} is not an installation directory.
421 You can override all makefile variables on the command line to
422 @code{make}. (See @ref{Overriding, Overriding Variables, Overriding
423 Variables, make, Make}.) If you do so, you will need to specify the
424 value precisely the same way for each invocation of @code{make}, or you
425 risk ending up with a broken installation. This is because many
426 programs have the locations of other programs or files compiled into
427 them. If you find yourself overriding any of the variables frequently,
428 you should consider site dependent Makefile fragments. See also
431 During @code{make install}, a number of standard directories are
432 created and populated. The following Makefile variables define them.
433 Those whose defaults are set by corresponding @code{configure} variables
434 are marked ``Makefile and configure''.
437 @defvr {Makefile and configure} prefix
438 The root of the installation tree. You can set
439 its Makefile default with the @code{-prefix=} command line option to
440 @code{configure}. (@ref{Invoking}.) The default value for
441 @code{prefix} is @file{/usr/local}.
445 @defvr Makefile bindir
446 A directory for binary programs that users can run.
447 The default value for @code{bindir} depends on @code{prefix};
448 @code{bindir} is normally changed only indirectly through @code{prefix}.
449 The default value for @code{bindir} is @file{$(prefix)/bin}.
453 @defvr {Makefile and configure} exec_prefix
454 A directory for host dependent files. You can specify the Makefile
455 default value by using the @code{-exec_prefix=} option to @code{configure}.
456 (See also @ref{Invoking}.) The default value for @code{exec_prefix} is
461 @defvr Makefile libdir
462 A directory for libraries and support programs. The default value for
463 @code{libdir} depends on @code{prefix}; @code{libdir} is normally
464 changed only indirectly through @code{prefix}. The default value for
465 @code{libdir} is @file{$(prefix)/lib}.
469 @defvr Makefile mandir
470 A directory for @code{man} format documentation (``man pages''). The
471 default value for @code{mandir} depends on @code{prefix};
472 @code{mandir} is normally changed only indirectly through @code{prefix}.
473 The default value for @code{mandir} is @file{$(prefix)/man}.
476 @vindex man@var{N}dir
477 @defvr Makefile man@var{N}dir
478 There are eight variables named @code{man1dir}, @code{man2dir}, etc.
479 They name the specific directories for each man page section. For
480 example, @code{man1dir} holds @file{emacs.1} (the man page for the emacs
481 program), while @code{man5dir} holds @file{rcsfile.5} (the man page
482 describing the @code{rcs} data file format). The default value for any
483 of the @code{man@var{N}dir} variables depends indirectly on
484 @code{prefix}, and is normally changed only through @code{prefix}. The
485 default value for @code{man@var{N}dir} is
486 @file{$(mandir)/man@var{N}}.
490 @defvr Makefile manext
491 @emph{Not supported by @code{configure}}. The @sc{gnu} coding standards
492 do not call for @code{man1ext}, @code{man2ext}, so the intended use for
493 @code{manext} is apparently not parallel to @code{mandir}. Its use is
494 not clear. (See also @ref{Makefile Extensions}.)
498 @defvr Makefile infodir
499 A directory for @emph{info} format documentation. The default value for
500 @code{infodir} depends indirectly on @code{prefix}; @code{infodir} is
501 normally changed only through @code{prefix}. The default value for
502 @code{infodir} is @file{$(prefix)/info}.
506 @defvr Makefile docdir
507 A directory for any documentation that is in a format other than those
508 used by @code{info} or @code{man}. The default value for @code{docdir}
509 depends indirectly on @code{prefix}; @code{docdir} is normally changed only
510 through @code{prefix}. The default value for @code{docdir}
511 is @file{$(datadir)/doc}. @emph{This variable is an extension to
512 the @sc{gnu} coding standards}. (See also @ref{Makefile Extensions}.)
516 @defvr Makefile includedir
517 A directory for the header files accompanying the libraries installed in
518 @code{libdir}. The default value for @code{includedir} depends on
519 @code{prefix}; @code{includedir} is normally changed only indirectly
520 through @code{prefix}. The default value for @code{includedir} is
521 @file{$(prefix)/include}.
524 @node Build Directories, Host, Install Locations, Using Configure
525 @section Build Directories
526 @cindex Build directories
528 @cindex Object directories
530 @cindex Building for multiple hosts
531 @cindex Building for multiple targets
533 Normally, @code{configure} builds a @file{Makefile} and symbolic links
534 in the same directory as the source files. This is the typical
535 @sc{un*x} way to build programs, but it has limitations. For instance,
536 using this approach, you can only build for one host at a time.
538 We refer to the directories where @code{configure} builds a
539 Makefile as the @emph{build directories} or sometimes as
540 @emph{objdir} because these are the directories in which @code{make}
541 will build object files, among other things.
543 The default build directory is the same as the source directory.
544 You can use a different build directory with a sequence like the following:
549 configure @var{host} -srcdir=@var{sourcedirectory}
553 where @var{builddir} is the directory where you wish to build,
554 @var{host} is the host for which you want to build, and
555 @var{sourcedirectory} is the directory containing the source files.
557 If you were to do this twice with different values for @var{builddir}
558 and @var{host}, then you could @code{make} for both at the same time.
560 @node Host, Target, Build Directories, Using Configure
563 The arguments to @code{configure} are @emph{hosts}. By @emph{host} we
564 mean the environment in which the source will be compiled. This need
565 not necessarily be the same as the physical machine involved,
566 although it usually is.
568 For example, if some obscure machine running an operating system other
569 than @sc{un*x} had the @sc{gnu} @sc{posix} emulation libraries
570 available, it would be possible to configure most @sc{gnu} source for a
571 @sc{posix} system and build it on the obscure host.
573 For more on this topic, see @ref{Host Environments, , Host Environments,
574 cfg-paper, On Configuring Development Tools}.
576 @node Target, Local Conventions, Host, Using Configure
579 For building native development tools, or most of the other @sc{gnu}
580 tools, you need not worry about the target. The @emph{target} of a
581 configuration defaults to the same as the @emph{host}.
583 For building cross development tools, please see @ref{Building
584 Development Environments, , Building Development Environments,
585 cfg-paper, On Configuring Development Tools}.
587 @node Local Conventions, , Target, Using Configure
588 @section Local Conventions
590 If you find that a tool does not get configured to your liking, or if
591 @code{configure}'s conventions differ from your local conventions, you
592 should probably consider site specific Makefile fragments. See also
595 These are probably not the right choice for options that can be set from
596 the @code{configure} command line or for differences that are host or
599 @node Porting, Reference, Using Configure, top
600 @chapter Porting with Configure
603 This section explains how to add programs, host and target configuration
604 names, and site-specific information to Cygnus configure.
607 * Programs:: Adding configure to new programs
608 * Hosts and Targets:: Adding hosts and targets
609 * Sites:: Adding site info
613 @node Programs, Hosts and Targets, Porting, Porting
614 @section Adding Configure To New Programs
616 If you are writing a new program, you probably shouldn't worry about
617 porting issues or configure until it is running reasonably on some host.
618 Then refer back to this section.
620 If the program in question currently has a configure script that meets
621 the criteria set out by @cite{standards.text}, please do not add Cygnus
622 configure. It should be possible to add this program without change to
623 a Cygnus configure style source tree.
625 If the program is not target dependent, please consider using
626 @code{autoconf} instead of Cygnus configure. @code{autoconf} will
627 be available soon from the @sc{fsf}.
629 To add Cygnus configure to an existing program, do the following:
632 @item Make sure the Makefile conforms to @sc{gnu} standard
633 The coding standard for @sc{gnu} Makefiles is described in
634 @cite{standards.text}.
636 @item Add Cygnus extensions to the Makefile
637 These are described in @ref{Makefile Extensions}.
639 @item Move host support from Makefile to fragments
640 This usually involves finding sections of the Makefile that say things
641 like ``uncomment these lines for host foo'' and moving them to a new
642 file called @file{./config/mh-foo}. For more information, see @ref{Hosts
645 @item Choose defaults
646 If the program has compile time options that determine the way the
647 program should behave, chose reasonable defaults and make these Makefile
648 variables. Be sure the variables are assigned their default values
649 before the @code{####} line so that site specific Makefile fragments can
650 override them (@pxref{Makefile Extensions,,Extensions to the @sc{gnu}
653 @item Locate configuration files
654 If there is configuration information in header files or source files,
655 separate it in such a way that the files have a generic name. Then move
656 the specific instances of those files into the @file{./config}
659 @item Separate host and target information
660 Some programs already have this information separated. If yours does
661 not, you will need to separate these two kinds of configuration
662 information. @dfn{Host specific} information is the information needed to
663 compile the program. @dfn{Target specific} information is information on the
664 format of data files that the program will read or write. This
665 information should live in separate files in the @file{./config}
666 directory with names that reflect the configuration for which they are
669 At this point you might skip this step and simply move on. If you do,
670 you should end up with a program that can be configured only to build
671 native tools, that is, tools for which the host system is also the
672 target system. Later, you could attempt to build a cross tool and
673 separate out the target specific information by figuring out what went
674 wrong. This is often simpler than combing through all of the source
677 @item Write @code{configure.in}
678 Usually this involves writing shell script fragments to map from
679 canonical configuration names into the names of the configuration files.
680 These files will then be linked at configure time from the specific
681 instances of those files in @file{./config} to file in the build
682 directory with more generic names. (see also @ref{Build Directories}).
683 The format of configure.in is described in @ref{configure.in}.
685 @item Rename @file{Makefile} to @file{Makefile.in}
688 At this point you should have a program that can be configured using
689 Cygnus @code{configure}.
691 @node Hosts and Targets, Sites, Programs, Porting
692 @section Adding hosts and targets
694 To add a host or target to a program that already uses Cygnus
695 configure, do the following.
700 Make sure the new configuration name is represented in
701 @file{config.sub}. If not, add it. For more details, see the comments
702 in the shell script @file{config.sub}.
705 If you are adding a host configuration, look in @file{configure.in}, in
706 the per-host section. Make sure that your configuration name is
707 represented in the mapping from host configuration names to
708 configuration files. If not, add it. Also see @ref{configure.in}.
711 If you are adding a target configuration, look in @file{configure.in},
712 in the per-target section. Make sure that your configuration name is
713 represented in the mapping from target configuration names to
714 configuration files. If not, add it. Also see @ref{configure.in}.
717 Look in @file{configure.in} for the variables @samp{files},
718 @samp{links}, @samp{host_makefile_frag}, and
719 @samp{target_makefile_frag}. The values assigned to these variables are
720 the names of the configuration files, relative to @code{srcdir} that the
721 program uses. Make sure that copies of the files exist for your host.
722 If not, create them. See also @ref{Configure Variables}.
725 This should be enough to configure for a new host or target
726 configuration name. Getting the program to compile and run properly
727 remains the hard work of the port.
729 @node Sites, , Hosts and Targets, Porting
730 @section Adding site info
732 If some of the Makefile defaults are not right for your site, you can
733 build site specific Makefile fragments. To do this, do the following.
738 Choose a name for your site. It must be less than eleven characters for
742 If the program source does not have a @file{./config} directory, create it.
745 Create a file called @file{./config/ms-@var{site}} where @var{site} is
746 the name of your site. In it, set whatever Makefile variables you need
747 to override to match your site's conventions.
750 Configure the program with:
753 configure @dots{} +site=@var{site}
758 @node Reference, Known Bugs, Porting, top
759 @chapter Gory details described
762 Here we describe the backend support.
765 * Makefile Extensions:: Extensions to the @sc{gnu} coding standards
766 * configure.in:: The format of the configure.in file
767 * config.status:: config.status
768 * Makefile Fragments:: Makefile Fragments
771 @node Makefile Extensions, configure.in, Reference, Reference
772 @section Extensions to the @sc{gnu} coding standards
774 @cindex Makefile extensions
775 @cindex Cygnus extensions
777 The following additions to the @sc{gnu} coding standards are required
778 for Cygnus configure to work properly.
782 The Makefile must contain exactly one line starting with @code{####}.
783 This line should follow any default macro definitions but precede any
784 rules. Host, target, and site specific Makefile fragments will be
785 inserted immediately after this line. If the line is missing, the
786 fragments will not be inserted.
789 Cygnus adds the following targets to our Makefiles. Their existence is
790 not required for Cygnus configure, but they are documented here for
796 Build all info files from texinfo source.
800 Install all info files.
804 Remove all info files and any intermediate files that can be generated
829 These targets are in transition and may be removed shortly.
832 In addition, the following Makefile targets have revised semantics:
837 Should @emph{not} depend on the target @code{all}. If the program is
838 not already built, @code{make install} should fail. This allows you
839 to install programs even when @code{make} would otherwise determine
840 them to be out of date. This can happen when the result of a @code{make
841 all} is transported via tape to another machine for installation as
842 well as in a number of other cases.
846 Should remove any file that can be regenerated by the Makefile,
847 excepting only the Makefile itself, and any links created by configure.
848 That is, @code{make all clean} should return all directories to their
849 original condition. If this is not done, then:
852 configure @var{host1} ; make all clean ; configure @var{host2} ; make all
856 will fail because of intermediate files intended for @var{host1}.
859 Cygnus adds the following macros to all @file{Makefile.in} files, but
860 you are not required to use them to run Cygnus configure.
865 The directory in which to install any documentation that is not either a
866 man page or an info file. For man pages, see mandir, for info, see
871 The directory in which to install any headers files that should be made
872 available to users. This is distinct from the @code{gcc} include
873 directory which is intended for @code{gcc} only. Files in
874 @code{includedir} may be used by @code{cc} as well.
877 In addition, the following macros have revised semantics. Most of them
878 describe installation directories; see also @ref{Install Details,,Full
879 description of all installation subdirectories}.
885 is not used. The intended usage is not clear. For example, if you have a
886 @file{foo.man} and a @file{bar.man}, and @file{foo.man} is destined for
887 @file{/usr/local/lib/man/man1/foo.1} while @file{bar.man} is destined
888 for @file{/usr/local/lib/man/man5/bar.5}, then what is the desired value
893 is used for host independent data files.
897 The default path for @code{mandir} depends on @code{prefix}.
901 The default path for @code{infodir} depends on @code{prefix}.
905 is assumed to have a @code{yacc} calling convention. To use
906 @code{bison}, use @code{BISON=bison -y}.
909 Cygnus Makefiles also conform to one additional restriction:
913 When libraries are installed, the line containing the call to
914 @code{INSTALL_DATA} should always be followed by a line containing a
915 call to @code{RANLIB} on the installed library. This is to accomodate
916 systems that use @code{ranlib}. Systems that do not use @code{ranlib}
917 can set @code{RANLIB} to @code{echo} in a host specific Makefile
921 @node configure.in, config.status, Makefile Extensions, Reference
922 @section The format of the @file{configure.in} file
925 A @file{configure.in} file for Cygnus configure consists of a
926 @dfn{per-invocation} section, followed by a @dfn{per-host} section,
927 followed by a @dfn{per-target} section, optionally followed by a
928 @dfn{post-target} section. Each section is a shell script fragment,
929 which is sourced by the configure shell script at an appropriate time.
930 Values are passed among configure and the shell fragments through a
931 set of shell variables. When each section is being interpreted
932 (sourced) by the shell, the shell's current directory is the build
933 directory, and any files created by the section (or referred to by the
934 section) will be relative to the build directory. To reference files
935 in other places (such as the source directory), prepend a shell
936 variable such as @code{srcdir} to the desired file name.
938 @cindex Per-invocation section
939 The beginning of the @file{configure.in} file begins the per-invocation
942 @cindex Per-host section
943 A line beginning with @code{# Per-host:} begins the per-host section.
945 @cindex Per-target section
946 A line beginning with @code{# Per-target:} begins the per-target
949 @cindex Post-target section
950 If it exists, the post-target section begins with @code{# Per-target:}.
953 * Minimal:: A minimal configure.in
954 * Configure Variables:: Variables available to configure.in
955 * Declarations:: For each invocation
956 * Per-host:: For each host
957 * Per-target:: For each target
958 * Post-target:: After each target
959 * Example:: An example configure.in
962 @node Minimal, Configure Variables, configure.in, configure.in
963 @subsection A minimal @file{configure.in}
965 @cindex Minimal @file{configure.in} example
966 A minimal @file{configure.in} consists of four lines.
970 srcname="source for the foo program"
975 The @samp{Per-host} and @samp{Per-target} lines divide the file into the
976 three required sections. The @samp{srctrigger} line names a file.
977 @code{configure} checks to see that this file exists in the source
978 directory before configuring. If the @samp{srctrigger} file does not
979 exist, @code{configure} uses the value of @samp{srcname} to print an
980 error message about not finding the source.
982 This particular example uses no links, and only the default host,
983 target, and site specific Makefile fragments if they exist.
985 @node Configure Variables, Declarations, Minimal, configure.in
986 @subsection Variables available to configure.in
988 @cindex @file{configure.in} interface
990 The following variables pass information between the standard parts of
991 @code{configure} and the shell-script fragments in @file{configure.in}:
994 Contains the name of a source file that is expected to live in the
995 source directory. You must usually set this in the per-invocation
996 section of @file{configure.in}. Configure tests to see that this file
997 exists. If the file does not exist, configure prints an error message.
998 This is used as a sanity check that configure.in matches the source
1003 Contains the name of the source collection contained in the source
1004 directory. You must usually set this in the per-invocation section of
1005 @file{configure.in}. If the file named in @code{srctrigger} does not
1006 exist, configure uses the value of this variable when it prints the
1011 Contains the names of any subdirectories where @code{configure} should
1012 recur. You must usually set this in the per-invocation section of
1013 @file{configure.in}.
1014 If @file{Makefile.in} contains a line starting with @code{SUBDIRS =},
1015 then it will be replaced with an assignment to @code{SUBDIRS} using
1016 the value of @code{configdirs} (if @code{subdirs} is empty). This can
1017 be used to determine which directories to configure and build depending
1018 on the host and target configurations.
1019 @c Most other matching makefile/config vars use the same name. Why not
1021 @c Can we get rid of SUBDIRS-substitution? It doesn't work well with subdirs.
1022 Use @code{configdirs} (instead of the @code{subdirs} variable
1023 described below) if you want to be able to partition the
1024 sub-directories, or use independent Makefile fragments.
1025 Each sub-directory can be independent, and independently re-configured.
1029 Contains the names of any subdirectories where @code{configure} should
1030 create a @code{Makefile} (in addition to the current directory),
1031 @emph{without} recursively running @code{configure}.
1032 Use @code{subdirs} (instead of the @code{configdirs} variable
1033 described above) if you want to configure all of the directories
1034 as a unit. Since there is a single invocation of @code{configure}
1035 that configures many directories, all the directories can use the
1036 same Makefile fragments, and the same @code{configure.in}.
1040 Contains the full configuration name (generated by the script
1041 @file{config.sub} from the name that the user entered) for the host.
1042 This is a three-part name of the form
1045 @var{cpu}-@var{vendor}-@var{os}
1049 There are separate variables @code{host_cpu}, @code{host_vendor}, and
1050 @code{host_os} that you can use to test each of the three parts; this
1051 variable is useful, however, for error messages, and for testing
1052 combinations of the three components.
1056 Contains the first element of the canonical triple representing the host
1057 as returned by @file{config.sub}. This is occasionally used to
1058 distinguish between minor variations of a particular vendor's operating
1059 system and sometimes to determine variations in binary format between
1060 the host and the target.
1063 @defvar{host_vendor}
1064 Contains the second element of the canonical triple representing the
1065 host as returned by @file{config.sub}. This is usually used to
1066 distinguish betwen the numerous variations between @emph{common}
1068 @c "@emph{common} OS" doesn't convey much to me. Is this meant to cover
1069 @c cases like Unix, widespread but with many variations?
1073 Contains the the third element of the canonical triple representing the
1074 host as returned by @file{config.sub}.
1078 Contains the full configuration name (generated by the script
1079 @file{config.sub} from the name that the user entered) for the target.
1080 This is a three-part name of the form
1083 @var{cpu}-@var{vendor}-@var{os}
1087 There are separate variables @code{target_cpu}, @code{target_vendor}, and
1088 @code{target_os} that you can use to test each of the three parts; this
1089 variable is useful, however, for error messages, and for testing
1090 combinations of the three components.
1094 Contains the first element of the canonical triple representing the
1095 target as returned by @file{config.sub}. This is used heavily by
1096 programs involved in building programs, like the compiler, assembler,
1097 linker, etc. Most programs will not need the @code{target} variables at
1098 all, but this one could conceivably be used to build a program, for
1099 instance, that operated on binary data files whose byte order or
1100 alignment differ from the system where the program is running.
1103 @defvar{target_vendor}
1104 Contains the second element of the canonical triple representing the
1105 target as returned by @file{config.sub}. This is usually used to
1106 distinguish betwen the numerous variations between @emph{common}
1107 operating systems or object file formats. Sometimes it is used to
1108 switch between different flavors of user interfaces.
1109 @c above query re "@emph{common} OS" applies here too
1113 Contains the the third element of the canonical triple representing the
1114 target as returned by @file{config.sub}. This variable is used by
1115 development tools to distinguish between subtle variations in object
1116 file formats that some vendors use across operating system releases. It
1117 might also be use to decide which libraries to build or what user
1118 interface the tool should provide.
1121 @defvar{floating_point}
1122 Is set to @code{no} if the user invoked configure with the @code{-nfp}
1123 command line option, otherwise it is empty. This is a request to target
1124 machines with @emph{no floating point} unit, even if the targets
1125 ordinarily have floating point units available. This option has no
1130 Is set to @code{true} if the user invoked configure with the @code{-gas}
1131 command line option, otherwise it is empty. This is a request to assume
1132 that all target machines have @sc{gas} available even if they ordinarily do
1133 not. The converse option @samp{-no-gas} is not available.
1137 Is set to @code{true} if the user invoked configure with the @code{-x}
1138 command line option, otherwise it is empty. This is a request to assume
1139 that @sc{mit x11} compatible headers files and libraries are available
1140 on all hosts, regardless of what is normally available on them.
1144 Is set to the name of the directory containing the source for this
1145 program. This will be different from @file{.} if the user has specified
1146 the @code{-srcdir=} option. Note that @code{srcdir} is not necessarily
1150 @defvar{host_makefile_frag}
1151 If set by @file{configure.in}, this variable should be the name a file,
1152 relative to @code{srcdir} to be included in the resulting Makefile. If
1153 the named file does not exist, @code{configure} will print a warning
1154 message. This variable is not set by @code{configure}.
1157 @defvar{target_makefile_frag}
1158 If set by @file{configure.in}, this variable should be the name of a
1159 file, relative to @code{srcdir}, to be included in the resulting
1160 Makefile. If the named file does not exist, @code{configure} will print
1161 a warning message. This variable is not set by @code{configure}.
1164 @defvar{site_makefile_frag}
1165 Is set to a file name representing to the default Makefile fragment for
1166 this host. It may be set in @file{configure.in} to override this
1167 default. Normally @code{site_makefile_frag} is empty, but will have a
1168 value if the user specified @code{-site=} on the command line. It is
1169 probably not a good idea to override this variable from
1170 @file{configure.in}, since that may defeat the @code{configure} user's
1175 Is set to the name of the generated @file{Makefile}. Normally this
1176 value is precisely @file{Makefile} but some programs may want something
1181 Is normally empty but will be set to some non-empty value if the user
1182 specified @code{-rm} on the command line. That is, if @code{removing}
1183 is non-empty, then configure is @emph{removing} a configuration rather
1188 If this variable is non-empty following the @code{per-target:} section,
1189 then each word in its value will be the target of a symbolic link named
1190 in the corresponding word from the @code{links} variable.
1194 If the @code{files} variable is non-empty following the
1195 @code{per-target:} section, then @code{configure} creates symbolic links
1196 with the first word of @code{links} pointing to the first word of
1197 @code{files}, the second word of @code{links} pointing to the second
1198 word of @code{files}, and so on.
1201 @node Declarations, Per-host, Configure Variables, configure.in
1202 @subsection For each invocation
1204 @cindex Declarations section
1206 @code{configure} sources the entire shell script fragment from the start
1207 of @file{configure.in} up to a line beginning with @samp{# Per-host:}
1208 immediately after parsing command line arguments. The variables
1209 @code{srctrigger} and @code{srcname} @emph{must} be set here.
1211 You might also want to set the variable @code{configdirs} here.
1213 @node Per-host, Per-target, Declarations, configure.in
1214 @subsection For each host
1215 @cindex per-host section
1216 @cindex host shell-script fragment
1218 The per-host section of @file{configure.in} starts with the line that begins
1219 with @samp{# Per-host:} and ends before a line beginning with
1220 @samp{# Per-target:}. @code{configure} sources the per-host section once for
1223 This section usually contains a big case statement using the variables
1224 @samp{host_cpu}, @samp{host_vendor}, and @samp{host_os} to determine
1225 appropriate values for @samp{host_makefile_frag} and @samp{files},
1226 although @samp{files} is not usually set here. Usually, it is set
1227 at the end of the per-target section after determining the names of the
1228 target specific configuration files.
1230 @node Per-target, Post-target, Per-host, configure.in
1231 @subsection For each target
1232 @cindex per-target section
1233 @cindex target shell-script fragment
1235 The per-target section of @file{configure.in} starts with the line that
1236 begins with @samp{# Per-target:} and ends before the line that begins
1237 with @samp{# Post-target:}, if there is such a line. Otherwise the
1238 per-target section extends to the end of the file. @code{configure} sources
1239 the per-target section once for each target before building any files,
1240 directories, or links.
1242 This section usually contains a big case statement using the variables called
1243 @samp{target_cpu}, @samp{target_vendor}, and @samp{target_os} to determine
1244 appropriate values for @samp{target_makefile_frag} and @samp{files}.
1245 The last lines in the per-target section normally set the variables
1246 @code{files} and @code{links}.
1248 @node Post-target, Example, Per-target, configure.in
1249 @subsection After each target
1251 The post-target section is optional. If it exists, the post-target
1252 section starts with a line beginning with @code{# Post-target:} and
1253 extends to the end of the file. If it exists, @code{configure} sources this
1254 section once for each target after building all files, directories, or
1257 This section is seldom needed, but you can use it to edit the Makefile
1258 generated by @code{configure}.
1260 @node Example, , Post-target, configure.in
1261 @subsection An example @file{configure.in}
1262 @cindex example @file{configure.in}
1263 @cindex sample @file{configure.in}
1264 @cindex Bison @file{configure.in}
1266 Here is a small example of a @file{configure.in} file.
1269 # This file is a collection of shell script fragments used to tailor
1270 # a template configure script as appropriate for this directory.
1271 # For more information, see configure.texi.
1274 srctrigger=warshall.c
1278 case "$@{host_os@}" in
1280 host_makefile_frag=config/mh-delta88
1286 files="bison_in.hairy"
1292 @node config.status, Makefile Fragments, configure.in, Reference
1293 @section @code{config.status}
1295 @kindex config.status
1297 The final step in configuring a directory is to create an executable
1298 shell script, @file{config.status}. The main purpose of this file
1299 is to allow the Makefile for the current directory to rebuild itself, if
1300 necessary. For this reason, @file{config.status} uses the
1301 @samp{-norecursion} option to @code{configure}, and is therefore
1302 probably inappropriate for reconfiguring a tree of source code.
1304 @node Makefile Fragments, , config.status, Reference
1305 @section Makefile Fragments
1307 @cindex Makefile fragments
1309 Cygnus @code{configure} uses three types of Makefile fragments. In a
1310 generated Makefile they appear in the order target fragment, host
1311 fragment, and site fragment. This allows host fragments to override
1312 target fragments, and site fragments to override both.
1314 Host specific Makefile fragments conventionally reside in the
1315 @file{./config} directory with names of the form
1316 @file{mh-@var{host}}. They are used for hosts that require
1317 odd options to the standard compiler and for compile time options based
1318 on the host configuration.
1320 Target specific Makefile fragments conventionally reside in the
1321 @file{./config} directory with names of the form @file{mt-@var{target}}.
1322 They are used for target dependent compile time options.
1324 Site specific Makefile fragments conventionally reside in the
1325 @file{./config} directory with names of the form @file{ms-@var{site}}.
1326 They are used to override host and target independent compile time
1327 options. Note that you can also override these options on the
1328 @code{make} invocation line.
1330 @node Known Bugs, Variables Index, Reference, top
1335 We know of the following bugs:
1340 There is no way to query about known hosts, known targets, or the
1341 porting or testing status of any configuration.
1344 The negations to the options @code{-gas}, @code{-x}, and @code{-nfp} are
1350 @node Variables Index, Concept Index, Known Bugs, top
1351 @appendix Variable Index
1356 @node Concept Index, , Variables Index, top
1357 @appendix Concept Index
1365 @c outline-regexp: "@chap"
1367 @c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")