Creating Toolchain Archives¶
There are various scripts in the repository for producing archives of the build tools (e.g. compilers and linkers) required to build.
Clang and Rust¶
To modify the toolchains used for a particular task, you may need several things:
Which uses a toolchain task
Which uses a git fetch
(clang only) Which uses a config json
Which takes patches you may want to apply.
For the most part, you should be able to accomplish what you want by copying/editing the existing examples in those files.
Note for local builds: build-clang.py can be run on developer machines but its lengthy multi-stage build process is unnecessary for most local development. The upstream LLVM Getting Started Guide has instructions on how to build clang more directly.
Rust builds are handled by repack_rust.py. The primary purpose of that script is to download prebuilt tarballs from the Rust project.
It uses the same basic format as rustup for specifying the toolchain
request a stable build with
request a beta build with
request a nightly build with
request a build from Rust’s ci with
request a from-source build with
Rust From Source¶
As of this writing, from-source builds for Rust are a new feature, and not used anywhere by default. The feature was added so that we can test patches to rustc against the tree. Expect things to be a bit hacky and limited.
Most importantly, building from source requires your toolchain to have a
fetch of the rust tree as well as clang and binutils toolchains. It is also
recommended to upgrade the worker-type to e.g.
Rust’s build dependencies are fairly minimal, and it has a sanity check that should catch any missing or too-old dependencies. See the Rust README for more details.
Patches are set via the –patch flag (passed via
Patch paths are assumed to be relative to
/build/build-rust/, and may be
optionally prefixed with
module-path: to specify they apply to that git
submodule in the Rust source. e.g.
patches rust’s llvm with
/build/build-rust/mypatch.diff. There are no
currently checked in rust patches to use as an example, but they should be
the same format as the clang ones.
Rust builds are not currently configurable, and uses a hardcoded config.toml, which you may need to edit for your purposes. See Rust’s example config for details/defaults. Note that these options do occasionally change, so be sure you’re using options for the version you’re targeting. For instance, there was a large change around Rust ~1.48, and the currently checked in config was for 1.47, so it may not work properly when building the latest version of Rust.
Rust builds are currently limited to targeting only the host platform. Although the machinery is in place to request additional targets, the cross-compilation fails for some unknown reason. We have not yet investigated what needs to be done to get this working.
While Rust generally maintains a clean tree for building
cargo, other tools like
miri are allowed to be
transiently broken. This means not every commit in the Rust tree will be
able to build the tools we require.
rustfmt an optional package, Rust builds
do not currently implement this and will fail if
rustfmt is busted. Some
attempt was made to work around it, but more work is needed.
build/windows_toolchain.py script is used to build and manage
Windows toolchain archives containing Visual Studio executables, SDKs,
The way Firefox build automation works is an archive containing the toolchain is produced and uploaded to an internal Mozilla server. The build automation will download, verify, and extract this archive before building. The archive is self-contained so machines don’t need to install Visual Studio, SDKs, or various other dependencies. Unfortunately, Microsoft’s terms don’t allow Mozilla to distribute this archive publicly. However, the same tool can be used to create your own copy.
Configuring Your System¶
It is highly recommended to perform this process on a fresh installation of Windows 7 or 10 (such as in a VM). Installing all updates through Windows Update is not only acceptable - it is encouraged. Although it shouldn’t matter.
Next, install Visual Studio 2017 Community. The download link can be found at https://www.visualstudio.com/vs/community/. Be sure to follow these install instructions:
Custominstallation and click
Visual C++(make sure all sub items are selected)
Windows and Web Developmentuncheck everything except
Universal Windows App Development Toolsand the items under it (should be
Tools (1.3.1)...and the
Windows 10 SDK).
Once Visual Studio 2017 Community has been installed, from a checkout of mozilla-central, run something like the following to produce a ZIP archive:
$ ./mach python build/windows_toolchain.py create-zip vs2017_15.8.4
The produced archive will be the argument to
Firefox for Android with Gradle¶
To build Firefox for Android with Gradle in automation, archives containing both the Gradle executable and a Maven repository comprising the exact build dependencies are produced and uploaded to an internal Mozilla server. The build automation will download, verify, and extract these archive before building. These archives provide a self-contained Gradle and Maven repository so that machines don’t need to fetch additional Maven dependencies at build time. (Gradle and the downloaded Maven dependencies can be both redistributed publicly.)
Archiving the Gradle executable is straight-forward, but archiving a
local Maven repository is not. Therefore a toolchain job exists for
producing the required archives, android-gradle-dependencies. The
job runs in a container based on a custom Docker image and spawns a
Sonatype Nexus proxying Maven repository process in the background.
The job builds Firefox for Android using Gradle and the in-tree Gradle
configuration rooted at
build.gradle. The spawned proxying Maven
repository downloads external dependencies and collects them. After
the Gradle build completes, the job archives the Gradle version used
to build, and the downloaded Maven repository, and exposes them as
Task Cluster artifacts.
To update the version of Gradle in the archive produced, update
gradle/wrapper/gradle-wrapper.properties. Be sure to also update
the SHA256 checksum to prevent poisoning the build machines!
To update the versions of Gradle dependencies used, update
dependencies sections in the in-tree Gradle configuration rooted
build.gradle. Once you are confident your changes build
locally, push a fresh build to try. The android-gradle-dependencies
toolchain should run automatically, fetching your new dependencies and
wiring them into the appropriate try build jobs.
To update the version of Sonatype Nexus, update the sonatype-nexus fetch task definition.
To modify the Sonatype Nexus configuration, typically to proxy a new remote Maven repository, modify taskcluster/scripts/misc/android-gradle-dependencies/nexus.xml.
There is also a toolchain job that fetches the Android SDK and related packages. To update the versions of packaged fetched, modify python/mozboot/mozboot/android-packages.txt and update the various in-tree versions accordingly.