0x55aa
← Back to Blog

Rust's `build.rs`: The Secret Script That Runs Before Your Code Does 🔨🦀

•8 min read
"rust""systems-programming""performance""build-scripts""ffi"

Rust's build.rs: The Secret Script That Runs Before Your Code Does 🔨🦀

Here's a sentence I never expected to type: I wrote a Rust program to compile my other Rust program.

That's build.rs in a nutshell. A full Rust script — not a shell script, not a Makefile, not a YAML blob — that runs before your crate compiles, with access to environment variables, file system operations, and the ability to tell the Rust compiler what to link, where to find headers, and what code to generate.

Coming from 7 years of Laravel and Node.js, I had never thought deeply about what happens between "I typed cargo build" and "my binary exists." build.rs cracked that open for me in the best possible way.

The Problem That Led Me Here 🧩

For my RF/SDR hobby projects, I needed to call into librtlsdr — the C library that drives RTL-SDR dongles. It's not a Rust library. It's a C library, with a C API, and a .so or .dylib sitting somewhere on the system.

In Node.js, I would have used ffi-napi with a runtime path lookup and a prayer. In PHP, I would have called exec() to invoke a command-line tool and parsed stdout (no judgment, we've all been there). In Rust, the way to link a C library is: tell the compiler about it at build time.

Enter build.rs.

What Is build.rs? 🤔

build.rs is a file you place at the root of your crate (next to Cargo.toml). Cargo automatically detects it, compiles it with rustc, runs it as a standalone executable before your actual crate compiles, and reads its stdout for special instructions.

Your build.rs can print lines like:

cargo:rustc-link-lib=rtlsdr
cargo:rustc-link-search=/usr/local/lib
cargo:rerun-if-changed=wrapper.h

Cargo reads these and says: "Got it. Link librtlsdr, search /usr/local/lib for it, and re-run this script if wrapper.h changes." The compiler then proceeds with those instructions baked in.

Coming from web dev: This is like a composer.json script that actually runs at the moment packages are installed — except it's a real program, not a string, and it talks directly to the compiler.

The Simplest Possible build.rs 🪜

fn main() {
    // Tell the linker to link librtlsdr
    println!("cargo:rustc-link-lib=rtlsdr");

    // Tell Cargo to re-run this script if these files change
    println!("cargo:rerun-if-changed=build.rs");
    println!("cargo:rerun-if-changed=wrapper.h");
}

That's it. Three println! calls. Cargo picks them up, passes cargo:rustc-link-lib=rtlsdr to the linker, and your Rust code can now call into librtlsdr via unsafe extern "C" bindings.

No Makefile. No shell script. No package.json postinstall hook that runs node-gyp rebuild and breaks on every developer's machine differently.

The Real Power: bindgen Integration ⚡

Now here's where it gets genuinely exciting. Instead of hand-writing C FFI bindings, you can use the bindgen crate in your build.rs to automatically generate them from C header files.

// build.rs
use std::path::PathBuf;

fn main() {
    println!("cargo:rustc-link-lib=rtlsdr");
    println!("cargo:rerun-if-changed=wrapper.h");

    let bindings = bindgen::Builder::default()
        .header("wrapper.h")
        .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
        .generate()
        .expect("Unable to generate bindings");

    let out_path = PathBuf::from(std::env::var("OUT_DIR").unwrap());
    bindings
        .write_to_file(out_path.join("bindings.rs"))
        .expect("Couldn't write bindings!");
}

bindgen reads wrapper.h (which #includes the librtlsdr headers), parses all the C function signatures and struct definitions, and generates a Rust file with safe-ish wrappers. At compile time. Automatically.

Then in your main Rust code:

include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

Boom. All the C library functions are now accessible from Rust, typed correctly, without you ever touching them by hand.

What excited me about this: In Node.js, I've debugged node-gyp failures at 11pm more times than I care to admit. Missing Python version, wrong MSVC version, wrong libc — it always broke at the worst moment. In Rust, build.rs with bindgen runs in a deterministic Rust environment. If it compiles, it works. The compiler is the integration test.

Detecting System Libraries 🔍

build.rs doesn't just hard-code paths — it can search for libraries intelligently using the pkg_config crate:

fn main() {
    if let Ok(lib) = pkg_config::probe_library("librtlsdr") {
        // pkg-config found it, already set the link flags
        println!("Found librtlsdr at {:?}", lib.include_paths);
    } else {
        // Fallback: assume it's somewhere standard
        println!("cargo:rustc-link-lib=rtlsdr");
    }

    println!("cargo:rerun-if-changed=build.rs");
}

pkg_config::probe_library("librtlsdr") shells out to pkg-config, finds the library's include paths and library paths, and sets all the necessary rustc-link-* flags automatically. Cross-platform, no hardcoded /usr/local/lib.

The PHP comparison I can't help making: This is composer.json checking whether ext-gd is installed — except instead of throwing a vague error at install time, Rust finds the library, queries its version, validates it's compatible, and feeds the exact linker flags needed. All in a program you wrote. In Rust.

Code Generation: When You Need a Lookup Table 📊

build.rs is also where you generate code that would be annoying to maintain by hand. Classic example: a lookup table from a data file.

For my SDR projects, I have a list of known APRS frequency allocations by region. Instead of hardcoding a HashMap in my Rust code, I generate it at build time from a .csv file:

// build.rs
use std::fs;
use std::path::PathBuf;

fn main() {
    println!("cargo:rerun-if-changed=frequencies.csv");

    let csv = fs::read_to_string("frequencies.csv").unwrap();
    let mut entries = String::from("[\n");

    for line in csv.lines().skip(1) {
        let parts: Vec<&str> = line.split(',').collect();
        if parts.len() >= 2 {
            entries.push_str(&format!(
                "    (\"{}\", {}),\n",
                parts[0].trim(),
                parts[1].trim()
            ));
        }
    }
    entries.push(']');

    let out = PathBuf::from(std::env::var("OUT_DIR").unwrap());
    fs::write(out.join("frequencies.rs"), format!(
        "static FREQUENCIES: &[(&str, f64)] = &{};\n", entries
    )).unwrap();
}

If frequencies.csv changes, Cargo re-runs build.rs, regenerates frequencies.rs, and recompiles. The lookup table is always in sync with the source data, checked at compile time, with zero runtime parsing overhead. The data is baked into the binary as a static array.

For my RF/SDR hobby projects, I needed this: Real-time signal processing can't afford runtime CSV parsing. The frequencies need to be there instantly, at the speed of a static array lookup. build.rs made that trivial.

Environment Variables and Conditional Compilation 🌍

build.rs can also expose information to your code via cargo:rustc-cfg and cargo:rustc-env:

fn main() {
    // Expose a compile-time constant your code can read
    println!("cargo:rustc-env=BUILD_DATE={}", chrono::Utc::now().format("%Y-%m-%d"));

    // Conditionally enable a feature based on environment
    if std::env::var("ENABLE_EXPERIMENTAL").is_ok() {
        println!("cargo:rustc-cfg=experimental");
    }
}

In your code:

const BUILD_DATE: &str = env!("BUILD_DATE");

#[cfg(experimental)]
fn experimental_decoder() { /* ... */ }

BUILD_DATE is embedded at compile time, zero runtime cost. The experimental decoder literally doesn't exist in production binaries unless ENABLE_EXPERIMENTAL was set at build time.

This is compile-time .env configuration. Not "we read the env at startup." The value is sealed into the binary.

The Security Angle 🔒

As a security enthusiast, build.rs is both exciting and worth respecting. It runs arbitrary Rust code with the same permissions as your build process. That means:

  • It can read files from your filesystem
  • It can shell out with std::process::Command
  • It can make network requests (please don't)
  • It runs on every cargo build, including in CI/CD

The Rust ecosystem takes this seriously — crates.io shows whether a crate uses a build.rs (it's called "has build script"), and many security audits flag build scripts for review. You should treat build.rs with the same care as any code that runs with build-system permissions.

The flip side: because it's Rust, it's not a shell script. Shell injection isn't possible. The code is typed, linted, and compiled before it runs. Compare this to postinstall scripts in npm, which are arbitrary shell commands running with your permissions on npm install. The npm supply chain attacks of the last few years exploited exactly this. Rust's build.rs is safer by construction, though not immune to malicious crate authors.

When to Use build.rs — And When Not To 🎯

Use it when:

  • Linking C/C++ libraries (FFI)
  • Auto-generating bindings from C headers (bindgen)
  • Embedding build-time data (lookup tables, proto-generated code, timestamps)
  • Detecting system capabilities at compile time

Don't use it when:

  • You're doing something Cargo features already handle
  • You want to run tests (that's cargo test)
  • You're tempted to make network calls (seriously, don't)

The key rule: build.rs is for compile-time work. If it can happen at runtime, do it at runtime. If it must happen at compile time — linking, code generation, header parsing — build.rs is exactly right.

The Bottom Line 🏁

build.rs was one of those Rust discoveries that made me genuinely reconsider how I thought about the build process. In seven years of Laravel, "the build" was composer install and maybe npm run build. It was never programmable in a language I actually wrote production code in.

Rust gives you a full program, in Rust, to orchestrate your compile step. Link C libraries without Makefiles. Generate code from data files without code-gen scripts. Detect system capabilities without platform-specific shell scripts.

For my SDR projects specifically, build.rs + bindgen transformed "link this annoying C library" from a multi-hour yak shave into a 20-line Rust file that just works, on any machine with librtlsdr installed, detected automatically, linked correctly, bindings generated fresh.

If you've ever spent time debugging node-gyp, you'll understand why this feels like a superpower. 🦀🔨

Starting with FFI in Rust? bindgen + pkg_config in build.rs is the canonical approach. Check the bindgen user guide — it covers every edge case from incomplete types to blocked functions.

Building SDR tools? Connect with me on LinkedIn — I've linked more C SDR libraries in Rust than I care to admit.

Want to see the actual code? GitHub — the RTL-SDR projects show build.rs in action.

The compile step is programmable. Use that. 🦀⚡

← Back to all posts