Bug 1370156 - Add Gradle-integration into moz.build notes. r=me draft
authorNick Alexander <nalexander@mozilla.com>
Mon, 05 Jun 2017 11:24:12 -0700
changeset 589170 23815201ef98fac7cbfa3011e61cbe8a9d252ff3
parent 589169 41e33d94dfb674f3bad1c053683f0d769c47318b
child 631779 56154b0def8dc61fa41a5f7a6e61f7e6efce159e
push id62262
push usernalexander@mozilla.com
push dateMon, 05 Jun 2017 18:25:07 +0000
Bug 1370156 - Add Gradle-integration into moz.build notes. r=me DO NOT BUILD because NPOTB MozReview-Commit-ID: 6jvVDsGInnp
new file mode 100644
--- /dev/null
+++ b/build/docs/android-gradle.rst
@@ -0,0 +1,81 @@
+.. _android-gradle:
+Android Gradle integration into moz.build
+The build system support for building Android packages (APK files) is
+transitioning away from a Makefile-based system and towards a
+Gradle-based system.  Bug 1254353 tracks this transition.
+Right now, the Makefile-based system and the Gradle-based system
+coexist, and this document explains how the two systems interact.
+The Gradle-based system
+The original purpose of the Gradle-based system was to allow Fennec
+developers to use IntelliJ or Android Studio to speed up the
+edit-compile-run cycle.  The intention was not to replace the
+Makefile-based system, and most of the choices reflect that.
+The Gradle configuration is mostly determined by two parameters:
+- ``buildType`` [#buildType]_, either ``debug`` or ``release``, and
+- ``audience`` flavor dimension [#flavorDimension]_, either ``local``,
+  ``localOld``, ``official``.
+**The Makefile-based Fennec APK corresponds to the Gradle-based ``officialRelease`` APK.**
+The ``release`` build type turns on ProGuard.
+The ``official`` flavor dimension turns off developer-specific build
+tweaks, including ``multiDex`` mode.
+In particular, ``debug`` builds are not used in Mozilla automation to
+produce APKs (although they are used to build and run tests); and the
+``local`` and ``localOld`` builds are there to support local
+developers.  Everything else is ignored.
+Interaction without ``--with-gradle``
+When the ``--with-gradle`` flag *is not* in the ``mozconfig``, the
+Gradle integration sits on top of the Makefile-based system.  The
+developer chooses either a ``local`` (for API 21+ devices) or a
+``localOld`` (for API <21 devices) build configuration.  The main
+``mach build && mach package`` steps are augmented by IDE-specific
+invocations that let Android Studio:
+- rebuild ``AndroidManifest.xml`` if necessary;
+- compile modified Java;
+- update modified resources and assets;
+- rebuild ``omni.ja`` if any JavaScript or chrome XHTML/CSS has
+  changed;
+before producing a new APK (separate from the Makefile-based APK).
+This Gradle-produced APK *includes* the Gecko libraries (``libxul.so``,
+``libmozglue.so``, etc) so it can be deployed to device (from within
+an IDE, or directly by Gradle).
+The ``android-api-15`` task in automation exercises this flow.
+Interaction with ``--with-gradle``
+When the ``--with-gradle`` flag *is* in the ``mozconfig``, the
+Makefile-based system invokes Gradle itself to produce a Fennec APK.
+The Makefile-based system invokes Gradle to build the
+``officialRelease`` APK to complete the ``mach build`` process; the
+resulting Gradle APK *does not* include Gecko libraries
+(``libxul.so``, ``libmozglue.so``, etc) so it *cannot* be deployed to
+device (from within an IDE, or directly by Gradle).  (Technically it
+can be deployed, but it cannot be launched: it will crash immediately
+due to the missing native libraries.)  The ``mach package`` process
+will insert the required libraries into the Gradle-produced APK and
+``mach install`` will deploy it to device.
+The ``android-api-15-gradle`` task in automation exercises this flow.
+.. [#buildType] http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Build-Types
+.. [#flavorDimension] http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Multi-flavor-variants
--- a/build/docs/index.rst
+++ b/build/docs/index.rst
@@ -22,23 +22,23 @@ Important Concepts
+   android-gradle
 integrated development environment (IDE)
 .. toctree::
    :maxdepth: 1
-   androideclipse
 mozbuild is a Python package containing a lot of the code for the
 Mozilla build system.