daily update
[binutils.git] / etc / configure.texi
blob58c5285488fb5c96c7283fa474381d3f03d81fa4
1 \input texinfo
2 @c %**start of header
3 @setfilename configure.info
4 @settitle The GNU configure and build system
5 @setchapternewpage off
6 @c %**end of header
8 @dircategory GNU admin
9 @direntry
10 * configure: (configure).       The GNU configure and build system
11 @end direntry
13 @ifnottex
14 This file documents the GNU configure and build system.
16 Copyright (C) 1998 Cygnus Solutions.
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.
22 @ignore
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
28 @end ignore
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
37 by the Foundation.
38 @end ifnottex
40 @titlepage
41 @title The GNU configure and build system
42 @author Ian Lance Taylor
44 @page
45 @vskip 0pt plus 1filll
46 Copyright @copyright{} 1998 Cygnus Solutions
48 Permission is granted to make and distribute verbatim copies of
49 this manual provided the copyright notice and this permission notice
50 are preserved on all copies.
52 Permission is granted to copy and distribute modified versions of this
53 manual under the conditions for verbatim copying, provided that the entire
54 resulting derived work is distributed under the terms of a permission
55 notice identical to this one.
57 Permission is granted to copy and distribute translations of this manual
58 into another language, under the above conditions for modified versions,
59 except that this permission notice may be stated in a translation
60 approved by the Free Software Foundation.
61 @end titlepage
63 @ifnottex
64 @node Top
65 @top GNU configure and build system
67 The GNU configure and build system.
69 @menu
70 * Introduction::                Introduction.
71 * Getting Started::             Getting Started.
72 * Files::                       Files.
73 * Configuration Names::         Configuration Names.
74 * Cross Compilation Tools::     Cross Compilation Tools.
75 * Canadian Cross::              Canadian Cross.
76 * Cygnus Configure::            Cygnus Configure.
77 * Multilibs::                   Multilibs.
78 * FAQ::                         Frequently Asked Questions.
79 * Index::                       Index.
80 @end menu
82 @end ifnottex
84 @node Introduction
85 @chapter Introduction
87 This document describes the GNU configure and build systems.  It
88 describes how autoconf, automake, libtool, and make fit together.  It
89 also includes a discussion of the older Cygnus configure system.
91 This document does not describe in detail how to use each of the tools;
92 see the respective manuals for that.  Instead, it describes which files
93 the developer must write, which files are machine generated and how they
94 are generated, and where certain common problems should be addressed.
96 @ifnothtml
97 This document draws on several sources, including the autoconf manual by
98 David MacKenzie (@pxref{Top, , autoconf overview, autoconf, Autoconf}),
99 the automake manual by David MacKenzie and Tom Tromey (@pxref{Top, ,
100 automake overview, automake, GNU Automake}), the libtool manual by
101 Gordon Matzigkeit (@pxref{Top, , libtool overview, libtool, GNU
102 libtool}), and the Cygnus configure manual by K. Richard Pixley.
103 @end ifnothtml
104 @ifhtml
105 This document draws on several sources, including
106 @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_toc.html, the
107 autoconf manual} by David MacKenzie,
108 @uref{http://www.delorie.com/gnu/docs/automake/automake_toc.html, the
109 automake manual} by David MacKenzie and Tom Tromey,
110 @uref{http://www.delorie.com/gnu/docs/libtool/libtool_toc.html, the
111 libtool manual} by Gordon Matzigkeit, and the Cygnus configure manual by
112 K. Richard Pixley.
113 @end ifhtml
115 @menu
116 * Goals::                       Goals.
117 * Tools::                       The tools.
118 * History::                     History.
119 * Building::                    Building.
120 @end menu
122 @node Goals
123 @section Goals
124 @cindex goals
126 The GNU configure and build system has two main goals.
128 The first is to simplify the development of portable programs.  The
129 system permits the developer to concentrate on writing the program,
130 simplifying many details of portability across Unix and even Windows
131 systems, and permitting the developer to describe how to build the
132 program using simple rules rather than complex Makefiles.
134 The second is to simplify the building of programs distributed as source
135 code.  All programs are built using a simple, standardized, two step
136 process.  The program builder need not install any special tools in
137 order to build the program.
139 @node Tools
140 @section Tools
142 The GNU configure and build system is comprised of several different
143 tools.  Program developers must build and install all of these tools.
145 People who just want to build programs from distributed sources normally
146 do not need any special tools beyond a Unix shell, a make program, and a
147 C compiler.
149 @table @asis
150 @item autoconf
151 provides a general portability framework, based on testing the features
152 of the host system at build time.
153 @item automake
154 a system for describing how to build a program, permitting the developer
155 to write a simplified @file{Makefile}.
156 @item libtool
157 a standardized approach to building shared libraries.
158 @item gettext
159 provides a framework for translation of text messages into other
160 languages; not really discussed in this document.
161 @item m4
162 autoconf requires the GNU version of m4; the standard Unix m4 does not
163 suffice.
164 @item perl
165 automake requires perl.
166 @end table
168 @node History
169 @section History
170 @cindex history
172 This is a very brief and probably inaccurate history.
174 As the number of Unix variants increased during the 1980s, it became
175 harder to write programs which could run on all variants.  While it was
176 often possible to use @code{#ifdef} to identify particular systems,
177 developers frequently did not have access to every system, and the
178 characteristics of some systems changed from version to version.
180 By 1992, at least three different approaches had been developed:
181 @itemize @bullet
182 @item
183 The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael
184 Manfredi.
185 @item
186 The Cygnus configure script, by K. Richard Pixley, and the gcc configure
187 script, by Richard Stallman.  These use essentially the same approach,
188 and the developers communicated regularly.
189 @item
190 The autoconf program, by David MacKenzie.
191 @end itemize
193 The Metaconfig program is still used for Perl and a few other programs.
194 It is part of the Dist package.  I do not know if it is being developed.
196 In 1994, David MacKenzie and others modified autoconf to incorporate all
197 the features of Cygnus configure.  Since then, there has been a slow but
198 steady conversion of GNU programs from Cygnus configure to autoconf. gcc
199 has been converted, eliminating the gcc configure script.
201 GNU autoconf was regularly maintained until late 1996.  As of this
202 writing in June, 1998, it has no public maintainer.
204 Most programs are built using the make program, which requires the
205 developer to write Makefiles describing how to build the programs.
206 Since most programs are built in pretty much the same way, this led to a
207 lot of duplication.
209 The X Window system is built using the imake tool, which uses a database
210 of rules to eliminate the duplication.  However, building a tool which
211 was developed using imake requires that the builder have imake
212 installed, violating one of the goals of the GNU system.
214 The new BSD make provides a standard library of Makefile fragments,
215 which permits developers to write very simple Makefiles.  However, this
216 requires that the builder install the new BSD make program.
218 In 1994, David MacKenzie wrote the first version of automake, which
219 permitted writing a simple build description which was converted into a
220 Makefile which could be used by the standard make program.  In 1995, Tom
221 Tromey completely rewrote automake in Perl, and he continues to enhance
224 Various free packages built libraries, and by around 1995 several
225 included support to build shared libraries on various platforms.
226 However, there was no consistent approach.  In early 1996, Gordon
227 Matzigkeit began working on libtool, which provided a standardized
228 approach to building shared libraries.  This was integrated into
229 automake from the start.
231 The development of automake and libtool was driven by the GNITS project,
232 a group of GNU maintainers who designed standardized tools to help meet
233 the GNU coding standards.
235 @node Building
236 @section Building
238 Most readers of this document should already know how to build a tool by
239 running @samp{configure} and @samp{make}.  This section may serve as a
240 quick introduction or reminder.
242 Building a tool is normally as simple as running @samp{configure}
243 followed by @samp{make}.  You should normally run @samp{configure} from
244 an empty directory, using some path to refer to the @samp{configure}
245 script in the source directory.  The directory in which you run
246 @samp{configure} is called the @dfn{object directory}.
248 In order to use a object directory which is different from the source
249 directory, you must be using the GNU version of @samp{make}, which has
250 the required @samp{VPATH} support.  Despite this restriction, using a
251 different object directory is highly recommended:
252 @itemize @bullet
253 @item
254 It keeps the files generated during the build from cluttering up your
255 sources.
256 @item 
257 It permits you to remove the built files by simply removing the entire
258 build directory.
259 @item
260 It permits you to build from the same sources with several sets of
261 configure options simultaneously.
262 @end itemize
264 If you don't have GNU @samp{make}, you will have to run @samp{configure}
265 in the source directory.  All GNU packages should support this; in
266 particular, GNU packages should not assume the presence of GNU
267 @samp{make}.
269 After running @samp{configure}, you can build the tools by running
270 @samp{make}.
272 To install the tools, run @samp{make install}.  Installing the tools
273 will copy the programs and any required support files to the
274 @dfn{installation directory}.  The location of the installation
275 directory is controlled by @samp{configure} options, as described below.
277 In the Cygnus tree at present, the info files are built and installed as
278 a separate step.  To build them, run @samp{make info}.  To install them,
279 run @samp{make install-info}. The equivalent html files are also built
280 and installed in a separate step. To build the html files, run
281 @samp{make html}. To install the html files run @samp{make install-html}.
283 All @samp{configure} scripts support a wide variety of options.  The
284 most interesting ones are @samp{--with} and @samp{--enable} options
285 which are generally specific to particular tools.  You can usually use
286 the @samp{--help} option to get a list of interesting options for a
287 particular configure script.
289 The only generic options you are likely to use are the @samp{--prefix}
290 and @samp{--exec-prefix} options.  These options are used to specify the
291 installation directory.
293 The directory named by the @samp{--prefix} option will hold machine
294 independent files such as info files.
296 The directory named by the @samp{--exec-prefix} option, which is
297 normally a subdirectory of the @samp{--prefix} directory, will hold
298 machine dependent files such as executables.
300 The default for @samp{--prefix} is @file{/usr/local}.  The default for
301 @samp{--exec-prefix} is the value used for @samp{--prefix}.
303 The convention used in Cygnus releases is to use a @samp{--prefix}
304 option of @file{/usr/cygnus/@var{release}}, where @var{release} is the
305 name of the release, and to use a @samp{--exec-prefix} option of
306 @file{/usr/cygnus/@var{release}/H-@var{host}}, where @var{host} is the
307 configuration name of the host system (@pxref{Configuration Names}).
309 Do not use either the source or the object directory as the installation
310 directory.  That will just lead to confusion.
312 @node Getting Started
313 @chapter Getting Started
315 To start using the GNU configure and build system with your software
316 package, you must write three files, and you must run some tools to
317 manually generate additional files.
319 @menu
320 * Write configure.in::          Write configure.in.
321 * Write Makefile.am::           Write Makefile.am.
322 * Write acconfig.h::            Write acconfig.h.
323 * Generate files::              Generate files.
324 * Getting Started Example::     Example.
325 @end menu
327 @node Write configure.in
328 @section Write configure.in
329 @cindex @file{configure.in}, writing
331 You must first write the file @file{configure.in}.  This is an autoconf
332 input file, and the autoconf manual describes in detail what this file
333 should look like.
335 You will write tests in your @file{configure.in} file to check for
336 conditions that may change from one system to another, such as the
337 presence of particular header files or functions.
339 For example, not all systems support the @samp{gettimeofday} function.
340 If you want to use the @samp{gettimeofday} function when it is
341 available, and to use some other function when it is not, you would
342 check for this by putting @samp{AC_CHECK_FUNCS(gettimeofday)} in
343 @file{configure.in}.
345 When the configure script is run at build time, this will arrange to
346 define the preprocessor macro @samp{HAVE_GETTIMEOFDAY} to the value 1 if
347 the @samp{gettimeofday} function is available, and to not define the
348 macro at all if the function is not available.  Your code can then use
349 @samp{#ifdef} to test whether it is safe to call @samp{gettimeofday}.
351 If you have an existing body of code, the @samp{autoscan} program may
352 help identify potential portability problems, and hence configure tests
353 that you will want to use.
354 @ifnothtml
355 @xref{Invoking autoscan, , , autoconf, the autoconf manual}.
356 @end ifnothtml
357 @ifhtml
358 See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_4.html, the
359 autoscan documentation}.
360 @end ifhtml
362 Another handy tool for an existing body of code is @samp{ifnames}.  This
363 will show you all the preprocessor conditionals that the code already
364 uses.
365 @ifnothtml
366 @xref{Invoking ifnames, , , autoconf, the autoconf manual}.
367 @end ifnothtml
368 @ifhtml
369 See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_5.html, the
370 ifnames documentation}.
371 @end ifhtml
373 Besides the portability tests which are specific to your particular
374 package, every @file{configure.in} file should contain the following
375 macros.
377 @table @samp
378 @item AC_INIT
379 @cindex @samp{AC_INIT}
380 This macro takes a single argument, which is the name of a file in your
381 package.  For example, @samp{AC_INIT(foo.c)}.
383 @item AC_PREREQ(@var{VERSION})
384 @cindex @samp{AC_PREREQ}
385 This macro is optional.  It may be used to indicate the version of
386 @samp{autoconf} that you are using.  This will prevent users from
387 running an earlier version of @samp{autoconf} and perhaps getting an
388 invalid @file{configure} script.  For example, @samp{AC_PREREQ(2.12)}.
390 @item AM_INIT_AUTOMAKE
391 @cindex @samp{AM_INIT_AUTOMAKE}
392 This macro takes two arguments: the name of the package, and a version
393 number.  For example, @samp{AM_INIT_AUTOMAKE(foo, 1.0)}.  (This macro is
394 not needed if you are not using automake).
396 @item AM_CONFIG_HEADER
397 @cindex @samp{AM_CONFIG_HEADER}
398 This macro names the header file which will hold the preprocessor macro
399 definitions at run time.  Normally this should be @file{config.h}.  Your
400 sources would then use @samp{#include "config.h"} to include it.
402 This macro may optionally name the input file for that header file; by
403 default, this is @file{config.h.in}, but that file name works poorly on
404 DOS filesystems.  Therefore, it is often better to name it explicitly as
405 @file{config.in}.
407 This is what you should normally put in @file{configure.in}:
408 @example
409 AM_CONFIG_HEADER(config.h:config.in)
410 @end example
412 @cindex @samp{AC_CONFIG_HEADER}
413 (If you are not using automake, use @samp{AC_CONFIG_HEADER} rather than
414 @samp{AM_CONFIG_HEADER}).
416 @item AM_MAINTAINER_MODE
417 @cindex @samp{AM_MAINTAINER_MODE}
418 This macro always appears in Cygnus configure scripts.  Other programs
419 may or may not use it.
421 If this macro is used, the @samp{--enable-maintainer-mode} option is
422 required to enable automatic rebuilding of generated files used by the
423 configure system.  This of course requires that developers be aware of,
424 and use, that option.
426 If this macro is not used, then the generated files will always be
427 rebuilt automatically.  This will cause problems if the wrong versions
428 of autoconf, automake, or others are in the builder's @samp{PATH}.
430 (If you are not using automake, you do not need to use this macro).
432 @item AC_EXEEXT
433 @cindex @samp{AC_EXEEXT}
434 @cindex @samp{AM_EXEEXT}
435 Either this macro or @samp{AM_EXEEXT} always appears in Cygnus configure
436 files.  Other programs may or may not use one of them.
438 This macro looks for the executable suffix used on the host system.  On
439 Unix systems, this is the empty string.  On Windows systems, this is
440 @samp{.exe}.  This macro directs automake to use the executable suffix
441 as appropriate when creating programs.  This macro does not take any
442 arguments.
444 The @samp{AC_EXEEXT} form is new, and is part of a Cygnus patch to
445 autoconf to support compiling with Visual C++.  Older programs use
446 @samp{AM_EXEEXT} instead.
448 (Programs which do not use automake use neither @samp{AC_EXEEXT} nor
449 @samp{AM_EXEEXT}).
451 @item AC_PROG_CC
452 @cindex @samp{AC_PROG_CC}
453 If you are writing C code, you will normally want to use this macro.  It
454 locates the C compiler to use.  It does not take any arguments.
456 However, if this @file{configure.in} file is for a library which is to
457 be compiled by a cross compiler which may not fully work, then you will
458 not want to use @samp{AC_PROG_CC}.  Instead, you will want to use a
459 variant which does not call the macro @samp{AC_PROG_CC_WORKS}.  Examples
460 can be found in various @file{configure.in} files for libraries that are
461 compiled with cross compilers, such as libiberty or libgloss.  This is
462 essentially a bug in autoconf, and there will probably be a better
463 workaround at some point.
465 @item AC_PROG_CXX
466 @cindex @samp{AC_PROG_CXX}
467 If you are writing C++ code, you will want to use this macro.  It
468 locates the C++ compiler to use.  It does not take any arguments.  The
469 same cross compiler comments apply as for @samp{AC_PROG_CC}.
471 @item AM_PROG_LIBTOOL
472 @cindex @samp{AM_PROG_LIBTOOL}
473 If you want to build libraries, and you want to permit them to be
474 shared, or you want to link against libraries which were built using
475 libtool, then you will need this macro.  This macro is required in order
476 to use libtool.
478 @cindex @samp{AM_DISABLE_SHARED}
479 By default, this will cause all libraries to be built as shared
480 libraries.  To prevent this--to change the default--use
481 @samp{AM_DISABLE_SHARED} before @samp{AM_PROG_LIBTOOL}.  The configure
482 options @samp{--enable-shared} and @samp{--disable-shared} may be used
483 to override the default at build time.
485 @item AC_DEFINE(_GNU_SOURCE)
486 @cindex @samp{_GNU_SOURCE}
487 GNU packages should normally include this line before any other feature
488 tests.  This defines the macro @samp{_GNU_SOURCE} when compiling, which
489 directs the libc header files to provide the standard GNU system
490 interfaces including all GNU extensions.  If this macro is not defined,
491 certain GNU extensions may not be available.
493 @item AC_OUTPUT
494 @cindex @samp{AC_OUTPUT}
495 This macro takes a list of file names which the configure process should
496 produce.  This is normally a list of one or more @file{Makefile} files
497 in different directories.  If your package lives entirely in a single
498 directory, you would use simply @samp{AC_OUTPUT(Makefile)}.  If you also
499 have, for example, a @file{lib} subdirectory, you would use
500 @samp{AC_OUTPUT(Makefile lib/Makefile)}.
501 @end table
503 If you want to use locally defined macros in your @file{configure.in}
504 file, then you will need to write a @file{acinclude.m4} file which
505 defines them (if not using automake, this file is called
506 @file{aclocal.m4}).  Alternatively, you can put separate macros in an
507 @file{m4} subdirectory, and put @samp{ACLOCAL_AMFLAGS = -I m4} in your
508 @file{Makefile.am} file so that the @samp{aclocal} program will be able
509 to find them.
511 The different macro prefixes indicate which tool defines the macro.
512 Macros which start with @samp{AC_} are part of autoconf.  Macros which
513 start with @samp{AM_} are provided by automake or libtool.
515 @node Write Makefile.am
516 @section Write Makefile.am
517 @cindex @file{Makefile.am}, writing
519 You must write the file @file{Makefile.am}.  This is an automake input
520 file, and the automake manual describes in detail what this file should
521 look like.
523 The automake commands in @file{Makefile.am} mostly look like variable
524 assignments in a @file{Makefile}.  automake recognizes special variable
525 names, and automatically add make rules to the output as needed.
527 There will be one @file{Makefile.am} file for each directory in your
528 package.  For each directory with subdirectories, the @file{Makefile.am}
529 file should contain the line
530 @smallexample
531 SUBDIRS = @var{dir} @var{dir} @dots{}
532 @end smallexample
533 @noindent
534 where each @var{dir} is the name of a subdirectory.
536 For each @file{Makefile.am}, there should be a corresponding
537 @file{Makefile} in the @samp{AC_OUTPUT} macro in @file{configure.in}.
539 Every @file{Makefile.am} written at Cygnus should contain the line
540 @smallexample
541 AUTOMAKE_OPTIONS = cygnus
542 @end smallexample
543 @noindent
544 This puts automake into Cygnus mode.  See the automake manual for
545 details.
547 You may to include the version number of @samp{automake} that you are
548 using on the @samp{AUTOMAKE_OPTIONS} line.  For example,
549 @smallexample
550 AUTOMAKE_OPTIONS = cygnus 1.3
551 @end smallexample
552 @noindent
553 This will prevent users from running an earlier version of
554 @samp{automake} and perhaps getting an invalid @file{Makefile.in}.
556 If your package builds a program, then in the directory where that
557 program is built you will normally want a line like
558 @smallexample
559 bin_PROGRAMS = @var{program}
560 @end smallexample
561 @noindent
562 where @var{program} is the name of the program.  You will then want a
563 line like
564 @smallexample
565 @var{program}_SOURCES = @var{file} @var{file} @dots{}
566 @end smallexample
567 @noindent
568 where each @var{file} is the name of a source file to link into the
569 program (e.g., @samp{foo.c}).
571 If your package builds a library, and you do not want the library to
572 ever be built as a shared library, then in the directory where that
573 library is built you will normally want a line like
574 @smallexample
575 lib_LIBRARIES = lib@var{name}.a
576 @end smallexample
577 @noindent
578 where @samp{lib@var{name}.a} is the name of the library.  You will then
579 want a line like
580 @smallexample
581 lib@var{name}_a_SOURCES = @var{file} @var{file} @dots{}
582 @end smallexample
583 @noindent
584 where each @var{file} is the name of a source file to add to the
585 library.
587 If your package builds a library, and you want to permit building the
588 library as a shared library, then in the directory where that library is
589 built you will normally want a line like
590 @smallexample
591 lib_LTLIBRARIES = lib@var{name}.la
592 @end smallexample
593 The use of @samp{LTLIBRARIES}, and the @samp{.la} extension, indicate a
594 library to be built using libtool.  As usual, you will then want a line
595 like
596 @smallexample
597 lib@var{name}_la_SOURCES = @var{file} @var{file} @dots{}
598 @end smallexample
600 The strings @samp{bin} and @samp{lib} that appear above in
601 @samp{bin_PROGRAMS} and @samp{lib_LIBRARIES} are not arbitrary.  They
602 refer to particular directories, which may be set by the @samp{--bindir}
603 and @samp{--libdir} options to @file{configure}.  If those options are
604 not used, the default values are based on the @samp{--prefix} or
605 @samp{--exec-prefix} options to @file{configure}.  It is possible to use
606 other names if the program or library should be installed in some other
607 directory.
609 The @file{Makefile.am} file may also contain almost anything that may
610 appear in a normal @file{Makefile}.  automake also supports many other
611 special variables, as well as conditionals.
613 See the automake manual for more information.
615 @node Write acconfig.h
616 @section Write acconfig.h
617 @cindex @file{acconfig.h}, writing
619 If you are generating a portability header file, (i.e., you are using
620 @samp{AM_CONFIG_HEADER} in @file{configure.in}), then you will have to
621 write a @file{acconfig.h} file.  It will have to contain the following
622 lines.
624 @smallexample
625 /* Name of package.  */
626 #undef PACKAGE
628 /* Version of package.  */
629 #undef VERSION
630 @end smallexample
632 This requirement is really a bug in the system, and the requirement may
633 be eliminated at some later date.
635 The @file{acconfig.h} file will also similar comment and @samp{#undef}
636 lines for any unusual macros in the @file{configure.in} file, including
637 any macro which appears in a @samp{AC_DEFINE} macro.
639 In particular, if you are writing a GNU package and therefore include
640 @samp{AC_DEFINE(_GNU_SOURCE)} in @file{configure.in} as suggested above,
641 you will need lines like this in @file{acconfig.h}:
642 @smallexample
643 /* Enable GNU extensions.  */
644 #undef _GNU_SOURCE
645 @end smallexample
647 Normally the @samp{autoheader} program will inform you of any such
648 requirements by printing an error message when it is run.  However, if
649 you do anything particular odd in your @file{configure.in} file, you
650 will have to make sure that the right entries appear in
651 @file{acconfig.h}, since otherwise the results of the tests may not be
652 available in the @file{config.h} file which your code will use.
654 (Thee @samp{PACKAGE} and @samp{VERSION} lines are not required if you
655 are not using automake, and in that case you may not need a
656 @file{acconfig.h} file at all).
658 @node Generate files
659 @section Generate files
661 Once you have written @file{configure.in}, @file{Makefile.am},
662 @file{acconfig.h}, and possibly @file{acinclude.m4}, you must use
663 autoconf and automake programs to produce the first versions of the
664 generated files.  This is done by executing the following sequence of
665 commands.
667 @smallexample
668 aclocal
669 autoconf
670 autoheader
671 automake
672 @end smallexample
674 The @samp{aclocal} and @samp{automake} commands are part of the automake
675 package, and the @samp{autoconf} and @samp{autoheader} commands are part
676 of the autoconf package.
678 If you are using a @file{m4} subdirectory for your macros, you will need
679 to use the @samp{-I m4} option when you run @samp{aclocal}.
681 If you are not using the Cygnus tree, use the @samp{-a} option when
682 running @samp{automake} command in order to copy the required support
683 files into your source directory.
685 If you are using libtool, you must build and install the libtool package
686 with the same @samp{--prefix} and @samp{--exec-prefix} options as you
687 used with the autoconf and automake packages.  You must do this before
688 running any of the above commands.  If you are not using the Cygnus
689 tree, you will need to run the @samp{libtoolize} program to copy the
690 libtool support files into your directory.
692 Once you have managed to run these commands without getting any errors,
693 you should create a new empty directory, and run the @samp{configure}
694 script which will have been created by @samp{autoconf} with the
695 @samp{--enable-maintainer-mode} option.  This will give you a set of
696 Makefiles which will include rules to automatically rebuild all the
697 generated files.
699 After doing that, whenever you have changed some of the input files and
700 want to regenerated the other files, go to your object directory and run
701 @samp{make}.  Doing this is more reliable than trying to rebuild the
702 files manually, because there are complex order dependencies and it is
703 easy to forget something.
705 @node Getting Started Example
706 @section Example
708 Let's consider a trivial example.
710 Suppose we want to write a simple version of @samp{touch}.  Our program,
711 which we will call @samp{poke}, will take a single file name argument,
712 and use the @samp{utime} system call to set the modification and access
713 times of the file to the current time.  We want this program to be
714 highly portable.
716 We'll first see what this looks like without using autoconf and
717 automake, and then see what it looks like with them.
719 @menu
720 * Getting Started Example 1::           First Try.
721 * Getting Started Example 2::           Second Try.
722 * Getting Started Example 3::           Third Try.
723 * Generate Files in Example::           Generate Files.
724 @end menu
726 @node Getting Started Example 1
727 @subsection First Try
729 Here is our first try at @samp{poke.c}.  Note that we've written it
730 without ANSI/ISO C prototypes, since we want it to be highly portable.
732 @example
733 #include <stdio.h>
734 #include <stdlib.h>
735 #include <sys/types.h>
736 #include <utime.h>
739 main (argc, argv)
740      int argc;
741      char **argv;
743   if (argc != 2)
744     @{
745       fprintf (stderr, "Usage: poke file\n");
746       exit (1);
747     @}
749   if (utime (argv[1], NULL) < 0)
750     @{
751       perror ("utime");
752       exit (1);
753     @}
755   exit (0);
757 @end example
759 We also write a simple @file{Makefile}.
761 @example
762 CC = gcc
763 CFLAGS = -g -O2
765 all: poke
767 poke: poke.o
768         $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o
769 @end example
771 So far, so good.
773 Unfortunately, there are a few problems.
775 On older Unix systems derived from BSD 4.3, the @samp{utime} system call
776 does not accept a second argument of @samp{NULL}.  On those systems, we
777 need to pass a pointer to @samp{struct utimbuf} structure.
778 Unfortunately, even older systems don't define that structure; on those
779 systems, we need to pass an array of two @samp{long} values.
781 The header file @file{stdlib.h} was invented by ANSI C, and older
782 systems don't have a copy.  We included it above to get a declaration of
783 @samp{exit}.
785 We can find some of these portability problems by running
786 @samp{autoscan}, which will create a @file{configure.scan} file which we
787 can use as a prototype for our @file{configure.in} file.  I won't show
788 the output, but it will notice the potential problems with @samp{utime}
789 and @file{stdlib.h}.
791 In our @file{Makefile}, we don't provide any way to install the program.
792 This doesn't matter much for such a simple example, but a real program
793 will need an @samp{install} target.  For that matter, we will also want
794 a @samp{clean} target.
796 @node Getting Started Example 2
797 @subsection Second Try
799 Here is our second try at this program.
801 We modify @file{poke.c} to use preprocessor macros to control what
802 features are available.  (I've cheated a bit by using the same macro
803 names which autoconf will use).
805 @example
806 #include <stdio.h>
808 #ifdef STDC_HEADERS
809 #include <stdlib.h>
810 #endif
812 #include <sys/types.h>
814 #ifdef HAVE_UTIME_H
815 #include <utime.h>
816 #endif
818 #ifndef HAVE_UTIME_NULL
820 #include <time.h>
822 #ifndef HAVE_STRUCT_UTIMBUF
824 struct utimbuf
826   long actime;
827   long modtime;
830 #endif
832 static int
833 utime_now (file)
834      char *file;
836   struct utimbuf now;
838   now.actime = now.modtime = time (NULL);
839   return utime (file, &now);
842 #define utime(f, p) utime_now (f)
844 #endif /* HAVE_UTIME_NULL  */
847 main (argc, argv)
848      int argc;
849      char **argv;
851   if (argc != 2)
852     @{
853       fprintf (stderr, "Usage: poke file\n");
854       exit (1);
855     @}
857   if (utime (argv[1], NULL) < 0)
858     @{
859       perror ("utime");
860       exit (1);
861     @}
863   exit (0);
865 @end example
867 Here is the associated @file{Makefile}.  We've added support for the
868 preprocessor flags we use.  We've also added @samp{install} and
869 @samp{clean} targets.
871 @example
872 # Set this to your installation directory.
873 bindir = /usr/local/bin
875 # Uncomment this if you have the standard ANSI/ISO C header files.
876 # STDC_HDRS = -DSTDC_HEADERS
878 # Uncomment this if you have utime.h.
879 # UTIME_H = -DHAVE_UTIME_H
881 # Uncomment this if utime (FILE, NULL) works on your system.
882 # UTIME_NULL = -DHAVE_UTIME_NULL
884 # Uncomment this if struct utimbuf is defined in utime.h.
885 # UTIMBUF = -DHAVE_STRUCT_UTIMBUF
887 CC = gcc
888 CFLAGS = -g -O2
890 ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS)
892 all: poke
894 poke: poke.o
895         $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o
897 .c.o:
898         $(CC) -c $(ALL_CFLAGS) poke.c
900 install: poke
901         cp poke $(bindir)/poke
903 clean:
904         rm poke poke.o
905 @end example
907 Some problems with this approach should be clear.
909 Users who want to compile poke will have to know how @samp{utime} works
910 on their systems, so that they can uncomment the @file{Makefile}
911 correctly.
913 The installation is done using @samp{cp}, but many systems have an
914 @samp{install} program which may be used, and which supports optional
915 features such as stripping debugging information out of the installed
916 binary.
918 The use of @file{Makefile} variables like @samp{CC}, @samp{CFLAGS} and
919 @samp{LDFLAGS} follows the requirements of the GNU standards.  This is
920 convenient for all packages, since it reduces surprises for users.
921 However, it is easy to get the details wrong, and wind up with a
922 slightly nonstandard distribution.
924 @node Getting Started Example 3
925 @subsection Third Try
927 For our third try at this program, we will write a @file{configure.in}
928 script to discover the configuration features on the host system, rather
929 than requiring the user to edit the @file{Makefile}.  We will also write
930 a @file{Makefile.am} rather than a @file{Makefile}.
932 The only change to @file{poke.c} is to add a line at the start of the
933 file:
934 @smallexample
935 #include "config.h"
936 @end smallexample
938 The new @file{configure.in} file is as follows.
940 @example
941 AC_INIT(poke.c)
942 AM_INIT_AUTOMAKE(poke, 1.0)
943 AM_CONFIG_HEADER(config.h:config.in)
944 AC_PROG_CC
945 AC_HEADER_STDC
946 AC_CHECK_HEADERS(utime.h)
947 AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF))
948 AC_FUNC_UTIME_NULL
949 AC_OUTPUT(Makefile)
950 @end example
952 The first four macros in this file, and the last one, were described
953 above; see @ref{Write configure.in}.  If we omit these macros, then when
954 we run @samp{automake} we will get a reminder that we need them.
956 The other macros are standard autoconf macros.
958 @table @samp
959 @item AC_HEADER_STDC
960 Check for standard C headers.
961 @item AC_CHECK_HEADERS
962 Check whether a particular header file exists.
963 @item AC_EGREP_HEADER
964 Check for a particular string in a particular header file, in this case
965 checking for @samp{utimbuf} in @file{utime.h}.
966 @item AC_FUNC_UTIME_NULL
967 Check whether @samp{utime} accepts a NULL second argument to set the
968 file change time to the current time.
969 @end table
971 See the autoconf manual for a more complete description.
973 The new @file{Makefile.am} file is as follows.  Note how simple this is
974 compared to our earlier @file{Makefile}.
976 @example
977 bin_PROGRAMS = poke
979 poke_SOURCES = poke.c
980 @end example
982 This means that we should build a single program name @samp{poke}.  It
983 should be installed in the binary directory, which we called
984 @samp{bindir} earlier.  The program @samp{poke} is built from the source
985 file @file{poke.c}.
987 We must also write a @file{acconfig.h} file.  Besides @samp{PACKAGE} and
988 @samp{VERSION}, which must be mentioned for all packages which use
989 automake, we must include @samp{HAVE_STRUCT_UTIMBUF}, since we mentioned
990 it in an @samp{AC_DEFINE}.
992 @example
993 /* Name of package.  */
994 #undef PACKAGE
996 /* Version of package.  */
997 #undef VERSION
999 /* Whether utime.h defines struct utimbuf.  */
1000 #undef HAVE_STRUCT_UTIMBUF
1001 @end example
1003 @node Generate Files in Example
1004 @subsection Generate Files
1006 We must now generate the other files, using the following commands.
1008 @smallexample
1009 aclocal
1010 autoconf
1011 autoheader
1012 automake
1013 @end smallexample
1015 When we run @samp{autoheader}, it will remind us of any macros we forgot
1016 to add to @file{acconfig.h}.
1018 When we run @samp{automake}, it will want to add some files to our
1019 distribution.  It will add them automatically if we use the
1020 @samp{--add-missing} option.
1022 By default, @samp{automake} will run in GNU mode, which means that it
1023 will want us to create certain additional files; as of this writing, it
1024 will want @file{NEWS}, @file{README}, @file{AUTHORS}, and
1025 @file{ChangeLog}, all of which are files which should appear in a
1026 standard GNU distribution.  We can either add those files, or run
1027 @samp{automake} with the @samp{--foreign} option.
1029 Running these tools will generate the following files, all of which are
1030 described in the next chapter.
1032 @itemize @bullet
1033 @item
1034 @file{aclocal.m4}
1035 @item
1036 @file{configure}
1037 @item
1038 @file{config.in}
1039 @item
1040 @file{Makefile.in}
1041 @item
1042 @file{stamp-h.in}
1043 @end itemize
1045 @node Files
1046 @chapter Files
1048 As was seen in the previous chapter, the GNU configure and build system
1049 uses a number of different files.  The developer must write a few files.
1050 The others are generated by various tools.
1052 The system is rather flexible, and can be used in many different ways.
1053 In describing the files that it uses, I will describe the common case,
1054 and mention some other cases that may arise.
1056 @menu
1057 * Developer Files::             Developer Files.
1058 * Build Files::                 Build Files.
1059 * Support Files::               Support Files.
1060 @end menu
1062 @node Developer Files
1063 @section Developer Files
1065 This section describes the files written or generated by the developer
1066 of a package.
1068 @menu
1069 * Developer Files Picture::     Developer Files Picture.
1070 * Written Developer Files::     Written Developer Files.
1071 * Generated Developer Files::   Generated Developer Files.
1072 @end menu
1074 @node Developer Files Picture
1075 @subsection Developer Files Picture
1077 Here is a picture of the files which are written by the developer, the
1078 generated files which would be included with a complete source
1079 distribution, and the tools which create those files.
1080 @ifinfo
1081 The file names are plain text and the tool names are enclosed by
1082 @samp{*} characters
1083 @end ifinfo
1084 @ifnotinfo
1085 The file names are in rectangles with square corners and the tool names
1086 are in rectangles with rounded corners
1087 @end ifnotinfo
1088 (e.g., @samp{autoheader} is the name of a tool, not the name of a file).
1090 @image{configdev,,,,jpg}
1092 @node Written Developer Files
1093 @subsection Written Developer Files
1095 The following files would be written by the developer.
1097 @table @file
1098 @item configure.in
1099 @cindex @file{configure.in}
1100 This is the configuration script.  This script contains invocations of
1101 autoconf macros.  It may also contain ordinary shell script code.  This
1102 file will contain feature tests for portability issues.  The last thing
1103 in the file will normally be an @samp{AC_OUTPUT} macro listing which
1104 files to create when the builder runs the configure script.  This file
1105 is always required when using the GNU configure system.  @xref{Write
1106 configure.in}.
1108 @item Makefile.am
1109 @cindex @file{Makefile.am}
1110 This is the automake input file.  It describes how the code should be
1111 built.  It consists of definitions of automake variables.  It may also
1112 contain ordinary Makefile targets.  This file is only needed when using
1113 automake (newer tools normally use automake, but there are still older
1114 tools which have not been converted, in which the developer writes
1115 @file{Makefile.in} directly).  @xref{Write Makefile.am}.
1117 @item acconfig.h
1118 @cindex @file{acconfig.h}
1119 When the configure script creates a portability header file, by using
1120 @samp{AM_CONFIG_HEADER} (or, if not using automake,
1121 @samp{AC_CONFIG_HEADER}), this file is used to describe macros which are
1122 not recognized by the @samp{autoheader} command.  This is normally a
1123 fairly uninteresting file, consisting of a collection of @samp{#undef}
1124 lines with comments.  Normally any call to @samp{AC_DEFINE} in
1125 @file{configure.in} will require a line in this file. @xref{Write
1126 acconfig.h}.
1128 @item acinclude.m4
1129 @cindex @file{acinclude.m4}
1130 This file is not always required.  It defines local autoconf macros.
1131 These macros may then be used in @file{configure.in}.  If you don't need
1132 any local autoconf macros, then you don't need this file at all.  In
1133 fact, in general, you never need local autoconf macros, since you can
1134 put everything in @file{configure.in}, but sometimes a local macro is
1135 convenient.
1137 Newer tools may omit @file{acinclude.m4}, and instead use a
1138 subdirectory, typically named @file{m4}, and define
1139 @samp{ACLOCAL_AMFLAGS = -I m4} in @file{Makefile.am} to force
1140 @samp{aclocal} to look there for macro definitions.  The macro
1141 definitions are then placed in separate files in that directory.
1143 The @file{acinclude.m4} file is only used when using automake; in older
1144 tools, the developer writes @file{aclocal.m4} directly, if it is needed.
1145 @end table
1147 @node Generated Developer Files
1148 @subsection Generated Developer Files
1150 The following files would be generated by the developer.
1152 When using automake, these files are normally not generated manually
1153 after the first time.  Instead, the generated @file{Makefile} contains
1154 rules to automatically rebuild the files as required.  When
1155 @samp{AM_MAINTAINER_MODE} is used in @file{configure.in} (the normal
1156 case in Cygnus code), the automatic rebuilding rules will only be
1157 defined if you configure using the @samp{--enable-maintainer-mode}
1158 option.
1160 When using automatic rebuilding, it is important to ensure that all the
1161 various tools have been built and installed on your @samp{PATH}.  Using
1162 automatic rebuilding is highly recommended, so much so that I'm not
1163 going to explain what you have to do if you don't use it.
1165 @table @file
1166 @item configure
1167 @cindex @file{configure}
1168 This is the configure script which will be run when building the
1169 package.  This is generated by @samp{autoconf} from @file{configure.in}
1170 and @file{aclocal.m4}.  This is a shell script.
1172 @item Makefile.in
1173 @cindex @file{Makefile.in}
1174 This is the file which the configure script will turn into the
1175 @file{Makefile} at build time.  This file is generated by
1176 @samp{automake} from @file{Makefile.am}.  If you aren't using automake,
1177 you must write this file yourself.  This file is pretty much a normal
1178 @file{Makefile}, with some configure substitutions for certain
1179 variables.
1181 @item aclocal.m4
1182 @cindex @file{aclocal.m4}
1183 This file is created by the @samp{aclocal} program, based on the
1184 contents of @file{configure.in} and @file{acinclude.m4} (or, as noted in
1185 the description of @file{acinclude.m4} above, on the contents of an
1186 @file{m4} subdirectory).  This file contains definitions of autoconf
1187 macros which @samp{autoconf} will use when generating the file
1188 @file{configure}.  These autoconf macros may be defined by you in
1189 @file{acinclude.m4} or they may be defined by other packages such as
1190 automake, libtool or gettext.  If you aren't using automake, you will
1191 normally write this file yourself; in that case, if @file{configure.in}
1192 uses only standard autoconf macros, this file will not be needed at all.
1194 @item config.in
1195 @cindex @file{config.in}
1196 @cindex @file{config.h.in}
1197 This file is created by @samp{autoheader} based on @file{acconfig.h} and
1198 @file{configure.in}.  At build time, the configure script will define
1199 some of the macros in it to create @file{config.h}, which may then be
1200 included by your program.  This permits your C code to use preprocessor
1201 conditionals to change its behaviour based on the characteristics of the
1202 host system.  This file may also be called @file{config.h.in}.
1204 @item stamp.h-in
1205 @cindex @file{stamp-h.in}
1206 This rather uninteresting file, which I omitted from the picture, is
1207 generated by @samp{automake}.  It always contains the string
1208 @samp{timestamp}.  It is used as a timestamp file indicating whether
1209 @file{config.in} is up to date.  Using a timestamp file means that
1210 @file{config.in} can be marked as up to date without actually changing
1211 its modification time.  This is useful since @file{config.in} depends
1212 upon @file{configure.in}, but it is easy to change @file{configure.in}
1213 in a way which does not affect @file{config.in}.
1214 @end table
1216 @node Build Files
1217 @section Build Files
1219 This section describes the files which are created at configure and
1220 build time.  These are the files which somebody who builds the package
1221 will see.
1223 Of course, the developer will also build the package.  The distinction
1224 between developer files and build files is not that the developer does
1225 not see the build files, but that somebody who only builds the package
1226 does not have to worry about the developer files.
1228 @menu
1229 * Build Files Picture::         Build Files Picture.
1230 * Build Files Description::     Build Files Description.
1231 @end menu
1233 @node Build Files Picture
1234 @subsection Build Files Picture
1236 Here is a picture of the files which will be created at build time.
1237 @file{config.status} is both a created file and a shell script which is
1238 run to create other files, and the picture attempts to show that.
1240 @image{configbuild,,,,jpg}
1242 @node Build Files Description
1243 @subsection Build Files Description
1245 This is a description of the files which are created at build time.
1247 @table @file
1248 @item config.status
1249 @cindex @file{config.status}
1250 The first step in building a package is to run the @file{configure}
1251 script.  The @file{configure} script will create the file
1252 @file{config.status}, which is itself a shell script.  When you first
1253 run @file{configure}, it will automatically run @file{config.status}.
1254 An @file{Makefile} derived from an automake generated @file{Makefile.in}
1255 will contain rules to automatically run @file{config.status} again when
1256 necessary to recreate certain files if their inputs change.
1258 @item Makefile
1259 @cindex @file{Makefile}
1260 This is the file which make will read to build the program.  The
1261 @file{config.status} script will transform @file{Makefile.in} into
1262 @file{Makefile}.
1264 @item config.h
1265 @cindex @file{config.h}
1266 This file defines C preprocessor macros which C code can use to adjust
1267 its behaviour on different systems.  The @file{config.status} script
1268 will transform @file{config.in} into @file{config.h}.
1270 @item config.cache
1271 @cindex @file{config.cache}
1272 This file did not fit neatly into the picture, and I omitted it.  It is
1273 used by the @file{configure} script to cache results between runs.  This
1274 can be an important speedup.  If you modify @file{configure.in} in such
1275 a way that the results of old tests should change (perhaps you have
1276 added a new library to @samp{LDFLAGS}), then you will have to remove
1277 @file{config.cache} to force the tests to be rerun.
1279 The autoconf manual explains how to set up a site specific cache file.
1280 This can speed up running @file{configure} scripts on your system.
1282 @item stamp.h
1283 @cindex @file{stamp-h}
1284 This file, which I omitted from the picture, is similar to
1285 @file{stamp-h.in}.  It is used as a timestamp file indicating whether
1286 @file{config.h} is up to date.  This is useful since @file{config.h}
1287 depends upon @file{config.status}, but it is easy for
1288 @file{config.status} to change in a way which does not affect
1289 @file{config.h}.
1290 @end table
1292 @node Support Files
1293 @section Support Files
1295 The GNU configure and build system requires several support files to be
1296 included with your distribution.  You do not normally need to concern
1297 yourself with these.  If you are using the Cygnus tree, most are already
1298 present.  Otherwise, they will be installed with your source by
1299 @samp{automake} (with the @samp{--add-missing} option) and
1300 @samp{libtoolize}.
1302 You don't have to put the support files in the top level directory.  You
1303 can put them in a subdirectory, and use the @samp{AC_CONFIG_AUX_DIR}
1304 macro in @file{configure.in} to tell @samp{automake} and the
1305 @file{configure} script where they are.
1307 In this section, I describe the support files, so that you can know what
1308 they are and why they are there.
1310 @table @file
1311 @item ABOUT-NLS
1312 Added by automake if you are using gettext.  This is a documentation
1313 file about the gettext project.
1314 @item ansi2knr.c
1315 Used by an automake generated @file{Makefile} if you put @samp{ansi2knr}
1316 in @samp{AUTOMAKE_OPTIONS} in @file{Makefile.am}.  This permits
1317 compiling ANSI C code with a K&R C compiler.
1318 @item ansi2knr.1
1319 The man page which goes with @file{ansi2knr.c}.
1320 @item config.guess
1321 A shell script which determines the configuration name for the system on
1322 which it is run.
1323 @item config.sub
1324 A shell script which canonicalizes a configuration name entered by a
1325 user.
1326 @item elisp-comp
1327 Used to compile Emacs LISP files.
1328 @item install-sh
1329 A shell script which installs a program.  This is used if the configure
1330 script can not find an install binary.
1331 @item ltconfig
1332 Used by libtool.  This is a shell script which configures libtool for
1333 the particular system on which it is used.
1334 @item ltmain.sh
1335 Used by libtool.  This is the actual libtool script which is used, after
1336 it is configured by @file{ltconfig} to build a library.
1337 @item mdate-sh
1338 A shell script used by an automake generated @file{Makefile} to pretty
1339 print the modification time of a file.  This is used to maintain version
1340 numbers for texinfo files.
1341 @item missing
1342 A shell script used if some tool is missing entirely.  This is used by
1343 an automake generated @file{Makefile} to avoid certain sorts of
1344 timestamp problems.
1345 @item mkinstalldirs
1346 A shell script which creates a directory, including all parent
1347 directories.  This is used by an automake generated @file{Makefile}
1348 during installation.
1349 @item texinfo.tex
1350 Required if you have any texinfo files.  This is used when converting
1351 Texinfo files into DVI using @samp{texi2dvi} and @TeX{}.
1352 @item ylwrap
1353 A shell script used by an automake generated @file{Makefile} to run
1354 programs like @samp{bison}, @samp{yacc}, @samp{flex}, and @samp{lex}.
1355 These programs default to producing output files with a fixed name, and
1356 the @file{ylwrap} script runs them in a subdirectory to avoid file name
1357 conflicts when using a parallel make program.
1358 @end table
1360 @node Configuration Names
1361 @chapter Configuration Names
1362 @cindex configuration names
1363 @cindex configuration triplets
1364 @cindex triplets
1365 @cindex host names
1366 @cindex host triplets
1367 @cindex canonical system names
1368 @cindex system names
1369 @cindex system types
1371 The GNU configure system names all systems using a @dfn{configuration
1372 name}.  All such names used to be triplets (they may now contain four
1373 parts in certain cases), and the term @dfn{configuration triplet} is
1374 still seen.
1376 @menu
1377 * Configuration Name Definition::       Configuration Name Definition.
1378 * Using Configuration Names::           Using Configuration Names.
1379 @end menu
1381 @node Configuration Name Definition
1382 @section Configuration Name Definition
1384 This is a string of the form
1385 @var{cpu}-@var{manufacturer}-@var{operating_system}.  In some cases,
1386 this is extended to a four part form:
1387 @var{cpu}-@var{manufacturer}-@var{kernel}-@var{operating_system}.
1389 When using a configuration name in a configure option, it is normally
1390 not necessary to specify an entire name.  In particular, the
1391 @var{manufacturer} field is often omitted, leading to strings such as
1392 @samp{i386-linux} or @samp{sparc-sunos}.  The shell script
1393 @file{config.sub} will translate these shortened strings into the
1394 canonical form.  autoconf will arrange for @file{config.sub} to be run
1395 automatically when it is needed.
1397 The fields of a configuration name are as follows:
1399 @table @var
1400 @item cpu
1401 The type of processor.  This is typically something like @samp{i386} or
1402 @samp{sparc}.  More specific variants are used as well, such as
1403 @samp{mipsel} to indicate a little endian MIPS processor.
1404 @item manufacturer
1405 A somewhat freeform field which indicates the manufacturer of the
1406 system.  This is often simply @samp{unknown}.  Other common strings are
1407 @samp{pc} for an IBM PC compatible system, or the name of a workstation
1408 vendor, such as @samp{sun}.
1409 @item operating_system
1410 The name of the operating system which is run on the system.  This will
1411 be something like @samp{solaris2.5} or @samp{irix6.3}.  There is no
1412 particular restriction on the version number, and strings like
1413 @samp{aix4.1.4.0} are seen.  For an embedded system, which has no
1414 operating system, this field normally indicates the type of object file
1415 format, such as @samp{elf} or @samp{coff}.
1416 @item kernel
1417 This is used mainly for GNU/Linux.  A typical GNU/Linux configuration
1418 name is @samp{i586-pc-linux-gnulibc1}.  In this case the kernel,
1419 @samp{linux}, is separated from the operating system, @samp{gnulibc1}.
1420 @end table
1422 The shell script @file{config.guess} will normally print the correct
1423 configuration name for the system on which it is run.  It does by
1424 running @samp{uname} and by examining other characteristics of the
1425 system.
1427 Because @file{config.guess} can normally determine the configuration
1428 name for a machine, it is normally only necessary to specify a
1429 configuration name when building a cross-compiler or when building using
1430 a cross-compiler.
1432 @node Using Configuration Names
1433 @section Using Configuration Names
1435 A configure script will sometimes have to make a decision based on a
1436 configuration name.  You will need to do this if you have to compile
1437 code differently based on something which can not be tested using a
1438 standard autoconf feature test.
1440 It is normally better to test for particular features, rather than to
1441 test for a particular system.  This is because as Unix evolves,
1442 different systems copy features from one another.  Even if you need to
1443 determine whether the feature is supported based on a configuration
1444 name, you should define a macro which describes the feature, rather than
1445 defining a macro which describes the particular system you are on.
1447 Testing for a particular system is normally done using a case statement
1448 in @file{configure.in}.  The case statement might look something like
1449 the following, assuming that @samp{host} is a shell variable holding a
1450 canonical configuration name (which will be the case if
1451 @file{configure.in} uses the @samp{AC_CANONICAL_HOST} or
1452 @samp{AC_CANONICAL_SYSTEM} macro).
1454 @smallexample
1455 case "$@{host@}" in
1456 i[3-7]86-*-linux-gnu*) do something ;;
1457 sparc*-sun-solaris2.[56789]*) do something ;;
1458 sparc*-sun-solaris*) do something ;;
1459 mips*-*-elf*) do something ;;
1460 esac
1461 @end smallexample
1463 It is particularly important to use @samp{*} after the operating system
1464 field, in order to match the version number which will be generated by
1465 @file{config.guess}.
1467 In most cases you must be careful to match a range of processor types.
1468 For most processor families, a trailing @samp{*} suffices, as in
1469 @samp{mips*} above.  For the i386 family, something along the lines of
1470 @samp{i[3-7]86} suffices at present.  For the m68k family, you will
1471 need something like @samp{m68*}.  Of course, if you do not need to match
1472 on the processor, it is simpler to just replace the entire field by a
1473 @samp{*}, as in @samp{*-*-irix*}.
1475 @node Cross Compilation Tools
1476 @chapter Cross Compilation Tools
1477 @cindex cross tools
1479 The GNU configure and build system can be used to build @dfn{cross
1480 compilation} tools.  A cross compilation tool is a tool which runs on
1481 one system and produces code which runs on another system.
1483 @menu
1484 * Cross Compilation Concepts::          Cross Compilation Concepts.
1485 * Host and Target::                     Host and Target.
1486 * Using the Host Type::                 Using the Host Type.
1487 * Specifying the Target::               Specifying the Target.
1488 * Using the Target Type::               Using the Target Type.
1489 * Cross Tools in the Cygnus Tree::      Cross Tools in the Cygnus Tree
1490 @end menu
1492 @node Cross Compilation Concepts
1493 @section Cross Compilation Concepts
1495 @cindex cross compiler
1496 A compiler which produces programs which run on a different system is a
1497 cross compilation compiler, or simply a @dfn{cross compiler}.
1498 Similarly, we speak of cross assemblers, cross linkers, etc.
1500 In the normal case, a compiler produces code which runs on the same
1501 system as the one on which the compiler runs.  When it is necessary to
1502 distinguish this case from the cross compilation case, such a compiler
1503 is called a @dfn{native compiler}.  Similarly, we speak of native
1504 assemblers, etc.
1506 Although the debugger is not strictly speaking a compilation tool, it is
1507 nevertheless meaningful to speak of a cross debugger: a debugger which
1508 is used to debug code which runs on another system.  Everything that is
1509 said below about configuring cross compilation tools applies to the
1510 debugger as well.
1512 @node Host and Target
1513 @section Host and Target
1514 @cindex host system
1515 @cindex target system
1517 When building cross compilation tools, there are two different systems
1518 involved: the system on which the tools will run, and the system for
1519 which the tools generate code.
1521 The system on which the tools will run is called the @dfn{host} system.
1523 The system for which the tools generate code is called the @dfn{target}
1524 system.
1526 For example, suppose you have a compiler which runs on a GNU/Linux
1527 system and generates ELF programs for a MIPS embedded system.  In this
1528 case the GNU/Linux system is the host, and the MIPS ELF system is the
1529 target.  Such a compiler could be called a GNU/Linux cross MIPS ELF
1530 compiler, or, equivalently, a @samp{i386-linux-gnu} cross
1531 @samp{mips-elf} compiler.
1533 Naturally, most programs are not cross compilation tools.  For those
1534 programs, it does not make sense to speak of a target.  It only makes
1535 sense to speak of a target for tools like @samp{gcc} or the
1536 @samp{binutils} which actually produce running code.  For example, it
1537 does not make sense to speak of the target of a tool like @samp{bison}
1538 or @samp{make}.
1540 Most cross compilation tools can also serve as native tools.  For a
1541 native compilation tool, it is still meaningful to speak of a target.
1542 For a native tool, the target is the same as the host.  For example, for
1543 a GNU/Linux native compiler, the host is GNU/Linux, and the target is
1544 also GNU/Linux.
1546 @node Using the Host Type
1547 @section Using the Host Type
1549 In almost all cases the host system is the system on which you run the
1550 @samp{configure} script, and on which you build the tools (for the case
1551 when they differ, @pxref{Canadian Cross}).
1553 @cindex @samp{AC_CANONICAL_HOST}
1554 If your configure script needs to know the configuration name of the
1555 host system, and the package is not a cross compilation tool and
1556 therefore does not have a target, put @samp{AC_CANONICAL_HOST} in
1557 @file{configure.in}.  This macro will arrange to define a few shell
1558 variables when the @samp{configure} script is run.
1560 @table @samp
1561 @item host
1562 The canonical configuration name of the host.  This will normally be
1563 determined by running the @file{config.guess} shell script, although the
1564 user is permitted to override this by using an explicit @samp{--host}
1565 option.
1566 @item host_alias
1567 In the unusual case that the user used an explicit @samp{--host} option,
1568 this will be the argument to @samp{--host}.  In the normal case, this
1569 will be the same as the @samp{host} variable.
1570 @item host_cpu
1571 @itemx host_vendor
1572 @itemx host_os
1573 The first three parts of the canonical configuration name.
1574 @end table
1576 The shell variables may be used by putting shell code in
1577 @file{configure.in}.  For an example, see @ref{Using Configuration
1578 Names}.
1580 @node Specifying the Target
1581 @section Specifying the Target
1583 By default, the @samp{configure} script will assume that the target is
1584 the same as the host.  This is the more common case; for example, it
1585 leads to a native compiler rather than a cross compiler.
1587 @cindex @samp{--target} option
1588 @cindex target option
1589 @cindex configure target
1590 If you want to build a cross compilation tool, you must specify the
1591 target explicitly by using the @samp{--target} option when you run
1592 @samp{configure}.  The argument to @samp{--target} is the configuration
1593 name of the system for which you wish to generate code.
1594 @xref{Configuration Names}.
1596 For example, to build tools which generate code for a MIPS ELF embedded
1597 system, you would use @samp{--target mips-elf}.
1599 @node Using the Target Type
1600 @section Using the Target Type
1602 @cindex @samp{AC_CANONICAL_SYSTEM}
1603 When writing @file{configure.in} for a cross compilation tool, you will
1604 need to use information about the target.  To do this, put
1605 @samp{AC_CANONICAL_SYSTEM} in @file{configure.in}.
1607 @samp{AC_CANONICAL_SYSTEM} will look for a @samp{--target} option and
1608 canonicalize it using the @file{config.sub} shell script.  It will also
1609 run @samp{AC_CANONICAL_HOST} (@pxref{Using the Host Type}).
1611 The target type will be recorded in the following shell variables.  Note
1612 that the host versions of these variables will also be defined by
1613 @samp{AC_CANONICAL_HOST}.
1615 @table @samp
1616 @item target
1617 The canonical configuration name of the target.
1618 @item target_alias
1619 The argument to the @samp{--target} option.  If the user did not specify
1620 a @samp{--target} option, this will be the same as @samp{host_alias}.
1621 @item target_cpu
1622 @itemx target_vendor
1623 @itemx target_os
1624 The first three parts of the canonical target configuration name.
1625 @end table
1627 Note that if @samp{host} and @samp{target} are the same string, you can
1628 assume a native configuration.  If they are different, you can assume a
1629 cross configuration.
1631 It is arguably possible for @samp{host} and @samp{target} to represent
1632 the same system, but for the strings to not be identical.  For example,
1633 if @samp{config.guess} returns @samp{sparc-sun-sunos4.1.4}, and somebody
1634 configures with @samp{--target sparc-sun-sunos4.1}, then the slight
1635 differences between the two versions of SunOS may be unimportant for
1636 your tool.  However, in the general case it can be quite difficult to
1637 determine whether the differences between two configuration names are
1638 significant or not.  Therefore, by convention, if the user specifies a
1639 @samp{--target} option without specifying a @samp{--host} option, it is
1640 assumed that the user wants to configure a cross compilation tool.
1642 The variables @samp{target} and @samp{target_alias} should be handled
1643 differently.
1645 In general, whenever the user may actually see a string,
1646 @samp{target_alias} should be used.  This includes anything which may
1647 appear in the file system, such as a directory name or part of a tool
1648 name.  It also includes any tool output, unless it is clearly labelled
1649 as the canonical target configuration name.  This permits the user to
1650 use the @samp{--target} option to specify how the tool will appear to
1651 the outside world.
1653 On the other hand, when checking for characteristics of the target
1654 system, @samp{target} should be used.  This is because a wide variety of
1655 @samp{--target} options may map into the same canonical configuration
1656 name.  You should not attempt to duplicate the canonicalization done by
1657 @samp{config.sub} in your own code.
1659 By convention, cross tools are installed with a prefix of the argument
1660 used with the @samp{--target} option, also known as @samp{target_alias}
1661 (@pxref{Using the Target Type}).  If the user does not use the
1662 @samp{--target} option, and thus is building a native tool, no prefix is
1663 used.
1665 For example, if gcc is configured with @samp{--target mips-elf}, then
1666 the installed binary will be named @samp{mips-elf-gcc}.  If gcc is
1667 configured without a @samp{--target} option, then the installed binary
1668 will be named @samp{gcc}.
1670 The autoconf macro @samp{AC_ARG_PROGRAM} will handle this for you.  If
1671 you are using automake, no more need be done; the programs will
1672 automatically be installed with the correct prefixes.  Otherwise, see
1673 the autoconf documentation for @samp{AC_ARG_PROGRAM}.
1675 @node Cross Tools in the Cygnus Tree
1676 @section Cross Tools in the Cygnus Tree
1678 The Cygnus tree is used for various packages including gdb, the GNU
1679 binutils, and egcs.  It is also, of course, used for Cygnus releases.
1681 In the Cygnus tree, the top level @file{configure} script uses the old
1682 Cygnus configure system, not autoconf.  The top level @file{Makefile.in}
1683 is written to build packages based on what is in the source tree, and
1684 supports building a large number of tools in a single
1685 @samp{configure}/@samp{make} step.
1687 The Cygnus tree may be configured with a @samp{--target} option.  The
1688 @samp{--target} option applies recursively to every subdirectory, and
1689 permits building an entire set of cross tools at once.
1691 @menu
1692 * Host and Target Libraries::           Host and Target Libraries.
1693 * Target Library Configure Scripts::    Target Library Configure Scripts.
1694 * Make Targets in Cygnus Tree::         Make Targets in Cygnus Tree.
1695 * Target libiberty::                    Target libiberty
1696 @end menu
1698 @node Host and Target Libraries
1699 @subsection Host and Target Libraries
1701 The Cygnus tree distinguishes host libraries from target libraries.
1703 Host libraries are built with the compiler used to build the programs
1704 which run on the host, which is called the host compiler.  This includes
1705 libraries such as @samp{bfd} and @samp{tcl}.  These libraries are built
1706 with the host compiler, and are linked into programs like the binutils
1707 or gcc which run on the host.
1709 Target libraries are built with the target compiler.  If gcc is present
1710 in the source tree, then the target compiler is the gcc that is built
1711 using the host compiler.  Target libraries are libraries such as
1712 @samp{newlib} and @samp{libstdc++}.  These libraries are not linked into
1713 the host programs, but are instead made available for use with programs
1714 built with the target compiler.
1716 For the rest of this section, assume that gcc is present in the source
1717 tree, so that it will be used to build the target libraries.
1719 There is a complication here.  The configure process needs to know which
1720 compiler you are going to use to build a tool; otherwise, the feature
1721 tests will not work correctly.  The Cygnus tree handles this by not
1722 configuring the target libraries until the target compiler is built.  In
1723 order to permit everything to build using a single
1724 @samp{configure}/@samp{make}, the configuration of the target libraries
1725 is actually triggered during the make step.
1727 When the target libraries are configured, the @samp{--target} option is
1728 not used.  Instead, the @samp{--host} option is used with the argument
1729 of the @samp{--target} option for the overall configuration.  If no
1730 @samp{--target} option was used for the overall configuration, the
1731 @samp{--host} option will be passed with the output of the
1732 @file{config.guess} shell script.  Any @samp{--build} option is passed
1733 down unchanged.
1735 This translation of configuration options is done because since the
1736 target libraries are compiled with the target compiler, they are being
1737 built in order to run on the target of the overall configuration.  By
1738 the definition of host, this means that their host system is the same as
1739 the target system of the overall configuration.
1741 The same process is used for both a native configuration and a cross
1742 configuration.  Even when using a native configuration, the target
1743 libraries will be configured and built using the newly built compiler.
1744 This is particularly important for the C++ libraries, since there is no
1745 reason to assume that the C++ compiler used to build the host tools (if
1746 there even is one) uses the same ABI as the g++ compiler which will be
1747 used to build the target libraries.
1749 There is one difference between a native configuration and a cross
1750 configuration.  In a native configuration, the target libraries are
1751 normally configured and built as siblings of the host tools.  In a cross
1752 configuration, the target libraries are normally built in a subdirectory
1753 whose name is the argument to @samp{--target}.  This is mainly for
1754 historical reasons.
1756 To summarize, running @samp{configure} in the Cygnus tree configures all
1757 the host libraries and tools, but does not configure any of the target
1758 libraries.  Running @samp{make} then does the following steps:
1760 @itemize @bullet
1761 @item
1762 Build the host libraries.
1763 @item
1764 Build the host programs, including gcc.  Note that we call gcc both a
1765 host program (since it runs on the host) and a target compiler (since it
1766 generates code for the target).
1767 @item
1768 Using the newly built target compiler, configure the target libraries.
1769 @item
1770 Build the target libraries.
1771 @end itemize
1773 The steps need not be done in precisely this order, since they are
1774 actually controlled by @file{Makefile} targets.
1776 @node Target Library Configure Scripts
1777 @subsection Target Library Configure Scripts
1779 There are a few things you must know in order to write a configure
1780 script for a target library.  This is just a quick sketch, and beginners
1781 shouldn't worry if they don't follow everything here.
1783 The target libraries are configured and built using a newly built target
1784 compiler.  There may not be any startup files or libraries for this
1785 target compiler.  In fact, those files will probably be built as part of
1786 some target library, which naturally means that they will not exist when
1787 your target library is configured.
1789 This means that the configure script for a target library may not use
1790 any test which requires doing a link.  This unfortunately includes many
1791 useful autoconf macros, such as @samp{AC_CHECK_FUNCS}.  autoconf macros
1792 which do a compile but not a link, such as @samp{AC_CHECK_HEADERS}, may
1793 be used.
1795 This is a severe restriction, but normally not a fatal one, as target
1796 libraries can often assume the presence of other target libraries, and
1797 thus know which functions will be available.
1799 As of this writing, the autoconf macro @samp{AC_PROG_CC} does a link to
1800 make sure that the compiler works.  This may fail in a target library,
1801 so target libraries must use a different set of macros to locate the
1802 compiler.  See the @file{configure.in} file in a directory like
1803 @file{libiberty} or @file{libgloss} for an example.
1805 As noted in the previous section, target libraries are sometimes built
1806 in directories which are siblings to the host tools, and are sometimes
1807 built in a subdirectory.  The @samp{--with-target-subdir} configure
1808 option will be passed when the library is configured.  Its value will be
1809 an empty string if the target library is a sibling.  Its value will be
1810 the name of the subdirectory if the target library is in a subdirectory.
1812 If the overall build is not a native build (i.e., the overall configure
1813 used the @samp{--target} option), then the library will be configured
1814 with the @samp{--with-cross-host} option.  The value of this option will
1815 be the host system of the overall build.  Recall that the host system of
1816 the library will be the target of the overall build.  If the overall
1817 build is a native build, the @samp{--with-cross-host} option will not be
1818 used.
1820 A library which can be built both standalone and as a target library may
1821 want to install itself into different directories depending upon the
1822 case.  When built standalone, or when built native, the library should
1823 be installed in @samp{$(libdir)}.  When built as a target library which
1824 is not native, the library should be installed in @samp{$(tooldir)/lib}.
1825 The @samp{--with-cross-host} option may be used to distinguish these
1826 cases.
1828 This same test of @samp{--with-cross-host} may be used to see whether it
1829 is OK to use link tests in the configure script.  If the
1830 @samp{--with-cross-host} option is not used, then the library is being
1831 built either standalone or native, and a link should work.
1833 @node Make Targets in Cygnus Tree
1834 @subsection Make Targets in Cygnus Tree
1836 The top level @file{Makefile} in the Cygnus tree defines targets for
1837 every known subdirectory.
1839 For every subdirectory @var{dir} which holds a host library or program,
1840 the @file{Makefile} target @samp{all-@var{dir}} will build that library
1841 or program.
1843 There are dependencies among host tools.  For example, building gcc
1844 requires first building gas, because the gcc build process invokes the
1845 target assembler.  These dependencies are reflected in the top level
1846 @file{Makefile}.
1848 For every subdirectory @var{dir} which holds a target library, the
1849 @file{Makefile} target @samp{configure-target-@var{dir}} will configure
1850 that library.  The @file{Makefile} target @samp{all-target-@var{dir}}
1851 will build that library.
1853 Every @samp{configure-target-@var{dir}} target depends upon
1854 @samp{all-gcc}, since gcc, the target compiler, is required to configure
1855 the tool.  Every @samp{all-target-@var{dir}} target depends upon the
1856 corresponding @samp{configure-target-@var{dir}} target.
1858 There are several other targets which may be of interest for each
1859 directory: @samp{install-@var{dir}}, @samp{clean-@var{dir}}, and
1860 @samp{check-@var{dir}}.  There are also corresponding @samp{target}
1861 versions of these for the target libraries , such as
1862 @samp{install-target-@var{dir}}.
1864 @node Target libiberty
1865 @subsection Target libiberty
1867 The @file{libiberty} subdirectory is currently a special case, in that
1868 it is the only directory which is built both using the host compiler and
1869 using the target compiler.
1871 This is because the files in @file{libiberty} are used when building the
1872 host tools, and they are also incorporated into the @file{libstdc++}
1873 target library as support code.
1875 This duality does not pose any particular difficulties.  It means that
1876 there are targets for both @samp{all-libiberty} and
1877 @samp{all-target-libiberty}.
1879 In a native configuration, when target libraries are not built in a
1880 subdirectory, the same objects are normally used as both the host build
1881 and the target build.  This is normally OK, since libiberty contains
1882 only C code, and in a native configuration the results of the host
1883 compiler and the target compiler are normally interoperable.
1885 Irix 6 is again an exception here, since the SGI native compiler
1886 defaults to using the @samp{O32} ABI, and gcc defaults to using the
1887 @samp{N32} ABI.  On Irix 6, the target libraries are built in a
1888 subdirectory even for a native configuration, avoiding this problem.
1890 There are currently no other libraries built for both the host and the
1891 target, but there is no conceptual problem with adding more.
1893 @node Canadian Cross
1894 @chapter Canadian Cross
1895 @cindex canadian cross
1896 @cindex building with a cross compiler
1897 @cindex cross compiler, building with
1899 It is possible to use the GNU configure and build system to build a
1900 program which will run on a system which is different from the system on
1901 which the tools are built.  In other words, it is possible to build
1902 programs using a cross compiler.
1904 This is referred to as a @dfn{Canadian Cross}.
1906 @menu
1907 * Canadian Cross Example::              Canadian Cross Example.
1908 * Canadian Cross Concepts::             Canadian Cross Concepts.
1909 * Build Cross Host Tools::              Build Cross Host Tools.
1910 * Build and Host Options::              Build and Host Options.
1911 * CCross not in Cygnus Tree::           Canadian Cross not in Cygnus Tree.
1912 * CCross in Cygnus Tree::               Canadian Cross in Cygnus Tree.
1913 * Supporting Canadian Cross::           Supporting Canadian Cross.
1914 @end menu
1916 @node Canadian Cross Example
1917 @section Canadian Cross Example
1919 Here is an example of a Canadian Cross.
1921 While running on a GNU/Linux, you can build a program which will run on
1922 a Solaris system.  You would use a GNU/Linux cross Solaris compiler to
1923 build the program.
1925 Of course, you could not run the resulting program on your GNU/Linux
1926 system.  You would have to copy it over to a Solaris system before you
1927 would run it.
1929 Of course, you could also simply build the programs on the Solaris
1930 system in the first place.  However, perhaps the Solaris system is not
1931 available for some reason; perhaps you actually don't have one, but you
1932 want to build the tools for somebody else to use.  Or perhaps your
1933 GNU/Linux system is much faster than your Solaris system.
1935 A Canadian Cross build is most frequently used when building programs to
1936 run on a non-Unix system, such as DOS or Windows.  It may be simpler to
1937 configure and build on a Unix system than to support the configuration
1938 machinery on a non-Unix system.
1940 @node Canadian Cross Concepts
1941 @section Canadian Cross Concepts
1943 When building a Canadian Cross, there are at least two different systems
1944 involved: the system on which the tools are being built, and the system
1945 on which the tools will run.
1947 The system on which the tools are being built is called the @dfn{build}
1948 system.
1950 The system on which the tools will run is called the host system.
1952 For example, if you are building a Solaris program on a GNU/Linux
1953 system, as in the previous section, the build system would be GNU/Linux,
1954 and the host system would be Solaris.
1956 It is, of course, possible to build a cross compiler using a Canadian
1957 Cross (i.e., build a cross compiler using a cross compiler).  In this
1958 case, the system for which the resulting cross compiler generates code
1959 is called the target system.  (For a more complete discussion of host
1960 and target systems, @pxref{Host and Target}).
1962 An example of building a cross compiler using a Canadian Cross would be
1963 building a Windows cross MIPS ELF compiler on a GNU/Linux system.  In
1964 this case the build system would be GNU/Linux, the host system would be
1965 Windows, and the target system would be MIPS ELF.
1967 The name Canadian Cross comes from the case when the build, host, and
1968 target systems are all different.  At the time that these issues were
1969 all being hashed out, Canada had three national political parties.
1971 @node Build Cross Host Tools
1972 @section Build Cross Host Tools
1974 In order to configure a program for a Canadian Cross build, you must
1975 first build and install the set of cross tools you will use to build the
1976 program.
1978 These tools will be build cross host tools.  That is, they will run on
1979 the build system, and will produce code that runs on the host system.
1981 It is easy to confuse the meaning of build and host here.  Always
1982 remember that the build system is where you are doing the build, and the
1983 host system is where the resulting program will run.  Therefore, you
1984 need a build cross host compiler.
1986 In general, you must have a complete cross environment in order to do
1987 the build.  This normally means a cross compiler, cross assembler, and
1988 so forth, as well as libraries and include files for the host system.
1990 @node Build and Host Options
1991 @section Build and Host Options
1992 @cindex configuring a canadian cross
1993 @cindex canadian cross, configuring
1995 When you run @file{configure}, you must use both the @samp{--build} and
1996 @samp{--host} options.
1998 @cindex @samp{--build} option
1999 @cindex build option
2000 @cindex configure build system
2001 The @samp{--build} option is used to specify the configuration name of
2002 the build system.  This can normally be the result of running the
2003 @file{config.guess} shell script, and it is reasonable to use
2004 @samp{--build=`config.guess`}.
2006 @cindex @samp{--host} option
2007 @cindex host option
2008 @cindex configure host
2009 The @samp{--host} option is used to specify the configuration name of
2010 the host system.
2012 As we explained earlier, @file{config.guess} is used to set the default
2013 value for the @samp{--host} option (@pxref{Using the Host Type}).  We
2014 can now see that since @file{config.guess} returns the type of system on
2015 which it is run, it really identifies the build system.  Since the host
2016 system is normally the same as the build system (i.e., people do not
2017 normally build using a cross compiler), it is reasonable to use the
2018 result of @file{config.guess} as the default for the host system when
2019 the @samp{--host} option is not used.
2021 It might seem that if the @samp{--host} option were used without the
2022 @samp{--build} option that the configure script could run
2023 @file{config.guess} to determine the build system, and presume a
2024 Canadian Cross if the result of @file{config.guess} differed from the
2025 @samp{--host} option.  However, for historical reasons, some configure
2026 scripts are routinely run using an explicit @samp{--host} option, rather
2027 than using the default from @file{config.guess}.  As noted earlier, it
2028 is difficult or impossible to reliably compare configuration names
2029 (@pxref{Using the Target Type}).  Therefore, by convention, if the
2030 @samp{--host} option is used, but the @samp{--build} option is not used,
2031 then the build system defaults to the host system.
2033 @node CCross not in Cygnus Tree
2034 @section Canadian Cross not in Cygnus Tree.
2036 If you are not using the Cygnus tree, you must explicitly specify the
2037 cross tools which you want to use to build the program.  This is done by
2038 setting environment variables before running the @file{configure}
2039 script.
2041 You must normally set at least the environment variables @samp{CC},
2042 @samp{AR}, and @samp{RANLIB} to the cross tools which you want to use to
2043 build.
2045 For some programs, you must set additional cross tools as well, such as
2046 @samp{AS}, @samp{LD}, or @samp{NM}.
2048 You would set these environment variables to the build cross tools which
2049 you are going to use.
2051 For example, if you are building a Solaris program on a GNU/Linux
2052 system, and your GNU/Linux cross Solaris compiler were named
2053 @samp{solaris-gcc}, then you would set the environment variable
2054 @samp{CC} to @samp{solaris-gcc}.
2056 @node CCross in Cygnus Tree
2057 @section Canadian Cross in Cygnus Tree
2058 @cindex canadian cross in cygnus tree
2060 This section describes configuring and building a Canadian Cross when
2061 using the Cygnus tree.
2063 @menu
2064 * Standard Cygnus CCross::      Building a Normal Program.
2065 * Cross Cygnus CCross::         Building a Cross Program.
2066 @end menu
2068 @node Standard Cygnus CCross
2069 @subsection Building a Normal Program
2071 When configuring a Canadian Cross in the Cygnus tree, all the
2072 appropriate environment variables are automatically set to
2073 @samp{@var{host}-@var{tool}}, where @var{host} is the value used for the
2074 @samp{--host} option, and @var{tool} is the name of the tool (e.g.,
2075 @samp{gcc}, @samp{as}, etc.).  These tools must be on your @samp{PATH}.
2077 Adding a prefix of @var{host} will give the usual name for the build
2078 cross host tools.  To see this, consider that when these cross tools
2079 were built, they were configured to run on the build system and to
2080 produce code for the host system.  That is, they were configured with a
2081 @samp{--target} option that is the same as the system which we are now
2082 calling the host.  Recall that the default name for installed cross
2083 tools uses the target system as a prefix (@pxref{Using the Target
2084 Type}).  Since that is the system which we are now calling the host,
2085 @var{host} is the right prefix to use.
2087 For example, if you configure with @samp{--build=i386-linux-gnu} and
2088 @samp{--host=solaris}, then the Cygnus tree will automatically default
2089 to using the compiler @samp{solaris-gcc}.  You must have previously
2090 built and installed this compiler, probably by doing a build with no
2091 @samp{--host} option and with a @samp{--target} option of
2092 @samp{solaris}.
2094 @node Cross Cygnus CCross
2095 @subsection Building a Cross Program
2097 There are additional considerations if you want to build a cross
2098 compiler, rather than a native compiler, in the Cygnus tree using a
2099 Canadian Cross.
2101 When you build a cross compiler using the Cygnus tree, then the target
2102 libraries will normally be built with the newly built target compiler
2103 (@pxref{Host and Target Libraries}).  However, this will not work when
2104 building with a Canadian Cross.  This is because the newly built target
2105 compiler will be a program which runs on the host system, and therefore
2106 will not be able to run on the build system.
2108 Therefore, when building a cross compiler with the Cygnus tree, you must
2109 first install a set of build cross target tools.  These tools will be
2110 used when building the target libraries.
2112 Note that this is not a requirement of a Canadian Cross in general.  For
2113 example, it would be possible to build just the host cross target tools
2114 on the build system, to copy the tools to the host system, and to build
2115 the target libraries on the host system.  The requirement for build
2116 cross target tools is imposed by the Cygnus tree, which expects to be
2117 able to build both host programs and target libraries in a single
2118 @samp{configure}/@samp{make} step.  Because it builds these in a single
2119 step, it expects to be able to build the target libraries on the build
2120 system, which means that it must use a build cross target toolchain.
2122 For example, suppose you want to build a Windows cross MIPS ELF compiler
2123 on a GNU/Linux system.  You must have previously installed both a
2124 GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF
2125 compiler.
2127 In order to build the Windows (configuration name @samp{i386-cygwin32})
2128 cross MIPS ELF (configure name @samp{mips-elf}) compiler, you might
2129 execute the following commands (long command lines are broken across
2130 lines with a trailing backslash as a continuation character).
2132 @example
2133 mkdir linux-x-cygwin32
2134 cd linux-x-cygwin32
2135 @var{srcdir}/configure --target i386-cygwin32 --prefix=@var{installdir} \
2136   --exec-prefix=@var{installdir}/H-i386-linux
2137 make
2138 make install
2139 cd ..
2140 mkdir linux-x-mips-elf
2141 cd linux-x-mips-elf
2142 @var{srcdir}/configure --target mips-elf --prefix=@var{installdir} \
2143   --exec-prefix=@var{installdir}/H-i386-linux
2144 make
2145 make install
2146 cd ..
2147 mkdir cygwin32-x-mips-elf
2148 cd cygwin32-x-mips-elf
2149 @var{srcdir}/configure --build=i386-linux-gnu --host=i386-cygwin32 \
2150   --target=mips-elf --prefix=@var{wininstalldir} \
2151   --exec-prefix=@var{wininstalldir}/H-i386-cygwin32
2152 make
2153 make install
2154 @end example
2156 You would then copy the contents of @var{wininstalldir} over to the
2157 Windows machine, and run the resulting programs.
2159 @node Supporting Canadian Cross
2160 @section Supporting Canadian Cross
2162 If you want to make it possible to build a program you are developing
2163 using a Canadian Cross, you must take some care when writing your
2164 configure and make rules.  Simple cases will normally work correctly.
2165 However, it is not hard to write configure and make tests which will
2166 fail in a Canadian Cross.
2168 @menu
2169 * CCross in Configure::         Supporting Canadian Cross in Configure Scripts.
2170 * CCross in Make::              Supporting Canadian Cross in Makefiles.
2171 @end menu
2173 @node CCross in Configure
2174 @subsection Supporting Canadian Cross in Configure Scripts
2175 @cindex canadian cross in configure
2177 In a @file{configure.in} file, after calling @samp{AC_PROG_CC}, you can
2178 find out whether this is a Canadian Cross configure by examining the
2179 shell variable @samp{cross_compiling}.  In a Canadian Cross, which means
2180 that the compiler is a cross compiler, @samp{cross_compiling} will be
2181 @samp{yes}.  In a normal configuration, @samp{cross_compiling} will be
2182 @samp{no}.
2184 You ordinarily do not need to know the type of the build system in a
2185 configure script.  However, if you do need that information, you can get
2186 it by using the macro @samp{AC_CANONICAL_SYSTEM}, the same macro that is
2187 used to determine the target system.  This macro will set the variables
2188 @samp{build}, @samp{build_alias}, @samp{build_cpu}, @samp{build_vendor},
2189 and @samp{build_os}, which correspond to the similar @samp{target} and
2190 @samp{host} variables, except that they describe the build system.
2192 When writing tests in @file{configure.in}, you must remember that you
2193 want to test the host environment, not the build environment.
2195 Macros like @samp{AC_CHECK_FUNCS} which use the compiler will test the
2196 host environment.  That is because the tests will be done by running the
2197 compiler, which is actually a build cross host compiler.  If the
2198 compiler can find the function, that means that the function is present
2199 in the host environment.
2201 Tests like @samp{test -f /dev/ptyp0}, on the other hand, will test the
2202 build environment.  Remember that the configure script is running on the
2203 build system, not the host system.  If your configure scripts examines
2204 files, those files will be on the build system.  Whatever you determine
2205 based on those files may or may not be the case on the host system.
2207 Most autoconf macros will work correctly for a Canadian Cross.  The main
2208 exception is @samp{AC_TRY_RUN}.  This macro tries to compile and run a
2209 test program.  This will fail in a Canadian Cross, because the program
2210 will be compiled for the host system, which means that it will not run
2211 on the build system.
2213 The @samp{AC_TRY_RUN} macro provides an optional argument to tell the
2214 configure script what to do in a Canadian Cross.  If that argument is
2215 not present, you will get a warning when you run @samp{autoconf}:
2216 @smallexample
2217 warning: AC_TRY_RUN called without default to allow cross compiling
2218 @end smallexample
2219 @noindent
2220 This tells you that the resulting @file{configure} script will not work
2221 with a Canadian Cross.
2223 In some cases while it may better to perform a test at configure time,
2224 it is also possible to perform the test at run time.  In such a case you
2225 can use the cross compiling argument to @samp{AC_TRY_RUN} to tell your
2226 program that the test could not be performed at configure time.
2228 There are a few other autoconf macros which will not work correctly with
2229 a Canadian Cross: a partial list is @samp{AC_FUNC_GETPGRP},
2230 @samp{AC_FUNC_SETPGRP}, @samp{AC_FUNC_SETVBUF_REVERSED}, and
2231 @samp{AC_SYS_RESTARTABLE_SYSCALLS}.  The @samp{AC_CHECK_SIZEOF} macro is
2232 generally not very useful with a Canadian Cross; it permits an optional
2233 argument indicating the default size, but there is no way to know what
2234 the correct default should be.
2236 @node CCross in Make
2237 @subsection Supporting Canadian Cross in Makefiles.
2238 @cindex canadian cross in makefile
2240 The main Canadian Cross issue in a @file{Makefile} arises when you want
2241 to use a subsidiary program to generate code or data which you will then
2242 include in your real program.
2244 If you compile this subsidiary program using @samp{$(CC)} in the usual
2245 way, you will not be able to run it.  This is because @samp{$(CC)} will
2246 build a program for the host system, but the program is being built on
2247 the build system.
2249 You must instead use a compiler for the build system, rather than the
2250 host system.  In the Cygnus tree, this make variable
2251 @samp{$(CC_FOR_BUILD)} will hold a compiler for the build system.
2253 Note that you should not include @file{config.h} in a file you are
2254 compiling with @samp{$(CC_FOR_BUILD)}.  The @file{configure} script will
2255 build @file{config.h} with information for the host system.  However,
2256 you are compiling the file using a compiler for the build system (a
2257 native compiler).  Subsidiary programs are normally simple filters which
2258 do no user interaction, and it is normally possible to write them in a
2259 highly portable fashion so that the absence of @file{config.h} is not
2260 crucial.
2262 @cindex @samp{HOST_CC}
2263 The gcc @file{Makefile.in} shows a complex situation in which certain
2264 files, such as @file{rtl.c}, must be compiled into both subsidiary
2265 programs run on the build system and into the final program.  This
2266 approach may be of interest for advanced build system hackers.  Note
2267 that the build system compiler is rather confusingly called
2268 @samp{HOST_CC}.
2270 @node Cygnus Configure
2271 @chapter Cygnus Configure
2272 @cindex cygnus configure
2274 The Cygnus configure script predates autoconf.  All of its interesting
2275 features have been incorporated into autoconf.  No new programs should
2276 be written to use the Cygnus configure script.
2278 However, the Cygnus configure script is still used in a few places: at
2279 the top of the Cygnus tree and in a few target libraries in the Cygnus
2280 tree.  Until those uses have been replaced with autoconf, some brief
2281 notes are appropriate here.  This is not complete documentation, but it
2282 should be possible to use this as a guide while examining the scripts
2283 themselves.
2285 @menu
2286 * Cygnus Configure Basics::             Cygnus Configure Basics.
2287 * Cygnus Configure in C++ Libraries::   Cygnus Configure in C++ Libraries.
2288 @end menu
2290 @node Cygnus Configure Basics
2291 @section Cygnus Configure Basics
2293 Cygnus configure does not use any generated files; there is no program
2294 corresponding to @samp{autoconf}.  Instead, there is a single shell
2295 script named @samp{configure} which may be found at the top of the
2296 Cygnus tree.  This shell script was written by hand; it was not
2297 generated by autoconf, and it is incorrect, and indeed harmful, to run
2298 @samp{autoconf} in the top level of a Cygnus tree.
2300 Cygnus configure works in a particular directory by examining the file
2301 @file{configure.in} in that directory.  That file is broken into four
2302 separate shell scripts.
2304 The first is the contents of @file{configure.in} up to a line that
2305 starts with @samp{# per-host:}.  This is the common part.
2307 The second is the rest of @file{configure.in} up to a line that starts
2308 with @samp{# per-target:}.  This is the per host part.
2310 The third is the rest of @file{configure.in} up to a line that starts
2311 with @samp{# post-target:}.  This is the per target part.
2313 The fourth is the remainder of @file{configure.in}.  This is the post
2314 target part.
2316 If any of these comment lines are missing, the corresponding shell
2317 script is empty.
2319 Cygnus configure will first execute the common part.  This must set the
2320 shell variable @samp{srctrigger} to the name of a source file, to
2321 confirm that Cygnus configure is looking at the right directory.  This
2322 may set the shell variables @samp{package_makefile_frag} and
2323 @samp{package_makefile_rules_frag}.
2325 Cygnus configure will next set the @samp{build} and @samp{host} shell
2326 variables, and execute the per host part.  This may set the shell
2327 variable @samp{host_makefile_frag}.
2329 Cygnus configure will next set the @samp{target} variable, and execute
2330 the per target part.  This may set the shell variable
2331 @samp{target_makefile_frag}.
2333 Any of these scripts may set the @samp{subdirs} shell variable.  This
2334 variable is a list of subdirectories where a @file{Makefile.in} file may
2335 be found.  Cygnus configure will automatically look for a
2336 @file{Makefile.in} file in the current directory.  The @samp{subdirs}
2337 shell variable is not normally used, and I believe that the only
2338 directory which uses it at present is @file{newlib}.
2340 For each @file{Makefile.in}, Cygnus configure will automatically create
2341 a @file{Makefile} by adding definitions for @samp{make} variables such
2342 as @samp{host} and @samp{target}, and automatically editing the values
2343 of @samp{make} variables such as @samp{prefix} if they are present.
2345 Also, if any of the @samp{makefile_frag} shell variables are set, Cygnus
2346 configure will interpret them as file names relative to either the
2347 working directory or the source directory, and will read the contents of
2348 the file into the generated @file{Makefile}.  The file contents will be
2349 read in after the first line in @file{Makefile.in} which starts with
2350 @samp{####}.
2352 These @file{Makefile} fragments are used to customize behaviour for a
2353 particular host or target.  They serve to select particular files to
2354 compile, and to define particular preprocessor macros by providing
2355 values for @samp{make} variables which are then used during compilation.
2356 Cygnus configure, unlike autoconf, normally does not do feature tests,
2357 and normally requires support to be added manually for each new host.
2359 The @file{Makefile} fragment support is similar to the autoconf
2360 @samp{AC_SUBST_FILE} macro.
2362 After creating each @file{Makefile}, the post target script will be run
2363 (i.e., it may be run several times).  This script may further customize
2364 the @file{Makefile}.  When it is run, the shell variable @samp{Makefile}
2365 will hold the name of the @file{Makefile}, including the appropriate
2366 directory component.
2368 Like an autoconf generated @file{configure} script, Cygnus configure
2369 will create a file named @file{config.status} which, when run, will
2370 automatically recreate the configuration.  The @file{config.status} file
2371 will simply execute the Cygnus configure script again with the
2372 appropriate arguments.
2374 Any of the parts of @file{configure.in} may set the shell variables
2375 @samp{files} and @samp{links}.  Cygnus configure will set up symlinks
2376 from the names in @samp{links} to the files named in @samp{files}.  This
2377 is similar to the autoconf @samp{AC_LINK_FILES} macro.
2379 Finally, any of the parts of @file{configure.in} may set the shell
2380 variable @samp{configdirs} to a set of subdirectories.  If it is set,
2381 Cygnus configure will recursively run the configure process in each
2382 subdirectory.  If the subdirectory uses Cygnus configure, it will
2383 contain a @file{configure.in} file but no @file{configure} file, in
2384 which case Cygnus configure will invoke itself recursively.  If the
2385 subdirectory has a @file{configure} file, Cygnus configure assumes that
2386 it is an autoconf generated @file{configure} script, and simply invokes
2387 it directly.
2389 @node Cygnus Configure in C++ Libraries
2390 @section Cygnus Configure in C++ Libraries
2391 @cindex @file{libstdc++} configure
2392 @cindex @file{libio} configure
2393 @cindex @file{libg++} configure
2395 The C++ library configure system, written by Per Bothner, deserves
2396 special mention.  It uses Cygnus configure, but it does feature testing
2397 like that done by autoconf generated @file{configure} scripts.  This
2398 approach is used in the libraries @file{libio}, @file{libstdc++}, and
2399 @file{libg++}.
2401 Most of the @file{Makefile} information is written out by the shell
2402 script @file{libio/config.shared}.  Each @file{configure.in} file sets
2403 certain shell variables, and then invokes @file{config.shared} to create
2404 two package @file{Makefile} fragments.  These fragments are then
2405 incorporated into the resulting @file{Makefile} by the Cygnus configure
2406 script.
2408 The file @file{_G_config.h} is created in the @file{libio} object
2409 directory by running the shell script @file{libio/gen-params}.  This
2410 shell script uses feature tests to define macros and typedefs in
2411 @file{_G_config.h}.
2413 @node Multilibs
2414 @chapter Multilibs
2415 @cindex multilibs
2417 For some targets gcc may have different processor requirements depending
2418 upon command line options.  An obvious example is the
2419 @samp{-msoft-float} option supported on several processors.  This option
2420 means that the floating point registers are not available, which means
2421 that floating point operations must be done by calling an emulation
2422 subroutine rather than by using machine instructions.
2424 For such options, gcc is often configured to compile target libraries
2425 twice: once with @samp{-msoft-float} and once without.  When gcc
2426 compiles target libraries more than once, the resulting libraries are
2427 called @dfn{multilibs}.
2429 Multilibs are not really part of the GNU configure and build system, but
2430 we discuss them here since they require support in the @file{configure}
2431 scripts and @file{Makefile}s used for target libraries.
2433 @menu
2434 * Multilibs in gcc::                    Multilibs in gcc.
2435 * Multilibs in Target Libraries::       Multilibs in Target Libraries.
2436 @end menu
2438 @node Multilibs in gcc
2439 @section Multilibs in gcc
2441 In gcc, multilibs are defined by setting the variable
2442 @samp{MULTILIB_OPTIONS} in the target @file{Makefile} fragment.  Several
2443 other @samp{MULTILIB} variables may also be defined there.  @xref{Target
2444 Fragment, , The Target Makefile Fragment, gcc, Using and Porting GNU
2445 CC}.
2447 If you have built gcc, you can see what multilibs it uses by running it
2448 with the @samp{-print-multi-lib} option.  The output @samp{.;} means
2449 that no multilibs are used.  In general, the output is a sequence of
2450 lines, one per multilib.  The first part of each line, up to the
2451 @samp{;}, is the name of the multilib directory.  The second part is a
2452 list of compiler options separated by @samp{@@} characters.
2454 Multilibs are built in a tree of directories.  The top of the tree,
2455 represented by @samp{.} in the list of multilib directories, is the
2456 default library to use when no special compiler options are used.  The
2457 subdirectories of the tree hold versions of the library to use when
2458 particular compiler options are used.
2460 @node Multilibs in Target Libraries
2461 @section Multilibs in Target Libraries
2463 The target libraries in the Cygnus tree are automatically built with
2464 multilibs.  That means that each library is built multiple times.
2466 This default is set in the top level @file{configure.in} file, by adding
2467 @samp{--enable-multilib} to the list of arguments passed to configure
2468 when it is run for the target libraries (@pxref{Host and Target
2469 Libraries}).
2471 Each target library uses the shell script @file{config-ml.in}, written
2472 by Doug Evans, to prepare to build target libraries.  This shell script
2473 is invoked after the @file{Makefile} has been created by the
2474 @file{configure} script.  If multilibs are not enabled, it does nothing,
2475 otherwise it modifies the @file{Makefile} to support multilibs.
2477 The @file{config-ml.in} script makes one copy of the @file{Makefile} for
2478 each multilib in the appropriate subdirectory.  When configuring in the
2479 source directory (which is not recommended), it will build a symlink
2480 tree of the sources in each subdirectory.
2482 The @file{config-ml.in} script sets several variables in the various
2483 @file{Makefile}s.  The @file{Makefile.in} must have definitions for
2484 these variables already; @file{config-ml.in} simply changes the existing
2485 values.  The @file{Makefile} should use default values for these
2486 variables which will do the right thing in the subdirectories.
2488 @table @samp
2489 @item MULTISRCTOP
2490 @file{config-ml.in} will set this to a sequence of @samp{../} strings,
2491 where the number of strings is the number of multilib levels in the
2492 source tree.  The default value should be the empty string.
2493 @item MULTIBUILDTOP
2494 @file{config-ml.in} will set this to a sequence of @samp{../} strings,
2495 where the number of strings is number of multilib levels in the object
2496 directory.  The default value should be the empty string.  This will
2497 differ from @samp{MULTISRCTOP} when configuring in the source tree
2498 (which is not recommended).
2499 @item MULTIDIRS
2500 In the top level @file{Makefile} only, @file{config-ml.in} will set this
2501 to the list of multilib subdirectories.  The default value should be the
2502 empty string.
2503 @item MULTISUBDIR
2504 @file{config-ml.in} will set this to the installed subdirectory name to
2505 use for this subdirectory, with a leading @samp{/}.  The default value
2506 shold be the empty string.
2507 @item MULTIDO
2508 @itemx MULTICLEAN
2509 In the top level @file{Makefile} only, @file{config-ml.in} will set
2510 these variables to commands to use when doing a recursive make.  These
2511 variables should both default to the string @samp{true}, so that by
2512 default nothing happens.
2513 @end table
2515 All references to the parent of the source directory should use the
2516 variable @samp{MULTISRCTOP}.  Instead of writing @samp{$(srcdir)/..},
2517 you must write @samp{$(srcdir)/$(MULTISRCTOP)..}.
2519 Similarly, references to the parent of the object directory should use
2520 the variable @samp{MULTIBUILDTOP}.
2522 In the installation target, the libraries should be installed in the
2523 subdirectory @samp{MULTISUBDIR}.  Instead of installing
2524 @samp{$(libdir)/libfoo.a}, install
2525 @samp{$(libdir)$(MULTISUBDIR)/libfoo.a}.
2527 The @file{config-ml.in} script also modifies the top level
2528 @file{Makefile} to add @samp{multi-do} and @samp{multi-clean} targets
2529 which are used when building multilibs.
2531 The default target of the @file{Makefile} should include the following
2532 command:
2533 @smallexample
2534 @@$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
2535 @end smallexample
2536 @noindent
2537 This assumes that @samp{$(FLAGS_TO_PASS)} is defined as a set of
2538 variables to pass to a recursive invocation of @samp{make}.  This will
2539 build all the multilibs.  Note that the default value of @samp{MULTIDO}
2540 is @samp{true}, so by default this command will do nothing.  It will
2541 only do something in the top level @file{Makefile} if multilibs were
2542 enabled.
2544 The @samp{install} target of the @file{Makefile} should include the
2545 following command:
2546 @smallexample
2547 @@$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
2548 @end smallexample
2550 In general, any operation, other than clean, which should be performed
2551 on all the multilibs should use a @samp{$(MULTIDO)} line, setting the
2552 variable @samp{DO} to the target of each recursive call to @samp{make}.
2554 The @samp{clean} targets (@samp{clean}, @samp{mostlyclean}, etc.) should
2555 use @samp{$(MULTICLEAN)}.  For example, the @samp{clean} target should
2556 do this:
2557 @smallexample
2558 @@$(MULTICLEAN) DO=clean multi-clean
2559 @end smallexample
2561 @node FAQ
2562 @chapter Frequently Asked Questions
2564 @table @asis
2565 @item Which do I run first, @samp{autoconf} or @samp{automake}?
2566 Except when you first add autoconf or automake support to a package, you
2567 shouldn't run either by hand.  Instead, configure with the
2568 @samp{--enable-maintainer-mode} option, and let @samp{make} take care of
2571 @cindex undefined macros
2572 @item @samp{autoconf} says something about undefined macros.
2573 This means that you have macros in your @file{configure.in} which are
2574 not defined by @samp{autoconf}.  You may be using an old version of
2575 @samp{autoconf}; try building and installing a newer one.  Make sure the
2576 newly installled @samp{autoconf} is first on your @samp{PATH}.  Also,
2577 see the next question.
2579 @cindex @samp{CY_GNU_GETTEXT} in @file{configure}
2580 @cindex @samp{AM_PROG_LIBTOOL} in @file{configure}
2581 @item My @file{configure} script has stuff like @samp{CY_GNU_GETTEXT} in it.
2582 This means that you have macros in your @file{configure.in} which should
2583 be defined in your @file{aclocal.m4} file, but aren't.  This usually
2584 means that @samp{aclocal} was not able to appropriate definitions of the
2585 macros.  Make sure that you have installed all the packages you need.
2586 In particular, make sure that you have installed libtool (this is where
2587 @samp{AM_PROG_LIBTOOL} is defined) and gettext (this is where
2588 @samp{CY_GNU_GETTEXT} is defined, at least in the Cygnus version of
2589 gettext).
2591 @cindex @file{Makefile}, garbage characters
2592 @item My @file{Makefile} has @samp{@@} characters in it.
2593 This may mean that you tried to use an autoconf substitution in your
2594 @file{Makefile.in} without adding the appropriate @samp{AC_SUBST} call
2595 to your @file{configure} script.  Or it may just mean that you need to
2596 rebuild @file{Makefile} in your build directory.  To rebuild
2597 @file{Makefile} from @file{Makefile.in}, run the shell script
2598 @file{config.status} with no arguments.  If you need to force
2599 @file{configure} to run again, first run @samp{config.status --recheck}.
2600 These runs are normally done automatically by @file{Makefile} targets,
2601 but if your @file{Makefile} has gotten messed up you'll need to help
2602 them along.
2604 @cindex @samp{config.status --recheck}
2605 @item Why do I have to run both @samp{config.status --recheck} and @samp{config.status}?
2606 Normally, you don't; they will be run automatically by @file{Makefile}
2607 targets.  If you do need to run them, use @samp{config.status --recheck}
2608 to run the @file{configure} script again with the same arguments as the
2609 first time you ran it.  Use @samp{config.status} (with no arguments) to
2610 regenerate all files (@file{Makefile}, @file{config.h}, etc.) based on
2611 the results of the configure script.  The two cases are separate because
2612 it isn't always necessary to regenerate all the files after running
2613 @samp{config.status --recheck}.  The @file{Makefile} targets generated
2614 by automake will use the environment variables @samp{CONFIG_FILES} and
2615 @samp{CONFIG_HEADERS} to only regenerate files as they are needed.
2617 @item What is the Cygnus tree?
2618 The Cygnus tree is used for various packages including gdb, the GNU
2619 binutils, and egcs.  It is also, of course, used for Cygnus releases.
2620 It is the build system which was developed at Cygnus, using the Cygnus
2621 configure script.  It permits building many different packages with a
2622 single configure and make.  The configure scripts in the tree are being
2623 converted to autoconf, but the general build structure remains intact.
2625 @item Why do I have to keep rebuilding and reinstalling the tools?
2626 I know, it's a pain.  Unfortunately, there are bugs in the tools
2627 themselves which need to be fixed, and each time that happens everybody
2628 who uses the tools need to reinstall new versions of them.  I don't know
2629 if there is going to be a clever fix until the tools stabilize.
2631 @item Why not just have a Cygnus tree @samp{make} target to update the tools?
2632 The tools unfortunately need to be installed before they can be used.
2633 That means that they must be built using an appropriate prefix, and it
2634 seems unwise to assume that every configuration uses an appropriate
2635 prefix.  It might be possible to make them work in place, or it might be
2636 possible to install them in some subdirectory; so far these approaches
2637 have not been implemented.
2638 @end table
2640 @node Index
2641 @unnumbered Index
2643 @printindex cp
2645 @contents
2646 @bye