Skip to content

Commit 4907df5

Browse files
committed
docs: README 的授权段说 vendored 源码「unchanged」,而那句话现在是假的
⚠️ llvm/PATCHES.md 记录着五处原地标记补丁,而 README 的授权段写着 vendored 源码 「are unchanged」。一句与授权相邻的陈述不该与台账矛盾。 改为「几乎未改动」,并把例外**枚举**出来而不是描述:四个文件五处区域,各自夹在 BEGIN/END 之间,一条 grep 数得完。同时写明判据(upstream 在这里问哪个 OS,而真正 的答案是 openkal 的某个接口)以及那份文档更重要的另一半 —— 十九处 <windows.h> 里 有十二处**不需要动**,谓词答对之后 libc++ 的 POSIX 分支本来就已经经 musl 到达 openkal。 并补一节「四个目标,一份源码」:四种目标格式、各自怎么被运行,以及为什么裸机那个 不会侥幸通过;⚠️ 并写明产物是在**真机上被运行**而不是被检查 —— 这个包在 Mach-O 和 PE 上要找的每一处差异都是链接成功、运行时失败。
1 parent 0cf9e18 commit 4907df5

1 file changed

Lines changed: 42 additions & 1 deletion

File tree

README.md

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,32 @@ that enquiry from `__ehdr_start`.
122122

123123
A package that had only ever been built would have shipped that.
124124

125+
## Four targets, one source
126+
127+
`examples/same-source` is built for four machines from one `src/main.cpp` with
128+
nothing edited between them, and it prints the same four lines on each:
129+
130+
| target | format | how it is run |
131+
|---|---|---|
132+
| `x86_64-linux-gnu` | ELF | directly |
133+
| `x86_64-windows-gnu` | PE32+ | on a Windows machine |
134+
| `aarch64-macos` | Mach-O | on an arm64 Mac |
135+
| `riscv64-none-elf` | ELF | QEMU with real OpenSBI firmware |
136+
137+
The fourth is the one that cannot pass by accident. A hosted target has a C
138+
library, a C++ runtime and an unwinder already installed, so a program that
139+
reaches one of them by mistake still works. There is nothing to reach on the
140+
fourth: the C library is openkal-musl, the standard library and the unwinder are
141+
this package's, and beneath them is firmware whose whole interface is `ecall`.
142+
143+
⚠️ **And the artefacts are run on the real machines, not inspected.** Continuous
144+
integration builds all three hosted targets on Linux and executes each on the
145+
system it was built for; `mcpp`'s own `openkal-cross` workflow builds them from
146+
three hosts and runs all nine combinations. Every difference this package had to
147+
find on Mach-O and PE — the loader-bootstrapped thread-local, the unwinder's
148+
search for its own tables, the personality routine, the visibility of weak
149+
definitions — **links successfully and fails at run time**.
150+
125151
## Not supported
126152

127153
- **the sanitizers.** compiler-rt's sanitizers depend on a host's internals —
@@ -131,4 +157,19 @@ A package that had only ever been built would have shipped that.
131157
## Licence
132158

133159
The port is Apache-2.0. The vendored sources under `llvm/` are Apache-2.0 with
134-
LLVM exceptions and are unchanged; `llvm/LICENSE.TXT` is theirs.
160+
LLVM exceptions; `llvm/LICENSE.TXT` is theirs.
161+
162+
⚠️ They are **almost** unchanged, and the exceptions are enumerated rather than
163+
described. `llvm/PATCHES.md` lists every one — five regions in four files, each
164+
between `// ─── openkal ─── BEGIN` and `// ─── openkal ─── END`, countable with
165+
166+
```sh
167+
grep -rn "openkal ─── BEGIN" llvm/
168+
```
169+
170+
Each replacement fits one sentence: *upstream asks here which operating system
171+
this is, and the real answer is openkal's `<interface>`.* A change that does not
172+
fit it is not made. The larger half of that document is the list of places that
173+
did **not** need changing — twelve of the nineteen `#include <windows.h>` sites
174+
resolve themselves once the predicate is answered correctly, because libc++'s
175+
POSIX branch was already reaching openkal through musl.

0 commit comments

Comments
 (0)