Installation and Test
Table of Contents
- Building and Test
- Table of Contents
- Use docker image
- Install Dependencies
- Detailed things about building
- build options
- Build and install the complete runtime in release mode(With ubpf jit)
- Build and install the complete runtime in debug mode(With ubpf jit)
- Build and install the complete runtime in release mode(With llvm jit)
- Compile with LTO enabled
- Compile with userspace verifier
- Compile with libbpf disabled
- Testing targets
- Compile only the vm (No runtime, No uprobe)
- More compile options
Use docker image
We provide a docker image for building and testing bpftime.
# run the container
docker run -it --rm --name test_bpftime -v "$(pwd)":/workdir -w /workdir ghcr.io/eunomia-bpf/bpftime:latest /bin/bash
# start another shell in the container (If needed)
docker exec -it test_bpftime /bin/bash
Or build the docker from dockerfile:
Install Dependencies
Install the required packages:
sudo apt-get update && sudo apt-get install \
libelf1 libelf-dev zlib1g-dev make cmake git libboost-all-dev \
binutils-dev libyaml-cpp-dev ca-certificates clang llvm pkg-config llvm-dev
git submodule update --init --recursive
We've tested on Ubuntu 23.04. The recommended gcc
>= 12.0.0 clang
>= 16.0.0. It's recommanded to use libboost1.74-all-dev
.
On Ubuntu 20.04, you may need to manually switch to gcc-12.
Build and install all things
Install all things that could be installed to ~/.bpftime
, includes:
bpftime
: A cli tool used for injecting agent & server to userspace programsbpftime-vm
: A cli tool used for compiling eBPF programs into native programs, or run the compiled programbpftimetool
: A cli tool used to manage things stored in shared memory, such as the data of maps or programsbpftime_daemon
: An executable used for implementing the similar thing like syscall server, but don't need to be injected to the userspace programlibbpftime-agent.so
,libbpftime-agent-transformer.so
: Libraries needed by bpftime agentlibbpftime-syscall-server.so
: Library needed by bpftime syscall server
Build with makefile:
Or you can also build with cmake
(The Makefile is a wrapper of cmake commands):
cmake -Bbuild -DCMAKE_BUILD_TYPE:STRING=Release \
-DSPDLOG_ACTIVE_LEVEL=SPDLOG_LEVEL_INFO
cmake --build build --config Release --target install
export PATH=$PATH:~/.bpftime
Then you can run cli:
See the Makefile for some common commands.
Detailed things about building
We use cmake as build system.
build options
You may be interested in the following cmake options:
CMAKE_BUILD_TYPE
: Specify the build type. It could beDebug
,Release
,MinSizeRel
orRelWithDebInfo
. If you are not going to debug bpftime, you just need to set it toRelease
. Default toDebug
.BPFTIME_ENABLE_UNIT_TESTING
: Whether to build unit test targets. SeeTesting targets
for details. Default toNO
.BPFTIME_ENABLE_LTO
: Whether to enable Link Time Optimization. Enabling this may increase the compile time, but it may lead to a better performance. Default toNo
.BPFTIME_ENABLE_CCACHE
: Enable the usage of Ccache to speed up rebuild times. Default toOFF
.BPFTIME_ENABLE_ASAN
: Enable Address Sanitizer to detect memory errors. Default toOFF
.ENABLE_EBPF_VERIFIER
: Whether to enable userspace eBPF verifier. Default toOFF
.BPFTIME_LLVM_JIT
: Whether to use LLVM JIT as the ebpf runtime. Requires LLVM >= 15. It's recommended to enable this, since the ubpf intepreter is no longer maintained. Default toON
.BPFTIME_UBPF_JIT
: Whether to use uBPF JIT backend. Default toON
.LLVM_DIR
: Specify the installing directory of LLVM. CMake may not discover the LLVM installation by default. Set this option to the directory that containsLLVMConfig.cmake
, such as/usr/lib/llvm-15/cmake
on UbuntuBUILD_BPFTIME_DAEMON
: Build with the daemon for load the eBPF program into hkernel and se kernel verifier. Default toON
.BPFTIME_BUILD_WITH_LIBBPF
: Build bpftime with libbpf. When disabled, it can only be run in userspace but can be easily ported to other platforms, e.g. macOS. Default toON
.BPFTIME_BUILD_KERNEL_BPF
: Whether to build with bpf share maps. Default toON
.BPFTIME_BUILD_STATIC_LIB
: Build bpftime runtime into a whole static libraries. It can be easily linked into other programs. Default toOFF
.BPFTIME_ENABLE_MPK
: Enable Memory Protection Keys for the shared memory. Default toOFF
.BPFTIME_ENABLE_IOURING_EXT
: Enable iouring helpers extensions. Default toOFF
.ENABLE_PROBE_WRITE_CHECK
: Enable the probe write check. It will check the bpf_probe_write_user operation and report the error if the probe write address is invalid. Default toON
.ENABLE_PROBE_READ_CHECK
: Enable the probe read check. It will check the bpf_probe_write operation and report the error if the probe read address is invalid. Default toON
.BPFTIME_ENABLE_CUDA_ATTACH
: Enable CUDA/GPU attach support. RequiresBPFTIME_CUDA_ROOT
to be set to the CUDA installation directory (e.g.,/usr/local/cuda-12.8
). Default toOFF
.BPFTIME_CUDA_ROOT
: Specify the root directory of CUDA installation. Required whenBPFTIME_ENABLE_CUDA_ATTACH=1
.BPFTIME_WARNINGS_AS_ERRORS
: Treat compiler warnings as errors. Default toOFF
.BPFTIME_VERBOSE_OUTPUT
: Enable verbose output, allowing for a better understanding of each step taken. Default toON
.
Please see https://github.com/eunomia-bpf/bpftime/blob/master/cmake/StandardSettings.cmake forall the build options.
Build and install the complete runtime in release mode(With ubpf jit)
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DBPFTIME_ENABLE_LTO=NO
cmake --build build --config Release --target install
Build and install the complete runtime in debug mode(With ubpf jit)
cmake -Bbuild -DCMAKE_BUILD_TYPE=Debug -DBPFTIME_ENABLE_LTO=NO
cmake --build build --config Debug --target install
Build and install the complete runtime in release mode(With llvm jit)
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DBPFTIME_ENABLE_LTO=NO -DBPFTIME_LLVM_JIT=YES
cmake --build build --config RelWithDebInfo --target install
Compile with LTO enabled
Just set BPFTIME_ENABLE_LTO
to YES
For example, build the package, with llvm-jit and LTO enabled:
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DBPFTIME_ENABLE_LTO=YES -DBPFTIME_LLVM_JIT=YES
cmake --build build --config RelWithDebInfo --target install
Compile with userspace verifier
Note that we are using https://github.com/vbpf/ebpf-verifier as userspace verifier. It's not perfect, and may not support some features (such as ringbuf)
cmake -DBPFTIME_LLVM_JIT=NO -DENABLE_EBPF_VERIFIER=YES -DCMAKE_BUILD_TYPE=Release -B build
cmake --build build --config Release --target install
Compile with libbpf disabled
This flag can be used to compile bpftime
on macOS. It will disable all the libbpf related libraries and features that are used in bpftime.
cmake -Bbuild -DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo -DBPFTIME_BUILD_WITH_LIBBPF=OFF -DBPFTIME_BUILD_KERNEL_BPF=OFF
cmake --build build --config RelWithDebInfo --target install -j$(JOBS)
Compile with CUDA/GPU attach support
To enable CUDA attach support, set BPFTIME_ENABLE_CUDA_ATTACH=1
and specify the CUDA installation path:
# Example with CUDA 12.8
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DBPFTIME_ENABLE_CUDA_ATTACH=1 -DBPFTIME_CUDA_ROOT=/usr/local/cuda-12.8
cmake --build build --config Release --target install
Note: Ensure that BPFTIME_CUDA_ROOT
points to your CUDA installation directory (e.g., /usr/local/cuda-12.8
, /usr/local/cuda-12.6
, etc.).
Testing targets
We have some targets for unit testing, they are:
bpftime_daemon_tests
bpftime_runtime_tests
llvm_jit_tests
These targets will only be enabled when BPFTIME_ENABLE_UNIT_TESTING
was set to YES
.
Build and run them to test, for example:
cmake -DCMAKE_PREFIX_PATH=/usr/include/llvm -DBPFTIME_LLVM_JIT=YES -DBPFTIME_ENABLE_UNIT_TESTING=YES -DCMAKE_BUILD_TYPE=Release -B build
cmake --build build --config RelWithDebInfo --target bpftime_runtime_tests
sudo ./build/runtime/unit-test/bpftime_runtime_tests
Compile only the vm (No runtime, No uprobe)
For a lightweight build without the runtime (only vm library and LLVM JIT):
More compile options
See https://github.com/eunomia-bpf/bpftime/blob/master/cmake/StandardSettings.cmake for all cmake build options.