Welcome back, privacy-preserving AI enthusiast! In our previous chapters, we peeled back the layers of homomorphic encryption (HE) and fully homomorphic encryption (FHE), discovering how they enable computation on encrypted data. We then introduced HEIR, an ambitious open-source compiler designed to make FHE practical for AI inference. Now, it’s time to roll up our sleeves and get HEIR running on your machine.

This chapter will guide you through the essential steps to set up your HEIR development environment. We’ll cover everything from installing necessary prerequisites like CMake and a C++ compiler to cloning the HEIR and LLVM projects, and finally building the HEIR compiler itself. By the end, you’ll have a working HEIR environment, ready for your first foray into private AI inference.

Setting up a compiler from source can sometimes feel like a complex puzzle, but we’ll break it down into the smallest, most manageable pieces. Remember, HEIR is an actively developed project, so while these instructions are accurate as of 2026-08-18, slight adjustments might be needed in the future.

Why a Proper Setup Matters for Private AI

A correctly configured development environment is the bedrock of any successful project, especially when diving into complex domains like homomorphic encryption and compiler development. For HEIR, an FHE compiler built on the LLVM/MLIR infrastructure, a precise setup ensures that:

  • Dependencies are Met: HEIR relies on specific versions and configurations of tools like CMake, C++ compilers, and the MLIR framework. An incorrect setup can lead to cryptic compilation errors and wasted debugging time.
  • Optimal Performance: Compiler builds can be resource-intensive. A streamlined setup prevents unnecessary rebuilds and ensures you’re using efficient build systems like Ninja, which significantly speeds up development cycles.
  • Future Compatibility: As HEIR evolves, having a clean, modular setup makes it easier to update components and adapt to new versions without breaking your existing work. This is crucial for an experimental project.

Think of it like preparing a specialized workshop for a delicate engineering task. You wouldn’t start building a precision instrument without ensuring all your tools are present, sharp, and calibrated. This meticulous preparation saves significant time and frustration down the line.

Core Concepts: Understanding the HEIR Build Architecture

Before we start typing commands, let’s understand the landscape of the HEIR build process. HEIR isn’t a standalone tool; it’s deeply integrated into the broader LLVM ecosystem. Understanding this architecture helps demystify the setup steps.

What is LLVM and MLIR?

LLVM (Low-Level Virtual Machine) is a collection of modular and reusable compiler and toolchain technologies. It’s famous for its flexible intermediate representation (IR) and its ability to optimize code for various architectures. LLVM provides the foundation for many modern compilers, including Clang.

MLIR (Multi-Level Intermediate Representation) is an extension of the LLVM philosophy. It’s designed to address the complexity of modern compilers by allowing multiple IRs at different levels of abstraction. This means you can represent code at a very high, domain-specific level (like FHE operations) and gradually lower it to more general, machine-level instructions. HEIR leverages MLIR to represent FHE programs, enabling sophisticated, FHE-specific optimizations before targeting specific HE backends.

📌 Key Idea: HEIR uses MLIR as its foundation, allowing it to represent and optimize FHE programs in a structured, multi-level way, benefiting from LLVM’s robust compiler infrastructure.

The Role of CMake and Build Systems

CMake is a cross-platform, open-source build system generator. Instead of directly compiling code, CMake reads configuration files (CMakeLists.txt) and generates native build tool files (like Makefiles or Ninja build files) that are then used by your chosen build system (e.g., make or ninja) to compile the source code.

This abstraction is crucial for large, complex projects like HEIR and LLVM, which need to support various operating systems, hardware architectures, and compiler toolchains. You’ll run CMake once to configure the build, and then use ninja (our recommended build tool) repeatedly to compile and link the project as you make changes.

HEIR’s Current Development State

It’s important to reiterate that HEIR is an actively developed, experimental project. As of 2026-08-18, the integration between its “Middle-End” (MLIR-based FHE optimization) and “Back-End” (targeting specific FHE libraries) is still evolving. The official GitHub repository explicitly states that if you require an executable from HEIR, you might need to use format_assistant/h (a specific utility within the project). This means our focus will be on successfully building the core HEIR compiler components, which will include tools like heir-opt (the HEIR optimizer), rather than achieving a fully end-to-end FHE compilation to an executable in this early stage.

🧠 Important: While we’ll build the HEIR compiler, its full end-to-end FHE compilation capabilities are still under active development. Expect to work with intermediate representations and tools like heir-opt to apply FHE-specific optimizations, rather than directly compiling to a final FHE-encrypted executable just yet.

Here’s a simplified visual of the HEIR build process, showing how these components interact:

flowchart TD A[HEIR Source Code] --> B[CMake Configuration] B --> C[Generate Ninja Build Files] C --> D[Ninja Build System] D --> E[Compile LLVM MLIR] D --> F[Compile HEIR Components] E --> G[MLIR Libraries] F --> H[HEIR Tools heir-opt] G -.-> F

Step-by-Step Implementation: Preparing Your Environment

Let’s begin by ensuring your system has all the necessary tools. We’ll focus on Linux (Ubuntu/Debian-based distributions) and macOS, as these are common environments for compiler development.

Step 1: Install Git (Version Control)

Git is essential for cloning the HEIR and LLVM repositories from GitHub.

Why Git? It allows us to download the source code, track changes, and manage updates easily from the project’s official repository.

  • For Ubuntu/Debian (or similar Linux distributions):
    sudo apt update
sudo apt install git -y
  • For macOS: Git is usually pre-installed with Xcode Command Line Tools. For a more up-to-date version or if you don’t have Xcode, you can install it via Homebrew (recommended).
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git

Verify Installation:

git --version

You should see an output like git version 2.45.2 (or newer, as of 2026-08-18).

Step 2: Install CMake (Build System Generator)

CMake is crucial for generating the build files that will compile HEIR. We’ll aim for a recent stable version.

Why CMake? It abstracts the build process, making it consistent across different operating systems and compiler toolchains, simplifying complex project setups like HEIR’s.

  • For Ubuntu/Debian:
    sudo apt install cmake -y
    ⚡ Quick Note: The apt package manager might provide an older stable version. While generally sufficient for HEIR, for the absolute latest, consider downloading from the official CMake website or building from source if you encounter specific compatibility issues.
  • For macOS:
    brew install cmake

Verify Installation:

cmake --version

You should see cmake version 3.29.3 (or newer, as of 2026-08-18).

Step 3: Install a C++ Compiler (Clang or GCC)

HEIR and LLVM are predominantly written in C++, so you’ll need a robust C++ compiler. Clang is often preferred for LLVM development due to its tight integration, but GCC works perfectly fine. We recommend a C++17 compatible compiler or newer.

Why a C++ Compiler? It translates the C++ source code into executable machine instructions, making the compiler tools runnable on your system.

  • For Ubuntu/Debian: Install build-essential, which includes GCC and G++.
    sudo apt install build-essential -y
    To specifically install Clang and related tools (often newer than GCC on some systems):
    sudo apt install clang lld -y
  • For macOS: Install Xcode Command Line Tools. This provides Clang and other essential development utilities.
    xcode-select --install

Verify Installation:

g++ --version
clang --version

You should see versions like g++ (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0 or Apple clang version 15.0.0 (clang-1500.3.9.4) (or newer, as of 2026-08-18).

Step 4: Install Ninja (Fast Build System)

Ninja is a small, fast build system that significantly speeds up compilation, especially for large projects like LLVM and HEIR. It’s often much faster than traditional make.

Why Ninja? It’s designed for speed, minimizing overhead in the build process by focusing on parallelism and efficient dependency tracking.

  • For Ubuntu/Debian:
    sudo apt install ninja-build -y
  • For macOS:
    brew install ninja

Verify Installation:

ninja --version

You should see 1.11.1 (or newer, as of 2026-08-18).

Step 5: Install Python (for LLVM/MLIR Scripts)

Python is used for various utility scripts within the LLVM/MLIR ecosystem, including build automation and testing.

Why Python? Many build and testing scripts, as well as some parts of the LLVM infrastructure, are written in Python. Having it installed ensures these utilities function correctly.

  • For Ubuntu/Debian:
    sudo apt install python3 python3-pip -y
  • For macOS: Python 3 is usually pre-installed. You can also install it via Homebrew for a managed installation:
    brew install python

Verify Installation:

python3 --version

You should see Python 3.10.12 (or newer, as of 2026-08-18).

Step-by-Step Implementation: Building HEIR

Now that your system is prepared, let’s get HEIR compiled. This process involves cloning two repositories: llvm-project (which contains MLIR) and HEIR. We’ll build llvm-project first, specifically MLIR, then use its output to compile HEIR.

Step 1: Clone the LLVM Project Repository

We need the llvm-project repository to build MLIR, which HEIR depends on.

# Create a dedicated directory for your HEIR development
mkdir heir_dev && cd heir_dev

# Clone the LLVM project. This is a very large repository (several GB).
# It will take some time depending on your internet connection.
git clone https://github.com/llvm/llvm-project.git

This command downloads the entire LLVM project source code. Be patient!

Step 2: Build MLIR from LLVM Project

Next, we’ll configure and build MLIR within the llvm-project. This step is crucial as HEIR relies on the MLIR libraries and tools.

# Create a build directory for LLVM components, separate from the source
mkdir llvm-project/build && cd llvm-project/build

# Run CMake to configure the build.
# We explicitly enable MLIR and use Ninja as the generator.
cmake -GNinja -DLLVM_ENABLE_PROJECTS=mlir -DLLVM_TARGETS_TO_BUILD="X86;AArch64" -DCMAKE_BUILD_TYPE=Release ..

Let’s break down these important CMake flags:

  • -GNinja: Specifies Ninja as the build system. This is generally faster for large projects.
  • -DLLVM_ENABLE_PROJECTS=mlir: Tells CMake to build only the MLIR project from the vast llvm-project repository. This saves a lot of compilation time and disk space.
  • -DLLVM_TARGETS_TO_BUILD="X86;AArch64": Specifies which target architectures to build. X86 is generally sufficient for most development on desktop/laptop systems. AArch64 is for ARM-based systems like Apple Silicon Macs. You can adjust this based on your specific needs.
  • -DCMAKE_BUILD_TYPE=Release: Builds in release mode, which optimizes for performance. This is ideal for a compiler you intend to use.

⚠️ What can go wrong: If CMake fails here, carefully review the error messages. Common issues include missing CMake or C++ compiler installations, or an incorrect path if you’ve deviated from the mkdir build && cd build pattern.

After CMake finishes configuring (which might take a minute or two), compile MLIR:

ninja

This step will take a significant amount of time (potentially 30 minutes to an hour or more, depending on your system’s specs) and consume considerable CPU and memory resources, as it compiles the entire MLIR framework. This is a good time to grab a coffee, or two!

Step 3: Clone the HEIR Repository

Once MLIR is built, navigate back to your heir_dev directory and clone the HEIR repository.

# Go back to the parent directory (heir_dev)
cd ../..

# Clone the HEIR compiler repository
git clone https://github.com/heir-compiler/HEIR.git

Step 4: Build HEIR

Now we’ll build HEIR, linking it against the MLIR we just compiled. This step is critical for HEIR to find its necessary MLIR dependencies.

# Create a build directory for HEIR, separate from its source
mkdir HEIR/build && cd HEIR/build

# Run CMake to configure HEIR.
# CRITICAL: We need to tell HEIR where to find the MLIR build.
# The `MLIR_DIR` variable points to the `lib/cmake/mlir` directory within your LLVM build.
# Adjust the path carefully if your directory structure is different.
cmake -GNinja -DMLIR_DIR=$(pwd)/../../llvm-project/build/lib/cmake/mlir ..

Let’s look at the crucial MLIR_DIR flag:

  • -DMLIR_DIR=$(pwd)/../../llvm-project/build/lib/cmake/mlir: This is the most vital part of the HEIR CMake command. It explicitly tells HEIR’s CMake where to find the MLIR configuration files and libraries that were generated during the llvm-project build. The $(pwd)/../../llvm-project/build/lib/cmake/mlir path assumes HEIR/build and llvm-project/build are located as siblings within your heir_dev directory, as set up in our steps.
    • $(pwd) is your current directory (e.g., ~/heir_dev/HEIR/build).
    • .. goes up one level to ~/heir_dev/HEIR.
    • .. again goes up one level to ~/heir_dev.
    • Then /llvm-project/build/lib/cmake/mlir points to the specific MLIR installation directory.

🧠 Important: Carefully verify the MLIR_DIR path. An incorrect path is the most common reason for HEIR’s CMake configuration to fail. If you’ve placed llvm-project or HEIR in different locations, you’ll need to adjust this path accordingly.

After CMake successfully configures, compile HEIR:

ninja

This compilation should be much faster than the MLIR build, as HEIR is a smaller project that builds on top of the already compiled MLIR.

Step 5: Verify Your HEIR Installation

After ninja completes, you should have the HEIR tools built and ready. The primary tool we’ll look for is heir-opt, the HEIR optimizer.

# Check if heir-opt exists in the build/bin directory
ls bin/heir-opt

If you see bin/heir-opt listed, congratulations! You’ve successfully built the HEIR compiler. You can also try running it to confirm its basic functionality:

./bin/heir-opt --help

This command should print a list of available command-line options and passes for heir-opt, indicating that the executable is functional.

⚡ Quick Note: Remember the comment from the HEIR GitHub repository: “If you require an executable, please use format_assistant/h.” This implies that direct, end-to-end compilation to a final FHE executable is not fully stable or streamlined yet. Your heir-opt tool allows you to apply HEIR’s MLIR-based optimizations to FHE-specific intermediate representations, which is the core functionality you’ve just built and will be the focus of our initial explorations.

Mini-Challenge: Optimizing a Simple MLIR Fragment with HEIR

Let’s put your newly built heir-opt to a small test. We’ll create a very basic MLIR file and try to run heir-opt over it. While HEIR’s full power comes with FHE-specific dialects, heir-opt can still process generic MLIR, allowing us to confirm the build’s integrity.

Challenge:

  1. Create a simple MLIR file named simple.mlir that defines a basic function.
  2. Use your heir-opt executable to process this file and observe the output.

Instructions: First, create the simple.mlir file. You can place it directly in your HEIR/build directory, or in the parent HEIR directory (then adjust the path in the command).

// simple.mlir
func.func @my_simple_func(%arg0: i32) -> i32 {
  %0 = arith.addi %arg0, %arg0 : i32
  func.return %0 : i32
}

Now, run heir-opt on it. You can specify a pass to apply, or just let it print the IR by default, which confirms parsing and basic processing.

# Make sure you are in the HEIR/build directory to easily access ./bin/heir-opt
# If not, adjust the path, e.g., ~/heir_dev/HEIR/build/bin/heir-opt
./bin/heir-opt ../simple.mlir

What to Observe/Learn:

  • heir-opt should print the MLIR code, possibly with some default passes applied. You should see the content of your simple.mlir file echoed back, potentially with minor formatting changes.
  • The primary goal here is to confirm that heir-opt can successfully parse and process an MLIR file without crashing. This confirms your basic HEIR build is functional and can interpret MLIR.
  • In future chapters, we’ll explore how to apply HEIR’s specific FHE-related passes using flags like --heir-some-fhe-pass. For now, just confirming basic execution is a big step!

Common Pitfalls & Troubleshooting

Building complex software like a compiler can sometimes hit snags. Here are some common issues you might encounter and practical strategies to approach them:

  • “CMake Error: The source directory … does not appear to contain CMakeLists.txt.”
    • Problem: You’re running cmake from the wrong directory or pointing it to an incorrect source directory.
    • Solution: Ensure you are in the correct build directory (e.g., heir_dev/llvm-project/build or heir_dev/HEIR/build) and that cmake .. correctly points to the parent directory containing the CMakeLists.txt file for the project you’re trying to build.
  • “Could not find a package configuration file provided by ‘MLIR’…”
    • Problem: HEIR’s CMake couldn’t find the MLIR installation. This is almost always due to an incorrect DMLIR_DIR path.
    • Solution: Double-check the DMLIR_DIR argument in your HEIR CMake command. Make sure it points exactly to $(YOUR_LLVM_BUILD_DIR)/lib/cmake/mlir. The $(pwd) trick is sensitive to your current working directory. If in doubt, use an absolute path for MLIR_DIR.
  • “fatal error: ‘mlir/IR/BuiltinOps.h’ file not found” (or similar header errors)
    • Problem: The C++ compiler cannot locate the MLIR header files. This usually means MLIR wasn’t built correctly, or the MLIR_DIR path is still off, preventing HEIR from finding its dependencies.
    • Solution: Revisit the MLIR build steps (Step 2 of “Building HEIR”). Ensure ninja completed successfully in llvm-project/build and that no errors were reported. If it did, then focus again on the DMLIR_DIR path for HEIR’s CMake.
  • Compilation failures during ninja (many C++ errors)
    • Problem: This can be due to an incompatible C++ compiler version, missing development libraries, or insufficient system resources (memory, CPU).
    • Solution:
      • Ensure your C++ compiler (GCC/Clang) is up-to-date and supports C++17 or newer.
      • Verify you have enough RAM and CPU cores. Building LLVM/MLIR is very memory-intensive; a machine with less than 8GB RAM might struggle, and 16GB+ is recommended.
      • Sometimes, cleaning the build directory (rm -rf * within the build folder) and re-running CMake and Ninja can resolve transient issues caused by corrupted build artifacts.
  • Disk Space Issues:
    • Problem: The llvm-project repository and its build artifacts can consume a significant amount of disk space (tens of gigabytes).
    • Solution: Ensure you have ample free disk space (at least 50GB recommended) before starting the build. If you run out, ninja will fail.

Summary

Phew! You’ve successfully navigated the intricate process of setting up your HEIR development environment. This is a significant accomplishment in your journey toward understanding private AI. Let’s quickly recap what we’ve achieved:

  • Understood HEIR’s Architecture: We clarified HEIR’s deep reliance on the LLVM and MLIR frameworks as its foundational compiler infrastructure.
  • Installed Core Prerequisites: You’ve equipped your system with essential development tools including Git, CMake, Ninja, a C++ compiler (Clang/GCC), and Python.
  • Built MLIR: You successfully cloned the llvm-project and compiled the MLIR framework, which is a critical dependency for HEIR.
  • Compiled HEIR: By correctly pointing HEIR’s build system to your MLIR installation, you compiled the HEIR compiler components, including the heir-opt tool.
  • Verified Installation: You confirmed the presence and basic functionality of heir-opt with a mini-challenge, ensuring your build is operational.
  • Identified Common Pitfalls: You’re now aware of potential build issues and equipped with troubleshooting strategies, making future development smoother.

You now have a functional HEIR environment, which is a significant achievement given the complexity of compiler development. This setup provides the foundation for exploring how HEIR processes and optimizes FHE programs, bringing us closer to practical private AI inference.

In the next chapter, we’ll dive deeper into HEIR’s specific MLIR dialects and how they represent FHE computations. We’ll start to see how HEIR bridges the gap between high-level programming and privacy-preserving encrypted operations, enabling you to build truly private AI applications.

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.

References