forked from jsnbuchanan/crowd-funder-for-time-pwa
db5da0cdfc
- Create logical sub-folder classification for all documentation - Organize 91 migration files into component-specific folders - Separate user guides, build system, migration, and development docs - Maintain maximum 7 items per folder for easy navigation - Add comprehensive README and reorganization summary - Ensure all changes tracked in git with proper versioning Structure: - user-guides/ (3 items): user-facing documentation - build-system/ (3 items): core, platforms, automation - migration/ (6 items): assessments, testing, templates - development/ (4 items): tools and standards - architecture/, testing/, examples/ (ready for future docs) Total: 24 folders created, all within 7-item limits
422 lines
9.8 KiB
Markdown
422 lines
9.8 KiB
Markdown
# Android Build Scripts Documentation
|
|
|
|
**Author**: Matthew Raymer
|
|
**Date**: 2025-07-11
|
|
**Status**: ✅ **COMPLETE** - Full Android build system integration
|
|
|
|
## Overview
|
|
|
|
The Android build system for TimeSafari has been integrated with the Vite
|
|
mode-based pattern, providing consistent environment management and flexible
|
|
build options across development, testing, and production environments.
|
|
|
|
**Note:** All Android builds should be invoked via `npm run build:android*` scripts for consistency. The legacy `build:capacitor:android*` scripts are now aliases for the corresponding `build:android*` scripts.
|
|
|
|
## Build Script Integration
|
|
|
|
### Package.json Scripts
|
|
|
|
The Android build system is fully integrated into `package.json` with the
|
|
following scripts:
|
|
|
|
#### Basic Build Commands
|
|
|
|
```bash
|
|
# Development builds (defaults to --mode development)
|
|
npm run build:android:dev # Development build
|
|
npm run build:android:test # Testing build
|
|
npm run build:android:prod # Production build
|
|
```
|
|
|
|
#### Build Type Commands
|
|
|
|
```bash
|
|
# Debug builds
|
|
npm run build:android:debug # Debug APK build
|
|
|
|
# Release builds
|
|
npm run build:android:release # Release APK build
|
|
```
|
|
|
|
#### Specialized Commands
|
|
|
|
```bash
|
|
# Android Studio integration
|
|
npm run build:android:studio # Build + open Android Studio
|
|
|
|
# Package builds
|
|
npm run build:android:apk # Build APK file
|
|
npm run build:android:aab # Build AAB (Android App Bundle)
|
|
|
|
# Utility commands
|
|
npm run build:android:clean # Clean build artifacts only
|
|
npm run build:android:sync # Sync Capacitor only
|
|
npm run build:android:assets # Generate assets only
|
|
```
|
|
|
|
#### Legacy Command
|
|
|
|
```bash
|
|
# Original script (maintains backward compatibility)
|
|
npm run build:android # Full build process
|
|
```
|
|
|
|
## Script Usage
|
|
|
|
### Direct Script Usage
|
|
|
|
The `build-android.sh` script supports comprehensive command-line options:
|
|
|
|
```bash
|
|
# Basic usage
|
|
./scripts/build-android.sh [options]
|
|
|
|
# Environment-specific builds
|
|
./scripts/build-android.sh --dev --studio # Development + open studio
|
|
./scripts/build-android.sh --test --apk # Testing APK build
|
|
./scripts/build-android.sh --prod --aab # Production AAB build
|
|
|
|
# Utility operations
|
|
./scripts/build-android.sh --clean # Clean only
|
|
./scripts/build-android.sh --sync # Sync only
|
|
./scripts/build-android.sh --assets # Assets only
|
|
```
|
|
|
|
### Command-Line Options
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `--dev`, `--development` | Build for development environment | ✅ |
|
|
| `--test` | Build for testing environment | |
|
|
| `--prod`, `--production` | Build for production environment | |
|
|
| `--debug` | Build debug APK | ✅ |
|
|
| `--release` | Build release APK | |
|
|
| `--studio` | Open Android Studio after build | |
|
|
| `--apk` | Build APK file | |
|
|
| `--aab` | Build AAB (Android App Bundle) | |
|
|
| `--clean` | Clean build artifacts only | |
|
|
| `--sync` | Sync Capacitor only | |
|
|
| `--assets` | Generate assets only | |
|
|
| `-h`, `--help` | Show help message | |
|
|
| `-v`, `--verbose` | Enable verbose logging | |
|
|
|
|
## Build Process
|
|
|
|
### Complete Build Flow
|
|
|
|
1. **Resource Check**: Validate Android resources
|
|
2. **Cleanup**: Clean Android app and build artifacts
|
|
3. **Capacitor Build**: Build web assets with environment-specific mode
|
|
4. **Gradle Clean**: Clean Gradle build cache
|
|
5. **Gradle Build**: Assemble debug/release APK
|
|
6. **Capacitor Sync**: Sync web assets to Android platform
|
|
7. **Asset Generation**: Generate Android-specific assets
|
|
8. **Package Build**: Build APK/AAB if requested
|
|
9. **Studio Launch**: Open Android Studio if requested
|
|
|
|
### Environment-Specific Builds
|
|
|
|
#### Development Environment (`--dev`)
|
|
|
|
```bash
|
|
# Uses --mode development
|
|
npm run build:capacitor
|
|
# Builds with development optimizations and debugging enabled
|
|
```
|
|
|
|
#### Testing Environment (`--test`)
|
|
|
|
```bash
|
|
# Uses --mode test
|
|
npm run build:capacitor -- --mode test
|
|
# Builds with testing configurations and test API endpoints
|
|
```
|
|
|
|
#### Production Environment (`--prod`)
|
|
|
|
```bash
|
|
# Uses --mode production
|
|
npm run build:capacitor -- --mode production
|
|
# Builds with production optimizations and live API endpoints
|
|
```
|
|
|
|
## Build Artifacts
|
|
|
|
### APK Files
|
|
|
|
- **Debug APK**: `android/app/build/outputs/apk/debug/app-debug.apk`
|
|
- **Release APK**: `android/app/build/outputs/apk/release/app-release.apk`
|
|
|
|
### AAB Files
|
|
|
|
- **Release AAB**: `android/app/build/outputs/bundle/release/app-release.aab`
|
|
|
|
### Build Locations
|
|
|
|
```bash
|
|
# APK files
|
|
android/app/build/outputs/apk/debug/
|
|
android/app/build/outputs/apk/release/
|
|
|
|
# AAB files
|
|
android/app/build/outputs/bundle/release/
|
|
|
|
# Gradle build cache
|
|
android/app/build/
|
|
android/.gradle/
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
The build system automatically sets environment variables based on the build
|
|
type:
|
|
|
|
### Capacitor Environment
|
|
|
|
```bash
|
|
VITE_PLATFORM=capacitor
|
|
VITE_PWA_ENABLED=false
|
|
VITE_DISABLE_PWA=true
|
|
DEBUG_MIGRATIONS=0
|
|
```
|
|
|
|
### Git Integration
|
|
|
|
```bash
|
|
VITE_GIT_HASH=<git-commit-hash>
|
|
# Automatically set from current git commit
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Exit Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 1 | Android cleanup failed |
|
|
| 2 | Web build failed |
|
|
| 3 | Capacitor build failed |
|
|
| 4 | Gradle clean failed |
|
|
| 5 | Gradle assemble failed |
|
|
| 6 | Capacitor sync failed |
|
|
| 7 | Asset generation failed |
|
|
| 8 | Android Studio launch failed |
|
|
| 9 | Resource check failed |
|
|
|
|
### Common Issues
|
|
|
|
#### Resource Check Failures
|
|
|
|
```bash
|
|
# Resource check may find issues but continues build
|
|
log_warning "Resource check found issues, but continuing with build..."
|
|
```
|
|
|
|
#### Gradle Build Failures
|
|
|
|
```bash
|
|
# Check Android SDK and build tools
|
|
./android/gradlew --version
|
|
# Verify JAVA_HOME is set correctly
|
|
echo $JAVA_HOME
|
|
```
|
|
|
|
## Integration with Capacitor
|
|
|
|
### Capacitor Sync Process
|
|
|
|
```bash
|
|
# Full sync (all platforms)
|
|
npx cap sync
|
|
|
|
# Android-specific sync
|
|
npx cap sync android
|
|
```
|
|
|
|
### Asset Generation
|
|
|
|
```bash
|
|
# Generate Android-specific assets
|
|
npx capacitor-assets generate --android
|
|
```
|
|
|
|
### Android Studio Integration
|
|
|
|
```bash
|
|
# Open Android Studio with project
|
|
npx cap open android
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Typical Development Cycle
|
|
|
|
```bash
|
|
# 1. Make code changes
|
|
# 2. Build for development
|
|
npm run build:android:dev
|
|
|
|
# 3. Open Android Studio for debugging
|
|
npm run build:android:studio
|
|
|
|
# 4. Test on device/emulator
|
|
# 5. Iterate and repeat
|
|
```
|
|
|
|
### Testing Workflow
|
|
|
|
```bash
|
|
# 1. Build for testing environment
|
|
npm run build:android:test
|
|
|
|
# 2. Build test APK
|
|
npm run build:android:test -- --apk
|
|
|
|
# 3. Install and test on device
|
|
adb install android/app/build/outputs/apk/debug/app-debug.apk
|
|
```
|
|
|
|
### Production Workflow
|
|
|
|
```bash
|
|
# 1. Build for production environment
|
|
npm run build:android:prod
|
|
|
|
# 2. Build release AAB for Play Store
|
|
npm run build:android:prod -- --aab
|
|
|
|
# 3. Sign and upload to Play Console
|
|
```
|
|
|
|
## Performance Optimization
|
|
|
|
### Build Time Optimization
|
|
|
|
- **Incremental Builds**: Gradle caches build artifacts
|
|
- **Parallel Execution**: Multiple build steps run in parallel
|
|
- **Resource Optimization**: Assets are optimized for Android
|
|
|
|
### Memory Management
|
|
|
|
- **Gradle Daemon**: Reuses JVM for faster builds
|
|
- **Build Cache**: Caches compiled resources
|
|
- **Clean Builds**: Full cleanup when needed
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Build Issues
|
|
|
|
#### Gradle Build Failures
|
|
|
|
```bash
|
|
# Clean Gradle cache
|
|
cd android && ./gradlew clean && cd ..
|
|
|
|
# Check Java version
|
|
java -version
|
|
|
|
# Verify Android SDK
|
|
echo $ANDROID_HOME
|
|
```
|
|
|
|
#### Capacitor Sync Issues
|
|
|
|
```bash
|
|
# Force full sync
|
|
npx cap sync android --force
|
|
|
|
# Check Capacitor configuration
|
|
cat capacitor.config.json
|
|
```
|
|
|
|
#### Asset Generation Issues
|
|
|
|
```bash
|
|
# Regenerate assets
|
|
npx capacitor-assets generate --android --force
|
|
|
|
# Check asset source files
|
|
ls -la src/assets/
|
|
```
|
|
|
|
### Debug Mode
|
|
|
|
```bash
|
|
# Enable verbose logging
|
|
./scripts/build-android.sh --verbose
|
|
|
|
# Show environment variables
|
|
./scripts/build-android.sh --env
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Build Optimization
|
|
|
|
1. **Use Appropriate Environment**: Always specify the correct environment
|
|
2. **Clean When Needed**: Use `--clean` for troubleshooting
|
|
3. **Incremental Builds**: Avoid unnecessary full rebuilds
|
|
4. **Asset Management**: Keep assets optimized for mobile
|
|
|
|
### Development Workflow
|
|
|
|
1. **Development Builds**: Use `--dev` for daily development
|
|
2. **Testing Builds**: Use `--test` for QA testing
|
|
3. **Production Builds**: Use `--prod` for release builds
|
|
4. **Studio Integration**: Use `--studio` for debugging
|
|
|
|
### Error Prevention
|
|
|
|
1. **Resource Validation**: Always run resource checks
|
|
2. **Environment Consistency**: Use consistent environment variables
|
|
3. **Build Verification**: Test builds on actual devices
|
|
4. **Version Control**: Keep build scripts in version control
|
|
|
|
## Migration from Legacy System
|
|
|
|
### Backward Compatibility
|
|
|
|
The new system maintains full backward compatibility:
|
|
|
|
```bash
|
|
# Old command still works (now an alias)
|
|
npm run build:capacitor:android
|
|
|
|
# New commands provide more flexibility
|
|
npm run build:android:dev
|
|
npm run build:android:test
|
|
npm run build:android:prod
|
|
```
|
|
|
|
**Note:** All Android builds should use the `build:android*` pattern. The `build:capacitor:android*` scripts are provided as aliases for compatibility but will be deprecated in the future.
|
|
|
|
### Migration Checklist
|
|
|
|
- [ ] Update CI/CD pipelines to use new commands
|
|
- [ ] Update documentation references
|
|
- [ ] Train team on new build options
|
|
- [ ] Test all build environments
|
|
- [ ] Verify artifact locations
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Features
|
|
|
|
1. **Build Profiles**: Custom build configurations
|
|
2. **Automated Testing**: Integration with test suites
|
|
3. **Build Analytics**: Performance metrics and reporting
|
|
4. **Cloud Builds**: Remote build capabilities
|
|
|
|
### Integration Opportunities
|
|
|
|
1. **Fastlane Integration**: Automated deployment
|
|
2. **CI/CD Enhancement**: Pipeline optimization
|
|
3. **Monitoring**: Build performance tracking
|
|
4. **Documentation**: Auto-generated build reports
|
|
|
|
---
|
|
|
|
**Status**: Complete and ready for production use
|
|
**Last Updated**: 2025-07-11
|
|
**Version**: 1.0
|
|
**Maintainer**: Matthew Raymer |