merge from gcc
[binutils.git] / etc / configure.texi
blobd69dc414d0f3e5581980f85fa56c495642226e14
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 @ifinfo
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 ifinfo
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 @ifinfo
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 ifinfo
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}.
281 All @samp{configure} scripts support a wide variety of options.  The
282 most interesting ones are @samp{--with} and @samp{--enable} options
283 which are generally specific to particular tools.  You can usually use
284 the @samp{--help} option to get a list of interesting options for a
285 particular configure script.
287 The only generic options you are likely to use are the @samp{--prefix}
288 and @samp{--exec-prefix} options.  These options are used to specify the
289 installation directory.
291 The directory named by the @samp{--prefix} option will hold machine
292 independent files such as info files.
294 The directory named by the @samp{--exec-prefix} option, which is
295 normally a subdirectory of the @samp{--prefix} directory, will hold
296 machine dependent files such as executables.
298 The default for @samp{--prefix} is @file{/usr/local}.  The default for
299 @samp{--exec-prefix} is the value used for @samp{--prefix}.
301 The convention used in Cygnus releases is to use a @samp{--prefix}
302 option of @file{/usr/cygnus/@var{release}}, where @var{release} is the
303 name of the release, and to use a @samp{--exec-prefix} option of
304 @file{/usr/cygnus/@var{release}/H-@var{host}}, where @var{host} is the
305 configuration name of the host system (@pxref{Configuration Names}).
307 Do not use either the source or the object directory as the installation
308 directory.  That will just lead to confusion.
310 @node Getting Started
311 @chapter Getting Started
313 To start using the GNU configure and build system with your software
314 package, you must write three files, and you must run some tools to
315 manually generate additional files.
317 @menu
318 * Write configure.in::          Write configure.in.
319 * Write Makefile.am::           Write Makefile.am.
320 * Write acconfig.h::            Write acconfig.h.
321 * Generate files::              Generate files.
322 * Getting Started Example::     Example.
323 @end menu
325 @node Write configure.in
326 @section Write configure.in
327 @cindex @file{configure.in}, writing
329 You must first write the file @file{configure.in}.  This is an autoconf
330 input file, and the autoconf manual describes in detail what this file
331 should look like.
333 You will write tests in your @file{configure.in} file to check for
334 conditions that may change from one system to another, such as the
335 presence of particular header files or functions.
337 For example, not all systems support the @samp{gettimeofday} function.
338 If you want to use the @samp{gettimeofday} function when it is
339 available, and to use some other function when it is not, you would
340 check for this by putting @samp{AC_CHECK_FUNCS(gettimeofday)} in
341 @file{configure.in}.
343 When the configure script is run at build time, this will arrange to
344 define the preprocessor macro @samp{HAVE_GETTIMEOFDAY} to the value 1 if
345 the @samp{gettimeofday} function is available, and to not define the
346 macro at all if the function is not available.  Your code can then use
347 @samp{#ifdef} to test whether it is safe to call @samp{gettimeofday}.
349 If you have an existing body of code, the @samp{autoscan} program may
350 help identify potential portability problems, and hence configure tests
351 that you will want to use.
352 @ifnothtml
353 @xref{Invoking autoscan, , , autoconf, the autoconf manual}.
354 @end ifnothtml
355 @ifhtml
356 See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_4.html, the
357 autoscan documentation}.
358 @end ifhtml
360 Another handy tool for an existing body of code is @samp{ifnames}.  This
361 will show you all the preprocessor conditionals that the code already
362 uses.
363 @ifnothtml
364 @xref{Invoking ifnames, , , autoconf, the autoconf manual}.
365 @end ifnothtml
366 @ifhtml
367 See @uref{http://www.delorie.com/gnu/docs/autoconf/autoconf_5.html, the
368 ifnames documentation}.
369 @end ifhtml
371 Besides the portability tests which are specific to your particular
372 package, every @file{configure.in} file should contain the following
373 macros.
375 @table @samp
376 @item AC_INIT
377 @cindex @samp{AC_INIT}
378 This macro takes a single argument, which is the name of a file in your
379 package.  For example, @samp{AC_INIT(foo.c)}.
381 @item AC_PREREQ(@var{VERSION})
382 @cindex @samp{AC_PREREQ}
383 This macro is optional.  It may be used to indicate the version of
384 @samp{autoconf} that you are using.  This will prevent users from
385 running an earlier version of @samp{autoconf} and perhaps getting an
386 invalid @file{configure} script.  For example, @samp{AC_PREREQ(2.12)}.
388 @item AM_INIT_AUTOMAKE
389 @cindex @samp{AM_INIT_AUTOMAKE}
390 This macro takes two arguments: the name of the package, and a version
391 number.  For example, @samp{AM_INIT_AUTOMAKE(foo, 1.0)}.  (This macro is
392 not needed if you are not using automake).
394 @item AM_CONFIG_HEADER
395 @cindex @samp{AM_CONFIG_HEADER}
396 This macro names the header file which will hold the preprocessor macro
397 definitions at run time.  Normally this should be @file{config.h}.  Your
398 sources would then use @samp{#include "config.h"} to include it.
400 This macro may optionally name the input file for that header file; by
401 default, this is @file{config.h.in}, but that file name works poorly on
402 DOS filesystems.  Therefore, it is often better to name it explicitly as
403 @file{config.in}.
405 This is what you should normally put in @file{configure.in}:
406 @example
407 AM_CONFIG_HEADER(config.h:config.in)
408 @end example
410 @cindex @samp{AC_CONFIG_HEADER}
411 (If you are not using automake, use @samp{AC_CONFIG_HEADER} rather than
412 @samp{AM_CONFIG_HEADER}).
414 @item AM_MAINTAINER_MODE
415 @cindex @samp{AM_MAINTAINER_MODE}
416 This macro always appears in Cygnus configure scripts.  Other programs
417 may or may not use it.
419 If this macro is used, the @samp{--enable-maintainer-mode} option is
420 required to enable automatic rebuilding of generated files used by the
421 configure system.  This of course requires that developers be aware of,
422 and use, that option.
424 If this macro is not used, then the generated files will always be
425 rebuilt automatically.  This will cause problems if the wrong versions
426 of autoconf, automake, or others are in the builder's @samp{PATH}.
428 (If you are not using automake, you do not need to use this macro).
430 @item AC_EXEEXT
431 @cindex @samp{AC_EXEEXT}
432 @cindex @samp{AM_EXEEXT}
433 Either this macro or @samp{AM_EXEEXT} always appears in Cygnus configure
434 files.  Other programs may or may not use one of them.
436 This macro looks for the executable suffix used on the host system.  On
437 Unix systems, this is the empty string.  On Windows systems, this is
438 @samp{.exe}.  This macro directs automake to use the executable suffix
439 as appropriate when creating programs.  This macro does not take any
440 arguments.
442 The @samp{AC_EXEEXT} form is new, and is part of a Cygnus patch to
443 autoconf to support compiling with Visual C++.  Older programs use
444 @samp{AM_EXEEXT} instead.
446 (Programs which do not use automake use neither @samp{AC_EXEEXT} nor
447 @samp{AM_EXEEXT}).
449 @item AC_PROG_CC
450 @cindex @samp{AC_PROG_CC}
451 If you are writing C code, you will normally want to use this macro.  It
452 locates the C compiler to use.  It does not take any arguments.
454 However, if this @file{configure.in} file is for a library which is to
455 be compiled by a cross compiler which may not fully work, then you will
456 not want to use @samp{AC_PROG_CC}.  Instead, you will want to use a
457 variant which does not call the macro @samp{AC_PROG_CC_WORKS}.  Examples
458 can be found in various @file{configure.in} files for libraries that are
459 compiled with cross compilers, such as libiberty or libgloss.  This is
460 essentially a bug in autoconf, and there will probably be a better
461 workaround at some point.
463 @item AC_PROG_CXX
464 @cindex @samp{AC_PROG_CXX}
465 If you are writing C++ code, you will want to use this macro.  It
466 locates the C++ compiler to use.  It does not take any arguments.  The
467 same cross compiler comments apply as for @samp{AC_PROG_CC}.
469 @item AM_PROG_LIBTOOL
470 @cindex @samp{AM_PROG_LIBTOOL}
471 If you want to build libraries, and you want to permit them to be
472 shared, or you want to link against libraries which were built using
473 libtool, then you will need this macro.  This macro is required in order
474 to use libtool.
476 @cindex @samp{AM_DISABLE_SHARED}
477 By default, this will cause all libraries to be built as shared
478 libraries.  To prevent this--to change the default--use
479 @samp{AM_DISABLE_SHARED} before @samp{AM_PROG_LIBTOOL}.  The configure
480 options @samp{--enable-shared} and @samp{--disable-shared} may be used
481 to override the default at build time.
483 @item AC_DEFINE(_GNU_SOURCE)
484 @cindex @samp{_GNU_SOURCE}
485 GNU packages should normally include this line before any other feature
486 tests.  This defines the macro @samp{_GNU_SOURCE} when compiling, which
487 directs the libc header files to provide the standard GNU system
488 interfaces including all GNU extensions.  If this macro is not defined,
489 certain GNU extensions may not be available.
491 @item AC_OUTPUT
492 @cindex @samp{AC_OUTPUT}
493 This macro takes a list of file names which the configure process should
494 produce.  This is normally a list of one or more @file{Makefile} files
495 in different directories.  If your package lives entirely in a single
496 directory, you would use simply @samp{AC_OUTPUT(Makefile)}.  If you also
497 have, for example, a @file{lib} subdirectory, you would use
498 @samp{AC_OUTPUT(Makefile lib/Makefile)}.
499 @end table
501 If you want to use locally defined macros in your @file{configure.in}
502 file, then you will need to write a @file{acinclude.m4} file which
503 defines them (if not using automake, this file is called
504 @file{aclocal.m4}).  Alternatively, you can put separate macros in an
505 @file{m4} subdirectory, and put @samp{ACLOCAL_AMFLAGS = -I m4} in your
506 @file{Makefile.am} file so that the @samp{aclocal} program will be able
507 to find them.
509 The different macro prefixes indicate which tool defines the macro.
510 Macros which start with @samp{AC_} are part of autoconf.  Macros which
511 start with @samp{AM_} are provided by automake or libtool.
513 @node Write Makefile.am
514 @section Write Makefile.am
515 @cindex @file{Makefile.am}, writing
517 You must write the file @file{Makefile.am}.  This is an automake input
518 file, and the automake manual describes in detail what this file should
519 look like.
521 The automake commands in @file{Makefile.am} mostly look like variable
522 assignments in a @file{Makefile}.  automake recognizes special variable
523 names, and automatically add make rules to the output as needed.
525 There will be one @file{Makefile.am} file for each directory in your
526 package.  For each directory with subdirectories, the @file{Makefile.am}
527 file should contain the line
528 @smallexample
529 SUBDIRS = @var{dir} @var{dir} @dots{}
530 @end smallexample
531 @noindent
532 where each @var{dir} is the name of a subdirectory.
534 For each @file{Makefile.am}, there should be a corresponding
535 @file{Makefile} in the @samp{AC_OUTPUT} macro in @file{configure.in}.
537 Every @file{Makefile.am} written at Cygnus should contain the line
538 @smallexample
539 AUTOMAKE_OPTIONS = cygnus
540 @end smallexample
541 @noindent
542 This puts automake into Cygnus mode.  See the automake manual for
543 details.
545 You may to include the version number of @samp{automake} that you are
546 using on the @samp{AUTOMAKE_OPTIONS} line.  For example,
547 @smallexample
548 AUTOMAKE_OPTIONS = cygnus 1.3
549 @end smallexample
550 @noindent
551 This will prevent users from running an earlier version of
552 @samp{automake} and perhaps getting an invalid @file{Makefile.in}.
554 If your package builds a program, then in the directory where that
555 program is built you will normally want a line like
556 @smallexample
557 bin_PROGRAMS = @var{program}
558 @end smallexample
559 @noindent
560 where @var{program} is the name of the program.  You will then want a
561 line like
562 @smallexample
563 @var{program}_SOURCES = @var{file} @var{file} @dots{}
564 @end smallexample
565 @noindent
566 where each @var{file} is the name of a source file to link into the
567 program (e.g., @samp{foo.c}).
569 If your package builds a library, and you do not want the library to
570 ever be built as a shared library, then in the directory where that
571 library is built you will normally want a line like
572 @smallexample
573 lib_LIBRARIES = lib@var{name}.a
574 @end smallexample
575 @noindent
576 where @samp{lib@var{name}.a} is the name of the library.  You will then
577 want a line like
578 @smallexample
579 lib@var{name}_a_SOURCES = @var{file} @var{file} @dots{}
580 @end smallexample
581 @noindent
582 where each @var{file} is the name of a source file to add to the
583 library.
585 If your package builds a library, and you want to permit building the
586 library as a shared library, then in the directory where that library is
587 built you will normally want a line like
588 @smallexample
589 lib_LTLIBRARIES = lib@var{name}.la
590 @end smallexample
591 The use of @samp{LTLIBRARIES}, and the @samp{.la} extension, indicate a
592 library to be built using libtool.  As usual, you will then want a line
593 like
594 @smallexample
595 lib@var{name}_la_SOURCES = @var{file} @var{file} @dots{}
596 @end smallexample
598 The strings @samp{bin} and @samp{lib} that appear above in
599 @samp{bin_PROGRAMS} and @samp{lib_LIBRARIES} are not arbitrary.  They
600 refer to particular directories, which may be set by the @samp{--bindir}
601 and @samp{--libdir} options to @file{configure}.  If those options are
602 not used, the default values are based on the @samp{--prefix} or
603 @samp{--exec-prefix} options to @file{configure}.  It is possible to use
604 other names if the program or library should be installed in some other
605 directory.
607 The @file{Makefile.am} file may also contain almost anything that may
608 appear in a normal @file{Makefile}.  automake also supports many other
609 special variables, as well as conditionals.
611 See the automake manual for more information.
613 @node Write acconfig.h
614 @section Write acconfig.h
615 @cindex @file{acconfig.h}, writing
617 If you are generating a portability header file, (i.e., you are using
618 @samp{AM_CONFIG_HEADER} in @file{configure.in}), then you will have to
619 write a @file{acconfig.h} file.  It will have to contain the following
620 lines.
622 @smallexample
623 /* Name of package.  */
624 #undef PACKAGE
626 /* Version of package.  */
627 #undef VERSION
628 @end smallexample
630 This requirement is really a bug in the system, and the requirement may
631 be eliminated at some later date.
633 The @file{acconfig.h} file will also similar comment and @samp{#undef}
634 lines for any unusual macros in the @file{configure.in} file, including
635 any macro which appears in a @samp{AC_DEFINE} macro.
637 In particular, if you are writing a GNU package and therefore include
638 @samp{AC_DEFINE(_GNU_SOURCE)} in @file{configure.in} as suggested above,
639 you will need lines like this in @file{acconfig.h}:
640 @smallexample
641 /* Enable GNU extensions.  */
642 #undef _GNU_SOURCE
643 @end smallexample
645 Normally the @samp{autoheader} program will inform you of any such
646 requirements by printing an error message when it is run.  However, if
647 you do anything particular odd in your @file{configure.in} file, you
648 will have to make sure that the right entries appear in
649 @file{acconfig.h}, since otherwise the results of the tests may not be
650 available in the @file{config.h} file which your code will use.
652 (Thee @samp{PACKAGE} and @samp{VERSION} lines are not required if you
653 are not using automake, and in that case you may not need a
654 @file{acconfig.h} file at all).
656 @node Generate files
657 @section Generate files
659 Once you have written @file{configure.in}, @file{Makefile.am},
660 @file{acconfig.h}, and possibly @file{acinclude.m4}, you must use
661 autoconf and automake programs to produce the first versions of the
662 generated files.  This is done by executing the following sequence of
663 commands.
665 @smallexample
666 aclocal
667 autoconf
668 autoheader
669 automake
670 @end smallexample
672 The @samp{aclocal} and @samp{automake} commands are part of the automake
673 package, and the @samp{autoconf} and @samp{autoheader} commands are part
674 of the autoconf package.
676 If you are using a @file{m4} subdirectory for your macros, you will need
677 to use the @samp{-I m4} option when you run @samp{aclocal}.
679 If you are not using the Cygnus tree, use the @samp{-a} option when
680 running @samp{automake} command in order to copy the required support
681 files into your source directory.
683 If you are using libtool, you must build and install the libtool package
684 with the same @samp{--prefix} and @samp{--exec-prefix} options as you
685 used with the autoconf and automake packages.  You must do this before
686 running any of the above commands.  If you are not using the Cygnus
687 tree, you will need to run the @samp{libtoolize} program to copy the
688 libtool support files into your directory.
690 Once you have managed to run these commands without getting any errors,
691 you should create a new empty directory, and run the @samp{configure}
692 script which will have been created by @samp{autoconf} with the
693 @samp{--enable-maintainer-mode} option.  This will give you a set of
694 Makefiles which will include rules to automatically rebuild all the
695 generated files.
697 After doing that, whenever you have changed some of the input files and
698 want to regenerated the other files, go to your object directory and run
699 @samp{make}.  Doing this is more reliable than trying to rebuild the
700 files manually, because there are complex order dependencies and it is
701 easy to forget something.
703 @node Getting Started Example
704 @section Example
706 Let's consider a trivial example.
708 Suppose we want to write a simple version of @samp{touch}.  Our program,
709 which we will call @samp{poke}, will take a single file name argument,
710 and use the @samp{utime} system call to set the modification and access
711 times of the file to the current time.  We want this program to be
712 highly portable.
714 We'll first see what this looks like without using autoconf and
715 automake, and then see what it looks like with them.
717 @menu
718 * Getting Started Example 1::           First Try.
719 * Getting Started Example 2::           Second Try.
720 * Getting Started Example 3::           Third Try.
721 * Generate Files in Example::           Generate Files.
722 @end menu
724 @node Getting Started Example 1
725 @subsection First Try
727 Here is our first try at @samp{poke.c}.  Note that we've written it
728 without ANSI/ISO C prototypes, since we want it to be highly portable.
730 @example
731 #include <stdio.h>
732 #include <stdlib.h>
733 #include <sys/types.h>
734 #include <utime.h>
737 main (argc, argv)
738      int argc;
739      char **argv;
741   if (argc != 2)
742     @{
743       fprintf (stderr, "Usage: poke file\n");
744       exit (1);
745     @}
747   if (utime (argv[1], NULL) < 0)
748     @{
749       perror ("utime");
750       exit (1);
751     @}
753   exit (0);
755 @end example
757 We also write a simple @file{Makefile}.
759 @example
760 CC = gcc
761 CFLAGS = -g -O2
763 all: poke
765 poke: poke.o
766         $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o
767 @end example
769 So far, so good.
771 Unfortunately, there are a few problems.
773 On older Unix systems derived from BSD 4.3, the @samp{utime} system call
774 does not accept a second argument of @samp{NULL}.  On those systems, we
775 need to pass a pointer to @samp{struct utimbuf} structure.
776 Unfortunately, even older systems don't define that structure; on those
777 systems, we need to pass an array of two @samp{long} values.
779 The header file @file{stdlib.h} was invented by ANSI C, and older
780 systems don't have a copy.  We included it above to get a declaration of
781 @samp{exit}.
783 We can find some of these portability problems by running
784 @samp{autoscan}, which will create a @file{configure.scan} file which we
785 can use as a prototype for our @file{configure.in} file.  I won't show
786 the output, but it will notice the potential problems with @samp{utime}
787 and @file{stdlib.h}.
789 In our @file{Makefile}, we don't provide any way to install the program.
790 This doesn't matter much for such a simple example, but a real program
791 will need an @samp{install} target.  For that matter, we will also want
792 a @samp{clean} target.
794 @node Getting Started Example 2
795 @subsection Second Try
797 Here is our second try at this program.
799 We modify @file{poke.c} to use preprocessor macros to control what
800 features are available.  (I've cheated a bit by using the same macro
801 names which autoconf will use).
803 @example
804 #include <stdio.h>
806 #ifdef STDC_HEADERS
807 #include <stdlib.h>
808 #endif
810 #include <sys/types.h>
812 #ifdef HAVE_UTIME_H
813 #include <utime.h>
814 #endif
816 #ifndef HAVE_UTIME_NULL
818 #include <time.h>
820 #ifndef HAVE_STRUCT_UTIMBUF
822 struct utimbuf
824   long actime;
825   long modtime;
828 #endif
830 static int
831 utime_now (file)
832      char *file;
834   struct utimbuf now;
836   now.actime = now.modtime = time (NULL);
837   return utime (file, &now);
840 #define utime(f, p) utime_now (f)
842 #endif /* HAVE_UTIME_NULL  */
845 main (argc, argv)
846      int argc;
847      char **argv;
849   if (argc != 2)
850     @{
851       fprintf (stderr, "Usage: poke file\n");
852       exit (1);
853     @}
855   if (utime (argv[1], NULL) < 0)
856     @{
857       perror ("utime");
858       exit (1);
859     @}
861   exit (0);
863 @end example
865 Here is the associated @file{Makefile}.  We've added support for the
866 preprocessor flags we use.  We've also added @samp{install} and
867 @samp{clean} targets.
869 @example
870 # Set this to your installation directory.
871 bindir = /usr/local/bin
873 # Uncomment this if you have the standard ANSI/ISO C header files.
874 # STDC_HDRS = -DSTDC_HEADERS
876 # Uncomment this if you have utime.h.
877 # UTIME_H = -DHAVE_UTIME_H
879 # Uncomment this if utime (FILE, NULL) works on your system.
880 # UTIME_NULL = -DHAVE_UTIME_NULL
882 # Uncomment this if struct utimbuf is defined in utime.h.
883 # UTIMBUF = -DHAVE_STRUCT_UTIMBUF
885 CC = gcc
886 CFLAGS = -g -O2
888 ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS)
890 all: poke
892 poke: poke.o
893         $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o
895 .c.o:
896         $(CC) -c $(ALL_CFLAGS) poke.c
898 install: poke
899         cp poke $(bindir)/poke
901 clean:
902         rm poke poke.o
903 @end example
905 Some problems with this approach should be clear.
907 Users who want to compile poke will have to know how @samp{utime} works
908 on their systems, so that they can uncomment the @file{Makefile}
909 correctly.
911 The installation is done using @samp{cp}, but many systems have an
912 @samp{install} program which may be used, and which supports optional
913 features such as stripping debugging information out of the installed
914 binary.
916 The use of @file{Makefile} variables like @samp{CC}, @samp{CFLAGS} and
917 @samp{LDFLAGS} follows the requirements of the GNU standards.  This is
918 convenient for all packages, since it reduces surprises for users.
919 However, it is easy to get the details wrong, and wind up with a
920 slightly nonstandard distribution.
922 @node Getting Started Example 3
923 @subsection Third Try
925 For our third try at this program, we will write a @file{configure.in}
926 script to discover the configuration features on the host system, rather
927 than requiring the user to edit the @file{Makefile}.  We will also write
928 a @file{Makefile.am} rather than a @file{Makefile}.
930 The only change to @file{poke.c} is to add a line at the start of the
931 file:
932 @smallexample
933 #include "config.h"
934 @end smallexample
936 The new @file{configure.in} file is as follows.
938 @example
939 AC_INIT(poke.c)
940 AM_INIT_AUTOMAKE(poke, 1.0)
941 AM_CONFIG_HEADER(config.h:config.in)
942 AC_PROG_CC
943 AC_HEADER_STDC
944 AC_CHECK_HEADERS(utime.h)
945 AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF))
946 AC_FUNC_UTIME_NULL
947 AC_OUTPUT(Makefile)
948 @end example
950 The first four macros in this file, and the last one, were described
951 above; see @ref{Write configure.in}.  If we omit these macros, then when
952 we run @samp{automake} we will get a reminder that we need them.
954 The other macros are standard autoconf macros.
956 @table @samp
957 @item AC_HEADER_STDC
958 Check for standard C headers.
959 @item AC_CHECK_HEADERS
960 Check whether a particular header file exists.
961 @item AC_EGREP_HEADER
962 Check for a particular string in a particular header file, in this case
963 checking for @samp{utimbuf} in @file{utime.h}.
964 @item AC_FUNC_UTIME_NULL
965 Check whether @samp{utime} accepts a NULL second argument to set the
966 file change time to the current time.
967 @end table
969 See the autoconf manual for a more complete description.
971 The new @file{Makefile.am} file is as follows.  Note how simple this is
972 compared to our earlier @file{Makefile}.
974 @example
975 bin_PROGRAMS = poke
977 poke_SOURCES = poke.c
978 @end example
980 This means that we should build a single program name @samp{poke}.  It
981 should be installed in the binary directory, which we called
982 @samp{bindir} earlier.  The program @samp{poke} is built from the source
983 file @file{poke.c}.
985 We must also write a @file{acconfig.h} file.  Besides @samp{PACKAGE} and
986 @samp{VERSION}, which must be mentioned for all packages which use
987 automake, we must include @samp{HAVE_STRUCT_UTIMBUF}, since we mentioned
988 it in an @samp{AC_DEFINE}.
990 @example
991 /* Name of package.  */
992 #undef PACKAGE
994 /* Version of package.  */
995 #undef VERSION
997 /* Whether utime.h defines struct utimbuf.  */
998 #undef HAVE_STRUCT_UTIMBUF
999 @end example
1001 @node Generate Files in Example
1002 @subsection Generate Files
1004 We must now generate the other files, using the following commands.
1006 @smallexample
1007 aclocal
1008 autoconf
1009 autoheader
1010 automake
1011 @end smallexample
1013 When we run @samp{autoheader}, it will remind us of any macros we forgot
1014 to add to @file{acconfig.h}.
1016 When we run @samp{automake}, it will want to add some files to our
1017 distribution.  It will add them automatically if we use the
1018 @samp{--add-missing} option.
1020 By default, @samp{automake} will run in GNU mode, which means that it
1021 will want us to create certain additional files; as of this writing, it
1022 will want @file{NEWS}, @file{README}, @file{AUTHORS}, and
1023 @file{ChangeLog}, all of which are files which should appear in a
1024 standard GNU distribution.  We can either add those files, or run
1025 @samp{automake} with the @samp{--foreign} option.
1027 Running these tools will generate the following files, all of which are
1028 described in the next chapter.
1030 @itemize @bullet
1031 @item
1032 @file{aclocal.m4}
1033 @item
1034 @file{configure}
1035 @item
1036 @file{config.in}
1037 @item
1038 @file{Makefile.in}
1039 @item
1040 @file{stamp-h.in}
1041 @end itemize
1043 @node Files
1044 @chapter Files
1046 As was seen in the previous chapter, the GNU configure and build system
1047 uses a number of different files.  The developer must write a few files.
1048 The others are generated by various tools.
1050 The system is rather flexible, and can be used in many different ways.
1051 In describing the files that it uses, I will describe the common case,
1052 and mention some other cases that may arise.
1054 @menu
1055 * Developer Files::             Developer Files.
1056 * Build Files::                 Build Files.
1057 * Support Files::               Support Files.
1058 @end menu
1060 @node Developer Files
1061 @section Developer Files
1063 This section describes the files written or generated by the developer
1064 of a package.
1066 @menu
1067 * Developer Files Picture::     Developer Files Picture.
1068 * Written Developer Files::     Written Developer Files.
1069 * Generated Developer Files::   Generated Developer Files.
1070 @end menu
1072 @node Developer Files Picture
1073 @subsection Developer Files Picture
1075 Here is a picture of the files which are written by the developer, the
1076 generated files which would be included with a complete source
1077 distribution, and the tools which create those files.
1078 @ifinfo
1079 The file names are plain text and the tool names are enclosed by
1080 @samp{*} characters
1081 @end ifinfo
1082 @ifnotinfo
1083 The file names are in rectangles with square corners and the tool names
1084 are in rectangles with rounded corners
1085 @end ifnotinfo
1086 (e.g., @samp{autoheader} is the name of a tool, not the name of a file).
1088 @image{configdev}
1090 @node Written Developer Files
1091 @subsection Written Developer Files
1093 The following files would be written by the developer.
1095 @table @file
1096 @item configure.in
1097 @cindex @file{configure.in}
1098 This is the configuration script.  This script contains invocations of
1099 autoconf macros.  It may also contain ordinary shell script code.  This
1100 file will contain feature tests for portability issues.  The last thing
1101 in the file will normally be an @samp{AC_OUTPUT} macro listing which
1102 files to create when the builder runs the configure script.  This file
1103 is always required when using the GNU configure system.  @xref{Write
1104 configure.in}.
1106 @item Makefile.am
1107 @cindex @file{Makefile.am}
1108 This is the automake input file.  It describes how the code should be
1109 built.  It consists of definitions of automake variables.  It may also
1110 contain ordinary Makefile targets.  This file is only needed when using
1111 automake (newer tools normally use automake, but there are still older
1112 tools which have not been converted, in which the developer writes
1113 @file{Makefile.in} directly).  @xref{Write Makefile.am}.
1115 @item acconfig.h
1116 @cindex @file{acconfig.h}
1117 When the configure script creates a portability header file, by using
1118 @samp{AM_CONFIG_HEADER} (or, if not using automake,
1119 @samp{AC_CONFIG_HEADER}), this file is used to describe macros which are
1120 not recognized by the @samp{autoheader} command.  This is normally a
1121 fairly uninteresting file, consisting of a collection of @samp{#undef}
1122 lines with comments.  Normally any call to @samp{AC_DEFINE} in
1123 @file{configure.in} will require a line in this file. @xref{Write
1124 acconfig.h}.
1126 @item acinclude.m4
1127 @cindex @file{acinclude.m4}
1128 This file is not always required.  It defines local autoconf macros.
1129 These macros may then be used in @file{configure.in}.  If you don't need
1130 any local autoconf macros, then you don't need this file at all.  In
1131 fact, in general, you never need local autoconf macros, since you can
1132 put everything in @file{configure.in}, but sometimes a local macro is
1133 convenient.
1135 Newer tools may omit @file{acinclude.m4}, and instead use a
1136 subdirectory, typically named @file{m4}, and define
1137 @samp{ACLOCAL_AMFLAGS = -I m4} in @file{Makefile.am} to force
1138 @samp{aclocal} to look there for macro definitions.  The macro
1139 definitions are then placed in separate files in that directory.
1141 The @file{acinclude.m4} file is only used when using automake; in older
1142 tools, the developer writes @file{aclocal.m4} directly, if it is needed.
1143 @end table
1145 @node Generated Developer Files
1146 @subsection Generated Developer Files
1148 The following files would be generated by the developer.
1150 When using automake, these files are normally not generated manually
1151 after the first time.  Instead, the generated @file{Makefile} contains
1152 rules to automatically rebuild the files as required.  When
1153 @samp{AM_MAINTAINER_MODE} is used in @file{configure.in} (the normal
1154 case in Cygnus code), the automatic rebuilding rules will only be
1155 defined if you configure using the @samp{--enable-maintainer-mode}
1156 option.
1158 When using automatic rebuilding, it is important to ensure that all the
1159 various tools have been built and installed on your @samp{PATH}.  Using
1160 automatic rebuilding is highly recommended, so much so that I'm not
1161 going to explain what you have to do if you don't use it.
1163 @table @file
1164 @item configure
1165 @cindex @file{configure}
1166 This is the configure script which will be run when building the
1167 package.  This is generated by @samp{autoconf} from @file{configure.in}
1168 and @file{aclocal.m4}.  This is a shell script.
1170 @item Makefile.in
1171 @cindex @file{Makefile.in}
1172 This is the file which the configure script will turn into the
1173 @file{Makefile} at build time.  This file is generated by
1174 @samp{automake} from @file{Makefile.am}.  If you aren't using automake,
1175 you must write this file yourself.  This file is pretty much a normal
1176 @file{Makefile}, with some configure substitutions for certain
1177 variables.
1179 @item aclocal.m4
1180 @cindex @file{aclocal.m4}
1181 This file is created by the @samp{aclocal} program, based on the
1182 contents of @file{configure.in} and @file{acinclude.m4} (or, as noted in
1183 the description of @file{acinclude.m4} above, on the contents of an
1184 @file{m4} subdirectory).  This file contains definitions of autoconf
1185 macros which @samp{autoconf} will use when generating the file
1186 @file{configure}.  These autoconf macros may be defined by you in
1187 @file{acinclude.m4} or they may be defined by other packages such as
1188 automake, libtool or gettext.  If you aren't using automake, you will
1189 normally write this file yourself; in that case, if @file{configure.in}
1190 uses only standard autoconf macros, this file will not be needed at all.
1192 @item config.in
1193 @cindex @file{config.in}
1194 @cindex @file{config.h.in}
1195 This file is created by @samp{autoheader} based on @file{acconfig.h} and
1196 @file{configure.in}.  At build time, the configure script will define
1197 some of the macros in it to create @file{config.h}, which may then be
1198 included by your program.  This permits your C code to use preprocessor
1199 conditionals to change its behaviour based on the characteristics of the
1200 host system.  This file may also be called @file{config.h.in}.
1202 @item stamp.h-in
1203 @cindex @file{stamp-h.in}
1204 This rather uninteresting file, which I omitted from the picture, is
1205 generated by @samp{automake}.  It always contains the string
1206 @samp{timestamp}.  It is used as a timestamp file indicating whether
1207 @file{config.in} is up to date.  Using a timestamp file means that
1208 @file{config.in} can be marked as up to date without actually changing
1209 its modification time.  This is useful since @file{config.in} depends
1210 upon @file{configure.in}, but it is easy to change @file{configure.in}
1211 in a way which does not affect @file{config.in}.
1212 @end table
1214 @node Build Files
1215 @section Build Files
1217 This section describes the files which are created at configure and
1218 build time.  These are the files which somebody who builds the package
1219 will see.
1221 Of course, the developer will also build the package.  The distinction
1222 between developer files and build files is not that the developer does
1223 not see the build files, but that somebody who only builds the package
1224 does not have to worry about the developer files.
1226 @menu
1227 * Build Files Picture::         Build Files Picture.
1228 * Build Files Description::     Build Files Description.
1229 @end menu
1231 @node Build Files Picture
1232 @subsection Build Files Picture
1234 Here is a picture of the files which will be created at build time.
1235 @file{config.status} is both a created file and a shell script which is
1236 run to create other files, and the picture attempts to show that.
1238 @image{configbuild}
1240 @node Build Files Description
1241 @subsection Build Files Description
1243 This is a description of the files which are created at build time.
1245 @table @file
1246 @item config.status
1247 @cindex @file{config.status}
1248 The first step in building a package is to run the @file{configure}
1249 script.  The @file{configure} script will create the file
1250 @file{config.status}, which is itself a shell script.  When you first
1251 run @file{configure}, it will automatically run @file{config.status}.
1252 An @file{Makefile} derived from an automake generated @file{Makefile.in}
1253 will contain rules to automatically run @file{config.status} again when
1254 necessary to recreate certain files if their inputs change.
1256 @item Makefile
1257 @cindex @file{Makefile}
1258 This is the file which make will read to build the program.  The
1259 @file{config.status} script will transform @file{Makefile.in} into
1260 @file{Makefile}.
1262 @item config.h
1263 @cindex @file{config.h}
1264 This file defines C preprocessor macros which C code can use to adjust
1265 its behaviour on different systems.  The @file{config.status} script
1266 will transform @file{config.in} into @file{config.h}.
1268 @item config.cache
1269 @cindex @file{config.cache}
1270 This file did not fit neatly into the picture, and I omitted it.  It is
1271 used by the @file{configure} script to cache results between runs.  This
1272 can be an important speedup.  If you modify @file{configure.in} in such
1273 a way that the results of old tests should change (perhaps you have
1274 added a new library to @samp{LDFLAGS}), then you will have to remove
1275 @file{config.cache} to force the tests to be rerun.
1277 The autoconf manual explains how to set up a site specific cache file.
1278 This can speed up running @file{configure} scripts on your system.
1280 @item stamp.h
1281 @cindex @file{stamp-h}
1282 This file, which I omitted from the picture, is similar to
1283 @file{stamp-h.in}.  It is used as a timestamp file indicating whether
1284 @file{config.h} is up to date.  This is useful since @file{config.h}
1285 depends upon @file{config.status}, but it is easy for
1286 @file{config.status} to change in a way which does not affect
1287 @file{config.h}.
1288 @end table
1290 @node Support Files
1291 @section Support Files
1293 The GNU configure and build system requires several support files to be
1294 included with your distribution.  You do not normally need to concern
1295 yourself with these.  If you are using the Cygnus tree, most are already
1296 present.  Otherwise, they will be installed with your source by
1297 @samp{automake} (with the @samp{--add-missing} option) and
1298 @samp{libtoolize}.
1300 You don't have to put the support files in the top level directory.  You
1301 can put them in a subdirectory, and use the @samp{AC_CONFIG_AUX_DIR}
1302 macro in @file{configure.in} to tell @samp{automake} and the
1303 @file{configure} script where they are.
1305 In this section, I describe the support files, so that you can know what
1306 they are and why they are there.
1308 @table @file
1309 @item ABOUT-NLS
1310 Added by automake if you are using gettext.  This is a documentation
1311 file about the gettext project.
1312 @item ansi2knr.c
1313 Used by an automake generated @file{Makefile} if you put @samp{ansi2knr}
1314 in @samp{AUTOMAKE_OPTIONS} in @file{Makefile.am}.  This permits
1315 compiling ANSI C code with a K&R C compiler.
1316 @item ansi2knr.1
1317 The man page which goes with @file{ansi2knr.c}.
1318 @item config.guess
1319 A shell script which determines the configuration name for the system on
1320 which it is run.
1321 @item config.sub
1322 A shell script which canonicalizes a configuration name entered by a
1323 user.
1324 @item elisp-comp
1325 Used to compile Emacs LISP files.
1326 @item install-sh
1327 A shell script which installs a program.  This is used if the configure
1328 script can not find an install binary.
1329 @item ltconfig
1330 Used by libtool.  This is a shell script which configures libtool for
1331 the particular system on which it is used.
1332 @item ltmain.sh
1333 Used by libtool.  This is the actual libtool script which is used, after
1334 it is configured by @file{ltconfig} to build a library.
1335 @item mdate-sh
1336 A shell script used by an automake generated @file{Makefile} to pretty
1337 print the modification time of a file.  This is used to maintain version
1338 numbers for texinfo files.
1339 @item missing
1340 A shell script used if some tool is missing entirely.  This is used by
1341 an automake generated @file{Makefile} to avoid certain sorts of
1342 timestamp problems.
1343 @item mkinstalldirs
1344 A shell script which creates a directory, including all parent
1345 directories.  This is used by an automake generated @file{Makefile}
1346 during installation.
1347 @item texinfo.tex
1348 Required if you have any texinfo files.  This is used when converting
1349 Texinfo files into DVI using @samp{texi2dvi} and @TeX{}.
1350 @item ylwrap
1351 A shell script used by an automake generated @file{Makefile} to run
1352 programs like @samp{bison}, @samp{yacc}, @samp{flex}, and @samp{lex}.
1353 These programs default to producing output files with a fixed name, and
1354 the @file{ylwrap} script runs them in a subdirectory to avoid file name
1355 conflicts when using a parallel make program.
1356 @end table
1358 @node Configuration Names
1359 @chapter Configuration Names
1360 @cindex configuration names
1361 @cindex configuration triplets
1362 @cindex triplets
1363 @cindex host names
1364 @cindex host triplets
1365 @cindex canonical system names
1366 @cindex system names
1367 @cindex system types
1369 The GNU configure system names all systems using a @dfn{configuration
1370 name}.  All such names used to be triplets (they may now contain four
1371 parts in certain cases), and the term @dfn{configuration triplet} is
1372 still seen.
1374 @menu
1375 * Configuration Name Definition::       Configuration Name Definition.
1376 * Using Configuration Names::           Using Configuration Names.
1377 @end menu
1379 @node Configuration Name Definition
1380 @section Configuration Name Definition
1382 This is a string of the form
1383 @var{cpu}-@var{manufacturer}-@var{operating_system}.  In some cases,
1384 this is extended to a four part form:
1385 @var{cpu}-@var{manufacturer}-@var{kernel}-@var{operating_system}.
1387 When using a configuration name in a configure option, it is normally
1388 not necessary to specify an entire name.  In particular, the
1389 @var{manufacturer} field is often omitted, leading to strings such as
1390 @samp{i386-linux} or @samp{sparc-sunos}.  The shell script
1391 @file{config.sub} will translate these shortened strings into the
1392 canonical form.  autoconf will arrange for @file{config.sub} to be run
1393 automatically when it is needed.
1395 The fields of a configuration name are as follows:
1397 @table @var
1398 @item cpu
1399 The type of processor.  This is typically something like @samp{i386} or
1400 @samp{sparc}.  More specific variants are used as well, such as
1401 @samp{mipsel} to indicate a little endian MIPS processor.
1402 @item manufacturer
1403 A somewhat freeform field which indicates the manufacturer of the
1404 system.  This is often simply @samp{unknown}.  Other common strings are
1405 @samp{pc} for an IBM PC compatible system, or the name of a workstation
1406 vendor, such as @samp{sun}.
1407 @item operating_system
1408 The name of the operating system which is run on the system.  This will
1409 be something like @samp{solaris2.5} or @samp{irix6.3}.  There is no
1410 particular restriction on the version number, and strings like
1411 @samp{aix4.1.4.0} are seen.  For an embedded system, which has no
1412 operating system, this field normally indicates the type of object file
1413 format, such as @samp{elf} or @samp{coff}.
1414 @item kernel
1415 This is used mainly for GNU/Linux.  A typical GNU/Linux configuration
1416 name is @samp{i586-pc-linux-gnulibc1}.  In this case the kernel,
1417 @samp{linux}, is separated from the operating system, @samp{gnulibc1}.
1418 @end table
1420 The shell script @file{config.guess} will normally print the correct
1421 configuration name for the system on which it is run.  It does by
1422 running @samp{uname} and by examining other characteristics of the
1423 system.
1425 Because @file{config.guess} can normally determine the configuration
1426 name for a machine, it is normally only necessary to specify a
1427 configuration name when building a cross-compiler or when building using
1428 a cross-compiler.
1430 @node Using Configuration Names
1431 @section Using Configuration Names
1433 A configure script will sometimes have to make a decision based on a
1434 configuration name.  You will need to do this if you have to compile
1435 code differently based on something which can not be tested using a
1436 standard autoconf feature test.
1438 It is normally better to test for particular features, rather than to
1439 test for a particular system.  This is because as Unix evolves,
1440 different systems copy features from one another.  Even if you need to
1441 determine whether the feature is supported based on a configuration
1442 name, you should define a macro which describes the feature, rather than
1443 defining a macro which describes the particular system you are on.
1445 Testing for a particular system is normally done using a case statement
1446 in @file{configure.in}.  The case statement might look something like
1447 the following, assuming that @samp{host} is a shell variable holding a
1448 canonical configuration name (which will be the case if
1449 @file{configure.in} uses the @samp{AC_CANONICAL_HOST} or
1450 @samp{AC_CANONICAL_SYSTEM} macro).
1452 @smallexample
1453 case "$@{host@}" in
1454 i[3-7]86-*-linux-gnu*) do something ;;
1455 sparc*-sun-solaris2.[56789]*) do something ;;
1456 sparc*-sun-solaris*) do something ;;
1457 mips*-*-elf*) do something ;;
1458 esac
1459 @end smallexample
1461 It is particularly important to use @samp{*} after the operating system
1462 field, in order to match the version number which will be generated by
1463 @file{config.guess}.
1465 In most cases you must be careful to match a range of processor types.
1466 For most processor families, a trailing @samp{*} suffices, as in
1467 @samp{mips*} above.  For the i386 family, something along the lines of
1468 @samp{i[3-7]86} suffices at present.  For the m68k family, you will
1469 need something like @samp{m68*}.  Of course, if you do not need to match
1470 on the processor, it is simpler to just replace the entire field by a
1471 @samp{*}, as in @samp{*-*-irix*}.
1473 @node Cross Compilation Tools
1474 @chapter Cross Compilation Tools
1475 @cindex cross tools
1477 The GNU configure and build system can be used to build @dfn{cross
1478 compilation} tools.  A cross compilation tool is a tool which runs on
1479 one system and produces code which runs on another system.
1481 @menu
1482 * Cross Compilation Concepts::          Cross Compilation Concepts.
1483 * Host and Target::                     Host and Target.
1484 * Using the Host Type::                 Using the Host Type.
1485 * Specifying the Target::               Specifying the Target.
1486 * Using the Target Type::               Using the Target Type.
1487 * Cross Tools in the Cygnus Tree::      Cross Tools in the Cygnus Tree
1488 @end menu
1490 @node Cross Compilation Concepts
1491 @section Cross Compilation Concepts
1493 @cindex cross compiler
1494 A compiler which produces programs which run on a different system is a
1495 cross compilation compiler, or simply a @dfn{cross compiler}.
1496 Similarly, we speak of cross assemblers, cross linkers, etc.
1498 In the normal case, a compiler produces code which runs on the same
1499 system as the one on which the compiler runs.  When it is necessary to
1500 distinguish this case from the cross compilation case, such a compiler
1501 is called a @dfn{native compiler}.  Similarly, we speak of native
1502 assemblers, etc.
1504 Although the debugger is not strictly speaking a compilation tool, it is
1505 nevertheless meaningful to speak of a cross debugger: a debugger which
1506 is used to debug code which runs on another system.  Everything that is
1507 said below about configuring cross compilation tools applies to the
1508 debugger as well.
1510 @node Host and Target
1511 @section Host and Target
1512 @cindex host system
1513 @cindex target system
1515 When building cross compilation tools, there are two different systems
1516 involved: the system on which the tools will run, and the system for
1517 which the tools generate code.
1519 The system on which the tools will run is called the @dfn{host} system.
1521 The system for which the tools generate code is called the @dfn{target}
1522 system.
1524 For example, suppose you have a compiler which runs on a GNU/Linux
1525 system and generates ELF programs for a MIPS embedded system.  In this
1526 case the GNU/Linux system is the host, and the MIPS ELF system is the
1527 target.  Such a compiler could be called a GNU/Linux cross MIPS ELF
1528 compiler, or, equivalently, a @samp{i386-linux-gnu} cross
1529 @samp{mips-elf} compiler.
1531 Naturally, most programs are not cross compilation tools.  For those
1532 programs, it does not make sense to speak of a target.  It only makes
1533 sense to speak of a target for tools like @samp{gcc} or the
1534 @samp{binutils} which actually produce running code.  For example, it
1535 does not make sense to speak of the target of a tool like @samp{bison}
1536 or @samp{make}.
1538 Most cross compilation tools can also serve as native tools.  For a
1539 native compilation tool, it is still meaningful to speak of a target.
1540 For a native tool, the target is the same as the host.  For example, for
1541 a GNU/Linux native compiler, the host is GNU/Linux, and the target is
1542 also GNU/Linux.
1544 @node Using the Host Type
1545 @section Using the Host Type
1547 In almost all cases the host system is the system on which you run the
1548 @samp{configure} script, and on which you build the tools (for the case
1549 when they differ, @pxref{Canadian Cross}).
1551 @cindex @samp{AC_CANONICAL_HOST}
1552 If your configure script needs to know the configuration name of the
1553 host system, and the package is not a cross compilation tool and
1554 therefore does not have a target, put @samp{AC_CANONICAL_HOST} in
1555 @file{configure.in}.  This macro will arrange to define a few shell
1556 variables when the @samp{configure} script is run.
1558 @table @samp
1559 @item host
1560 The canonical configuration name of the host.  This will normally be
1561 determined by running the @file{config.guess} shell script, although the
1562 user is permitted to override this by using an explicit @samp{--host}
1563 option.
1564 @item host_alias
1565 In the unusual case that the user used an explicit @samp{--host} option,
1566 this will be the argument to @samp{--host}.  In the normal case, this
1567 will be the same as the @samp{host} variable.
1568 @item host_cpu
1569 @itemx host_vendor
1570 @itemx host_os
1571 The first three parts of the canonical configuration name.
1572 @end table
1574 The shell variables may be used by putting shell code in
1575 @file{configure.in}.  For an example, see @ref{Using Configuration
1576 Names}.
1578 @node Specifying the Target
1579 @section Specifying the Target
1581 By default, the @samp{configure} script will assume that the target is
1582 the same as the host.  This is the more common case; for example, it
1583 leads to a native compiler rather than a cross compiler.
1585 @cindex @samp{--target} option
1586 @cindex target option
1587 @cindex configure target
1588 If you want to build a cross compilation tool, you must specify the
1589 target explicitly by using the @samp{--target} option when you run
1590 @samp{configure}.  The argument to @samp{--target} is the configuration
1591 name of the system for which you wish to generate code.
1592 @xref{Configuration Names}.
1594 For example, to build tools which generate code for a MIPS ELF embedded
1595 system, you would use @samp{--target mips-elf}.
1597 @node Using the Target Type
1598 @section Using the Target Type
1600 @cindex @samp{AC_CANONICAL_SYSTEM}
1601 When writing @file{configure.in} for a cross compilation tool, you will
1602 need to use information about the target.  To do this, put
1603 @samp{AC_CANONICAL_SYSTEM} in @file{configure.in}.
1605 @samp{AC_CANONICAL_SYSTEM} will look for a @samp{--target} option and
1606 canonicalize it using the @file{config.sub} shell script.  It will also
1607 run @samp{AC_CANONICAL_HOST} (@pxref{Using the Host Type}).
1609 The target type will be recorded in the following shell variables.  Note
1610 that the host versions of these variables will also be defined by
1611 @samp{AC_CANONICAL_HOST}.
1613 @table @samp
1614 @item target
1615 The canonical configuration name of the target.
1616 @item target_alias
1617 The argument to the @samp{--target} option.  If the user did not specify
1618 a @samp{--target} option, this will be the same as @samp{host_alias}.
1619 @item target_cpu
1620 @itemx target_vendor
1621 @itemx target_os
1622 The first three parts of the canonical target configuration name.
1623 @end table
1625 Note that if @samp{host} and @samp{target} are the same string, you can
1626 assume a native configuration.  If they are different, you can assume a
1627 cross configuration.
1629 It is arguably possible for @samp{host} and @samp{target} to represent
1630 the same system, but for the strings to not be identical.  For example,
1631 if @samp{config.guess} returns @samp{sparc-sun-sunos4.1.4}, and somebody
1632 configures with @samp{--target sparc-sun-sunos4.1}, then the slight
1633 differences between the two versions of SunOS may be unimportant for
1634 your tool.  However, in the general case it can be quite difficult to
1635 determine whether the differences between two configuration names are
1636 significant or not.  Therefore, by convention, if the user specifies a
1637 @samp{--target} option without specifying a @samp{--host} option, it is
1638 assumed that the user wants to configure a cross compilation tool.
1640 The variables @samp{target} and @samp{target_alias} should be handled
1641 differently.
1643 In general, whenever the user may actually see a string,
1644 @samp{target_alias} should be used.  This includes anything which may
1645 appear in the file system, such as a directory name or part of a tool
1646 name.  It also includes any tool output, unless it is clearly labelled
1647 as the canonical target configuration name.  This permits the user to
1648 use the @samp{--target} option to specify how the tool will appear to
1649 the outside world.
1651 On the other hand, when checking for characteristics of the target
1652 system, @samp{target} should be used.  This is because a wide variety of
1653 @samp{--target} options may map into the same canonical configuration
1654 name.  You should not attempt to duplicate the canonicalization done by
1655 @samp{config.sub} in your own code.
1657 By convention, cross tools are installed with a prefix of the argument
1658 used with the @samp{--target} option, also known as @samp{target_alias}
1659 (@pxref{Using the Target Type}).  If the user does not use the
1660 @samp{--target} option, and thus is building a native tool, no prefix is
1661 used.
1663 For example, if gcc is configured with @samp{--target mips-elf}, then
1664 the installed binary will be named @samp{mips-elf-gcc}.  If gcc is
1665 configured without a @samp{--target} option, then the installed binary
1666 will be named @samp{gcc}.
1668 The autoconf macro @samp{AC_ARG_PROGRAM} will handle this for you.  If
1669 you are using automake, no more need be done; the programs will
1670 automatically be installed with the correct prefixes.  Otherwise, see
1671 the autoconf documentation for @samp{AC_ARG_PROGRAM}.
1673 @node Cross Tools in the Cygnus Tree
1674 @section Cross Tools in the Cygnus Tree
1676 The Cygnus tree is used for various packages including gdb, the GNU
1677 binutils, and egcs.  It is also, of course, used for Cygnus releases.
1679 In the Cygnus tree, the top level @file{configure} script uses the old
1680 Cygnus configure system, not autoconf.  The top level @file{Makefile.in}
1681 is written to build packages based on what is in the source tree, and
1682 supports building a large number of tools in a single
1683 @samp{configure}/@samp{make} step.
1685 The Cygnus tree may be configured with a @samp{--target} option.  The
1686 @samp{--target} option applies recursively to every subdirectory, and
1687 permits building an entire set of cross tools at once.
1689 @menu
1690 * Host and Target Libraries::           Host and Target Libraries.
1691 * Target Library Configure Scripts::    Target Library Configure Scripts.
1692 * Make Targets in Cygnus Tree::         Make Targets in Cygnus Tree.
1693 * Target libiberty::                    Target libiberty
1694 @end menu
1696 @node Host and Target Libraries
1697 @subsection Host and Target Libraries
1699 The Cygnus tree distinguishes host libraries from target libraries.
1701 Host libraries are built with the compiler used to build the programs
1702 which run on the host, which is called the host compiler.  This includes
1703 libraries such as @samp{bfd} and @samp{tcl}.  These libraries are built
1704 with the host compiler, and are linked into programs like the binutils
1705 or gcc which run on the host.
1707 Target libraries are built with the target compiler.  If gcc is present
1708 in the source tree, then the target compiler is the gcc that is built
1709 using the host compiler.  Target libraries are libraries such as
1710 @samp{newlib} and @samp{libstdc++}.  These libraries are not linked into
1711 the host programs, but are instead made available for use with programs
1712 built with the target compiler.
1714 For the rest of this section, assume that gcc is present in the source
1715 tree, so that it will be used to build the target libraries.
1717 There is a complication here.  The configure process needs to know which
1718 compiler you are going to use to build a tool; otherwise, the feature
1719 tests will not work correctly.  The Cygnus tree handles this by not
1720 configuring the target libraries until the target compiler is built.  In
1721 order to permit everything to build using a single
1722 @samp{configure}/@samp{make}, the configuration of the target libraries
1723 is actually triggered during the make step.
1725 When the target libraries are configured, the @samp{--target} option is
1726 not used.  Instead, the @samp{--host} option is used with the argument
1727 of the @samp{--target} option for the overall configuration.  If no
1728 @samp{--target} option was used for the overall configuration, the
1729 @samp{--host} option will be passed with the output of the
1730 @file{config.guess} shell script.  Any @samp{--build} option is passed
1731 down unchanged.
1733 This translation of configuration options is done because since the
1734 target libraries are compiled with the target compiler, they are being
1735 built in order to run on the target of the overall configuration.  By
1736 the definition of host, this means that their host system is the same as
1737 the target system of the overall configuration.
1739 The same process is used for both a native configuration and a cross
1740 configuration.  Even when using a native configuration, the target
1741 libraries will be configured and built using the newly built compiler.
1742 This is particularly important for the C++ libraries, since there is no
1743 reason to assume that the C++ compiler used to build the host tools (if
1744 there even is one) uses the same ABI as the g++ compiler which will be
1745 used to build the target libraries.
1747 There is one difference between a native configuration and a cross
1748 configuration.  In a native configuration, the target libraries are
1749 normally configured and built as siblings of the host tools.  In a cross
1750 configuration, the target libraries are normally built in a subdirectory
1751 whose name is the argument to @samp{--target}.  This is mainly for
1752 historical reasons.
1754 To summarize, running @samp{configure} in the Cygnus tree configures all
1755 the host libraries and tools, but does not configure any of the target
1756 libraries.  Running @samp{make} then does the following steps:
1758 @itemize @bullet
1759 @item
1760 Build the host libraries.
1761 @item
1762 Build the host programs, including gcc.  Note that we call gcc both a
1763 host program (since it runs on the host) and a target compiler (since it
1764 generates code for the target).
1765 @item
1766 Using the newly built target compiler, configure the target libraries.
1767 @item
1768 Build the target libraries.
1769 @end itemize
1771 The steps need not be done in precisely this order, since they are
1772 actually controlled by @file{Makefile} targets.
1774 @node Target Library Configure Scripts
1775 @subsection Target Library Configure Scripts
1777 There are a few things you must know in order to write a configure
1778 script for a target library.  This is just a quick sketch, and beginners
1779 shouldn't worry if they don't follow everything here.
1781 The target libraries are configured and built using a newly built target
1782 compiler.  There may not be any startup files or libraries for this
1783 target compiler.  In fact, those files will probably be built as part of
1784 some target library, which naturally means that they will not exist when
1785 your target library is configured.
1787 This means that the configure script for a target library may not use
1788 any test which requires doing a link.  This unfortunately includes many
1789 useful autoconf macros, such as @samp{AC_CHECK_FUNCS}.  autoconf macros
1790 which do a compile but not a link, such as @samp{AC_CHECK_HEADERS}, may
1791 be used.
1793 This is a severe restriction, but normally not a fatal one, as target
1794 libraries can often assume the presence of other target libraries, and
1795 thus know which functions will be available.
1797 As of this writing, the autoconf macro @samp{AC_PROG_CC} does a link to
1798 make sure that the compiler works.  This may fail in a target library,
1799 so target libraries must use a different set of macros to locate the
1800 compiler.  See the @file{configure.in} file in a directory like
1801 @file{libiberty} or @file{libgloss} for an example.
1803 As noted in the previous section, target libraries are sometimes built
1804 in directories which are siblings to the host tools, and are sometimes
1805 built in a subdirectory.  The @samp{--with-target-subdir} configure
1806 option will be passed when the library is configured.  Its value will be
1807 an empty string if the target library is a sibling.  Its value will be
1808 the name of the subdirectory if the target library is in a subdirectory.
1810 If the overall build is not a native build (i.e., the overall configure
1811 used the @samp{--target} option), then the library will be configured
1812 with the @samp{--with-cross-host} option.  The value of this option will
1813 be the host system of the overall build.  Recall that the host system of
1814 the library will be the target of the overall build.  If the overall
1815 build is a native build, the @samp{--with-cross-host} option will not be
1816 used.
1818 A library which can be built both standalone and as a target library may
1819 want to install itself into different directories depending upon the
1820 case.  When built standalone, or when built native, the library should
1821 be installed in @samp{$(libdir)}.  When built as a target library which
1822 is not native, the library should be installed in @samp{$(tooldir)/lib}.
1823 The @samp{--with-cross-host} option may be used to distinguish these
1824 cases.
1826 This same test of @samp{--with-cross-host} may be used to see whether it
1827 is OK to use link tests in the configure script.  If the
1828 @samp{--with-cross-host} option is not used, then the library is being
1829 built either standalone or native, and a link should work.
1831 @node Make Targets in Cygnus Tree
1832 @subsection Make Targets in Cygnus Tree
1834 The top level @file{Makefile} in the Cygnus tree defines targets for
1835 every known subdirectory.
1837 For every subdirectory @var{dir} which holds a host library or program,
1838 the @file{Makefile} target @samp{all-@var{dir}} will build that library
1839 or program.
1841 There are dependencies among host tools.  For example, building gcc
1842 requires first building gas, because the gcc build process invokes the
1843 target assembler.  These dependencies are reflected in the top level
1844 @file{Makefile}.
1846 For every subdirectory @var{dir} which holds a target library, the
1847 @file{Makefile} target @samp{configure-target-@var{dir}} will configure
1848 that library.  The @file{Makefile} target @samp{all-target-@var{dir}}
1849 will build that library.
1851 Every @samp{configure-target-@var{dir}} target depends upon
1852 @samp{all-gcc}, since gcc, the target compiler, is required to configure
1853 the tool.  Every @samp{all-target-@var{dir}} target depends upon the
1854 corresponding @samp{configure-target-@var{dir}} target.
1856 There are several other targets which may be of interest for each
1857 directory: @samp{install-@var{dir}}, @samp{clean-@var{dir}}, and
1858 @samp{check-@var{dir}}.  There are also corresponding @samp{target}
1859 versions of these for the target libraries , such as
1860 @samp{install-target-@var{dir}}.
1862 @node Target libiberty
1863 @subsection Target libiberty
1865 The @file{libiberty} subdirectory is currently a special case, in that
1866 it is the only directory which is built both using the host compiler and
1867 using the target compiler.
1869 This is because the files in @file{libiberty} are used when building the
1870 host tools, and they are also incorporated into the @file{libstdc++}
1871 target library as support code.
1873 This duality does not pose any particular difficulties.  It means that
1874 there are targets for both @samp{all-libiberty} and
1875 @samp{all-target-libiberty}.
1877 In a native configuration, when target libraries are not built in a
1878 subdirectory, the same objects are normally used as both the host build
1879 and the target build.  This is normally OK, since libiberty contains
1880 only C code, and in a native configuration the results of the host
1881 compiler and the target compiler are normally interoperable.
1883 Irix 6 is again an exception here, since the SGI native compiler
1884 defaults to using the @samp{O32} ABI, and gcc defaults to using the
1885 @samp{N32} ABI.  On Irix 6, the target libraries are built in a
1886 subdirectory even for a native configuration, avoiding this problem.
1888 There are currently no other libraries built for both the host and the
1889 target, but there is no conceptual problem with adding more.
1891 @node Canadian Cross
1892 @chapter Canadian Cross
1893 @cindex canadian cross
1894 @cindex building with a cross compiler
1895 @cindex cross compiler, building with
1897 It is possible to use the GNU configure and build system to build a
1898 program which will run on a system which is different from the system on
1899 which the tools are built.  In other words, it is possible to build
1900 programs using a cross compiler.
1902 This is referred to as a @dfn{Canadian Cross}.
1904 @menu
1905 * Canadian Cross Example::              Canadian Cross Example.
1906 * Canadian Cross Concepts::             Canadian Cross Concepts.
1907 * Build Cross Host Tools::              Build Cross Host Tools.
1908 * Build and Host Options::              Build and Host Options.
1909 * CCross not in Cygnus Tree::           Canadian Cross not in Cygnus Tree.
1910 * CCross in Cygnus Tree::               Canadian Cross in Cygnus Tree.
1911 * Supporting Canadian Cross::           Supporting Canadian Cross.
1912 @end menu
1914 @node Canadian Cross Example
1915 @section Canadian Cross Example
1917 Here is an example of a Canadian Cross.
1919 While running on a GNU/Linux, you can build a program which will run on
1920 a Solaris system.  You would use a GNU/Linux cross Solaris compiler to
1921 build the program.
1923 Of course, you could not run the resulting program on your GNU/Linux
1924 system.  You would have to copy it over to a Solaris system before you
1925 would run it.
1927 Of course, you could also simply build the programs on the Solaris
1928 system in the first place.  However, perhaps the Solaris system is not
1929 available for some reason; perhaps you actually don't have one, but you
1930 want to build the tools for somebody else to use.  Or perhaps your
1931 GNU/Linux system is much faster than your Solaris system.
1933 A Canadian Cross build is most frequently used when building programs to
1934 run on a non-Unix system, such as DOS or Windows.  It may be simpler to
1935 configure and build on a Unix system than to support the configuration
1936 machinery on a non-Unix system.
1938 @node Canadian Cross Concepts
1939 @section Canadian Cross Concepts
1941 When building a Canadian Cross, there are at least two different systems
1942 involved: the system on which the tools are being built, and the system
1943 on which the tools will run.
1945 The system on which the tools are being built is called the @dfn{build}
1946 system.
1948 The system on which the tools will run is called the host system.
1950 For example, if you are building a Solaris program on a GNU/Linux
1951 system, as in the previous section, the build system would be GNU/Linux,
1952 and the host system would be Solaris.
1954 It is, of course, possible to build a cross compiler using a Canadian
1955 Cross (i.e., build a cross compiler using a cross compiler).  In this
1956 case, the system for which the resulting cross compiler generates code
1957 is called the target system.  (For a more complete discussion of host
1958 and target systems, @pxref{Host and Target}).
1960 An example of building a cross compiler using a Canadian Cross would be
1961 building a Windows cross MIPS ELF compiler on a GNU/Linux system.  In
1962 this case the build system would be GNU/Linux, the host system would be
1963 Windows, and the target system would be MIPS ELF.
1965 The name Canadian Cross comes from the case when the build, host, and
1966 target systems are all different.  At the time that these issues were
1967 all being hashed out, Canada had three national political parties.
1969 @node Build Cross Host Tools
1970 @section Build Cross Host Tools
1972 In order to configure a program for a Canadian Cross build, you must
1973 first build and install the set of cross tools you will use to build the
1974 program.
1976 These tools will be build cross host tools.  That is, they will run on
1977 the build system, and will produce code that runs on the host system.
1979 It is easy to confuse the meaning of build and host here.  Always
1980 remember that the build system is where you are doing the build, and the
1981 host system is where the resulting program will run.  Therefore, you
1982 need a build cross host compiler.
1984 In general, you must have a complete cross environment in order to do
1985 the build.  This normally means a cross compiler, cross assembler, and
1986 so forth, as well as libraries and include files for the host system.
1988 @node Build and Host Options
1989 @section Build and Host Options
1990 @cindex configuring a canadian cross
1991 @cindex canadian cross, configuring
1993 When you run @file{configure}, you must use both the @samp{--build} and
1994 @samp{--host} options.
1996 @cindex @samp{--build} option
1997 @cindex build option
1998 @cindex configure build system
1999 The @samp{--build} option is used to specify the configuration name of
2000 the build system.  This can normally be the result of running the
2001 @file{config.guess} shell script, and it is reasonable to use
2002 @samp{--build=`config.guess`}.
2004 @cindex @samp{--host} option
2005 @cindex host option
2006 @cindex configure host
2007 The @samp{--host} option is used to specify the configuration name of
2008 the host system.
2010 As we explained earlier, @file{config.guess} is used to set the default
2011 value for the @samp{--host} option (@pxref{Using the Host Type}).  We
2012 can now see that since @file{config.guess} returns the type of system on
2013 which it is run, it really identifies the build system.  Since the host
2014 system is normally the same as the build system (i.e., people do not
2015 normally build using a cross compiler), it is reasonable to use the
2016 result of @file{config.guess} as the default for the host system when
2017 the @samp{--host} option is not used.
2019 It might seem that if the @samp{--host} option were used without the
2020 @samp{--build} option that the configure script could run
2021 @file{config.guess} to determine the build system, and presume a
2022 Canadian Cross if the result of @file{config.guess} differed from the
2023 @samp{--host} option.  However, for historical reasons, some configure
2024 scripts are routinely run using an explicit @samp{--host} option, rather
2025 than using the default from @file{config.guess}.  As noted earlier, it
2026 is difficult or impossible to reliably compare configuration names
2027 (@pxref{Using the Target Type}).  Therefore, by convention, if the
2028 @samp{--host} option is used, but the @samp{--build} option is not used,
2029 then the build system defaults to the host system.
2031 @node CCross not in Cygnus Tree
2032 @section Canadian Cross not in Cygnus Tree.
2034 If you are not using the Cygnus tree, you must explicitly specify the
2035 cross tools which you want to use to build the program.  This is done by
2036 setting environment variables before running the @file{configure}
2037 script.
2039 You must normally set at least the environment variables @samp{CC},
2040 @samp{AR}, and @samp{RANLIB} to the cross tools which you want to use to
2041 build.
2043 For some programs, you must set additional cross tools as well, such as
2044 @samp{AS}, @samp{LD}, or @samp{NM}.
2046 You would set these environment variables to the build cross tools which
2047 you are going to use.
2049 For example, if you are building a Solaris program on a GNU/Linux
2050 system, and your GNU/Linux cross Solaris compiler were named
2051 @samp{solaris-gcc}, then you would set the environment variable
2052 @samp{CC} to @samp{solaris-gcc}.
2054 @node CCross in Cygnus Tree
2055 @section Canadian Cross in Cygnus Tree
2056 @cindex canadian cross in cygnus tree
2058 This section describes configuring and building a Canadian Cross when
2059 using the Cygnus tree.
2061 @menu
2062 * Standard Cygnus CCross::      Building a Normal Program.
2063 * Cross Cygnus CCross::         Building a Cross Program.
2064 @end menu
2066 @node Standard Cygnus CCross
2067 @subsection Building a Normal Program
2069 When configuring a Canadian Cross in the Cygnus tree, all the
2070 appropriate environment variables are automatically set to
2071 @samp{@var{host}-@var{tool}}, where @var{host} is the value used for the
2072 @samp{--host} option, and @var{tool} is the name of the tool (e.g.,
2073 @samp{gcc}, @samp{as}, etc.).  These tools must be on your @samp{PATH}.
2075 Adding a prefix of @var{host} will give the usual name for the build
2076 cross host tools.  To see this, consider that when these cross tools
2077 were built, they were configured to run on the build system and to
2078 produce code for the host system.  That is, they were configured with a
2079 @samp{--target} option that is the same as the system which we are now
2080 calling the host.  Recall that the default name for installed cross
2081 tools uses the target system as a prefix (@pxref{Using the Target
2082 Type}).  Since that is the system which we are now calling the host,
2083 @var{host} is the right prefix to use.
2085 For example, if you configure with @samp{--build=i386-linux-gnu} and
2086 @samp{--host=solaris}, then the Cygnus tree will automatically default
2087 to using the compiler @samp{solaris-gcc}.  You must have previously
2088 built and installed this compiler, probably by doing a build with no
2089 @samp{--host} option and with a @samp{--target} option of
2090 @samp{solaris}.
2092 @node Cross Cygnus CCross
2093 @subsection Building a Cross Program
2095 There are additional considerations if you want to build a cross
2096 compiler, rather than a native compiler, in the Cygnus tree using a
2097 Canadian Cross.
2099 When you build a cross compiler using the Cygnus tree, then the target
2100 libraries will normally be built with the newly built target compiler
2101 (@pxref{Host and Target Libraries}).  However, this will not work when
2102 building with a Canadian Cross.  This is because the newly built target
2103 compiler will be a program which runs on the host system, and therefore
2104 will not be able to run on the build system.
2106 Therefore, when building a cross compiler with the Cygnus tree, you must
2107 first install a set of build cross target tools.  These tools will be
2108 used when building the target libraries.
2110 Note that this is not a requirement of a Canadian Cross in general.  For
2111 example, it would be possible to build just the host cross target tools
2112 on the build system, to copy the tools to the host system, and to build
2113 the target libraries on the host system.  The requirement for build
2114 cross target tools is imposed by the Cygnus tree, which expects to be
2115 able to build both host programs and target libraries in a single
2116 @samp{configure}/@samp{make} step.  Because it builds these in a single
2117 step, it expects to be able to build the target libraries on the build
2118 system, which means that it must use a build cross target toolchain.
2120 For example, suppose you want to build a Windows cross MIPS ELF compiler
2121 on a GNU/Linux system.  You must have previously installed both a
2122 GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF
2123 compiler.
2125 In order to build the Windows (configuration name @samp{i386-cygwin32})
2126 cross MIPS ELF (configure name @samp{mips-elf}) compiler, you might
2127 execute the following commands (long command lines are broken across
2128 lines with a trailing backslash as a continuation character).
2130 @example
2131 mkdir linux-x-cygwin32
2132 cd linux-x-cygwin32
2133 @var{srcdir}/configure --target i386-cygwin32 --prefix=@var{installdir} \
2134   --exec-prefix=@var{installdir}/H-i386-linux
2135 make
2136 make install
2137 cd ..
2138 mkdir linux-x-mips-elf
2139 cd linux-x-mips-elf
2140 @var{srcdir}/configure --target mips-elf --prefix=@var{installdir} \
2141   --exec-prefix=@var{installdir}/H-i386-linux
2142 make
2143 make install
2144 cd ..
2145 mkdir cygwin32-x-mips-elf
2146 cd cygwin32-x-mips-elf
2147 @var{srcdir}/configure --build=i386-linux-gnu --host=i386-cygwin32 \
2148   --target=mips-elf --prefix=@var{wininstalldir} \
2149   --exec-prefix=@var{wininstalldir}/H-i386-cygwin32
2150 make
2151 make install
2152 @end example
2154 You would then copy the contents of @var{wininstalldir} over to the
2155 Windows machine, and run the resulting programs.
2157 @node Supporting Canadian Cross
2158 @section Supporting Canadian Cross
2160 If you want to make it possible to build a program you are developing
2161 using a Canadian Cross, you must take some care when writing your
2162 configure and make rules.  Simple cases will normally work correctly.
2163 However, it is not hard to write configure and make tests which will
2164 fail in a Canadian Cross.
2166 @menu
2167 * CCross in Configure::         Supporting Canadian Cross in Configure Scripts.
2168 * CCross in Make::              Supporting Canadian Cross in Makefiles.
2169 @end menu
2171 @node CCross in Configure
2172 @subsection Supporting Canadian Cross in Configure Scripts
2173 @cindex canadian cross in configure
2175 In a @file{configure.in} file, after calling @samp{AC_PROG_CC}, you can
2176 find out whether this is a Canadian Cross configure by examining the
2177 shell variable @samp{cross_compiling}.  In a Canadian Cross, which means
2178 that the compiler is a cross compiler, @samp{cross_compiling} will be
2179 @samp{yes}.  In a normal configuration, @samp{cross_compiling} will be
2180 @samp{no}.
2182 You ordinarily do not need to know the type of the build system in a
2183 configure script.  However, if you do need that information, you can get
2184 it by using the macro @samp{AC_CANONICAL_SYSTEM}, the same macro that is
2185 used to determine the target system.  This macro will set the variables
2186 @samp{build}, @samp{build_alias}, @samp{build_cpu}, @samp{build_vendor},
2187 and @samp{build_os}, which correspond to the similar @samp{target} and
2188 @samp{host} variables, except that they describe the build system.
2190 When writing tests in @file{configure.in}, you must remember that you
2191 want to test the host environment, not the build environment.
2193 Macros like @samp{AC_CHECK_FUNCS} which use the compiler will test the
2194 host environment.  That is because the tests will be done by running the
2195 compiler, which is actually a build cross host compiler.  If the
2196 compiler can find the function, that means that the function is present
2197 in the host environment.
2199 Tests like @samp{test -f /dev/ptyp0}, on the other hand, will test the
2200 build environment.  Remember that the configure script is running on the
2201 build system, not the host system.  If your configure scripts examines
2202 files, those files will be on the build system.  Whatever you determine
2203 based on those files may or may not be the case on the host system.
2205 Most autoconf macros will work correctly for a Canadian Cross.  The main
2206 exception is @samp{AC_TRY_RUN}.  This macro tries to compile and run a
2207 test program.  This will fail in a Canadian Cross, because the program
2208 will be compiled for the host system, which means that it will not run
2209 on the build system.
2211 The @samp{AC_TRY_RUN} macro provides an optional argument to tell the
2212 configure script what to do in a Canadian Cross.  If that argument is
2213 not present, you will get a warning when you run @samp{autoconf}:
2214 @smallexample
2215 warning: AC_TRY_RUN called without default to allow cross compiling
2216 @end smallexample
2217 @noindent
2218 This tells you that the resulting @file{configure} script will not work
2219 with a Canadian Cross.
2221 In some cases while it may better to perform a test at configure time,
2222 it is also possible to perform the test at run time.  In such a case you
2223 can use the cross compiling argument to @samp{AC_TRY_RUN} to tell your
2224 program that the test could not be performed at configure time.
2226 There are a few other autoconf macros which will not work correctly with
2227 a Canadian Cross: a partial list is @samp{AC_FUNC_GETPGRP},
2228 @samp{AC_FUNC_SETPGRP}, @samp{AC_FUNC_SETVBUF_REVERSED}, and
2229 @samp{AC_SYS_RESTARTABLE_SYSCALLS}.  The @samp{AC_CHECK_SIZEOF} macro is
2230 generally not very useful with a Canadian Cross; it permits an optional
2231 argument indicating the default size, but there is no way to know what
2232 the correct default should be.
2234 @node CCross in Make
2235 @subsection Supporting Canadian Cross in Makefiles.
2236 @cindex canadian cross in makefile
2238 The main Canadian Cross issue in a @file{Makefile} arises when you want
2239 to use a subsidiary program to generate code or data which you will then
2240 include in your real program.
2242 If you compile this subsidiary program using @samp{$(CC)} in the usual
2243 way, you will not be able to run it.  This is because @samp{$(CC)} will
2244 build a program for the host system, but the program is being built on
2245 the build system.
2247 You must instead use a compiler for the build system, rather than the
2248 host system.  In the Cygnus tree, this make variable
2249 @samp{$(CC_FOR_BUILD)} will hold a compiler for the build system.
2251 Note that you should not include @file{config.h} in a file you are
2252 compiling with @samp{$(CC_FOR_BUILD)}.  The @file{configure} script will
2253 build @file{config.h} with information for the host system.  However,
2254 you are compiling the file using a compiler for the build system (a
2255 native compiler).  Subsidiary programs are normally simple filters which
2256 do no user interaction, and it is normally possible to write them in a
2257 highly portable fashion so that the absence of @file{config.h} is not
2258 crucial.
2260 @cindex @samp{HOST_CC}
2261 The gcc @file{Makefile.in} shows a complex situation in which certain
2262 files, such as @file{rtl.c}, must be compiled into both subsidiary
2263 programs run on the build system and into the final program.  This
2264 approach may be of interest for advanced build system hackers.  Note
2265 that the build system compiler is rather confusingly called
2266 @samp{HOST_CC}.
2268 @node Cygnus Configure
2269 @chapter Cygnus Configure
2270 @cindex cygnus configure
2272 The Cygnus configure script predates autoconf.  All of its interesting
2273 features have been incorporated into autoconf.  No new programs should
2274 be written to use the Cygnus configure script.
2276 However, the Cygnus configure script is still used in a few places: at
2277 the top of the Cygnus tree and in a few target libraries in the Cygnus
2278 tree.  Until those uses have been replaced with autoconf, some brief
2279 notes are appropriate here.  This is not complete documentation, but it
2280 should be possible to use this as a guide while examining the scripts
2281 themselves.
2283 @menu
2284 * Cygnus Configure Basics::             Cygnus Configure Basics.
2285 * Cygnus Configure in C++ Libraries::   Cygnus Configure in C++ Libraries.
2286 @end menu
2288 @node Cygnus Configure Basics
2289 @section Cygnus Configure Basics
2291 Cygnus configure does not use any generated files; there is no program
2292 corresponding to @samp{autoconf}.  Instead, there is a single shell
2293 script named @samp{configure} which may be found at the top of the
2294 Cygnus tree.  This shell script was written by hand; it was not
2295 generated by autoconf, and it is incorrect, and indeed harmful, to run
2296 @samp{autoconf} in the top level of a Cygnus tree.
2298 Cygnus configure works in a particular directory by examining the file
2299 @file{configure.in} in that directory.  That file is broken into four
2300 separate shell scripts.
2302 The first is the contents of @file{configure.in} up to a line that
2303 starts with @samp{# per-host:}.  This is the common part.
2305 The second is the rest of @file{configure.in} up to a line that starts
2306 with @samp{# per-target:}.  This is the per host part.
2308 The third is the rest of @file{configure.in} up to a line that starts
2309 with @samp{# post-target:}.  This is the per target part.
2311 The fourth is the remainder of @file{configure.in}.  This is the post
2312 target part.
2314 If any of these comment lines are missing, the corresponding shell
2315 script is empty.
2317 Cygnus configure will first execute the common part.  This must set the
2318 shell variable @samp{srctrigger} to the name of a source file, to
2319 confirm that Cygnus configure is looking at the right directory.  This
2320 may set the shell variables @samp{package_makefile_frag} and
2321 @samp{package_makefile_rules_frag}.
2323 Cygnus configure will next set the @samp{build} and @samp{host} shell
2324 variables, and execute the per host part.  This may set the shell
2325 variable @samp{host_makefile_frag}.
2327 Cygnus configure will next set the @samp{target} variable, and execute
2328 the per target part.  This may set the shell variable
2329 @samp{target_makefile_frag}.
2331 Any of these scripts may set the @samp{subdirs} shell variable.  This
2332 variable is a list of subdirectories where a @file{Makefile.in} file may
2333 be found.  Cygnus configure will automatically look for a
2334 @file{Makefile.in} file in the current directory.  The @samp{subdirs}
2335 shell variable is not normally used, and I believe that the only
2336 directory which uses it at present is @file{newlib}.
2338 For each @file{Makefile.in}, Cygnus configure will automatically create
2339 a @file{Makefile} by adding definitions for @samp{make} variables such
2340 as @samp{host} and @samp{target}, and automatically editing the values
2341 of @samp{make} variables such as @samp{prefix} if they are present.
2343 Also, if any of the @samp{makefile_frag} shell variables are set, Cygnus
2344 configure will interpret them as file names relative to either the
2345 working directory or the source directory, and will read the contents of
2346 the file into the generated @file{Makefile}.  The file contents will be
2347 read in after the first line in @file{Makefile.in} which starts with
2348 @samp{####}.
2350 These @file{Makefile} fragments are used to customize behaviour for a
2351 particular host or target.  They serve to select particular files to
2352 compile, and to define particular preprocessor macros by providing
2353 values for @samp{make} variables which are then used during compilation.
2354 Cygnus configure, unlike autoconf, normally does not do feature tests,
2355 and normally requires support to be added manually for each new host.
2357 The @file{Makefile} fragment support is similar to the autoconf
2358 @samp{AC_SUBST_FILE} macro.
2360 After creating each @file{Makefile}, the post target script will be run
2361 (i.e., it may be run several times).  This script may further customize
2362 the @file{Makefile}.  When it is run, the shell variable @samp{Makefile}
2363 will hold the name of the @file{Makefile}, including the appropriate
2364 directory component.
2366 Like an autoconf generated @file{configure} script, Cygnus configure
2367 will create a file named @file{config.status} which, when run, will
2368 automatically recreate the configuration.  The @file{config.status} file
2369 will simply execute the Cygnus configure script again with the
2370 appropriate arguments.
2372 Any of the parts of @file{configure.in} may set the shell variables
2373 @samp{files} and @samp{links}.  Cygnus configure will set up symlinks
2374 from the names in @samp{links} to the files named in @samp{files}.  This
2375 is similar to the autoconf @samp{AC_LINK_FILES} macro.
2377 Finally, any of the parts of @file{configure.in} may set the shell
2378 variable @samp{configdirs} to a set of subdirectories.  If it is set,
2379 Cygnus configure will recursively run the configure process in each
2380 subdirectory.  If the subdirectory uses Cygnus configure, it will
2381 contain a @file{configure.in} file but no @file{configure} file, in
2382 which case Cygnus configure will invoke itself recursively.  If the
2383 subdirectory has a @file{configure} file, Cygnus configure assumes that
2384 it is an autoconf generated @file{configure} script, and simply invokes
2385 it directly.
2387 @node Cygnus Configure in C++ Libraries
2388 @section Cygnus Configure in C++ Libraries
2389 @cindex @file{libstdc++} configure
2390 @cindex @file{libio} configure
2391 @cindex @file{libg++} configure
2393 The C++ library configure system, written by Per Bothner, deserves
2394 special mention.  It uses Cygnus configure, but it does feature testing
2395 like that done by autoconf generated @file{configure} scripts.  This
2396 approach is used in the libraries @file{libio}, @file{libstdc++}, and
2397 @file{libg++}.
2399 Most of the @file{Makefile} information is written out by the shell
2400 script @file{libio/config.shared}.  Each @file{configure.in} file sets
2401 certain shell variables, and then invokes @file{config.shared} to create
2402 two package @file{Makefile} fragments.  These fragments are then
2403 incorporated into the resulting @file{Makefile} by the Cygnus configure
2404 script.
2406 The file @file{_G_config.h} is created in the @file{libio} object
2407 directory by running the shell script @file{libio/gen-params}.  This
2408 shell script uses feature tests to define macros and typedefs in
2409 @file{_G_config.h}.
2411 @node Multilibs
2412 @chapter Multilibs
2413 @cindex multilibs
2415 For some targets gcc may have different processor requirements depending
2416 upon command line options.  An obvious example is the
2417 @samp{-msoft-float} option supported on several processors.  This option
2418 means that the floating point registers are not available, which means
2419 that floating point operations must be done by calling an emulation
2420 subroutine rather than by using machine instructions.
2422 For such options, gcc is often configured to compile target libraries
2423 twice: once with @samp{-msoft-float} and once without.  When gcc
2424 compiles target libraries more than once, the resulting libraries are
2425 called @dfn{multilibs}.
2427 Multilibs are not really part of the GNU configure and build system, but
2428 we discuss them here since they require support in the @file{configure}
2429 scripts and @file{Makefile}s used for target libraries.
2431 @menu
2432 * Multilibs in gcc::                    Multilibs in gcc.
2433 * Multilibs in Target Libraries::       Multilibs in Target Libraries.
2434 @end menu
2436 @node Multilibs in gcc
2437 @section Multilibs in gcc
2439 In gcc, multilibs are defined by setting the variable
2440 @samp{MULTILIB_OPTIONS} in the target @file{Makefile} fragment.  Several
2441 other @samp{MULTILIB} variables may also be defined there.  @xref{Target
2442 Fragment, , The Target Makefile Fragment, gcc, Using and Porting GNU
2443 CC}.
2445 If you have built gcc, you can see what multilibs it uses by running it
2446 with the @samp{-print-multi-lib} option.  The output @samp{.;} means
2447 that no multilibs are used.  In general, the output is a sequence of
2448 lines, one per multilib.  The first part of each line, up to the
2449 @samp{;}, is the name of the multilib directory.  The second part is a
2450 list of compiler options separated by @samp{@@} characters.
2452 Multilibs are built in a tree of directories.  The top of the tree,
2453 represented by @samp{.} in the list of multilib directories, is the
2454 default library to use when no special compiler options are used.  The
2455 subdirectories of the tree hold versions of the library to use when
2456 particular compiler options are used.
2458 @node Multilibs in Target Libraries
2459 @section Multilibs in Target Libraries
2461 The target libraries in the Cygnus tree are automatically built with
2462 multilibs.  That means that each library is built multiple times.
2464 This default is set in the top level @file{configure.in} file, by adding
2465 @samp{--enable-multilib} to the list of arguments passed to configure
2466 when it is run for the target libraries (@pxref{Host and Target
2467 Libraries}).
2469 Each target library uses the shell script @file{config-ml.in}, written
2470 by Doug Evans, to prepare to build target libraries.  This shell script
2471 is invoked after the @file{Makefile} has been created by the
2472 @file{configure} script.  If multilibs are not enabled, it does nothing,
2473 otherwise it modifies the @file{Makefile} to support multilibs.
2475 The @file{config-ml.in} script makes one copy of the @file{Makefile} for
2476 each multilib in the appropriate subdirectory.  When configuring in the
2477 source directory (which is not recommended), it will build a symlink
2478 tree of the sources in each subdirectory.
2480 The @file{config-ml.in} script sets several variables in the various
2481 @file{Makefile}s.  The @file{Makefile.in} must have definitions for
2482 these variables already; @file{config-ml.in} simply changes the existing
2483 values.  The @file{Makefile} should use default values for these
2484 variables which will do the right thing in the subdirectories.
2486 @table @samp
2487 @item MULTISRCTOP
2488 @file{config-ml.in} will set this to a sequence of @samp{../} strings,
2489 where the number of strings is the number of multilib levels in the
2490 source tree.  The default value should be the empty string.
2491 @item MULTIBUILDTOP
2492 @file{config-ml.in} will set this to a sequence of @samp{../} strings,
2493 where the number of strings is number of multilib levels in the object
2494 directory.  The default value should be the empty string.  This will
2495 differ from @samp{MULTISRCTOP} when configuring in the source tree
2496 (which is not recommended).
2497 @item MULTIDIRS
2498 In the top level @file{Makefile} only, @file{config-ml.in} will set this
2499 to the list of multilib subdirectories.  The default value should be the
2500 empty string.
2501 @item MULTISUBDIR
2502 @file{config-ml.in} will set this to the installed subdirectory name to
2503 use for this subdirectory, with a leading @samp{/}.  The default value
2504 shold be the empty string.
2505 @item MULTIDO
2506 @itemx MULTICLEAN
2507 In the top level @file{Makefile} only, @file{config-ml.in} will set
2508 these variables to commands to use when doing a recursive make.  These
2509 variables should both default to the string @samp{true}, so that by
2510 default nothing happens.
2511 @end table
2513 All references to the parent of the source directory should use the
2514 variable @samp{MULTISRCTOP}.  Instead of writing @samp{$(srcdir)/..},
2515 you must write @samp{$(srcdir)/$(MULTISRCTOP)..}.
2517 Similarly, references to the parent of the object directory should use
2518 the variable @samp{MULTIBUILDTOP}.
2520 In the installation target, the libraries should be installed in the
2521 subdirectory @samp{MULTISUBDIR}.  Instead of installing
2522 @samp{$(libdir)/libfoo.a}, install
2523 @samp{$(libdir)$(MULTISUBDIR)/libfoo.a}.
2525 The @file{config-ml.in} script also modifies the top level
2526 @file{Makefile} to add @samp{multi-do} and @samp{multi-clean} targets
2527 which are used when building multilibs.
2529 The default target of the @file{Makefile} should include the following
2530 command:
2531 @smallexample
2532 @@$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
2533 @end smallexample
2534 @noindent
2535 This assumes that @samp{$(FLAGS_TO_PASS)} is defined as a set of
2536 variables to pass to a recursive invocation of @samp{make}.  This will
2537 build all the multilibs.  Note that the default value of @samp{MULTIDO}
2538 is @samp{true}, so by default this command will do nothing.  It will
2539 only do something in the top level @file{Makefile} if multilibs were
2540 enabled.
2542 The @samp{install} target of the @file{Makefile} should include the
2543 following command:
2544 @smallexample
2545 @@$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
2546 @end smallexample
2548 In general, any operation, other than clean, which should be performed
2549 on all the multilibs should use a @samp{$(MULTIDO)} line, setting the
2550 variable @samp{DO} to the target of each recursive call to @samp{make}.
2552 The @samp{clean} targets (@samp{clean}, @samp{mostlyclean}, etc.) should
2553 use @samp{$(MULTICLEAN)}.  For example, the @samp{clean} target should
2554 do this:
2555 @smallexample
2556 @@$(MULTICLEAN) DO=clean multi-clean
2557 @end smallexample
2559 @node FAQ
2560 @chapter Frequently Asked Questions
2562 @table @asis
2563 @item Which do I run first, @samp{autoconf} or @samp{automake}?
2564 Except when you first add autoconf or automake support to a package, you
2565 shouldn't run either by hand.  Instead, configure with the
2566 @samp{--enable-maintainer-mode} option, and let @samp{make} take care of
2569 @cindex undefined macros
2570 @item @samp{autoconf} says something about undefined macros.
2571 This means that you have macros in your @file{configure.in} which are
2572 not defined by @samp{autoconf}.  You may be using an old version of
2573 @samp{autoconf}; try building and installing a newer one.  Make sure the
2574 newly installled @samp{autoconf} is first on your @samp{PATH}.  Also,
2575 see the next question.
2577 @cindex @samp{CY_GNU_GETTEXT} in @file{configure}
2578 @cindex @samp{AM_PROG_LIBTOOL} in @file{configure}
2579 @item My @file{configure} script has stuff like @samp{CY_GNU_GETTEXT} in it.
2580 This means that you have macros in your @file{configure.in} which should
2581 be defined in your @file{aclocal.m4} file, but aren't.  This usually
2582 means that @samp{aclocal} was not able to appropriate definitions of the
2583 macros.  Make sure that you have installed all the packages you need.
2584 In particular, make sure that you have installed libtool (this is where
2585 @samp{AM_PROG_LIBTOOL} is defined) and gettext (this is where
2586 @samp{CY_GNU_GETTEXT} is defined, at least in the Cygnus version of
2587 gettext).
2589 @cindex @file{Makefile}, garbage characters
2590 @item My @file{Makefile} has @samp{@@} characters in it.
2591 This may mean that you tried to use an autoconf substitution in your
2592 @file{Makefile.in} without adding the appropriate @samp{AC_SUBST} call
2593 to your @file{configure} script.  Or it may just mean that you need to
2594 rebuild @file{Makefile} in your build directory.  To rebuild
2595 @file{Makefile} from @file{Makefile.in}, run the shell script
2596 @file{config.status} with no arguments.  If you need to force
2597 @file{configure} to run again, first run @samp{config.status --recheck}.
2598 These runs are normally done automatically by @file{Makefile} targets,
2599 but if your @file{Makefile} has gotten messed up you'll need to help
2600 them along.
2602 @cindex @samp{config.status --recheck}
2603 @item Why do I have to run both @samp{config.status --recheck} and @samp{config.status}?
2604 Normally, you don't; they will be run automatically by @file{Makefile}
2605 targets.  If you do need to run them, use @samp{config.status --recheck}
2606 to run the @file{configure} script again with the same arguments as the
2607 first time you ran it.  Use @samp{config.status} (with no arguments) to
2608 regenerate all files (@file{Makefile}, @file{config.h}, etc.) based on
2609 the results of the configure script.  The two cases are separate because
2610 it isn't always necessary to regenerate all the files after running
2611 @samp{config.status --recheck}.  The @file{Makefile} targets generated
2612 by automake will use the environment variables @samp{CONFIG_FILES} and
2613 @samp{CONFIG_HEADERS} to only regenerate files as they are needed.
2615 @item What is the Cygnus tree?
2616 The Cygnus tree is used for various packages including gdb, the GNU
2617 binutils, and egcs.  It is also, of course, used for Cygnus releases.
2618 It is the build system which was developed at Cygnus, using the Cygnus
2619 configure script.  It permits building many different packages with a
2620 single configure and make.  The configure scripts in the tree are being
2621 converted to autoconf, but the general build structure remains intact.
2623 @item Why do I have to keep rebuilding and reinstalling the tools?
2624 I know, it's a pain.  Unfortunately, there are bugs in the tools
2625 themselves which need to be fixed, and each time that happens everybody
2626 who uses the tools need to reinstall new versions of them.  I don't know
2627 if there is going to be a clever fix until the tools stabilize.
2629 @item Why not just have a Cygnus tree @samp{make} target to update the tools?
2630 The tools unfortunately need to be installed before they can be used.
2631 That means that they must be built using an appropriate prefix, and it
2632 seems unwise to assume that every configuration uses an appropriate
2633 prefix.  It might be possible to make them work in place, or it might be
2634 possible to install them in some subdirectory; so far these approaches
2635 have not been implemented.
2636 @end table
2638 @node Index
2639 @unnumbered Index
2641 @printindex cp
2643 @contents
2644 @bye