[#496] New package suffix for the app builds

- Created new gradle.properties attributes to configure package and app name
- Improved app/build.gradle to support the attribute
- Let Manifest file work with the new placeholder app name field
- Change debug builds with suffixes to avoid production app collision

Co-authored-by: Carter Jernigan <git@carterjernigan.com>

.github/workflows/pull-request.yml

@@ -246,7 +246,9 @@ jobs:
       - name: Test
         timeout-minutes: 30
         env:
-          # This first environment variable is used by Flank, since the temporary token is missing the project name
+          # Force blank suffix for screenshot tests
+          ORG_GRADLE_PROJECT_ZCASH_DEBUG_APP_NAME_SUFFIX: ""
+          # Used by Flank, since the temporary token is missing the project name
           GOOGLE_CLOUD_PROJECT: ${{ secrets.FIREBASE_TEST_LAB_PROJECT }}
           ORG_GRADLE_PROJECT_ZCASH_FIREBASE_TEST_LAB_API_KEY_PATH: ${{ steps.auth_test_lab.outputs.credentials_file_path }}
           # Because Fulladle doesn't allow Test Orchestrator to be enabled/disabled for a specific submodule, it must be enabled for all modules
@@ -288,6 +290,8 @@ jobs:
       - name: Build and test
         timeout-minutes: 25
         env:
+          # Force blank suffix for screenshot tests
+          ORG_GRADLE_PROJECT_ZCASH_DEBUG_APP_NAME_SUFFIX: ""
           ORG_GRADLE_PROJECT_ZCASH_EMULATOR_WTF_API_KEY: ${{ secrets.EMULATOR_WTF_API_KEY }}
         run: |
           ./gradlew testDebugWithEmulatorWtf :app:testZcashmainnetDebugWithEmulatorWtf

README.md

@@ -23,7 +23,9 @@ Contributions are very much welcomed!  Please read our [Contributing Guidelines]
 # Forking
 If you plan to fork the project to create a new app of your own, please make the following changes.  (If you're making a GitHub fork to contribute back to the project, these steps are not necessary.)
 
-1. Change the app name under app/src/main/res/values/strings.xml
+1. Change the app name and package name under [gradle.properties](gradle.properties)
+    1. ZCASH_RELEASE_APP_NAME
+    1. ZCASH_RELEASE_PACKAGE_NAME
 1. Change the support email address under ui-lib/src/res/ui/support/values/strings.xml
 1. Remove any copyrighted ZCash or Electric Coin Company icons, logos, or assets
     1. ui-lib/src/main/res/common/ - All of the the ic_launcher assets

app/build.gradle.kts

@@ -8,11 +8,13 @@ plugins {
     id("secant.emulator-wtf-conventions")
 }
 
-val packageName = "co.electriccoin.zcash"
+val packageName = project.property("ZCASH_RELEASE_PACKAGE_NAME").toString()
 
 // Force orchestrator to be used for this module, because we need cleared state to generate screenshots
 val isOrchestratorEnabled = true
 
+val testnetNetworkName = "Testnet"
+
 android {
     defaultConfig {
         applicationId = packageName
@@ -85,6 +87,11 @@ android {
         getByName("debug").apply {
             // Note that the build-conventions defines the res configs
             isPseudoLocalesEnabled = true
+
+            // Suffixing app package name and version to avoid collisions with other installed Zcash
+            // apps (e.g. from Google Play)
+            versionNameSuffix = "-debug"
+            applicationIdSuffix = ".debug"
         }
         getByName("release").apply {
             isMinifyEnabled = project.property("IS_MINIFY_ENABLED").toString().toBoolean()
@@ -99,6 +106,26 @@ android {
         }
     }
 
+    // Resolve final app name
+    applicationVariants.all {
+        val defaultAppName = project.property("ZCASH_RELEASE_APP_NAME").toString()
+        val debugAppNameSuffix = project.property("ZCASH_DEBUG_APP_NAME_SUFFIX").toString()
+        when (this.name) {
+            "zcashtestnetDebug" -> {
+                resValue( "string", "app_name", "$defaultAppName ($testnetNetworkName)$debugAppNameSuffix")
+            }
+            "zcashmainnetDebug" -> {
+                resValue( "string", "app_name", "$defaultAppName$debugAppNameSuffix")
+            }
+            "zcashtestnetRelease" -> {
+                resValue( "string", "app_name", "$defaultAppName ($testnetNetworkName)")
+            }
+            "zcashmainnetRelease" -> {
+                resValue( "string", "app_name", defaultAppName)
+            }
+        }
+    }
+
     packagingOptions {
         resources.excludes.addAll(
             listOf(

app/src/main/res/values/strings.xml

@@ -1,3 +0,0 @@
-<resources>
-    <string name="app_name">Zcash</string>
-</resources>

app/src/zcashtestnet/res/values/strings.xml

@@ -1,6 +1,4 @@
 <resources>
-    <string name="app_name">Zcash (Testnet)</string>
-
     <!-- Important; this is the resource overlay that sets the Zcash network -->
     <string name="network_name">Testnet</string>
 </resources>

docs/Setup.md

@@ -162,7 +162,7 @@ Although the goal of this document is to enable readers to build the app from so
     1. If using a physical device, run the terminal command `adb install -r $PATH_TO_APK`
     
 Notes:
- - Android apps can have build variants (debug, release) and build flavors (mainnet, testnet).  Debug builds are up to 10x slower due to JIT being disabled by Android's runtime, so they should not be used for benchmarks.  Debug builds also have logging enabled.
+ - Android apps can have build variants (debug, release) and build flavors (mainnet, testnet).  Debug builds are up to 10x slower due to JIT being disabled by Android's runtime, so they should not be used for benchmarks.  Debug builds also have logging enabled.  By convention, debug builds have a different package name which means that both a release build from Google Play and a debug build for development can be installed simultaneously.  Another difference is that release builds are processed with R8 which performs "tree shaking" to reduce the size of the final app by stripping unused code and performing code level optimizations.
  - Apps can be distributed in two different formats: Application Package (APK) and Android App Bundle (AAB).  AAB is uploaded to Google Play, and allows the store to deliver device-specific slices (e.g. CPU architecture, screen size, etc) for smaller downloads.  APK is the format for sideloading.  APK files are the original format from Android 1.0, and can be generated directly from a Gradle build.  AAB files are a newer format, and APK files can also be derived from AAB.  A "universal" APK is one that was derived from an AAB without any slicing.  We use "universal" APKs for testing of release builds, as they are processed through bundletool (which has introduced bugs in the past) and therefore somewhat closer to what would be delivered to end user devices.
  - Android apps must be digitally signed.  The signing key is critical to app sandbox security (preventing other apps from reading our app's data).  We have multiple signing configurations:
    - If you build from source, your computer will generate a random debug signing key.  This key will be consistent for multiple builds, allowing you to keep re-deploying changes of the app.  But if you connect your physical Android device to a different computer, the debug key will be different and therefore the app will need to be uninstalled/reinstalled to update it.

gradle.properties

@@ -42,6 +42,15 @@ IS_MINIFY_ENABLED=true
 ZCASH_VERSION_CODE=1
 ZCASH_VERSION_NAME=0.1
 
+# Set these fields, as you need them (e.g. with values "Zcash X" and "co.electriccoin.zcash.x")
+# to distinguish a different release build that can be installed alongside the official version
+# available on Google Play.  This is particularly useful for debugging R8 rules.
+# These are consumed by app/build.gradle.kts
+ZCASH_RELEASE_APP_NAME=Zcash
+ZCASH_RELEASE_PACKAGE_NAME=co.electriccoin.zcash
+
+ZCASH_DEBUG_APP_NAME_SUFFIX=" Debug"
+
 # Set keystore details to enable build signing.  Typically these
 # are overridden via ~/.gradle/gradle.properties to allow secure injection.
 # Debug keystore is useful if using Google Maps or Firebase, which require API keys to be linked