whitehall build

Transpile Whitehall code to Kotlin and build APK/AAB files.

Usage

whitehall build [options]

Basic Build

Transpile .wh files to Kotlin and build debug APK:

whitehall build

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

Options

Release Build

Build signed, minified release APK:

whitehall build --release

Release builds:

ProGuard/R8 minification and obfuscation
Optimized for size and performance
Require signing configuration

Watch Mode

Automatically rebuild when files change:

whitehall build --watch

Perfect for development - keep this running while you edit:

# Terminal 1
whitehall build --watch

# Terminal 2
whitehall run

Transpile Only

Convert .wh to .kt without building APK:

whitehall compile

Useful for:

Inspecting generated Kotlin code
Using Whitehall with existing Android projects
CI/CD pipelines that build separately

Build Outputs

Debug APK

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

Release APK

build/outputs/apk/release/app-release.apk

Android App Bundle (AAB)

For Play Store distribution:

whitehall build --release --aab

Output: build/outputs/bundle/release/app-release.aab

Configuration

Output Directory

Customize in whitehall.toml:

[build]
output_dir = "dist"

Signing Configuration

For release builds, configure signing:

[android.signing]
keystore = "release.keystore"
alias = "release"

Set keystore password via environment:

# .env.release
KEYSTORE_PASSWORD=your-password
KEY_PASSWORD=your-key-password

Build Process

The build command performs these steps:

Transpile .wh files to Kotlin
Generate routing code
Generate ViewModel bindings
Run Kotlin compiler
Package into APK/AAB
Sign (if release)
Align (if release)

Environment Variables

Build type determines which env files are loaded:

Debug

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

Release

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

Optimization

ProGuard Rules

Add custom ProGuard rules in proguard-rules.pro:

# Keep data classes for serialization
-keep class com.example.myapp.models.** { *; }

Build Cache

Whitehall uses Gradle build cache for faster incremental builds:

# First build: 30-60s
whitehall build

# Incremental: 5-10s
whitehall build

Parallel Builds

Enabled by default. Configure in whitehall.toml:

[build]
parallel = true
max_workers = 4

Size Analysis

Analyze APK size after building:

whitehall build --release
unzip -l build/outputs/apk/release/app-release.apk | sort -nk1

Clean Build

Remove all build artifacts:

whitehall clean

Or manually:

rm -rf build/

Troubleshooting

Build Failed

Check the error output. Common issues:

Syntax errors in .wh files
Missing dependencies
Out of memory (increase heap size)

Out of Memory

Increase Gradle heap size:

export GRADLE_OPTS="-Xmx4g"
whitehall build

Slow Builds

Speed up with:

Watch mode: whitehall build --watch
Parallel builds (enabled by default)
Build cache (enabled by default)

Stale Generated Code

Clean and rebuild:

whitehall clean
whitehall build

CI/CD Integration

GitHub Actions

name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Whitehall
        run: cargo install whitehall

      - name: Build Release
        run: whitehall build --release

      - name: Upload APK
        uses: actions/upload-artifact@v3
        with:
          name: app-release.apk
          path: build/outputs/apk/release/app-release.apk

GitLab CI

build:
  script:
    - cargo install whitehall
    - whitehall build --release
  artifacts:
    paths:
      - build/outputs/apk/release/app-release.apk

Comparison: Build vs Compile vs Run

Command	Transpile	Build APK	Install	Launch
`compile`	✓	✗	✗	✗
`build`	✓	✓	✗	✗
`run`	✓	✓	✓	✓