# Building the DailyNotification Plugin

**Author**: Matthew Raymer  
**Last Updated**: 2025-10-12 04:57: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 plugin library (recommended for plugin development)
./gradlew :plugin:assembleRelease

# Build test app (requires proper Capacitor integration)
./gradlew :app:assembleRelease

# Build all modules
./gradlew build

# 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/plugin/build/outputs/aar/plugin-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/
│   └── ...
├── plugin/                        # Plugin library module
│   ├── build.gradle
│   ├── src/main/java/
│   │   └── com/timesafari/dailynotification/
│   │       ├── DailyNotificationPlugin.kt
│   │       ├── FetchWorker.kt
│   │       ├── NotifyReceiver.kt
│   │       └── ...
│   └── build/outputs/aar/
│       └── plugin-release.aar    # Built plugin AAR
├── build.gradle                  # Root 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

# Problem: Build fails with "Could not resolve project :capacitor-cordova-android-plugins"
# Solution: Build the plugin module instead of the test app
./gradlew :plugin:assembleRelease

# Problem: Build fails with "Cannot locate tasks that match ':android:assembleRelease'"
# Solution: Use correct project name - available projects are:
# - :app (test app, may have Capacitor issues)
# - :plugin (plugin library, recommended)
# - :capacitor-android
# - :capacitor-cordova-android-plugins
./gradlew :plugin:assembleRelease

# Problem: Build fails with "Plugin with id 'kotlin-android' not found"
# Solution: The plugin module doesn't need Kotlin plugin for Java/Kotlin code
# Check the plugin/build.gradle file
```

#### Capacitor Integration Warnings
```bash
# ⚠️  WARNING: capacitor.build.gradle is auto-generated!
# Any manual fixes will be lost when running:
# - npx cap sync
# - npx cap update  
# - npx cap add android

# ⚠️  NOTE: npx cap sync will fail in plugin development projects!
# This is expected - plugin projects don't have www/ directory
# Error: "Could not find the web assets directory: ./www"
# This is normal for plugin development projects

# To fix after Capacitor operations:
./scripts/fix-capacitor-build.sh

# Or use the build script (applies fix 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.