From 4304addde199ac2fab67ee0ea3fffa7d953c6777 Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Mon, 13 Oct 2025 03:10:26 +0000 Subject: [PATCH] docs: add comprehensive standalone emulator guide - Document complete process for running Android app without Android Studio - Include step-by-step commands and troubleshooting - Cover emulator startup, app building, installation, and launching - Add performance optimization tips and alternative methods - Provide copy-paste ready command sequences - Include expected results and success indicators This enables development and testing without Android Studio IDE. --- docs/standalone-emulator-guide.md | 365 ++++++++++++++++++++++++++++++ 1 file changed, 365 insertions(+) create mode 100644 docs/standalone-emulator-guide.md diff --git a/docs/standalone-emulator-guide.md b/docs/standalone-emulator-guide.md new file mode 100644 index 0000000..9f03a5b --- /dev/null +++ b/docs/standalone-emulator-guide.md @@ -0,0 +1,365 @@ +# Running Android App in Standalone Emulator (Without Android Studio) + +**Author**: Matthew Raymer +**Last Updated**: 2025-10-12 06:50:00 UTC +**Version**: 1.0.0 + +## Overview + +This guide demonstrates how to run the DailyNotification plugin test app in a standalone Android emulator without using Android Studio. This method is useful for development, CI/CD pipelines, and resource-constrained environments. + +## Prerequisites + +### Required Software +- **Android SDK** with command line tools +- **Android Emulator** (`emulator` command) +- **ADB** (Android Debug Bridge) +- **Gradle** (via Gradle Wrapper) +- **Node.js** and **npm** (for TypeScript compilation) + +### System Requirements +- **RAM**: 4GB minimum, 8GB recommended +- **Storage**: 2GB free space for emulator +- **OS**: Linux, macOS, or Windows with WSL + +## Step-by-Step Process + +### 1. Check Available Emulators + +```bash +# List available Android Virtual Devices (AVDs) +emulator -list-avds + +# Example output: +# Pixel8_API34 +``` + +### 2. Start the Emulator + +```bash +# Start emulator in background (recommended) +emulator -avd Pixel8_API34 -no-snapshot-load & + +# Alternative: Start in foreground +emulator -avd Pixel8_API34 +``` + +**Flags Explained:** +- `-avd Pixel8_API34` - Specifies the AVD to use +- `-no-snapshot-load` - Forces fresh boot (recommended for testing) +- `&` - Runs in background (optional) + +### 3. Wait for Emulator to Boot + +```bash +# Wait for emulator to be ready +adb wait-for-device + +# Verify emulator is running +adb devices + +# Example output: +# List of devices attached +# emulator-5554 device +``` + +### 4. Build the Plugin and Test App + +```bash +# Navigate to project directory +cd /path/to/daily-notification-plugin + +# Build TypeScript and native code +./scripts/build-native.sh --platform android +``` + +**What this does:** +- Compiles TypeScript to JavaScript +- Builds Android native code +- Creates plugin AAR files +- Builds test app APK + +### 5. Build Debug APK (Required for Installation) + +```bash +# Navigate to Android directory +cd android + +# Build debug version (includes debug signing) +./gradlew :app:assembleDebug +``` + +**Why Debug APK:** +- **Debug signing** - Automatically signed for installation +- **No certificates needed** - Uses default debug keystore +- **Faster builds** - No optimization, faster compilation + +### 6. Install APK on Emulator + +```bash +# Install the debug APK +adb install app/build/outputs/apk/debug/app-debug.apk + +# Alternative: Install with replacement +adb install -r app/build/outputs/apk/debug/app-debug.apk +``` + +**Installation Options:** +- `adb install` - Install new app +- `adb install -r` - Replace existing app +- `adb install -t` - Allow test APKs + +### 7. Launch the App + +```bash +# Launch the app +adb shell am start -n com.timesafari.dailynotification/.MainActivity + +# Alternative: Launch with specific intent +adb shell am start -a android.intent.action.MAIN -n com.timesafari.dailynotification/.MainActivity +``` + +### 8. Monitor App Logs + +```bash +# View all logs +adb logcat + +# Filter for specific tags +adb logcat -s "Capacitor" "DailyNotification" "Console" + +# View logs for specific process +adb logcat --pid= + +# Clear logs and view new ones +adb logcat -c && adb logcat +``` + +## Complete Command Sequence + +### Quick Start (Copy-Paste Ready) + +```bash +# 1. Start emulator +emulator -avd Pixel8_API34 -no-snapshot-load & + +# 2. Wait for emulator +adb wait-for-device + +# 3. Build everything +./scripts/build-native.sh --platform android + +# 4. Build debug APK +cd android && ./gradlew :app:assembleDebug + +# 5. Install APK +adb install app/build/outputs/apk/debug/app-debug.apk + +# 6. Launch app +adb shell am start -n com.timesafari.dailynotification/.MainActivity + +# 7. Monitor logs +adb logcat -s "Capacitor" "DailyNotification" "Console" +``` + +## Alternative Methods + +### Method 1: Using Capacitor CLI + +```bash +# Build and run in one command +npx cap run android + +# This will: +# - Build the plugin +# - Sync web assets +# - Build and install APK +# - Launch the app +``` + +### Method 2: Direct Gradle Commands + +```bash +# Build and install directly +cd android +./gradlew :app:assembleDebug +adb install app/build/outputs/apk/debug/app-debug.apk +adb shell am start -n com.timesafari.dailynotification/.MainActivity +``` + +### Method 3: Using Monkey (Alternative Launch) + +```bash +# Install and launch with Monkey +adb install app/build/outputs/apk/debug/app-debug.apk +adb shell monkey -p com.timesafari.dailynotification -c android.intent.category.LAUNCHER 1 +``` + +## Troubleshooting + +### Common Issues + +#### Emulator Won't Start +```bash +# Check available AVDs +emulator -list-avds + +# Check emulator process +ps aux | grep emulator + +# Kill existing emulator +pkill -f emulator + +# Start with verbose logging +emulator -avd Pixel8_API34 -verbose +``` + +#### ADB Connection Issues +```bash +# Check ADB connection +adb devices + +# Restart ADB server +adb kill-server +adb start-server + +# Check ADB version +adb version +``` + +#### APK Installation Fails +```bash +# Check if app is already installed +adb shell pm list packages | grep timesafari + +# Uninstall existing app +adb uninstall com.timesafari.dailynotification + +# Install with force +adb install -r -t app/build/outputs/apk/debug/app-debug.apk +``` + +#### Build Failures +```bash +# Clean build +cd android && ./gradlew clean + +# Rebuild +./gradlew :app:assembleDebug + +# Check Gradle daemon +./gradlew --status +``` + +### Performance Optimization + +#### Emulator Performance +```bash +# Start with hardware acceleration +emulator -avd Pixel8_API34 -accel on + +# Start with specific RAM allocation +emulator -avd Pixel8_API34 -memory 2048 + +# Start with GPU acceleration +emulator -avd Pixel8_API34 -gpu host +``` + +#### Build Performance +```bash +# Enable Gradle daemon +echo "org.gradle.daemon=true" >> ~/.gradle/gradle.properties + +# Increase memory +echo "org.gradle.jvmargs=-Xmx4g" >> ~/.gradle/gradle.properties + +# Enable parallel builds +echo "org.gradle.parallel=true" >> ~/.gradle/gradle.properties +``` + +## Expected Results + +### Successful App Launch +When the app launches successfully, you should see: + +```bash +# ADB output +Starting: Intent { cmp=com.timesafari.dailynotification/.MainActivity } + +# Logcat output +D Capacitor: Starting BridgeActivity +D Capacitor: Registering plugin instance: CapacitorCookies +D Capacitor: Registering plugin instance: WebView +D Capacitor: Registering plugin instance: CapacitorHttp +D Capacitor: Loading app at https://localhost +D Capacitor: App started +D Capacitor: App resumed +I Capacitor/Console: Script loading... +I Capacitor/Console: Creating mock DailyNotification plugin... +I Capacitor/Console: Functions attached to window: [object Object] +``` + +### App Interface +The app should display: +- **Title**: "🔔 DailyNotification Plugin Test" +- **Three buttons**: "Test Plugin", "Configure Plugin", "Check Status" +- **Status area**: Shows test results and plugin status + +## Benefits of Standalone Approach + +### Advantages +- ✅ **No Android Studio** - Pure command line workflow +- ✅ **Faster startup** - No IDE overhead +- ✅ **CI/CD friendly** - Works in automated environments +- ✅ **Resource efficient** - Lower memory usage +- ✅ **Scriptable** - Can be automated +- ✅ **Remote development** - Works over SSH + +### Use Cases +- **Development** - Quick testing and iteration +- **CI/CD pipelines** - Automated testing +- **Remote development** - SSH-based development +- **Resource-constrained environments** - Low-spec machines +- **Team environments** - Shared development servers + +## Integration with Development Workflow + +### Daily Development +```bash +# Quick test cycle +./scripts/build-native.sh --platform android +cd android && ./gradlew :app:assembleDebug +adb install -r app/build/outputs/apk/debug/app-debug.apk +adb shell am start -n com.timesafari.dailynotification/.MainActivity +``` + +### Automated Testing +```bash +# CI/CD pipeline +emulator -avd Pixel8_API34 -no-snapshot-load & +adb wait-for-device +./scripts/build-native.sh --platform android +cd android && ./gradlew :app:assembleDebug +adb install app/build/outputs/apk/debug/app-debug.apk +adb shell am start -n com.timesafari.dailynotification/.MainActivity +# Run tests... +``` + +## Next Steps + +### Testing the App +1. **Click "Test Plugin"** - Tests the mock plugin implementation +2. **Click "Configure Plugin"** - Tests plugin configuration +3. **Click "Check Status"** - Tests plugin status retrieval +4. **Monitor logs** - Check for any errors or issues + +### Development Workflow +1. **Make changes** - Edit plugin code or test app +2. **Rebuild** - Run the build commands +3. **Reinstall** - Install updated APK +4. **Test** - Launch and test functionality +5. **Iterate** - Repeat as needed + +--- + +**This method provides a complete standalone Android development environment without requiring Android Studio!** 🎉