mirror of
https://gitlab.winehq.org/wine/wine-gecko.git
synced 2024-09-13 09:24:08 -07:00
886d400168
Sphinx has been complaining about a number of reStructuredText warnings for a while. Fix all the ones in .rst files. Not asking for review because this is docs only and changing .rst files can't break anything important. DONTBUILD (NPOTB)
352 lines
11 KiB
ReStructuredText
352 lines
11 KiB
ReStructuredText
.. _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.
|
|
|
|
.. code-block:: python
|
|
|
|
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`` template.
|
|
|
|
.. code-block:: python
|
|
|
|
Library('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`` names can be added to the ``USE_LIBS`` variable. Like ``SOURCES``, it
|
|
requires the appended list to be alphanumerically ordered.
|
|
|
|
.. code-block:: python
|
|
|
|
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):
|
|
|
|
.. code-block:: python
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
.. code-block:: python
|
|
|
|
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 similarly to static libraries, using the ``SharedLibrary`` template
|
|
instead of ``Library``.
|
|
|
|
.. code-block:: python
|
|
|
|
SharedLibrary('foo')
|
|
|
|
When this template is used, no static library is built. See further below to
|
|
build both types of libraries.
|
|
|
|
With a ``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.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 ``Framework`` template.
|
|
|
|
.. code-block:: python
|
|
|
|
Framework('foo')
|
|
|
|
With a ``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
|
|
===========
|
|
|
|
Executables, a.k.a. programs, are, in the simplest form, defined with the
|
|
``Program`` template.
|
|
|
|
.. code-block:: python
|
|
|
|
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``
|
|
names.
|
|
|
|
In some cases, we want to create an executable per source file in the current
|
|
directory, in which case we can use the ``SimplePrograms`` template
|
|
|
|
.. code-block:: python
|
|
|
|
SimplePrograms([
|
|
'FirstProgram',
|
|
'SecondProgram',
|
|
])
|
|
|
|
Contrary to ``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:
|
|
|
|
.. code-block:: python
|
|
|
|
SimplePrograms([
|
|
'ThirdProgram',
|
|
'FourthProgram',
|
|
], ext='.c')
|
|
|
|
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 ``.cpp``.
|
|
|
|
Similar to ``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 ``.cpp``.
|
|
|
|
|
|
Linking with system libraries
|
|
=============================
|
|
|
|
Programs and libraries usually need to link with system libraries, such as a
|
|
widget toolkit, etc. Those required dependencies can be given with the
|
|
``OS_LIBS`` variable.
|
|
|
|
.. code-block:: python
|
|
|
|
OS_LIBS += [
|
|
'foo',
|
|
'bar',
|
|
]
|
|
|
|
This expands to ``foo.lib bar.lib`` when building with MSVC, and
|
|
``-lfoo -lbar`` otherwise.
|
|
|
|
For convenience with ``pkg-config``, ``OS_LIBS`` can also take linker flags
|
|
such as ``-L/some/path`` and ``-llib``, such that it is possible to directly
|
|
assign ``LIBS`` variables from ``CONFIG``, such as:
|
|
|
|
.. code-block:: python
|
|
|
|
OS_LIBS += CONFIG['MOZ_PANGO_LIBS']
|
|
|
|
(assuming ``CONFIG['MOZ_PANGO_LIBS']`` is a list, not a string)
|
|
|
|
Like ``USE_LIBS``, this variable applies to static and shared libraries, as
|
|
well as programs.
|
|
|
|
|
|
Libraries from third party build system
|
|
=======================================
|
|
|
|
Some libraries in the tree are not built by the moz.build-governed build
|
|
system, and there is no ``Library`` corresponding to them.
|
|
|
|
However, ``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.
|
|
|
|
.. code-block:: python
|
|
|
|
USE_LIBS += [
|
|
'/path/from/topsrcdir/to/third-party/bar',
|
|
'../relative/third-party/baz',
|
|
]
|
|
|
|
Note that ``/path/from/topsrcdir/to/third-party`` and
|
|
``../relative/third-party/baz`` must lead under a subconfigured directory (a
|
|
directory with an AC_OUTPUT_SUBDIRS in configure.in), or ``security/nss``.
|
|
|
|
|
|
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.
|
|
|
|
.. code-block:: python
|
|
|
|
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 the name given to the ``Library`` template.
|
|
|
|
The ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME`` variables can be used
|
|
to change either the static or the shared library name.
|
|
|
|
.. code-block:: python
|
|
|
|
Library('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:
|
|
|
|
.. code-block:: python
|
|
|
|
Library('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('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 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
|
|
``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``.
|
|
|
|
|
|
Gecko-related binaries
|
|
======================
|
|
|
|
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":
|
|
|
|
- ``GeckoProgram``
|
|
- ``GeckoSimplePrograms``
|
|
- ``GeckoCppUnitTests``
|
|
- ``GeckoSharedLibrary``
|
|
- ``GeckoFramework``
|
|
|
|
There is also ``XPCOMBinaryComponent`` for XPCOM components, which is a
|
|
special kind of library.
|
|
|
|
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.
|