agentleFS
giolaqgiolaq/tv-build-harness/skills/kmp-build-commands/SKILL.md

kmp-build-commands

Skill4 starsChanged 5 months agoMIT-0View on GitHub

Gradle build commands: assembleDebug, assembleRelease, APK output paths, and emulator installation

  • Deletes or force-pushes

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use for emulator testing and development

    line 24
  2. Very specific:

    Fix: Create local.properties in project root:

    line 163
  3. Very specific:

    Fix: Ensure JAVA_HOME points to JDK 17:

    line 177
  4. Very specific:

    Running ./gradlew assembleDebug from a subdirectory: Always run from project root where gradlew lives.

    line 238
  5. Very specific:

    Not checking adb devices before install: If no device is connected, installDebug fails silently or with a confusing error.

    line 242

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

ArtifactPath
Debug APKandroidtv-app/build/outputs/apk/debug/androidtv-app-debug.apk
Release APKandroidtv-app/build/outputs/apk/release/androidtv-app-release-unsigned.apk
Lint reportandroidtv-app/build/reports/lint-results-debug.html
Test results (shared-core)shared-core/build/reports/tests/
iOS frameworkshared-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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.