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.
This commit is contained in:
Matthew Raymer
655
BUILDING.md
Normal file
655
BUILDING.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user