libbpf-sys

Rust bindings to libbpf from the Linux kernel

Maintainer: Alex Forster <[email protected]>
License: BSD-2-Clause

libbpf-sys is the packaged result of using bindgen to automatically generate Rust FFI bindings to libbpf from the Linux kernel.

Warning: this crate does not provide a high-level or "safe" API wrapper around libbpf. If you are looking for an easier way to use libbpf, check out these other crates that implement higher-level APIs using libbpf-sys...

• afxdp: a Rust interface for AF_XDP – GitHub | Crates.io
• libbpf-cargo: Cargo plugin to build bpf programs – GitHub | Crates.io
• libbpf-rs: a safe, idiomatic, and opinionated wrapper around libbpf-sys – GitHub | Crates.io
• rebpf: write and load eBPF programs in Rust – GitHub | Crates.io
• xsk-rs: a Rust interface for Linux AF_XDP sockets – Github | Crates.io

The community is encouraged to build higher-level crates using libbpf-sys. Please let me know if you do!

Building

As part of the cargo build process, an included copy of libbpf is compiled and statically linked into the resulting binary. This means that, in order to build a project that depends on this crate, your system must provide a working C compiler toolchain (GCC and Clang should both work). Additionally, your system must provide development headers for zlib and libelf, and they must be discoverable via pkgconfig.

Building on a fresh Debian/Ubuntu installation:

$ apt-get install git rustc cargo build-essential pkgconf zlib1g-dev libelf-dev
$ git clone --recurse-submodules https://github.com/libbpf/libbpf-sys.git && cd libbpf-sys
$ cargo build

Building on a fresh RHEL/Fedora installation:

$ yum install git rust cargo gcc make pkgconf zlib-devel elfutils-libelf-devel
$ git clone --recurse-submodules https://github.com/libbpf/libbpf-sys.git && cd libbpf-sys
$ cargo build

Environment Variables

• LIBBPF_SYS_EXTRA_CFLAGS can be used to pass extra cflags when vendoring libbpf, libz or libelf.
• LIBBPF_SYS_LIBRARY_PATH: colon separated paths for the linker to find native libs.
• LIBBPF_SYS_LIBRARY_PATH_<TARGET_TRIPLE>: similar to LIBBPF_SYS_LIBRARY_PATH, but used to set per-target library path, to help cross-compilation environments. If LIBBPF_SYS_LIBRARY_PATH_<TARGET_TRIPLE> and LIBBPF_SYS_LIBRARY_PATH are defined, the paths from both will be used, and the "target" paths will have precedence.

Distribution

When you add this crate as a dependency to your project, your resulting binaries will dynamically link with libz and libelf. This means that the systems where you run your binaries must have these libraries installed.

Versioning

Because the API of this crate is automatically generated from libbpf sources, it uses a versioning scheme based on the version of libbpf that it provides.

The "Major.Minor" semver numbers correspond exactly to the libbpf version that each release provides. For example, the 0.6.x releases of this crate provides the API for the libbpf v0.6.x releases.

In order to allow for human error, the "Patch" semver number is used by this crate and does not necessarily match the provided libbpf version. For example, both the 0.6.1 and 0.6.2 releases of this crate contain bindings to libbpf v0.6.1, but the later release contains bugfixes and/or enhancements to the crate itself.

The exact version of libbpf that is provided by any given release can be found in the "Build Metadata" semver section, which comes after the + in the version string. For example, 0.6.2+v0.6.1 indicates that the crate version is 0.6.2 and the upstream libbpf version is v0.6.1.

Licensing and Dependencies

This crate is released under the BSD 2-Clause license, and is careful to avoid infecting users with viral licenses.

It currently depends on the following third-party libraries: