{"id":13450677,"url":"https://github.com/bazel-contrib/toolchains_llvm","last_synced_at":"2025-03-23T16:31:55.312Z","repository":{"id":32970370,"uuid":"133101528","full_name":"bazel-contrib/toolchains_llvm","owner":"bazel-contrib","description":"LLVM toolchain for bazel","archived":false,"fork":false,"pushed_at":"2024-08-01T22:06:01.000Z","size":598,"stargazers_count":284,"open_issues_count":23,"forks_count":207,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-08-02T05:09:18.232Z","etag":null,"topics":["bazel","clang","llvm-toolchain","toolchain"],"latest_commit_sha":null,"homepage":"","language":"Starlark","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bazel-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"bazel-rules-authors-sig"}},"created_at":"2018-05-12T00:44:44.000Z","updated_at":"2024-08-02T05:09:25.650Z","dependencies_parsed_at":"2024-02-18T20:26:11.293Z","dependency_job_id":"d87f9d76-a7ec-4389-b064-fabb1ef82561","html_url":"https://github.com/bazel-contrib/toolchains_llvm","commit_stats":null,"previous_names":["bazel-contrib/toolchains_llvm","grailbio/bazel-toolchain"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Ftoolchains_llvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Ftoolchains_llvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Ftoolchains_llvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Ftoolchains_llvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bazel-contrib","download_url":"https://codeload.github.com/bazel-contrib/toolchains_llvm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221856421,"owners_count":16892439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bazel","clang","llvm-toolchain","toolchain"],"created_at":"2024-07-31T07:00:37.236Z","updated_at":"2025-03-23T16:31:55.269Z","avatar_url":"https://github.com/bazel-contrib.png","language":"Starlark","readme":"# LLVM toolchain for Bazel [![Tests](https://github.com/bazel-contrib/toolchains_llvm/actions/workflows/tests.yml/badge.svg)](https://github.com/bazel-contrib/toolchains_llvm/actions/workflows/tests.yml)\n\n## Quickstart\n\nSee notes on the [release](https://github.com/bazel-contrib/toolchains_llvm/releases)\nfor how to get started.\n\nNOTE: For releases prior to 0.10.1, please also see [these notes](REPO_RENAME.md).\n\n\u003c!-- Release Notes template is at .github/workflows/release_prep.sh --\u003e\n\n## Basic Usage\n\nThe toolchain can automatically detect your OS and arch type, and use the right\npre-built binary LLVM distribution. See the section on \"Bring Your Own LLVM\"\nbelow for more options.\n\nSee in-code documentation in [rules.bzl](toolchain/rules.bzl) for available\nattributes to `llvm_toolchain`.\n\n## Advanced Usage\n\n### Per host architecture LLVM version\n\nLLVM does not come with distributions for all host architectures in each\nversion. In particular patch versions often come with few prebuilt packages.\nThis means that a single version probably is not enough to address all hosts\none wants to support.\n\nThis can be solved by providing a target/version map with a default version.\nThe example below selects `15.0.6` as the default version for all targets not\nspecified explicitly. This is like providing `llvm_version = \"15.0.6\"`, just\nlike in the example on the top. However, here we provide two more entries that\nmap their respective target to a distinct version:\n\n```starlark\nllvm_toolchain(\n    name = \"llvm_toolchain\",\n    llvm_versions = {\n        \"\": \"15.0.6\",\n        \"darwin-aarch64\": \"15.0.7\",\n        \"darwin-x86_64\": \"15.0.7\",\n    },\n)\n```\n\n### Customizations\n\nWe currently offer limited customizability through attributes of the\n[llvm_toolchain\\_\\* rules](toolchain/rules.bzl). You can send us a PR to add\nmore configuration attributes.\n\nThe following shows how to add a specific version for a specific target before\nthe version was added to [llvm_distributions.bzl](toolchain/internal/llvm_distributions.bzl):\n\n```starlark\nllvm_toolchain(\n    name = \"llvm_toolchain\",\n    llvm_version = \"19.1.6\",\n    sha256 = {\"linux-x86_64\": \"d55dcbb309de7ade4e3073ec3ac3fac4d3ff236d54df3c4de04464fe68bec531\"},\n    strip_prefix = {\n        \"linux-x86_64\": \"LLVM-19.1.6-Linux-X64\",\n    },\n    urls = {\n        \"linux-x86_64\": [\n            \"https://github.com/llvm/llvm-project/releases/download/llvmorg-19.1.6/LLVM-19.1.6-Linux-X64.tar.xz\",\n        ],\n    },\n)\n```\n\nA majority of the complexity of this project is to make it generic for multiple\nuse cases. For one-off experiments with new architectures, cross-compilations,\nnew compiler features, etc., my advice would be to look at the toolchain\nconfigurations generated by this repo, and copy-paste/edit to make your own in\nany package in your own workspace.\n\n```sh\nbazel query --output=build @llvm_toolchain//:all | grep -v -e '^#' -e '^  generator'\n```\n\nBesides defining your toolchain in your package BUILD file, and until this\n[issue](https://github.com/bazelbuild/bazel/issues/7746) is resolved, you would\nalso need a way for bazel to access the tools in LLVM distribution as relative\npaths from your package without using `..` up-references. For this, you can\ncreate a symlink that uses up-references to point to the LLVM distribution\ndirectory, and also create a wrapper script for clang such that the actual\nclang invocation is not through the symlinked path. See the files in the\n`@llvm_toolchain//:` package as a reference.\n\n```sh\n# See generated files for reference.\nls -lR \"$(bazel info output_base)/external/llvm_toolchain\"\n\n# Create symlink to LLVM distribution.\ncd _your_package_directory_\nln -s ../....../external/llvm_toolchain_llvm llvm\n\n# Create CC wrapper script.\nmkdir bin\ncp \"$(bazel info output_base)/external/llvm_toolchain/bin/cc_wrapper.sh\" bin/cc_wrapper.sh\nvim bin/cc_wrapper.sh # Review to ensure relative paths, etc. are good.\n```\n\nSee [bazel\ntutorial](https://docs.bazel.build/versions/main/tutorial/cc-toolchain-config.html)\nfor how CC toolchains work in general.\n\n### Selecting Toolchains\n\nIf toolchains are registered (see Quickstart section above), you do not need to\ndo anything special for bazel to find the toolchain. You may want to check once\nwith the `--toolchain_resolution_debug` flag to see which toolchains were\nselected by bazel for your target platform.\n\nFor specifying unregistered toolchains on the command line, please use the\n`--extra_toolchains` flag. For example,\n`--extra_toolchains=@llvm_toolchain//:cc-toolchain-x86_64-linux`.\n\n### Bring Your Own LLVM\n\nThe following mechanisms are available for using an LLVM toolchain:\n\n1. Host OS information is used to find the right pre-built binary distribution\n   from llvm.org, given the `llvm_version` or `llvm_versions` attribute. The\n   LLVM toolchain archive is downloaded and extracted as a separate repository\n   with the suffix `_llvm`. The detection logic for `llvm_version` is not\n   perfect, so you may have to use `llvm_versions` for some host OS type and\n   versions. We expect the detection logic to grow through community\n   contributions. We welcome PRs.\n2. You can use the `urls` attribute to specify your own URLs for each OS type,\n   version and architecture. For example, you can specify a different URL for\n   Arch Linux and a different one for Ubuntu. Just as with the option above,\n   the archive is downloaded and extracted as a separate repository with the\n   suffix `_llvm`.\n3. You can also specify your own bazel package paths or local absolute paths\n   for each host os-arch pair through the `toolchain_roots` attribute (without\n   bzlmod) or the `toolchain_root` module extension tags (with bzlmod). Note\n   that the keys here are different and less granular than the keys in the `urls`\n   attribute. When using a bazel package path, each of the values is typically\n   a package in the user's workspace or configured through `local_repository` or\n   `http_archive`; the BUILD file of the package should be similar to\n   `@toolchains_llvm//toolchain:BUILD.llvm_repo`. If using only\n   `http_archive`, maybe consider using the `urls` attribute instead to get more\n   flexibility if you need.\n4. All the above options rely on host OS information, and are not suited for\n   docker based sandboxed builds or remote execution builds. Such builds will\n   need a single distribution version specified through the `distribution`\n   attribute, or URLs specified through the `urls` attribute with an empty key, or\n   a toolchain root specified through the `toolchain_roots` attribute with an\n   empty key.\n\n### Sysroots\n\nA sysroot can be specified through the `sysroot` attribute (without bzlmod) or\nthe `sysroot` module extension tag (with bzlmod). This can be either a path on\nthe user's system, or a bazel `filegroup` like label. One way to create a\nsysroot is to use `docker export` to get a single archive of the entire\nfilesystem for the image you want. Another way is to use the build scripts\nprovided by the [Chromium\nproject](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux/sysroot.md).\n\n### Cross-compilation\n\nThe toolchain supports cross-compilation if you bring your own sysroot. When\ncross-compiling, we link against the libstdc++ from the sysroot\n(single-platform build behavior is to link against libc++ bundled with LLVM).\nThe following pairs have been tested to work for some hello-world binaries:\n\n- {linux, x86_64} -\u003e {linux, aarch64}\n- {linux, aarch64} -\u003e {linux, x86_64}\n- {darwin, x86_64} -\u003e {linux, x86_64}\n- {darwin, x86_64} -\u003e {linux, aarch64}\n\nA recommended approach would be to define two toolchains, one without sysroot\nfor single-platform builds, and one with sysroot for cross-compilation builds.\nThen, when cross-compiling, explicitly specify the toolchain with the sysroot\nand the target platform. For example, see the [MODULE.bazel](tests/MODULE.bazel)\nfile for `llvm_toolchain_with_sysroot` and the [test\nscript](tests/scripts/run_xcompile_tests.sh) for cross-compilation.\n\n```sh\nbazel build \\\n  --platforms=@toolchains_llvm//platforms:linux-x86_64 \\\n  --extra_toolchains=@llvm_toolchain_with_sysroot//:cc-toolchain-x86_64-linux \\\n  //...\n```\n\n### Multi-platform builds\n\nThe toolchain supports multi-platform builds through the combination of the\n`exec_os`, `exec_arch` attribute pair, and either the `distribution` attribute,\nor the `urls` attribute. This allows one to run their builds on one platform\n(e.g. macOS) and their build actions to run on another (e.g. Linux), enabling\nremote build execution (RBE). For example, see the [MODULE.bazel](tests/MODULE.bazel)\nfile for `llvm_toolchain_linux_exec` and the [test\nscript](tests/scripts/run_docker_exec_test.sh) for running the build actions on\nLinux even if the build is being run from macOS.\n\n```sh\nbazel build \\\n  --platforms=@toolchains_llvm//platforms:linux-x86_64 \\\n  --extra_execution_platforms=@toolchains_llvm//platforms:linux-x86_64 \\\n  --extra_toolchains=@llvm_toolchain_linux_exec//:cc-toolchain-x86_64-linux \\\n  //...\n```\n\n### Supporting New Target Platforms\n\nThe following is a rough (untested) list of steps:\n\n1. To help us detect if you are cross-compiling or not, note the arch string as\n   given by `python3 -c 'import platform; print(platform.machine())`.\n2. Edit `SUPPORTED_TARGETS` in\n   [toolchain/internal/common.bzl](toolchain/internal/common.bzl) with the os\n   and the arch string from above.\n3. Add `target_system_name`, etc. in\n   [toolchain/cc_toolchain_config.bzl](toolchain/cc_toolchain_config.bzl).\n4. For cross-compiling, add a `platform` bazel type for your target platform in\n   [platforms/BUILD.bazel](platforms/BUILD.bazel), and add an appropriate\n   sysroot entry to your `llvm_toolchain` repository definition.\n5. If not cross-compiling, bring your own LLVM (see section above) through the\n   `toolchain_roots` or `urls` attribute.\n6. Test your build.\n\n### Sandbox\n\nSandboxing the toolchain introduces a significant overhead (100ms per action,\nas of mid 2018). To overcome this, one can use\n`--experimental_sandbox_base=/dev/shm`. However, not all environments might\nhave enough shared memory available to load all the files in memory. If this is\na concern, you may set the attribute for using absolute paths, which will\nsubstitute templated paths to the toolchain as absolute paths. When running\nbazel actions, these paths will be available from inside the sandbox as part of\nthe / read-only mount. Note that this will make your builds non-hermetic.\n\n### Compatibility\n\nThe toolchain is tested to work with `rules_go`, `rules_rust`, and\n`rules_foreign_cc`.\n\n### Accessing tools\n\nThe LLVM distribution also provides several tools like `clang-format`. You can\ndepend on these tools directly in the bin directory of the distribution. When\nnot using the `toolchain_roots` attribute, the distribution is available in the\nrepo with the suffix `_llvm` appended to the name you used for the\n`llvm_toolchain` rule. For example, `@llvm_toolchain_llvm//:bin/clang-format`\nis a valid and visible target in the quickstart example above.\n\nWhen using the `toolchain_roots` attribute, there is currently no single target\nthat you can reference, and you may have to alias the tools you want with a\n`select` clause in your workspace.\n\nAs a convenience, some targets are aliased appropriately in the configuration\nrepo (as opposed to the LLVM distribution repo) for you to use and will work\neven when using `toolchain_roots`. The complete list is in the file\n[aliases.bzl](toolchain/aliases.bzl). If your repo is named `llvm_toolchain`,\nthen they can be referenced as:\n\n- `@llvm_toolchain//:omp`\n- `@llvm_toolchain//:clang-format`\n- `@llvm_toolchain//:llvm-cov`\n\n### Strict header deps (Linux only)\n\nThe toolchain supports Bazel's `layering_check` feature, which relies on\n[Clang modules](https://clang.llvm.org/docs/Modules.html) to implement strict\ndeps (also known as \"depend on what you use\") for `cc_*` rules. This feature\ncan be enabled by enabling the `layering_check` feature on a per-target,\nper-package or global basis.\n\n## Prior Art\n\nOther examples of toolchain configuration:\n\nhttps://bazel.build/tutorials/ccp-toolchain-config\n\nhttps://github.com/vsco/bazel-toolchains\n","funding_links":["https://opencollective.com/bazel-rules-authors-sig"],"categories":["Tooling"],"sub_categories":["Toolchains"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbazel-contrib%2Ftoolchains_llvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbazel-contrib%2Ftoolchains_llvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbazel-contrib%2Ftoolchains_llvm/lists"}