#bpf #ebpf #linker #llvm

no-std bin+lib bpf-linker

BPF static linker

6 releases

0.9.5 Sep 9, 2022
0.9.4 May 16, 2022
0.9.3 Jan 11, 2022
0.9.2 Sep 19, 2021
0.9.0 Dec 1, 2020

#53 in Unix APIs

Download history 301/week @ 2022-11-29 227/week @ 2022-12-06 292/week @ 2022-12-13 285/week @ 2022-12-20 264/week @ 2022-12-27 451/week @ 2023-01-03 500/week @ 2023-01-10 626/week @ 2023-01-17 1002/week @ 2023-01-24 351/week @ 2023-01-31 412/week @ 2023-02-07 269/week @ 2023-02-14 287/week @ 2023-02-21 363/week @ 2023-02-28 437/week @ 2023-03-07 230/week @ 2023-03-14

1,340 downloads per month


960 lines

BPF Linker 🔗

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



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 must be bitcode files (.bc) or object files with embedded bitcode (.o), optionally stored inside ar archives (.a).


The linker requires LLVM 15. It can use the same LLVM used by the rust compiler, or it can use an external LLVM installation.

If your target is aarch64-unknown-linux-gnu (i.e. Linux on Apple Silicon) you will have to use the external LLVM method.

Using LLVM provided by rustc

All you need to do is run:

cargo install bpf-linker

Using external LLVM

On Debian based distributions you need to install the llvm-15-dev and libclang-15-dev packages. If your distro doesn't have them you can get them from the official LLVM repo at https://apt.llvm.org.

On rpm based distribution you need the llvm-devel and clang-devel packages. If your distro doesn't have them you can get them from Fedora Rawhide.

Once you have installed LLVM 15 you can install the linker running:

cargo install --git https://github.com/aya-rs/bpf-linker  --tag v0.9.5 --no-default-features --features system-llvm -- bpf-linker

If you don't have cargo you can get it from https://rustup.rs or from your distro's package manager.




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:

target = "bpfel-unknown-none"

build-std = ["core"]

If for whatever reason you can't use rust nightly to build your project, you can still compile your eBPF crate with:

$ cargo rustc --release -- \
        -C linker-plugin-lto \
        -C linker-flavor=wasm-ld -C linker=bpf-linker \
        -C link-arg=--target=bpf
   Compiling bpf-log-clone v0.1.0 (/home/alessandro/bpf-log-clone)
   Finished release [optimized] target(s) in 0.86s

$ file target/release/libbpf_log_clone.so
target/release/libbpf_log_clone.so: ELF 64-bit LSB relocatable, eBPF, version 1 (SYSV), not stripped


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.



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

        --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
    -V, --version                           Prints version information

        --cpu <cpu>                  Target BPF processor. Can be one of `generic`, `probe`, `v1`, `v2`, `v3` [default:
        --cpu-features <features>    Enable or disable CPU features. The available features are: alu32, dummy, dwarfris.
                                     Use +feature to enable a feature, or -feature to disable it.  For example --cpu-
                                     features=+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

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


bpf-linker is licensed under either of

at your option.


~18K SLoC