diff --git a/.agents/skills/mcpp-ide-contributing/SKILL.md b/.agents/skills/mcpp-ide-contributing/SKILL.md new file mode 100644 index 0000000..3617688 --- /dev/null +++ b/.agents/skills/mcpp-ide-contributing/SKILL.md @@ -0,0 +1,73 @@ +--- +name: mcpp-ide-contributing +description: Use when contributing to mcpp-ide -- reporting a bug, proposing a feature, opening an issue or a pull request, or making any change as a person or an AI agent. Covers triage (core or plugin, fix or workaround), issue and pull-request conventions, commits, review and merge. +--- + +# Contributing to mcpp-ide + +Read [AGENTS.md](../../../AGENTS.md) first: who owns what, and the rules every change follows. The +flow is **issue → branch → pull request → CI → review → squash merge**. Nothing is pushed to `main` +directly, whatever its size, and that includes a version bump or a change to documentation. + +## 1. Triage before anything else + +Answer the three questions of AGENTS.md §3 and write the answers into the issue: + +| Question | How to decide | Outcome | +|---|---|---| +| Whose problem? | reproduce without the editor: `mcpp-ide self-check --json`, `mcpp-ide serve`, the mock mcpp | mcpp, mcppls or an editor's upstream: report it there and link it here | +| Core or plugin? | would another editor need the same change? | yes → backend (`src/`, `spec/`, `protocol/`); no → `mide-plugins/` | +| Fix or workaround? | does the cause lie in this repository? | no → no workaround by default; an exception states its cause, the upstream issue, why it cannot wait and when it is removed | + +## 2. Issues + +Open one with a template (`.github/ISSUE_TEMPLATE/`): **Bug report**, **Feature request** or +**Task**. A blank issue is not offered, and a question goes to the +[forum](https://forum.d2learn.org/category/20). + +- Title: `(): `, for example `fix(clion): the test tree loses a case's + location after a rebuild`. The type is one of `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, + `ci`, `chore`. The component is `backend`, `vscode`, `clion`, `nvim`, `docs` or `ci`. +- A bug carries the output of `mcpp-ide self-check --json` (backend, mcpp, mcppls, xlings, trust), + the editor and its version, the steps, the expected and actual behaviour, and the triage answers. + The IDE report (**mcpp: Export IDE Report**) is attached when the backend is involved. +- A feature states the motivation, which party it belongs to, the protocol or `spec/` change it + needs, and what each editor shows. A change larger than one pull request gets a design record in + `.agents/docs/` (`YYYY-MM-DD-.md`, opening with its status) before any code. + +## 3. Branches and commits + +- Branch from the latest `main`: `/`, for example `fix/clion-case-location`. A + release is made on `release/X.Y.Z` (see [mcpp-ide-development](../mcpp-ide-development/SKILL.md)). +- A commit is English and declarative, `(): ` or `X.Y.Z: ` for + a release, with no emoji. Its body says why, citing the issue, the design record or mcpp's spec + clause where there is one. + +## 4. Pull requests + +- One pull request does one thing and links the issue it closes (`Closes #N`). The title follows + the commit form, since it becomes the subject of the squash merge. +- The body follows `.github/pull_request_template.md`: summary, triage, the criteria (the test that + fails before and passes after, and where it ran), compatibility and the checklist. +- A change of behaviour updates, in the same pull request: `protocol/protocol.schema.json`, the docs + it touches (README.md and README.zh-CN.md together), `spec/i18n` in both languages, and + CHANGELOG.md under its series. +- The required check is `ci`. It runs the components the change reaches (`.github/components.tsv`), + so a backend change runs every plugin. A red job is fixed, never retried until green. +- The merge is a squash with an explicit subject and body; GitHub's composed message is not used. + +## 5. AI agents + +An agent contributes under the same rules, plus these: + +- **Read before writing:** AGENTS.md, the docs it links for the area, and the neighbouring code. Do + the triage before editing, and say in the pull request which party the problem belongs to. +- **Ask before outward actions:** creating an issue, a pull request, a comment, a tag or a release + needs the person's confirmation. Never push to `main`, force-push a shared branch, merge, tag or + publish unless explicitly asked. +- **Report what ran:** each criterion says whether it ran locally, on which system, or was left to + CI. A test that did not run is not described as passing. +- **Stay in scope:** no drive-by refactors, no new dependency and no workaround for another party's + problem without the person's decision. +- **No attribution trailers:** commits and pull requests carry no `Co-Authored-By` lines or + generated-by footers. The person who submits a change is responsible for it. diff --git a/.agents/skills/mcpp-ide-development/SKILL.md b/.agents/skills/mcpp-ide-development/SKILL.md new file mode 100644 index 0000000..e2e87aa --- /dev/null +++ b/.agents/skills/mcpp-ide-development/SKILL.md @@ -0,0 +1,77 @@ +--- +name: mcpp-ide-development +description: Use when setting up a development environment for mcpp-ide, building or testing the backend or an editor plugin, changing the protocol, spec/, fixtures or strings, bumping a pinned tool, or preparing a release (a series vX.Y.0 or a plugin patch). +--- + +# Developing mcpp-ide + +## 1. Environment + +The pins live in [.github/versions.env](../../../.github/versions.env), which CI reads. A local +setup uses the same versions: + +| Tool | Version | For | Install | +|---|---|---|---| +| xlings | `XLINGS_VERSION` | mcpp, toolchains, gradle | [xlings](https://github.com/d2learn/xlings) | +| mcpp | `.xlings.json` (= `MCPP_VERSION`) | the backend; its toolchain comes from `mcpp.toml` | `xlings install` in the repository | +| Node.js | 22 | the VS Code extension, the web UI tests | any Node 22 | +| VS Code | `VSCODE_VERSION` (the oldest supported) | the extension's e2e tests | fetched by `@vscode/test-electron` | +| Gradle and its JDK | xlings's | the CLion plugin | `xlings install gradle` | +| Neovim | 0.10+ | the Neovim plugin | system package | + +Check the environment with `mcpp build && mcpp run mcpp-ide -- self-check`. + +## 2. Build and test, per component + +Run what a change reaches ([.github/components.tsv](../../../.github/components.tsv)). A backend +change reaches every plugin, because each plugin is tested over the backend. + +| Component | Paths | Commands | +|---|---|---| +| backend | `src/`, `protocol/`, `spec/`, `webui/`, `tests/`, `testsupport/`, `mcpp.toml` | `mcpp build`, `mcpp test`, `mcpp run mcpp-ide-dev -- check-sources`, `mcpp run mcpp-ide-dev -- check-i18n` | +| vscode | `mide-plugins/vscode/` | `npm ci && npm test`; `npm run test:parity`, `npm run test:webui`, `npm run test:e2e`; `npm run package` | +| clion | `mide-plugins/clion/` | `gradle test buildPlugin verifyPlugin` | +| nvim | `mide-plugins/nvim/` | `nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua` | +| CI | `.github/` | `bash .github/scripts/test_changes.sh`, `bash .github/scripts/release-plan.sh` | + +## 3. Common changes + +- **A protocol method or notification:** change `protocol/protocol.schema.json` together with the + backend and every plugin that uses it. The backend's tests check its answers against the schema. +- **A setting, command or editor string:** edit `spec/` (`settings.json`, `commands.json`, + `i18n/*.json`), then run `mcpp run mcpp-ide-dev -- gen vscode` and commit what it rewrites in + `mide-plugins/vscode`. CLion's declarations are generated at build time. Neovim reads the table at + run time. A command that an editor does not offer states why (`omitted`). +- **A runtime string:** pass it through `t(...)` and add its Chinese entry to + `spec/i18n/runtime.zh-cn.json`; `check-i18n` enforces this. +- **What mcpp reports:** run `mcpp run mcpp-ide-dev -- capture` against a real mcpp and review the + diff in `protocol/fixtures`. Update `protocol/mcpp-contract.schema.json` if the contract grew. + The mock mcpp and every plugin's tests replay these fixtures. +- **A feature of a newer mcpp or mcppls:** enable it from what mcpp states (`features`). An earlier + release is described by a table frozen at that release, not by comparing versions. +- **A pinned tool:** change `.github/versions.env`, `.xlings.json` and `mcpp = ">=..."` in + `mcpp.toml` together, and only to versions that are already released and indexed. + +## 4. Diagnosing + +- `mcpp-ide self-check --json` reports the backend, mcpp and its contract, mcppls, xlings and trust. +- The IDE report (**mcpp: Export IDE Report**, `:Mcpp exportReport`) collects the projects' mcpp, + mcppls's status, the settings in effect, recent jobs and the backend's log. +- `mcpp.backend.logLevel` controls how much the backend writes to the editor's log. + +## 5. Release + +The rules are in AGENTS.md §4 and [release-plan.sh](../../../.github/scripts/release-plan.sh). + +1. Decide the kind. Any backend path changed since `vX.Y.0` means a series release `vX.Y+1.0` (or + `vX+1.0.0`). Otherwise it is a plugin patch, `-vX.Y.Z+1`. +2. On `release/`, bump the version statements (all six for a series, only the plugin's + own for a patch) and add the CHANGELOG.md section under its series, listing each component's + version. Then run `bash .github/scripts/release-plan.sh `. +3. Open a pull request titled `X.Y.Z: ` and merge it after `ci` passes. +4. Tag the merge commit and push the tag. `release.yml` runs CI, publishes the GitHub release with + `SHA256SUMS`, then submits the same VSIX to Open VSX and the same ZIP to JetBrains Marketplace. + The Visual Studio Marketplace upload is manual. The secrets are `OPENVSX_TOKEN` and + `JETBRAINS_TOKEN`; Marketplace availability follows JetBrains review. +5. Watch the run until every job passes, then check that the release assets install + (`mcpp-ide self-check` on a project). diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..24ab8e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,64 @@ +name: Bug report +description: mcpp-ide or one of its editor plugins behaves wrongly +title: "fix(): " +labels: [bug] +body: + - type: markdown + attributes: + value: | + Triage first ([AGENTS.md §3](https://github.com/mcpp-community/mcpp-ide/blob/main/AGENTS.md)): + reproduce without the editor where you can, and report problems of mcpp or mcppls in their own repositories. + - type: dropdown + id: component + attributes: + label: Component + options: [backend, vscode, clion, nvim, packaging / install, docs] + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: The smallest project and the actions that show the problem. + placeholder: | + 1. mcpp new demo && cd demo + 2. ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected and actual behaviour + validations: + required: true + - type: textarea + id: selfcheck + attributes: + label: mcpp-ide self-check --json + description: The backend, mcpp and its contract, mcppls, xlings and trust. + render: json + validations: + required: true + - type: input + id: editor + attributes: + label: Editor and OS + placeholder: VS Code 1.95 / CLion 2026.1 / Neovim 0.11 on Ubuntu 24.04 x86_64 + validations: + required: true + - type: dropdown + id: party + attributes: + label: Whose problem is it? + description: Where does it still reproduce once the editor is taken away? + options: + - The backend (every editor shows it) + - One editor plugin only + - Not sure yet + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs or IDE report + description: "mcpp: Export IDE Report (Neovim :Mcpp exportReport), or the backend's log." diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..f9d6354 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Question or discussion + url: https://forum.d2learn.org/category/20 + about: Usage questions and ideas go to the community forum. + - name: A problem of mcpp itself + url: https://github.com/mcpp-community/mcpp/issues/new/choose + about: Wrong output from mcpp (builds, tests, the machine contract) is reported to mcpp. + - name: A C++ language feature (mcppls) + url: https://github.com/Sunrisepeak/mcpp-language-server/issues + about: Completion, navigation and diagnostics of C++ files come from mcppls. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..e16e59e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,34 @@ +name: Feature request +description: A new capability or a change of behaviour +title: "feat(): " +labels: [enhancement] +body: + - type: textarea + id: motivation + attributes: + label: Motivation + description: The problem it solves, and for whom. + validations: + required: true + - type: dropdown + id: party + attributes: + label: Where does it belong? + description: A decision every editor shares belongs to the backend; plugins only map it onto their UI. + options: + - Backend (protocol / spec), shown by every editor + - One editor plugin's presentation + - Needs mcpp or mcppls to state something new first + validations: + required: true + - type: textarea + id: design + attributes: + label: Design + description: The protocol or spec/ change, what each editor shows, and the mcpp feature it relies on. A change larger than one pull request starts with a record in .agents/docs/. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml new file mode 100644 index 0000000..3c28a2f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/task.yml @@ -0,0 +1,22 @@ +name: Task +description: Maintenance, refactoring, CI, documentation or a release +labels: [task] +body: + - type: dropdown + id: type + attributes: + label: Type + options: [refactor, perf, test, docs, ci, chore, release] + validations: + required: true + - type: textarea + id: what + attributes: + label: What and why + validations: + required: true + - type: textarea + id: done + attributes: + label: Done when + description: The criteria that close this task. diff --git a/.github/components.tsv b/.github/components.tsv index 18d1e99..54d5476 100644 --- a/.github/components.tsv +++ b/.github/components.tsv @@ -25,5 +25,8 @@ docs docs/* docs agents/* docs *.md docs LICENSE +# The forms of issues and pull requests are read by people too, although they live under .github/. +docs .github/ISSUE_TEMPLATE/* +docs .github/pull_request_template.md # The workflows, the scripts and the pins every job runs with. all .github/* diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..6bd7edd --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +## Summary + + + +## Triage + + + +## Criteria + + + +## Compatibility + + + +## Checklist + +- [ ] One thing; the title is `(): ` (or `X.Y.Z: `). +- [ ] The protocol schema, docs (README in both languages), `spec/i18n` and CHANGELOG.md follow the behaviour. +- [ ] `spec/` is edited, not its output; `mcpp-ide-dev gen vscode` leaves no diff. +- [ ] No commit carries an attribution trailer (`git log origin/main..HEAD -i --grep=Co-Authored-By` is empty). diff --git a/.github/scripts/test_changes.sh b/.github/scripts/test_changes.sh index 6213e91..ebd3707 100755 --- a/.github/scripts/test_changes.sh +++ b/.github/scripts/test_changes.sh @@ -26,6 +26,8 @@ check "its README is the plugin's" pull_request vscode=true docs=false backend=f check "documentation alone" pull_request docs=true backend=false vscode=false -- docs/x.md README.md check "the backend reaches every plugin" pull_request backend=true vscode=true clion=true nvim=true -- src/main.cpp check "spec/ is the backend's" pull_request backend=true vscode=true -- spec/test-frameworks.json +check "the issue and pull-request forms are documentation" pull_request docs=true backend=false full=false -- .github/ISSUE_TEMPLATE/bug_report.yml .github/pull_request_template.md +check "a skill is documentation" pull_request docs=true backend=false full=false -- .agents/skills/mcpp-ide-development/SKILL.md AGENTS.md check "a workflow reaches everything" pull_request full=true backend=true -- .github/workflows/ci.yml check "a path of no component reaches everything" pull_request full=true -- newdir/x check "a push reaches everything" push full=true backend=true -- docs/x.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8561ce6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,100 @@ +# AGENTS.md + +mcpp-ide is the IDE layer of [mcpp](https://github.com/mcpp-community/mcpp): one backend (`mcpp-ide serve`, +C++23 modules) and the editor plugins that host it (`mide-plugins/`: VS Code, CLion, Neovim). This file +gives the rules in their shortest form and links to the full statement, which holds where they differ. + +## 1. Where a fact lives + +| Path | States | +|---|---| +| [docs/architecture.md](docs/architecture.md) | the layers, the adapters, a request end to end, distribution | +| [docs/versions.md](docs/versions.md) | series and tags, the project's mcpp and what each of its features adds | +| [protocol/](protocol) | the backend's protocol, the part of mcpp's contract it reads, mcpp's real output (`fixtures/`) | +| [spec/](spec) | settings, commands, strings: the source of every editor's declarations | +| [.agents/docs/](.agents/docs) | design records, `YYYY-MM-DD-.md`, each opening with its status | +| [.agents/skills/](.agents/skills) | procedures: [contributing](.agents/skills/mcpp-ide-contributing/SKILL.md) (issues, pull requests, agents), [development](.agents/skills/mcpp-ide-development/SKILL.md) (environment, tests, release) | +| [agents/](agents/README.md) | for agents that *use* mcpp-ide: the [mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) | +| `mide-plugins//README.md` | one plugin: installing it, its settings, what it maps onto | +| [CHANGELOG.md](CHANGELOG.md) | by series; release.yml publishes it as the release notes | + +## 2. Who owns what + +| Party | Owns | Never | +|---|---|---| +| mcpp | the machine contract: events, result records, launches, JSON queries, `features` | an IDE concept | +| backend (`src/`) | every decision: projects, jobs and lanes, view models, cleanup plans, settings, the command table, strings, the rules of mcpp.toml and build.mcpp | a manifest's meaning, resolving dependencies | +| plugins (`mide-plugins/`) | the protocol mapped onto the editor's native UI, the backend process, workspace trust | any decision | +| mcppls | every language feature of C++ files | | + +- **One answer everywhere.** What two editors would both decide is the backend's. A decision made + in a plugin is a defect, even a correct one. +- **Only mcpp's contract.** A fact mcpp does not state is requested from mcpp (an issue there). It is + never derived by parsing mcpp's files or its human-readable output. +- **Capabilities, not versions.** A feature is enabled by what the project's mcpp (or mcppls) states. + An older release is described by a table frozen at that release. Versions are never compared. +- **Native in each editor.** A plugin uses its editor's own components. VS Code's pages stay + byte-identical to mcpp-vscode 0.9.0 (`test/parity`). +- **Doing less is never silent.** A missing capability is reported with the party responsible and + the remedy (`capabilities/explain`, `self-check`). + +## 3. Before a change: triage + +1. **Whose problem is it?** Reproduce it without the editor: `mcpp-ide self-check --json`, the + protocol over `mcpp-ide serve`, the mock mcpp. Wrong output from mcpp goes to mcpp, a C++ language + feature to mcppls, an editor API to that editor's upstream. Report it there with the reproduction. +2. **Backend or plugin?** If another editor would need the same change, it belongs to the backend. + A plugin changes only for how an answer is shown or for its host's API. +3. **Fix or workaround?** Fix the cause in the party that owns it. A problem that is not this + project's gets no workaround by default. A workaround that must ship anyway (a blocked release, + an upstream fix that will not arrive in time) states in the code and in the pull request: the + cause, the upstream issue, why it cannot wait, and when it will be removed; it stays narrow. + +## 4. Versions ([release-plan.sh](.github/scripts/release-plan.sh)) + +- A version is `X.Y.Z`. The series `X.Y` is shared by the backend and every plugin; `Z` is one + plugin's own patch. The backend is always `X.Y.0`: every package carries it, so a change to any + backend path ([components.tsv](.github/components.tsv)) begins a new series. +- Six statements: `mcpp.toml`, `src/server.cppm` (`kVersion`, `kSeries`), `vscode/package.json`, + `clion/gradle.properties` (`pluginVersion`), `nvim/lua/mcpp/session.lua` (`M.version`). A series + changes all of them in one commit, a patch only its plugin's; CI checks that they agree. +- Tags: `vX.Y.0` releases every component. `vscode-vX.Y.Z`, `clion-vX.Y.Z` and `nvim-vX.Y.Z` release + one plugin's patch, and are refused if the backend changed after `vX.Y.0`. +- Pins name only released versions: [versions.env](.github/versions.env) (CI), `.xlings.json`, `mcpp = ">=..."`. + +## 5. Build and test + +```bash +mcpp build && mcpp test # backend (mtest: unit, e2e, cts, bench) +mcpp run mcpp-ide-dev -- check-sources && mcpp run mcpp-ide-dev -- check-i18n +(cd mide-plugins/vscode && npm ci && npm test) # extension, parity gates included +(cd mide-plugins/clion && gradle buildPlugin verifyPlugin) # CLion plugin +nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # Neovim plugin +``` + +- Edit `spec/`, never what is generated from it. `mcpp-ide-dev gen vscode` rewrites the extension's + manifest, bundles and registry, and CI expects no diff afterwards. +- A change in what mcpp reports begins with `mcpp-ide-dev capture` and the diff in `protocol/fixtures`, + which the mock mcpp replays; CI runs the components a change reaches (`components.tsv`). + +## 6. Code + +- Backend: C++23 modules and `import std;`, with no header, no `#include` and no `#if`. The system is + reached only through `mcpplibs.os` (`os::host()`, never `os::is_`, which an ok image answers + false). `check-sources` enforces all of this. +- CLion: public IntelliJ API only (the verifier reports internal use). VS Code: the oldest + `engines.vscode` (`VSCODE_VERSION`). Neovim: 0.10 and later, over `vim.lsp`. +- User-facing strings belong to the backend (`spec/i18n`), and English and Chinese change together. +- Follow the neighbouring code and change only what the task needs. A comment says why, not what. + +## 7. Change workflow + +- Follow the [contributing skill](.agents/skills/mcpp-ide-contributing/SKILL.md): an issue from a + template, a branch `/` from `main`, a pull request, passing `ci`, review, a squash + merge. Nothing is pushed directly to `main`; an agent asks before any outward action. +- Commits and pull requests are English and declarative, `(): ` or + `X.Y.Z: `, with no attribution trailer. Documentation follows mcpp's + [docs style](https://github.com/mcpp-community/mcpp/blob/main/.agents/skills/mcpp-docs-style/SKILL.md), + and README.md and README.zh-CN.md stay in step. +- One pull request does one thing. A change in behaviour updates the protocol schema, the affected + docs and CHANGELOG.md in the same pull request; a decision worth keeping goes to `.agents/docs/`. diff --git a/README.md b/README.md index 1fe0ef8..2103706 100644 --- a/README.md +++ b/README.md @@ -1,153 +1,114 @@ -# mcpp-ide - the IDE layer of mcpp +
-> One backend for every editor of [mcpp](https://github.com/mcpp-community/mcpp) projects: VS Code -> (mcpp-vscode), CLion (mcpp-clion) and Neovim (mcpp-nvim) build, run, test, debug and pack alike +# mcpp-ide + +**One backend for every editor of [mcpp](https://github.com/mcpp-community/mcpp) projects** + +VS Code · CLion · Neovim build, run, test, debug and pack alike + +[![Release](https://img.shields.io/github/v/release/mcpp-community/mcpp-ide)](https://github.com/mcpp-community/mcpp-ide/releases) +[![CI](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml) +[![VS Code](https://img.shields.io/badge/VS_Code-mcpp--vscode-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) +[![Open VSX](https://img.shields.io/open-vsx/v/mcpp-community/mcpp-vscode?label=Open%20VSX)](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) +[![JetBrains](https://img.shields.io/jetbrains/plugin/v/io.github.mcpp-community.mcpp-clion?label=CLion)](https://plugins.jetbrains.com/plugin/35632-mcpp) +[![C++23](https://img.shields.io/badge/C%2B%2B-23_modules-blue.svg)](https://en.cppreference.com/w/cpp/23) +[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE) **English** | [简体中文](README.zh-CN.md) -[Documentation](docs/README.md) · [Protocol](protocol/protocol.schema.json) · [Settings](spec/settings.json) · -[For agents](agents/README.md) · [Releases](https://github.com/mcpp-community/mcpp-ide/releases) +[Documentation](docs/README.md) · [Architecture](docs/architecture.md) · [Protocol](protocol/protocol.schema.json) · +[For agents](agents/README.md) · [Contributing](AGENTS.md) · [Releases](https://github.com/mcpp-community/mcpp-ide/releases) + +
+ +An editor integration of a build tool makes many decisions: which command a build runs, what a test +result means, how dangerous a cleanup is. If each editor makes them separately, the editors drift +apart. mcpp-ide makes them once. Its backend, `mcpp-ide serve`, reads only mcpp's machine contract +and answers every editor as an LSP server. Each plugin then shows those answers in its editor's own UI. + +```mermaid +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 26, "rankSpacing": 56, "padding": 14}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#54aeff", "edgeLabelBackground": "#ffffff"}}}%% +flowchart TB + vscode("VS Code
mcpp-vscode"):::client + clion("CLion
mcpp-clion"):::client + nvim("Neovim
mcpp-nvim"):::client + agent("Agents
mcpp-ide skill"):::client + serve("mcpp-ide serve
LSP · every decision"):::core + mcppls("mcppls
C++ language server"):::ls + mcpp("mcpp
build · test · pack"):::tool + vscode & clion & nvim & agent --> serve + serve -- contract --> mcpp + serve -. status .-> mcppls + classDef client fill:#ffffff,stroke:#54aeff,color:#0550ae + classDef core fill:#0969da,stroke:#0550ae,color:#ffffff + classDef ls fill:#fbefff,stroke:#c297ff,color:#6639ba + classDef tool fill:#f6f8fa,stroke:#8c959f,color:#24292f + linkStyle 5 stroke:#c297ff +``` -An editor integration of a build tool decides a great deal: which command a build runs, what a -test result means, how dangerous a cleanup is, which target a project builds for. Written once per -editor, those decisions drift apart, and a person who moves from one editor to another meets a -different tool. +## Highlights -mcpp-ide makes them once. Its backend, `mcpp-ide serve`, is a C++ program that reads only mcpp's -machine contract (event streams, result records, launch descriptors, JSON queries) and answers the -editors as an LSP server (JSON-RPC, protocol 2). The VS Code extension's views and pages are -mcpp-vscode 0.9.0's; the CLion plugin shows the same information in CLion's own trees, lists and -settings form (a graph in JCEF), and the Neovim plugin maps the answers onto buffers, floating -windows and the quickfix list. The editor plugins are `mide-plugins/` of this repository. Language -features of C++ files come from [mcppls](https://github.com/Sunrisepeak/mcpp-language-server); -those of mcpp.toml and build.mcpp come from the backend ([docs/rules.md](docs/rules.md)). +- **One answer everywhere**: what a build runs, how a test is reported and what a cleanup costs are decided by the backend +- **Only mcpp's contract**: no manifest parsing and no dependency resolution of its own +- **Tests as mcpp states them**: programs, cases, live results, diffs, metrics and Test Insights +- **Jobs in order**: one build at a time per project, a newer build replaces a waiting one, and cancelling ends cleanly +- **Safe cleanups**: each plan has a danger level, a preview and the confirmation that level requires -## Features +## Editors -| | VS Code (mcpp-vscode) | CLion (mcpp-clion) | Neovim (mcpp-nvim) | +| | VS Code 1.91+ | CLion 2026.1+ | Neovim 0.10+ | |---|---|---|---| -| Build, run, test | Tasks in a pseudoterminal showing mcpp's output | "mcpp" run configurations, PTY console, ▶ beside `main` | `:Mcpp build`, `test`: jobs streamed into a buffer; `:Mcpp run` in a terminal buffer | -| Test tree, re-run one test | Testing view: program, file, case; `@kind:bench` and a case's tags filter it | IDE test runner: a suite per program and per file | `:Mcpp test `: `mcpp://tests`, signs, the quickfix list | -| Test results | Live per case; a failure with both sides opens VS Code's diff; a case's line ends with its duration and metrics | Live per case; a comparison failure opens the IDE's diff; metrics in the case's output | Live per case; both sides in the buffer and the quickfix list; duration and metrics as virtual text | -| Test insights (the runs mcpp keeps) | "mcpp: Show Test Insights", a webview | The mcpp tool window's Test Insights tab (JCEF) | `:Mcpp test.insights`, a floating window | -| Debug | CodeLLDB, C/C++ (gdb, lldb), lldb-dap | CLion's GDB or LLDB | nvim-dap (codelldb, lldb-dap, cppdbg, gdb) | -| Diagnostics | Problems, from mcpp's located diagnostics | Console links to the reported location | `vim.diagnostic`, `:Mcpp problems` in the quickfix list | -| mcpp.toml, build.mcpp | Completion, hover, jumps and the rules' diagnostics from the backend (language client); Problems from mcpp | The same, through CLion's completion, documentation, annotations and go-to | The same, through `vim.lsp`; mcpp's problems in `vim.diagnostic` | -| Libraries, a package's page, graphs, cache, settings | mcpp-vscode's views and pages | Native trees and lists, a settings form from the registry, the graphs in JCEF | Text in floating windows, `vim.ui.select`; settings in `setup()` | -| Targets (target sets among them), pack | Quick picks | Popups | `vim.ui.select` | -| Language features | mcppls (installed with the extension) | mcppls CLion plugin (a dependency) | mcppls-nvim (`xlings install mcppls-nvim`) | - -CLion's **Settings | Tools | mcpp** validates finite numbers and their allowed ranges before -saving the form. Invalid input displays an error and leaves every stored value unchanged. -Entering a setting's default removes its stored override. - -Graph queries report build-database errors instead of showing an empty graph. After correcting -the reported problem, reopen the graph to retry. - -**Tests.** The editors show tests as `mcpp test` states them ([docs/architecture.md](docs/architecture.md), -"A test run, end to end"). A program of several files (`[test] programs = "directory"`) has its files as -children, each the part of the program a run gives a process. A case of the mtest test protocol carries its -kind, tags and the bounds on its metrics. Test Insights reads the runs mcpp keeps in `target/mtest`: the last -run, its failures and since when, each metric against its bound, the slowest and the flaky cases, and the -schedule with its critical path. What an editor shows follows the project's mcpp: - -| The project's mcpp | Adds | -|---|---| -| any | programs and their results | -| 2026.11.8.1 (`test-protocol`) | cases, their places and results, both sides of a failure | -| 2026.11.9.1 | the files of a program of several files; Test Insights over the kept runs | -| `test-parts`, `test-case-stream`, `test-metrics` ([mcpp#917](https://github.com/mcpp-community/mcpp/issues/917)) | the parts as mcpp states them, results as each case ends, metrics and their trends | - -A view that needs a feature the project's mcpp does not state is left out. The self-check -(`capabilities/explain`) says which mcpp states it. - -- **One answer everywhere** -- what a build runs, how a test is reported, what a cleanup costs: the backend's -- **Only mcpp's contract** -- no manifest parsing, no dependency resolution of its own -- **Jobs in order** -- one at a time per project, a newer build replaces a waiting one, cancelling ends cleanly -- **Platforms visible** -- each target with the platform that configures it and where every value came from -- **Safe cleanups** -- a plan with a danger level, a preview and the confirmation that level requires - -## Install - -### From an agent - -``` -Read agents/README.md of https://github.com/mcpp-community/mcpp-ide, then install mcpp-ide for -the editor I use (VS Code, CLion or Neovim) from its latest release, and check it with -`mcpp-ide self-check` on my mcpp project. +| **Install** | [Marketplace](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) · [Open VSX](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/35632-mcpp) | `xlings install mcpp-ide-nvim` | +| **Build · run · test** | tasks, Testing view | run configurations, test runner | `:Mcpp`, quickfix | +| **Debug** | CodeLLDB · C/C++ · lldb-dap | GDB · LLDB | nvim-dap | +| **Views** | libraries, graphs, cache, settings | native trees, forms, JCEF graphs | floating windows | +| **C++ (mcppls)** | [installed with it](https://marketplace.visualstudio.com/items?itemName=sunrisepeak.mcpp-language-server) | [mcppls plugin](https://plugins.jetbrains.com/plugin/35609) | `xlings install mcppls-nvim` | +| **Guide** | [mcpp-vscode](mide-plugins/vscode/README.md) | [mcpp-clion](mide-plugins/clion/README.md) | [mcpp-nvim](mide-plugins/nvim/README.md) | + +mcpp.toml and build.mcpp get completion, hover, jumps and diagnostics in every editor. The VS Code and +CLion packages carry the backend for Linux x64/arm64, macOS arm64 and Windows x64; offline, install the +`.vsix` or `.zip` from [Releases](https://github.com/mcpp-community/mcpp-ide/releases). Agents and other clients use `xlings install mcpp-ide`, then +`mcpp-ide serve`. Verify any install with `mcpp-ide self-check`; versions: [docs/versions.md](docs/versions.md). + +## With an agent + +Paste this into any coding agent. It reads only what your task needs, and asks you first when the +task is not clear. + +```text +Work with mcpp-ide (https://github.com/mcpp-community/mcpp-ide), the IDE layer of mcpp. +Read AGENTS.md first, then only what my task needs: +- install or use it: agents/README.md, verified with `mcpp-ide self-check` on my project +- understand it: docs/architecture.md, saying which layer owns what +- report a bug or propose a feature: .agents/skills/mcpp-ide-contributing, triage first + (mcpp, mcppls, backend or one plugin; fix or workaround), then draft the issue from its template +- change the code: that skill and .agents/skills/mcpp-ide-development, with tests that prove it +My task: +If it is empty or unclear, tell me in three lines what mcpp-ide is, then ask which of the above +I want, with one suggested first step for each. Ask me before opening an issue or a pull request, +pushing, or tagging. ``` -### From a release - -| Editor | Asset | Install | -|---|---|---| -| VS Code | the Marketplace (`mcpp-community.mcpp-vscode`), or `mcpp-vscode-.vsix` | search *mcpp*, or `code --install-extension mcpp-vscode-.vsix` | -| VS Code-compatible editors | Open VSX, or the `.vsix` | install the `.vsix` from the extensions view | -| CLion 2026.1+ | JetBrains Marketplace (`mcpp-clion`), or `mcpp-clion-.zip` | Settings → Plugins → Install Plugin from Disk; the mcppls CLion plugin (its package for this system carries the server) first | -| Neovim 0.10+ | `mide-plugins/nvim` of the release's source tree | `xlings install mcpp-ide-nvim` (the backend with it, set up at start); or the directory on the runtimepath and `require('mcpp').setup()` ([its README](mide-plugins/nvim/README.md)) | -| Agents, other clients | `mcpp-ide--openkal-bundle-all.tar.gz` (both images; okrun for Linux x64/arm64, macOS arm64, Windows x64), `mcpp-ide-.okb` with okrun, or `xlings install mcpp-ide` | run `bin/mcpp-ide serve` (`bin\mcpp-ide.exe` on Windows), or `okrun mcpp-ide-.okb serve` | - -Each editor package serves every system: it carries the backend as one ok-image bundle -(`backend/mcpp-ide.okb`, the x86_64 and aarch64 images on openkal-platform 0.24) and okrun for -Linux x64/arm64, macOS arm64 and Windows x64. The Neovim plugin carries none: it starts the -`mcpp-ide` command xlings installs (okrun on the same bundle). -VS Code and CLion check for the local build tool only when a user starts an action that needs it. - -**Versions.** A version is `X.Y.Z`. `X.Y`, the series, is shared by the backend and every plugin: a -plugin works with any backend of its series and refuses another, naming both versions and the -install that matches. The VS Code and CLion packages carry the backend, so a change of the backend is a -change of every package: it begins a series, every component at `X.Y.0`, tagged `vX.Y.0`, and the backend -is always its series' `X.Y.0`. `Z` is an editor plugin's own patch, tagged `vscode-`, `clion-` or -`nvim-vX.Y.Z`, which publishes that plugin alone over its series' backend: VS Code 1.3.2 and CLion 1.3.1 -both carry backend 1.3.0. A plugin's patch is refused when a path of the backend has changed since its -series' tag. A pull request runs the jobs of -the components it changes ([`.github/components.tsv`](.github/components.tsv)): a change of the backend runs -everything, a change of one plugin runs that plugin's jobs over the backend main built from the same inputs, -a change of the documentation its checks; `.github/` and any path the table does not name run everything. -The one required check is `ci`. -If `mcpp` is absent, they show one notification linking to the -[mcpp repository](https://github.com/mcpp-community/mcpp). - -### From source +## Development ```bash -mcpp build # the backend, the mock mcpp, mcpp-ide-dev -mcpp test # the backend's tests (mtest: tests/unit, e2e, cts, bench) -cd mide-plugins/vscode && npm ci && npm test # the extension's tests, the parity gates against 0.9.0 among them -npm run test:webui # the graph and tests pages in Chromium, over the backend -npm run package # dist/mcpp-vscode-.vsix -cd ../clion && gradle buildPlugin verifyPlugin # build/distributions/mcpp-clion-.zip -cd ../.. && nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # the Neovim plugin's tests +mcpp build && mcpp test # the backend, its mocks and mcpp-ide-dev +(cd mide-plugins/vscode && npm ci && npm test) # VS Code, the parity gates included +(cd mide-plugins/clion && gradle buildPlugin verifyPlugin) # CLion (xlings install gradle) +nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # Neovim ``` -`xlings install gradle` brings Gradle and its JDK. - -## Documentation - -- [docs/architecture.md](docs/architecture.md) -- the three layers and their boundaries -- [protocol/protocol.schema.json](protocol/protocol.schema.json) -- the backend's methods and notifications -- [protocol/mcpp-contract.schema.json](protocol/mcpp-contract.schema.json) -- the part of mcpp's contract it reads -- [spec/](spec) -- settings, commands, translations: the source of the editors' declarations and command tables -- [mide-plugins/vscode/README.md](mide-plugins/vscode/README.md), - [mide-plugins/clion/README.md](mide-plugins/clion/README.md), - [mide-plugins/nvim/README.md](mide-plugins/nvim/README.md) +The environment, the tests for each component, common changes and the release procedure are in the +[development skill](.agents/skills/mcpp-ide-development/SKILL.md). ## Contributing -The backend is C++23 with modules, built by mcpp; the repository's tools are a program of it -(`mcpp-ide-dev`: fixture capture, the editors' declarations, the translation check). Generated -files are not committed. A change to what mcpp reports starts with `mcpp-ide-dev capture` and the -diff in `protocol/fixtures`. - -A release runs the repository CI, publishes the checked archives of what its -tag names (`.github/scripts/release-plan.sh`) and `SHA256SUMS` on GitHub, then -independently submits the same VSIX to Open VSX and the same CLion ZIP to -JetBrains Marketplace when the release carries them. The JetBrains job checks the -archive digest, plugin XML ID and version before upload and retains a receipt; -Marketplace availability follows JetBrains review. `OPENVSX_TOKEN` and -`JETBRAINS_TOKEN` are repository secrets. The Visual Studio Marketplace upload -remains manual. +Every change starts with an issue ([templates](https://github.com/mcpp-community/mcpp-ide/issues/new/choose)) +and goes through a pull request. The rules are in [AGENTS.md](AGENTS.md): who owns what, how to +triage (core or plugin, fix or workaround), versions and code. The procedure for people and agents +is in the [contributing skill](.agents/skills/mcpp-ide-contributing/SKILL.md). Questions go to the +[forum](https://forum.d2learn.org/category/20). ## License -Apache-2.0 +[Apache-2.0](LICENSE) diff --git a/README.zh-CN.md b/README.zh-CN.md index cfbd485..7dc8e46 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,126 +1,109 @@ -# mcpp-ide - mcpp 的 IDE 层 +
-> 所有编辑器共用一个后端来对待 [mcpp](https://github.com/mcpp-community/mcpp) 工程:VS Code(mcpp-vscode)、 -> CLion(mcpp-clion)与 Neovim(mcpp-nvim)的构建、运行、测试、调试、打包行为一致 +# mcpp-ide + +**所有编辑器共用一个后端来对待 [mcpp](https://github.com/mcpp-community/mcpp) 工程** + +VS Code · CLion · Neovim 的构建、运行、测试、调试、打包行为一致 + +[![Release](https://img.shields.io/github/v/release/mcpp-community/mcpp-ide)](https://github.com/mcpp-community/mcpp-ide/releases) +[![CI](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml) +[![VS Code](https://img.shields.io/badge/VS_Code-mcpp--vscode-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) +[![Open VSX](https://img.shields.io/open-vsx/v/mcpp-community/mcpp-vscode?label=Open%20VSX)](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) +[![JetBrains](https://img.shields.io/jetbrains/plugin/v/io.github.mcpp-community.mcpp-clion?label=CLion)](https://plugins.jetbrains.com/plugin/35632-mcpp) +[![C++23](https://img.shields.io/badge/C%2B%2B-23_modules-blue.svg)](https://en.cppreference.com/w/cpp/23) +[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE) [English](README.md) | **简体中文** -[文档](docs/README.md) · [协议](protocol/protocol.schema.json) · [设置](spec/settings.json) · -[面向 Agent](agents/README.md) · [发布](https://github.com/mcpp-community/mcpp-ide/releases) +[文档](docs/README.md) · [架构](docs/architecture.md) · [协议](protocol/protocol.schema.json) · +[面向 Agent](agents/README.md) · [贡献](AGENTS.md) · [发布](https://github.com/mcpp-community/mcpp-ide/releases) + +
+ +构建工具的编辑器集成要做许多决定:构建运行哪条命令、测试结果是什么含义、一次清理有多危险。每个编辑器各写一遍, +这些决定就会分歧。mcpp-ide 只做一次:后端 `mcpp-ide serve` 只读取 mcpp 的机器契约,以 LSP 服务器回答所有编辑器, +各插件再用编辑器自己的界面呈现这些回答。 + +```mermaid +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 26, "rankSpacing": 56, "padding": 14}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#54aeff", "edgeLabelBackground": "#ffffff"}}}%% +flowchart TB + vscode("VS Code
mcpp-vscode"):::client + clion("CLion
mcpp-clion"):::client + nvim("Neovim
mcpp-nvim"):::client + agent("Agents
mcpp-ide skill"):::client + serve("mcpp-ide serve
LSP · 所有决定"):::core + mcppls("mcppls
C++ 语言服务器"):::ls + mcpp("mcpp
构建 · 测试 · 打包"):::tool + vscode & clion & nvim & agent --> serve + serve -- 契约 --> mcpp + serve -. 状态 .-> mcppls + classDef client fill:#ffffff,stroke:#54aeff,color:#0550ae + classDef core fill:#0969da,stroke:#0550ae,color:#ffffff + classDef ls fill:#fbefff,stroke:#c297ff,color:#6639ba + classDef tool fill:#f6f8fa,stroke:#8c959f,color:#24292f + linkStyle 5 stroke:#c297ff +``` -构建工具的编辑器集成要做许多决定:构建运行哪条命令、测试结果是什么含义、一次清理有多危险、工程为哪个目标构建。 -每个编辑器各写一遍,这些决定就会分歧;从一个编辑器换到另一个,用户遇到的就是另一个工具。 +## 特性 -mcpp-ide 只做一次。它的后端 `mcpp-ide serve` 是一个 C++ 程序,只读取 mcpp 的机器契约(事件流、结果记录、启动描述、 -JSON 查询),以 LSP 服务器(JSON-RPC,协议 2)回答编辑器。VS Code 扩展的视图与页面即 mcpp-vscode 0.9.0 的视图与页面; -CLion 插件以 CLion 自己的树、列表与设置表单显示同样的信息(图在 JCEF 中);Neovim 插件把这些回答映射到缓冲区、浮动窗口与 -quickfix 列表。各编辑器插件位于本仓库的 `mide-plugins/`。C++ 文件的语言功能来自 -[mcppls](https://github.com/Sunrisepeak/mcpp-language-server);mcpp.toml 与 build.mcpp 的语言功能来自后端 -([docs/rules.md](docs/rules.md))。 +- **处处同一答案**:构建运行什么、测试如何报告、清理的代价,都由后端决定 +- **只读 mcpp 的契约**:不自行解析清单,不自行解析依赖 +- **测试即 mcpp 所述**:程序、用例、实时结果、差异对比、指标与 Test Insights +- **任务有序**:每个工程同一时间一个构建,新构建替换等待中的构建,取消会正常结束 +- **安全清理**:每个计划都带危险等级与预览,并按该等级要求确认 -## 功能 +## 编辑器 -| | VS Code(mcpp-vscode) | CLion(mcpp-clion) | Neovim(mcpp-nvim) | +| | VS Code 1.91+ | CLion 2026.1+ | Neovim 0.10+ | |---|---|---|---| -| 构建、运行、测试 | 伪终端中的任务,显示 mcpp 自身的输出 | "mcpp" 运行配置、PTY 控制台、`main` 旁的 ▶ | `:Mcpp build`、`test`:任务输出流入缓冲区;`:Mcpp run` 在终端缓冲区中运行 | -| 测试树、单个测试重跑 | 测试视图:程序、文件、用例;`@kind:bench` 与用例的标签可筛选 | IDE 测试运行器:每个程序、每个文件一个套件 | `:Mcpp test `:`mcpp://tests`、标记、quickfix 列表 | -| 测试结果 | 逐用例实时显示;陈述两侧的失败可打开 VS Code 的差异视图;用例所在行末显示耗时与指标 | 逐用例实时显示;比较型失败可打开 IDE 的差异视图;指标在用例输出中 | 逐用例实时显示;两侧写入缓冲区与 quickfix 列表;耗时与指标以虚拟文本显示 | -| 测试洞察(mcpp 保留的运行) | "mcpp: Show Test Insights",一个 webview | mcpp 工具窗口的 Test Insights 页(JCEF) | `:Mcpp test.insights`,浮动窗口 | -| 调试 | CodeLLDB、C/C++(gdb、lldb)、lldb-dap | CLion 的 GDB 或 LLDB | nvim-dap(codelldb、lldb-dap、cppdbg、gdb) | -| 诊断 | 问题面板,来自 mcpp 带位置的诊断 | 控制台链接到报告的位置 | `vim.diagnostic`,`:Mcpp problems` 填入 quickfix 列表 | -| mcpp.toml、build.mcpp | 补全、悬停、跳转与规则诊断来自后端(语言客户端);问题来自 mcpp | 同上,经 CLion 的补全、文档、标注与跳转 | 同上,经 `vim.lsp`;mcpp 的问题在 `vim.diagnostic` | -| 库、包页面、依赖图、缓存、设置 | mcpp-vscode 的视图与页面 | 原生的树与列表、由设置注册表生成的设置表单、JCEF 中的图 | 浮动窗口中的文本、`vim.ui.select`;设置在 `setup()` 中 | -| 目标(含目标集合)、打包 | 快速选择 | 弹出列表 | `vim.ui.select` | -| 语言功能 | mcppls(随扩展一并安装) | mcppls CLion 插件(依赖) | mcppls-nvim(`xlings install mcppls-nvim`) | - -CLion 的 **Settings | Tools | mcpp** 在保存表单前检查数值是否有限、是否处于允许范围内。 -无效输入会显示错误,并保持所有已存储的值不变。输入某项设置的默认值会移除其存储覆盖。 - -图查询失败时显示构建数据库错误。修正所报告的问题后,重新打开图即可重试。 - -**测试。** 编辑器按 `mcpp test` 的陈述显示测试([docs/architecture.md](docs/architecture.md), -"A test run, end to end")。多文件程序(`[test] programs = "directory"`)以其文件为子项,每个文件是一次运行中 -单独成进程的那一部分。mtest 测试协议的用例带有其类别、标签与指标上下限。测试洞察读取 mcpp 保存在 -`target/mtest` 的运行:最近一次运行、其失败及起始时间、各指标与上下限、最慢与不稳定的用例、调度与关键路径。 -编辑器所显示的内容取决于工程的 mcpp: - -| 工程的 mcpp | 增加 | -|---|---| -| 任意版本 | 程序及其结果 | -| 2026.11.8.1(`test-protocol`) | 用例、其位置与结果、失败的两侧 | -| 2026.11.9.1 | 多文件程序的文件;基于已保留运行的测试洞察 | -| `test-parts`、`test-case-stream`、`test-metrics`([mcpp#917](https://github.com/mcpp-community/mcpp/issues/917)) | 由 mcpp 陈述的部分、逐用例结束时的结果、指标及其趋势 | - -工程的 mcpp 未声明某视图所需的能力时,该视图不显示;自检(`capabilities/explain`)说明哪个版本的 mcpp 声明了它。 - -- **处处同一答案**——构建运行什么、测试如何报告、清理的代价:都由后端决定 -- **只读 mcpp 的契约**——不自行解析清单,不自行解析依赖 -- **任务有序**——每个工程同一时间一个任务,新构建替换等待中的构建,取消会正常结束 -- **平台可见**——每个目标连同配置它的平台,以及每个值的来源 -- **安全清理**——带危险等级与预览的计划,按该等级要求确认 - -## 安装 - -### 让 Agent 安装 - -``` -阅读 https://github.com/mcpp-community/mcpp-ide 的 agents/README.md,为我使用的编辑器(VS Code、CLion 或 Neovim) -从最新发布安装 mcpp-ide,并在我的 mcpp 工程上用 `mcpp-ide self-check` 检查。 +| **安装** | [Marketplace](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) · [Open VSX](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/35632-mcpp) | `xlings install mcpp-ide-nvim` | +| **构建 · 运行 · 测试** | 任务、测试视图 | 运行配置、测试运行器 | `:Mcpp`、quickfix | +| **调试** | CodeLLDB · C/C++ · lldb-dap | GDB · LLDB | nvim-dap | +| **视图** | 库、依赖图、缓存、设置 | 原生树、表单、JCEF 图 | 浮动窗口 | +| **C++(mcppls)** | [随扩展安装](https://marketplace.visualstudio.com/items?itemName=sunrisepeak.mcpp-language-server) | [mcppls 插件](https://plugins.jetbrains.com/plugin/35609) | `xlings install mcppls-nvim` | +| **指南** | [mcpp-vscode](mide-plugins/vscode/README.zh-CN.md) | [mcpp-clion](mide-plugins/clion/README.md) | [mcpp-nvim](mide-plugins/nvim/README.md) | + +mcpp.toml 与 build.mcpp 在所有编辑器中都有补全、悬停、跳转与诊断。VS Code 与 CLion 的包自带后端,覆盖 +Linux x64/arm64、macOS arm64 与 Windows x64;离线时从[发布页](https://github.com/mcpp-community/mcpp-ide/releases)安装 `.vsix` 或 `.zip`。Agent 与其他 +客户端使用 `xlings install mcpp-ide`,然后运行 `mcpp-ide serve`。安装后用 `mcpp-ide self-check` 验证;版本见 +[docs/versions.md](docs/versions.md)。 + +## 使用 Agent + +把下面这段粘贴给任意编程 Agent。它只读任务需要的文档;任务不明确时,会先询问你。 + +```text +协助我处理 mcpp-ide(https://github.com/mcpp-community/mcpp-ide),即 mcpp 的 IDE 层。 +先读 AGENTS.md,再只读我的任务需要的文档: +- 安装或使用:agents/README.md,并在我的工程上用 `mcpp-ide self-check` 验证 +- 了解项目:docs/architecture.md,说明各层分别负责什么 +- 报告问题或提出功能:.agents/skills/mcpp-ide-contributing,先分诊(mcpp、mcppls、后端还是某个插件; + 修复还是 workaround),再按模板起草 issue +- 修改代码:上述 skill 与 .agents/skills/mcpp-ide-development,并给出能证明改动的测试 +我的任务:<在此描述,或留空> +若留空或不明确,先用三行说明 mcpp-ide 是什么,再问我想做上面哪一项,并为每项给出建议的第一步。 +开 issue、PR,推送或打 tag 之前先征得我的同意。 ``` -### 从 release 安装 - -| 编辑器 | 资产 | 安装 | -|---|---|---| -| VS Code | Marketplace(`mcpp-community.mcpp-vscode`),或 `mcpp-vscode-.vsix` | 搜索 *mcpp*,或 `code --install-extension mcpp-vscode-.vsix` | -| 兼容 VS Code 的编辑器 | Open VSX,或 `.vsix` | 在扩展视图中安装 `.vsix` | -| CLion 2026.1+ | JetBrains Marketplace(`mcpp-clion`),或 `mcpp-clion-.zip` | Settings → Plugins → Install Plugin from Disk;先安装 mcppls CLion 插件(本系统的包自带服务端) | -| Neovim 0.10+ | release 源码树中的 `mide-plugins/nvim` | `xlings install mcpp-ide-nvim` 与 `xlings install mcpp-ide`,再 `require('mcpp').setup()`;或把该目录加入 runtimepath([其 README](mide-plugins/nvim/README.md)) | -| Agent、其他客户端 | `mcpp-ide--openkal-bundle-all.tar.gz`(两个架构的映像;Linux x64/arm64、macOS arm64、Windows x64 的 okrun),携带 okrun 的 `mcpp-ide-.okb`,或 `xlings install mcpp-ide` | 运行 `bin/mcpp-ide serve`(Windows 上为 `bin\mcpp-ide.exe`),或 `okrun mcpp-ide-.okb serve` | - -每个编辑器包都服务全部系统:后端以一个 ok 映像包(`backend/mcpp-ide.okb`,openkal-platform 0.24 上的 -x86_64 与 aarch64 映像)加上 Linux x64/arm64、macOS arm64、Windows x64 的 okrun 携带。Neovim 插件不携带后端: -它启动 xlings 安装的 `mcpp-ide` 命令(由 okrun 运行同一个映像包)。 -VS Code 和 CLion 仅在用户主动执行依赖本地构建工具的操作时检查 `mcpp`;未安装时只提示一次,并提供 -[mcpp 开源仓库](https://github.com/mcpp-community/mcpp)链接。 - -**版本。** 版本为 `X.Y.Z`。`X.Y` 是系列,由后端与全部插件共享:插件与同系列的任何后端配合,遇到其他系列时拒绝, -并写出双方的版本与对应的安装方法。VS Code 与 CLion 的包内含后端,因此后端的改动即是全部包的改动:它开启一个新系列, -全部组件为 `X.Y.0`,标签为 `vX.Y.0`;后端始终是所属系列的 `X.Y.0`。`Z` 是编辑器插件自己的补丁,标签为 `vscode-`、 -`clion-` 或 `nvim-vX.Y.Z`,只发布该插件,所带的后端仍是本系列的那一份:VS Code 1.3.2 与 CLion 1.3.1 都带后端 1.3.0。 -自本系列的标签以来后端的任何路径有改动时,插件补丁被拒绝。 -拉取请求只运行它所改动的组件的作业([`.github/components.tsv`](.github/components.tsv)):后端的改动运行全部作业; -一个插件的改动只运行该插件的作业,所用的后端是 main 以相同输入构建的那一份;文档的改动只运行文档的检查;`.github/` -与表中没有列出的路径运行全部作业。唯一必需的检查是 `ci`。 - -### 从源码构建 +## 开发 ```bash -mcpp build # 后端、mock mcpp、mcpp-ide-dev -mcpp test # 后端测试(mtest:tests/unit、e2e、cts、bench) -cd mide-plugins/vscode && npm ci && npm test # 扩展的测试,含对 0.9.0 的一致性门 -npm run test:webui # 图页面与测试页面在 Chromium 中、经后端运行 -npm run package # dist/mcpp-vscode-.vsix -cd ../clion && gradle buildPlugin verifyPlugin # build/distributions/mcpp-clion-.zip -cd ../.. && nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # Neovim 插件的测试 +mcpp build && mcpp test # 后端、mock 与 mcpp-ide-dev +(cd mide-plugins/vscode && npm ci && npm test) # VS Code,含 parity 门禁 +(cd mide-plugins/clion && gradle buildPlugin verifyPlugin) # CLion(xlings install gradle) +nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # Neovim ``` -`xlings install gradle` 会一并带来 Gradle 及其 JDK。 - -## 文档 - -- [docs/architecture.md](docs/architecture.md)——三层及其边界 -- [protocol/protocol.schema.json](protocol/protocol.schema.json)——后端的方法与通知 -- [protocol/mcpp-contract.schema.json](protocol/mcpp-contract.schema.json)——后端读取的 mcpp 契约部分 -- [spec/](spec)——设置、命令、翻译:各编辑器声明与命令表的唯一来源 -- [mide-plugins/vscode/README.md](mide-plugins/vscode/README.md)、[mide-plugins/clion/README.md](mide-plugins/clion/README.md)、 - [mide-plugins/nvim/README.md](mide-plugins/nvim/README.md) +环境、各组件的测试、常见改动与发布流程见[开发 skill](.agents/skills/mcpp-ide-development/SKILL.md)。 ## 参与贡献 -后端是用 mcpp 构建的 C++23 模块程序;仓库的工具是它的一个程序(`mcpp-ide-dev`:抓取 fixture、生成编辑器声明、 -检查翻译)。生成物不提交。mcpp 的输出有变化时,从 `mcpp-ide-dev capture` 与 `protocol/fixtures` 的差异开始。 +每个改动都从 issue 开始([模板](https://github.com/mcpp-community/mcpp-ide/issues/new/choose)),并通过 PR 合入。 +规则见 [AGENTS.md](AGENTS.md):谁负责什么、如何分诊(core 还是插件,修复还是 workaround)、版本与代码规范。 +面向人与 Agent 的完整流程见[贡献 skill](.agents/skills/mcpp-ide-contributing/SKILL.md)。问题与讨论请到 +[论坛](https://forum.d2learn.org/category/20)。 ## 许可证 -Apache-2.0 +[Apache-2.0](LICENSE) diff --git a/agents/README.md b/agents/README.md index db130ee..5e0af04 100644 --- a/agents/README.md +++ b/agents/README.md @@ -22,13 +22,20 @@ and its contract, mcppls, xlings, trust. ## A session -``` -→ initialize {"editor": "cli", "workspaceFolders": ["/path/to/project"]} -← result {"projects": [...], "mcpp": {...}, "languageService": {...}, "checks": [...]} -→ test/list {"root": "/path/to/project"} -→ job/start {"kind": "test", "root": "/path/to/project", "color": false} -← job/started, job/output, job/plan, test/result ..., test/summary, job/finished -→ shutdown, then the notification exit +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#ddf4ff", "actorBorder": "#54aeff", "actorTextColor": "#0550ae", "actorLineColor": "#b6e3ff", "signalColor": "#54aeff", "signalTextColor": "#57606a", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fbefff", "noteBorderColor": "#c297ff", "noteTextColor": "#6639ba", "labelBoxBkgColor": "#ddf4ff", "labelBoxBorderColor": "#54aeff", "labelTextColor": "#0550ae", "loopTextColor": "#57606a"}}}%% +sequenceDiagram + participant A as Agent + participant B as mcpp-ide serve + A->>B: initialize {editor: "cli", workspaceFolders: [dir]} + B-->>A: projects, mcpp, languageService, checks + A->>B: test/list {root} + B-->>A: programs, their files and parts + A->>B: job/start {kind: "test", root, color: false} + B-->>A: job/started, job/output, job/plan + B-->>A: test/result ..., test/summary + B-->>A: job/finished + A->>B: shutdown, then the notification exit ``` Each message is framed as in LSP: `Content-Length: \r\n\r\n`. diff --git a/docs/README.md b/docs/README.md index a692e64..44099fd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,7 @@ # mcpp-ide documentation - [architecture.md](architecture.md) -- the three layers, what each holds, and how a request travels +- [versions.md](versions.md) -- series and tags, the project's mcpp and what each of its features adds - [rules.md](rules.md) -- mcpp.toml and build.mcpp: completion, hover, jumps and diagnostics over LSP - [../protocol/protocol.schema.json](../protocol/protocol.schema.json) -- the backend's protocol - [../agents/README.md](../agents/README.md) -- driving the backend from an agent diff --git a/docs/architecture.md b/docs/architecture.md index c7a9e30..e8b3046 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -62,6 +62,26 @@ mcppls what a compiler answers better. ## A build, end to end +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#ddf4ff", "actorBorder": "#54aeff", "actorTextColor": "#0550ae", "actorLineColor": "#b6e3ff", "signalColor": "#54aeff", "signalTextColor": "#57606a", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fbefff", "noteBorderColor": "#c297ff", "noteTextColor": "#6639ba", "labelBoxBkgColor": "#ddf4ff", "labelBoxBorderColor": "#54aeff", "labelTextColor": "#0550ae", "loopTextColor": "#57606a"}}}%% +sequenceDiagram + autonumber + participant E as Editor plugin + participant B as mcpp-ide serve + participant M as mcpp + participant L as mcppls + E->>B: job/start {kind: "build", root} + Note over B: queued on the project's lane + B->>M: mcpp build --message-format json + M-->>B: narration and events + B-->>E: job/output, job/plan, job/progress, job/diagnostic, job/artifact + M-->>B: the closing envelope + B-->>E: job/finished + Note over M: writes the result record + B-->>E: result/changed (the watcher) + Note over L: reads the same record, refreshes +``` + 1. The user runs Build. The adapter sends `mcpp-ide/job/start {kind: "build", root}`. 2. The backend queues it on the project's lane and runs `mcpp build --message-format json` with `MCPP_CLIENT`, colour for a terminal, and `MCPP_DENY_EFFECTS` in an untrusted workspace. @@ -80,6 +100,35 @@ builds and runs the programs and states their cases and results; a framework is program is written with, and the backend knows none by name. What a framework offers beyond the base, it states of itself (`mcpp test --guide`, B6). +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#ddf4ff", "actorBorder": "#54aeff", "actorTextColor": "#0550ae", "actorLineColor": "#b6e3ff", "signalColor": "#54aeff", "signalTextColor": "#57606a", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fbefff", "noteBorderColor": "#c297ff", "noteTextColor": "#6639ba", "labelBoxBkgColor": "#ddf4ff", "labelBoxBorderColor": "#54aeff", "labelTextColor": "#0550ae", "loopTextColor": "#57606a"}}}%% +sequenceDiagram + autonumber + participant E as Editor plugin + participant B as mcpp-ide serve + participant M as mcpp + participant S as test session + E->>B: test/list + B->>M: mcpp test --list + B-->>E: programs, files, parts + E->>B: test/cases + B->>M: mcpp test --cases + B-->>E: the cases, kept until the project changes + alt a framework states a session and mcpp gives launches + E->>B: test/runCases + B->>S: started once per project (JSON-RPC) + S-->>B: build, cases, end + B-->>E: test/caseEvent ..., job/finished + else otherwise + E->>B: job/start {kind: "test"} + B->>M: mcpp test --message-format json + M-->>B: records + B-->>E: test/result, test/caseEvent ..., job/finished + end + E->>B: test/insights + B-->>E: the runs mcpp keeps (target/mtest) +``` + 1. `test/list` runs `mcpp test --list` and answers each program with its files, its `main` and its parts. A protocol program of several files (`[test] programs = "directory"`) runs as one process per file, `/`. mcpp states the parts with `test-parts`; before it, the backend derives them as @@ -128,6 +177,19 @@ editor package carries that bundle and the runner that starts it on each system: | `backend/mcpp-ide.okb` | the x86_64 and aarch64 images | | | `backend/okrun/-/okrun[.exe]` | okrun for `linux-x86_64`, `linux-aarch64`, `macos-aarch64`, `windows-x86_64`, from the universal self-contained package (`--mode self-contained --systems all`: each okrun built over the platform's hosted arrangement); one command packs both, `mcpp pack mcpp-ide --target openkal --mode self-contained --systems all --pkg-format tar,okb`, and the package's `runs_on.self` names the systems it runs on | `okrun mcpp-ide.okb serve`: the okrun carried for this system, else okrun on PATH | +```mermaid +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 26, "rankSpacing": 56, "padding": 14}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#54aeff", "edgeLabelBackground": "#ffffff"}}}%% +flowchart LR + cfg("1 · mcpp.ide.backendPath"):::tool + pkg("2 · the package's .okb
run by okrun"):::core + inst("3 · mcpp-ide
from xlings or PATH"):::client + cfg -- unset --> pkg -- not carried --> inst + classDef client fill:#ffffff,stroke:#54aeff,color:#0550ae + classDef core fill:#0969da,stroke:#0550ae,color:#ffffff + classDef ls fill:#fbefff,stroke:#c297ff,color:#6639ba + classDef tool fill:#f6f8fa,stroke:#8c959f,color:#24292f +``` + Before it, a configured `mcpp.ide.backendPath` (a program or an `.okb`) is used; after it, an installed `mcpp-ide` (xlings, whose command runs okrun on its bundle) or one on PATH. The Neovim plugin carries no package of the backend: it starts setup()'s `backend`, else `mcpp-ide` on PATH, diff --git a/docs/versions.md b/docs/versions.md new file mode 100644 index 0000000..2f99b90 --- /dev/null +++ b/docs/versions.md @@ -0,0 +1,42 @@ +# Versions and compatibility + +## Series + +A version is `X.Y.Z`. The series `X.Y` is shared by the backend and every plugin. A plugin works +with any backend of its series and refuses one from another series, naming both versions and the +install that matches. + +The VS Code and CLion packages carry the backend, so a change to the backend changes every package. +It therefore begins a new series: every component moves to `X.Y.0`, tagged `vX.Y.0`, and the +backend is always its series' `X.Y.0`. `Z` is an editor plugin's own patch, tagged +`vscode-vX.Y.Z`, `clion-vX.Y.Z` or `nvim-vX.Y.Z`. Such a tag publishes that plugin alone over its +series' backend; VS Code 1.3.2 and CLion 1.3.1, for example, both carry backend 1.3.0. A plugin +patch is refused when any backend path has changed since its series' tag +([release-plan.sh](../.github/scripts/release-plan.sh)). + +## The project's mcpp + +Each project is described by the mcpp that builds it: the one its `.xlings.json` pins, or +`mcpp.path`. A feature is enabled by what that mcpp states (`features`). An earlier release is +described by a table frozen at that release, never by comparing versions. A view that needs a +feature the project's mcpp does not state is left out, and the self-check (`capabilities/explain`) +names the mcpp that states it. If `mcpp` is absent, VS Code and CLion show one notification linking +to the [mcpp repository](https://github.com/mcpp-community/mcpp); they look for mcpp only when an +action needs it. + +## Tests + +The editors show tests as `mcpp test` states them ([architecture.md](architecture.md), "A test +run, end to end"). A program made of several files (`[test] programs = "directory"`) lists its +files as children, each file being the part of the program that a run gives a process. A case of +the mtest protocol carries its kind, its tags and the bounds on its metrics. Test Insights reads +the runs mcpp keeps in `target/mtest`: the last run, its failures and when they began, each metric +against its bound, the slowest and the flaky cases, and the schedule with its critical path. + +| The project's mcpp | Adds | +|---|---| +| any | programs and their results | +| 2026.11.8.1 (`test-protocol`) | cases, their places and results, both sides of a failure | +| 2026.11.9.1 | the files of a multi-file program; Test Insights over the kept runs | +| `test-parts`, `test-case-stream`, `test-metrics` ([mcpp#917](https://github.com/mcpp-community/mcpp/issues/917)) | the parts as mcpp states them, results as each case ends, metrics and their trends | +| `test-launch-records` (2026.11.10.1) | cases run through a framework's test session |