0.9.3: dist-apk carries the graph's shared libraries, and the manifest template gains the version tokens (#23)

Two things an application whose framework is a separate `lib<fw>.so`
on Android (the shape Gradle builds) hits against 0.9.2.

The graph's shared libraries never reached the APK. A dependency declared
`linkage = "shared"` is linked as `lib<dep>.so` beside the app's object
in the ordinary build's `bin/` and NEEDed by name; the engine stages the
app's own object and the deployed files, but the closure on this row is
`not-walked` (a host cannot run an Android artifact), so `lib/` carried
the app and `libc++_shared.so` only, and the APK installed and died at
`dlopen`. `apk:needed` now walks NEEDED from the app's own object at
command time -- the set is not knowable at plan time without the
closure -- and copies every name that exists beside the object,
recursively, into `lib/<abi>/`; platform libraries live nowhere beside
it and are skipped.

The manifest template gains `{{version_name}}` (the package version as
written) and `{{version_code}}` (major * 1000000 + minor * 1000 +
patch over the leading numeric segments, 1 when none parses), so a
template can carry `android:versionName` / `android:versionCode`
without a second spelling of the version. The built-in default stays
byte-identical to 0.8.0's.

`tests/apk-consumer-shared` (a path dependency shared on the Android
row; the APK lists `lib/x86_64/libapk-consumer-dep.so`) and criterion
(h) of `tests/apk-consumer` (versionName 0.3.0, versionCode 3000).
Both measured locally with mcpp 2026.9.13.2; (a) to (g) unchanged.

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

Author: Sunrisepeak

.github/workflows/ci.yml

@@ -1219,10 +1219,28 @@ jobs:
       # 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)
+      - name: dist-apk's manifest template, Java roots, res/ and version tokens, (a) to (h)
         working-directory: tests/apk-consumer
         run: MCPP="$MCPP" ./check-apk-features.sh
 
+      # A dependency linked as a shared object on the Android row reaches
+      # `lib/<abi>/` beside the app's own: walked from the app's NEEDED at
+      # command time, because the closure on this row is `not-walked` and the
+      # engine stages the app's object and the deployed files only (0.9.3).
+      - name: dist-apk carries the graph's shared libraries
+        working-directory: tests/apk-consumer-shared
+        run: |
+          "$MCPP" build --target x86_64-linux-android
+          "$MCPP" pack --format apk --target x86_64-linux-android | tee pack.log
+          apk=$(find target -name 'apk-consumer-shared.apk' | head -1)
+          test -n "$apk" || { cat pack.log; echo "FAIL: no apk-consumer-shared.apk"; exit 1; }
+          JDK=$(find "$MCPP_HOME/registry/data/xpkgs/xim-x-jdk-temurin" -mindepth 1 -maxdepth 1 -type d | head -1)
+          "$JDK/bin/jar" tf "$apk" | tee listing.log
+          for f in "lib/x86_64/libapk-consumer-shared.so" "lib/x86_64/libapk-consumer-dep.so"; do
+            grep -qxF "$f" listing.log || { echo "FAIL: the apk does not list $f"; exit 1; }
+          done
+          echo "ok: the dependency's shared object is in the apk beside the app's"
+
       # Compiles the device unit on a machine with no GPU: the clang route
       # produces sm_89 code from the payload toolkit. Running it needs a
       # device, so the run is of the CPU variant, which the same seam serves.

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. From 0.9.2 the staged tree's deployed files (`bin/<to>/...`, which the engine stages for a Mach-O program before the closure walk since the release for mcpp#630) land at the bundle's resource destination -- `Contents/Resources/<to>/...` on macOS, the bundle root on iOS -- and the launcher alone goes to the executable directory, so `CFBundleExecutable` names a file that is where it says. The iOS fixture declares `llvm.libcxx` and `llvm.compiler-rt-builtins` under `cfg(os = "ios")`, which is what an application that imports `std` on those rows declares |
 | `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::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 |
+| `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. From 0.9.3 the member walks the app object's `NEEDED` at command time and copies every graph-built shared library it finds beside the object (a dependency declared `linkage = "shared"`) into `lib/<abi>/`, since the closure on this row is `not-walked`; and the manifest template gains `{{version_name}}` / `{{version_code}}` (the package version, and `major * 1000000 + minor * 1000 + patch`). `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

@@ -386,13 +386,39 @@ inline std::string replace_all_copy(std::string s, std::string_view from, std::s
     return s;
 }
 
-// The six tokens a manifest template may use.
+// The eight tokens a manifest template may use. `version_name` is the
+// package version as written; `version_code` is Android's monotonic integer
+// derived from its leading numeric segments (`version_code_for`).
 inline const std::vector<std::string>& manifest_tokens() {
     static const std::vector<std::string> v = {
-        "application_id", "label", "activity", "lib_name", "min_sdk", "target_sdk"};
+        "application_id", "label", "activity", "lib_name", "min_sdk", "target_sdk",
+        "version_name", "version_code"};
     return v;
 }
 
+// `android:versionCode` from a version string: major * 1000000 + minor * 1000
+// + patch over the first three dot-separated numeric segments, so that every
+// release a project cuts orders after the one before it, and "1" when the
+// string starts with no number at all -- Android refuses 0 and a manifest
+// without the attribute installs but never updates.
+inline std::string version_code_for(const std::string& version) {
+    long long code = 0, seg = 0;
+    int segments = 0;
+    bool digits = false;
+    const long long weights[3] = {1000000, 1000, 1};
+    for (std::size_t i = 0; i <= version.size() && segments < 3; ++i) {
+        const char c = i < version.size() ? version[i] : '\0';
+        if (c >= '0' && c <= '9') { seg = seg * 10 + (c - '0'); digits = true; continue; }
+        if (!digits) break;
+        code += std::min<long long>(seg, 999) * weights[segments] ;
+        ++segments; seg = 0; digits = false;
+        if (c != '.') break;
+    }
+    if (segments == 0) return "1";
+    if (code <= 0) return "1";
+    return std::to_string(code);
+}
+
 // Every `{{...}}` a template names, in first-appearance order, duplicates
 // dropped -- what both checks in `render_manifest` below read.
 inline std::vector<std::string> tokens_in(const std::string& text) {
@@ -478,13 +504,14 @@ inline bool render_manifest(const std::string& templateText, bool has_code,
                             const std::string& appId, const std::string& label,
                             const std::string& activityName, const std::string& libName,
                             const std::string& minSdk, const std::string& targetSdk,
+                            const std::string& versionName, const std::string& versionCode,
                             std::string& out, std::string& reason) {
     for (auto const& tok : tokens_in(templateText)) {
         if (std::ranges::find(manifest_tokens(), tok) == manifest_tokens().end()) {
             std::cerr << "mcpp.dist.apk: the manifest template names an unknown "
                          "token '{{" << tok << "}}' -- expected one of "
                          "application_id, label, activity, lib_name, min_sdk, "
-                         "target_sdk\n";
+                         "target_sdk, version_name, version_code\n";
             reason = "unknown manifest template token '" + tok + "'";
             return false;
         }
@@ -507,6 +534,8 @@ inline bool render_manifest(const std::string& templateText, bool has_code,
     out = replace_all_copy(std::move(out), "{{lib_name}}", libName);
     out = replace_all_copy(std::move(out), "{{min_sdk}}", minSdk);
     out = replace_all_copy(std::move(out), "{{target_sdk}}", targetSdk);
+    out = replace_all_copy(std::move(out), "{{version_name}}", versionName);
+    out = replace_all_copy(std::move(out), "{{version_code}}", versionCode);
     return true;
 }
 
@@ -818,9 +847,12 @@ inline plan plan_for(options opt = {}) {
         manifestTemplateText = default_manifest_template(hasCode);
     }
 
+    const std::string versionName = mcpp::package_version() ? mcpp::package_version() : "";
+    const std::string versionCode = version_code_for(versionName);
     std::string manifestBytes;
     if (!render_manifest(manifestTemplateText, hasCode, appId, label, activityName,
-                         target, minSdk, targetSdk, manifestBytes, p.reason)) {
+                         target, minSdk, targetSdk, versionName, versionCode,
+                         manifestBytes, p.reason)) {
         return p;
     }
 
@@ -932,6 +964,42 @@ inline plan plan_for(options opt = {}) {
     { std::error_code ec; fs::permissions(copyThenJar,
         fs::perms::owner_exec | fs::perms::group_exec | fs::perms::others_exec,
         fs::perm_options::add, ec); }
+    // THE SHARED LIBRARIES THE GRAPH BUILT, WHICH THE STAGED TREE DOES NOT
+    // CARRY. A dependency declared `linkage = "shared"` is linked as its own
+    // `lib<dep>.so` beside the app's in the ordinary build's `bin/`, and the
+    // app's dynamic section NEEDs it by name. The engine stages the app's
+    // own object and the deployed files, but on this row the closure is
+    // `not-walked` (a host cannot run an Android artifact), so nothing else
+    // reaches `lib/` -- and an APK without `lib<dep>.so` installs and dies
+    // at `dlopen` (measured: HuxerUI's framework as a shared library,
+    // `NEEDED libhuxerui.so`, 2026.9.13.2 + 0.9.2). This helper walks NEEDED
+    // from the app's own object at command time -- the set is not knowable
+    // at plan time without the closure -- and copies every name that exists
+    // beside the object, recursively, into `lib/<abi>/`; names that live
+    // nowhere beside it (the platform's `libandroid.so`, `libc.so`) are
+    // skipped, and `libc++_shared.so` is the plan-time copy above.
+    const std::string collectNeeded = (helpersDir / "collect-needed.sh").string();
+    write_if_different(collectNeeded,
+        "#!/bin/sh\n"
+        "# mcpp.dist.apk helper. Do not edit.\n"
+        "set -e\n"
+        "readelf=\"$1\"; so=\"$2\"; dst=\"$3\"; stamp=\"$4\"\n"
+        "dir=$(dirname \"$so\")\n"
+        "mkdir -p \"$dst\"\n"
+        "copy_needed() {\n"
+        "  \"$readelf\" -d \"$1\" | sed -n 's/.*(NEEDED).*\\[\\(.*\\)\\].*/\\1/p' | while IFS= read -r n; do\n"
+        "    if [ -f \"$dir/$n\" ] && [ ! -f \"$dst/$n\" ]; then\n"
+        "      cp \"$dir/$n\" \"$dst/$n\"\n"
+        "      copy_needed \"$dir/$n\"\n"
+        "    fi\n"
+        "  done\n"
+        "}\n"
+        "copy_needed \"$so\"\n"
+        "mkdir -p \"$(dirname \"$stamp\")\"\n"
+        ": > \"$stamp\"\n");
+    { std::error_code ec; fs::permissions(collectNeeded,
+        fs::perms::owner_exec | fs::perms::group_exec | fs::perms::others_exec,
+        fs::perm_options::add, ec); }
     const std::string runAndStamp = (helpersDir / "run-and-stamp.sh").string();
     write_if_different(runAndStamp,
         "#!/bin/sh\n"
@@ -1088,6 +1156,21 @@ inline plan plan_for(options opt = {}) {
         javaOutputs.push_back(d8Step.output);
     }
 
+    // ── the graph's shared libraries, walked from the app's NEEDED ────────
+    step needed;
+    needed.id = "apk:needed";
+    needed.role = "artifact";
+    needed.description = "APK NEEDED";
+    needed.output = (outDir / "needed.stamp").string();
+    {
+        const std::string toolchainDir = mcpp::toolchain_dir();
+        const std::string readelf = (fs::path(toolchainDir) / "bin" / "llvm-readelf").string();
+        const std::string targetFile = std::format("${{mcpp.target_file:{}}}", target);
+        needed.argv = { collectNeeded, readelf, targetFile, libAbiDir.string(), needed.output };
+        needed.inputs = { targetFile };
+    }
+    p.steps.push_back(needed);
+
     // ── native library and assets join the archive ─────────────────────
     step libs;
     libs.id = "apk:libs";
@@ -1102,7 +1185,7 @@ inline plan plan_for(options opt = {}) {
         libs.argv.push_back((outDir / "dex").string());
         libs.argv.push_back("classes.dex");
     }
-    libs.inputs = { apkPath };
+    libs.inputs = { apkPath, needed.output };
     for (auto const& f : libInputs) libs.inputs.push_back(f);
     for (auto const& f : assetInputs) libs.inputs.push_back(f);
     for (auto const& f : javaOutputs) libs.inputs.push_back(f);

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 name        = "plugins"
 namespace   = "mcpp"
-version     = "0.9.2"
+version     = "0.9.3"
 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"]

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.2";
+inline constexpr std::string_view version = "0.9.3";
 
 } // namespace mcpp::plugins