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
209
210
|
Pushing to Try
==============
"Pushing to Try" allows developers to build and test their changes on Mozilla's automation servers
without requiring their code to be reviewed and landed.
First, :doc:`ensure that you can push to Try <configuration>`.
Try knows how to run tasks that are defined in-tree,
such as ``build-linux64/opt`` (build Firefox for Linux). To manually select some tasks for
Try to process, run the following command:
.. code-block:: shell
./mach try fuzzy
After submitting your requested tasks, you'll be given a link to your "push" in Treeherder.
It may take a few minutes for your push to appear in Treeherder! Be patient, and it will automatically
update when Try begins processing your work.
Another very useful Try command is ``./mach try auto``, which will automatically select the tasks
that are mostly likely to be affected by your changes.
See the :doc:`selectors page <selectors/index>` to view all the other ways to select which tasks to push.
It is possible to set environment variables, notably :doc:`MOZ_LOG </xpcom/logging>`, when pushing to
try:
.. code-block:: shell
./mach try fuzzy --env MOZ_LOG=cubeb:4
On macOS and Linux Desktop, it is also possible to get a screen recording of the test run:
.. code-block:: shell
./mach try fuzzy --env MOZ_RECORD_TEST=1
The screen recording will be in the ``Artifacts and Debugging Tools`` section on Treeherder.
Pushing via Lando (default behaviour)
-------------------------------------
By default, ``mach try`` uses Lando to push your commits to Try. This is the same
behaviour that was previously accessed with ``--push-to-lando``.
**Prerequisites (local setup)**
- Your local Git repo must have the official Firefox repository configured as a remote.
You can verify this with:
.. code-block:: shell
git remote -v
Commonly the official remote is named ``origin``. You can add the remote with:
.. code-block:: shell
git remote add origin https://github.com/mozilla-firefox/firefox
- You must have remote branch references from the official Firefox repo in your local Git repo
(for example, ``origin/autoland``). If those are missing, fetch them:
.. code-block:: shell
git fetch origin
git branch -r | grep origin/
- You need an account on Mozilla's Auth0 instance in order to authenticate when submitting via Lando.
How Pushing via Lando Works (high level)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. ``mach try`` scans your Git remotes (via ``git remote -v``) to identify the official Firefox
repository remote.
2. It finds the first commit in the history from your current ``HEAD`` that is also present on that
remote. This commit is used as the **base commit**.
3. All commits from the base commit (exclusive) up to ``HEAD`` are exported in ``git format-patch``
format.
4. You authenticate in your browser through Auth0 to obtain a token that authorizes requests to Lando.
5. ``mach try`` sends the base commit and the patch series to Lando using that token.
6. On the Lando side:
- Lando converts the submitted Git base commit to the corresponding Mercurial SHA in
``mozilla-unified``.
- Lando applies the submitted patches starting from that base commit.
- Lando pushes the resulting changes to ``hg.mozilla.org/try`` so they appear in Treeherder.
Pushing directly to VCS
-----------------------
In some cases, you may want to bypass Lando and push directly to ``hg.mozilla.org/try``.
This is done with the ``--push-to-vcs`` flag:
.. code-block:: shell
./mach try auto --push-to-vcs
Requirements for using ``--push-to-vcs``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- You must be using Mercurial directly, or a Git checkout created with
`git-cinnabar <https://github.com/glandium/git-cinnabar>`_.
- Your local repo must already be able to push directly to ``hg.mozilla.org``.
- Unlike the default Lando-based workflow, no Auth0 authentication is used. Instead,
your SSH credentials are used to push.
This option is generally only recommended for developers who are comfortable working directly
with Mercurial or git-cinnabar.
Resolving "<Try build> is damaged and can't be opened" error
------------------------------------------------------------
To run a try build on macOS, you need to get around Apple's restrictions on downloaded applications.
These restrictions differ based on your hardware: Apple Silicon machines (M1 etc.) are much stricter.
For Apple Silicon machines, you will need to download the target.dmg artifact from the
"repackage-macosx64-shippable/opt" job.
This is a universal build (i.e. it contains both x86_64 and arm64 code), and it is signed but not notarized.
You can trigger this job using ``./mach try fuzzy --full``.
On Intel Macs, you can run unsigned builds, once you get around the quarantining (see below),
so you can just download the "target.dmg" from a regular opt build.
Regardless of hardware, you need to make sure that there is no quarantining attribute on
the downloaded dmg file before you attempt to run it:
Apple automatically quarantines apps that are downloaded with a browser from an untrusted
location. This "quarantine status" can be cleared by doing ``xattr -c <Try build>`` after
downloading. You can avoid this "quarantine status" by downloading the build from the command
line instead, such as by using ``curl``:
.. code-block:: shell
curl -L <artifact-url> -o <file-name>
.. _attach-job-review:
Profiler symbols for try builds
-------------------------------
When `profiling a tryserver build </testing/debugging-intermittents/index.html#use-the-firefox-profiler>`__,
symbols are only available by default for artifact builds. With full
(non-artifact) builds, you don't get symbols by default. You have to trigger an
additional `upload-symbols` job on your try push so that the symbols are
available on the symbol server.
You can trigger this job manually in the Treeherder UI, using "Add new jobs (Search)...".
Assuming you want to profile a "shippable" build (recommended), follow these steps:
1. On the treeherder push, click the dropdown triangle in the top right corner.
2. Select "Add new jobs (Search)..."
3. Enter "shippable sym" in the search box and press enter.
4. Important: Check the "Use full job list" checkbox.
5. Pick the job for your try build. For Windows 64 bit builds, the job name is ``build-win64-shippable/opt-upload-symbols`` (this was written in February 2024).
6. Click "Add selected", scroll down, and click "Trigger (1) Selected Jobs".
Around ten minutes later, the symbols will be available on the symbol server, and profile symbolication will succeed.
For other build types, choose the corresponding job for your build type. The job names all
end in ``-upload-symbols``, and share a prefix with the build job.
.. image:: img/treeherder-trigger-symbols.png
If you've already captured a profile from a try build before the symbols were available, you can
fix up the collected profile once the symbols are available. To do so, in the Firefox Profiler UI,
click the "Profile Info" button in the top right corner, and then click the "Re-symbolicate profile"
button in the panel.
If you want to trigger the upload-symbol job when pushing to try, you can pick it in the list
when running ``./mach try fuzzy --full`` - the ``--full`` part is necessary.
The ``-upload-symbols`` task has a dependency on the build task, so you don't have to trigger
the build task separately if you do this.
Adding Try jobs to a Phabricator patch
--------------------------------------
For every patch submitted for review in Phabricator, a new Try run is automatically created.
A link called ``Treeherder Jobs`` can be found in the ``Diff Detail`` section of the review in
Phabricator.
.. image:: img/phab-treeherder-link.png
This run is created for static analysis, linting and other tasks. Attaching new jobs to the run is
easy and doesn't require more actions from the developer.
Click on the down-arrow to access the actions menu, select the relevant jobs
and, click on ``Trigger X new jobs`` (located on the top of the job).
.. image:: img/add-new-jobs.png
Table of Contents
-----------------
.. toctree::
:maxdepth: 2
configuration
selectors/index
presets
tasks
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
|
