Android 15 16KB Native Page Size ELF Memory Alignment Guardrail

Android 15 introduces support for devices configured with 16KB memory page sizes, departing from the legacy 4KB standard. Native C/C++ and Rust shared libraries (.so) packaged in APKs or AABs must align their ELF PT_LOAD segments to 16KB (0x4000) boundaries, and zip archives must store uncompressed native libraries aligned to 16KB boundaries. Failure to enforce these constraints results in immediate kernel memory mapping failure and linker crash (SIGSEGV or dlopen abort) during process initialization on 16KB-configured devices.

--- description: Android 15 16KB Native Page Size ELF Memory Alignment Guardrail - Android 15 introduces support for devices configured with 16KB memory page sizes, departing from the legacy 4KB standard. Native C/C++ and Rust shared libraries (.so) packaged in APKs or AABs must align their ELF PT_LOAD segments to 16KB (0x4000) boundaries, and zip archives must store uncompressed native libraries aligned to 16KB boundaries. Failure to enforce these constraints results in immediate kernel memory mapping failure and linker crash (SIGSEGV or dlopen abort) during process initialization on 16KB-configured devices. globs: **/CMakeLists.txt, **/Android.mk, **/build.gradle, **/build.gradle.kts, **/.cargo/config.toml, **/Cargo.toml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-16kb-page-size-elf-alignment-guardrail" --- # Android 15 16KB Native Page Size ELF Memory Alignment Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Compiling Native JNI Libraries with Default 4KB ELF Segment Alignment or Packaging Unaligned .so Files in APKs ## System Constraints You are a Principal Mobile Systems Architect and Compiler Engineer enforcing strict compliance with Android 15 16KB memory page size requirements across all native codebases (C++, C, Rust) and Android Gradle configurations. Native ELF binaries not aligned to 16KB boundaries crash during dlopen() on 16KB devices. You must mandate 16KB segment alignment linker flags, ensure NDK r27+ or explicit linker arguments (-Wl,-z,max-page-size=16384), enforce correct APK 16KB zip alignment, and prohibit deprecated legacy packaging options that unpack misaligned libraries. ## Strict Guidelines - Engineers MUST ALWAYS pass '-Wl,-z,max-page-size=16384' to native linkers in CMake, ndk-build, or custom toolchains if targeting NDK version r26 or lower. - Engineers SHOULD upgrade to Android NDK r27 or higher, which enables 16KB ELF alignment by default for all 64-bit architectures (arm64-v8a, x86_64). - Engineers MUST configure Cargo rustflags with '-C link-arg=-Wl,-z,max-page-size=16384' in .cargo/config.toml for all 64-bit Android targets ('aarch64-linux-android' and 'x86_64-linux-android'). - Engineers MUST NOT disable uncompressed native library alignment by setting 'android.bundle.enableUncompressedNativeLibs=false' or 'useLegacyPackaging = true' without explicit 16KB zipalign verification. - Engineers MUST verify every compiled .so file using 'llvm-readelf -l <lib.so>' or the Android alignment verification script to ensure the 'Align' column for all PT_LOAD segments equals '0x4000' (16384) or greater. - Third-party prebuilt .so binaries MUST NOT be embedded directly without inspecting their ELF PT_LOAD alignment; misaligned prebuilts MUST be recompiled from source or updated by upstream vendors. - Build scripts MUST configure Android Gradle Plugin (AGP) 8.5.1+ or 8.3.0+ with proper packaging blocks to ensure uncompressed libraries are 16KB page-aligned inside APK zip containers. ## Bad vs Good Implementations ### CMake Native Linker Configuration for 16KB Page Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting explicit max-page-size linker flags when building with NDK versions prior to r27 causes lld to default to 4096-byte alignment. On a 16KB-paged kernel, the Android dynamic linker fails to map the ELF segments into memory, aborting process launch. ```cmake # CMakeLists.txt without explicit 16KB alignment cmake_minimum_required(VERSION 3.22.1) project("native-engine") add_library(native-engine SHARED src/engine.cpp src/jni_bridge.cpp ) # Anti-pattern: Default linker options on NDK <= r26 emit 4KB (0x1000) PT_LOAD alignment, # causing immediate SIGSEGV on Android 15 devices with 16KB page kernels. target_link_libraries(native-engine log) ``` #### Production Standard (Correct) > **Standard**: Explicitly passing '-Wl,-z,max-page-size=16384' instructs the linker to align all PT_LOAD segments to 16384-byte boundaries, ensuring seamless execution on both 4KB and 16KB page size devices. ```cmake # CMakeLists.txt enforcing 16KB page alignment cmake_minimum_required(VERSION 3.22.1) project("native-engine") add_library(native-engine SHARED src/engine.cpp src/jni_bridge.cpp ) # Enforce 16KB ELF segment alignment across all 64-bit architectures if(ANDROID_ABI STREQUAL "arm64-v8a" OR ANDROID_ABI STREQUAL "x86_64") target_link_options(native-engine PRIVATE "-Wl,-z,max-page-size=16384") endif() target_link_libraries(native-engine log) ``` ### Rust Cargo Configuration for Android JNI Libraries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default Rust compilation for Android targets does not set max-page-size. Rust shared libraries (.so) produced with default settings contain 4KB PT_LOAD alignment and fail loading via System.loadLibrary on Android 15 16KB kernels. ```toml # .cargo/config.toml [target.aarch64-linux-android] # Anti-pattern: Default linker behavior defaults to 4KB alignment on Android ar = "llvm-ar" linker = "aarch64-linux-android24-clang" ``` #### Production Standard (Correct) > **Standard**: Passing '-C link-arg=-Wl,-z,max-page-size=16384' via target-specific rustflags forces rustc/lld to produce 16KB-aligned ELF segments for both ARM64 and x86_64 Android targets. ```toml # .cargo/config.toml [target.aarch64-linux-android] ar = "llvm-ar" linker = "aarch64-linux-android24-clang" rustflags = ["-C", "link-arg=-Wl,-z,max-page-size=16384"] [target.x86_64-linux-android] ar = "llvm-ar" linker = "x86_64-linux-android24-clang" rustflags = ["-C", "link-arg=-Wl,-z,max-page-size=16384"] ``` ### Android Gradle Plugin Packaging Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Enabling useLegacyPackaging forces native libraries to be extracted at install time or stored without 16KB page boundary alignment, resulting in zip alignment failures on 16KB page devices. ```kotlin // build.gradle.kts (App Module) android { // Anti-pattern: Legacy packaging compresses .so files or fails to 16KB align them packaging { jniLibs { useLegacyPackaging = true } } } ``` #### Production Standard (Correct) > **Standard**: Using modern packaging (useLegacyPackaging = false) combined with NDK r27+ ensures the APK zipalign tool aligns uncompressed .so files on 16KB boundaries directly within the zip archive, allowing direct mmap by the kernel. ```kotlin // build.gradle.kts (App Module) android { ndkVersion = "27.1.12297006" // NDK r27+ aligns to 16KB by default packaging { jniLibs { // Keep libraries uncompressed and aligned directly in the APK useLegacyPackaging = false } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Native Page Size ELF Memory Alignment Guardrail

Android 15 16KB Native Page Size ELF Memory Alignment Guardrail defines an industrial-grade behavioral standard for mobile engineering. Android 15 introduces support for devices configured with 16KB memory page sizes, departing from the legacy 4KB standard. Native C/C++ and Rust shared libraries (.so) packaged in APKs or AABs must align their ELF PT_LOAD segments to 16KB (0x4000) boundaries, and zip archives must store uncompressed native libraries aligned to 16KB boundaries. Failure to enforce these constraints results in immediate kernel memory mapping failure and linker crash (SIGSEGV or dlopen abort) during process initialization on 16KB-configured devices. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Compiling Native JNI Libraries with Default 4KB ELF Segment Alignment or Packaging Unaligned .so Files in APKs Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Compiling Native JNI Libraries with Default 4KB ELF Segment Alignment or Packaging Unaligned .so Files in APKs	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS pass '-Wl,-z,max-page-size=16384' to native linkers in CMake, ndk-build, or custom toolchains if targeting NDK version r26 or lower.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.