caio/clice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update build (#335)

Browse Source
This commit is contained in:
ykiko
2026-01-01 00:36:07 +08:00
committed by GitHub
parent c6d87cccf3
commit 4d16cf7b0a
13 changed files with 538 additions and 1220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
docs/en/dev/build.md
View File

@@ -1,45 +1,78 @@
# Build from Source
## Supported Platforms
clice depends on C++23 features and requires a modern C++ toolchain. We also need to link against LLVM/Clang to parse ASTs. To speed up builds, the default configuration downloads our published [clice-llvm](https://github.com/clice-io/clice-llvm) prebuilt package. This assumes your local environment matches the prebuild environment closely (especially when enabling Address Sanitizer or LTO).
- Windows
- Linux
- macOS
To simplify setup and keep builds reproducible, we **strongly recommend** [pixi](https://pixi.prefix.dev/latest) to manage the development environment. Dependency versions are pinned in `pixi.toml`.
## Prerequisite
If you prefer not to use pixi, see [Manual Build](#manual-build) below.
- cmake/xmake
- clang, lld >= 20
- c++23 **compatible** standard library
- MSVC STL >= 19.44(VS 2022 17.4)
- GCC libstdc++ >= 14
- Clang libc++ >= 20
## 🚀 Quick Start
clice uses C++23 as its language standard. Please ensure you have a clang 20 (or higher) compiler and a C++23 compatible standard library available. clice depends on lld as its linker. Please ensure your clang toolchain can find it (clang distributions usually bundle lld, or you may need to install the lld-20 package separately).
Install pixi following the [official guide](https://pixi.prefix.dev/latest/installation).
> clice is currently only guaranteed to compile with clang (as ensured by CI testing). We do our best to maintain compatibility with gcc and msvc, but we do not add corresponding tests in CI. Contributions are welcome if you encounter any issues.
## CMake
Use the following commands to build clice
We ship several tasks; the commands below configure, build, and run tests:
```shell
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build build
# configure && build (default RelWithDebInfo)
pixi run build
# unit && integration
pixi run test
```
For finer-grained tasks (first argument sets the build type):
```shell
pixi run cmake-config Debug
pixi run cmake-build Debug
pixi run unit-test Debug
pixi run integration-test Debug
```
> [!TIP]
> If you want to develop directly with `cmake`, `ninja`, `clang++`, etc., run `pixi shell -e develop` to enter a shell with all env vars configured.
### XMake
We also support building with XMake:
```shell
# config & build (default releasedbg)
pixi run xmake
# unit & integration
pixi run xmake-test
```
## 🛠️ Manual Build
If you plan to build manually, first ensure your toolchain matches the versions defined in `pixi.toml`.
> Compatibility: In theory clice does not rely on compiler-specific extensions, so mainstream compilers (GCC/Clang/MSVC) should work. However, CI only guarantees specific versions of Clang. Other compilers or versions are supported on a **best-effort** basis. Please open an issue or PR if you hit problems.
### CMake
```shell
cmake -B build -G Ninja \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
-DCLICE_ENABLE_TEST=ON
```
> Note: `CMAKE_TOOLCHAIN_FILE` is optional. If your toolchain exactly matches ours, you can use the predefined `cmake/toolchain.cmake`; otherwise remove that flag.
Optional build options:
| Option | Default | Description |
| :------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------- |
| LLVM_INSTALL_PATH | "" | Build clice using llvm libs from a custom path |
| CLICE_ENABLE_TEST | OFF | Whether to build clice's unit tests |
| CLICE_USE_LIBCXX | OFF | Whether to build clice with libc++ (adds `-std=libc++`). If enabled, ensure that the llvm libs were also compiled with libc++. |
| CLICE_CI_ENVIRONMENT | OFF | Whether to enable the `CLICE_CI_ENVIRONMENT` macro. Some tests only run in a CI environment. |
| Option | Default | Effect |
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| LLVM_INSTALL_PATH | "" | Build clice with LLVM from a custom path |
| CLICE_ENABLE_TEST | OFF | Build clice unit tests |
| CLICE_USE_LIBCXX | OFF | Build clice with libc++ (adds `-std=libc++`); if enabled, ensure the LLVM libs are also built with libc++ |
| CLICE_CI_ENVIRONMENT | OFF | Enable the `CLICE_CI_ENVIRONMENT` macro; some tests only run in CI |
## XMake
### XMake
Use the following commands to build clice
Build clice with:
```bash
xmake f -c --mode=releasedbg --toolchain=clang
@@ -48,35 +81,22 @@ xmake build --all
Optional build options:
| Option | Default | Description |
| :------------ | :------ | :--------------------------------------------- |
| --llvm | "" | Build clice using llvm libs from a custom path |
| --enable_test | false | Whether to build clice's unit tests |
| --ci | false | Whether to enable `CLICE_CI_ENVIRONMENT` |
| Option | Default | Effect |
| ------------- | ------- | ---------------------------------------- |
| --llvm | "" | Build clice with LLVM from a custom path |
| --enable_test | false | Build clice unit tests |
| --ci | false | Enable `CLICE_CI_ENVIRONMENT` |
## A Note on LLVM Libs
## 📦 About LLVM
Due to the complexity of C++ syntax, writing a new parser from scratch is unrealistic. clice calls clang's APIs to parse C++ source files and obtain the AST, which means it needs to link against llvm/clang libs. Because clice uses clang's private headers, which are not included in the binary releases published by LLVM, you cannot use the system's llvm package directly.
clice calls Clang APIs to parse C++ code, so it must link LLVM/Clang. Because clice uses Clang private headers (usually absent from distro packages), the system LLVM package cannot be used directly.
1. We publish pre-compiled binaries for the LLVM version we use on [clice-llvm](https://github.com/clice-io/clice-llvm/releases), which are used for CI or release builds. By default, cmake and xmake will download and use the llvm libs from here during the build.
Two ways to satisfy this dependency:
1. We publish prebuilt binaries of the LLVM version we use at [clice-llvm](https://github.com/clice-io/clice-llvm/releases) for CI and release builds. During builds, cmake and xmake download these LLVM libs by default.
> [!IMPORTANT]
>
> For debug builds of llvm libs, we enable address sanitizer. Address sanitizer depends on compiler-rt, which is highly sensitive to the compiler version.
>
> Therefore, if you use a debug build, please ensure your clang's compiler-rt version is **strictly identical** to the one used in our build.
>
> - Windows does not currently have debug builds for llvm libs, as it does not support building clang as a dynamic library. Related progress is tracked [here](https://github.com/clice-io/clice/issues/42).
> - Linux uses clang20
> - macOS uses homebrew llvm@20. **Do not use apple clang**.
>
> You can refer to the [cmake](https://github.com/clice-io/clice/blob/main/.github/workflows/cmake.yml) and [xmake](https://github.com/clice-io/clice/blob/main/.github/workflows/xmake.yml) files in our CI as a reference, as they maintain an environment strictly consistent with the pre-compiled llvm libs.
> For debug LLVM builds, we enable address sanitizer, which depends on compiler-rt and is very sensitive to compiler version. If you use a debug build, ensure your clang compiler-rt version matches the one defined in `pixi.toml`.
2. Build llvm/clang yourself to match your current environment. If the default pre-compiled binaries (Method 1) fail to run on your system due to ABI or library version (e.g., glibc) incompatibility, or if you need a custom Debug build, we recommend you use this method to compile llvm libs from scratch. We provide a script to build the llvm libs required by clice: [build-llvm-libs.py](https://github.com/clice-io/clice/blob/main/scripts/build-llvm-libs.py).
```bash
cd llvm-project
python3 <clice>/scripts/build-llvm-libs.py debug
```
You can also refer to LLVM's official build tutorial: [Building LLVM with CMake](https://llvm.org/docs/CMake.html).
2. Build LLVM/Clang yourself to match your environment. If the default prebuilt binaries fail due to ABI or library version mismatches, or you need a custom debug build, use this approach. We provide `scripts/build-llvm.py` to build the required LLVM libs, or refer to LLVM's official guide [Building LLVM with CMake](https://llvm.org/docs/CMake.html).

70
docs/en/dev/extension.md Normal file
View File

@@ -0,0 +1,70 @@
# Extension
This section covers development and release workflows for the editor extensions (VSCode / Neovim / Zed).
## 🌐 VSCode
The VSCode extension uses the Node/PNPM/VSCE toolchain. Work inside the pixi `node` environment for consistent versions.
```shell
# prepare environment (install pixi first)
pixi shell -e node
# install deps (uses pnpm-lock)
pixi run install-vscode
# package the extension; outputs editors/vscode/*.vsix
pixi run build-vscode
```
Publish to the VSCode Marketplace (`VSCE_PAT` env var required):
```shell
pixi run publish-vscode
```
> [!TIP]
> If clice is already built locally, set `clice.executable` in VSCode settings to point the extension to your custom binary.
Develop and debug:
1. `pixi shell -e node`
2. In `editors/vscode`, run `pnpm run watch` for incremental builds
3. In VSCode, use the “Run Extension/Launch Extension” configs, or run `code --extensionDevelopmentPath=$(pwd)/editors/vscode`
Common scripts (inside `pixi shell -e node`):
```bash
pnpm run package # same as pixi run build-vscode
pnpm run publish # same as pixi run publish-vscode
```
If you skip pixi, install node.js >= 20 and pnpm yourself, then in `editors/vscode` run:
```bash
pnpm install
pnpm run package
```
## 🧩 Neovim
The Neovim extension lives in `editors/nvim` and is written in Lua. It is still evolving.
- Add the repo path to `runtimepath`, e.g. `set rtp+=/path/to/clice/editors/nvim`
- Or create a local symlink: `~/.config/nvim/pack/clice/start/clice` -> `<repo>/editors/nvim`
- Ensure the `clice` executable is discoverable in `$PATH`
Dev tips: the codebase is small—load it directly in Neovim and watch `:messages`/LSP logs; format with `stylua` (config included).
## 🪶 Zed
The Zed extension lives in `editors/zed` and uses Rust plus `zed_extension_api`.
Suggested local verification:
```bash
cd editors/zed
cargo build --release
```
Then load the local extension per Zed's official guide (Zed CLI required). Make sure `clice` is on `PATH` before launching. Follow the Zed extension publishing flow when releasing.

122
docs/zh/dev/build.md
View File

@@ -1,45 +1,78 @@
# Build from Source
## Supported Platforms
clice 依赖 C++23 特性，需要使用高版本的 C++ 编译器。同时，我们需要链接 LLVM/Clang 库来解析 AST。为了加快构建速度，默认配置会下载我们发布的 [clice-llvm](https://github.com/clice-io/clice-llvm) 预编译包。这要求你的本地环境与预编译环境保持较高的一致性（尤其是开启 Address Sanitizer 或 LTO 时）。
- Windows
- Linux
- macOS
为了简化环境设置并保证可复现性，我们**强烈推荐**使用 [pixi](https://pixi.prefix.dev/latest) 来管理开发环境。所有的依赖版本均严格定义在 `pixi.toml` 中。
## Prerequisite
如果你不想使用 pixi，请参考下方的 [Manual Build](#manual-build) 章节。
- cmake/xmake
- clang, lld >= 20
- c++23 **compatible** standard library
- MSVC STL >= 19.44(VS 2022 17.4)
- GCC libstdc++ >= 14
- Clang libc++ >= 20
## 🚀 Quick Start
clice 使用 C++23 作为语言标准，请确保有可用的 clang 20 以及以上的编译器，以及兼容 C++23 的标准库。clice 依赖 lld 作为链接器。请确保你的 clang 工具链可以找到它（通常 clang 发行版会自带 lld，或者你需要单独安装 lld-20 包）。
请参考 [pixi](https://pixi.prefix.dev/latest/installation) 官方指南安装 pixi。
> clice 目前只保证能使用 clang 编译（CI 测试保证）。对于 gcc 和 msvc 的兼容，我们尽力而为，但不会在 CI 中添加对应的测试。如果遇到任何问题，欢迎贡献。
## CMake
使用如下的命令构建 clice
我们内置了一系列任务，以下命令可直接完成编译并运行测试：
```shell
cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build build
# configure && build (default RelWithDebInfo)
pixi run build
# unit && integration
pixi run test
```
细粒度任务：上述命令由多个子任务组成，你也可以单独运行它们，并支持通过第一个参数指定构建类型：
```shell
pixi run cmake-config Debug
pixi run cmake-build Debug
pixi run unit-test Debug
pixi run integration-test Debug
```
> [!TIP]
> 如果你想直接使用 `cmake`, `ninja`, `clang++` 等命令进行开发，请运行 `pixi shell -e develop` 进入已配置好环境变量的终端
### XMake
我们同样支持使用 XMake 构建：
```shell
# config & build (default releasedbg)
pixi run xmake
# unit & integration
pixi run xmake-test
```
## 🛠️ Manual Build
如果你打算手动构建，请务必先确认你的工具链满足 pixi.toml 中定义的版本要求。
> 兼容性说明：理论上 clice 不依赖特定编译器的扩展，可以使用主流编译器（GCC/Clang/MSVC）编译。但我们仅在 CI 中保证特定版本的 Clang 能通过测试。对于其他编译器或版本，我们提供**尽力而为 (Best Effort)** 的支持。如果遇到问题，欢迎提交 Issue 或 PR
### CMake
```shell
cmake -B build -G Ninja \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake \
-DCLICE_ENABLE_TEST=ON
```
> 注意：`CMAKE_TOOLCHAIN_FILE` 是可选的。如果你使用的工具链与我们完全一致，可以使用预定义的 `cmake/toolchain.cmake`，否则请移除该选项
可选的构建选项：
| 选项 | 默认值 | 效果 |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| LLVM_INSTALL_PATH | "" | 使用自定义路径的 llvm libs 来构建 clice |
| CLICE_ENABLE_TEST | OFF | 是否构建 clice 的单元测试 |
| CLICE_USE_LIBCXX | OFF | 是否使用 libc++ 来构建 clice（添加 `-std=libc++`），如果开启，请确保 llvm libs 也是使用 libc++ 编译的 |
| CLICE_CI_ENVIRONMENT | OFF | 是否打开 `CLICE_CI_ENVIRONMENT` 这个宏，有些测试在 CI 环境才会执行 |
| 选项 | 默认值 | 效果 |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| LLVM_INSTALL_PATH | "" | 使用自定义路径的 LLVM 库来构建 clice |
| CLICE_ENABLE_TEST | OFF | 是否构建 clice 的单元测试 |
| CLICE_USE_LIBCXX | OFF | 是否使用 libc++ 来构建 clice（添加 `-std=libc++`），如果开启，请确保 LLVM 库也是使用 libc++ 编译的 |
| CLICE_CI_ENVIRONMENT | OFF | 是否打开 `CLICE_CI_ENVIRONMENT` 这个宏，有些测试在 CI 环境才会执行 |
## XMake
### XMake
使用如下的命令即可构建 clice
使用如下命令即可构建 clice：
```bash
xmake f -c --mode=releasedbg --toolchain=clang
@@ -48,33 +81,22 @@ xmake build --all
可选的构建选项：
| 选项 | 默认值 | 效果 |
| ------------- | ------ | --------------------------------------- |
| --llvm | "" | 使用自定义路径的 llvm libs 来构建 clice |
| --enable_test | false | 是否构建 clice 的单元测试 |
| --ci | false | 是否打开 `CLICE_CI_ENVIRONMENT` |
| 选项 | 默认值 | 效果 |
| ------------- | ------ | ------------------------------------ |
| --llvm | "" | 使用自定义路径的 LLVM 库来构建 clice |
| --enable_test | false | 是否构建 clice 的单元测试 |
| --ci | false | 是否打开 `CLICE_CI_ENVIRONMENT` |
## A Note on LLVM Libs
## 📦 About LLVM
由于 C++ 的语法太过复杂，自己编写一个新的 parser 是不现实的。clice 调用 clang 的 API 来 parse C++ 源文件获取 AST，这意味它需要链接 llvm/clang libs。由于 clice 使用了 clang 的私有头文件，这些私有头文件在 llvm 发布的 binary release 中是没有的，所以不能直接使用系统的 llvm package。
clice 调用 Clang API 来解析 C++ 代码，因此必须链接 LLVM/Clang 库。由于 clice 使用了 Clang 的私有头文件（这些文件通常不包含在发行版中），不能直接使用系统安装的 LLVM 包。
1. 我们在 [clice-llvm](https://github.com/clice-io/clice-llvm/releases) 上会发布使用的 llvm 版本的预编译二进制，用于 CI 或者 release 构建。在构建时 cmake 和 xmake 默认会从此处下载 llvm libs 然后使用，
主要有两种方式解决这个依赖问题：
1. 我们在 [clice-llvm](https://github.com/clice-io/clice-llvm/releases) 上会发布使用的 LLVM 版本的预编译二进制，用于 CI 或者 release 构建。在构建时 cmake 和 xmake 默认会从此处下载 LLVM 库然后使用。
> [!IMPORTANT]
>
> 对于 debug 版本的 llvm libs，构建的时候我们开启了 address sanitizer，而 address sanitizer 依赖于 compiler rt，它对编译器版本十分敏感。所以如果使用 debug 版本，请确保你的 clang 的 compiler rt 版本和我们构建的时候**严格一致**。
>
> - Windows 暂时没有 debug 构建的 llvm libs，因为它不支持将 clang 构建为动态库，相关的进展在 [这里](https://github.com/clice-io/clice/issues/42) 跟踪
> - Linux 使用 clang20
> - macOS 使用 homebrew llvm@20，**不要使用 apple clang**
>
> 可以参考 CI 中的 [cmake](https://github.com/clice-io/clice/blob/main/.github/workflows/cmake.yml) 和 [xmake](https://github.com/clice-io/clice/blob/main/.github/workflows/xmake.yml) 文件作为参考，它们与预编译 llvm libs 的环境保持严格一致。
> 对于 debug 版本的 LLVM 库，构建的时候我们开启了 address sanitizer，而 address sanitizer 依赖于 compiler rt，它对编译器版本十分敏感。所以如果使用 debug 版本，请确保你的 clang 的 compiler rt 版本与 `pixi.toml` 中的定义严格一致。
2. 自己重新一个与当前环境一致的 llvm/clang。如果默认的预编译二进制文件（方法 1）在你的系统上因 ABI 或库版本（如 glibc）不兼容而运行失败，或者你需要一个自定义的 Debug 版本，那么我们推荐你使用此方法从头编译 llvm libs。我们提供了一个脚本，用于构建 clice 所需要的 llvm libs：[build-llvm-libs.py](https://github.com/clice-io/clice/blob/main/scripts/build-llvm-libs.py)。
```bash
cd llvm-project
python3 <clice>/scripts/build-llvm-libs.py debug
```
也可以参考 llvm 的官方构建教程 [Building LLVM with CMake](https://llvm.org/docs/CMake.html)。
2. 自行构建一套与当前环境一致的 LLVM/Clang。如果默认的预编译二进制文件在你的系统上因 ABI 或库版本不兼容而运行失败，或者你需要一个自定义的 Debug 版本，那么我们推荐你使用此方法从头编译 LLVM 库。我们提供了一个脚本 `scripts/build-llvm.py` 用于构建所需要的 LLVM 库，也可以参考 LLVM 的官方构建教程 [Building LLVM with CMake](https://llvm.org/docs/CMake.html)。

70
docs/zh/dev/extension.md Normal file
View File

@@ -0,0 +1,70 @@
# Extension
本节汇总各编辑器插件的开发与发布流程。目前包含 VSCode / Neovim / Zed。
## 🌐 VSCode
VSCode 插件使用 Node/PNPM/VSCE 链路。推荐在 pixi 的 `node` 环境下操作以获得一致的工具链版本。
```shell
# 准备环境（先安装 pixi）
pixi shell -e node
# 安装依赖（基于 pnpm-lock）
pixi run install-vscode
# 打包扩展，产物位于 editors/vscode/*.vsix
pixi run build-vscode
```
发布到 VSCode Marketplace（需要 `VSCE_PAT` 环境变量）：
```shell
pixi run publish-vscode
```
> [!TIP]
> 若已编译 clice，本地调试时可在 VSCode 设置中填写 `clice.executable`，使扩展指向你的自定义构建。
开发与调试：
1. `pixi shell -e node`
2. 在 `editors/vscode` 下运行 `pnpm run watch`（增量构建）
3. VSCode 中使用 “Run Extension/Launch Extension” 调试配置，或执行 `code --extensionDevelopmentPath=$(pwd)/editors/vscode`
常用脚本（在 `pixi shell -e node` 下）：
```bash
pnpm run package # 等价于 pixi run build-vscode
pnpm run publish # 等价于 pixi run publish-vscode
```
如果不使用 pixi，请自行准备 node.js >= 20、pnpm，然后在 `editors/vscode` 目录执行：
```bash
pnpm install
pnpm run package
```
## 🧩 Neovim
Neovim 插件位于 `editors/nvim`，使用 Lua 编写。目前功能仍在演进中。
- 将仓库路径加入 `runtimepath`，例如：`set rtp+=/path/to/clice/editors/nvim`
- 或在本地创建软链接：`~/.config/nvim/pack/clice/start/clice` -> `<repo>/editors/nvim`
- 需要 `clice` 可执行文件可在 `$PATH` 中被找到
开发提示：代码量较小，可直接在 Neovim 中加载并通过 `:messages`/LSP 日志观察效果；格式化可使用 `stylua`（仓库中已提供 `stylua.toml`）。
## 🪶 Zed
Zed 插件位于 `editors/zed`，使用 Rust 和 `zed_extension_api`。
建议的本地验证流程：
```bash
cd editors/zed
cargo build --release
```
随后按 Zed 官方指南加载本地扩展（需安装 Zed CLI），在启动前确保 `clice` 已在 PATH 中。发布时同样遵循 Zed 扩展发布流程。