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