1.. _build_toolchains:
2
3===========================
4Creating Toolchain Archives
5===========================
6
7There are various scripts in the repository for producing archives
8of the build tools (e.g. compilers and linkers) required to build.
9
10Clang
11=====
12
13See the ``build/build-clang`` directory. Read ``build/build-clang/README``
14for more.
15
16Windows
17=======
18
19The ``build/windows_toolchain.py`` script is used to build and manage
20Windows toolchain archives containing Visual Studio executables, SDKs,
21etc.
22
23The way Firefox build automation works is an archive containing the
24toolchain is produced and uploaded to an internal Mozilla server. The
25build automation will download, verify, and extract this archive before
26building. The archive is self-contained so machines don't need to install
27Visual Studio, SDKs, or various other dependencies. Unfortunately,
28Microsoft's terms don't allow Mozilla to distribute this archive
29publicly. However, the same tool can be used to create your own copy.
30
31Configuring Your System
32-----------------------
33
34It is **highly** recommended to perform this process on a fresh installation
35of Windows 7 or 10 (such as in a VM). Installing all updates through
36Windows Update is not only acceptable - it is encouraged. Although it
37shouldn't matter.
38
39Next, install Visual Studio 2015 Community. The download link can be
40found at https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx.
41Be sure to follow these install instructions:
42
431. Choose a ``Custom`` installation and click ``Next``
442. Select ``Programming Languages`` -> ``Visual C++`` (make sure all sub items are
45   selected)
463. Under ``Windows and Web Development`` uncheck everything except
47   ``Universal Windows App Development Tools`` and the items under it
48   (should be ``Tools (1.3.1)...`` and the ``Windows 10 SDK``).
49
50Once Visual Studio 2015 Community has been installed, from a checkout
51of mozilla-central, run something like the following to produce a ZIP
52archive::
53
54   $ ./mach python build/windows_toolchain.py create-zip vs2017_15.4.2
55
56The produced archive will be the argument to ``create-zip`` + ``.zip``.
57
58Firefox for Android with Gradle
59===============================
60
61To build Firefox for Android with Gradle in automation, archives
62containing both the Gradle executable and a Maven repository
63comprising the exact build dependencies are produced and uploaded to
64an internal Mozilla server.  The build automation will download,
65verify, and extract these archive before building.  These archives
66provide a self-contained Gradle and Maven repository so that machines
67don't need to fetch additional Maven dependencies at build time.
68(Gradle and the downloaded Maven dependencies can be both
69redistributed publicly.)
70
71Archiving the Gradle executable is straight-forward, but archiving a
72local Maven repository is not.  Therefore a special Task Cluster
73Docker image and toolchain job exist for producing the required
74archives.  The Docker image definition is rooted in
75``taskcluster/docker/android-build``.  The Task Cluster toolchain job
76is named `android-gradle-dependencies`.  The job runs in a container
77based on the custom Docker image and spawns a Sonatype Nexus proxying
78Maven repository process in the background.  The job builds Firefox
79for Android using Gradle and the in-tree Gradle configuration rooted
80at ``build.gradle``.  The spawned proxying Maven repository downloads
81external dependencies and collects them.  After the Gradle build
82completes, the job archives the Gradle version used to build, and the
83downloaded Maven repository, and exposes them as Task Cluster
84artifacts.
85
86To update the version of Gradle in the archive produced, update
87``gradle/wrapper/gradle-wrapper.properties``.  Be sure to also update
88the SHA256 checksum to prevent poisoning the build machines!
89
90To update the versions of Gradle dependencies used, update
91``dependencies`` sections in the in-tree Gradle configuration rooted
92at ``build.gradle``.  Once you are confident your changes build
93locally, push a fresh build to try.  The `android-gradle-dependencies`
94toolchain should run automatically, fetching your new dependencies and
95wiring them into the appropriate try build jobs.
96
97To update the version of Sonatype Nexus, update `NEXUS_VERSION` in the
98`android-build` Docker image.
99
100To modify the Sonatype Nexus configuration, typically to proxy a new
101remote Maven repository, modify
102`taskcluster/scripts/misc/android-gradle-dependencies/nexus.xml`.
103
104There is also a toolchain job that fetches the Android SDK and related
105packages.  To update the versions of packaged fetched, modify
106`python/mozboot/mozboot/android-packages.txt` and update the various
107in-tree versions accordingly.
108