From fda0124aa5d06b3b8f09faf7030d236fd4beef7e Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Tue, 21 Oct 2025 09:30:22 +0000 Subject: [PATCH] docs(build): comprehensive BUILDING.md updates for test apps and deployment - Add detailed documentation for Vue 3 test app (test-apps/daily-notification-test/) - Add comprehensive /android/app structure and editing guidelines - Document all 15+ build scripts in scripts/ directory - Add deployment section covering npm publishing and external project integration - Clarify distinction between plugin module and test app modules - Update Android Studio capabilities (can now run test apps, test notifications) - Add complete project structure including test apps and scripts - Document build processes for all three Android components (plugin, main app, Vue app) Covers full development workflow from plugin development to production deployment. Co-authored-by: Matthew Raymer --- BUILDING.md | 408 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 372 insertions(+), 36 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index e65180b..82a2602 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,7 +1,7 @@ # Building the DailyNotification Plugin **Author**: Matthew Raymer -**Last Updated**: 2025-10-12 04:57:00 UTC +**Last Updated**: 2025-10-21 09:03:53 UTC **Version**: 1.0.0 ## Overview @@ -201,17 +201,18 @@ When opened correctly, you'll see: ``` android/ -├── app/ # Test app (may not be fully configured) -│ ├── build.gradle -│ ├── src/main/ -│ └── ... +├── app/ # Main Android test app +│ ├── build.gradle # App build configuration +│ ├── src/main/java/ # MainActivity.java +│ ├── src/main/assets/ # Capacitor assets (HTML/JS) +│ └── build/outputs/apk/ # Built APK files ├── plugin/ # Plugin library module -│ ├── build.gradle +│ ├── build.gradle # Plugin build configuration │ ├── src/main/java/ │ │ └── com/timesafari/dailynotification/ -│ │ ├── DailyNotificationPlugin.kt -│ │ ├── FetchWorker.kt -│ │ ├── NotifyReceiver.kt +│ │ ├── DailyNotificationPlugin.java +│ │ ├── DailyNotificationWorker.java +│ │ ├── DailyNotificationScheduler.java │ │ └── ... │ └── build/outputs/aar/ │ └── plugin-release.aar # Built plugin AAR @@ -221,29 +222,39 @@ android/ └── gradle/wrapper/ # Gradle wrapper files ``` -### Important Limitations +**Note**: There's also a separate Vue 3 test app at `test-apps/daily-notification-test/android/` with its own Android module. -#### This is NOT a Full Android App -- **No MainActivity** - This is a plugin, not an app +### Important Distinctions + +#### Plugin Module (`android/plugin/`) +- **Purpose**: Contains the actual plugin code +- **No MainActivity** - This is a library, not an app - **No UI Components** - Plugins provide functionality to host apps -- **No App Manifest** - The host app provides the manifest -- **No Resources** - Plugins use host app resources +- **Output**: AAR library files + +#### Test App Module (`android/app/`) +- **Purpose**: Test application for the plugin +- **Has MainActivity** - Full Capacitor app with BridgeActivity +- **Has UI Components** - HTML/JS interface for testing +- **Output**: APK files for installation #### What You CAN Do in Android Studio -✅ **Edit Kotlin/Java code** -✅ **Run unit tests** -✅ **Debug plugin code** -✅ **Build the plugin AAR** +✅ **Edit Java/Kotlin code** (both plugin and app) +✅ **Run unit tests** (both modules) +✅ **Debug plugin code** (plugin module) +✅ **Build the plugin AAR** (plugin module) +✅ **Build test app APK** (app module) +✅ **Run the test app** (app module) +✅ **Test notifications** (app module) +✅ **Test background tasks** (app module) +✅ **Debug full integration** (app module) ✅ **Check for compilation errors** ✅ **Use code completion and refactoring** ✅ **View build logs and errors** #### What You CANNOT Do -❌ **Run the app directly** (no MainActivity) -❌ **Test notifications** (needs host app context) -❌ **Test background tasks** (needs Capacitor runtime) -❌ **Debug full integration** (needs host app) -❌ **Test UI components** (plugin has no UI) +❌ **Run plugin module directly** (it's a library) +❌ **Test plugin without host app** (needs Capacitor runtime) ## Command Line Building @@ -355,9 +366,180 @@ xcodebuild test -workspace DailyNotificationPlugin.xcworkspace \ -destination 'platform=iOS Simulator,name=iPhone 14' ``` +### Test Apps Within Project + +#### Vue 3 Test Application +The project includes a comprehensive Vue 3 test app for interactive plugin testing: + +```bash +# Navigate to Vue 3 test app +cd test-apps/daily-notification-test + +# Install dependencies +npm install + +# Build Vue 3 app +npm run build + +# Sync with Capacitor +npx cap sync android + +# Run on Android device/emulator +npx cap run android + +# Run on iOS device/simulator +npx cap run ios +``` + +**Test App Features:** +- Interactive plugin testing interface +- Plugin diagnostics and status checking +- Notification scheduling and management +- Permission testing and management +- Comprehensive logging and debugging + +**Test App Structure:** +``` +test-apps/daily-notification-test/ +├── src/ # Vue 3 source code +│ ├── views/ # Test interface views +│ ├── components/ # Reusable UI components +│ └── stores/ # Pinia state management +├── android/ # Android Capacitor app +├── docs/ # Test app documentation +└── scripts/ # Test app build scripts +``` + +#### Android Test Apps +The project includes **two separate Android test applications**: + +##### 1. Main Android Test App (`/android/app`) +A Capacitor-based Android test app with full plugin integration: + +```bash +# Build main Android test app +cd android +./gradlew :app:assembleDebug + +# Install on device +adb install app/build/outputs/apk/debug/app-debug.apk + +# Run tests +./gradlew :app:test + +# Run in Android Studio +# File → Open → /path/to/daily-notification-plugin/android +# Select 'app' module and run +``` + +**App Structure:** +``` +android/app/ +├── src/ +│ ├── main/ +│ │ ├── AndroidManifest.xml # App manifest with permissions +│ │ ├── assets/ # Capacitor web assets +│ │ │ ├── capacitor.config.json # Capacitor configuration +│ │ │ ├── capacitor.plugins.json # Plugin registry +│ │ │ └── public/ # Web app files +│ │ │ ├── index.html # Main test interface +│ │ │ ├── cordova.js # Cordova compatibility +│ │ │ └── plugins/ # Plugin JS files +│ │ ├── java/ +│ │ │ └── com/timesafari/dailynotification/ +│ │ │ └── MainActivity.java # Capacitor BridgeActivity +│ │ └── res/ # Android resources +│ │ ├── drawable/ # App icons and images +│ │ ├── layout/ # Android layouts +│ │ ├── mipmap/ # App launcher icons +│ │ ├── values/ # Strings, styles, colors +│ │ └── xml/ # Configuration files +│ ├── androidTest/ # Instrumented tests +│ └── test/ # Unit tests +├── build.gradle # App build configuration +├── capacitor.build.gradle # Auto-generated Capacitor config +└── proguard-rules.pro # Code obfuscation rules +``` + +**Key Files Explained:** + +**`MainActivity.java`** - Entry point extending Capacitor's BridgeActivity: +```java +public class MainActivity extends BridgeActivity { + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + } +} +``` + +**`AndroidManifest.xml`** - App permissions and configuration: +- Notification permissions +- Background execution permissions +- Exact alarm permissions +- Capacitor plugin declarations + +**`assets/public/index.html`** - Main test interface: +- Interactive plugin testing buttons +- Plugin diagnostics and status checking +- Notification scheduling interface +- Permission management UI + +**`capacitor.plugins.json`** - Plugin registry: +```json +{ + "plugins": { + "DailyNotification": { + "class": "com.timesafari.dailynotification.DailyNotificationPlugin" + } + } +} +``` + +**Build Process:** +1. **Web Assets**: Capacitor copies `assets/public/` to APK +2. **Java Compilation**: Compiles `MainActivity.java` and dependencies +3. **Resource Processing**: Processes Android resources and assets +4. **APK Generation**: Packages everything into installable APK +5. **Plugin Integration**: Links with plugin AAR from `android/plugin/` + +**Editing Guidelines:** +- **HTML/JS**: Edit `assets/public/index.html` for UI changes +- **Java**: Edit `src/main/java/` for native Android code +- **Resources**: Edit `src/main/res/` for icons, strings, layouts +- **Configuration**: Edit `AndroidManifest.xml` for permissions +- **Build**: Modify `build.gradle` for dependencies and build settings + +**Features:** +- Full Capacitor integration +- Plugin testing interface (HTML/JS) +- Native Android testing capabilities +- Complete app lifecycle testing + +##### 2. Vue 3 Test App Android Module (`/test-apps/daily-notification-test/android`) +Android module within the Vue 3 test application: + +```bash +# Build Vue 3 test app Android module +cd test-apps/daily-notification-test/android +./gradlew assembleDebug + +# Install on device +adb install app/build/outputs/apk/debug/app-debug.apk + +# Run tests +./gradlew test +``` + +**Features:** +- Integrated with Vue 3 frontend +- Plugin diagnostics and management +- Interactive testing interface +- Comprehensive logging and debugging + ### Integration Testing -#### 1. Create Test Capacitor App +#### 1. Create External Test Capacitor App ```bash # Create new Capacitor app npx @capacitor/create-app@latest TestApp @@ -419,7 +601,124 @@ npx cap run ios - [ ] Battery optimization settings - [ ] Low storage conditions -## Development Workflow +## Build Scripts and Automation + +### Available Build Scripts + +The project includes several automated build scripts in the `scripts/` directory: + +#### Core Build Scripts +```bash +# Main build script (handles TypeScript + native) +./scripts/build-native.sh --platform android +./scripts/build-native.sh --platform ios +./scripts/build-native.sh --verbose + +# TimeSafari-specific builds +node scripts/build-timesafari.js + +# Comprehensive testing +./scripts/comprehensive-test-v2.sh + +# Capacitor build fixes +./scripts/fix-capacitor-build.sh +``` + +#### Setup and Configuration Scripts +```bash +# Gradle setup automation +./scripts/setup-gradle.sh + +# Native environment setup +node scripts/setup-native.js + +# Environment checking +node scripts/check-environment.js +``` + +#### Testing and Validation Scripts +```bash +# Chaos testing for reliability +node scripts/chaos-test.js + +# API changes detection +node scripts/check-api-changes.js + +# Bundle size monitoring +node scripts/check-bundle-size.js + +# Daily notification testing +./scripts/daily-notification-test.sh +node scripts/daily-notification-test.py +``` + +#### Release and Deployment Scripts +```bash +# Release notes generation +node scripts/update-release-notes.js + +# Type checksum generation +node scripts/generate-types-checksum.js +``` + +### Deployment to External Projects + +#### 1. Publishing to npm Registry +```bash +# Build the plugin +npm run build + +# Run tests +npm test + +# Update version +npm version patch # or minor, major + +# Publish to npm +npm publish + +# Verify publication +npm view @timesafari/daily-notification-plugin +``` + +#### 2. Installing in External Capacitor Projects +```bash +# Install from npm +npm install @timesafari/daily-notification-plugin + +# Install from local development +npm install /path/to/daily-notification-plugin + +# Install from git repository +npm install git+https://github.com/timesafari/daily-notification-plugin.git +``` + +#### 3. Integration in Host Applications +```bash +# Add to Capacitor project +npx cap add android +npx cap add ios + +# Sync with Capacitor +npx cap sync android +npx cap sync ios + +# Build and run +npx cap run android +npx cap run ios +``` + +#### 4. Version Management +```bash +# Check current version +npm list @timesafari/daily-notification-plugin + +# Update to latest version +npm update @timesafari/daily-notification-plugin + +# Install specific version +npm install @timesafari/daily-notification-plugin@1.2.3 +``` ### For Plugin Development @@ -612,7 +911,9 @@ daily-notification-plugin/ ├── ios/ # iOS native code ├── src/ # TypeScript plugin interface ├── dist/ # Built plugin files -├── scripts/ # Build scripts +├── scripts/ # Build scripts and automation +├── test-apps/ # Test applications +│ └── daily-notification-test/ # Vue 3 test app ├── docs/ # Documentation ├── examples/ # Usage examples ├── tests/ # Test files @@ -625,8 +926,16 @@ daily-notification-plugin/ ### Android Structure ``` android/ -├── src/main/java/ # Kotlin plugin code -├── build.gradle # Android build configuration +├── app/ # Main Android test app +│ ├── src/main/java/ # MainActivity.java +│ ├── src/main/assets/ # Capacitor assets +│ ├── build.gradle # App build configuration +│ └── build/outputs/apk/ # Built APK files +├── plugin/ # Plugin library module +│ ├── src/main/java/ # Plugin source code +│ ├── build.gradle # Plugin build configuration +│ └── build/outputs/aar/ # Built AAR files +├── build.gradle # Root Android build configuration ├── settings.gradle # Gradle settings ├── gradle.properties # Gradle properties └── gradle/wrapper/ # Gradle wrapper files @@ -642,15 +951,42 @@ ios/ └── Tests/ # iOS unit tests ``` -### TypeScript Structure +### Test Apps Structure +``` +test-apps/ +└── daily-notification-test/ # Vue 3 test application + ├── src/ # Vue 3 source code + │ ├── views/ # Test interface views + │ ├── components/ # Reusable UI components + │ ├── stores/ # Pinia state management + │ └── router/ # Vue Router configuration + ├── android/ # Android Capacitor app + │ ├── app/ # Android app module + │ ├── dailynotification/ # Plugin module + │ └── build.gradle # Android build config + ├── docs/ # Test app documentation + ├── scripts/ # Test app build scripts + ├── package.json # Vue 3 dependencies + └── vite.config.ts # Vite build configuration +``` + +### Scripts Structure ``` -src/ -├── definitions.ts # TypeScript definitions -├── index.ts # Plugin entry point -├── android/ # Android-specific code -├── ios/ # iOS-specific code -├── web/ # Web-specific code (legacy) -└── utils/ # Utility functions +scripts/ +├── build-native.sh # Main build script +├── build-timesafari.js # TimeSafari-specific builds +├── comprehensive-test-v2.sh # Full test suite +├── fix-capacitor-build.sh # Capacitor build fixes +├── setup-gradle.sh # Gradle setup automation +├── setup-native.js # Native environment setup +├── check-environment.js # Environment validation +├── chaos-test.js # Reliability testing +├── check-api-changes.js # API change detection +├── check-bundle-size.js # Bundle size monitoring +├── daily-notification-test.sh # Notification testing +├── daily-notification-test.py # Python test runner +├── update-release-notes.js # Release notes generation +└── generate-types-checksum.js # Type checksum generation ``` ## Best Practices