kmp-build-commands

name	kmp-build-commands
description	Gradle build commands: assembleDebug, assembleRelease, APK output paths, and emulator installation
applies_to	["scaffold","screens","branding","content"]
load_when	building the app, installing on emulator, or locating build artifacts

KMP Build Commands

The kmptv project uses Gradle with the Android Gradle Plugin. All builds run from the project root. The Android TV app produces an APK; the Apple TV app builds via Xcode.

Android TV builds

Debug APK (development)

./gradlew :androidtv-app:assembleDebug

Output: androidtv-app/build/outputs/apk/debug/androidtv-app-debug.apk

• Debuggable, not minified
• Fast build (~30-60s after first build)
• Use for emulator testing and development

Release APK (production)

./gradlew :androidtv-app:assembleRelease

Output: androidtv-app/build/outputs/apk/release/androidtv-app-release-unsigned.apk

• Minified (if proguard is enabled, currently disabled in template)
• Not debuggable
• Requires signing for device installation

Build both variants

./gradlew :androidtv-app:assemble

Installing on emulator

Prerequisites

• Android TV emulator running (API 34, TV profile recommended)
• Android CLI installed and initialized with android init
• adb in PATH for D-pad input and Logcat only

Build, install, and launch the debug APK

# Android CLI describes targets and expected output artifacts.
android describe --project_dir=.

# Gradle owns compilation.
./gradlew :androidtv-app:assembleDebug

# Android CLI owns deployment and launch.
android run \
  --apks=androidtv-app/build/outputs/apk/debug/androidtv-app-debug.apk \
  --device=<serial> \
  --activity=.MainActivity

Shared-core builds

Compile for Android target

./gradlew :shared-core:compileKotlinAndroid

Compile for iOS targets (requires macOS)

./gradlew :shared-core:compileKotlinIosArm64
./gradlew :shared-core:compileKotlinIosSimulatorArm64
./gradlew :shared-core:compileKotlinIosX64

Run all shared-core tests

./gradlew :shared-core:allTests

Generate iOS framework (for Apple TV app)

./gradlew :shared-core:linkDebugFrameworkIosSimulatorArm64

Output: shared-core/build/bin/iosSimulatorArm64/debugFramework/shared_core.framework

Full project builds

Compile everything

./gradlew compileKotlin

Clean build (when caches are stale)

./gradlew clean :androidtv-app:assembleDebug

Check dependencies

# Show dependency tree for androidtv-app
./gradlew :androidtv-app:dependencies --configuration releaseRuntimeClasspath

# Check for dependency updates (if plugin installed)
./gradlew dependencyUpdates

Apple TV builds (Xcode)

The Apple TV app is built via Xcode, not Gradle:

# Open in Xcode
open appletv-app/kmptv/kmptv.xcodeproj

# Build from command line
xcodebuild -project appletv-app/kmptv/kmptv.xcodeproj \
    -scheme kmptv \
    -destination 'platform=tvOS Simulator,name=Apple TV 4K (3rd generation)' \
    build

Build output locations

Artifact	Path
Debug APK	androidtv-app/build/outputs/apk/debug/androidtv-app-debug.apk
Release APK	androidtv-app/build/outputs/apk/release/androidtv-app-release-unsigned.apk
Lint report	androidtv-app/build/reports/lint-results-debug.html
Test results (shared-core)	shared-core/build/reports/tests/
iOS framework	shared-core/build/bin/iosSimulatorArm64/debugFramework/

Gradle wrapper

The project uses Gradle 8.9 via the wrapper. Always use ./gradlew (not a system-installed gradle):

# Check Gradle version
./gradlew --version

# Update wrapper (if needed)
./gradlew wrapper --gradle-version 8.9

Common build issues

SDK location not found

Fix: Create local.properties in project root:

sdk.dir=/Users/<username>/Library/Android/sdk

Or set ANDROID_HOME environment variable.

compileOptions / jvmToolchain mismatch

The project requires JDK 17:

kotlin { jvmToolchain(17) }

Fix: Ensure JAVA_HOME points to JDK 17:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)

Build cache is corrupted

./gradlew clean
rm -rf ~/.gradle/caches/transforms-*
./gradlew :androidtv-app:assembleDebug

Out of memory during build

Add to gradle.properties:

org.gradle.jvmargs=-Xmx4g -XX:+HeapDumpOnOutOfMemoryError

Emulator management

List available emulators

android emulator list

Start TV emulator

android emulator start <avd-name>

Check connected devices

adb devices

TV testing commands

# Android CLI owns layout and screenshot evidence.
android layout --pretty --output=layout.json
android screen capture --output=screenshot.png

# Android CLI has no remote-key command, so ADB sends D-pad events.
adb shell input keyevent KEYCODE_DPAD_UP
adb shell input keyevent KEYCODE_DPAD_DOWN
adb shell input keyevent KEYCODE_DPAD_LEFT
adb shell input keyevent KEYCODE_DPAD_RIGHT
adb shell input keyevent KEYCODE_DPAD_CENTER  # Select
adb shell input keyevent KEYCODE_BACK

# Android CLI has no Logcat command, so ADB captures logs.
adb logcat -s "kmptv" --format=brief

Anti-patterns

• Running ./gradlew assembleDebug from a subdirectory. Always run from project root where gradlew lives.
• Using gradle instead of ./gradlew. System Gradle may be a different version and break the build.
• Building release for development testing. Release builds are slower and not debuggable. Use debug for iteration.
• Skipping installDebug and manually copying the APK. installDebug handles uninstall-reinstall and is faster.
• Not checking adb devices before install. If no device is connected, installDebug fails silently or with a confusing error.