# Rust on Android
[](https://github.com/rust-windowing/android-ndk-rs/actions)  
Libraries and tools for Rust programming on Android targets:
[`ndk-sys`](./ndk-sys) | Raw FFI bindings to the NDK | [](https://crates.io/crates/ndk-sys) [](https://docs.rs/ndk-sys)
[`ndk`](./ndk) | Safe abstraction of the bindings | [](https://crates.io/crates/ndk) [](https://docs.rs/ndk)
[`ndk-context`](./ndk-context) | Android handles | [](https://crates.io/crates/ndk-context)
[`ndk-glue`](./ndk-glue) | Startup code | [](https://crates.io/crates/ndk-glue) [](https://docs.rs/ndk-glue)
[`ndk-build`](./ndk-build) | Everything for building apk's | [](https://crates.io/crates/ndk-build) [](https://docs.rs/ndk-build)
[`cargo-apk`](./cargo-apk) | Build tool | [](https://crates.io/crates/cargo-apk) [](https://docs.rs/cargo-apk)
See [`ndk-examples`](./ndk-examples) for examples using the NDK and the README files of the crates for more details.
## Supported NDK versions
`android-ndk-rs` aims to support at least the `LTS` and `Rolling Release` branches of the NDK, as described on [their wiki](https://github.com/android/ndk/wiki#supported-downloads). Additionally the `Beta Release` might be supported to prepare for an upcoming release.
As of writing (2021-07-24) the following NDKs are tested:
r18 | 18.1.5063045 | _Deprecated_ | :x:
r19 | 19.2.5345600 | _Deprecated_ | :heavy_check_mark:
r20 | 20.1.5948944 | _Deprecated_ | :heavy_check_mark:
r21 | 21.4.7075529 | _Deprecated_ | :heavy_check_mark:
r22 | 22.1.7171670 | _Deprecated_ | :heavy_check_mark:
r23 | beta 1/2 | _Deprecated_ | :heavy_check_mark:
r23 | 23.0.7272597-beta3 | _Deprecated_ | :heavy_check_mark: Workaround in [#189](https://github.com/rust-windowing/android-ndk-rs/pull/189)
r23 | 23.1.7779620 | LTS | :heavy_check_mark: Workaround in [#189](https://github.com/rust-windowing/android-ndk-rs/pull/189)
r24 | 24.0.7856742-beta1 | Rolling Release | :heavy_check_mark: Workaround in [#189](https://github.com/rust-windowing/android-ndk-rs/pull/189)
## Quick start: `Hello World` crate on Android
Quick start setting up a new project with support for Android, using the `ndk-glue` layer for communicating with the Android framework through [`NativeActivity`](https://developer.android.com/reference/android/app/NativeActivity) and `cargo-apk` for packaging a crate in an Android `.apk` file.
This short guide can also be used as a reference for converting existing crates to be runnable on Android.
### 1. Install the Android NDK and SDK
Make sure the Android NDK is installed, together with a target platform (`30` by default), `build-tools` and `platform-tools`, using either the [`sdkmanager`](https://developer.android.com/studio/command-line/sdkmanager) or [Android Studio](https://developer.android.com/studio/projects/install-ndk).
### 2. Create a new library crate
```console
$ cargo new hello_world_android --lib
```
Never name your project `android` as this results in a target binary named `libandroid.so` which is also the name of Android's framework library: this will fail to link.
### 3. Configure crate for use on Android
Add the `ndk-glue` dependency to your crate.
`Cargo.toml`
```toml
# This dependency will only be included when targeting Android
[target.'cfg(target_os = "android")'.dependencies]
ndk-glue = "xxx" # Substitute this with the latest ndk-glue version you wish to use
```
Then configure the library target to be compiled to a Rust `lib` (for use in an executable on desktop) and a `cdylib` to create a native binary that can be bundled in the final `.apk` and loaded by Android.
`Cargo.toml`
```toml
[lib]
crate-type = ["lib", "cdylib"]
```
### 4. Wrap entry point with `ndk-glue`
Create a `main` function holding your code in the library portion of the crate, and wrap it in the `ndk_glue::main` attribute macro when targeting Android.
`src/lib.rs`
```rust
#[cfg_attr(target_os = "android", ndk_glue::main(backtrace = "on"))]
pub fn main() {
println!("Hello World");
}
```
See the [`ndk-macro` documentation](./ndk-macro/README.md) for more options.
Additionally, to make this crate runnable outside of Android, create a binary that calls the main function in the library.
`src/main.rs`
```rust
fn main() {
hello_world_android::main()
}
```
As a sanity check, run this binary to make sure everything is set up correctly:
```console
$ cargo run
```
### 5. Run the crate on your Android device
Install `cargo apk` for building, running and debugging your application:
```console
$ cargo install cargo-apk
```
We can now directly execute our `Hello World` application on a real connected device or an emulator:
```console
$ cargo apk run
```
If the crate includes a runnable binary as suggested above, you will likely be greeted by the following error:
```console
$ cargo apk run
error: extra arguments to `rustc` can only be passed to one target, consider filtering
the package by passing, e.g., `--lib` or `--bin NAME` to specify a single target
Error: Command `cargo rustc --target aarch64-linux-android -- -L hello_world_android/target/cargo-apk-temp-extra-link-libraries` had a non-zero exit code.
```
To solve this, add `--lib` to the run invocation, like so:
```console
$ cargo apk run --lib
```
### 6. Inspect the output
`ndk-glue` redirects stdout and stderr to Android `logcat`, including the `println!("Hello World")` by the example above. See [Logging and stdout](##Logging-and-stdout) below how to access it.
## Rendering to the window
Android native apps have no easy access to [Android's User Interface](https://developer.android.com/guide/topics/ui) functionality (bar [JNI](##jni) interop). Applications can instead draw pixels directly to the window using [`ANativeWindow_lock`](https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window_1ga0b0e3b7d442dee83e1a1b42e5b0caee6), or use a graphics API like OpenGL or Vulkan for high performance rendering.
## Logging and stdout
Stdout is redirected to the android log api when using `ndk-glue`. Any logger that logs to
stdout, like `println!`, should therefore work.
To filter on this output in `logcat`:
```console
$ adb logcat RustStdoutStderr:D *:S
```
### Android logger
Enable the `"logger"` feature on the `ndk-glue` macro and configure its log tag and debug level through the attribute macro:
`src/lib.rs`
```rust
#[cfg_attr(target_os = "android", ndk_glue::main(logger(level = "debug", tag = "my-tag")))]
pub fn main() {
log!("hello world");
}
```
## App/APK configuration
Android APKs contain a file called `AndroidManifest.xml`, which has things like permission requests and feature declarations, plus configuration of activities, intents, resource folders and more. This file is autogenerated by `cargo-apk`. To control what goes in it through Cargo.toml, refer to [`cargo-apk`'s README](./cargo-apk/README.md).
## Overriding crate paths
The macro `ndk_glue::main` tries to determine crate names from current _Cargo.toml_.
You can override this names with specific paths like so:
```rust
#[ndk_glue::main(
ndk_glue = "path::to::ndk_glue",
)]
fn main() {}
```
## JNI
Java Native Interface (JNI) allows executing Java code in a VM from native applications. To access
the JNI use the `AndroidContext` from the `ndk-context` crate. `ndk-examples` contains a `jni_audio`
example which will print out all output audio devices in the log.
- [`jni`](https://crates.io/crates/jni), JNI bindings for Rust