A template project for creating Rust libraries that can be embedded in multiple platforms using UniFFI for automatic binding generation.

📝 Using this as a template? Run ./scripts/run_me_first.sh to customize all project names!

• What is This?
• Template Functions
• Quick Start
  • Prerequisites
  • Setup
• Demo Applications
  • iOS/macOS App
  • Android App
  • Desktop CLI App
• Building
  • Build All Platforms
  • Build Specific Platforms
• Using the Generated Libraries
  • iOS/macOS (Swift)
  • Android (Kotlin/Java)
  • JVM Desktop (Kotlin/Java)
• Project Structure
• Testing
  • Test All Platforms
  • Test Specific Platforms
• Documentation
  • Generate Documentation for All Platforms
  • View Documentation Locally
  • Publishing Documentation
• Development
• Contributing
• Contact
• License
• Resources

This template demonstrates how to write Rust code once and use it across:

• iOS (arm64 devices)
• iOS Simulator (arm64 M1+ and x86_64 Intel)
• macOS (arm64 Apple Silicon)
• Android (arm64-v8a, armeabi-v7a, x86, x86_64)
• JVM (Desktop applications in Java/Kotlin)

The template uses UniFFI to automatically generate Swift and Kotlin bindings from your Rust code.

This template includes two async example functions:

• echo(input, token) → Returns an EchoResult with text, length, and timestamp, or null/nil if empty (demonstrates optional returns, structured data, and cancellation)
• random() → Returns a random number between 0.0 and 1.0 (demonstrates async functions and working with dependencies)

If you're using this repository as a GitHub template, start here:

# 1. Clone the template
git clone https://github.com/yourusername/rust-multiplatform-template-lib.git my-project
cd my-project

# 2. Run the initialization script (interactive)
./scripts/run_me_first.sh

# This will guide you through:
# - Setting your Rust crate name
# - Setting your Swift module name
# - Setting your Java/Kotlin package name
# - Updating all ~50+ files in the project
# - Updating demo applications
# - Cleaning build artifacts

That's it! Your project is now customized with your names.

• Rust - Install from rustup.rs
• Xcode (for iOS/macOS) - Required for Apple platforms
• Android SDK & NDK (for Android/JVM) - Required for Kotlin multiplatform builds
  • Set ANDROID_HOME environment variable, or
  • Create platforms/kotlin/local.properties with sdk.dir path
  • See platforms/kotlin/README.md for setup details

# Install required Rust targets
./scripts/setup.sh

# Build for all platforms
./scripts/build-all.sh

That's it! The library is now built for iOS, macOS, Android, and JVM.

This template includes three complete demo applications that show how to use the Rust library:

A SwiftUI app for iOS 14+ and macOS 11+ with interactive UI.

Location: apps/apple/

Run:

# 1. Build the library
./scripts/build-apple.sh

# 2. Open in Xcode
cd apps/apple
open DemoApp.xcodeproj

# 3. Select iPhone simulator or My Mac, then press Cmd+R

Features:

• Color-coded sections for each function
• Text input field for echo testing
• Real-time result display with EchoResult metadata
• Error handling with alerts
• Async/await with Swift concurrency

A Jetpack Compose app for Android 5.0+ (API 21+).

Location: apps/android/

Run:

# 1. Build the Kotlin library
./scripts/build-kotlin.sh

# 2. Build the AAR (Android Archive)
cd platforms/kotlin
./gradlew assembleRelease
cd ../..

# 3. Open in Android Studio
# File -> Open -> Select apps/android/

# 4. Run on emulator or device

Features:

• Material Design 3 with Jetpack Compose
• Color-coded cards for each function
• Interactive text input
• Modern Android UI patterns
• Coroutines for async operations

A command-line JVM application that runs on macOS, Linux, and Windows.

Location: apps/desktop/

Run:

# 1. Build the Kotlin library and publish to Maven Local
cd platforms/kotlin
./gradlew publishToMavenLocal
cd ../..

# 2. Run the desktop app
cd apps/desktop
./gradlew run

# Or build a standalone JAR
./gradlew jar
java -jar build/libs/template-demo-desktop-1.0.0.jar

Features:

• Automated testing of both functions
• Detailed output with statistics
• Portable JAR file
• No GUI dependencies
• Async support with Kotlin coroutines

./scripts/build-all.sh

This will build for all supported platforms (Apple, Android, JVM).

Apple platforms (iOS + macOS):

./scripts/build-apple.sh

Android + JVM:

./scripts/build-kotlin.sh

1. In Xcode: File → Add Package Dependencies
2. Click Add Local and select the platforms/apple directory
3. Add the Template package to your target
4. Import and use in Swift:

import Template

// Echo function (async)
Task {
    do {
        let result = try await echo(input: "Hello!", token: nil)
        if let echoResult = result {
            print("Text: \(echoResult.text)")
            print("Length: \(echoResult.length)")
        }
    } catch {
        print("Error: \(error)")
    }
}

// Random function (async)
Task {
    let number = await random()
    print("Random: \(number)")
}

1. Build and publish to Maven Local:

   cd platforms/kotlin
   ./gradlew publishToMavenLocal

2. Add to your app's build.gradle.kts:

   dependencies {
       implementation("com.template:template:0.1.0")
   }

3. Use in Kotlin:

   import kotlinx.coroutines.launch
   import uniffi.rust_multiplatform_template_lib.*
   
   // Echo function (async)
   scope.launch {
       val result = templateEcho("Hello!", null)
       if (result != null) {
           println("Text: ${result.text}")
           println("Length: ${result.length}")
       }
   }
   
   // Random function (async)
   scope.launch {
       val number = templateRandom()
       println("Random: $number")
   }

Same as Android - the Kotlin Multiplatform setup supports both Android and JVM targets.

rust-multiplatform-template-lib/
├── src/                          # Rust source code
│   ├── lib.rs                    # Library entry point
│   ├── template.rs               # Core Rust functions
│   └── template.udl              # UniFFI interface definition
├── tests/                        # Rust integration tests
│   └── template_tests.rs         # Test suite
├── platforms/                    # Platform-specific bindings
│   ├── apple/                    # iOS/macOS Swift package
│   │   ├── Package.swift         # Swift Package Manager manifest
│   │   ├── Sources/Template/     # Generated Swift bindings
│   │   ├── Tests/                # Swift tests
│   │   └── xcframework/          # Built XCFramework
│   └── kotlin/                   # Android/JVM Kotlin package
│       ├── build.gradle.kts      # Gradle build configuration
│       ├── src/
│       │   ├── commonMain/kotlin/    # Generated Kotlin bindings
│       │   ├── commonTest/kotlin/    # Kotlin tests
│       │   ├── jniLibs/              # Android native libraries
│       │   └── jvmMain/kotlin/       # JVM native libraries
│       └── settings.gradle.kts
├── apps/                         # Demo applications
│   ├── apple/                    # iOS/macOS SwiftUI app
│   │   ├── DemoApp.xcodeproj/        # Xcode project
│   │   ├── TemplateDemo/             # Source files
│   │   └── README.md
│   ├── android/                  # Android Compose app
│   │   ├── app/                      # App module
│   │   │   ├── src/main/             # Source files
│   │   │   └── build.gradle.kts
│   │   ├── build.gradle.kts
│   │   └── settings.gradle.kts
│   └── desktop/                  # Desktop CLI JVM app
│       ├── src/main/kotlin/          # Kotlin source
│       ├── build.gradle.kts
│       └── settings.gradle.kts
├── scripts/                      # Build, test, and documentation scripts
│   ├── build-all.sh              # Build all platforms
│   ├── build-apple.sh            # Build script for iOS/macOS
│   ├── build-kotlin.sh           # Build script for Android/JVM
│   ├── test-all.sh               # Test all platforms
│   ├── test-apple.sh             # Test script for iOS/macOS
│   ├── test-kotlin.sh            # Test script for Android/JVM
│   ├── doc-all.sh                # Generate documentation
│   └── setup.sh                  # Install Rust targets
├── docs_src/                     # Documentation source (markdown)
│   ├── UDL_GUIDE.md              # UniFFI interface guide
│   ├── SWIFT_EXAMPLES.md         # Swift usage examples
│   ├── KOTLIN_EXAMPLES.md        # Kotlin usage examples
│   └── TESTING.md                # Testing guide
├── docs/                         # Generated documentation (HTML)
│   ├── *.html                    # HTML from markdown (auto-generated)
│   └── lib/                      # Rust API docs (from cargo doc)
├── Cargo.toml                    # Rust package manifest
├── DEVELOPMENT.md                # Development guide
├── CONTRIBUTING.md               # Contributing guidelines
└── README.md                     # This file

./scripts/test-all.sh

This will run tests for:

• Rust core library (unit, integration, and doc tests)
• Apple platforms (iOS + macOS Swift tests)
• Kotlin platforms (Android + JVM tests)

Test Rust code:

cargo test

Test Apple platforms (iOS + macOS):

./scripts/test-apple.sh

Test Kotlin platforms (Android + JVM):

./scripts/test-kotlin.sh

Manual testing (if needed):

For Swift:

cd platforms/apple
swift test

For Kotlin:

cd platforms/kotlin
./gradlew test

The project documentation is organized into two directories:

• docs_src/ - Source markdown files (edit these)
• docs/ - Generated HTML documentation (auto-generated, published to GitHub Pages)

./scripts/doc-all.sh

This will generate API documentation for:

• Rust → docs/lib/index.html

After running ./scripts/doc-all.sh, open the generated HTML files in your browser:

open docs/lib/index.html

Or start a local web server:

cd docs && python3 -m http.server 8000
# Then open: http://localhost:8000/

1. Add markdown files to docs_src/ for platform-specific guides
2. Root-level documentation (README.md, DEVELOPMENT.md, CONTRIBUTING.md) stays in project root
3. CI/CD automatically converts markdown to HTML and publishes to GitHub Pages

Documentation is automatically published to GitHub Pages when you push to main:

git add docs/ docs_src/
git commit -m "Update documentation"
git push

The GitHub Actions workflow handles:

• Converting markdown → HTML
• Generating Rust API docs
• Deploying to gh-pages branch

For contributors and maintainers, see DEVELOPMENT.md for detailed instructions on:

• Setting up your development environment
• Building and testing
• Adding new features
• Customizing the template
• Troubleshooting common issues
• Contributing guidelines

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Reporting bugs
• Suggesting enhancements
• Submitting pull requests
• Development workflow

Ezequiel (Kimi) Aceto

• 📧 Email: eaceto@pm.me
• 🌐 Website: eaceto.dev
• 💼 LinkedIn: linkedin.com/in/ezequielaceto
• 🐙 GitHub: @eaceto

For questions, issues, or discussions about this project:

• 🐛 Report issues
• 💬 Start a discussion

MIT License - see LICENSE for details.

Copyright (c) 2025 Ezequiel (Kimi) Aceto

• UniFFI Documentation
• Rust Book
• Swift Package Manager
• Kotlin Multiplatform