diff --git a/en/clice/dev/build.md b/en/clice/dev/build.md index f29bb51f..cfbea439 100644 --- a/en/clice/dev/build.md +++ b/en/clice/dev/build.md @@ -1,6 +1,6 @@ # Build from Source -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 prebuilt environment closely (especially when enabling Address Sanitizer or LTO). +clice depends on C++23 features and requires a modern C++ toolchain. We also need to link against LLVM/Clang to parse ASTs. Both come from [xclang](https://github.com/clice-io/xclang), clice-io's clang toolchain: pixi installs its compiler, and the default configuration downloads the prebuilt LLVM/Clang libraries of the same xclang release. The two must match: the libraries hold ThinLTO bitcode, which only the compiler of that release reads. 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`. @@ -38,7 +38,7 @@ pixi run snap-test Debug 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. +> Compatibility: clice itself does not rely on compiler-specific extensions, but the LLVM/Clang libraries it links hold ThinLTO bitcode, so the compiler must be the xclang release pinned in `pixi.toml`; `cmake/llvm.cmake` checks this at configure time. Please open an issue or PR if you hit problems. ### CMake @@ -70,10 +70,10 @@ clice calls Clang APIs to parse C++ code, so it must link against LLVM/Clang. Be 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 downloads these LLVM libs by default. +1. Every [xclang](https://github.com/clice-io/xclang/releases) release publishes prebuilt LLVM/Clang libraries (the `libclang-*` archives) for all six targets, built by that release's toolchain. During builds, cmake downloads the archive of the target by default. > [!IMPORTANT] > -> 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`. +> Debug builds for x86_64 Linux and arm64 macOS enable Address Sanitizer and link the ASan-instrumented libraries xclang publishes for these two targets. Debug builds for the other targets link the release libraries, without Address Sanitizer. -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). +2. Build LLVM/Clang yourself and pass the install directory as `LLVM_INSTALL_PATH`. `cmake/llvm.cmake` checks the install against the manifest xclang writes, `lib/cmake/xclang/libclang.cmake`, so the way to build one is xclang's `scripts/toolchain.ts`; see [xclang](https://github.com/clice-io/xclang). diff --git a/zh/clice/dev/build.md b/zh/clice/dev/build.md index 67d48245..4a9642dc 100644 --- a/zh/clice/dev/build.md +++ b/zh/clice/dev/build.md @@ -1,6 +1,6 @@ # 从源码构建 -clice 依赖 C++23 特性，需要使用现代 C++ 工具链。同时还需要链接 LLVM/Clang 以解析 AST。为了加快构建速度，默认配置会下载我们发布的 [clice-llvm](https://github.com/clice-io/clice-llvm) 预编译包。这要求本地环境与预编译环境高度一致（尤其是在启用 Address Sanitizer 或 LTO 时）。 +clice 依赖 C++23 特性，需要使用现代 C++ 工具链。同时还需要链接 LLVM/Clang 以解析 AST。两者都来自 clice-io 的 clang 工具链 [xclang](https://github.com/clice-io/xclang)：pixi 安装它的编译器，默认配置则下载同一 xclang 版本预编译的 LLVM/Clang 库。两者必须一致：这些库里是 ThinLTO bitcode，只有该版本的编译器能读取。 为了简化环境配置并确保构建可复现，我们**强烈推荐**使用 [pixi](https://pixi.prefix.dev/latest) 管理开发环境。依赖版本固定在 `pixi.toml` 中。 @@ -38,7 +38,7 @@ pixi run snap-test Debug 如果你打算手动构建，请先确保工具链版本与 `pixi.toml` 中定义的版本一致。 -> 兼容性说明：理论上，clice 不依赖任何编译器特有的扩展，因此主流编译器（GCC/Clang/MSVC）应该都能使用。不过，CI 仅保证特定版本的 Clang 可用。对于其他编译器或版本，我们只会尽力提供支持。如果遇到问题，请提交 issue 或 PR。 +> 兼容性说明：clice 本身不依赖任何编译器特有的扩展，但它链接的 LLVM/Clang 库里是 ThinLTO bitcode，因此编译器必须是 `pixi.toml` 中固定的 xclang 版本；`cmake/llvm.cmake` 会在配置时检查这一点。遇到问题欢迎提交 issue 或 PR。 ### CMake @@ -70,10 +70,10 @@ clice 调用 Clang API 解析 C++ 代码，因此必须链接 LLVM/Clang。由 可以通过以下两种方式满足此依赖： -1. 我们在 [clice-llvm](https://github.com/clice-io/clice-llvm/releases) 中发布所用 LLVM 版本的预编译二进制文件，供 CI 和发布版构建使用。构建时，CMake 默认会下载这些 LLVM 库。 +1. 每个 [xclang](https://github.com/clice-io/xclang/releases) 版本都会为全部六个目标发布预编译的 LLVM/Clang 库（`libclang-*` 压缩包），由该版本自己的工具链构建。构建时，CMake 默认会下载对应目标的压缩包。 > [!IMPORTANT] > -> 对于 LLVM 的调试构建，我们会启用 Address Sanitizer；它依赖 compiler-rt，并且对编译器版本非常敏感。如果使用调试构建，请确保 clang 的 compiler-rt 版本与 `pixi.toml` 中定义的版本一致。 +> 在 x86_64 Linux 和 arm64 macOS 上，调试构建会启用 Address Sanitizer，并链接 xclang 为这两个目标发布的 ASan 插桩库。其他目标的调试构建链接发布版的库，不启用 Address Sanitizer。 -2. 自行构建 LLVM/Clang，使其与你的环境相匹配。如果默认的预编译二进制文件因 ABI 或库版本不匹配而无法使用，或者你需要自定义调试构建，请采用这种方式。我们提供了 `scripts/build-llvm.py`，用于构建所需的 LLVM 库；你也可以参阅 LLVM 官方指南[使用 CMake 构建 LLVM](https://llvm.org/docs/CMake.html)。 +2. 自行构建 LLVM/Clang，并通过 `LLVM_INSTALL_PATH` 传入安装目录。`cmake/llvm.cmake` 会用 xclang 写入的清单 `lib/cmake/xclang/libclang.cmake` 检查该安装，因此构建方法是使用 xclang 的 `scripts/toolchain.ts`；参见 [xclang](https://github.com/clice-io/xclang)。