jsnbuchanan/crowd-funder-for-time-pwa
1
0
Fork 1
forked from trent_larson/crowd-funder-for-time-pwa
Code Issues Pull Requests Projects Releases Wiki Activity

Remove redundant build:capacitor:* script aliases

Browse Source 
- 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
This commit is contained in:
Matthew Raymer
2025-07-14 02:00:51 -07:00
parent e3608e9338
commit 14276fbc9c
6 changed files with 840 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

405
docs/auto-run-guide.md Normal file
View File

@@ -0,0 +1,405 @@
# 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)