diff --git a/en/clice/dev/test-and-debug.md b/en/clice/dev/test-and-debug.md index cc6c4bf..3fab5cd 100644 --- a/en/clice/dev/test-and-debug.md +++ b/en/clice/dev/test-and-debug.md @@ -62,6 +62,21 @@ pixi run test # runs unit + integration + smoke pixi run test Debug # all tests with debug build ``` +## Editor E2E Tests + +Smoke tests that run real editors (headless Neovim and VSCode) against a locally built clice binary, covering startup, first diagnostics, hover, definition and completion on two fixtures (including a C++20 modules project). CI runs them in the `test-editor` job on Linux with the latest stable editor releases, on purpose unpinned: the job exists to catch breakage caused by new editor versions. + +```bash +$ pixi run build # build/RelWithDebInfo/bin/clice +$ pixi run -e editor editor-test # nvim + vscode, both fixtures +``` + +Prerequisites outside the pixi env: + +- `nvim` (stable) on `PATH` for `nvim-e2e`. +- A system `cmake`/`ninja`/`clang` for `editor-prepare` to configure the CMake-based module fixture (same assumption the integration tests make). +- A display (or `xvfb-run`) plus the usual Electron system libraries for `vscode-e2e`. + ## Debug If you want to attach a debugger to clice, start it in socket mode independently, then connect a client. diff --git a/en/clice/guide/editors.md b/en/clice/guide/editors.md new file mode 100644 index 0000000..63991c5 --- /dev/null +++ b/en/clice/guide/editors.md @@ -0,0 +1,103 @@ +# Editor Setup + +clice implements the [Language Server Protocol](https://microsoft.github.io/language-server-protocol), so any editor with an LSP client can use it. The editors below fall into two groups: editors with an official clice plugin, and editors configured through their generic LSP client. + +All setups assume: + +- The `clice` executable is on your `PATH` (or use an absolute path in the snippets below). +- Your project provides a `compile_commands.json` (by default clice searches the workspace root and `build/`). + +## Official Plugins + +### Visual Studio Code + +Install the [clice extension](https://marketplace.visualstudio.com/items?itemName=ykiko.clice-vscode) from the marketplace. The extension downloads a clice binary automatically; set `clice.executable` to use your own build. + +### Neovim + +clice ships an LSP config for Neovim ≥ 0.11 in [`editors/nvim`](https://github.com/clice-io/clice/tree/main/editors/nvim). Copy `doc/clice.lua` into your config's `lsp/` directory, then enable it: + +```lua +vim.lsp.enable('clice') +``` + +### Zed + +The Zed extension lives in [`editors/zed`](https://github.com/clice-io/clice/tree/main/editors/zed). + +## Generic LSP Clients + +### Helix + +Add to `~/.config/helix/languages.toml`: + +```toml +[language-server.clice] +command = "clice" +args = ["server"] + +[[language]] +name = "cpp" +language-servers = ["clice"] + +[[language]] +name = "c" +language-servers = ["clice"] +``` + +### Emacs + +With the built-in eglot: + +```elisp +(with-eval-after-load 'eglot + (add-to-list 'eglot-server-programs + '((c-mode c-ts-mode c++-mode c++-ts-mode) + . ("clice" "server")))) +``` + +### Sublime Text + +Install the [LSP package](https://packagecontrol.io/packages/LSP), then add to its settings: + +```json +{ + "clients": { + "clice": { + "enabled": true, + "command": ["clice", "server"], + "selector": "source.c | source.c++" + } + } +} +``` + +### Kate + +Open `Settings → Configure Kate → LSP Client → User Server Settings` and add: + +```json +{ + "servers": { + "c": { + "command": ["clice", "server"], + "url": "https://github.com/clice-io/clice", + "highlightingModeRegex": "^(C|C\\+\\+)$" + } + } +} +``` + +### Vim + +With [vim-lsp](https://github.com/prabirshrestha/vim-lsp): + +```vim +if executable('clice') + au User lsp_setup call lsp#register_server({ + \ 'name': 'clice', + \ 'cmd': {server_info->['clice', 'server']}, + \ 'allowlist': ['c', 'cpp'], + \ }) +endif +``` diff --git a/en/clice/guide/quick-start.md b/en/clice/guide/quick-start.md index 00e5968..bad70ac 100644 --- a/en/clice/guide/quick-start.md +++ b/en/clice/guide/quick-start.md @@ -6,33 +6,7 @@ clice implements the [Language Server Protocol](https://microsoft.github.io/lang Beyond the standard protocol, clice also supports some protocol extensions. For better integration, using a dedicated clice plugin is recommended. -### Visual Studio Code - -Install the [clice](https://marketplace.visualstudio.com/items?itemName=ykiko.clice-vscode) extension from the Marketplace. It handles downloading the clice binary automatically. - -To use a custom binary, set `clice.executable` in your workspace settings: - -```jsonc -{ - "clice.executable": "/path/to/clice", -} -``` - -### Vim/Neovim - -Add the clice Neovim plugin to your runtime path: - -```lua --- lazy.nvim -{ dir = "/path/to/clice/editors/nvim" } - --- or manually -vim.opt.rtp:append("/path/to/clice/editors/nvim") -``` - -### Others - -Other editors don't have dedicated clice plugins yet (contributions welcome!). To use clice in them, install the binary and configure your editor's LSP client to run `clice server`. +See [Editor Setup](./editors.md) for per-editor instructions: official plugins for Visual Studio Code, Neovim and Zed, plus configuration snippets for editors with generic LSP clients (Helix, Emacs, Sublime Text, Kate, Vim). ## Installation diff --git a/zh/clice/dev/test-and-debug.md b/zh/clice/dev/test-and-debug.md index 6d13e6a..eb80b92 100644 --- a/zh/clice/dev/test-and-debug.md +++ b/zh/clice/dev/test-and-debug.md @@ -62,6 +62,21 @@ pixi run test # 单元 + 集成 + 冒烟 pixi run test Debug # debug 构建的全部测试 ``` +## Editor E2E Tests + +冒烟测试，用真实编辑器（无头 Neovim 和 VSCode）对本地构建的 clice 二进制进行测试，在两个 fixture（包括一个 C++20 模块项目）上覆盖启动、首批诊断、hover、definition 和 completion。CI 在 Linux 的 `test-editor` job 中使用最新 stable 版编辑器运行，刻意不固定版本：这个 job 的目的就是发现新版编辑器导致的破坏。 + +```bash +$ pixi run build # build/RelWithDebInfo/bin/clice +$ pixi run -e editor editor-test # nvim + vscode，两个 fixture +``` + +pixi 环境之外的依赖： + +- `nvim`（stable）在 `PATH` 中，供 `nvim-e2e` 使用。 +- 系统的 `cmake`/`ninja`/`clang`，供 `editor-prepare` 配置基于 CMake 的模块 fixture（与集成测试相同的假设）。 +- 显示环境（或 `xvfb-run`）以及 Electron 所需的系统库，供 `vscode-e2e` 使用。 + ## 调试 如果想在 clice 上附加调试器，推荐先以 socket 模式单独启动 clice，然后连接客户端。 diff --git a/zh/clice/guide/editors.md b/zh/clice/guide/editors.md new file mode 100644 index 0000000..ae688c5 --- /dev/null +++ b/zh/clice/guide/editors.md @@ -0,0 +1,103 @@ +# Editor Setup + +clice 实现了 [Language Server Protocol](https://microsoft.github.io/language-server-protocol)，任何带 LSP 客户端的编辑器都可以使用它。下面的编辑器分为两类：有官方 clice 插件的，以及通过通用 LSP 客户端配置的。 + +所有配置的前提： + +- `clice` 可执行文件在 `PATH` 中（或在下面的片段中使用绝对路径）。 +- 项目提供 `compile_commands.json`（clice 默认搜索工作区根目录和 `build/`）。 + +## Official Plugins + +### Visual Studio Code + +从市场安装 [clice 扩展](https://marketplace.visualstudio.com/items?itemName=ykiko.clice-vscode)。扩展会自动下载 clice 二进制；如需使用自己构建的版本，设置 `clice.executable`。 + +### Neovim + +clice 在 [`editors/nvim`](https://github.com/clice-io/clice/tree/main/editors/nvim) 中提供了 Neovim ≥ 0.11 的 LSP 配置。把 `doc/clice.lua` 复制到你配置目录的 `lsp/` 下，然后启用： + +```lua +vim.lsp.enable('clice') +``` + +### Zed + +Zed 扩展位于 [`editors/zed`](https://github.com/clice-io/clice/tree/main/editors/zed)。 + +## Generic LSP Clients + +### Helix + +添加到 `~/.config/helix/languages.toml`： + +```toml +[language-server.clice] +command = "clice" +args = ["server"] + +[[language]] +name = "cpp" +language-servers = ["clice"] + +[[language]] +name = "c" +language-servers = ["clice"] +``` + +### Emacs + +使用内置的 eglot： + +```elisp +(with-eval-after-load 'eglot + (add-to-list 'eglot-server-programs + '((c-mode c-ts-mode c++-mode c++-ts-mode) + . ("clice" "server")))) +``` + +### Sublime Text + +安装 [LSP 包](https://packagecontrol.io/packages/LSP)，然后在其设置中添加： + +```json +{ + "clients": { + "clice": { + "enabled": true, + "command": ["clice", "server"], + "selector": "source.c | source.c++" + } + } +} +``` + +### Kate + +打开 `设置 → 配置 Kate → LSP 客户端 → 用户服务器设置`，添加： + +```json +{ + "servers": { + "c": { + "command": ["clice", "server"], + "url": "https://github.com/clice-io/clice", + "highlightingModeRegex": "^(C|C\\+\\+)$" + } + } +} +``` + +### Vim + +使用 [vim-lsp](https://github.com/prabirshrestha/vim-lsp)： + +```vim +if executable('clice') + au User lsp_setup call lsp#register_server({ + \ 'name': 'clice', + \ 'cmd': {server_info->['clice', 'server']}, + \ 'allowlist': ['c', 'cpp'], + \ }) +endif +``` diff --git a/zh/clice/guide/quick-start.md b/zh/clice/guide/quick-start.md index e36ae48..4cf0806 100644 --- a/zh/clice/guide/quick-start.md +++ b/zh/clice/guide/quick-start.md @@ -6,33 +6,7 @@ clice 实现了 [Language Server Protocol](https://microsoft.github.io/language- 除了标准协议之外，clice 还支持一些协议扩展。为了更好地处理这些扩展以及更好地与编辑器集成，使用专用的 clice 插件是推荐方案。 -### Visual Studio Code - -从插件市场安装 [clice](https://marketplace.visualstudio.com/items?itemName=ykiko.clice-vscode) 插件。它会自动下载 clice 二进制文件。 - -如需使用自定义二进制文件，在工作区设置中配置 `clice.executable`： - -```jsonc -{ - "clice.executable": "/path/to/clice", -} -``` - -### Vim/Neovim - -将 clice Neovim 插件添加到 runtime path： - -```lua --- lazy.nvim -{ dir = "/path/to/clice/editors/nvim" } - --- 或手动添加 -vim.opt.rtp:append("/path/to/clice/editors/nvim") -``` - -### 其它编辑器 - -其它编辑器暂时还没有专用的 clice 插件（欢迎贡献！）。请自行安装 clice 二进制文件，并配置编辑器的 LSP 客户端运行 `clice server`。 +各编辑器的具体配置见 [Editor Setup](./editors.md)：Visual Studio Code、Neovim 和 Zed 有官方插件，Helix、Emacs、Sublime Text、Kate、Vim 等通用 LSP 客户端提供配置片段。 ## 安装