Android Build System

Android Build System

Expert reference for configuring Android app builds in two environments:

1. Android Studio / Gradle — Kotlin DSL, Version Catalogs, Convention Plugins, KSP.
2. AOSP / Soong — Android.bp, Android.mk, product packages, signing, partition placement.

When to Use This Skill

• Setting up a new app module in build.gradle.kts.
• Adding a dependency and unsure of scope (api vs implementation).
• Migrating a KAPT annotation processor to KSP.
• Creating a Convention Plugin for shared build logic.
• Writing or reviewing an Android.bp android_app module.
• Choosing signing certificate or partition for an AOSP app.
• Debugging m, mma, or Gradle sync failures.

Part 1: Android Studio — Gradle (Kotlin DSL)

Project structure

root/
├── build.gradle.kts                # root: only plugin repos, project-level config
├── settings.gradle.kts             # include modules, management plugins
├── gradle/
│   └── libs.versions.toml          # Version Catalog
├── build-logic/                    # Convention Plugins
│   ├── settings.gradle.kts
│   └── convention/
│       ├── build.gradle.kts
│       └── src/main/kotlin/
│           ├── AndroidApplicationConventionPlugin.kt
│           └── AndroidLibraryConventionPlugin.kt
├── app/
│   └── build.gradle.kts
└── feature/home/
    └── build.gradle.kts

Version Catalog (gradle/libs.versions.toml)

[versions]
agp = "8.4.0"
kotlin = "1.9.24"
compose-bom = "2024.05.00"
hilt = "2.51"
room = "2.6.1"
retrofit = "2.11.0"
coroutines = "1.8.1"
mockk = "1.13.11"
turbine = "1.1.0"

[libraries]
# AndroidX Core
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version = "1.13.1" }
androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version = "2.8.0" }

# Compose BOM (manages all compose versions via BOM)
compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
compose-ui = { group = "androidx.compose.ui", name = "ui" }
compose-material3 = { group = "androidx.compose.material3", name = "material3" }
compose-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
compose-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }

# Hilt
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
hilt-compiler = { group = "com.google.dagger", name = "hilt-compiler", version.ref = "hilt" }
hilt-android-testing = { group = "com.google.dagger", name = "hilt-android-testing", version.ref = "hilt" }

# Room
room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }

# Network
retrofit = { group = "com.squareup.retrofit2", name = "retrofit", version.ref = "retrofit" }
okhttp-logging = { group = "com.squareup.okhttp3", name = "logging-interceptor", version = "4.12.0" }

# Testing
junit4 = { group = "junit", name = "junit", version = "4.13.2" }
mockk = { group = "io.mockk", name = "mockk", version.ref = "mockk" }
turbine = { group = "app.cash.turbine", name = "turbine", version.ref = "turbine" }
kotlinx-coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "coroutines" }
truth = { group = "com.google.truth", name = "truth", version = "1.4.2" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
ksp = { id = "com.google.devtools.ksp", version = "1.9.24-1.0.20" }
room = { id = "androidx.room", version.ref = "room" }

[bundles]
compose = ["compose-ui", "compose-material3", "androidx-lifecycle-runtime-ktx"]
testing-unit = ["junit4", "mockk", "turbine", "kotlinx-coroutines-test", "truth"]

Convention Plugins

Convention Plugins centralise shared build logic in build-logic/. Each feature module adds a single plugin instead of duplicating config.

// build-logic/convention/src/main/kotlin/AndroidApplicationConventionPlugin.kt
class AndroidApplicationConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(pluginManager) {
                apply("com.android.application")
                apply("org.jetbrains.kotlin.android")
                apply("com.google.dagger.hilt.android")
                apply("com.google.devtools.ksp")
            }
            extensions.configure<ApplicationExtension> {
                configureKotlinAndroid(this)
                defaultConfig.targetSdk = 34
            }
        }
    }
}

// Shared AndroidOptions extension
internal fun Project.configureKotlinAndroid(commonExtension: CommonExtension<*, *, *, *, *, *>) {
    commonExtension.apply {
        compileSdk = 34
        defaultConfig { minSdk = 30 }
        compileOptions {
            sourceCompatibility = JavaVersion.VERSION_17
            targetCompatibility = JavaVersion.VERSION_17
        }
        kotlinOptions { jvmTarget = "17" }
    }
}

// build-logic/convention/build.gradle.kts
plugins { `kotlin-dsl` }
dependencies {
    compileOnly(libs.agp)
    compileOnly(libs.kotlin.gradle.plugin)
}
gradlePlugin {
    plugins {
        register("androidApplication") {
            id = "myapp.android.application"
            implementationClass = "AndroidApplicationConventionPlugin"
        }
    }
}

// app/build.gradle.kts — minimal!
plugins {
    alias(libs.plugins.myapp.android.application)  // convention plugin
}
android {
    namespace = "com.example.myapp"
    defaultConfig { applicationId = "com.example.myapp" }
    signingConfigs { ... }
}
dependencies {
    implementation(project(":feature:home"))
    implementation(libs.bundles.compose)
    ksp(libs.hilt.compiler)
}

Dependency Scopes

Rules

• Prefer implementation over api — leaking transitive dependencies causes slow builds.
• Use ksp instead of kapt for all new annotation processors.
• Use Compose BOM — do not specify Compose library versions individually.

Build Variants

android {
    buildTypes {
        debug {
            applicationIdSuffix = ".debug"
            isDebuggable = true
            isMinifyEnabled = false
        }
        release {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
        }
    }
    productFlavors {
        flavorDimensions += "target"
        create("phone") { dimension = "target" }
        create("automotive") {
            dimension = "target"
            applicationIdSuffix = ".auto"
        }
    }
}

Build Performance

// gradle.properties
org.gradle.configuration-cache=true        # cache task graph between builds
org.gradle.caching=true                    # reuse task outputs from cache
org.gradle.parallel=true                   # parallel module compilation
org.gradle.daemon=true                     # keep Gradle in memory
kotlin.incremental=true
android.enableR8.fullMode=true             # better shrinking

• Use ksp (not kapt) — 2× faster annotation processing.
• Keep :core:* modules small and stable — they are on the critical compilation path.
• Avoid api dependencies — transitive dependency changes force consumer recompilation.

Part 2: AOSP — Soong Build System (Android.bp)

android_app module

android_app {
    name: "MyCarApp",

    // Source
    srcs: ["src/**/*.kt", "src/**/*.java"],
    resource_dirs: ["res"],
    asset_dirs: ["assets"],
    manifest: "AndroidManifest.xml",

    // Dependencies
    static_libs: [
        // Jetpack (bundled in AOSP)
        "androidx.appcompat_appcompat",
        "androidx.lifecycle_lifecycle-viewmodel-ktx",
        "androidx.navigation_navigation-fragment-ktx",
        "car-ui-lib",
        "hilt_android",
    ],
    libs: [
        "android.car",         // platform lib — link only, not bundled
    ],

    // Build config
    sdk_version: "current",        // prefer over platform_apis
    min_sdk_version: "30",
    target_sdk_version: "34",

    // Signing & placement
    certificate: "platform",       // platform, shared, media, testkey
    privileged: true,              // /system/priv-app
    product_specific: true,        // /product/priv-app (if product_specific + privileged)

    // Kotlin
    kotlincflags: ["-Xjvm-default=all"],

    // Annotation processors
    plugins: ["hilt_compiler"],

    // Optimization
    dex_preopt: { enabled: true, profile: "profile.txt" },

    // Lint
    lint: { strict: ["NewApi"], warning: ["MissingPermission"] },
}

android_library module

android_library {
    name: "MyCarLib",
    srcs: ["src/**/*.kt"],
    resource_dirs: ["res"],
    manifest: "AndroidManifest.xml",
    static_libs: ["androidx.core_core-ktx"],
    sdk_version: "current",
    apex_available: ["//apex_available:platform"],
}

java_library (pure Kotlin/Java, no Android)

java_library {
    name: "MyDomainLib",
    srcs: ["src/**/*.kt"],
    sdk_version: "current",
    libs: ["kotlin-stdlib"],
}

Signing Certificates

Rules

• Never use testkey in production flash images.
• platform certificate allows sharing UID with system — only when strictly needed.
• For custom OEM certificates: certificate: "vendor/oem/certs/mykey".

Partition Placement

Product Package Inclusion

# device/oem/product/my_product.mk
PRODUCT_PACKAGES += \
    MyCarApp \
    MyCarLib

Legacy Android.mk (read-only reference)

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)

LOCAL_MODULE_TAGS := optional
LOCAL_PACKAGE_NAME := MyCarApp
LOCAL_SRC_FILES := $(call all-subdir-java-files)
LOCAL_RESOURCE_DIR := $(LOCAL_PATH)/res
LOCAL_MANIFEST_FILE := AndroidManifest.xml

LOCAL_STATIC_JAVA_LIBRARIES := \
    androidx.appcompat_appcompat \
    car-ui-lib

LOCAL_JAVA_LIBRARIES := android.car

LOCAL_CERTIFICATE := platform
LOCAL_PRIVILEGED_MODULE := true
LOCAL_PRODUCT_MODULE := true

include $(BUILD_PACKAGE)

Rule: Prefer Android.bp (Soong) for all new modules. Android.mk is legacy and not supported in Bazel/Soong hybrid builds.

Common AOSP Build Commands

# Initialize build environment
source build/envsetup.sh
lunch <product>-<variant>       # e.g., aosp_car_x86_64-userdebug

# Build specific module
m MyCarApp                      # build + place in out/
mma                             # build current dir + dependencies
mmm packages/apps/MyCarApp      # build specific directory

# Install to running device
adb install out/target/product/<product>/product/priv-app/MyCarApp/MyCarApp.apk
# or
adb sync product                # sync entire product partition

# Check installed module
adb shell pm list packages -f | grep MyCarApp

Prerequisites

• Android Studio (Flamingo or newer) or AOSP build environment set up.
• Android SDK Platform-Tools installed (adb on PATH).
• Target device or emulator running Android 11+ (API 30+).
• For AOSP modules: repo tool, AOSP source synced, lunch target configured.

Step-by-Step Workflows

Step 1: Identify the build environment

Determine whether you are working in Android Studio (Gradle) or AOSP (Soong / Android.bp).

Step 2: Configure dependencies / modules

Add dependencies in build.gradle.kts (Gradle) or Android.bp (Soong).

Step 3: Define build variants or module types

Set up buildTypes and productFlavors (Gradle) or cc_library / android_app (Soong).

Step 4: Build and resolve errors

Run ./gradlew assembleDebug (Gradle) or m <module> (AOSP); fix any reported errors.

Step 5: Sign and package for release

Configure signing configs (Gradle) or certificate field (Soong) for release builds.

Troubleshooting

• Duplicate class Gradle error — conflicting transitive dependency versions; use implementation(enforcedPlatform(...)) or resolutionStrategy.force.
• AOSP ninja: error: ... during m — check Android.bp syntax with bpfmt -w Android.bp; look for circular dependencies.
• Gradle build cache miss slowing CI — enable org.gradle.caching=true in gradle.properties; configure a remote build cache.
• APK not signed for release — configure signingConfigs in build.gradle.kts and reference it in the release build type.

Pre-Commit Checklist

Gradle

• New dependencies use Version Catalog aliases, not string literals.
• Scope is implementation, not api, unless intentionally exposing the API.
• KSP used for annotation processors, not KAPT.
• Convention Plugin used for shared build config, not copy-pasted blocks.
• Configuration Cache enabled and not broken by the change.

AOSP Soong

• Android.bp module name is PascalCase and unique in the product.
• Correct sdk_version — prefer "current" over platform_apis: true.
• certificate matches security requirements (dev vs release).
• Partition (privileged, product_specific, vendor) is intentional.
• PRODUCT_PACKAGES updated in product .mk file.
• App builds and installs with m MyModule ; adb sync.

References

• Gradle Kotlin DSL
• Android Gradle Plugin docs
• Version Catalogs
• Soong Build System (AOSP)
• Android.bp Reference
• Now in Android — build-logic