Skip to content

docs: add local development guide and improve Android build setup #368

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ignaciosantise wants to merge 6 commits into
base: main
Choose a base branch
from
Open

docs: add local development guide and improve Android build setup #368

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
02d7f6d
Save work before archive
ignaciosantise Feb 3, 2026
4fdf8c7
docs: add local development guide and improve Android build setup
ignaciosantise Feb 3, 2026
31c4777
Merge branch 'main' into readme-improvements
ignaciosantise Feb 3, 2026
06a8b92
fix: improve Java version validation in prerequisites check
ignaciosantise Feb 3, 2026
92e7ef0
Merge branch 'main' into readme-improvements
ignaciosantise Feb 4, 2026
2ed2c73
Merge branch 'main' into readme-improvements
ignaciosantise Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 50 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,42 @@ cargo install cargo-ndk --locked

You will also need to install Android Studio and the "NDK (Side by side)" SDK Tools.

### Building Swift Frameworks Locally
## Local Development

This section covers how to build and test yttrium locally on both Android and iOS platforms.

### Android/Kotlin Prerequisites

| Prerequisite | Error when missing | Solution |
| ------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------- |
| Android NDK | Script shows helpful message | Install via Android Studio SDK Manager |
| `ANDROID_NDK_HOME` | "ANDROID_NDK_HOME is not set" | `export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/<version>` |
| `cargo-ndk` | "no such command: ndk" | `cargo install cargo-ndk` |
| Rust targets | "target may not be installed" | `rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android` |
| Java 17 | "Android Gradle plugin requires Java 17" | Use Zulu JDK, Homebrew, or Android Studio's bundled JDK |
Comment on lines +97 to +103
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error message shown in the prerequisites table does not match the actual error message generated by the script. The script outputs "ERROR: Java 17 or higher is required (found Java X)" (line 57 of generate_kotlin_locally.sh), but the table shows "Android Gradle plugin requires Java 17" which is a different error that might come from Gradle itself, not from the prerequisite check. Consider updating the table to show the actual error from the check_prerequisites function, or clarify that this is the Gradle build error (which would occur if the prerequisite check is skipped).

Suggested change
| Prerequisite | Error when missing | Solution |
| ------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------- |
| Android NDK | Script shows helpful message | Install via Android Studio SDK Manager |
| `ANDROID_NDK_HOME` | "ANDROID_NDK_HOME is not set" | `export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/<version>` |
| `cargo-ndk` | "no such command: ndk" | `cargo install cargo-ndk` |
| Rust targets | "target may not be installed" | `rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android` |
| Java 17 | "Android Gradle plugin requires Java 17" | Use Zulu JDK, Homebrew, or Android Studio's bundled JDK |
| Prerequisite | Error when missing | Solution |
| ------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Android NDK | Script shows helpful message | Install via Android Studio SDK Manager |
| `ANDROID_NDK_HOME` | "ANDROID_NDK_HOME is not set" | `export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/<version>` |
| `cargo-ndk` | "no such command: ndk" | `cargo install cargo-ndk` |
| Rust targets | "target may not be installed" | `rustup target add aarch64-linux-android armv7-linux-android x86_64-linux-android` |
| Java 17 | "ERROR: Java 17 or higher is required (found Java X)" | Use Zulu JDK, Homebrew, or Android Studio's bundled JDK |

Copilot uses AI. Check for mistakes.

### Android Local Testing Workflow

1. Build and publish to Maven Local:
```bash
./generate_kotlin_locally.sh
```
2. In the consuming app's `build.gradle`, add `mavenLocal()` to repositories:
```gradle
repositories {
mavenLocal()
// ... other repos
}
```
3. Change the dependency to use the local version:
```gradle
// "unspecified" is the default version for Maven Local publishes
implementation("com.github.reown-com:yttrium-utils:unspecified")
```

### iOS/Swift Local Testing Workflow

#### Building Swift Frameworks Locally

To build and test the Swift XCFrameworks locally:

Expand Down Expand Up @@ -136,6 +171,20 @@ git update-index --no-assume-unchanged Package.swift
git checkout -- Package.swift
```

#### CocoaPods (Alternative)

1. Modify `YttriumUtilsWrapper.podspec` to use local paths:
```ruby
spec.source = { :path => "." }
spec.vendored_frameworks = "target/ios-utils/libyttrium-utils.xcframework"
spec.source_files = "platforms/swift/Sources/YttriumUtils/**/*.swift"
```
2. Update the app's Podfile:
```ruby
pod 'YttriumUtilsWrapper', :path => '/path/to/yttrium'
```
3. Run `pod install`

### Setup

After installing the above dependencies, you can run `just ci` to run the checks that CI does and initialize your repo.
Expand Down
2 changes: 1 addition & 1 deletion crates/kotlin-ffi/android/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ subprojects {

java {
toolchain {
languageVersion.set(JavaLanguageVersion.of(11))
languageVersion.set(JavaLanguageVersion.of(17))
Copy link
Copy Markdown
Contributor

@github-actions github-actions Bot Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Auto Review Issue: Java version mismatch between toolchain and compile options

Severity: MEDIUM
Category: configuration
Tool: Claude Auto Review

Context:

  • Pattern: Java toolchain set to version 17 (line 76) but compileOptions/kotlinOptions still use version 11 (lines 57-62)
  • Risk: Toolchain enforces Java 17 for compilation but bytecode targets Java 11, creating potential incompatibility
  • Impact: Build may succeed but runtime crashes on Java 11 JVMs, or Gradle may reject the inconsistent configuration
  • Trigger: Running the build with this configuration

Recommendation: Update compile options to match toolchain:

compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

kotlinOptions {
    jvmTarget = "17"
}

Copy link
Copy Markdown
Collaborator Author

@ignaciosantise ignaciosantise Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are you sure about this?

Java compilers can produce bytecode for older versions (that's what targetCompatibility does)
Using Java 17 to compile Java 11-compatible code works fine
This won't cause "runtime crashes on Java 11 JVMs" - the bytecode IS Java 11 compatible

Copy link
Copy Markdown
Collaborator Author

@ignaciosantise ignaciosantise Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@claude review

}
}

Expand Down
85 changes: 77 additions & 8 deletions generate_kotlin_locally.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,73 @@ fi

echo "Using ANDROID_NDK_HOME: $ANDROID_NDK_HOME"

check_prerequisites() {
local has_error=0

# Check cargo-ndk
if ! command -v cargo-ndk &> /dev/null; then
echo "ERROR: cargo-ndk is not installed!"
echo "Please install it with:"
echo " cargo install cargo-ndk"
echo ""
has_error=1
fi

# Check Rust Android targets
local required_targets=("aarch64-linux-android" "armv7-linux-androideabi" "x86_64-linux-android")
local installed_targets
installed_targets=$(rustup target list --installed 2>/dev/null || echo "")
local missing_targets=()
for target in "${required_targets[@]}"; do
if ! echo "$installed_targets" | grep -q "^${target}$"; then
missing_targets+=("$target")
fi
done
if [ ${#missing_targets[@]} -gt 0 ]; then
echo "ERROR: Missing Rust Android targets: ${missing_targets[*]}"
echo "Please install them with:"
echo " rustup target add ${missing_targets[*]}"
echo ""
has_error=1
fi

# Check Java version (need Java 17+)
if command -v java &> /dev/null; then
local java_version
# Extract major version, handling various JDK output formats
java_version=$(java -version 2>&1 | awk -F'"' '/version/ {print $2}' | cut -d. -f1)
# Fallback for non-standard outputs (e.g., "17.0.1" without quotes)
if [ -z "$java_version" ]; then
java_version=$(java -version 2>&1 | grep -oE '[0-9]+\.[0-9]+' | head -1 | cut -d. -f1)
Comment on lines +50 to +54
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Java version detection will produce a confusing error message for Java 8. Java 8 reports its version as "1.8.0_xxx", and cutting on the first dot-separated field will extract "1" instead of "8". While the script will correctly reject Java 8 (since 1 < 17), the error message will say "found Java 1" instead of "found Java 8", which may confuse users.

Consider handling the legacy "1.x" version format explicitly to extract the correct major version for better error messages.

Suggested change
# Extract major version, handling various JDK output formats
java_version=$(java -version 2>&1 | awk -F'"' '/version/ {print $2}' | cut -d. -f1)
# Fallback for non-standard outputs (e.g., "17.0.1" without quotes)
if [ -z "$java_version" ]; then
java_version=$(java -version 2>&1 | grep -oE '[0-9]+\.[0-9]+' | head -1 | cut -d. -f1)
local java_version_raw
# Extract full version string, handling standard JDK output formats (e.g., "1.8.0_402", "17.0.1")
java_version_raw=$(java -version 2>&1 | awk -F'"' '/version/ {print $2}')
if [ -n "$java_version_raw" ]; then
# Handle legacy "1.x" format (Java 8 and earlier) by taking the second component as major
if [[ "$java_version_raw" == 1.* ]]; then
java_version=$(echo "$java_version_raw" | cut -d. -f2)
else
java_version=$(echo "$java_version_raw" | cut -d. -f1)
fi
fi
# Fallback for non-standard outputs (e.g., version without quotes)
if [ -z "$java_version" ]; then
java_version_raw=$(java -version 2>&1 | grep -oE '[0-9]+\.[0-9]+' | head -1)
if [ -n "$java_version_raw" ]; then
if [[ "$java_version_raw" == 1.* ]]; then
java_version=$(echo "$java_version_raw" | cut -d. -f2)
else
java_version=$(echo "$java_version_raw" | cut -d. -f1)
fi
fi

Copilot uses AI. Check for mistakes.
fi
if [ -n "$java_version" ] && [ "$java_version" -ge 1 ] 2>/dev/null && [ "$java_version" -lt 17 ]; then
echo "ERROR: Java 17 or higher is required (found Java $java_version)"
echo "Please install Java 17+ using one of:"
echo " - Android Studio's bundled JDK"
echo " - Homebrew: brew install openjdk@17"
echo " - Zulu JDK: https://www.azul.com/downloads/"
echo ""
has_error=1
fi
Comment on lines +56 to +64
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If Java version extraction fails completely (both primary and fallback methods), the variable java_version will be empty, and the version check will be silently skipped, allowing the script to proceed. While Gradle itself will catch Java version issues later, it would be more user-friendly to provide early feedback with a warning when version detection fails. Consider adding:

if [ -z "$java_version" ] || ! [[ "$java_version" =~ ^[0-9]+$ ]]; then
    echo "WARNING: Could not determine Java version"
    echo "The build may fail if Java 17+ is not installed"
    echo ""
fi

Copilot uses AI. Check for mistakes.
else
echo "ERROR: Java is not installed!"
echo "Please install Java 17+ using one of:"
echo " - Android Studio's bundled JDK"
echo " - Homebrew: brew install openjdk@17"
echo " - Zulu JDK: https://www.azul.com/downloads/"
echo ""
has_error=1
fi

if [ $has_error -eq 1 ]; then
exit 1
fi

echo "All prerequisites satisfied"
}

check_prerequisites

# Link-time optimization flag for dead code elimination (Android targets only)
# Using target-specific RUSTFLAGS avoids conflicts with macOS host builds
export CARGO_TARGET_AARCH64_LINUX_ANDROID_RUSTFLAGS="-C link-arg=-Wl,--gc-sections"
Expand Down Expand Up @@ -171,19 +238,20 @@ install_variant_sources() {

# Process yttrium.kt:
# 1. Change package: uniffi.yttrium -> uniffi.yttrium_utils
# 2. Change imports: uniffi.uniffi_yttrium -> uniffi.uniffi_yttrium_utils
# 3. Change type references: uniffi.yttrium.Type -> uniffi.yttrium_utils.Type
# 2. Change type references: uniffi.yttrium.X -> uniffi.yttrium_utils.X
# 3. Change imports: uniffi.uniffi_yttrium -> uniffi.uniffi_yttrium_utils
# 4. Change library name: "uniffi_yttrium" -> "uniffi_yttrium_utils"
if command -v perl >/dev/null 2>&1; then
perl -0pi -e 's/\bpackage\s+uniffi\.yttrium\b/package uniffi.yttrium_utils/g' "$kotlin_base/yttrium.kt"
perl -0pi -e 's/\buniffi\.yttrium(?!_utils)\b/uniffi.yttrium_utils/g' "$kotlin_base/yttrium.kt"
perl -0pi -e 's/\buniffi\.uniffi_yttrium(?!_utils)\b/uniffi.uniffi_yttrium_utils/g' "$kotlin_base/yttrium.kt"
perl -0pi -e 's/\buniffi\.yttrium\.(\w)/uniffi.yttrium_utils.$1/g' "$kotlin_base/yttrium.kt"
perl -0pi -e 's/return "uniffi_yttrium"/return "uniffi_yttrium_utils"/g' "$kotlin_base/yttrium.kt"
else
sed -i '' 's/^package uniffi\.yttrium$/package uniffi.yttrium_utils/' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.yttrium\([^_]\)/uniffi.yttrium_utils\1/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.yttrium$/uniffi.yttrium_utils/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.uniffi_yttrium\([^_]\)/uniffi.uniffi_yttrium_utils\1/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.uniffi_yttrium$/uniffi.uniffi_yttrium_utils/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.yttrium\.\([A-Za-z]\)/uniffi.yttrium_utils.\1/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/return "uniffi_yttrium"/return "uniffi_yttrium_utils"/g' "$kotlin_base/yttrium.kt" || true
fi
fi
Expand All @@ -208,19 +276,20 @@ install_variant_sources() {

# Process yttrium.kt:
# 1. Change package: uniffi.yttrium -> uniffi.yttrium_wcpay
# 2. Change imports: uniffi.uniffi_yttrium -> uniffi.uniffi_yttrium_wcpay
# 3. Change type references: uniffi.yttrium.Type -> uniffi.yttrium_wcpay.Type
# 2. Change type references: uniffi.yttrium.X -> uniffi.yttrium_wcpay.X
# 3. Change imports: uniffi.uniffi_yttrium -> uniffi.uniffi_yttrium_wcpay
# 4. Change library name: "uniffi_yttrium" -> "uniffi_yttrium_wcpay"
if command -v perl >/dev/null 2>&1; then
perl -0pi -e 's/\bpackage\s+uniffi\.yttrium\b/package uniffi.yttrium_wcpay/g' "$kotlin_base/yttrium.kt"
perl -0pi -e 's/\buniffi\.yttrium(?!_wcpay)\b/uniffi.yttrium_wcpay/g' "$kotlin_base/yttrium.kt"
perl -0pi -e 's/\buniffi\.uniffi_yttrium(?!_wcpay)\b/uniffi.uniffi_yttrium_wcpay/g' "$kotlin_base/yttrium.kt"
perl -0pi -e 's/\buniffi\.yttrium\.(\w)/uniffi.yttrium_wcpay.$1/g' "$kotlin_base/yttrium.kt"
perl -0pi -e 's/return "uniffi_yttrium"/return "uniffi_yttrium_wcpay"/g' "$kotlin_base/yttrium.kt"
else
sed -i '' 's/^package uniffi\.yttrium$/package uniffi.yttrium_wcpay/' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.yttrium\([^_]\)/uniffi.yttrium_wcpay\1/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.yttrium$/uniffi.yttrium_wcpay/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.uniffi_yttrium\([^_]\)/uniffi.uniffi_yttrium_wcpay\1/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.uniffi_yttrium$/uniffi.uniffi_yttrium_wcpay/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/uniffi\.yttrium\.\([A-Za-z]\)/uniffi.yttrium_wcpay.\1/g' "$kotlin_base/yttrium.kt" || true
sed -i '' 's/return "uniffi_yttrium"/return "uniffi_yttrium_wcpay"/g' "$kotlin_base/yttrium.kt" || true
fi
fi
Expand Down