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
|
Vis5D Porting and Development Notes
This file attempts to give a *brief* overview of how the autoconf
build system works, for the aid of porters and developers. It centers
around the GNU autoconf, autoheader, automake, and libtool development
tools, and for more information you should see the GNU documentation,
which can be found online (among other places) at:
http://www.gnu.org/manual/manual.html
---------------------------------------------------------------------------
If Vis5D doesn't build on your machine, what you want to do is:
1) Figure out what you need to do to build it, e.g. replace some
function call or link to a particular library. If there are problems
during the configure run, look in the file config.log for diagnostic
output.
2) Write an autoconf test in configure.in (see below) that tests for
the problem.
3) Modify the code or the Makefile.am (see below) to alter its
behaviour based upon the result of the test in step (2).
---------------------------------------------------------------------------
There are essentially three human-edited files which control the build
process:
configure.in: specifies what tests to run in the configure script
acconfig.h: specifies outputs of configure.in that can't be guessed
by autoheader
Makefile.am: a high-level type of Makefile for input to automake;
there's one of these in each subdirectory too
(Oh, there's also an acinclude.m4 file that contains some extra macros
for configure.in that I gathered from external sources.)
---------------------------------------------------------------------------
When an ordinary user builds Vis5D, what happens is that the configure
script generates two things:
a) config.h from config.h.in
config.h contains #define statements indicating results of most of the
configure tests, e.g. #define HAVE_LIBNETCDF 1 if the netcdf library
was found. It is included by all of the .c files and used to tailor
their behavior to the machine in question. (config.h.in was generated
by autoheader, as described below.)
b) Makefile(s) from Makefile.in(s) in each directory
A Makefile, of course, is just the ordinary thing that 'make' uses.
Makefile.in is a template, into which the configure script substitutes
things like the C compiler name and the linker flags. (The Makefile.in
file, in turn, was generated from Makefile.am by automake; see below.)
---------------------------------------------------------------------------
To build everything from scratch, assuming you have up-to-date
versions of automake, libtool, autoconf, and autoheader (all of which
can be gotten from the GNU web site; I think autoheader comes with
autoconf), you do the below. Once you've got things built for the
first time, though, the Makefiles know enough to rebuild the various
things when necessary (usually).
0) things you only need to do once (or probably never, since I've
already done them for you):
% aclocal
% autoheader
% automake --add-missing
% autoconf
% automake
% autoconf
You do this once, the first time you start development. automake
--add-missing fetches any extra files that the build system will need;
e.g. the config.guess script, which figures out what kind of machine
you have and outputs it in a canonical format (for example,
i686-pc-linux-gnu). The rest of the commands (yes, some of them are
repeated, and the order is important) will make sure all the other
necessary files are in place. After these steps you can do the
ordinary ./configure, make, make install, etcetera.
Below, we'll go into some of the individual commands in more detail,
and explain what they are and when you'll want to re-run them.
---------------------------------------------------------------------------
1)
% aclocal
This is a command that is part of automake, which you shouldn't have
to run often. It fetches necessary macros from various sources and
uses them to create aclocal.m4; one of the places it fetches macros
from is acinclude.m4, so you'll need to re-run aclocal if acinclude.m4
is changed.
2)
% autoheader
Scans configure.in and aclocal.m4 to see what tests are performed, and
uses them to regenerate config.h.in. config.h.in basically contains
default settings for the various preprocessor symbols that will
eventually be used in config.h. Rerun this when configure.in,
aclocal.m4, or acconfig.h change.
3)
% automake
automake generates Makefile.in files from Makefile.am files (note that
it automatically goes into subdirectories as necessary). Makefile.am
files are a sort of very high-level Makefile that doesn't look very
much like an ordinary Makefile. It specifies the programs and
libraries to be built, and automake automatically generates things
like:
* sets up all the templates where the configure script can
substitute its build information (e.g. C compiler flags)
* install and uninstall targets
* handles shared libraries (which are otherwise nigh-impossible
to do portably)
You'll need to re-run automake when the Makefile.am files change
4)
% autoconf
Generates the configure script from configure.in and aclocal.m4. As
mentioned above, the configure.in file specifies tests to be performed
to determine system features, using a mixture of the m4 macro language
and the Bourne Shell (sh) script. autoconf supplies a large number of
predefined macros to help you test for features; e.g. AC_PROG_CC is a
macro to find out the name of the C compiler. Rerun this when
configure.in or aclocal.m4 change.
The general philosophy of autoconf is to actively go out and look for
a feature, instead of trying to infer it from other information. For
example, if you want to know whether your system has the setrlimit()
function, it doesn't look at the system name and then go to a table of
systems and features. Instead, it directly tries to link a C program
calling setrlimit and sees if it succeeds. You specify this in
configure.in by calling the following macro: AC_CHECK_FUNCS(setrlimit)
(This will #define HAVE_SETRLIMIT in config.h if it is successful,
which we can then use to decide in our program if we want to call that
function.)
Because of this philosophy, a program that is maintained with autoconf
will generally compile and run even on many systems that the developer
didn't specifically anticipate.
---------------------------------------------------------------------------
Standard build targets (can be run after the Makefile is generated by
configure):
% make
Builds the program, libraries, and utilities, automatically rerunning
autoconf, autoheader, automake, and/or aclocal if the relevant files
have changed.
% make clean
Gets rid of all object files, libraries, and programs produced by make.
You may need to do this if you change a header file or something and
the software isn't rebuilding completely (the Makefiles don't have all
the possible dependency rules for header files).
% make install
Install the software under the installation prefix.
% make distclean
Restore to the state in which Vis5d is distributed. Does 'make clean'
and in addition gets rid of the cached configure information,
Makefiles, etcetera. configure must be re-run after this if you want
to do anything else.
% make maintainer-clean
Gets rid of even more files than 'make distclean', including some
files that may need special tools to rebuild. Currently, this doesn't
do much; if you really want to clean the directory, use:
% make super-clean
Gets rid of *all* the automatically generated files, including the
configure script, the Makefile.in files, etcetera. You will need to
re-run the commands in step (0) above after doing this. Don't do this
unless you have automake, autoconf, etcetera!
% make dist
Make the distribution package; results in a file
vis5d-<version>.tar.gz in the current directory. This is the file
that you should give out to users. The nice thing about this is that
you don't have to worry about any files you might have lying around
from your development efforts; only those files explicitely specified
in the Makefile.am's will go into the dist.
|
