# Android Emulator Deployment Guide (No Android Studio)

**Author**: Matthew Raymer  
**Date**: 2025-01-27  
**Status**: 🎯 **ACTIVE** - Complete guide for deploying TimeSafari to Android emulator using command-line tools

## Overview

This guide provides comprehensive instructions for building and deploying TimeSafari to Android emulators using only command-line tools, without requiring Android Studio. It leverages the existing build system and adds emulator-specific deployment workflows.

## Prerequisites

### Required Tools

1. **Android SDK Command Line Tools**
   ```bash
   # Install via package manager (Arch Linux)
   sudo pacman -S android-sdk-cmdline-tools-latest
   
   # Or download from Google
   # https://developer.android.com/studio/command-line
   ```

2. **Android SDK Platform Tools**
   ```bash
   # Install via package manager
   sudo pacman -S android-sdk-platform-tools
   
   # Or via Android SDK Manager
   sdkmanager "platform-tools"
   ```

3. **Android SDK Build Tools**
   ```bash
   sdkmanager "build-tools;34.0.0"
   ```

4. **Android Platform**
   ```bash
   sdkmanager "platforms;android-34"
   ```

5. **Android Emulator**
   ```bash
   sdkmanager "emulator"
   ```

6. **System Images**
   ```bash
   # For API 34 (Android 14)
   sdkmanager "system-images;android-34;google_apis;x86_64"
   
   # For API 33 (Android 13) - alternative
   sdkmanager "system-images;android-33;google_apis;x86_64"
   ```

### Environment Setup

```bash
# Add to ~/.bashrc or ~/.zshrc
export ANDROID_HOME=$HOME/Android/Sdk
export ANDROID_AVD_HOME=$HOME/.android/avd  # Important for AVD location
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/build-tools/34.0.0

# Reload shell
source ~/.bashrc
```

### Verify Installation

```bash
# Check all tools are available
adb version
emulator -version
avdmanager list
```

## Resource-Aware Emulator Setup

### ⚡ **Quick Start Recommendation**

**For best results, always start with resource analysis:**

```bash
# 1. Check your system capabilities
./scripts/avd-resource-checker.sh

# 2. Use the generated optimal startup script
/tmp/start-avd-TimeSafari_Emulator.sh

# 3. Deploy your app
npm run build:android:dev
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
```

This prevents system lockups and ensures optimal performance.

### AVD Resource Checker Script

**New Feature**: TimeSafari includes an intelligent resource checker that automatically detects your system capabilities and recommends optimal AVD configurations.

```bash
# Check system resources and get recommendations
./scripts/avd-resource-checker.sh

# Check resources for specific AVD
./scripts/avd-resource-checker.sh TimeSafari_Emulator

# Test AVD startup performance
./scripts/avd-resource-checker.sh TimeSafari_Emulator --test

# Create optimized AVD with recommended settings
./scripts/avd-resource-checker.sh TimeSafari_Emulator --create
```

**What the script analyzes:**
- **System Memory**: Total and available RAM
- **CPU Cores**: Available processing power
- **GPU Capabilities**: NVIDIA, AMD, Intel, or software rendering
- **Hardware Acceleration**: Optimal graphics settings

**What it generates:**
- **Optimal configuration**: Memory, cores, and GPU settings
- **Startup command**: Ready-to-use emulator command
- **Startup script**: Saved to `/tmp/start-avd-{name}.sh` for reuse

## Emulator Management

### Create Android Virtual Device (AVD)

```bash
# List available system images
avdmanager list target

# Create AVD for API 34
avdmanager create avd \
  --name "TimeSafari_Emulator" \
  --package "system-images;android-34;google_apis;x86_64" \
  --device "pixel_7"

# List created AVDs
avdmanager list avd
```

### Start Emulator

```bash
# Start emulator with hardware acceleration (recommended)
emulator -avd TimeSafari_Emulator -gpu host -no-audio &

# Start with reduced resources (if system has limited RAM)
emulator -avd TimeSafari_Emulator \
  -no-audio \
  -memory 2048 \
  -cores 2 \
  -gpu swiftshader_indirect &

# Start with minimal resources (safest for low-end systems)
emulator -avd TimeSafari_Emulator \
  -no-audio \
  -memory 1536 \
  -cores 1 \
  -gpu swiftshader_indirect &

# Check if emulator is running
adb devices
```

### Resource Management

**Important**: Android emulators can consume significant system resources. Choose the appropriate configuration based on your system:

- **High-end systems** (16GB+ RAM, dedicated GPU): Use `-gpu host`
- **Mid-range systems** (8-16GB RAM): Use `-memory 2048 -cores 2`
- **Low-end systems** (4-8GB RAM): Use `-memory 1536 -cores 1 -gpu swiftshader_indirect`

### Emulator Control

```bash
# Stop emulator
adb emu kill

# Restart emulator
adb reboot

# Check emulator status
adb get-state
```

## Build and Deploy Workflow

### Method 1: Using Existing Build Scripts

The TimeSafari project already has comprehensive Android build scripts that can be adapted for emulator deployment:

```bash
# Development build with auto-run
npm run build:android:dev:run

# Test build with auto-run  
npm run build:android:test:run

# Production build with auto-run
npm run build:android:prod:run
```

### Method 2: Custom Emulator Deployment Script

Create a new script specifically for emulator deployment:

```bash
# Create emulator deployment script
cat > scripts/deploy-android-emulator.sh << 'EOF'
#!/bin/bash
# deploy-android-emulator.sh
# Author: Matthew Raymer
# Date: 2025-01-27
# Description: Deploy TimeSafari to Android emulator without Android Studio

set -e

# Source common utilities
source "$(dirname "$0")/common.sh"

# Default values
BUILD_MODE="development"
AVD_NAME="TimeSafari_Emulator"
START_EMULATOR=true
CLEAN_BUILD=true

# Parse command line arguments
while [[ $# -gt 0 ]]; do
    case $1 in
        --dev|--development)
            BUILD_MODE="development"
            shift
            ;;
        --test)
            BUILD_MODE="test"
            shift
            ;;
        --prod|--production)
            BUILD_MODE="production"
            shift
            ;;
        --avd)
            AVD_NAME="$2"
            shift 2
            ;;
        --no-start-emulator)
            START_EMULATOR=false
            shift
            ;;
        --no-clean)
            CLEAN_BUILD=false
            shift
            ;;
        -h|--help)
            echo "Usage: $0 [options]"
            echo "Options:"
            echo "  --dev, --development    Build for development"
            echo "  --test                  Build for testing"
            echo "  --prod, --production    Build for production"
            echo "  --avd NAME              Use specific AVD name"
            echo "  --no-start-emulator     Don't start emulator"
            echo "  --no-clean              Skip clean build"
            echo "  -h, --help             Show this help"
            exit 0
            ;;
        *)
            log_error "Unknown option: $1"
            exit 1
            ;;
    esac
done

# Function to check if emulator is running
check_emulator_running() {
    if adb devices | grep -q "emulator.*device"; then
        return 0
    else
        return 1
    fi
}

# Function to start emulator
start_emulator() {
    log_info "Starting Android emulator: $AVD_NAME"
    
    # Check if AVD exists
    if ! avdmanager list avd | grep -q "$AVD_NAME"; then
        log_error "AVD '$AVD_NAME' not found. Please create it first."
        log_info "Create AVD with: avdmanager create avd --name $AVD_NAME --package system-images;android-34;google_apis;x86_64"
        exit 1
    fi
    
    # Start emulator in background
    emulator -avd "$AVD_NAME" -no-audio -no-snapshot &
    EMULATOR_PID=$!
    
    # Wait for emulator to boot
    log_info "Waiting for emulator to boot..."
    adb wait-for-device
    
    # Wait for boot to complete
    log_info "Waiting for boot to complete..."
    while [ "$(adb shell getprop sys.boot_completed)" != "1" ]; do
        sleep 2
    done
    
    log_success "Emulator is ready!"
}

# Function to build and deploy
build_and_deploy() {
    log_info "Building TimeSafari for $BUILD_MODE mode..."
    
    # Clean build if requested
    if [ "$CLEAN_BUILD" = true ]; then
        log_info "Cleaning previous build..."
        npm run clean:android
    fi
    
    # Build based on mode
    case $BUILD_MODE in
        "development")
            npm run build:android:dev
            ;;
        "test")
            npm run build:android:test
            ;;
        "production")
            npm run build:android:prod
            ;;
    esac
    
    # Deploy to emulator
    log_info "Deploying to emulator..."
    adb install -r android/app/build/outputs/apk/debug/app-debug.apk
    
    # Launch app
    log_info "Launching TimeSafari..."
    adb shell am start -n app.timesafari/.MainActivity
    
    log_success "TimeSafari deployed and launched successfully!"
}

# Main execution
main() {
    log_info "TimeSafari Android Emulator Deployment"
    log_info "Build Mode: $BUILD_MODE"
    log_info "AVD Name: $AVD_NAME"
    
    # Start emulator if requested and not running
    if [ "$START_EMULATOR" = true ]; then
        if ! check_emulator_running; then
            start_emulator
        else
            log_info "Emulator already running"
        fi
    fi
    
    # Build and deploy
    build_and_deploy
    
    log_success "Deployment completed successfully!"
}

# Run main function
main "$@"
EOF

# Make script executable
chmod +x scripts/deploy-android-emulator.sh
```

### Method 3: Direct Command Line Deployment

For quick deployments without scripts:

```bash
# 1. Ensure emulator is running
adb devices

# 2. Build the app
npm run build:android:dev

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

# 4. Launch app
adb shell am start -n app.timesafari/.MainActivity

# 5. View logs
adb logcat | grep -E "(TimeSafari|Capacitor|MainActivity)"
```

## Advanced Deployment Options

### Custom API Server Configuration

For development with custom API endpoints:

```bash
# Build with custom API IP
npm run build:android:dev:custom

# Or modify capacitor.config.ts for specific IP
# Then build normally
npm run build:android:dev
```

### Debug vs Release Builds

```bash
# Debug build (default)
npm run build:android:debug

# Release build
npm run build:android:release

# Install specific build
adb install -r android/app/build/outputs/apk/release/app-release.apk
```

### Asset Management

```bash
# Validate Android assets
npm run assets:validate:android

# Generate assets only
npm run build:android:assets

# Clean assets
npm run assets:clean
```

## Troubleshooting

### Common Issues

1. **Emulator Not Starting / AVD Not Found**
   ```bash
   # Check available AVDs
   avdmanager list avd
   
   # If AVD exists but emulator can't find it, check AVD location
   echo $ANDROID_AVD_HOME
   ls -la ~/.android/avd/
   
   # Fix AVD path issue (common on Arch Linux)
   export ANDROID_AVD_HOME=/home/$USER/.config/.android/avd
   
   # Or create symlinks if AVDs are in different location
   mkdir -p ~/.android/avd
   ln -s /home/$USER/.config/.android/avd/* ~/.android/avd/
   
   # Create new AVD if needed
   avdmanager create avd --name "TimeSafari_Emulator" --package "system-images;android-34;google_apis;x86_64"
   
   # Check emulator logs
   emulator -avd TimeSafari_Emulator -verbose
   ```

2. **System Lockup / High Resource Usage**
   ```bash
   # Kill any stuck emulator processes
   pkill -f emulator
   
   # Check system resources
   free -h
   nvidia-smi  # if using NVIDIA GPU
   
   # Start with minimal resources
   emulator -avd TimeSafari_Emulator \
     -no-audio \
     -memory 1536 \
     -cores 1 \
     -gpu swiftshader_indirect &
   
   # Monitor resource usage
   htop
   
   # If still having issues, try software rendering only
   emulator -avd TimeSafari_Emulator \
     -no-audio \
     -no-snapshot \
     -memory 1024 \
     -cores 1 \
     -gpu off &
   ```

3. **ADB Device Not Found**
   ```bash
   # Restart ADB server
   adb kill-server
   adb start-server
   
   # Check devices
   adb devices
   
   # Check emulator status
   adb get-state
   ```

3. **Build Failures**
   ```bash
   # Clean everything
   npm run clean:android
   
   # Rebuild
   npm run build:android:dev
   
   # Check Gradle logs
   cd android && ./gradlew clean --stacktrace
   ```

4. **Installation Failures**
   ```bash
   # Uninstall existing app
   adb uninstall app.timesafari
   
   # Reinstall
   adb install android/app/build/outputs/apk/debug/app-debug.apk
   
   # Check package info
   adb shell pm list packages | grep timesafari
   ```

### Performance Optimization

1. **Emulator Performance**
   ```bash
   # Start with hardware acceleration
   emulator -avd TimeSafari_Emulator -gpu host
   
   # Use snapshot for faster startup
   emulator -avd TimeSafari_Emulator -snapshot default
   
   # Allocate more RAM
   emulator -avd TimeSafari_Emulator -memory 4096
   ```

2. **Build Performance**
   ```bash
   # Use Gradle daemon
   echo "org.gradle.daemon=true" >> android/gradle.properties
   
   # Increase heap size
   echo "org.gradle.jvmargs=-Xmx4g" >> android/gradle.properties
   
   # Enable parallel builds
   echo "org.gradle.parallel=true" >> android/gradle.properties
   ```

## Integration with Existing Build System

### NPM Scripts Integration

Add emulator-specific scripts to `package.json`:

```json
{
  "scripts": {
    "emulator:check": "./scripts/avd-resource-checker.sh",
    "emulator:check:test": "./scripts/avd-resource-checker.sh TimeSafari_Emulator --test",
    "emulator:check:create": "./scripts/avd-resource-checker.sh TimeSafari_Emulator --create",
    "emulator:start": "emulator -avd TimeSafari_Emulator -no-audio &",
    "emulator:start:optimized": "/tmp/start-avd-TimeSafari_Emulator.sh",
    "emulator:stop": "adb emu kill",
    "emulator:deploy": "./scripts/deploy-android-emulator.sh",
    "emulator:deploy:dev": "./scripts/deploy-android-emulator.sh --dev",
    "emulator:deploy:test": "./scripts/deploy-android-emulator.sh --test",
    "emulator:deploy:prod": "./scripts/deploy-android-emulator.sh --prod",
    "emulator:logs": "adb logcat | grep -E '(TimeSafari|Capacitor|MainActivity)'",
    "emulator:shell": "adb shell"
  }
}
```

### CI/CD Integration

For automated testing and deployment:

```bash
# GitHub Actions example
- name: Start Android Emulator
  run: |
    emulator -avd TimeSafari_Emulator -no-audio -no-snapshot &
    adb wait-for-device
    adb shell getprop sys.boot_completed

- name: Build and Deploy
  run: |
    npm run build:android:test
    adb install -r android/app/build/outputs/apk/debug/app-debug.apk
    adb shell am start -n app.timesafari/.MainActivity

- name: Run Tests
  run: |
    npm run test:android
```

## Best Practices

### Development Workflow

1. **Start emulator once per session**
   ```bash
   emulator -avd TimeSafari_Emulator -no-audio &
   ```

2. **Use incremental builds**
   ```bash
   # For rapid iteration
   npm run build:android:sync
   adb install -r android/app/build/outputs/apk/debug/app-debug.apk
   ```

3. **Monitor logs continuously**
   ```bash
   adb logcat | grep -E "(TimeSafari|Capacitor|MainActivity)" --color=always
   ```

### Performance Tips

1. **Use snapshots for faster startup**
2. **Enable hardware acceleration**
3. **Allocate sufficient RAM (4GB+)**
4. **Use SSD storage for AVDs**
5. **Close unnecessary applications**

### Security Considerations

1. **Use debug builds for development only**
2. **Never commit debug keystores**
3. **Use release builds for testing**
4. **Validate API endpoints in production builds**

## Conclusion

This guide provides a complete solution for deploying TimeSafari to Android emulators without Android Studio. The approach leverages the existing build system while adding emulator-specific deployment capabilities.

The key benefits:
- ✅ **No Android Studio required**
- ✅ **Command-line only workflow**
- ✅ **Integration with existing build scripts**
- ✅ **Automated deployment options**
- ✅ **Comprehensive troubleshooting guide**

For questions or issues, refer to the troubleshooting section or check the existing build documentation in `BUILDING.md`.