build/docs/unified-builds.rst

   1 .. _unified-builds:
   2
   3 ==============
   4 Unified Builds
   5 ==============
   6
   7 The Firefox build system uses the technique of "unified builds" (or elsewhere
   8 called "`unity builds <https://en.wikipedia.org/wiki/Unity_build>`_") to
   9 improve compilation performance. Rather than compiling source files individually,
  10 groups of files in the same directory are concatenated together, then compiled once
  11 in a single batch.
  12
  13 Unified builds can be configured using the ``UNIFIED_SOURCES`` variable in ``moz.build`` files.
  14
  15 .. _unified_build_compilation_failures:
  16
  17 Why are there unrelated compilation failures when I change files?
  18 =================================================================
  19
  20 Since multiple files are concatenated together in a unified build, it's possible for a change
  21 in one file to cause the compilation of a seemingly unrelated file to fail.
  22 This is usually because source files become implicitly dependent on each other for:
  23
  24 * ``#include`` statements
  25 * ``using namespace ...;`` statements
  26 * Other symbol imports or definitions
  27
  28 One of the more common cases of unexpected failures are when source code files are added or
  29 removed, and the "chunking" is changed. There's a limit on the number of files that are combined
  30 together for a single compilation, so sometimes the addition of a new file will cause another one
  31 to be bumped into a different chunk. If that other chunk doesn't meet the implicit requirements
  32 of the bumped file, there will be a tough-to-debug compilation failure.
  33
  34 Building outside of the unified environment
  35 ===========================================
  36
  37 As described above, unified builds can cause source files to implicitly depend on each other, which
  38 not only causes unexpected build failures but also can cause issues when using source-analysis tools.
  39 To combat this, we'll use a "non-unified" build that attempts to perform a build with as many files compiled
  40 individually as possible.
  41
  42 To build in the non unified mode, set the following flag in your ``mozconfig``:
  43
  44 ``ac_add_options --disable-unified-build``
  45
  46 Other notes:
  47 ============
  48
  49 * Some IDEs (such as VSCode with ``clangd``) build files in standalone mode, so they may show
  50   more failures than a ``mach build``.
  51 * The amount of files per chunk can be adjusted in ``moz.build`` files with the
  52   ``FILES_PER_UNIFIED_FILE`` variable. Note that changing the chunk size can introduce
  53   compilation failures as described :ref:`above<unified_build_compilation_failures>`.
  54 * We are happy to accept patches that fix problematic unified build chunks (such as by adding
  55   includes or namespace annotations).