diff options
Diffstat (limited to 'docs/contributing/build')
| -rw-r--r-- | docs/contributing/build/artifact_builds.rst | 193 | ||||
| -rw-r--r-- | docs/contributing/build/building_mobile_firefox.rst | 34 | ||||
| -rw-r--r-- | docs/contributing/build/supported.rst | 1 |
3 files changed, 228 insertions, 0 deletions
diff --git a/docs/contributing/build/artifact_builds.rst b/docs/contributing/build/artifact_builds.rst new file mode 100644 index 0000000000..302331e4c0 --- /dev/null +++ b/docs/contributing/build/artifact_builds.rst @@ -0,0 +1,193 @@ +Understanding Artifact Builds +============================= + +Firefox for Desktop and Android supports a **fast build mode** called +*artifact mode*. The resulting builds are called *artifact builds*. +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 `mozilla-central <https://hg.mozilla.org/mozilla-central/>`__. + +To automatically download and use pre-built binary artifacts, add the +following lines into your :ref:`mozconfig <Configuring Build Options>` +file: + +.. code-block:: shell + + # 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): + +.. code-block:: shell + + # 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 <https://github.com/glandium/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 <https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development>`__. + +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 + +.. code-block:: shell + + ./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: + +.. code-block:: shell + + ./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 + +.. code-block:: shell + + ./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. + +Pulling artifacts from local build / remote URL +----------------------------------------------- + +If you need to do an artifact build against a local build or one hosted +somewhere, you need to make use of respectively ``MOZ_ARTIFACT_FILE`` or +``MOZ_ARTIFACT_URL``. In case of a local build, you will have to make sure you + +- produce a package using ``./mach package`` +- point to it via ``MOZ_ARTIFACT_FILE=path/to/firefox.tar.bz2`` on your + ``./mach build`` command line. The path needs to be absolute, and the package + is under your object directory within ``dist/``. + +Using ``MOZ_ARTIFACT_URL`` will download the package at the given URL and then +follow the same process as the local build case. + +``MOZ_ARTIFACT_FILE`` and ``MOZ_ARTIFACT_URL`` only provide the package, they +do not provide sibling artifacts including the test artifacts, extra archives +such as XPT data, etc. In general, prefer ``MOZ_ARTIFACT_REVISION``, which +will can provide these sibling 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 FTL 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 + Android are not supported and are unlikely to ever be supported. + Other projects like Thunderbird may provide + `their own support <https://developer.thunderbird.net/thunderbird-development/building-thunderbird/artifact-builds>`__ + 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 <https://bugzilla.mozilla.org/show_bug.cgi?id=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. + +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 + +.. code-block:: shell + + ./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 <https://lists.mozilla.org/listinfo/dev-builds>`__. Questions are +best raised in `#build <https://chat.mozilla.org/#/room/#build:mozilla.org>`__ on `Matrix <https://chat.mozilla.org/>`__. Please +file bugs in *Firefox Build System :: General*, blocking `Bug 901840 <https://bugzilla.mozilla.org/show_bug.cgi?id=901840>`__ diff --git a/docs/contributing/build/building_mobile_firefox.rst b/docs/contributing/build/building_mobile_firefox.rst new file mode 100644 index 0000000000..90e922af8a --- /dev/null +++ b/docs/contributing/build/building_mobile_firefox.rst @@ -0,0 +1,34 @@ +Firefox for Mobile Devices +-------------------------- + +We have several different mobile products aimed at different tasks, +devices, and audiences: + +- Building **Firefox for Android** (codename: fenix). Our general-purpose + mobile browser is split into several different artifact layers: + + - `The fenix Android application </mobile/android/fenix.html>`_ + - `The android-components Android library <https://github.com/mozilla-mobile/firefox-android/tree/main/android-components>`_ + - `The GeckoView platform </mobile/android/geckoview>`_ + +- `Firefox for iOS <https://github.com/mozilla-mobile/firefox-ios>`_, + our general-purpose browser for iOS with desktop sync built-in. +- Building **Firefox Focus**, our privacy-focused browser for + + - `iOS <https://github.com/mozilla-mobile/focus-ios>`_ + - `Android <https://github.com/mozilla-mobile/firefox-android/tree/main/focus-android>`_. This browser + also uses the android-components library and GeckoView platform, like Firefox for Android + +For both Desktop and Mobile development, please bear the following in +mind: + +- While you can build Firefox on older hardware it can take quite a bit + of time to compile on slower machines. Having at least 8GB of RAM is + recommended, and more is always better. The build process is both CPU + and I/O intensive, so building on a machine with an SSD is also + strongly preferred. +- Fast broadband internet is strongly recommended as well. Both the + development environment and the source code repository are quite + large. +- Though you can build Firefox to run on 32-bit machines, the build + process for almost all of our products requires a 64-bit OS. diff --git a/docs/contributing/build/supported.rst b/docs/contributing/build/supported.rst new file mode 100644 index 0000000000..4223f812ff --- /dev/null +++ b/docs/contributing/build/supported.rst @@ -0,0 +1 @@ +.. include:: ../../build/buildsystem/supported-configurations.rst |