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