1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
|
<?xml version="1.0"?>
<guide self="general-concepts/autotools/">
<chapter>
<title>The Basics of Autotools</title>
<body>
<todo>
This is too long for <uri link="::general-concepts"/>. It needs to be split up and
moved somewhere, either to a top-level of its own or into <uri link="::appendices/"/>.
</todo>
<p>
An understanding of GNU autotools (<c>automake</c>, <c>autoconf</c> etc.) can be useful
when working with ebuilds:
</p>
<ul>
<li>
Finding and correcting build issues is often easier if the build system is
not seen simply as a scary black box.
</li>
<li>
The autotools input files can help when determining a package's build-time
dependencies.
</li>
<li>
The risk of accidentally breaking something by patching the wrong file at the
wrong time is greatly reduced if the relationship between the build system
files is understood.
</li>
</ul>
</body>
<section>
<title>Major Autotools Components</title>
<body>
<p>
Autotools is a collection of related packages which, when used together, remove
much of the difficulty involved in creating portable software. These tools,
together with a few relatively simple upstream-supplied input files, are used to
create the build system for a package.
</p>
<figure short="How autotools fits together" link="diagram.png">
A basic overview of how the main autotools components fit together.
</figure>
<p>
In a simple setup:
</p>
<ul>
<li>
The <c>autoconf</c> program produces a <c>configure</c> script from either
<c>configure.in</c> or <c>configure.ac</c> (see note below).
</li>
<li>
The <c>automake</c> program produces a <c>Makefile.in</c> from a <c>Makefile.am</c>.
</li>
<li>
The <c>configure</c> script is run to produce one or more <c>Makefile</c> files from
<c>Makefile.in</c> files.
</li>
<li>
The <c>make</c> program uses the <c>Makefile</c> to compile the program.
</li>
</ul>
<note>
The <c>configure.in</c> name used to be standard. However, the GNU
documentation now recommends <c>configure.ac</c> as it is more obvious which
program should be used when processing it. The files perform the same purpose
and have the same format <d/> the only difference is the name.
</note>
<p>
You may see autotools being used in a variety of phase
functions. Prior to EAPI2, the QA team preferred that the source
code be manipulated in <c>src_unpack</c><d/>the rationale being that
<c>src_unpack</c> handles "getting the package ready to be
compiled."
</p>
<p>
EAPI2, however, introduced a new phase function: <uri
link="::ebuild-writing/functions/src_prepare" />. This is now the
appropriate place to manipulate the source code prior to
configuration and compilation. In particular, <c>src_prepare</c> is
called before <uri link="::ebuild-writing/functions/src_configure"
/>, which usually expects the <c>configure</c> script to exist.
</p>
<p>
The <c>autoreconf</c> tool supposedly runs <c>autoconf</c> (and <c>automake</c>,
<c>autoheader</c>, <c>aclocal</c>, <c>autopoint</c> and <c>libtoolize</c>) as necessary.
Sometimes it works. Some packages ship a shell script named <c>autogen.sh</c> which
does the same thing (this is <e>not</e> related to <c>autogen</c>).
The autotools.eclass contains helper functions for the stand-alone tools with their
corresponding names e.g. <c>eautoconf</c> and <c>eautomake</c>.
</p>
<warning>
You must <b>not</b> attempt to modify any of the generated files in
between running <c>configure</c> and <c>make</c>. This can lead to autotools
trying to be clever and recreate the files, in turn leading to your changes
being removed. In some situations this will also result in <c>./configure</c>
arguments being silently dropped, which can give broken dependencies.
The best way to proceed is usually to work with the <c>.ac</c> / <c>.in</c> files
instead.
</warning>
</body>
</section>
<section>
<title>Simple Autotools Patching Example</title>
<body>
<p>
The following snippet illustrates the correct way to proceed after patching
either <c>Makefile.am</c> or <c>configure.ac</c>:
</p>
<codesample lang="ebuild">
EAPI=5
inherit autotools
src_prepare() {
# Remove problematic LDFLAGS declaration
sed -i -e '/^LDFLAGS/d' src/Makefile.am || die
# Rerun autotools
einfo "Regenerating autotools files..."
WANT_AUTOCONF=2.5 eautoconf
WANT_AUTOMAKE=1.9 eautomake
}
src_compile() {
econf $(use_enable nls)
emake
}
</codesample>
<p>
The <c>einfo</c> message before running autotools is not mandatory. However, these
steps can sometimes take a while and may produce no output, so it may make sense
to let the user know that something is still happening. See
<uri link="::ebuild-writing/messages"/>.
</p>
</body>
</section>
<section>
<title>The <c>configure.ac</c> File</title>
<body>
<p>
The <c>configure.ac</c> file is used to create the <c>./configure</c> script. It
consists of a series of macros which are processed and expanded by <c>autoconf</c>.
These macros can check for packages and libraries, handle <c>--enable</c> and
<c>--with</c> switches, and generate various files.
</p>
</body>
<subsection>
<title>Basic Format of <c>configure.ac</c></title>
<body>
<p>
The <c>configure.ac</c> file is a basic text file. Indenting and whitespace are
largely irrelevant. Comments are indicated by the string <c>dnl</c> (<c>dnl</c> is
actually a macro which discards the remainder of the input <d/> it stands for
"discard new line").
</p>
<p>
If the previous sentence made you uneasy, you should probably stop reading this
page. It gets far worse.
</p>
<p>
A typical file might start with something like the following:
</p>
<codesample lang="m4">
dnl Process this file with autoconf
AC_INIT(appname, 0.1)
AC_PREREQ(2.5)
AC_CONFIG_SRCDIR(src/main.c)
AC_CONFIG_AUX_DIR(config)
AM_INIT_AUTOMAKE(1.8)
</codesample>
<p>
The <c>AC_PREREQ</c> line, if present, tells you which <c>autoconf</c> version you
need. This is useful, because <c>autoconf</c> is not compatible between versions.
In the above example, we need <c>=autoconf-2.5*</c>. and we should
<c>export WANT_AUTOCONF="2.5"</c> (or use the <c>autoconf-2.59</c> script) when calling
<c>autoconf</c>.
</p>
<p>
The <c>AM_INIT_AUTOMAKE</c> line tells us which <c>automake</c> version we need.
Again, there is little chance that an <c>automake-1.7</c> script will work properly
with <c>automake-1.8</c>. Setting <c>WANT_AUTOMAKE="1.8"</c> in the environment can be
used to make an unversioned <c>automake</c> call run the correct version.
</p>
<note>
The <c>WANT_</c> variables are a Gentoo feature that originally came from
Mandrake. Other distributions may handle things differently.
</note>
<p>
Usually, some standard checks will follow:
</p>
<codesample lang="m4">
dnl Check for toolchain and install components
AC_PROG_CC
AC_PROG_INSTALL
AC_PROG_LN_S
AC_PROG_RANLIB
</codesample>
<p>
For non-standard applications, you may also see manual checks:
</p>
<codesample lang="m4">
dnl Check for sed
AC_CHECK_PROGS(regex_cmd, sed)
if test x$regex_cmd = "x" ; then
AC_MSG_ERROR([sed is required to build the data files.])
fi
</codesample>
<p>
You may also see checks for compiler features:
</p>
<codesample lang="m4">
dnl Check that our compiler can do const and inline
AC_C_CONST
AC_C_INLINE
</codesample>
<p>
Library and header checks:
</p>
<codesample lang="m4">
dnl Check for standard headers:
AC_HEADER_STDC
AC_HEADER_DIRENT
AC_CHECK_HEADERS([stdlib.h stdio.h libintl.h locale.h])
dnl Check for libraries:
AC_CHECK_LIB(ssl, SSL_free)
</codesample>
<p>
And function checks:
</p>
<codesample lang="m4">
dnl Check for functions:
AC_CHECK_FUNCS([setlocale strtol])
</codesample>
<p>
Often these will be all jumbled together without any useful comments. In some
cases, many of the checks done won't even be necessary for the application in
question <d/> most autotools code is copy/pasted rather than written from scratch,
and <c>autoscan</c> (a tool which helps write <c>configure.ac</c>) is sometimes
over-eager to add in checks.
</p>
<p>
The file will finish with some output functions:
</p>
<codesample lang="m4">
AM_CONFIG_HEADER(config.h)
AC_OUTPUT(Makefile src/Makefile nls/Makefile man/Makefile tests/Makefile)
</codesample>
<p>
These are used to make the <c>./configure</c> script generate the relevant files.
</p>
</body>
</subsection>
<subsection>
<title>Enable and Disable Checks</title>
<body>
<p>
So far we've only seen 'hard' dependencies. Many packages have <e>optional</e>
support for various extras (graphics toolkits, libraries which add
functionality, interpreters, features, ...). This is (if we're lucky) handled
via <c>--enable-foo</c> and <c>--disable-foo</c> switches to <c>./configure</c>. which
are generated from <c>autoconf</c> rules.
</p>
<p>
A simple <c>--enable</c> / <c>--disable</c> function might look something like the
following:
</p>
<codesample lang="m4">
AC_MSG_CHECKING(--enable-cscope argument)
AC_ARG_ENABLE(cscope,
[ --enable-cscope Include cscope interface.],
[enable_cscope=$enableval],
[enable_cscope="no"])
AC_MSG_RESULT($enable_cscope)
if test "$enable_cscope" = "yes"; then
AC_DEFINE(FEAT_CSCOPE)
fi
</codesample>
<p>
Sometimes more complicated checks are included based upon whether or not an
option is enabled. There are also some predefined macros which include
<c>AC_ARG_ENABLE</c>. so grepping <c>configure.ac</c> for <c>AC_ARG_ENABLE</c> may not
give a complete list. A better way is to use <c>./configure --help</c> and check
the output.
</p>
<important>
The third argument is used when a <c>--enable</c> or <c>--disable</c>
switch to <c>./configure</c> is provided, and the fourth is used when such a
switch is <e>not</e> passed. A common misconception is that the third is enable
and the fourth is disable <d/> this is <b>not</b> the case. You may encounter
packages that get this wrong.
</important>
<p>
A simple way to check that a package is using this macro properly is to
install the optional dependency, and then try all of <c>./configure</c>.
<c>./configure --enable-foo</c> and <c>./configure --disable-foo</c>. If the second
and third runs give the same results, something is wrong. If the first run gives
a <e>different</e> result to the second and third, there is a good chance that a
misunderstanding of the <c>AC_ARG_ENABLE</c> arguments is to blame.
</p>
</body>
</subsection>
<subsection>
<title>With and Without Checks</title>
<body>
<p>
A simple <c>--with</c> / <c>--without</c> check might look like:
</p>
<codesample lang="m4">
AC_MSG_CHECKING([whether to enable foo])
AC_ARG_WITH(foo,
[ --with-foo enable foo support],
with_foo=$withval,
with_foo=yes)
AC_MSG_RESULT($with_foo)
</codesample>
<p>
Again, the third argument is for 'specified' and the fourth for 'not specified',
and there are standard macros which include <c>with</c> options.
</p>
</body>
</subsection>
<subsection>
<title>Automatic Checks</title>
<body>
<p>
It's possible to write autoconf rules which bypass the manual enable / disable
convention (or which just ignore what the user asks for). If your package does
this, it must be fixed to avoid dependency problems.
</p>
<p>
The most common form is packages which simply use <c>AC_CHECK_LIB</c> to decide
whether or not to enable a feature. If you find a package which does this, you
<b>must</b> change the behaviour.
</p>
</body>
</subsection>
<subsection>
<title>Quoting Rules for <c>configure.ac</c></title>
<body>
<p>
Behind the scenes, <c>autoconf</c> makes heavy use of the <c>m4</c> macro processor to
do the work. The <c>m4</c> quote characters are set by <c>autoconf</c> to be <c>[</c> and
<c>]</c> for opening and closing quotes respectively. Using <c>"</c> or <c>'</c> may
produce unexpected results.
</p>
<p>
To include a literal left square bracket, the easiest thing to do is to use the
special string <c>@<:@</c>. For a right bracket, use <c>@:>@</c>.
</p>
<p>
For example:
</p>
<codesample lang="m4">
AC_MSG_RESULT(the first)
AC_MSG_RESULT([the second])
AC_MSG_RESULT("the third")
AC_MSG_RESULT(@<:@the fourth@:>@)
AC_MSG_RESULT([@<:@the fifth@:>@])
</codesample>
<p>
gives:
</p>
<pre>
the first
the second
"the third"
[the fourth]
[the fifth]
</pre>
<p>
When in doubt, it is generally safest to quote macro arguments using <c>[ ]</c>
rather than leaving things unquoted.
</p>
</body>
</subsection>
</section>
<section>
<title>The <c>Makefile.am</c> Files</title>
<body>
<p>
The <c>Makefile.am</c> file is processed by <c>automake</c> to create <c>Makefile.in</c>,
which is in turn processed by <c>configure</c> to create <c>Makefile</c>, which is in
turn used by <c>make</c> to build the software.
</p>
<p>
The basic format is like that of a <c>Makefile</c>. However, you will see various
'special' variables being set, rather than every rule being written manually.
</p>
<p>
A very simple example:
</p>
<codesample lang="make">
bin_PROGRAMS = myapp
myapp_SOURCES = myapp_commandline.c myapp.c
</codesample>
<p>
All the standard GNU rules will be generated, so <c>make</c>. <c>make clean</c>.
<c>make distclean</c>. <c>make dist</c> and so on will all work here.
</p>
<p>
You may also see some standard <c>Makefile</c> constructs showing up whenever there
isn't a standard <c>automake</c> way of handling a certain task. For example:
</p>
<codesample lang="make">
CLEANFILES = glep31check.1
man_MANS = glep31check.1
EXTRA_DIST = glep31check.in
%.1 : %.in
@regex_cmd@ -e "s,\@VERSION\@,$(VERSION),g" $? > $@
</codesample>
<p>
Here, the <c>@regex_cmd@</c> variable will be substituted with whatever
<c>configure</c> detects (<c>sed</c> in this case) when creating the <c>Makefile</c>.
This is handled via the macro <c>AC_SUBST(VARNAME)</c> in <c>configure.ac</c>.
</p>
</body>
<subsection>
<title>Makefile Variables</title>
<body>
<p>
Sometimes, badly behaved <c>Makefile.am</c> files will override user variables such
as <c>CFLAGS</c>. This must not be allowed <d/> see
<uri link="::general-concepts/user-environment#Not Filtering Variables"/>. There
are separate special variables which should be used in these situations <d/> for
setting <c>CFLAGS</c>. for example, a <c>Makefile.am</c> should use <c>AM_CFLAGS</c> so
that user preferences are not ignored.
</p>
<p>
So, if a <c>Makefile.am</c> contains, say:
</p>
<codesample lang="ebuild">
CFLAGS="-Wall"
</codesample>
<p>
You should <c>sed</c> or <c>patch</c> it to use:
</p>
<codesample lang="ebuild">
AM_CFLAGS="-Wall"
</codesample>
<p>
Remember to manually run <c>autoconf</c> then <c>automake</c> if you do this.
</p>
</body>
</subsection>
</section>
<section>
<title>The <c>config.h.in</c> File</title>
<body>
<p>
The <c>config.h.in</c> file is generated by <c>autoheader</c>. You shouldn't have to
worry about this usually, but occasionally you may need to run <c>autoheader</c>
manually as part of the build process if upstream do not ship a pre-generated
version.
</p>
</body>
</section>
<section>
<title><c>aclocal</c> and <c>m4</c> Files</title>
<body>
<p>
In the <c>configure.ac</c> or <c>configure.in</c> files you can call not only the
default macros defined by <c>autoconf</c> and <c>automake</c>. but also other
functions which can be defined by specific packages like libraries and programs
to check for their features in the correct manner.
</p>
<p>
Those functions are (usually) defined in <c>m4</c> files placed in
the <c>/usr/share/aclocal</c> directory by packages. Problems can arise when you
need to regenerate the <c>autotools</c> files, because the functions used by the
<c>configure.ac</c> file can be defined in an <c>m4</c> macro file which isn't
installed on the user's system. This is the case for example for some optional
features which require libraries and are disabled by <c>USE</c> flags. If the
<c>m4</c> files aren't installed in the user's system, the <c>autoconf</c> step will
fail.
</p>
<p>
To resolve this, most packages just ship the <c>m4</c> macro files needed for their
<c>configure.ac</c> in an <c>m4</c> subdirectory in the source package. Unfortunately,
not all <c>m4</c> directories are complete, even if they are present.
</p>
<p>
In those cases you need to find out the <c>m4</c> file, usually installed by the
dependency in <c>/usr/share/aclocal</c>. and make sure that the <c>src_unpack</c>
stage both makes available those files to the autotools and calls <c>aclocal</c> to
recreate the <c>aclocal.m4</c> file which is used by <c>autoconf</c> when creating the
configure script.
</p>
<p>
Usually it's more than one <c>m4</c> file which is missing, so you probably want to
package them in a tarball, and add it to <c>SRC_URI</c>. After making sure that the
tarball is extracted somewhere in <c>${WORKDIR}</c> (say, in a <c>gentoo-m4</c>
directory), you usually have two general ways to handle those macro files, one
for packages which ships with an incomplete <c>m4</c> directory and one for
packages which ships without the <c>m4</c> directory.
</p>
<p>
In the first case you usually want to do something like:
</p>
<codesample lang="ebuild">
einfo "Regenerating autotools files..."
cp "${WORKDIR}/gentoo-m4" "${S}/m4" || die "m4 copy failed"
WANT_AUTOCONF="2.5" aclocal -I "${S}/m4" || die "aclocal failed"
WANT_AUTOCONF="2.5" autoconf || die "autoconf failed"
</codesample>
<p>
and so on. In the second case you can simplify it in this way:
</p>
<codesample lang="ebuild">
einfo "Regenerating autotools files..."
WANT_AUTOCONF="2.5" aclocal -I "${WORKDIR}/gentoo-m4" || die "aclocal failed"
WANT_AUTOCONF="2.5" autoconf || die "autoconf failed"
</codesample>
<p>
without need to copy the files.
</p>
<p>
It's always better inform upstream when the needed <c>m4</c> files are missing in
the distribution, asking them to add all the needed files in the source tarball
to avoid version conflicts if the macro changes.
</p>
</body>
</section>
<section>
<title>Libtool</title>
<body>
<todo>
Stuff about libtool, libtoolize, elibtoolize, libtool.eclass. Which I
know almost nothing about... Yay!
</todo>
</body>
</section>
<section>
<title>Further Autotools Reading</title>
<body>
<p>
For more details on autotools:
</p>
<ul>
<li>
The book "GNU Autoconf, Automake and Libtool" by Gary V. Vaughan, Ben
Elliston, Tom Tromey and Ian Lance Taylor (often called "The Autobook")
provides a good but somewhat outdated description of autotools. It is
<uri link="http://sources.redhat.com/autobook/">freely available online</uri>.
</li>
<li>
The GNU documentation for the various autotools components is of varying
quality and completeness:
</li>
<ul>
<li>
<uri link="https://www.gnu.org/software/automake/manual/automake.html">
GNU automake Manual
</uri>
</li>
<li>
<uri link="https://www.gnu.org/software/autoconf/manual/">GNU autoconf Manual</uri>
</li>
<li>
<uri link="https://www.gnu.org/software/libtool/manual/">GNU libtool Manual</uri>
</li>
<li>
<uri link="https://www.gnu.org/software/m4/manual/m4.html">GNU m4 Manual</uri>
</li>
</ul>
<li>
There are some good overview lectures available online. <uri
link="http://www.shlomifish.org/lecture/Autotools/">These
slides</uri> are one example.
</li>
</ul>
</body>
</section>
</chapter>
</guide>
|
GitWeb