![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to configure.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / libg++ / etc|
Return to configure.texi CVS log | Up to [Apple XNU] / GNUtools / libg++ / etc |
1.1 root 1: \input texinfo @c -*-texinfo-*-
2: @setfilename configure.info
3: @settitle Cygnus configure
4:
5: @synindex ky cp
6:
7: @setchapternewpage odd
8:
9: @ifinfo
10: @format
11: START-INFO-DIR-ENTRY
12: * configure:: Cygnus configure.
13: END-INFO-DIR-ENTRY
14: @end format
15: @end ifinfo
16:
17: @ifinfo
18: This document describes the Cygnus Support version of @code{configure}.
19:
20: Copyright (C) 1991, 1992, 1993 Cygnus Support
21: Permission is granted to make and distribute verbatim copies of
22: this manual provided the copyright notice and this permission notice
23: are preserved on all copies.
24:
25: @ignore
26: Permission is granted to process this file through TeX and print the
27: results, provided the printed document carries copying permission
28: notice identical to this one except for the removal of this paragraph
29: (this paragraph not being relevant to the printed manual).
30: @end ignore
31:
32: Permission is granted to copy and distribute modified versions of this
33: manual under the conditions for verbatim copying, provided that the entire
34: resulting derived work is distributed under the terms of a permission
35: notice identical to this one.
36:
37: Permission is granted to copy and distribute translations of this manual
38: into another language, under the above conditions for modified versions,
39: except that this permission notice may be stated in a translation approved
40: by Cygnus Support.
41: @end ifinfo
42:
43: @smallbook
44: @finalout
45: @titlepage
46: @title Cygnus configure
47: @author K. Richard Pixley
48: @author Cygnus Support
49: @page
50: @cindex copyleft
51:
52: @vskip 0pt plus 1filll
53: Edited January, 1993, by Jeffrey Osier, Cygnus Support.
54:
55: Copyright @copyright{} 1991, 1992, 1993 Cygnus Support
56:
57: Permission is granted to make and distribute verbatim copies of
58: this manual provided the copyright notice and this permission notice
59: are preserved on all copies.
60:
61: Permission is granted to copy and distribute modified versions of this
62: manual under the conditions for verbatim copying, provided that the entire
63: resulting derived work is distributed under the terms of a permission
64: notice identical to this one.
65:
66: Permission is granted to copy and distribute translations of this manual
67: into another language, under the above conditions for modified versions,
68: except that this permission notice may be stated in a translation approved
69: by Cygnus Support.
70: @end titlepage
71:
72: @c ---------------------------------------------------------------------
73: @ifinfo
74: @node Top
75: @top Cygnus configure
76:
77: This file documents the configuration system used and distributed by
78: Cygnus Support.
79:
80: @menu
81: * What configure does:: What configure does
82: * Invoking configure:: Invoking configure---basic usage
83: * Using configure:: More than you ever wanted to know
84: * Porting:: How to use configure with new programs
85: * Variables Index::
86: * Concept Index::
87: @end menu
88: @end ifinfo
89:
90: @c ---------------------------------------------------------------------
91: @node What configure does
92: @chapter What @code{configure} does
93: @cindex Introduction
94: @cindex Overview
95: @cindex What @code{configure} does
96: @kindex Cygnus Support Developer's Kit
97:
98: This manual documents Cygnus @code{configure}, a program which helps to
99: automate much of the setup activity associated with building large suites of
100: programs, such the Cygnus Support Developer's Kit. This manual is therefore
101: geared toward readers who are likely to face the problem of configuring
102: software in source form before compiling and installing it. We assume you are
103: an experienced programmer or system administrator.
104: @ifinfo
105: For further background on this topic, see @ref{Some Basic Terms, , Apologia
106: Configure, cfg-paper, On Configuring Development Tools}, by K. Richard
107: Pixley.
108: @end ifinfo
109: @iftex
110: For further background on this topic, see @cite{On Configuring Development
111: Tools} by K. Richard Pixley.
112: @end iftex
113:
114: When @code{configure} runs, it does the following things:
115:
116: @table @emph
117: @item @bullet{} creates build directories
118: @vindex srcdir
119: @cindex @code{srcdir}
120: @cindex Build directories
121: When you run @code{configure} with the @samp{--srcdir} option, it uses the
122: current directory as the @dfn{build directory}, creating under it a directory
123: tree that parallels the directory structure of the source directory. If you
124: don't specify a @samp{srcdir}, @code{configure} first assumes that the source
125: code you wish to configure is in your current directory; if it finds no
126: @file{configure.in} input file there, it searches in the directory
127: @code{configure} itself lies in. (For details, see @ref{Build directories, ,
128: Build directories}.)
129:
130: @item @bullet{} generates @file{Makefile}
131: @cindex @code{Makefile} generation
132: A @file{Makefile} template from the source directory, usually called
133: @file{Makefile.in}, is copied to an output file in the build directory which is
134: most often named @file{Makefile}. @code{configure} places definitions for a
135: number of standard @file{Makefile} macros at the beginning of the output file.
136: If @w{@samp{--prefix=@var{dir}}} or @w{@samp{--exec_prefix=@var{dir}}} are
137: specified on the @code{configure} command line, corresponding @file{Makefile}
138: variables are set accordingly. If host, target, or site-specific
139: @file{Makefile} fragments exist, these are inserted into the output file. (For
140: details, see @ref{Makefile generation, , @code{Makefile} generation}.)
141:
142: @item @bullet{} generates @file{.gdbinit}
143: @cindex @code{.gdbinit}
144: If the source directory contains a @file{.gdbinit} file and the build directory
145: is not the same as the source directory, a @file{.gdbinit} file is created in
146: the build directory. This @file{.gdbinit} file contains commands which allow
147: the source directory to be read when debugging with the @sc{gnu} debugger,
148: @code{gdb}. (@xref{Command Files, , Command Files, gdb, Debugging With GDB}.)
149:
150: @item @bullet{} makes symbolic links
151: @cindex Symbolic links
152: Most build directories require that some symbolic links with generic names are
153: built pointing to specific files in the source directory. If the system where
154: @code{configure} runs cannot support symbolic links, hard links are used
155: instead. (For details, see @ref{configure.in, , The @code{configure.in} input
156: file}.)
157:
158: @item @bullet{} generates @file{config.status}
159: @cindex @code{config.status}
160: @code{configure} creates a shell script named @file{config.status} in the build
161: directory. This shell script, when run from the build directory (usually from
162: within a @file{Makefile}), will reconfigure the build directory (but not its
163: subdirectories). This is most often used to have a @file{Makefile} update
164: itself automatically if a new source directory is available.
165:
166: @item @bullet{} calls itself recursively
167: @cindex Recursion
168: If the source directory has subdirectories that should also be configured,
169: @code{configure} is called for each.
170: @end table
171:
172: @c ---------------------------------------------------------------------
173: @node Invoking configure
174: @chapter Invoking @code{configure}
175: @cindex Invoking @code{configure}
176: @cindex Usage
177:
178: Cygnus @code{configure} is a shell script which resides in a source tree. The
179: usual way to invoke @code{configure} is from the shell, as follows:
180:
181: @cindex Example session
182: @example
183: eg$ ./configure @var{hosttype}
184: @end example
185:
186: @noindent
187: This prepares the source in the current directory (@file{.}) to be
188: compiled for a @var{hosttype} environment. It assumes that you wish to
189: build programs and files in the default @dfn{build directory} (also the
190: current directory, @file{.}). If you do not specify a value for
191: @var{hosttype}, Cygnus @code{configure} will attempt to discover this
192: information by itself (@pxref{config.guess, , Determining system
193: information}). For information on @var{hosttype} environments,
194: @xref{Host, , Host}.
195:
196: All @sc{gnu} software is packaged with one or more @code{configure} script(s)
197: (@pxref{Configuration, , How Configuration Should Work, standards, GNU Coding
198: Standards}). By using @code{configure} you prepare the source for your
199: specific environment by selecting and using @file{Makefile} fragments and
200: fragments of shell scripts, which are prepared in advance and stored with the
201: source.
202:
203: @code{configure}'s command-line options also allow you to specify other aspects
204: of the source configuration:
205:
206: @smallexample
207: configure @var{hosttype} [--target=@var{target}] [--srcdir=@var{dir}] [--rm]
208: [--site=@var{site}] [--prefix=@var{dir}] [--exec-prefix=@var{dir}]
209: [--program-prefix=@var{string}] [--tmpdir=@var{dir}]
210: [--with-@var{package}[=@var{yes/no}]] [--norecursion]
211: [--nfp] [-s] [-v] [-V | --version] [--help]
212: @end smallexample
213:
214: @table @code
215: @item --target=@var{target}
216: @cindex @code{--target}
217: @cindex @code{target} option
218: @vindex target
219: Requests that the sources be configured to target the @var{target} machine. If
220: no target is specified explicitly, the target is assumed to be the same as the
221: host (i.e., a @dfn{native} configuration). @xref{Host, , Host}, and
222: @ref{Target, , Target}, for
223: discussions of each.
224:
225: @item --srcdir=@var{dir}
226: @cindex @code{--srcdir}
227: @cindex @code{srcdir} option
228: @vindex srcdir
229: Direct each generated @file{Makefile} to use the sources located in directory
230: @var{dir}. Use this option whenever you wish the object code to reside in a
231: different place from the source code. The @dfn{build directory} is always
232: assumed to be the directory you call @code{configure} from. See @ref{Build
233: directories, , Build directories}, for an example. If the source directory is
234: not specified, @code{configure} assumes that the source is in your current
235: directory. If @code{configure} finds no @file{configure.in} there, it searches
236: in the same directory that the @code{configure} script itself lies in.
237: Pathnames specified (Values for @var{dir}) can be either absolute relative to
238: the @emph{build} directory.
239:
240: @item --rm
241: @cindex @code{--rm}
242: @cindex @code{rm} option
243: @vindex rm
244: @emph{Remove} the configuration specified by @var{hosttype} and the other
245: command-line options, rather than create it.
246:
247: @c FIXME: check @ref
248: @quotation
249: @emph{Note:} We recommend that you use @samp{make distclean} rather than
250: use this option; see @ref{Invoking make,,Invoking @code{make},make,GNU
251: Make}, for details on @samp{make distclean}.
252: @end quotation
253:
254: @item --site=@var{site}
255: @cindex @code{--site}
256: @cindex @code{site} option
257: @vindex site
258: Generate the @file{Makefile} using site-specific @file{Makefile} fragments for
259: @var{site}. @xref{Makefile fragments, , Adding information about local
260: conventions}.
261:
262: @item --prefix=@var{dir}
263: @cindex @code{--prefix}
264: @cindex @code{prefix} option
265: @vindex prefix
266: Configure the source to install programs and files under directory @var{dir}.
267:
268: This option sets the variable @samp{prefix}. Each generated @file{Makefile}
269: will have its @samp{prefix} variables set to this value. (@xref{What configure
270: really does, , What @code{configure} really does}.)
271:
272: @item --exec-prefix=@var{dir}
273: @cindex @code{--exec-prefix}
274: @cindex @code{exec-prefix} option
275: @vindex exec-prefix
276: Configure the source to install @dfn{host dependent} files in @var{dir}.
277:
278: This option sets the variable @samp{exec_prefix}. Each generated
279: @file{Makefile} will have its @samp{exec_prefix} variables set to this value.
280: (@xref{What configure really does, , What @code{configure} really does}.)
281:
282: @item --program-prefix=@var{string}
283: @cindex @code{--program-prefix}
284: @cindex @code{program-prefix} option
285: @vindex program-prefix
286: Configure the source to install certain programs using @var{string} as a
287: prefix. This applies to programs which might be used for cross-compilation,
288: such as the compiler and the binary utilities, and also to programs which have
289: the same names as common Unix programs, such as @code{make}.
290:
291: This option sets the variable @samp{program_prefix}. Each generated
292: @file{Makefile} will have its @samp{program_prefix} variables set to this
293: value. (@xref{What configure really does, , What @code{configure} really
294: does}.)
295:
296: @item --tmpdir=@var{tmpdir}
297: @cindex @code{--tmpdir}
298: @cindex @code{tmpdir} option
299: @vindex tmpdir
300: Use the directory @var{tmpdir} for @code{configure}'s temporary files. The
301: default is the value of the environment variable @w{@code{TMPDIR}}, or
302: @file{/tmp} if the environment variable is not set.
303:
304: @item --with-@var{package}[=@var{yes/no}]
305: @cindex @code{--with-@var{package}}
306: @cindex @code{with-@var{package}} option
307: @vindex with-@var{package}
308: Indicate that @var{package} is present, or not present, depending on
309: @var{yes/no}. If @var{yes/no} is nonexistent, its value is assumed to
310: be @code{yes}.
311:
312: For example, if you wish to configure the program @code{gcc} for a Sun
313: SPARCstation running SunOS 4.x, and you want @code{gcc} to use the
314: @sc{gnu} linker @code{ld}, you can configure @code{gcc} using
315:
316: @cindex Example session
317: @smallexample
318: eg$ configure --with-gnu-ld sun4
319: @end smallexample
320:
321: @noindent
322: @xref{What configure really does, , What @code{configure} really does}, for
323: details. See the installation or release notes for your particular package for
324: details on which other @var{package} options are recognized.
325: @c FIXME - need to include info about --with-* in other dox!
326:
327: @item --norecursion
328: @cindex @code{--norecursion}
329: @cindex @code{norecursion} option
330: @vindex norecursion
331: Configure only this directory; ignore any subdirectories. This is used by the
332: executable shell script @file{config.status} to reconfigure only the current
333: directory; it is most often used non-interactively, when @code{make} is
334: invoked. (@xref{config.status, , @code{config.status}}.)
335:
336: @item --nfp
337: @cindex @code{--nfp}
338: @cindex @code{nfp} option
339: @vindex nfp
340: Assume that the intended @var{hosttype} has no floating point unit.
341:
342: @item -s
343: @cindex @code{-s}
344: @cindex @code{s} option
345: Suppress status output. This option is used internally by
346: @code{configure} when calling itself recursively in subdirectories. You
347: can override this option with the @code{--verbose} option.
348:
349: @item -v
350: @itemx --verbose
351: @cindex @code{-v}
352: @cindex @code{--verbose}
353: @cindex @code{v} option
354: @cindex @code{verbose} option
355: @cindex Verbose Output
356: @vindex verbose
357: Print status lines for each directory configured. Normally, only the
358: status lines for the initial working directory are printed.
359:
360: @item --version
361: @itemx -V
362: @cindex version
363: @cindex @code{--version}
364: @cindex version
365: Print the @code{configure} version number.
366:
367: @item --help
368: @cindex Usage
369: @cindex @code{--help}
370: @cindex @code{help} option
371: Print a short summary of how to invoke @code{configure}.
372: @end table
373:
374: @cindex Abbreviating option names
375: @cindex Truncating option names
376: @cartouche
377: @emph{Note:} You may introduce options with a single dash, @samp{-}, rather
378: than two dashes, @samp{--}. However, you may not be able to truncate long
379: option names when using a single dash. When using two dashes, options may be
380: abbreviated as long as each option can be uniquely identified. For example,
381: @smallexample
382: eg$ configure --s=/u/me/src @var{hosttype}
383: @end smallexample
384: @noindent
385: is ambiguous, as @w{@samp{--s}} could refer to either @w{@samp{--site}} or
386: @w{@samp{--srcdir}}. However,
387: @smallexample
388: eg$ configure --src=/u/me/src @var{hosttype}
389: @end smallexample
390: @noindent
391: is a valid abbreviation.
392: @end cartouche
393:
394:
395: @c ========================================================================
396: @node Using configure
397: @chapter Using @code{configure}
398: @cindex Using @code{configure}
399: @cindex Detailed usage
400: @cindex Usage: detailed
401:
402: @code{configure} prepares source directories for building programs in
403: them. ``Configuring'' is the process of preparing software to compile
404: correctly on a given @dfn{host}, for a given @dfn{target}.
405:
406: @code{configure} subsequently writes a configured @file{Makefile} from a
407: pre-built template; @code{configure} uses variables that have been set in the
408: configuring process to determine the values of some variables in the
409: @file{Makefile}. Because of this we will refer to both @code{configure}
410: variables and @file{Makefile} variables. This convention allows us to
411: determine where the variable should be set initially, in either
412: @file{configure.in} or @file{Makefile.in}.
413:
414: @menu
415: * What configure really does:: What configure really does
416: * configure.in:: The configure.in input file
417: * Install locations:: Where to install things once they are built
418: * Host:: Telling configure what will source will be built
419: * Target:: Telling configure what the source will target
420: * Makefile fragments:: Adding information about local conventions
421: * Makefile extensions:: Extensions to the GNU coding standards
422: @end menu
423:
424: @c ---------------------------------------------------------------------
425: @node What configure really does
426: @section What @code{configure} really does
427: @cindex What @code{configure} really does
428: @cindex Behind the scenes
429: @cindex @code{configure} back end
430: @cindex @code{configure} details
431:
432: Cygnus @code{configure} is a shell script that sets up an environment in
433: which your programs will compile correctly for your machine and
434: operating system, and will install in proper places. @code{configure}
435: accomplishes this task by doing the following:
436:
437: @itemize @bullet
438: @item
439: it generates a @file{Makefile} from a custom template called
440: @file{Makefile.in} in each relevant source directory;
441:
442: @item
443: it customizes the build process to your specifications; you set certain
444: variables for @code{configure}, either on the command line or in the
445: file @file{configure.in}, which subsequently sets variables in each
446: generated @file{Makefile} to be used by @code{make} when actually
447: building the software;
448:
449: @item
450: it creates @dfn{build directories}, places for your code to be compiled
451: in before being installed;
452:
453: @item
454: it generates a @file{.gdbinit} in the build directory, if needed, to
455: communicate to @code{gdb} where to find the program's source code;
456:
457: @item
458: it generates a shell script called @file{config.status}
459: which is used most often by the @file{Makefile} to reconfigure itself;
460:
461: @item
462: it recurses in subdirectories, setting up entire trees so that they build
463: correctly; if @code{configure} finds another @code{configure} script
464: further down in a given source tree, it knows to use this script and not
465: recur.
466: @end itemize
467:
468: For the sake of safety (i.e., in order to prevent broken installations), the
469: @sc{gnu} coding standards call for software to be @dfn{configured} in such a
470: way that an end user trying to build a given package will be able to do so by
471: affecting a finite number of variables. All @sc{gnu} software comes with an
472: executable @code{configure} shell script which sets up an environment within a
473: build directory which will correctly compile your new package for your host
474: (or, alternatively, whatever host you specify to @code{configure}).
475: @ifinfo
476: For further background on this topic, see @ref{Some Basic Terms, , Apologia
477: Configure, cfg-paper, On Configuring Development Tools}, by K. Richard
478: Pixley.
479: @end ifinfo
480: @iftex
481: For further background on this topic, see @cite{On Configuring Development
482: Tools} by K. Richard Pixley.
483: @end iftex
484:
485: Use @code{configure} to set for the build process:
486:
487: @itemize @bullet
488: @item
489: correct values for certain variables;
490:
491: @item
492: which type of host you wish to configure a given package for
493: (@pxref{Host, , Host});
494:
495: @item
496: where you want to install this package (by using @samp{prefix},
497: @samp{exec-prefix} and @samp{program-prefix}; @pxref{Install details, ,
498: Full descriptions of all installation directories});
499:
500: @item
501: optionally, which type of machine you wish to @dfn{target} this
502: package's output to (@pxref{Target, , Target});
503:
504: @item
505: which other @sc{gnu} packages are already installed and available to
506: this particular build (by using the @samp{--with-@var{package}} option;
507: @pxref{Invoking configure, , Invoking @code{configure}});
508:
509: @item
510: where to place temporary files (by using the @samp{--tmpdir=@var{dir}}
511: option; @pxref{Invoking configure, , Invoking @code{configure}});
512:
513: @item whether to recur in subdirectories (changeable through the
514: @w{@samp{--norecursion}} option; @pxref{Invoking configure, , Invoking
515: @code{configure}}).
516: @end itemize
517:
518: @code{configure} uses a few other files to complete its tasks. These are
519: discussed in detail where noted.
520:
521: @table @code
522: @cindex Other files
523: @item configure.in
524: @cindex @code{configure.in} definition
525: Input file for @code{configure}. Shell script fragments reside here.
526: @xref{configure.in, , The @code{configure.in} input file}.
527:
528: @item Makefile.in
529: @cindex @code{Makefile.in} definition
530: Template which @code{configure} uses to build a file called @file{Makefile} in
531: the @dfn{build directory}. @xref{Makefile generation, , @code{Makefile}
532: generation}.
533:
534: @item config.sub
535: @cindex @code{config.sub} definition
536: Shell script used by @code{configure} to expand referents to the
537: @var{hosttype} argument into a single specification of the form
538: @w{@var{cpu-vendor-os}}. For instance, on the command line you can
539: specify
540:
541: @cindex Example session
542: @example
543: eg$ ./configure sun4
544: @end example
545:
546: @noindent
547: to configure for a Sun SPARCstation running SunOS 4.x. @code{configure}
548: consults @code{config.sub} to find that the three-part specification for this
549: is
550:
551: @example
552: sparc-sun-sunos4.1.1
553: @end example
554:
555: @noindent
556: which notes the @var{cpu} as @samp{sparc}, the @var{manufacturer} as @samp{sun}
557: (Sun Microsystems), and the @var{os} (operating system) as @samp{sunos4.1.1},
558: the SunOS 4.1.1 release. @xref{configure variables, , Variables available to @code{configure}}.
559:
560: @item config.guess
561: @cindex @code{config.guess} definition
562: If you do not put the @var{hosttype} argument on the command line,
563: @code{configure} uses the @code{config.guess} shell script to make an
564: analysis of your machine (it assumes that you wish to configure your
565: software for the type of machine on which you are running). The output
566: of @code{config.guess} is a three-part identifier as described above.
567:
568: @item config.status
569: @cindex @code{config.status} definition
570: The final step in configuring a directory is to create a shell script,
571: @code{config.status}. The main purpose of this file is to allow the
572: @file{Makefile} for the current directory to rebuild itself, if
573: necessary. @xref{config.status, , @code{config.status}}.
574:
575: @item config/*
576: @cindex @code{config/} subdirectory
577: @code{configure} uses three types of @file{Makefile} @dfn{fragments}, which
578: reside in the directory @file{@var{srcdir}/config/}. @xref{Makefile fragments,
579: , Adding information about local conventions}.
580: @end table
581:
582: @menu
583: * Build variables:: Variable-spaghetti made simple
584: * Build directories:: Build directories described well
585: * Makefile generation:: To build a Makefile
586: * config.guess:: Be vewwy quiet, I'm hunting system information
587: * config.status:: To rebuild a Makefile
588: @end menu
589:
590: @c ---------------------------------------------------------------------
591: @node Build variables
592: @subsection Build variables
593: @cindex Build variables
594: @cindex Cygnus Support Developer's Kit
595: @cindex Variables
596:
597: There are several variables in the build process which you can control through
598: build programs such as @code{make}. These include machine definitions, local
599: conventions, installation locations, locations for temporary files, etc. This
600: data is accessible through certain variables which are configurable in the
601: build process; we refer to them as @dfn{build variables}.
602:
603: For lists of build variables which you can affect by using @code{configure},
604: see @ref{configure variables, , Variables available to @code{configure.in}},
605: and @ref{Install details, , Full descriptions of all installation directories}.
606:
607: Generally, build variables, which are used by the @file{Makefile} to
608: determine various aspects of the build and installation processes, are
609: changeable with command-line options to @code{configure}. In most large
610: suites of programs, like the Cygnus Support Developer's Kit, the
611: individual programs reside in several subdirectories of a single source
612: code ``tree''. All of these subdirectories need to be configured with
613: information relative to the @dfn{build directory}, which is not known
614: until @code{configure} is run. Unless specified otherwise,
615: @code{configure} recursively configures every subdirectory in the source
616: tree.
617:
618: Build variables are passed from @code{configure} directly into the
619: @file{Makefile}, and use the same names (except that dashes are
620: transformed into underbars; for example, when you specify the option
621: @samp{--exec-prefix} on the command line, the @file{Makefile} variable
622: @samp{exec_prefix} is set). In other words, if you specify
623:
624: @cindex Example session
625: @example
626: eg$ ./configure --prefix=/usr/gnu/local @dots{} @var{hosttype}
627: @end example
628:
629: @noindent
630: on the command line, @code{configure} sets an variable called @samp{prefix} to
631: @samp{/usr/gnu/local}, and passes this into the @file{Makefile} in the same
632: manner. After this command, each @file{Makefile} generated by @code{configure}
633: will contain a line that reads:
634:
635: @example
636: prefix = /usr/gnu/local
637: @end example
638:
639: For a list of the @file{Makefile} variables @code{configure} can change, and
640: instructions on how to change them, see @ref{configure variables, , Variables
641: available to @code{configure.in}}, and @ref{Invoking configure, , Invoking
642: @code{configure}}.
643:
644: @c ---------------------------------------------------------------------
645: @node Build directories
646: @subsection Build directories
647: @cindex Build directories
648: @cindex Object directories
649: @cindex Building for multiple hosts
650: @cindex Building for multiple targets
651:
652: By default, @code{configure} builds a @file{Makefile} and symbolic links in the
653: same directory as the source files. This default works for many cases, but it
654: has limitations. For instance, using this approach, you can only build object
655: code for one host at a time.
656:
657: We refer to each directory where @code{configure} builds a @file{Makefile} as
658: a @dfn{build directory}.
659:
660: The build directory for any given build is always the directory from which you
661: call @code{configure}, or @file{.} relative to your prompt. The default
662: @dfn{source directory}, the place @code{configure} looks to find source code,
663: is also @file{.}. For instance, if we have a directory @file{/gnu-stuff/src/}
664: that is the top branch of a tree of @sc{gnu} source code we wish to configure,
665: then the program we will use to configure this code is
666: @file{/gnu-stuff/src/configure}, as follows. (Assume for the sake of argument
667: that our machine is a sun4.)
668:
669: @cindex Example session
670: @smallexample
671: @group
672: eg$ cd /gnu-stuff/src
673: eg$ ./configure sun4
674: Created "Makefile" in /gnu-stuff/src
675: eg$
676: @end group
677: @end smallexample
678:
679: We just configured the code in @file{/gnu-stuff/src} to run on a Sun
680: SPARCstation using SunOS 4.x by creating a @file{Makefile} in
681: @file{/gnu-stuff/src}. By default, we also specified that when this code is
682: built, the object code should reside in the same directory,
683: @file{/gnu-stuff/src}.
684:
685: However, if we wanted to build this code for more than one host, we would be in
686: trouble, because the new configuration would write over the old one, destroying
687: it in the process. What we can do is to make a new @dfn{build directory} and
688: configure from there. Running @code{configure} from the new directory will
689: place a correct @file{Makefile} and a @file{config.status} in this new file.
690: That is all @code{configure} does; we must run @code{make} to generate any
691: object code.
692:
693: The new @file{Makefile} in @file{/gnu-stuff/sun4-obj}, created from the
694: template file @file{/gnu-stuff/src/Makefile.in}, contains all the information
695: needed to build the program.
696:
697: @cindex Example session
698: @smallexample
699: @group
700: eg$ mkdir /gnu-stuff/sun4-obj
701: eg$ cd /gnu-stuff/sun4-obj
702: eg$ ../src/configure --srcdir=../src sun4
703: Created "Makefile" in /gnu-stuff/sun4-obj
704: eg$ ls
705: Makefile config.status
706: eg$ make all info install install-info clean
707: @var{compilation messages@dots{}}
708: eg$ mkdir /gnu-stuff/solaris2
709: eg$ cd /gnu-stuff/solaris2
710: eg$ ../src/configure --srcdir=../src sol2
711: Created "Makefile" in /gnu-stuff/solaris2
712: eg$ ls
713: Makefile config.status
714: eg$ make all info install install-info clean
715: @var{compilation messages@dots{}}
716: @end group
717: @end smallexample
718:
719: We can repeat this for other configurations of the same software simply
720: by making a new build directory and reconfiguring from inside it. If
721: you do not specify the @var{hosttype} argument, @code{configure}
722: will attempt to figure out what kind of machine and operating system you
723: happen to be using. @xref{config.guess, , Determining system
724: information}. Of course, this may not always be the configuration you
725: wish to build.
726:
727: @emph{Caution:} If you build more than one configuration for a single program,
728: remember that you must also specify a different @samp{--prefix} for each
729: configuration at configure-time. Otherwise, both configurations will be
730: installed in the same default location (@file{/usr/local}); the configuration
731: to be installed last would overwrite previously installed configurations.
732:
733: @c ---------------------------------------------------------------------
734: @node Makefile generation
735: @subsection @code{Makefile} generation
736: @cindex @code{Makefile} generation
737:
738: Cygnus @code{configure} creates a file called @file{Makefile} in the build
739: directory which can be used with @code{make} to automatically build a given
740: program or package. @code{configure} also builds a @file{Makefile} for each
741: relevant subdirectory for a given program or package (irrelevant subdirectories
742: would be those which contain no code which needs configuring, and which
743: therefore have no @code{configure} input file @file{configure.in} and no
744: @file{Makefile} template @file{Makefile.in}). @xref{Running, @code{make}
745: Invocation, How to Run @code{make}, make, GNU Make}, for details on using
746: @code{make} to compile your source code.
747:
748: Each @file{Makefile} contains variables which have been configured for a
749: specific build. These build variables are determined when @code{configure} is
750: run. All build variables have defaults. By default, @code{configure}
751: generates a @file{Makefile} which specifies:
752:
753: @cindex Default configuration
754: @itemize @bullet
755: @item a @dfn{native} build, which is to occur
756:
757: @item in the current directory, and which will be installed
758:
759: @item in the default installation directory (@file{/usr/local}) when the code
760: is compiled with @code{make}.
761: @end itemize
762:
763: @noindent
764: Variables are changeable through command-line options to @code{configure}
765: (@pxref{Invoking configure, , Invoking @code{configure}}).
766:
767: If you are porting a new program and intend to use @code{configure}, see
768: @ref{Porting, , Porting with @code{configure}}, as well as @ref{Makefiles, ,
769: Writing Makefiles, make, GNU Make}, and @ref{Makefiles, , Makefile Conventions,
770: standards, GNU Coding Standards}.
771:
772: @c ---------------------------------------------------------------------
773: @node config.guess
774: @subsection Determining system information
775: @cindex @code{config.guess}
776:
777: The shell script @code{config.guess} is called when you do not specify a
778: @var{hosttype} on the command line to @code{configure}. @code{config.guess}
779: acquires available system information from your local machine through the shell
780: command @code{uname}. It compares this information to a database and attempts
781: to determine a usable three-part system identifier (known as a @dfn{triple}) to
782: use as your @var{hosttype}. @xref{What configure really does, , What
783: @code{configure} really does}, to see how this information is used.
784:
785: @emph{Note:} If you do not specify a @var{hosttype} on the command line,
786: @code{configure} will attempt to configure your software to run on the machine
787: you happen to be using. This may not be the configuration you desire.
788:
789: @c ---------------------------------------------------------------------
790: @node config.status
791: @subsection @code{config.status}
792: @cindex @code{config.status}
793:
794: The final step in configuring a directory is to create an executable shell
795: script, @file{config.status}. The main purpose of this file is to allow the
796: @file{Makefile} for the current directory to rebuild itself, if necessary. It
797: is usually run from within the @file{Makefile}. @xref{Makefile extensions, ,
798: Extensions to the @sc{gnu} coding standards}.
799:
800: @file{config.status} also contains a record of the @code{configure} session
801: which created it.
802:
803: @c ---------------------------------------------------------------------
804: @node configure.in
805: @section The @code{configure.in} input file
806: @cindex @code{configure.in}
807:
808: A @file{configure.in} file for Cygnus @code{configure} consists of a
809: @dfn{per-invocation} section, followed by a @dfn{per-host} section, followed by
810: a @dfn{per-target} section, optionally followed by a @dfn{post-target} section.
811: Each section is a shell script fragment, which is executed by the
812: @code{configure} shell script at an appropriate time. Values are passed among
813: @code{configure} and the shell fragments through a set of shell variables.
814: When each section is being interpreted by the shell, the shell's current
815: directory is the build directory, and any files created by the section (or
816: referred to by the section) will be relative to the build directory. To
817: reference files in other places (such as the source directory), prepend a shell
818: variable such as @samp{$(srcdir)/} to the desired file name.
819:
820: @cindex @i{per-invocation} section
821: The beginning of the @file{configure.in} file begins the @dfn{per-invocation}
822: section.
823:
824: @cindex @i{per-host} section
825: A line beginning with @samp{# per-host:} begins the @dfn{per-host} section.
826:
827: @cindex @i{per-target} section
828: A line beginning with @samp{# per-target:} begins the @dfn{per-target} section.
829:
830: @cindex @i{post-target} section
831: If it exists, the @dfn{post-target} section begins with @samp{# post-target:}.
832:
833: @menu
834: * configure variables:: Variables available to configure.in
835: * Minimal:: A minimal configure.in
836: * Declarations:: For each invocation
837: * per-host:: Host-specific instructions
838: * per-target:: Target-specific instructions
839: * post-target:: Instructions to be executed after target info
840: * Example:: An example configure.in
841: @end menu
842:
843: @c ---------------------------------------------------------------------
844: @node configure variables
845: @subsection Variables available to @code{configure.in}
846: @cindex @file{configure.in} interface
847: @cindex configure variables
848:
849: The following variables pass information between the standard parts of
850: @code{configure} and the shell-script fragments in @file{configure.in}:
851:
852: @table @code
853: @item srctrigger
854: @cindex @code{srctrigger}
855: @vindex srctrigger
856: Contains the name of a source file that is expected to live in the source
857: directory. You must usually set this in the @dfn{per-invocation} section of
858: @file{configure.in}. @code{configure} tests to see that this file exists. If
859: the file does not exist, @code{configure} prints an error message. This is
860: used as a sanity check that @file{configure.in} matches the source directory.
861:
862: @item srcname
863: @cindex @code{srcname}
864: @vindex srcname
865: Contains the name of the source collection contained in the source directory.
866: You must usually set this in the @dfn{per-invocation} section of
867: @file{configure.in}. If the file named in @samp{srctrigger} does not exist,
868: @code{configure} uses the value of @samp{srcname} when it prints the error
869: message.
870:
871: @item configdirs
872: @cindex @code{configdirs}
873: @vindex configdirs
874: Contains the names of any subdirectories in which @code{configure} should
875: recurse. You must usually set this in the @dfn{per-invocation} section of
876: @file{configure.in}.
877: If @file{Makefile.in} contains a line starting with @samp{SUBDIRS =},
878: then it will be replaced with an assignment to @samp{SUBDIRS} using
879: the value of @samp{configdirs} (if @samp{subdirs} is empty). This can
880: be used to determine which directories to configure and build depending
881: on the host and target configurations.
882: @c Most other matching makefile/config vars use the same name. Why not
883: @c this? (FIXME).
884: @c Can we get rid of SUBDIRS-substitution? It doesn't work well with subdirs.
885: Use @samp{configdirs} (instead of the @samp{subdirs} variable
886: described below) if you want to be able to partition the
887: subdirectories, or use independent @file{Makefile} fragments.
888: Each subdirectory can be independent, and independently reconfigured.
889:
890: @item subdirs
891: @cindex @code{subdirs}
892: @vindex subdirs
893: Contains the names of any subdirectories where @code{configure} should create a
894: @file{Makefile} (in addition to the current directory), @emph{without}
895: recursively running @code{configure}. Use @samp{subdirs} (instead of the
896: @samp{configdirs} variable described above) if you want to configure all of the
897: directories as a unit. Since there is a single invocation of @code{configure}
898: that configures many directories, all the directories can use the same
899: @file{Makefile} fragments, and the same @code{configure.in}.
900:
901: @item host
902: @cindex @code{host}
903: @cindex Canonical ``triple''
904: @vindex host
905: Contains the full configuration name for the host (generated by the script
906: @file{config.sub} from the name that you entered). This is a three-part
907: name (commonly referred to as a @dfn{triple}) of the form
908: @var{cpu}-@var{vendor}-@var{os}.
909:
910: There are separate variables @samp{host_cpu}, @samp{host_vendor}, and
911: @samp{host_os} that you can use to test each of the three parts; this variable
912: is useful, however, for error messages, and for testing combinations of the
913: three components.
914:
915: @item host_cpu
916: @vindex host_cpu
917: Contains the first element of the canonical triple representing the host
918: as returned by @file{config.sub}. This is occasionally used to
919: distinguish between minor variations of a particular vendor's operating
920: system and sometimes to determine variations in binary format between
921: the host and the target.
922:
923: @item host_vendor
924: @vindex host_vendor
925: Contains the second element of the canonical triple representing the host as
926: returned by @file{config.sub}. This is usually used to distinguish among the
927: numerous variations of @emph{common} operating systems.
928: @c "@emph{common} OS" doesn't convey much to me. Is this meant to cover
929: @c cases like Unix, widespread but with many variations?
930:
931: @item host_os
932: @vindex host_os
933: Contains the the third element of the canonical triple representing the
934: host as returned by @file{config.sub}.
935:
936: @item target
937: @cindex @code{target}
938: @cindex Canonical ``triple''
939: @vindex target
940: Contains the full configuration name (generated by the script @file{config.sub}
941: from the name that you entered) for the target. Like the host, this is a
942: three-part name of the form @var{cpu}-@var{vendor}-@var{os}.
943:
944: There are separate variables @samp{target_cpu}, @samp{target_vendor}, and
945: @samp{target_os} that you can use to test each of the three parts; this
946: variable is useful, however, for error messages, and for testing combinations
947: of the three components.
948:
949: @item target_cpu
950: @vindex target_cpu
951: Contains the first element of the canonical triple representing the target as
952: returned by @file{config.sub}. This variable is used heavily by programs which
953: are involved in building other programs, like the compiler, assembler, linker,
954: etc. Most programs will not need the @samp{target} variables at all, but this
955: one could conceivably be used to build a program, for instance, that operated
956: on binary data files whose byte order or alignment differ from the system where
957: the program is running.
958:
959: @item target_vendor
960: @vindex target_vendor
961: Contains the second element of the canonical triple representing the target as
962: returned by @file{config.sub}. This is usually used to distinguish among the
963: numerous variations of @emph{common} operating systems or object file
964: formats. It is sometimes used to switch between different flavors of user
965: interfaces.
966: @c above query re "@emph{common} OS" applies here too
967:
968: @item target_os
969: @vindex target_os
970: Contains the the third element of the canonical triple representing the
971: target as returned by @file{config.sub}. This variable is used by
972: development tools to distinguish between subtle variations in object
973: file formats that some vendors use across operating system releases. It
974: might also be use to decide which libraries to build or what user
975: interface the tool should provide.
976:
977: @item floating_point
978: @cindex @code{floating_point}
979: @cindex @code{nfp} option
980: @vindex floating_point
981: Set to @samp{no} if you invoked @code{configure} with the @samp{--nfp}
982: command-line option, otherwise it is empty. This is a request to target
983: machines with @dfn{no floating point} unit, even if the targets ordinarily have
984: floating point units available.
985:
986: @item gas
987: @cindex @code{with-gnu-as} option
988: @vindex gas
989: Set to @samp{true} if you invoked @code{configure} with the
990: @w{@samp{--with-gnu-as}} command line option, otherwise it is empty. This is a
991: request to assume that the specified @var{hosttype} machine has @sc{gnu} @code{as}
992: available even if it ordinarily does not.
993:
994: @item srcdir
995: @cindex @code{srcdir}
996: @vindex srcdir
997: Set to the name of the directory containing the source for this program.
998: This will be different from @file{.} if you have specified the
999: @samp{--srcdir=@var{dir}} option. @samp{srcdir} can indicate either an
1000: absolute path or a path relative to the build directory.
1001:
1002: @item package_makefile_frag
1003: @vindex package_makefile_frag
1004: If set in @file{configure.in}, this variable should be the name a file relative
1005: to @samp{srcdir} to be included in the resulting @file{Makefile}. If the named
1006: file does not exist, @code{configure} will print a warning message. This
1007: variable is not set by @code{configure}.
1008:
1009: @item host_makefile_frag
1010: @vindex host_makefile_frag
1011: If set in @file{configure.in}, this variable should be the name a file relative
1012: to @samp{srcdir} to be included in the resulting @file{Makefile}. If the named
1013: file does not exist, @code{configure} will print a warning message. This
1014: variable is not set by @code{configure}.
1015:
1016: @item target_makefile_frag
1017: @vindex target_makefile_frag
1018: If set in @file{configure.in}, this variable should be the name of a file,
1019: relative to @samp{srcdir}, to be included in the resulting @file{Makefile}. If
1020: the named file does not exist, @code{configure} will print a warning message.
1021: This variable is not set by @code{configure}.
1022:
1023: @item site_makefile_frag
1024: @vindex site_makefile_frag
1025: Set to a file name representing to the default @file{Makefile} fragment for
1026: this host. It may be set in @file{configure.in} to override this default.
1027: Normally @samp{site_makefile_frag} is empty, but will have a value if you
1028: specify @samp{--site=@var{site}} on the command line.
1029: @ignore -- this doesn't fit
1030: It is probably not a good idea to override this variable from
1031: @file{configure.in}, since that may defeat the @code{configure} user's
1032: intentions.
1033: @end ignore
1034:
1035: @item Makefile
1036: @vindex Makefile
1037: Set to the name of the generated @file{Makefile}. Normally this value is
1038: precisely @file{Makefile}, but some programs may want something else.
1039:
1040: @item removing
1041: @cindex @code{rm} option
1042: @vindex removing
1043: Normally empty but will be set to some non-null value if you specified
1044: @samp{--rm} on the command line. That is, if @samp{removing} is not empty,
1045: then @code{configure} is @emph{removing} a configuration rather than creating
1046: one.
1047:
1048: @item files
1049: @cindex Symbolic links
1050: @vindex files
1051: If this variable is not empty following the @dfn{per-target} section,
1052: then each word in its value will be the target of a symbolic link named
1053: in the corresponding word from the @samp{links} variable.
1054:
1055: @item links
1056: @cindex Symbolic links
1057: @vindex links
1058: If the @samp{files} variable is not empty following the @dfn{per-target}
1059: section, then @code{configure} creates symbolic links with the first word of
1060: @samp{links} pointing to the first word of @samp{files}, the second word of
1061: @samp{links} pointing to the second word of @samp{files}, and so on.
1062: @end table
1063:
1064: @c ---------------------------------------------------------------------
1065: @node Minimal
1066: @subsection A minimal @code{configure.in}
1067: @cindex Minimal @file{configure.in} example
1068:
1069: A minimal @file{configure.in} consists of four lines.
1070:
1071: @example
1072: srctrigger=foo.c
1073: srcname="source for the foo program"
1074: # per-host:
1075: # per-target:
1076: @end example
1077:
1078: The @samp{# per-host:} and @samp{# per-target:} lines divide the file into the
1079: three required sections. The @samp{srctrigger} line names a file.
1080: @code{configure} checks to see that this file exists in the source directory
1081: before configuring. If the @samp{srctrigger} file does not exist,
1082: @code{configure} uses the value of @samp{srcname} to print an error message
1083: about not finding the source.
1084:
1085: This particular example uses no links, and only the default host,
1086: target, and site-specific @file{Makefile} fragments if they exist.
1087:
1088: @c ---------------------------------------------------------------------
1089: @node Declarations
1090: @subsection For each invocation
1091: @cindex For each invocation
1092: @cindex Declarations section
1093: @cindex @i{per-invocation} section
1094:
1095: @code{configure} invokes the entire shell script fragment from the start of
1096: @file{configure.in} up to a line beginning with @w{@samp{# per-host:}}
1097: immediately after parsing command line arguments. The variables
1098: @samp{srctrigger} and @samp{srcname} @emph{must} be set here.
1099:
1100: You might also want to set the variables @samp{configdirs} and
1101: @samp{package_makefile_frag} here.
1102:
1103: @c ---------------------------------------------------------------------
1104: @node per-host
1105: @subsection Host-specific instructions
1106: @cindex Host-specific instructions
1107: @cindex @i{host} shell-script fragment
1108: @cindex @i{per-host} section
1109:
1110: The @dfn{per-host} section of @file{configure.in} starts with the line that
1111: begins with @w{@samp{# per-host:}} and ends before a line beginning with
1112: @w{@samp{# per-target:}}. @code{configure} invokes the commands in the
1113: @dfn{per-host} section when determining host-specific information.
1114:
1115: This section usually contains a big @code{case} statement using the variable
1116: @samp{host} to determine appropriate values for @samp{host_makefile_frag} and
1117: @samp{files}, although @samp{files} is not usually set here. Usually, it is
1118: set at the end of the @dfn{per-target} section after determining the names of
1119: the target specific configuration files.
1120:
1121: @c ---------------------------------------------------------------------
1122: @node per-target
1123: @subsection Target-specific instructions
1124: @cindex Target-specific instructions
1125: @cindex target shell-script fragment
1126: @cindex @i{per-target} section
1127:
1128: The @dfn{per-target} section of @file{configure.in} starts with the line that
1129: begins with @w{@samp{# per-target:}} and ends before the line that begins with
1130: @w{@samp{# post-target:}}, if there is such a line. Otherwise the
1131: @dfn{per-target} section extends to the end of the file. @code{configure}
1132: invokes the commands in the @dfn{per-target} section when determining
1133: target-specific information, and before building any files, directories, or
1134: links.
1135:
1136: This section usually contains a big @code{case} statement using the variable
1137: @samp{target} to determine appropriate values for @samp{target_makefile_frag}
1138: and @samp{files}. The last lines in the @dfn{per-target} section normally set
1139: the variables @samp{files} and @samp{links}.
1140:
1141: @c ---------------------------------------------------------------------
1142: @node post-target
1143: @subsection Instructions to be executed after target info
1144: @cindex Post-target shell-script fragment
1145: @cindex @i{post-target} section
1146:
1147: The @dfn{post-target} section is optional. If it exists, the
1148: @samp{post-target} section starts with a line beginning with @w{@samp{#
1149: Post-target:}} and extends to the end of the file. If it exists,
1150: @code{configure} invokes this section once for each target after
1151: building all files, directories, or links.
1152:
1153: This section is seldom needed, but you can use it to edit the @file{Makefile}
1154: generated by @code{configure}.
1155:
1156: @c ---------------------------------------------------------------------
1157: @node Example
1158: @subsection An example @code{configure.in}
1159: @cindex Example @file{configure.in}
1160: @cindex Sample @file{configure.in}
1161: @c @cindex @code{bison} @file{configure.in}
1162: @c this won't be the bison configure.in for long.. need better example
1163:
1164: Here is a small example of a @file{configure.in} file.
1165:
1166: @cartouche
1167: @example
1168: @group
1169: # This file is a collection of shell script fragments
1170: # used to tailor a template configure script as
1171: # appropriate for this directory. For more information,
1172: # see configure.texi.
1173:
1174: configdirs=
1175: srctrigger=warshall.c
1176: srcname="bison"
1177:
1178: # per-host:
1179: case "$@{host@}" in
1180: m88k-motorola-*)
1181: host_makefile_frag=config/mh-delta88
1182: ;;
1183: esac
1184:
1185: # per-target:
1186: files="bison_in.hairy"
1187: links="bison.hairy"
1188:
1189: # post-target:
1190: @end group
1191: @end example
1192: @end cartouche
1193:
1194: @c ---------------------------------------------------------------------
1195: @node Install locations
1196: @section Install locations
1197: @cindex Where to install
1198: @cindex Install locations
1199:
1200: Using the default configuration, @samp{make install} creates a single tree of
1201: files, some of which are programs. The location of this tree is determined by
1202: the value of the variable @samp{prefix}. The default value of @samp{prefix} is
1203: @samp{/usr/local}. This is often correct for native tools installed on only
1204: one host.
1205:
1206: @menu
1207: * prefix:: Changing the default install directory
1208: * exec_prefix:: How to separate host independent files
1209: from host dependent files when
1210: installing for multiple hosts
1211: * Install details:: Full descriptions of all installation subdirectories
1212: @end menu
1213:
1214: @c ---------------------------------------------------------------------
1215: @node prefix
1216: @subsection Changing the default install directory
1217: @cindex Changing the install directory
1218: @cindex @code{prefix} option
1219: @vindex prefix
1220:
1221: In the default configuration, all files are installed in subdirectories
1222: of @file{/usr/local}. The location is determined by the value of
1223: the @code{configure} variable @samp{prefix}; in turn, this determines the
1224: value of the @file{Makefile} variable of the same name (@samp{prefix}).
1225:
1226: You can also set the value of the @file{Makefile} variable @samp{prefix}
1227: explicitly each time you invoke @code{make} if you are so inclined. However,
1228: because many programs have this location compiled in, you must specify the
1229: @samp{prefix} value consistently on each invocation of @code{make}, or you will
1230: end up with a broken installation.
1231:
1232: To make this easier, the value of the @code{configure} variable
1233: @samp{prefix} can be set on the command line to @code{configure}
1234: using the option @samp{--prefix=}.
1235:
1236: @c ---------------------------------------------------------------------
1237: @node exec_prefix
1238: @subsection Installing for multiple hosts
1239: @cindex Configuring for multiple hosts
1240: @cindex Sharing host-independent files
1241: @cindex Installing host-independent files
1242: @cindex The @code{exec_prefix} directory
1243: @vindex exec_prefix
1244:
1245: By default, host dependent files are installed in subdirectories of
1246: @file{$(exec_prefix)}. The location is determined by the value of the
1247: @code{configure} variable @samp{exec_prefix}, which determines the value of the
1248: @file{Makefile} variable @samp{exec_prefix}. This makes it easier to install
1249: for a single host, and simplifies changing the default location for the install
1250: tree. The default doesn't allow for multiple hosts to effectively share
1251: host independent files, however.
1252:
1253: To configure so that multiple hosts can share common files, use something like:
1254:
1255: @cindex Example session
1256: @smallexample
1257: configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
1258: make all info install install-info clean
1259:
1260: configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
1261: make all info install install-info
1262: @end smallexample
1263:
1264: The first line configures the source for @var{host1} to place host-specific
1265: programs in subdirectories of @file{/usr/gnu/H-@var{host1}}.
1266:
1267: The second line builds and installs all programs for @var{host1},
1268: including both host-independent and host-specific files, as well as removing
1269: the host-specific object files from of the build directory.
1270:
1271: The third line reconfigures the source for @var{host2} to place host
1272: specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}}.
1273:
1274: The fourth line builds and installs all programs for @var{host2}. Host
1275: specific files are installed in new directories, but the host
1276: independent files are installed @emph{on top of} the host
1277: independent files installed for @var{host1}. This results in a single
1278: copy of the host independent files, suitable for use by both hosts.
1279:
1280: @xref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}, for
1281: more information.
1282:
1283: @c ---------------------------------------------------------------------
1284: @node Install details
1285: @subsection Full descriptions of all installation subdirectories
1286: @cindex Install details
1287: @cindex Installation subdirectories
1288: @cindex Subdirectories
1289:
1290: During any install, a number of standard directories are created. Their names
1291: are determined by @file{Makefile} variables. Some of the defaults for
1292: @file{Makefile} variables can be changed at configuration time using command
1293: line options to @code{configure}. For more information on the standard
1294: directories or the @file{Makefile} variables, please refer to @ref{Makefiles, ,
1295: Makefile Conventions, standards, GNU Coding Standards}. See also @ref{Makefile
1296: extensions, , Extensions to the @sc{gnu} coding standards}.
1297:
1298: Note that @code{configure} does not create the directory indicated by the
1299: variable @samp{srcdir} at any time. @code{$(srcdir)} is not an installation
1300: directory.
1301:
1302: You can override all @file{Makefile} variables on the command line to
1303: @code{make}. (@xref{Overriding, , Overriding Variables, make, GNU Make}.) If
1304: you do so, you will need to specify the value precisely the same way for each
1305: invocation of @code{make}, or you risk ending up with a broken installation.
1306: This is because many programs have the locations of other programs or files
1307: compiled into them. If you find yourself overriding any of the variables
1308: frequently, you should consider site dependent @file{Makefile} fragments. See
1309: also @ref{Sites, , Adding site info}.
1310:
1311: During @samp{make install}, a number of standard directories are created and
1312: populated. The following @file{Makefile} variables define them. Those whose
1313: defaults are set by corresponding @code{configure} variables are marked
1314: ``@code{Makefile} and @code{configure}''.
1315:
1316: @table @code
1317: @item prefix (@code{Makefile} and @code{configure})
1318: @cindex @code{prefix}
1319: @vindex prefix
1320: The root of the installation tree. You can set its @file{Makefile} default
1321: with the @samp{--prefix=} command line option to @code{configure}
1322: (@pxref{Invoking configure, , Invoking @code{configure}}). The default value
1323: for @samp{prefix} is @samp{/usr/local}.
1324:
1325: @item bindir
1326: @cindex @code{bindir}
1327: @vindex bindir
1328: A directory for binary programs that users can run. The default value for
1329: @samp{bindir} depends on @samp{prefix}; @samp{bindir} is normally changed only
1330: indirectly through @samp{prefix}. The default value for @samp{bindir} is
1331: @samp{$(prefix)/bin}.
1332:
1333: @item exec_prefix (@code{Makefile} and @code{configure})
1334: @cindex @code{exec_prefix}
1335: @vindex exec_prefix
1336: A directory for host dependent files. You can specify the @file{Makefile}
1337: default value by using the @samp{--exec_prefix=} option to @code{configure}.
1338: (@xref{Invoking configure, , Invoking @code{configure}}.) The default value
1339: for @samp{exec_prefix} is @samp{$(prefix)}.
1340:
1341: @item libdir
1342: @cindex @code{libdir}
1343: @vindex libdir
1344: A directory for libraries and support programs. The default value for
1345: @samp{libdir} depends on @samp{prefix}; @samp{libdir} is normally changed only
1346: indirectly through @samp{prefix}. The default value for @samp{libdir} is
1347: @samp{$(prefix)/lib}.
1348:
1349: @item mandir
1350: @cindex @code{mandir}
1351: @vindex mandir
1352: A directory for @code{man} format documentation (``man pages''). The default
1353: value for @samp{mandir} depends on @samp{prefix}; @samp{mandir} is normally
1354: changed only indirectly through @samp{prefix}. The default value for
1355: @samp{mandir} is @samp{$(prefix)/man}.
1356:
1357: @item man@var{N}dir
1358: @cindex @code{man@var{N}dir}
1359: @vindex man@var{N}dir
1360: These are eight variables named @samp{man1dir}, @samp{man2dir}, etc. They name
1361: the specific directories for each man page section. For example,
1362: @samp{man1dir} by default holds the filename @file{$(mandir)/man1}; this
1363: directory contains @file{emacs.1} (the man page for @sc{gnu} Emacs).
1364: Similarly, @samp{man5dir} contains the value @file{$(mandir)/man5}, indicating
1365: the directory which holds @file{rcsfile.5} (the man page describing the
1366: @code{rcs} data file format). The default value for any of the
1367: @samp{man@var{N}dir} variables depends indirectly on @samp{prefix}, and is
1368: normally changed only through @samp{prefix}. The default value for
1369: @samp{man@var{N}dir} is @samp{$(mandir)/man@var{N}}.
1370:
1371: @item man@var{N}ext
1372: @cindex @code{man@var{N}ext}
1373: @vindex man@var{N}ext
1374: @emph{Not supported by Cygnus @code{configure}}. The @cite{@sc{gnu} Coding
1375: Standards} do not call for @samp{man1ext}, @samp{man2ext}, so the intended use
1376: for @code{manext} is apparently not parallel to @samp{mandir}. Its use is not
1377: clear. (See also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding
1378: standards}.)
1379:
1380: @item infodir
1381: @cindex @code{infodir}
1382: @vindex infodir
1383: A directory for @code{info} format documentation. The default value for
1384: @samp{infodir} depends indirectly on @samp{prefix}; @samp{infodir} is
1385: normally changed only through @samp{prefix}. The default value for
1386: @samp{infodir} is @samp{$(prefix)/info}.
1387:
1388: @item docdir
1389: @cindex @code{docdir}
1390: @vindex docdir
1391: A directory for any documentation that is in a format other than those used by
1392: @code{info} or @code{man}. The default value for @samp{docdir} depends
1393: indirectly on @samp{prefix}; @samp{docdir} is normally changed only through
1394: @samp{prefix}. The default value for @samp{docdir} is @samp{$(datadir)/doc}.
1395: @emph{This variable is an extension to the @sc{gnu} coding standards}. (See
1396: also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}.)
1397:
1398: @item includedir
1399: @cindex @code{includedir}
1400: @vindex includedir
1401: A directory for the header files accompanying the libraries installed in
1402: @samp{libdir}. The default value for @samp{includedir} depends on
1403: @samp{prefix}; @samp{includedir} is normally changed only indirectly
1404: through @samp{prefix}. The default value for @samp{includedir} is
1405: @samp{$(prefix)/include}.
1406: @end table
1407:
1408: @c ---------------------------------------------------------------------
1409: @node Host
1410: @section Host
1411: @cindex Host
1412:
1413: The arguments to @code{configure} are @dfn{hosttypes}. By
1414: @dfn{hosttype} we mean the @dfn{environment} in which the source will be
1415: compiled. This need not necessarily be the same as the physical machine
1416: involved, although it usually is.
1417:
1418: For example, if some obscure machine had the @sc{gnu} @code{POSIX} emulation
1419: libraries available, it would be possible to configure most @sc{gnu} source for
1420: a @code{POSIX} system and build it on the obscure host.
1421:
1422: For more on this topic, see @ref{Host Environments, On Configuring Development
1423: Tools, Host Environments, cfg-paper, On Configuring Development Tools}.
1424:
1425: @c ---------------------------------------------------------------------
1426: @node Target
1427: @section Target
1428: @cindex Target
1429:
1430: For building native development tools, or most of the other @sc{gnu}
1431: tools, you need not worry about the target. The @dfn{target} of a
1432: configuration defaults to the same as the @dfn{host}.
1433:
1434: For building cross development tools, please see @ref{Building Development
1435: Environments, On Configuring Development Tools, Building Development
1436: Environments, cfg-paper, On Configuring Development Tools}.
1437:
1438: @c ---------------------------------------------------------------------
1439: @node Makefile fragments
1440: @section Adding information about local conventions
1441: @cindex @code{Makefile} fragments
1442: @cindex Local conventions
1443: @cindex Adding local info
1444: @cindex Adding site info
1445:
1446: If you find that a tool does not get configured to your liking, or if
1447: @code{configure}'s conventions differ from your local conventions, you should
1448: probably consider @dfn{site-specific @file{Makefile} fragments}. See also
1449: @ref{Sites, , Adding site info}.
1450:
1451: These are probably not the right choice for options that can be set from
1452: the @code{configure} command line or for differences that are host or
1453: target dependent.
1454:
1455: Cygnus @code{configure} uses three types of @file{Makefile} fragments. In a
1456: generated @file{Makefile} they appear in the order: @dfn{target fragment},
1457: @dfn{host fragment}, and @dfn{site fragment}. This allows host fragments to
1458: override target fragments, and site fragments to override both.
1459:
1460: Host-specific @file{Makefile} fragments conventionally reside in the
1461: @file{./config/} subdirectory with names of the form @file{mh-@var{hosttype}}.
1462: They are used for hosts that require odd options to the standard compiler and
1463: for compile time options based on the host configuration.
1464:
1465: Target-specific @file{Makefile} fragments conventionally reside in the
1466: @file{./config/} subdirectory with names of the form @file{mt-@var{target}}.
1467: They are used for target dependent compile time options.
1468:
1469: Site specific @file{Makefile} fragments conventionally reside in the
1470: @file{./config/} subdirectory with names of the form @file{ms-@var{site}}.
1471: They are used to override host- and target-independent compile time options.
1472: Note that you can also override these options on the @code{make} invocation
1473: line.
1474:
1475: @c ---------------------------------------------------------------------
1476: @node Makefile extensions
1477: @section Extensions to the @sc{gnu} coding standards
1478: @cindex @code{Makefile} extensions
1479: @cindex Cygnus extensions
1480: @cindex Coding standards extensions
1481:
1482: The following additions to the @sc{gnu} coding standards are required for
1483: Cygnus @code{configure} to work properly.
1484:
1485: @itemize @bullet
1486: @item
1487: The @file{Makefile} must contain exactly one line starting with @samp{####}.
1488: This line should follow any default macro definitions but precede any rules.
1489: Host, target, and site-specific @file{Makefile} fragments will be inserted
1490: immediately after this line. If the line is missing, the fragments will not be
1491: inserted.
1492:
1493: @item
1494: Cygnus adds the following targets to each @file{Makefile}. Their existence is
1495: not required for Cygnus @code{configure}, but they are documented here for
1496: completeness.
1497:
1498: @table @code
1499: @kindex info
1500: @item info
1501: Build all info files from texinfo source.
1502:
1503: @kindex install-info
1504: @item install-info
1505: Install all info files.
1506:
1507: @kindex clean-info
1508: @item clean-info
1509: Remove all info files and any intermediate files that can be generated
1510: from texinfo source.
1511:
1512: @kindex Makefile
1513: @item Makefile
1514: Calls @code{./config.status} to rebuild the @file{Makefile} in this directory.
1515: @end table
1516:
1517: @item
1518: The following @file{Makefile} targets have revised semantics:
1519:
1520: @table @code
1521: @kindex install
1522: @item install
1523: Should @emph{not} depend on the target @samp{all}. If the program is not
1524: already built, @samp{make install} should fail. This allows you to install
1525: programs even when @code{make} would otherwise determine them to be out of
1526: date. This can happen, for example, when the result of a @samp{make all} is
1527: transported via tape to another machine for installation.
1528:
1529: @kindex clean
1530: @item clean
1531: Should remove any file that can be regenerated by the @file{Makefile},
1532: excepting only the @file{Makefile} itself, and any links created by
1533: @code{configure}. That is, @code{make all clean} should return all directories
1534: to their original condition. If this is not done, then the command sequence
1535:
1536: @cindex Example session
1537: @example
1538: configure @var{host1} ; make all install clean ;
1539: configure @var{host2} ; make all install
1540: @end example
1541:
1542: @noindent
1543: will fail because of intermediate files intended for @var{host1}.
1544: @end table
1545:
1546: @item
1547: Cygnus adds the following macros to all @file{Makefile.in} files, but
1548: you are not required to use them to run Cygnus @code{configure}.
1549:
1550: @table @code
1551: @kindex docdir
1552: @item docdir
1553: The directory in which to install any documentation that is not either a
1554: @code{man} page or an @code{info} file. For @code{man} pages, see
1555: @samp{mandir}; for @code{info}, see @samp{infodir}.
1556:
1557: @kindex includedir
1558: @item includedir
1559: The directory in which to install any header files that should be made
1560: available to users. This is distinct from the @code{gcc} include directory,
1561: which is intended for @code{gcc} only. Files in @samp{includedir} may be used
1562: by @code{cc} as well.
1563: @end table
1564:
1565: @item
1566: The following macros have revised semantics. Most of them describe
1567: installation directories; see also @ref{Install details, , Full description of
1568: all installation subdirectories}.
1569:
1570: @table @code
1571: @kindex datadir
1572: @item datadir
1573: is used for host independent data files.
1574:
1575: @kindex mandir
1576: @item mandir
1577: The default path for @samp{mandir} depends on @samp{prefix}.
1578:
1579: @kindex infodir
1580: @item infodir
1581: The default path for @samp{infodir} depends on @samp{prefix}.
1582:
1583: @kindex BISON
1584: @item BISON
1585: is assumed to have a @code{yacc} calling convention. To use @sc{gnu}
1586: @code{bison}, use @samp{BISON=bison -y}.
1587: @end table
1588:
1589: @item
1590: Each Cygnus @file{Makefile} also conforms to one additional restriction:
1591:
1592: When libraries are installed, the line containing the call to
1593: @samp{INSTALL_DATA} should always be followed by a line containing a call to
1594: @samp{RANLIB} on the installed library. This is to accommodate systems that
1595: use @code{ranlib}. Systems that do not use @code{ranlib} can set @samp{RANLIB}
1596: to ``@code{echo}'' in a host specific @file{Makefile} fragment.
1597: @end itemize
1598:
1599: @c ========================================================================
1600: @node Porting
1601: @chapter Porting with @code{configure}
1602: @cindex Porting with @code{configure}
1603:
1604: This section explains how to add programs, host and target configuration
1605: names, and site-specific information to Cygnus @code{configure}.
1606:
1607: @menu
1608: * Programs:: Adding configure to new programs
1609: * Hosts and targets:: Adding hosts and targets
1610: * Sites:: Adding site info
1611: @end menu
1612:
1613: @c ---------------------------------------------------------------------
1614: @node Programs
1615: @section Adding @code{configure} to new programs
1616: @cindex Adding @code{configure} to new programs
1617:
1618: If you are writing a new program, you probably shouldn't worry about porting or
1619: configuration issues until it is running reasonably on some host. Then refer
1620: back to this section.
1621:
1622: If your program currently has a @code{configure} script that meets the @sc{gnu}
1623: standards (@pxref{Configuration, , How Configuration Should Work, standards,
1624: GNU Coding Standards}, please do not add Cygnus @code{configure}. It should be
1625: possible to add this program without change to a Cygnus @code{configure} style
1626: source tree.
1627:
1628: @cindex @code{autoconf}
1629: If the program is not target dependent, please consider using @code{autoconf}
1630: instead of Cygnus @code{configure}. @code{autoconf} is available from the Free
1631: Software Foundation; it is a program which generates an executable shell script
1632: called @file{configure} by automatically finding information on the system to
1633: be configured on and embedding this information in the shell script.
1634: @file{configure} scripts generated by @code{autoconf} require no arguments, and
1635: accept the same options as Cygnus @code{configure}. For detailed instructions
1636: on using @code{autoconf}, see @ref{Making configure Scripts, , How to organize
1637: and produce Autoconf scripts, autoconf, Autoconf}.
1638:
1639:
1640: To add Cygnus @code{configure} to an existing program, do the following:
1641:
1642: @table @bullet
1643: @item Make sure the @file{Makefile} conforms to the @sc{gnu} standard
1644: The coding standard for writing a @sc{gnu} @file{Makefile} is described in
1645: @ref{Makefiles, , Makefile Conventions, standards, GNU Coding Standards}. For
1646: technical information on writing a @file{Makefile}, see @ref{Makefiles, ,
1647: Writing Makefiles, make, GNU Make}.
1648:
1649: @item Add Cygnus extensions to the @file{Makefile}
1650: These are described in @ref{Makefile extensions, , Extensions to the @sc{gnu}
1651: coding standards}.
1652:
1653: @item Collect package specific definitions in a single file
1654: Many packages are best configured using a common @file{Makefile} fragment which
1655: is included by all of the makefiles in the different directories of the
1656: package. In order to accomplish this, set the variable
1657: @samp{package_makefile_fragment} to the name of the file. It will be inserted
1658: into the final @file{Makefile} before the target-specific fragment.
1659:
1660: @item Move host support from @file{Makefile} to fragments
1661: This usually involves finding sections of the @file{Makefile} that say things
1662: like ``uncomment these lines for host @var{hosttype}'' and moving them to a new
1663: file called @file{./config/mh-@var{hosttype}}. For more information, see @ref{Hosts
1664: and targets, , Adding hosts and targets}.
1665:
1666: @item Choose defaults
1667: If the program has compile-time options that determine the way the program
1668: should behave, choose reasonable defaults and make these @file{Makefile}
1669: variables. Be sure the variables are assigned their default values before the
1670: @samp{####} line so that site-specific @file{Makefile} fragments can override
1671: them (@pxref{Makefile extensions, , Extensions to the @sc{gnu} coding
1672: standards}).
1673:
1674: @item Locate configuration files
1675: If there is configuration information in header files or source files, separate
1676: it in such a way that the files have generic names. Then move the specific
1677: instances of those files into the @file{./config/} subdirectory.
1678:
1679: @item Separate host and target information
1680: Some programs already have this information separated. If yours does not, you
1681: will need to separate these two kinds of configuration information. @dfn{Host
1682: specific} information is the information needed to compile the program.
1683: @dfn{Target specific} information is information on the format of data files
1684: that the program will read or write. This information should live in separate
1685: files in the @file{./config/} subdirectory with names that reflect the
1686: configuration for which they are intended.
1687:
1688: At this point you might skip this step and simply move on. If you do, you
1689: should end up with a program that can be configured only to build @dfn{native}
1690: tools, that is, tools for which the host system is also the target system.
1691: Later, you could attempt to build a cross tool and separate out the
1692: target-specific information by figuring out what went wrong. This is often
1693: simpler than combing through all of the source code.
1694:
1695: @item Write @code{configure.in}
1696: Usually this involves writing shell script fragments to map from canonical
1697: configuration names into the names of the configuration files. These files
1698: will then be linked at configure time from the specific instances of those
1699: files in @file{./config} to files in the build directory with more generic
1700: names. (See also @ref{Build directories, , Build directories}.) The format of
1701: @file{configure.in} is described in @ref{configure.in, , The
1702: @code{configure.in} input file}.
1703:
1704: @item Rename @file{Makefile} to @file{Makefile.in}
1705: @end table
1706:
1707: At this point you should have a program that can be configured using
1708: Cygnus @code{configure}.
1709:
1710: @c ---------------------------------------------------------------------
1711: @node Hosts and targets
1712: @section Adding hosts and targets
1713: @cindex Adding hosts and targets
1714: @cindex Hosts and targets
1715:
1716: To add a host or target to a program that already uses Cygnus @code{configure},
1717: do the following.
1718:
1719: @itemize @bullet
1720:
1721: @item
1722: Make sure the new configuration name is represented in @file{config.sub}. If
1723: not, add it. For more details, see the comments in the shell script
1724: @file{config.sub}.
1725:
1726: @item
1727: If you are adding a host configuration, look in @file{configure.in}, in the
1728: @dfn{per-host} section. Make sure that your configuration name is represented
1729: in the mapping from host configuration names to configuration files. If not,
1730: add it. Also see @ref{configure.in, , The @code{configure.in} input file}.
1731:
1732: @item
1733: If you are adding a target configuration, look in @file{configure.in}, in the
1734: @dfn{per-target} section. Make sure that your configuration name is
1735: represented in the mapping from target configuration names to configuration
1736: files. If not, add it. Also see @ref{configure.in, , The @code{configure.in}
1737: input file}.
1738:
1739: @item
1740: Look in @file{configure.in} for the variables @samp{files}, @samp{links},
1741: @samp{host_makefile_frag}, and @samp{target_makefile_frag}. The values
1742: assigned to these variables are the names of the configuration files, (relative
1743: to @samp{srcdir}) that the program uses. Make sure that copies of the files
1744: exist for your host. If not, create them. See also @ref{configure variables,
1745: , Variables available to @code{configure.in}}.
1746: @end itemize
1747:
1748: This should be enough to @code{configure} for a new host or target
1749: configuration name. Getting the program to compile and run properly represents
1750: the hardest work of any port.
1751:
1752: @c ---------------------------------------------------------------------
1753: @node Sites
1754: @section Adding site info
1755: @cindex Sites
1756: @cindex Adding site info
1757:
1758: If some of the @file{Makefile} defaults are not right for your site, you can
1759: build site-specific @file{Makefile} fragments. To do this, do the following.
1760:
1761: @itemize @bullet
1762:
1763: @item
1764: Choose a name for your site. It must currently be less than eleven characters.
1765:
1766: @item
1767: If the program source does not have a @file{./config/} subdirectory, create it.
1768:
1769: @item
1770: Create a file called @file{./config/ms-@var{site}} where @var{site} is the name
1771: of your site. In it, set whatever @file{Makefile} variables you need to
1772: override to match your site's conventions.
1773:
1774: @item
1775: Configure the program with:
1776:
1777: @cindex Example session
1778: @example
1779: configure @dots{} --site=@var{site}
1780: @end example
1781:
1782: @end itemize
1783:
1784: @c ---------------------------------------------------------------------
1785: @node Variables Index
1786: @unnumbered Variable Index
1787:
1788: @printindex vr
1789:
1790: @page
1791: @c ---------------------------------------------------------------------
1792: @node Concept Index
1793: @unnumbered Concept Index
1794:
1795: @printindex cp
1796: @contents
1797: @bye
1798:
1799: @c Local Variables:
1800: @c fill-column: 79
1801: @c outline-regexp: "@chap"
1802: @c End:
1803: @c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")
1804:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.