android

Android Skill

Build, deploy, and debug Pulp on Android. This skill captures the architecture decisions and hard-won gotchas from the Android platform bringup.

Pre-flight: plugin ↔ CLI skew check

Before running pulp doctor android / pulp build / pulp ship for Android work, source the shared skew-check helper so a user on an outdated CLI sees a one-line hint (stderr, once per session) before wrestling with a confusing flag-missing error:

source "$(git rev-parse --show-toplevel)/tools/scripts/cli_version_check.sh"
pulp_cli_version_check

Advisory only. Full release-discovery contract in the upgrade skill.

Architecture Overview

Kotlin (Android UI)          C++ (Pulp core)
├── PulpApplication          ├── libpulp.so (arm64)
│   └── System.loadLibrary   │   ├── core/* subsystems
├── PulpSurfaceView          │   ├── Dawn (Vulkan backend)
│   ├── SurfaceHolder.Cb     │   ├── Skia Graphite
│   └── onTouchEvent ──JNI──→│   └── Oboe audio
├── PulpActivity             │
├── PulpAudioService         └── gpu_surface_android.cpp
└── PulpMidiService              ├── Surface lifecycle
                                 ├── Touch → View routing
                                 └── Widget hierarchy

Key Files

File	Purpose
tools/cmake/PulpAndroid.cmake	NDK toolchain integration, Oboe, platform wiring
core/render/platform/android/gpu_surface_android.cpp	Vulkan surface, touch routing, widget hierarchy
android/app/src/main/kotlin/com/pulp/render/PulpSurfaceView.kt	SurfaceView + touch dispatch
android/app/src/main/kotlin/com/pulp/PulpApplication.kt	JNI load, lifecycle
core/platform/src/android/jni_bridge.cpp	JNI_OnLoad, class caching, exception guards
tools/build-skia-android.sh	Skia Graphite + Dawn arm64 build script

Branch & Worktree

Android work lives on feature/android-targeting, typically in a worktree at ../pulp-android:

# Create worktree (if not already present)
git worktree add ../pulp-android feature/android-targeting

# Always work in the worktree, not the main repo
cd ../pulp-android