-
Notifications
You must be signed in to change notification settings - Fork 3
/
autoconf-project.page.in
142 lines (122 loc) · 8.11 KB
/
autoconf-project.page.in
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
<page xmlns="http://projectmallard.org/1.0/"
type="topic"
id="autoconf-project">
<info>
<credit type="author maintainer copyright">
<name>Philip Chimento</name>
<email>philip.chimento@gmail.com</email>
<years>2008-2012</years>
</credit>
<license href="http://creativecommons.org/licenses/by-nc-sa/3.0/">
<p>This work is licensed under a <link href="http://creativecommons.org/licenses/by-nc-sa/3.0/">Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License</link>.</p>
</license>
<link type="next" xref="automake-project"/>
<link type="guide" xref="real-life-app-setup" group="#first"/>
<desc>Starting a new project from scratch</desc>
</info>
<title>Setting up <app>Autoconf</app></title>
<synopsis>
<p>In this tutorial, you will learn how to set up an empty Autotools build system.</p>
<p>This is the first tutorial in the <em>Setting up a real-life GTK application</em> series.</p>
</synopsis>
<p>To get started, we will build up an Autotools project from scratch.
First create a directory called <file>app-skeleton1</file>.
In the directory, create an empty file called <file>Makefile.am</file>.
(For example, you can type <cmd>touch Makefile.am</cmd> in a terminal.)
This is an Automake file, which is where we put the instructions for transforming source code into programs.
We will fill it later.
First, we will use Autoconf to configure our project.</p>
<p>Open a new file in the directory with your editor and call it <file>configure.ac</file>.
This is an Autoconf file, where we put instructions for what tools we would like to use to build our project.
We also note what capabilities of the system we would like to use, so that Autoconf can check to make sure the system has those capabilities.
In <file>configure.ac</file>, write:</p>
<!--{{{app-skeleton1/configure.ac:1-4%autoconf}}}-->
<p>This file consists of macros that Autoconf expands into shell scripts.
Macros beginning with <code>AC_</code> are Autoconf's own macros, and macros that start with <code>AM_</code> belong to Automake.
Notice that the macros' argument lists are enclosed in parentheses, and each argument is enclosed in square brackets.
The square brackets are <em>quotes</em>.
They are quite complicated and explained in detail in the Autoconf manual, but a good rule of thumb is:
always quote each argument of a macro.
We will go through these macros one by one:
</p>
<terms>
<item>
<title><code>AC_INIT</code></title>
<p>This initializes Autoconf, telling it the name and version of the project.
The third, optional argument is an e-mail address for reporting bugs in the program.
You can replace it with your own e-mail address if you like, but bugs in the tutorial programs should probably still be reported to me.</p>
</item>
<item>
<title><code>AM_INIT_AUTOMAKE</code></title>
<p>This tells Autoconf that we will be using Automake (yes, it is possible to use one without the other.)
It also initializes Automake and configures it.
<code>-Wall</code> and <code>foreign</code> are Automake options.
Note that they are not separate arguments to the <code>AM_INIT_AUTOMAKE</code> macro; all the options are one space-separated argument.</p>
<p><code>-Wall</code> tells Automake to have the compiler report all warnings when compiling our program, much like the <cmd>-Wall</cmd> option to the C compiler.
<code>foreign</code> tells Automake that we will not be building a GNU package, so it will not complain about the lack of files such as README.
If you are building a real application, you might want to remove the <code>foreign</code> option so that you will not forget to provide any files that users might expect.</p>
</item>
<item>
<title><code>AC_CONFIG_FILES</code></title>
<p>This is a list of files that we would like to output when configuring our project.
If we put a file named <file>plerp</file> in this list, then Autoconf will look for a file named <file>plerp.in</file> and transform it into <file>plerp</file>.
It does this by scanning <file>plerp.in</file> and replacing any text in the form of <code>@VARIABLE@</code> with the contents of the variable <code>VARIABLE</code>.
We have not defined any of these variables explicitly yet, but they are defined internally by many Autoconf and Automake macros.</p>
<p>Here, we tell Autoconf that we would like to transform <file>Makefile.in</file> into <file>Makefile</file>.
Where is <file>Makefile.in</file>?
When we run Automake, it creates <file>Makefile.in</file> from <file>Makefile.am</file>.
We will do this in the <link role="next" xref="automake-project">next step</link>.</p>
</item>
<item>
<title><code>AC_OUTPUT</code></title>
<p>This macro takes care of outputting any files we have asked Autoconf to output.</p>
</item>
</terms>
<p>We must now <em>bootstrap</em> this project (initialize it from this pristine state into a state where the build system is working.)
The Autoreconf program does this.
Autoreconf runs Autoconf, Automake, and several other programs in order to get the project ready to be built.
In a terminal, type:</p>
<screen>
<input>autoreconf -i</input>
<output>configure.ac:2: installing `./install.sh'
configure.ac:2: installing `./missing'</output>
</screen>
<p>You will be notified of files being installed.
(That is what the <cmd>-i</cmd> option does; once the files are there, you can simply run <cmd>autoreconf</cmd> without any options.)
If you look inside the directory, however, those won't be the only files that have appeared.
<file>Makefile.in</file>, <file>aclocal.m4</file>, <file>configure</file>, and a directory <file>autom4te.cache</file> will also have been created.</p>
<note>
<title>Bootstrapping</title>
<p>It is worth noting here that anybody who wants to build your program from this point onwards doesn't need Autoconf or Automake, only a shell and Make.
Distributions of source code usually include all the files that are in the directory right now, so that users who want to compile the software from source don't have to bother with Autotools.
When checking out source code from a repository, however, only the handwritten files are included.
The reasoning goes that those who are savvy enough to mess with development snapshots of software can be expected to have various build tools installed.
If you check out source code from a repository, bootstrap it using <cmd>autoreconf -i</cmd>.
Sometimes there is a script called <cmd>autogen.sh</cmd> or <cmd>bootstrap</cmd> to do this for you, especially if there are other steps needed for bootstrapping.
If one of these files exists, use it instead.</p>
</note>
<p>Now the build system is initialized, we can build the source in the usual way.</p>
<screen>
<input>./configure</input>
<output>checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
configure: creating ./config.status
config.status: creating Makefile</output>
<input>make</input>
<output>make: Nothing to be done for `all'.</output>
</screen>
<p>Of course there is nothing for <cmd>make</cmd> to do.
We have no source files, and our <file>Makefile.am</file> was empty.
If you look at the size of the generated <file>Makefile</file>, however, it is anything but empty: my system reports it to be 14 kilobytes large.
Even though we have no project yet, we still have a versatile build system in place.</p>
<p>For an example of just how versatile, type <input>make dist</input>.
A file named <file>app-skeleton-1.tar.gz</file> will appear in the directory.
It is a <em>tarball</em> (archive) of the project's source code, ready to be distributed.
It is also worth noting that whoever downloads this tarball can build the project without having Autotools installed:
all they need are the <file>configure</file> and <file>Makefile</file> files, which are included.</p>
<p>We can do other things, such as clean up our project directory.
For a full list of standard <em>make targets</em>, refer to the <link href="http://www.gnu.org/s/hello/manual/make/Standard-Targets.html">Make manual</link>.</p>
</page>