Skip to content

Support cross-compiling for Android - #314

Open
mdepinet wants to merge 2 commits into
livekit:mainfrom
mdepinet:mike/android-build
Open

mdepinet wants to merge 2 commits into
livekit:mainfrom
mdepinet:mike/android-build

Conversation

@mdepinet

Copy link
Copy Markdown
Contributor

This lets the SDK cross-compile for Android with the NDK's CMake toolchain file. We use client-sdk-cpp in a Godot plugin (godot-livekit) that ships on Android, which has meant depending on a fork until now. We didn't find an issue, PR or roadmap item about Android, so this PR is partly a question: if Android isn't something you want to take on, feel free to close it.

Changes

  • Rust target: map ANDROID_ABI to the Rust target (arm64-v8a, armeabi-v7a, x86_64). Give cargo, the cc crate and bindgen the NDK's compiler, archiver and sysroot for the build's ABI and API level, as cargo-ndk does.
  • TLS: on Android, build livekit-ffi with rustls-tls-webpki-roots instead of the default native roots, as LiveKit's own Android FFI builds do. rustls-native-certs doesn't find Android's CA certificates.
  • protoc: when cross-compiling, use a host protoc, checked against the vendored Protobuf version. The vendored build can't produce a protoc that runs on the host.
  • UniFFI metadata: build the unstripped metadata library for the target too, so the build doesn't also need a native host toolchain.
  • Skipped on Android: curl and OpenSSL. tokenSourceHttpRequest() returns an error there.
  • C++ runtime warning: configuring with a static C++ runtime warns. With one, apps can't catch the SDK's exceptions: we hit exactly that, an uncaught std::runtime_error aborting the app.
  • Docs: docs/building.md gets a "Cross-compiling for Android" section. It covers prerequisites (NDK r27+, since webrtc-sys doesn't compile with r26) and what apps need: libc++_shared.so, libwebrtc.jar, and loading livekit_ffi with System.loadLibrary.

Non-Android builds are unaffected, except that any cross-compiling build now uses a host protoc.

Testing

  • Built for arm64-v8a, armeabi-v7a and x86_64 with NDK r27d, and natively for Linux x86_64.
  • Ran godot-livekit's test suites on an Android 14 x86_64 emulator, against a local livekit-server --dev. These cover connecting, audio and video, data, RPC, E2EE and disconnecting. All passed, except tests that fail for reasons unrelated to this change (a timing-sensitive warning in the plugin, and screen capture, which the plugin doesn't build on Android).
  • The arm64-v8a build loads and passes the tests that don't need WebRTC under the emulator's ARM translation. The rest need a JavaVM lookup that the translation layer doesn't provide. We haven't tried a physical device yet.

Not included

  • A CI job. We'd be happy to add an Android build to builds.yml if you'd like one.
  • build.sh support. The docs use CMake directly, since build.sh doesn't take a toolchain file.

Questions

  1. Would you take Android support? If so, should it come with a CI job, and should it be listed in the supported platforms?
  2. For HTTP token sources on Android, is an error OK, or would you prefer bundling libcurl (and a TLS library), or something else?

Written with Claude Opus 5.5 (an AI model by Anthropic), working with @mdepinet.

🤖 Generated with Claude Code

Map the Android ABI to its Rust target and give cargo the NDK's
compiler, archiver and sysroot, as cargo-ndk does. When cross-compiling,
use a host protoc, checked against the vendored Protobuf version, and
build the UniFFI metadata library for the target.

On Android, livekit-ffi trusts its bundled webpki roots, as LiveKit's
own Android FFI builds do, since rustls-native-certs doesn't find
Android's CA certificates. There's no system libcurl or OpenSSL, so HTTP
token sources return an error there.

Configuring with a static C++ runtime now warns, since apps then can't
catch the SDK's exceptions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mdepinet
mdepinet requested review from a team and xianshijing-lk as code owners November 15, 2026 02:07
Copilot AI balanced review requested due to automatic review settings November 15, 2026 02:07
devin-ai-integration[bot]

This comment was marked as resolved.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 Changes recommended

Android builds with different API levels or NDKs can overwrite shared Cargo artifacts and package the wrong library, while the protoc lookup can select a target binary that cannot run on the host.

2 open issues
What changed in this PR

Adds Android cross-compilation support to the C++ SDK and its Rust FFI build using the NDK toolchain, with documentation for application integration.

Changes:

  • Configures Android Rust targets, NDK tools, bundled certificate roots, and target-built UniFFI metadata.
  • Uses a version-checked host protoc for cross-compilation and disables curl/OpenSSL dependencies on Android.
  • Documents Android prerequisites, packaging, JNI setup, and the HTTP token-source limitation.
File Description
src/​token_source_http.cpp Returns an explicit unsupported error for Android HTTP token requests.
docs/​building.md Documents Android builds and runtime integration requirements.
CMakeLists.txt Adds Android target, toolchain, TLS, and dependency configuration.
cmake/​uniffi_cpp.cmake Builds UniFFI metadata for the selected target.
cmake/​run_cargo.cmake Passes Android toolchain settings and feature flags to Cargo.
cmake/​protobuf.cmake Selects and version-checks host protoc when cross-compiling.

Review effort: Balanced

Comment thread CMakeLists.txt
Comment on lines +306 to +307
set(LIVEKIT_ANDROID_CC
"${_lk_android_toolchain_bin}/${_lk_android_clang_triple}${_lk_android_api}-clang")

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done in d614163: on Android, the NDK compiler path (which includes the API level) is now part of the hash. Other platforms keep their current paths.

Written with Claude Opus 5.5 (an AI model by Anthropic), working with @mdepinet.

Comment thread cmake/protobuf.cmake Outdated
if(CMAKE_CROSSCOMPILING)
# A protoc built for the target can't run during the build, so use one for the build machine. Its version must
# match the vendored runtime, which only accepts code generated by the same release.
find_program(Protobuf_PROTOC_EXECUTABLE NAMES protoc REQUIRED)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done in d614163: added NO_CMAKE_FIND_ROOT_PATH.

Written with Claude Opus 5.5 (an AI model by Anthropic), working with @mdepinet.

Builds for the same ABI with a different NDK or API level shared a Cargo
directory, so one could package the other's livekit_ffi. Also look up the
host protoc outside the cross-compiling sysroot, and list the host protoc
and the Android exceptions in the Dependencies table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants