# How to Enable LLVM JIT Support When Building bpftime: A Complete Guide

> Enable LLVM JIT support in bpftime by setting the CMake flag -DBPFTIME_LLVM_JIT=ON. Discover how to activate the default eBPF execution engine for high performance.

- Repository: [eunomia-bpf/bpftime](https://github.com/eunomia-bpf/bpftime)
- Tags: how-to-guide
- Published: 2026-03-01

---

**Set the CMake flag `-DBPFTIME_LLVM_JIT=ON` during configuration to enable the high-performance LLVM JIT backend, which serves as the default eBPF execution engine in bpftime.**

The bpftime project provides a userspace eBPF runtime that supports multiple JIT compilation backends. Enabling LLVM JIT support when building bpftime unlocks the primary high-performance execution engine, which compiles eBPF bytecode to native machine code using the LLVM infrastructure. This guide explains the `BPFTIME_LLVM_JIT` configuration flag and the exact build steps required to compile bpftime with LLVM JIT support enabled.

## Understanding the BPFTIME_LLVM_JIT Configuration Flag

The LLVM JIT backend is controlled by the **`BPFTIME_LLVM_JIT`** CMake option, which determines whether the build system compiles and links the LLVM-based VM or falls back to the uBPF interpreter.

### Where the Flag is Defined

According to the bpftime source code, the flag is declared in `cmake/StandardSettings.cmake` at line 10 as a Boolean option that defaults to `ON`:

```cmake
option(BPFTIME_LLVM_JIT "Enable LLVM JIT support" ON)

```

### How the Flag Propagates Through the Build System

When `BPFTIME_LLVM_JIT` is enabled, the configuration cascades through multiple CMake files:

1. **Runtime activation** – In [`runtime/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/CMakeLists.txt) at line 127, the build system defines the `BPFTIME_LLVM_JIT=1` preprocessor macro and adds the LLVM VM target to the runtime dependencies.

2. **VM compilation** – The actual LLVM-based VM implementation resides in [`vm/compat/llvm-vm/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/compat/llvm-vm/CMakeLists.txt), which builds the `bpftime_llvm_vm` library and links against the `llvmbpf` submodule.

3. **Static library handling** – For static library builds, the root [`CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/CMakeLists.txt) around line 197 adds the LLVM VM objects to the static archive via the `bpftime_add_static_lib_component_command` macro.

## Prerequisites for Building with LLVM JIT

Before configuring the build, ensure your system meets the following requirements:

- **LLVM version 15 or higher** – The JIT backend requires LLVM libraries and headers.
- **Development tools** – Install `clang`, `llvm-config`, and LLVM development packages.
- **Standard build tools** – CMake (3.15+), a C++17-compatible compiler, and `make` or `ninja`.

On Ubuntu/Debian systems, install dependencies with:

```bash
sudo apt-get install clang llvm llvm-dev libboost-all-dev cmake make git

```

## Step-by-Step Build Instructions

### Basic Release Build with LLVM JIT

Since `BPFTIME_LLVM_JIT` defaults to `ON`, a standard configuration automatically enables LLVM JIT:

```bash
cmake -B build \
      -DCMAKE_BUILD_TYPE=Release \
      -DBPFTIME_LLVM_JIT=ON

cmake --build build --config Release --target install

```

To explicitly verify the configuration, check the CMake output for lines indicating LLVM VM compilation.

### Custom LLVM Installation Paths

If LLVM is installed in a non-standard location, point CMake to the LLVM CMake configuration:

```bash
cmake -B build \
      -DCMAKE_BUILD_TYPE=Release \
      -DBPFTIME_LLVM_JIT=ON \
      -DLLVM_DIR=/usr/local/lib/cmake/llvm

```

### Building Static Libraries with LLVM JIT

To create a static library that includes the LLVM JIT components:

```bash
cmake -B build \
      -DCMAKE_BUILD_TYPE=Release \
      -DBPFTIME_LLVM_JIT=ON \
      -DBPFTIME_BUILD_STATIC_LIB=ON

cmake --build build --target install

```

The root [`CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/CMakeLists.txt) handles embedding the LLVM VM objects into the static archive via `bpftime_add_static_lib_component_command` around line 197.

### Disabling LLVM JIT (uBPF Fallback)

To explicitly disable LLVM JIT and use the uBPF interpreter instead:

```bash
cmake -B build -DBPFTIME_LLVM_JIT=OFF

```

When disabled, the build skips the `vm/compat/llvm-vm` directory and links only the uBPF backend.

## Summary

- **The `BPFTIME_LLVM_JIT` CMake option** (defined in `cmake/StandardSettings.cmake` line 10) controls whether bpftime compiles with LLVM JIT support, defaulting to `ON`.
- **Enabling the flag** activates the LLVM VM target in [`runtime/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/CMakeLists.txt) (line 127), compiles the `bpftime_llvm_vm` library from [`vm/compat/llvm-vm/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/compat/llvm-vm/CMakeLists.txt), and links the `llvmbpf` submodule.
- **Build requirements** include LLVM 15+, clang, and standard development tools.
- **Configuration** uses `-DBPFTIME_LLVM_JIT=ON` (or `YES`), with optional `-DLLVM_DIR` for custom LLVM paths and `-DBPFTIME_BUILD_STATIC_LIB=ON` for static archives.

## Frequently Asked Questions

### What LLVM version is required for bpftime JIT support?

bpftime requires **LLVM version 15 or higher** to compile the LLVM JIT backend. The build system uses `llvm-config` to locate the necessary libraries and headers. Ensure you have the development packages installed (e.g., `llvm-dev` on Ubuntu) so that CMake can detect the LLVM CMake modules.

### How do I verify that LLVM JIT is enabled in my bpftime build?

You can verify LLVM JIT support by checking the CMake configuration output for references to `bpftime_llvm_vm` or `llvmbpf`. Additionally, after building, check that the macro `BPFTIME_LLVM_JIT` is defined to `1` in the compiled runtime (visible in [`runtime/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/CMakeLists.txt) line 127). If the build succeeds with `-DBPFTIME_LLVM_JIT=ON` but fails with `OFF`, this confirms the LLVM backend is active.

### Can I use LLVM JIT with static linking in bpftime?

Yes, you can statically link the LLVM JIT components by enabling both `BPFTIME_LLVM_JIT` and `BPFTIME_BUILD_STATIC_LIB`. The root [`CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/CMakeLists.txt) (around line 197) uses `bpftime_add_static_lib_component_command` to embed the LLVM VM objects into the static archive. Use the following configuration:

```bash
cmake -B build -DBPFTIME_LLVM_JIT=ON -DBPFTIME_BUILD_STATIC_LIB=ON

```

### What is the difference between the LLVM JIT and uBPF backends in bpftime?

The **LLVM JIT** (enabled via `BPFTIME_LLVM_JIT=ON`) is the primary high-performance execution engine that uses LLVM infrastructure to compile eBPF bytecode to native machine code. It resides in `vm/compat/llvm-vm/` and links against the `llvmbpf` submodule. The **uBPF** backend is a fallback interpreter/JIT maintained for compatibility when LLVM is unavailable or when `BPFTIME_LLVM_JIT=OFF` is set. The LLVM backend generally offers better optimization and performance for complex eBPF programs.