docs(07/17): 依赖的 [xlings] 声明会被采纳,且 xpkg_dir 现在回答范围 —— 两处陈述已过期

Author: speak-agent

docs/07-build-mcpp.md

@@ -121,7 +121,7 @@ int main() {
 | `mcpp::link_flag(s)` *(2026.9.6.5+)* | `mcpp:link-flag=` |
 | `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 this manifest declared in `[xlings.workspace]`; `""` when it was not declared or is not installed (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) |
 | `mcpp::warning(text)` *(2026.8.21.2+)* | `mcpp:warning=` — see below |
 | `mcpp::action{…}.submit()` *(2026.8.5.1+)* | `mcpp:action=` — declares a **build-graph node** instead of doing the work here (see below) |
 
@@ -335,6 +335,18 @@ A **pinned** reference resolves to exactly that version or to nothing. A
 build that asked for `1.8.12` and silently got `1.9.0` is an answer only
 discovered later, in the artifact.
 
+A **constrained** one (`>=8.5.0`, `^1.2`) resolves to the highest installed
+version satisfying it *(2026.9.6.6+)*. Before that release the whole version
+position was compared against a directory name, so a range installed a payload
+and then answered that nothing was installed — which is why a rule package
+could not state a floor and every project repeated its rule's package list.
+
+**A package a DEPENDENCY declared is answered too** *(2026.9.6.6+)*, at the
+version this build actually installed rather than the one the local manifest
+wrote. One package means one version: where a project and a rule both name it,
+the declaration nearer the artifact wins and both sides are told the same
+answer. See *One package, one version* in [05 — mcpp.toml](05-mcpp-toml.md).
+
 **`[feature-xlings.<f>]` is answered too, while `<f>` is active**
 *(2026.9.6.2+)*. That table has provisioned its packages since it existed --
 naming one downloads and installs it -- but the build program's environment was

docs/17-the-project-environment.md

@@ -68,8 +68,9 @@ behind it.
 ### 2.1 Which version pins apply (2026.9.3+)
 
 Naming an environment also changes where a tool's version comes from. A
-project's own `[xlings.workspace]` entries always win; what differs is what
-they are laid over:
+project's own `[xlings.workspace]` entries always win — over the environment
+here, and over a dependency's declaration by the rule in section 3 — and what
+differs is what they are laid over:
 
 | The project declares | The version of a tool it did not name comes from |
 |---|---|
@@ -93,9 +94,23 @@ different question from `PATH` and stays a different answer: a build program
 that needs a package's data files (protoc's well-known `.proto` files, say)
 asks for the directory, and one that needs to *run* a program asks `PATH`.
 
-A dependency's own `[xlings]` declaration is never consulted or propagated. In
-a workspace build the workspace root owns the selection; a member's declaration
-applies only when that member is built as an independent root.
+**A workspace member's declaration is not the workspace's.** In a workspace
+build the workspace root owns the selection; a member's `[xlings]` applies only
+when that member is built as an independent root.
+
+**A dependency's declaration is a different matter, and it is honoured**
+(2026.9.5.4+ for `[xlings] deps`, 2026.9.6.6 for the version rule below). A
+board-support package knows which emulator reaches its machine, and a rule
+package knows which toolkit its rule drives; a consumer that had to repeat
+either is the duplication such packages exist to remove. What the dependency
+declares is installed, and `MCPP_XPKG_<NAME>_DIR` answers for it in that
+dependency's own build program.
+
+Where a project and a dependency name **one package**, one version of it is
+installed: identity is `(namespace, name)` and the version is a constraint on
+it. The declaration nearer the artifact wins and the override is reported;
+a pin that fails a requirement the other side stated is refused naming both.
+See *One package, one version* in [05 — mcpp.toml](05-mcpp-toml.md).
 
 ## 4. Reading an environment, never creating one
 

docs/zh/07-build-mcpp.md

@@ -110,7 +110,7 @@ int main() {
 | `mcpp::link_flag(s)` *(2026.9.6.5+)* | `mcpp:link-flag=` |
 | `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+)* | 本 manifest 在 `[xlings.workspace]` 里声明的包的载荷目录;没声明或没安装时返回 `""`(见下) |
+| `mcpp::xpkg_dir(ns, name)` / `mcpp::xpkg_dir(name)` *(2026.8.19+)* | `[xlings.workspace]` 里声明的包的载荷目录 —— 本 manifest 声明的,或编进本构建程序的某个依赖声明的(2026.9.6.6+);没声明或没安装时返回 `""`(见下) |
 | `mcpp::warning(text)` *(2026.8.21.2+)* | `mcpp:warning=` —— 见下 |
 | `mcpp::action{…}.submit()` *(2026.8.5.1+)* | `mcpp:action=` —— **声明一个构建图节点**,而不是在这里把活干了(见下) |
 
@@ -289,6 +289,14 @@ store 内部结构 —— 与 `dep_dir` 存在的理由相同。
 **带版本固定**的引用只解析到那个版本,否则什么都不返回。请求 `1.8.12` 却静默拿
 到 `1.9.0`,是那种要到产物里才被发现的答案。
 
+**带约束**的引用(`>=8.5.0`、`^1.2`)解析到满足它的**最高已安装版本**
+(2026.9.6.6+)。在那之前整个版本位是拿去与目录名比对的,于是一条范围装上了载荷,然后
+回答「没装」—— 这正是规则包无法声明下界、而每个工程都要把规则的包列表重写一遍的原因。
+
+**依赖声明的包同样被作答**(2026.9.6.6+),而且答的是这次构建**真正装上**的版本,不是
+本地 manifest 写下的那个。一个包只有一个版本:工程与规则都命名它时,离产物更近的声明赢,
+而两侧被告知同一个答案。见 [05 — mcpp.toml](05-mcpp-toml.md) 的「一个包一个版本」。
+
 **`[feature-xlings.<f>]` 在 `<f>` 生效时同样被作答**(2026.9.6.2+)。这张表从诞生
 起就参与供给 —— 在那里写下一个包,它就会被下载并安装 —— 但构建程序的环境只由
 `[xlings.workspace]` 填充,于是载荷明明在盘上,`xpkg_dir` 却返回 `""`。这时构建程序

docs/zh/17-the-project-environment.md

@@ -79,8 +79,17 @@ SubOS 里。前置让被声明的环境成为默认答案;其余的仍在它后
 的数据文件(比如 protoc 自带的 well-known `.proto`)的构建程序问目录,需要
 **运行**某个程序的构建程序问 `PATH`。
 
-依赖自己的 `[xlings]` 声明从不被读取也不被传播。工作区构建中由工作区根持有这个
-选择;成员的声明只在该成员作为独立根被构建时生效。
+**工作区成员的声明不是工作区的声明。** 工作区构建中由工作区根持有这个选择;成员的
+`[xlings]` 只在该成员作为独立根被构建时生效。
+
+**依赖的声明是另一回事,而且它被采纳**(`[xlings] deps` 自 2026.9.5.4,下面那条版本
+规则自 2026.9.6.6)。板级支持包知道哪个模拟器够得到它那台机器,规则包知道它驱动哪个
+工具包;要消费者把这些再写一遍,正是这类包存在的意义所反对的重复。依赖声明的东西会被
+装上,而 `MCPP_XPKG_<NAME>_DIR` 在那个依赖自己的构建程序里为它作答。
+
+工程与依赖命名**同一个包**时,只装它的一个版本:身份是 `(namespace, name)`,版本是这个
+包上的约束。离产物更近的声明赢,并且覆盖会被报出来;不满足对方所陈述之要求的钉会被拒绝
+并点出两侧。见 [05 — mcpp.toml](05-mcpp-toml.md) 的「一个包一个版本」。
 
 ## 4. 只读取环境,从不创建环境