Support 16 KB page sizes on Android

[marcprux]

Android 15+ requires that native libraries be compiled with a linker flag to support 16 KB page sizes. See: https://developer.android.com/guide/practices/page-sizes#compile-r26-lower

[compnerd]

This is also incompatible with 4K pages, which is still supported I believe. Unless Google has stated that they are going to prevent 4K pages on ARM64, we should have two separate runtimes.

[finagolfin]

Android 15+ requires that native libraries be compiled with a linker flag to support 16 KB page sizes.

I don't think the OS will require this, only the Play store.

I see conflicting reports on whether such 16 KB-aligned shared libraries will continue working with older 4 KB devices: have you built and tested Swift packages using this flag in 16 KB and 4 KB emulators? Until we've done so, no point in applying this flag.

[andriydruk]

This is also incompatible with 4K pages

It’s fully compatible with devices that use 4K pages. In fact, starting from Android NDK 28, this linker flag is enabled by default and cannot be disabled. We only need to set this flag manually because we are using NDK 27.

I don't think the OS will require this, only the Play Store.

No, the binary will crash on startup if it is not properly aligned when running on a device with 16 KB pages. Google provides an emulator image for 16 KB page size devices, so this can be tested even without real hardware.

Mark pushed it a little bit early. We are still in the process of testing our toolchain on both 4 KB and 16 KB devices, but so far, no issues have been detected - it runs smoothly on both.

[finagolfin]

No, the binary will crash on startup if it is not properly aligned when running on a device with 16 KB pages.

Right, but he said "Android 15+ requires," not just devices with 16 KB pages. I think they will continue supporting the 4 KB kernel and old 4 KB-aligned apps on the majority of Android 15+ devices, hence it is not a requirement of the Android 15+ OS yet.

[marcprux]

Right, but he said "Android 15+ requires," not just devices with 16 KB pages.

I should have clarified that there are two separate requirements:

1. Apps using native libraries compiled without the "max-page-size=16384" flag will crash when run on devices that use 16KB page sizes as supported in Android 15+.
2. Starting November 1st, 2025, all new apps and updates to existing apps submitted to Google Play and targeting Android 15+ devices must support 16 KB page sizes.¹

Footnotes

1. https://android-developers.googleblog.com/2025/05/prepare-play-apps-for-devices-with-16kb-page-size.html ↩

[marcprux]

Given that the only objection was based on an incorrect assumption, what is blocking this? If we don't get 16KB support for the Android SDK, the Play Store is going to block any app submissions that use Swift in a few months.

[finagolfin]

Should be fine, but we should apply it to the corelibs also here, -Xclang-linker -Wl,-z,max-page-size=16384. See if that produces a bundle in your local builds with all 16K-aligned libraries: report back what else is only 4K-aligned after that and we can see where to pass in this flag for them.

[marcprux]

See if that produces a bundle in your local builds with all 16K-aligned libraries: report back what else is only 4K-aligned after that and we can see where to pass in this flag for them.

That got us a lot closer. Running the handy check_elf_alignment.sh script on the output of the build yields:

% ~/Downloads/check_elf_alignment.sh ~/Downloads/swift-DEVELOPMENT-SNAPSHOT-2025-07-18-a-android-0.1.artifactbundle/swift-android/swift-resources/usr/lib/swift-aarch64/android/

=== ELF alignment ===
./libswiftAndroid.so: ALIGNED (2**14)
./libFoundation.so: ALIGNED (2**14)
./lib_Testing_Foundation.so: UNALIGNED (2**12)
./libdispatch.so: UNALIGNED (2**12)
./libswiftRegexBuilder.so: ALIGNED (2**14)
./libswift_Concurrency.so: ALIGNED (2**14)
./libBlocksRuntime.so: UNALIGNED (2**12)
./libXCTest.so: ALIGNED (2**14)
./libswiftCore.so: ALIGNED (2**14)
./libswiftDistributed.so: ALIGNED (2**14)
./libswift_Differentiation.so: ALIGNED (2**14)
./libFoundationNetworking.so: ALIGNED (2**14)
./libswiftSynchronization.so: ALIGNED (2**14)
./libswiftSwiftOnoneSupport.so: ALIGNED (2**14)
./libswift_Volatile.so: ALIGNED (2**14)
./libswift_StringProcessing.so: ALIGNED (2**14)
./lib_FoundationICU.so: UNALIGNED (2**12)
./libswiftDispatch.so: ALIGNED (2**14)
./libswift_Builtin_float.so: ALIGNED (2**14)
./libFoundationEssentials.so: ALIGNED (2**14)
./libswift_RegexParser.so: ALIGNED (2**14)
./libswift_math.so: ALIGNED (2**14)
./aarch64/swiftrt.o: UNALIGNED ()
./libFoundationXML.so: ALIGNED (2**14)
./libTesting.so: UNALIGNED (2**12)
./libswiftObservation.so: ALIGNED (2**14)
./libFoundationInternationalization.so: ALIGNED (2**14)
Found 6 unaligned libs (only arm64-v8a/x86_64 libs need to be aligned).
=====================

I don't think we need to worry about swiftrt.o, so we are left with lib_Testing_Foundation.so, libdispatch.so, libBlocksRuntime.so, lib_FoundationICU.so, and libTesting.so.

Any suggestions on where to add the flag for those?

[finagolfin]

Those are the remaining C/C++ libraries, plus Testing, that we distribute. Testing is currently not supported officially for Android, which is why I still patch it in for our SDK bundles. I'm looking at properly adding build config for that in this repo, so I will add this linker flag separately for it then.

As for C/C++ libraries, I believe the right way to pass that in was long with the CMAKE_SHARED_LINKER_FLAGS variable, but ever since CMake 3.30, it is now wrongly passing those linker flags to the Swift compiler also, breaking Swift builds. Strangely, it only breaks trunk libdispatch, so there is probably some other config that also makes it break in this way.

I suggest we get this in and punt those last few libraries for whenever we get those CMake issues figured out.

[finagolfin]

@swift-ci smoke test

[marcprux]

I suggest we get this in and punt those last few libraries for whenever we get those CMake issues figured out.

An alternative way to activate the 16KB page support is to specify -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON (see https://github.com/android/ndk/wiki/Changelog-r27). I'll add this to the docker pull build script and see what happens…

[finagolfin]

That's if using the NDK's CMake config, which we don't use.

[finagolfin]

Works fine on my Android CI in testing on an Android x86_64 emulator with the old 4K pages.

[finagolfin]

Gave others time to review, passed CI and only affects Android, so merging.