> ## Documentation Index
> Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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](https://github.com/OrlovEvgeny/filetrace/blob/master/CONTRIBUTING.md) describes the development workflow, the pinned tools and the checks that continuous integration runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.