Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(android): make the availability guards mean something below the floor

esengine1a90c22d4ec8
diff --git a/build-tools/cli.js b/build-tools/cli.js
index f396bb37f..1528d5638 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -167,7 +167,9 @@ program
.option('--dawn-build <dir>', 'Dawn build dir for this target (default: <dawn>/out-<target>, built if absent)')
.option('--quickjs <dir>', 'QuickJS-ng source dir (default: the pinned checkout; or ESTELLA_QUICKJS_DIR)')
.option('--abi <abi>', 'Android ABI', 'arm64-v8a')
- .option('--platform <platform>', 'Android platform', 'android-24')
+ // No default: the floor is the manifest's, and repeating it here is how the
+ // two drift. An unset value reaches androidMinPlatform() in the task.
+ .option('--platform <platform>', 'Android platform (default: the manifest\'s minSdkVersion)')
.option('--ios-min <version>', 'iOS deployment target', '17.0')
.option('--simulator', 'iOS: build the simulator slice (needs a simulator Dawn)', false)
.option('--package', 'Assemble the app around --content from the installed runtime template: Android a signed APK, iOS an Xcode project', false)
diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.js
index 0b3c93154..e00581edd 100644
--- a/build-tools/tasks/native.js
+++ b/build-tools/tasks/native.js
@@ -17,6 +17,7 @@ import { runCommand, getCpuCount, resolvePython } from '../utils/emscripten.js';
import { requireSdk, requireNdk, sdkCmake } from '../utils/android.js';
import { emitNativeTemplate, writeTemplateIndex, readEngineVersion } from './nativeTemplateEmit.js';
import { fetchNativeDeps, pinnedDep, ensureDawnBuild, dawnLibrary, DAWN_TARGETS } from './nativeDeps.js';
+import { androidMinPlatform } from '../utils/androidFloor.js';
import {
ANDROID_ABIS, BYTECODE_FILE, findTemplate, iosTemplateSources, templateStoreDir,
} from '../utils/nativeTemplate.js';
@@ -319,7 +320,7 @@ async function buildAndroidHost(options) {
// into a load-time requirement. At android-33 that shipped a host which could
// not dlopen below API 31: `cannot locate symbol APerformanceHint_getManager`,
// on Android 10 and 11, before a line of our code ran.
- const { abi = 'arm64-v8a', platform = 'android-24' } = options;
+ const { abi = 'arm64-v8a', platform = androidMinPlatform() } = options;
const rootDir = config.paths.root;
const sdk = requireSdk();
@@ -327,7 +328,7 @@ async function buildAndroidHost(options) {
const toolchain = path.join(ndk, 'build', 'cmake', 'android.toolchain.cmake');
const { cmake, ninja } = sdkCmake(sdk);
- const { dawnDir, dawnBuild } = await dawnPaths(options, 'android', { ndk, cmake, ninja });
+ const { dawnDir, dawnBuild } = await dawnPaths({ ...options, platform }, 'android', { ndk, cmake, ninja });
// One build tree per ABI, beside the generated sources they share — a second
// architecture must not overwrite the first one's objects.
const buildDir = path.join(rootDir, 'build/cmake/native', abi);
@@ -349,6 +350,17 @@ async function buildAndroidHost(options) {
`-DCMAKE_TOOLCHAIN_FILE=${toolchain}`,
`-DANDROID_ABI=${abi}`,
`-DANDROID_PLATFORM=${platform}`,
+ // Without this the NDK marks every symbol newer than the platform
+ // `unavailable` outright — a hard compile error that no availability
+ // guard can satisfy, because the annotation means "this build cannot see
+ // it" rather than "call me under a check". ON makes those references
+ // weak, which is what gives `__builtin_available` something to test.
+ //
+ // Turning it on used to be the riskier choice: while the floor equalled
+ // the newest API the host called, dropping the flag changed nothing and
+ // would have gone unnoticed. Below that floor it cannot — the build stops
+ // and names the symbol, which is how this line came to be here.
+ '-DANDROID_WEAK_API_DEFS=ON',
'-DANDROID_STL=c++_shared',
'-DCMAKE_BUILD_TYPE=Release',
// Emit build/cmake/native/compile_commands.json so editor IntelliSense (the
diff --git a/build-tools/tasks/nativeDeps.js b/build-tools/tasks/nativeDeps.js
index f681d7631..b285437a9 100644
--- a/build-tools/tasks/nativeDeps.js
+++ b/build-tools/tasks/nativeDeps.js
@@ -10,6 +10,7 @@
// without a flag.
import path from 'path';
+import { androidMinPlatform } from '../utils/androidFloor.js';
import { existsSync, readFileSync } from 'fs';
import { mkdir } from 'fs/promises';
import config from '../build.config.js';
@@ -109,10 +110,18 @@ export function dawnLibrary(dawnBuild, target) {
/** Dawn's build directory for a target. Android's is per-ABI — an emulator build
* and a device build are different binaries — with the default ABI keeping the
- * plain name a checkout may already have. */
-export function dawnBuildDir(dawn, target, abi) {
- const suffix = target === 'android' && abi && abi !== 'arm64-v8a' ? `-${abi}` : '';
- return path.join(dawn, DAWN_TARGETS[target].out + suffix);
+ * plain name a checkout may already have.
+ *
+ * The API level is part of it for the same reason the ABI is: a Dawn compiled
+ * against a newer platform links symbols the host's own floor promised not to
+ * need, and the result installs and then fails to load on the versions the floor
+ * exists to cover. Sharing one directory across levels made lowering the floor a
+ * no-op on whichever machine already had a build. */
+export function dawnBuildDir(dawn, target, abi, androidPlatform) {
+ if (target !== 'android') return path.join(dawn, DAWN_TARGETS[target].out);
+ const abiSuffix = abi && abi !== 'arm64-v8a' ? `-${abi}` : '';
+ const apiSuffix = androidPlatform ? `-${String(androidPlatform).replace(/^android-/, 'api')}` : '';
+ return path.join(dawn, DAWN_TARGETS[target].out + abiSuffix + apiSuffix);
}
/**
@@ -124,7 +133,8 @@ export function dawnBuildDir(dawn, target, abi) {
export async function ensureDawnBuild(options) {
const target = DAWN_TARGETS[options.target];
if (!target) throw new Error(`Unknown Dawn target ${options.target}.`);
- const buildDir = options.buildDir || dawnBuildDir(options.dawn, options.target, options.abi);
+ const buildDir = options.buildDir
+ || dawnBuildDir(options.dawn, options.target, options.abi, options.androidPlatform);
if (existsSync(dawnLibrary(buildDir, options.target))) return buildDir;
const cmake = options.cmake || 'cmake';
@@ -145,7 +155,7 @@ export async function ensureDawnBuild(options) {
? [
`-DCMAKE_TOOLCHAIN_FILE=${path.join(options.ndk, 'build', 'cmake', 'android.toolchain.cmake')}`,
`-DANDROID_ABI=${options.abi || 'arm64-v8a'}`,
- `-DANDROID_PLATFORM=${options.androidPlatform || 'android-24'}`,
+ `-DANDROID_PLATFORM=${options.androidPlatform || androidMinPlatform()}`,
'-DANDROID_STL=c++_shared',
'-DDAWN_ENABLE_VULKAN=ON', '-DDAWN_ENABLE_METAL=OFF',
// Shared on Android (the APK ships the .so); static on iOS (an app
diff --git a/build-tools/tasks/nativeTemplateEmit.js b/build-tools/tasks/nativeTemplateEmit.js
index 0918b0038..76b045bdd 100644
--- a/build-tools/tasks/nativeTemplateEmit.js
+++ b/build-tools/tasks/nativeTemplateEmit.js
@@ -10,6 +10,7 @@
// to put a game on a phone.
import path from 'path';
+import { androidMinPlatform } from '../utils/androidFloor.js';
import { existsSync, readFileSync, writeFileSync } from 'fs';
import { createHash } from 'crypto';
import { mkdir, rm, cp, readdir } from 'fs/promises';
@@ -200,7 +201,7 @@ export async function emitNativeTemplate(options) {
spineVersion: options.spineVersion || '4.2',
...(platform === 'ios' ? { deploymentTarget: options.deploymentTarget || '17.0' } : {}),
...(platform === 'android'
- ? { androidPlatform: options.androidPlatform || 'android-24', abis: templateAbis(dir) }
+ ? { androidPlatform: options.androidPlatform || androidMinPlatform(), abis: templateAbis(dir) }
: {}),
});
diff --git a/build-tools/utils/androidFloor.js b/build-tools/utils/androidFloor.js
new file mode 100644
index 000000000..41bbfd64b
--- /dev/null
+++ b/build-tools/utils/androidFloor.js
@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The Android API floor, read from the one place that declares it.
+ *
+ * The NDK must build against exactly the manifest's minSdkVersion. Above it,
+ * every `__builtin_available` guard compiles out and its symbol becomes a
+ * load-time requirement, so the app installs on an older device and then fails
+ * before a line of our code runs — which is how a build targeted at android-33
+ * shipped a host that could not dlopen below API 31.
+ *
+ * That coupling used to be a rule someone had to remember while editing four
+ * defaults in four files. Reading the number instead means the manifest is the
+ * only place it is written, and the two cannot disagree.
+ */
+import { readFileSync } from 'fs';
+import path from 'path';
+
+import config from '../build.config.js';
+
+/** The template every packaged game's manifest is filled from. */
+export function manifestTemplatePath() {
+ return path.join(config.paths.root, 'native', 'android', 'host', 'AndroidManifest.xml.in');
+}
+
+let cached = null;
+
+/** `minSdkVersion` as declared, e.g. 24. */
+export function androidMinSdk() {
+ if (cached !== null) return cached;
+ const template = manifestTemplatePath();
+ const found = /android:minSdkVersion="(\d+)"/.exec(readFileSync(template, 'utf8'));
+ if (!found) {
+ throw new Error(`No android:minSdkVersion in ${template} — it is the single source for `
+ + 'the API level the NDK builds against, so a build cannot proceed without it.');
+ }
+ cached = Number(found[1]);
+ return cached;
+}
+
+/** The same number as the NDK spells it, e.g. `android-24`. */
+export function androidMinPlatform() {
+ return `android-${androidMinSdk()}`;
+}
diff --git a/native/host/platform/android.cpp b/native/host/platform/android.cpp
index e214fe345..d481edc18 100644
--- a/native/host/platform/android.cpp
+++ b/native/host/platform/android.cpp
@@ -518,19 +518,17 @@ void onAppCmd(android_app* app, int32_t cmd) {
//
// Resolved by hand, through dlsym, rather than called directly.
//
-// ADPF is API 33 and this host builds against the manifest's floor, so the NDK
-// marks those four symbols `unavailable`: a hard compile error, and no
-// `__builtin_available` guard changes that — the annotation is not "call me
-// under a check", it is "this build cannot see me". Raising the build target is
-// what makes them callable, and that is precisely the mistake being fixed here:
-// at android-33 every availability guard in this file became dead code and every
-// guarded symbol became a load-time requirement, so the released host could not
-// dlopen on Android 10 or 11 at all.
+// This predates the build turning on ANDROID_WEAK_API_DEFS, which is what makes
+// `__builtin_available` mean anything: without it the NDK marks a newer symbol
+// `unavailable` outright — not "call me under a check" but "this build cannot
+// see me" — and no guard satisfies that. Every other guarded call here now goes
+// through the flag; ADPF still comes through dlsym because it works and this is
+// not the change to test it in.
//
-// The NDK's own answer is ANDROID_WEAK_API_DEFS, which turns such symbols into
-// weak references. Looking them up here instead keeps the decision in the code
-// that depends on it, where it is visible, rather than in a toolchain flag whose
-// absence would silently restore the same class of failure.
+// The objection to the flag was that its absence would silently restore the
+// failure it prevents. That was true while the floor equalled the newest API
+// this file called, when dropping it changed nothing. Below that floor it is a
+// compile error naming the symbol, which is how the flag got turned on.
struct PerformanceHints {
void* session = nullptr;