The Bazel Module
xclang's Bazel module (packages/bazel) makes C++ builds hermetic and cacheable across checkouts and machines: every toolchain and SDK file an action reads is a declared Bazel input, no command line or build output contains an absolute path (except for Xcode's SDK and native sanitizer rpaths on macOS hosts), and cc_library dependencies link statically into programs and tests by default. How to set up and use the module is in Bazel, and its labels, flags and features are in the Bazel API.
Every Toolchain File Is an Input
The xclang_toolchain repository rule downloads the host toolchain archive by its pinned sha256 from bazel/versions.bzl. Every file of the archive that a compile or link action reads is declared in its cc_toolchain filegroups: the binaries in bin/, clang's resource headers, the target's sysroot headers and shared libc++ / mingw-w64 headers for compiling, and the target's sysroot libraries and compiler-rt for linking. Vendor SDKs fetched by the module extension are declared inputs in the same way (below); the only host path outside Bazel is Xcode's macOS SDK on macOS hosts, located by xcrun --show-sdk-path.
Before the module existed, xclang's Bazel setup wrapped a clang found on PATH with no declared toolchain files, which broke caching in two ways:
- Any change to
PATHinvalidated the toolchain repository and rebuilt the workspace. - Upgrading
clangonPATHchanged no action input, so the build cache continued serving object files from the previous compiler.
Declaring every toolchain file as an action input fixes both: upgrading the xclang module changes the input digests of every compile and link action and triggers a rebuild, while building with the same release in another directory or on another machine shares cache hits.
The trade-off is sandbox staging: Bazel's sandbox creates links for thousands of declared toolchain files on every compile and link action. On Windows hosts, Bazel runs actions without a sandbox by default (unless --experimental_use_windows_sandbox is enabled), so missing input declarations are caught by Linux and macOS builds of the same targets instead; and because Bazel's default output root on Windows exceeds path length limits when staging deep toolchain and SDK trees, Windows hosts set startup --output_user_root=C:/b (on a Windows host).
No Absolute Paths
A disk or remote cache can reuse an action across directories and machines only when both the action command line and the action outputs contain no checkout-, output-base- or sandbox-specific paths. packages/bazel removes absolute paths from every compile, module and link action:
- Rewritten config files:
clangresolves<CFGDIR>in a config file to an absolute path, which then enters.ddependency files. During repository setup,_bazel_cfg(bazel/repositories.bzl) writes copies of each target's config files intocfg/with<CFGDIR>/..replaced byexternal/<repository>and-resource-dir=external/<repository>/lib/clang/<major>, and the toolchain passes--no-default-config --config=external/<repository>/cfg/<target>.cfg. - Relative tool prefixes:
-no-canonical-prefixesin compile and link flags, and wrapper scripts (scan_depsanddsym_link) that locate tools relative to their own directory. - Debug information and binary timestamps:
-ffile-compilation-dir=.on every compile;-Wl,-oso_prefix,.on macOS links;-Wl,--no-insert-timestampon MinGW links; and on MSVC targets-mno-incremental-linker-compatibleand-gno-codeview-command-lineon compiles (keeping Windows launcher paths out of CodeView records),-Wl,/Breproon links,/pdbsourcepath:.for PDB source paths, and PDB names embedded without a directory prefix (paths in debug information). - C++20 module files:
-Xclang -fmodule-file-home-is-cwdso.pcmfiles record input paths relative to the execution root, and-Xclang -fmodules-embed-all-files(modules_embed_all_files, on by default) so importers compiled with-gread source text from the.pcmitself inside the sandbox (build caches and modules). - Preprocessor timestamps:
-Wno-builtin-macro-redefinedwith__DATE__,__TIME__and__TIMESTAMP__defined to"redacted".
Two absolute paths remain on macOS hosts: Xcode's SDK path (-isysroot), which comes from the host machine, and -Wl,-rpath,<absolute_root>/lib/clang/<major>/lib/darwin when a sanitizer feature is enabled for a native macOS build so the binary finds the sanitizer .dylib at run time.
A Toolchain per Host and Target
Because every host archive contains the sysroots and runtimes for all bundled targets, the module registers a cc_toolchain for every (host, target) pair: exec_compatible_with the host OS and CPU, and target_compatible_with the target platform. Bazel selects the toolchain matching the host machine and the --platforms target, and downloads only that host's toolchain archive.
For targets that require a vendor SDK (the MSVC targets, and the macOS targets on Linux and Windows hosts), a build without the corresponding tag in the root MODULE.bazel resolves to a toolchain that fails immediately at analysis time and prints the required xclang.windows_sdk or xclang.macos_sdk tag.
The platforms in @xclang//platforms:<target> declare @platforms//os, @platforms//cpu and a C library constraint (@xclang//platforms/libc:glibc, :musl, :mingw, :macosx or :msvc). Because the musl toolchains (//bazel/toolchains/musl:all) and MSVC toolchains (//bazel/toolchains/msvc:all) require :musl or :msvc and are registered in MODULE.bazel ahead of //bazel/toolchains:all (which match on OS and CPU alone), a custom platform without a libc constraint defaults to glibc on Linux and MinGW on Windows.
rules_cc's Config, Copied
Changing a .bzl file in another Bazel module through single_version_override patches only works when placed in the root MODULE.bazel, which would require every project using xclang to carry patch files in its own repository; and patching the build's rules_cc repository in place breaks whenever a new rules_cc version edits nearby lines (as rules_cc 0.2.28 did). Migrating to rules_cc's rule-based toolchain API would have required reimplementing --macos_minimum_os, libtool, dead stripping and sanitizer features.
packages/bazel/bazel/unix_cc_toolchain_config.bzl therefore carries xclang's own copy of rules_cc 0.2.28's unix_cc_toolchain_config.bzl. Because the copy loads only public files from rules_cc, apple_support and bazel_skylib, it works with any rules_cc 0.2.25 or later without a consumer override.
Compared to upstream rules_cc, xclang's config and bazel/toolchain.bzl add:
.exeand.dlloutput names for MinGW and MSVC targets, and norpathon Windows;- MSVC target support using the GNU-style
clangdriver withlld-linkflags,-std=c++17by default, no PIC, PDB generation (generate_pdb_file), CRT selection (dynamic_link_msvcrt,debug_msvcrt), and runtime DLL staging (copy_dynamic_libraries_to_binary); - static linking of
cc_librarydependencies by default (below); - external repositories' headers passed via
-isystem(external_include_pathson by default) so dependency warnings do not fail the build; - sanitizer flags, switching to the prebuilt ASan
libc++underasan, buildinglibc++,libc++abiandlibunwindfromlibc++/srcunder--@xclang//runtimes:source, and supporting MemorySanitizer (msan) on the glibc Linux targets (runtimes from source); gc_sectionsenabled inopton Linux and disabled by default on Windows (gc-sectionsand static initializers);- macOS links without
-fobjc-link-runtimeunlessmacos_default_link_flagsis enabled,--macos_minimum_osclamped to at least13.0, library objects passed between--start-liband--end-libon Linux and macOS (sodsymutilnever confuses same-named archive members with zeroed Bazel timestamps), anddsym_linkgenerating the.dSYMbundle during the link withdsymutil --linker classic(avoiding DWARF 5 line tables from LLVM 23's parallel linker that crashatos; why a dSYM comes from the link); - format-specific binary stripping (
--strip-unneededfor ELF and COFF,--strip-allwith-Wl,-no_exported_symbolsinoptfor Mach-O; strip); - library
definespassed to C++20 module compiles andclang-scan-depsscans on macOS as on Linux and Windows.
Static by Default
By default, rules_cc links cc_library dependencies of cc_test targets as separate shared libraries when supports_dynamic_linker is enabled. Because every shared library linked by xclang carries its own private static libc++ (one libc++ per shared object), linking each cc_library as a shared object gave each library a separate libc++ instance (causing kotatsu's tests to crash at startup with a double free, and failing to link on Windows).
The toolchain config therefore disables supports_dynamic_linker by default so cc_library targets link statically into executables and tests. cc_binary(linkshared = True) still produces shared libraries (libfoo.so, libfoo.dylib, foo.dll), and features = ["supports_dynamic_linker"] re-enables dynamic linking for Linux targets.
Vendor SDKs as Repositories
The MSVC targets require Microsoft's CRT, STL and Windows SDK, and the macOS targets on Linux and Windows hosts require Apple's macOS SDK. Whereas plain clang and CMake unpack fetched SDKs into <toolchain>/sdk/ with the xclang command, a Bazel build cannot write into the toolchain repository and must declare every SDK file as an input. bazel/sdk.bzl manages each vendor SDK as its own external repository:
- License acceptance in the root
MODULE.bazel: onlyxclang.windows_sdkandxclang.macos_sdktags in the root module (mod.is_root) take effect, so a dependency module cannot accept a vendor license on behalf of its consumers. - Bazel downloads,
xclangunpacks: the repository rule runsxclang sdk packages <vendor> --jsonto query the pinned package URLs, sizes andsha256digests, downloads them withrctx.downloadinto Bazel's shared repository cache (applying any configured Bazel mirror, proxy or--distdir), and invokesxclang sdk fetch <vendor> --accept-license --cache downloads --sdk-dir sdkto unpack the archive and create case-folding links on case-sensitive file systems. When Apple withdraws a pinned macOS Command Line Tools package,xclang sdk fetchlocates the replacement package in Apple's catalogs and verifies the unpacked SDK by its content digest (packages Apple withdraws). - Generated
sdk.cfg: each SDK repository writessdk.cfgwith paths relative to the execution root (-isysroot external/<repo>/sdk/<name>for macOS, and the rewritten<arch>-pc-windows-msvc.cfgnaming the MSVC and Windows SDK version directories for MSVC targets), which the toolchain'scfg/<target>.cfgincludes via@../../<sdk_repo>/sdk.cfg. - Lazy per-architecture repositories:
xclang_windows_sdk_x86_64(310 MB download),xclang_windows_sdk_aarch64(380 MB download) andxclang_macos_sdkare fetched only when a build targets that platform. - Split compile and link filegroups:
BUILD.bazelin the SDK repository exports:compiler_filesand:linker_filesviaglob(). For the macOS SDK,_unlink_cyclesremoves directory symlink cycles (such asRuby.framework'sHeaders/ruby/ruby -> .) beforeglob()runs;:compiler_filesstages the headers and frameworks (15,000 files) and:linker_filesstages the.tbdstubs andSDKSettings.*(9,800 files). For an MSVC target,:compiler_filesdeclares 7,300 headers and links and:linker_filesdeclares 1,300 libraries.
The Registry
After published.yml builds and tests a release tag against the published release assets, node packages/bazel/bazel.ts archive builds xclang-bazel-<version>.tar.gz and publishes the module to bazel.clice.io. bazel.ts constructs the ustar archive deterministically in memory—sorted entries, 0755/0644 permissions, zeroed owner and timestamp fields, and gzip's OS header byte set to 255—so the registry archive is identical byte for byte on every host.
