feat: exports -- one neutral statement of the symbol surface, three renderings

Stage two of the general build-infrastructure design.

Both platforms already publish everything: ELF gives symbols default
visibility, and PE gets an auto-generated .def listing every symbol
(mcpp.build.coff_exports, WINDOWS_EXPORT_ALL_SYMBOLS semantics). What was
missing is the other direction.

A runtime with a stable ABI publishes a reviewed set so that what is outside it
stays free to change; a plugin loaded beside its rivals must not collide -- a
Vulkan ICD that exports its internals collides with the loader and with the
other ICDs in the process. This repository has the symptom on file: mcpp's own
duplicate-symbol check on the SYCL example reports 68 _Unwind_* symbols,
because one image holds two C++ runtimes and both export them.

exports takes a file of symbol patterns or an inline list, and the backend
renders it per platform -- version script, -exported_symbols_list, or the .def
that replaces the all-exports one. One statement, three renderings, which is
the shape [runtime] already established and the reason this is a manifest key
rather than three platform-specific flag lists.

IT DOES NOT IMPLY HIDDEN VISIBILITY, and that CORRECTS the design doc, which
said it should. The narrowing is a link-time property on all three formats, so
implying a compile-time one would give a single key two effects -- and the
second effect also changes how this library's own translation units see each
other, which is a separate decision with a separate reason.
-fvisibility=hidden stays available through [build] cxxflags for the code
generation it buys.

The export list is read at manifest load rather than at plan time, so every
later stage sees one representation; origin's parent is the package root and
that holds for the root, a path dependency and a store dependency alike, which
is the "same decision in N places" this would otherwise become.

e2e 621 builds one source twice and requires the two readings to DIFFER.
Asserting only that the public symbol is present passes for a library that
exports everything, which is the state before this change; asserting only that
the internal one is absent cannot distinguish "correctly hidden" from "never
linked at all".

Author: speak-agent

CHANGELOG.md

@@ -5,6 +5,30 @@
 
 ## [Unreleased]
 
+### 共享库能说出自己发布哪些符号:`exports`
+
+两个平台的默认都是"全导出":ELF 给符号默认可见性,PE 由引擎自动生成列出全部符号的
+`.def`。**缺的是反方向** —— 声明式地只发布一组。
+
+两类工程需要它。有稳定 ABI 的运行时只发布一份经评审的集合;与同类并存的插件不能撞名
+—— 一个把内部符号也导出的 Vulkan ICD 会与 loader 以及同进程内另一个 ICD 相撞。本仓库
+自己就有现成的例子:SYCL 示例构建时重复符号检查报的那 68 个 `_Unwind_*`,是一个镜像里
+两个 C++ 运行时都在导出 unwinder 符号。
+
+`exports` 接受一个符号模式文件或一个内联数组,由引擎按平台渲染成 version script /
+`-exported_symbols_list` / `.def` —— 一句中立的话三种渲染,与 `[runtime]` 已确立的形状
+相同,而不是让作者写三份平台专用文件。
+
+**它不隐含编译期 hidden。** 三种格式上收窄都是链接期属性,所以一个键只有一个效果;
+`-fvisibility=hidden` 仍可经 `[build] cxxflags` 取得代码生成收益,而那是单独的决定,
+因为它同时改变本库各 TU 之间如何看见彼此。符号**版本化**(`foo@@LIB_1.0`)不在此列,
+它是 ELF 独有、无法中立表达的能力。
+
+判据 e2e 621 把同一份源码构建两次并要求两次读数**不同**:只断言公开符号在,会对"导出
+全部"同样成立(那正是本特性之前的状态);只断言内部符号不在,分不开"正确地隐藏了"与
+"根本没链上"。
+
+
 ### 构建程序能发出它算出来的链接标志:`mcpp:link-flag`
 
 `link-lib`、`link-search`、`link-script` 各自命名一类东西,于是一条**算出来的**标志无处

docs/05-mcpp-toml.md

@@ -145,6 +145,48 @@ the loader opens and the import library the linker consumes, with the export
 list generated from the objects on the MSVC ABI (which exports nothing without
 `__declspec(dllexport)` or a `.def`). See `tests/e2e/08`, `257` and `259`.
 
+#### `exports` — which symbols the artifact publishes (mcpp 2026.9.6.5+)
+
+```toml
+[targets.mydriver]
+kind    = "shared"
+soname  = "libmydriver.so.1"
+exports = "abi/mydriver.exports"     # or inline: exports = ["vk_icd*"]
+```
+
+**Omitting the key publishes everything, which is what both platforms already
+do** — ELF gives symbols default visibility, and PE gets an auto-generated
+`.def` listing every symbol. `exports` narrows that.
+
+Two projects need the narrowing. A **runtime with a stable ABI** publishes a
+reviewed set and nothing else, so that what is not in the set stays free to
+change. A **plugin loaded beside its rivals** must not collide: a Vulkan ICD is
+found by name for `vk_icdGetInstanceProcAddr`, and one that also exports its
+internals collides with the loader and with the other ICDs in the process.
+
+The file lists one symbol pattern per line, `#` starts a comment, and `*` is the
+only wildcard. The inline array says the same thing and is for the two or three
+entry points where a separate file would be ceremony.
+
+One statement, three renderings:
+
+| Platform | Rendered as |
+|---|---|
+| ELF | a version script, `-Wl,--version-script=` |
+| Mach-O | `-Wl,-exported_symbols_list` (the leading underscore is added for you) |
+| PE | the `.def`, replacing the auto-generated all-exports one |
+
+**It does not change compile-time visibility, and that is deliberate.** The
+narrowing is a link-time property on all three formats, so one key has one
+effect. `-fvisibility=hidden` remains available through `[build] cxxflags` for
+the code-generation benefit it brings, and it is a separate decision because it
+also changes how this library's own translation units see each other.
+
+**Symbol versioning is not this key.** `foo@@LIB_1.0` alongside `foo@LIB_0.9`
+is an ELF-only capability that cannot be stated neutrally; a package that needs
+it writes the version script itself and passes it through `[build] ldflags`, or
+computes it and emits `mcpp:link-flag=` (docs/07).
+
 A `soname` is meaningful on `kind = "lib"` too — see
 [`dependency_linkage`](#dependency_linkage--static-or-shared-is-the-consumers-decision)
 below, where the form a library takes becomes the consumer's decision.

docs/zh/05-mcpp-toml.md

@@ -138,6 +138,42 @@ soname = "libmylib.so.1"  # 可选: Linux/ELF ABI 名称,运行时会生成同
 MSVC ABI 上从对象生成导出表(该 ABI 没有 `__declspec(dllexport)` 或 `.def` 时
 不导出任何符号)。参见 `tests/e2e/08`、`257`、`259`。
 
+#### `exports` —— 产物发布哪些符号(mcpp 2026.9.6.5+)
+
+```toml
+[targets.mydriver]
+kind    = "shared"
+soname  = "libmydriver.so.1"
+exports = "abi/mydriver.exports"     # 或内联:exports = ["vk_icd*"]
+```
+
+**不写这个键就发布全部,而那正是两个平台今天的默认**——ELF 给符号默认可见性,PE 会
+自动生成列出全部符号的 `.def`。`exports` 把它收窄。
+
+两类工程需要收窄。**有稳定 ABI 的运行时**只发布一份经过评审的集合,不在集合里的东西
+才保持可改。**与同类并存的插件**不能撞名:Vulkan loader 按名字找
+`vk_icdGetInstanceProcAddr`,一个把内部符号也导出的 ICD 会与 loader 以及同进程内另一个
+ICD 相撞。
+
+文件一行一条符号模式,`#` 起注释,`*` 是唯一的通配符。内联数组说的是同一件事,用于
+只有两三个入口、单开一个文件反而是仪式的场合。
+
+一句话,三种渲染:
+
+| 平台 | 渲染为 |
+|---|---|
+| ELF | version script,`-Wl,--version-script=` |
+| Mach-O | `-Wl,-exported_symbols_list`(前导下划线由引擎补) |
+| PE | `.def`,取代自动生成的全导出版本 |
+
+**它不改变编译期可见性,这是有意的。** 三种格式上收窄都是链接期属性,所以一个键只有
+一个效果。`-fvisibility=hidden` 仍可经 `[build] cxxflags` 使用以取得代码生成上的收益,
+而它是一个**单独**的决定,因为它同时改变本库各翻译单元之间如何看见彼此。
+
+**符号版本化不是这个键。** `foo@@LIB_1.0` 与 `foo@LIB_0.9` 并存是 ELF 独有的能力,
+无法中立表达;需要它的包自己写 version script 经 `[build] ldflags` 传入,或者算出来后
+用 `mcpp:link-flag=` 发出(docs/07)。
+
 `soname` 对 `kind = "lib"` 同样有意义 —— 见下文的 `dependency_linkage`,
 库以何种形态出现是**消费者**的决定。
 

modules/manifest/src/toml.cppm

@@ -1042,6 +1042,65 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
         if (auto msg = validate_target_soname(t, std::format("targets.{}.", tname))) {
             return std::unexpected(error(origin, *msg));
         }
+        // `exports` -- a file of symbol patterns, or the patterns inline.
+        //
+        // BOTH FORMS, because the two are used at different scales and the ABI
+        // contract of a real library is reviewed as a unit. A file is what a
+        // library with a stable ABI wants (it is the contract, and it belongs
+        // in review beside the headers); the inline array is for the two or
+        // three entry points a plugin publishes, where a separate file would
+        // be ceremony.
+        if (auto eit = tt.find("exports"); eit != tt.end()) {
+            if (eit->second.is_string()) {
+                t.exportsFile = eit->second.as_string();
+                // READ IT HERE, so every later stage sees one representation.
+                // The alternative -- carrying the path and reading it at plan
+                // time -- would need the package root at three call sites (the
+                // root, a path dependency, a store dependency) and is the
+                // "same decision derived in N places" shape this repository
+                // has paid for. `origin` is the manifest's own path, so the
+                // root is its parent, and that is true for all three.
+                auto file = origin.parent_path() / t.exportsFile;
+                std::ifstream in(file);
+                if (!in)
+                    return std::unexpected(error(origin, std::format(
+                        "targets.{}.exports names '{}', which does not exist "
+                        "(looked at '{}')", tname, t.exportsFile,
+                        file.generic_string())));
+                for (std::string line; std::getline(in, line); ) {
+                    if (auto h = line.find('#'); h != std::string::npos)
+                        line.erase(h);
+                    auto b = line.find_first_not_of(" \t\r");
+                    if (b == std::string::npos) continue;
+                    auto e = line.find_last_not_of(" \t\r");
+                    t.exportPatterns.push_back(line.substr(b, e - b + 1));
+                }
+                if (t.exportPatterns.empty())
+                    return std::unexpected(error(origin, std::format(
+                        "targets.{}.exports: '{}' names no symbol. An empty "
+                        "export list is not how a library says 'publish "
+                        "everything' -- omitting the key is.",
+                        tname, t.exportsFile)));
+            } else if (eit->second.is_array()) {
+                for (auto& v : eit->second.as_array()) {
+                    if (!v.is_string())
+                        return std::unexpected(error(origin, std::format(
+                            "targets.{}.exports: every entry must be a symbol "
+                            "pattern (a string)", tname)));
+                    t.exportPatterns.push_back(v.as_string());
+                }
+                if (t.exportPatterns.empty())
+                    return std::unexpected(error(origin, std::format(
+                        "targets.{}.exports is an empty list. A library that "
+                        "publishes nothing is not what an empty list means "
+                        "here -- omit the key to publish everything, which is "
+                        "the default, or name the symbols.", tname)));
+            } else {
+                return std::unexpected(error(origin, std::format(
+                    "targets.{}.exports must be a path to a file of symbol "
+                    "patterns, or an inline list of them", tname)));
+            }
+        }
 
         // Per-target flags (entry-scoped) + required-features gate.
         auto read_list = [&](const char* key, std::vector<std::string>& out) {
@@ -1069,7 +1128,7 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
         // must reach SHARED code is intentionally not a target key; point users
         // at the right axis (workspace / features / profile).
         static constexpr std::string_view kKnownTargetKeys[] = {
-            "kind", "main", "soname",
+            "kind", "main", "soname", "exports",
             "cflags", "cxxflags", "defines", "required_features",
         };
         for (auto& [key, _] : tt) {

modules/manifest/src/types.cppm

@@ -117,6 +117,22 @@ struct Target {
     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
+    // WHICH SYMBOLS THIS ARTIFACT PUBLISHES. Empty = every symbol, which is
+    // what both platforms do today (ELF default visibility; PE gets an
+    // auto-generated .def listing everything, mcpp.build.coff_exports).
+    //
+    // ONE NEUTRAL STATEMENT, THREE RENDERINGS -- the shape `[runtime]` already
+    // established, and the reason this is a manifest key rather than three
+    // platform-specific flag lists. ELF gets a version script, Mach-O an
+    // `-exported_symbols_list`, PE a `.def` that REPLACES the all-exports one.
+    //
+    // The entries are symbol patterns, one per line in the named file or one
+    // per element inline. `*` is the only wildcard, because it is the only one
+    // all three renderings share.
+    std::vector<std::string>    exportPatterns;
+    // Where they came from, for diagnostics and for the re-read that a changed
+    // file must trigger. Empty when `exports` was written inline.
+    std::string                 exportsFile;
     // Per-target compile flags. SCOPE: applied ONLY to this target's exclusive
     // entry source (its `main`) — never to shared module/impl objects, which are
     // compiled once and linked into every target (the build's compile-once model;

src/build/ninja_backend.cppm

@@ -272,6 +272,55 @@ std::string shared_soname_flag(const LinkUnit& lu, const BuildPlan& plan) {
     return lu.soname.empty() ? "" : "-Wl,-soname," + lu.soname;
 }
 
+// WHICH SYMBOLS A SHARED LIBRARY PUBLISHES, rendered per platform from one
+// neutral list.
+//
+// The default on both platforms is "everything": ELF gives symbols default
+// visibility, and PE gets an auto-generated .def listing every symbol
+// (mcpp.build.coff_exports, CMake's WINDOWS_EXPORT_ALL_SYMBOLS semantics).
+// Declaring `exports` narrows that, which is what a runtime with a stable ABI
+// and a plugin loaded beside its rivals both need -- an ICD that exports its
+// internals collides with the loader and with the other ICDs in the process.
+//
+// THREE RENDERINGS OF ONE STATEMENT, and that is the reason this is a manifest
+// key rather than three flag lists in three `[target.<os>]` blocks. It is the
+// same shape `[runtime]` already established for link intent.
+//
+// The file is written into the build directory rather than read from the
+// package, because the inline form has no file to read and because a version
+// script's syntax is not what the author wrote.
+std::string exports_file_contents(const LinkUnit& lu, std::string_view os) {
+    std::string out;
+    if (os == "macos") {
+        // One symbol per line. Mach-O symbols carry a leading underscore that
+        // the C++ source never writes, so it is added here -- the author names
+        // the symbol, not the object format's spelling of it.
+        for (auto const& p : lu.exportPatterns) out += "_" + p + "\n";
+        return out;
+    }
+    // ELF version script. One anonymous version node: naming versions is a
+    // separate capability (symbol VERSIONING, `foo@@LIB_1.0`) that cannot be
+    // stated neutrally, and a package needing it writes the map itself and
+    // passes it with `[build] ldflags`.
+    out = "{\n  global:\n";
+    for (auto const& p : lu.exportPatterns) out += "    " + p + ";\n";
+    out += "  local:\n    *;\n};\n";
+    return out;
+}
+
+// The flag that names the file. PE is absent on purpose: there the export set
+// is the `.def`, which lu.defFile already declares and the def-generating step
+// already writes, so narrowing it is that step's business rather than a second
+// flag on the link line.
+std::string exports_flag(const LinkUnit& lu, std::string_view os,
+                         const std::filesystem::path& file) {
+    if (lu.kind != LinkUnit::SharedLibrary || lu.exportPatterns.empty()) return "";
+    if (os == "windows") return "";
+    if (os == "macos")
+        return "-Wl,-exported_symbols_list," + file.generic_string();
+    return "-Wl,--version-script=" + file.generic_string();
+}
+
 // Write only when the bytes would actually change.
 //
 // One of these files is a BUILD INPUT: `obj/mcpp_ios_init.c`, the generated
@@ -2081,6 +2130,31 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             implicit.empty() ? std::string{} : " |" + implicit);
         if (auto flag = shared_soname_flag(lu, plan); !flag.empty())
             out_line += "  soname_flag = " + flag + "\n";
+        // The export set, written beside the artifact and named on the link.
+        //
+        // Folded into `soname_flag` rather than given a rule variable of its
+        // own: both are "a property of THIS shared library's link", the rule
+        // already interpolates that variable in the right place, and a second
+        // one would have to be added to every link rule that mentions the
+        // first -- the "same decision in N places" shape this repository keeps
+        // paying for.
+        if (lu.kind == LinkUnit::SharedLibrary && !lu.exportPatterns.empty()) {
+            const auto tr = mcpp::toolchain::triple::parse(plan.toolchain.targetTriple);
+            const std::string os = tr ? tr->os
+                : (mcpp::platform::is_macos   ? "macos"
+                 : mcpp::platform::is_windows ? "windows" : "linux");
+            const auto file = plan.outputDir / "obj"
+                            / (lu.targetName + ".exports.gen");
+            std::error_code mkec;
+            std::filesystem::create_directories(file.parent_path(), mkec);
+            write_file(file, exports_file_contents(lu, os));
+            if (auto ef = exports_flag(lu, os, file); !ef.empty()) {
+                if (out_line.find("  soname_flag = ") == std::string::npos)
+                    out_line += "  soname_flag = " + ef + "\n";
+                else
+                    out_line.insert(out_line.rfind('\n'), " " + ef);
+            }
+        }
         // Where the linker is told to write it. A rule-level `$out.lib` would
         // spell the msvc case `foo.dll.lib`, i.e. a name nothing else in mcpp
         // agrees with — the name belongs to plan.cppm's import_library_for, and

src/build/plan.cppm

@@ -94,6 +94,11 @@ struct LinkUnit {
     // wins, so the emitter puts this after every other linker argument.
     // Deciding it stays here; placing it is the emitter's business.
     std::string                     loaderTagFlag;
+    // The symbol patterns this unit publishes, empty when it publishes all.
+    // Carried as the neutral list rather than a rendered flag: the file to
+    // write and the flag that names it are both platform-shaped, and the
+    // backend is where the target OS is known.
+    std::vector<std::string>        exportPatterns;
     std::filesystem::path           output;            // relative to plan.outputDir
     // The import library a PE shared library also produces — empty on ELF and
     // Mach-O, and empty for every non-shared unit. It is a SECOND output of the
@@ -1675,6 +1680,7 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
         if (msvcTarget && !lu.importLibrary.empty())
             lu.defFile = std::filesystem::path("bin") / (dep.target.name + ".def");
         lu.soname     = dep.target.soname;
+        lu.exportPatterns = dep.target.exportPatterns;
         lu.runtimeAliases = runtime_aliases_for_target(dep.target, naming);
         lu.loaderTagFlag = loader_tag_flag(lu.kind);
         append_package_objects(lu, dep.packageName);
@@ -1707,6 +1713,7 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
             if (msvcTarget && !lu.importLibrary.empty())
                 lu.defFile = std::filesystem::path("bin") / (t.name + ".def");
             lu.soname = t.soname;
+            lu.exportPatterns = t.exportPatterns;
             lu.runtimeAliases = runtime_aliases_for_target(t, naming);
         } else if (t.kind == mcpp::manifest::Target::TestBinary) {
             lu.kind   = LinkUnit::TestBinary;