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

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:

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 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, 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 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:

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:

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:

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:

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 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:

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 (line 127), compiles the bpftime_llvm_vm library from 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 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 (around line 197) uses bpftime_add_static_lib_component_command to embed the LLVM VM objects into the static archive. Use the following configuration:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}