From dacbd49e41668ca750266232529661f3b692db01 Mon Sep 17 00:00:00 2001 From: Rohit Luthra Date: Wed, 22 Apr 2026 07:43:22 +0530 Subject: [PATCH] Refine Authenticator App opt-in documentation and add fail-fast check for missing checkout --- README.md | 38 ++++++++++++-------------------------- gradle.properties | 29 ++++++++++++++--------------- settings.gradle | 26 ++++++++++++++++++++++++++ 3 files changed, 52 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 4645e34b..30c26d06 100644 --- a/README.md +++ b/README.md @@ -91,46 +91,32 @@ For MSAuthenticator, please use "devDebug" to test against PROD, and "integratio ## Authenticator App (Opt-in) -Authenticator modules are **excluded by default** to keep Gradle sync/build fast for developers who don't work on Authenticator. To enable them, set `includeAuthenticatorApp=true` in one of these locations (highest priority wins): - -| Priority | Location | Scope | Committed? | -|----------|----------|-------|------------| -| 1 (highest) | `./gradlew -PincludeAuthenticatorApp=true` | Single invocation | No | -| 2 | `~/.gradle/gradle.properties` | All projects on your machine | No | -| 3 | `gradle.properties` | Everyone who clones the repo | Yes | -| 4 (lowest) | `local.properties` | This checkout only (gitignored) | No | - -**Recommended for most developers** — add to `local.properties` (create it if it doesn't exist): +Authenticator modules are **excluded by default** so Gradle sync/build stays fast for developers who don't work on Authenticator. To enable them, edit the **root `gradle.properties`** — not the one in `authenticator/` but the one at the root of the repo. Turn these two lines ON: ```properties includeAuthenticatorApp=true android.enableJetifier=true ``` -> **Jetifier is required.** Some Authenticator dependencies (e.g. Samsung Knox supportlib, MsaSdk .aar) use the legacy Android Support Library. `android.enableJetifier=true` rewrites their bytecode to AndroidX at build time. Without it you'll get `ClassNotFoundException` at runtime. +Then re-sync Gradle in Android Studio. That's it — one file, two lines. -### How it works +#### If `authenticator/` isn't on disk yet -- **Gradle** (`settings.gradle` / `build.gradle`): The flag gates the AuthApp Maven feed registration and all Authenticator module includes. -- **Git aliases** (`.gitconfig`): The `droid*` commands (e.g. `droidSetup`, `droidNewFeature`, `droidPull`) use `scripts/resolve-include-authenticator.sh` to check the same flag with the same priority order. When enabled, they clone/pull/push the authenticator repo alongside the other repos. - -### Quick reference +Flipping the flag to `true` in a checkout where `droidSetup` was previously run with Authenticator disabled will cause Gradle sync to fail fast with a clear message. The fix is: ```bash -# Enable for this checkout only -echo "includeAuthenticatorApp=true" >> local.properties -echo "android.enableJetifier=true" >> local.properties - -# Enable globally (all android-complete checkouts) -echo "includeAuthenticatorApp=true" >> ~/.gradle/gradle.properties +git droidSetup # idempotent — clones only what's missing +``` -# One-off build with Authenticator -./gradlew -PincludeAuthenticatorApp=true :MSAuthenticator:assembleDevDebug +If `authenticator/` exists but looks partial (e.g. `authenticator/PhoneFactor/` is missing), remove it first: -# One-off build WITHOUT Authenticator (overrides gradle.properties default) -./gradlew -PincludeAuthenticatorApp=false assembleLocalDebug +```bash +rm -rf authenticator && git droidSetup ``` +#### To opt back out + +Flip both flags back to `false` in `gradle.properties` and re-sync. The `authenticator/` checkout can stay on disk — Gradle simply won't include it. ## Projects Properties (Command Line Build flags) We support a number of different project properties as command line flags across some of our modules. Please read the doc on [Gradle Project Properties](./docs/ProjectBuild/gradle_project_properties.md) to learn more about them. diff --git a/gradle.properties b/gradle.properties index ed17cc13..67f91b5e 100755 --- a/gradle.properties +++ b/gradle.properties @@ -17,22 +17,21 @@ org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemor # This the TSL versionName... versionName=1.5.9 -# Authenticator App opt-in flag (default: false). -# When false, all Authenticator modules are excluded from the build, giving a -# leaner and faster Gradle sync/build for developers who don't work on Authenticator. -# To enable, set to true in one of the following (highest priority wins): -# 1. Command line: ./gradlew -PincludeAuthenticatorApp=true ... -# 2. ~/.gradle/gradle.properties (per-user, never committed) -# 3. local.properties (per-checkout, gitignored) -# 4. This file (committed default for everyone) +# Authenticator App opt-in switch. # -# IMPORTANT: When enabling Authenticator, you must ALSO set android.enableJetifier=true. -# Some Authenticator dependencies (e.g. Samsung Knox supportlib, MsaSdk .aar blobs) were -# compiled against the legacy Android Support Library. Jetifier rewrites their bytecode to -# use AndroidX at build time. Without it, you will get ClassNotFoundException at runtime. -# Add both flags to your local.properties or ~/.gradle/gradle.properties: -# includeAuthenticatorApp=true -# android.enableJetifier=true +# This file is the single source of truth for toggling the Authenticator app +# sub-project on/off for your local build. Flip the two lines below: +# +# includeAuthenticatorApp=true ? includes all Authenticator modules +# includeAuthenticatorApp=false ? excludes them (leaner, faster sync) +# +# +# IMPORTANT ? Jetifier pairing: +# When includeAuthenticatorApp=true, android.enableJetifier MUST also be true. +# Some Authenticator dependencies (Samsung Knox supportlib, MsaSdk .aar blobs) +# were compiled against the legacy Android Support Library; Jetifier rewrites +# their bytecode to AndroidX at build time. Without it you'll hit +# ClassNotFoundException at runtime. Always flip both flags together. includeAuthenticatorApp=false android.enableJetifier=false diff --git a/settings.gradle b/settings.gradle index b40b6535..97a748c6 100644 --- a/settings.gradle +++ b/settings.gradle @@ -100,6 +100,32 @@ pluginManagement { // local variable so the module-include section below reads naturally. def includeAuthenticatorApp = settings.ext.includeAuthenticatorApp +// Fail fast when the opt-in flag is set but the authenticator/ checkout is missing +// or incomplete. Without this, Gradle would emit a confusing cascade of "project +// directory does not exist" errors deep in the include() calls below. +def __authenticatorDir = new File(settings.rootDir, 'authenticator') +def __authenticatorPhoneFactorDir = new File(__authenticatorDir, 'PhoneFactor') +if (includeAuthenticatorApp && !__authenticatorPhoneFactorDir.isDirectory()) { + def __msg + if (!__authenticatorDir.exists()) { + // Case 1: nothing cloned yet. + __msg = "includeAuthenticatorApp=true but authenticator/ is not checked out.\n" + + " Fix: re-run git droidSetup (clones only what's missing)." + } else { + // Case 2: authenticator/ exists but is empty / partial / wrong contents. + // git clone refuses to write into a non-empty directory, so droidSetup alone + // won't recover — the stale folder has to be removed first. + __msg = "includeAuthenticatorApp=true and authenticator/ exists, but " + + "authenticator/PhoneFactor/ is missing (partial or stale checkout).\n" + + " Fix: delete the folder and re-run droidSetup:\n" + + " rm -rf authenticator && git droidSetup" + } + throw new GradleException( + __msg + "\n" + + " To build without Authenticator instead, set includeAuthenticatorApp=false " + + "in gradle.properties (or ~/.gradle/gradle.properties).") +} + rootProject.name = 'android_auth' // Android DevX Projects