docs/contributing/build/artifact_builds.rst

   1 Understanding Artifact Builds
   2 =============================
   3
   4 Firefox for Desktop and Android supports a **fast build mode** called
   5 *artifact mode*. The resulting builds are called *artifact builds*.
   6 Artifact mode downloads pre-built C++ components rather than building them
   7 locally, trading bandwidth for time.
   8
   9 Artifact builds will be useful to many developers who are not working
  10 with compiled code (see "Restrictions" below). Artifacts are typically
  11 fetched from `mozilla-central <https://hg.mozilla.org/mozilla-central/>`__.
  12
  13 To automatically download and use pre-built binary artifacts, add the
  14 following lines into your :ref:`mozconfig <Configuring Build Options>`
  15 file:
  16
  17 .. code-block:: shell
  18
  19    # Automatically download and use compiled C++ components:
  20    ac_add_options --enable-artifact-builds
  21
  22    # Write build artifacts to:
  23    mk_add_options MOZ_OBJDIR=./objdir-frontend
  24
  25 To automatically download and use the debug version of the pre-built
  26 binary artifact (currently supported for Linux, OSX and Windows
  27 artifacts), add ``ac_add_options --enable-debug`` to your mozconfig file
  28 (with artifact builds option already enabled):
  29
  30 .. code-block:: shell
  31
  32    # Enable debug versions of the pre-built binary artifacts:
  33    ac_add_options --enable-debug
  34
  35    # Automatically download and use compiled C++ components:
  36    ac_add_options --enable-artifact-builds
  37
  38    # Download debug info so that stack traces refers to file and columns rather than library and Hex address
  39    ac_add_options --enable-artifact-build-symbols
  40
  41    # Write build artifacts to:
  42    mk_add_options MOZ_OBJDIR=./objdir-frontend-debug-artifact
  43
  44
  45 Prerequisites
  46 -------------
  47
  48 Artifact builds are supported for users of Mercurial and Git. Git
  49 artifact builds require a mozilla-central clone made with the help of
  50 `git-cinnabar <https://github.com/glandium/git-cinnabar>`__. Please
  51 follow the instructions on the git-cinnabar project page to install
  52 git-cinnabar. Further information about using git-cinnabar to interact
  53 with Mozilla repositories can be found on `the project
  54 wiki <https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development>`__.
  55
  56 Building
  57 --------
  58
  59 If you've added ``--enable-artifact-builds`` to your ``mozconfig``, each
  60 time you run ``mach build`` and ``mach build path/to/subdirectory`` the
  61 build system will determine what the best pre-built binary artifacts
  62 available are, download them, and put them in place for you. The
  63 computations are cached, so the additional calculations should be very
  64 fast after the up-to-date artifacts are downloaded -- just a second or
  65 two on modern hardware. Most Desktop developers should find that
  66
  67 .. code-block:: shell
  68
  69    ./mach build
  70    ./mach run
  71
  72 just works.
  73
  74 To only rebuild local changes (to avoid re-checking for pushes and/or
  75 unzipping the downloaded cached artifacts after local commits), you can
  76 use:
  77
  78 .. code-block:: shell
  79
  80    ./mach build faster
  81
  82 which only "builds" local JS, CSS and packaged (e.g. images and other
  83 asset) files.
  84
  85 Most Firefox for Android developers should find that
  86
  87 .. code-block:: shell
  88
  89    ./mach build
  90    ./mach package
  91    ./mach install
  92
  93 just works.
  94
  95 Pulling artifacts from a try build
  96 ----------------------------------
  97
  98 To only accept artifacts from a specific revision (such as a try build),
  99 set ``MOZ_ARTIFACT_REVISION`` in your environment to the value of the
 100 revision that is at the head of the desired push. Note that this will
 101 override the default behavior of finding a recent candidate build with
 102 the required artifacts, and will cause builds to fail if the specified
 103 revision does not contain the required artifacts.
 104
 105 Restrictions
 106 ------------
 107
 108 Oh, so many. Artifact builds are rather delicate: any mismatch between
 109 your local source directory and the downloaded binary artifacts can
 110 result in difficult to diagnose incompatibilities, including unexplained
 111 crashes and catastrophic XPCOM initialization and registration
 112 failures. These are rare, but do happen.
 113
 114 Things that are supported
 115 -------------------------
 116
 117 -  Modifying JavaScript, (X)HTML, and CSS resources; and string
 118    properties and DTD and FTL files.
 119 -  Modifying Android Java code, resources, and strings.
 120 -  Running mochitests and xpcshell tests.
 121 -  Modifying ``Scalars.yaml`` to add Scalar Telemetry (since {{
 122    Bug("1425909") }}, except artifact builds on try).
 123 -  Modifying ``Events.yaml`` to add Event Telemetry (since {{
 124    Bug("1448945") }}, except artifact builds on try).
 125
 126 Essentially everything updated by ``mach build faster`` should work with
 127 artifact builds.
 128
 129 Things that are not supported
 130 -----------------------------
 131
 132 -  Support for products other than Firefox for Desktop and
 133    Android are not supported and are unlikely to ever be supported.
 134    Other projects like Thunderbird may provide
 135    `their own support <https://developer.thunderbird.net/thunderbird-development/building-thunderbird/artifact-builds>`__
 136    for artifact builds.
 137 -  You cannot modify C, C++, or Rust source code anywhere in the tree.
 138    If it’s compiled to machine code, it can't be changed.
 139 -  You cannot modify ``histograms.json`` to add Telemetry histogram
 140    definitions.(But see `Bug 1206117 <https://bugzilla.mozilla.org/show_bug.cgi?id=1206117>`__).
 141 -  Modifying build system configuration and definitions does not work in
 142    all situations.
 143
 144 Things that are not **yet** supported
 145 -------------------------------------
 146
 147 -  Tests other than mochitests, xpcshell, and Marionette-based tests.
 148    There aren’t inherent barriers here, but these are not known to work.
 149 -  Modifying WebIDL definitions, even ones implemented in JavaScript.
 150
 151 Troubleshooting
 152 ---------------
 153
 154 There are two parts to artifact mode:
 155 the ``--disable-compile-environment`` option, and the ``mach artifact``
 156 command that implements the downloading and caching. Start by running
 157
 158 .. code-block:: shell
 159
 160    ./mach artifact install --verbose
 161
 162 to see what the build system is trying to do. There is some support for
 163 querying and printing the cache; run ``mach artifact`` to see
 164 information about those commands.
 165
 166 Downloaded artifacts are stored in
 167 ``$MOZBUILD_STATE_PATH/package-frontend``, which is almost always
 168 ``~/.mozbuild/package-frontend``.
 169
 170 Discussion is best started on the `dev-builds mailing
 171 list <https://lists.mozilla.org/listinfo/dev-builds>`__. Questions are
 172 best raised in `#build <https://chat.mozilla.org/#/room/#build:mozilla.org>`__ on `Matrix <https://chat.mozilla.org/>`__. Please
 173 file bugs in *Firefox Build System :: General*, blocking  `Bug 901840 <https://bugzilla.mozilla.org/show_bug.cgi?id=901840>`__