forked from trent_larson/crowd-funder-for-time-pwa
feat: Add automatic Android asset validation to prevent build failures
- Add validate_android_assets() function to build-android.sh - Check for missing source assets (icon.png, splash.png, splash_dark.png) - Verify Android resources exist (drawable/splash.png, mipmap/*/ic_launcher*.png) - Auto-regenerate missing resources using @capacitor/assets - Integrate validation into main build process with exit code 9 - Add npm run assets:validate:android for manual validation - Support --assets-only flag for asset-only operations - Create comprehensive documentation in doc/android-asset-validation.md Fixes build failures caused by missing drawable/splash and mipmap/ic_launcher resources. Prevents "Android resource linking failed" errors during Gradle builds. Resolves: Android build failures due to missing asset resources
This commit is contained in:
Jose Olarte III
238
doc/android-asset-validation.md
Normal file
238
doc/android-asset-validation.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# Android Asset Validation System
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-22
|
||||
**Status**: 🎯 **ACTIVE** - Production Ready
|
||||
|
||||
## Overview
|
||||
|
||||
The Android Asset Validation System automatically detects and fixes missing Android resources before building, preventing common build failures related to missing splash screens and app icons.
|
||||
|
||||
## Problem Solved
|
||||
|
||||
Previously, Android builds would fail with errors like:
|
||||
```
|
||||
error: resource drawable/splash (aka app.timesafari.app:drawable/splash) not found.
|
||||
error: resource mipmap/ic_launcher (aka app.timesafari.app:mipmap/ic_launcher) not found.
|
||||
```
|
||||
|
||||
This happened when:
|
||||
- Source assets existed but weren't generated into Android resources
|
||||
- Android resource directories were missing
|
||||
- Asset generation tools weren't run before building
|
||||
|
||||
## Solution
|
||||
|
||||
### Enhanced Build Script Validation
|
||||
|
||||
The `scripts/build-android.sh` script now includes comprehensive asset validation that:
|
||||
|
||||
1. **Checks Source Assets**: Validates that required source files exist in `resources/`
|
||||
2. **Checks Android Resources**: Verifies that generated Android resources exist
|
||||
3. **Auto-Regenerates**: Automatically regenerates missing resources when detected
|
||||
4. **Verifies Results**: Confirms that regeneration was successful
|
||||
|
||||
### Validation Process
|
||||
|
||||
```bash
|
||||
# Validates and regenerates if needed
|
||||
npm run assets:validate:android
|
||||
|
||||
# Full build with validation
|
||||
npm run build:android:studio
|
||||
```
|
||||
|
||||
### What Gets Validated
|
||||
|
||||
#### Source Assets (Required)
|
||||
- `resources/icon.png` - App icon source
|
||||
- `resources/splash.png` - Splash screen source
|
||||
- `resources/splash_dark.png` - Dark mode splash source
|
||||
|
||||
#### Android Resources (Generated)
|
||||
- `android/app/src/main/res/drawable/splash.png` - Splash screen drawable
|
||||
- `android/app/src/main/res/mipmap-*/ic_launcher.png` - App icons for all densities
|
||||
- `android/app/src/main/res/mipmap-*/ic_launcher_round.png` - Round app icons for all densities
|
||||
|
||||
### Density Levels Checked
|
||||
- `mipmap-mdpi` (1x)
|
||||
- `mipmap-hdpi` (1.5x)
|
||||
- `mipmap-xhdpi` (2x)
|
||||
- `mipmap-xxhdpi` (3x)
|
||||
- `mipmap-xxxhdpi` (4x)
|
||||
|
||||
## Usage
|
||||
|
||||
### Automatic Validation (Recommended)
|
||||
The validation runs automatically during all Android builds:
|
||||
|
||||
```bash
|
||||
# Development build with validation
|
||||
npm run build:android:studio
|
||||
|
||||
# Production build with validation
|
||||
npm run build:android:prod
|
||||
|
||||
# Debug build with validation
|
||||
npm run build:android:debug
|
||||
```
|
||||
|
||||
### Manual Validation
|
||||
Run validation only to check/fix assets:
|
||||
|
||||
```bash
|
||||
# Validate and regenerate if needed
|
||||
npm run assets:validate:android
|
||||
|
||||
# Alternative command
|
||||
./scripts/build-android.sh --assets-only
|
||||
```
|
||||
|
||||
### Validation Only (No Regeneration)
|
||||
Check configuration without fixing:
|
||||
|
||||
```bash
|
||||
npm run assets:validate
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Missing Source Assets
|
||||
If source assets are missing, the build fails with clear error messages:
|
||||
|
||||
```
|
||||
[ERROR] Missing source assets:
|
||||
[ERROR] - resources/icon.png
|
||||
[ERROR] - resources/splash.png
|
||||
[ERROR] Please ensure all required assets are present in the resources/ directory.
|
||||
```
|
||||
|
||||
### Missing Generated Resources
|
||||
If generated resources are missing, they're automatically regenerated:
|
||||
|
||||
```
|
||||
[WARN] Missing Android resources detected:
|
||||
[WARN] - drawable/splash.png
|
||||
[WARN] - mipmap-mdpi/ic_launcher.png
|
||||
[INFO] Regenerating Android assets...
|
||||
[SUCCESS] Android assets regenerated successfully
|
||||
```
|
||||
|
||||
### Generation Failure
|
||||
If regeneration fails, helpful guidance is provided:
|
||||
|
||||
```
|
||||
[ERROR] Failed to generate Android assets
|
||||
[INFO] You may need to manually create the missing resources:
|
||||
[INFO] - android/app/src/main/res/drawable/splash.png
|
||||
[INFO] - android/app/src/main/res/mipmap-mdpi/ic_launcher.png
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Build Script Integration
|
||||
The validation is integrated into the main build process:
|
||||
|
||||
```bash
|
||||
# In scripts/build-android.sh
|
||||
validate_dependencies
|
||||
validate_android_assets || {
|
||||
log_error "Android asset validation failed. Please fix the issues above and try again."
|
||||
exit 9
|
||||
}
|
||||
```
|
||||
|
||||
### NPM Scripts
|
||||
New npm scripts for asset management:
|
||||
|
||||
```json
|
||||
{
|
||||
"assets:validate": "npx tsx scripts/assets-validator.ts",
|
||||
"assets:validate:android": "./scripts/build-android.sh --assets-only",
|
||||
"assets:clean": "rimraf android/app/src/main/res/mipmap-* ios/App/App/Assets.xcassets/**/AppIcon*.png ios/App/App/Assets.xcassets/**/Splash*.png || true"
|
||||
}
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
### For Developers
|
||||
- **No More Build Failures**: Automatic detection and fixing of missing resources
|
||||
- **Faster Development**: No need to manually run asset generation tools
|
||||
- **Clear Error Messages**: Helpful guidance when issues occur
|
||||
- **Consistent Results**: Same validation on all development machines
|
||||
|
||||
### For CI/CD
|
||||
- **Reliable Builds**: Consistent asset validation across environments
|
||||
- **Early Detection**: Catches issues before they reach production
|
||||
- **Automated Fixes**: Self-healing builds when possible
|
||||
|
||||
### For Project Maintenance
|
||||
- **Reduced Support**: Fewer "build doesn't work" issues
|
||||
- **Documentation**: Clear requirements for required assets
|
||||
- **Standardization**: Consistent asset structure across the project
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### "No assets found in the asset path"
|
||||
This occurs when the `assets/` directory is empty. The validation system automatically copies source assets and regenerates them.
|
||||
|
||||
#### "Failed to generate Android assets"
|
||||
Check that:
|
||||
- Source assets exist in `resources/`
|
||||
- `@capacitor/assets` is installed
|
||||
- You have write permissions to the Android directories
|
||||
|
||||
#### "Asset generation completed but some resources are still missing"
|
||||
This indicates a problem with the asset generation tool. Try:
|
||||
1. Running `npm install` to ensure dependencies are up to date
|
||||
2. Manually running `npx @capacitor/assets generate`
|
||||
3. Checking the asset generation logs for specific errors
|
||||
|
||||
### Manual Recovery
|
||||
If automatic regeneration fails, you can manually create the missing resources:
|
||||
|
||||
```bash
|
||||
# Create missing directories
|
||||
mkdir -p android/app/src/main/res/drawable
|
||||
mkdir -p android/app/src/main/res/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}
|
||||
|
||||
# Copy source assets to assets directory
|
||||
cp resources/icon.png assets/
|
||||
cp resources/splash.png assets/
|
||||
cp resources/splash_dark.png assets/
|
||||
|
||||
# Generate assets manually
|
||||
npx @capacitor/assets generate
|
||||
|
||||
# Clean up
|
||||
rm assets/icon.png assets/splash.png assets/splash_dark.png
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Improvements
|
||||
- **iOS Asset Validation**: Extend validation to iOS assets
|
||||
- **Asset Quality Checks**: Validate image dimensions and formats
|
||||
- **Performance Optimization**: Cache validation results
|
||||
- **CI/CD Integration**: Add validation to GitHub Actions
|
||||
|
||||
### Configuration Options
|
||||
- **Custom Asset Paths**: Support for different asset directory structures
|
||||
- **Validation Rules**: Configurable validation requirements
|
||||
- **Skip Options**: Ability to skip validation for specific scenarios
|
||||
|
||||
## References
|
||||
|
||||
- [Capacitor Assets Documentation](https://github.com/ionic-team/capacitor-assets)
|
||||
- [Android Resource System](https://developer.android.com/guide/topics/resources/providing-resources)
|
||||
- [Build Script Documentation](./build-android.sh)
|
||||
- [Asset Configuration](./capacitor-assets.config.json)
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active validation system
|
||||
**Priority**: High
|
||||
**Maintainer**: Development team
|
||||
**Next Review**: 2025-09-22
|
||||
Reference in New Issue
Block a user