forked from jsnbuchanan/crowd-funder-for-time-pwa
docs: reorganize documentation structure with 7-item folder limits
- 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
This commit is contained in:
Matthew Raymer
422
docs/build-system/platforms/android-build-scripts.md
Normal file
422
docs/build-system/platforms/android-build-scripts.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user