Skip to content

Plain Clang, Make and Meson ​

Any build tool that invokes a compiler by name works with xclang. Put xclang's bin/ first in PATH (as pixi shell does) or invoke the binaries by path, and pass --target=<triple> to build for another target.

Requires: xclang's bin/ in PATH (Install).

Clang ​

Run clang or clang++ for the host, or add --target=<triple> for another target. These are the commands from the quick start for hello.cpp:

sh
clang++ -O2 hello.cpp -o hello
clang++ -O2 --target=x86_64-unknown-linux-gnu hello.cpp -o hello-linux-x64
clang++ -O2 --target=aarch64-unknown-linux-gnu hello.cpp -o hello-linux-arm64
clang++ -O2 --target=x86_64-w64-mingw32 hello.cpp -o hello-windows-x64.exe
clang++ -O2 --target=aarch64-w64-mingw32 hello.cpp -o hello-windows-arm64.exe

Each target has a config file (bin/<triple>.cfg) that selects its sysroot or SDK, links libc++, libunwind and compiler-rt statically, uses lld, and sets the OS floor (Cross-Compiling, Toolchain Design). Clang's alternate target spellings, such as x86_64-pc-linux-gnu or arm64-apple-macos, load the same config files.

  • musl targets: --target=x86_64-unknown-linux-musl and --target=aarch64-unknown-linux-musl build static Linux binaries (musl targets).

  • macOS targets: --target=aarch64-apple-darwin and --target=x86_64-apple-darwin build against Xcode's SDK on macOS hosts, and against the SDK fetched by xclang sdk fetch macos --accept-license on Linux and Windows hosts (macOS).

  • MSVC targets: --target=x86_64-pc-windows-msvc, --target=aarch64-pc-windows-msvc and clang-cl build against the Windows SDK fetched by xclang sdk fetch windows --accept-license, or an installed Visual Studio on Windows hosts (MSVC targets).

  • The platform's C++ library: -stdlib=platform (or /clang:-stdlib=platform with clang-cl) selects <triple>-system.cfg and builds against the target's system C++ library: libstdc++ on Linux and MinGW, Microsoft's STL on MSVC, or /usr/lib/libc++.1.dylib on macOS (the platform's C++ library). --no-default-config disables xclang's config files altogether.

  • GCC compatibility: Build scripts written for GCC work without changes. -latomic, -lgcc, -lgcc_eh, -lgcc_s and (on Windows) -lssp resolve to empty stub archives, -lstdc++ links libc++, and windres invokes llvm-windres (GCC library names, Hermeticity).

Make ​

Include --target=<triple> in CC and CXX so every compile and link rule receives it. The project is examples/make:

make
# make CXX=clang++
# make -B CXX="clang++ --target=aarch64-unknown-linux-gnu"
hello: hello.cpp
	$(CXX) $(CXXFLAGS) -O2 hello.cpp -o $@ $(LDFLAGS)
sh
make CXX=clang++
./hello

Pass -B when switching targets so make rebuilds targets that are already present on disk:

sh
make -B CXX="clang++ --target=aarch64-unknown-linux-gnu"

When a build creates static archives, also pass AR=llvm-ar and RANLIB=llvm-ranlib. Autotools configure scripts accept the same CC, CXX, AR and RANLIB variables.

Meson ​

Set CC=clang and CXX=clang++ (or list clang, clang++, llvm-ar and llvm-strip under [binaries] in a --native-file) to configure Meson for the host. The project is examples/meson:

sh
CXX=clang++ meson setup build
meson compile -C build
./build/hello

For another target, pass a --cross-file that sets --target=<triple> in [binaries] and describes the target in [host_machine]:

ini
[binaries]
c = ['clang', '--target=aarch64-w64-mingw32']
cpp = ['clang++', '--target=aarch64-w64-mingw32']
ar = 'llvm-ar'
strip = 'llvm-strip'
windres = ['llvm-windres', '--target=aarch64-w64-mingw32']

[host_machine]
system = 'windows'
cpu_family = 'aarch64'
cpu = 'aarch64'
endian = 'little'
sh
meson setup build-aarch64-w64-mingw32 --cross-file cross/aarch64-w64-mingw32.ini
meson compile -C build-aarch64-w64-mingw32

cross/aarch64-unknown-linux-gnu.ini in the same directory configures Linux on Arm64 with system = 'linux' and without windres.

Turn On libc++ Hardening ​

The prebuilt libc++ archive is compiled with hardening mode none. Because hardening checks in headers are controlled per translation unit, pass -D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_FAST (or _EXTENSIVE or _DEBUG) on the compiler command line to turn them on. To enable hardening assertions inside the compiled libc++ library as well, build the runtimes from source in CMake or Bazel (Runtimes from Source).

Features ​

  • C++20 modules and import std: Precompile std.cppm and your module interfaces with --precompile (C++20 Modules).
  • Sanitizers: Pass -fsanitize=..., and add -L$XCLANG/<target>/lib/asan on Linux, MinGW and macOS when linking with AddressSanitizer (Sanitizers).
  • Debug symbols: Run dsymutil and llvm-gsymutil from the toolchain's bin/ to extract .dSYM and .gsym files (Debugging).
  • libclang and the ThinLTO cache: Link the archives from libclang-<version>-<target>.tar.xz with the ThinLTO cache flag for your target's linker (libclang, the ThinLTO cache).