mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-19 08:15:31 +00:00
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 --HG-- extra : rebase_source : 311e1b18a2f0ad60b41d574f3c23aa160ecd56c0
This commit is contained in:
parent
68b13698a1
commit
188f0ab668
101
mobile/android/docs/gradle.rst
Normal file
101
mobile/android/docs/gradle.rst
Normal file
@ -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`.
|
@ -20,6 +20,7 @@ Contents:
|
||||
defaultdomains
|
||||
shutdown
|
||||
push
|
||||
gradle
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
Loading…
Reference in New Issue
Block a user