Skip to content
/ ondk Public

Oxidized NDK - NDK repackaged with Rust toolchain

License

Notifications You must be signed in to change notification settings

topjohnwu/ondk

Repository files navigation

Oxidized NDK

This is not an officially supported Google product.

Oxidized NDK (ONDK) is an unofficial repackaged Android NDK that includes a Rust toolchain. This repository hosts build scripts to build and package ONDK using GitHub Actions. Every file included in the final package either originates from the official NDK zip or is built in GitHub Actions.

This project does not include or attempt to do any modifications to Rust and LLVM.
This project is for experimental purposes, and does not guarantee any Android NDK or Rust functionality.
Use at your own risk.

Download the latest ONDK in releases.

Supports all NDK host platforms:
Linux (x64), Windows (x64), and macOS (x64 + arm64, universal binaries).

How to Use

For building C/C++ code, ONDK is just like any ordinary Android NDK, no special configurations are needed.

For building Rust code, link ONDK's Rust toolchain with rustup:

rustup toolchain link <name> <ondk>/toolchains/rust

The std crate is intentionally not prebuilt and included in ONDK, so building requires a little bit of setup.
Here is an example for building a project targeting API 21 for ARM64:

LLVM_BIN="<ondk>/toolchains/llvm/prebuilt/<os>-x86_64/bin"

# We need to tell cargo where to find the NDK linker for Android.
# You can also set this in config.toml, check the official documentation.
export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER="$LLVM_BIN/aarch64-linux-android21-clang"

# Finally, build our project with -Z build-std
cargo <+name> build -Z build-std --target aarch64-linux-android

P.S. I strongly recommend checking out min-sized-rust to minimize Rust binaries.

How ONDK is Built

  • Download the latest Rust source code
  • Apply some patches to its build system (no patches to any code that is part of the final product)
  • Build a Rust sysroot with rustc + cargo + std source code + clang
  • Download the latest stable NDK zip
  • Replace only the LLVM/Clang executables of NDK, and copy the Rust sysroot into the package

FAQ

  • Q: Why do we need this? Doesn't the official Rust toolchains already work for Android?
    A: I started this project because I wanted to enable Cross-Language LTO. This allows C/C++ and Rust code to be optimized together during link time, extremely useful for mixed language projects. However, because NDK's Clang and official Rust toolchains are not built with the same LLVM, their LTO output format is very likely to be incompatible with each other. ONDK builds rustc and clang from scratch with the same LLVM source code to ensure cross-language LTO compatibility.

  • Q: Why is std not prebuilt for Android targets?
    A: I personally strongly dislike the idea of prebuilding any dependency that will be included in the final product of a project. Building std along with the project's compilation pipeline makes it easy to disable features, such as removing unwind for panic, and allow std to be LTO-ed with your project. The toolchain should not forcefully include and link code that is unnecessary for your project!

License

Copyright 2022-2024 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.