forked from trent_larson/crowd-funder-for-time-pwa
656 lines
16 KiB
Markdown
656 lines
16 KiB
Markdown
# 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`.
|