Key Configuration Options for Building bpftime: A Complete CMake Guide

bpftime uses CMake cache variables defined in cmake/StandardSettings.cmake to control JIT backends, kernel integration, GPU support, and static linking, allowing you to customize builds for debugging, production, or specialized deployments via -D<option>=ON/OFF flags.

The eunomia-bpf/bpftime repository provides a userspace eBPF runtime that requires careful configuration during compilation. Understanding the key configuration options for building bpftime allows developers to enable specific JIT compilers, integrate with kernel BPF facilities, and optimize for target environments ranging from development workstations to embedded systems.

Core Build Configuration Categories

All configuration options are declared as CMake option() variables in cmake/StandardSettings.cmake and consumed throughout the project hierarchy. These options control five major build dimensions.

Build Type and Output Format

The fundamental build characteristics are controlled by standard and project-specific CMake variables:

• CMAKE_BUILD_TYPE – Controls optimization levels. Set to Debug (default) for development with symbols, or Release for production optimizations.
• BPFTIME_BUILD_EXECUTABLE – When ON, builds the standalone bpftime CLI binary instead of only the library components. Default is OFF.
• BPFTIME_BUILD_STATIC_LIB – When enabled, packs all components (vm, runtime, spdlog, etc.) into a single libbpftime.a archive. Default is OFF.

JIT Backend Selection

bpftime supports multiple execution engines selectable at build time:

• BPFTIME_LLVM_JIT – Enables the LLVM-based JIT/AOT VM implementation. Consumed in vm/CMakeLists.txt to compile LLVM-specific sources. Default is ON.
• BPFTIME_UBPF_JIT – Enables the uBPF interpreter/JIT backend. Also consumed in vm/CMakeLists.txt. Default is ON.

You can disable one to reduce binary size if only a specific backend is required for your deployment.

Kernel Integration and Daemon Features

Integration with the Linux kernel BPF subsystem and userspace daemon capabilities:

• BPFTIME_BUILD_WITH_LIBBPF – Links against libbpf and Linux kernel headers. Required for syscall-trace functionality and daemon operation. Default is ON.
• BUILD_BPFTIME_DAEMON – Builds the optional bpftime-daemon service. Guarded by the libbpf option above. Default is ON.
• BPFTIME_BUILD_KERNEL_BPF – Enables shared kernel BPF maps used by the daemon for coordination. Default is ON.

GPU and Advanced Memory Options

Specialized hardware acceleration and memory protection features:

• BPFTIME_ENABLE_CUDA_ATTACH – Builds the CUDA attach implementation for GPU tracing. Default is OFF.
• BPFTIME_ENABLE_GDRCOPY – Pulls in the GDRCopy library for faster GPU memory copies. Depends on CUDA attach. Default is OFF.
• BPFTIME_ENABLE_MPK – Enables Memory-Protection-Keys-based protection for shared memory regions. Default is OFF.
• BPFTIME_ENABLE_IOURING_EXT – Enables extra eBPF helpers that utilize io_uring. Default is OFF.

Developer and Safety Options

Debugging, verification, and code quality controls:

• ENABLE_EBPF_VERIFIER – Compiles the PREVAIL-based verifier for userspace eBPF programs. Consumed in bpftime-verifier/CMakeLists.txt. Default is OFF.
• ENABLE_PROBE_READ_CHECK and ENABLE_PROBE_WRITE_CHECK – Insert runtime safety checks for map read and write operations. Both default to ON.
• BPFTIME_WARNINGS_AS_ERRORS – Treats compiler warnings as errors. Default is OFF.
• BPFTIME_ENABLE_LTO – Enables link-time optimization (IPO). Default is OFF.
• BPFTIME_ENABLE_CCACHE – Uses ccache to speed up recompilation. Default is OFF.
• BPFTIME_ENABLE_ASAN – Builds with AddressSanitizer and UndefinedBehaviorSanitizer. Default is OFF.
• BPFTIME_VERBOSE_OUTPUT – Prints detailed CMake progress messages. Default is ON.

Where Configuration Options Are Defined

Understanding the CMake architecture helps when modifying build behavior. The option declarations and consumption follow a specific hierarchy:

• cmake/StandardSettings.cmake – The single source of truth containing all option() declarations for the project.
• CMakeLists.txt (project root) – Orchestrates sub-directories, applies compile definitions, and creates static archives based on the options.
• vm/CMakeLists.txt – Selects which VM implementation (LLVM or uBPF) gets compiled based on BPFTIME_LLVM_JIT and BPFTIME_UBPF_JIT.
• runtime/CMakeLists.txt – Injects compile definitions for JIT backends, CUDA support, verifier flags, MPK, and io_uring extensions.
• daemon/CMakeLists.txt – Guarded by BUILD_BPFTIME_DAEMON and BPFTIME_BUILD_WITH_LIBBPF.
• bpftime-verifier/CMakeLists.txt – Built only when ENABLE_EBPF_VERIFIER=ON.
• tools/cli/CMakeLists.txt – Demonstrates linking whole-archive of selected VM libraries, relevant for static builds.

Build Configuration Examples

Debug Build with Dual JIT Backends

The standard development configuration enables both LLVM and uBPF backends with kernel integration:

git clone https://github.com/eunomia-bpf/bpftime.git
cd bpftime
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug \
         -DBPFTIME_LLVM_JIT=ON \
         -DBPFTIME_UBPF_JIT=ON \
         -DBPFTIME_BUILD_WITH_LIBBPF=ON
make -j$(nproc)

This produces libbpftime_llvm_vm.so and libbpftime_ubpf_vm.so, links the runtime against libbpf, and compiles the daemon.

Static Library Release Build

For deployment scenarios requiring a single static archive:

cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DBPFTIME_BUILD_STATIC_LIB=ON \
         -DBPFTIME_BUILD_WITH_LIBBPF=ON \
         -DBPFTIME_ENABLE_IOURING_EXT=ON
make -j$(nproc)

The resulting libbpftime.a contains all components including the VM, runtime, and spdlog.

GPU Tracing with CUDA Support

Enabling GPU attach capabilities requires CUDA toolkit configuration:

cmake .. -DBPFTIME_ENABLE_CUDA_ATTACH=ON \
         -DBPFTIME_ENABLE_GDRCOPY=ON \
         -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda

If automatic CUDA detection fails, set BPFTIME_CUDA_ROOT instead of CUDA_TOOLKIT_ROOT_DIR.

Sanitizer-Enabled Debug Build

For detecting memory errors during development:

cmake .. -DBPFTIME_ENABLE_ASAN=ON -DCMAKE_BUILD_TYPE=Debug

This compiles all targets with -fsanitize=address,undefined and links the sanitizer runtime.

eBPF Verifier Integration

To include the PREVAIL-based userspace verifier:

cmake .. -DENABLE_EBPF_VERIFIER=ON

This builds the verifier sources in bpftime-verifier/ and injects the ENABLE_EBPF_VERIFIER and ENABLE_BPFTIME_VERIFIER definitions into the runtime.

Summary

Configuring bpftime requires understanding the CMake option hierarchy defined in cmake/StandardSettings.cmake. The essential configuration categories include:

• JIT Backend Selection – Toggle BPFTIME_LLVM_JIT and BPFTIME_UBPF_JIT to control which VM implementations are compiled in vm/CMakeLists.txt.
• Output Format – Use BPFTIME_BUILD_EXECUTABLE for CLI tools or BPFTIME_BUILD_STATIC_LIB for single-archive deployments.
• Kernel Integration – Enable BPFTIME_BUILD_WITH_LIBBPF and BUILD_BPFTIME_DAEMON for syscall tracing and daemon functionality.
• Hardware Acceleration – Activate BPFTIME_ENABLE_CUDA_ATTACH and BPFTIME_ENABLE_GDRCOPY for GPU tracing, or BPFTIME_ENABLE_MPK for memory protection.
• Developer Tools – Utilize BPFTIME_ENABLE_ASAN, ENABLE_EBPF_VERIFIER, and BPFTIME_WARNINGS_AS_ERRORS for debugging and code quality.

Adjust these options at the CMake command line to tailor the build for development, production, or specialized hardware environments.

Frequently Asked Questions

How do I build bpftime with only the LLVM JIT backend?

Set -DBPFTIME_LLVM_JIT=ON and -DBPFTIME_UBPF_JIT=OFF when running CMake. The vm/CMakeLists.txt file uses these flags to select which source files are compiled, ensuring only the LLVM-based VM implementation is included in the final binaries.

What is the difference between BPFTIME_BUILD_STATIC_LIB and BPFTIME_BUILD_EXECUTABLE?

BPFTIME_BUILD_STATIC_LIB creates a single libbpftime.a archive containing all components suitable for embedding in other projects, while BPFTIME_BUILD_EXECUTABLE produces a standalone bpftime CLI binary for direct command-line usage. These options are processed in the root CMakeLists.txt to determine the final output targets.

Which configuration options are required to enable GPU tracing support?

You must set -DBPFTIME_ENABLE_CUDA_ATTACH=ON to compile the CUDA attach implementation, and optionally -DBPFTIME_ENABLE_GDRCOPY=ON for optimized GPU memory copies. Ensure you also specify the CUDA toolkit path via -DCUDA_TOOLKIT_ROOT_DIR or the BPFTIME_CUDA_ROOT environment variable if automatic detection fails.

How do I enable the eBPF verifier during the build process?

Add -DENABLE_EBPF_VERIFIER=ON to your CMake command. This compiles the PREVAIL-based verifier sources located in bpftime-verifier/ and injects the necessary compile definitions into runtime/CMakeLists.txt, enabling runtime verification of userspace eBPF programs.

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