whitehall run

Build, install, and launch your app on a connected Android device or emulator.

Usage

whitehall run [options]

Basic Example

whitehall run

This command:

1. Transpiles .wh files to Kotlin
2. Builds an APK
3. Installs on connected device
4. Launches the app

Options

Release Build

Build and run an optimized release build:

whitehall run --release

Release builds are:

• Minified and obfuscated
• Optimized for performance
• Smaller in size
• Not debuggable

Specify Device

Run on a specific device when multiple are connected:

whitehall run --device emulator-5554
whitehall run --device 1A2B3C4D5E6F

List Devices

See all connected devices:

adb devices

Development Workflow

Quick Iteration

For rapid development, use watch mode in a separate terminal:

# Terminal 1: Watch for changes
whitehall build --watch

# Terminal 2: Run when ready
whitehall run

Hot Reload

Whitehall uses Compose's hot reload. After running once, most changes apply instantly without rebuilding:

whitehall run  # Initial run
# Edit .wh files - changes apply automatically

Device Setup

Physical Device

1. Enable Developer Options on your Android device
2. Enable USB Debugging
3. Connect via USB
4. Accept the debugging prompt

Emulator

Whitehall automatically detects running emulators. Start one with:

emulator -avd Pixel_7_API_34

Environment Selection

Environment files are loaded based on build type:

Debug Build (default)

Loads in order:

.env
.env.local
.env.debug
.env.debug.local

Release Build

Loads in order:

.env
.env.local
.env.release
.env.release.local

Logs and Debugging

View Logs

After running, view app logs with:

adb logcat | grep MyApp

Clear App Data

Reset app state between runs:

adb shell pm clear com.example.myapp

Uninstall

adb uninstall com.example.myapp

Common Issues

No Devices Found

Ensure a device is connected and authorized:

adb devices

Should show:

List of devices attached
1A2B3C4D5E6F    device

Installation Failed

If installation fails due to version conflict:

adb uninstall com.example.myapp
whitehall run

App Crashes on Launch

Check logs for errors:

adb logcat | grep -E "(AndroidRuntime|FATAL)"

Performance

Build Times

• First build: 30-60 seconds (downloads dependencies)
• Incremental builds: 5-10 seconds
• Hot reload: Instant

Speed Up Builds

Use watch mode to keep the build system warm:

whitehall build --watch

CI/CD Integration

For automated testing and deployment:

# GitHub Actions example
- name: Run tests
  run: |
    whitehall build --release
    whitehall test

Advanced Options

Custom Build Directory

Specify output location in whitehall.toml:

[build]
output_dir = "dist"

Skip Installation

Build APK without installing:

whitehall build

Install Existing APK

adb install build/outputs/apk/debug/app-debug.apk

Comparison with Android Studio

Feature	Whitehall	Android Studio
Build + Run	whitehall run	Click Run button
Hot Reload	Automatic	Apply Changes
Setup	Zero config	Manual SDK setup
Toolchain	Auto-managed	Manual updates

See Also

• whitehall build - Build without running
• whitehall init - Create new project
• Environment Variables - Configure app settings