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, 1992 Cygnus Support
18 Permission is granted to make and distribute verbatim copies of
19 this manual provided the copyright notice and this permission notice
20 are preserved on all copies.
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, 1992 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
80 * What Configure Does:: What Configure Does
82 * Using Configure:: Using Configure
83 * Porting:: Porting with Configure
84 * Reference:: Gory details described
85 * Known Bugs:: Known Bugs
86 * Variables Index:: Variable Index
87 * Concept Index:: Concept Index
89 --- The Detailed Node Listing ---
93 * Install Locations:: Where to install things once they are built
94 * Build Directories:: Where to build object files
95 * Host:: Telling @code{configure} what will source will
97 * Target:: Telling @code{configure} what the source will
99 * Local Conventions:: Adding information about local conventions
103 * prefix:: Changing the default install directory
104 * exec_prefix:: How to separate host independent files
105 from host dependent files when
106 installing for multiple hosts
107 * Install Details:: Full descriptions of all installation
110 Porting with Configure
112 * Programs:: Adding configure to new programs
113 * Hosts and Targets:: Adding hosts and targets
114 * Sites:: Adding site info
116 Gory details described
118 * Makefile Extensions:: Extensions to the @sc{gnu} coding standards
119 * configure.in:: The format of the configure.in file
120 * config.status:: config.status
121 * Makefile Fragments:: Makefile Fragments
123 The format of the @file{configure.in} file
125 * Minimal:: A minimal configure.in
126 * Configure Variables:: Variables available to configure.in
127 * Declarations:: For each invocation
128 * Per-host:: For each host
129 * Per-target:: For each target
130 * Post-target:: After each target
131 * Example:: An example configure.in
136 @node What Configure Does, Invoking, top, top
137 @chapter What Configure Does
139 @code{configure} prepares source directories for building working
140 programs. A program cannot be built until its source has been
141 configured. When configure runs, it does the following things.
144 @item Create build directories
145 (see @ref{Build Directories}). When you run @code{configure} with the
146 @code{-srcdir=} option, it uses the current directory as build
147 directory, creating under it a directory tree that parallels the
148 directory structure under the source directory. (See @ref{Invoking}).
150 @item Generate makefiles
151 A makefile template from the source directory, usually called
152 @file{Makefile.in}, is copied to an output file in the build directory.
153 The output file is usually named @file{Makefile}. @code{configure}
154 places definitions for a number of standard makefile macros at the
155 beginning of the output file. If @code{-prefix=} or @code{-exec_prefix}
156 were specified on the @code{configure} command line, corresponding
157 makefile variables are set accordingly. If host, target, or site
158 specific makefile fragments exist, these are inserted into the output
159 file. (See @ref{Makefiles, , , make, Makefiles}.)
161 @item Generate @file{.gdbinit} If the source directory contains a
162 @file{.gdbinit} file and the build directory is not the same as the
163 source directory, a @file{.gdbinit} file is created in the build
164 directory. This @file{.gdbinit} file contains @code{dir} commands and
165 a @code{source} command, which will cause the @file{.gdbinit} file from
166 the source directory to be read by GDB, and will allow GDB to find
167 source files in either the source directory or the build directory.
168 (see @ref{Command Files, , , gdb, Command Files}.)
170 @item Make symbolic links
171 Most directories have some symbolic links with generic names built
172 pointing to specific files in the source directory. If the system where
173 @code{configure} runs cannot support symbolic links, hard links are used
177 If the source directory has special needs, they are handled by shell
178 script fragments stored with the source. Usually there are no special
179 needs, but sometimes they involve changes to the output makefile.
181 @item Generate @file{config.status}
182 @code{configure} creates a shell script named @file{config.status} in
183 the build directory. This shell script, when run from the build
184 directory, will reconfigure the build directory (but not its
185 subdirectories). This is most often used to have a @code{Makefile} update
186 itself automatically if a new source directory is available.
189 If the source directory has subdirectories that should also be
190 configured, @code{configure} is called for each.
193 @node Invoking, Using Configure, What Configure Does, top
196 The usual way to invoke @code{configure} is as follows:
200 This prepares the source to be compiled in a
201 @var{host} environment with programs and files to be installed in
204 @code{configure} prepares the source as you specify by selecting and
205 using script and Makefile fragments prepared in advance, and stored with
206 the source. @code{configure}'s command line options also allow you to
207 specify other aspects of the source configuration:
210 @item -exec_prefix=@var{dir}
211 Configure the source to install host dependent files in @var{dir}.
213 This option sets the @code{configure} variable @code{exec_prefix}.
214 Generated Makefiles will have their @code{exec_prefix} variables set to
215 this value. (See @ref{Install Details}.)
218 Configure to use the @sc{GNU} assembler.
221 Display a quick summary of how to invoke @code{configure}.
223 @item -host=@var{host}
224 FIXME-soon: I don't think this option should be documented.
225 @c Then why does it exist? /Pesch 7jan92
228 @emph{No floating point} unit available on the target; configure to
229 avoid dependencies on hardware floating point.
232 Configure only this directory; ignore any subdirectories. This is used
233 by the executable shell script @file{config.status} to reconfigure the
234 current directory. (see @ref{config.status}).
236 @item -prefix=@var{dir}
237 Configure the source to install programs and files under directory
240 This option sets the @code{configure} variable @code{prefix}. Generated
241 Makefiles will have their @code{prefix} variables set to this value.
242 (See @ref{Install Details}.)
245 @c Wouldn't it make more sense to call this "-quiet"? (FIXME).
246 This option is used internally by @code{configure} when recurring on
247 subdirectories. Its sole purpose is to suppress status output. You can
248 override this effect with the @code{-verbose} option.
251 @emph{Remove} the configuration specified by @var{host} and the other
252 command-line options, rather than creating it.
254 @item -site=@var{site}
255 Generate Makefiles using site specific Makefile fragments for
256 @var{site}. See also @ref{Sites}.
258 @item -srcdir=@var{_dir}
259 Build Makefiles to use the sources located in directory @file{@var{dir}}. The
260 build directory is assumed to be @file{.}.
262 @item -target=@var{target}
263 Requests that the sources be configured to target the @var{target}
264 machine. If no target is specified explicitly, the target is assumed
265 to be the same as the host.
267 @item -tmpdir=@var{tmpdir}
268 Use the directory @var{tmpdir} for @code{configure}'s temporary files.
269 The default is the value of the environment variable TMPDIR, or
270 @file{/tmp} if the environment variable is not set.
274 Print status lines for each directory configured. Normally, only the
275 status lines for the initial working directory are printed.
278 Use @sc{MIT} style @sc{X11} header files and libraries on the host, even
279 if they are not normally available.
282 @node Using Configure, Porting, Invoking, top
283 @chapter Using Configure
285 The choices and options available at configuration time
286 generally have valid defaults, but the defaults do not cover all cases.
287 The choices available include install locations, build directories,
288 host, target, and local conventions.
291 * Install Locations:: Where to install things once they are built
292 * Build Directories:: Where to build object files
293 * Host:: Telling @code{configure} what will source will
295 * Target:: Telling @code{configure} what the source will
297 * Local Conventions:: Adding information about local conventions
300 @node Install Locations, Build Directories, Using Configure, Using Configure
301 @section Install Locations
302 @cindex Where to install
304 Using the default configuration, @code{make install} creates a
305 single tree of files, some of which are programs. The location of this
306 tree is determined by the value of the variable @code{prefix}. The
307 default value of @code{prefix} is @file{/usr/local}. This is
308 often correct for native tools installed on only one host.
311 * prefix:: Changing the default install directory
312 * exec_prefix:: How to separate host independent files
313 from host dependent files when
314 installing for multiple hosts
315 * Install Details:: Full descriptions of all installation
319 @node prefix, exec_prefix, Install Locations, Install Locations
320 @subsection Changing the default install directory
321 @cindex Changing the default install directory
322 @cindex Prefix directory
324 In the default configuration, all files are installed in subdirectories
325 of @file{/usr/local}. The location is determined by the value of
326 the @code{configure} variable @code{prefix}; in turn, this determines the
327 value of the Makefile variable of the same name (@code{prefix}).
329 You can also set the value of the Makefile variable @code{prefix}
330 explicitly each time you invoke @code{make} if you are so inclined; but
331 because many programs have this location compiled in, you must specify
332 the @code{prefix} value consistently on each invocation of @code{make},
333 or you will end up with a broken installation.
335 To make this easier, the value of the @code{configure} variable
336 @code{prefix} can be set on the command line to @code{configure}
337 using the option @code{-prefix=}.
340 @node exec_prefix, Install Details, prefix, Install Locations
341 @subsection Installing for multiple hosts
342 @cindex Configuring for multiple hosts
343 @cindex Sharing host independent files
344 @cindex The @file{exec_prefix} directory
345 @cindex Installing host independent files
347 By default, host dependent files are installed in subdirectories of
348 @file{@var{exec_prefix}}. The location is determined by the value of the
349 @code{configure} variable @code{exec_prefix}, which determines the value of
350 the Makefile variable @code{exec_prefix}. This makes it simpler to install
351 for a single host, and simplifies changing the default location for the
352 install tree; but the default doesn't allow for multiple hosts to
353 effectively share host independent files.
355 To configure so that multiple hosts can share common files, use
359 configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
360 make all info install install-info clean
362 configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
363 make all info install install-info
366 The first line configures the source for @var{host1} to place host
367 specific programs in subdirectories of @file{/usr/gnu/H-@var{host1}}.
369 The second line builds and installs all programs for @var{host1},
370 including both host independent and host specific files.
372 The third line reconfigures the source for @var{host2} to place host
373 specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}}.
375 The fourth line builds and installs all programs for @var{host2}. Host
376 specific files are installed in new directories, but the host
377 independent files are installed @emph{on top of} the host
378 independent files installed for @var{host1}. This results in a single
379 copy of the host independent files, suitable for use by both hosts.
381 @node Install Details, , exec_prefix, Install Locations
382 @subsection Full descriptions of all installation subdirectories
384 During any install, a number of standard directories are created. Their
385 names are determined by Makefile variables. Some of the
386 defaults for Makefile variables can be changed at configure time using
387 command line options to @code{configure}. For more information on the
388 standard directories or the Makefile variables, please refer to
389 @cite{standards.text}.
391 Note that @code{configure} does not create the directory @code{srcdir}
392 at any time. @code{srcdir} is not an installation directory.
394 You can override all makefile variables on the command line to
395 @code{make}. (See @ref{Overriding, Overriding Variables, Overriding
396 Variables, make, Make}.) If you do so, you will need to specify the
397 value precisely the same way for each invocation of @code{make}, or you
398 risk ending up with a broken installation. This is because many
399 programs have the locations of other programs or files compiled into
400 them. If you find yourself overriding any of the variables frequently,
401 you should consider site dependent Makefile fragments. See also
404 During @code{make install}, a number of standard directories are
405 created and populated. The following Makefile variables define them.
406 Those whose defaults are set by corresponding @code{configure} variables
407 are marked ``Makefile and configure''.
410 @defvr {Makefile and configure} prefix
411 The root of the installation tree. You can set
412 its Makefile default with the @code{-prefix=} command line option to
413 @code{configure}. (@ref{Invoking}.) The default value for
414 @code{prefix} is @file{/usr/local}.
418 @defvr Makefile bindir
419 A directory for binary programs that users can run.
420 The default value for @code{bindir} depends on @code{prefix};
421 @code{bindir} is normally changed only indirectly through @code{prefix}.
422 The default value for @code{bindir} is @file{$(prefix)/bin}.
426 @defvr {Makefile and configure} exec_prefix
427 A directory for host dependent files. You can specify the Makefile
428 default value by using the @code{-exec_prefix=} option to @code{configure}.
429 (See also @ref{Invoking}.) The default value for @code{exec_prefix} is
434 @defvr Makefile libdir
435 A directory for libraries and support programs. The default value for
436 @code{libdir} depends on @code{prefix}; @code{libdir} is normally
437 changed only indirectly through @code{prefix}. The default value for
438 @code{libdir} is @file{$(prefix)/lib}.
442 @defvr Makefile mandir
443 A directory for @code{man} format documentation (``man pages''). The
444 default value for @code{mandir} depends on @code{prefix};
445 @code{mandir} is normally changed only indirectly through @code{prefix}.
446 The default value for @code{mandir} is @file{$(prefix)/man}.
449 @vindex man@var{N}dir
450 @defvr Makefile man@var{N}dir
451 There are eight variables named @code{man1dir}, @code{man2dir}, etc.
452 They name the specific directories for each man page section. For
453 example, @code{man1dir} holds @file{emacs.1} (the man page for the emacs
454 program), while @code{man5dir} holds @file{rcsfile.5} (the man page
455 describing the @code{rcs} data file format). The default value for any
456 of the @code{man@var{N}dir} variables depends indirectly on
457 @code{prefix}, and is normally changed only through @code{prefix}. The
458 default value for @code{man@var{N}dir} is
459 @file{$(mandir)/man@var{N}}.
463 @defvr Makefile manext
464 @emph{Not supported by @code{configure}}. The @sc{gnu} coding standards
465 do not call for @code{man1ext}, @code{man2ext}, so the intended use for
466 @code{manext} is apparently not parallel to @code{mandir}. Its use is
467 not clear. (See also @ref{Makefile Extensions}.)
471 @defvr Makefile infodir
472 A directory for @emph{info} format documentation. The default value for
473 @code{infodir} depends indirectly on @code{prefix}; @code{infodir} is
474 normally changed only through @code{prefix}. The default value for
475 @code{infodir} is @file{$(prefix)/info}.
479 @defvr Makefile docdir
480 A directory for any documentation that is in a format other than those
481 used by @code{info} or @code{man}. The default value for @code{docdir}
482 depends indirectly on @code{prefix}; @code{docdir} is normally changed only
483 through @code{prefix}. The default value for @code{docdir}
484 is @file{$(datadir)/doc}. @emph{This variable is an extension to
485 the @sc{gnu} coding standards}. (See also @ref{Makefile Extensions}.)
489 @defvr Makefile includedir
490 A directory for the header files accompanying the libraries installed in
491 @code{libdir}. The default value for @code{includedir} depends on
492 @code{prefix}; @code{includedir} is normally changed only indirectly
493 through @code{prefix}. The default value for @code{includedir} is
494 @file{$(prefix)/include}.
497 @node Build Directories, Host, Install Locations, Using Configure
498 @section Build Directories
499 @cindex Build directories
501 @cindex Object directories
503 @cindex Building for multiple hosts
504 @cindex Building for multiple targets
506 Normally, @code{configure} builds a @file{Makefile} and symbolic links
507 in the same directory as the source files. This is the typical
508 @sc{un*x} way to build programs, but it has limitations. For instance,
509 using this approach, you can only build for one host at a time.
511 We refer to the directories where @code{configure} builds a
512 Makefile as the @emph{build directories} or sometimes as
513 @emph{objdir} because these are the directories in which @code{make}
514 will build object files, among other things.
516 The default build directory is the same as the source directory.
517 You can use a different build directory with a sequence like the following:
522 configure @var{host} -srcdir=@var{sourcedirectory}
526 where @var{builddir} is the directory where you wish to build,
527 @var{host} is the host for which you want to build, and
528 @var{sourcedirectory} is the directory containing the source files.
530 If you were to do this twice with different values for @var{builddir}
531 and @var{host}, then you could @code{make} for both at the same time.
533 @node Host, Target, Build Directories, Using Configure
536 The arguments to @code{configure} are @emph{hosts}. By @emph{host} we
537 mean the environment in which the source will be compiled. This need
538 not necessarily be the same as the physical machine involved,
539 although it usually is.
541 For example, if some obscure machine running an operating system other
542 than @sc{un*x} had the @sc{gnu} @sc{posix} emulation libraries
543 available, it would be possible to configure most @sc{gnu} source for a
544 @sc{posix} system and build it on the obscure host.
546 For more on this topic, see @ref{Host Environments, , Host Environments,
547 cfg-paper, On Configuring Development Tools}.
549 @node Target, Local Conventions, Host, Using Configure
552 For building native development tools, or most of the other @sc{gnu}
553 tools, you need not worry about the target. The @emph{target} of a
554 configuration defaults to the same as the @emph{host}.
556 For building cross development tools, please see @ref{Building
557 Development Environments, , Building Development Environments,
558 cfg-paper, On Configuring Development Tools}.
560 @node Local Conventions, , Target, Using Configure
561 @section Local Conventions
563 If you find that a tool does not get configured to your liking, or if
564 @code{configure}'s conventions differ from your local conventions, you
565 should probably consider site specific Makefile fragments. See also
568 These are probably not the right choice for options that can be set from
569 the @code{configure} command line or for differences that are host or
572 @node Porting, Reference, Using Configure, top
573 @chapter Porting with Configure
576 This section explains how to add programs, host and target configuration
577 names, and site-specific information to Cygnus configure.
580 * Programs:: Adding configure to new programs
581 * Hosts and Targets:: Adding hosts and targets
582 * Sites:: Adding site info
586 @node Programs, Hosts and Targets, Porting, Porting
587 @section Adding Configure To New Programs
589 If you are writing a new program, you probably shouldn't worry about
590 porting issues or configure until it is running reasonably on some host.
591 Then refer back to this section.
593 If the program in question currently has a configure script that meets
594 the criteria set out by @cite{standards.text}, please do not add Cygnus
595 configure. It should be possible to add this program without change to
596 a Cygnus configure style source tree.
598 If the program is not target dependent, please consider using
599 @code{autoconf} instead of Cygnus configure. @code{autoconf} will
600 be available soon from the @sc{fsf}.
602 To add Cygnus configure to an existing program, do the following:
605 @item Make sure the Makefile conforms to @sc{gnu} standard
606 The coding standard for @sc{gnu} Makefiles is described in
607 @cite{standards.text}.
609 @item Add Cygnus extensions to the Makefile
610 These are described in @ref{Makefile Extensions}.
612 @item Move host support from Makefile to fragments
613 This usually involves finding sections of the Makefile that say things
614 like ``uncomment these lines for host foo'' and moving them to a new
615 file called @file{./config/mh-foo}. For more information, see @ref{Hosts
618 @item Choose defaults
619 If the program has compile time options that determine the way the
620 program should behave, chose reasonable defaults and make these Makefile
621 variables. Be sure the variables are assigned their default values
622 before the @code{####} line so that site specific Makefile fragments can
623 override them (@pxref{Makefile Extensions,,Extensions to the @sc{gnu}
626 @item Locate configuration files
627 If there is configuration information in header files or source files,
628 separate it in such a way that the files have a generic name. Then move
629 the specific instances of those files into the @file{./config}
632 @item Separate host and target information
633 Some programs already have this information separated. If yours does
634 not, you will need to separate these two kinds of configuration
635 information. @dfn{Host specific} information is the information needed to
636 compile the program. @dfn{Target specific} information is information on the
637 format of data files that the program will read or write. This
638 information should live in separate files in the @file{./config}
639 directory with names that reflect the configuration for which they are
642 At this point you might skip this step and simply move on. If you do,
643 you should end up with a program that can be configured only to build
644 native tools, that is, tools for which the host system is also the
645 target system. Later, you could attempt to build a cross tool and
646 separate out the target specific information by figuring out what went
647 wrong. This is often simpler than combing through all of the source
650 @item Write @code{configure.in}
651 Usually this involves writing shell script fragments to map from
652 canonical configuration names into the names of the configuration files.
653 These files will then be linked at configure time from the specific
654 instances of those files in @file{./config} to file in the build
655 directory with more generic names. (see also @ref{Build Directories}).
656 The format of configure.in is described in @ref{configure.in}.
658 @item Rename @file{Makefile} to @file{Makefile.in}
661 At this point you should have a program that can be configured using
662 Cygnus @code{configure}.
664 @node Hosts and Targets, Sites, Programs, Porting
665 @section Adding hosts and targets
667 To add a host or target to a program that already uses Cygnus
668 configure, do the following.
673 Make sure the new configuration name is represented in
674 @file{config.sub}. If not, add it. For more details, see the comments
675 in the shell script @file{config.sub}.
678 If you are adding a host configuration, look in @file{configure.in}, in
679 the per-host section. Make sure that your configuration name is
680 represented in the mapping from host configuration names to
681 configuration files. If not, add it. Also see @ref{configure.in}.
684 If you are adding a target configuration, look in @file{configure.in},
685 in the per-target section. Make sure that your configuration name is
686 represented in the mapping from target configuration names to
687 configuration files. If not, add it. Also see @ref{configure.in}.
690 Look in @file{configure.in} for the variables @samp{files},
691 @samp{links}, @samp{host_makefile_frag}, and
692 @samp{target_makefile_frag}. The values assigned to these variables are
693 the names of the configuration files, relative to @code{srcdir} that the
694 program uses. Make sure that copies of the files exist for your host.
695 If not, create them. See also @ref{Configure Variables}.
698 This should be enough to configure for a new host or target
699 configuration name. Getting the program to compile and run properly
700 remains the hard work of the port.
702 @node Sites, , Hosts and Targets, Porting
703 @section Adding site info
705 If some of the Makefile defaults are not right for your site, you can
706 build site specific Makefile fragments. To do this, do the following.
711 Choose a name for your site. It must be less than eleven characters for
715 If the program source does not have a @file{./config} directory, create it.
718 Create a file called @file{./config/ms-@var{site}} where @var{site} is
719 the name of your site. In it, set whatever Makefile variables you need
720 to override to match your site's conventions.
723 Configure the program with:
726 configure @dots{} +site=@var{site}
731 @node Reference, Known Bugs, Porting, top
732 @chapter Gory details described
735 Here we describe the backend support.
738 * Makefile Extensions:: Extensions to the @sc{gnu} coding standards
739 * configure.in:: The format of the configure.in file
740 * config.status:: config.status
741 * Makefile Fragments:: Makefile Fragments
744 @node Makefile Extensions, configure.in, Reference, Reference
745 @section Extensions to the @sc{gnu} coding standards
747 @cindex Makefile extensions
748 @cindex Cygnus extensions
750 The following additions to the @sc{gnu} coding standards are required
751 for Cygnus configure to work properly.
755 The Makefile must contain exactly one line starting with @code{####}.
756 This line should follow any default macro definitions but precede any
757 rules. Host, target, and site specific Makefile fragments will be
758 inserted immediately after this line. If the line is missing, the
759 fragments will not be inserted.
762 Cygnus adds the following targets to our Makefiles. Their existence is
763 not required for Cygnus configure, but they are documented here for
769 Build all info files from texinfo source.
773 Install all info files.
777 Remove all info files and any intermediate files that can be generated
802 These targets are in transition and may be removed shortly.
805 In addition, the following Makefile targets have revised semantics:
810 Should @emph{not} depend on the target @code{all}. If the program is
811 not already built, @code{make install} should fail. This allows you
812 to install programs even when @code{make} would otherwise determine
813 them to be out of date. This can happen when the result of a @code{make
814 all} is transported via tape to another machine for installation as
815 well as in a number of other cases.
819 Should remove any file that can be regenerated by the Makefile,
820 excepting only the Makefile itself, and any links created by configure.
821 That is, @code{make all clean} should return all directories to their
822 original condition. If this is not done, then:
825 configure @var{host1} ; make all clean ; configure @var{host2} ; make all
829 will fail because of intermediate files intended for @var{host1}.
832 Cygnus adds the following macros to all @file{Makefile.in} files, but
833 you are not required to use them to run Cygnus configure.
838 The directory in which to install any documentation that is not either a
839 man page or an info file. For man pages, see mandir, for info, see
844 The directory in which to install any headers files that should be made
845 available to users. This is distinct from the @code{gcc} include
846 directory which is intended for @code{gcc} only. Files in
847 @code{includedir} may be used by @code{cc} as well.
850 In addition, the following macros have revised semantics. Most of them
851 describe installation directories; see also @ref{Install Details,,Full
852 description of all installation subdirectories}.
858 is not used. The intended usage is not clear. For example, if you have a
859 @file{foo.man} and a @file{bar.man}, and @file{foo.man} is destined for
860 @file{/usr/local/lib/man/man1/foo.1} while @file{bar.man} is destined
861 for @file{/usr/local/lib/man/man5/bar.5}, then what is the desired value
866 is used for host independent data files.
870 The default path for @code{mandir} depends on @code{prefix}.
874 The default path for @code{infodir} depends on @code{prefix}.
878 is assumed to have a @code{yacc} calling convention. To use
879 @code{bison}, use @code{BISON=bison -y}.
882 Cygnus Makefiles also conform to one additional restriction:
886 When libraries are installed, the line containing the call to
887 @code{INSTALL_DATA} should always be followed by a line containing a
888 call to @code{RANLIB} on the installed library. This is to accomodate
889 systems that use @code{ranlib}. Systems that do not use @code{ranlib}
890 can set @code{RANLIB} to @code{echo} in a host specific Makefile
894 @node configure.in, config.status, Makefile Extensions, Reference
895 @section The format of the @file{configure.in} file
898 A @file{configure.in} file for Cygnus configure consists of a
899 @dfn{per-invocation} section, followed by a @dfn{per-host} section,
900 followed by a @dfn{per-target} section, optionally followed by a
901 @dfn{post-target} section. Each section is a shell script fragment,
902 which is sourced by the configure shell script at an appropriate time.
903 Values are passed among configure and the shell fragments through a
904 set of shell variables. When each section is being interpreted
905 (sourced) by the shell, the shell's current directory is the build
906 directory, and any files created by the section (or referred to by the
907 section) will be relative to the build directory. To reference files
908 in other places (such as the source directory), prepend a shell
909 variable such as @code{srcdir} to the desired file name.
911 @cindex Per-invocation section
912 The beginning of the @file{configure.in} file begins the per-invocation
915 @cindex Per-host section
916 A line beginning with @code{# Per-host:} begins the per-host section.
918 @cindex Per-target section
919 A line beginning with @code{# Per-target:} begins the per-target
922 @cindex Post-target section
923 If it exists, the post-target section begins with @code{# Per-target:}.
926 * Minimal:: A minimal configure.in
927 * Configure Variables:: Variables available to configure.in
928 * Declarations:: For each invocation
929 * Per-host:: For each host
930 * Per-target:: For each target
931 * Post-target:: After each target
932 * Example:: An example configure.in
935 @node Minimal, Configure Variables, configure.in, configure.in
936 @subsection A minimal @file{configure.in}
938 @cindex Minimal @file{configure.in} example
939 A minimal @file{configure.in} consists of four lines.
943 srcname="source for the foo program"
948 The @samp{Per-host} and @samp{Per-target} lines divide the file into the
949 three required sections. The @samp{srctrigger} line names a file.
950 @code{configure} checks to see that this file exists in the source
951 directory before configuring. If the @samp{srctrigger} file does not
952 exist, @code{configure} uses the value of @samp{srcname} to print an
953 error message about not finding the source.
955 This particular example uses no links, and only the default host,
956 target, and site specific Makefile fragments if they exist.
958 @node Configure Variables, Declarations, Minimal, configure.in
959 @subsection Variables available to configure.in
961 @cindex @file{configure.in} interface
963 The following variables pass information between the standard parts of
964 @code{configure} and the shell-script fragments in @file{configure.in}:
967 Contains the name of a source file that is expected to live in the
968 source directory. You must usually set this in the per-invocation
969 section of @file{configure.in}. Configure tests to see that this file
970 exists. If the file does not exist, configure prints an error message.
971 This is used as a sanity check that configure.in matches the source
976 Contains the name of the source collection contained in the source
977 directory. You must usually set this in the per-invocation section of
978 @file{configure.in}. If the file named in @code{srctrigger} does not
979 exist, configure uses the value of this variable when it prints the
984 Contains the names of any subdirectories where @code{configure} should
985 recur. You must usually set this in the per-invocation section of
987 If @file{Makefile.in} contains a line starting with @code{SUBDIRS =},
988 then it will be replaced with an assignment to @code{SUBDIRS} using
989 the value of @code{configdirs} (if #code{subdirs} is empty). This can
990 be used to determine which directories to configure and build depending
991 on the host and target configurations.
992 @c Most other matching makefile/config vars use the same name. Why not
994 @c Can we get rid of SUBDIRS-substitution? It doesn't work well with subdirs.
995 Use @code{configdirs} (instead of the @code{subdirs} variable
996 described below) if you want to be able to partition the
997 sub-directories, or use independent Makefile fragments.
998 Each sub-directory can be independent, and independently re-configured.
1002 Contains the names of any subdirectories where @code{configure} should
1003 create a @code{Makefile} (in addition to the current directory),
1004 @emph{without} recursively running @code{configure}.
1005 Use @code{subdirs} (instead of the @code{configdirs} variable
1006 described above) if you want to configure all of the directories
1007 as a unit. Since there is a single invocation of @code{configure}
1008 that configures many directories, all the directories can use the
1009 same Makefile fragments, and the same @code{configure.in}.
1013 Contains the name that the user entered for the host. Since many things
1014 that the user could enter would map to the same output from
1015 @code{config.sub}, this variable is innappropriate to use for picking
1016 available configurations. For that, use @code{host_cpu},
1017 @code{host_vendor}, and/or @code{host_os}. This variable is useful,
1018 however, for error messages.
1022 Contains the first element of the canonical triple representing the host
1023 as returned by @file{config.sub}. This is occasionally used to
1024 distinguish between minor variations of a particular vendor's operating
1025 system and sometimes to determine variations in binary format between
1026 the host and the target.
1029 @defvar{host_vendor}
1030 Contains the second element of the canonical triple representing the
1031 host as returned by @file{config.sub}. This is usually used to
1032 distinguish betwen the numerous variations between @emph{common}
1034 @c "@emph{common} OS" doesn't convey much to me. Is this meant to cover
1035 @c cases like Unix, widespread but with many variations?
1039 Contains the the third element of the canonical triple representing the
1040 host as returned by @file{config.sub}.
1044 Contains the name that the user entered for the target. Since
1045 many things that the user could enter would map to the same canonical
1046 triple, this variable is innappropriate to use for picking available
1047 configurations. For that, use @code{target_cpu}, @code{target_vendor},
1048 and/or @code{target_os}. This variable is useful, however, for error
1053 Contains the first element of the canonical triple representing the
1054 target as returned by @file{config.sub}. This is used heavily by
1055 programs involved in building programs, like the compiler, assembler,
1056 linker, etc. Most programs will not need the @code{target} variables at
1057 all, but this one could conceivably be used to build a program, for
1058 instance, that operated on binary data files whose byte order or
1059 alignment differ from the system where the program is running.
1062 @defvar{target_vendor}
1063 Contains the second element of the canonical triple representing the
1064 target as returned by @file{config.sub}. This is usually used to
1065 distinguish betwen the numerous variations between @emph{common}
1066 operating systems or object file formats. Sometimes it is used to
1067 switch between different flavors of user interfaces.
1068 @c above query re "@emph{common} OS" applies here too
1072 Contains the the third element of the canonical triple representing the
1073 target as returned by @file{config.sub}. This variable is used by
1074 development tools to distinguish between subtle variations in object
1075 file formats that some vendors use across operating system releases. It
1076 might also be use to decide which libraries to build or what user
1077 interface the tool should provide.
1081 Is set to @code{true} if the user invoked configure with the @code{-nfp}
1082 command line option, otherwise it is empty. This is a request to target
1083 machines with @emph{no floating point} unit, even if the targets
1084 ordinarily have floating point units available. This option has no
1089 Is set to @code{true} if the user invoked configure with the @code{-gas}
1090 command line option, otherwise it is empty. This is a request to assume
1091 that all target machines have @sc{gas} available even if they ordinarily do
1092 not. The converse option @samp{-no-gas} is not available.
1096 Is set to @code{true} if the user invoked configure with the @code{-x}
1097 command line option, otherwise it is empty. This is a request to assume
1098 that @sc{mit x11} compatible headers files and libraries are available
1099 on all hosts, regardless of what is normally available on them.
1103 Is set to the name of the directory containing the source for this
1104 program. This will be different from @file{.} if the user has specified
1105 the @code{-srcdir=} option. Note that @code{srcdir} is not necessarily
1109 @defvar{host_makefile_frag}
1110 If set by @file{configure.in}, this variable should be the name a file,
1111 relative to @code{srcdir} to be included in the resulting Makefile. If
1112 the named file does not exist, @code{configure} will print a warning
1113 message. This variable is not set by @code{configure}.
1116 @defvar{target_makefile_frag}
1117 If set by @file{configure.in}, this variable should be the name of a
1118 file, relative to @code{srcdir}, to be included in the resulting
1119 Makefile. If the named file does not exist, @code{configure} will print
1120 a warning message. This variable is not set by @code{configure}.
1123 @defvar{site_makefile_frag}
1124 Is set to a file name representing to the default Makefile fragment for
1125 this host. It may be set in @file{configure.in} to override this
1126 default. Normally @code{site_makefile_frag} is empty, but will have a
1127 value if the user specified @code{-site=} on the command line. It is
1128 probably not a good idea to override this variable from
1129 @file{configure.in}, since that may defeat the @code{configure} user's
1134 Is set to the name of the generated @file{Makefile}. Normally this
1135 value is precisely @file{Makefile} but some programs may want something
1140 Is normally empty but will be set to some non-empty value if the user
1141 specified @code{-rm} on the command line. That is, if @code{removing}
1142 is non-empty, then configure is @emph{removing} a configuration rather
1147 If this variable is non-empty following the @code{per-target:} section,
1148 then each word in its value will be the target of a symbolic link named
1149 in the corresponding word from the @code{links} variable.
1153 If the @code{files} variable is non-empty following the
1154 @code{per-target:} section, then @code{configure} creates symbolic links
1155 with the first word of @code{links} pointing to the first word of
1156 @code{files}, the second word of @code{links} pointing to the second
1157 word of @code{files}, and so on.
1160 @node Declarations, Per-host, Configure Variables, configure.in
1161 @subsection For each invocation
1163 @cindex Declarations section
1165 @code{configure} sources the entire shell script fragment from the start
1166 of @file{configure.in} up to a line beginning with @samp{# Per-host:}
1167 immediately after parsing command line arguments. The variables
1168 @code{srctrigger} and @code{srcname} @emph{must} be set here.
1170 You might also want to set the variable @code{configdirs} here.
1172 @node Per-host, Per-target, Declarations, configure.in
1173 @subsection For each host
1174 @cindex per-host section
1175 @cindex host shell-script fragment
1177 The per-host section of @file{configure.in} starts with the line that begins
1178 with @samp{# Per-host:} and ends before a line beginning with
1179 @samp{# Per-target:}. @code{configure} sources the per-host section once for
1182 This section usually contains a big case statement using the variables
1183 @samp{host_cpu}, @samp{host_vendor}, and @samp{host_os} to determine
1184 appropriate values for @samp{host_makefile_frag} and @samp{files},
1185 although @samp{files} is not usually set here. Usually, it is set
1186 at the end of the per-target section after determining the names of the
1187 target specific configuration files.
1189 @node Per-target, Post-target, Per-host, configure.in
1190 @subsection For each target
1191 @cindex per-target section
1192 @cindex target shell-script fragment
1194 The per-target section of @file{configure.in} starts with the line that
1195 begins with @samp{# Per-target:} and ends before the line that begins
1196 with @samp{# Post-target:}, if there is such a line. Otherwise the
1197 per-target section extends to the end of the file. @code{configure} sources
1198 the per-target section once for each target before building any files,
1199 directories, or links.
1201 This section usually contains a big case statement using the variables called
1202 @samp{target_cpu}, @samp{target_vendor}, and @samp{target_os} to determine
1203 appropriate values for @samp{target_makefile_frag} and @samp{files}.
1204 The last lines in the per-target section normally set the variables
1205 @code{files} and @code{links}.
1207 @node Post-target, Example, Per-target, configure.in
1208 @subsection After each target
1210 The post-target section is optional. If it exists, the post-target
1211 section starts with a line beginning with @code{# Post-target:} and
1212 extends to the end of the file. If it exists, @code{configure} sources this
1213 section once for each target after building all files, directories, or
1216 This section is seldom needed, but you can use it to edit the Makefile
1217 generated by @code{configure}.
1219 @node Example, , Post-target, configure.in
1220 @subsection An example @file{configure.in}
1221 @cindex example @file{configure.in}
1222 @cindex sample @file{configure.in}
1223 @cindex Bison @file{configure.in}
1225 Here is a small example of a @file{configure.in} file.
1228 # This file is a collection of shell script fragments used to tailor
1229 # a template configure script as appropriate for this directory.
1230 # For more information, see configure.texi.
1233 srctrigger=warshall.c
1237 case "$@{host_os@}" in
1239 host_makefile_frag=config/mh-delta88
1245 files="bison_in.hairy"
1251 @node config.status, Makefile Fragments, configure.in, Reference
1252 @section @code{config.status}
1254 @kindex config.status
1256 The final step in configuring a directory is to create an executable
1257 shell script, @file{config.status}. The main purpose of this file
1258 is to allow the Makefile for the current directory to rebuild itself, if
1259 necessary. For this reason, @file{config.status} uses the
1260 @samp{-norecursion} option to @code{configure}, and is therefore
1261 probably inappropriate for reconfiguring a tree of source code.
1263 @node Makefile Fragments, , config.status, Reference
1264 @section Makefile Fragments
1266 @cindex Makefile fragments
1268 Cygnus @code{configure} uses three types of Makefile fragments. In a
1269 generated Makefile they appear in the order target fragment, host
1270 fragment, and site fragment. This allows host fragments to override
1271 target fragments, and site fragments to override both.
1273 Host specific Makefile fragments conventionally reside in the
1274 @file{./config} directory with names of the form
1275 @file{mh-@var{host}}. They are used for hosts that require
1276 odd options to the standard compiler and for compile time options based
1277 on the host configuration.
1279 Target specific Makefile fragments conventionally reside in the
1280 @file{./config} directory with names of the form @file{mt-@var{target}}.
1281 They are used for target dependent compile time options.
1283 Site specific Makefile fragments conventionally reside in the
1284 @file{./config} directory with names of the form @file{ms-@var{site}}.
1285 They are used to override host and target independent compile time
1286 options. Note that you can also override these options on the
1287 @code{make} invocation line.
1289 @node Known Bugs, Variables Index, Reference, top
1294 We know of the following bugs:
1299 There is no way to query about known hosts, known targets, or the
1300 porting or testing status of any configuration.
1303 The negations to the options @code{-gas}, @code{-x}, and @code{-nfp} are
1309 @node Variables Index, Concept Index, Known Bugs, top
1310 @appendix Variable Index
1315 @node Concept Index, , Variables Index, top
1316 @appendix Concept Index
1324 @c outline-regexp: "@chap"
1326 @c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")