companion-app-base/doc.md

Wiring common into another app

This module provides a shared entry-point flow (splash → permissions → main), a permission-request helper, a tiny prefs wrapper, and AppCompat theme support. It carries its own version catalog, so it doesn't need anything from the consuming project's gradle/libs.versions.toml.

1. Get the module into the new project

Clone (or copy) this repo into the new project's root as a folder named common:

your-new-app/
  app/
  common/          ← this repo
  build.gradle.kts
  settings.gradle.kts

2. Wire it up in settings.gradle.kts

Add the module and register its catalog:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
    versionCatalogs {
        create("commonLibs") {
            from(files("common/gradle/libs.versions.toml"))
        }
    }
}

include(":common")

Make sure pluginManagement.repositories includes google(), mavenCentral(), and gradlePluginPortal() (needed to resolve the Android/Kotlin plugins declared in common's own catalog).

3. Depend on it from your app module

In app/build.gradle.kts:

dependencies {
    implementation(project(":common"))
}

Your app's own minSdk must be 31 or higher — that's what common targets.

4. Use BaseEntryPoint

Make your launcher activity extend it instead of writing splash/permission routing from scratch:

class EntryPoint : BaseEntryPoint() {
    override val mainActivityClass = MainActivity::class.java
    override val permissionsActivityClass = PermissionsActivity::class.java
    override val splashTitle = "Your App Name"

    override fun isSetupComplete(): Boolean =
        prefs.hasCompletedInitialPermissions // from the shared PrefManager
}

Declare it as the launcher activity in your manifest as usual (MAIN / LAUNCHER intent-filter). Optional overrides: splashLogoResId, handleIntent() (deep-link short-circuiting before the splash shows), showContent() (wrap the splash in your own theme instead of plain Material3).

5. Use PermissionManager in your permissions screen

val permissionManager = PermissionManager.create(context) {
    addPermissions(Manifest.permission.ACCESS_FINE_LOCATION)
    setPermissionName(Manifest.permission.ACCESS_FINE_LOCATION, "Location")
    includeInstallPermission(true) // if you need the "install unknown apps" flow
}

permissionManager.areAllPermissionsGranted()
permissionManager.requestAllMissingPermissions(activityResultLauncher)

6. Use PrefManager for the shared setup flags

val prefs = PrefManager(context)
prefs.hasCompletedInitialPermissions = true

Add your own app-specific flags directly to PrefManager.kt if needed — it's just a thin SharedPreferences wrapper (setupWizard_prefs).

Updating common later

Since it's its own git repo nested in each project, pull changes with a normal git pull from inside the common/ folder in each project that uses it. There's no submodule wiring — it's just a plain repo that happens to live inside a non-git parent project.