forked from trent_larson/crowd-funder-for-time-pwa
experiment: setting up emulators
This commit is contained in:
Matthew Raymer
655
doc/android-emulator-deployment-guide.md
Normal file
655
doc/android-emulator-deployment-guide.md
Normal file
@@ -0,0 +1,655 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user