-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
273 lines (190 loc) · 8.27 KB
/
README
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
-----------------------------------
AutoConf and AutoMake Build Scripts
===================================
Author - Copyright (C) 2014-2021, 2023 Mark Grant
--------
Contents
========
1 ... Project Description
2 ... AutoTools (configure and make) Installation
3 ... Installation of Distro-Native Packages
4 ... Utility Scripts
-------------------------
1 ... Project Description
=========================
This project produces a helper script for AutoTools projects. It has two main
goals; to reduce repetitive typing of some AutoTools commands, and, to afford a
more standard interface for the programmer across AutoTools projects.
Design
------
At the command line level the script offers it's own options and provides that
all other arguments are passed unparsed and untouched straight to the configure
command line. For example:-
acmbuild --config .. sysconfdir=/etc -- --prefix=/usr
In this case --config is an acmbuild option to configure the project, .. is the
base directory and everything else is passed untouched to configure, invoking:-
../configure sysconfdir=/etc --prefix=/usr
thereby obviously supporting environment variable setting and option passing for
configure.
The acmbuild options come in two flavours; action options and enabling options.
b, c, C, D, g, K, m and T are action options. -b, for instance will run make,
whereas -D will run make dist.
The rest, (apart from help and version), are enabling options. Invariably these
are implemented merely by passing an enable argument to configure. For example
acmbuild --config --debug ..
will run
configure --enable-debug=yes
That is all. For it to be meaningful the developer must process this argument
in configure. The script does not know if the option is sensible, or indeed, if
it is supported by configure, so, in the above example, if the developer had not
written code in configure to process this argument, configure will issue a
warning and then just ignore the option.
As an example of the simplification this script affords, the following acmbuild
command
acmbuild -cb .
will run
autoreconf -if .
./configure (plus options)
make (plus options)
Implementation
--------------
The project functionality is implemented as two scripts; acmbuild and
bootstrap.sh. acmbuild does nothing more than invoke bootstrap.sh with the same
arguments. This means that all the functionality is in bootstrap.sh. On project
install both scripts are installed but only acmbuild is installed in the PATH.
So all usage is via acmbuild. The reason for this is that it enables a secondary
usage of bootstrap.sh. bootstrap.sh can be copied and pasted into the
project-root of all AutoTools project to provide a simplified and standardised
build bootstrap as is generally recommended. This eliminates any possible
confusion as to which version of bootstrap.sh is being used whilst also
obviating any dependency on this project.
Command Line Syntax
-------------------
acmbuild -b [-c [-a] [-A] [{--CC=COMPILER|-s}] [-d] [-H] [-m] [-t] [-v]]
[-g] [-K] [-pX] [-- PASS_THRU_OPTIONS ...]
acmbuild -c [-a] [-A] [{--CC=COMPILER|-s}] [-d] [-H] [-m] [-pX] [-t] [-v]
[-- PASS_THRU_OPTIONS ...]
acmbuild -c {-i|-S} [--CC=COMPILER] [-pX] [-v] [-- PASS_THRU_OPTIONS ...]
acmbuild {-C|-D|-T} [-c] [-g] [-pX] [-- PASS_THRU_OPTIONS ...]
acmbuild -g [-b]
[-c [-a] [-A] [{--CC=COMPILER|-s}] [-d] [-H] [-m] [-t] [-v]]
[-K] [-pX] [-- PASS_THRU_OPTIONS ...]
acmbuild {-h|-V}
acmbuild -K [-b]
[-c [-a] [-A] [{--CC=COMPILER|-s}] [-d] [-H] [-m] [-t] [-v]]
[-g] [-pX] [-- PASS_THRU_OPTIONS ...]
acmbuild [OPTIONS] [-- PASS_THRU_OPTIONS ...]
Options
-------
The script offers the following options:-
-a, --at-only
during testing and for an AutoTools-only install, some build
changes are required. e.g. You may reference an external Java
jar in datadir but in AT builds and installations this may ex‐
pand to /usr/local/share... So a substitution is required for
this scenario.
-A, --analyzer
enable compiler analyzer output.
-b, --build
make the project.
-c, --config
configure the project.
-C, --distcheck
perform a normal make distcheck.
--CC compiler
Specify a compiler to use. Functionally equivalent to:-
bootstrap.sh -c . -- CC=compiler
More ephemerally, as a one-off you can use:-
make CC=compiler
-d, --debug
build with appropriate debug flags.
-D, --dist
perform a make dist.
-g, --gnulib
run gnulib-tool --update. Checks for the existence of the cache
file proj-root/m4/gnulib-cache.m4. If it does not exist the up‐
date is not run.
-h, --help
prints usage information.
-H, --header-check
show include stack depth
-i, --iwyu
Run clang's include-what-you-use to analyse header file usage.
include-what-you-use invokes the clang compiler, so this option
automatically sets clang as the compiler and requires that op‐
tion c is specified.
-K, --check
run make check
-m, --config-menu
invoke menu of configurable options. The only thing fixed is the
script name, configurable-options.sh in the project root direc‐
tory. Usually this would be expected to have a dialog interface.
-p[X], --parallel-jobs[=X]
if X is specified then make runs with X parallel jobs. If X is
not specified then make will run with the same number of jobs as
processors. If this option is not specified then make runs se‐
quentially.
-s, --sparse
pass --enable-sparse=yes to configure.
-S, --scan-build
Run clang's scan-build static analyser.
-t, --testing-hacks
some build changes may be required for testing purposes. e.g. A
script may invoke a project jar file which when installed will
be somewhere under datadir, but during testing it is in the
project tree.
-T, --source-tarball
perform a make srctarball to build a source tarball.
-v, --verbose
emit extra information
-V, --version
prints version information
-- PASS_THRU_OPTIONS The -- stops processing command line arguments and
instead passes subsequent arguments on, as-is, to AutoTools
N.B.
----
At a source modification / development level, this project expects to reside in
a git environment. This manifests itself in 2 places:-
1) ... .gitignore files are included in the source.
2) ... The make target, 'srctarball', relies on the command 'git archive' so it
will fail if git is not installed or it is not in a git repository.
-------------------------------------------------
2 ... AutoTools (configure and make) Installation
=================================================
a) ... Download either the source or distribution tarball (the .tar.gz file)
from:-
https://github.com/m-grant-prg/acmbuild/releases
b) ... Extract the tarball preserving the directory structure.
c) ... cd to the directory created.
d) ... If you downloaded the source tarball type 'autoreconf -if'
e) ... Type './configure'
f) ... As root or sudo, type 'make install clean'
(Quote marks are for textual clarity only).
To uninstall the package:
1 ... cd to the directory created in the above install process.
2 ... As root or sudo, type 'make uninstall clean'
--------------------------------------------
3 ... Installation of Distro-Native Packages
============================================
Installation packages native to different distributions are available, please
refer to the relevant installation section on the wiki at:-
https://github.com/m-grant-prg/acmbuild/wiki
---------------------
4 ... Utility Scripts
=====================
In the project root directory there is 1 helper script; bootstrap.sh.
bootstrap.sh
------------
This misleadingly named script bootstraps the project build and provides other
useful features. The main script options are probably b, c, C, D and T.
In AutoTools it is usually advisable to perform parallel builds. This means you
build somewhere other than the project root. This is because building creates
files and they would confuse the project root downwards. I always create a build
directory straight off the project root, cd to there and do all build and git
work from there, (.gitignore is already set to ignore such a directory).
Assuming you adopt the preceding paragraph then a typical invocation of the
script would be:-
../bootstrap.sh --config --build ..
The last '..' points the way to project root.
For the full list of arguments to bootstrap.sh please look at the acmbuild
options section above.