Building with Bazel

This page walks through building IREE from source using the Bazel build system.

Warning

Bazel build support is primarily for internal project infrastructure. We strongly recommend using CMake instead.

Our Bazel configuration is also only tested on Linux. Windows and macOS may be unstable.

Prerequisites

Linux macOS Windows

1. Install Bazel, matching IREE's .bazelversion by following the official docs.

2. Install a compiler such as Clang (GCC is not fully supported).

   sudo apt install clang
   

   Set environment variables for Bazel:

   export CC=clang
   export CXX=clang++
   

3. Install Python build requirements:

   python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt
   

1. Install Homebrew:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
   

2. Install Bazel, matching IREE's .bazelversion by following the official docs or via Homebrew:

   brew install bazel
   

3. Install Python build requirements:

   python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt
   

Tip

You can simplify installation by using a package manager like Scoop or Chocolatey.

1. Install Bazel, matching IREE's .bazelversion by following the official docs.

   Also install MSYS2 by following Bazel's documentation.

2. Install Python3 (docs here) and Python build requirements:

   python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt
   

3. Install the full Visual Studio or "Build Tools For Visual Studio" from the downloads page then set the BAZEL_VS environment variable:

   > $env:BAZEL_VS = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools"
   

Quickstart: clone and build

Clone

Use Git to clone the IREE repository and initialize its submodules:

git clone https://github.com/iree-org/iree.git
cd iree
git submodule update --init

Configure Bazel:

# This generates a `configured.bazelrc` file by analyzing your environment.
# Skipping this step will make it difficult to select your platform/compiler.
python3 configure_bazel.py

Linux macOS Windows

(No Linux-specific tips for configuring)

(No macOS-specific tips for configuring)

Tip

Clone to a short path like C:\projects\ to avoid issues with Windows maximum path lengths (260 characters).

Tip

configure_bazel.py only detects that you have Windows and will output the default --config=windows to configured.bazelrc, which assumes the latest version of MSVC. To avoid some warnings, you may want to replace it with (for example) --config=msvc2022.

Build

Run all tests:

bazel test -k //...

Run all tests except those that require CUDA:

bazel test -k //... \
    --iree_drivers=local-sync,local-task,vulkan \
    --test_tag_filters="-driver=cuda,-target=cuda" \
    --build_tag_filters="-driver=cuda,-target=cuda"

Run all tests except those that require a GPU (any API):

bazel test -k //... \
    --iree_drivers=local-sync,local-task,vulkan \
    --test_tag_filters="-driver=vulkan,-driver=metal,-driver=cuda,-target=cuda" \
    --build_tag_filters="-driver=cuda,-target=cuda"

Tip

See the build_tools/bazel/build_test_all.sh script for examples of other flags and environment variables that can be used to configure what Bazel runs.

In general, build artifacts will be under the bazel-bin directory at the top level.

Recommended user.bazelrc

You can put a user.bazelrc at the root of the repository and it will be ignored by git.

Linux macOS Windows

build --disk_cache=/tmp/bazel-cache

# Use --config=debug to compile IREE and LLVM without optimizations
# and with assertions enabled.
build:debug --config=asserts --compilation_mode=opt '--per_file_copt=iree|llvm@-O0' --strip=never

# Use --config=asserts to enable assertions. This has to be done globally:
# Code compiled with and without assertions can't be linked together (ODR violation).
build:asserts --compilation_mode=opt '--copt=-UNDEBUG'

build --disk_cache=/tmp/bazel-cache

# Use --config=debug to compile IREE and LLVM without optimizations
# and with assertions enabled.
build:debug --config=asserts --compilation_mode=opt '--per_file_copt=iree|llvm@-O0' --strip=never

# Use --config=asserts to enable assertions. This has to be done globally:
# Code compiled with and without assertions can't be linked together (ODR violation).
build:asserts --compilation_mode=opt '--copt=-UNDEBUG'

build --disk_cache=c:/bazelcache
build:debug --compilation_mode=dbg --copt=/O2 --per_file_copt=iree@/Od --strip=never

What's next?

Take a Look Around

Build all of IREE's 'tools' directory:

bazel build tools/...

Check out what was built:

ls bazel-bin/tools/
./bazel-bin/tools/iree-compile --help

Translate a MLIR file and execute a function in the compiled module:

# iree-run-mlir <compiler flags> [input.mlir] <runtime flags>
$ ./bazel-bin/tools/iree-run-mlir \
  --iree-hal-target-backends=vmvx --print-mlir \
  ./samples/models/simple_abs.mlir \
  --input=f32=-2