Artifact builds

For additional information, see the general Firefox build documentation.

Artifact builds

Firefox for Desktop and Android supports a fast build mode called artifact mode.  The resulting builds are called artifact builds.  (Some mobile team managers call it manager mode since it's particularly helpful if you only write code infrequently.)  Artifact mode downloads pre-built C++ components rather than building them locally, trading bandwidth for time.

Artifact builds will be useful to many developers who are not working with compiled code (see "Restrictions" below). Artifacts are typically fetched from fx-team, mozilla-inbound, or mozilla-central.

To automatically download and use pre-built binary artifacts, add the following lines into your mozconfig file:

# Automatically download and use compiled C++ components:
ac_add_options --enable-artifact-builds

# Write build artifacts to:
mk_add_options MOZ_OBJDIR=./objdir-frontend

To automatically download and use the debug version of the pre-built binary artifact (currently supported for Linux, OSX and Windows artifacts), add ac_add_options --enable-debug to your mozconfig file (with artifact builds option already enabled):

# Enable debug versions of the pre-built binary artifacts:
ac_add_options --enable-debug

# Automatically download and use compiled C++ components:
ac_add_options --enable-artifact-builds

# Download debug info so that stack traces refers to file and columns rather than library and Hex address
ac_add_options --enable-artifact-build-symbols 

# Write build artifacts to:
mk_add_options MOZ_OBJDIR=./objdir-frontend-debug-artifact

Prerequisites

Artifact builds are supported for users of Mercurial and Git. Git artifact builds require a mozilla-central clone made with the help of git-cinnabar. Please follow the instructions on the git-cinnabar project page to install git-cinnabar. Further information about using git-cinnabar to interact with Mozilla repositories can be found on the project wiki.

Building

If you've added --enable-artifact-builds to your mozconfig, each time you run mach build and mach build path/to/subdirectory the build system will determine what the best pre-built binary artifacts available are, download them, and put them in place for you.  The computations are cached, so the additional calculations should be very fast after the up-to-date artifacts are downloaded -- just a second or two on modern hardware.  Most Desktop developers should find that

./mach build
./mach run

just works. 

To only rebuild local changes (to avoid re-checking for pushes and/or unzipping the downloaded cached artifacts after local commits), you can use:

./mach build faster

which only "builds" local JS, CSS and packaged (e.g. images and other asset) files.

Most Firefox for Android developers should find that

./mach build
./mach package
./mach install

just works.

Pulling artifacts from a try build

To only accept artifacts from a specific revision (such as a try build), set MOZ_ARTIFACT_REVISION in your environment to the value of the revision that is at the head of the desired push. Note that this will override the default behavior of finding a recent candidate build with the required artifacts, and will cause builds to fail if the specified revision does not contain the required artifacts.

Restrictions

Oh, so many.  Artifact builds are rather delicate: any mismatch between your local source directory and the downloaded binary artifacts can result in difficult to diagnose incompatibilities, including unexplained crashes and catastrophic XPCOM initialization and registration failures.  These are rare, but do happen.

Things that are supported

• Modifying JavaScript, (X)HTML, and CSS resources; and string properties and DTD files.
• Modifying Android Java code, resources, and strings.
• Running mochitests and xpcshell tests.
• Modifying Scalars.yaml to add Scalar Telemetry (since bug 1425909, except artifact builds on try).
• Modifying Events.yaml to add Event Telemetry (since bug 1448945, except artifact builds on try).

Essentially everything updated by mach build faster should work with artifact builds.

Things that are not supported

• Support for products other than Firefox for Desktop and Firefox for Android is not maintained. Other projects like Thunderbird may provide their own support for artifact builds.
• You cannot modify C, C++, or Rust source code anywhere in the tree.  If it’s compiled to machine code, it can't be changed.
• You cannot modify histograms.json to add Telemetry histogram definitions.  (But see bug 1206117.).
• Modifying build system configuration and definitions does not work in all situations.

Things that are not yet supported

• Tests other than mochitests, xpcshell, and Marionette-based tests. There aren’t inherent barriers here, but these are not known to work.
• Modifying WebIDL definitions, even ones implemented in JavaScript.  We don’t really know if there are barriers to making this work, and would appreciate somebody trying it and documenting the results.

Troubleshooting

There are two parts to artifact mode: the --disable-compile-environment option, and the mach artifact command that implements the downloading and caching.  Start by running

./mach artifact install --verbose

to see what the build system is trying to do.  There is some support for querying and printing the cache; run mach artifact to see information about those commands.

Downloaded artifacts are stored in $MOZBUILD_STATE_PATH/package-frontend, which is almost always ~/.mozbuild/package-frontend.

Discussion is best started on the dev-builds mailing list.  Questions are best raised in #build on IRC.  Please file bugs in Firefox Build System :: General, blocking bug 901840.