feat: 本包从哪儿编,与本包发布什么,现在是两件事

`port/include/features.h` 从 2026-08-22 起记着这个缺口和它的第一优解:

  ⓘ THIS IS THE SECOND-BEST REMEDY. The first would be for a package to
  distinguish the directories it is built from from the directories it
  publishes. Measured: mcpp cannot express it — publicUsage takes
  privateBuild's include directories entire.

mcpp 2026.8.27.1 增了 `[build] private_include_dirs`。本包改用它:
musl 的三个内部目录(`src/include`、`src/internal`、`musl-generated/internal`)
只到达本包自己的源码,不再进入任何消费者的命令行。

⇒ openkal-musl#13(把 `hidden` 当普通标识符的消费者编不过)在**目录**这一层
解决,而不是在**宏**这一层再打一个补丁。

## ⚠️ 为什么 features.h 那段还在

两条轴回答的是不同的问题,只有一条是关于可见性的:

  private_include_dirs  谁看得见 —— 消费者的命令行上根本没有这些目录
  OKM_MUSL_INTERNAL     谁在编译 —— 一个确实带着这些目录、但不是 musl 的 C 单元
                        (板子在这里构建 compiler-rt 时)仍然需要那些宏是惰性的

第二种情形已被实测过:`int_util.c:49: use of undeclared identifier __weak__`。
去掉任何一条都会让一个已经付过代价的缺陷回来。

## ⚠️ 为什么是 include_dirs 的子集而不是第二个列表

顺序承重:`port/include` 必须排在架构目录之前,内部覆盖层必须排在
`musl/include` 之前 —— 把这三个挪到末尾,musl 自己的构建会先找到公共
`<features.h>` 并以 `unknown type name hidden` 失败(同一份文件里记着这次实测)。
两个 TOML 数组表达不了一个顺序,所以那一个有序列表仍然是那一个有序列表。

## 判据

CI 增一步,断言的是**目录**不是症状 —— 断言某个宏不再冲突,会在包侧再打一个
宏补丁时变绿而泄漏还在。并带两个控制项:

- 分母:compile_commands.json 至少有一行,否则 grep 恒真
- 反向:`port/include` 必须仍在消费者命令行上,否则「什么都没发布」也会通过

本机实测(mcpp feat/target-side-reaches-every-unit + examples/cross-hello):
消费者单元 公共目录=有、三个内部目录=无。

Author: speak-agent

.github/workflows/ci.yml

@@ -190,6 +190,49 @@ jobs:
                  grep kal_random syms.txt; exit 1; }
           echo "  ok  kal_random_fill is weak, kal_time_sleep is strong"
 
+      # ⭐⭐ THE INTERNAL OVERLAY STOPS AT THIS PACKAGE'S BOUNDARY.
+      #
+      # musl reaches its own declarations through `src/include`, whose headers
+      # define `hidden`, `weak` and `weak_alias` — names that mean something
+      # only to musl's own sources. This package publishes the path it is built
+      # from, so every consumer used to see them too, and which consumer broke
+      # on which name was found one at a time (openkal-musl#13).
+      #
+      # `[build] private_include_dirs` (mcpp 2026.8.27.1) says which entries of
+      # `include_dirs` stop here. This asserts the DIRECTORY is absent from a
+      # consumer's command line — not that one macro no longer collides, which
+      # would go green again the moment the package patched that macro while
+      # the leak stayed.
+      - name: What this package is built from is not what it publishes
+        working-directory: examples/cross-hello
+        run: |
+          extra=''
+          [ -n '${{ matrix.target }}' ] && extra='--target ${{ matrix.target }}'
+          "$MCPP" build --toolchain '${{ matrix.toolchain }}' $extra
+          test -s compile_commands.json \
+            || { echo "::error::no compile_commands.json — nothing to check"; exit 1; }
+
+          # ⚠️ A DENOMINATOR. With no consumer row the greps below are
+          # vacuously true, which is the false green this check must not have.
+          rows="$(grep -c '"file"' compile_commands.json || true)"
+          [ "${rows:-0}" -ge 1 ] \
+            || { echo "::error::compile_commands.json has no rows"; exit 1; }
+
+          bad=0
+          for d in musl/src/include musl/src/internal musl-generated/internal; do
+            if grep -q -- "$d" compile_commands.json; then
+              echo "::error::the internal overlay '$d' reached a consumer"
+              bad=1
+            fi
+          done
+          # The control: a PUBLIC directory must still be there, or this check
+          # would pass for a build that published nothing at all.
+          grep -q -- 'port/include' compile_commands.json \
+            || { echo "::error::no public include directory reached the consumer — the check above proves nothing"
+                 exit 1; }
+          [ "$bad" = 0 ] || exit 1
+          echo "  ok  the internal overlay stops here; the public headers do not"
+
       # A program above this package names one package. It does not name
       # openkal, it does not name an implementation, and it says nothing about
       # the platform.

mcpp.toml

@@ -196,6 +196,37 @@ include_dirs = [
   "musl/include",
 ]
 
+# ⭐⭐ THE FIRST-BEST REMEDY, WHICH port/include/features.h SAID WAS NOT
+# AVAILABLE AND NOW IS.
+#
+# That file records the measurement of 2026-08-22: "The first would be for a
+# package to distinguish the directories it is BUILT FROM from the directories
+# it PUBLISHES. Measured: mcpp cannot express it — publicUsage takes
+# privateBuild's include directories entire."
+#
+# It can now. `private_include_dirs` names the entries OF `include_dirs` that
+# stop at this package's boundary, so musl's internal overlay reaches musl's
+# own sources and reaches no consumer.
+#
+# ⚠️ A SUBSET OF THE LIST ABOVE RATHER THAN A LIST OF ITS OWN, and that is the
+# point: the ORDER is load-bearing. `port/include` must precede the
+# architecture's directory, and the internal overlay must precede
+# `musl/include` — moving these three to the end makes musl's own build find
+# the public <features.h> first and fail with `unknown type name hidden`.
+# The one ordered list stays the one ordered list.
+#
+# ⚠️ THIS DOES NOT REPLACE `OKM_MUSL_INTERNAL`. That answers a different
+# question — "is this package the one compiling this unit" — and it is what
+# keeps the macros inert for a C consumer that IS built with these directories
+# on its line (compiler-rt, when a board builds it here). The two are the
+# authorship axis and the visibility axis; removing either brings back a defect
+# that has already been measured.
+private_include_dirs = [
+  "musl/src/include",
+  "musl/src/internal",
+  "musl-generated/internal",
+]
+
 cflags = [
   # musl is written to C99 and to nothing else. -nostdinc is not an
   # optimisation: a C library that included the headers of another C library

port/include/features.h

@@ -71,14 +71,36 @@
  * and finds <features.h> defining `weak', `hidden' and `weak_alias' as macros
  * that mean something only to musl's own sources.
  *
- * ⓘ THIS IS THE SECOND-BEST REMEDY. The first would be for a package to
- * distinguish the directories it is built from from the directories it
- * publishes. Measured 2026-08-22: mcpp cannot express it --- publicUsage takes
- * privateBuild's include directories entire. Moving the two directories into
+ * ⓘ THIS WAS THE SECOND-BEST REMEDY, AND THE FIRST ONE HAS ARRIVED.
+ *
+ * The note used to read: "The first would be for a package to distinguish the
+ * directories it is built from from the directories it publishes. Measured
+ * 2026-08-22: mcpp cannot express it --- publicUsage takes privateBuild's
+ * include directories entire." It was left here so that the better fix would
+ * not be lost, and it was not: mcpp 2026.8.27.1 added
+ * `[build] private_include_dirs`, and this package's manifest now uses it.
+ *
+ * ⚠️ SO WHY IS THE BLOCK BELOW STILL HERE? Because the two answer different
+ * questions and only one of them is about visibility.
+ *
+ *   private_include_dirs  --- WHO SEES the internal overlay. A consumer no
+ *                             longer has these directories on its command line
+ *                             at all, so the macros cannot reach it.
+ *   OKM_MUSL_INTERNAL     --- WHO IS COMPILING. A C source that IS built with
+ *                             these directories on its line and is NOT musl's
+ *                             --- compiler-rt, when a board builds it here ---
+ *                             still needs the macros inert.
+ *
+ * The second case is measured and is recorded further down: `int_util.c:49:
+ * use of undeclared identifier __weak__'. Removing either axis brings back a
+ * defect that has already been paid for once.
+ *
+ * ⚠️ The rejected alternative is also kept: moving the two directories into
  * per-glob flags places them AFTER include_dirs on the command line, and musl's
  * own build then finds the public <features.h> before the internal one and
- * fails with `unknown type name hidden'. The note is here so that the better
- * fix is not lost.
+ * fails with `unknown type name hidden'. That is why `private_include_dirs` is
+ * a SUBSET of `include_dirs` rather than a second list --- the order is the
+ * thing that cannot be given up.
  *
  * ⭐⭐ THE DISCRIMINATOR WAS WRONG ONCE, AND THE WRONG ONE HELD FOR A DAY.
  *