Skip to content

Latest commit

 

History

History
234 lines (173 loc) · 7.47 KB

ANDROID.md

File metadata and controls

234 lines (173 loc) · 7.47 KB

Orange SDK Android Bindings - Build Guide

This document outlines the complete process for generating Android UniFFI bindings and preparing them for Maven Central publication.

Prerequisites

  • Rust with Android targets: Install Android cross-compilation targets
  • Android NDK: Located at /opt/android-ndk (or set ANDROID_NDK_ROOT)
  • Android SDK: Located at ~/Android/Sdk (or set ANDROID_SDK_ROOT)
  • GPG Key: For signing Maven Central artifacts

Quick Build Process

1. Generate Android Bindings with Native Libraries

# This script handles everything: cross-compilation + bindings generation
./scripts/uniffi_bindgen_generate_kotlin_android.sh

This script:

  • Installs required Rust targets (x86_64-linux-android, aarch64-linux-android, armv7-linux-androideabi)
  • Cross-compiles for 3 Android architectures using Android NDK
  • Generates Kotlin bindings using uniffi-android.toml config
  • Places native libraries in proper jniLibs/ directories
  • Creates complete Android Gradle project structure

2. Build Android Library (AAR)

cd bindings/kotlin/orange-sdk-android
ANDROID_SDK_ROOT="~/Android/Sdk" ./gradlew build

This generates:

  • lib-release.aar - Production Android library
  • lib-debug.aar - Debug version
  • Contains Kotlin bindings + native libraries for all architectures

3. Create Complete Maven Central Package

# Basic usage (will prompt for GPG passphrase if needed)
./scripts/create_android_maven_package.sh YOUR_GPG_KEY_ID

# With passphrase for automated signing
./scripts/create_android_maven_package.sh YOUR_GPG_KEY_ID "your_passphrase"

# For CI/CD - use environment variables (more secure)
export GPG_KEY_ID="YOUR_GPG_KEY_ID"
export GPG_PASSPHRASE="your_passphrase"
./scripts/create_android_maven_package.sh

# Find your GPG key ID
gpg --list-secret-keys --keyid-format=long

This consolidated script:

  • Uses Gradle to generate the POM file (following ldk-node pattern)
  • Creates properly named Maven Central artifacts (orange-sdk-android-0.1.0.aar, etc.)
  • Generates sources JAR and javadoc JAR
  • Generates all required checksums (MD5, SHA1, SHA256, SHA512)
  • Signs everything with your GPG key (supports automated signing with passphrase)
  • Creates final ZIP ready for Maven Central upload

Project Structure

bindings/kotlin/orange-sdk-android/
├── lib/
│   ├── build.gradle.kts          # Android library build config
│   ├── src/main/
│   │   ├── kotlin/               # Generated Kotlin bindings
│   │   │   └── org/lightningdevkit/orangesdk/
│   │   │       └── orange_sdk.kt # Main bindings file
│   │   └── jniLibs/              # Native libraries by architecture
│   │       ├── arm64-v8a/
│   │       ├── armeabi-v7a/      
│   │       └── x86_64/
│   └── build/outputs/aar/        # Final AAR artifacts
│       ├── lib-release.aar       # Main library (37MB)
│       └── lib-debug.aar         # Debug version
├── gradle.properties             # Build configuration  
├── settings.gradle.kts
└── build.gradle.kts              # Root project config

Configuration Files

uniffi-android.toml

[bindings.kotlin]
android = true
android_cleaner = true
package_name = "org.lightningdevkit.orangesdk"
cdylib_name = "orange_sdk"

lib/build.gradle.kts (Maven Publishing)

Following the ldk-node pattern, the POM file is generated by Gradle with proper metadata:

  • Group ID: org.lightningdevkit
  • Artifact ID: orange-sdk-android
  • Version: Defined in gradle.properties
  • Dependencies: JNA, Kotlin coroutines, etc.
  • Licensing: Apache 2.0 + MIT
  • SCM info: GitHub repository links

Key Build Settings

  • Package: org.lightningdevkit.orangesdk
  • Min SDK: 21 (Android 5.0)
  • Target SDK: 34
  • Native Architectures: arm64-v8a, armeabi-v7a, x86_64

Maven Central Requirements ✅

The generated artifacts include all Maven Central requirements:

  • Main AAR: Contains compiled Kotlin + native libraries
  • Checksums: MD5, SHA1, SHA256, SHA512 for all artifacts
  • GPG Signatures: .asc files for every artifact
  • Source: Kotlin source code included in AAR
  • Metadata: Android Gradle project provides POM generation

Environment Variables

Set these before building:

export ANDROID_NDK_ROOT="/opt/android-ndk"
export ANDROID_SDK_ROOT="~/Android/Sdk"

Troubleshooting

Build Failures

  • SDK not found: Set ANDROID_SDK_ROOT environment variable
  • NDK not found: Set ANDROID_NDK_ROOT environment variable
  • Cross-compilation fails: Verify Android NDK toolchain is accessible

Native Library Issues

  • Missing architectures: Check that all Rust targets are installed
  • Large file sizes: Native libraries are ~25-37MB each (normal for Rust+LDK)
  • Strip symbols: Build uses release-smaller profile for size optimization

Signing Issues

  • GPG key not found: Run gpg --list-secret-keys to verify keys
  • Wrong key: Pass key ID to signing script: ./sign-maven-artifacts.sh YOUR_KEY_ID

Complete Automation Script

For CI/CD, combine all steps:

#!/bin/bash
set -e

# Set GPG credentials (required - use CI environment variables)
export GPG_KEY_ID="${GPG_SIGNING_KEY_ID}"          # Required: Your GPG key ID
export GPG_PASSPHRASE="${GPG_SIGNING_PASSPHRASE}"  # Optional: For automated signing

# 1. Generate Android bindings and native libraries
./scripts/uniffi_bindgen_generate_kotlin_android.sh

# 2. Build Android library (AAR)
cd bindings/kotlin/orange-sdk-android
ANDROID_SDK_ROOT="$ANDROID_SDK_ROOT" ./gradlew build
cd ../../../

# 3. Create complete Maven Central package (with automated GPG signing)
./scripts/create_android_maven_package.sh

echo "✅ Android Maven Central package ready for upload!"

GPG Security Options:

Interactive (development):

# Will prompt for passphrase
./scripts/create_android_maven_package.sh YOUR_GPG_KEY_ID

Environment variables (CI/CD):

export GPG_KEY_ID="YOUR_GPG_KEY_ID"
export GPG_PASSPHRASE="your_passphrase"
./scripts/create_android_maven_package.sh

GPG Agent (most secure):

# Configure GPG agent to cache passphrase
gpg-connect-agent reloadagent /bye
./scripts/create_android_maven_package.sh YOUR_GPG_KEY_ID

Next Steps

  1. Upload to Maven Central: Use the generated ZIP file
  2. Version Management: Update version in gradle.properties
  3. Release Notes: Document API changes and features
  4. Testing: Verify AAR works in Android projects

Files Generated

The create_android_maven_package.sh script generates:

  • Maven Central ZIP: orange-sdk-android-0.1.0-maven-central.zip (~36MB)
  • Location: maven-central-package/
  • Contents: 40 total files (4 main artifacts × 10 files each)
    • orange-sdk-android-0.1.0.aar - Main Android library
    • orange-sdk-android-0.1.0-sources.jar - Source code
    • orange-sdk-android-0.1.0-javadoc.jar - Documentation
    • orange-sdk-android-0.1.0.pom - Maven metadata
    • All checksums (.md5, .sha1, .sha256, .sha512) for each file
    • All GPG signatures (.asc) for each file

Script Reference

  • uniffi_bindgen_generate_kotlin_android.sh - Generate bindings + native libraries
  • create_android_maven_package.sh - Create complete Maven Central package
  • generate_checksum_files.sh - Generate checksums (used internally)

The Android bindings are now ready for Maven Central publication! 🚀