crowd-funder-for-time-pwa/doc/android-emulator-deployment-guide.md

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

   # 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

   # Install via package manager
   sudo pacman -S android-sdk-platform-tools
   
   # Or via Android SDK Manager
   sdkmanager "platform-tools"
   

3. Android SDK Build Tools

   sdkmanager "build-tools;34.0.0"
   

4. Android Platform

   sdkmanager "platforms;android-34"
   

5. Android Emulator

   sdkmanager "emulator"
   

6. System Images

   # 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

# 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

# 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:

# 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.

# 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)

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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

   # 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

   # 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

   # Restart ADB server
   adb kill-server
   adb start-server
   
   # Check devices
   adb devices
   
   # Check emulator status
   adb get-state
   

4. Build Failures

   # Clean everything
   npm run clean:android
   
   # Rebuild
   npm run build:android:dev
   
   # Check Gradle logs
   cd android && ./gradlew clean --stacktrace
   

5. Installation Failures

   # 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

   # 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

   # 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:

{
  "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:

# 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

   emulator -avd TimeSafari_Emulator -no-audio &
   

2. Use incremental builds

   # For rapid iteration
   npm run build:android:sync
   adb install -r android/app/build/outputs/apk/debug/app-debug.apk
   

3. Monitor logs continuously

   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.