Repository files navigation

See notes on thereleasefor how to get started.

NOTE: For releases prior to 0.10.1, please also seethese notes.

The toolchain can automatically detect your OS and arch type, and use the rightpre-built binary LLVM distribution. See the section on "Bring Your Own LLVM"below for more options.

See in-code documentation inrules.bzl for availableattributes tollvm_toolchain.

LLVM does not come with distributions for all host architectures in eachversion. In particular patch versions often come with few prebuilt packages.This means that a single version probably is not enough to address all hostsone wants to support.

This can be solved by providing a target/version map with a default version.The example below selects15.0.6 as the default version for all targets notspecified explicitly. This is like providingllvm_version = "15.0.6", justlike in the example on the top. However, here we provide two more entries thatmap their respective target to a distinct version:

llvm_toolchain(name="llvm_toolchain",llvm_versions= {"":"15.0.6","darwin-aarch64":"15.0.7","darwin-x86_64":"15.0.7",    },)

We currently offer limited customizability through attributes of thellvm_toolchain_* rules. You can send us a PR to addmore configuration attributes.

The following shows how to add a specific version for a specific target beforethe version was added tollvm_distributions.bzl:

llvm_toolchain(name="llvm_toolchain",llvm_version="19.1.6",sha256= {"linux-x86_64":"d55dcbb309de7ade4e3073ec3ac3fac4d3ff236d54df3c4de04464fe68bec531"},strip_prefix= {"linux-x86_64":"LLVM-19.1.6-Linux-X64",    },urls= {"linux-x86_64": ["https://github.com/llvm/llvm-project/releases/download/llvmorg-19.1.6/LLVM-19.1.6-Linux-X64.tar.xz",        ],    },)

A majority of the complexity of this project is to make it generic for multipleuse cases. For one-off experiments with new architectures, cross-compilations,new compiler features, etc., my advice would be to look at the toolchainconfigurations generated by this repo, and copy-paste/edit to make your own inany package in your own workspace.

bazel query --output=build @llvm_toolchain//:all| grep -v -e'^#' -e'^  generator'

Besides defining your toolchain in your package BUILD file, and until thisissue is resolved, you wouldalso need a way for bazel to access the tools in LLVM distribution as relativepaths from your package without using.. up-references. For this, you cancreate a symlink that uses up-references to point to the LLVM distributiondirectory, and also create a wrapper script for clang such that the actualclang invocation is not through the symlinked path. See the files in the@llvm_toolchain//: package as a reference.

# See generated files for reference.ls -lR"$(bazel info output_base)/external/llvm_toolchain"# Create symlink to LLVM distribution.cd _your_package_directory_ln -s ../....../external/llvm_toolchain_llvm llvm# Create CC wrapper script.mkdir bincp"$(bazel info output_base)/external/llvm_toolchain/bin/cc_wrapper.sh" bin/cc_wrapper.shvim bin/cc_wrapper.sh# Review to ensure relative paths, etc. are good.

Seebazeltutorialfor how CC toolchains work in general.

If toolchains are registered (see Quickstart section above), you do not need todo anything special for bazel to find the toolchain. You may want to check oncewith the--toolchain_resolution_debug flag to see which toolchains wereselected by bazel for your target platform.

For specifying unregistered toolchains on the command line, please use the--extra_toolchains flag. For example,--extra_toolchains=@llvm_toolchain//:cc-toolchain-x86_64-linux.

The following mechanisms are available for using an LLVM toolchain:

1. Host OS information is used to find the right pre-built binary distributionfrom llvm.org, given thellvm_version orllvm_versions attribute. TheLLVM toolchain archive is downloaded and extracted as a separate repositorywith the suffix_llvm. The detection logic forllvm_version is notperfect, so you may have to usellvm_versions for some host OS type andversions. We expect the detection logic to grow through communitycontributions. We welcome PRs.
2. You can use theurls attribute to specify your own URLs for each OS type,version and architecture. For example, you can specify a different URL forArch Linux and a different one for Ubuntu. Just as with the option above,the archive is downloaded and extracted as a separate repository with thesuffix_llvm.
3. You can also specify your own bazel package paths or local absolute pathsfor each host os-arch pair through thetoolchain_roots attribute (withoutbzlmod) or thetoolchain_root module extension tags (with bzlmod). Notethat the keys here are different and less granular than the keys in theurlsattribute. When using a bazel package path, each of the values is typicallya package in the user's workspace or configured throughlocal_repository orhttp_archive; the BUILD file of the package should be similar to@toolchains_llvm//toolchain:BUILD.llvm_repo. If using onlyhttp_archive, maybe consider using theurls attribute instead to get moreflexibility if you need.
4. All the above options rely on host OS information, and are not suited fordocker based sandboxed builds or remote execution builds. Such builds willneed a single distribution version specified through thedistributionattribute, or URLs specified through theurls attribute with an empty key, ora toolchain root specified through thetoolchain_roots attribute with anempty key.

A sysroot can be specified through thesysroot attribute (without bzlmod) orthesysroot module extension tag (with bzlmod). This can be either a path onthe user's system, or a bazelfilegroup like label. One way to create asysroot is to usedocker export to get a single archive of the entirefilesystem for the image you want. Another way is to use the build scriptsprovided by theChromiumproject.

The toolchain supports cross-compilation if you bring your own sysroot. Whencross-compiling, we link against the libstdc++ from the sysroot(single-platform build behavior is to link against libc++ bundled with LLVM).The following pairs have been tested to work for some hello-world binaries:

• {linux, x86_64} -> {linux, aarch64}
• {linux, aarch64} -> {linux, x86_64}
• {darwin, x86_64} -> {linux, x86_64}
• {darwin, x86_64} -> {linux, aarch64}

A recommended approach would be to define two toolchains, one without sysrootfor single-platform builds, and one with sysroot for cross-compilation builds.Then, when cross-compiling, explicitly specify the toolchain with the sysrootand the target platform. For example, see theMODULE.bazelfile forllvm_toolchain_with_sysroot and thetestscript for cross-compilation.

bazel build \  --platforms=@toolchains_llvm//platforms:linux-x86_64 \  --extra_toolchains=@llvm_toolchain_with_sysroot//:cc-toolchain-x86_64-linux \  //...

The toolchain supports multi-platform builds through the combination of theexec_os,exec_arch attribute pair, and either thedistribution attribute,or theurls attribute. This allows one to run their builds on one platform(e.g. macOS) and their build actions to run on another (e.g. Linux), enablingremote build execution (RBE). For example, see theMODULE.bazelfile forllvm_toolchain_linux_exec and thetestscript for running the build actions onLinux even if the build is being run from macOS.

bazel build \  --platforms=@toolchains_llvm//platforms:linux-x86_64 \  --extra_execution_platforms=@toolchains_llvm//platforms:linux-x86_64 \  --extra_toolchains=@llvm_toolchain_linux_exec//:cc-toolchain-x86_64-linux \  //...

The following is a rough (untested) list of steps:

1. To help us detect if you are cross-compiling or not, note the arch string asgiven bypython3 -c 'import platform; print(platform.machine()).
2. EditSUPPORTED_TARGETS intoolchain/internal/common.bzl with the osand the arch string from above.
3. Addtarget_system_name, etc. intoolchain/cc_toolchain_config.bzl.
4. For cross-compiling, add aplatform bazel type for your target platform inplatforms/BUILD.bazel, and add an appropriatesysroot entry to yourllvm_toolchain repository definition.
5. If not cross-compiling, bring your own LLVM (see section above) through thetoolchain_roots orurls attribute.
6. Test your build.

Sandboxing the toolchain introduces a significant overhead (100ms per action,as of mid 2018). To overcome this, one can use--experimental_sandbox_base=/dev/shm. However, not all environments mighthave enough shared memory available to load all the files in memory. If this isa concern, you may set the attribute for using absolute paths, which willsubstitute templated paths to the toolchain as absolute paths. When runningbazel actions, these paths will be available from inside the sandbox as part ofthe / read-only mount. Note that this will make your builds non-hermetic.

The toolchain is tested to work withrules_go,rules_rust, andrules_foreign_cc.

The LLVM distribution also provides several tools likeclang-format. You candepend on these tools directly in the bin directory of the distribution. Whennot using thetoolchain_roots attribute, the distribution is available in therepo with the suffix_llvm appended to the name you used for thellvm_toolchain rule. For example,@llvm_toolchain_llvm//:bin/clang-formatis a valid and visible target in the quickstart example above.

When using thetoolchain_roots attribute, there is currently no single targetthat you can reference, and you may have to alias the tools you want with aselect clause in your workspace.

As a convenience, some targets are aliased appropriately in the configurationrepo (as opposed to the LLVM distribution repo) for you to use and will workeven when usingtoolchain_roots. The complete list is in the filealiases.bzl. If your repo is namedllvm_toolchain,then they can be referenced as:

• @llvm_toolchain//:omp
• @llvm_toolchain//:clang-format
• @llvm_toolchain//:llvm-cov

The toolchain supports Bazel'slayering_check feature, which relies onClang modules to implement strictdeps (also known as "depend on what you use") forcc_* rules. This featurecan be enabled by enabling thelayering_check feature on a per-target,per-package or global basis.

Other examples of toolchain configuration:

https://bazel.build/tutorials/ccp-toolchain-config

https://github.com/vsco/bazel-toolchains