Skip to content

Bazel API ​

Everything the xclang Bazel module offers. How to use it is in Bazel; this page is the list. The module needs Bazel 9 and rules_cc 0.2.25 or later. It is packages/bazel of the repository, and is published to bazel.clice.io for every release.

Toolchains ​

The module registers, for every host, one C++ toolchain per target: @xclang//bazel/toolchains:<host> for the host itself, and <host>-to-<target> for the others, @xclang//bazel/toolchains/musl:<host>-to-<target> for the musl targets and @xclang//bazel/toolchains/msvc:<host>-to-<target> for the MSVC ones, registered first. Each is the host archive configured for the target, and only the archive of the machine Bazel runs on is downloaded. The MSVC targets, and the macOS targets off macOS hosts, build against the vendor SDK the root module fetches (tags); without it, their toolchain fails the build and says why.

Every toolchain:

  • builds Windows programs named .exe, and shared libraries named .dll;
  • links libraries statically into tests and programs (static by default);
  • compiles the headers of other repositories as system headers (-isystem);
  • redacts __DATE__, __TIME__ and __TIMESTAMP__;
  • puts no absolute path on a command line (no absolute paths).

Platforms ​

@xclang//platforms:<target>, for --platforms:

platformalsotarget
x86_64-unknown-linux-gnux86_64-linux-gnuLinux x64, glibc 2.17
aarch64-unknown-linux-gnuaarch64-linux-gnuLinux arm64, glibc 2.17
x86_64-w64-mingw32x86_64-w64-windows-gnuWindows x64, MinGW-w64 (UCRT)
aarch64-w64-mingw32aarch64-w64-windows-gnuWindows arm64, MinGW-w64 (UCRT)
aarch64-apple-darwinarm64-apple-darwinmacOS arm64; off macOS hosts, with Apple's SDK
x86_64-apple-darwinmacOS x64; off macOS hosts, with Apple's SDK
x86_64-pc-windows-msvcWindows x64, MSVC ABI, with Microsoft's SDK
aarch64-pc-windows-msvcWindows arm64, MSVC ABI, with Microsoft's SDK
x86_64-unknown-linux-muslx86_64-linux-muslLinux x64, musl, static
aarch64-unknown-linux-muslaarch64-linux-muslLinux arm64, musl, static

Each has @platforms//os, @platforms//cpu and a C library, @xclang//platforms/libc:glibc, :musl, :mingw, :macosx or :msvc. The toolchains ask a platform for os and cpu only, but those of musl and of the MSVC targets, which ask for :musl or :msvc too; so a platform of one's own with an os and a cpu works, and gets glibc on Linux and MinGW on Windows unless it names one of those.

Features ​

featuredefault
asan, tsan, ubsan, lsanoffsanitizers, for the whole build (--features=asan); asan compiles and links with the ASan libc++, or with the runtimes from source instrumented by it. For the Windows targets ubsan, and asan for x64, whose DLL every program then has beside it; for the musl targets ubsan. Others are refused
msanoffMemorySanitizer, for the whole build, with the runtimes from source (--@xclang//runtimes:source), which then include its runtime; Linux targets (glibc). Refused without them, and for the other targets.
copy_dynamic_libraries_to_binaryWindows targets: ona program's DLLs beside it in bazel-bin and in its runfiles, ASan's among them, as Bazel's own Windows toolchains have it
cpp_modulesoffC++20 modules: module_interfaces of a cc_library/cc_binary, scanned by clang-scan-deps; needs --experimental_cpp_modules
gc_sectionsLinux targets: on in opt; Windows targets: offlld's --gc-sections, lld-link's /opt:ref for the MSVC targets (why not for Windows)
thinlto_cacheonthe linker's ThinLTO cache, with flags only when XCLANG_THINLTO_CACHE names a directory
generate_dsym_fileoffmacOS targets: the link makes <name>.dSYM (output group dsyms); --apple_generate_dsym turns it on for the build
supports_dynamic_linkeroffBazel's dynamic linking of libraries into tests and programs, for the Linux targets; off, they link statically, as they do for the others always
release_striponwhat <name>.stripped does: --strip-unneeded for ELF and COFF, --strip-all for Mach-O (strip)
modules_embed_all_filesona C++20 module interface's file embeds its sources (-Xclang -fmodules-embed-all-files): an importer that reads them (with -g) has them in the sandbox
macos_default_link_flagsoffrules_cc's: -fobjc-link-runtime in every link of a macOS target, which links Foundation and libobjc into each program and library; off, a target links the frameworks it names (macOS links).
no_exported_symbolsmacOS targets: on in optthe program exports nothing (-Wl,-no_exported_symbols), so that its strip leaves no symbol to name a crash log's frames (strip); off for a program whose plugins bind to its symbols
generate_pdb_fileMSVC targets: on in dbgthe link writes <name>.pdb (output group pdb_file), with paths relative to the execution root
dynamic_link_msvcrtoffMSVC targets: the VC runtime's DLLs (/MD) in place of the hybrid CRT
debug_msvcrtoffMSVC targets: the debug CRT (/MTd, /MDd with dynamic_link_msvcrt)

A feature is turned on for a build with --features=<name>, off with --features=-<name>, and for one target with features = ["<name>"] or ["-<name>"].

The C++ Library ​

A flag of the whole build:

flagdefault
--@xclang//bazel:stdliblibc++platform: the platform's C++ library in place of libc++, for the MSVC targets Microsoft's STL and for the macOS ones the SDK's libc++, from the same SDK; the config file <target>-system.cfg in place of the target's (the system's C++ library). @xclang//bazel:std follows it. The other targets refuse it, as does --@xclang//runtimes:source

Runtimes from Source ​

Flags of the whole build, in @xclang//runtimes (runtimes from source):

flagdefault
--@xclang//runtimes:sourcefalselibc++ (with libc++abi), libc++experimental and libunwind built from the toolchain's libc++/src for the target platform, with the build's features and --copt, and every compile and link against them in place of the prebuilt ones. Refused for the MSVC targets
--@xclang//runtimes:hardeningnonelibc++'s hardening mode: none, fast, extensive, debug
--@xclang//runtimes:abi_version1libc++'s ABI version, 1 or 2
--@xclang//runtimes:abi_namespace__<version>libc++'s inline namespace, __<name>
--@xclang//runtimes:abi_definesnonelibc++'s ABI macros, _LIBCPP_ABI_*, comma-separated
--@xclang//runtimes:exceptionstruefalse: libc++ and libc++abi without exceptions
--@xclang//runtimes:rttitruefalse: libc++ without RTTI; needs exceptions=false

The runtimes are libraries of the host toolchain's repository, compiled as LLVM's CMake build compiles them (bazel/runtimes_sources.bzl) in a configuration of their own, the build's with @xclang//runtimes:building set, whose toolchain is the same without them. The build's sanitizer features instrument libc++ and libc++abi, not libunwind or MemorySanitizer's runtime. No runtime is compiled with ThinLTO.

What the module cannot build stops the build at once, saying why: the runtimes from source, or any of the flags beside it, for an MSVC target; those flags without --@xclang//runtimes:source; msan without it, or for a target other than glibc's; a sanitizer feature whose runtime the target has not.

Targets and Rules ​

label
@xclang//bazel:stdthe std and std.compat modules of libc++, for the target platform, as a library to depend on; built with the --cxxopt of the build. For the MSVC targets with --@xclang//bazel:stdlib=platform, those of Microsoft's STL; for the macOS targets with it, none (incompatible)
xclang_debug_symbols(name, binary, gsymutil_args) in @xclang//bazel:debug_symbols.bzl<binary>.gsym for every target but the MSVC ones, by llvm-gsymutil with one thread (the same file each run; gsymutil_args come after --num-threads=1), and <binary>.dSYM for macOS ones (with generate_dsym_file on the cc_binary); llvm-gsymutil's output in the output group gsym_log. For an MSVC target, <binary>.pdb (with generate_pdb_file)
@xclang//bazel:llvm-gsymutilthe llvm-gsymutil of the machine's toolchain, for bazel run: bazel run @xclang//bazel:llvm-gsymutil -- <absolute .gsym> --address=0x<address>
xclang_resource_dir(name, srcs) in @xclang//bazel:resource_dir.bzlclang's resource directory laid out as lib/clang/<major>/ in the rule's package, for a program bin/<name> of that package; @libclang's by default

Tags ​

Of the module extension, use_extension("@xclang//bazel:extensions.bzl", "xclang"), in the root module only: the vendor SDKs it fetches, from the vendor, accepting the vendor's license (build for MSVC, and for macOS anywhere). The options are those of xclang sdk fetch (versions).

tag
xclang.windows_sdk(accept_license, preset, msvc_version, sdk_version)Microsoft's CRT, STL and Windows SDK, for the MSVC targets; accept_license = True accepts the Visual Studio Build Tools and Windows SDK licenses
xclang.macos_sdk(accept_license, preset, version)Apple's macOS SDK, for the macOS targets off macOS hosts; accept_license = True accepts the Xcode and Apple SDKs Agreement. version = "latest" takes the newest SDK Apple's catalogs list when the repository is fetched, which is not reproducible

Repositories ​

From the module extension, use_extension("@xclang//bazel:extensions.bzl", "xclang"); each is fetched only when a build uses it.

repository
@libclangthe target platform's libclang: @libclang//:clangBasic, :LLVMSupport, ... with their link interfaces; :headers; :resource_dir; :AllTargetsInfos, :AllTargetsDescs, :AllTargetsAsmParsers, :AllTargetsDisassemblers. With --features=asan, the ASan build. None for the MSVC targets: what depends on it is incompatible with them
@libclang_asanthe ASan build (Linux x64 and macOS arm64 targets)
@libclang_<target>the libclang of one target
@llvm_option_incthe option tables of clang, lld, llvm-lib and llvm-dlltool, as a header-only library

Environment ​

Given with --repo_env=<name>=<value>:

variable
XCLANG_THINLTO_CACHEan absolute directory for the ThinLTO cache of the linker; the module makes it (the ThinLTO cache)
XCLANG_ROOTan unpacked host toolchain to use instead of the release's
XCLANG_LIBCLANG_ROOT, XCLANG_LIBCLANG_ASAN_ROOTan unpacked host libclang, or its ASan build, to use instead of the release's
BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1rules_cc's: turns its detection of a local compiler off. Needed unless xclang's bazel_dep comes before rules_cc's: Bazel tries the toolchains of the modules in the order of their bazel_deps, and rules_cc's of the local compiler takes the host's builds, and on Windows those of every Windows platform
BAZEL_NO_APPLE_CPP_TOOLCHAIN=1apple_support's: turns its toolchain of Xcode's clang off, which takes the macOS targets' builds on a Mac when apple_support's bazel_dep comes before xclang's

The Release ​

packages/bazel/bazel/versions.bzl names the release the module downloads, and the sha256 of each of its archives, from the SHA256SUMS of the release. The version of the module is the release's.