forked from jsnbuchanan/crowd-funder-for-time-pwa
14276fbc9c
- Removed 24 redundant build:capacitor:* scripts that were just aliases - Kept essential build:capacitor and build:capacitor:sync scripts - Improves script clarity and reduces maintenance overhead - No functional changes to build processes
405 lines
9.3 KiB
Markdown
405 lines
9.3 KiB
Markdown
# Auto-Run Guide
|
|
|
|
**Author**: Matthew Raymer
|
|
**Date**: 2025-07-12
|
|
**Status**: 🎯 **ACTIVE** - In Use
|
|
|
|
## Overview
|
|
|
|
The TimeSafari auto-run system intelligently detects available devices and
|
|
automatically builds and launches the app on the best available target. It
|
|
supports Android devices/emulators, iOS devices/simulators, and Electron
|
|
desktop apps.
|
|
|
|
## Features
|
|
|
|
### Smart Device Detection
|
|
- **Android**: Detects real devices vs emulators using ADB
|
|
- **iOS**: Detects real devices vs simulators using xcrun
|
|
- **Electron**: Checks for Electron availability
|
|
- **Priority**: Real devices preferred over simulators/emulators
|
|
|
|
### Build Mode Support
|
|
- **Development**: Default mode for daily development
|
|
- **Test**: Optimized for testing with test data
|
|
- **Production**: Production-ready builds
|
|
|
|
### Platform Targeting
|
|
- **All platforms**: Automatically detects and runs on all available
|
|
- **Specific platform**: Target only iOS, Android, or Electron
|
|
- **Cross-platform**: Works on macOS, Linux, and Windows
|
|
|
|
### Auto-Run Options
|
|
- **Build + Auto-Run**: Single command to build and launch
|
|
- **Smart Detection**: Automatically chooses best available target
|
|
- **Error Handling**: Graceful fallbacks when devices unavailable
|
|
|
|
## Usage
|
|
|
|
### Auto-Run Script (Recommended)
|
|
|
|
```bash
|
|
# Auto-detect and run on all available platforms (development mode)
|
|
npm run auto-run
|
|
|
|
# Run in test mode
|
|
npm run auto-run:test
|
|
|
|
# Run in production mode
|
|
npm run auto-run:prod
|
|
|
|
# Target specific platforms
|
|
npm run auto-run:ios
|
|
npm run auto-run:android
|
|
npm run auto-run:electron
|
|
```
|
|
|
|
### Build Script Auto-Run
|
|
|
|
#### iOS Auto-Run Commands
|
|
|
|
```bash
|
|
# Test build + auto-run
|
|
npm run build:ios:test:run
|
|
|
|
# Production build + auto-run
|
|
npm run build:ios:prod:run
|
|
|
|
# Debug build + auto-run
|
|
npm run build:ios:debug:run
|
|
|
|
# Release build + auto-run
|
|
npm run build:ios:release:run
|
|
```
|
|
|
|
#### Android Auto-Run Commands
|
|
|
|
```bash
|
|
# Test build + auto-run
|
|
npm run build:android:test:run
|
|
|
|
# Production build + auto-run
|
|
npm run build:android:prod:run
|
|
|
|
# Debug build + auto-run
|
|
npm run build:android:debug:run
|
|
|
|
# Release build + auto-run
|
|
npm run build:android:release:run
|
|
```
|
|
|
|
#### Electron Auto-Run Commands
|
|
|
|
```bash
|
|
# Development build + auto-run
|
|
npm run build:electron:dev:run
|
|
|
|
# Test build + auto-run
|
|
npm run build:electron:test:run
|
|
|
|
# Production build + auto-run
|
|
npm run build:electron:prod:run
|
|
```
|
|
|
|
### Advanced Usage
|
|
|
|
```bash
|
|
# Direct script usage with options
|
|
./scripts/auto-run.sh --test --platform=ios
|
|
./scripts/auto-run.sh --prod --platform=android
|
|
./scripts/auto-run.sh --auto # Skip confirmation prompts
|
|
|
|
# Build script with auto-run flag
|
|
./scripts/build-ios.sh --test --auto-run
|
|
./scripts/build-android.sh --prod --auto-run
|
|
./scripts/build-electron.sh --test --auto-run
|
|
|
|
# Combine options
|
|
./scripts/auto-run.sh --test --platform=all --auto
|
|
```
|
|
|
|
### Command Line Options
|
|
|
|
| Option | Description | Example |
|
|
|--------|-------------|---------|
|
|
| `--test` | Build and run in test mode | `--test` |
|
|
| `--prod` | Build and run in production mode | `--prod` |
|
|
| `--platform=PLATFORM` | Target specific platform | `--platform=ios` |
|
|
| `--auto` | Skip confirmation prompts | `--auto` |
|
|
| `--auto-run` | Auto-run after build | `--auto-run` |
|
|
| `--help` | Show help message | `--help` |
|
|
|
|
**Platform Options:**
|
|
- `ios` - iOS devices/simulators only
|
|
- `android` - Android devices/emulators only
|
|
- `electron` - Electron desktop app only
|
|
- `all` - All available platforms (default)
|
|
|
|
## How It Works
|
|
|
|
### 1. Device Detection
|
|
|
|
**Android Detection:**
|
|
```bash
|
|
# Uses ADB to list devices
|
|
adb devices
|
|
|
|
# Parses output to distinguish:
|
|
# - Real devices: Physical Android phones/tablets
|
|
# - Emulators: Android emulator instances
|
|
```
|
|
|
|
**iOS Detection:**
|
|
```bash
|
|
# Uses xcrun to list devices
|
|
xcrun xctrace list devices
|
|
|
|
# Parses output to distinguish:
|
|
# - Real devices: Physical iPhones/iPads
|
|
# - Simulators: iOS Simulator instances
|
|
```
|
|
|
|
### 2. Build Process
|
|
|
|
The script automatically calls the appropriate build commands:
|
|
|
|
```bash
|
|
# Development mode
|
|
npm run build:ios:dev
|
|
npm run build:android:dev
|
|
npm run build:electron:dev
|
|
|
|
# Test mode
|
|
npm run build:ios:test
|
|
npm run build:android:test
|
|
npm run build:electron:test
|
|
|
|
# Production mode
|
|
npm run build:ios:prod
|
|
npm run build:android:prod
|
|
npm run build:electron:prod
|
|
```
|
|
|
|
### 3. Launch Process
|
|
|
|
**Android:**
|
|
- Real devices: Install APK and launch via ADB
|
|
- Emulators: Use `npx cap run android`
|
|
|
|
**iOS:**
|
|
- Real devices: Build release version (requires Xcode setup)
|
|
- Simulators: Use `npx cap run ios`
|
|
|
|
**Electron:**
|
|
- Launch via `npm run electron:start`
|
|
|
|
## Examples
|
|
|
|
### Development Workflow
|
|
|
|
```bash
|
|
# Quick development run
|
|
npm run auto-run
|
|
|
|
# Output:
|
|
# ✅ Found 1 real Android device: ABC123DEF456
|
|
# ✅ Found 1 iOS simulator: iPhone 15 Pro
|
|
# ✅ Electron: available
|
|
#
|
|
# Available targets:
|
|
# Android: real:ABC123DEF456
|
|
# iOS: simulator:iPhone 15 Pro
|
|
# Electron: available
|
|
#
|
|
# Continue with auto-run? (y/N): y
|
|
#
|
|
# 🔄 Building and running Android (real: ABC123DEF456)...
|
|
# 🔄 Building and running iOS (simulator: iPhone 15 Pro)...
|
|
# 🔄 Building and running Electron...
|
|
#
|
|
# ✅ Auto-run completed successfully! 3 platform(s) launched.
|
|
```
|
|
|
|
### Test Mode with Build Scripts
|
|
|
|
```bash
|
|
# iOS test build + auto-run
|
|
npm run build:ios:test:run
|
|
|
|
# Android test build + auto-run
|
|
npm run build:android:test:run
|
|
|
|
# Electron test build + auto-run
|
|
npm run build:electron:test:run
|
|
|
|
# Output:
|
|
# === TimeSafari iOS Build Process ===
|
|
# 🔄 Building Capacitor version (test)...
|
|
# 🔄 Syncing with Capacitor...
|
|
# 🔄 Building iOS app...
|
|
# 🔄 Auto-running iOS app...
|
|
# ✅ iOS app launched successfully!
|
|
# ✅ iOS build completed successfully!
|
|
```
|
|
|
|
### Production Mode
|
|
|
|
```bash
|
|
# Production build and run
|
|
npm run auto-run:prod
|
|
|
|
# Output:
|
|
# 🔄 Building Android (production)...
|
|
# 🔄 Building iOS (production)...
|
|
# 🔄 Building Electron (production)...
|
|
#
|
|
# ✅ Auto-run completed successfully! 3 platform(s) launched.
|
|
```
|
|
|
|
## Comparison: Auto-Run Script vs Build Scripts
|
|
|
|
### Auto-Run Script (`auto-run.sh`)
|
|
**Best for:**
|
|
- Multi-platform development
|
|
- Quick testing across devices
|
|
- Automated workflows
|
|
- CI/CD integration
|
|
|
|
**Features:**
|
|
- Smart device detection
|
|
- Multi-platform support
|
|
- Interactive confirmation
|
|
- Error recovery
|
|
|
|
### Build Scripts with `--auto-run`
|
|
**Best for:**
|
|
- Single platform development
|
|
- Specific build configurations
|
|
- Non-interactive workflows
|
|
- Build customization
|
|
|
|
**Features:**
|
|
- Platform-specific optimization
|
|
- Build customization options
|
|
- Direct control over build process
|
|
- Integration with existing workflows
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**No devices detected:**
|
|
```bash
|
|
# Check Android devices
|
|
adb devices
|
|
|
|
# Check iOS devices (macOS only)
|
|
xcrun xctrace list devices
|
|
|
|
# Check Electron availability
|
|
which electron
|
|
```
|
|
|
|
**Build failures:**
|
|
```bash
|
|
# Clean and rebuild
|
|
npm run clean:android
|
|
npm run clean:ios
|
|
npm run clean:electron
|
|
|
|
# Then retry auto-run
|
|
npm run auto-run
|
|
```
|
|
|
|
**Permission issues:**
|
|
```bash
|
|
# Make script executable
|
|
chmod +x scripts/auto-run.sh
|
|
|
|
# Check ADB permissions (Android)
|
|
adb kill-server
|
|
adb start-server
|
|
```
|
|
|
|
### Platform-Specific Issues
|
|
|
|
**Android:**
|
|
- Ensure ADB is in PATH
|
|
- Enable USB debugging on device
|
|
- Accept device authorization prompt
|
|
- Check device is in "device" state (not "unauthorized")
|
|
|
|
**iOS:**
|
|
- Requires macOS with Xcode
|
|
- Ensure Xcode command line tools installed
|
|
- Check iOS Simulator is available
|
|
- For real devices: Requires proper certificates
|
|
|
|
**Electron:**
|
|
- Ensure Electron is installed globally or locally
|
|
- Check Node.js version compatibility
|
|
- Verify build dependencies are installed
|
|
|
|
### Debug Mode
|
|
|
|
Enable verbose logging by modifying the script:
|
|
|
|
```bash
|
|
# Add debug logging to auto-run.sh
|
|
set -x # Enable debug mode
|
|
```
|
|
|
|
## Integration with CI/CD
|
|
|
|
The auto-run script can be integrated into CI/CD pipelines:
|
|
|
|
```yaml
|
|
# Example GitHub Actions workflow
|
|
- name: Auto-run tests
|
|
run: |
|
|
npm run auto-run:test --auto
|
|
env:
|
|
# Set environment variables for CI
|
|
CI: true
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Development Workflow
|
|
1. **Daily development**: Use `npm run auto-run` for quick testing
|
|
2. **Testing**: Use `npm run auto-run:test` before commits
|
|
3. **Production**: Use `npm run auto-run:prod` for final testing
|
|
4. **Single platform**: Use `npm run build:ios:test:run` for focused work
|
|
|
|
### Device Management
|
|
1. **Keep devices connected**: Reduces detection time
|
|
2. **Use consistent device names**: Helps with identification
|
|
3. **Regular cleanup**: Clear old builds and caches
|
|
|
|
### Performance Tips
|
|
1. **Use --auto flag**: Skip prompts in automated workflows
|
|
2. **Target specific platforms**: Use `--platform=ios` for faster runs
|
|
3. **Parallel execution**: Script runs platforms in sequence (can be optimized)
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Features
|
|
- **Parallel execution**: Run multiple platforms simultaneously
|
|
- **Device selection**: Choose specific devices when multiple available
|
|
- **Custom build configurations**: Support for custom build modes
|
|
- **Integration with IDEs**: VS Code and other IDE integration
|
|
- **Performance monitoring**: Track build and launch times
|
|
|
|
### Contributing
|
|
To add new features or fix issues:
|
|
1. Modify `scripts/auto-run.sh`
|
|
2. Update this documentation
|
|
3. Test on multiple platforms
|
|
4. Submit pull request
|
|
|
|
## Related Documentation
|
|
|
|
- [iOS Simulator Build and Icons](./ios-simulator-build-and-icons.md)
|
|
- [Android Build Guide](./android-build-guide.md)
|
|
- [Electron Build Guide](./electron-build-guide.md)
|
|
- [Testing Guide](./testing-guide.md) |