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
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`