Quick Start
From one machine, you will install xclang, cross-compile a C++ program for Linux, Windows and macOS targets, inspect its runtime dependencies, and build a CMake project that uses import std for the host and for Windows on Arm.
Prerequisites
- pixi and git.
- bash (Git Bash on Windows).
- On macOS, Xcode or the Command Line Tools, whose SDK the macOS targets build against.
- For step 4, CMake 3.28 or later and Ninja 1.11 or later (
pip install cmake ninja).
1. Install with pixi
Clone the repository and enter examples/quickstart:
git clone --depth 1 https://github.com/clice-io/xclang
cd xclang/examples/quickstartpixi.toml configures a pixi workspace with xclang from the clice conda channel:
[workspace]
name = "hello"
channels = ["conda-forge", "https://conda.clice.io"]
platforms = ["linux-64", "linux-aarch64", "osx-64", "osx-arm64", "win-64", "win-arm64"]
[dependencies]
xclang = "*"pixi installThe package unpacks the host archive, with every bundled target, into $PREFIX/opt/xclang (the toolchain directory, $XCLANG in commands; archive layout). pixi run and pixi shell put $PREFIX/opt/xclang/bin first in PATH without placing files in $PREFIX/bin, so conda-forge's compilers stay untouched. The channel also publishes llvm-option-inc (noarch), which installs the option tables into $PREFIX/include/llvm-options-td (libclang).
2. Build a Program for Other Targets
hello.cpp throws and catches an exception, which exercises the C++ standard library and unwinder:
#include <iostream>
#include <stdexcept>
#include <string>
int main() {
try {
throw std::runtime_error("hello from xclang");
} catch (const std::exception& e) {
std::cout << e.what() << '\n';
}
}Build it for the host, and for the glibc Linux and MinGW Windows targets:
pixi run clang++ -O2 hello.cpp -o hello
./hello
pixi run clang++ -O2 --target=x86_64-unknown-linux-gnu hello.cpp -o hello-linux-x64
pixi run clang++ -O2 --target=aarch64-unknown-linux-gnu hello.cpp -o hello-linux-arm64
pixi run clang++ -O2 --target=x86_64-w64-mingw32 hello.cpp -o hello-windows-x64.exe
pixi run clang++ -O2 --target=aarch64-w64-mingw32 hello.cpp -o hello-windows-arm64.exe./hello prints hello from xclang. On a Windows host, the first command writes hello.exe because a MinGW link appends .exe when the output name has no extension. On a macOS host, build the macOS targets too:
pixi run clang++ -O2 --target=aarch64-apple-darwin hello.cpp -o hello-macos-arm64
pixi run clang++ -O2 --target=x86_64-apple-darwin hello.cpp -o hello-macos-x64You do not need to install a sysroot or pass --sysroot or -L. For each --target, clang reads that target's config file in xclang's bin/, which points it to the bundled sysroot and runtimes. Building static Linux programs with musl, building for MSVC targets, and building for macOS from Linux and Windows hosts are covered in cross-compiling.
3. Check What the Programs Need
Inspect the shared libraries that the Linux and Windows binaries load at run time:
pixi run llvm-readobj --needed-libs hello-linux-x64 hello-windows-x64.exeOn every host, this prints only the OS's own libraries (trimmed here):
File: hello-linux-x64
NeededLibraries [
ld-linux-x86-64.so.2
libc.so.6
libdl.so.2
libm.so.6
libpthread.so.0
]
File: hello-windows-x64.exe
NeededLibraries [
KERNEL32.dll
api-ms-win-crt-convert-l1-1-0.dll
api-ms-win-crt-environment-l1-1-0.dll
...
api-ms-win-crt-time-l1-1-0.dll
]A macOS binary loads only /usr/lib/libSystem.B.dylib. None of the binaries depends on libstdc++.so.6, libc++.dll, libgcc_s_seh-1.dll or libwinpthread-1.dll. Each binary runs as a single file on any machine of its target: glibc 2.17 or later on Linux, Windows 10 or later, or macOS 13 or later (hermeticity).
4. Build a CMake Project with import std
examples/cmake is a C++23 project that imports the standard library module:
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());
}
}Configure, build and run it for the host:
pixi run cmake -G Ninja -S ../cmake -B build -DCMAKE_CXX_COMPILER=clang++
pixi run cmake --build build
./build/helloIt prints hello from xclang: 3 targets, the first linux. xclang::std compiles the std and std.compat modules of libc++ for this build with its language options, without an experimental CMake switch (C++20 modules).
Now cross-compile the same project for Windows on Arm using xclang's CMake toolchain file:
XCLANG=$PWD/.pixi/envs/default/opt/xclang
pixi run cmake -G Ninja -S ../cmake -B build-aarch64-w64-mingw32 \
--toolchain "$XCLANG/lib/cmake/xclang/toolchain.cmake" -DXCLANG_TARGET=aarch64-w64-mingw32
pixi run cmake --build build-aarch64-w64-mingw32XCLANG_TARGET accepts any target of the toolchain, including the MSVC targets and macOS targets from Linux and Windows once their SDK is fetched (CMake). Copy build-aarch64-w64-mingw32/hello.exe to a Windows on Arm machine, and it runs there with nothing installed.
Other Ways to Install
Release Archives
Every GitHub release publishes a toolchain archive for each host, xclang-<version>-<host>.tar.xz (about 100 MB; releases). Unpack it anywhere and run the tools from xclang/bin/. On Linux:
h=x86_64-unknown-linux-gnu
curl -LO https://github.com/clice-io/xclang/releases/latest/download/SHA256SUMS
v=$(sed -n "s/^[0-9a-f]* xclang-\(.*\)-$h\.tar\.xz$/\1/p" SHA256SUMS)
curl -LO https://github.com/clice-io/xclang/releases/download/$v/xclang-$v-$h.tar.xz
sha256sum -c --ignore-missing SHA256SUMS
tar -xf xclang-$v-$h.tar.xz
xclang/bin/clang++ --target=aarch64-w64-mingw32 hello.cpp -o hello.exeOn macOS, verify the digest with shasum -a 256 -c --ignore-missing SHA256SUMS. On Windows, use PowerShell, where tar is C:\Windows\System32\tar.exe:
$h = "x86_64-w64-mingw32"
curl.exe -LO https://github.com/clice-io/xclang/releases/latest/download/SHA256SUMS
$v = (Select-String -Path SHA256SUMS -Pattern " xclang-(.+)-$h\.tar\.xz$").Matches[0].Groups[1].Value
curl.exe -LO https://github.com/clice-io/xclang/releases/download/$v/xclang-$v-$h.tar.xz
$sum = (Get-FileHash xclang-$v-$h.tar.xz -Algorithm SHA256).Hash.ToLower()
if (-not (Select-String -SimpleMatch -Quiet "$sum xclang-$v-$h.tar.xz" SHA256SUMS)) { throw "sha256 mismatch" }
tar -xf xclang-$v-$h.tar.xz
xclang\bin\clang++ --target=aarch64-unknown-linux-gnu hello.cpp -o helloTo pin a release, set v to its version and download SHA256SUMS from releases/download/$v. A Windows archive contains no symbolic links, so it unpacks without administrator rights or Developer Mode (the launchers). Vendor SDKs that xclang sdk fetch adds on Windows are reached through junctions with absolute paths; after moving the toolchain directory, run xclang sdk use <name> (and fetch a macOS SDK again; the xclang command).
CMake FetchContent
A CMake project can download the host toolchain before project(), so the build configures on a machine with only CMake, Ninja and Git installed (CMake):
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)xclang.cmake downloads the host archive for the release, verifies it against the release's SHA256SUMS, and unpacks it into the user's cache once per release and host.
Bazel
Add the clice registry at bazel.clice.io to .bazelrc and declare xclang in MODULE.bazel (Bazel):
common --registry=https://bazel.clice.io/
common --registry=https://bcr.bazel.build/bazel_dep(name = "xclang", version = "23.1.5.1")The module downloads the host archive verified by its pinned sha256 and registers it as the C++ toolchain for every target.
Check It Works
Run clang++ --version from PATH or from the toolchain directory to print the compiler version and InstalledDir, the bin/ directory it runs from:
pixi run clang++ --versionxclang --version prints its own version, the toolchain directory and its release version, <llvm version>.<revision> (releases).
Next
- Cross-Compiling: all targets, vendor SDKs, and running what you built.
- CMake, Bazel, Make and Meson, Cargo.
- Releases: versions, channels, release assets, and verifying downloads.
