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