Skip to content

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:

sh
git clone --depth 1 https://github.com/clice-io/xclang
cd xclang/examples/quickstart

pixi.toml configures a pixi workspace with xclang from the clice conda channel:

toml
[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 = "*"
sh
pixi install

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

cpp
#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:

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

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

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

sh
pixi run llvm-readobj --needed-libs hello-linux-x64 hello-windows-x64.exe

On every host, this prints only the OS's own libraries (trimmed here):

text
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
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)
cpp
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:

sh
pixi run cmake -G Ninja -S ../cmake -B build -DCMAKE_CXX_COMPILER=clang++
pixi run cmake --build build
./build/hello

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

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

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

sh
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.exe

On macOS, verify the digest with shasum -a 256 -c --ignore-missing SHA256SUMS. On Windows, use PowerShell, where tar is C:\Windows\System32\tar.exe:

powershell
$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 hello

To 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):

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/
python
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:

sh
pixi run clang++ --version

xclang --version prints its own version, the toolchain directory and its release version, <llvm version>.<revision> (releases).

Next ​