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.
This commit is contained in:
Matthew Raymer
365
docs/standalone-emulator-guide.md
Normal file
365
docs/standalone-emulator-guide.md
Normal file
@@ -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=<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!** 🎉
|
||||
Reference in New Issue
Block a user