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