1. Enable Developer options: Settings > About phone > tap Build number 7 times
2. Disable auto-blocker if present (Samsung): Settings > Security > Auto Blocker
3. Enable wireless debugging: Settings > Developer options > Wireless debugging
4. Tap Pair device with pairing code and note the IP:port
5. Pair and connect:

   just pair-android 192.168.1.100:37000  # Enter pairing code when prompted
   just list-android                       # Get device ID
   just run-android DEVICE_ID
   

just build-android              # Build only (windowed app)
just build-android-all          # Build for arm64 and x64
just build-android-openxr       # Build for Meta Quest VR
just install-android DEVICE_ID  # Install without running
just connect-android IP:PORT    # Connect over wireless ADB
just list-android               # List connected devices
just run-android-x64 DEVICE_ID  # Run x86_64 build (for emulators / x64 devices)
just start-android-emulator AVD # Launch a local Google AVD with host GPU
just list-android-emulators     # List local AVDs

For local testing without a physical device. Use Google's emulator with -gpu host, which routes graphics through the host GPU via gfxstream; wgpu's Vulkan/GLES path works there. Third-party emulators like MuMu and BlueStacks do not work: their legacy libEGL_emulation.so driver leaves the ANativeWindow bound after wgpu's Vulkan adapter probe, so the GLES surface fails with EGL_BAD_ALLOC → Surface::configure: Invalid surface.

Apple Silicon Macs: the snippets below use x86_64 system images and just run-android-x64. On ARM Macs, swap x86_64 for arm64-v8a everywhere (system-image package, the avdmanager create avd -k argument), and run the app with the existing just run-android recipe (arm64) instead of run-android-x64. HVF can't accelerate x86_64 guests on ARM hosts, so the x64 path falls back to a software rasterizer and won't hit your GPU.

1. Install the Android SDK + emulator. Easiest path is Android Studio - run it once and walk through the setup wizard, which installs platform-tools, emulator, a system image, and creates a default AVD.

If you'd rather stay on the command line, install the cmdline-tools and use sdkmanager:

Then accept licenses and install components (set ANDROID_HOME to your SDK root first):

sdkmanager --licenses    # On Windows PowerShell, see note below
sdkmanager --install "platform-tools" "emulator" "platforms;android-34" "system-images;android-34;google_apis;x86_64"

just start-android-emulator uses $ANDROID_HOME directly, so it works without PATH setup as long as ANDROID_HOME is set. scoop sets it persistently during android-clt install; the brew cask only prints a caveats block (you'll need to export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools or similar in your shell rc); on a manual Linux install you set it yourself. If you also want to run emulator, adb, or avdmanager directly from your shell, add the relevant subdirs to PATH:

# Windows (one-time, persists in user PATH; restart shell to pick up)
$dirs = "$env:ANDROID_HOME\emulator", "$env:ANDROID_HOME\platform-tools", "$env:ANDROID_HOME\cmdline-tools\latest\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path","User") + ";" + ($dirs -join ";"), "User")

# macOS / Linux (add to ~/.zshrc or ~/.bashrc)
export PATH="$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"

Windows PowerShell note: stdin piping to sdkmanager --licenses is unreliable. Either run it from cmd.exe (yes | sdkmanager --licenses), or write the license accept files directly, see the snippet at the bottom of this section.

2. Verify hardware acceleration.

emulator -accel-check

Expect WHPX/HVF/KVM is installed and usable. On Windows 11, WHPX is on by default; if not, run Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All from an admin shell and reboot. macOS uses HVF with no setup. On Linux, install qemu-kvm and add yourself to the kvm group (sudo usermod -aG kvm $USER, then log out/in).

3. Create an AVD (skip if Studio's wizard already made one; just list-android-emulators shows existing):

echo no | avdmanager create avd -n wgpu_test -k "system-images;android-34;google_apis;x86_64" -d "pixel_6"

4. Launch the emulator and run the app:

just start-android-emulator wgpu_test    # in one shell
just run-android-x64 emulator-5554       # in another

just run-android-x64 requires xbuild from git master - cargo install xbuild from crates.io ships v0.2.0 which has a linker bug for --arch x64 (passes --target=aarch64-linux-android to clang while linking x86_64 objects). just init-android already pulls from master.

The recipe also creates libs/x86_64/ on demand. xbuild's runtime_libs scan in manifest.yaml requires the per-ABI directory to exist for any ABI you build, even though the repo only ships libs/arm64-v8a/libopenxr_loader.so for Quest.

$licDir = Join-Path $env:ANDROID_HOME "licenses"
New-Item -Path $licDir -ItemType Directory -Force | Out-Null
@{
  "android-sdk-license"           = "24333f8a63b6825ea9c5514f83c2829b004d1fee`nd56f5187479451eabf01fb78af6dfcb131a6481e`n8933bad161af4178b1185d1a37fbf41ea5269c55"
  "android-sdk-preview-license"   = "84831b9409646a918e30573bab4c9c91346d8abd"
  "android-googletv-license"      = "601085b94cd77f0b54ff86406957099ebe79c4d6"
  "google-gdk-license"            = "33b6a2b64607f11b759f320ef9dff4ae5c47d97a"
  "mips-android-sysimage-license" = "e9acab5b5fbb560a72cfaecce8946896ff6aab9d"
  "android-sdk-arm-dbt-license"   = "859f317696f67ef3d7f30a50a5560e7834b43903"
  "intel-android-extra-license"   = "d975f751698a77b662f1254ddbeed3901e976f5a"
}.GetEnumerator() | ForEach-Object {
  Set-Content -Path (Join-Path $licDir $_.Key) -Value $_.Value -NoNewline -Encoding ASCII
}

• Uses the android-openxr feature which combines android and openxr features
• Bundles Meta's OpenXR loader from libs/arm64-v8a/libopenxr_loader.so
• Manifest includes com.oculus.intent.category.VR for proper VR app handling
• Supports Quest hand tracking and controller input
• Requires manifest.yaml with runtime_libs configuration for library bundling