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