1 |
6 |
jlechner |
\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
|