RSSuper/native-route/README.md

# RSSuper - Multi-Platform Native Build System

This directory contains the build infrastructure for building RSSuper natively across multiple platforms.

## Architecture

```
native-route/
├── ios/          - iOS/macOS app (Swift/SwiftUI)
│   └── RSSuper/
│       ├── RSSuper.xcodeproj/
│       ├── RSSuper/
│       ├── RSSuperTests/
│       └── RSSuperUITests/
├── android/      - Android app (Kotlin/Jetpack Compose)
│   └── (auto-generated on first build)
├── linux/        - Linux app (C/Vala + GTK4)
│   └── (auto-generated on first build)
└── windows/      - Windows app (TODO)
```

## Quick Start

### Build All Platforms

```bash
# From project root
./scripts/build.sh
```

### Build Specific Platform

```bash
# iOS/macOS only
./scripts/build.sh -p ios

# Android only
./scripts/build.sh -p android

# Linux only
./scripts/build.sh -p linux

# Multiple platforms
./scripts/build.sh -p ios,android
```

### Build Types

```bash
# Debug build (default)
./scripts/build.sh -t debug

# Release build
./scripts/build.sh -t release
```

### Run Tests

```bash
# Build and test all platforms
./scripts/build.sh --test

# Test specific platform
./scripts/build.sh -p ios --test
```

### Clean Build

```bash
# Clean all platforms
./scripts/build.sh -a clean

# Clean specific platform
./scripts/build-ios.sh clean
./scripts/build-android.sh clean
./scripts/build-linux.sh clean
```

## Individual Platform Scripts

### iOS/macOS

```bash
# Build
./scripts/build-ios.sh [Debug|Release] [iOS|macOS] [destination] [action]

# Examples
./scripts/build-ios.sh                          # Debug iOS
./scripts/build-ios.sh Release                  # Release iOS
./scripts/build-ios.sh Debug iOS "platform=iOS Simulator,name=iPhone 15"
./scripts/build-ios.sh clean
./scripts/build-ios.sh Debug iOS "generic/platform=iOS" test
```

### Android

```bash
# Build
./scripts/build-android.sh [debug|release] [assemble|build|test|clean]

# Examples
./scripts/build-android.sh                    # Assemble debug
./scripts/build-android.sh release            # Assemble release
./scripts/build-android.sh debug test         # Run tests
./scripts/build-android.sh clean              # Clean
```

### Linux

```bash
# Build
./scripts/build-linux.sh [debug|release] [build|install|test|clean|setup]

# Examples
./scripts/build-linux.sh                     # Build debug
./scripts/build-linux.sh release             # Build release
./scripts/build-linux.sh debug setup         # Setup build environment
./scripts/build-linux.sh debug install-deps  # Install dependencies
./scripts/build-linux.sh debug run           # Build and run
./scripts/build-linux.sh clean               # Clean
```

## Platform-Specific Details

### iOS/macOS

- **Language**: Swift
- **UI Framework**: SwiftUI
- **Build System**: Xcode/xcodebuild
- **Minimum Deployment**: iOS 16.0+
- **Features**:
  - SwiftUI for declarative UI
  - Combine for reactive programming
  - Core Data for persistence
  - Background fetch for feed updates

### Android

- **Language**: Kotlin
- **UI Framework**: Jetpack Compose
- **Build System**: Gradle
- **Minimum SDK**: 24 (Android 7.0)
- **Features**:
  - Jetpack Compose for modern UI
  - ViewModel + LiveData for state management
  - Room for local database
  - Retrofit for networking

### Linux

- **Language**: C + Vala
- **UI Framework**: GTK4 + Libadwaita
- **Build System**: Meson + Ninja
- **Dependencies**:
  - GTK4
  - Libadwaita
  - SQLite3
  - libxml2
  - libsoup-3.0
- **Features**:
  - Native Linux look and feel
  - GNOME integration
  - System tray support
  - Desktop notifications

## CI/CD

GitHub Actions workflow is configured in `.github/workflows/ci.yml`:

- **iOS**: Builds on macos-15 runner
- **Android**: Builds on ubuntu-24.04 runner
- **Linux**: Builds on ubuntu-24.04 runner

### Workflow Features

- Automatic builds on push/PR
- Manual trigger with configurable options
- Build artifacts uploaded for download
- Build reports generated
- Test execution (configurable)

## Project Structure Template

When you add shared code, use this structure:

```
RSSuper/
├── native-route/
│   ├── common/           # Shared code (if using a shared language)
│   ├── ios/
│   │   └── RSSuper/
│   ├── android/
│   ├── linux/
│   └── windows/
├── scripts/
│   ├── build.sh          # Main build orchestrator
│   ├── build-ios.sh      # iOS/macOS builder
│   ├── build-android.sh  # Android builder
│   ├── build-linux.sh    # Linux builder
│   └── common.sh         # Shared utilities
└── .github/
    └── workflows/
        └── ci.yml        # CI configuration
```

## Migration Notes

Build scripts adapted from Nessa project:
- Xcode version selection logic
- Build report generation
- Error extraction and display
- CI workflow structure

## Troubleshooting

### iOS Build Fails

```bash
# Check Xcode installation
xcodebuild -version

# Select Xcode manually
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

# Clean DerivedData
rm -rf ~/Library/Developer/Xcode/DerivedData/RSSuper-*
```

### Android Build Fails

```bash
# Check Java installation
java -version

# Check Android SDK
echo $ANDROID_HOME

# Run with more verbose output
./scripts/build-android.sh debug assemble --info
```

### Linux Build Fails

```bash
# Install dependencies (Ubuntu/Debian)
sudo apt install meson ninja-build pkg-config libgtk-4-dev libadwaita-1-dev

# Check meson installation
meson --version

# Setup build manually
cd native-route/linux
meson setup build --buildtype=debug
```

## Future Enhancements

- [ ] Windows support (Win32 + DirectUI or WebView2)
- [ ] Shared business logic layer
- [ ] Cross-platform test suite
- [ ] Automated code signing
- [ ] App store deployment scripts
- [ ] Performance benchmarking