feat: support shared soname runtime aliases

Author: Sunrisepeak

CHANGELOG.md

@@ -3,6 +3,20 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.0.46] — 2026-06-03
+
+### 新增
+
+- 共享库 target 支持声明 `soname`,Linux 构建会传递 `-Wl,-soname,...`,
+  并在运行产物目录生成 ABI 名称 alias,供下游 `DT_NEEDED` / `dlopen()`
+  以标准 SONAME 加载。
+
+### 修复
+
+- `mcpp run` / `mcpp test` 会把工具链 runtime 目录加入进程库搜索环境。
+  这修复了 GLX/OpenGL driver 这类经由 `dlopen()` 加载的库无法找到自身
+  `DT_NEEDED` 闭包的问题。
+
 ## [0.0.45] — 2026-06-02
 
 ### 修复

docs/05-mcpp-toml.md

@@ -71,8 +71,15 @@ kind = "lib"
 # 共享库
 [targets.mylib]
 kind = "shared"
+soname = "libmylib.so.1"  # 可选: ELF/Mach-O ABI 名称,运行时会生成同名 alias
 ```
 
+`soname` 用于共享库的 ABI 名称,类似 Autotools/CMake 中的
+`SOVERSION`/`SONAME`。在 Linux 上,mcpp 会向链接器传递
+`-Wl,-soname,<name>`,并在输出目录生成 `<name> -> lib<target>.so` alias,
+让下游程序可通过标准 ABI 名称 `DT_NEEDED` 或 `dlopen()` 加载该库。
+该字段只对 `kind = "shared"` 有效,值必须是文件名 basename。
+
 ### 2.3 `[build]` — 构建配置
 
 ```toml

mcpp.toml

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version     = "0.0.45"
+version     = "0.0.46"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

src/build/ninja_backend.cppm

@@ -102,6 +102,17 @@ std::string join_flags(const std::vector<std::string>& flags) {
     return out;
 }
 
+std::string shared_soname_flag(const LinkUnit& lu) {
+    if (lu.kind != LinkUnit::SharedLibrary || lu.soname.empty()) return "";
+#if defined(__APPLE__)
+    return "-Wl,-install_name,@rpath/" + lu.soname;
+#elif defined(__linux__)
+    return "-Wl,-soname," + lu.soname;
+#else
+    return "";
+#endif
+}
+
 void write_file(const std::filesystem::path& p, std::string_view content) {
     std::filesystem::create_directories(p.parent_path());
     std::ofstream os(p);
@@ -369,9 +380,17 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     append("  description = AR $out\n\n");
 
     append("rule cxx_shared\n");
-    append("  command = $cxx -shared $in -o $out $ldflags $unit_ldflags\n");
+    append("  command = $cxx -shared $in -o $out $ldflags $soname_flag $unit_ldflags\n");
     append("  description = SHARED $out\n\n");
 
+    append("rule runtime_alias\n");
+    if constexpr (mcpp::platform::is_windows) {
+        append("  command = powershell -NoProfile -Command \"Copy-Item -Force '$in' -Destination '$out'\"\n");
+    } else {
+        append("  command = mkdir -p $$(dirname $out) && rm -f $out && ln -s $$(basename $in) $out\n");
+    }
+    append("  description = ALIAS $out\n\n");
+
     if (dyndep) {
         // Scan rule: produce P1689 .ddi for one TU.
         // GCC: built-in -fdeps-format=p1689r5 flags during preprocessing.
@@ -618,16 +637,27 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         std::string out_line = std::format("build {} : {}{}{}\n",
             escape_ninja_path(lu.output), rule, ins,
             implicit.empty() ? std::string{} : " |" + implicit);
+        if (auto flag = shared_soname_flag(lu); !flag.empty())
+            out_line += "  soname_flag = " + flag + "\n";
         if (auto flags = join_flags(lu.linkFlags); !flags.empty())
             out_line += "  unit_ldflags =" + flags + "\n";
         append(std::move(out_line));
+
+        for (auto const& alias : lu.runtimeAliases) {
+            append(std::format("build {} : runtime_alias {}\n",
+                escape_ninja_path(alias),
+                escape_ninja_path(lu.output)));
+        }
     }
     append("\n");
 
     if (!plan.linkUnits.empty()) {
         std::string defaults;
         for (auto& lu : plan.linkUnits) {
             defaults += " " + escape_ninja_path(lu.output);
+            for (auto const& alias : lu.runtimeAliases) {
+                defaults += " " + escape_ninja_path(alias);
+            }
         }
         append("default" + defaults + "\n");
     }
@@ -720,6 +750,9 @@ std::expected<BuildResult, BuildError> NinjaBackend::build(const BuildPlan& plan
             std::fputs(out.c_str(), stdout);
         for (auto& lu : plan.linkUnits) {
             r.producedArtifacts.push_back(plan.outputDir / lu.output);
+            for (auto const& alias : lu.runtimeAliases) {
+                r.producedArtifacts.push_back(plan.outputDir / alias);
+            }
         }
     } else {
         auto prefixes = command_prefixes(flags, plan);

src/build/plan.cppm

@@ -33,6 +33,8 @@ struct LinkUnit {
     std::vector<std::filesystem::path> implicitInputs; // relative to plan.outputDir
     std::vector<std::string>        linkFlags;          // per-link edge flags
     std::filesystem::path           output;            // relative to plan.outputDir
+    std::string                     soname;            // ABI name for shared libraries
+    std::vector<std::filesystem::path> runtimeAliases; // relative aliases, e.g. bin/libfoo.so.1
     std::optional<std::filesystem::path> entryMain;   // src path of main.cpp for bin
 };
 
@@ -133,6 +135,20 @@ std::filesystem::path target_output(const mcpp::manifest::Target& t) {
            std::format("{}{}", t.name, mcpp::platform::exe_suffix);
 }
 
+std::vector<std::filesystem::path> runtime_aliases_for_target(
+    const mcpp::manifest::Target& t) {
+    std::vector<std::filesystem::path> aliases;
+    if (t.kind != mcpp::manifest::Target::SharedLibrary || t.soname.empty()) {
+        return aliases;
+    }
+
+    auto output = target_output(t);
+    if (t.soname != output.filename().string()) {
+        aliases.push_back(output.parent_path() / t.soname);
+    }
+    return aliases;
+}
+
 bool is_implementation_source(const std::filesystem::path& source) {
     auto ext = source.extension();
     return ext == ".cpp" || ext == ".cc" || ext == ".cxx" || ext == ".c" || ext == ".m";
@@ -207,6 +223,16 @@ BuildPlan make_plan(const mcpp::manifest::Manifest&         manifest,
                 dir.is_absolute() ? dir : package.root / dir);
         }
     }
+    // The same private runtime directories embedded as executable RUNPATH are
+    // also needed in the process environment for libraries reached only via
+    // dlopen(), because their own DT_NEEDED closure does not consult the main
+    // executable's RUNPATH.
+    for (auto const& dir : tc.linkRuntimeDirs) {
+        append_unique_path(plan.runtimeLibraryDirs, dir);
+    }
+    if (tc.payloadPaths) {
+        append_unique_path(plan.runtimeLibraryDirs, tc.payloadPaths->glibcLib);
+    }
 
     // 1a. Detect basename collisions (both cross-package AND intra-package:
     //     ftxui ships dom/color.cpp + screen/color.cpp, for instance).
@@ -375,6 +401,8 @@ BuildPlan make_plan(const mcpp::manifest::Manifest&         manifest,
         lu.targetName = dep.target.name;
         lu.kind       = LinkUnit::SharedLibrary;
         lu.output     = dep.output;
+        lu.soname     = dep.target.soname;
+        lu.runtimeAliases = runtime_aliases_for_target(dep.target);
         append_package_objects(lu, dep.packageName);
         append_direct_shared_deps(lu, dep.packageIndex);
         plan.linkUnits.push_back(std::move(lu));
@@ -399,6 +427,8 @@ BuildPlan make_plan(const mcpp::manifest::Manifest&         manifest,
         } else if (t.kind == mcpp::manifest::Target::SharedLibrary) {
             lu.kind   = LinkUnit::SharedLibrary;
             lu.output = target_output(t);
+            lu.soname = t.soname;
+            lu.runtimeAliases = runtime_aliases_for_target(t);
         } else if (t.kind == mcpp::manifest::Target::TestBinary) {
             lu.kind   = LinkUnit::TestBinary;
             lu.output = target_output(t);

src/manifest.cppm

@@ -55,6 +55,7 @@ struct Target {
     std::string                 name;
     enum Kind { Library, Binary, SharedLibrary, TestBinary } kind;
     std::string                 main;           // for binary / test
+    std::string                 soname;         // ABI name for shared libraries, e.g. libfoo.so.1
 };
 
 // `DependencySpec` and `kDefaultNamespace` have moved to mcpp.pm.dep_spec.
@@ -304,6 +305,25 @@ ManifestError error(const std::filesystem::path& origin,
     return ManifestError{msg, origin, pos.line, pos.column};
 }
 
+bool is_basename(std::string_view value) {
+    return !value.empty()
+        && value.find('/') == std::string_view::npos
+        && value.find('\\') == std::string_view::npos;
+}
+
+std::optional<std::string> validate_target_soname(const Target& t,
+                                                  std::string_view targetPath) {
+    if (t.soname.empty()) return std::nullopt;
+    if (t.kind != Target::SharedLibrary) {
+        return std::format("{}soname is only valid for shared targets", targetPath);
+    }
+    if (!is_basename(t.soname)) {
+        return std::format("{}soname must be a library basename, got '{}'",
+                           targetPath, t.soname);
+    }
+    return std::nullopt;
+}
+
 } // namespace
 
 std::expected<CppStandardConfig, std::string> normalize_cpp_standard(std::string_view raw) {
@@ -481,6 +501,16 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             }
             t.main = mit->second.as_string();
         }
+        if (auto sit = tt.find("soname"); sit != tt.end()) {
+            if (!sit->second.is_string()) {
+                return std::unexpected(error(origin,
+                    std::format("targets.{}.soname must be a string", tname)));
+            }
+            t.soname = sit->second.as_string();
+        }
+        if (auto msg = validate_target_soname(t, std::format("targets.{}.", tname))) {
+            return std::unexpected(error(origin, *msg));
+        }
         m.targets.push_back(std::move(t));
     }
     } // close `if (targets_table && !targets_table->empty())`
@@ -1620,6 +1650,8 @@ synthesize_from_xpkg_lua(std::string_view luaContent,
                               || k == "so" || k == "shlib")        t.kind = Target::SharedLibrary;
                     } else if (sub == "main") {
                         t.main = cur.read_string();
+                    } else if (sub == "soname") {
+                        t.soname = cur.read_string();
                     } else {
                         // unknown subfield — skip its value
                         cur.skip_ws_and_comments();
@@ -1629,6 +1661,9 @@ synthesize_from_xpkg_lua(std::string_view luaContent,
                     cur.skip_ws_and_comments();
                 }
                 cur.consume('}');
+                if (auto msg = validate_target_soname(t, std::format("targets.{}.", tname))) {
+                    return std::unexpected(ManifestError{*msg, m.sourcePath, 0, 0});
+                }
                 m.targets.push_back(std::move(t));
                 cur.skip_ws_and_comments();
             }

src/toolchain/fingerprint.cppm

@@ -18,7 +18,7 @@ import mcpp.toolchain.detect;
 
 export namespace mcpp::toolchain {
 
-inline constexpr std::string_view MCPP_VERSION = "0.0.45";
+inline constexpr std::string_view MCPP_VERSION = "0.0.46";
 
 struct FingerprintInputs {
     Toolchain                       toolchain;

tests/e2e/64_shared_soname_runtime_alias.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# requires: elf
+# Shared libraries can declare an ABI SONAME. Consumers may load that ABI name
+# through dlopen(), and mcpp run must provide the runtime alias automatically.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+cd "$TMP"
+mkdir -p depShared/src app/src
+
+cat > depShared/src/dep.c <<'EOF'
+int dep_shared_answer(void) {
+    return 42;
+}
+EOF
+
+cat > depShared/mcpp.toml <<'EOF'
+[package]
+name    = "depShared"
+version = "0.1.0"
+
+[build]
+sources = ["src/*.c"]
+
+[targets.depShared]
+kind = "shared"
+soname = "libdepShared.so.1"
+EOF
+
+cat > app/src/main.cpp <<'EOF'
+#include <dlfcn.h>
+
+using answer_fn = int (*)();
+
+int main() {
+    void* handle = dlopen("libdepShared.so.1", RTLD_NOW);
+    if (!handle) {
+        return 10;
+    }
+    auto answer = reinterpret_cast<answer_fn>(dlsym(handle, "dep_shared_answer"));
+    if (!answer) {
+        dlclose(handle);
+        return 11;
+    }
+    int result = answer();
+    dlclose(handle);
+    return result == 42 ? 0 : 12;
+}
+EOF
+
+cat > app/mcpp.toml <<'EOF'
+[package]
+name    = "app"
+version = "0.1.0"
+
+[build]
+sources = ["src/*.cpp"]
+ldflags = ["-ldl"]
+
+[targets.app]
+kind = "bin"
+main = "src/main.cpp"
+
+[dependencies.depShared]
+path = "../depShared"
+EOF
+
+cd app
+"$MCPP" build > build.log 2>&1 || {
+    cat build.log
+    echo "build failed"
+    exit 1
+}
+
+so="$(find target -name 'libdepShared.so' | head -1)"
+alias="$(find target -name 'libdepShared.so.1' | head -1)"
+[[ -n "$so" && -n "$alias" ]] || {
+    cat build.log
+    find target -path '*/bin/*' -maxdepth 4 -type f -o -type l 2>/dev/null || true
+    echo "expected shared library and ABI soname alias were not produced"
+    exit 1
+}
+
+readelf -d "$so" | grep -q 'Library soname: \[libdepShared.so.1\]' || {
+    readelf -d "$so" || true
+    echo "shared library missing requested SONAME"
+    exit 1
+}
+
+"$MCPP" run > run.log 2>&1 || {
+    cat run.log
+    echo "run failed"
+    exit 1
+}
+
+echo "OK"