1# Introduction 2 3*Warning* The Bazel build is experimental and best-effort, supported in line 4with the policy for 5[LLVM's peripheral support tier](https://llvm.org/docs/SupportPolicy.html). 6LLVM's official build system is CMake. If in doubt use that. If you make changes 7to LLVM, you're expected to update the CMake build but you don't need to update 8Bazel build files. Reviewers should not ask authors to update Bazel build files 9unless the author has opted in to support Bazel. Keeping the Bazel build files 10up-to-date is on the people who use the Bazel build. 11 12[Bazel](https://bazel.build/) is a multi-language build system focused on 13reproducible builds to enable dependency analysis and caching for fast 14incremental builds. 15 16The main motivation behind the existence of an LLVM Bazel build is that a number 17of projects that depend on LLVM use Bazel, and Bazel works best when it knows 18about the whole source tree (as opposed to installing artifacts coming from 19another build system). Community members are also welcome to use Bazel for their 20own development as long as they continue to maintain the official CMake build 21system. See also, the 22[proposal](https://github.com/llvm/llvm-www/blob/main/proposals/LP0002-BazelBuildConfiguration.md) 23for adding this configuration. 24 25# Quick Start 26 271. `git clone https://github.com/llvm/llvm-project.git; cd llvm-project` if 28 you don't have a checkout yet. 292. Install Bazel at the version indicated by [.bazelversion](./.bazelversion), 30 following the official instructions, if you don't have it installed yet: 31 https://docs.bazel.build/versions/main/install.html. 323. `cd utils/bazel` 334. `bazel build --config=generic_clang @llvm-project//...` (if building on Unix 34 with Clang). `--config=generic_gcc` and `--config=msvc` are also available. 35 36 37# Configuration 38 39The repository `.bazelrc` will import user-specific settings from a 40`user.bazelrc` file (in addition to the standard locations). Adding your typical 41config setting is recommended. 42 43```.bazelrc 44build --config=generic_clang 45``` 46 47You can enable 48[disk caching](https://docs.bazel.build/versions/main/remote-caching.html#disk-cache), 49which will cache build results 50 51```.bazelrc 52build --disk_cache=~/.cache/bazel-disk-cache 53``` 54 55You can instruct Bazel to use a ramdisk for its sandboxing operations via 56[--sandbox_base](https://docs.bazel.build/versions/main/command-line-reference.html#flag--sandbox_base), 57which can help avoid IO bottlenecks for the symlink stragegy used for 58sandboxing. This is especially important with many inputs and many cores (see 59https://github.com/bazelbuild/bazel/issues/11868): 60 61```.bazelrc 62build --sandbox_base=/dev/shm 63``` 64 65Bear in mind that this requires that your ramdisk is of sufficient size to hold 66any temporary files. Anecdotally, 1GB should be sufficient. 67 68# Coverage 69 70The LLVM, MLIR, and Clang subprojects have configurations for Linux (Clang and 71GCC), Mac (Clang and GCC), and Windows (MSVC). Configuration options that are 72platform-specific are selected for in defines. Many are also hardcoded to the 73values currently used by all supported configurations. If there is a 74configuration you'd like to use that isn't supported, please send a patch. 75 76# Continuous Testing 77 78A [Buildkite pipeline](https://buildkite.com/llvm-project/upstream-bazel-rbe) 79runs the full Bazel build on every commit to the main branch. Notifications of 80failures are sent to the 81[llvm-bazel-alerts google group](https://groups.google.com/g/llvm-bazel-alerts), 82which anyone is free to join. Currently, the behavior is just to send an email 83on each failure using Buildkite's built-in notification system, so if you 84subscribe, it is highly recommended that you set up email filters or some other 85mechanism to not flood your inbox. More sophisticated notifications, e.g. only 86on status change or routed based on blamelist are TODO (contributions welcome). 87 88# Pre-merge Testing 89 90A Buildkite pipeline runs the full Bazel build as a pre-merge test using the 91[LLVM pre-merge testing](https://github.com/google/llvm-premerge-checks/). It 92is triggered on all changes to the utils/bazel directory and when the patch 93author is a member of the 94[Bazel Phabricator project](https://reviews.llvm.org/project/members/107/). If 95you use or benefit from the Bazel build, please join the project so that you 96can help keep it green. As a bonus, it runs in under 5 minutes, much faster 97than any of the other pre-merge builds. 98 99# Usage in Downstream Projects 100 101To use in dependent projects using Bazel, you can import LLVM and then use the 102provided configuration rule. See example usage in the `examples/` directory. 103