mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-10 03:45:46 +00:00
0ac52aa9d7
By hybrid unified system we understand a system that encapsulates modules that are built in the unified mode but also other modules, like `dom/Animation`, as an example, in the non unified environment. This approach is desirable since we already have most of the modules transitioned to the non unified system but there are still some that are not yet compatible, but in the long term this will be done by each module owner and can be also tested locally using the build system. If a module can't be built outside the unified method it's `moz.build` config file needs to have `REQUIRES_UNIFIED_BUILD = False` To also enable this we need to have a flag from `mozconfig`, like: ``` ac_add_options --disable-unified-build ``` Differential Revision: https://phabricator.services.mozilla.com/D122328
60 lines
2.8 KiB
ReStructuredText
60 lines
2.8 KiB
ReStructuredText
.. _unified-builds:
|
|
|
|
==============
|
|
Unified Builds
|
|
==============
|
|
|
|
The Firefox build system uses the technique of "unified builds" (or elsewhere
|
|
called "`unity builds <https://en.wikipedia.org/wiki/Unity_build>`_") to
|
|
improve compilation performance. Rather than compiling source files individually,
|
|
groups of files in the same directory are concatenated together, then compiled once
|
|
in a single batch.
|
|
|
|
Unified builds can be configured using the ``UNIFIED_SOURCES`` variable in ``moz.build`` files.
|
|
|
|
.. _unified_build_compilation_failures:
|
|
|
|
Why are there unrelated compilation failures when I change files?
|
|
=================================================================
|
|
|
|
Since multiple files are concatenated together in a unified build, it's possible for a change
|
|
in one file to cause the compilation of a seemingly unrelated file to fail.
|
|
This is usually because source files become implicitly dependent on each other for:
|
|
|
|
* ``#include`` statements
|
|
* ``using namespace ...;`` statements
|
|
* Other symbol imports or definitions
|
|
|
|
One of the more common cases of unexpected failures are when source code files are added or
|
|
removed, and the "chunking" is changed. There's a limit on the number of files that are combined
|
|
together for a single compilation, so sometimes the addition of a new file will cause another one
|
|
to be bumped into a different chunk. If that other chunk doesn't meet the implicit requirements
|
|
of the bumped file, there will be a tough-to-debug compilation failure.
|
|
|
|
Building outside of the unified environment
|
|
===========================================
|
|
|
|
As described above, unified builds can cause source files to implicitly depend on each other, which
|
|
not only causes unexpected build failures but also can cause issues when using source-analysis tools.
|
|
To combat this, we'll use a "hybrid" build that attempts to perform a build with as many files compiled
|
|
individually as possible.
|
|
|
|
Due to the implicit dependency problem, not all modules are able to be compiled in a non-unified
|
|
environment yet. To designate these for the hybrid build, the ``REQUIRES_UNIFIED_BUILD`` option can be
|
|
set in their corresponding ``moz.build`` file.
|
|
|
|
To build in the hybrid mode, set the following flag in your ``mozconfig``:
|
|
|
|
``ac_add_options --disable-unified-build``
|
|
|
|
Other notes:
|
|
============
|
|
|
|
* Some IDEs (such as VSCode with ``clangd``) build files in standalone mode, so they may show
|
|
more failures than a ``mach build``.
|
|
* The amount of files per chunk can be adjusted in ``moz.build`` files with the
|
|
``FILES_PER_UNIFIED_FILE`` variable. Note that changing the chunk size can introduce
|
|
compilation failures as described :ref:`above<unified_build_compilation_failures>`.
|
|
* We are happy to accept patches that fix problematic unified build chunks (such as by adding
|
|
includes or namespace annotations).
|