forked from dmoulding/boilermake
-
Notifications
You must be signed in to change notification settings - Fork 0
/
MANUAL
224 lines (181 loc) · 9.37 KB
/
MANUAL
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
boilermake - A reusable, but flexible, boilerplate Makefile.
Boilermake Manual
-----------------
This manual attempts to document all of the special variables that can be
specified in a boilermake submakefile. Of all the variables, the only one that
is absolutely required is "TARGET". However, it wouldn't really be useful to
only specify "TARGET". Normally, at a minimum, some SOURCES should also be
defined.
Many of the variable names below begin with "SRC_" or "TGT_". These variables
apply to the current list of source files or the current target, respectively.
The "current" list of source files is the list of files specified on the
"SOURCES" line in the *current* submakefile. The "SRC_*" variables cannot be
applied to source files defined in some other submakefile.
The "current" target could be a "TARGET" defined in the current submakefile, or
it could be a "TARGET" defined in some ancestor makefile (see the description
of TARGET below for more details).
In addition to the special variables documented here, boilermake respects many
of the built-in GNU Make variables, such as: AR, ARFLAGS, CC, CFLAGS, CXX,
CXXFLAGS, LDFLAGS, and possibly others. You can use these variables in your
boilermake submakefiles and they should generally behave in the expected
manner.
Following is the list of special variables recognized by boilermake. Unless
otherwise noted, the default value for each variable is the empty string.
BUILD_DIR
---------
Specifies the directory in which all intermediate build-generated files
(e.g. .o files) will be placed. The final targets (executables and/or
libraries) can be placed in a different directory (see TARGET_DIR). A file
hierarchy that mirrors the source hierarchy will be generated under this
directory.
It is advised to set this variable only once (so that all intermediate
build-generated files are placed under a common directory). Changing this
variable from one submakefile to the next is not recommended (and is not
guaranteed to work properly).
Default value: build
INCDIRS
-------
Globally specifies include directories to be searched during source
compilation. These will apply to sources from all submakefiles and for all
targets. These should be specified as just directory names (i.e. they should
not be prefixed with a "-I"). The paths should be specified relative to the
root of the project (i.e. the directory from which you run make).
DEFS
----
Globally specifies preprocessor definitions to be defined during source
compilation. These will apply to sources from all submakefiles and for all
targets. These should be specified exactly as they should be defined (i.e.
they should not be prefixed with a "-D").
SOURCES
-------
Specifies one or more source files that are prerequesites of the "current"
target (the current target may be a target specified in the same submakefile
as the SOURCES variable, or it may be a target specified in some ancestor
makefile).
Currently supported sources are C and C++ sources ending with any of the
following filename extensions:
For C sources: .c
For C++ sources: .C .cc .cp .cpp .CPP .cxx .c++
SRC_CFLAGS
----------
Specifies compile flags to be applied to the C sources listed in the current
submakefile only. This can be used to augment the globally applied CFLAGS
for selected C sources. Note that flags specified here can *override* flags
specified in CFLAGS. For instance, if a small subset of C source files
*must* be compiled with "-std=c99", then setting SRC_CFLAGS to "-std=c99"
will ensure that the "-std=c99" flag is used at compilation time for those
sources, even if "CFLAGS=-ansi" is specified on the "make" command line.
For specifying include directories or preprocessor definitions, SRC_INCDIRS
and SRC_DEFS (or their global equivalents, INCDIRS and DEFS) can often be
more convenient.
SRC_CXXFLAGS
------------
Like SRC_CFLAGS, but for C++ sources.
SRC_DEFS
--------
Specifies preprocessor definitions to be defined during compilation of
sources listed in the current submakefile only. This can be used to augment
the globally applied DEFS for selected sources.
SRC_INCDIRS
-----------
Specifies include directories to be searched during compilation of sources
listed in the current submakefile only. This can be used to augment the
globally applied INCDIRS for selected sources. Unlike the global INCDIRS
variable, paths assigned to this variable should be relative to the
*current* submakefile's directory (not the root of the project).
SUBMAKEFILES
------------
Specifies one or more submakefiles of the current submakefile. This allows
the construction of a submakefile hierarchy, which makes it possible to
define multiple targets with unique sources and compiler/linker flags.
For example, a group of source files that should all be compiled with a
common set of compile flags can be specified in their own submakefile that
specifies the SRC_CFLAGS variable. Or a new target, with its own list of
prerequesites and link-time libraries can be specified in a new submakefile.
TARGET
------
Specifies that a new target is to be made by the Makefile. Targets can be
static libraries or executables (shared objects are considered executables).
Any target whose name ends with ".a" will be treated as a static library.
All others are treated as executables. By default, the Makefile will build
all targets if "make" is invoked without specifying a target. This behavior
can be overridden using the GNU Make variable ".DEFAULT_GOAL", if desired.
At least one target must be defined in order to do anything useful.
The TARGET variable should be specified only *once* anywhere in the makefile
hierarchy for a given target name. Each time the TARGET variable is
specified, the Makefile interprets this to mean that a *new* target is being
defined. No two targets should have the same name.
All target-specific boilermake variables apply to the "closest" ancestor
target specified in the submakefile hierarchy. For example, if a grandparent
makefile specifies a target named "foo" and a parent makefile specifies a
target "bar" while the child makefile does not specify a target, then the
SOURCES variable or any "TGT_*" variable specified in the child makefile
applies to the target named "bar".
TARGET_DIR
----------
Specifies the directory in which *all* final target files will be placed.
Intermediate build-generated files (.o files) are usually placed in a
different directory (see BUILD_DIR).
Like BUILD_DIR, it is advised to set this variable only once.
Default value: . (make's working directory; aka project root)
TGT_CFLAGS
----------
Like SRC_CFLAGS, but applies to all sources belonging to the current target,
not just sources in the current submakefile.
TGT_CXXFLAGS
------------
Like SRC_CXXFLAGS, but applies to all sources belonging to the current
target, not just sources in the current submakefile.
TGT_DEFS
--------
Like SRC_DEFS, but applies to all sources belonging to the current target,
not just sources in the current submakefile.
TGT_INCDIRS
-----------
Like SRC_INCDIRS, but applies to all sources belonging to the current target,
not just sources in the current submakefile.
TGT_LDFLAGS
-----------
Specifies flags that should be passed to the linker when linking the target.
Flags specified with this variable can *override* flags specified with
LDFLAGS, in the same way that SRC_CFLAGS can override CFLAGS.
Examples of flags that are often specified here include "-L" and "-shared".
TGT_LDLIBS
----------
Specifies libraries (static or dynamic) that should be passed to the linker
when linking the target. Libraries should be listed using the same format
used with the traditional LDLIBS variable (e.g. to link with librt.a you
would list "-lrt").
TGT_LINKER
----------
Specifies the program to be used for linking the target (applies to
executable targets only). If this option is not specified, the Makefile will
attempt to make a reasonable decision based upon the sources that are
prerequesites of the target (it will choose CXX if there are C++ sources,
otherwise it will choose CC).
TGT_POSTCLEAN
-------------
Specifies one or more actions to be performed after the target has been
cleaned. These should be entered as shell commands (normal GNU Make
processing applies, so you can use make variables in the commands).
See TGT_POSTMAKE below for more related information.
TGT_POSTMAKE
------------
Specifies one or more actions to be performed after the target has been
made. These should be entered as shell commands (normal GNU Make processing
applies, so you can use make variables in the commands).
To specify a long series of commands, they can be separated by semicolons,
or pehaps it may be preferable to use the GNU Make "define" directive to
define the sequence of commands (with newlines allowed) and then refer to
the defined variable's name here. For example:
define MOVE_AND_LINK
mv foo bar
ln -s bar/foo
endef
TGT_POSTMAKE := ${MOVE_AND_LINK}
TGT_PREREQS
-----------
Can be used to specify dependencies between targets. For example, an
executable target may depend on one or more static library targets defined
elsewhere. This variable can be used to tell boilermake that the executable
depends on those libraries.