# Key Configuration Options for Building bpftime: A Complete CMake Guide

> Discover bpftime's key CMake configuration options for JIT, kernel integration, GPU support, and static linking. Customize your build for debugging or production with simple flags.

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

---

**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`](https://github.com/eunomia-bpf/bpftime/blob/main/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`](https://github.com/eunomia-bpf/bpftime/blob/main/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`](https://github.com/eunomia-bpf/bpftime/blob/main/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`](https://github.com/eunomia-bpf/bpftime/blob/main/CMakeLists.txt) (project root)** – Orchestrates sub-directories, applies compile definitions, and creates static archives based on the options.
- **[`vm/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/vm/CMakeLists.txt)** – Selects which VM implementation (LLVM or uBPF) gets compiled based on `BPFTIME_LLVM_JIT` and `BPFTIME_UBPF_JIT`.
- **[`runtime/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/CMakeLists.txt)** – Injects compile definitions for JIT backends, CUDA support, verifier flags, MPK, and io_uring extensions.
- **[`daemon/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/daemon/CMakeLists.txt)** – Guarded by `BUILD_BPFTIME_DAEMON` and `BPFTIME_BUILD_WITH_LIBBPF`.
- **[`bpftime-verifier/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime-verifier/CMakeLists.txt)** – Built only when `ENABLE_EBPF_VERIFIER=ON`.
- **[`tools/cli/CMakeLists.txt`](https://github.com/eunomia-bpf/bpftime/blob/main/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:

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

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

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

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

```bash
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`](https://github.com/eunomia-bpf/bpftime/blob/main/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`](https://github.com/eunomia-bpf/bpftime/blob/main/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`](https://github.com/eunomia-bpf/bpftime/blob/main/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`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/CMakeLists.txt), enabling runtime verification of userspace eBPF programs.