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 prebuilt package. This assumes your local environment matches the prebuilt environment closely (especially when enabling Address Sanitizer or LTO).

To simplify setup and keep builds reproducible, we strongly recommend pixi to manage the development environment. Dependency versions are pinned in pixi.toml.

If you prefer not to use pixi, see Manual Build below.

Quick Start

Install pixi following the official guide.

We ship several tasks; the commands below configure, build, and run tests:

# configure && build (default RelWithDebInfo)
pixi run build

# unit && integration
pixi run test

For finer-grained tasks (first argument sets the build type):

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 to enter a shell with all env vars configured.

XMake

We also support building with XMake:

# 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

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

Build clice with:

xmake f -c --mode=releasedbg --toolchain=clang
xmake build --all

Optional build options:

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

clice calls Clang APIs to parse C++ code, so it must link against LLVM/Clang. Because clice uses Clang's private headers (usually absent from distro packages), the system LLVM package cannot be used directly.

Two ways to satisfy this dependency:

1. We publish prebuilt binaries of the LLVM version we use at clice-llvm for CI and release builds. During builds, cmake and xmake download these LLVM libs 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.

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.