mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-24 13:21:05 +00:00
Bug 1179358 - Consolidation of documentation patches into MC r=sylvestre
Depends on D68835 Differential Revision: https://phabricator.services.mozilla.com/D76398
This commit is contained in:
mhoye
parent
57a1c6a1d8
commit
cb2f30a40e
@ -4,7 +4,7 @@
|
||||
# Sub categories orders are preserved
|
||||
categories:
|
||||
setup_doc:
|
||||
- contributing/setup
|
||||
- setup
|
||||
contributing_doc:
|
||||
- contributing
|
||||
- bug-mgmt
|
||||
@ -48,6 +48,7 @@ categories:
|
||||
|
||||
redirects:
|
||||
browser/browser: browser
|
||||
contributing/how_to_contribute_firefox.html: contributing/contribution_quickref.html
|
||||
contributing/artifact_builds.html: contributing/build/artifact_builds.html
|
||||
contributing/linux_build.html: contributing/build/linux_build.html
|
||||
contributing/mercurial.html: contributing/vcs/mercurial.html
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
Artifact builds
|
||||
===============
|
||||
Understanding Artifact Builds
|
||||
=============================
|
||||
|
||||
Firefox for Desktop and Android supports a **fast build mode** called
|
||||
*artifact mode*. The resulting builds are called *artifact builds*.
|
||||
|
||||
@ -1 +0,0 @@
|
||||
.. _linux-build-documentation:
|
||||
@ -1,6 +1,5 @@
|
||||
Contributing To Firefox - Quick Reference
|
||||
=========================================
|
||||
|
||||
Firefox Contributors' Quick Reference
|
||||
=====================================
|
||||
|
||||
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>`__
|
||||
@ -262,7 +261,8 @@ information <https://developer.mozilla.org/docs/Mozilla/Developer_guide/How_to_S
|
||||
Contributing to GeckoView
|
||||
-------------------------
|
||||
|
||||
GeckoView information and contribution docs live in `geckoview.dev <https://geckoview.dev>`__.
|
||||
Note that the GeckoView setup and contribution processes are different from those of Firefox;
|
||||
GeckoView setup and contribution docs live in `geckoview.dev <https://geckoview.dev>`__.
|
||||
|
||||
More documentation about contribution
|
||||
-------------------------------------
|
||||
@ -1,14 +1,14 @@
|
||||
Contributing to Firefox
|
||||
=======================
|
||||
Working on Firefox
|
||||
==================
|
||||
|
||||
This section has the details about how we make changes to Firefox, and how you can
|
||||
do the same.
|
||||
Welcome to the Firefox codebase. This is the home of the Firefox
|
||||
development process and source code documentation.
|
||||
|
||||
.. toctree::
|
||||
:caption: Making Changes To Firefox
|
||||
:maxdepth: 1
|
||||
|
||||
how_to_contribute_firefox
|
||||
contribution_quickref
|
||||
editor
|
||||
reviews
|
||||
|
||||
|
||||
@ -1,19 +0,0 @@
|
||||
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
|
||||
@ -4,12 +4,12 @@ Firefox Source Tree Documentation
|
||||
|
||||
.. toctree::
|
||||
:caption: Getting Started
|
||||
:maxdepth: 2
|
||||
:maxdepth: 1
|
||||
|
||||
{setup_doc}
|
||||
|
||||
.. toctree::
|
||||
:caption: Contributing To Firefox
|
||||
:caption: Working On Firefox
|
||||
:maxdepth: 2
|
||||
|
||||
{contributing_doc}
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
How to contribute to Firefox
|
||||
============================
|
||||
How To Contribute Code 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>`
|
||||
@ -189,7 +189,7 @@ 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
|
||||
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
|
||||
@ -62,15 +62,4 @@ 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!
|
||||
|
||||
Read on for information about how to set up your machine to build Firefox.
|
||||
21
docs/setup/index.rst
Normal file
21
docs/setup/index.rst
Normal file
@ -0,0 +1,21 @@
|
||||
Getting Set Up To Work On The Firefox Codebase
|
||||
==============================================
|
||||
|
||||
This page will help you get set up to build Firefox on your own machine.
|
||||
|
||||
.. toctree::
|
||||
:caption: Thank you for contributing to Firefox
|
||||
|
||||
getting_set_up
|
||||
|
||||
.. toctree::
|
||||
:caption: Setting Up Your Machine
|
||||
|
||||
windows_build
|
||||
macos_build
|
||||
linux_build
|
||||
|
||||
.. toctree::
|
||||
:caption: Getting Ready To Contribute
|
||||
|
||||
contributing_code
|
||||
@ -1,7 +1,7 @@
|
||||
Building Firefox On MacOS
|
||||
=========================
|
||||
|
||||
This document will help you get set up to build Firefox on your own
|
||||
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.
|
||||
@ -90,8 +90,8 @@ 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
|
||||
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
|
||||
@ -173,7 +173,7 @@ require you to sign in with an Apple ID:
|
||||
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`` )
|
||||
by running ``sudo xcode-select -switch /Applications/Xcode.app`` )
|
||||
- From the Mac App Store - `direct
|
||||
link <https://apps.apple.com/us/app/xcode>`.
|
||||
|
||||
@ -181,7 +181,7 @@ 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.
|
||||
running \ ``xcode-select --install`` in your terminal.
|
||||
|
||||
1.2 Get the local macOS SDK
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -240,8 +240,8 @@ when installing it:
|
||||
|
||||
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:
|
||||
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
|
||||
|
||||
@ -283,10 +283,10 @@ 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
|
||||
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
|
||||
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
|
||||
@ -361,9 +361,8 @@ couple hundred megabytes of data over the internet.
|
||||
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>`.)
|
||||
(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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -436,7 +435,7 @@ 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
|
||||
- **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.
|
||||
@ -30,40 +30,50 @@ 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.
|
||||
.. note::
|
||||
|
||||
As of `bug
|
||||
1483835 <https://bugzilla.mozilla.org/show_bug.cgi?id=1483835>`, local
|
||||
Windows builds `use clang-cl by
|
||||
default <https://groups.google.com/d/topic/mozilla.dev.platform/MdbLAcvHC0Y/discussion>`
|
||||
as compiler. Visual Studio is still necessary for build tools, headers,
|
||||
and SDK.
|
||||
|
||||
.. note::
|
||||
|
||||
Automation builds still use Visual Studio 2017, so there may be some
|
||||
divergence until we upgrade. `Bug
|
||||
1581930 <https://bugzilla.mozilla.org/show_bug.cgi?id=1581930>` tracks
|
||||
various issues building with 2019. Please file your issue there and
|
||||
downgrade in the interim if you encounter build failures.
|
||||
|
||||
`Download and install the Community
|
||||
edition <https://visualstudio.microsoft.com/downloads/>` of Visual
|
||||
Studio 2019. Professional and Enterprise are also supported if you have
|
||||
either of those editions.
|
||||
|
||||
When installing, the following workloads must be checked:
|
||||
.. note::
|
||||
|
||||
- "Desktop development with C++" (under the Windows group)
|
||||
- "Game development with C++" (under the Mobile & Gaming group)
|
||||
When installing, the following workloads must be checked:
|
||||
|
||||
In addition, go to the Individual Components tab and make sure the
|
||||
following components are selected under the "SDKs, libraries, and
|
||||
frameworks" group:
|
||||
- "Desktop development with C++" (under the Windows group)
|
||||
- "Game development with C++" (under the Mobile & Gaming 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)
|
||||
In addition, go to the Individual Components tab and make sure the
|
||||
following components are selected under the "SDKs, libraries, and
|
||||
frameworks" group:
|
||||
|
||||
- "Windows 10 SDK" (at least version **10.0.17134.0**)
|
||||
- "C++ ATL for v142 build tools (x86 and x64)" (also select ARM64
|
||||
if you'll be building for ARM64)
|
||||
|
||||
Make sure you run Visual Studio once after installing, so it finishes
|
||||
any first-run tasks and associates the installation with your account.
|
||||
|
||||
If you already have Visual Studio 2019 installed, you can get to the
|
||||
installer via its menu "Tools" → "Get Tools and Features".
|
||||
|
||||
Other Required Tools
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -136,8 +146,8 @@ 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
|
||||
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
|
||||
@ -221,7 +231,7 @@ Overview
|
||||
~~~~~~~~
|
||||
|
||||
The Mozilla build process requires many tools that are not pre-installed
|
||||
on most Windows systems. In addition to Visual Studio, install
|
||||
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.
|
||||
|
||||
@ -242,7 +252,7 @@ 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.
|
||||
#. 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
|
||||
@ -298,19 +308,19 @@ cause issues**
|
||||
|
||||
.. 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.
|
||||
**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,
|
||||
`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.
|
||||
|
||||
@ -321,29 +331,31 @@ 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
|
||||
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.
|
||||
.. note::
|
||||
|
||||
**MozillaBuild command prompt expectation setting:** Note that the
|
||||
"UNIX-like" environment provided by MozillaBuild is only really useful
|
||||
for building and committing to the Mozilla source. Most command line
|
||||
tools you would expect in a modern Linux distribution are not present,
|
||||
and those tools that are provided can be as much as a decade or so old
|
||||
(especially those provided by MSYS). It's the old tools in particular
|
||||
that can cause problems since they often don't behave as expected, are
|
||||
buggy, or don't support command line arguments that have been taken for
|
||||
granted for years. For example, copying a source tree using
|
||||
``cp -rf src1 src2`` does not work correctly because of an old version
|
||||
of cp (it gives "cp: will not create hard link" errors for some files).
|
||||
In short, MozillaBuild supports essential developer interactions with
|
||||
the Mozilla code, but beyond that don't be surprised if it trips you up
|
||||
in all sorts of exciting and unexpected ways.
|
||||
|
||||
Opening a MozillaBuild command prompt
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After the prerequisites are installed, launch
|
||||
the \ **``start-shell.bat``** batch file using the Windows command
|
||||
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
|
||||
@ -352,8 +364,8 @@ 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.
|
||||
Note: This is not the same as what you get with the Windows CMD.EXE
|
||||
shell.
|
||||
|
||||
Create a directory for the source
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -389,11 +401,11 @@ Command prompt tips and caveats
|
||||
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
|
||||
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 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.
|
||||
@ -437,7 +449,7 @@ Common problems, hints, and restrictions
|
||||
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
|
||||
- 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
|
||||
@ -460,7 +472,7 @@ Common problems, hints, and restrictions
|
||||
- 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
|
||||
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``,
|
||||
@ -470,8 +482,8 @@ Common problems, hints, and restrictions
|
||||
``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
|
||||
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
|
||||
PROGRA~2. If you got "access denied", try to restart your computer
|
||||
to safe mode and try again.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user