IREE Developer Tools

This directory contains command-line tools that developers add to their PATH for convenient access across all IREE worktrees. Tools here provide streamlined workflows for building, testing, and experimenting with IREE.

Naming convention: All tools must be prefixed with iree- to avoid PATH conflicts. Do not use names that conflict with existing IREE tools (e.g., don't name something iree-run-module or iree-compile).

Setup

Add this directory to your PATH:

export PATH="$PATH:$PWD/build_tools/bin"

Or add to your shell configuration for persistence.

Bazel Tools

Wrapper tools for building IREE with Bazel. These handle configuration, provide better defaults, and work from any subdirectory within a worktree.

For complete Bazel build documentation, see: Building with Bazel

Quick Start

# Configure once per worktree
iree-bazel-configure

# Build
iree-bazel-build //tools:iree-compile

# Test
iree-bazel-test //runtime/src/iree/base:status_test

# Run
iree-bazel-run //tools:iree-compile -- --help

Tip: Working with Claude Code?

All iree-bazel-* tools provide machine-readable documentation via --agent_md:

# Generate documentation for Claude
iree-bazel-configure --agent_md >> CLAUDE.local.md

This appends concise tool documentation to your local Claude instructions, teaching Claude how to use the iree-bazel-* tools in your project.

Tools

Common Options

All tools support:

• -h, --help - Show help
• -n, --dry_run - Show command without executing
• -v, --verbose - Verbose output

Short flags can be combined: -nv is equivalent to -n -v.

Configuration

Driver configuration happens during iree-bazel-configure:

# Enable CUDA driver
IREE_HAL_DRIVER_CUDA=ON iree-bazel-configure

# Enable multiple drivers
IREE_HAL_DRIVER_CUDA=ON IREE_HAL_DRIVER_VULKAN=ON iree-bazel-configure

Output Directories

Built artifacts are placed in standard Bazel output directories at the repo root:

• bazel-bin/ - Built executables and libraries
• bazel-testlogs/ - Test outputs and logs
• bazel-out/ - Full build tree

Watch Mode

Several tools support watch mode (-w) which rebuilds/reruns on file changes:

iree-bazel-build -w //tools:iree-opt     # Rebuild on changes
iree-bazel-test -w //runtime/...:test    # Rerun tests on changes
iree-bazel-run -w //tools:iree-opt -- input.mlir  # Restart on changes

Watch mode requires ibazel.

Quick Experiments with iree-bazel-try

Compile and run C/C++ snippets against IREE without writing BUILD files:

# Quick API exploration
iree-bazel-try -e '
#include "iree/base/api.h"
#include <stdio.h>
int main() {
  printf("ok: %d\n", iree_status_is_ok(iree_ok_status()));
  return 0;
}'

# Run tests
iree-bazel-try -e '
#include "iree/testing/gtest_harness.h"
TEST(Status, Ok) { IREE_EXPECT_OK(iree_ok_status()); }
'

# MLIR transforms
echo 'func.func @f() { return }' | iree-bazel-try -e '
#include "iree/compiler/Tools/MlirTransformHarness.h"
void xform(ModuleOp m) { m.walk([](Operation *op) { llvm::outs() << op->getName() << "\n"; }); }
MLIR_TRANSFORM_MAIN_NO_PRINT(xform)
'

Run iree-bazel-try --help for full documentation.