BPF Linker 🔗

bpf-linker aims to simplify building modern BPF programs while still supporting older, more restrictive kernels.

Overview

bpf-linker can be used to statically link multiple BPF object files together and optionally perform optimizations needed to target older kernels. It operates on LLVM bitcode, so the inputs can be bitcode files (.bc), LLVM IR files (.ll), or object files with embedded bitcode (.o), optionally stored inside ar archives (.a).

Installation

cargo-binstall

The recommended installation method is via cargo-binstall. Install cargo-binstall first, then run:

cargo binstall bpf-linker

Manual download

Download the tarball from the releases page that matches your Rust target triple. The published binaries currently use *-apple-darwin for macOS and *-unknown-linux-musl for Linux, and *-pc-windows-gnullvm for Windows.

After downloading, unpack the archive into a directory that is included in your PATH.

Example:

# Linux ARM64
curl -LO https://github.com/aya-rs/bpf-linker/releases/latest/download/bpf-linker-aarch64-unknown-linux-musl.tar.zst
# Linux x86_64
curl -LO https://github.com/aya-rs/bpf-linker/releases/latest/download/bpf-linker-x86_64-unknown-linux-musl.tar.zst
# macOS ARM64
curl -LO https://github.com/aya-rs/bpf-linker/releases/latest/download/bpf-linker-aarch64-apple-darwin.tar.zst
# macOS x86_64
curl -LO https://github.com/aya-rs/bpf-linker/releases/latest/download/bpf-linker-x86_64-apple-darwin.tar.zst
# Windows ARM64
curl -LO https://github.com/aya-rs/bpf-linker/releases/latest/download/bpf-linker-aarch64-pc-windows-gnullvm.tar.zst
# Windows x86_64
curl -LO https://github.com/aya-rs/bpf-linker/releases/latest/download/bpf-linker-x86_64-pc-windows-gnullvm.tar.zst

mkdir -p "$HOME/.local/bin"
tar -xpf bpf-linker-*.tar.zst -C "$HOME/.local/bin"
# Add this line to your shell startup file. If you use a different shell,
# refer to its documentation for adding directories to PATH.
export PATH="$HOME/.local/bin:$PATH"

Packages

bpf-linker may also be available through your operating system's package repositories. In general, packaged builds are expected to work with Rust toolchains provided by the same package manager. If you use Rust via rustup, prefer installing bpf-linker with cargo-binstall or from the release tarballs instead.

Current packaging status:

Building from source

Building from source, including even a plain cargo install bpf-linker invocation, is not recommended for regular users due to dependency on specific LLVM version, system libraries and overall complexity of getting the setup right.

If you're interested in packaging or contributing to bpf-linker, you're welcome to check the build instructions in BUILDING.md.

Usage

Rust

Nightly

To compile your eBPF crate just run:

cargo +nightly build --target=bpfel-unknown-none -Z build-std=core --release

If you don't want to have to pass the target and build-std options every time, you can put them in .cargo/config.toml under the crate's root folder:

[build]
target = "bpfel-unknown-none"

[unstable]
build-std = ["core"]

(Experimental) BTF support

To emit BTF debug information, set the following rustflags:

-C debuginfo=2 -C link-arg=--btf

These flags will work only for the eBPF targets (bpfeb-unknown-none, bpfel-unknown-none). Make sure you are specifying them only for eBPF crates, not for the user-space ones!

When compiling an eBPF crate directly with cargo +nightly build, they can be defined through the RUSTFLAGS environment variable:

RUSTFLAGS="-C debuginfo=2 -C link-arg=--btf" cargo +nightly build --target=bpfel-unknown-none -Z build-std=core --release

To avoid specifying them manually, you can put them in .cargo/config.toml:

[build]
target = "bpfel-unknown-none"
rustflags = "-C debuginfo=2 -C link-arg=--btf"

[unstable]
build-std = ["core"]

After that, the BPF object file present in target/bpfel-unknown-none/release should contain a BTF section.

Clang

For a simple example of how to use the linker with clang see this gist. In the example lib.c is compiled as a static library which is then linked by program.c. The Makefile shows how to compile the C code and then link it.

CLI syntax

bpf-linker

USAGE:
    bpf-linker [FLAGS] [OPTIONS] --output <output> [--] [inputs]...

FLAGS:
        --disable-expand-memcpy-in-order    Disable passing --bpf-expand-memcpy-in-order to LLVM
        --disable-memory-builtins           Disble exporting memcpy, memmove, memset, memcmp and bcmp. Exporting those
                                            is commonly needed when LLVM does not manage to expand memory intrinsics to
                                            a sequence of loads and stores
    -h, --help                              Prints help information
        --ignore-inline-never               Ignore `noinline`/`#[inline(never)]`. Useful when targeting kernels that
                                            don't support function calls
        --unroll-loops                      Try hard to unroll loops. Useful when targeting kernels that don't support
                                            loops
    -V, --version                           Prints version information

OPTIONS:
        --cpu <cpu>                  Target BPF processor. Can be one of `generic`, `probe`, `v1`, `v2`, `v3` [default:
                                     generic]
        --cpu-features <features>    Enable or disable CPU features. The available features are: alu32, dummy, dwarfris.
                                     LLVM 22 builds also support allows-misaligned-mem-access. Use +feature to
                                     enable a feature, or -feature to disable it. For example --cpu-features=+allows-
                                     misaligned-mem-access,+alu32,-dwarfris [default: ]
        --dump-module <path>         Dump the final IR module to the given `path` before generating the code
        --emit <emit>                Output type. Can be one of `llvm-bc`, `asm`, `llvm-ir`, `obj` [default: obj]
        --export <symbols>...        Comma separated list of symbols to export. See also `--export-symbols`
        --export-symbols <path>      Export the symbols specified in the file `path`. The symbols must be separated by
                                     new lines
    -L <libs>...                     Add a directory to the library search path
        --llvm-args <args>...        Extra command line arguments to pass to LLVM
        --log-file <path>            Output logs to the given `path`
        --log-level <level>          Set the log level. Can be one of `off`, `info`, `warn`, `debug`, `trace`
    -O <optimize>...                 Optimization level. 0-3, s, or z [default: 2]
    -o, --output <output>            Write output to <output>
        --target <target>            LLVM target triple. When not provided, the target is inferred from the inputs

ARGS:
    <inputs>...    Input files. Can be object files or static libraries

License

bpf-linker is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.