Table of contents

  1. GeckoView Contributor Quick Start Guide
    1. Get set up with Mozilla Central
    2. Bootstrap Gecko
    3. Build from the command line
    4. Build Using Android Studio
    5. Performing a bug fix
      1. Updating the changelog and API documentation
      2. Submitting to the try server
      3. Tagging a reviewer
    6. Include GeckoView as a dependency
      1. Publish to a local repository
      2. Archive GeckoView
    7. Next Steps

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.

You may also be interested in how to get up and running with Firefox For Android.

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, or the Contributing to the Mozilla code base guide on MDN 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 development.

  • Ensure you have mozilla-central checked out. If this is the first time you are doing this, it may take some time.
git checkout central/default

If you are on a mac, you will need to have the Xcode build tools installed. You can do this by either installing 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.

./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 tell you to copy and paste some configuration into your mozconfig file. The mozconfig file can be found in the root of your gecko repo - or create a file called mozconfig if it does not exist. Check that the correct value is associated with the --target argument as this may not correctly match your setup. Copy the file contents from the mach bootstrap output into your file and save in the root directory of your project.

  • Configure your build.
./mach configure

Build from the command line

In order to pick up the configuration changes we just made we need to build from the command line and package the app.

./mach build
./mach package

Build Using Android Studio

  • Install Android Studio.
  • 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.
  • 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

Now you’re set up and ready to go.

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 for you to follow. To contribute to GeckoView specifically, you will need the following additional information.

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.

./mach 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. i.e.

  - Added methods for each setting in [`GeckoSessionSettings`][66.3] 
  [66.3]: ../GeckoSessionSettings.html

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:

./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 two ways of doing this, publishing GeckoView to a local Maven repository (recommended), or linking to a local archive.

Publish to a local repository

Publish GeckoView to your local maven by running

./gradlew geckoview:publishWithGeckoBinariesDebugPublicationToMavenLocal
  • The binary will have been published to a repo found in ~/.m2. Run the following command to figure out the name of the artifcat:
$ tree ~/.m2/repository/org/mozilla/geckoview
  • Make a note of the name of your artifact. Update your build.gradle file to point to the dependency and link to your local repository.
dependencies {
    // ...
    implementation "org.mozilla.geckoview:geckoview-default:70.0.20190729181900"
    // ...
}

// ...

repositories {
  //...
  mavenLocal()
  //..
}

Archive GeckoView

./mach android archive-geckoview

This should create a file named geckoview-*.aar in your build output folder (MOZ_OBJDIR):

ls <your-output-directory>/gradle/build/mobile/android/geckoview/outputs/aar
geckoview-official-withGeckoBinaries-noMinApi-release.aar

Then all you need to do is point to the AAR in your build.gradle file.

repositories {
    // ...

    flatDir(
        name: 'localBuild',
        dirs: '<absolute path to AAR>'
    )
}
// ...
dependencies {
    // ...
    implementation (
            name: 'geckoview-official-withGeckoBinaries-noMinApi-release',
            ext: 'aar'
    )
    implementation "org.mozilla:geckoview-default:70.0"
    
    // ...
}

Next Steps