1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
Mercurial Overview
==================
Mercurial is a source-code management tool which allows users to keep track of changes to the source code locally and share their changes with others.
We use it for the development of Firefox.
Installation
------------
See `Mercurial Page <https://www.mercurial-scm.org/downloads>`__ for installation.
Using `hg clone`
----------------
If you are not worried about network interruptions, then you can simply
use Mercurial to directly clone the repository you're interested in
using its URL, as given below. For example, to use the command line to
clone ``mozilla-central`` into a directory called ``firefox-source``,
you would use the following:
.. code-block:: shell
hg clone https://hg.mozilla.org/mozilla-central/ firefox-source
cd firefox-source
Using Mercurial bundles
-----------------------
If you are worried that your Internet connection is not fast or robust
enough to download such a large amount of data all in one go without
being interrupted and cannot clone using the command given above, then you are recommended to try :ref:`Mercurial bundles <Mercurial bundles>`. If interrupted, they can be resumed (continued without downloading
from the beginning) if the app you're using to download supports it. For
example, in Firefox you would right click on the download and select
`Resume` once your connection to the Internet was reestablished.
Basic configuration
-------------------
You should configure Mercurial before submitting patches to Mozilla.
If you will be pulling the Firefox source code or one of the derived repositories, the easiest way to configure Mercurial is to run the vcs-setup mach command:
.. code-block:: shell
$ ./mach vcs-setup
This command starts an interactive wizard that will help ensure your Mercurial is configured with the latest recommended settings. This command will not change any files on your machine without your consent.
Other configuration tips
------------------------
If you don't have the Firefox source code available, you should edit your Mercurial configuration file to look like the following:
.. code-block:: shell
[ui]
username = Your Real Name <user@example.com>
merge = your-merge-program (or internal:merge)
[diff]
git = 1
showfunc = 1
unified = 8
[defaults]
commit = -v
On Windows, these settings can be added to `$HOME\.hgrc` or `$HOME\Mercurial.ini`, or, if you'd like global settings, `C:\mozilla-build\hg\Mercurial.ini`
or `C:\Program Files\Mercurial\Mercurial.ini.` On UNIX-like systems, they should be in your `$HOME/.hgrc` file.
You can configure the editor to use for commit messages using the `editor` option in the `[ui]` section or by setting the `EDITOR` environment variable.
If you are trying to access the repository through a proxy server, see `these
instructions <http://www.selenic.com/mercurial/hgrc.5.html#http-proxy>`__
Selecting a repository (tree)
-----------------------------
There are multiple hg repositories hosted at mozilla.org to choose from.
A summary of the main trees is given below, but see
https://hg.mozilla.org/ for the full list.
mozilla-central
---------------
This is the main development tree for Firefox. Most developers write
patches against mozilla-central.
URL: https://hg.mozilla.org/mozilla-central/
mozilla-beta
------------
The source for the current beta version of Firefox (and the next and all
previous betas). This code represents the expected next release of the
Firefox browser, and should be pretty stable.
URL: https://hg.mozilla.org/releases/mozilla-beta/
mozilla-release
---------------
The source for the current release of Firefox (and the next and all
previous releases).
URL: https://hg.mozilla.org/releases/mozilla-release/
autoland
--------
This is the integration tree for Firefox. Patches land in this repository first,
and then are merged by the sheriffs in mozilla-central.
URL: https://hg.mozilla.org/integration/autoland/
L10n repos
----------
Mainly useful for localizers working on localizing Firefox. Code for all
l10n projects lives here and is organized into separate repos that (in
most cases) have the locale's two character ISO code. To get the repo
that you need look for the repo you're interested in on the following
page.
URL: https://hg.mozilla.org/l10n-central/
Unified Repositories
--------------------
It is common for advanced users to want to interact with more than one
firefox repository. If you get to the point where having individual
copies of repositories is annoying you, then see
https://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/unifiedrepo.html
for instructions on doing this efficiently.
Selecting a revision to build
-----------------------------
Most of the time the `tip` revision of most repositories will build
without issue. If you are worried about it not, then you may want to
`get the latest revision that has passed the automatic
tests <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Source_Code/LatestPassingSource>`__.
Building
--------
By default with no configuration a similar-to-release build is done. If
you wish you can :ref:`configure <Configuring Build Options>` the build using a ``.mozconfig`` file
and ``mach build``.
Different OSs have different prerequisites for a successful build,
please refer to the :ref:`build documentation <Getting Set Up To Work On The Firefox Codebase>`
to verify they are available on your build machine.
Extensions
----------
There's a number of extensions you can enable. See http://mercurial.selenic.com/wiki/UsingExtensions. Almost everyone should probably enable the following, most of them are enabled by ``mach boostrap``:
#. color - Colorize terminal output
#. histedit - Provides git rebase --interactive behavior.
#. progress - Draw progress bars on long-running operations.
#. rebase - Ability to easily rebase patches on top of other heads.
#. evolve - Enable and enhance the inprogress ChangesetEvolution work.
#. firefoxtree - Enhances the interaction with Firefox repositories.
#. transplant - Easily move patches between repositories, branches, etc.
These can all be turned on by just adding this to your `.hgrc` file:
.. code-block:: shell
[extensions]
color =
rebase =
histedit =
progress =
firefoxtree =
evolve =
transplant =
In addition, there are some 3rd party extensions that are incredibly
useful for basic development:
`mozext <https://hg.mozilla.org/hgcustom/version-control-tools/file/default/hgext/mozext>`__
Mozilla-specific functionality to aid in developing Firefox/Gecko.
`trychooser <https://github.com/pbiggar/trychooser>`__
Automatically creates a try commit message and then pushes changes to
Mozilla's Try infrastructure. Just run:
.. code-block:: shell
hg trychooser
Configuring the try repository
------------------------------
About `Try Server <Try Server>`__.
Learning to use Mercurial
-------------------------
If you are new to Mercurial, you should start with the `official guide <https://www.mercurial-scm.org/guide>`__.
Then, move on to the `version control tool docs <https://mozilla-version-control-tools.readthedocs.io/en/latest/hgmozilla/>`__ for Mozilla-centric Mercurial information.
|
