Adding upstream version 86.0.1.upstream/86.0.1upstream

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

9 files changed, 2099 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..316e04af31
--- /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 explcitly
+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..b870632ad4
--- /dev/null
+++ b/docs/setup/configuring_build_options.rst
@@ -0,0 +1,440 @@
+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 application 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 applications 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 application 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 applications (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::
+
+   **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_MAKE_FLAGS="-j4"
+
+If your machine is overheating, you might want to try a lower value,
+e.g. ``-j1``.
+
+
+Choose an application
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``--enable-application=application`` flag is used to select an
+application 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-application=browser
+
+   .. note::
+
+      **Note**: This is the default
+
+Mail (Thunderbird)
+   .. code::
+
+      ac_add_options --enable-application=comm/mail
+
+Mozilla Suite (SeaMonkey)
+   .. code::
+
+      ac_add_options --enable-application=suite
+
+Calendar (Lightning Extension, uses Thunderbird)
+   .. code::
+
+      ac_add_options --enable-application=comm/mail
+      ac_add_options --enable-calendar
+
+
+Selecting build options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The build options you choose depends on what application 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
+applications. The full list of options can be obtained by running
+``./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``.
+
+Optimization
+^^^^^^^^^^^^
+
+``ac_add_options --enable-optimize``
+   Enables the default compiler optimization options
+
+   .. note::
+
+      **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 applications 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-crashreporter``
+   This enables the machinery that allows Firefox to write out a
+   `minidump <https://docs.microsoft.com/en-us/windows/desktop/Debug/minidump-files>`__
+   files when crashing as well as the tools to process and submit crash
+   reports to Mozilla. After enabling the crash reporter in your local
+   build, you will need to run mach with the --enable-crash-reporter
+   (note the extra dash) to enable it at runtime, like so:
+   ``./mach run --enable-crash-reporter``
+``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 applications from the same source tree
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to build multiple applications from the same source tree,
+as long as you `use a different objdir <#Building_with_an_Objdir>`__ for
+each application.
+
+You can either create multiple ``mozconfig`` files, or alternatively,
+use the ``MOZ_BUILD_PROJECTS`` make option.
+
+Using ``MOZ_BUILD_PROJECTS`` in a single ``mozconfig``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use ``MOZ_BUILD_PROJECTS``, you must specify a ``MOZ_OBJDIR`` and a
+``MOZ_BUILD_PROJECTS`` make option, containing space separated names.
+Each name can be an arbitrary directory name. For each name, a
+subdirectory is created under the toplevel objdir. You then need to use
+the ``ac_add_app_options`` with the specified names to enable different
+applications in each object directory.
+
+For example:
+
+.. code::
+
+    ac_add_options --disable-optimize --enable-debug
+    mk_add_options MOZ_OBJDIR=/mozilla/src/obj-@CONFIG_GUESS@
+    mk_add_options MOZ_BUILD_PROJECTS="browser mail"
+    ac_add_app_options browser --enable-application=browser
+    ac_add_app_options mail --enable-application=comm/mail
+
+If you want to build only one project using this ``mozconfig``, use the
+following command line:
+
+.. code::
+
+   MOZ_CURRENT_PROJECT=browser ./mach build
+
+This will build only the browser.
+
+Using multiple mozconfig files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Alternatively, you may want to create separate ``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_MAKE_FLAGS="-j4"
+   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-application=browser
+
+``mozconfig-thunderbird``:
+
+.. code::
+
+   # include the common mozconfig
+   . ./mozconfig-common
+
+   # Build Thunderbird
+   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-thunderbird
+   ac_add_options --enable-application=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..91a1264e0d
--- /dev/null
+++ b/docs/setup/contributing_code.rst
@@ -0,0 +1,199 @@
+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.
+-  Visit `firefox-dev.tools <http://firefox-dev.tools>`_ - we list
+   Firefox Developer Tools bugs for new contributors.
+-  `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 <https://developer.mozilla.org/docs/Mozilla/Bugzilla>`_ and `Searching
+   Bugzilla <https://developer.mozilla.org/docs/Mozilla/QA/Searching_Bugzilla>`_ 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
+   `https://developer.mozilla.org/docs/Developer_Guide <https://developer.mozilla.org/docs/Developer_Guide>`_
+   and its parent document,
+   https://developer.mozilla.org/docs/Mozilla
+-  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 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 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 an out of date `list of
+   modules <https://wiki.mozilla.org/Modules>`_, 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, or contact `Mike
+Hoye <mailto:mhoye@mozilla.com?subject=Code%20Review%20Request%20&body=URL%3A%20%20%5Bplease%20paste%20a%20link%20to%20your%20patch%20here.%5D>`_
+directly.
+
+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 `try
+server <https://wiki.mozilla.org/ReleaseEngineering/TryServer>`_,
+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.
+
+Once you have a **green** try server run, mark that your patch is ready
+to commit by
+
+#. opening the Phabricator page for your patch
+#. clicking the 'Edit Revision' link in the sidebar on the right
+#. then into the 'Tags' field and
+#. typing 'Check-In Needed' to get the tag added.
+
+A friendly Mozillian, with commit access, will be along shortly to push
+your patch to the repository, and update the bug as required. If your
+patch passes all Mozilla's automated testing, it will soon be merged
+into the main branch, and become a part of the Nightly build.
+
+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 <http://www.whatcanidoformozilla.org/>`_. 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 guide to learning the Firefox 
+   codebase <http://www.joshmatthews.net/blog/2010/03/getting-involve-with-mozilla/>`_
+-  `A beginner's guide to SpiderMonkey, Mozilla's Javascript
+   engine <https://wiki.mozilla.org/JavaScript:New_to_SpiderMonkey>`_
+-  `Mozilla platform development
+   cheatsheet <https://web.archive.org/web/20160813112326/http://www.codefirefox.com:80/cheatsheet>`_
+   (archive.org)
diff --git a/docs/setup/getting_set_up.rst b/docs/setup/getting_set_up.rst
new file mode 100644
index 0000000000..63482148aa
--- /dev/null
+++ b/docs/setup/getting_set_up.rst
@@ -0,0 +1,65 @@
+Welcome to the Firefox codebase!
+--------------------------------
+
+This page is here to help you get from "I want to build Firefox"
+to "I'm building my own Firefox" to "I can contribute to Firefox". 
+So if you'd like to help Mozilla build the best web browser in the
+world, you're in the right place.
+
+.. rubric:: Need help?
+   :name: Need_help
+
+The Mozilla community prides itself on being an open, accessible, and
+friendly community for new participants. If you have any difficulties
+getting involved or finding answers to your questions, please `come and
+ask your questions in our
+chatroom <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_,
+where we can help you get started.
+
+We know even before you start contributing that getting set up to work
+on Firefox and finding a bug that's a good fit for your skills can be a
+challenge, and we're always looking for ways to improve this process: making
+Mozilla more open, accessible, and easier to participate with. If you're
+having any trouble following this documentation, or hit a barrier you
+can't get around, please join us in the the Introduction room on Matrix
+or contact Mike Hoye directly at mhoye@mozilla.com. 
+
+What skills do I need?
+----------------------
+
+Mozilla is a large project and we are thrilled to have contributors with
+very diverse skills:
+
+-  If you know **C++,** **Rust,** **JavaScript,** **HTML** or **CSS**,
+   you can contribute to the core layers of Firefox and many other Mozilla
+   projects. 
+-  If you know **Rust**, you can also contribute to the Rust programming
+   language itself, and `Servo <https://servo.org/>`_, the web browser engine
+   designed for parallelism and safety.
+-  If you know **Java**, you can contribute to Firefox on Android,
+   `Firefox Focus for
+   Android <https://github.com/mozilla-mobile/focus-android>`_ .
+-  If you know **Kotlin**, you can contribute to `Firefox
+   Preview <https://github.com/mozilla-mobile/fenix>`_ (code name:
+   "Fenix").
+-  If you know **Swift**, you can contribute to `Firefox for
+   iOS <https://github.com/mozilla-mobile/firefox-ios>`_ and `Firefox
+   Focus for iOS <https://github.com/mozilla-mobile/focus-ios>`_
+-  If you know **Python**, you can contribute to our web services,
+   including Firefox Sync and Firefox Accounts
+-  If you know **Make**, **shell**, **Perl**, or **Python**, you can
+   contribute to our build systems, release engineering, and automation
+-  If you know **C**, you can contribute to NSS, Opus, and Daala
+-  There are even many ways to contribute to the Mozilla mission without
+   programming. If getting involved in design, support, translation,
+   testing, or other types of contributions sparks your interest please
+   see the `Volunteer Opportunities
+   wiki <https://contribute.mozilla.org>`_ or the `Mozilla
+   community <https://mozilla.community/>`_ site.
+
+Perhaps you do not know programming yet, but you want to start learning?
+There are `plenty of
+resources <https://developer.mozilla.org/learn>`_ available on
+the MDN Web Docs!
+
+Read on for information about how to set up your machine to build Firefox.
diff --git a/docs/setup/index.rst b/docs/setup/index.rst
new file mode 100644
index 0000000000..332ac8d001
--- /dev/null
+++ b/docs/setup/index.rst
@@ -0,0 +1,21 @@
+Getting Set Up To Work On The Firefox Codebase
+==============================================
+
+This page will help you get set up to build Firefox on your own machine.
+
+.. toctree::
+   :caption: Thank you for contributing to Firefox 
+
+   getting_set_up
+
+.. toctree::
+   :caption: Setting Up Your Machine
+
+   windows_build
+   macos_build
+   linux_build
+
+.. 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..fb6682672e
--- /dev/null
+++ b/docs/setup/linux_32bit_build_on_64bit_OS.rst
@@ -0,0 +1,78 @@
+Building Firefox 32-bit On Linux 64-bit
+=======================================
+
+Instructions for Fedora 20 and 19
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First ensure that your compiler toolchain and Gecko build dependencies
+are installed.
+
+.. code::
+
+   sudo yum install \
+     ccache cmake gcc gcc-c++ glibc-devel.i686 \
+     libstdc++-devel libstdc++-devel.i686 \
+     gtk2-devel.i686 gtk+-devel.i686 gtk+extra-devel.i686 \
+     glib-devel.i686 glib2-devel.i686 \
+     dbus-devel.i686 dbus-glib-devel.i686 \
+     alsa-lib-devel.i686 yasm-devel.i686 \
+     libxml2-devel.i686 zlib-devel.i686 \
+     freetype-devel.i686 \
+     atk-devel.i686 pango-devel.i686 fontconfig-devel.i686 \
+     cairo-devel.i686 gdk-pixbuf2-devel.i686 \
+     libX11-devel.i686 libXt-devel.i686 libXext-devel.i686 \
+     libXrender-devel.i686 libXau-devel.i686 libxcb-devel.i686 \
+     pulseaudio-libs-devel.i686 harfbuzz-devel.i686 \
+     mesa-libGL-devel.i686 libXxf86vm-devel.i686 \
+     libXfixes-devel.i686 libdrm-devel-2.4.49-2.fc19.i686 \
+     mesa-libEGL-devel libXdamage-devel.i686 libXcomposite-devel.i686
+
+Then you need to use a .mozconfig that looks like the following example.
+
+.. code::
+
+   # Flags set for targeting x86.
+   export CROSS_COMPILE=1
+   export PKG_CONFIG_PATH=/usr/lib/pkgconfig
+
+   CC="ccache gcc -m32"
+   CXX="ccache g++ -m32"
+   AR=ar
+   ac_add_options --target=i686-pc-linux
+
+   # Normal build flags.  These make a debug browser build.
+   ac_add_options --enable-application=browser
+   mk_add_options MOZ_MAKE_FLAGS="-s -j6"
+   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../ff-dbg
+
+   ac_add_options --enable-debug
+   ac_add_options --disable-optimize
+
+Instructions for Ubuntu 19.10
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These steps were verified to work as of June 2020
+
+#. Install mercurial or git and :ref:`fetch a copy <Mercurial Bundles>` of ``mozilla-central``.
+#. Run ``./mach bootstrap`` to install some dependencies. Note that this
+   will install some amd64 packages that are not needed to build 32-bit
+   Firefox.
+#. 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 libdbus-glib-1-dev:i386 \
+       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
+
+5. Create a file called ``mozconfig`` in the top-level directory of you
+   ``mozilla-central`` checkout, containing at least the following:
+
+  .. code::
+
+     ac_add_options --target=i686
+
+6. Run ``./mach build``.
diff --git a/docs/setup/linux_build.rst b/docs/setup/linux_build.rst
new file mode 100644
index 0000000000..321db0a96a
--- /dev/null
+++ b/docs/setup/linux_build.rst
@@ -0,0 +1,282 @@
+Building Firefox On Linux
+=========================
+
+They aren’t complicated, but there are a few prerequisites to building Firefox on Linux. You need:
+
+#. A 64-bit installation of Linux. You can check by opening a terminal window; if ``uname -m`` returns ``x86_64`` you can proceed.
+#. Next, you’ll need Python 3.6 or later installed. You can check with ``python3 --version`` to see if you have it already. If not, see `Installing Python <#installingpython>`_. You'll also need to install Mercurial and can do so with ``pip3 install Mercurial``.
+#. Finally, a reasonably fast internet connection and 30GB of free disk space.
+
+Getting Started
+---------------
+
+Getting set up on Linux is fast and easy.
+
+If you don’t have one yet, create a "``src``" directory for
+yourself under your home directory:
+
+.. code-block:: shell
+
+   mkdir src && cd src
+
+Next `download the bootstrap.py
+script <https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py>`_
+and save it in the ``src/`` directory created above.
+
+.. warning::
+
+   Building Firefox in Linux on top of a non-native file system -
+   for example, on a mounted NTFS partition - is explicitly not
+   supported. While a build environment like this may succeed it
+   may also fail while claiming to have succeeded, which can be
+   quite difficult to diagnose and fix.
+
+And finally, in your terminal from above start the bootstrapper
+like this:
+
+.. code-block:: shell
+
+   python3 bootstrap.py
+
+... and follow the prompts. This will use mercurial to checkout
+the source code. If you prefer to work with ``git``, use this command
+instead (make sure you have ``git`` installed):
+
+.. code-block:: shell
+
+   python3 bootstrap.py --vcs=git
+
+Let’s Build Firefox
+-------------------
+
+You’re ready; now we can tie it all together. In your terminal:
+
+.. code-block:: shell
+
+   cd mozilla-unified  # ... or the name of the repo you chose in the above step
+
+If you are not working on the C/C++ files you can also opt for
+:ref:`Artifact Builds <Understanding Artifact Builds>`
+which are much faster. To enable artifact build set up a
+:ref:`mozconfig <Configuring Build Options>`
+file with the following options:
+
+.. code-block:: shell
+
+   # Automatically download and use compiled C++ components:
+   # This option will disable C/C++ compilation
+   ac_add_options --enable-artifact-builds
+
+   # Write build artifacts to (not mandatory):
+   mk_add_options MOZ_OBJDIR=./objdir-frontend
+
+If you plan to walk through code with a debugger, set up a
+:ref:`.mozconfig <Configuring Build Options>`
+file with the following options:
+
+.. code-block:: shell
+
+   ac_add_options --disable-optimize
+   ac_add_options --enable-debug
+
+
+Older clang versions (especially clang 6) `from LTS linux
+distributions sometimes miscompile
+Firefox <https://bugzilla.mozilla.org/show_bug.cgi?id=1594686>`_,
+resulting in startup crashes when starting the resulting build.
+If this happens, you can force the use of the ``clang`` version
+that ``./mach bootstrap`` downloaded by adding the following to
+your ``.mozconfig``:
+
+.. code-block:: shell
+
+   export CC=path/to/home/.mozbuild/clang/bin/clang
+   export CXX=path/to/home/.mozbuild/clang/bin/clang++
+
+And finally, run the build command:
+
+.. code-block:: shell
+
+   ./mach build
+
+If you encounter any error related to LLVM/Clang on Ubuntu or
+Debian, download the latest version of LLVM and Clang and then
+re-run ``./mach build``.
+
+And you’re on your way, building your own copy of Firefox from
+source. Don’t be discouraged if this takes a while; this takes
+some time on even the fastest modern machines, and as much as two
+hours or more on older hardware. When the
+``--enable-artifact-builds`` option is used, builds usually finish
+within a few minutes.
+
+Now the fun starts
+------------------
+
+You have the code, you’ve compiled Firefox. Fire it up with
+``./mach run`` and you’re ready to start hacking. The next steps
+are up to you: join us on `Matrix <https://chat.mozilla.org/>`_
+in the `Introduction <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_
+channel, and find `a bug to start working on. <https://codetribute.mozilla.org/>`_
+
+
+General considerations
+----------------------
+
+#. 4GB RAM with an additional 4GB of available swap space is the bare minimum, and more RAM is always better - having 8GB or more will dramatically improve build time.
+#. A 64-bit x86 CPU and a 64-bit OS. As of early 2015 it is no longer possible to do a full build of Firefox from source on most 32-bit systems; a 64-bit OS is required. ":ref:`Artifact Builds <Understanding Artifact Builds>`" may be possible, but are not a supported configuration. On Linux you can determine this by typing "``uname -a``" in a terminal. It is possible to build a 32-bit Firefox on a 64-bit system, see :ref:`Building Firefox 32-bit on Linux 64-bit <Building Firefox 32-bit On Linux 64-bit>`.
+#. A recent version of Clang is required to build Firefox. You can learn more about the features we use and their :ref:`compiler support <Using C++ in Mozilla code>`.
+#. If you are on a Fedora machine then simply install the following prerequisites from the terminal window:
+
+.. code-block:: shell
+
+   sudo dnf install @development-tools @c-development gtk2-devel gtk3-devel libXt-devel GConf2-devel dbus-glib-devel yasm-devel alsa-lib-devel pulseaudio-libs-devel
+
+
+.. _installingpython:
+
+Installing 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 some development tasks, like testing and pushing to ``try``.
+
+Often, you can install both Python 2 and 3 with your system package manager.
+Make sure your system is up to date! However, users on older Linux distributions
+might find they are unable to install a recent enough Python 3, while users on
+newer Linux distributions may find that they can no longer install Python 2.7.
+`pyenv <https://github.com/pyenv/pyenv>`_ is an easy way to install arbitrary
+Python versions if you fall into either of these categories. Your system package
+manager may or may not provide ``pyenv``, but the ``pyenv`` GitHub repository
+provides detailed `manual installation instructions
+<https://github.com/pyenv/pyenv#installation>`_ in any case.
+
+Once you have ``pyenv`` configured properly and ``pyenv``'s ``shims`` directory
+at the front of your ``$PATH``, you can easily install any version of Python
+and configure your project to use them. For example, at the root of your
+checkout, do the following:
+
+.. code-block:: shell
+
+    pyenv install 2.7.17
+    pyenv install 3.7.8
+    pyenv local 3.7.8 2.7.17
+
+
+Requirements for Debian / Ubuntu users
+--------------------------------------
+
+You need a number of different packages:
+
+.. code-block:: shell
+
+   # the rust compiler
+   aptitude install rustc
+
+   # the rust package manager
+   aptitude install cargo
+
+   # the headers of important libs
+   aptitude install libgtk-2-dev
+   aptitude install libgtk-3-dev
+   aptitude install libgconf2-dev
+   aptitude install libdbus-glib-1-dev
+   aptitude install libpulse-dev
+
+   # rust dependencies
+   cargo install cbindgen
+
+   # an assembler for compiling webm
+   aptitude install yasm
+
+   # Python 3 dependencies. This will work on Ubuntu 18.04LTS and later or
+   # Debian buster and later. For earlier releases of Ubuntu or Debian, you
+   # may prefer to use pyenv.
+   aptitude install python3 python3-dev python3-pip python3-setuptools
+
+   # Python 2 dependencies. This will work on Ubuntu versions prior to 20.04 LTS
+   # and Debian versions prior to bullseye. For later releases of Ubuntu or
+   # Debian, you may prefer to use pyenv.
+   aptitude install python python-dev python-pip python-setuptools
+
+
+One-Line Bootstrapping
+----------------------
+
+Our system bootstrapping script can automatically install the required
+dependencies. You can download and run it by copying this line and
+pasting it into a terminal window:
+
+.. code-block:: shell
+
+   wget -q https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O bootstrap.py && python3 bootstrap.py
+
+.. note::
+
+   Note: piping bootstrap.py to stdin of a python process will cause
+   interactive prompts in the bootstrap script to fail, causing the
+   bootstrap process to fail. You must run Python against a local file.
+
+If the above command fails, the reason is often because some Linux
+distributions ship with an outdated list of root certificates. In this
+case, you should upgrade your Linux distribution or use your browser to
+download the file. That ensures that you will get it from the right
+source.
+If you get an error from this process, consider `filing a
+bug <https://bugzilla.mozilla.org/enter_bug.cgi?product=Core&component=Build%20Config>`_
+saying that the bootstrapper didn't work and `contact Mike
+Hoye <mailto:mhoye@mozilla.com>` directly for help. Please include the
+error message and some details about your operating system.
+
+If you have already checked out the source code via Mercurial or Git you
+can also use :ref:`mach` with the bootstrap command:
+
+.. code-block:: shell
+
+   ./mach bootstrap
+
+
+
+Common Bootstrapper Failures
+----------------------------
+
+.. code-block:: shell
+
+   wget: command not found
+
+You may not have wget (or curl) installed. In that case, you can either
+install it via your package manager: 
+
+On Debian-based distros like Ubuntu:
+
+.. code-block:: shell
+
+   sudo apt install wget 
+
+On Fedora-based distros:
+
+.. code-block:: shell
+
+   sudo dnf install wget
+
+or you can just `download
+bootstrap.py <https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py>`_
+using your browser and then run it with this command:
+
+.. code-block:: shell
+
+   python3 bootstrap.py
+
+In some cases people who've customized their command prompt to include
+emoji or other non-text symbols have found that bootstrap.py fails with
+a ``UnicodeDecodeError``. We have a bug filed for that but in the
+meantime if you run into this problem you'll need to change your prompt
+back to something boring.
+
+
+More info
+---------
+
+The above bootstrap script supports popular Linux distributions. If it
+doesn't work for you, see :ref:`Linux build prerequisites <Building Firefox On Linux>` for more.
diff --git a/docs/setup/macos_build.rst b/docs/setup/macos_build.rst
new file mode 100644
index 0000000000..098f2b9f5b
--- /dev/null
+++ b/docs/setup/macos_build.rst
@@ -0,0 +1,477 @@
+Building Firefox On macOS
+=========================
+
+This document will help you get set up to build Firefox on your own
+computer. Getting set up won't be difficult, but it 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.
+
+The details are further down this page, but this quick-start guide
+should get you up and running:
+
+.. rubric:: Quick start (Try this first!)
+   :name: Quick_start_Try_this_first!
+
+.. rubric:: Prerequisites
+   :name: Prerequisites
+
+You will need:
+
+-  an Apple ID to download and install Apple-distributed developer tools
+   mentioned below
+-  from 5 minutes to 1 hour to download and install Xcode, which is
+   large
+-  download and install a local copy of specific macOS SDK version
+
+You will need administrator permissions on your machine to install these
+prerequisites. (You can verify that you have these permissions in System
+Preferences -> Users & Groups.)
+
+See :ref:`1.1 Install Xcode and Xcode command line tools <xcode>` and :ref:`1.2
+Get the local macOS SDK <macossdk>` for more information on how to
+install these prerequisites.
+
+.. rubric:: Getting the source
+   :name: Getting_the_source
+   :class: heading-tertiary
+
+Firstly you need to prepare a directory and get the bootstrap script
+that will do the rest:
+
+.. code-block:: shell
+
+    # the bootstrap script needs this directory, but you can choose a different target directory for the Mozilla code later
+    cd ~ && mkdir -p src && cd src
+
+    # download the bootstrap script
+    curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -o bootstrap.py
+
+If you don't have Python 3.6 or later or Mercurial installed, see :ref:`2.1a Install
+dependencies via Homebrew <#install-via-homebrew>` for more information on how
+to do so. Then in your terminal from above start the bootstrapper like this:
+
+.. code-block:: shell
+
+    python3 bootstrap.py
+
+... and follow the prompts. This will use mercurial to checkout the
+source code. If you prefer to work with git, use this command instead:
+
+.. code-block:: shell
+
+    python3 bootstrap.py --vcs=git
+
+If you don't have `Homebrew <https://brew.sh/>`_ or
+`Ports <https://www.macports.org/>`__ installed - software package
+managers that will let us install some programs we'll need - you'll be
+asked to pick one. Either will work, but most Mozilla developers use
+Homebrew.
+
+If you don't let the ``bootstrap.py`` script clone the source for you
+make sure you do it manually afterward before moving onto the next step.
+
+.. rubric:: Build Firefox!
+   :name: Build_Firefox!
+   :class: heading-tertiary highlight-spanned
+
+Now we tie it all together.
+
+In your terminal window, ``cd`` to your Mozilla source directory chosen
+before and type:
+
+.. code-block:: shell
+
+    # create a minimal build options file
+    echo "ac_add_options --with-macos-sdk=$HOME/SDK-archive/MacOSX10.12.sdk" >> mozconfig
+
+    ./mach bootstrap
+
+    ./mach build
+
+The ``./mach bootstrap`` step is a catch-all for any dependencies not
+covered in this documentation. If you are working on Firefox frontends
+or building Firefox without any changes, select :ref:`Artifact Builds
+<Understanding Artifact Builds>` in
+the first question in ``./mach bootstrap``.  Artifact builds will
+complete more quickly!  Artifact builds are unsuitable for those working
+on C++ code.
+
+You’re on your way. Don’t be discouraged if this takes a while; it takes
+some time even on the fastest modern machines and as much as two hours
+or more on older hardware. Firefox is pretty big, because the Web is
+big.
+
+.. rubric:: Now the Fun Starts
+   :name: Now_the_Fun_Starts
+   :class: heading-tertiary
+
+You have the code, you’ve compiled Firefox. Fire it up with
+``./mach run`` and you’re ready to start hacking.
+
+Build steps (details)
+---------------------
+
+Building on macOS is divided into the following steps:
+
+#. Install Apple-distributed developer tools - Xcode, Xcode cli tools
+   and macOS SDK locally
+#. Install supplementary build tools
+#. Obtain a copy of the Mozilla source code
+#. Configure the Mozilla source tree to suit your needs
+#. Build Firefox
+
+
+.. _xcode:
+
+1.1 Install Xcode and Xcode command line tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You first need to install Xcode, for which you have two options but both
+require you to sign in with an Apple ID:
+
+-  From Apple Developer Download page - `direct
+   link <https://developer.apple.com/download/release/>`__. Install the
+   latest **release** (non-beta) version of Xcode, open ``Xcode.xip``,
+   and then **before** **running the extracted Xcode.app, move it from
+   the download folder to /Applications**. (Running it from another
+   location may screw up various build paths, homebrew builds, etc. Fix
+   by running ``sudo xcode-select -switch /Applications/Xcode.app`` )
+-  From the Mac App Store - `direct
+   link <https://apps.apple.com/us/app/xcode>`__.
+
+Open /Applications/Xcode.app and let it do its initial first run and
+setup stuff.
+
+Install the Xcode command line tools by
+running ``xcode-select --install`` in your terminal.
+
+.. _macossdk:
+
+1.2 Get the local macOS SDK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Firefox currently requires a local copy of macOS 10.12 SDK to build (all
+your other apps will still use your more recent version of this SDK,
+most probably matching your macOS version).
+
+There are various issues when building the Mozilla source code with
+other SDKs and that's why we recommend this specific version.
+
+To get the 10.12 SDK, first download Xcode 8.2 from the `More
+Downloads for Apple
+Developers <https://developer.apple.com/download/more/>`__ page. Once
+downloaded, mount the .dmg file. Then in the Terminal run the following:
+
+.. code-block:: shell
+
+    mkdir -p $HOME/SDK-archive
+    cp -a /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk $HOME/SDK-archive/MacOSX10.12.sdk
+
+2. Install supplementary build tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mozilla's source tree requires a number of third-party tools and
+applications to build it. You will need to install these before you can
+build anything.
+
+You have the choice of how to install all these components. You can use
+a package manager like Homebrew or Ports. Or, you can obtain, compile,
+and install them individually. For simplicity and to save your time,
+using a package manager is recommended. The following sections describe
+how to install the packages using existing package managers. Choose
+whatever package manager you prefer.
+
+.. _install-via-homebrew:
+
+2.1a Install dependencies via Homebrew
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`Homebrew <http://brew.sh/>`__ is "the missing package manager for
+macOS." It provides a simple command-line interface to install packages,
+typically by compiling them from source.
+
+The first step is to install Homebrew. See https://brew.sh/
+
+Once you have Homebrew installed, you'll need to run the following:
+
+.. code-block:: shell
+
+    brew install yasm mercurial gawk ccache python
+
+Python 2 is never necessary solely to build Firefox, but it is still required
+for some development tasks (including testing and pushing to ``try``). If your
+system does not already have a Python 2 installed, you can use ``brew`` to
+install one:
+
+.. code-block:: shell
+
+    brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/86a44a0a552c673a05f11018459c9f5faae3becc/Formula/python@2.rb
+
+2.1b Install Dependencies via MacPorts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MacPorts is a package manager for macOS. If you are running Homebrew,
+you can ignore this section.
+
+To install MacPorts, go to their `install
+page <http://www.macports.org/install.php>`_, download the .dmg for
+your platform, and install it. If you already have MacPorts installed,
+ensure it is up to date by running:
+
+.. code::
+
+    sudo port selfupdate
+    sudo port sync
+
+The first of these commands will ask for your root password.
+
+Common errors include:
+
+-  ``sudo`` doesn't accept a blank password: create a password for your
+   account in System Preferences.
+-  ``port`` command not found: add it to your path (see the
+   troubleshooting section below).
+
+Use MacPorts to install the packages needed for building Firefox:
+
+.. code::
+
+    sudo port install libidl yasm python27 py27-gnureadline
+
+You'll then see lots of output as MacPorts builds and installs these
+packages and their dependencies -- it takes a while, so go grab a cup of
+coffee.
+
+**Note:** By default, this will install Python 2.7, which in turn will
+pull in all of the X11 libraries, which may take a while to build. You
+don't need any of those to build Firefox; you may want to consider
+adding +no\_tkinter to the install line to build a python without
+support for the X11 UI packages. This should result in a much faster
+install.
+
+**Note:** With older versions of Xcode (eg 6.4) you may need to use
+MacPorts to get the proper version of clang, such as clang-3.6 or later.
+See bugs in Core, Build Config referring to clang.
+
+2.2 Install Mercurial
+~~~~~~~~~~~~~~~~~~~~~
+
+Mozilla's source code is hosted in Mercurial repositories. You use
+Mercurial to interact with these repositories. There are many ways to
+install Mercurial on macOS:
+
+1. Install `official builds from
+   Selenic <http://mercurial.selenic.com/>`_
+
+2. Install via Homebrew:
+
+.. code-block:: shell
+
+       brew install mercurial
+
+3. Install via MacPorts:
+
+.. code-block:: shell
+
+       sudo port install mercurial
+
+4. Install via Pip:
+
+.. code-block:: shell
+
+       easy_install pip && pip install mercurial
+
+Once you have installed Mercurial, test it by running:
+
+.. code-block:: shell
+
+    hg version
+
+If this works, congratulations! You'll want to configure your Mercurial
+settings to match other developers. See :ref:`Getting Mozilla Source Code
+Using Mercurial <Mercurial Overview>`.
+
+If this fails with the error "``ValueError: unknown locale: UTF-8``",
+then see the
+`workarounds <http://www.selenic.com/mercurial/wiki/index.cgi/UnixInstall#head-1c10f216d5b9ccdcb2613ea37d407eb45f22a394>`_
+on the Mercurial wiki's Unix Install page.
+
+When trying to clone a repository you may get an HTTP 500 error
+(internal server error). This seems to be due to something that Mac
+Mercurial sends to the server (it's been observed both with MacPort and
+selenic.com Mercurial binaries). Try restarting your shell, your
+computer, or reinstall Mercurial (in that order), then report back here
+what worked, please.
+
+3. Obtain a copy of the Mozilla source code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may want to read :ref:`Getting Mozilla Source Code
+Using Mercurial <Mercurial Overview>` for the
+complete instructions.
+
+If you are interested in Firefox development only then run the following
+command, which will create a new directory, ``mozilla-central``, in the
+current one with the contents of the remote repository.
+
+Below command will take many minutes to run, as it will be copying a
+couple hundred megabytes of data over the internet.
+
+.. code::
+
+    hg clone https://hg.mozilla.org/mozilla-central/
+    cd mozilla-central
+
+(If you are building Firefox for Android, you should now return to the
+`Android build instructions <https://wiki.mozilla.org/Mobile/Fennec/Android#Mac_OS_X>`_.)
+
+4. Configure the build options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In your checked out source tree create a new file, ``mozconfig``, which
+will contain your build options. For more on this file, see :ref:`Configuring Build Options`.
+
+To get started quickly, create the file with the following contents:
+
+.. code::
+
+    # Define where build files should go. This places them in the directory
+    # "obj-ff-dbg" under the current source directory
+    mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-dbg
+
+    # Enable debug builds
+    ac_add_options --enable-debug
+
+    # Use the local copy of specific version of macOS SDK compatible with Mozilla source code
+    ac_add_options --with-macos-sdk=$HOME/SDK-archive/MacOSX10.12.sdk
+
+Firefox no longer builds with gcc 4.8 or earlier, but the build system
+should automatically select clang if it is available in the PATH. If
+that is not the case, you need to set CC and CXX. For instance, if you
+installed Clang 9 via Homebrew, then you need to have this in your
+``mozconfig``:
+
+.. code::
+
+    CC=clang-9
+    CXX=clang++-9
+
+5. Build
+~~~~~~~~
+
+Once you have your ``mozconfig`` file in place, you should be able to
+build!
+
+.. code-block:: shell
+
+    ./mach build
+
+If the build step works, you should be able to find the built
+application inside ``obj-ff-dbg/dist/``. If building the browser with
+``--enable-debug``, the name of the application is ``NightlyDebug.app``.
+To launch the application, try running the following:
+
+.. code-block:: shell
+
+    ./mach run
+
+**Note:** The compiled application may also be named after the branch
+you're building; for example, if you changed these instructions to fetch
+the ``mozilla-1.9.2`` branch, the application will be named
+``Namoroka.app`` or ``NamorokaDebug.app``.
+
+Hardware requirements
+---------------------
+
+There are no specific hardware requirements, provided that the hardware
+accommodates all of the `software <#Software_Requirements>`_ required
+to build Firefox. Firefox can take a long time to build, so more CPU,
+more RAM and lots of fast disk space are always recommended.
+
+-  **Processor:** Intel CPUs are required. Building for PowerPC chips is
+   not supported.
+-  **Memory:** 2GB RAM minimum, 8GB recommended.
+-  **Disk Space:** At least 30GB of free disk space.
+
+Software requirements
+---------------------
+
+-  **Operating System:** macOS 10.12 or later. It is advisable to
+   upgrade to the latest “point” release by running Software Update,
+   found in the Apple menu. You will need administrative privileges to
+   set up your development environment
+-  **Development Environment:** Xcode. You can obtain this from the App
+   Store.
+-  **Package Management:** Either Homebrew or
+   `MacPorts <http://www.macports.org/>`_.
+
+These options are specific to Mozilla builds for macOS. For a more
+general overview of build options and the ``mozconfig`` file, see
+:ref:`Configuring Build Options`.
+
+-  **Compiler:** Firefox releases are no longer built with gcc-4.8 or
+   earlier. A recent copy of clang is needed.
+
+   -  There are some options on where to get clang:
+
+      -  Newer versions of Xcode.
+      -  Following the instructions in the `clang
+         website <http://clang.llvm.org/get_started.html>`__ for
+         information on how to get it.
+      -  Using some of the package managers (see above).
+
+   -  Once clang is installed, make sure it is on the PATH and configure
+      should use it.
+
+The following options, specified with ``ac_add_options``, are lines that
+are intended to be added to your ``mozconfig`` file.
+
+-  **macOS SDK:** This selects the version of the system headers and
+   libraries to build against, ensuring that the product you build will
+   be able to run on older systems with less complete APIs available.
+   Selecting an SDK with this option overrides the default headers and
+   libraries in ``/usr/include``, ``/usr/lib``, and ``/System/Library``.
+
+   .. code-block:: shell
+
+         ac_add_options --with-macos-sdk=/path/to/SDK
+
+   Official trunk builds use `MacOSX10.12.sdk`. Check
+   `build/macosx/universal/mozconfig.common <https://searchfox.org/mozilla-central/source/build/macosx/cross-mozconfig.common>`__
+   for the SDK version used for official builds of any particular source
+   release.
+
+   Applications built against a particular SDK will usually run on
+   earlier versions of macOS as long as they are careful not to use
+   features or frameworks only available on later versions. Note that
+   some frameworks (notably AppKit) behave differently at runtime
+   depending on which SDK was used at build time. This may be the source
+   of bugs that only appear on certain platforms or in certain builds.
+
+For macOS builds, defines are set up as follows:
+
+-  ``XP_MACOSX`` is defined
+-  ``XP_UNIX`` is defined
+-  ``XP_MAC`` is **not** defined. ``XP_MAC`` is obsolete and has been
+   removed from the source tree (see {{ Bug(281889) }}). It was used for
+   CFM (non-Mach-O) builds for the classic (pre-X) Mac OS.
+
+This requires care when writing code for Unix platforms that exclude
+Mac:
+
+.. code-block:: shell
+
+    #if defined(XP_UNIX) && !defined(XP_MACOSX)
+
+Troubleshooting
+---------------
+
+-  **If configure (or generally building with clang) fails with
+   ``fatal error: 'stdio.h' file not found``:** Make sure the Xcode
+   command line tools are installed by running.
+   ``xcode-select --install``.
+-  **For inexplicable errors in the configure phase:** Review all
+   modifications of your PATH in .bash\_profile, .bash\_rc or whatever
+   configuration file you're using for your chosen shell. Removing all
+   modifications and then re-adding them one-by-one can narrow down
+   problems.
diff --git a/docs/setup/windows_build.rst b/docs/setup/windows_build.rst
new file mode 100644
index 0000000000..945d38c349
--- /dev/null
+++ b/docs/setup/windows_build.rst
@@ -0,0 +1,476 @@
+Building Firefox On Windows
+===========================
+
+Thank you for helping us build the world's best browser on the world's
+most popular OS. This document will help you get set up to build and
+hack on your own version of Firefox on your local machine.
+
+Getting set up won't be difficult, but it 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.
+
+The details are further down this page, but this quick start guide
+should get you up and running:
+
+Getting ready
+-------------
+
+To build Firefox on Windows, you need a 64-bit version of Windows 7 or
+later and about 40 GB of free space on your hard drive. You can make
+sure your version of Windows is 64-bit on Windows 7 by right-clicking on
+“Computer” in your “Start” menu, clicking “Properties” and then
+“System”. On Windows 8.1 and Windows 10, right-clicking the “Windows”
+menu button and choosing “System” will show you the same information.
+You can alternatively press the “Windows” and “Pause Break” buttons
+simultaneously on your keyboard on any version of Windows.
+
+Next, we want to start on a solid foundation: make sure you’re up to
+date with Windows Update and then we’ll get moving.
+
+.. note::
+
+   Microsoft is providing some Windows images with Visual Studio and code
+   https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/
+
+
+Visual Studio 2019
+~~~~~~~~~~~~~~~~~~
+
+
+.. note:: 
+
+   As of `bug
+   1483835 <https://bugzilla.mozilla.org/show_bug.cgi?id=1483835>`_, local
+   Windows builds `use clang-cl by
+   default <https://groups.google.com/d/topic/mozilla.dev.platform/MdbLAcvHC0Y/discussion>`_
+   as compiler. Visual Studio is still necessary for build tools, headers,
+   and SDK.
+
+.. note::
+
+   Automation builds still use Visual Studio 2017, so there may be some
+   divergence until we upgrade. `Bug
+   1581930 <https://bugzilla.mozilla.org/show_bug.cgi?id=1581930>`_ tracks
+   various issues building with 2019. Please file your issue there and
+   downgrade in the interim if you encounter build failures.
+
+`Download and install the Community
+edition <https://visualstudio.microsoft.com/downloads/>`_ of Visual
+Studio 2019. Professional and Enterprise are also supported if you have
+either of those editions.
+
+.. note::
+
+   When installing, the following workloads must be checked:
+
+   -  "Desktop development with C++" (under the Windows group)
+   -  "Game development with C++" (under the Mobile & Gaming group)
+
+   In addition, go to the Individual Components tab and make sure the
+   following components are selected under the "SDKs, libraries, and
+   frameworks" group:
+
+   -  "Windows 10 SDK" (at least version **10.0.17134.0**)
+   -  "C++ ATL for v142 build tools (x86 and x64)" (also select ARM64
+      if you'll be building for ARM64)
+
+Make sure you run Visual Studio once after installing, so it finishes
+any first-run tasks and associates the installation with your account.
+
+If you already have Visual Studio 2019 installed, you can get to the
+installer via its menu "Tools" → "Get Tools and Features".
+
+Other Required Tools
+~~~~~~~~~~~~~~~~~~~~
+
+MozillaBuild
+^^^^^^^^^^^^
+
+Finally, download the `MozillaBuild
+Package <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__
+from Mozilla. Accept the default settings, in particular the default
+installation directory: ``c:\mozilla-build\``. On some versions of
+Windows an error dialog will give you the option to ‘reinstall with the
+correct settings’ - you should agree and proceed.
+
+Once this is done, creating a shortcut to
+``c:\mozilla-build\start-shell.bat`` on your desktop will make your life
+easier.
+
+Getting the source
+~~~~~~~~~~~~~~~~~~
+
+This is the last big step. Double-clicking **start-shell.bat** in
+``c:\mozilla-build`` (or the shortcut you’ve created above) will open a
+terminal window.
+
+Start by creating a "mozilla-source" directory off of ``C:\`` and cd
+into it like so
+
+.. code-block:: shell
+
+    cd c:/
+
+    mkdir mozilla-source
+
+    cd mozilla-source
+
+Next, you can get the Firefox source code with Mercurial. There is a
+wiki page on how to :ref:`get the source using
+Mercurial <Mercurial Overview>`
+but, in summary, if your network connection is good enough to download
+1+ GB without interuption and you want the main development repository,
+then you can just use:
+
+.. code-block:: shell
+
+    curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -o bootstrap.py
+
+    python3 bootstrap.py
+
+... and follow the prompts. This will use mercurial to checkout the
+source code. If you prefer to work with git, use this command instead (you'll
+have to have `Git for Windows <https://git-scm.com/download/win>`_ installed):
+
+.. code-block:: shell
+
+    python3 bootstrap.py --vcs=git
+
+While you’re waiting for that process to finish, take a look at `our
+Mercurial
+documentation <http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html>`_.
+It explains how we use version control at Mozilla to manage our code and
+land changes to our source tree.
+
+Build Firefox!
+~~~~~~~~~~~~~~
+
+Now we tie it all together. In your terminal window, ``cd`` to your
+source directory as before and type
+
+.. code-block:: shell
+
+    cd mozilla-unified  # ... or the name of the repo you chose earlier
+
+    ./mach bootstrap
+
+    ./mach build
+
+The ``./mach bootstrap`` step is a catch-all for any dependencies not
+covered in this documentation. Note that, bootstrap works **only with
+the Mercurial repo of the source**, not with source tar balls, nor the
+github mirror. If you are working on Firefox or Firefox for Android
+frontends or building Firefox without any changes, select :ref:`Artifact Builds
+<Understanding Artifact Builds>` in
+the first question in ``./mach bootstrap``.  Artifact builds will
+complete more quickly!  Artifact builds are unsuitable for those working
+on C++ or Rust code.
+
+You’re on your way. Don’t be discouraged if this takes a while; it takes
+some time even on the fastest modern machines and as much as two hours
+or more on older hardware. Firefox is pretty big, because the Web is
+big.
+
+
+You're ready
+~~~~~~~~~~~~
+
+When mach build completes, you'll have your own version of Firefox built
+from the source code on your hard drive, ready to run. You can run it
+with
+
+.. code-block:: shell
+
+    ./mach run
+
+Now you have your own home-built version of Firefox.
+
+If you saw an error here, look further down in this document for the
+"Troubleshooting" section - some antivirus software quarantine some of
+our tests, so you need to create exceptions for the "mozilla-source" and
+"mozilla-build" directories. Don't turn your antivirus off! Just add the
+exceptions.
+
+
+Details and troubleshooting
+---------------------------
+
+Hardware and software requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Firefox build process is both I/O and CPU-intensive, and can take a
+long time to build even on modern hardware. The minimum and recommended
+hardware requirements for Mozilla development are:
+
+-  At least 4 GB of RAM. 8 GB or more is recommended, and more is always
+   better.
+-  35 GB free disk space. This amount of disk space accommodates Visual
+   Studio 2019 Community Edition, the required SDKs, the MozillaBuild
+   package, the Mercurial source repository and enough free disk space
+   to compile. A solid-state hard disk is recommended as the Firefox
+   build process is I/O-intensive.
+-  A 64-bit version of Windows 7 (Service Pack 1) or later. You can
+   still build 32-bit Firefox on a 64-bit Windows installation.
+
+Overview
+~~~~~~~~
+
+The Mozilla build process requires many tools that are not pre-installed
+on most Windows systems. In addition to Visual Studio, install
+MozillaBuild - a software bundle that includes the required versions of
+bash, GNU make, Mercurial, and much more.
+
+Firefox 61+ require Visual Studio 2017 Update 6 or newer to build.
+
+Firefox 48 to 60 build with Visual Studio 2015. Visual Studio 2017 also
+works for building Firefox 58 or newer.
+
+Firefox 37 through to 47 build with Visual Studio 2013 (VC12) and
+possibly Visual Studio 2015 (although Visual Studio 2015 may not build
+every revision).
+
+Earlier versions of Firefox build with older versions of Visual Studio.
+
+Installing the build prerequisites
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Complete each of these steps otherwise, you may not be able to build
+successfully. There are notes on these software requirements below.
+
+#. Make sure your system is up-to-date through Windows Update.
+#. Install `Visual Studio Community
+   2019 <https://www.visualstudio.com/downloads/>`_ (free).
+   Alternatively, you can also use a paid version of Visual Studio. Some
+   additional components may be required to build Firefox, as noted in
+   the "Visual Studio 2019" section above. Earlier versions of Visual
+   Studio are not supported; the Firefox codebase relies on C++ features
+   that are not supported in earlier releases.
+#. Optionally, in addition to VS2019, you may want to install `Visual
+   C++ 2008 Express <http://go.microsoft.com/?linkid=7729279>`_ (free)
+   to compile some Python extensions used in the build system as Python
+   2.7.x for Windows is built with that compiler by default. Note, if
+   you want to use "mach resource-usage", "mach doctor", "mach
+   android-emulator", or run talos tests locally, you should install it
+   for building psutil.
+#. Download and install the
+   `MozillaBuild <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__
+   package, containing additional build tools. If you have Cygwin
+   installed, read the note in the tips section. If you see a Windows
+   error dialog giving you the option to re-install with the 'correct
+   settings', after the MozillaBuild's installer exits, choose the
+   option and after that all should be well. More information about
+   MozillaBuild and links to newer versions are available at
+   https://wiki.mozilla.org/MozillaBuild.
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+In some circumstances, the following problems can arise:
+
+Antivirus performance
+^^^^^^^^^^^^^^^^^^^^^
+
+-  Windows Defender and some scanning antivirus products are known to
+   have a major impact on build times. For example, if you have cloned
+   ``mozilla-unified`` successfully but ``./mach build`` fails, reporting
+   a missing file, you are likely experiencing this problem. Our
+   regression tests, for well-known security bugs, can include code
+   samples that some antivirus software will identify as a threat, and
+   will either quarantine or otherwise corrupt the files involved. To
+   resolve this you will need to add your source and object directories
+   (the ``mozilla-source`` and ``mozilla-build``
+   directories) to the
+   `exclusion list in Windows Defender <https://support.microsoft.com/en-ca/help/4028485/windows-10-add-an-exclusion-to-windows-security>`_
+   or your antivirus software. If you are missing files, revert your source
+   tree with the ``hg update -C`` command. Once this is done your next
+   ``./mach build`` should complete successfully.
+
+Installing Visual Studio in a different language than the system can cause issues
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+-  For example, having Visual Studio in French when the system is in
+   English causes the build to spew a lot of include errors and finishes
+   with a link error.
+
+.. note::
+
+   **Note:** **Mozilla will not build** if the path to the installation
+   tool folders contains **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.
+
+MozillaBuild package
+~~~~~~~~~~~~~~~~~~~~
+
+The MozillaBuild package contains other software prerequisites necessary
+for building Mozilla, including the MSYS build environment,
+`Mercurial <https://www.mercurial-scm.org/>`_, CVS, Python, YASM, NSIS, and UPX,
+as well as optional but useful tools such as wget and emacs.
+
+`Download the current MozillaBuild
+package. <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`_
+
+By default, the package installs to ``c:\mozilla-build`` and it is
+recommended to use the default path. Don't use a path that contains
+spaces. The installer does not modify the Windows registry. Note that
+some binaries may require `Visual C++ Redistributable
+package <https://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2&displaylang=en>`_ to
+run.
+
+.. note::
+
+   **MozillaBuild command prompt expectation setting:** Note that the
+   "UNIX-like" environment provided by MozillaBuild is only really useful
+   for building and committing to the Mozilla source. Most command line
+   tools you would expect in a modern Linux distribution are not present,
+   and those tools that are provided can be as much as a decade or so old
+   (especially those provided by MSYS). It's the old tools in particular
+   that can cause problems since they often don't behave as expected, are
+   buggy, or don't support command line arguments that have been taken for
+   granted for years. For example, copying a source tree using
+   ``cp -rf src1 src2`` does not work correctly because of an old version
+   of cp (it gives "cp: will not create hard link" errors for some files).
+   In short, MozillaBuild supports essential developer interactions with
+   the Mozilla code, but beyond that don't be surprised if it trips you up
+   in all sorts of exciting and unexpected ways.
+
+Opening a MozillaBuild command prompt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After the prerequisites are installed, launch
+the ``start-shell.bat`` batch file using the Windows command
+prompt in the directory to which you installed MozillaBuild
+(``c:\mozilla-build`` by default). This will launch an MSYS/BASH command
+prompt properly configured to build Firefox. All further commands should
+be executed in this command prompt window. (Note that this is not the
+same as what you get with the Windows CMD.EXE shell.)
+
+.. note::
+
+  Note: This is not the same as what you get with the Windows CMD.EXE
+  shell.
+
+Create a directory for the source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Note:** You won't be able to build the Firefox source code if it's
+under a directory with spaces in the path such as "Documents and
+Settings". You can pick any other location, such as a new directory
+c:/mozilla-source or c:/thunderbird-src. The build command prompt also
+tolerates "c:\\" and "/c/", but the former gives confusion in the
+Windows command prompt, and the latter is misinterpreted by some tools
+(at least MOZ\_OBJDIR). The "C:/" syntax helps draw attention that the
+**MozillaBuild** command prompt is assumed from here on out since it
+provides configured environment and tools.
+
+
+It's a sensible idea to create a new shallow directory, like
+"c:/mozilla-source" dedicated solely to the
+code:
+
+.. code-block:: shell
+
+    cd c:/; mkdir mozilla-source; cd mozilla-source
+
+Keeping in mind the diagnostic hints below should you have issues. You
+are now ready to get the Firefox source and build.
+
+Command prompt tips and caveats
+-------------------------------
+
+-  To paste into this window, you must right-click on the window's title
+   bar, move your cursor to the “Edit” menu, and click “Paste”. You can
+   also set “Quick Edit Mode” in the “Properties” menu and right-click
+   the window to paste your selection.
+-  If you have Cygwin installed, make sure that the MozillaBuild
+   directories come before any Cygwin directories in the search path
+   enhanced by ``start-shell-msvc2015.bat`` (use ``echo $PATH`` to see
+   your search path).
+-  In the MSYS / BASH shell started by ``start-shell-msvc2015.bat``,
+   UNIX-style forward slashes (/) are used as path separators instead of
+   the Windows-style backward slashes (\\).  So if you want to change to
+   the directory ``c:\mydir``, in the MSYS shell to improve clarity, you
+   would use ``cd /c/mydir ``though both ``c:\mydir`` and ``c:/mydir``
+   are supported.
+-  The MSYS root directory is located in ``/c/mozilla-build/msys`` if
+   you used the default installation directory. It's a good idea not to
+   build anything under this directory. Instead use something like
+   ``/c/mydir``.
+
+Common problems, hints, and restrictions
+----------------------------------------
+
+-  :ref:`Debugging Firefox on Windows FAQ <Debugging On Windows>`:
+   Tips on how to debug Mozilla on Windows.
+-  Your installed MozillaBuild may be too old. The build system may
+   assume you have new features and bugfixes that are only present in
+   newer versions of MozillaBuild. Instructions for how to update
+   MozillaBuild `can be found
+   here <https://wiki.mozilla.org/MozillaBuild>`_.
+-  If the bootstrapping script ``bootstrap.py`` fails, you can also try running
+   ``hg clone https://hg.mozilla.org/mozilla-unified`` followed by
+   ``cd mozilla-unified; ./mach bootstrap`` yourself.
+-  The build may fail if your machine is configured with the wrong
+   architecture. If you want to build 64-bit Firefox, add the two lines
+   below to your mozconfig file:
+
+.. code-block:: shell
+
+       ac_add_options --target=x86_64-pc-mingw32
+       ac_add_options --host=x86_64-pc-mingw32
+
+-  The build may fail if your ``PATH`` environment variable contains
+   quotation marks("). Quotes are not properly translated when passed
+   down to MozillaBuild sub-shells and they are usually not needed so
+   they can be removed.
+-  The build may fail if you have a ``PYTHON`` environment variable set.
+   It displays an error almost immediately that says
+   "``The system cannot find the file specified``." Typing
+   "``unset PYTHON``" before running the Mozilla build tools in the same
+   command shell should fix this. Make sure that ``PYTHON`` is unset,
+   rather than set to an empty value.
+-  The build may fail if you have Cygwin installed. Make sure that the
+   MozillaBuild directories (``/c/mozilla-build`` and subdirectories)
+   come before any Cygwin directories in your PATH environment variable.
+   If this does not help, remove the Cygwin directories from PATH, or
+   try building on a clean PC with no Cygwin.
+-  Building with versions of NSIS other than the version that comes with
+   the latest supported version of MozillaBuild is not supported and
+   will likely fail.
+-  If you intend to distribute your build to others, set
+   ``WIN32_REDIST_DIR=$VCINSTALLDIR\redist\x86\Microsoft.VC141.CRT`` in
+   your mozconfig to get the Microsoft CRT DLLs packaged along with the
+   application. Note the exact .CRT file may depend on your Visual
+   Studio version.
+-  The Microsoft Antimalware service can interfere with compilation,
+   often manifesting as an error related to ``conftest.exe`` during
+   build. To remedy this, add at your object directory at least to the
+   exclusion settings.
+-  Errors like "second C linkage of overloaded function
+   '\_interlockedbittestandset' not allowed", are encountered when
+   intrin.h and windows.h are included together. Use a *#define* to
+   redefine one instance of the function's name.
+-  Parallel builds (``-jN``) do not work with GNU makes on Windows. You
+   should use the ``mozmake`` command included with current versions of
+   MozillaBuild. Building with the ``mach`` command will always use the
+   best available make command.
+-  If you encounter a build failure like "ERROR: Cannot find
+   makecab.exe", try applying the patch from `bug
+   1383578 <https://bugzilla.mozilla.org/show_bug.cgi?id=1383578>`_,
+   i.e. change: ``SET PATH="%PATH%;!LLVMDIR!\bin"``  to
+   ``SET "PATH=%PATH%;!LLVMDIR!\bin"``.
+-  If you encounter a build failure with
+   ``LINK: fatal error LNK1181: cannot open input file ..\..\..\..\..\security\nss3.lib``,
+   it may be related to your clone of ``mozilla-unified`` being located
+   in the Users folder (possibly encrypted). Try moving it outside of
+   the Users folder. The docs recommend
+   ``C:\mozilla-source\mozilla-unified`` which should work.
+-  If you encounter a build failure with
+   ``ERROR: GetShortPathName returned a long path name.``.You need
+   create a 8dot3name short name for the path which has space.For
+   example : fsutil file setshortname "C:\\Program Files (x86)"
+   PROGRA~2.  If you got "access denied", try to restart your computer
+   to safe mode and try again.
+