diff options
Diffstat (limited to 'build/docs/toolchains.rst')
| -rw-r--r-- | build/docs/toolchains.rst | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/build/docs/toolchains.rst b/build/docs/toolchains.rst new file mode 100644 index 000000000..eba640fa0 --- /dev/null +++ b/build/docs/toolchains.rst @@ -0,0 +1,111 @@ +.. _build_toolchains: + +=========================== +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 +===== + +See the ``build/build-clang`` directory. Read ``build/build-clang/README`` +for more. + +Windows +======= + +The ``build/windows_toolchain.py`` script is used to build and manage +Windows toolchain archives containing Visual Studio executables, SDKs, +etc. + +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 2015 Community. The download link can be +found at https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx. +Be sure to follow these install instructions: + +1. Choose a ``Custom`` installation and click ``Next`` +2. Select ``Programming Languages`` -> ``Visual C++`` (make sure all sub items are + selected) +3. Under ``Windows and Web Development`` uncheck everything except + ``Universal Windows App Development Tools`` and the items under it + (should be ``Tools (1.3.1)...`` and the ``Windows 10 SDK``). + +Once Visual Studio 2015 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 vs2015u3 + +The produced archive will be the argument to ``create-zip`` + ``.zip``. + +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 special Task Cluster +Docker image and job exist for producing the required archives. The +Docker image definition is rooted in +``taskcluster/docker/android-gradle-build``. The Task Cluster job +definition is in +``testing/taskcluster/tasks/builds/android_api_15_gradle_dependencies.yml``. +The job runs in a container based on the 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. + +Here is `an example try job fetching these dependencies +<https://treeherder.mozilla.org/#/jobs?repo=try&revision=75bc98935147&selectedJob=17793653>`_. +The resulting task produced a `Gradle archive +<https://queue.taskcluster.net/v1/task/CeYMgAP3Q-KF8h37nMhJjg/runs/0/artifacts/public%2Fbuild%2Fgradle.tar.xz>`_ +and a `Maven repository archive +<https://queue.taskcluster.net/v1/task/CeYMgAP3Q-KF8h37nMhJjg/runs/0/artifacts/public%2Fbuild%2Fjcentral.tar.xz>`_. +These archives were then uploaded (manually) to Mozilla automation +using tooltool for consumption in Gradle builds. + +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 +at ``build.gradle``. Once you are confident your changes build +locally, push a fresh try build with an invocation like:: + + $ hg push-to-try -m "try: -b o -p android-api-15-gradle-dependencies" + +Then `upload your archives to tooltool +<https://wiki.mozilla.org/ReleaseEngineering/Applications/Tooltool#How_To_Upload_To_Tooltool>`_, +update the in-tree manifests in +``mobile/android/config/tooltool-manifests``, and push a fresh try +build. |