Bug 1411654 - Part 0: Add rudimentary documentation about Gradle integration. r=maliu
authorNick Alexander <nalexander@mozilla.com>
Wed, 15 Nov 2017 15:02:18 -0800
changeset 453614 cec2b8828cc8800fa269d290ce38ea82c454b445
parent 453613 76085ddd5ac768b3ec8dfe9ca03283630c436681
child 453615 f918500d9cf5112b70bc8e0a120df435b02252b7
push id1648
push usermtabara@mozilla.com
push dateThu, 01 Mar 2018 12:45:47 +0000
treeherdermozilla-release@cbb9688c2eeb [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmaliu
bugs1411654, 1417232
milestone59.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1411654 - Part 0: Add rudimentary documentation about Gradle integration. r=maliu This sketches the flavor dimensions. The important ones are `audience` and `geckoBinaries`, which I think simplify the situation greatly. Coupled with Bug 1417232 centralizing most everything in `mobile/android/gradle.configure`, the Gradle configuration shouldn't be so hard to evolve. MozReview-Commit-ID: DILjVrnLA3F
mobile/android/docs/gradle.rst
mobile/android/docs/index.rst
new file mode 100644
--- /dev/null
+++ b/mobile/android/docs/gradle.rst
@@ -0,0 +1,101 @@
+.. -*- Mode: rst; fill-column: 80; -*-
+
+=================================
+ The Fennec Gradle configuration
+=================================
+
+The Fennec Gradle configuration has three major facets:
+
+1. separation into Gradle projects;
+2. Android-Gradle build configurations using `flavorDimensions`;
+3. integration into the larger `moz.build` build system.
+
+Separation into Gradle projects
+===============================
+
+The Fennec source code is separated into multiple Gradle projects.  Right now,
+there are only a few: `:app`, `:geckoview`, `:thirdparty`, etc.  Over time, pieces
+of the Fennec source code will be extracted into separate, more-or-less
+stand-alone Gradle projects (e.g., `:services`, `:stumbler`, `:media`) and use
+modern techniques such as dependency injection to configure themselves at
+runtime.
+
+The `:omnijar` project is special and exists only to support integration with
+Android Studio.
+
+The details of the Gradle projects are reflected in the root `settings.gradle`
+and the `**/build.gradle` files throughout the tree.
+
+Android-Gradle build configurations
+===================================
+
+The Fennec `:app` project uses the Android-Gradle build plugin
+`flavorDimensions` feature set to support many different configurations.  The
+Gradle integration must support many often conflicting requirements; the flavor
+dimensions chosen support these requirements.
+
+Version 3.0+ of the Android-Gradle build plugin improves support for "variant
+dependencies".  This makes it easier for a consuming application (for us,
+`:app`) to use the appropriate configuration of consumed libraries (for us,
+`:geckoview`).  This allows us to simplify the logic around packaging the Gecko
+libraries and Omnijar.
+
+The details of the Android-Gradle build configurations are reflected
+`**/build.gradle` files throughout the tree, in the
+`mobile/android/gradle/*.gradle` files, and in the configuration baked into
+`mobile/android/gradle.configure`.
+
+The notable flavor dimensions are:
+
+audience
+--------
+
+The `audience` flavor dimension determines who the build is for.  "local"
+audiences are developers: they should get extra logging and as much support for
+building Fennec as possible.  In particular, "local" audiences get support for
+modifying the Android manifest and regenerating the pre-processed `strings.xml`
+files while building with Gradle from within Android Studio.
+
+"official" audiences are end users: they should get Mozilla's official branding
+and have security-sensitive developer features disabled.  The "official"
+audience corresponds roughly to the `MOZILLA_OFFICIAL=1` build setting.
+
+**Builds shipped to the Google Play Store are always for "official" audiences.**
+
+geckoBinaries
+-------------
+
+For deep historical reasons, Mozilla's build system has multiple stages, the
+most important of which are the build stage and the package stage.  During the
+build stage, the Gecko compiled libraries (e.g., `libxul.so`) and the Omnijar
+have not yet been built.  These libraries are only available during the package
+stage.  Gradle builds always want to include the Gecko libraries and the
+Omnijar.
+
+To accommodate the different stages, the build stage always invokes
+"withoutGeckoBinaries" Gradle configurations. These configurations don't expect
+or use the Gecko libraries or Omnijar.  At the moment, the package stage also
+invokes "withoutGeckoBinaries", but in the future, the package stage will invoke
+"withGeckoBinaries" Gradle configurations to simplify the packaging of libraries
+and the omnijar.
+
+**Local developers almost always want to build "withGeckoBinaries", so that the
+APK files produced can be run on device.**
+
+minApi
+------
+
+At various times in the past, Fennec has supported APK splits, producing APKs
+that support only specific Android versions.  While this is not used at this
+time, there are certain developer options (i.e., options that should only apply
+to "local" audiences) that *also* depend on the target Android version.  This
+flavor dimension allows to opt in to those options, improving the speed of
+development.
+
+Integration into the larger `moz.build` build system
+====================================================
+
+The details of the Gradle integration into the larger `moz.build` system are
+mostly captured in configuration baked into `mobile/android/gradle.configure`.
+This configuration is reflected in the Android-specific `mach android *`
+commands defined in `mobile/android/mach_commands.py`.
--- a/mobile/android/docs/index.rst
+++ b/mobile/android/docs/index.rst
@@ -15,15 +15,16 @@ Contents:
    uitelemetry
    activitystreamtelemetry
    downloadcontenttelemetry
    adjust
    mma
    defaultdomains
    shutdown
    push
+   gradle
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`