artifact_builds.rst (7535B)
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 Pulling artifacts from local build / remote URL 106 ----------------------------------------------- 107 108 If you need to do an artifact build against a local build or one hosted 109 somewhere, you need to make use of respectively ``MOZ_ARTIFACT_FILE`` or 110 ``MOZ_ARTIFACT_URL``. In case of a local build, you will have to make sure you 111 112 - produce a package using ``./mach package`` 113 - point to it via ``MOZ_ARTIFACT_FILE=path/to/firefox.tar.bz2`` on your 114 ``./mach build`` command line. The path needs to be absolute, and the package 115 is under your object directory within ``dist/``. 116 117 Using ``MOZ_ARTIFACT_URL`` will download the package at the given URL and then 118 follow the same process as the local build case. 119 120 ``MOZ_ARTIFACT_FILE`` and ``MOZ_ARTIFACT_URL`` only provide the package, they 121 do not provide sibling artifacts including the test artifacts, extra archives 122 such as XPT data, etc. In general, prefer ``MOZ_ARTIFACT_REVISION``, which 123 will can provide these sibling artifacts. 124 125 Restrictions 126 ------------ 127 128 Oh, so many. Artifact builds are rather delicate: any mismatch between 129 your local source directory and the downloaded binary artifacts can 130 result in difficult to diagnose incompatibilities, including unexplained 131 crashes and catastrophic XPCOM initialization and registration 132 failures. These are rare, but do happen. 133 134 Things that are supported 135 ------------------------- 136 137 - Modifying JavaScript, (X)HTML, and CSS resources; and string 138 properties and FTL files. 139 - Modifying Android Java code, resources, and strings. 140 - Running mochitests and xpcshell tests. 141 - Modifying ``Scalars.yaml`` to add Scalar Telemetry (since {{ 142 Bug("1425909") }}, except artifact builds on try). 143 - Modifying ``Events.yaml`` to add Event Telemetry (since {{ 144 Bug("1448945") }}, except artifact builds on try). 145 146 Essentially everything updated by ``mach build faster`` should work with 147 artifact builds. 148 149 Things that are not supported 150 ----------------------------- 151 152 - Support for products other than Firefox for Desktop and 153 Android are not supported and are unlikely to ever be supported. 154 Other projects like Thunderbird may provide 155 `their own support <https://developer.thunderbird.net/thunderbird-development/building-thunderbird/artifact-builds>`__ 156 for artifact builds. 157 - You cannot modify C, C++, or Rust source code anywhere in the tree. 158 If it’s compiled to machine code, it can't be changed. 159 - You cannot modify ``histograms.json`` to add Telemetry histogram 160 definitions.(But see `Bug 1206117 <https://bugzilla.mozilla.org/show_bug.cgi?id=1206117>`__). 161 - Modifying build system configuration and definitions does not work in 162 all situations. 163 164 Things that are not **yet** supported 165 ------------------------------------- 166 167 - Tests other than mochitests, xpcshell, and Marionette-based tests. 168 There aren’t inherent barriers here, but these are not known to work. 169 - Modifying WebIDL definitions, even ones implemented in JavaScript. 170 171 Troubleshooting 172 --------------- 173 174 There are two parts to artifact mode: 175 the ``--disable-compile-environment`` option, and the ``mach artifact`` 176 command that implements the downloading and caching. Start by running 177 178 .. code-block:: shell 179 180 ./mach artifact install --verbose 181 182 to see what the build system is trying to do. There is some support for 183 querying and printing the cache; run ``mach artifact`` to see 184 information about those commands. 185 186 Downloaded artifacts are stored in 187 ``$MOZBUILD_STATE_PATH/package-frontend``, which is almost always 188 ``~/.mozbuild/package-frontend``. 189 190 Discussion is best started on the `dev-builds mailing 191 list <https://lists.mozilla.org/listinfo/dev-builds>`__. Questions are 192 best raised in `#build <https://chat.mozilla.org/#/room/#build:mozilla.org>`__ on `Matrix <https://chat.mozilla.org/>`__. Please 193 file bugs in *Firefox Build System :: General*, blocking `Bug 901840 <https://bugzilla.mozilla.org/show_bug.cgi?id=901840>`__