Rust Android Build

As of 2026-09, the current NDK LTS is r30 (30.0.16248370, NDK downloads). Rust supports the most recent NDK LTS (rustc Android platform page), and that page names no NDK version. Check both pages again after an NDK or Rust toolchain bump.

Release gates

Each claim has one check. A green check proves its own row only.

Run the ELF, export, and size gates in one repository script against the merged native-library tree. Run the package and device checks against the final artifact. A check of the merged jniLibs tree proves nothing about the archive that ships, and a successful assemble task is not runtime proof. Build the package and its native symbols in one release invocation; file names and archive presence do not prove that symbols match the shipped code. When no 16 KB emulator image or device is available, report the device rows as not run; do not report the release gate as passed.

The size gate compares each build against a checked-in per-ABI baseline of byte counts. The default thresholds are at most 128 KiB growth for one tracked library, and total growth across all tracked libraries of at most the tighter of 2% or 256 KiB; tune them per product. Keep byte counts in the baseline file, not in prose, and update the baseline in a separate commit that states the reason.

Read references/elf-verification.md when you write or change the gate script, or when the size gate fails: it has the audit commands and the linker size flags. Read references/release-packaging.md when you configure native debug symbols, prove a release closure, run the installed smoke, or publish an AAR or Prefab package.

Get separate explicit authorization before a Play Console upload, a symbol upload, or a repository publish. Local builds, signing for a local smoke, and inspection need none.

Failure triage

Link flags in .cargo/config.toml

Put the Android link flags in .cargo/config.toml at the workspace root. Cargo reads config files from the current directory upward, not from the --manifest-path directory. Run every Android cargo invocation from the workspace root or below it, or cargo drops these flags without a message. Two cfg tables cover every Android target:

[target.'cfg(target_os = "android")']
rustflags = ["-C", "link-arg=-Wl,--build-id=sha1"]

[target.'cfg(all(target_os = "android", any(target_arch = "aarch64", target_arch = "x86_64")))']
rustflags = ["-C", "link-arg=-Wl,-z,max-page-size=16384"]

Cargo joins the rustflags of every matching [target.<triple>] and [target.<cfg>] table. A profiling addition in a triple table therefore adds to these flags; the rust-performance skill owns force-frame-pointers. A matching target table also makes Cargo ignore build.rustflags. Copy any build.rustflags entry that Android builds need into the cfg table.

The NDK driver links armeabi-v7a and x86 at 4 KiB (0x1000), and the NDK plans no 16 KiB page size for 32-bit ABIs. Apply the 16 KiB flag there only as a stated project policy, and then gate on it.

A RUSTFLAGS or CARGO_ENCODED_RUSTFLAGS environment variable replaces every config rustflags entry. It does not add to them. Even RUSTFLAGS="" removes both flags. The build ID then disappears without a message, and so does the alignment flag on NDK r27 or older and on 32-bit ABIs under a 16 KiB policy. Never set or inherit either variable in the Gradle task or CI job that builds the shipped library. To deny warnings, use CARGO_BUILD_WARNINGS=deny (Cargo 1.97+) instead of RUSTFLAGS=-Dwarnings.

16 KiB page size

Policy as of 2026-09

The page-size guide (updated 2026-09-16) requires apps that target API 35 or higher to support 16 KB pages on 64-bit devices. From 2027-02-01, Play blocks an app update that does not. New phone apps and updates must target API 36 since 2026-08-31 (target API rules), so every phone release is in scope. Read both pages again before a release decision.

A device with a 16 KB kernel can run a non-compliant app in 16 KB backcompat mode and warn the user. A misaligned library therefore does not always fail to load, and a smoke test on that device can pass. The android:pageSizeCompat manifest attribute turns backcompat mode on or off for one app and suppresses the warning. Fail the release gate when the merged release manifest sets android:pageSizeCompat="enabled", because a library manifest can add it.

ELF check

Set NDK_BIN once for every NDK tool command in this skill. The macOS NDK uses darwin-x86_64 on Apple silicon too.

NDK_BIN="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/$(uname | tr '[:upper:]' '[:lower:]')-x86_64/bin"
"$NDK_BIN/llvm-readelf" -lW <lib-dir>/arm64-v8a/libnative.so \
  | awk '/LOAD/ {print $NF}' \
  | sort -u
# Expected on arm64-v8a and x86_64: one line, 0x4000.
# A larger power of two, such as 0x10000, also passes.

Run it on every shipped .so in the merged native-library tree. On a 32-bit ABI, expect 0x1000 unless the project policy requires 0x4000.

Package check

A correctly linked .so can still sit at a 4 KiB ZIP offset. Use zipalign from build-tools 35.0.0 or later; older versions do not have -P 16.

ZIPALIGN="$ANDROID_HOME/build-tools/<35.0.0-or-later>/zipalign"
"$ZIPALIGN" -c -P 16 -v 4 app-release.apk            # a final APK

# An AAB: prove the requested alignment, then check every APK in the DEFAULT set.
# Do not pass --mode=universal here.
bundletool dump config --bundle=app-release.aab | grep PAGE_ALIGNMENT_16K
bundletool build-apks --bundle=app-release.aab \
  --output=app-release-default.apks --overwrite
unzip -q app-release-default.apks -d <default-apks-dir>
find <default-apks-dir> -name '*.apk' -print0 \
  | xargs -0 -n1 "$ZIPALIGN" -c -P 16 -v 4

A universal APK is a local smoke artifact only. It does not cover the split and standalone APKs that Play can serve. Fail the gate when an AAB with uncompressed native libraries does not declare PAGE_ALIGNMENT_16K. AGP 8.5.1 and later align uncompressed native libraries at 16 KiB. On an older AGP, upgrade, or set packaging.jniLibs.useLegacyPackaging = true so that the libraries ship compressed and the device extracts them at install.

Device check

The static checks do not prove the runtime path. When no 16 KB emulator image or device is available, report the device rows as not run; do not report the release gate as passed. On a 16 KB emulator image or device, run these commands before you install the app:

adb shell getconf PAGE_SIZE     # must print 16384
adb shell setprop bionic.linker.16kb.app_compat.enabled false
adb shell setprop pm.16kb.app_compat.disabled true
test "$(adb shell getprop bionic.linker.16kb.app_compat.enabled)" = false
test "$(adb shell getprop pm.16kb.app_compat.disabled)" = true

Fail when a read-back differs: setprop can fail on a user build without root. On Android 17 or later, set fatal instead of false so that a misaligned library aborts at load, and expect fatal. Then run the installed release smoke from references/release-packaging.md.

Common traps

Read references/elf-verification.md when a prebuilt .so, a static C archive, an mmap or mprotect size, or a C PAGE_SIZE macro breaks 16 KiB alignment.

Release profile

Declare the profiles in the workspace Cargo.toml:

[profile.android-jni]
inherits = "release"
opt-level = "z"             # measure against "s" and 3
lto = "fat"
codegen-units = 1
panic = "unwind"            # catch_unwind at the JNI boundary needs unwind
strip = "none"              # packaging strips the shipped copy
debug = "line-tables-only"

[profile.android-jni-dev]
inherits = "dev"
opt-level = 1               # faster local iteration
panic = "unwind"
debug = "line-tables-only"  # no debugger variables; use true for an LLDB session

• With panic = "abort" or the nightly panic = "immediate-abort", a panic kills the app process instead of raising a Java exception. The rust-panic-safety skill, when it is installed, owns the choice between unwind and abort and the boundary policy.
• Keep strip = "none". The packaging step strips the shipped copy and extracts symbols from the unstripped input. A Cargo-stripped input destroys the symbol file.
• Measure opt-level ("z", "s", 3), lto, and codegen-units changes on the real .so with the size gate. "z" is not always the smallest. "s" and "z" both disable loop vectorization, so a compute-bound JNI path can need 3. The rust-performance skill has the measurement workflow.
• Do not add -Wl,--gc-sections: rustc already passes it for a cdylib. Use -Wl,--icf=all only after a size measurement, and only when no linked C or C++ code compares function addresses.

Exported symbols

Read references/elf-verification.md when you derive expected-exports.txt, run the dynamic-symbol allowlist diff, consider a --version-script, or remove an unexpected export.

Gradle and jniLibs integration

Build the shipped library through one Gradle task per ABI that writes <generated-dir>/jniLibs/<abi>/libnative.so, not through a hand-written cargo command. Give each ABI its own CARGO_TARGET_DIR, and pass --locked on every cargo call. Remove both rustflags variables from the task environment, because the Gradle daemon inherits them from its shell, and set the Exec task workingDir to the workspace root. Read references/ndk-and-gradle.md when you write or change the task.

Targets and linker

Read references/ndk-and-gradle.md when you map an Android ABI to its Rust target and NDK driver, add a rustup target, set a CARGO_TARGET_<TRIPLE>_LINKER variable, run the manual cargo rustc --crate-type cdylib build, or compute <api>.

Related skills

Use these skills when they are installed:

• cargo-workflows: Cargo.lock policy, profiles, and the full cross-compilation variable set.
• rust-jni: JNI export naming, JNIEnv handling, and JNI_OnLoad.
• rust-panic-safety: the panic policy at the JNI boundary.
• uniffi-packaging-versioning: packaging a generated UniFFI layer.
• rust-performance: profiling additions such as frame pointers, simpleperf, and size audits.
• rust-debugging: tombstones and symbolication of a native crash.