Consume the xlings revision and glibc runtime data

The packaging revision xlings records for a payload
(`.xpkg-install.json`, openxlings/xlings#620) is read in one place,
`mcpp::xlings::paths::installed_revision`, and used twice.

The runtime contract (fingerprint field 11) includes the revision of
each runtime payload whose revision is 1 or more, so a C library
reinstalled under the same version with changed content selects a new
output directory. Revision 0 contributes nothing, so no existing key
changes.

An index dependency whose recorded revision differs from its
descriptor's entry is not installed (#524 A): mcpp's descriptor reader
now reads `revision` the way libxpkg does, and a stale payload goes back
through xlings, which reinstalls it. A payload with no xlings record is
judged by the marker, as before.

`mcpp pack --mode self-contained` copies the bundled C library's
`lib/locale` and `lib/gconv` from its payload when present and exports
LOCPATH and GCONV_PATH in the launcher, keeping a value the user set
(openxlings/xlings#621).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MajuX4J8ewFeWvZJjzRJt5

Author: claude

modules/manifest/src/xpkg.cppm

@@ -38,6 +38,10 @@ struct XpkgVersionEntry {
     std::string version;          // the literal key, as written
     bool        alias = false;    // entry carries `ref = "..."`
     std::string sha256;           // payload digest when declared at entry level
+    // The packaging revision of this version's payload (xpkg V2 `revision`),
+    // 0 when the entry states none or states something that is not a
+    // non-negative integer -- the reference implementation's reading.
+    int         revision = 0;
 };
 
 // Extract the version entries for `platform` (e.g. "linux", "macosx",
@@ -574,6 +578,40 @@ std::string top_level_table_body_for_key(std::string_view body, std::string_view
     return {};
 }
 
+// The non-negative integer bound to `wantedKey` at the top level of `body`,
+// or 0: `revision = 1` reads 1, and a string, a negative or a fractional value
+// reads as absent.
+int top_level_nonneg_int_for_key(std::string_view body, std::string_view wantedKey) {
+    LuaCursor cur { body };
+    cur.skip_ws_and_comments();
+    while (!cur.eof()) {
+        auto key = cur.read_key();
+        if (key.empty()) {
+            cur.skip_ws_and_comments();
+            if (cur.eof()) break;
+            ++cur.pos;
+            continue;
+        }
+        cur.skip_ws_and_comments();
+        if (!cur.consume('=')) {
+            cur.skip_ws_and_comments();
+            continue;
+        }
+        cur.skip_ws_and_comments();
+        if (cur.peek() == '{') { cur.skip_table(); cur.skip_ws_and_comments(); continue; }
+        if (cur.at_string_start()) { (void)cur.read_string(); cur.skip_ws_and_comments(); continue; }
+        const auto word = cur.read_bareword();
+        if (key == wantedKey) {
+            if (word.empty() || word.size() > 9
+                || !std::ranges::all_of(word, [](char c) { return c >= '0' && c <= '9'; }))
+                return 0;
+            return std::stoi(std::string(word));
+        }
+        cur.skip_ws_and_comments();
+    }
+    return 0;
+}
+
 std::string top_level_string_value_for_key(std::string_view body, std::string_view wantedKey) {
     LuaCursor cur { body };
     cur.skip_ws_and_comments();
@@ -1072,6 +1110,8 @@ list_xpkg_version_entries(std::string_view luaContent,
                 e.alias = entry_is_alias(v, entry_end);
                 e.sha256 = top_level_string_value_for_key(
                     luaContent.substr(v + 1, entry_end - v - 1), "sha256");
+                e.revision = top_level_nonneg_int_for_key(
+                    luaContent.substr(v + 1, entry_end - v - 1), "revision");
                 versions.push_back(std::move(e));
                 q = entry_end + 1;
                 continue;

src/build/prepare.cppm

@@ -6130,9 +6130,33 @@ prepare_build(bool print_fingerprint,
             return false;
         };
 
+        // THE DESCRIPTOR'S REVISION IS PART OF WHAT IS INSTALLED (#524 A,
+        // openxlings/xlings#620). A descriptor that changes what it installs
+        // keeps its version and raises the entry's `revision`; a payload whose
+        // recorded revision differs is not this version any more, however
+        // complete it is, and goes back through xlings, which reinstalls it
+        // and records the new revision. A payload with no xlings record at
+        // all is judged by the marker alone, as before.
+        const int recipeRevision = [&] {
+            if (!luaContent) return 0;
+            for (auto const& e : mcpp::manifest::list_xpkg_version_entries(
+                     *luaContent, targetPlatform))
+                if (e.version == version) return e.revision;
+            return 0;
+        }();
+        auto revisionIsCurrent = [&](const std::filesystem::path& p) {
+            const auto installed = mcpp::xlings::paths::installed_revision(p);
+            if (!installed || *installed == recipeRevision) return true;
+            mcpp::log::verbose("fetcher", std::format(
+                "{}@{}: installed revision {}, descriptor revision {}; reinstalling",
+                depName, version, *installed, recipeRevision));
+            return false;
+        };
+
         auto findCompleteInstalled = [&]() -> std::optional<std::filesystem::path> {
             auto p = findRawInstalled();
             if (!p) return std::nullopt;
+            if (!revisionIsCurrent(*p)) return std::nullopt;
             if (mcpp::fallback::is_install_complete(*p)) return p;
             if (installedLayoutMatchesIndex(*p)) {
                 mcpp::fallback::mark_install_complete(*p);

src/pack/pack.cppm

@@ -1041,8 +1041,21 @@ write_executable_script(const std::filesystem::path& path,
 std::expected<void, std::string>
 write_bundle_all_wrappers(const std::filesystem::path& stagingRoot,
                           std::string_view binaryName,
-                          std::string_view loaderName)
+                          std::string_view loaderName,
+                          bool localeData = false,
+                          bool gconvData = false)
 {
+    // glibc's compiled locales and its character-set converters, when the
+    // bundle carries them (openxlings/xlings#621). The C library that runs here
+    // is the bundled one, and it reads both from paths compiled into it, which
+    // name the machine the payload was installed on. This script is the only
+    // entry of the bundle, so exporting the variables here reaches every run;
+    // a value the user already set is kept.
+    std::string runtimeData;
+    if (localeData)
+        runtimeData += "LOCPATH=\"${LOCPATH:-$here/lib/locale}\"\nexport LOCPATH\n";
+    if (gconvData)
+        runtimeData += "GCONV_PATH=\"${GCONV_PATH:-$here/lib/gconv}\"\nexport GCONV_PATH\n";
     auto body = std::format(
         "#!/bin/sh\n"
         "# Auto-generated by `mcpp pack --mode self-contained`. Launches the\n"
@@ -1066,8 +1079,9 @@ write_bundle_all_wrappers(const std::filesystem::path& stagingRoot,
         "here=$(cd \"$(dirname \"$0\")\" && pwd)\n"
         "MCPP_BUNDLE_DIR=\"$here\"\n"
         "export MCPP_BUNDLE_DIR\n"
+        "{}"
         "exec \"$here/lib/{}\" --library-path \"$here/lib\" \"$here/bin/{}\" \"$@\"\n",
-        loaderName, binaryName);
+        runtimeData, loaderName, binaryName);
     if (auto r = write_executable_script(stagingRoot / "run.sh", body); !r) return r;
     if (auto r = write_executable_script(stagingRoot / std::string(binaryName), body); !r) return r;
     return {};
@@ -2312,11 +2326,39 @@ run(const Plan& plan, const mcpp::config::GlobalConfig& cfg)
                 // which the user typically wouldn't combine with --mode
                 // bundle-all. Skip wrapper, ship as-is.
             } else {
+                // The runtime data of the C library the bundle carries
+                // (openxlings/xlings#621): its compiled locales and its
+                // character-set converters, from the payload the bundled
+                // loader came from (`<payload>/lib64/ld-linux-*` ->
+                // `<payload>/lib/{locale,gconv}`). A payload without them
+                // contributes nothing, and the program runs as before.
+                bool localeData = false, gconvData = false;
+                for (auto const& d : toBundle) {
+                    if (d.soname != loader) continue;
+                    std::error_code dec;
+                    const auto payload =
+                        std::filesystem::canonical(d.path, dec).parent_path().parent_path();
+                    if (dec) break;
+                    auto copy_dir = [&](std::string_view sub) {
+                        const auto from = payload / "lib" / std::string(sub);
+                        std::error_code cec;
+                        if (!std::filesystem::is_directory(from, cec)) return false;
+                        const auto to = plan.stagingRoot / "lib" / std::string(sub);
+                        std::filesystem::create_directories(to, cec);
+                        std::filesystem::copy(from, to,
+                            std::filesystem::copy_options::recursive
+                            | std::filesystem::copy_options::overwrite_existing, cec);
+                        return !cec;
+                    };
+                    localeData = copy_dir("locale");
+                    gconvData  = copy_dir("gconv");
+                    break;
+                }
                 // Mode B writes BOTH `run.sh` and `<binary_name>` at the
                 // bundle root — same content, different names — so users
                 // can pick whichever entry point they prefer.
                 if (auto r = write_bundle_all_wrappers(plan.stagingRoot,
-                        plan.binaryName, loader); !r)
+                        plan.binaryName, loader, localeData, gconvData); !r)
                     return std::unexpected(Error{r.error()});
                 collect_licenses(toBundle, plan.stagingRoot);
             }

src/runtime/binding.cppm

@@ -16,6 +16,7 @@ import mcpp.libs.json;
 import mcpp.platform;
 import mcpp.xlings.runtime_selection;
 import mcpp.xlings.subos_info;
+import mcpp.xlings;
 
 export namespace mcpp::platform::runtime {
 
@@ -178,6 +179,15 @@ std::string canonical_contract(const RuntimeBinding& binding) {
     append_field(out, binding.hostLibc);
     for (auto const& p : binding.libraryDirs)
         append_field(out, p.generic_string());
+    // A payload reinstalled under the same version with changed content is a
+    // different runtime (openxlings/xlings#620), so its packaging revision is
+    // part of the contract. Revision 0 contributes nothing: a payload installed
+    // before revisions existed keeps the contract, and the output directory,
+    // it had.
+    for (auto const& p : binding.libraryDirs)
+        if (const int r = mcpp::xlings::paths::installed_revision(p.parent_path())
+                              .value_or(0); r > 0)
+            append_field(out, std::format("revision={}", r));
     // The farm participates in the hash because it participates in the
     // artifact: it lands in DT_RPATH, so a build made against one farm is not
     // interchangeable with a build made against another. `declared` is in for

src/xlings/xlings.cppm

@@ -210,6 +210,12 @@ namespace paths {
     std::optional<std::filesystem::path>
     recorded_payload(const Env& env, const XpkgRef& ref);
 
+    // The packaging revision xlings recorded for the payload in `payloadDir`
+    // (`.xpkg-install.json`, xlings 2026.9.27.1+; openxlings/xlings#620), and
+    // 0 when it recorded none -- the reading xlings itself gives a record that
+    // predates the field. `nullopt` when there is no record at all.
+    std::optional<int> installed_revision(const std::filesystem::path& payloadDir);
+
     // From compiler binary, climb parent dirs to find "xpkgs" directory.
     // Replaces 3 duplicate implementations in flags.cppm, ninja_backend.cppm,
     // stdmod.cppm.
@@ -1066,6 +1072,16 @@ void record_resolutions(const Env& env, std::span<const ResolvedTarget> targets)
     }
 }
 
+std::optional<int> installed_revision(const std::filesystem::path& payloadDir) {
+    std::ifstream in{payloadDir / ".xpkg-install.json", std::ios::binary};
+    if (!in) return std::nullopt;
+    std::string text{std::istreambuf_iterator<char>(in), {}};
+    auto j = nlohmann::json::parse(text, nullptr, /*allow_exceptions=*/false);
+    if (!j.is_object()) return std::nullopt;
+    if (!j.contains("revision") || !j["revision"].is_number_integer()) return 0;
+    return j["revision"].get<int>();
+}
+
 std::optional<std::filesystem::path>
 recorded_payload(const Env& env, const XpkgRef& ref) {
     if (ref.name.empty()) return std::nullopt;

tests/unit/test_freestanding.cpp

@@ -313,6 +313,23 @@ TEST(XpkgPayload, ABareVersionSelectsWhatXlingsSelected) {
     std::filesystem::remove_all(base);
 }
 
+// The revision xlings recorded for a payload (openxlings/xlings#620): the
+// field when present, 0 for a record that predates it, and nothing at all when
+// there is no record -- which is the case mcpp judges by its marker alone.
+TEST(XpkgPayload, InstalledRevisionReadsTheXlingsRecord) {
+    namespace xp = mcpp::xlings::paths;
+    auto dir = std::filesystem::temp_directory_path()
+             / std::format("mcpp-xpkg-rev-{}", ::getpid());
+    std::filesystem::remove_all(dir);
+    std::filesystem::create_directories(dir);
+    EXPECT_FALSE(xp::installed_revision(dir).has_value());
+    std::ofstream(dir / ".xpkg-install.json") << R"({"os":"linux","version":"2.44.3"})";
+    EXPECT_EQ(xp::installed_revision(dir), 0);
+    std::ofstream(dir / ".xpkg-install.json") << R"({"version":"2.44.3","revision":1})";
+    EXPECT_EQ(xp::installed_revision(dir), 1);
+    std::filesystem::remove_all(dir);
+}
+
 TEST(XpkgEnvVar, BothSpellingsAreDerivedFromOneSanitizer) {
     using mcpp::build::xpkg_env_var;
     // The two sides of the channel must agree; drifting apart would make the

tests/unit/test_manifest.cpp

@@ -504,6 +504,37 @@ package = {
     EXPECT_EQ(keys[2], "25.0.4.7.1");
 }
 
+// openxlings/xlings#620, mcpp#524 A: a version entry's `revision` is read the
+// way the reference implementation reads it -- a non-negative integer, and 0
+// for anything else or for its absence -- including the per-arch shape, whose
+// arch tables must not be mistaken for the revision.
+TEST(ListXpkgVersions, RevisionIsReadPerEntry) {
+    constexpr auto src = R"(
+package = {
+    name = "rev",
+    xpm = {
+        linux = {
+            ["latest"] = { ref = "1.2.0" },
+            ["1.0.0"]  = { url = "u", sha256 = "a" },
+            ["1.1.0"]  = { url = "u", sha256 = "b", revision = 2 },
+            ["1.2.0"]  = { x86_64 = { url = "u", sha256 = "c" }, revision = 1 },
+            ["1.3.0"]  = { url = "u", sha256 = "d", revision = "3" },
+            ["1.4.0"]  = { url = "u", sha256 = "e", revision = -1 },
+        },
+    },
+}
+)";
+    auto e = mcpp::manifest::list_xpkg_version_entries(
+        src, mcpp::platform::TargetPlatform::for_lint_of("linux"));
+    ASSERT_EQ(e.size(), 6u);
+    EXPECT_EQ(e[0].revision, 0);   // an alias carries none
+    EXPECT_EQ(e[1].revision, 0);
+    EXPECT_EQ(e[2].revision, 2);
+    EXPECT_EQ(e[3].revision, 1);
+    EXPECT_EQ(e[4].revision, 0);   // a string is not a revision
+    EXPECT_EQ(e[5].revision, 0);   // nor is a negative number
+}
+
 // The scanner used to walk the platform table character by character, so a
 // bracket key nested inside a version's own body (mirror tables write
 // `["GLOBAL"] = "https://..."`) counted as a published version.