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.
2 weeks ago · 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.