Bug 1411654 - Part 0: Add rudimentary documentation about Gradle inte…

…gration. 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

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

mobile/android/docs/index.rst

@@ -20,6 +20,7 @@ Contents:
    defaultdomains
    shutdown
    push
+   gradle
 
 Indices and tables
 ==================