Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-11-24 13:21:05 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1179358 - Moving contribution and related info from MDN to m-c r=sylvestre

Browse Source 
Differential Revision: https://phabricator.services.mozilla.com/D68835
This commit is contained in:
mhoye 2020-05-25 08:53:37 +00:00
parent f2401ecda3
commit 57a1c6a1d8
13 changed files with 1722 additions and 294 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/config.yml
View File

@ -3,6 +3,8 @@
# The order of the main categories are defined in index.rst
# Sub categories orders are preserved
categories:
setup_doc:
- contributing/setup
contributing_doc:
- contributing
- bug-mgmt

30
docs/contributing/build/building_mobile_firefox.rst Normal file
View File

@ -0,0 +1,30 @@
Firefox for Mobile Devices
--------------------------
We have several different mobile products aimed at different tasks,
devices, and audiences:
- `Building Firefox for
Android <https://geckoview.dev/contributor/geckoview-quick-start>`.
(Codename: Fennec)
- `Building Firefox for iOS <https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_for_iOS>`,
our general-purpose browser for iOS with desktop sync built-in.
- `Building Firefox
Focus <https://github.com/mozilla-mobile/focus>`, our
privacy-focused browser for
`iOS <https://github.com/mozilla-mobile/focus-ios>` and
`Android <https://github.com/mozilla-mobile/focus-android>`.
For both Desktop and Mobile development, please bear the following in
mind:
- While you can build Firefox on older hardware it can take quite a bit
of time to compile on slower machines. Having at least 8GB of RAM is
recommended, and more is always better. The build process is both CPU
and I/O intensive, so building on a machine with an SSD is also
strongly preferred.
- Fast broadband internet is strongly recommended as well. Both the
development environment and the source code repository are quite
large.
- Though you can build Firefox to run on 32-bit machines, the build
process for almost all of our products requires a 64-bit OS.

271
docs/contributing/build/linux_build.rst
View File

@ -1,272 +1 @@
.. _linux-build-documentation:
Linux build preparation
=======================
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 2.7 and Python 3.x installed. You can check with ``python --version`` to see if you have it already.If not, you can install it with your distribution’s package manager. Make sure your system is up to date!
#. 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
python 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
python bootstrap.py --vcs=git
Getting Access
--------------
`Bugzilla <https://bugzilla.mozilla.org/>`__ is Mozilla’s issue
tracker; you'll need to be able to log into it to comment on a bug
or submit a patch. You can either use your `GitHub
account <https://github.com>`__, or you can `sign up for a
Bugzilla account
here. <https://bugzilla.mozilla.org/createaccount.cgi>`__
As well as Bugzilla, much of Mozilla’s internal communication
happens over Riot/Matrix. The instance is available on https://chat.mozilla.org/.
If you’re just getting started or have questions about getting set up you can join us in
the `#introduction <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ channel,
where some of our community members hang out to try and help new contributors get rolling.
Let’s Build Firefox
-------------------
You’re ready; now we can tie it all together. In your terminal:
.. code-block:: shell
cd mozilla-central
If you are not working on the C/C++ files you can also opt for
`Artifact
Builds <https://developer.mozilla.org/en-US/docs/Artifact_builds>`__
which are much faster. To enable artifact build set up a
`.mozconfig </en-US/docs/Mozilla/Developer_guide/Build_Instructions/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
`.mozconfig </en-US/docs/Mozilla/Developer_guide/Build_Instructions/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 IRC in the ``#introduction`` channel,
and find `a bug to start working
on. <https://codetribute.mozilla.org/>`__
General considerations
----------------------
#. 2GB RAM with an additional 2GB 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. "`Artifact builds <https://developer.mozilla.org/en-US/docs/Artifact_builds>`__" may be possible, but are not a supported configuration. On Linux you can determine this by typing "``uname -a``" in a terminal.
#. A recent version of Clang is required to build Firefox. You can `learn more about the features we use and their compiler support here <https://developer.mozilla.org/en-US/docs/Using_CXX_in_Mozilla_code>`__
#. Most Linux distros now install a later version of autoconf, which the build system cannot use, reporting the error "``*** Couldn't find autoconf 2.13. Stop.``" However a separate ``autoconf2.13`` package is usually available. To install `autoconf 2.13` in Debian based distros copy this line and paste it into a terminal window:
.. code-block:: shell
$ sudo apt install autoconf2.13
#. 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 autoconf213 gtk2-devel gtk3-devel libXt-devel GConf2-devel dbus-glib-devel yasm-devel alsa-lib-devel pulseaudio-libs-devel
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 required (old) version of autoconf
aptitude install autoconf2.13
# 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
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 && python 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 `mach </en-US/docs/Developer_Guide/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
python 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 `Linux build
prerequisites <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Linux_Prerequisites>`__ for more.

88
docs/contributing/build/supported_configurations.rst Normal file
View File

@ -0,0 +1,88 @@
Supported Firefox Build Targets
===============================
There are three tiers of **supported Firefox build targets** at this
time. These tiers represent the shared engineering priorities of the
Mozilla project.
The term **"Tier-1 platform"** refers to those platforms - CPU
architectures and operating systems - that are the primary focus of
Firefox development efforts. Tier-1 platforms are fully supported by
Mozilla's `continuous integration processes <https://developer.mozilla.org/en-US/docs/>` and the
`Try Server <https://developer.mozilla.org/en-US/docs/>`. Any proposed change to Firefox on these
platforms that results in build failures, test failures, performance
regressions or other major problems **will be reverted immediately**.
Tier-1 Firefox Platforms
------------------------
The **Tier-1 Firefox platforms** and their supported compilers are:
- Android on Linux x86, x86-64, ARMv7 and ARMv8-A (clang)
- Linux/x86 and x86-64 (gcc and clang)
- OSX 10.9 and later on x86-64 (clang)
- Windows/x86, x86-64 and AArch64 (clang-cl)
Prior to Firefox 63, Windows/x86 and Windows/x86-64 relied on the MSVC
compiler; from **Firefox 63 onward MSVC is not supported**. Older 32-bit
x86 CPUs without SSE2 instructions such as the Pentium III and Athlon XP
are also **not considered Tier-1 platforms, and are not supported**.
Note also that while Windows/x86 and ARM/AArch64 are supported *as build
targets*, it is not possible to build Firefox *on* Windows/x86 or
Windows/AArch64 systems.
Tier-2 Firefox Platforms
------------------------
**Tier-2 platforms** are actively maintained by the Mozilla community,
though with less rigorous requirements. Proposed changes resulting in
breakage or regressions limited to these platforms **may not immediately
result in reversion**. However, developers who break these platforms are
expected to work with platform maintainers to fix problems, and **may be
required to revert their changes** if a fix cannot be found.
The **Tier-2 Firefox platforms** and their supported compilers are:
- Linux/AArch64 (clang)
- Windows/x86 (mingw-clang) - maintained by Tom Ritter and Jacek Caban
.. note:
*Note that some features of this platform are disabled, as they
require MS COM or the w32api project doesn't expose the necessary
Windows APIs.*
Tier-3 Firefox Platforms
------------------------
**Tier-3 platforms** have a maintainer or community which attempt to
keep the platform working. These platforms are **not supported by our
continuous integration processes**, and **Mozilla does not routinely
test on these platforms**, nor do we block further development on the
outcomes of those tests.
At any given time a Firefox built from mozilla-central for these
platforms may or may not work correctly or build at all.
**Tier-3 Firefox platforms** include: 
- Linux on various CPU architectures including ARM variants not listed
above, PowerPC, and x86 CPUs without SSE2 support - maintained by
various Linux distributions
- FreeBSD/x86, x86-64, Aarch64 (clang) - maintained by Jan Beich
- OpenBSD/x86, x86-64 (clang) - maintained by Landry Breuil
- NetBSD/x86-64 (gcc) - maintained by David Laight
- Solaris/x86-64, sparc64 (gcc) - maintained by Petr Sumbera
- [STRIKEOUT:Windows/x86-64 (mingw-gcc)] - Unsupported due to
requirements for clang-bindgen
If you're filing a bug against Firefox on a Tier-3 platform (or any
combination of OS, CPU and compiler not listed above) please bear in
mind that Mozilla developers do not reliably have access to non-Tier-1
platforms or build environments. To be actionable bug reports against
non-Tier-1 platforms should include as much information as possible to
help the owner of the bug determine the cause of the problem and the
proper solution. If you can provide a patch, a regression range or
assist in verifying that the developer's patches work for your platform,
that would help a lot towards getting your bugs fixed and checked into
the tree.

12
docs/contributing/how_to_contribute_firefox.rst
View File

@ -1,9 +1,9 @@
How to contribute to Firefox
============================
Contributing To Firefox - Quick Reference
=========================================
The whole process is a bit long, and it will 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>`__
Some parts of this process, including cloning and compiling, can take a long time even on modern hardware.
If at any point you get 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.
Clone the sources
@ -17,7 +17,7 @@ You can use either mercurial or git. `Mercurial <https://www.mercurial-scm.org/d
For git, see the `git cinnabar documentation <https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development>`__
The clone should be around 30 minutes (depending on your connection) and
The clone can take from 40 minutes to two hours,(depending on your connection) and
the repository should be less than 5GB (~ 20GB after the build).
If you have any network connection issues and cannot clone with command, try :ref:`Mercurial bundles <Mercurial bundles>`.
@ -43,7 +43,7 @@ Windows dependencies
--------------------
#. You need 64-bit version of Windows 7 or later.
#. Download and install `Visual Studio. <https://visualstudio.microsoft.com/downloads/>`__
#. Download and install `Visual Studio Community Edition. <https://visualstudio.microsoft.com/downloads/>`__
#. Finally download the `MozillaBuild Package. <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__ Installation directory should be:
.. code-block:: shell

20
docs/contributing/index.rst
View File

@ -1,21 +1,19 @@
Contributing to Firefox
=======================
This is the preferred location for all Firefox development process and
source code documentation.
This section has the details about how we make changes to Firefox, and how you can
do the same.
.. toctree::
:caption: Making Changes To Firefox
:maxdepth: 1
:glob:
how_to_contribute_firefox
editor
reviews
directory_structure
.. toctree::
:caption: Version control system
:caption: The Mercurial Version Control System
:maxdepth: 1
:glob:
@ -23,8 +21,10 @@ source code documentation.
.. toctree::
:caption: How to build Firefox
:caption: Additional Information
:maxdepth: 1
:glob:
build/*
directory_structure
build/artifact_builds
build/building_mobile_firefox
build/supported_configurations

214
docs/contributing/setup/contributing_code.rst Normal file
View File

@ -0,0 +1,214 @@
How to contribute to Firefox
============================
The whole process is a bit long, and it will 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.
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://bugzil.la/sw:%22%5Bgood%20first%20bug%5D%22&limit=0>`
- 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.
- Follow `@StartMozilla on
Twitter <https://twitter.com/startmozilla>` - we link up Good First
Bugs for new contributors across Mozilla every day.
- 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>`, and one
for `implementing new
applications. <https://github.com/Yoric/Mozilla-Student-Projects/issues>`
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/en-US/docs/Mozilla/Bugzilla>`\ and `Searching
Bugzilla <https://developer.mozilla.org/en-US/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
- Ask in our matrix channels :
`#introduction:mozilla.org <https://riot.im/app/#/room/#introduction:mozilla.org>`
or
`#developers:mozilla.org <https://chat.mozilla.org/#/room/#developers:mozilla.org>`
Fixing your bug
---------------
We leave this in your hands. Here are some further resources to help:
- Ask for help in a comment on the bug, or in
`#introduction <https://chat.mibbit.com/?url=irc%3A%2F%2Firc.mozilla.org%2F%23introduction>`
or
`#developers <https://chat.mibbit.com/?url=irc%3A%2F%2Firc.mozilla.org%2F%23developers>`
- Check out
`https://developer.mozilla.org/en-US/docs/Developer\_Guide <https://developer.mozilla.org/en-US/docs/Developer_Guide>`
and its parent document,
https://developer.mozilla.org/en-US/docs/Mozilla
- Our `reviewer
checklist <https://developer.mozilla.org/en-US/docs/Developer_Guide/Reviewer_Checklist>` is very
useful, if you have a patch near completion, and seek a favorable
review
- Utilize our build tool
`Mach <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/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)

76
docs/contributing/setup/getting_set_up.rst Normal file
View File

@ -0,0 +1,76 @@
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!
How To Get Started: Setting Up To Build Firefox
-----------------------------------------------
If you'd like to contribute to Firefox, your first step will be to get
set up for your platform. This will be straightforward, but may take some
time; there are some big downloads and long compiles involved, so you may want to move
on to the next steps while it builds.
Firefox is big, and there are a lot of moving parts to it; if you're starting from
scratch, you're going to need about forty gigabytes of free disk space and reliable
internet connection to pull in everything you need. For more information, click Next!

19
docs/contributing/setup/index.rst Normal file
View File

@ -0,0 +1,19 @@
Getting Started With The Firefox Codebase
=========================================
.. toctree::
:caption: Getting Set Up To Work On Firefox
getting_set_up
.. toctree::
:caption: Setting Up Your Machine
windows_build
macos_build
linux_build
.. toctree::
:caption: Getting Ready To Contribute
contributing_code

253
docs/contributing/setup/linux_build.rst Normal file
View File

@ -0,0 +1,253 @@
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 2.7 and Python 3.x installed. You can check with ``python --version`` to see if you have it already.If not, you can install it with your distribution’s package manager. Make sure your system is up to date!
#. 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
python 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
python 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-central
If you are not working on the C/C++ files you can also opt for
`Artifact
Builds <https://developer.mozilla.org/en-US/docs/Artifact_builds>`
which are much faster. To enable artifact build set up a
`.mozconfig <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/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
`.mozconfig <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/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 IRC in the ``#introduction`` channel,
and find `a bug to start working
on. <https://codetribute.mozilla.org/>`
General considerations
----------------------
#. 2GB RAM with an additional 2GB 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. "`Artifact builds <https://developer.mozilla.org/en-US/docs/Artifact_builds>`" may be possible, but are not a supported configuration. On Linux you can determine this by typing "``uname -a``" in a terminal.
#. A recent version of Clang is required to build Firefox. You can `learn more about the features we use and their compiler support here <https://developer.mozilla.org/en-US/docs/Using_CXX_in_Mozilla_code>`
#. Most Linux distros now install a later version of autoconf, which the build system cannot use, reporting the error "``*** Couldn't find autoconf 2.13. Stop.``" However a separate ``autoconf2.13`` package is usually available. To install `autoconf 2.13` in Debian based distros copy this line and paste it into a terminal window:
.. code-block:: shell
$ sudo apt install autoconf2.13
#. 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 autoconf213 gtk2-devel gtk3-devel libXt-devel GConf2-devel dbus-glib-devel yasm-devel alsa-lib-devel pulseaudio-libs-devel
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 required (old) version of autoconf
aptitude install autoconf2.13
# 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
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 && python 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 `mach <https://developer.mozilla.org/en-US/docs/Developer_Guide/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
python 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 `Linux build
prerequisites <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Linux_Prerequisites>` for more.

535
docs/contributing/setup/macos_build.rst Normal file
View File

@ -0,0 +1,535 @@
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 `1.1 Install Xcode and Xcode command line tools <#xcode>` and `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
Then in your terminal from above start the bootstrapper like this:
.. code-block:: shell
python 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
python 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 (``mozilla-unified``) and type:
.. code-block:: shell
# create a minimal build options file
echo "ac_add_options --with-macos-sdk=$HOME/SDK-archive/MacOSX10.11.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 `artifact
builds <https://developer.mozilla.org/en-US/docs/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:: Getting Connected
:name: Getting_Connected
:class: heading-tertiary
That last step can take some time to finish. While it’s running, take a
moment to sign in to\ `Bugzilla <https://bugzilla.mozilla.org/>`,
Mozilla’s issue tracker. To comment on a bug or submit a patch you’ll
need a Bugzilla account. You can either use your `GitHub
account <https://github.com>`, or you can `sign up for a Bugzilla
account here. <https://bugzilla.mozilla.org/createaccount.cgi>`
As well as Bugzilla, much of Mozilla’s internal communication happens
over Internet Relay Chat (IRC). You can learn how to `connect to Mozilla
with IRC here <https://wiki.mozilla.org/IRC>`. If you’re just getting
started or have questions about getting set up you can join us in the
*"#introduction channel"*, where some of our community members hang out
to try and help new contributors get rolling.
.. rubric:: Join Mozillians.org!
:name: Join_Mozillians.org!
:class: heading-tertiary
There’s one more thing you can do for yourself while you’re waiting:
create an account for yourself on
`Mozillians <https://mozillians.org/>`. Mozillians is the Mozilla
community directory, where you can connect with people who share your
interests, projects or countries. This step is optional, but we think it
will be worth your while.
.. 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. The next steps are up
to you: join us on IRC in the *#introduction* channel, follow
`StartMozilla on Twitter <https://twitter.com/StartMozilla>` and find
a `bug to start working
on <http://www.joshmatthews.net/bugsahoy/?simple=1>`.
.. rubric:: Thank You
:name: Thank_You
:class: heading-tertiary
Mozilla's strength is the community behind it; Firefox is the product of
a global development team working to `keep the Web free, open and
participatory <https://www.mozilla.org/about/manifesto/>`, and your
contributions will make Firefox and the Web better for hundreds of
millions of people around the world.
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
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.
1.2 Get the local macOS SDK
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Firefox currently requires a local copy of macOS 10.11 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.11 SDK, first download Xcode 7.3.1 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.11.sdk $HOME/SDK-archive/MacOSX10.11.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.
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
You will also need Autoconf 2.13, but the core Homebrew repository will
install a newer version by default, so you need to specify the version
when installing it:
.. code-block:: shell
brew install autoconf@2.13
If you get errors trying to build, it means you have another version of
Autoconf installed and used as default. To use Autoconf 2.13, run:
.. code-block:: shell
brew link --overwrite autoconf@2.13
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:: eval
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:: eval
sudo port install libidl autoconf213 yasm
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:
#. Install `official builds from
Selenic <http://mercurial.selenic.com/>`
#. Install via MacPorts:
.. code-block:: shell
sudo port install mercurial
#. Install via Homebrew:
.. code-block:: shell
brew install mercurial
#. 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 `Getting Mozilla Source Code
Using Mercurial <https://developer.mozilla.org/en-US/Developer_Guide/Source_Code/Mercurial>`.
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 `Getting Mozilla Source Code Using
Mercurial <https://developer.mozilla.org/en-US/Developer_Guide/Source_Code/Mercurial>` 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:: syntaxbox
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 `Configuring
Build Options <https://developer.mozilla.org/en/Configuring_Build_Options>`.
To get started quickly, create the file with the following contents:
.. code:: eval
# 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.11.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 3.7 via Homebrew, then you need to have this in your
``mozconfig``:
.. code:: eval
CC=clang-mp-3.7
CXX=clang++-mp-3.7
If you installed Autoconf 2.13 with the Homebrew recipe linked above,
you may need to add the following to your ``mozconfig``:
.. code:: eval
mk_add_options AUTOCONF=/usr/local/Cellar/autoconf@2.13/2.13/bin/autoconf213
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 disks 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:** Mac OS X 10.9 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 from the App
Store.
- **Package Management:** Either
*`MacPorts <http://www.macports.org/>`* or Homebrew.
These options are specific to Mozilla builds for macOS. For a more
general overview of build options and the ``mozconfig`` file, see
`Configuring Build Options <https://developer.mozilla.org/en/Configuring_Build_Options>`. For
specific information on configuring to build a universal binary, see
`Mac OS X Universal Binaries <https://developer.mozilla.org/en/Mac_OS_X_Universal_Binaries>`.
- **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. The one in Xcode 7.0 or newer and the
open source 3.6 release should work.
(Xcode 6.4 is based on pre-release of clang 3.6, that doesn't
match to requirement.)
- 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``.
Mac macOS SDKs are installed in ``/Developer/SDKs`` during the `Xcode
installation <#Software_Requirements>` by selecting the **Cross
Development** category in the installer’s **Customize** screen.
.. code-block:: shell
ac_add_options --with-macos-sdk=/path/to/SDK
Official trunk builds use ``/Developer/SDKs/MacOSX10.11.sdk``. Check
```build/macosx/universal/mozconfig.common`` <https://dxr.mozilla.org/mozilla-central/source/build/macosx/cross-mozconfig.common#23>`
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 Mac 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``. [jgilbert] found this necessary during an
install for 10.9.
- **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.

477
docs/contributing/setup/windows_build.rst Normal file
View File

@ -0,0 +1,477 @@
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.
Visual Studio 2019
~~~~~~~~~~~~~~~~~~
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.
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.
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.
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 `get the source using
Mercurial <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Source_Code/Mercurial>`
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
hg clone https://hg.mozilla.org/mozilla-central
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-central
./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 Mercuial 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 `artifact
builds <https://developer.mozilla.org/en-US/docs/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.
Getting connected
~~~~~~~~~~~~~~~~~
That last step can take some time. While it’s finishing you should take
a moment to sign up for a Bugzilla account!
`Bugzilla.mozilla.org <https://bugzilla.mozilla.org/>` is Mozilla’s
issue tracker. To comment on a bug or submit a patch you’ll need a
Bugzilla account; you can use your GitHub account if you have one, or
`sign up for a Bugzilla account
directly. <https://bugzilla.mozilla.org/createaccount.cgi>`
As well as Bugzilla, much of Mozilla’s internal communication happens
over Internet Relay Chat (IRC). You can learn how to `connect to Mozilla
with IRC here <https://wiki.mozilla.org/IRC>`. If you’re just getting
started or have questions about getting set up you can join us in the
*"#introduction channel"*, where some of our community members hang out
to try and help new contributors get rolling.
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.
Now the fun starts
~~~~~~~~~~~~~~~~~~
You have the code and you’ve compiled Firefox. Just fire it up with
``./mach run`` and you’re ready to start hacking. The next steps are up
to you: join us on IRC in the “\ *#introduction* *channel*\ ”, follow
`StartMozilla on Twitter <https://twitter.com/StartMozilla>` and find
`a bug to start working
on <http://www.joshmatthews.net/bugsahoy/?simple=1>`.
Thank you for joining us and helping us make Firefox and the open Web
better for everyone.
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, autoconf, 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:
**Some antivirus and system protection software can dramatically slow or
break the build process**
- Windows Defender and some scanning antivirus products are known to
have a major impact on build times. For example, if you have cloned
``mozilla-central`` 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 whitelist your source and object
directories (the ``mozilla-source`` and ``mozilla-build``
directories) in Windows Defender or your antivirus software and if
you're 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
~~~~~~~~~~~~
The MozillaBuild package contains other software prerequisites necessary
for building Mozilla, including the MSYS build environment,
`Mercurial <https://www.mercurial-scm.org/>`, autoconf-2.13, 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.
**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
----------------------------------------
- `Debugging Firefox on Windows
FAQ <https://developer.mozilla.org/en-US/docs/Mozilla/Debugging/Debugging_Mozilla_on_Windows_FAQ>`:
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>`.
- 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-central`` being located
in the Users folder (possibly encrypted). Try moving it outside of
the Users folder. The docs recommend
``C:\mozilla-source\mozilla-central`` 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.

19
docs/index.rst
View File

@ -3,38 +3,43 @@ Firefox Source Tree Documentation
=================================
.. toctree::
:caption: Contributing
:caption: Getting Started
:maxdepth: 2
{setup_doc}
.. toctree::
:caption: Contributing To Firefox
:maxdepth: 2
{contributing_doc}
.. toctree::
:caption: Source code doc
:caption: Source Code Documentation
:maxdepth: 2
{source_doc}
.. toctree::
:caption: Build
:caption: The Firefox Build System
:maxdepth: 1
{build_doc}
.. toctree::
:caption: Testing
:caption: Testing & Test Infrastructure
:maxdepth: 1
{testing_doc}
.. toctree::
:caption: Localization
:caption: Localization & Internationalization
:maxdepth: 2
{l10n_doc}
.. toctree::
:caption: Python
:caption: Firefox and Python
:maxdepth: 1
{python_doc}