utils/bazel/README.md

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