1.. -*- Mode: rst; fill-column: 80; -*-
2
3=============================
4GeckoView For Gecko Engineers
5=============================
6
7Table of contents
8=================
9
10.. contents:: :local:
11
12Introduction
13------------
14
15Who this guide is for: As the title suggests, the target audience of
16this guide is existing Gecko engineers who need to be able to build and
17(locally) test GeckoView. If you aren’t already familiar with building
18Firefox on a desktop platform, you’ll likely be better served by reading
19`our general introduction <geckoview-quick-start>`_. This guide may
20also be helpful if you find you’ve written a patch that requires
21changing GeckoView’s public API, see `Landing a
22Patch <#landing-a-patch>`_.
23
24Who this guide is not for: As mentioned above, if you are not already
25familiar with building Firefox for desktop, you’d likely be better
26served by our general bootstrapping guide. If you are looking to
27contribute to front-end development of one of Mozilla’s Android
28browsers, you’re likely better off starting with their codebase and
29returning here only if actual GeckoView changes are needed. See, for
30example, `Fenix’s GitHub <https://github.com/mozilla-mobile/fenix>`_.
31
32What to do if this guide contains bugs or leads you astray: The quickest
33way to get a response is to ask generally on #gv on Mozilla Slack;
34#mobile on Mozilla IRC may also work for the time being, albeit likely
35with slower response times. If you believe the guide needs updating, it
36would also be good to file a ticket to request that.
37
38Configuring the build system
39----------------------------
40
41First, a quick note: This guide was written on MacOS 10.14; it should
42translate quite closely to other supported versions of MacOS and to
43Linux. Building GeckoView on Windows is not officially supported at the
44moment. To begin with, re-run ``./mach bootstrap``; it will present you
45with options for the version of Firefox/GV that you want to build.
46Currently, option ``3`` is
47``GeckoView/Firefox for Android Artifact Mode`` and ``4`` is
48``GeckoView/Firefox for Android``; if you’re here, you want one of
49these. The brief and approximately correct breakdown of ``Artifact`` vs
50regular builds for GeckoView is that ``Artifact`` builds will not allow
51you to work on native code, only on JS or Java. Once you’ve selected
52your build type, ``bootstrap`` should do its usual thing and grab
53whatever dependencies are necessary. You may need to agree to some
54licenses along the way. Once ``bootstrap`` has successfully completed,
55it will spit out a recommended ``mozconfig``.
56
57Mozconfig and Building
58----------------------
59
60If you’ve followed from the previous section, ``./mach bootstrap``
61printed out a recommended ``mozconfig`` that looks something like this:
62
63::
64
65   # Build GeckoView/Firefox for Android:
66   ac_add_options --enable-application=mobile/android
67
68   # Targeting the following architecture.
69   # For regular phones, no --target is needed.
70   # For x86 emulators (and x86 devices, which are uncommon):
71   # ac_add_options --target=i686
72   # For newer phones.
73   # ac_add_options --target=aarch64
74   # For x86_64 emulators (and x86_64 devices, which are even less common):
75   # ac_add_options --target=x86_64
76
77As written, this defaults to building for a 32-bit ARM architecture,
78which is probably not what you want. If you intend to work on an actual
79device, you almost certainly want a 64-bit ARM build, as it is supported
80by virtually all modern ARM phones/tablets and is the only ARM build we
81ship on the Google Play Store. To go this route, uncomment the
82``ac_add_options --target=aarch64`` line in the ``mozconfig``. On the
83other hand, x86-64 emulated devices are widely used by the GeckoView
84team and are used extensively on ``try``; if you intend to use an
85emulator, uncomment the ``ac_add_options --target=x86_64`` line in the
86``mozconfig``. Don’t worry about installing an emulator at the moment,
87that will be covered shortly. It’s worth noting here that other
88``mozconfig`` options will generally work as you’d expect. Additionally,
89if you plan on debugging native code on Android, you should include the
90``mozconfig`` changes mentioned `in our native debugging guide <native-debugging.html>`_. Now, using
91that ``mozconfig`` with any modifications you’ve made, simply
92``./mach build``. If all goes well, you will have successfully built
93GeckoView.
94
95Installing, Running, and Using in Fenix/AC
96------------------------------------------
97
98An (x86-64) emulator is the most common and developer-friendly way of
99contributing to GeckoView in most cases. If you’re going to go this
100route, simply run ``./mach android-emulator`` — by default, this will
101install and launch an x86-64 Android emulator running the same Android
1027.0 image that is used on ``try``. If you need a different emulator
103image you can run ``./mach android-emulator --help`` for information on
104what Android images are available via ``mach``. You can also install an
105emulator image via Android Studio. In cases where an emulator may not
106suffice (eg graphics or performance testing), or if you’d simply prefer
107not to use an emulator, you can opt to use an actual phone instead. To
108do so, you’ll need to enable ``USB Debugging`` on your phone if you
109haven’t already. On most modern Android devices, you can do this by
110opening ``Settings``, going to ``About phone``, and tapping
111``Build number`` seven times. You should get a notification informing
112you that you’ve unlocked developer options. Now return to ``Settings``,
113go to ``Developer options``, and enable USB debugging.
114
115GeckoView Example App
116~~~~~~~~~~~~~~~~~~~~~
117
118Now that you’ve connected a phone or setup an emulator, the simplest way
119to test GeckoView is to launch the GeckoView Example app by running
120``./mach run`` (or install it with ``./mach install`` and run it
121yourself). This is a simplistic GV-based browser that lives in the tree;
122in many cases, it is sufficient to test and debug Gecko changes, and is
123by far the simplest way of doing so. It supports remote debugging by
124default — simply open Remote Debugging on your desktop browser and the
125connected device/emulator should show up when the example app is open.
126You can also use the example app for native debugging, follow the
127`native debugging guide <native-debugging.html>`_.
128
129GeckoView JUnit Tests
130~~~~~~~~~~~~~~~~~~~~~
131
132Once you’ve successfully built GV, you can run tests from the GeckoView
133JUnit test suite with ``./mach geckoview-junit``. For further examples
134(eg running individual tests, repeating tests, etc.), consult the `quick
135start guide <geckoview-quick-start.html#running-tests-locally>`_.
136
137Fenix and other GV-based Apps
138~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
139
140If you are working on something for which the GeckoView Example app is
141not sufficient for some reason, you may need to `use your local build of
142GeckoView in one of Mozilla’s GV-based apps like Fenix <geckoview-quick-start.html#include-geckoview-as-a-dependency>`_.
143
144Debugging
145---------
146
147Remote Debugging
148~~~~~~~~~~~~~~~~
149
150To recap a bit of the above, in the GeckoView Example app, remote
151debugging is enabled by default, and your device should show up in your
152desktop browser’s Remote Debugging window with no special effort. For
153Fenix, you can enable remote debugging by opening the three-dot menu and
154toggling ``Remote debugging via USB`` under ``Developer tools``; other
155Mozilla GV-based browsers have similar options.
156
157Native Debugging
158~~~~~~~~~~~~~~~~
159
160To perform native debugging on any GV app will require you to install
161Android Studio and follow instructions `here <native-debugging.html>`_.
162
163Landing a Patch
164---------------
165
166In most cases, there shouldn’t be anything out of the ordinary to deal
167with when landing a patch that affects GeckoView; make sure you include
168Android in your ``try`` runs and you should be good. However, if you
169need to alter the GeckoView public API in any way — essentially anything
170that’s exposed as ``public`` in GeckoView Java files — then you’ll find
171that you need to run the API linter and update the change log. To do
172this, first run ``./mach lint --linter android-api-lint`` — if you have
173indeed changed the public API, this will give you a ``gradle`` command
174to run that will give further instructions. GeckoView API changes
175require two reviews from GeckoView team members; you can open it up to
176the team in general by adding ``#geckoview-reviewers`` as a reviewer on
177Phabricator.
178