Build Filetrace from source

Build the filetrace command and the filetrace-agent daemon with CMake and Clang, enable static linking or sanitizers, and run the unit and kernel tests.

Filetrace is written in C23 and builds with CMake. On Linux the build produces both programs with their BPF probes embedded; on macOS only the command-line interface and the unit tests build. Release builds link statically, so a binary from a release archive needs nothing installed beside it.

​

Dependencies

Dependency	Version	Used for
Clang	19 or later	C23 and #embed
CMake	3.25 or later	The build
libbpf	1.3 or later	Loading the probes (Linux)
llvm-strip		Stripping the BPF objects (Linux)
protobuf-c	1.3 or later	The OTLP exporter and the gRPC API
nghttp2	1.60 or later	gRPC over HTTP/2

tools/dev/Dockerfile in the repository lists the Debian packages. On macOS, brew install protobuf-c libnghttp2 provides the last two.

​

Build

git clone https://github.com/OrlovEvgeny/filetrace.git
cd filetrace
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
sudo build/filetrace doctor

The build tree holds build/filetrace and build/filetrace-agent.

CMake option	Effect
-DFILETRACE_STATIC=ON	Links libbpf, protobuf-c and nghttp2 into the programs. On Linux the result is fully static.
-DFILETRACE_SANITIZE=ON	Builds with AddressSanitizer and UndefinedBehaviorSanitizer.

The C code generated from the protobuf schemas is committed under gen/, so building needs neither Buf nor network access.

​

Run the tests

ctest --test-dir build --output-on-failure

The unit tests run on Linux and macOS. integration-auto and integration-kprobe need root and a kernel that supports the probes, and are skipped otherwise. They start the agent with the probe set the kernel prefers and with the kprobe set, generate real transfers, and check exact byte counts, rates, confidence levels and the output of every command.

​

Develop on macOS

Collection needs a Linux kernel. From macOS, tools/dev/linux.sh <command> runs a command in a Linux container with the source tree mounted at /src, and this runs the demo, which builds the project, starts the agent, generates transfers and walks through the commands:

tools/dev/linux.sh tools/dev/demo.sh

The container sees the kernel it runs on: under Docker Desktop that is the Docker VM, not the macOS host.

The repository’s CONTRIBUTING.md describes the development workflow, the pinned tools and the checks that continuous integration runs.