2026.9.27.1: a build.mcpp can declare a runtime library search directory, joining [runtime] library_dirs

`mcpp::runtime_library_dir(dir)` (`mcpp:runtime-library-dir=`, protocol 12)
is the build-program form of `[runtime] library_dirs`: a launch-time search
directory for a dependency a build.mcpp discovers (a vcpkg prefix's `bin/`,
a Qt SDK's `bin/`) rather than one an author can write into a fixed TOML
array.

It joins the SAME field the manifest key populates
(`RuntimeConfig::libraryDirs`), so every existing consumer of that field
sees a directive-declared entry without any of them changing: `mcpp run`'s
loader path, `mcpp pack`'s closure search, and the ELF/Mach-O
`-Wl,-rpath` rendering. Persisted like `deploy`/`warning`/`pack-format`
(non-empty cache tag, `kCacheEpoch` not bumped, same reasoning), and the
root package's own build.mcpp needed the same manifest-snapshot mirror
`deploy` already has in prepare.cppm, or `resolve_runtime_contract` never
sees a directive-sourced entry.

Adds unit coverage in test_build_directives.cpp and an e2e script
(779) that links an executable against a prebuilt shared library only the
directive's RUNPATH makes loadable, checks the build.mcpp cache-hit replay,
and checks `mcpp pack --format dir`'s closure staging.

Docs: docs/30-build-mcpp.md and docs/zh/30-build-mcpp.md gain the directive,
the typed API entry and a worked section; docs/04-mcpp-toml.md and its zh
counterpart point `[runtime] library_dirs` at the build-program form.

Author: speak-agent

docs/04-mcpp-toml.md

@@ -1473,6 +1473,11 @@ For one compatibility train, `library_dirs` maps only to runtime search,
 `capabilities` maps to required run-phase capability requirements. None of
 these legacy fields creates a provider.
 
+`library_dirs` has a build-program form for a directory only a build.mcpp can
+locate (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`): `mcpp::runtime_library_dir(dir)`
+(2026.9.27.1+, protocol 12; [30 — Build Programs](30-build-mcpp.md)), which
+joins this same field.
+
 `target/<triple>/<fp>/resolution.json` schema 2 stores the RuntimeBinding,
 canonical requirements/providers/artifacts, LinkIntent, platform search
 mechanism, and post-link verdict. `mcpp why runtime` is a pure interpreter of

docs/30-build-mcpp.md

@@ -67,6 +67,7 @@ is ignored, so diagnostics may be logged freely.
 | `mcpp:windows-subsystem=<target>:<value>` *(2026.9.12.2+)* | set the PE subsystem (`console` or `windows`) of the executable `<target>` of **this** package, the same field as `[targets.<target>] windows_subsystem` (docs/04). Reaches that target's link and no other, never a consumer, and renders nothing on a target that is not PE. A target the package does not declare with `kind = "bin"`, a value outside the set, and a value that contradicts mcpp.toml are each refused before any directive is applied |
 | `mcpp:windows-entry=<target>:<value>` *(2026.9.12.2+)* | set the entry function (`main`, `wmain`, `WinMain` or `wWinMain`) of the executable `<target>`, the same field as `windows_entry`; the scope and the refusals are those of `windows-subsystem` |
 | `mcpp:deploy=<from>\t<to>` *(2026.9.12.3+, protocol 11)* | place a file this program produced or selected beside the artifact, at `<to>`, relative to the executable's directory — the build-program form of `[runtime] deploy` (docs/04 §2.11). `<from>` may be absolute (an action's own declared output) or resolved against the package root; TAB-separated, because an absolute Windows `<from>` contains a colon. **Reaches the consumer**, joining the same `LinkIntent` `link-lib`/`link-search`/`link-flag` feed — see below |
+| `mcpp:runtime-library-dir=<dir>` *(2026.9.27.1+, protocol 12)* | add `<dir>` to the launch-time search path — the build-program form of `[runtime] library_dirs` (docs/04 §2.11). Relative resolves against the package root. **Reaches the consumer**, joining the same `LinkIntent` field the manifest key populates: RUNPATH/rpath on ELF and Mach-O, never `-L`, and `mcpp pack`'s closure search — see below |
 | `mcpp:link-script=<path>` *(2026.8.19+)* | link with this **linker script** (`-T`; relative resolves against the package root, and the emitted path is absolute because the link runs in the build directory). Reaches the **consumer**, unlike `include-dir` — a board's memory layout is the one thing a consumer cannot write for itself |
 | `mcpp:warning=<text>` *(2026.8.21.2+)* | say something to the user and **keep going**. The one directive that changes no compile line, no link line and no source set. Survives the build cache — see below |
 | `mcpp:fact=<name>=<version>` *(2026.9.5.2+)* | state something the program **established about the machine** (`cuda.driver=12.4`). Compared against floors before anything is compiled; see below |
@@ -134,6 +135,7 @@ int main() {
 | `mcpp::link_flag(s)` *(2026.9.6.5+)* | `mcpp:link-flag=` |
 | `mcpp::windows_subsystem(target, value)` / `mcpp::windows_entry(target, value)` *(2026.9.12.2+)* | `mcpp:windows-subsystem=` / `mcpp:windows-entry=` |
 | `mcpp::deploy(from, to)` *(2026.9.12.3+, protocol 11)* | `mcpp:deploy=<from>\t<to>` — see below |
+| `mcpp::runtime_library_dir(dir)` *(2026.9.27.1+, protocol 12)* | `mcpp:runtime-library-dir=<dir>` — see below |
 | `mcpp::link_script(p)` *(2026.8.19+)* | `mcpp:link-script=` |
 | `mcpp::runner(tok)` *(2026.8.19.2+)* | `mcpp:runner=` — see below |
 | `mcpp::xpkg_dir(ns, name)` / `mcpp::xpkg_dir(name)` *(2026.8.19+)* | the payload directory of a package declared in `[xlings.workspace]` — by this manifest, or by a dependency compiled into this build program *(2026.9.6.6+)*; `""` when it was not declared or is not installed (see below) |
@@ -656,6 +658,38 @@ int main() {
   | `.apk` | `assets/myapp.resources/` |
   | web | the same relative path in the static directory, served beside `<name>.js`. A project that wants the files inside the `.data` preload instead links with `--preload-file <dir>@/<to>`, an ordinary link flag |
 
+### A launch-time search directory: `runtime_library_dir` (2026.9.27.1+, protocol 12)
+
+`[runtime] library_dirs` (docs/04 §2.11) names a directory to search when the
+artifact runs. It is a fixed TOML array, so it cannot name a directory a
+build.mcpp only discovers — a vcpkg prefix's `bin/`, a Qt SDK's `bin/`, or any
+other prebuilt-dependency layout a build-time probe locates. `mcpp::runtime_library_dir`
+is that same declaration, reached from a build program:
+
+```cpp
+import mcpp;
+#include <string>
+
+int main() {
+    const std::string qtBin = locate_qt_prefix() + "/bin";   // however this
+                                                              // package finds it
+    mcpp::link_search(qtBin.c_str());
+    mcpp::runtime_library_dir(qtBin.c_str());
+}
+```
+
+- **Joins the same field the manifest key populates.** A directive-declared
+  directory reaches every consumer of `[runtime] library_dirs` exactly as one
+  written in `mcpp.toml` would: `mcpp run`'s loader path, `mcpp pack`'s closure
+  search, and RUNPATH/rpath on ELF and Mach-O (never `-L` — a launch-time
+  search directory is not a link-library search path).
+- **`dir` may be absolute or package-relative.** A relative value resolves
+  against the package root, like every other `AbsPath` directive
+  (`include-dir`, `deploy`'s `from`).
+- **Replayed on a cache hit.** A `runtime-library-dir` directive is persisted
+  in the build cache like `deploy` and `warning`; a cached run restores it
+  exactly as a fresh run would.
+
 ### Producing a distributable: `pack_format` / `stage_dir` (2026.9.11.1+)
 
 An `.msi`, a `.deb`, an AppImage and a signed `.app` are none of the four roles'

docs/zh/04-mcpp-toml.md

@@ -1405,6 +1405,11 @@ Link intent 把各个发现阶段分开处理：
 映射到必需的运行期 soname 要求，`capabilities` 映射到必需的运行期
 能力要求。这些遗留字段都不创建提供者。
 
+`library_dirs` 有一个构建程序形态，用于一个只有 build.mcpp 才能定位的目录
+（一个 vcpkg 前缀的 `bin/`、一个 Qt SDK 的 `bin/`）：`mcpp::runtime_library_dir(dir)`
+（2026.9.27.1+，protocol 12；[30 —— 构建程序](30-build-mcpp.md)），并入的是
+同一个字段。
+
 `target/<triple>/<fp>/resolution.json` schema 2 存储 RuntimeBinding、
 规范化后的要求/提供者/产物、LinkIntent、平台发现机制与链接后判定。
 `mcpp why runtime` 是对最新存储文件的一个纯粹解读器：它既不会重新

docs/zh/30-build-mcpp.md

@@ -64,6 +64,7 @@ mcpp build      # compiles + runs build.mcpp, then builds the project
 | `mcpp:windows-subsystem=<target>:<value>` *(2026.9.12.2+)* | 设置**本包**可执行目标 `<target>` 的 PE 子系统（`console` 或 `windows`），与 `[targets.<target>] windows_subsystem`（docs/04）是同一字段。只到达该目标的链接，不到达其他目标或消费者，在非 PE 目标上不产生任何标志。本包未以 `kind = "bin"` 声明该目标、取值不在集合内、取值与 mcpp.toml 的声明矛盾，这三种情形都在应用任何指令之前被拒绝 |
 | `mcpp:windows-entry=<target>:<value>` *(2026.9.12.2+)* | 设置可执行目标 `<target>` 的入口函数（`main`、`wmain`、`WinMain` 或 `wWinMain`），与 `windows_entry` 是同一字段；作用域与拒绝条件同 `windows-subsystem` |
 | `mcpp:deploy=<from>\t<to>` *(2026.9.12.3+,protocol 11)* | 把本程序生成或选中的一个文件放到产物旁边的 `<to>`（相对可执行文件所在目录）——`[runtime] deploy`（docs/04 §2.11）的构建程序形态。`<from>` 可以是绝对路径（某个 action 自己声明的输出），也可以按包根解析；用 TAB 分隔，因为一个绝对的 Windows `<from>` 本身含冒号。**到达消费者**，并入同一个被 `link-lib`/`link-search`/`link-flag` 喂入的 `LinkIntent`——见下 |
+| `mcpp:runtime-library-dir=<dir>` *(2026.9.27.1+,protocol 12)* | 把 `<dir>` 加入启动期搜索路径——`[runtime] library_dirs`（docs/04 §2.11）的构建程序形态。相对路径按包根解析。**到达消费者**，并入清单键所填的同一个 `LinkIntent` 字段：在 ELF 与 Mach-O 上是 RUNPATH/rpath，绝不是 `-L`，并进入 `mcpp pack` 的闭包搜索——见下 |
 | `mcpp:link-script=<path>` *(2026.8.19+)* | 用这个**链接脚本**链接（`-T`；相对路径按包根解析，发出的是绝对路径，因为链接是在构建目录里跑的）。与 `include-dir` 不同，它**到达消费者** —— 板子的内存布局恰恰是消费者写不出来的那一项 |
 | `mcpp:warning=<text>` *(2026.8.21.2+)* | 对用户说一句话并**继续**。唯一一条不改变编译行、链接行与源码集的指令。它**穿过构建缓存** —— 见下 |
 | `mcpp:fact=<name>=<version>` *(2026.9.5.2+)* | 陈述程序**测得的机器事实**(`cuda.driver=12.4`)。在编译任何东西之前与 floor 比较；见下 |
@@ -123,6 +124,7 @@ int main() {
 | `mcpp::link_flag(s)` *(2026.9.6.5+)* | `mcpp:link-flag=` |
 | `mcpp::windows_subsystem(target, value)` / `mcpp::windows_entry(target, value)` *(2026.9.12.2+)* | `mcpp:windows-subsystem=` / `mcpp:windows-entry=` |
 | `mcpp::deploy(from, to)` *(2026.9.12.3+,protocol 11)* | `mcpp:deploy=<from>\t<to>` —— 见下 |
+| `mcpp::runtime_library_dir(dir)` *(2026.9.27.1+,protocol 12)* | `mcpp:runtime-library-dir=<dir>` —— 见下 |
 | `mcpp::link_script(p)` *(2026.8.19+)* | `mcpp:link-script=` |
 | `mcpp::runner(tok)` *(2026.8.19.2+)* | `mcpp:runner=` —— 见下 |
 | `mcpp::xpkg_dir(ns, name)` / `mcpp::xpkg_dir(name)` *(2026.8.19+)* | `[xlings.workspace]` 里声明的包的载荷目录 —— 本 manifest 声明的，或编进本构建程序的某个依赖声明的（2026.9.6.6+）；没声明或没安装时返回 `""`（见下） |
@@ -559,6 +561,35 @@ int main() {
   | `.apk` | `assets/myapp.resources/` |
   | web | 静态目录里同一个相对路径，与 `<name>.js` 放在一起。想把文件放进 `.data` 预加载的项目改用链接标志 `--preload-file <dir>@/<to>`，那是一条普通的链接标志 |
 
+### 一个启动期搜索目录：`runtime_library_dir`（2026.9.27.1+,protocol 12）
+
+`[runtime] library_dirs`（docs/04 §2.11）声明产物运行时要搜索的一个目录。
+它是一个固定的 TOML 数组，因此点不了一个只有 build.mcpp 才能发现的目录——
+一个 vcpkg 前缀的 `bin/`、一个 Qt SDK 的 `bin/`，或任何其它由构建期探测
+才能定位的预编译依赖布局。`mcpp::runtime_library_dir` 就是同一次声明，从
+构建程序里发出：
+
+```cpp
+import mcpp;
+#include <string>
+
+int main() {
+    const std::string qtBin = locate_qt_prefix() + "/bin";   // 本包自己
+                                                              // 怎么找到它
+    mcpp::link_search(qtBin.c_str());
+    mcpp::runtime_library_dir(qtBin.c_str());
+}
+```
+
+- **并入清单键所填的同一个字段。** 一个由指令声明的目录，到达
+  `[runtime] library_dirs` 的每一个消费者，与写在 `mcpp.toml` 里的完全一样：
+  `mcpp run` 的加载器路径、`mcpp pack` 的闭包搜索，以及 ELF 与 Mach-O 上的
+  RUNPATH/rpath（绝不是 `-L`——一个启动期搜索目录不是一个链接库搜索路径）。
+- **`dir` 可以是绝对路径或按包根解析的相对路径。** 相对路径按包根解析，
+  与其它每一个 `AbsPath` 指令（`include-dir`、`deploy` 的 `from`）一样。
+- **在缓存命中时被重放。** `runtime-library-dir` 指令与 `deploy`、`warning`
+  一样进入构建缓存；一次缓存命中的重跑会像真正跑过一样把它恢复回来。
+
 ### 产出可分发物：`pack_format` 与 `stage_dir`（2026.9.11.1+）
 
 一个 `.msi`、一个 `.deb`、一个 AppImage、一个签过名的 `.app`，都不是那四个 role 的

mcpp.toml

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

modules/buildmcpp/src/directives.cppm

@@ -164,6 +164,18 @@ enum class Slot : std::size_t {
     // splitting it into two slots would let a build with N deploy directives
     // pair them up wrong the moment N > 1.
     Deploy,
+    // A LAUNCH-TIME SEARCH DIRECTORY, THE BUILD-PROGRAM FORM OF `[runtime]
+    // library_dirs` (docs/04 §2.11). A dependency that brings a prebuilt
+    // shared library (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`) knows where
+    // it lives only at build-program time, and the manifest key cannot be
+    // computed -- it is a fixed TOML array. `Transform::AbsPath`, not a new
+    // path shape: this is the SAME field the manifest key feeds
+    // (`RuntimeConfig::libraryDirs`), so every consumer of it -- `mcpp run`'s
+    // loader path, `mcpp pack`'s closure search, and the ELF/Mach-O
+    // `-Wl,-rpath` rendering -- sees a directive-declared entry exactly as it
+    // sees a TOML one, through the one merge in `plan.cppm` that already
+    // exists for the manifest key. No new downstream code path.
+    RuntimeLibraryDir,
     Count
 };
 inline constexpr std::size_t kSlotCount = static_cast<std::size_t>(Slot::Count);
@@ -262,7 +274,7 @@ struct Def {
     int              sinceProtocol;
 };
 
-inline constexpr std::array<Def, 26> kTable{{
+inline constexpr std::array<Def, 27> kTable{{
     //  wire                    tag                  slot                    scope                  transform                must   missingPrefix                 missingSuffix                                    since
     {"cxxflag",             "cxxflag",           Slot::CxxFlags,         Scope::PackagePrivate, Transform::Verbatim,      false, "",                           "",                                              1},
     {"cflag",               "cflag",             Slot::CFlags,           Scope::PackagePrivate, Transform::Verbatim,      false, "",                           "",                                              1},
@@ -413,6 +425,29 @@ inline constexpr std::array<Def, 26> kTable{{
     // before `apply` on both the run path and the cache-hit path, so a cached
     // replay refuses exactly what a fresh run would.
     {"deploy",              "deploy",            Slot::Deploy,           Scope::LinkGlobal,     Transform::Deploy,        false, "",                           "",                                              11},
+    // v12. The build-program form of `[runtime] library_dirs` (docs/04
+    // §2.11): a launch-time search directory, for a dependency (a vcpkg
+    // prefix's `bin/`, a Qt SDK's `bin/`) whose location a build.mcpp learns
+    // rather than one an author can write into TOML. Scope::LinkGlobal,
+    // exactly as `deploy` above, because `apply` folds it into
+    // `RuntimeConfig::libraryDirs` -- the SAME field the manifest key
+    // populates -- so `resolve_runtime_contract`'s per-package merge
+    // (plan.cppm) carries it into a consumer's `linkIntent.runtimeSearchDirs`
+    // through the one path that already exists for the manifest key, rather
+    // than a second one this table would have to keep in sync. `mustExistAfterRun`
+    // is FALSE: a directory is not the declared-output contract's shape
+    // (`generated=`/`source=` name a file), and the directory need not even
+    // exist yet -- a payload not installed on this machine is the manifest
+    // key's own behaviour (`xpkg_dir()` returning empty configures no runner,
+    // silently and correctly).
+    //
+    // kCacheEpoch is NOT bumped, the same reasoning `warning`/`pack-format`
+    // state explicitly: an entry written before this row carries no
+    // `d runtime-library-dir` line, and the program that wrote it could not
+    // emit one -- so replaying it yields exactly what that program said, and
+    // the entry is still correct. An older engine reading a newer entry
+    // already discards the whole record through the unknown-tag path.
+    {"runtime-library-dir", "runtime-library-dir", Slot::RuntimeLibraryDir, Scope::LinkGlobal, Transform::AbsPath,       false, "",                           "",                                              12},
 }};
 
 // ── Collected output of one run ────────────────────────────────────────────
@@ -945,6 +980,14 @@ void apply(mcpp::manifest::Manifest& m, const Directives& d) {
     for (auto const& p : d.at(Slot::IncludeDirsAfter))
         bc.includeDirsAfter.emplace_back(p);
 
+    // `runtime-library-dir`: already absolute from the AbsPath
+    // transform, like IncludeDirs above. Joins `RuntimeConfig::libraryDirs`,
+    // the exact field `[runtime] library_dirs` populates from TOML -- so a
+    // consumer sees it exactly as it sees the manifest key, folded in by the
+    // SAME merge (plan.cppm's `resolve_runtime_contract`), never a second one.
+    for (auto const& p : d.at(Slot::RuntimeLibraryDir))
+        m.runtimeConfig.libraryDirs.emplace_back(p);
+
     // Claims join the runtime declarations the manifest could have carried
     // itself, so the version-floor check in prepare reads ONE list and never
     // learns which spelling a claim arrived in.

modules/buildmcpp/src/program_protocol.cppm

@@ -81,7 +81,14 @@ export namespace mcpp::build::program_protocol {
 // at a path relative to the executable. Same cost as v5's: a package calling
 // `mcpp::deploy()` fails on an older engine at the build.mcpp COMPILE, because
 // that engine's bundled module has no such function.
-inline constexpr int kProtocolVersion = 11;
+// v12: adds `runtime-library-dir` -- the build-program form of `[runtime]
+// library_dirs`: a launch-time search directory for a dependency (a vcpkg
+// prefix's `bin/`, a Qt SDK's `bin/`) whose location a build.mcpp learns
+// rather than one an author can write into TOML. Same cost as v5's: a
+// package calling `mcpp::runtime_library_dir()` fails on an older engine at
+// the build.mcpp COMPILE, because that engine's bundled module has no such
+// function.
+inline constexpr int kProtocolVersion = 12;
 
 // ── Cache-format epoch ─────────────────────────────────────────────────────
 //

modules/versioning/src/version.cppm

@@ -31,6 +31,6 @@ import std;
 
 export namespace mcpp {
 
-inline constexpr std::string_view MCPP_VERSION = "2026.9.26.1";
+inline constexpr std::string_view MCPP_VERSION = "2026.9.27.1";
 
 } // namespace mcpp

src/build/hostprogram.cppm

@@ -183,6 +183,17 @@ inline void windows_entry(const char* target, const char* value) {
 inline void deploy(const char* from, const char* to) {
     std::printf("mcpp:deploy=%s\t%s\n", from, to);
 }
+// The build-program form of `[runtime] library_dirs` (docs/04 §2.11): a
+// directory to search at LAUNCH time, for a dependency (a vcpkg prefix's
+// `bin/`, a Qt SDK's `bin/`) whose location this program learns rather than
+// one an author can write into `mcpp.toml`. Reaches the consumer, joining the
+// same `LinkIntent` `link_lib`/`link_search`/`deploy` feed, and gets the same
+// treatment the manifest key does: RUNPATH/rpath on ELF and Mach-O, never
+// `-L`, and `mcpp pack`'s closure search. Relative paths resolve against this
+// package's root, like every other AbsPath directive.
+inline void runtime_library_dir(const char* dir) {
+    std::printf("mcpp:runtime-library-dir=%s\n", dir);
+}
 // ── Build-graph nodes (mcpp 2026.8.5.1+) ────────────────────────────────
 // Declare WORK instead of doing it. A build program is a good place to decide
 // what the build looks like and a bad place to perform it: work done here is