mirror of
https://github.com/mozilla/gecko-dev.git
synced 2025-02-10 01:08:21 +00:00
Bug 1036894 part 10 - Documentation for programs and libraries in moz.build world. r=gps
This commit is contained in:
Mike Hommey
parent
95063176fa
commit
1c8e21d2d8
233
build/docs/defining-binaries.rst
Normal file
233
build/docs/defining-binaries.rst
Normal file
@ -0,0 +1,233 @@
|
||||
.. _defining_binaries:
|
||||
|
||||
======================================
|
||||
Defining Binaries for the Build System
|
||||
======================================
|
||||
|
||||
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
|
||||
============
|
||||
|
||||
Source files to be used in a given directory are registered in the ``SOURCES``
|
||||
and ``UNIFIED_SOURCES`` variables. ``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.
|
||||
|
||||
``SOURCES`` and ``UNIFIED_SOURCES`` are lists which must be appended to, and
|
||||
each append requires the given list to be alphanumerically ordered.
|
||||
|
||||
UNIFIED_SOURCES += [
|
||||
'FirstSource.cpp',
|
||||
'SecondSource.cpp',
|
||||
'ThirdSource.cpp',
|
||||
]
|
||||
|
||||
SOURCES += [
|
||||
'OtherSource.cpp',
|
||||
]
|
||||
|
||||
``SOURCES`` and ``UNIFIED_SOURCES`` can contain a mix of different file types,
|
||||
for C, C++, and Objective C.
|
||||
|
||||
|
||||
Static Libraries
|
||||
================
|
||||
|
||||
To build a static library, other than defining the source files (see above), one
|
||||
just needs to define a library name with the ``LIBRARY_NAME`` variable.
|
||||
|
||||
LIBRARY_NAME = 'foo'
|
||||
|
||||
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_NAME`` can be added to the ``USE_LIBS`` variable. Like ``SOURCES``, it
|
||||
requires the appended list to be alphanumerically ordered.
|
||||
|
||||
USE_LIBS += ['bar', 'baz']
|
||||
|
||||
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):
|
||||
|
||||
USE_LIBS += [
|
||||
'/path/from/topsrcdir/to/bar',
|
||||
'../relative/baz',
|
||||
]
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Intermediate (Static) Libraries
|
||||
===============================
|
||||
|
||||
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`` variable.
|
||||
|
||||
FINAL_LIBRARY = 'xul'
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Shared Libraries
|
||||
================
|
||||
|
||||
Sometimes, we want shared libraries, a.k.a. dynamic libraries. Such libraries
|
||||
are defined with the same variables as static libraries, with the addition of
|
||||
the ``FORCE_SHARED_LIB`` boolean variable:
|
||||
|
||||
FORCE_SHARED_LIB = True
|
||||
|
||||
When this variable is set, no static library is built. See further below to
|
||||
build both types of libraries.
|
||||
|
||||
With a ``LIBRARY_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.dylib`` and
|
||||
``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 ``IS_FRAMEWORK`` boolean variable.
|
||||
|
||||
IS_FRAMEWORK = True
|
||||
|
||||
With a ``LIBRARY_NAME`` of ``foo``, the framework file name will be ``foo``.
|
||||
This variable however affects the behavior on all platforms, so it needs to
|
||||
be set only on OSX.
|
||||
|
||||
Another special kind of library, XPCOM-specific, are XPCOM components. One can
|
||||
build such a component with the ``IS_COMPONENT`` boolean variable.
|
||||
|
||||
IS_COMPONENT = True
|
||||
|
||||
|
||||
Executables
|
||||
===========
|
||||
|
||||
Executables, a.k.a. programs, are, in the simplest form, defined with the
|
||||
``PROGRAM`` variable.
|
||||
|
||||
PROGRAM = 'foobar'
|
||||
|
||||
On UNIX systems, the executable file name will be ``foobar``, while on Windows,
|
||||
it will be ``foobar.exe``.
|
||||
|
||||
Like static and shared libraries, the build system can be instructed to link
|
||||
libraries to the executable with ``USE_LIBS``, listing various ``LIBRARY_NAME``.
|
||||
|
||||
In some cases, we want to create an executable per source file in the current
|
||||
directory, in which case we can use the ``SIMPLE_PROGRAMS`` list:
|
||||
|
||||
SIMPLE_PROGRAMS = [
|
||||
'FirstProgram',
|
||||
'SecondProgram',
|
||||
]
|
||||
|
||||
The corresponding ``SOURCES`` must match:
|
||||
|
||||
SOURCES += [
|
||||
'FirstProgram.cpp',
|
||||
'SecondProgram.c',
|
||||
]
|
||||
|
||||
Similar to ``SIMPLE_PROGRAMS``, is ``CPP_UNIT_TESTS``, which defines, with the
|
||||
same rules, C++ unit tests programs.
|
||||
|
||||
|
||||
Building both static and shared libraries
|
||||
=========================================
|
||||
|
||||
When both types of libraries are required, one needs to set both
|
||||
``FORCE_SHARED_LIB`` and ``FORCE_STATIC_LIB`` boolean variables.
|
||||
|
||||
FORCE_SHARED_LIB = True
|
||||
FORCE_STATIC_LIB = True
|
||||
|
||||
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 ``LIBRARY_NAME``.
|
||||
|
||||
The ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME`` variables can be used
|
||||
to change either the static or the shared library name.
|
||||
|
||||
LIBRARY_NAME = 'foo'
|
||||
STATIC_LIBRARY_NAME = 'foo_s'
|
||||
|
||||
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
|
||||
``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME``. For example:
|
||||
|
||||
LIBRARY_NAME = 'mylib'
|
||||
STATIC_LIBRARY_NAME = 'mylib_s'
|
||||
SHARED_LIBRARY_NAME = CONFIG['SHARED_NAME']
|
||||
|
||||
This allows to use ``mylib`` in the ``USE_LIBS`` of another library or
|
||||
executable.
|
||||
|
||||
When refering 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 ``static:`` in ``USE_LIBS``
|
||||
|
||||
a/moz.build:
|
||||
LIBRARY_NAME = 'mylib'
|
||||
FORCE_SHARED_LIB = True
|
||||
FORCE_STATIC_LIB = True
|
||||
STATIC_LIBRARY_NAME = 'mylib_s'
|
||||
b/moz.build:
|
||||
PROGRAM = 'myprog'
|
||||
USE_LIBS += [
|
||||
'static:mylib',
|
||||
]
|
||||
|
||||
|
||||
Miscellaneous
|
||||
=============
|
||||
|
||||
The ``SDK_LIBRARY`` boolean variable defines whether the library in the current
|
||||
directory is going to be installed in the SDK.
|
||||
|
||||
The ``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 ``LIBRARY_NAME``. This only impacts ELF systems.
|
||||
|
||||
a/moz.build:
|
||||
LIBRARY_NAME = 'mylib'
|
||||
b/moz.build:
|
||||
LIBRARY_NAME = '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
|
||||
``libmylib.so`` and ``libfoo.so`` instead of ``libmylib.so`` and
|
||||
``libotherlib.so`` if there weren't a ``SONAME``. This means the runtime
|
||||
requirement for ``myprog`` is ``libfoo.so`` instead of ``libotherlib.so``.
|
||||
@ -22,6 +22,7 @@ Important Concepts
|
||||
mozinfo
|
||||
preprocessor
|
||||
jar-manifests
|
||||
defining-binaries
|
||||
|
||||
integrated development environment (IDE)
|
||||
========================================
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user