Getting startedlink

Prerequisiteslink

IREE can be built from source using CMake. We also recommend the Ninja CMake generator and the clang or MSVC C/C++ compilers.

Note - Other CMake generators and compilers

IREE developers and CIs primarily use Ninja, clang, and MSVC. Other configurations (including the Makefile generator and gcc) are "best effort". Patches to improve support are always welcome.

Linux macOS Windows

Install a compiler/linker (typically "clang" and "lld" package)
Install CMake (typically "cmake" package)
Install Ninja (typically "ninja-build" package)

On Debian/Ubuntu:

sudo apt install cmake ninja-build clang lld

Install CMake
Install Ninja

If using Homebrew:

brew install cmake ninja

Install MSVC from Visual Studio or "Tools for Visual Studio" on the official downloads page
Install CMake from the official downloads page
Install Ninja from the official site

Note

Initialize MSVC by running vcvarsall.bat to build on the command line. See the official documentation for details.

Quickstart: clone and buildlink

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

The most basic CMake workflow is:

# Configure
cmake -G Ninja -B ../iree-build/ .

# Build
cmake --build ../iree-build/

Caution - slow builds

The compiler build is complex. You will want a powerful machine and to tune the settings following the next section. In 2023, we've seen builds take around 5-10 minutes on 64-core Linux machines.

Use case permitting, disabling the compiler build with -DIREE_BUILD_COMPILER=OFF will drastically simplify the build.

Configuration settingslink

The configure step should be customized for your build environment. These settings can improve compile and link times substantially.

Linux macOS Windows

# Recommended development options using clang and lld:
cmake -G Ninja -B ../iree-build/ -S . \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DIREE_ENABLE_ASSERTIONS=ON \
    -DIREE_ENABLE_SPLIT_DWARF=ON \
    -DIREE_ENABLE_THIN_ARCHIVES=ON \
    -DCMAKE_C_COMPILER=clang \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DIREE_ENABLE_LLD=ON

# Recommended development options using clang and lld:
cmake -G Ninja -B ../iree-build/ -S . \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DIREE_ENABLE_ASSERTIONS=ON \
    -DIREE_ENABLE_SPLIT_DWARF=ON \
    -DCMAKE_C_COMPILER=clang \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DIREE_ENABLE_LLD=ON

It is also possible to add -DIREE_ENABLE_THIN_ARCHIVES=ON if the CMAKE_AR variable is defined and points to the path of either the GNU binutils or LLVM ar program, overriding the default Apple ar.

# Recommended development options:
cmake -G Ninja -B ../iree-build/ -S . \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DIREE_ENABLE_ASSERTIONS=ON

Tip - CMAKE_BUILD_TYPE values

We recommend using the RelWithDebInfo build type by default for a good balance of debug info and performance. The Debug, Release, and MinSizeRel build types are useful in more specific cases. Note that several useful LLVM debugging features are only available in Debug builds. See the official CMake documentation for general details.

Tip - Faster recompilation with ccache

We recommend using ccache with CMake, especially when rebuilding the compiler. To use it, configure CMake with:

-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

Optional componentslink

Enabled components and other configurations can be changed via CMake options, listed in the root CMakeLists.txt. We also maintain a few CMake presets at build_tools/cmake/presets for common configurations.

By default, the CMake build includes:

All compiler targets (llvm-cpu, cuda, vulkan-spirv, etc.)
All runtime HAL drivers (local-task, cuda, vulkan, etc.)
All compiler input formats (PyTorch, StableHLO, TOSA, etc.)
All compiler output formats (VM bytecode, C)

The default build does not include:

Python and other language bindings for the compiler or runtime
Advanced features like AddressSanitizer or tracing instrumentation
Experimental components

Configuration examples

Disable all backends except CPUDisable just CUDA

This configure command will

Disable all compiler target backends then enable just llvm-cpu
Disable all runtime HAL drivers then enable just the CPU "local" runtime HAL drivers

cmake -G Ninja -B ../iree-build/ -S . \
    -DIREE_TARGET_BACKEND_DEFAULTS=OFF \
    -DIREE_TARGET_BACKEND_LLVM_CPU=ON \
    -DIREE_HAL_DRIVER_DEFAULTS=OFF \
    -DIREE_HAL_DRIVER_LOCAL_SYNC=ON \
    -DIREE_HAL_DRIVER_LOCAL_TASK=ON

This configure command will

Disable just the CUDA compiler target backend
Disable just the CUDA runtime HAL driver

cmake -G Ninja -B ../iree-build/ -S . \
    -DIREE_TARGET_BACKEND_CUDA=OFF \
    -DIREE_HAL_DRIVER_CUDA=OFF

Extensions and integrationslink

When using IREE within other projects, you can register compiler plugins and runtime HAL drivers. You can also bring your own copy of LLVM and some other tools. See the root CMakeLists.txt for details.

Tests and sampleslink

Running testslink

Tests are run via ctest. To build and run the core project tests:

# Build default targets
cmake --build ../iree-build/

# Run tests
ctest --test-dir ../iree-build/

Caution

This has two limitations:

Large tests are excluded from the build by default
Some tests require hardware like a GPU and will fail on unsupported systems

To build and then run all tests:

# 1. Build default targets
cmake --build ../iree-build/

# 2. Build test dependencies
cmake --build ../iree-build/ --target iree-test-deps

# 3. Run tests
ctest --test-dir ../iree-build/


# Or combine all steps using a utility target
cmake --build ../iree-build --target iree-run-tests

To run only certain tests, we have a helper script that converts environment variables into ctest filters:

# Run default tests
./build_tools/cmake/ctest_all.sh ../iree-build

# Run tests, turning CUDA on and Vulkan off
export IREE_CUDA_DISABLE=0
export IREE_VULKAN_DISABLE=1
./build_tools/cmake/ctest_all.sh ../iree-build

Running sampleslink

# Build
cmake --build ../iree-build/

# Run a standalone sample application
../iree-build/runtime/src/iree/runtime/demo/hello_world_embedded
# 4xf32=1 1.1 1.2 1.3
#  *
# 4xf32=10 100 1000 10000
#  =
# 4xf32=10 110 1200 13000

# Try out the developer tools
ls ../iree-build/tools/
../iree-build/tools/iree-compile --help
../iree-build/tools/iree-run-module --help

Python bindingslink

Python packages can either be built from source or installed from our releases. See the Python bindings page for details about the bindings themselves.

Dependencieslink

You will need a recent Python installation >=3.9 (we aim to support non-eol Python versions).

Tip - Managing Python versions

Make sure your 'python' is what you expect:

Linux macOS Windows

Note that on multi-python systems, this may have a version suffix, and on many Linuxes where python2 and python3 can co-exist, you may also want to use python3.

which python
python --version

Note that on multi-python systems, this may have a version suffix, and on macOS where python2 and python3 can co-exist, you may also want to use python3.

which python
python --version

The Python launcher for Windows (py) can help manage versions.

which python
python --version
py --list-paths

Tip - Virtual environments

We recommend using virtual environments to manage python packages, such as through venv (about, tutorial):

Linux macOS Windows

python -m venv .venv
source .venv/bin/activate

python -m venv .venv
source .venv/bin/activate

python -m venv .venv
.venv\Scripts\activate.bat

When done, run deactivate.

# Upgrade PIP before installing other requirements
python -m pip install --upgrade pip

# Install IREE build requirements
python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt

Building with CMakelink

To build the Python bindings, configure CMake with the IREE_BUILD_PYTHON_BINDINGS option. We also recommend explicitly setting which Python executable to use with Python3_EXECUTABLE:

# Configure (including other options as discussed above)
cmake -G Ninja -B ../iree-build/ \
  -DIREE_BUILD_PYTHON_BINDINGS=ON  \
  -DPython3_EXECUTABLE="$(which python)" \
  .

# Build
cmake --build ../iree-build/

Using the Python bindingslink

Extend your PYTHONPATH with IREE's bindings/python paths and try importing:

Linux macOS Windows

source ../iree-build/.env && export PYTHONPATH
# The 'PYTHONPATH' environment variable should now contain
#   iree-build/compiler/bindings/python;iree-build/runtime/bindings/python

python -c "import iree.compiler; help(iree.compiler)"
python -c "import iree.runtime; help(iree.runtime)"

source ../iree-build/.env && export PYTHONPATH
# The 'PYTHONPATH' environment variable should now contain
#   iree-build/compiler/bindings/python;iree-build/runtime/bindings/python

python -c "import iree.compiler; help(iree.compiler)"
python -c "import iree.runtime; help(iree.runtime)"

..\iree-build\.env.ps1  # or ..\iree-build\.env.bat
# The 'PYTHONPATH' environment variable should now contain
#   iree-build/compiler/bindings/python;iree-build/runtime/bindings/python

python -c "import iree.compiler; help(iree.compiler)"
python -c "import iree.runtime; help(iree.runtime)"

Using IREE's ML framework importers requires a few extra steps:

# Install test requirements
python -m pip install -r integrations/tensorflow/test/requirements.txt

# Install pure Python packages (no build required)
python -m pip install integrations/tensorflow/python_projects/iree_tf
python -m pip install integrations/tensorflow/python_projects/iree_tflite

# Then test the tools:
iree-import-tf --help
iree-import-tflite --help