Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .agents/docs/mcppls-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ mcppls 侧**没有** `extensionDependencies`:依赖是单向的。
| `mcppls.collectReport` | 收集诊断报告 | none |
| `mcppls.exportDiagnosticBundle` | 导出诊断包(服务器命令 `mcppls.exportBundle`) | none |
| `mcppls.runBuildToolInTerminal` | 在集成终端运行构建工具 | confirm |
| `mcppls.turnOffOtherCppFeatures` / `mcppls.restoreOtherCppFeatures` | 关闭/恢复其它 C++ 扩展的语言特性(**会写别的扩展自己的设置**,由 mcppls 执行) | confirm |
| `mcppls.turnOffOtherCppFeatures` / `mcppls.restoreOtherCppFeatures` | 关闭/恢复其它 C++ 扩展的语言特性(**会写别的扩展自己的设置**,由 mcppls 执行;它自己先问作用范围,关掉问题即不执行)。0.7.0 起是两条能力,不再共用一条候选链 | none |
| `mcppls.turnOnInWorkspace` / `mcppls.turnOffInWorkspace` | 在本工作区启用/停用 C++ Modules(**会写 `mcppls.enable`**,由 mcppls 执行) | confirm |
| `mcppls.installCommandLineTools` | macOS 命令行工具 | confirm |
| `mcppls.review.run` / `mcppls.review.clear` | Review Changes(**服务器广告**的命令,服务器运行后才存在;受 `mcppls.ai.enabled` 约束) | none |
Expand Down Expand Up @@ -120,6 +120,7 @@ VS Code 命令,重名会让 mcppls 的语言客户端启动失败。mcppls 因
| `serverCommands(): string[]` | ✅(服务器未运行时为空数组) | 判断服务器是否广告了某命令 |
| `environment()` | ✅ | version / vscode / appName / appHost / uiKind / platform / remote |
| `waitForState()` | ✅ | 需要等待某个状态时使用 |
| `otherCppFeatures(): { active: { extensionId, displayName, settable }[]; canRestore }` | ✅(mcppls 0.0.16 起) | 「其他 C++ 语言服务」一行:哪些在工作、mcppls 能否恢复。缺失、抛错或形状不对时退回本地只读检测(`src/mcppls/otherCppFeatures.ts`,同三个候选),`canRestore` 为 false |
| 计数器类(`notificationCount` 等) | ❌ 非测试模式下返回 `-1`/`0` | **不使用** |

**使用纪律**(写进 `mcpp-vscode/src/mcppls/state.ts`,并有单测与 e2e 覆盖):
Expand Down
47 changes: 47 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,50 @@
## 0.7.0 - 2026-10-14

`build.mcpp` is C++ again, compiled by C++ Modules as the build program it is, and the project
view says when another C++ language service is answering the same files.

### Changed

- **`build.mcpp` is a `cpp` document.** 0.6.0 gave it a language of its own, `mcpp-build`.
VS Code prefers a filename match over an extension match, so that hid the file from C++
Modules, which selects `cpp`: the build program got a line-by-line text check instead of a
compiler. The `mcpp-build` language, its grammar and its language configuration are gone;
this extension's build-script help now registers on `cpp` documents named `build.mcpp`, and
the C++ module grammar is injected into `source.cpp` only.
- **While C++ Modules serves `build.mcpp`, it answers what it answers better**: the
`unknownSymbol` check and the module names after `import` (completion and hover) are left to
it. The SPEC-007 rule checks, the `mcpp::…` directive completion and hover, and the snippets
stay. "Serves" means the extension is installed and enabled and `mcppls.enable` is not
`false` here; the open files are re-checked when that changes.
- **`unknownSymbol` reads the file's imports** when it does run: `import mcpp.rules.qt;` makes
`mcpp::rules::…` a name the snapshot cannot judge, so it is no longer reported
(`unknown mcpp::rules` on every Qt build program).
- The diagnostics' owner is `mcpp-build-script` (was `mcpp-build`).
- The build-script snapshot and the `mcpp.toml` schema are regenerated from mcpp 2026.10.11.1.
The schema generator reads the `[build]` keys from mcpp's key registry, where 2026.10.11.1
moved them.

### Added

- **Project → Basics → Language service → "Other C++ language services".** While C/C++
IntelliSense, clangd or ccls is active next to C++ Modules, the row shows a warning and their
names, and one click runs C++ Modules' own **Turn Off Other C++ Language Services** (it asks
whether for this workspace or everywhere, and writes the other extensions' own settings).
With none, the row is a dimmed check mark, "Only C++ Modules is serving C++". When C++
Modules remembers what it turned off, the row's context menu offers **Restore**. The list is
C++ Modules' own answer (0.0.16+); with an older one, a read-only look at the same three
extensions.
- `mcpp.languageServer.restoreConflicts` ("C++ Modules: Restore Other C++ Language Services").
`mcpp.languageServer.manageConflicts` is now titled "Turn Off Other C++ Language Services",
which is what it always ran.

### Migrating

- A setting written for the old language id, `"[mcpp-build]": { … }` in `settings.json`, no
longer applies. Move it under `"[cpp]"`.
- Turning other C++ services off or restoring them no longer asks a second time in this
extension: C++ Modules' command asks where to act, and closing that question does nothing.

## 0.6.0 - 2026-10-02

The sidebar was reorganised around one rule: **the body shows state, the actions sit
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Opening a project never runs `mcpp` on its own and never downloads a toolchain.

- **mcpp CLI and tasks** — build, run, test, clean, the quick menu, toolchains: [docs/commands.md](docs/commands.md).
- **`mcpp.toml` editing** — structural completion, hovers, go-to-definition, seven structural diagnostics, no formatting: [docs/mcpp-toml.md](docs/mcpp-toml.md).
- **`build.mcpp` intelligence** — completion and hovers for `mcpp::…` and `import`, seven SPEC-007 diagnostics, never a spurious "module not found": [docs/build-script.md](docs/build-script.md).
- **`build.mcpp` help** — `build.mcpp` is a `cpp` file that C++ Modules compiles as the build program; this extension adds the `mcpp::…` directive completion, hovers and snippets and the SPEC-007 rule checks no compiler makes: [docs/build-script.md](docs/build-script.md).
- **Libraries** — browse the package index already on this machine, offline; the detail page shows the real example code, the version matrix, and whether the workspace already depends on it.
- **Cache views and cleanup** — project artifacts and the shared build cache, previewed before anything is deleted: [docs/cache.md](docs/cache.md).
- **C++ Modules** — the other extension's state and actions, in the project view and the status-bar menu, forwarded not reimplemented: [docs/commands.md](docs/commands.md).
Expand Down
2 changes: 1 addition & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ C++ 模块语义——诊断、补全、悬停、定义、引用、模块图—

- **mcpp CLI 与任务** —— 构建、运行、测试、清理、快捷菜单、工具链:[docs/commands.md](docs/commands.md)。
- **`mcpp.toml` 编辑** —— 结构补全、悬停、跳转与七条结构诊断,不做格式化:[docs/mcpp-toml.md](docs/mcpp-toml.md)。
- **`build.mcpp` 智能** —— `mcpp::…` 与 `import` 的补全悬停、七条 SPEC-007 诊断,且永不误报「模块找不到」:[docs/build-script.md](docs/build-script.md)。
- **`build.mcpp` 辅助** —— `build.mcpp` 是普通的 `cpp` 文件,由 C++ Modules 当作构建程序编译;本扩展补上 `mcpp::…` 指令的补全、悬停、代码片段,以及编译器不会检查的 SPEC-007 规则:[docs/build-script.md](docs/build-script.md)。
- **库生态** —— 离线浏览本机已刷新的包索引;详情页展示真实示例代码、版本矩阵,以及工程是否已依赖它。
- **缓存视图与清理** —— 工程产物与共享缓存,删除前一律先给出预览:[docs/cache.md](docs/cache.md)。
- **C++ Modules** —— 对方扩展的状态与操作,集中在工程视图与状态栏快捷菜单,只转发不重写:[docs/commands.md](docs/commands.md)。
Expand Down
18 changes: 10 additions & 8 deletions data/buildscript-api.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"sourceVersion": "2026.10.3.1",
"sourceCommit": "74bcb859e60afc71ad759540d2de5344dda400e9",
"sourceVersion": "2026.10.11.1",
"sourceCommit": "3fb2d0cc89296c527fcda710792b67bb7a481bed",
"protocolVersion": 15,
"cacheEpoch": 3,
"roles": [
Expand Down Expand Up @@ -118,7 +118,8 @@
"rules": [
"R2.1",
"R3.3",
"R3.6"
"R3.6",
"R3.9"
],
"docsUrl": null
},
Expand All @@ -131,7 +132,7 @@
"mustExist": false,
"since": 4,
"rules": [],
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/74bcb859e60afc71ad759540d2de5344dda400e9/docs/30-build-mcpp.md#runner-how-the-artifact-is-executed-20268192"
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/3fb2d0cc89296c527fcda710792b67bb7a481bed/docs/30-build-mcpp.md#runner-how-the-artifact-is-executed-20268192"
},
{
"wire": "runner-named",
Expand Down Expand Up @@ -262,7 +263,7 @@
"R2.1",
"R9.4"
],
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/74bcb859e60afc71ad759540d2de5344dda400e9/docs/30-build-mcpp.md#warning-succeeding-and-still-being-heard-20268212"
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/3fb2d0cc89296c527fcda710792b67bb7a481bed/docs/30-build-mcpp.md#warning-succeeding-and-still-being-heard-20268212"
},
{
"wire": "diagnostic",
Expand Down Expand Up @@ -294,6 +295,7 @@
"R3.5",
"R3.7",
"R3.8",
"R3.9",
"R5.1",
"R5.3",
"R6.4",
Expand All @@ -312,7 +314,7 @@
"rules": [
"R2.1"
],
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/74bcb859e60afc71ad759540d2de5344dda400e9/docs/30-build-mcpp.md#the-probe-channel-fact-floor-2026952"
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/3fb2d0cc89296c527fcda710792b67bb7a481bed/docs/30-build-mcpp.md#the-probe-channel-fact-floor-2026952"
},
{
"wire": "floor",
Expand All @@ -325,7 +327,7 @@
"rules": [
"R2.1"
],
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/74bcb859e60afc71ad759540d2de5344dda400e9/docs/30-build-mcpp.md#the-probe-channel-fact-floor-2026952"
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/3fb2d0cc89296c527fcda710792b67bb7a481bed/docs/30-build-mcpp.md#the-probe-channel-fact-floor-2026952"
},
{
"wire": "pack-format",
Expand Down Expand Up @@ -374,7 +376,7 @@
"R9.2",
"R9.5"
],
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/74bcb859e60afc71ad759540d2de5344dda400e9/docs/30-build-mcpp.md#deploying-what-the-program-generated-deploy-20269123-protocol-11"
"docsUrl": "https://github.com/mcpp-community/mcpp/blob/3fb2d0cc89296c527fcda710792b67bb7a481bed/docs/30-build-mcpp.md#deploying-what-the-program-generated-deploy-20269123-protocol-11"
},
{
"wire": "runtime-search-dir",
Expand Down
6 changes: 5 additions & 1 deletion data/i18n/zh-cn.json
Original file line number Diff line number Diff line change
Expand Up @@ -467,5 +467,9 @@
"Could not write the clipboard.": "无法写入剪贴板。",
"The workspace is not trusted; mcpp itself was not probed.": "工作区未受信任;未探测 mcpp 本身。",
"This workspace is not trusted, so mcpp is not run; the versions below come from the descriptor's text.": "工作区未受信任,因此不运行 mcpp;下面的版本来自描述符文本。",
"The workspace is not trusted; the other registries were not searched.": "工作区未受信任;未搜索其他 registry。"
"The workspace is not trusted; the other registries were not searched.": "工作区未受信任;未搜索其他 registry。",
"Only C++ Modules is serving C++": "仅 C++ Modules 在提供 C++ 语言服务",
"No other C++ language service (C/C++, clangd, ccls) is active, so no result is shown twice.": "没有其他 C++ 语言服务(C/C++、clangd、ccls)在工作,结果不会重复出现。",
"Other C++ language services": "其他 C++ 语言服务",
"They answer the same C++ files, so results appear twice. Click to turn their C++ language features off; C++ Modules asks whether for this workspace or everywhere.": "它们也在处理同一批 C++ 文件,结果会出现两次。点击即可关闭它们的 C++ 语言功能;C++ Modules 会询问只对本工作区还是对所有地方生效。"
}
11 changes: 8 additions & 3 deletions data/toml-schema.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"sourceVersion": "2026.10.3.1",
"sourceCommit": "74bcb859e60afc71ad759540d2de5344dda400e9",
"sourceVersion": "2026.10.11.1",
"sourceCommit": "3fb2d0cc89296c527fcda710792b67bb7a481bed",
"sections": [
{
"header": "[build]",
Expand Down Expand Up @@ -690,6 +690,11 @@
"key": "soname",
"type": "string"
},
{
"key": "windows_auto_export",
"type": "string",
"unmodelled": true
},
{
"key": "windows_code_page",
"type": "enum",
Expand Down Expand Up @@ -778,7 +783,7 @@
"header": "[workspace]",
"name": "workspace",
"plane": "unclassified",
"doc": "https://github.com/mcpp-community/mcpp/blob/main/docs/04-mcpp-toml.md",
"doc": "https://github.com/mcpp-community/mcpp/blob/main/docs/04-mcpp-toml.md#218-workspace--tables-a-workspace-shares-202610101",
"deprecatedBy": null
},
{
Expand Down
80 changes: 39 additions & 41 deletions docs/build-script.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,35 @@
# Editing `build.mcpp`

`build.mcpp` is mcpp's build program: C++ that the engine compiles and runs to produce the
build graph. It gets its own language id, `mcpp-build` (exact filename `build.mcpp`), with the
TextMate grammar `source.mcpp-build` from `syntaxes/mcpp-build.tmLanguage.json`; the module
grammar `source.cpp.mcpp-modules` is injected into both `source.cpp` and `source.mcpp-build`.

## Why it is not handed to the C++ language service

Measured on a real mcppls payload with clangd 23.1.0, handing `build.mcpp` to the C++ language
service fails for **both** `import std;` and `import mcpp;`:

```text
$ mcppls check build.mcpp --payload <payload>
root …/examples/11-features/greeter
database 6 entries, 2 standard library units, 0 left out
module build.mcpp:2: module 'mcpp' not found
E [module_not_found] Line 1: module 'std' not found
E Failed to build module mcpp; due to Don't get the module unit for module mcpp
clangd exit 3

$ mcppls check src/main.cpp --payload <payload>
database 6 entries, 2 standard library units, 0 left out
clangd exit 0
```

The reason is in the build database: `mcpp emit build-database --spec compile-commands --format
json` lists 6 records and **none of them is `build.mcpp`** — it only appears under `data.watch`.
mcpp deliberately does not put the build program into the compilation database, and mcppls's
model has no `build.mcpp` (it handles `target/.build-mcpp/deps/…`). So this is not "only `mcpp`
is missing": `std` fails too, and VS Code has no public API to filter a diagnostic another
extension published.

**Therefore `build.mcpp` stays in its own language id and the C++ language service never sees
it.** This extension analyses the file itself, and it never reports any import as missing.
build graph. **It is an ordinary `cpp` document** (this extension declares the filename for the
`cpp` language, and C++ Modules associates `.mcpp` with `cpp` too); the module grammar
`source.cpp.mcpp-modules` is injected into `source.cpp`.

## Who answers what

C++ Modules (mcppls, 0.0.12 and later) compiles `build.mcpp` as the build program it is: against
the modules it really imports, `mcpp`, `std` and the plugins named in
`[build-dependencies]`, with the toolchain the build uses. Its completion, hover, navigation and
diagnostics are a compiler's. This extension adds what no compiler says:

| | C++ Modules serves the file | C++ Modules is disabled or switched off here |
| --- | --- | --- |
| SPEC-007 rule checks (six of the seven rules below) | this extension | this extension |
| `unknownSymbol` | off — the compiler's answer replaces it | this extension, import-aware |
| `mcpp::…` directive completion and hover, snippets | this extension | this extension |
| Module names after `import` (completion, hover) | C++ Modules | this extension |

"Serves" is read without asking anything of the language server: the C++ Modules extension is
installed and enabled, and `mcppls.enable` is not `false` for the workspace. When that changes
(the extension is enabled, disabled, or switched off for the workspace) the open `build.mcpp`
files are re-checked at once.

Up to 0.6.0 this extension gave `build.mcpp` a language id of its own, `mcpp-build`. VS Code
prefers a filename match over an extension match, so that hid the file from C++ Modules, which
selects `cpp` documents: the build program got a line-by-line text check instead of a compiler,
and `import mcpp.rules.qt;` followed by `mcpp::rules::qt::…` was reported as an unknown name.
A setting written for that language (`"[mcpp-build]": { … }`) no longer applies; write it under
`"[cpp]"`.

## What this extension provides

Expand All @@ -42,19 +39,20 @@ work in an untrusted workspace.

### Completion

Registered for the `mcpp-build` language in `src/buildscript/providers.ts`.
Registered for `cpp` documents named `build.mcpp`, in `src/buildscript/providers.ts`.

- After `mcpp::` (or `mcpp::pre`): directive names, from the 31 entries in the snapshot's
`directives` array, with `-` rewritten to `_` (so the wire name `link-flag` offers
`link_flag`). Kind: function.
- After `import ` or `export import `: the concrete module names from the known-module table
(the `prefix.*` patterns are not offered as literal text). Kind: module, with the module's
description as documentation.
- After `import ` or `export import `, only while C++ Modules does not serve the file: the
concrete module names from the known-module table (the `prefix.*` patterns are not offered as
literal text). Kind: module, with the module's description as documentation.

### Hover

- On a known module name in an `import`: the module name and its description (for a
`prefix.*` match, the concrete name the user wrote is shown).
- On a known module name in an `import`, only while C++ Modules does not serve the file: the
module name and its description (for a `prefix.*` match, the concrete name the user wrote is
shown).
- On `mcpp::<name>`: the wire spelling (`mcpp:<wire>=`), `slot`, `scope`, `since protocol`, the
SPEC-007 rules and a link into mcpp's `docs/30-build-mcpp.md`.

Expand All @@ -78,7 +76,7 @@ diagnostic's `code`; `source` is `mcpp`.

| Code | What it flags | SPEC-007 |
| --- | --- | --- |
| `mcpp.buildscript.unknownSymbol` | An `mcpp::<name>` that is not a directive, an action role or a typed-API name in the snapshot | §2 |
| `mcpp.buildscript.unknownSymbol` | An `mcpp::<name>` that is not a directive, an action role or a typed-API name in the snapshot, and not a namespace the file imports (`import mcpp.rules.qt;` covers `mcpp::rules::…`). Only while C++ Modules does not serve the file | §2 |
| `mcpp.buildscript.roleLiteral` | `role = "<known role>"`; use `mcpp::roles::<role>` so an engine that does not know it refuses to compile | R3.6 |
| `mcpp.buildscript.prepareNeedsOutputDir` | A `prepare` action with no `output_dir(…)` | R3.3 |
| `mcpp.buildscript.rpathInLinkFlag` | `-Wl,-rpath` in `link_flag`; use `mcpp::runtime_search_dir(…)` | R4.4 |
Expand Down Expand Up @@ -113,8 +111,8 @@ the raw-string and block-comment state carries across lines.

| Field | Value |
| --- | --- |
| `sourceVersion` | `2026.10.1.3` |
| `sourceCommit` | `4d81d062` |
| `sourceVersion` | `2026.10.11.1` |
| `sourceCommit` | `3fb2d0cc` |
| `protocolVersion` | `15` |
| `cacheEpoch` | `3` |
| `roles` | `source`, `check`, `object`, `artifact`, `prepare` |
Expand Down
Loading
Loading