3 ======================================
4 Defining Binaries for the Build System
5 ======================================
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.
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.
21 ``SOURCES`` and ``UNIFIED_SOURCES`` are lists which must be appended to, and
22 each append requires the given list to be alphanumerically ordered.
34 ``SOURCES`` and ``UNIFIED_SOURCES`` can contain a mix of different file types,
35 for C, C++, and Objective C.
41 To build a static library, other than defining the source files (see above), one
42 just needs to define a library name with the ``Library`` template.
46 The library file name will be ``libfoo.a`` on UNIX systems and ``foo.lib`` on
49 If the static library needs to aggregate other static libraries, a list of
50 ``Library`` names can be added to the ``USE_LIBS`` variable. Like ``SOURCES``, it
51 requires the appended list to be alphanumerically ordered.
53 USE_LIBS += ['bar', 'baz']
55 If there are multiple directories containing the same ``Library`` name, it is
56 possible to disambiguate by prefixing with the path to the wanted one (relative
60 '/path/from/topsrcdir/to/bar',
64 Note that the leaf name in those paths is the ``Library`` name, not an actual
67 Note that currently, the build system may not create an actual library for
68 static libraries. It is an implementation detail that shouldn't need to be
71 As a special rule, ``USE_LIBS`` is allowed to contain references to shared
72 libraries. In such cases, programs and shared libraries linking this static
73 library will inherit those shared library dependencies.
76 Intermediate (Static) Libraries
77 ===============================
79 In many cases in the tree, static libraries are built with the only purpose
80 of being linked into another, bigger one (like libxul). Instead of adding all
81 required libraries to ``USE_LIBS`` for the bigger one, it is possible to tell
82 the build system that the library built in the current directory is meant to
83 be linked to that bigger library, with the ``FINAL_LIBRARY`` variable.
87 The ``FINAL_LIBRARY`` value must match a unique ``Library`` name somewhere
90 As a special rule, those intermediate libraries don't need a ``Library`` name
97 Sometimes, we want shared libraries, a.k.a. dynamic libraries. Such libraries
98 are defined similarly to static libraries, using the ``SharedLibrary`` template
99 instead of ``Library``.
103 When this template is used, no static library is built. See further below to
104 build both types of libraries.
106 With a ``SharedLibrary`` name of ``foo``, the library file name will be
107 ``libfoo.dylib`` on OSX, ``libfoo.so`` on ELF systems (Linux, etc.), and
108 ``foo.dll`` on Windows. On Windows, there is also an import library named
109 ``foo.lib``, used on the linker command line. ``libfoo.dylib`` and
110 ``libfoo.so`` are considered the import library name for, resp. OSX and ELF
113 On OSX, one may want to create a special kind of dynamic library: frameworks.
114 This is done with the ``Framework`` template.
118 With a ``Framework`` name of ``foo``, the framework file name will be ``foo``.
119 This template however affects the behavior on all platforms, so it needs to
126 Executables, a.k.a. programs, are, in the simplest form, defined with the
127 ``Program`` template.
131 On UNIX systems, the executable file name will be ``foobar``, while on Windows,
132 it will be ``foobar.exe``.
134 Like static and shared libraries, the build system can be instructed to link
135 libraries to the executable with ``USE_LIBS``, listing various ``Library``
138 In some cases, we want to create an executable per source file in the current
139 directory, in which case we can use the ``SimplePrograms`` template
146 Contrary to ``Program``, which requires corresponding ``SOURCES``, when using
147 ``SimplePrograms``, the corresponding ``SOURCES`` are implied. If the
148 corresponding ``sources`` have an extension different from ``.cpp``, it is
149 possible to specify the proper extension:
156 Please note this construct was added for compatibility with what already lives
157 in the mozilla tree ; it is recommended not to add new simple programs with
158 sources with a different extension than ``.cpp``.
160 Similar to ``SimplePrograms``, is the ``CppUnitTests`` template, which defines,
161 with the same rules, C++ unit tests programs. Like ``SimplePrograms``, it takes
162 an ``ext`` argument to specify the extension for the corresponding ``SOURCES``,
163 if it's different from ``.cpp``.
166 Linking with system libraries
167 =============================
169 Programs and libraries usually need to link with system libraries, such as a
170 widget toolkit, etc. Those required dependencies can be given with the
171 ``OS_LIBS`` variable.
178 This expands to ``foo.lib bar.lib`` when building with MSVC, and
179 ``-lfoo -lbar`` otherwise.
181 For convenience with ``pkg-config``, ``OS_LIBS`` can also take linker flags
182 such as ``-L/some/path`` and ``-llib``, such that it is possible to directly
183 assign ``LIBS`` variables from ``CONFIG``, such as:
185 OS_LIBS += CONFIG['MOZ_PANGO_LIBS']
187 (assuming ``CONFIG['MOZ_PANGO_LIBS']`` is a list, not a string)
189 Like ``USE_LIBS``, this variable applies to static and shared libraries, as
193 Libraries from third party build system
194 =======================================
196 Some libraries in the tree are not built by the moz.build-governed build
197 system, and there is no ``Library`` corresponding to them.
199 However, ``USE_LIBS`` allows to reference such libraries by giving a full
200 path (like when disambiguating identical ``Library`` names). The same naming
201 rules apply as other uses of ``USE_LIBS``, so only the library name without
202 prefix and suffix shall be given.
205 '/path/from/topsrcdir/to/third-party/bar',
206 '../relative/third-party/baz',
209 Note that ``/path/from/topsrcdir/to/third-party`` and
210 ``../relative/third-party/baz`` must lead under a subconfigured directory (a
211 directory with an AC_OUTPUT_SUBDIRS in configure.in), or ``security/nss``.
214 Building both static and shared libraries
215 =========================================
217 When both types of libraries are required, one needs to set both
218 ``FORCE_SHARED_LIB`` and ``FORCE_STATIC_LIB`` boolean variables.
220 FORCE_SHARED_LIB = True
221 FORCE_STATIC_LIB = True
223 But because static libraries and Windows import libraries have the same file
224 names, either the static or the shared library name needs to be different
225 than the name given to the ``Library`` template.
227 The ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME`` variables can be used
228 to change either the static or the shared library name.
231 STATIC_LIBRARY_NAME = 'foo_s'
233 With the above, on Windows, ``foo_s.lib`` will be the static library,
234 ``foo.dll`` the shared library, and ``foo.lib`` the import library.
236 In some cases, for convenience, it is possible to set both
237 ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME``. For example:
240 STATIC_LIBRARY_NAME = 'mylib_s'
241 SHARED_LIBRARY_NAME = CONFIG['SHARED_NAME']
243 This allows to use ``mylib`` in the ``USE_LIBS`` of another library or
246 When refering to a ``Library`` name building both types of libraries in
247 ``USE_LIBS``, the shared library is chosen to be linked. But sometimes,
248 it is wanted to link the static version, in which case the ``Library`` name
249 needs to be prefixed with ``static:`` in ``USE_LIBS``
253 FORCE_SHARED_LIB = True
254 FORCE_STATIC_LIB = True
255 STATIC_LIBRARY_NAME = 'mylib_s'
266 The ``SDK_LIBRARY`` boolean variable defines whether the library in the current
267 directory is going to be installed in the SDK.
269 The ``SONAME`` variable declares a "shared object name" for the library. It
270 defaults to the ``Library`` name or the ``SHARED_LIBRARY_NAME`` if set. When
271 linking to a library with a ``SONAME``, the resulting library or program will
272 have a dependency on the library with the name corresponding to the ``SONAME``
273 instead of the ``Library`` name. This only impacts ELF systems.
287 On e.g. Linux, the above ``myprog`` will have DT_NEEDED markers for
288 ``libmylib.so`` and ``libfoo.so`` instead of ``libmylib.so`` and
289 ``libotherlib.so`` if there weren't a ``SONAME``. This means the runtime
290 requirement for ``myprog`` is ``libfoo.so`` instead of ``libotherlib.so``.
293 Gecko-related binaries
294 ======================
296 Some programs or libraries are totally independent of Gecko, and can use the
297 above mentioned templates. Others are Gecko-related in some way, and may
298 need XPCOM linkage, mozglue. These things are tedious. A set of additional
299 templates exists to ease defining such programs and libraries. They are
300 essentially the same as the above mentioned templates, prefixed with "Gecko":
303 - ``GeckoSimplePrograms``
304 - ``GeckoCppUnitTests``
305 - ``GeckoSharedLibrary``
308 There is also ``XPCOMBinaryComponent`` for XPCOM components, which is a
309 special kind of library.
311 All the Gecko-prefixed templates take the same arguments as their
312 non-Gecko-prefixed counterparts, and can take a few more arguments
313 for non-standard cases. See the definition of ``GeckoBinary`` in
314 build/gecko_templates.mozbuild for more details, but most usecases
315 should not require these additional arguments.