This page covers the steps needed to build a bleeding-edge, development version of Firefox for Desktop or Firefox for Android using pre-built binary artifacts. Welcome, we're delighted to see you! :)
If you're having trouble following this documentation or hit a roadblock you can't get around, please contact Nick Alexander at email@example.com directly so we can solve the problem for you and every new contributor after you.
For additional information, see the general Firefox build documentation.
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.
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 # Write build artifacts to: mk_add_options MOZ_OBJDIR=./objdir-frontend-debug-artifact
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.
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
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
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.
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 Android Java code, resources, and strings.
- Running mochitests and xpcshell tests.
Scalars.yamlto add Scalar Telemetry (since bug 1425909, except artifact builds on try).
Events.yamlto 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
- Products other than Firefox for Desktop and Firefox for Android are not supported and are unlikely to ever be supported.
- You cannot modify C or C++ source code anywhere in the tree. If it's compiled to machine code, it can't be changed.
- You cannot modify
histograms.jsonto 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 or xpcshell tests. There aren't inherent barriers here, but these are not known to work.
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