Source code

Revision control

Other Tools

1
.. _defining_binaries:
2
3
======================================
4
Defining Binaries for the Build System
5
======================================
6
7
One part of what the build system does is compile C/C++ and link the resulting
8
objects to produce executables and/or libraries. This document describes the
9
basics of defining what is going to be built and how. All the following
10
describes constructs to use in moz.build files.
11
12
13
Source files
14
============
15
16
Source files to be used in a given directory are registered in the ``SOURCES``
17
and ``UNIFIED_SOURCES`` variables. ``UNIFIED_SOURCES`` have a special behavior
18
in that they are aggregated by batches of 16, requiring, for example, that there
19
are no conflicting variables in those source files.
20
21
``SOURCES`` and ``UNIFIED_SOURCES`` are lists which must be appended to, and
22
each append requires the given list to be alphanumerically ordered.
23
24
.. code-block:: python
25
26
UNIFIED_SOURCES += [
27
'FirstSource.cpp',
28
'SecondSource.cpp',
29
'ThirdSource.cpp',
30
]
31
32
SOURCES += [
33
'OtherSource.cpp',
34
]
35
36
``SOURCES`` and ``UNIFIED_SOURCES`` can contain a mix of different file types,
37
for C, C++, and Objective C.
38
39
40
Static Libraries
41
================
42
43
To build a static library, other than defining the source files (see above), one
44
just needs to define a library name with the ``Library`` template.
45
46
.. code-block:: python
47
48
Library('foo')
49
50
The library file name will be ``libfoo.a`` on UNIX systems and ``foo.lib`` on
51
Windows.
52
53
If the static library needs to aggregate other static libraries, a list of
54
``Library`` names can be added to the ``USE_LIBS`` variable. Like ``SOURCES``, it
55
requires the appended list to be alphanumerically ordered.
56
57
.. code-block:: python
58
59
USE_LIBS += ['bar', 'baz']
60
61
If there are multiple directories containing the same ``Library`` name, it is
62
possible to disambiguate by prefixing with the path to the wanted one (relative
63
or absolute):
64
65
.. code-block:: python
66
67
USE_LIBS += [
68
'/path/from/topsrcdir/to/bar',
69
'../relative/baz',
70
]
71
72
Note that the leaf name in those paths is the ``Library`` name, not an actual
73
file name.
74
75
Note that currently, the build system may not create an actual library for
76
static libraries. It is an implementation detail that shouldn't need to be
77
worried about.
78
79
As a special rule, ``USE_LIBS`` is allowed to contain references to shared
80
libraries. In such cases, programs and shared libraries linking this static
81
library will inherit those shared library dependencies.
82
83
84
Intermediate (Static) Libraries
85
===============================
86
87
In many cases in the tree, static libraries are built with the only purpose
88
of being linked into another, bigger one (like libxul). Instead of adding all
89
required libraries to ``USE_LIBS`` for the bigger one, it is possible to tell
90
the build system that the library built in the current directory is meant to
91
be linked to that bigger library, with the ``FINAL_LIBRARY`` variable.
92
93
.. code-block:: python
94
95
FINAL_LIBRARY = 'xul'
96
97
The ``FINAL_LIBRARY`` value must match a unique ``Library`` name somewhere
98
in the tree.
99
100
As a special rule, those intermediate libraries don't need a ``Library`` name
101
for themselves.
102
103
104
Shared Libraries
105
================
106
107
Sometimes, we want shared libraries, a.k.a. dynamic libraries. Such libraries
108
are defined similarly to static libraries, using the ``SharedLibrary`` template
109
instead of ``Library``.
110
111
.. code-block:: python
112
113
SharedLibrary('foo')
114
115
When this template is used, no static library is built. See further below to
116
build both types of libraries.
117
118
With a ``SharedLibrary`` name of ``foo``, the library file name will be
119
``libfoo.dylib`` on OSX, ``libfoo.so`` on ELF systems (Linux, etc.), and
120
``foo.dll`` on Windows. On Windows, there is also an import library named
121
``foo.lib``, used on the linker command line. ``libfoo.dylib`` and
122
``libfoo.so`` are considered the import library name for, resp. OSX and ELF
123
systems.
124
125
On OSX, one may want to create a special kind of dynamic library: frameworks.
126
This is done with the ``Framework`` template.
127
128
.. code-block:: python
129
130
Framework('foo')
131
132
With a ``Framework`` name of ``foo``, the framework file name will be ``foo``.
133
This template however affects the behavior on all platforms, so it needs to
134
be set only on OSX.
135
136
137
Executables
138
===========
139
140
Executables, a.k.a. programs, are, in the simplest form, defined with the
141
``Program`` template.
142
143
.. code-block:: python
144
145
Program('foobar')
146
147
On UNIX systems, the executable file name will be ``foobar``, while on Windows,
148
it will be ``foobar.exe``.
149
150
Like static and shared libraries, the build system can be instructed to link
151
libraries to the executable with ``USE_LIBS``, listing various ``Library``
152
names.
153
154
In some cases, we want to create an executable per source file in the current
155
directory, in which case we can use the ``SimplePrograms`` template
156
157
.. code-block:: python
158
159
SimplePrograms([
160
'FirstProgram',
161
'SecondProgram',
162
])
163
164
Contrary to ``Program``, which requires corresponding ``SOURCES``, when using
165
``SimplePrograms``, the corresponding ``SOURCES`` are implied. If the
166
corresponding ``sources`` have an extension different from ``.cpp``, it is
167
possible to specify the proper extension:
168
169
.. code-block:: python
170
171
SimplePrograms([
172
'ThirdProgram',
173
'FourthProgram',
174
], ext='.c')
175
176
Please note this construct was added for compatibility with what already lives
177
in the mozilla tree ; it is recommended not to add new simple programs with
178
sources with a different extension than ``.cpp``.
179
180
Similar to ``SimplePrograms``, is the ``CppUnitTests`` template, which defines,
181
with the same rules, C++ unit tests programs. Like ``SimplePrograms``, it takes
182
an ``ext`` argument to specify the extension for the corresponding ``SOURCES``,
183
if it's different from ``.cpp``.
184
185
186
Linking with system libraries
187
=============================
188
189
Programs and libraries usually need to link with system libraries, such as a
190
widget toolkit, etc. Those required dependencies can be given with the
191
``OS_LIBS`` variable.
192
193
.. code-block:: python
194
195
OS_LIBS += [
196
'foo',
197
'bar',
198
]
199
200
This expands to ``foo.lib bar.lib`` when building with MSVC, and
201
``-lfoo -lbar`` otherwise.
202
203
For convenience with ``pkg-config``, ``OS_LIBS`` can also take linker flags
204
such as ``-L/some/path`` and ``-llib``, such that it is possible to directly
205
assign ``LIBS`` variables from ``CONFIG``, such as:
206
207
.. code-block:: python
208
209
OS_LIBS += CONFIG['MOZ_PANGO_LIBS']
210
211
(assuming ``CONFIG['MOZ_PANGO_LIBS']`` is a list, not a string)
212
213
Like ``USE_LIBS``, this variable applies to static and shared libraries, as
214
well as programs.
215
216
217
Libraries from third party build system
218
=======================================
219
220
Some libraries in the tree are not built by the moz.build-governed build
221
system, and there is no ``Library`` corresponding to them.
222
223
However, ``USE_LIBS`` allows to reference such libraries by giving a full
224
path (like when disambiguating identical ``Library`` names). The same naming
225
rules apply as other uses of ``USE_LIBS``, so only the library name without
226
prefix and suffix shall be given.
227
228
.. code-block:: python
229
230
USE_LIBS += [
231
'/path/from/topsrcdir/to/third-party/bar',
232
'../relative/third-party/baz',
233
]
234
235
Note that ``/path/from/topsrcdir/to/third-party`` and
236
``../relative/third-party/baz`` must lead under a subconfigured directory (a
237
directory with an AC_OUTPUT_SUBDIRS in configure.in), or ``security/nss``.
238
239
240
Building both static and shared libraries
241
=========================================
242
243
When both types of libraries are required, one needs to set both
244
``FORCE_SHARED_LIB`` and ``FORCE_STATIC_LIB`` boolean variables.
245
246
.. code-block:: python
247
248
FORCE_SHARED_LIB = True
249
FORCE_STATIC_LIB = True
250
251
But because static libraries and Windows import libraries have the same file
252
names, either the static or the shared library name needs to be different
253
than the name given to the ``Library`` template.
254
255
The ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME`` variables can be used
256
to change either the static or the shared library name.
257
258
.. code-block:: python
259
260
Library('foo')
261
STATIC_LIBRARY_NAME = 'foo_s'
262
263
With the above, on Windows, ``foo_s.lib`` will be the static library,
264
``foo.dll`` the shared library, and ``foo.lib`` the import library.
265
266
In some cases, for convenience, it is possible to set both
267
``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME``. For example:
268
269
.. code-block:: python
270
271
Library('mylib')
272
STATIC_LIBRARY_NAME = 'mylib_s'
273
SHARED_LIBRARY_NAME = CONFIG['SHARED_NAME']
274
275
This allows to use ``mylib`` in the ``USE_LIBS`` of another library or
276
executable.
277
278
When referring to a ``Library`` name building both types of libraries in
279
``USE_LIBS``, the shared library is chosen to be linked. But sometimes,
280
it is wanted to link the static version, in which case the ``Library`` name
281
needs to be prefixed with ``static:`` in ``USE_LIBS``
282
283
::
284
285
a/moz.build:
286
Library('mylib')
287
FORCE_SHARED_LIB = True
288
FORCE_STATIC_LIB = True
289
STATIC_LIBRARY_NAME = 'mylib_s'
290
b/moz.build:
291
Program('myprog')
292
USE_LIBS += [
293
'static:mylib',
294
]
295
296
297
Miscellaneous
298
=============
299
300
The ``SONAME`` variable declares a "shared object name" for the library. It
301
defaults to the ``Library`` name or the ``SHARED_LIBRARY_NAME`` if set. When
302
linking to a library with a ``SONAME``, the resulting library or program will
303
have a dependency on the library with the name corresponding to the ``SONAME``
304
instead of the ``Library`` name. This only impacts ELF systems.
305
306
::
307
308
a/moz.build:
309
Library('mylib')
310
b/moz.build:
311
Library('otherlib')
312
SONAME = 'foo'
313
c/moz.build:
314
Program('myprog')
315
USE_LIBS += [
316
'mylib',
317
'otherlib',
318
]
319
320
On e.g. Linux, the above ``myprog`` will have DT_NEEDED markers for
321
``libmylib.so`` and ``libfoo.so`` instead of ``libmylib.so`` and
322
``libotherlib.so`` if there weren't a ``SONAME``. This means the runtime
323
requirement for ``myprog`` is ``libfoo.so`` instead of ``libotherlib.so``.
324
325
326
Gecko-related binaries
327
======================
328
329
Some programs or libraries are totally independent of Gecko, and can use the
330
above mentioned templates. Others are Gecko-related in some way, and may
331
need XPCOM linkage, mozglue. These things are tedious. A set of additional
332
templates exists to ease defining such programs and libraries. They are
333
essentially the same as the above mentioned templates, prefixed with "Gecko":
334
335
- ``GeckoProgram``
336
- ``GeckoSimplePrograms``
337
- ``GeckoCppUnitTests``
338
- ``GeckoSharedLibrary``
339
- ``GeckoFramework``
340
341
All the Gecko-prefixed templates take the same arguments as their
342
non-Gecko-prefixed counterparts, and can take a few more arguments
343
for non-standard cases. See the definition of ``GeckoBinary`` in
344
build/gecko_templates.mozbuild for more details, but most usecases
345
should not require these additional arguments.