Environment:Fede1024 Rust rdkafka Rust Librdkafka Build Environment

Knowledge Sources	rust-rdkafka librdkafka CONFIGURATION rdkafka-sys README
Domains	Infrastructure, Build_System
Last Updated	2026-02-07 19:30 GMT

Overview

Rust 1.74+ build environment with GNU toolchain, libcurl-dev, and optional CMake for compiling the rdkafka crate with statically-linked librdkafka C library.

Description

This environment provides the compilation context required to build the rust-rdkafka crate, which wraps the C librdkafka library. By default, librdkafka is compiled from a bundled git submodule and statically linked into the Rust binary. The build process uses either the mklove (GNU make) or CMake build system to compile the native C library, then links it via Cargo's FFI build script mechanism in `rdkafka-sys/build.rs`. Optional features control SSL, GSSAPI, compression codec, and linking strategy.

Usage

Use this environment for any project that depends on the `rdkafka` crate. It is the mandatory prerequisite for compiling all producers, consumers, and admin clients provided by rust-rdkafka. The build environment must be configured before `cargo build` can succeed.

System Requirements

Category	Requirement	Notes
OS	Linux (Ubuntu 20.04+), macOS 15+, Windows (with CMake)	FreeBSD also supported (uses `gmake`)
Rust	>= 1.74 (MSRV)	Edition 2021; CI uses Rust 1.85
Toolchain	GNU toolchain	Required for compiling bundled librdkafka C code
Build Tool	GNU `make`	FreeBSD requires `gmake`; Windows requires CMake feature
Threading	`pthreads`	Required by librdkafka for thread safety
Disk	Moderate	librdkafka source tree cloned into `OUT_DIR` during build

Dependencies

System Packages

`make` (GNU make) - required for default mklove build
`pthreads` - required by librdkafka
`libcurl-dev` (e.g., `libcurl4-openssl-dev` on Ubuntu) - required
`cmake` - optional, for `cmake-build` feature (required on Windows)
`libssl-dev` - optional, for `ssl` feature
`libsasl2-dev` - optional, for `gssapi` feature
`libzstd-dev` - optional, for `zstd-pkg-config` feature
`zlib` - optional but included by default via `libz` feature
`pkg-config` - required if using `dynamic-linking` feature

Rust Crate Dependencies

`rdkafka-sys` = 4.10.0 (bundles librdkafka 2.12.1)
`futures-channel` >= 0.3.31
`futures-util` >= 0.3.31
`libc` >= 0.2.172
`log` >= 0.4.27
`serde` >= 1.0.219
`serde_json` >= 1.0.140
`slab` >= 0.4
`tokio` >= 1.45.0 (optional, default enabled)
`tracing` >= 0.1.41 (optional)

Cargo Feature Flags

`default` = `["libz", "tokio"]`
`cmake-build` - Use CMake instead of mklove (recommended, required on Windows)
`dynamic-linking` - Link system librdkafka via pkg-config (version must match 2.12.1)
`static-linking` - Link prebuilt static librdkafka from `DEP_LIBRDKAFKA_STATIC_ROOT`
`ssl` / `ssl-vendored` - Enable OpenSSL support
`gssapi` / `gssapi-vendored` - Enable SASL GSSAPI (auto-enables SSL)
`libz` / `libz-static` - Enable zlib compression (default: enabled)
`curl` / `curl-static` - Enable HTTP client via curl
`zstd` / `zstd-pkg-config` - Enable zstd compression
`external-lz4` - Use external lz4-sys instead of bundled lz4
`naive-runtime` - Use futures-executor instead of tokio

Credentials

No credentials are required for building. The following environment variables are used only by the build script:

`CFLAGS` / `LDFLAGS`: Optional compiler/linker flags merged during librdkafka compilation.
`DEP_OPENSSL_ROOT`: Path to OpenSSL root (set automatically by `openssl-sys` when `ssl-vendored` is used).
`DEP_SASL2_ROOT`: Path to libsasl2 root (set automatically by `sasl2-sys` when `gssapi-vendored` is used).
`DEP_LIBRDKAFKA_STATIC_ROOT`: Path to prebuilt librdkafka (only for `static-linking` feature).
`CMAKE_SYSTEM_NAME`: Cross-compilation target name (optional, for CMake builds).
`CMAKE_MAKE_PROGRAM`: Custom make program path (optional, for CMake builds).

Quick Install

# Ubuntu/Debian - install system dependencies
sudo apt-get update && sudo apt-get install -y \
    build-essential cmake pkg-config \
    libcurl4-openssl-dev libssl-dev libsasl2-dev

# Add to Cargo.toml
# [dependencies]
# rdkafka = { version = "0.39", features = ["cmake-build"] }

Code Evidence

Build mode selection from `rdkafka-sys/build.rs:42-101`:

fn main() {
    if env::var("CARGO_FEATURE_DYNAMIC_LINKING").is_ok() {
        eprintln!("librdkafka will be linked dynamically");
        let librdkafka_version = match env!("CARGO_PKG_VERSION")
            .split('+')
            .collect::<Vec<_>>()
            .as_slice()
        {
            [_rdsys_version, librdkafka_version] => *librdkafka_version,
            _ => panic!("Version format is not valid"),
        };
        let pkg_probe = pkg_config::Config::new()
            .cargo_metadata(true)
            .atleast_version(librdkafka_version)
            .probe("rdkafka");
        // ...
    } else if env::var("CARGO_FEATURE_STATIC_EXTERNAL").is_ok() {
        if let Ok(rdkafka_dir) = env::var("DEP_LIBRDKAFKA_STATIC_ROOT") {
            // ...
        } else {
            eprintln!("Path to DEP_LIBRDKAFKA_STATIC_ROOT not set.");
            process::exit(1);
        }
    } else {
        // Default: build from bundled source via git submodule
        if !Path::new("librdkafka/LICENSE").exists() {
            run_command_or_fail("../", "git", &["submodule", "update", "--init"]);
        }
        build_librdkafka();
    }
}

Platform-specific make command from `rdkafka-sys/build.rs:206`:

if cfg!(target_os = "freebsd") {
    "gmake"
} else {
    "make"
},

MSRV declaration from `Cargo.toml:13`:

rust-version = "1.74"

Common Errors

Error Message	Cause	Solution
`librdkafka X.Y.Z cannot be found on the system`	Dynamic linking enabled but system librdkafka version mismatch	Install exact matching librdkafka version (2.12.1) or remove `dynamic-linking` feature
`Path to DEP_LIBRDKAFKA_STATIC_ROOT not set`	Using `static-linking` feature without setting the environment variable	Set `DEP_LIBRDKAFKA_STATIC_ROOT` to prebuilt librdkafka directory
`Command failed with error code` during make	Missing system build dependencies	Install `build-essential`, `make`, `pthreads`, `libcurl-dev`
Linker errors with multiple library versions	System has conflicting versions of zlib, OpenSSL, etc.	Use vendored features (`ssl-vendored`, `libz-static`) or build in Docker/chroot

Compatibility Notes

Windows: Only the `cmake-build` feature is supported. The default mklove build system does not work on Windows.
FreeBSD: Uses `gmake` instead of `make` automatically (detected in build script).
macOS: Default features work; CMake recommended for full feature set.
docs.rs: Must use `cmake-build` feature because the shared cargo registry is read-only (mklove requires in-tree builds).
GSSAPI: Enabling `gssapi` automatically requires SSL support as well.
LZ4: No dynamic linking option available for external LZ4; only static via `external-lz4` or the bundled version.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment