docs: sync documentation with current behavior - #348
Merged
Sunrisepeak merged 2 commits intoAug 3, 2026
Conversation
…g, correct the pin-checker claim Review of mcpp-community#348 against the current tree (2026.8.3.4, three releases newer than when the sync was written). Four things needed adjusting. 1. The ZH toolchain doc was missing THREE sections the EN one has, including the whole `x86_64-linux-musl`-from-Windows feature (2026.8.3.2). A Chinese reader had no way to learn that Windows can produce Linux ELF at all. Added, mirroring EN: "Windows 上产出 Linux ELF", "MSVC(系统工具链,Windows)", and the Clang 20+ operator-template hazard. EN/ZH are now at 16 sections each, and every other doc pair already matched. The EN section's claims were re-derived from `toolchain::host_can_serve` before translating: Windows serves linux targets only when musl AND same arch, which is exactly "no x86_64-linux-gnu, no cross-arch". Both languages now also state the fact that function makes explicit and the docs omitted — **a macOS host has no Linux-targeting payload at all** — and point at `mcpp toolchain list` as the authority so nobody has to memorize the matrix. 2. Artifact naming, undocumented since 2026.8.3.3 changed it. `kind = "lib"` for `x86_64-windows-gnu` produces `libfoo.a`, not `foo.lib`: the static-lib convention splits on the triple's *env* segment, not its OS. That release fixed a name that was wrong (a GNU archive wearing an MSVC name, which MSVC cannot consume), so anyone globbing `*.lib` out of a mingw build needs to know. Added as a table to both languages. 3. `docs/spec/package-identity.md` carried "当前实现为 2026.8.3.2" — already stale two releases later. A spec should not restate a value that expires on every release; the minimum-implementation version (0.0.106) is the load bearing one and it is still there. Dropped the parenthetical rather than bumping it, so it cannot go stale again. 4. **`check_version_pins.sh` does not have a Bash syntax error.** It parses (`bash -n`), runs, and exits 0 — verified on this tree. The failure is `sh check_version_pins.sh`: the script uses process substitution (`done < <(...)`), which dash cannot parse, so it reports "line 95: Syntax error: redirection unexpected". That is the invoking shell, not the script — its shebang is `#!/usr/bin/env bash` and CI invokes it as bash. This mattered enough to chase down because the claim appeared in six places across three files, each instructing the releaser to skip the guard and check pins by hand. That guard is the only machine check for pin drift, and pin drift has broken releases here before. All six now show the correct invocation and explain the sh-vs-bash trap instead. Also noted the cache-entry layout change from 2026.8.3.4 in the `[build] cache` section (both languages): entry layout is versioned, an upgrade that changes it retires older entries and the next build repopulates — nothing to clean by hand. The PR's other two findings were re-verified against the source and are correct: `kind = "shared"` really is refused off Linux/ELF (plan.cppm:513), and `[build].cxx_runtime` really is parsed but missing from `kKnownBuildKeys` — the allowlist's own comment says it "MUST stay in sync with the doc->get_* reads", and it is not. Left as-is; this PR touches no source.
Member
Review + 已直接推到本分支(
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
摘要
mcpp-usage、mcpp-contributing、mcpp-releaseskills。mcpp test与 shell E2E 的边界，补充 Windows 默认工具链、安装器平台范围、Linux ARM64 发布资产、offline/logging、pack 模式、release pin 和 SPEC-001 说明。kind = "shared"目前只支持 Linux/ELF；macOS/Windows（含交叉构建）应使用静态库或改用 Linux target。[build].cxx_runtime已能被解析但当前 allowlist 漏列，普通构建会 warning、--strict会失败；本 PR 不修改源码。Closes #347
验证
git diff --check origin/main...HEAD通过。docs/和.agents/skills/文件，无源码、workflow 或测试文件。mcpp build、mcpp test或 E2E：本次仅更新文档，无运行时行为变更。备注
.github/tools/check_version_pins.sh在第 95 行存在 Bash 语法错误，未将其执行结果当作验证。