diff options
Diffstat (limited to 'mobile/android/docs/geckoview/contributor')
6 files changed, 1199 insertions, 0 deletions
diff --git a/mobile/android/docs/geckoview/contributor/contributing-to-mc.rst b/mobile/android/docs/geckoview/contributor/contributing-to-mc.rst new file mode 100644 index 0000000000..341a23c72b --- /dev/null +++ b/mobile/android/docs/geckoview/contributor/contributing-to-mc.rst @@ -0,0 +1,241 @@ +.. -*- Mode: rst; fill-column: 80; -*- + +================================= +Mozilla Central Contributor Guide +================================= + +Table of contents +================= + +.. contents:: :local: + +Submitting a patch to Firefox using Git. +======================================== + +This guide will take you through submitting and updating a patch to +``mozilla-central`` as a git user. You need to already be `set up to use +git to contribute to mozilla-central <mc-quick-start.html>`_. + +Performing a bug fix +-------------------- + +All of the open bugs for issues in Firefox can be found in +`Bugzilla <https://bugzilla.mozilla.org>`_. If you know the component +that you wish to contribute to you can use Bugzilla to search for issues +in that project. If you are unsure which component you are interested +in, you can search the `Good First +Bugs <https://bugzilla.mozilla.org/buglist.cgi?quicksearch=good-first-bug>`_ +list to find something you want to work on. + +- Once you have your bug, assign it to yourself in Bugzilla. +- Update your local copy of the firefox codebase to match the current + version on the servers to ensure you are working with the most up to + date code. + +.. code:: bash + + git remote update + +- Create a new feature branch tracking either Central or Inbound. + +.. code:: bash + + git checkout -b bugxxxxxxx [inbound|central]/default + +- Work on your bug, checking into git according to your preferred + workflow. *Try to ensure that each individual commit compiles and + passes all of the tests for your component. This will make it easier + to land if you use ``moz-phab`` to submit (details later in this + post).* + +It may be helpful to have Mozilla commit access, at least level 1. There +are three levels of commit access that give increasing levels of access +to the repositories. + +Level 1: Try/User access. You will need this level of access commit to +the try server. + +Level 2: General access. This will give you full commit +access to any mercurial or SVN repository not requiring level 3 access. + +Level 3: Core access. You will need this level to commit directly to any +of the core repositories (Firefox/Thunderbird/Fennec). + +If you wish to apply for commit access, please follow the guide found in +the `Mozilla Commit Access +Policy <https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/>`_. + +Submitting a patch that touches C/C++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your patch makes changes to any C or C++ code and your editor does +not have ``clang-format`` support, you should run the clang-format +linter before submitting your patch to ensure that your code is properly +formatted. + +.. code:: bash + + mach clang-format -p path/to/file.cpp + +Note that ``./mach bootstrap`` will offer to set up a commit hook that +will automatically do this for you. + +Submitting to ``try`` with Level 1 commit access. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you only have Level 1 access, you will still need to submit your +patch through phabricator, but you can test it on the try server first. + +- Use ``./mach try fuzzy`` to select jobs to run and push to try. + +Submitting a patch via Phabricator. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To commit anything to the repository, you will need to set up Arcanist +and Phabricator. If you are using ``git-cinnabar`` then you will need to +use git enabled versions of these tools. + +Install Arcanist (Github version) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Ensure PHP is installed +- `Install + Arcanist <https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/>`_ + +Set up Phabricator +^^^^^^^^^^^^^^^^^^ + +- In a browser, visit Mozilla’s Phabricator instance at + https://phabricator.services.mozilla.com/. + +- Click “Log In” at the top of the page + + .. figure:: ../assets/LogInPhab.png + :alt: Log in to Phabricator + + alt text + +- Click the “Log In or Register” button on the next page. This will + take you to Bugzilla to log in or register a new account. + + .. figure:: ../assets/LogInOrRegister.png + :alt: Log in or register a Phabiricator account + + alt text + +- Sign in with your Bugzilla credentials, or create a new account. + + .. figure:: ../assets/LogInBugzilla.png + :alt: Log in with Bugzilla + + alt text + +- You will be redirected back to Phabricator, where you will have to + create a new Phabricator account. + + .. raw:: html + + <Screenshot Needed> + +- Fill in/amend any fields on the form and click “Register Account”. + + .. raw:: html + + <Screenshot Needed> + +- You now have a Phabricator account and can submit and review patches. + +Using Arcanist to submit a patch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Ensure you are on the branch where you have commits that you want to + submit. + +.. code:: bash + + git checkout "your-branch-with-commits" + +- Create a differential patch containing your commits + +.. code:: bash + + arc diff + +- If you have any uncommitted files, Arcanist will ask if you want to + commit them. +- If you have any files in the path not added to git Arcanist will ask + if you want to ignore them. +- After formatting your patch, Arcanist will open a nano/emacs file for + you to enter the commit details. If you have many individual git + commits in your arcanist diff then the first line of the first commit + message will become the patch title, and the rest of the commit, plus + the messages for the other commits in the patch will form the + summary. +- Ensure you have entered the bug number against the ``Bug #`` field. +- If you know who you want to review your patch, put their Phabricator + handle against the ``reviewers`` field. If in doubt, look to see who + filed, or is listed as a mentor on, the bug you are addressing and + choose them. +- Close the editor (Ctrl X) to save the patch. +- Arcanist now formats your patch and submits it to Phabricator. It + will display the Phabricator link in the output. +- Copy that link and paste it into a browser window to view your patch. + +You may have noticed when using Arcanist that it wraps all of your +carefully curated Github commits into a single patch. If you have made +many commits that are self contained and pass all the tests then you may +wish to submit a patch for each commit. This will make it easier to +review. The way to do this is via ``moz-phab``. ``moz-phab`` required +Arcanist so you do have to have that installed first. + +Installing ``moz-phab`` +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: bash + + pip install MozPhab [--user] + +Submitting a patch using ``moz-phab``. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Ensure you are on the branch where you have commits that you want to + submit. + +.. code:: bash + + git checkout your-branch + +- Check the revision numbers for the commits you want to submit + +.. code:: bash + + git log + +- Run ``moz-phab``. Specifying a start commit will submit all commits + from that commit. Specifying an end commit will submit all commits up + to that commit. If no positional arguments are provided, the range is + determined to be starting with the first non-public, non-obsolete + changeset (for Mercurial) and ending with the currently checked-out + changeset. + +.. code:: bash + + moz-phab submit [start_rev] [end_rev] + +- You will receive a Phabricator link for each commit in the set. + +Updating a patch +~~~~~~~~~~~~~~~~ + +- Often you will need to make amendments to a patch after it has been + submitted to address review comments. To do this, add your commits to + the base branch of your fix as normal. + +To submit the update using Arcanist, run +``arc diff --update <PhabricatorDifferentialNumber>``. + +For ``moz-phab`` run in the same way as the initial submission with the +same arguments, that is, specifying the full original range of commits. +Note that, while inserting and amending commits should work fine, +reordering commits is not yet supported, and deleting commits will leave +the associated revisions open, which should be abandoned manually diff --git a/mobile/android/docs/geckoview/contributor/for-gecko-engineers.rst b/mobile/android/docs/geckoview/contributor/for-gecko-engineers.rst new file mode 100644 index 0000000000..2a406d83ff --- /dev/null +++ b/mobile/android/docs/geckoview/contributor/for-gecko-engineers.rst @@ -0,0 +1,177 @@ +.. -*- Mode: rst; fill-column: 80; -*- + +============================= +GeckoView For Gecko Engineers +============================= + +Table of contents +================= + +.. contents:: :local: + +Introduction +------------ + +Who this guide is for: As the title suggests, the target audience of +this guide is existing Gecko engineers who need to be able to build and +(locally) test GeckoView. If you aren’t already familiar with building +Firefox on a desktop platform, you’ll likely be better served by reading +`our general introduction <geckoview-quick-start>`_. This guide may +also be helpful if you find you’ve written a patch that requires +changing GeckoView’s public API, see `Landing a +Patch <#landing-a-patch>`_. + +Who this guide is not for: As mentioned above, if you are not already +familiar with building Firefox for desktop, you’d likely be better +served by our general bootstrapping guide. If you are looking to +contribute to front-end development of one of Mozilla’s Android +browsers, you’re likely better off starting with their codebase and +returning here only if actual GeckoView changes are needed. See, for +example, `Fenix’s GitHub <https://github.com/mozilla-mobile/fenix>`_. + +What to do if this guide contains bugs or leads you astray: The quickest +way to get a response is to ask generally on #gv on Mozilla Slack; +#mobile on Mozilla IRC may also work for the time being, albeit likely +with slower response times. If you believe the guide needs updating, it +would also be good to file a ticket to request that. + +Configuring the build system +---------------------------- + +First, a quick note: This guide was written on MacOS 10.14; it should +translate quite closely to other supported versions of MacOS and to +Linux. Building GeckoView on Windows is not officially supported at the +moment. To begin with, re-run ``./mach bootstrap``; it will present you +with options for the version of Firefox/GV that you want to build. +Currently, option ``3`` is +``GeckoView/Firefox for Android Artifact Mode`` and ``4`` is +``GeckoView/Firefox for Android``; if you’re here, you want one of +these. The brief and approximately correct breakdown of ``Artifact`` vs +regular builds for GeckoView is that ``Artifact`` builds will not allow +you to work on native code, only on JS or Java. Once you’ve selected +your build type, ``bootstrap`` should do its usual thing and grab +whatever dependencies are necessary. You may need to agree to some +licenses along the way. Once ``bootstrap`` has successfully completed, +it will spit out a recommended ``mozconfig``. + +Mozconfig and Building +---------------------- + +If you’ve followed from the previous section, ``./mach bootstrap`` +printed out a recommended ``mozconfig`` that looks something like this: + +:: + + # Build GeckoView/Firefox for Android: + ac_add_options --enable-application=mobile/android + + # Targeting the following architecture. + # For regular phones, no --target is needed. + # For x86 emulators (and x86 devices, which are uncommon): + # ac_add_options --target=i686 + # For newer phones. + # ac_add_options --target=aarch64 + # For x86_64 emulators (and x86_64 devices, which are even less common): + # ac_add_options --target=x86_64 + +As written, this defaults to building for a 32-bit ARM architecture, +which is probably not what you want. If you intend to work on an actual +device, you almost certainly want a 64-bit ARM build, as it is supported +by virtually all modern ARM phones/tablets and is the only ARM build we +ship on the Google Play Store. To go this route, uncomment the +``ac_add_options --target=aarch64`` line in the ``mozconfig``. On the +other hand, x86-64 emulated devices are widely used by the GeckoView +team and are used extensively on ``try``; if you intend to use an +emulator, uncomment the ``ac_add_options --target=x86_64`` line in the +``mozconfig``. Don’t worry about installing an emulator at the moment, +that will be covered shortly. It’s worth noting here that other +``mozconfig`` options will generally work as you’d expect. Additionally, +if you plan on debugging native code on Android, you should include the +``mozconfig`` changes mentioned `in our native debugging guide <native-debugging.html>`_. Now, using +that ``mozconfig`` with any modifications you’ve made, simply +``./mach build``. If all goes well, you will have successfully built +GeckoView. + +Installing, Running, and Using in Fenix/AC +------------------------------------------ + +An (x86-64) emulator is the most common and developer-friendly way of +contributing to GeckoView in most cases. If you’re going to go this +route, simply run ``./mach android-emulator`` — by default, this will +install and launch an x86-64 Android emulator running the same Android +7.0 image that is used on ``try``. If you need a different emulator +image you can run ``./mach android-emulator --help`` for information on +what Android images are available via ``mach``. You can also install an +emulator image via Android Studio. In cases where an emulator may not +suffice (eg graphics or performance testing), or if you’d simply prefer +not to use an emulator, you can opt to use an actual phone instead. To +do so, you’ll need to enable ``USB Debugging`` on your phone if you +haven’t already. On most modern Android devices, you can do this by +opening ``Settings``, going to ``About phone``, and tapping +``Build number`` seven times. You should get a notification informing +you that you’ve unlocked developer options. Now return to ``Settings``, +go to ``Developer options``, and enable USB debugging. + +GeckoView Example App +~~~~~~~~~~~~~~~~~~~~~ + +Now that you’ve connected a phone or setup an emulator, the simplest way +to test GeckoView is to launch the GeckoView Example app by running +``./mach run`` (or install it with ``./mach install`` and run it +yourself). This is a simplistic GV-based browser that lives in the tree; +in many cases, it is sufficient to test and debug Gecko changes, and is +by far the simplest way of doing so. It supports remote debugging by +default — simply open Remote Debugging on your desktop browser and the +connected device/emulator should show up when the example app is open. +You can also use the example app for native debugging, follow the +`native debugging guide <native-debugging.html>`_. + +GeckoView JUnit Tests +~~~~~~~~~~~~~~~~~~~~~ + +Once you’ve successfully built GV, you can run tests from the GeckoView +JUnit test suite with ``./mach geckoview-junit``. For further examples +(eg running individual tests, repeating tests, etc.), consult the `quick +start guide <geckoview-quick-start.html#running-tests-locally>`_. + +Fenix and other GV-based Apps +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are working on something for which the GeckoView Example app is +not sufficient for some reason, you may need to `use your local build of +GeckoView in one of Mozilla’s GV-based apps like Fenix <geckoview-quick-start.html#include-geckoview-as-a-dependency>`_. + +Debugging +--------- + +Remote Debugging +~~~~~~~~~~~~~~~~ + +To recap a bit of the above, in the GeckoView Example app, remote +debugging is enabled by default, and your device should show up in your +desktop browser’s Remote Debugging window with no special effort. For +Fenix, you can enable remote debugging by opening the three-dot menu and +toggling ``Remote debugging via USB`` under ``Developer tools``; other +Mozilla GV-based browsers have similar options. + +Native Debugging +~~~~~~~~~~~~~~~~ + +To perform native debugging on any GV app will require you to install +Android Studio and follow instructions `here <native-debugging.html>`_. + +Landing a Patch +--------------- + +In most cases, there shouldn’t be anything out of the ordinary to deal +with when landing a patch that affects GeckoView; make sure you include +Android in your ``try`` runs and you should be good. However, if you +need to alter the GeckoView public API in any way — essentially anything +that’s exposed as ``public`` in GeckoView Java files — then you’ll find +that you need to run the API linter and update the change log. To do +this, first run ``./mach lint --linter android-api-lint`` — if you have +indeed changed the public API, this will give you a ``gradle`` command +to run that will give further instructions. GeckoView API changes +require two reviews from GeckoView team members; you can open it up to +the team in general by adding ``#geckoview-reviewers`` as a reviewer on +Phabricator. diff --git a/mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst b/mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst new file mode 100644 index 0000000000..3e4af1ffc4 --- /dev/null +++ b/mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst @@ -0,0 +1,317 @@ +.. -*- Mode: rst; fill-column: 80; -*- + +=========================== +GeckoView Contributor Guide +=========================== + +Table of contents +================= + +.. contents:: :local: + +GeckoView Contributor Quick Start Guide +======================================= + +This is a guide for developers who want to contribute to the GeckoView +project. If you want to get started using GeckoView in your app then you +should refer to the +`wiki <https://wiki.mozilla.org/Mobile/GeckoView#Get_Started>`_. + +Get set up with Mozilla Central +------------------------------- + +The GeckoView codebase is part of the main Firefox tree and can be found +in ``mozilla-central``. You will need to get set up as a contributor to +Firefox in order to contribute to GeckoView. To get set up with +``mozilla-central``, follow the `Quick Start Guide for Git +Users <mc-quick-start.html>`_, or the `Contributing to the Mozilla code +base <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Introduction>`_ +guide on `MDN <https://developer.mozilla.org/>`_ for Mercurial users. + +Once you have a copy of ``mozilla-central``, you will need to build +GeckoView. + +Bootstrap Gecko +--------------- + +Bootstrap configures everything for GeckoView and Fennec (Firefox for Android) development. + +- Ensure you have ``mozilla-central`` checked out. If this is the first + time you are doing this, it may take some time. + +.. code:: bash + + git checkout central/default + +If you are on Windows, you will need to install the +`Java 1.8 SDK <https://adoptopenjdk.net/?variant=openjdk8>`__. + +If you are on a mac, you will need to have the Xcode build tools +installed. You can do this by either `installing +Xcode <https://developer.apple.com/xcode/>`__ or installing only the +tools from the command line by running ``xcode-select --install`` and +following the on screen instructions. Use the ``--no-interactive`` +argument to automatically accept any license agreements. + +.. code:: bash + + ./mach bootstrap [ --no-interactive] + +- Choose option \`4. Firefox for Android\` for GeckoView development. + This will give you a version of Gecko configured for Android that has + not bundled the native code into embedded libraries so you can amend + the code. +- Say Y to all configuration options +- Once ``mach bootstrap`` is complete, it will automatically write + the configuration into a new ``mozconfig`` file. If you already + have a ``mozconfig``, ``mach`` will instead output new configuration + that you should append to your existing file. + +Build from the command line +--------------------------- + +In order to pick up the configuration changes we just made we need to +build from the command line. This will update generated sources, compile +native code, and produce GeckoView AARs and example and test APKs. + +.. code:: bash + + ./mach build + +Build Using Android Studio +-------------------------- + +- Install `Android + Studio <https://developer.android.com/studio/install>`_. +- Disable Instant Run. This is because Fennec and the Geckoview Example + app cannot deploy with Instant Run on. + + - Select Android Studio > Preferences from the menu bar + - Navigate to Build, Execution, Deployment > Instant Run. + - Uncheck the box that reads + ``Enable Instant Run to hot swap code/resource changes on deploy``. + + |alt text| +- Choose File->Open from the toolbar +- Navigate to the root of your ``mozilla-central`` source directory and + click “Open” +- Click yes if it asks if you want to use the gradle wrapper. + + - If the gradle sync does not automatically start, select File > + Sync Project with Gradle Files. + +- Wait for the project to index and gradle to sync. Once synced, the + workspace will reconfigure to display the different projects. + + - annotations contains custom annotations used inside GeckoView and + Fennec. + - app is Fennec - Firefox for Android. Here is where you will find + code specific to that app. + - geckoview is the GeckoView project. Here is all the Java files + related to GeckoView + - geckoview_example is an example browser built using GeckoView. + - omnijar contains the parts of Gecko and GeckoView that are not + written in Java or Kotlin + - thirdparty contains third party code that Fennec and GeckoView + use. + + |alt text 1| + +Now you’re set up and ready to go. + +**Important: at this time, building from Android Studio or directly from +Gradle does not (re-)compile native code, including C++ and Rust.** This +means you will need to run ``mach build`` yourself to pick up changes to +native code. `Bug +1509539 <https://bugzilla.mozilla.org/show_bug.cgi?id=1509539>`_ tracks +making Android Studio and Gradle do this automatically. + +Performing a bug fix +-------------------- + +One you have got GeckoView building and running, you will want to start +contributing. There is a general guide to `Performing a Bug Fix for Git +Developers <contributing-to-mc.html>`_ for you to follow. To contribute to +GeckoView specifically, you will need the following additional +information. + +Running tests and linter locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To ensure that your patch does not break existing functionality in +GeckoView, you can run the junit test suite with the following command + +:: + + ./mach geckoview-junit + +This command also allows you to run individual tests or test classes, +e.g. + +:: + + ./mach geckoview-junit org.mozilla.geckoview.test.NavigationDelegateTest + ./mach geckoview-junit org.mozilla.geckoview.test.NavigationDelegateTest#loadUnknownHost + +If your patch makes a GeckoView JavaScript module, you should run ESLint +as well: + +:: + + ./mach lint -l eslint mobile/android/modules/geckoview/ + +To see information on other options, simply run +``./mach geckoview-junit --help``; of particular note for dealing with +intermittent test failures are ``--repeat N`` and +``--run-until-failure``, both of which do exactly what you’d expect. + +Updating the changelog and API documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the patch that you want to submit changes the public API for +GeckoView, you must ensure that the API documentation is kept up to +date. To check whether your patch has altered the API, run the following +command. + +.. code:: bash + + ./mach lint --linter android-api-lint + +The output of this command will inform you if any changes you have made +break the existing API. Review the changes and follow the instructions +it provides. + +If the linter asks you to update the changelog, please ensure that you +follow the correct format for changelog entries. Under the heading for +the next release version, add a new entry for the changes that you are +making to the API, along with links to any relevant files, and bug +number e.g. + +:: + + - Added [`GeckoRuntimeSettings.Builder#aboutConfigEnabled`][71.12] to control whether or + not `about:config` should be available. + ([bug 1540065]({{bugzilla}}1540065)) + + [71.12]: {{javadoc_uri}}/GeckoRuntimeSettings.Builder.html#aboutConfigEnabled-boolean- + +Submitting to the ``try`` server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is advisable to run your tests before submitting your patch. You can +do this using Mozilla’s ``try`` server. To submit a GeckoView patch to +``try`` before submitting it for review, type: + +.. code:: bash + + ./mach try fuzzy -q "android" + +This will run all of the Android test suite. If your patch passes on +``try`` you can be (fairly) confident that it will land successfully +after review. + +Tagging a reviewer +~~~~~~~~~~~~~~~~~~ + +When submitting a patch to Phabricator, if you know who you want to +review your patch, put their Phabricator handle against the +``reviewers`` field. + +If you don’t know who to tag for a review in the Phabricator submission +message, leave the field blank and, after submission, follow the link to +the patch in Phabricator and scroll to the bottom of the screen until +you see the comment box. + +- Select the ``Add Action`` drop down and pick the ``Change Reviewers`` option. +- In the presented box, add ``geckoview-reviewers``. Selecting this group as the reviewer will notify all the members of the GeckoView team there is a patch to review. +- Click ``Submit`` to submit the reviewer change request. + +Include GeckoView as a dependency +--------------------------------- + +If you want to include a development version of GeckoView as a +dependency inside another app, you must link to a local copy. There are +several ways to achieve this, but the preferred way is to use Gradle’s +*dependency substitution* mechanism, for which there is first-class +support in ``mozilla-central`` and a pattern throughout Mozilla’s +GeckoView-consuming ecosystem. + +The good news is that ``mach build`` produces everything you need, so +that after the configuration below, you should find that the following +commands rebuild your local GeckoView and then consume your local +version in the downstream project. + +.. code:: sh + + cd /path/to/mozilla-central && ./mach build + cd /path/to/project && ./gradlew assembleDebug + +**Be sure that your ``mozconfig`` specifies the correct ``--target`` +argument for your target device.** Many projects use “ABI splitting” to +include only the target device’s native code libraries in APKs deployed +to the device. On x86-64 and aarch64 devices, this can result in +GeckoView failing to find any libraries, because valid x86 and ARM +libraries were not included in a deployed APK. Avoid this by setting +``--target`` to the exact ABI that your device supports. + +Dependency substiting your local GeckoView into a Mozilla project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most GeckoView-consuming projects produced by Mozilla support dependency +substitution via ``local.properties``. These projects include: + +- `Fenix <https://github.com/mozilla-mobile/fenix>`_ +- `reference-browser <https://github.com/mozilla-mobile/reference-browser>`_ +- `android-components <https://github.com/mozilla-mobile/android-components>`_ +- `Firefox Reality <https://github.com/MozillaReality/FirefoxReality>`_ + +Simply edit (or create) the file ``local.properties`` in the project +root and include a line like: + +.. code:: properties + + dependencySubstitutions.geckoviewTopsrcdir=/path/to/mozilla-central + +The default object directory – the one that a plain ``mach build`` +discovers – will be used. You can optionally specify a particular object +directory with an additional line like: + +.. code:: properties + + dependencySubstitutions.geckoviewTopobjdir=/path/to/object-directory + +With these lines, the GeckoView-consuming project should use the +GeckoView AAR produced by ``mach build`` in your local +``mozilla-central``. + +**Remember to remove the lines in ``local.properties`` when you want to +return to using the published GeckoView builds!** + +Dependency substituting your local GeckoView into a non-Mozilla project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In projects that don’t have first-class support for dependency +substitution already, you can do the substitution yourself. See the +documentation in +`substitue-local-geckoview.gradle <https://hg.mozilla.org/mozilla-central/file/tip/substitute-local-geckoview.gradle>`_, +but roughly: in each Gradle project that consumes GeckoView, i.e., in +each ``build.gradle`` with a +``dependencies { ... 'org.mozilla.geckoview:geckoview-...' }`` block, +include lines like: + +.. code:: groovy + + ext.topsrcdir = "/path/to/mozilla-central" + ext.topobjdir = "/path/to/object-directory" // Optional. + apply from: "${topsrcdir}/substitute-local-geckoview.gradle" + +**Remember to remove the lines from all ``build.gradle`` files when you +want to return to using the published GeckoView builds!** + +Next Steps +---------- + +- Get started with `Native Debugging <native-debugging.html>`_ + +.. |alt text| image:: ../assets/DisableInstantRun.png +.. |alt text 1| image:: ../assets/GeckoViewStructure.png diff --git a/mobile/android/docs/geckoview/contributor/index.rst b/mobile/android/docs/geckoview/contributor/index.rst new file mode 100644 index 0000000000..b93cebe634 --- /dev/null +++ b/mobile/android/docs/geckoview/contributor/index.rst @@ -0,0 +1,38 @@ +.. -*- Mode: rst; fill-column: 80; -*- + +========================= +Contributing to GeckoView +========================= + +Contributor Site +================ + +.. toctree:: + :maxdepth: 1 + :hidden: + + geckoview-quick-start + for-gecko-engineers + mc-quick-start + contributing-to-mc + native-debugging + +If you want to run GeckoView from code, or start contributing back to +the project, here you will find resources to help you do that. + +- `GeckoView Contributor Quick Start Guide <geckoview-quick-start.html>`_: + Get GeckoView set up for development. +- `GeckoView for Gecko Engineers <for-gecko-engineers.html>`_: A + quick-start guide for those already familiar with contributing to + Firefox development. +- `Mozilla Central Quick Start Guide <mc-quick-start.html>`_: Get Mozilla + Central set up for development. +- `Mozilla Central Contributor Guide <contributing-to-mc.html>`_: Get + started as a contributor to Mozilla Central. +- `Guide to Native Debugging in Android Studio <native-debugging.html>`_: + Set up Android Studio for debugging native code. + +If there is documentation that you feel is missing, or an existing +document doesn’t cover the aspect that you are looking for, please +request it by raising an issue on our `documentation +site <https://github.com/mozilla/geckoview/issues>`_. diff --git a/mobile/android/docs/geckoview/contributor/mc-quick-start.rst b/mobile/android/docs/geckoview/contributor/mc-quick-start.rst new file mode 100644 index 0000000000..19c9b09e5c --- /dev/null +++ b/mobile/android/docs/geckoview/contributor/mc-quick-start.rst @@ -0,0 +1,184 @@ +.. -*- Mode: rst; fill-column: 80; -*- + +=========================== +Mozilla Central Quick Start +=========================== + +Table of contents +================= + +.. contents:: :local: + +Firefox Developer Git Quick Start Guide +======================================= + +Getting setup to as a first time Mozilla contributor is hard. There are +plenty of guides out there to help you get started as a contributor, but +many of the new contributor guides out of date often more current ones +are aimed at more experienced contributors. If you want to review these +guides, you can find several linked to from `Contributing to the Mozilla code base <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Introduction>`_ +on `MDN <https://developer.mozilla.org/>`_. + +This guide will take you through setting up as a contributor to +``mozilla-central``, the Firefox main repository, as a git user. + +Setup +----- + +The first thing you will need is to install Mercurial as this is the VCS +that ``mozilla-central`` uses. + +.. _mac-0: + +Mac +~~~ + +.. _homebrew-0: + +Homebrew +^^^^^^^^ + +.. code:: bash + + brew install mercurial + +macports +^^^^^^^^ + +.. code:: bash + + sudo port install mercurial + +Linux +~~~~~ + +apt +^^^ + +.. code:: bash + + sudo apt-get install mercurial + +Alternatively you can install `Mercurial directly <https://www.mercurial-scm.org/wiki/Download>`_. + +Check that you have successfully installed Mercurial by running: + +.. code:: bash + + hg --version + +If you are an experienced git user and are unfamiliar with Mercurial, +you may want to install ``git-cinnabar``. Cinnabar is a git remote +helper that allows you to interact with Mercurial repos using git +semantics. + +git-cinnabar +------------ + +There is a Homebrew install option for ``git-cinnabar``, but this did +not work for me, nor did the installer option. Using these tools, when I +tried to clone the Mercurial repo it hung and did not complete. I had to +do a manual install before I could use ``git-cinnabar`` successfully to +download a Mercurial repo. If you would like to try either of these +option, however, here they are: + +.. _mac-1: + +Mac +~~~~~ + +.. _homebrew-1: + +Homebrew +^^^^^^^^ + +.. code:: bash + + brew install git-cinnabar + +All Platforms +~~~~~~~~~~~~~ + +Installer +^^^^^^^^^ + +.. code:: bash + + git cinnabar download + +Manual installation +^^^^^^^^^^^^^^^^^^^ + +.. code:: bash + + git clone https://github.com/glandium/git-cinnabar.git && cd git-cinnabar + make + export PATH="$PATH:/somewhere/git-cinnabar" + echo 'export PATH="$PATH:/somewhere/git-cinnabar"' >> ~/.bash_profile + git cinnabar download + +``git-cinnabar``\ ’s creator, `glandium <https://glandium.org/>`_, has +written a number of posts about setting up for Firefox Development with +git. This `post <https://glandium.org/blog/?page_id=3438>`_ is the one +that has formed the basis for this walkthrough. + +In synopsis: + +- initialize an empty git repository + +.. code:: bash + + git init gecko && cd gecko + +- Configure git: + +.. code:: bash + + git config fetch.prune true + git config push.default upstream + +- Add remotes for your repositories. There are several to choose from, + ``central``, ``inbound``, ``beta``, ``release`` etc. but in reality, + if you plan on using Phabricator, which is Firefox’s preferred patch + submission system, you only need to set up ``central``. It might be + advisable to have access to ``inbound`` however, if you want to work + on a version of Firefox that is queued for release. This guide will + be focused on Phabricator. + +.. code:: bash + + git remote add central hg::https://hg.mozilla.org/mozilla-central -t branches/default/tip + git remote add inbound hg::https://hg.mozilla.org/integration/mozilla-inbound -t branches/default/tip + git remote set-url --push central hg::ssh://hg.mozilla.org/mozilla-central + git remote set-url --push inbound hg::ssh://hg.mozilla.org/integration/mozilla-inbound + +- Expose the branch tip to get quick access with some easy names. + +.. code:: bash + + git config remote.central.fetch +refs/heads/branches/default/tip:refs/remotes/central/default + git config remote.inbound.fetch +refs/heads/branches/default/tip:refs/remotes/inbound/default + +- Setup a remote for the try server. The try server is an easy way to + test a patch without actually checking the patch into the core + repository. Your code will go through the same tests as a + ``mozilla-central`` push, and you’ll be able to download builds if + you wish. + +.. code:: bash + + git remote add try hg::https://hg.mozilla.org/try + git config remote.try.skipDefaultUpdate true + git remote set-url --push try hg::ssh://hg.mozilla.org/try + git config remote.try.push +HEAD:refs/heads/branches/default/tip + +- Now update all the remotes. This performs a ``git fetch`` on all the + remotes. Mozilla Central is a *large* repository. Be prepared for + this to take a very long time. + +.. code:: bash + + git remote update + +All that’s left to do now is pick a bug to fix and `submit a +patch <contributing-to-mc>`__. diff --git a/mobile/android/docs/geckoview/contributor/native-debugging.rst b/mobile/android/docs/geckoview/contributor/native-debugging.rst new file mode 100644 index 0000000000..e04872c141 --- /dev/null +++ b/mobile/android/docs/geckoview/contributor/native-debugging.rst @@ -0,0 +1,242 @@ +.. -*- Mode: rst; fill-column: 80; -*- + +===================== +Debugging Native Code +===================== + +Table of contents +================= + +.. contents:: :local: + +Debugging Native Code in Android Studio. +======================================== + +If you want to work on the C++ code that powers GeckoView, you will need +to be able to perform native debugging inside Android Studio. This +article will guide you through how to do that. + +If you need to get set up with GeckoView for the first time, follow the +`Quick Start Guide <geckoview-quick-start.html>`_. + +Perform a debug build of Gecko. +------------------------------- + +1. Edit your ``mozconfig`` file and add the following lines. These will + ensure that the build includes debug checks and symbols. + +.. code:: + + ac_add_options --enable-debug + ac_add_options --with-android-ndk="<path>/.mozbuild/android-ndk-r17b" + +2. Ensure that the following lines are commented out in your + ``mozconfig`` if present. ``./mach configure`` will not allow + artifact builds to be enabled when generating a debug build. + +.. code:: + + # ac_add_options --enable-artifact-builds + +3. To be absolutely sure that Android Studio will pick up your debug + symbols, the first time you perform a debug build it is best to + clobber your ``MOZ_OBJDIR``. Subsequent builds should not need this + step. + +.. code:: bash + + ./mach clobber + +4. Build as usual. Because this is a debug build, and because you have + clobbered your ``MOZ_OBJDIR``, this will take a long time. Subsequent + builds will be incremental and take less time, so go make yourself a + cup of your favourite beverage. + +.. code:: bash + + ./mach build + +Set up lldb to find your symbols +-------------------------------- + +Edit your ``~/.lldbinit`` file (or create one if one does not already +exist) and add the following lines. + +The first line tells LLDB to enable inline breakpoints - Android Studio +will need this if you want to use visual breakpoints. + +The remaining lines tell LLDB where to go to find the symbols for +debugging. + +.. code:: bash + + settings set target.inline-breakpoint-strategy always + settings append target.exec-search-paths <PATH>/objdir-android-opt/toolkit/library/build + settings append target.exec-search-paths <PATH>/objdir-android-opt/mozglue/build + +Set up Android Studio to perform native debugging. +================================================== + +1. Edit the configuration that you want to debug by clicking + ``Run -> Edit Configurations...`` and selecting the correct + configuration from the options on the left hand side of the resulting + window. +2. Select the ``Debugger`` tab. +3. Select ``Dual`` from the ``Debug type`` select box. Dual will allow + debugging of both native and Java code in the same session. It is + possible to use ``Native``, but it will only allow for debugging + native code, and it’s frequently necessary to break in the Java code + that configures Gecko and child processes in order to attach + debuggers at the correct times. +4. Under ``Symbol Directories``, add a new path pointing to + ``<PATH>/objdir-android-opt/toolkit/library/build``, the same path + that you entered into your ``.lldbinit`` file. +5. Select ``Apply`` and ``OK`` to close the window. + +Debug Native code in Android Studio +=================================== + +1. The first time you are running a debug session for your app, it’s + best to start from a completely clean build. Click + ``Build -> Rebuild Project`` to clean and rebuild. You can also + choose to remove any existing builds from your emulator to be + completely sure, but this may not be necessary. +2. If using Android Studio visual breakpoints, set your breakpoints in + your native code. +3. Run the app in debug mode as usual. +4. When debugging Fennec or geckoview_example, you will almost + immediately hit a breakpoint in ``ElfLoader.cpp``. This is expected. + If you are not using Android Studio visual breakpoints, you can set + your breakpoints here using the lldb console that is available now + this breakpoint has been hit. To set a breakpoint, select the app tab + (if running Dual, there will also be an ``<app> java`` tab) from the + debug window, and then select the ``lldb`` console tab. Type the + following into the console: + +.. code:: + + b <file>.cpp:<line number> + +5. Once your breakpoints have been set, click the continue execution + button to move beyond the ``ElfLoader`` breakpoint and your newly set + native breakpoints should be hit. Debug as usual. + +Attaching debuggers to content and other child processes +-------------------------------------------------------- + +Internally, GeckoView has a multi-process architecture. The main Gecko +process lives in the main Android process, but content rendering and +some other functions live in child processes. This balances load, +ensures certain critical security properties, and allows GeckoView to +recover if content processes become unresponsive or crash. However, it’s +generally delicate to debug child processes because they come and go. + +The general approach is to make the Java code in the child process that +you want to debug wait for a Java debugger at startup, and then to +connect such a Java debugger manually from the Android Studio UI. + +`Bug 1522318 <https://bugzilla.mozilla.org/show_bug.cgi?id=1522318>`__ +added environment variables that makes GeckoView wait for Java debuggers +to attach, making this debug process more developer-friendly. See +`Configuring GeckoView for Automation <../consumer/automation.html>`__ +for instructions on how to set environment variables that configure +GeckoView’s runtime environment. + +Making processes wait for a Java debugger +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following environment variable makes the main (Gecko) process wait +for a Java debugger to connect: + +.. code:: shell + + MOZ_DEBUG_WAIT_FOR_JAVA_DEBUGGER=1 + +This is a superset of Android Studio’s built-in debugging support so +it’s not particularly useful (unless you want to attach a different jdwp +debugger). + +The following environment variable makes every child process wait for a +Java debugger to connect: + +.. code:: shell + + MOZ_DEBUG_CHILD_WAIT_FOR_JAVA_DEBUGGER= + +Set ``MOZ_DEBUG_CHILD_WAIT_FOR_JAVA_DEBUGGER=suffix`` in the environment +to make child processes with an Android process name ending with +``suffix`` wait for a Java debugger to connect. For example, the +following environment variable makes every child content process wait +for a Java debugger to connect: + +.. code:: shell + + MOZ_DEBUG_CHILD_WAIT_FOR_JAVA_DEBUGGER=:tab + +An easy way to set this is with ``./mach run``: + +.. code:: shell + + ./mach run --setenv MOZ_DEBUG_CHILD_WAIT_FOR_JAVA_DEBUGGER=:tab + +Attaching a Java debugger to a waiting child process +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is standard: follow the `Android Studio instructions <https://developer.android.com/studio/debug/index.html#attach-debugger>`_. +You must attach a Java debugger, so you almost certainly want to attach +a ``Dual`` debugger and you definitely can’t attach only a ``Native`` +debugger. + +Determining the correct process to attach to is a little tricky because +the mapping from process ID (pid) to process name is not always clear. +Gecko content child processes are suffixed ``:tab`` at this time. + +If you attach ``Dual`` debuggers to both the main process and a content +child process, you will have four (4!) debug tabs to manage in Android +Studio, which is awkward. Android Studio doesn’t appear to configure +attached debuggers in the same way that it configures debuggers +connecting to launched Run Configurations, so you may need to manually +configure search paths – i.e., you may need to invoke the contents of +your ``lldbinit`` file in the appropriate ``lldb`` console by hand, +using an invocation like +``command source /absolute/path/to/topobjdir/lldbinit``. + +Android Studio also doesn’t appear to support targeting breakpoints from +the UI (say, from clicking in a gutter) to specific debug tabs, so you +may also need to set breakpoints in the appropriate ``lldb`` console by +hand. + +Managing more debug tabs may require different approaches. + +Using Android Studio on Windows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can now use :ref:`artifact builds <Understanding Artifact Builds>` +mode on `MozillaBuild environment <https://wiki.mozilla.org/MozillaBuild>`_ even if you are +not using WSL. If you want to debug GeckoView using Android Studio on +Windows, you have to set an additional environment variable via the +Control Panel to run the gradle script. The ``mach`` command sets these +variables automatically, but Android Studio cannot. + +If you install MozillaBuild tools to ``C:\mozilla-build`` (default +installation path), you have to set the ``MOZILLABUILD`` environment +variable to recognize MozillaBuild installation path. + +To set environment variable on Windows 10, open the ``Control Panel`` +from ``Windows System``, then select ``System and Security`` - +``System`` - ``Advanced system settings`` - +``Environment Variables ...``. + +To set the ``MOZILLABUILD`` variable, click ``New...`` in +``User variables for``, then ``Variable name:`` is ``MOZILLABUILD`` and +``Variable value:`` is ``C:\mozilla-build``. + +You also have to append some tool paths to the ``Path`` environment +variable. + +To append the variables to PATH, double click ``Path`` in +``User Variables for``, then click ``New``. And append the following +variables to ``Path``. + +- ``%MOZILLABUILD%\msys\bin`` +- ``%MOZILLABUILD%\bin`` |