What is xclang?
xclang is a clang toolchain for cross-compiling: one compiler for every target. One directory holds the compiler, the linker, the binary tools, and the sysroot (the C library's headers and libraries) and prebuilt runtimes for eight targets. Cross-compiling is a --target flag and nothing else:
clang++ --target=aarch64-w64-mingw32 hello.cpp -o hello.exeWhat Is in a Release
- clang, lld and the LLVM binary tools, built from stock LLVM with a few patches on their way upstream, packaged as one multicall program (
llvm) and linked statically against xclang's ownlibc++for six hosts (toolchain structure). - Eight targets in every archive: Linux x64 and arm64 (glibc 2.17, and musl 1.2.6 for static programs), Windows x64 and arm64 (MinGW-w64 with UCRT), and macOS arm64 and x64. Each target has its sysroot,
libc++,libc++abi,libunwindandcompiler-rt, prebuilt, and a config file that pointsclangat them (cross-compiling). - The MSVC targets, Windows x64 and arm64 with Microsoft's CRT and xclang's
libc++(or Microsoft's STL), from every host, against the SDK that thexclangcommand fetches from Microsoft or an installed Visual Studio on Windows (Windows, Windows design). - The
xclangcommand: it fetches the Apple and Microsoft SDKs that no one may redistribute, andxclang cargobuilds Rust for xclang's targets with no cargo config (thexclangcommand, Rust and Cargo). - A CMake package and a Bazel module, for the host or any target, with
import stdbuilt for the build (CMake, Bazel). - The runtimes' sources, which the CMake package and the Bazel module build on demand for MemorySanitizer and for
libc++'s hardening and ABI options, for every target but the MSVC ones (runtimes from source). - libclang: the static libraries and headers of
clangand LLVM that the release was built from, for tools built onclang(libclang).
Targets and features that no release has yet are in the roadmap.
What It Does for a Build
A C++ build is hermetic when its output depends only on its declared inputs: the same sources and toolchain give the same program on any machine and in any directory. That is what xclang is built for.
- Reproducible. A release is never replaced: a rebuild is the next revision. The Bazel module and CMake download check every archive by its
sha256. In Bazel builds, no command line or debug information holds an absolute path except for Xcode's macOS SDK, so a build in a second checkout produces the same bytes (the Bazel module). - Portable programs. A program depends at run time only on the system libraries every installation of its OS has: glibc 2.17 or later on Linux (or nothing with musl), Windows 10 or later, or macOS 13 or later.
libc++and the other runtimes are linked in, and build scripts written for GCC (-latomic,-lgcc_s,-lstdc++) link unchanged (hermeticity). - One compiler for every target.
clangcompiles for every LLVM target, and xclang ships the target libraries beside it. Selecting a target takes only--target=<triple>, and a compiler upgrade applies to all targets at once (cross-compiling). - Correct build caches. With a compiler taken from the machine, a new compiler version leaves a build cache serving objects from the old one. In Bazel, every toolchain file that an action reads is a declared input, so a new release rebuilds what it should, and module files are inputs of their importers (the Bazel module, C++20 modules).
- C++20 modules. A module file is usable only by importers compiled with the same language options, so a prebuilt
stdmodule cannot be shipped. xclang compileslibc++'sstdandstd.compatmodules for each build with its options, asxclang::stdin CMake without experimental switches and@xclang//bazel:stdin Bazel (C++20 modules). - Fast.
clangandlldare built with PGO and ThinLTO on every host, trained on compiling real C and C++ code, precompiled headers, C++20 modules and code completion (PGO).libclangships as ThinLTO bitcode, and the ThinLTO cache reduces relinks of tools built on it to seconds (libclang). - Correctness tools. xclang ships sanitizer runtimes along with an ASan build of
libc++that prevents false container-overflow reports (sanitizers), and builds the runtimes from source for MemorySanitizer (runtimes from source). Debug symbols come apart from the program: GSYM files, the same on every run, for every target but the MSVC ones, which have PDBs, and dSYMs for macOS (debugging). - Supply chain. Every archive is listed in
SHA256SUMS, built from LLVM's release tarball with documented patches, made twice on two machines and compared byte for byte, and packaged with its components' licenses and an SPDX document (releases, archive layout). Vendor SDKs are never in an archive; you fetch them from the vendor, pinned by version andsha256(thexclangcommand). - One toolchain for every build. The same toolchain directory serves plain clang, Make and Meson, CMake, Bazel, and cargo, from pixi, an archive, FetchContent or the Bazel registry (quick start).
Who It Is For
- Projects that ship programs to user machines: command-line tools, language servers and build tools that run as a single file without a redistributable or Homebrew.
- CI that builds for several targets from one runner OS, with one compiler version for all of them (CI).
- Teams that pin one toolchain across developer machines and CI, in CMake, Bazel and plain commands.
- C++20 modules with
import std, in CMake and Bazel. - Tools on clang, which link
libclangbuilt with PGO.
xclang is developed for clice, whose release builds are its first user. catter builds with it too. xclang's CI cross-compiles the tests of kotatsu for Windows from Linux and runs them on Windows.
What It Is Not
- C++ libraries from another toolchain need its C++ library. xclang's C++ library is
libc++, linked into every program. A C++ library built with GCC'slibstdc++or MSVC's STL has another ABI. Build C++ dependencies with xclang for the target, or pass-stdlib=platformto use the platform's C++ library and give up self-contained programs (cross-compiling). C libraries are not affected. - One
libc++per shared object. Each shared library carries its ownlibc++, so C++ objects should not cross shared libraries, and on Linux and macOS a standard exception thrown in one is caught in another only bycatch (...)(hermeticity, roadmap). - No OpenMP runtime, and no
clang-format,clang-tidyorclangdprograms. xclang is a compiler toolchain (OpenMP, tool binaries). - Not for conda-forge packages. Use conda-forge's compilers, which link its shared runtime packages through
run_exports; xclang does not (roadmap).
Next
- Quick Start: install xclang, build programs for every target, and build a CMake project with
import std. - Cross-Compiling: targets, vendor SDKs, and platform details.
- Releases: version tags, channels, assets, and verifying downloads.
