One part of what the build system does is compile C/C++ and link the resulting objects to produce executables and/or libraries. This document describes the basics of defining what is going to be built and how. All the following describes constructs to use in moz.build files.
Source files to be used in a given directory are registered in the
UNIFIED_SOURCES have a special behavior in that they are aggregated by batches of 16, requiring, for example, that there are no conflicting variables in those source files.
UNIFIED_SOURCES are lists which must be appended to, and each append requires the given list to be alphanumerically ordered.
UNIFIED_SOURCES can contain a mix of different file types, for C, C++, and Objective C.
To build a static library, other than defining the source files (see above), one just needs to define a library name with the
The library file name will be
libfoo.a on UNIX systems and
foo.lib on Windows.
If the static library needs to aggregate other static libraries, a list of
Library names can be added to the
USE_LIBS variable. Like
SOURCES, it requires the appended list to be alphanumerically ordered.
If there are multiple directories containing the same
Library name, it is possible to disambiguate by prefixing with the path to the wanted one (relative or absolute):
Note that the leaf name in those paths is the
Library name, not an actual file name.
Note that currently, the build system may not create an actual library for static libraries. It is an implementation detail that shouldn't need to be worried about.
As a special rule,
USE_LIBS is allowed to contain references to shared libraries. In such cases, programs and shared libraries linking this static library will inherit those shared library dependencies.
In many cases in the tree, static libraries are built with the only purpose of being linked into another, bigger one (like libxul). Instead of adding all required libraries to
USE_LIBS for the bigger one, it is possible to tell the build system that the library built in the current directory is meant to be linked to that bigger library, with the
FINAL_LIBRARY value must match a unique
Library name somewhere in the tree.
As a special rule, those intermediate libraries don't need a
Library name for themselves.
Sometimes, we want shared libraries, a.k.a. dynamic libraries. Such libraries are defined similarly to static libraries, using the
SharedLibrary template instead of
When this template is used, no static library is built. See further below to build both types of libraries.
SharedLibrary name of
foo, the library file name will be
libfoo.dylib on OSX,
libfoo.so on ELF systems (Linux, etc.), and
foo.dll on Windows. On Windows, there is also an import library named
foo.lib, used on the linker command line.
libfoo.so are considered the import library name for, resp. OSX and ELF systems.
On OSX, one may want to create a special kind of dynamic library: frameworks. This is done with the
Framework name of
foo, the framework file name will be
foo. This template however affects the behavior on all platforms, so it needs to be set only on OSX.
Executables, a.k.a. programs, are, in the simplest form, defined with the
On UNIX systems, the executable file name will be
foobar, while on Windows, it will be
Like static and shared libraries, the build system can be instructed to link libraries to the executable with
USE_LIBS, listing various
In some cases, we want to create an executable per source file in the current directory, in which case we can use the
Program, which requires corresponding
SOURCES, when using
SimplePrograms, the corresponding
SOURCES are implied. If the corresponding
sources have an extension different from
.cpp, it is possible to specify the proper extension:
Please note this construct was added for compatibility with what already lives in the mozilla tree ; it is recommended not to add new simple programs with sources with a different extension than
SimplePrograms, is the
CppUnitTests template, which defines, with the same rules, C++ unit tests programs. Like
SimplePrograms, it takes an
ext argument to specify the extension for the corresponding
SOURCES, if it's different from
Programs and libraries usually need to link with system libraries, such as a widget toolkit, etc. Those required dependencies can be given with the
This expands to
foo.lib bar.lib when building with MSVC, and
-lfoo -lbar otherwise.
For convenience with
OS_LIBS can also take linker flags such as
-llib, such that it is possible to directly assign
LIBS variables from
CONFIG, such as:
CONFIG['MOZ_PANGO_LIBS'] is a list, not a string)
USE_LIBS, this variable applies to static and shared libraries, as well as programs.
Some libraries in the tree are not built by the moz.build-governed build system, and there is no
Library corresponding to them.
USE_LIBS allows to reference such libraries by giving a full path (like when disambiguating identical
Library names). The same naming rules apply as other uses of
USE_LIBS, so only the library name without prefix and suffix shall be given.
../relative/third-party/baz must lead under a subconfigured directory (a directory with an AC_OUTPUT_SUBDIRS in configure.in), or
When both types of libraries are required, one needs to set both
FORCE_STATIC_LIB boolean variables.
But because static libraries and Windows import libraries have the same file names, either the static or the shared library name needs to be different than the name given to the
SHARED_LIBRARY_NAME variables can be used to change either the static or the shared library name.
With the above, on Windows,
foo_s.lib will be the static library,
foo.dll the shared library, and
foo.lib the import library.
In some cases, for convenience, it is possible to set both
SHARED_LIBRARY_NAME. For example:
This allows to use
mylib in the
USE_LIBS of another library or executable.
When referring to a
Library name building both types of libraries in
USE_LIBS, the shared library is chosen to be linked. But sometimes, it is wanted to link the static version, in which case the
Library name needs to be prefixed with
a/moz.build: Library('mylib') FORCE_SHARED_LIB = True FORCE_STATIC_LIB = True STATIC_LIBRARY_NAME = 'mylib_s' b/moz.build: Program('myprog') USE_LIBS += [ 'static:mylib', ]
SONAME variable declares a "shared object name" for the library. It defaults to the
Library name or the
SHARED_LIBRARY_NAME if set. When linking to a library with a
SONAME, the resulting library or program will have a dependency on the library with the name corresponding to the
SONAME instead of the
Library name. This only impacts ELF systems.
a/moz.build: Library('mylib') b/moz.build: Library('otherlib') SONAME = 'foo' c/moz.build: Program('myprog') USE_LIBS += [ 'mylib', 'otherlib', ]
On e.g. Linux, the above
myprog will have DT_NEEDED markers for
libfoo.so instead of
libotherlib.so if there weren't a
SONAME. This means the runtime requirement for
libfoo.so instead of
Some programs or libraries are totally independent of Gecko, and can use the above mentioned templates. Others are Gecko-related in some way, and may need XPCOM linkage, mozglue. These things are tedious. A set of additional templates exists to ease defining such programs and libraries. They are essentially the same as the above mentioned templates, prefixed with "Gecko":
All the Gecko-prefixed templates take the same arguments as their non-Gecko-prefixed counterparts, and can take a few more arguments for non-standard cases. See the definition of
GeckoBinary in build/gecko_templates.mozbuild for more details, but most usecases should not require these additional arguments.