Adding upstream version 124.0.1.upstream/124.0.1

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

8 files changed, 1234 insertions, 0 deletions

diff --git a/docs/setup/building_with_debug_symbols.rst b/docs/setup/building_with_debug_symbols.rst
new file mode 100644
index 0000000000..596bd9010b
--- /dev/null
+++ b/docs/setup/building_with_debug_symbols.rst
@@ -0,0 +1,61 @@
+Building with Debug Symbols
+===========================
+
++--------------------------------------------------------------------+
+| This page is an import from MDN and the contents might be outdated |
++--------------------------------------------------------------------+
+
+By default, a release build of Firefox will not generate debug symbols
+suitable for debugging or post-processing into the
+:ref:`breakpad <Crash reporting>` symbol format. Use the
+following :ref:`mozconfig <Configuring Build Options>` settings
+to do a build with symbols:
+
+
+
+Building Firefox with symbols
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is a single configure option to enable building with symbols on
+all platforms. This is enabled by default so unless you have explicitly
+disabled it your build you should include symbols.
+
+::
+
+   ac_add_options --enable-debug-symbols
+
+This can optionally take an argument for the type of symbols that need
+to be produced (like "-g3"). By default it uses "-g" on Linux and MacOS.
+This value takes precedence over the flags set in ``MOZ_DEBUG_FLAGS``
+
+Note that this will override the values provided for ``CFLAGS`` and
+``CXXFLAGS``.
+
+
+Breakpad symbol files
+~~~~~~~~~~~~~~~~~~~~~
+
+After the build is complete, run the following command to generate an
+archive of :ref:`Breakpad <Crash reporting>` symbol files:
+
+.. code:: bash
+
+   mach buildsymbols
+
+Treeherder uses an additional ``uploadsymbols`` target to upload
+symbols to a socorro server. See
+https://searchfox.org/mozilla-central/source/toolkit/crashreporter/tools/upload_symbols.py
+for more information about the environment variables used by this
+target.
+
+
+``make package``
+~~~~~~~~~~~~~~~~
+
+If you use ``make package`` to package your build, symbols will be
+stripped. If you want to keep the symbols in the patches, you need to
+add this to your mozconfig:
+
+.. code::
+
+    ac_add_options --disable-install-strip
diff --git a/docs/setup/configuring_build_options.rst b/docs/setup/configuring_build_options.rst
new file mode 100644
index 0000000000..0afded76cd
--- /dev/null
+++ b/docs/setup/configuring_build_options.rst
@@ -0,0 +1,407 @@
+Configuring Build Options
+=========================
+
++--------------------------------------------------------------------+
+| This page is an import from MDN and the contents might be outdated |
++--------------------------------------------------------------------+
+
+This document details how to configure Firefox builds.
+Most of the time a ``mozconfig`` file is not required. The default
+options are the most well-supported, so it is preferable to add as few
+options as possible. Please read the following directions carefully
+before building, and follow them in order. Skipping any step may cause
+the build to fail, or the built software to be unusable. Build options,
+including options not usable from the command-line, may appear in
+"``confvars.sh``" files in the source tree.
+
+
+Using a ``mozconfig`` configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The choice of which Mozilla project to build and other configuration
+options can be configured in a ``mozconfig`` file. (It is possible to
+manually call ``configure`` with command-line options, but this is not
+recommended). The ``mozconfig`` file should be in your source directory
+(that is, ``/mozilla-central/mozconfig``).
+
+Create a blank ``mozconfig`` file:
+
+.. code:: bash
+
+    echo "# My first mozilla config" > mozconfig
+
+If your mozconfig isn't in your source directory, you can also use the
+``MOZCONFIG`` environment variable to specify the path to your
+``mozconfig``. The path you specify **must** be an **absolute** path or
+else ``client.mk`` will not find it. This is useful if you choose to
+have multiple ``mozconfig`` files for different projects or
+configurations (see below for a full example). Note that in the
+``export`` example below the filename was not ``mozconfig``. Regardless
+of the name of the actual file you use, we refer to this file as the
+``mozconfig`` file in the examples below.
+
+Setting the ``mozconfig`` path:
+
+.. code:: bash
+
+   export MOZCONFIG=$HOME/mozilla/mozconfig-firefox
+
+.. note::
+
+   Calling the file ``.mozconfig`` (with a leading dot) is also
+   supported, but this is not recommended because it may make the file
+   harder to find. This will also help when troubleshooting because
+   people will want to know which build options you have selected and
+   will assume that you have put them in your ``mozconfig`` file.
+
+
+``mozconfig`` contains two types of options:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Options prefixed with ``mk_add_options`` are passed to
+   ``client.mk``. The most important of these is ``MOZ_OBJDIR``, which
+   controls where your project gets built (also known as the object
+   directory).
+-  Options prefixed with ``ac_add_options`` are passed to ``configure``,
+   and affect the build process.
+
+
+Building with an objdir
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This means that the source code and object files are not intermingled in
+your directory system and you can build multiple projects (e.g.,
+Firefox and Thunderbird) from the same source tree. If you do not
+specify a ``MOZ_OBJDIR``, it will be automatically set to
+``@TOPSRCDIR@/obj-@CONFIG_GUESS@``.
+
+If you need to re-run ``configure``, the easiest way to do it is using
+``./mach configure``; running ``configure`` manually is strongly
+discouraged.
+
+Adding the following line to your ``mozconfig`` allows you to change the
+objdir:
+
+.. code:: bash
+
+   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-@CONFIG_GUESS@
+
+It is a good idea to have your objdir name start with ``obj`` so that
+Mercurial ignores it.
+
+Sometimes it can be useful to build multiple versions of the source
+(such as with and without diagnostic asserts). To avoid the time it
+takes to do a full rebuild, you can create multiple ``mozconfig`` files
+which specify different objdirs. For example, a ``mozconfig-dbg``:
+
+.. code:: bash
+
+   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-dbg
+   ac_add_options --enable-debug
+
+and a ``mozconfig-rel-opt``:
+
+.. code:: bash
+
+   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-rel-opt
+   ac_add_options --disable-debug
+   ac_add_options --enable-optimize
+
+allow for building both versions by specifying the configuration via
+the ``MOZCONFIG`` environment variable:
+
+.. code:: bash
+
+   $ env MOZCONFIG=/path/to/mozconfig-dbg ./mach build
+   $ env MOZCONFIG=/path/to/mozconfig-rel-opt ./mach build
+
+Don't forget to set the ``MOZCONFIG`` environment variable for the
+``mach run`` command as well.
+
+Be aware that changing your ``mozconfig`` will require the configure
+process to be rerun and therefore the build will take considerably
+longer, so if you find yourself changing the same options regularly, it
+may be worth having a separate ``mozconfig`` for each. The main downside
+of this is that each objdir will take up a significant amount of space
+on disk.
+
+
+Parallel compilation
+~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+   The build system automatically makes an intelligent guess
+   for how many CPU cores to use when building. The option below is
+   typically not needed.
+
+Most modern systems have multiple cores or CPUs, and they can be
+optionally used concurrently to make the build faster. The ``-j`` flag
+controls how many parallel builds will run concurrently. You will see
+(diminishing) returns up to a value approximately 1.5× to 2.0× the
+number of cores on your system.
+
+.. code:: bash
+
+   mk_add_options MOZ_PARALLEL_BUILD=4
+
+If your machine is overheating, you might want to try a lower value.
+
+
+Choose a project
+~~~~~~~~~~~~~~~~
+
+The ``--enable-project=project`` flag is used to select a project to
+build. Firefox is the default.
+
+Choose one of the following options to add to your ``mozconfig`` file:
+
+Browser (Firefox)
+   .. code::
+
+      ac_add_options --enable-project=browser
+
+   .. note::
+
+      This is the default
+
+Mail (Thunderbird)
+   .. code::
+
+      ac_add_options --enable-project=comm/mail
+
+Mozilla Suite (SeaMonkey)
+   .. code::
+
+      ac_add_options --enable-project=suite
+
+Calendar (Lightning Extension, uses Thunderbird)
+   .. code::
+
+      ac_add_options --enable-project=comm/mail
+      ac_add_options --enable-calendar
+
+
+Selecting build options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The build options you choose depends on what project you are
+building and what you will be using the build for. If you want to use
+the build regularly, you will want a release build without extra
+debugging information; if you are a developer who wants to hack the
+source code, you probably want a non-optimized build with extra
+debugging macros.
+
+There are many options recognized by the configure script which are
+special-purpose options intended for embedders or other special
+situations, and should not be used to build the full suite/XUL
+projects. The full list of options can be obtained by running
+``./mach configure -- --help``.
+
+.. warning::
+
+   Do not use a configure option unless you know what it does.
+   The default values are usually the right ones. Each additional option
+   you add to your ``mozconfig`` file reduces the chance that your build
+   will compile and run correctly.
+
+The following build options are very common:
+
+sccache
+^^^^^^^
+
+`SCCache <https://github.com/mozilla/sccache>`__ allows speeding up subsequent
+C / C++ builds by caching compilation results. Unlike
+`ccache <https://ccache.dev>`__, it also allows caching Rust artifacts, and
+supports `distributed compilation
+<https://github.com/mozilla/sccache/blob/master/docs/DistributedQuickstart.md>`__.
+
+In order to enable ``sccache`` for Firefox builds, you can use
+``ac_add_options --with-ccache=sccache``.
+
+From version 0.7.4, sccache local builds are using the ``preprocessor cache mode``
+by default. With a hot cache, it decreases the build time by a factor of 2 to 3
+compared the previous method. This feature works like the `direct mode in ccache
+<https://ccache.dev/manual/3.7.9.html#_the_direct_mode>`__,
+using a similar way to handle caching and dependencies.
+
+   .. note::
+
+      When using sccache, because of the operation on the files and storage,
+      the initial build of Firefox will be slower.
+
+Optimization
+^^^^^^^^^^^^
+
+``ac_add_options --enable-optimize``
+   Enables the default compiler optimization options
+
+   .. note::
+
+      This is enabled by default
+
+``ac_add_options --enable-optimize=-O2``
+   Chooses particular compiler optimization options. In most cases, this
+   will not give the desired results, unless you know the Mozilla
+   codebase very well; note, however, that if you are building with the
+   Microsoft compilers, you probably **do** want this as ``-O1`` will
+   optimize for size, unlike GCC.
+``ac_add_options --enable-debug``
+   Enables assertions in C++ and JavaScript, plus other debug-only code.
+   This can significantly slow a build, but it is invaluable when
+   writing patches. **People developing patches (especially in C++)
+   should generally use this option.**
+``ac_add_options --disable-optimize``
+   Disables compiler optimization. This makes it much easier to step
+   through code in a debugger.
+``ac_add_options --enable-release``
+   Enables more conservative, release engineering-oriented options. This may
+   slow down builds. This also turns on full optimizations for Rust. Note this
+   is the default when building release/beta/esr.
+``ac_add_options --enable-debug-js-modules``
+   Enable only JavaScript assertions. This is useful when working
+   locally on JavaScript-powered components like the DevTools. This will
+   help catch any errors introduced into the JS code, with less of a
+   performance impact compared to the ``--enable-debug`` option.
+``export RUSTC_OPT_LEVEL=2``
+   Enable full optimizations for Rust code.
+
+You can make an optimized build with debugging symbols. See :ref:`Building
+with Debug Symbols <Building with Debug Symbols>`.
+
+Extensions
+^^^^^^^^^^
+
+``ac_add_options --enable-extensions=default|all|ext1,ext2,-skipext3``
+   There are many optional pieces of code that live in {{
+   Source("extensions/") }}. Many of these extensions are now considered
+   an integral part of the browsing experience. There is a default list
+   of extensions for the suite, and each app-specific ``mozconfig``
+   specifies a different default set. Some extensions are not compatible
+   with all apps, for example:
+
+   - ``cookie`` is not compatible with thunderbird
+   - ``typeaheadfind`` is not compatible with any toolkit app (Firefox,
+      Thunderbird)
+
+   Unless you know which extensions are compatible with which apps, do
+   not use the ``--enable-extensions`` option; the build system will
+   automatically select the proper default set of extensions.
+
+Tests
+^^^^^
+
+``ac_add_options --disable-tests``
+   By default, many auxiliary test programs are built, which can
+   help debug and patch the mozilla source. Disabling these tests can
+   speed build time and reduce disk space considerably. Developers
+   should generally not use this option.
+
+Localization
+^^^^^^^^^^^^
+
+``mk_add_options MOZ_CO_LOCALES=ISOcode``
+   TBD.
+``ac_add_options --enable-ui-locale=ISOcode``
+   TBD.
+``ac_add_options --with-l10n-base=/path/to/base/dir``
+   TBD.
+
+Other Options
+^^^^^^^^^^^^^
+
+``mk_add_options AUTOCLOBBER=1``
+   If a clobber would be required before a build, this will cause mach
+   to clobber and continue with the build instead of asking the user to
+   manually clobber and exiting.
+
+``ac_add_options --enable-warnings-as-errors``
+   This makes compiler warnings into errors which fail the build. This
+   can be useful since certain warnings coincide with reviewbot lints
+   which must be fixed before merging.
+
+.. _Example_.mozconfig_Files:
+
+Example ``mozconfig`` Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mozilla's official builds use mozconfig files from the appropriate
+directory within each repository.
+
+.. warning::
+
+   These ``mozconfig`` files are taken from production builds
+   and are provided as examples only. It is recommended to use the default
+   build options, and only change the properties from the list above as
+   needed. The production builds aren't really appropriate for local
+   builds."
+
+-  .. rubric:: Firefox, `Debugging Build (macOS
+      64bits) <http://hg.mozilla.org/mozilla-central/file/tip/browser/config/mozconfigs/macosx64/debug>`__
+      :name: Firefox.2C_Default_Release_Configuration
+
+Building multiple projects from the same source tree
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to build multiple projects from the same source tree,
+as long as you `use a different objdir <#Building_with_an_Objdir>`__ for
+each project.
+
+You need to create multiple ``mozconfig`` files.
+
+As an example, the following steps can be used to build Firefox and
+Thunderbird. You should first create three ``mozconfig`` files.
+
+``mozconfig-common``:
+
+.. code::
+
+   # add common options here, such as making an optimized release build
+   mk_add_options MOZ_PARALLEL_BUILD=4
+   ac_add_options --enable-optimize --disable-debug
+
+``mozconfig-firefox``:
+
+.. code::
+
+   # include the common mozconfig
+   . ./mozconfig-common
+
+   # Build Firefox
+   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-firefox
+   ac_add_options --enable-project=browser
+
+``mozconfig-thunderbird``:
+
+.. code::
+
+   # include the common mozconfig
+   . ./mozconfig-common
+
+   # Build Thunderbird
+   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-thunderbird
+   ac_add_options --enable-project=comm/mail
+
+To build Firefox, run the following commands:
+
+.. code::
+
+   export MOZCONFIG=/path/to/mozilla/mozconfig-firefox
+   ./mach build
+
+To build Thunderbird, run the following commands:
+
+.. code::
+
+   export MOZCONFIG=/path/to/mozilla/mozconfig-thunderbird
+   ./mach build
+
+Using mozconfigwrapper
+^^^^^^^^^^^^^^^^^^^^^^
+
+Mozconfigwrapper is similar to using multiple mozconfig files except
+that it abstracts and hides them so you don't have to worry about where
+they live or which ones you've created. It also saves you from having to
+export the MOZCONFIG variable each time. For information on installing
+and configuring mozconfigwrapper, see
+https://github.com/ahal/mozconfigwrapper.
diff --git a/docs/setup/contributing_code.rst b/docs/setup/contributing_code.rst
new file mode 100644
index 0000000000..2d3520e363
--- /dev/null
+++ b/docs/setup/contributing_code.rst
@@ -0,0 +1,176 @@
+How To Contribute Code To Firefox
+=================================
+
+The whole process can be a bit long, and it might take time to get things right.
+If at any point you are stuck, please don't hesitate to ask at `https://chat.mozilla.org <https://chat.mozilla.org>`_
+in the `#introduction <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_ channel.
+
+We make changes to Firefox by writing patches, testing them and pushing them into "the tree", the
+term we use for all the code in Mozilla-Central. Let's get started.
+
+Please see the :ref:`Firefox Contributors Quick Reference <Firefox Contributors' Quick Reference>` for simple check list.
+
+Finding something to work on
+----------------------------
+
+| Bugs listed as 'Assigned' are not usually a good place to start,
+  unless you're sure you have something worthy to contribute. Someone
+  else is already working on it!
+| Even with no assignee, it is polite to check if someone has recently
+  commented that they're looking at fixing the issue.
+| Once you have found something to work on, go ahead and comment! Let
+  the bug submitter, reviewer, and component owner know that you'd like
+  to work on the bug. You might receive some extra information, perhaps
+  also made the assignee.
+
+Find a bug we've identified as a good fit for new contributors.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With more than a million bugs filed in Bugzilla, it can be hard to know
+where to start, so we've created these bug categories to make getting
+involved a little easier:
+
+-  `Codetribute <https://codetribute.mozilla.org/>`_ - our site for
+   finding bugs that are mentored, some are good first bugs, some are
+   slightly harder. Your mentor will help guide you with the bug fix and
+   through the submission and landing process.
+-  `Good First Bugs <https://mzl.la/2yBg3zB>`_
+   - are the best way to take your first steps into the Mozilla
+   ecosystem. They're all about small changes, sometimes as little as a
+   few lines, but they're a great way to learn about setting up your
+   development environment, navigating Bugzilla, and making
+   contributions to the Mozilla codebase.
+-  `Student Projects <https://bugzil.la/kw:student-project>`_ - are
+   larger projects, such as might be suitable for a university student
+   for credit. Of course, if you are not a student, feel free to fix one
+   of these bugs. We maintain two lists: one for projects `based on the
+   existing codebase <https://bugzil.la/kw:student-project>`_.
+
+Fix that one bug
+~~~~~~~~~~~~~~~~
+
+If there's one particular bug you'd like to fix about Firefox, Thunderbird, or
+your other favorite Mozilla application, this can be a great place to
+start. There are a number of ways to do this:
+
+-  `Search bugzilla <https://bugzilla.mozilla.org/query.cgi>`_ for
+   relevant keywords. See pages on
+   `Bugzilla and Searching Bugzilla <https://bmo.readthedocs.io/en/latest/using/finding.html>`_ for further
+   help
+-  Learn the `bugzilla
+   component <https://bugzilla.mozilla.org/describecomponents.cgi>`_,
+   with which your pet bug is implemented, using the components list.
+   Browse this component on bugzilla for related bugs
+
+Fixing your bug
+---------------
+
+We leave this in your hands. Here are some further resources to help:
+
+-  Check out
+   :ref:`Our Developer Guide and its parent document <Working on Firefox>`
+-  Our :ref:`reviewer checklist <Reviewer Checklist>` is very
+   useful, if you have a patch near completion, and seek a favorable
+   review
+-  Utilize our build tool :ref:`mach`, its linting,
+   static analysis, and other code checking features
+
+Getting your code reviewed
+--------------------------
+
+Once you fix the bug, you can advance to having your code reviewed.
+
+Mozilla uses
+`Phabricator <https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html>`_
+for code review.
+
+Who is the right person to ask for a review?
+
+-  If you have a mentored bug: ask your mentor. They will help, or can
+   easily find out. It might be them!
+-  Run ``{hg, git} blame`` on the file and look for the people who have touched
+   the functions you're working on. They too are good candidates.
+   Running ``{hg, git} log`` and looking for regular reviewers might be a
+   solution too.
+-  The bug itself may contain a clear indication of the best person to
+   ask for a review
+-  Are there related bugs on similar topics? The reviewer in those bugs
+   might be another good choice
+-  We have a :ref:`list of modules <Governance>`, which lists peers and
+   owners for the module. Some of these will be good reviewers. In a
+   worst case scenario, set the module owner as the reviewer, asking
+   them in the comments to pick someone more suitable
+
+Please select only one reviewer.
+
+Following up and responding
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you've asked for a review, a reviewer will often respond within a
+day or two, reviewing the patch, or saying when they will be able to
+review it, perhaps due to a backlog. If you don't hear back within this
+time, naturally reach out to them: add a comment to the bug saying
+'review ping?', check the "Need more information from" box, and add the
+reviewer's name. If they don't respond within a day or two, you can ask
+for help on Matrix in the
+`#introduction:mozilla.org <https://riot.im/app/#/room/#introduction:mozilla.org>`_
+or
+`#developers:mozilla.org <https://chat.mozilla.org/#/room/#developers:mozilla.org>`_
+channels.
+
+Don't hesitate to contact your mentor as well if this isn't moving.
+
+For most new contributors, and even for long-time Mozillians, the first
+review of your patch will be "Requested Changes" (or an "r-" in
+Bugzilla). This does not mean you've done bad work. There is more work
+to do before the code can be merged into the tree. Your patch may need
+some changes - perhaps minor, perhaps major - and your reviewer will
+give you some guidance on what needs to be done next.
+
+This is an important process, so don't be discouraged! With our
+long-lived codebase, and hundreds of millions of users, the care and
+attention helping contributors bring good patches is the cornerstone of
+the Mozilla project. Make any changes your reviewer seeks; if you're
+unsure how, be sure to ask! Push your new patch up to Phabricator again and
+ask for a further review from the same reviewer. If they accept your
+changes, this means your patch can be landed into the tree!
+
+Getting code into Firefox
+-------------------------
+
+Once your patch has been accepted, it is ready to go. Before it can be
+merged into the tree, your patch will need to complete a successful run
+through our :ref:`try server <Pushing to Try>`,
+making sure there are no unexpected regressions. If you don't have try
+server access already, your mentor, or the person who reviewed your
+patch, will be able to help.
+
+Ask the reviewer to land the patch for you.
+For more details, see :ref:`push_a_change`
+
+
+Do it all again!
+----------------
+
+Thank you. You've fixed your very first bug, and the Open Web is
+stronger for it. But don't stop now.
+
+Go back to step 3, as there is plenty more to do. Your mentor might
+suggest a new bug for you to work on, or `find one that interests
+you <https://moztw.org/~petercpg/asknot/>`_. Now that you've got your
+first bug fixed you should request level 1 access to the repository to
+push to the try server and get automated feedback about your changes on
+multiple platforms. After fixing a nontrivial number of bugs you should
+request level 3 access so you can land your own code after it has been
+reviewed.
+
+More information
+----------------
+
+We're in the process of improving information on this page for newcomers
+to the project. We'll be integrating some information from these pages
+soon, but until then you may find them interesting in their current
+form:
+
+-  `A beginner's guide to SpiderMonkey, Mozilla's Javascript
+   engine <https://wiki.mozilla.org/JavaScript:New_to_SpiderMonkey>`_
diff --git a/docs/setup/index.rst b/docs/setup/index.rst
new file mode 100644
index 0000000000..eb0c68aa4e
--- /dev/null
+++ b/docs/setup/index.rst
@@ -0,0 +1,25 @@
+Getting Set Up To Work On The Firefox Codebase
+==============================================
+
+This page will help you get set up to build Firefox on your own machine.
+
+Don't hesitate to look at the :ref:`Firefox Contributors Quick Reference <Firefox Contributors' Quick Reference>` to read a quick tutorial.
+
+.. toctree::
+   :caption: Thank you for contributing to Firefox
+
+   /contributing/contributing_to_mozilla
+
+.. toctree::
+   :caption: Setting Up Your Machine
+   :maxdepth: 1
+
+   windows_build
+   macos_build
+   linux_build
+   linux_32bit_build_on_64bit_OS
+
+.. toctree::
+   :caption: Getting Ready To Contribute
+
+   contributing_code
diff --git a/docs/setup/linux_32bit_build_on_64bit_OS.rst b/docs/setup/linux_32bit_build_on_64bit_OS.rst
new file mode 100644
index 0000000000..f2022031b3
--- /dev/null
+++ b/docs/setup/linux_32bit_build_on_64bit_OS.rst
@@ -0,0 +1,37 @@
+Building Firefox 32-bit On Linux 64-bit
+=======================================
+
+.. note::
+
+   Unless you really want to target older hardware, you probably
+   want to :ref:`Build Firefox 64-bit <Building Firefox On Linux>`
+   since it is better-supported.
+
+Before following these 32-bit-Firefox-specific instructions, follow
+the :ref:`Building Firefox On Linux` instructions to ensure that
+your machine can do a normal build.
+
+Instructions for Ubuntu 19.10
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These steps were verified to work as of June 2020.
+
+#. Run ``rustup target install i686-unknown-linux-gnu`` to install the
+   32-bit Rust target.
+#. Install 32-bit dependencies with the following command (this shouldn't try to
+   remove packages. If this is the case, those instructions won't work as-is):
+
+  .. code::
+
+     sudo apt install gcc-multilib g++-multilib \
+       libgtk2.0-dev:i386 libgtk-3-dev:i386 libpango1.0-dev:i386 libxt-dev:i386 \
+       libx11-xcb-dev:i386 libpulse-dev:i386 libdrm-dev:i386
+
+#. Then, create a ``mozconfig`` file in your Firefox code directory
+   (probably ``mozilla-unified``) that looks like the following example:
+
+   .. code::
+
+      ac_add_options --target=i686
+
+#. Run ``./mach build``.
diff --git a/docs/setup/linux_build.rst b/docs/setup/linux_build.rst
new file mode 100644
index 0000000000..2cd2c39d7d
--- /dev/null
+++ b/docs/setup/linux_build.rst
@@ -0,0 +1,168 @@
+Building Firefox On Linux
+=========================
+
+This document will help you get set up to build Firefox on your own
+computer. Getting set up can take a while - we need to download a
+lot of bytes! Even on a fast connection, this can take ten to fifteen
+minutes of work, spread out over an hour or two.
+
+Requirements
+------------
+
+-  **Memory:** 4GB RAM minimum, 8GB+ recommended.
+-  **Disk Space:** At least 30GB of free disk space.
+-  **Operating System:** A 64-bit installation of Linux. It is strongly advised
+   that you use a supported distribution; see :ref:`build_hosts`.  We also
+   recommend that your system is fully up-to-date.
+
+.. note::
+
+    Some Linux distros are better-supported than others. Mozilla maintains
+    bootstrapping code for Ubuntu, but others are managed by the
+    community (thanks!). The more esoteric the distro you're using,
+    the more likely that you'll need to solve unexpected problems.
+
+
+1. System preparation
+---------------------
+
+1.1 Install Python
+~~~~~~~~~~~~~~~~~~
+
+To build Firefox, it's necessary to have a Python of version 3.6 or later
+installed. Python 2 is no longer required to build Firefox, although it is still
+required for running some kinds of tests. Additionally, you will probably need
+Python development files as well to install some pip packages.
+
+You should be able to install Python using your system package manager:
+
+-  For Debian-based Linux (such as Ubuntu): ``sudo apt-get install curl python3 python3-pip``
+-  For Fedora Linux: ``sudo dnf install python3 python3-pip``
+
+If you need a version of Python that your package manager doesn't have (e.g.:
+the provided Python 3 is too old, or you want Python 2 but it's not available),
+then you can use `pyenv <https://github.com/pyenv/pyenv>`_, assuming that your
+system is supported.
+
+1.2 Install Mercurial
+~~~~~~~~~~~~~~~~~~~~~
+
+Mozilla's source code is hosted in Mercurial repositories. You will
+need Mercurial to download and update the code.
+
+Note that if you'd prefer to use the version of Mercurial that is
+packaged by your distro, you can skip this section. However, keep in
+mind that distro-packaged Mercurial may be outdated, and therefore
+slower and less supported.
+
+.. code-block:: shell
+
+    python3 -m pip install --user mercurial
+
+You can test that Mercurial is installed by running:
+
+.. code-block:: shell
+
+    hg version
+
+.. note::
+
+    If your shell is showing ``command not found: hg``, then Python's packages aren't
+    being found in the ``$PATH``. You can resolve this by doing the following and
+    restarting your shell:
+
+    .. code-block:: shell
+
+        # If you're using zsh
+        echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.zshenv
+
+        # If you're using bash
+        echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.bashrc
+
+        # If you're using a different shell, follow its documentation to see
+        # how to configure your PATH. Ensure that `$(python3 -m site --user-base)/bin`
+        # is prepended.
+
+2. Bootstrap a copy of the Firefox source code
+----------------------------------------------
+
+Now that your system is ready, we can download the source code and have Firefox
+automatically download the other dependencies it needs. The below command
+will download a lot of data (years of Firefox history!) then guide you through
+the interactive setup process.
+
+.. code-block:: shell
+
+    curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O
+    python3 bootstrap.py
+
+.. note::
+
+    To use ``git``, you can grab the source code in "git" form by running the
+    bootstrap script with the ``vcs`` parameter:
+
+    .. code-block:: shell
+
+        python3 bootstrap.py --vcs=git
+
+    This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
+
+Choosing a build type
+~~~~~~~~~~~~~~~~~~~~~
+
+If you aren't modifying the Firefox backend, then select one of the
+:ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
+building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`.
+
+3. Build
+--------
+
+Now that your system is bootstrapped, you should be able to build!
+
+.. code-block:: shell
+
+    cd mozilla-unified
+    hg up -C central
+    ./mach build
+
+🎉 Congratulations! You've built your own home-grown Firefox!
+You should see the following message in your terminal after a successful build:
+
+.. code-block:: console
+
+    Your build was successful!
+    To take your build for a test drive, run: |mach run|
+    For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
+
+You can now use the ``./mach run`` command to run your locally built Firefox!
+
+If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
+
+Now the fun starts
+------------------
+
+Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
+say hello in the `Introduction channel
+<https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
+start working on <https://codetribute.mozilla.org/>`_.
+See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
+send patches to Mozilla, update your source code locally, and more.
+
+Troubleshooting
+---------------
+
+Build errors
+~~~~~~~~~~~~
+
+If you encounter a build error when trying to setup your development environment, please follow these steps:
+   1. Copy the entire build error to your clipboard
+   2. Paste this error to `paste.mozilla.org <https://paste.mozilla.org>`_ in the text area and change the "Expire in one hour" option to "Expire in one week". Note: it won't take a week to get help but it's better to have the snippet be around for a bit longer than expected.
+   3. Go to the `introduction channel <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ and ask for help with your build error. Make sure to post the link to the paste.mozilla.org snippet you created!
+
+Using a non-native file system (NTFS, network drive, etc)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In our experience building Firefox in these hybrid or otherwise complex environments
+always ends in unexpected, often silent and always hard-to-diagnose failure.
+Building Firefox in that environment is far more likely to reveal the flaws and
+shortcomings of those systems than it is to produce a running web browser.
diff --git a/docs/setup/macos_build.rst b/docs/setup/macos_build.rst
new file mode 100644
index 0000000000..df3719e648
--- /dev/null
+++ b/docs/setup/macos_build.rst
@@ -0,0 +1,151 @@
+Building Firefox On macOS
+=========================
+
+This document will help you get set up to build Firefox on your own
+computer. Getting set up can take a while - we need to download a
+lot of bytes! Even on a fast connection, this can take ten to fifteen
+minutes of work, spread out over an hour or two.
+
+Requirements
+------------
+
+-  **Memory:** 4GB RAM minimum, 8GB+ recommended.
+-  **Disk Space:** At least 30GB of free disk space.
+-  **Operating System:** macOS - most recent or prior release. It is advisable
+   to upgrade to the latest “point” release.  See :ref:`build_hosts` for more
+   information.
+
+
+1. System preparation
+---------------------
+
+1.1. Install Brew
+~~~~~~~~~~~~~~~~~
+
+Mozilla's source tree requires a number of third-party tools.
+You will need to install `Homebrew <https://brew.sh/>`__ so that we
+can automatically fetch the tools we need.
+
+1.2. Install Xcode
+~~~~~~~~~~~~~~~~~~
+
+Install Xcode from the App Store.
+Once done, finalize the installation in your terminal:
+
+.. code-block:: shell
+
+    sudo xcode-select --switch /Applications/Xcode.app
+    sudo xcodebuild -license
+
+1.3 Install Mercurial
+~~~~~~~~~~~~~~~~~~~~~
+
+Mozilla's source code is hosted in Mercurial repositories. You will
+need Mercurial to download and update the code. Additionally, we'll
+put user-wide python package installations on the ``$PATH``, so that
+both ``hg`` and ``moz-phab`` will be easily accessible:
+
+.. code-block:: shell
+
+    echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.zshenv
+    python3 -m pip install --user mercurial
+
+Now, restart your shell so that the ``PATH`` change took effect.
+You can test that Mercurial is installed by running:
+
+.. code-block:: shell
+
+    hg version
+
+.. note::
+
+    If you're using a shell other than ``zsh``, you'll need to manually add Python's
+    ``bin`` directory to your ``PATH``, as your shell probably won't pick up our
+    changes in ``~/.zshenv``.
+
+2. Bootstrap a copy of the Firefox source code
+----------------------------------------------
+
+Now that your system is ready, we can download the source code and have Firefox
+automatically download the other dependencies it needs. The below command
+will download a lot of data (years of Firefox history!) then guide you through
+the interactive setup process.
+
+.. code-block:: shell
+
+    curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O
+    python3 bootstrap.py
+
+.. note::
+
+    To use ``git``, you can grab the source code in "git" form by running the
+    bootstrap script with the ``vcs`` parameter:
+
+    .. code-block:: shell
+
+         python3 bootstrap.py --vcs=git
+
+    This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
+
+Choosing a build type
+~~~~~~~~~~~~~~~~~~~~~
+
+If you aren't modifying the Firefox backend, then select one of the
+:ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
+building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`.
+
+3. Build
+--------
+
+Now that your system is bootstrapped, you should be able to build!
+
+.. code-block:: shell
+
+    cd mozilla-unified
+    hg up -C central
+    ./mach build
+
+🎉 Congratulations! You've built your own home-grown Firefox!
+You should see the following message in your terminal after a successful build:
+
+.. code-block:: console
+
+    Your build was successful!
+    To take your build for a test drive, run: |mach run|
+    For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
+
+You can now use the ``./mach run`` command to run your locally built Firefox!
+
+If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
+
+Running outside the development environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To test your changes on another macOS system (or to keep that particular Firefox around after new builds), you can't just use the generated application bundle (``obj-*/dist/Nightly[Debug].app``), since it contains symbolic links to other built libraries. Instead, build a distributable disk image with:
+
+.. code-block:: shell
+
+   ./mach package
+
+Copy the resulting ``.dmg`` file from ``obj-*/dist/`` to the target system, then double-click it as usual to find an ``.app`` bundle containing all dependencies.
+
+Now the fun starts
+------------------
+
+Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
+say hello in the `Introduction channel
+<https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
+start working on <https://codetribute.mozilla.org/>`_.
+See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
+send patches to Mozilla, update your source code locally, and more.
+
+Troubleshooting
+---------------
+
+Build errors
+~~~~~~~~~~~~
+
+If you encounter a build error when trying to setup your development environment, please follow these steps:
+   1. Copy the entire build error to your clipboard
+   2. Paste this error to `paste.mozilla.org <https://paste.mozilla.org>`_ in the text area and change the "Expire in one hour" option to "Expire in one week". Note: it won't take a week to get help but it's better to have the snippet be around for a bit longer than expected.
+   3. Go to the `introduction channel <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ and ask for help with your build error. Make sure to post the link to the paste.mozilla.org snippet you created!
diff --git a/docs/setup/windows_build.rst b/docs/setup/windows_build.rst
new file mode 100644
index 0000000000..99f5fdf5d9
--- /dev/null
+++ b/docs/setup/windows_build.rst
@@ -0,0 +1,209 @@
+Building Firefox On Windows
+======================================
+
+This document will help you get set up to build Firefox on your own
+computer. Getting set up can take a while - we need to download a
+lot of bytes! Even on a fast connection, this can take ten to fifteen
+minutes of work, spread out over an hour or two.
+
+If you'd prefer to build Firefox for Windows in a virtual machine,
+you may be interested in the `Windows images provided by Microsoft
+<https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/>`_.
+
+Requirements
+------------
+
+-  **Memory:** 4GB RAM minimum, 8GB+ recommended.
+-  **Disk Space:** At least 40GB of free disk space.
+-  **Operating System:** Windows 10. It is advisable to have Windows Update be fully
+   up-to-date. See :ref:`build_hosts` for more information.
+
+Recommended (For Windows 11 Users)
+----------------------------------
+Setup a `Dev Drive
+<https://learn.microsoft.com/en-us/windows/dev-drive/#how-to-set-up-a-dev-drive>`_.
+
+.. note::
+
+    -  A Dev Drive has been shown to make Firefox builds and VCS operations 5-10% faster.
+    -  This guide assumes no Dev Drive, so all instructions of ``C:\mozilla-source`` should be to your Dev Drive letter instead (eg: ``D:\mozilla-source``), as your ``C:\`` drive can never be a Dev Drive.
+
+1. Install MozillaBuild
+-----------------------
+
+Install `MozillaBuild
+<https://ftp.mozilla.org/pub/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`_.
+
+Accept the default installation directory.
+Windows may prompt you to "reinstall with the correct settings", which you
+should click to accept.
+
+When working with Firefox tooling, you'll need to do so from within the MozillaBuild
+shell. You can start it by running ``C:\mozilla-build\start-shell.bat`` (you may want
+to make a shortcut to this file so it's easier to start).
+
+.. note::
+
+    The MozillaBuild shell is a lot more like a Linux shell than the Windows ``cmd``. You can
+    learn more about it `here <https://wiki.mozilla.org/MozillaBuild>`_.
+
+2. Bootstrap a copy of the Firefox source code
+----------------------------------------------
+
+Now that your system is ready, we can download the source code and have Firefox
+automatically download the other dependencies it needs. The below command
+will download a lot of data (years of Firefox history!) then guide you through
+the interactive setup process.
+
+.. code-block:: shell
+
+    # Using the C:\mozilla-build\start-shell.bat shell from step 1:
+    cd c:/
+    mkdir mozilla-source
+    cd mozilla-source
+    wget https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py
+    python3 bootstrap.py
+.. note::
+
+    When running ``bootstrap.py`` there will be a `UAC (User Account Control) prompt <https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/how-user-account-control-works>`_ for PowerShell after
+    selecting the destination directory for the source code clone. This is
+    necessary to add the Microsoft Defender Antivirus exclusions automatically. You
+    should select ``Yes`` on the UAC prompt, otherwise you will need
+    to :ref:`follow some manual steps below <Ensure antivirus exclusions>`.
+
+.. note::
+
+    To use ``git``, you can grab the source code in "git" form by running the
+    bootstrap script with the ``vcs`` parameter:
+
+    .. code-block:: shell
+
+        python3 bootstrap.py --vcs=git
+
+    This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood.
+
+Choosing a build type
+~~~~~~~~~~~~~~~~~~~~~
+
+If you aren't modifying the Firefox backend, then select one of the
+:ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are
+building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide <geckoview-contributor-guide>`.
+
+.. _Ensure antivirus exclusions:
+
+Ensure antivirus exclusions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Microsoft Defender Antivirus and some third-party antivirus products
+are known to significantly degrade build times and sometimes even cause failed
+builds (due to a "missing file"). This is usually because we have tests for
+well-known security bugs that have code samples that antivirus software identifies
+as a threat, automatically quarantining/corrupting the files.
+
+To avoid this, add the following folders to your third-party antivirus exclusion list:
+
+-  The ``C:\mozilla-build`` folder.
+-  The directory where the Firefox code is (probably ``C:\mozilla-source``).
+-  The ``%USERPROFILE%/.mozbuild`` directory (probably ``C:\Users\<user>\.mozbuild``).
+
+The ``bootstrap.py`` script attempts to add the above folders to the Microsoft
+Defender Antivirus exclusion list automatically. You should check that they were
+successfully added, but if they're missing you will need to `add the exclusions to
+Microsoft Defender Antivirus manually
+<https://support.microsoft.com/en-ca/help/4028485/windows-10-add-an-exclusion-to-windows-security>`_.
+
+.. note::
+
+    If you are using Mercurial and you're already missing files (you'll see them listed in ``hg status``), you can have them
+    brought back by reverting your source tree: ``hg update -C``.
+
+    If you are using Git and you're already missing files (you'll see them listed in ``git status``), you can have them brought back by discarding changes in your source tree: ``git restore .``.
+
+1. Build
+--------
+
+Now that your system is bootstrapped, you should be able to build!
+
+.. code-block:: shell
+
+    cd c:/mozilla-source/mozilla-unified
+    hg up -C central
+    ./mach build
+
+🎉 Congratulations! You've built your own home-grown Firefox!
+You should see the following message in your terminal after a successful build:
+
+.. code-block:: console
+
+    Your build was successful!
+    To take your build for a test drive, run: |mach run|
+    For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
+
+You can now use the ``./mach run`` command to run your locally built Firefox!
+
+If your build fails, please reference the steps in the `Troubleshooting section <#troubleshooting>`_.
+
+Now the fun starts
+------------------
+
+Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_,
+say hello in the `Introduction channel
+<https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to
+start working on <https://codetribute.mozilla.org/>`_.
+See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes,
+send patches to Mozilla, update your source code locally, and more.
+
+.. note::
+
+    If you'd like to interact with Mach from a different command line environment
+    than MozillaBuild, there's experimental support for it described
+    :ref:`over here <Using Mach on Windows Outside MozillaBuild>`.
+
+Troubleshooting
+---------------
+
+Build errors
+~~~~~~~~~~~~
+
+If you encounter a build error when trying to setup your development environment, please follow these steps:
+   1. Copy the entire build error to your clipboard
+   2. Paste this error on `paste.mozilla.org <https://paste.mozilla.org>`_ in the text area and change the "Expire in one hour" option to "Expire in one week". Note: it won't take a week to get help but it's better to have the snippet be around for a bit longer than expected.
+   3. Go to the `introduction channel <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ and ask for help with your build error. Make sure to post the link to the paste.mozilla.org snippet you created!
+
+MozillaBuild out-of-date
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The build system expects that you're using the most-recent MozillaBuild release.
+However, MozillaBuild doesn't auto-update. If you're running into local issues,
+they may be resolved by `upgrading your MozillaBuild <https://wiki.mozilla.org/MozillaBuild>`_.
+
+Spaces in folder names
+~~~~~~~~~~~~~~~~~~~~~~
+
+**Firefox will not build** if the path to MozillaBuild or the Firefox source
+contain **spaces** or other breaking characters such as pluses, quotation marks,
+or metacharacters.  The Visual Studio tools and SDKs are an exception - they may
+be installed in a directory which contains spaces. It is strongly recommended
+that you accept the default settings for all installation locations.
+
+Quotation marks in ``PATH``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Quotation marks (") aren't translated properly when passed to MozillaBuild
+sub-shells. Since they're not usually necessary, you should ensure they're
+not in your ``PATH`` environment variable.
+
+``PYTHON`` environment variable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If ``PYTHON`` is set, the build may fail with the error: "``The system
+cannot find the file specified``." Ensure that you aren't having
+a ``PYTHON`` environment variable set.
+
+Cygwin interference
+~~~~~~~~~~~~~~~~~~~
+
+If you happen to have Cygwin installed, its tools may erroneously be
+used when building Firefox. Ensure that MozillaBuild directories (in
+``C:\mozilla-build\``) are before Cygwin directories in the ``PATH``
+environment variable.