docs: update build

.github/workflows/test-cmake.yml

@@ -25,7 +25,7 @@ jobs:
           environments: develop
 
       - name: Build
-        run: pixi run ci-cmake-build ${{ matrix.build_type }}
+        run: pixi run build ${{ matrix.build_type }} ON
 
       - name: Test
-        run: pixi run ci-cmake-test
+        run: pixi run test ${{ matrix.build_type }}

.github/workflows/test-xmake.yml

@@ -34,7 +34,7 @@ jobs:
           environments: develop
 
       - name: Build
-        run: pixi run ci-xmake-build ${{ matrix.build_type }}
+        run: pixi run xmake ${{ matrix.build_type }}
 
       - name: Test
         run: pixi run xmake-test

docs/en/dev/build.md

@@ -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.
+We ship several tasks; the commands below configure, build, and run tests:
 
-## CMake
+```shell
+# 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.
 
-Use the following commands to build clice
+### CMake
 
 ```shell
-cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
-cmake --build build
+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`            |
+
+## 📦 About LLVM
 
-## A Note on LLVM Libs
+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.
 
-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.
+Two ways to satisfy this dependency:
 
-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.
+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.
-
-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
-```
+> 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`.
 
-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).

docs/en/dev/extension.md

@@ -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.