CMake
xclang's CMake package sets the toolchain as a build's compiler for the host or another target, and provides xclang::std for import std without CMake's experimental switches.
Requires: CMake 3.28 or later, Ninja 1.11 or later, and the Ninja or Ninja Multi-Config generator.
Set Up a Project
Call find_package(xclang REQUIRED CONFIG) after project() and link xclang::std to use import std. The project is examples/cmake, which the quick start also builds:
cmake_minimum_required(VERSION 3.28)
project(hello LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_EXTENSIONS OFF)
find_package(xclang REQUIRED CONFIG)
add_executable(hello main.cpp)
target_link_libraries(hello PRIVATE xclang::std)import std;
int main() {
std::vector<std::string> targets{"windows", "linux", "macos"};
std::ranges::sort(targets);
try {
throw std::runtime_error(std::format("{} targets, the first {}", targets.size(), targets[0]));
} catch (const std::exception& e) {
std::println("hello from xclang: {}", e.what());
}
}With xclang's bin/ first in PATH, as pixi shell sets it, name the compiler and build:
cmake -G Ninja -B build -DCMAKE_CXX_COMPILER=clang++
cmake --build build
./build/helloIt prints hello from xclang: 3 targets, the first linux.
CMake does not pick clang by itself, so pass -DCMAKE_CXX_COMPILER=clang++, and -DCMAKE_C_COMPILER=clang for a project with C. find_package(xclang) finds the package through PATH. When xclang is not in PATH, pass the toolchain file from the toolchain directory ($XCLANG below). It sets the compilers, the binary tools and the package location at once:
cmake -G Ninja -B build --toolchain $XCLANG/lib/cmake/xclang/toolchain.cmakeBuild for Another Target
Pass -DXCLANG_TARGET=<target> with the toolchain file to cross-compile:
cmake -G Ninja -B build-aarch64-w64-mingw32 --toolchain $XCLANG/lib/cmake/xclang/toolchain.cmake \
-DXCLANG_TARGET=aarch64-w64-mingw32
cmake --build build-aarch64-w64-mingw32- The ten supported targets and what each needs on the host are listed in Cross-Compiling.
- On a macOS host, building for the other macOS architecture sets
CMAKE_OSX_ARCHITECTURESrather thanCMAKE_SYSTEM_NAME, so CMake does not treat the build as cross-compiling. - On a Linux host of the same architecture, a musl target (
x86_64-unknown-linux-musloraarch64-unknown-linux-musl) is not a cross build to CMake either, because the static programs it produces run on the host.try_runandctestrun there. - When cross-compiling (
CMAKE_CROSSCOMPILINGis true), CMake searches only the target's sysroot for libraries, headers and packages. Point CMake to dependencies built for the target with<Package>_DIR, or add their prefix toCMAKE_FIND_ROOT_PATH. xclang::stdis built for the target of the build.- A build directory keeps the target of its first configure. Passing another
XCLANG_TARGETlater stops the configure; use a new build directory, or re-configure withcmake --fresh.
Build for MSVC Targets
Set XCLANG_TARGET to x86_64-pc-windows-msvc or aarch64-pc-windows-msvc after fetching the Windows SDK with $XCLANG/bin/xclang sdk fetch windows --accept-license (MSVC targets). On a Windows host without a fetched SDK, clang uses an installed Visual Studio; on Linux and macOS hosts without the SDK, the toolchain file stops and prints the xclang sdk fetch command:
cmake -G Ninja -B build-msvc --toolchain $XCLANG/lib/cmake/xclang/toolchain.cmake \
-DXCLANG_TARGET=x86_64-pc-windows-msvc
cmake --build build-msvc- The compilers are
clangandclang++, notclang-cl.WIN32is true,MSVCis false, andCMAKE_CXX_SIMULATE_IDisMSVC, so a project'sif(MSVC)options written forcl.exestay out (MSVC targets). CMAKE_MSVC_RUNTIME_LIBRARYdefaults toMultiThreadedin every configuration, which links the hybrid CRT. OtherCMAKE_MSVC_RUNTIME_LIBRARYvalues work too.- The default C++ library is
libc++, andxclang::stdbuilds itsstdandstd.compatmodules.-DXCLANG_STDLIB=platformswitches to Microsoft's STL and buildsxclang::stdfrom the STL's module manifest (the system's C++ library). - Links in
DebugandRelWithDebInfopass-gand write a.pdb. A target that adds-gin another configuration must also add-gtotarget_link_optionsto write a PDB.
Build for macOS from Linux or Windows
Set XCLANG_TARGET to aarch64-apple-darwin or x86_64-apple-darwin after fetching Apple's SDK with $XCLANG/bin/xclang sdk fetch macos --accept-license (macOS on Linux and Windows hosts). Without the SDK, the toolchain file stops and prints the xclang sdk fetch command:
cmake -G Ninja -B build-macos --toolchain $XCLANG/lib/cmake/xclang/toolchain.cmake \
-DXCLANG_TARGET=aarch64-apple-darwin
cmake --build build-macosAPPLEis true,CMAKE_SYSTEM_NAMEisDarwin, andCMAKE_OSX_ARCHITECTURESis the target's architecture.install_name_tool,lipoandlibtoolare set to the toolchain'sllvm-install-name-tool,llvm-lipoandllvm-libtool-darwin, so no CMake step requiresxcrunor Xcode.CMAKE_OSX_SYSROOTis the SDK path: the value given, elseSDKROOT, else the toolchain'ssdk/macos. CMake passes it as-isysrootand searches only the SDK for libraries, headers and packages.CMAKE_OSX_DEPLOYMENT_TARGETsets the deployment target as on a macOS host; when unset, binaries target macOS 13.0.- Each build directory targets one architecture, because each architecture has its own config file (two architectures).
- Objective-C (
OBJC,OBJCXX) compiles with the toolchain'sclangandclang++.
Without xclang Installed
Include packages/cmake/xclang.cmake via FetchContent before project() so CMake downloads the host toolchain itself on a machine with only CMake and Ninja. latest is a branch pointing at the newest release tag, or you can pin a specific release tag in GIT_TAG. The project is examples/cmake-fetch:
cmake_minimum_required(VERSION 3.28)
include(FetchContent)
FetchContent_Declare(xclang
GIT_REPOSITORY https://github.com/clice-io/xclang
GIT_TAG latest)
FetchContent_MakeAvailable(xclang)
include(${xclang_SOURCE_DIR}/packages/cmake/xclang.cmake)
project(hello LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_EXTENSIONS OFF)
find_package(xclang REQUIRED CONFIG)
add_executable(hello main.cpp)
target_link_libraries(hello PRIVATE xclang::std)cmake -G Ninja -B build
cmake --build build
./build/helloxclang.cmake verifies the archive against the release's SHA256SUMS and unpacks it into the user cache once per release and host. -DXCLANG_TARGET=<target> cross-compiles here too:
cmake -G Ninja -B build-x86_64-w64-mingw32 -DXCLANG_TARGET=x86_64-w64-mingw32
cmake --build build-x86_64-w64-mingw32| variable | |
|---|---|
XCLANG_CACHE_DIR | directory where toolchains are unpacked; also read from the environment |
XCLANG_ROOT | an unpacked toolchain to use instead of downloading one |
XCLANG_URL | base URL of a release mirror |
XCLANG_VERSION | release version to download when GIT_TAG names a commit rather than a release tag |
See the CMake API for the full variable list.
A build directory keeps the toolchain of its first configure: when latest moves to a new release, or XCLANG_VERSION, XCLANG_ROOT or XCLANG_CACHE_DIR changes, xclang.cmake stops before it downloads anything. Use a new build directory, or configure again with cmake --fresh. xclang.cmake also stops when the build has a toolchain file already, such as vcpkg's: chain-load xclang's toolchain file from vcpkg instead, with VCPKG_CHAINLOAD_TOOLCHAIN_FILE.
Use the System's C++ Library
Pass -DXCLANG_STDLIB=platform with the toolchain file to build against the platform's C++ library instead of xclang's libc++. The toolchain file adds -stdlib=platform to every compile and link:
cmake -G Ninja -B build-system --toolchain $XCLANG/lib/cmake/xclang/toolchain.cmake \
-DXCLANG_STDLIB=platform- For Linux (
glibc) targets, the sysroot is the host's/orCMAKE_SYSROOT. For musl and MinGW targets,CMAKE_SYSROOTis required and must point to a sysroot containing theirlibstdc++(the platform's C++ library). xclang::stdis built from the platform library's module manifest, such as Microsoft's STL on MSVC targets or GCC 15'slibstdc++.find_package(xclang)fails when the platform library has no module manifest.XCLANG_STDLIB=platformcannot be combined withXCLANG_RUNTIMES=source, andXCLANG_SANITIZER=addressdoes not link an ASan-instrumentedlibc++.
Features
- C++20 modules and
import std: Linkxclang::stdforimport std, declare project module interfaces withFILE_SET CXX_MODULES, and callxclang_add_stdwhen a target needs its own language flags (C++20 Modules). - Sanitizers: Pass
-DXCLANG_SANITIZER=address,undefined,thread,leakormemorywith the toolchain file to instrument the build and link the matching runtime (Sanitizers). - Runtimes from source: Pass
-DXCLANG_RUNTIMES=sourcewith the toolchain file to buildlibc++,libc++abiandlibunwindat configure time with hardening modes, custom ABI options,-fno-exceptions, or MemorySanitizer (Runtimes from Source). - Debug symbols: Call
xclang_debug_symbols(<program>)to generate<program>.gsymafter linking, and<program>.dSYMfor macOS targets (Debugging). - libclang and the ThinLTO cache: Find an unpacked
libclangarchive withfind_package(Clang), and pass-DXCLANG_THINLTO_CACHE=<dir>to cache ThinLTO objects across links (libclang, the ThinLTO cache).
