Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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