fix(dist-apk): link a project's res/ as the base, and pin android-platform 36-r2 (#21)

* fix(dist-apk): link a project's res/ as the base, and pin android-platform 36-r2

Two defects an application with a launcher icon hits, measured by
HuxerUI's Android row against 0.9.0.

`-R` is aapt2's overlay: every resource in that unit must override one the
base already defines. A project's `res/` IS the base, so its first colour
failed with `color/ic_launcher_background does not override an existing
resource`, and no icon, colour or string could be supplied at all. The
compiled unit is now passed positionally.

`xim:android-platform` was pinned at 35-r2 while the index has carried
36-r2 since openxlings/xim-pkgindex#834; a project declaring 36 for its
own targetSdkVersion got a two-versions warning and the nearer pin. The
option pins 36-r2, and the level-0 fixture manifest follows
(`targetSdkVersion="36"` -- the one byte in it that is read from the
platform, everything else is the template 0.8.0 rendered).

`tests/apk-consumer` gains criterion (g): with APK_CONSUMER_RES set, its
own `res/values/{strings,colors}.xml` -- two resources nothing else
defines -- link, and `aapt2 dump resources` on the apk lists both.
check-apk-features.sh (a) to (g) pass locally; HuxerUI's example 01 with
a launcher `res/` packs to an APK carrying `res/mipmap-*`,
`resources.arsc` and `application-icon-*` in its badging.

Version 0.9.1.

* fix: the version the module states follows the manifest (0.9.1)

---------

Co-authored-by: sunrisepeak <x.d2learn.org@gmail.com>

Author: Sunrisepeak

.github/workflows/ci.yml

@@ -1216,8 +1216,10 @@ jobs:
       # refusal's exit code of 0 (the script's own header says why); (e) two
       # Java roots, one under this project and one a sibling directory
       # reached by an absolute path, dex into one file carrying classes from
-      # both.
-      - name: dist-apk's manifest template and Java roots, (a) to (e)
+      # both; (g) a project's own res/ links as the BASE -- two resources
+      # nothing else defines reach the apk (0.9.0 linked res/ as an aapt2
+      # overlay, which refuses any resource the base does not already have).
+      - name: dist-apk's manifest template, Java roots and res/, (a) to (g)
         working-directory: tests/apk-consumer
         run: MCPP="$MCPP" ./check-apk-features.sh
 

README.md

@@ -75,7 +75,7 @@ engine's own module family and is not used here.
 | `dist-wix` | `mcpp.dist.wix` | 2026.9.11.1 | `xim:wix`, which this feature declares on the Windows target axis; the .NET 6 runtime the tool needs is a Windows component the payload does not carry, and `wix --version` names it when it is missing. Windows only. Renders a `.wxs` and passes the program in as a preprocessor variable, because a bind path that resolves to nothing is silent |
 | `dist-apple` | `mcpp.dist.apple` | 2026.9.11.2 (macOS), 2026.9.12.3 (iOS) | the base macOS install (`ditto`, and `codesign` only when an identity is given). macOS: `Contents/`-shaped, as always. iOS (`aarch64-ios-sim`, `aarch64-ios`): a flat bundle at the same call site -- no separate feature, no separate module -- with `MinimumOSVersion` from `mcpp::min_platform_version()` (#622 A11), `CFBundleSupportedPlatforms` read from `env == "sim"`, `UIDeviceFamily`, `LSRequiresIPhoneOS`, and a directory of flat PNGs listed under `CFBundleIcons` in place of macOS's single `.icns` file. Signing is skipped on the simulator row (`options::identity` is ignored, with a `mcpp::warning` naming why) and unchanged on the device row. The iOS row is measured end to end on `macos-15`: a real `mcpp build`, `mcpp pack --format app` and `mcpp run` against `aarch64-ios-sim`, through `xim:apple-simulator-tools`' `simctl-run`. **The macOS floor is one release higher than its siblings** and the reason is not this member: under 2026.9.11.1 `mcpp pack` staged before dispatching and let a staging failure fail the command, so on a Mach-O program -- which the built-in closure walk refuses, because it uses `LD_TRACE_LOADED_OBJECTS` and dyld answers that by running the program -- every dispatched format was unreachable, including one that reads no staged tree. 2026.9.11.2 makes staging a service to the provider |
 | `dist-web` | `mcpp.dist.web` | 2026.9.13.1, the release that carries `${mcpp.self}` and `mcpp stage`'s argument shape as an engine contract (`stage --verify content --output <dst> <src>`) -- what lets this member's copy run on every host mcpp does, Windows included, in place of the `cp` this member used through 0.8.0 | nothing beyond mcpp: `wasm32-emscripten` only. Copies `${mcpp.stage_dir}/bin/` -- the `.js` launcher, the implicit `.wasm`, the `.data` when present, and every `mcpp::deploy`'d file, all of which #622 A5 and A4 already stage there -- to `<out_dir>/web/`, dropping the `bin/` prefix a browser has no use for, and writes an `index.html` rendered from a project template or a built-in default that loads the script with a plain `<script src>`. Each staged file and the rendered page are copied with `${mcpp.self} stage --verify content --output <dst> <src>`, the same copier every `stage_file` edge in `build.ninja` already runs -- no host-specific copy tool, no plan-time `create_directories` (`stage` creates the destination's parent), and a second `mcpp pack --format web` with nothing changed copies nothing |
-| `dist-apk` | `mcpp.dist.apk` | 2026.9.13.1, raised alongside `dist-web` in the same 0.9.0 release: this member's own manifest-template and Java-array changes ask nothing new of the engine, but this collection publishes one package at one version, and this is the release CI verifies it under from here on | `xim:android-build-tools`, `xim:android-platform` (versioned by API level, read back for `targetSdkVersion`), `xim:jdk-temurin` (`javac`/`jar`; `android-build-tools`' own runtime dependency provisions a JDK for its OWN wrappers only), `xim:android-debug-keystore`, all on the `cfg(env = "android")` axis. Generates `AndroidManifest.xml` and signs with the published Android debug key by default. Level 0 needs no Java (`hasCode="false"`, `android.app.NativeActivity`); `options::java_sources` adds `javac` + `d8` and a real `<activity>`. `options::manifest_template` renders a project manifest with six tokens substituted verbatim; `{{application_id}}` and `{{activity}}` are required always and `{{lib_name}}` at level 0, each refused by name at plan time when missing (naming `assets/mcpp-run.json`, which `adb-run` reads them from too) or when the template names an unknown token; empty renders 0.8.0's manifest byte-identically. `options::java_sources` is an array: one `javac` over every root's `.java` files and one `d8` over the result, so a project's own sources and a path dependency's join without being merged into one directory first, and `rerun_if_changed_glob` is declared only for a root under `mcpp::manifest_dir()` -- a dependency root's files are already inputs of the `javac` action and its version is already in the build's fingerprint. Android only -- an `app` target is a shared object on this row (#622 A3), and this member reads its native library from the staged tree and whatever `mcpp::deploy` placed beside the ordinary build's link output, because Android's own closure stages neither the dependency set nor the deployed files (see `dist/apk.cppm`'s header). CI packages both level 0 and level 1 and checks the archive (`libc++_shared.so` bundled only when the closure's `NEEDED` entries require it, `mcpp::deploy`'d files under `assets/`); the runner has no emulator or device, so the two rows that actually run were measured locally on 2026-09-12, through `adb-run`, against a KVM-accelerated x86_64 emulator and a physical arm64-v8a phone, both printing `1-2-3` and exiting 0 |
+| `dist-apk` | `mcpp.dist.apk` | 2026.9.13.1, raised alongside `dist-web` in the same 0.9.0 release: this member's own manifest-template and Java-array changes ask nothing new of the engine, but this collection publishes one package at one version, and this is the release CI verifies it under from here on | `xim:android-build-tools`, `xim:android-platform` (versioned by API level, read back for `targetSdkVersion`), `xim:jdk-temurin` (`javac`/`jar`; `android-build-tools`' own runtime dependency provisions a JDK for its OWN wrappers only), `xim:android-debug-keystore`, all on the `cfg(env = "android")` axis. Generates `AndroidManifest.xml` and signs with the published Android debug key by default. Level 0 needs no Java (`hasCode="false"`, `android.app.NativeActivity`); `options::java_sources` adds `javac` + `d8` and a real `<activity>`. `options::manifest_template` renders a project manifest with six tokens substituted verbatim; `{{application_id}}` and `{{activity}}` are required always and `{{lib_name}}` at level 0, each refused by name at plan time when missing (naming `assets/mcpp-run.json`, which `adb-run` reads them from too) or when the template names an unknown token; empty renders 0.8.0's manifest byte-identically. `options::resources` is a project's own `res/`, linked as the application's base resources from 0.9.1 (0.9.0 linked it as an aapt2 overlay, which refuses every resource the base does not already define -- a launcher icon could not be supplied). `options::java_sources` is an array: one `javac` over every root's `.java` files and one `d8` over the result, so a project's own sources and a path dependency's join without being merged into one directory first, and `rerun_if_changed_glob` is declared only for a root under `mcpp::manifest_dir()` -- a dependency root's files are already inputs of the `javac` action and its version is already in the build's fingerprint. Android only -- an `app` target is a shared object on this row (#622 A3), and this member reads its native library from the staged tree and whatever `mcpp::deploy` placed beside the ordinary build's link output, because Android's own closure stages neither the dependency set nor the deployed files (see `dist/apk.cppm`'s header). CI packages both level 0 and level 1 and checks the archive (`libc++_shared.so` bundled only when the closure's `NEEDED` entries require it, `mcpp::deploy`'d files under `assets/`); the runner has no emulator or device, so the two rows that actually run were measured locally on 2026-09-12, through `adb-run`, against a KVM-accelerated x86_64 emulator and a physical arm64-v8a phone, both printing `1-2-3` and exiting 0 |
 
 ### Each rule brings its own environment
 

dist/apk.cppm

@@ -134,9 +134,10 @@ struct options {
     // manifest byte-identical to 0.8.0's (`tests/apk-consumer`).
     std::string manifest_template;
 
-    // A `res/`-shaped directory `aapt2 compile --dir` compiles. Empty means
-    // no resources at all -- a legal, common case for a NativeActivity
-    // application that draws everything itself.
+    // A `res/`-shaped directory `aapt2 compile --dir` compiles and `aapt2
+    // link` links as the application's OWN resources -- its launcher icon,
+    // colours, strings. Empty means no resources at all -- a legal, common
+    // case for a NativeActivity application that draws everything itself.
     std::string resources;
 
     // LEVEL 1. One or more directories of `.java` sources; one `javac` over
@@ -358,12 +359,12 @@ inline std::string label_for(const options& opt) {
 }
 
 // `xim:android-platform`'s own resolved directory is named after the
-// version it resolved -- "35-r2", "34-r3" (`pkgs/a/android-platform.lua`'s
-// own `extract_dir()` recovers the API level the identical way, from the
-// leading digits of its OWN version string) -- so the level a project
-// pinned is read back from the directory `xpkg_dir` already answered,
-// rather than duplicated as a second option this member could disagree
-// with.
+// version it resolved -- "36-r2", "35-r2", "34-r3" (`pkgs/a/android-
+// platform.lua`'s own `extract_dir()` recovers the API level the identical
+// way, from the leading digits of its OWN version string) -- so the level a
+// project pinned is read back from the directory `xpkg_dir` already
+// answered, rather than duplicated as a second option this member could
+// disagree with.
 inline std::string api_level_from_platform_dir(const std::string& dir) {
     if (dir.empty()) return {};
     const std::string leaf = fs::path(dir).filename().string();
@@ -995,7 +996,13 @@ inline plan plan_for(options opt = {}) {
     link.output = (outDir / "base.apk").string();
     link.argv = { aapt2, "link", "-I", androidJar, "--manifest", manifestPath,
                  "--min-sdk-version", minSdk, "--target-sdk-version", targetSdk };
-    if (!assembled.empty()) { link.argv.push_back("-R"); link.argv.push_back(assembled.back()); }
+    // POSITIONAL, NOT `-R`. `-R` is aapt2's overlay: a compilation unit whose
+    // resources must each override one the base already defines, and a
+    // project's `res/` IS the base -- linked with `-R`, its first colour
+    // failed as `color/ic_launcher_background does not override an existing
+    // resource` (0.9.0, measured by HuxerUI's Android row). A positional
+    // unit is the base.
+    if (!assembled.empty()) link.argv.push_back(assembled.back());
     link.argv.push_back("-o"); link.argv.push_back(link.output);
     link.inputs = { manifestPath, androidJar };
     if (!assembled.empty()) link.inputs.push_back(assembled.back());

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 name        = "plugins"
 namespace   = "mcpp"
-version     = "0.9.0"
+version     = "0.9.1"
 description = "Official mcpp build plugins: rule packages under mcpp.rules.*, build-time utilities under mcpp.tools.*, each member selected by a feature"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]
@@ -425,14 +425,14 @@ implies           = ["surface"]
 # key can be handed back as a dependency's "version" and joined to a store
 # path that does not exist, and this rule's own tools inherit the identical
 # hazard if they pin the alias. `xim:android-platform`'s table is keyed by
-# alias too (`"35" = { ref = "35-r2" }`), so this declares the resolved key
+# alias too (`"36" = { ref = "36-r2" }`), so this declares the resolved key
 # directly for the same reason -- `targetSdkVersion` is read back from the
 # directory this entry resolves to (`api_level_from_platform_dir`), so an
 # alias that silently failed to resolve would surface as a build-time
 # refusal rather than a wrong number, but there is no reason to court it.
 [target.'cfg(env = "android")'.feature-xlings.dist-apk]
 "xim:android-build-tools"     = ">=37.0.0"
-"xim:android-platform"        = "35-r2"
+"xim:android-platform"        = "36-r2"
 "xim:jdk-temurin"             = "25.0.4+7"
 "xim:android-debug-keystore"  = "1.0.0"
 

src/plugins.cppm

@@ -49,7 +49,7 @@ export namespace mcpp::plugins {
 //
 // One package, one version: the number lives in mcpp.toml, and the CI step
 // `the collection states its own version` compares the two.
-inline constexpr std::string_view version = "0.9.0";
+inline constexpr std::string_view version = "0.9.1";
 
 } // namespace mcpp::plugins
 

tests/apk-consumer/build.mcpp

@@ -4,8 +4,9 @@
 // -- see dist/apk.cppm's header for why that source is the ordinary build
 // tree and not the pack pipeline's own staged tree on this row.
 //
-// TWO ENVIRONMENT VARIABLES, READ ONLY HERE, SELECT THE FIVE CRITERIA OF
-// design record §3.5 / §9.2 P1-P2 WITHOUT A SECOND FIXTURE.
+// THREE ENVIRONMENT VARIABLES, READ ONLY HERE, SELECT THE SIX CRITERIA OF
+// design record §3.5 / §9.2 P1-P2 AND check-apk-features.sh's (g) WITHOUT A
+// SECOND FIXTURE.
 //
 //   APK_CONSUMER_TEMPLATE   a manifest template file, package-root-relative.
 //                           Unset is the byte-identity criterion (a): the
@@ -15,8 +16,11 @@
 //                           sibling directory this build program reaches by
 //                           an absolute path, standing in for a path
 //                           dependency's own Java tree (design record §3.3).
+//   APK_CONSUMER_RES        non-empty links this package's own `res/` -- two
+//                           resources nothing else defines, so they link only
+//                           as the BASE (positional), never as an overlay.
 //
-// Neither variable is read by `dist-apk` itself -- both are this fixture's
+// No variable is read by `dist-apk` itself -- both are this fixture's
 // own choice of which of its options to set, the same way any project would
 // choose them from its own configuration.
 import std;
@@ -44,6 +48,10 @@ int main() {
     if (const char* tpl = std::getenv("APK_CONSUMER_TEMPLATE"); tpl && *tpl) {
         opt.manifest_template = tpl;
     }
+    // (g) a project's own res/ -- the base, not an overlay.
+    if (const char* res = std::getenv("APK_CONSUMER_RES"); res && *res) {
+        opt.resources = root + "/res";
+    }
     if (const char* level1 = std::getenv("APK_CONSUMER_LEVEL1"); level1 && *level1) {
         opt.activity = "org.mcpp.apkconsumer.MainActivity";
         // The project's own Java root, and a SIBLING of this fixture's own

tests/apk-consumer/check-apk-features.sh

@@ -2,9 +2,9 @@
 # End-to-end checks for dist-apk's manifest template (design record
 # `2026-09-13-four-upstream-asks-from-a-ui-framework.md`, §3.2 / §9.2 P1) and
 # Java-array (§3.3 / P2) changes, criteria (a) to (e) of §3.5 read against
-# this fixture. `build.mcpp` here reads two environment variables this
-# script sets to reach each configuration without a second fixture -- see
-# its own header.
+# this fixture, plus (g): a project's own res/ links as the base. `build.mcpp`
+# here reads three environment variables this script sets to reach each
+# configuration without a second fixture -- see its own header.
 #
 # Usage: MCPP=<mcpp 2026.9.13.1+> ./check-apk-features.sh   (run from this
 # directory, after `tests/apk-consumer`'s own level-0 CI step, whose target/
@@ -25,6 +25,11 @@ DEXDUMP="$BT/dexdump"
 [ -x "$DEXDUMP" ] || fail "dexdump not found under $BT"
 
 # ── (a) level 0, no template: byte-identical to 0.8.0's manifest ───────────
+#
+# One byte is not 0.8.0's: `targetSdkVersion` is read back from the pinned
+# `xim:android-platform` (`api_level_from_platform_dir`), 36 since 0.9.1
+# (35 in 0.8.0 and 0.9.0). The fixture carries the current level; every
+# other byte is the template 0.8.0 rendered.
 echo "== (a) level 0, no template =="
 rm -rf target
 unset APK_CONSUMER_TEMPLATE APK_CONSUMER_LEVEL1 || true
@@ -193,3 +198,24 @@ unset APK_CONSUMER_LEVEL1
 
 rm -f build-*.log pack-*.log xmltree-*.log refusal-*.log dexdump-*.log mcpp-env.txt
 echo "PASS: dist-apk's manifest template and Java-array criteria (a) to (f)"
+
+# ── (g) a project's res/ is the base, so a NEW resource links ──────────────
+#
+# 0.9.0 handed the compiled res/ to `aapt2 link` as `-R`, which is aapt2's
+# overlay semantics: every resource must override one the base already
+# defines, so the first colour of a real res/ failed with `does not override
+# an existing resource`. A project's res/ is the base and is linked
+# positionally; the two resources here are defined by nothing else.
+echo "== (g) a project res/ links as the base =="
+rm -rf target
+unset APK_CONSUMER_TEMPLATE APK_CONSUMER_LEVEL1 || true
+export APK_CONSUMER_RES=1
+"$MCPP" build --target "$TARGET" > build-f.log 2>&1 || fail "build failed" build-f.log
+"$MCPP" pack --format apk --target "$TARGET" > pack-f.log 2>&1 || fail "pack failed" pack-f.log
+APK=$(find target -name 'apk-consumer.apk' | head -1)
+[ -n "$APK" ] || fail "no apk-consumer.apk" pack-f.log
+"$AAPT2" dump resources "$APK" > resources-f.log 2>&1 || fail "aapt2 dump resources failed" resources-f.log
+grep -q 'string/apk_consumer_title' resources-f.log || fail "the project's string did not link" resources-f.log
+grep -q 'color/apk_consumer_background' resources-f.log || fail "the project's colour did not link" resources-f.log
+unset APK_CONSUMER_RES
+echo "ok: a project res/ with resources nobody else defines links as the base"

tests/apk-consumer/fixtures/expected-manifest-level0-0.8.0.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="app.apk_consumer">
-    <uses-sdk android:minSdkVersion="24" android:targetSdkVersion="35"/>
+    <uses-sdk android:minSdkVersion="24" android:targetSdkVersion="36"/>
     <application android:label="apk-consumer" android:hasCode="false">
         <activity android:name="android.app.NativeActivity" android:exported="true">
             <meta-data android:name="android.app.lib_name" android:value="apk-consumer"/>

tests/apk-consumer/res/values/colors.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- A NEW resource, defined by nobody else: what an overlay link refuses. -->
+    <color name="apk_consumer_background">#FF3F51B5</color>
+</resources>

tests/apk-consumer/res/values/strings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="apk_consumer_title">apk-consumer</string>
+</resources>