Bug 1792258 - Post: Make it easier to test (Android) multi-locale packages. r=geckoview-reviewers,m_kato

This commit updates the outdated documentation for producing multi-locale
packages, and also arranges for Android multi-locale packages to produce a
GeckoViewExample binary that has `libs` and `assets/omni.ja`.  Together, these
greatly ease multi-locale testing.

Differential Revision: https://phabricator.services.mozilla.com/D160705

build.gradle

@@ -151,10 +151,11 @@ ext.geckoBinariesOnlyIf = { task ->
         return false
     }
 
-    // Multi-l10n builds set `AB_CD=multi`, which isn't a valid locale.  To
+    // Multi-l10n builds set `AB_CD=multi`, which isn't a valid locale, and
-    // avoid failures, if Gradle is invoked with AB_CD=multi, we don't invoke
+    // `MOZ_CHROME_MULTILOCALE`.  To avoid failures, if Gradle is invoked with
-    // Make at all.
+    // either, we don't invoke Make at all; this allows a multi-locale omnijar
-    if ('multi' == System.env.AB_CD) {
+    // to be consumed without modification.
+    if ('multi' == System.env.AB_CD || System.env.MOZ_CHROME_MULTILOCALE) {
         rootProject.logger.lifecycle("Skipping task ${task.path} because: AB_CD=multi")
         return false
     }

build/docs/locales.rst

@@ -90,20 +90,63 @@ If you want to create a single build with multiple locales, you will do
       ./mach build
       ./mach package
 
-#. For each locale you want to include in the build:
+#. Create the multi-locale package:
 
    .. code-block:: shell
 
-      export MOZ_CHROME_MULTILOCALE="de it zh-TW"
+      ./mach package-multi-locale --locales de it zh-TW
-      for AB_CD in $MOZ_CHROME_MULTILOCALE; do
-         ./mach build chrome-$AB_CD
-      done
 
-#. Create the multilingual package:
+On Android, this produces a multi-locale GeckoView AAR and multi-locale APKs,
+including GeckoViewExample.  You can test different locales by changing your
+Android OS locale and restarting GeckoViewExample.  You'll need to install with
+the ``MOZ_CHROME_MULTILOCALE`` variable set, like:
 
    .. code-block:: shell
 
-      AB_CD=multi ./mach package
+       env MOZ_CHROME_MULTILOCALE=en-US,de,it,zh-TW ./mach android install-geckoview_example
+
+Multi-locale builds without compiling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For deep technical reasons, artifact builds do not support multi-locale builds.
+However, with a little work, we can achieve the same effect:
+
+#. Arrange a ``mozconfig`` without a compilation environment but with support
+   for the ``RecursiveMake`` build backend, like:
+
+   .. code-block:: shell
+
+      ac_add_options --disable-compile-environment
+      export BUILD_BACKENDS=FasterMake,RecursiveMake
+      ... other options ...
+
+#. Configure.
+
+   .. code-block:: shell
+
+      ./mach configure
+
+#. Manually provide compiled artifacts.
+
+   .. code-block:: shell
+
+      ./mach artifact install [-v]
+
+#. Build.
+
+   .. code-block:: shell
+
+      ./mach build
+
+#. Produce a multi-locale package.
+
+   .. code-block:: shell
+
+      ./mach package-multi-locale --locales de it zh-TW
+
+This build configuration is fragile and not generally useful for active
+development (for that, use a full/compiled build), but it certainly speeds
+testing multi-locale packaging.
 
 General flow of repacks
 -----------------------

mobile/android/gradle/with_gecko_binaries.gradle

@@ -38,9 +38,13 @@ def getNDKDirectory() {
     return null
 }
 
+// Whether to include compiled artifacts: `libs/**/*.so` and `assets/omni.ja`.
+// Multi-locale packaging wants to include compiled artifacts but *not* rebuild
+// them: see also `rootProject.{machStagePackage,geckoBinariesOnlyIf}`.
 def hasCompileArtifacts() {
-    return project.mozconfig.substs.COMPILE_ENVIRONMENT
+    return project.mozconfig.substs.COMPILE_ENVIRONMENT // Full builds.
-        || project.mozconfig.substs.MOZ_ARTIFACT_BUILDS
+        || project.mozconfig.substs.MOZ_ARTIFACT_BUILDS // Artifact builds.
+        || System.getenv("MOZ_CHROME_MULTILOCALE") // Multi-locale packaging.
 }
 
 // Get the LLVM bin folder, either from the currently used toolchain or, if

python/mozbuild/mozbuild/mach_commands.py

@@ -2622,6 +2622,18 @@ def package_l10n(command_context, verbose=False, locales=[]):
             cwd=mozpath.join(command_context.topsrcdir),
         )
 
+        # This is tricky: most Android build commands will regenerate the
+        # omnijar, producing a `res/multilocale.txt` that does not contain the
+        # set of locales packaged by this command.  To avoid regenerating, we
+        # set a special environment variable.
+        print(
+            "Execute `env MOZ_CHROME_MULTILOCALE='{}' ".format(
+                append_env["MOZ_CHROME_MULTILOCALE"]
+            )
+            + "mach android install-geckoview_example` "
+            + "to install the multi-locale geckoview_example and test APKs."
+        )
+
     return 0