docs: add comprehensive BUILDING.md guide

- Document Android Studio setup and limitations - Explain plugin development vs full app development - Provide step-by-step build instructions - Include troubleshooting and best practices - Cover all build methods: script, command line, Android Studio - Add testing strategies and development workflow - Clarify project structure and file organization This addresses the need for clear build documentation for developers working with the Capacitor plugin.
2025-10-12 04:56:49 +00:00
parent 2712c8bf9b
commit 482b911b50
1 changed files with 655 additions and 0 deletions
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -0,0 +1,655 @@
 # Building the DailyNotification Plugin
 **Author**: Matthew Raymer  
 **Last Updated**: 2025-01-08 09:15:00 UTC  
 **Version**: 1.0.0
 ## Overview
 This document provides comprehensive instructions for building the DailyNotification Capacitor plugin using various methods, including Android Studio, command line, and integration testing.
 ## Table of Contents
 - [Quick Start](#quick-start)
 - [Prerequisites](#prerequisites)
 - [Build Methods](#build-methods)
 - [Android Studio Setup](#android-studio-setup)
 - [Command Line Building](#command-line-building)
 - [Testing Strategies](#testing-strategies)
 - [Development Workflow](#development-workflow)
 - [Troubleshooting](#troubleshooting)
 - [Project Structure](#project-structure)
 ## Quick Start
 ### For Plugin Development
 ```bash
 # Build plugin source code
 ./scripts/build-native.sh --platform android
 # Test in Capacitor app
 cd /path/to/test-capacitor-app
 npx cap sync android
 npx cap run android
 ```
 ### For Android Studio
 ```bash
 # 1. Open Android Studio
 # 2. File → Open → /path/to/daily-notification-plugin/android
 # 3. Wait for Gradle sync
 # 4. Build → Make Project (Ctrl+F9)
 ```
 ## Prerequisites
 ### Required Software
 - **Android Studio** (latest stable version)
 - **Java 11+** (for Kotlin compilation)
 - **Android SDK** with API level 21+
 - **Node.js** 16+ (for TypeScript compilation)
 - **npm** or **yarn** (for dependency management)
 ### Required Tools
 - **Gradle Wrapper** (included in project)
 - **Kotlin** (configured in build.gradle)
 - **TypeScript** (for plugin interface)
 ### System Requirements
 - **RAM**: 4GB minimum, 8GB recommended
 - **Storage**: 2GB free space
 - **OS**: Windows 10+, macOS 10.14+, or Linux
 ## Build Methods
 ### Method 1: Automated Build Script (Recommended)
 The project includes an automated build script that handles both TypeScript and native compilation:
 ```bash
 # Build all platforms
 ./scripts/build-native.sh
 # Build specific platform
 ./scripts/build-native.sh --platform android
 ./scripts/build-native.sh --platform ios
 # Build with verbose output
 ./scripts/build-native.sh --verbose
 ```
 **What it does:**
 1. Compiles TypeScript to JavaScript
 2. Bundles plugin code with Rollup
 3. Builds native Android/iOS code
 4. Handles plugin development project detection
 5. Provides helpful warnings and guidance
 ### Method 2: Manual Command Line
 #### TypeScript Compilation
 ```bash
 # Clean previous builds
 npm run clean
 # Build TypeScript and bundle
 npm run build
 # Watch mode for development
 npm run build:watch
 ```
 #### Android Native Build
 ```bash
 # Navigate to Android directory
 cd android
 # Build using Gradle Wrapper
 ./gradlew build
 # Build release AAR
 ./gradlew assembleRelease
 # Run tests
 ./gradlew test
 ```
 #### iOS Native Build
 ```bash
 # Navigate to iOS directory
 cd ios
 # Install CocoaPods dependencies
 pod install
 # Build using Xcode (command line)
 xcodebuild -workspace DailyNotificationPlugin.xcworkspace -scheme DailyNotificationPlugin -configuration Release
 ```
 ### Method 3: Android Studio
 See [Android Studio Setup](#android-studio-setup) for detailed instructions.
 ## Android Studio Setup
 ### Opening the Project
 #### Important: Open the Correct Directory
 ```bash
 # ✅ CORRECT: Open the android/ folder
 File → Open → /path/to/daily-notification-plugin/android
 # ❌ WRONG: Don't open the root project folder
 # This will cause Gradle sync issues
 ```
 ### Initial Configuration
 #### 1. Gradle Sync
 - Android Studio will prompt to sync Gradle
 - Click **"Sync Now"** or use the sync button in the toolbar
 - Wait for sync to complete (may take a few minutes)
 #### 2. SDK Configuration
 ```
 File → Project Structure → SDK Location
 - Android SDK: /path/to/Android/Sdk
 - JDK Location: /path/to/jdk-11
 ```
 #### 3. Gradle Settings
 ```
 File → Settings → Build → Gradle
 - Use Gradle from: 'gradle-wrapper.properties' file
 - Gradle JVM: Project SDK (Java 11)
 ```
 #### 4. Kotlin Configuration
 ```
 File → Settings → Languages & Frameworks → Kotlin
 - Target JVM version: 1.8
 - Language version: 1.5
 ```
 ### Building in Android Studio
 #### Build Commands
 ```bash
 # Build the project
 Build → Make Project (Ctrl+F9)
 # Clean and rebuild
 Build → Clean Project
 Build → Rebuild Project
 # Generate signed APK/AAR
 Build → Generate Signed Bundle / APK
 ```
 #### Build Output
 The built plugin AAR will be located at:
 ```
 android/build/outputs/aar/android-release.aar
 ```
 ### Project Structure in Android Studio
 When opened correctly, you'll see:
 ```
 android/
 ├── app/                           # Test app (may not be fully configured)
 │   ├── build.gradle
 │   ├── src/main/
 │   └── ...
 ├── src/main/java/                # Plugin source code
 │   └── com/timesafari/dailynotification/
 │       ├── DailyNotificationPlugin.kt
 │       ├── DailyNotificationBackgroundTask.kt
 │       ├── DailyNotificationConfig.kt
 │       └── ...
 ├── build.gradle                  # Module build file
 ├── settings.gradle               # Project settings
 ├── gradle.properties             # Gradle properties
 └── gradle/wrapper/               # Gradle wrapper files
 ```
 ### Important Limitations
 #### This is NOT a Full Android App
 - **No MainActivity** - This is a plugin, 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
 #### What You CAN Do in Android Studio
 ✅ **Edit Kotlin/Java code**  
 ✅ **Run unit tests**  
 ✅ **Debug plugin code**  
 ✅ **Build the plugin AAR**  
 ✅ **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)  
 ## Command Line Building
 ### TypeScript Build Process
 #### 1. Clean Previous Builds
 ```bash
 npm run clean
 # Removes: dist/, build/, out/
 ```
 #### 2. Compile TypeScript
 ```bash
 npm run build
 # Compiles: src/ → dist/
 # Bundles: dist/plugin.js, dist/esm/index.js
 ```
 #### 3. Watch Mode (Development)
 ```bash
 npm run build:watch
 # Automatically rebuilds on file changes
 ```
 ### Android Native Build Process
 #### 1. Navigate to Android Directory
 ```bash
 cd android
 ```
 #### 2. Build Commands
 ```bash
 # Build all variants
 ./gradlew build
 # Build debug variant
 ./gradlew assembleDebug
 # Build release variant
 ./gradlew assembleRelease
 # Clean build
 ./gradlew clean build
 # Run tests
 ./gradlew test
 ```
 #### 3. Build Outputs
 ```bash
 # Plugin AAR files
 android/build/outputs/aar/
 ├── android-debug.aar
 └── android-release.aar
 # Test results
 android/build/reports/tests/test/index.html
 ```
 ### iOS Native Build Process
 #### 1. Navigate to iOS Directory
 ```bash
 cd ios
 ```
 #### 2. Install Dependencies
 ```bash
 pod install
 ```
 #### 3. Build Commands
 ```bash
 # Build using Xcode command line
 xcodebuild -workspace DailyNotificationPlugin.xcworkspace \
           -scheme DailyNotificationPlugin \
           -configuration Release \
           -destination generic/platform=iOS
 # Build for simulator
 xcodebuild -workspace DailyNotificationPlugin.xcworkspace \
           -scheme DailyNotificationPlugin \
           -configuration Debug \
           -destination 'platform=iOS Simulator,name=iPhone 14'
 ```
 ## Testing Strategies
 ### Unit Testing
 #### Android Unit Tests
 ```bash
 # Run all tests
 ./gradlew test
 # Run specific test class
 ./gradlew test --tests "DailyNotificationPluginTest"
 # Run tests with coverage
 ./gradlew test jacocoTestReport
 ```
 #### iOS Unit Tests
 ```bash
 # Run tests using Xcode
 xcodebuild test -workspace DailyNotificationPlugin.xcworkspace \
                -scheme DailyNotificationPlugin \
                -destination 'platform=iOS Simulator,name=iPhone 14'
 ```
 ### Integration Testing
 #### 1. Create Test Capacitor App
 ```bash
 # Create new Capacitor app
 npx @capacitor/create-app@latest TestApp
 cd TestApp
 # Install your plugin
 npm install /path/to/daily-notification-plugin
 # Add platforms
 npx cap add android
 npx cap add ios
 # Sync with Capacitor
 npx cap sync android
 npx cap sync ios
 ```
 #### 2. Test in Android Studio
 ```bash
 # Open test app in Android Studio
 File → Open → TestApp/android
 # Now you can:
 # - Run the app
 # - Test notifications
 # - Debug full integration
 # - Test background tasks
 ```
 #### 3. Test on Device
 ```bash
 # Run on Android device
 npx cap run android
 # Run on iOS device
 npx cap run ios
 ```
 ### Manual Testing Checklist
 #### Basic Functionality
 - [ ] Plugin loads without errors
 - [ ] DailyNotification.configure() works
 - [ ] Background fetching works
 - [ ] Notifications appear
 - [ ] Settings are persisted
 #### Integration Testing
 - [ ] ActiveDid change handling
 - [ ] Settings synchronization
 - [ ] Request pattern matching
 - [ ] Error handling
 - [ ] Network failure recovery
 #### Edge Cases
 - [ ] Network failures
 - [ ] ActiveDid changes during fetch
 - [ ] App backgrounding/foregrounding
 - [ ] Battery optimization settings
 - [ ] Low storage conditions
 ## Development Workflow
 ### For Plugin Development
 #### 1. Edit Plugin Code
 ```bash
 # Edit TypeScript interface
 vim src/definitions.ts
 # Edit Android native code
 vim android/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.kt
 # Edit iOS native code
 vim ios/Plugin/DailyNotificationPlugin.swift
 ```
 #### 2. Build and Test
 ```bash
 # Build plugin
 ./scripts/build-native.sh --platform android
 # Test in Capacitor app
 cd /path/to/test-capacitor-app
 npx cap sync android
 npx cap run android
 ```
 #### 3. Iterate
 ```bash
 # Make changes
 # Build again
 # Test again
 # Repeat until working
 ```
 ### For Production Testing
 #### 1. Test in TimeSafari PWA
 ```bash
 # Install plugin in TimeSafari PWA
 npm install @timesafari/daily-notification-plugin
 # Sync with Capacitor
 npx cap sync android
 npx cap sync ios
 # Test on real devices
 npx cap run android
 npx cap run ios
 ```
 #### 2. Monitor and Debug
 ```bash
 # Check logs
 adb logcat | grep DailyNotification
 # Check plugin metrics
 # Use observability dashboards
 ```
 ## Troubleshooting
 ### Common Issues
 #### Gradle Sync Failures
 ```bash
 # Problem: Gradle sync fails
 # Solution: Check Java version
 java -version  # Should be 11+
 # Solution: Clear Gradle cache
 ./gradlew clean
 rm -rf ~/.gradle/caches/
 ```
 #### Build Failures
 ```bash
 # Problem: Build fails with "Could not read script"
 # Solution: This is a plugin development project
 # The build script handles this automatically
 ./scripts/build-native.sh --platform android
 ```
 #### Android Studio Issues
 ```bash
 # Problem: Android Studio can't find SDK
 # Solution: Configure SDK location
 File → Project Structure → SDK Location
 # Problem: Kotlin compilation errors
 # Solution: Check Kotlin version in build.gradle
 ```
 #### Capacitor Integration Issues
 ```bash
 # Problem: Plugin not found in Capacitor app
 # Solution: Check plugin installation
 npm list @timesafari/daily-notification-plugin
 # Solution: Re-sync Capacitor
 npx cap sync android
 ```
 ### Debug Commands
 #### Android Debugging
 ```bash
 # View Android logs
 adb logcat | grep DailyNotification
 # Check plugin installation
 adb shell pm list packages | grep timesafari
 # Test background tasks
 adb shell am start -n com.capacitorjs.app/.MainActivity
 ```
 #### iOS Debugging
 ```bash
 # View iOS logs
 xcrun simctl spawn booted log stream --predicate 'subsystem contains "DailyNotification"'
 # Check plugin installation
 # Use Xcode Organizer or Device Manager
 ```
 ### Performance Issues
 #### Build Performance
 ```bash
 # Enable Gradle daemon
 echo "org.gradle.daemon=true" >> ~/.gradle/gradle.properties
 # Increase memory
 echo "org.gradle.jvmargs=-Xmx4g" >> ~/.gradle/gradle.properties
 # Enable parallel builds
 echo "org.gradle.parallel=true" >> ~/.gradle/gradle.properties
 ```
 #### Android Studio Performance
 ```bash
 # Increase Android Studio memory
 # Help → Edit Custom VM Options
 -Xmx4g
 -XX:ReservedCodeCacheSize=1g
 ```
 ## Project Structure
 ### Root Directory
 ```
 daily-notification-plugin/
 ├── android/                 # Android native code
 ├── ios/                     # iOS native code
 ├── src/                     # TypeScript plugin interface
 ├── dist/                    # Built plugin files
 ├── scripts/                 # Build scripts
 ├── docs/                    # Documentation
 ├── examples/                # Usage examples
 ├── tests/                   # Test files
 ├── package.json             # Node.js dependencies
 ├── tsconfig.json            # TypeScript configuration
 ├── rollup.config.js         # Bundler configuration
 └── BUILDING.md              # This file
 ```
 ### Android Structure
 ```
 android/
 ├── src/main/java/           # Kotlin plugin code
 ├── build.gradle             # Android build configuration
 ├── settings.gradle          # Gradle settings
 ├── gradle.properties        # Gradle properties
 └── gradle/wrapper/          # Gradle wrapper files
 ```
 ### iOS Structure
 ```
 ios/
 ├── Plugin/                  # Swift plugin code
 ├── DailyNotificationPlugin.xcodeproj/  # Xcode project
 ├── DailyNotificationPlugin.xcworkspace/ # Xcode workspace
 ├── Podfile                  # CocoaPods dependencies
 └── Tests/                   # iOS unit tests
 ```
 ### TypeScript 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
 ```
 ## Best Practices
 ### Code Organization
 - Keep plugin code modular and testable
 - Use consistent naming conventions
 - Document all public APIs
 - Follow platform-specific coding standards
 ### Build Optimization
 - Use incremental builds when possible
 - Cache build artifacts
 - Parallelize builds where supported
 - Monitor build times and optimize
 ### Testing Strategy
 - Write unit tests for all plugin logic
 - Test on real devices, not just simulators
 - Test edge cases and error conditions
 - Monitor performance and memory usage
 ### Documentation
 - Keep BUILDING.md updated
 - Document all build requirements
 - Provide troubleshooting guides
 - Include examples and best practices
 ## Support
 ### Getting Help
 - Check the [troubleshooting section](#troubleshooting)
 - Review [GitHub issues](https://github.com/timesafari/daily-notification-plugin/issues)
 - Consult [Capacitor documentation](https://capacitorjs.com/docs)
 - Ask in [Capacitor community](https://github.com/ionic-team/capacitor/discussions)
 ### Contributing
 - Follow the [contributing guidelines](CONTRIBUTING.md)
 - Test all changes thoroughly
 - Update documentation as needed
 - Submit pull requests with clear descriptions
 ---
 **Remember**: This is a Capacitor plugin development project. For full functionality testing, use it in a Capacitor host application, not as a standalone Android/iOS app.