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 2020-05-25 07:26:51 +00:00
Родитель 57a1c6a1d8
Коммит cb2f30a40e
13 изменённых файлов: 119 добавлений и 117 удалений

Просмотреть файл

@ -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
Просмотреть файл

@ -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.
Youre on your way. Dont 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 well 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.
Youre on your way. Dont 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.