Skip to content

CMake API ​

Everything the CMake package of xclang defines. How to use it is in CMake; this page is the list.

The package is lib/cmake/xclang of every toolchain directory, and so of the conda package, and packages/cmake/ of the repository at every tag. It needs CMake 3.28 or later. For C++20 modules, it needs the Ninja or Ninja Multi-Config generator, with Ninja 1.11 or later.

Files ​

filewhat it is
xclang-config.cmakefind_package(xclang): xclang::std, xclang_add_std(), xclang_debug_symbols(), XCLANG_ROOT, the ThinLTO cache
xclang-config-version.cmakethe release, for find_package(xclang 23.1) (toolchain archives only)
toolchain.cmakethe toolchain directory as the toolchain of a build, for the host or XCLANG_TARGET
runtimes.cmakeincluded by toolchain.cmake: the runtimes built from source, and the build's sanitizers
runtimes-cxx.cmake, runtimes-compiler-rt.cmakethe CMake caches of xclang's own builds of libc++ and compiler-rt, which runtimes.cmake builds with (toolchain archives only)
xclang.cmakein packages/cmake/ only: included before project() from a FetchContent checkout, it downloads the toolchain

find_package(xclang) ​

It comes after project() or enable_language(CXX), whose C++ compiler must be xclang's clang++. It finds the package through PATH ($XCLANG/bin gives $XCLANG/lib/cmake/xclang), xclang_ROOT, or CMAKE_PREFIX_PATH.

namekind
xclang::stdCMake targeta static library of the std and std.compat modules of libc++ (with -stdlib=platform, XCLANG_STDLIB=platform, the platform library's: Microsoft's STL for an MSVC target), for the build's target; built only when something links it (language options)
xclang_add_std(<name>)functionanother such library; its PUBLIC options reach its importers
xclang_debug_symbols(<program> [GSYM_ARGS <option>...])functionafter each link of the CMake target <program>: <program>.gsym next to it, by llvm-gsymutil with one thread (the same file each run; GSYM_ARGS come after --num-threads=1), with its output in <program>.gsym.log; for a macOS target, <program>.dSYM first (debugging); nothing for an MSVC target, whose link writes a PDB
XCLANG_ROOTvariablethe toolchain directory
XCLANG_THINLTO_CACHEcache variablean absolute directory for the ThinLTO cache of the linker; its first value comes from the environment variable of the same name (the ThinLTO cache)

xclang::std asks its importers for C++23, or for the CMAKE_CXX_STANDARD it was built with if that is 20 or later. With XCLANG_RUNTIMES=source, it is built from the variant's modules and headers; that option needs the toolchain file, and find_package(xclang) fails without it.

toolchain.cmake ​

text
cmake -G Ninja -B build --toolchain $XCLANG/lib/cmake/xclang/toolchain.cmake [-DXCLANG_TARGET=<target>]
variable
XCLANG_TARGETx86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-unknown-linux-musl, aarch64-unknown-linux-musl, x86_64-w64-mingw32, aarch64-w64-mingw32, aarch64-apple-darwin, x86_64-apple-darwin, x86_64-pc-windows-msvc or aarch64-pc-windows-msvc; the host's by default. The MSVC targets, and the macOS targets on Linux and Windows hosts, build with the SDK that the toolchain's xclang fetched; the MSVC targets on a Windows host without it with the installed Visual Studio. The musl targets are no cross build on a Linux host of their architecture, which runs their static programs (try_run, tests). A build directory keeps the target of its first configure: another one later stops the configure (a new build directory, or cmake --fresh)
XCLANG_ROOTthe toolchain directory, when the file is used from outside one; a relative path is relative to the build directory
XCLANG_STDLIBlibc++, the default: xclang's libc++, and its sysroot. platform: the platform's C++ library, -stdlib=platform on every compile and link (the system's C++ library); no CMAKE_SYSROOT of the toolchain's for Linux targets, and one of the user's required for the musl and MinGW targets; xclang::std the platform library's where it has a module manifest (GCC 15's libstdc++), and find_package(xclang) fails where it has none. Not with XCLANG_RUNTIMES=source
XCLANG_RUNTIMES, XCLANG_SANITIZER, ...the runtimes built from source and the build's sanitizers (below)

It sets the C, C++ and ASM compilers, and the binary tools, to those of the toolchain directory: llvm-ar, llvm-ranlib, llvm-nm, llvm-objcopy, llvm-objdump, llvm-readelf, llvm-strip, llvm-addr2line, llvm-dlltool; for MinGW targets llvm-windres as the RC compiler; for macOS targets the Objective-C compilers (clang and clang++), llvm-libtool-darwin, llvm-lipo and llvm-install-name-tool (Apple's libtool cannot read the bitcode of a newer LLVM).

For a Linux or Windows target other than the host, it also sets CMAKE_SYSTEM_NAME, CMAKE_SYSTEM_PROCESSOR, CMAKE_<LANG>_COMPILER_TARGET, CMAKE_SYSROOT (the sysroot of the target) and CMAKE_FIND_ROOT_PATH_MODE_{LIBRARY,INCLUDE,PACKAGE} to ONLY, so libraries, headers and packages are looked for in the sysroot alone, and programs on the host. The other macOS architecture is CMAKE_OSX_ARCHITECTURES, which CMake does not treat as cross-compiling. The sysroot, C++ library, runtimes and linker come from the config file of the target, not from this file.

For an MSVC target on a Linux or macOS host, it stops unless the toolchain's sdk/windows has the SDK for the target; on a Windows host without one, clang finds Visual Studio. It sets llvm-rc as the RC compiler, which CMake runs on the output of the target's clang. CMAKE_MSVC_RUNTIME_LIBRARY is MultiThreaded unless set, and a link with MultiThreadedDebug or MultiThreadedDebugDLL gets /nodefaultlib:ucrt.lib. The SDK is added to CMAKE_FIND_ROOT_PATH, except on a Windows host for its own architecture, which is no cross build to CMake, and on a Windows host without one.

For a macOS target on a Linux or Windows host, CMAKE_OSX_SYSROOT is the one given, else SDKROOT, else the toolchain's sdk/macos, and it stops if that has no SDK. It sets CMAKE_SYSTEM_NAME to Darwin, CMAKE_SYSTEM_PROCESSOR and CMAKE_OSX_ARCHITECTURES to arm64 or x86_64, CMAKE_<LANG>_COMPILER_TARGET (C, C++, ASM, Objective-C), and adds the SDK to CMAKE_FIND_ROOT_PATH, with the modes above.

Runtimes from Source ​

runtimes.cmake, which the toolchain file includes, reads these variables (runtimes from source):

variable
XCLANG_RUNTIMESprebuilt, the default: the toolchain's runtimes. source: libc++ (with libc++abi), libc++experimental and libunwind built from the toolchain's libc++/src for the target, with the options below, at the first configure that asks for the variant; every compile and link of the build is against them in place of the prebuilt ones, try_compile's too. Not for the MSVC targets
XCLANG_SANITIZERa list of address, memory, thread, undefined, leak: -fsanitize= on every compile and link of the build, and runtimes that suit it. With the prebuilt runtimes, address adds the ASan libc++ where the target has one, and memory stops the configure; with source, the runtimes are built with the sanitizers (LLVM_USE_SANITIZER: ASan with UBSan if both are named, else one of MemorySanitizer, ThreadSanitizer, UBSan and LeakSanitizer, in that order), and memory builds compiler-rt's MemorySanitizer runtime too, linked into executables; memory for the glibc Linux targets. A sanitizer whose runtime the target has not stops the configure: the Windows targets have undefined, and x64 address; the musl targets undefined
XCLANG_LIBCXX_HARDENINGnone, fast, extensive or debug: libc++'s hardening mode (LIBCXX_HARDENING_MODE), of the library and the default of its headers
XCLANG_LIBCXX_ABI_VERSION1 or 2 (LIBCXX_ABI_VERSION)
XCLANG_LIBCXX_ABI_NAMESPACElibc++'s inline namespace, __<name> (LIBCXX_ABI_NAMESPACE)
XCLANG_LIBCXX_ABI_DEFINESa list of libc++'s ABI macros, such as _LIBCPP_ABI_BOUNDED_ITERATORS (LIBCXX_ABI_DEFINES)
XCLANG_RUNTIMES_EXCEPTIONSOFF, or another false CMake boolean: libc++ and libc++abi without exceptions
XCLANG_RUNTIMES_RTTIOFF, or another false CMake boolean: libc++ without RTTI; needs XCLANG_RUNTIMES_EXCEPTIONS=OFF
XCLANG_RUNTIMES_FLAGSmore compile options of libc++ and libc++abi, such as -flto=thin
XCLANG_RUNTIMES_CMAKE_ARGSmore arguments of the runtimes' CMake build, LLVM's runtimes/, -D<variable>=<value> each
XCLANG_RUNTIMES_DIRwhere the variants are built, <target>-<digest> each; ${CMAKE_BINARY_DIR}/xclang-runtimes by default; a relative path is relative to the build directory

The options but XCLANG_RUNTIMES and XCLANG_SANITIZER need XCLANG_RUNTIMES=source. A variant's directory holds its CMake builds (runtimes, and with MemorySanitizer compiler-rt), their logs, and install: include/c++/v1, the headers, __config_site among them, which come before the config file's with -nostdinc++; lib, the libraries, linked with -nostdlib++ and, but for macOS and with sanitizers, --unwindlib=none; lib/libc++.modules.json and share/libc++/v1, the modules of xclang::std. Its name is a digest of the options, the target and the toolchain, so a variant is built once per build directory, and another set of options builds another beside it. The build needs Python 3, as LLVM's does.

xclang.cmake ​

Included before project(), from a FetchContent checkout of the tag of a release (CMake has the snippet):

cmake
include(${xclang_SOURCE_DIR}/packages/cmake/xclang.cmake)
variable
XCLANG_VERSIONthe release to download; without it, the release tagging the checkout
XCLANG_TARGETanother target to build for, as for toolchain.cmake
XCLANG_ROOTan unpacked xclang to use instead of downloading one
XCLANG_CACHE_DIRwhere toolchains are unpacked, <version>/<host> each (also an environment variable); by default $XDG_CACHE_HOME/xclang or ~/.cache/xclang, ~/Library/Caches/xclang on macOS, %LOCALAPPDATA%\xclang on Windows
XCLANG_URLwhere SHA256SUMS and the archives are downloaded from, a mirror of the release; its SHA256SUMS is then the one trusted

It downloads the SHA256SUMS of the release and the host archive, xclang-<version>-<host>.tar.xz, checking the server's certificate, and checks the archive against its line. It unpacks the archive aside and moves it into the cache, so that build trees configured at once do not clash. Then it sets CMAKE_TOOLCHAIN_FILE. It stops if the build already has a toolchain file, such as vcpkg's; vcpkg chain-loads xclang's instead (VCPKG_CHAINLOAD_TOOLCHAIN_FILE). A build directory keeps the toolchain file of its first configure: when the release, XCLANG_ROOT or XCLANG_CACHE_DIR changes, it stops before downloading, for a new build directory or cmake --fresh.

libclang's Package ​

The libclang archives carry the own CMake packages of LLVM and clang (find_package(Clang)). They also carry lib/cmake/xclang/libclang.cmake, which records the build: XCLANG_LLVM_VERSION, XCLANG_LTO, XCLANG_PGO, XCLANG_PATCHES and the like (libclang).