summaryrefslogtreecommitdiffstats
path: root/docs/setup
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/setup/building_with_debug_symbols.rst61
-rw-r--r--docs/setup/configuring_build_options.rst404
-rw-r--r--docs/setup/contributing_code.rst181
-rw-r--r--docs/setup/index.rst25
-rw-r--r--docs/setup/linux_32bit_build_on_64bit_OS.rst37
-rw-r--r--docs/setup/linux_build.rst151
-rw-r--r--docs/setup/macos_build.rst122
-rw-r--r--docs/setup/windows_build.rst181
8 files changed, 1162 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..fd57930022
--- /dev/null
+++ b/docs/setup/configuring_build_options.rst
@@ -0,0 +1,404 @@
+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::
+
+ **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::
+
+ **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``.
+
+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 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-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 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..8b24dac87d
--- /dev/null
+++ b/docs/setup/contributing_code.rst
@@ -0,0 +1,181 @@
+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 <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/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..6e8656fc4a
--- /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 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
+
+#. 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..8582a52be6
--- /dev/null
+++ b/docs/setup/linux_build.rst
@@ -0,0 +1,151 @@
+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::
+
+ In general, the Firefox workflow works best with Mercurial. However,
+ if you'd prefer 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`.
+
+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
+ ./mach run
+
+🎉 Congratulations! You've built your own home-grown Firefox!
+
+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
+---------------
+
+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..3d32b8aed0
--- /dev/null
+++ b/docs/setup/macos_build.rst
@@ -0,0 +1,122 @@
+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:
+
+**NOTE** Pay special attention to the `==6.1.4`, as Mercurial >=6.2 is incompatible with several plugins
+
+.. code-block:: shell
+
+ echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.zshenv
+ python3 -m pip install --user mercurial==6.1.4
+
+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::
+
+ In general, the Firefox workflow works best with Mercurial. However,
+ if you'd prefer 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`.
+
+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
+ ./mach run
+
+🎉 Congratulations! You've built your own home-grown Firefox!
+
+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.
diff --git a/docs/setup/windows_build.rst b/docs/setup/windows_build.rst
new file mode 100644
index 0000000000..2e8da661e9
--- /dev/null
+++ b/docs/setup/windows_build.rst
@@ -0,0 +1,181 @@
+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.
+
+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::
+
+ In general, the Firefox workflow works best with Mercurial. However,
+ if you'd prefer 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`.
+
+.. _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'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``).
+
+3. 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
+ ./mach run
+
+🎉 Congratulations! You've built your own home-grown Firefox!
+
+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
+---------------
+
+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 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.
+
+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.