Build & Setup Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide describes the procedures for setting up a development environment and building the RunAnywhere SDK monorepo. The project utilizes a centralized task runner and CMake-based build system to manage a cross-platform C++ core and multiple platform-specific SDK bindings.
Unified Task Runner (./run)
The project provides a unified CLI tool named ./run (or run.bat on Windows) to orchestrate environment scanning, dependency provisioning, and build actions across all SDKs.
The ./run wrapper ensures that paths resolve correctly by deriving the repo root from the script location rather than the current working directory.
Sources: CONTRIBUTING.md:46-52, scripts/CLAUDE.md:27-38, AGENTS.md:144-153
Core Setup Commands
| Command | Action |
|---|---|
./run doctor | Scans host toolchains (Xcode, Android NDK, Node, etc.) and displays buildable targets. |
./run setup | Provisions environment files like local.properties and fetches platform dependencies. |
./run codegen | Regenerates language bindings (Swift, Kotlin, TS, Dart) from Protobuf IDL schemas. |
./run lint | Runs linters and formatters across all SDK modules. |
Sources: CONTRIBUTING.md:52-57, AGENTS.md:154-162, scripts/README.md:32-37
Native Build Architecture
The native build system centers on a single C/C++ core (runanywhere-commons) using CMake. All SDKs interact with this core through a pure C ABI (prefixed with rac_*).
CMake Presets
The project uses CMakePresets.json to define deterministic build configurations for different environments:
- Desktop:
macos-debug,macos-release,linux-debug,windows-x64. - Mobile:
android-arm64,ios-device,ios-simulator. - Web:
wasm.
Sources: AGENTS.md:140-144, scripts/CLAUDE.md:37-43
Native Library Sourcing
The SDKs support two modes for acquiring native binaries, controlled via configuration flags like useLocalNatives:
- Local Build: Compiles C++ source code on the developer's machine.
- Prebuilt Download: Downloads versioned
.so,.xcframework, or.wasmfiles from GitHub Releases.
Sources: bindings/kotlin/AGENTS.md:31-35, AGENTS.md:214-217, bindings/react-native/Docs/DEVELOPMENT.md:45-50
Platform SDK Setup
Kotlin (Android)
The Kotlin SDK is a typed wrapper for Android (min API 24). It requires the Android NDK (pinned version 27.3.13750724).
- Native Compilation: Use
./gradlew setupLocalDevelopmentto build JNI libraries from source. - Library Path: Native binaries are staged into
src/main/jniLibs/. - Build Target: Run
./gradlew assembleDebugto produce the Android AAR.
Sources: bindings/kotlin/AGENTS.md:10-27, bindings/kotlin/AGENTS.md:210-213
React Native
The React Native SDK uses NitroModules (JSI) for zero-serialization bridging. It requires Node.js 22.12+ and Yarn Berry 3.6.1.
IDL and Codegen
Protobuf schemas in idl/ serve as the source of truth for all types.
- Install the toolchain using
scripts/setup/setup-toolchain.sh. - Generate all bindings using
idl/codegen/generate_all.sh. - The system verifies the
idl/SCHEMA_LOCKto ensure consistency across languages.
Sources: AGENTS.md:88-92, scripts/README.md:37, bindings/kotlin/AGENTS.md:83-93
Environment Verification
Before building, verify the host environment using the doctor utility. This prevents build failures due to missing toolchain pins.
| Requirement | Pinned Version | Source of Truth |
|---|---|---|
| Android NDK | 27.3.13750724 | core/VERSIONS |
| CMake | 3.24+ | CMakeLists.txt |
| Node.js | 24 LTS (CI) | bindings/react-native/Docs/DEVELOPMENT.md |
| Xcode | 26+ | AGENTS.md |
Sources: AGENTS.md:210-213, bindings/react-native/Docs/DEVELOPMENT.md:10-15
The build process is successfully completed when native artifacts are staged into the respective SDK jniLibs (Android) or Binaries (iOS) directories, enabling the platform-specific toolchains (Gradle, Xcode, or Yarn) to finalize the build.
Sources: scripts/README.md:95-103, bindings/react-native/Docs/DEVELOPMENT.md:38-42