alfred-mobile/BUILD_INSTRUCTIONS.md

# Alfred Mobile - Build Instructions

## Quick Start

### Environment Variables

Before building, set these environment variables:

```bash
export JAVA_HOME=~/android-dev/jdk-17.0.2
export ANDROID_HOME=~/android-dev/android-sdk
export PATH=$JAVA_HOME/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH
```

### Build Commands

```bash
# Navigate to project
cd ~/.openclaw/workspace/alfred-mobile

# List available tasks
./gradlew tasks

# Build debug APK
./gradlew assembleDebug

# Build release APK (requires signing config)
./gradlew assembleRelease

# Run unit tests
./gradlew test

# Clean build
./gradlew clean

# Check project dependencies
./gradlew dependencies
```

### Build Output

Debug APK will be located at:
```
app/build/outputs/apk/debug/app-debug.apk
```

Release APK will be located at:
```
app/build/outputs/apk/release/app-release-unsigned.apk
```

## Installing on Device

### Via ADB (Android Debug Bridge)

```bash
# List connected devices
adb devices

# Install debug APK
adb install app/build/outputs/apk/debug/app-debug.apk

# Or use Gradle
./gradlew installDebug

# Uninstall
adb uninstall com.openclaw.alfred
```

## Development on Windows

If you prefer to use Android Studio on Windows:

1. **Install Android Studio** from https://developer.android.com/studio

2. **Clone the repository** (in Windows, not WSL):
   ```cmd
   cd C:\Development
   git clone https://repo.anhonesthost.net/jknapp/alfred-mobile.git
   ```

3. **Open in Android Studio**:
   - File → Open → Select alfred-mobile folder
   - Wait for Gradle sync to complete
   - Click Run button or press Shift+F10

4. **Configure emulator** (if needed):
   - Tools → Device Manager
   - Create Virtual Device
   - Select a device definition (e.g., Pixel 6)
   - Download system image (API 34 recommended)
   - Launch emulator

## Troubleshooting

### Gradle Daemon Issues
```bash
# Stop all Gradle daemons
./gradlew --stop

# Clean and rebuild
./gradlew clean build
```

### SDK License Issues
```bash
export ANDROID_HOME=~/android-dev/android-sdk
yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses
```

### Java Version Issues
```bash
# Verify Java version (should be 17)
java -version

# If wrong version, ensure JAVA_HOME is set correctly
export JAVA_HOME=~/android-dev/jdk-17.0.2
```

### Missing Dependencies
```bash
# Update SDK components
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"
```

## IDE Configuration

### Android Studio Preferences

**Gradle JDK**: Set to Java 17
- File → Settings → Build → Build Tools → Gradle
- Gradle JDK: Select Java 17

**Kotlin Plugin**: Ensure version 1.9.20 or compatible

**Code Style**: Kotlin official style guide

## Testing

### Running Tests

```bash
# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests com.openclaw.alfred.ExampleTest

# Run tests with coverage
./gradlew testDebugUnitTestCoverage
```

### UI Tests (Android Instrumentation)

```bash
# Ensure device/emulator is running
adb devices

# Run instrumentation tests
./gradlew connectedAndroidTest
```

## Signing Configuration (Production)

For release builds, create `keystore.properties` in the project root:

```properties
storeFile=/path/to/keystore.jks
storePassword=your_store_password
keyAlias=your_key_alias
keyPassword=your_key_password
```

Then update `app/build.gradle.kts` to load signing config.

## Continuous Integration

### GitHub Actions / GitLab CI Example

```yaml
build:
  image: openjdk:17-jdk
  before_script:
    - wget -q https://dl.google.com/android/repository/commandlinetools-linux-9477386_latest.zip
    - unzip -q commandlinetools-linux-9477386_latest.zip
    - yes | cmdline-tools/bin/sdkmanager --sdk_root=$ANDROID_HOME --licenses
    - cmdline-tools/bin/sdkmanager --sdk_root=$ANDROID_HOME "platform-tools" "platforms;android-34" "build-tools;34.0.0"
  script:
    - ./gradlew assembleDebug
    - ./gradlew test
  artifacts:
    paths:
      - app/build/outputs/apk/debug/app-debug.apk
```

## Performance Optimization

### Build Performance

Add to `gradle.properties`:
```properties
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configureondemand=true
kotlin.incremental=true
```

### APK Size Reduction

- Enable ProGuard/R8 in release builds (already configured)
- Use APK Analyzer: `Build → Analyze APK...` in Android Studio
- Enable resource shrinking in `app/build.gradle.kts`

## Additional Resources

- **Android Documentation**: https://developer.android.com/docs
- **Jetpack Compose**: https://developer.android.com/jetpack/compose
- **Kotlin**: https://kotlinlang.org/docs/home.html
- **Hilt**: https://dagger.dev/hilt/
- **Material 3**: https://m3.material.io/

---

**Note**: This project is currently in Phase 1 (scaffold complete). Phase 2 will add OpenClaw integration.