Build Scripts: Code Generation and Native Linking with `build.rs`

19 min read

A build script (build.rs) is Rust code that Cargo compiles and runs before it builds your crate. It is the closest thing Rust has to a prebuild/postinstall npm hook or a node-gyp step — but it is plain Rust, it talks to Cargo over stdout, and it is sandboxed to a private output directory.

Quick Overview

In the Node.js world, anything you need to happen before your code runs — generating files, compiling a native addon, downloading a binary — lives in a scripts hook (prebuild, postinstall) or a tool like node-gyp. Rust folds all of that into a single optional file named build.rs at the crate root: Cargo compiles it, runs it once per build, and listens to special cargo:: lines it prints to decide what to compile, what native libraries to link, and when to re-run. This page focuses on the three jobs build scripts do most: generating Rust source code, compiling and linking native (C/C++) libraries, and controlling re-runs with cargo::rerun-if-* directives.

Note: A build script is not a place to run your app’s logic. It runs at compile time on the build machine, not at runtime. Think tsc plugin or node-gyp, not node index.js.

TypeScript/JavaScript Example

In a Node project, build-time work is wired through package.json lifecycle scripts and sometimes a helper script that generates code:

1
{
2
  "name": "status-lib",
3
  "version": "1.0.0",
4
  "type": "module",
5
  "scripts": {
6
    "generate": "node scripts/generate-status.mjs",
7
    "prebuild": "npm run generate",
8
    "build": "tsc"
9
  },
10
  "devDependencies": {
11
    "typescript": "^5.5.0"
12
  }
13
}

1
// scripts/generate-status.mjs — run before `tsc` to emit a TS file from data
2
import { readFile, writeFile } from "node:fs/promises";
3

4
const raw = await readFile(new URL("../status_codes.json", import.meta.url), "utf8");
5
const map = JSON.parse(raw);
6

7
let out = "// AUTO-GENERATED — do not edit\n";
8
out += "export function reasonPhrase(code: number): string | undefined {\n";
9
out += "  switch (code) {\n";
10
for (const [code, reason] of Object.entries(map)) {
11
  out += `    case ${code}: return ${JSON.stringify(reason)};\n`;
12
}
13
out += "    default: return undefined;\n  }\n}\n";
14

15
await writeFile(new URL("../src/status.generated.ts", import.meta.url), out);

This works, but notice the friction: the script writes into your source tree (src/status.generated.ts), you must remember to .gitignore it, and prebuild runs every single time regardless of whether the input changed. For native addons you would reach for an entirely separate toolchain (node-gyp + a binding.gyp file).

Rust Equivalent

The same code-generation task as a Cargo build script. The generated file goes into a Cargo-managed scratch directory (OUT_DIR), never your source tree:

1
[package]
2
name = "status-lib"
3
version = "1.0.0"
4
edition = "2024"
5

6
[build-dependencies]
7
serde_json = "1"

1
// build.rs — Cargo compiles and runs this before building the crate
2
use std::collections::BTreeMap;
3
use std::env;
4
use std::fmt::Write as _;
5
use std::fs;
6
use std::path::Path;
7

8
fn main() {
9
    // Cargo hands every build script a private scratch directory via OUT_DIR.
10
    let out_dir = env::var("OUT_DIR").unwrap();
11
    let dest = Path::new(&out_dir).join("status.rs");
12

13
    let raw = fs::read_to_string("status_codes.json").expect("status_codes.json");
14
    let map: BTreeMap<u16, String> =
15
        serde_json::from_str(&raw).expect("valid JSON object of code->reason");
16

17
    // Build a `match`-based lookup function as a String of Rust source.
18
    let mut code = String::from(
19
        "pub fn reason_phrase(code: u16) -> Option<&'static str> {\n    match code {\n",
20
    );
21
    for (status, reason) in &map {
22
        // {reason:?} prints the &str with quotes + escaping — valid Rust literal.
23
        writeln!(code, "        {status} => Some({reason:?}),").unwrap();
24
    }
25
    code.push_str("        _ => None,\n    }\n}\n");
26
    fs::write(&dest, code).unwrap();
27

28
    // Re-run ONLY when these inputs change (see the directives section below).
29
    println!("cargo::rerun-if-changed=status_codes.json");
30
    println!("cargo::rerun-if-changed=build.rs");
31
}

1
// src/lib.rs — pull the generated file in at compile time
2
include!(concat!(env!("OUT_DIR"), "/status.rs"));
3

4
#[cfg(test)]
5
mod tests {
6
    #[test]
7
    fn known_code() {
8
        assert_eq!(super::reason_phrase(404), Some("Not Found"));
9
    }
10
}

Running cargo build produces (real output from a cargo run driver of this exact code):

1
   Compiling status-lib v1.0.0 (/private/tmp/.../status-lib)
2
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.03s
3
200 => Some("OK")
4
404 => Some("Not Found")
5
418 => None

The generated status.rs lives under target/, so it is gitignored automatically and never pollutes your source tree.

Detailed Explanation

A build script is convention over configuration: if a file named build.rs exists at the crate root, Cargo automatically compiles it as a separate tiny binary and runs it before compiling your crate. There is no manifest entry to add (though you can point at a different file with build = "path/to/build.rs" under [package]).

Walking through the moving parts:

[build-dependencies] is a separate dependency table just for the build script. Crates listed here are compiled for the host (build) machine and are not linked into your final binary. serde_json here is used only during the build. This is distinct from [dependencies] and [dev-dependencies] — see Dev & Build Dependencies.
OUT_DIR is an environment variable Cargo sets for the build script, pointing at a unique per-crate directory like target/debug/build/status-lib-<hash>/out. You write generated files there, never into src/. The unwrap() is safe because Cargo always sets it.
Communication is via stdout. The build script does not return data through a function. Instead it prints lines beginning with cargo:: (note the double colon — the modern syntax). Cargo parses those lines and acts on them. Lines that do not start with cargo:: are treated as ordinary log output.
include!(concat!(env!("OUT_DIR"), "/status.rs")) is the bridge back into your crate. Here env! is a compile-time macro (it reads the env var while rustc runs, not at program startup), concat! builds the path literal, and include! textually pastes the generated tokens into your module — exactly as if you had typed them. This is the standard pattern for consuming generated code.
{reason:?} in the writeln! uses Rust’s Debug formatting for &str, which emits a properly quoted and escaped string literal. Generating source as text means you must produce syntactically valid Rust; Debug formatting of strings does the escaping for you.

Contrast with the Node version: there is no prebuild hook to wire up, the output never touches your source tree, and — crucially — the cargo::rerun-if-changed lines let Cargo skip the script entirely when nothing relevant changed. The Node prebuild runs unconditionally.

Tip: The build script is just Rust. You can unit-test the generation logic by factoring it into a function, and you get the full standard library plus any [build-dependencies].

Compiling and Linking Native Libraries

The second major job of build scripts is building and linking C/C++ code — Rust’s answer to node-gyp. The community standard is the cc crate, which locates a C compiler, compiles your sources into a static library, and emits the correct link directives automatically.

1
[package]
2
name = "native_math"
3
version = "0.1.0"
4
edition = "2024"
5

6
[build-dependencies]
7
cc = "1.2"

1
/* csrc/checksum.c — a small Fletcher-16 checksum in C */
2
#include <stddef.h>
3
#include <stdint.h>
4

5
uint16_t fletcher16(const uint8_t *data, size_t len) {
6
    uint16_t sum1 = 0, sum2 = 0;
7
    for (size_t i = 0; i < len; i++) {
8
        sum1 = (sum1 + data[i]) % 255;
9
        sum2 = (sum2 + sum1) % 255;
10
    }
11
    return (sum2 << 8) | sum1;
12
}

1
fn main() {
2
    // cc finds a C compiler, builds the source into a static lib, AND emits
3
    // the cargo::rustc-link-* directives for you. No manual linking needed.
4
    cc::Build::new()
5
        .file("csrc/checksum.c")
6
        .compile("checksum");
7

8
    // Recompile the C only when the C source changes.
9
    println!("cargo::rerun-if-changed=csrc/checksum.c");
10
}

1
// src/main.rs — call the C function through an FFI declaration
2
// In edition 2024, `extern` blocks MUST be marked `unsafe`.
3
unsafe extern "C" {
4
    fn fletcher16(data: *const u8, len: usize) -> u16;
5
}
6

7
fn checksum(bytes: &[u8]) -> u16 {
8
    // SAFETY: we pass a valid pointer + matching length from a live slice.
9
    unsafe { fletcher16(bytes.as_ptr(), bytes.len()) }
10
}
11

12
fn main() {
13
    let sum = checksum(b"abcde");
14
    println!("fletcher16(\"abcde\") = {sum:#06x}");
15
}

Real output from cargo run:

1
   Compiling cc v1.2.63
2
   Compiling native_math v0.1.0 (/private/tmp/.../native_math)
3
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.11s
4
     Running `target/debug/native_math`
5
fletcher16("abcde") = 0xc8f0

Under cargo build -vv (very verbose) you can see the directives cc emits on the build script’s behalf — these are the real lines from this build:

1
[native_math 0.1.0] cargo:rustc-link-lib=static=checksum
2
[native_math 0.1.0] cargo:rustc-link-search=native=.../build/native_math-<hash>/out

If you are linking against a pre-installed system library rather than compiling your own C, you skip cc and print the directives yourself:

1
// build.rs — link against a system-installed library (e.g. libz)
2
fn main() {
3
    // Tell the linker to link `libz` dynamically.
4
    println!("cargo::rustc-link-lib=dylib=z");
5
    // Add a directory to the linker's search path if it is non-standard.
6
    println!("cargo::rustc-link-search=native=/usr/local/lib");
7
}

Note: FFI, unsafe, and raw pointers are a large topic in their own right — covered in depth in section 20 — Unsafe & FFI. The build-script side is just the link wiring; this page stays in that lane.

The `cargo::rerun-if-*` Directives

By default, a build script re-runs whenever any file in the package changes. That is rarely what you want — it makes builds slower and can re-run expensive code generation needlessly. The moment you print any cargo::rerun-if-* line, you switch off the default and take explicit control: Cargo re-runs the script only if one of the conditions you listed is met.

Directive	Re-run when…	TS/JS analogy
`cargo::rerun-if-changed=PATH`	the file or directory at `PATH` changes	a watched input in a `chokidar` glob
`cargo::rerun-if-env-changed=VAR`	the value of env var `VAR` differs from the last build	reading `process.env.X` and reacting to it

1
// build.rs — explicit, minimal re-run triggers
2
use std::env;
3

4
fn main() {
5
    // Read configuration from the environment, with a default.
6
    let api_base = env::var("API_BASE_URL")
7
        .unwrap_or_else(|_| "https://api.example.com".to_string());
8

9
    // Expose it to the crate as a compile-time env var read with env!().
10
    println!("cargo::rustc-env=API_BASE_URL={api_base}");
11

12
    // Re-run if the env var changes between builds...
13
    println!("cargo::rerun-if-env-changed=API_BASE_URL");
14
    // ...and if the build script itself changes.
15
    println!("cargo::rerun-if-changed=build.rs");
16
}

1
fn main() {
2
    println!("API base: {}", env!("API_BASE_URL"));
3
}

Real output across two builds:

1
--- default ---
2
API base: https://api.example.com
3
--- overridden ---
4
API base: https://staging.internal

Warning: Once you print one rerun-if-changed, the blanket “re-run on any file change” behavior is disabled. If your script reads three input files, you must list all three rerun-if-changed lines, or edits to the unlisted files will be silently ignored until something else triggers a rebuild.

Two more directives round out the common set:

cargo::rustc-env=KEY=VALUE — sets an env var that your crate reads with the env!("KEY") macro at compile time. This is the cleanest way to embed small values like a git hash or build timestamp without writing a file.
cargo::warning=MESSAGE — surfaces a warning in the build output, useful for nudging users about missing optional tooling.

1
// build.rs — embed the git commit hash, no file generation needed
2
use std::process::Command;
3

4
fn main() {
5
    let git_hash = Command::new("git")
6
        .args(["rev-parse", "--short", "HEAD"])
7
        .output()
8
        .ok()
9
        .filter(|out| out.status.success())
10
        .map(|out| String::from_utf8_lossy(&out.stdout).trim().to_string())
11
        .unwrap_or_else(|| "unknown".to_string());
12

13
    println!("cargo::rustc-env=GIT_HASH={git_hash}");
14
    println!("cargo::rerun-if-changed=.git/HEAD"); // re-run when HEAD moves
15
}

1
fn main() {
2
    println!("version {} (commit {})",
3
        env!("CARGO_PKG_VERSION"), // Cargo sets this one for you
4
        env!("GIT_HASH"));         // we set this one in build.rs
5
}

Real output: version 0.1.0 (commit c530f7d).

Key Differences

Concept	Node.js / TypeScript	Rust (`build.rs`)
Where build logic lives	`scripts` in `package.json` + helper `.mjs` files	a single `build.rs` at the crate root (auto-detected)
Language	JavaScript / shell	plain Rust, with `[build-dependencies]`
When it runs	on the lifecycle event (`prebuild`, `postinstall`)	once before each crate build, if re-run conditions are met
Incremental skipping	none built in (runs every time)	`cargo::rerun-if-*` lets Cargo skip it
Output location	wherever your script writes (often into `src/`)	the Cargo-managed `OUT_DIR` under `target/`
Native addons	`node-gyp` + `binding.gyp` (separate toolchain)	the `cc` crate (or your own link directives)
Talking to the build tool	exit code / writing files	printing `cargo::...` lines to `stdout`
Consuming generated code	`import` the emitted file	`include!(concat!(env!("OUT_DIR"), "/file.rs"))`

The deepest difference is integration. In Node, prebuild is a string of shell that npm runs blindly; it has no idea what your script reads or produces, so it cannot skip work. Cargo’s build script is a first-class citizen: it declares its inputs (rerun-if-changed), its outputs go to a directory Cargo owns and cleans, and its effect on the real compile (link flags, cfg flags, env vars) is communicated through a typed protocol. The build graph stays correct and incremental.

Note: The directive syntax changed from a single colon (cargo:rustc-env=...) to a double colon (cargo::rustc-env=...) when the new form stabilized in Rust 1.77. The single-colon form still works for backward compatibility, but prefer the double colon in new code, and use it consistently — this guide targets the latest stable Rust (1.96.0) and the 2024 edition.

Common Pitfalls

Pitfall 1: Writing generated files into `src/`

Coming from the Node prebuild habit of writing src/status.generated.ts, it is tempting to write generated Rust into your source tree. Don’t. Always write to OUT_DIR. Files in src/ get committed, fight with formatting/linting, and break reproducible builds. Files in OUT_DIR live under target/, are gitignored by default, and are regenerated cleanly.

Pitfall 2: Forgetting that one `rerun-if-changed` disables the blanket re-run

If your script reads data/a.csv and data/b.csv but only prints cargo::rerun-if-changed=data/a.csv, then editing b.csv will not trigger a rebuild. List every input, or point at the directory: cargo::rerun-if-changed=data.

Pitfall 3: Mistyping a directive key

Cargo validates cargo:: keys. A typo produces a hard error, not a silent no-op. This is the real message for an unknown key:

1
fn main() {
2
    println!("cargo::rerun-if-changed=build.rs");
3
    println!("cargo::totally-made-up-key=oops"); // does not compile/build
4
}

1
error: invalid output in build script of `buildgen v0.1.0 (...)`: `cargo::totally-made-up-key=oops`
2
Unknown key: `totally-made-up-key`.
3
See https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script for more information about build script outputs.

Pitfall 4: Forgetting `unsafe` on `extern` blocks in edition 2024

In the 2024 edition, FFI declaration blocks must be marked unsafe extern "C". Writing a plain extern "C" block is a compile error. This is the real rustc message:

1
// does not compile in edition 2024 — needs `unsafe extern "C"`
2
extern "C" {
3
    fn fletcher16(data: *const u8, len: usize) -> u16;
4
}

1
error: extern blocks must be unsafe
2
 --> src/main.rs:1:1
3
  |
4
1 | / extern "C" {
5
2 | |     fn fletcher16(data: *const u8, len: usize) -> u16;
6
3 | | }
7
  | |_^

The fix is to write unsafe extern "C" { ... }. Note that declaring the block unsafe is separate from the unsafe { ... } block you still need at each call site.

Pitfall 5: Expecting `build.rs` to run at program runtime

A build script runs at compile time on the build machine. It cannot read your end user’s environment, cannot make runtime network calls for your app, and its println! output is build-log noise, not your program’s output. If you need runtime behavior, that belongs in src/, not build.rs.

Best Practices

Reach for a crate before hand-rolling. Use cc for C/C++, bindgen for generating Rust FFI bindings from C headers, pkg-config for discovering system libraries, and prost-build/tonic-build for Protocol Buffers. They emit the correct directives for you and handle cross-platform quirks.
Always write to OUT_DIR. Never generate into src/.
Be specific about re-runs. List exactly the files and env vars your script depends on with cargo::rerun-if-changed / cargo::rerun-if-env-changed. This keeps incremental builds fast and correct.
Prefer cargo::rustc-env over file generation for scalar values. A git hash or build timestamp does not need a generated .rs file; one rustc-env line plus env!() is cleaner.
Keep build scripts cheap and deterministic. They run on every fresh build and on CI. Avoid slow network calls; if you must fetch, cache into OUT_DIR and guard with re-run directives.
Add only build-time crates to [build-dependencies]. They are compiled for the host and excluded from your final binary — keep your runtime dependency tree lean.
Emit a friendly cargo::warning when an optional native dependency is missing, so users get a clear message instead of a cryptic linker error.

Tip: Reserve build scripts for things that genuinely must happen at build time. If a problem can be solved with a regular function, a const, a feature flag, or a procedural macro (see 14 — Macros), prefer that — build scripts add a compile step and a maintenance surface.

Real-World Example

A common production need: turn a checked-in data file into a fast, allocation-free, compile-time lookup table. Here we generate a match-based function from a CSV of color names — no runtime parsing, no HashMap allocation, and a hard compile error if the data file is malformed.

1
[package]
2
name = "color_codes"
3
version = "0.1.0"
4
edition = "2024"
5
# No [build-dependencies] needed — std is enough for CSV this simple.

1
# colors.csv (checked into the repo)
2
red,#ff0000
3
green,#00ff00
4
blue,#0000ff
5
slate,#708090

1
use std::env;
2
use std::fmt::Write as _;
3
use std::fs;
4
use std::path::Path;
5

6
fn main() {
7
    let out_dir = env::var("OUT_DIR").unwrap();
8
    let dest = Path::new(&out_dir).join("colors.rs");
9

10
    let csv = fs::read_to_string("colors.csv").expect("colors.csv must exist");
11

12
    // Generate a `match`-based lookup function from the rows.
13
    let mut code = String::from(
14
        "/// Look up a hex code for a named color (generated from colors.csv).\n\
15
         pub fn hex_for(name: &str) -> Option<&'static str> {\n    match name {\n",
16
    );
17
    for line in csv.lines().filter(|l| !l.trim().is_empty()) {
18
        let (name, hex) = line.split_once(',').expect("each row is name,hex");
19
        writeln!(
20
            code,
21
            "        {name:?} => Some({hex:?}),",
22
            name = name.trim(),
23
            hex = hex.trim()
24
        )
25
        .unwrap();
26
    }
27
    code.push_str("        _ => None,\n    }\n}\n");
28
    fs::write(&dest, code).unwrap();
29

30
    // Regenerate only when the data or the generator changes.
31
    println!("cargo::rerun-if-changed=colors.csv");
32
    println!("cargo::rerun-if-changed=build.rs");
33
}

1
include!(concat!(env!("OUT_DIR"), "/colors.rs"));
2

3
fn main() {
4
    for name in ["slate", "blue", "chartreuse"] {
5
        match hex_for(name) {
6
            Some(hex) => println!("{name:>10} -> {hex}"),
7
            None => println!("{name:>10} -> (unknown)"),
8
        }
9
    }
10
}

Real output from cargo run:

1
   Compiling color_codes v0.1.0 (/private/tmp/.../color_codes)
2
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.69s
3
     Running `target/debug/color_codes`
4
     slate -> #708090
5
      blue -> #0000ff
6
chartreuse -> (unknown)

The payoff over a runtime approach: the lookup compiles to a jump table, there is zero startup cost, and a malformed colors.csv fails the build (via the expect panics in build.rs) rather than crashing at runtime. Edit colors.csv and cargo build regenerates and recompiles automatically; edit an unrelated file and the script is skipped.

Exercises

Exercise 1: Embed a build timestamp

Difficulty: Easy

Objective: Use a build script to bake the build’s Unix timestamp into the binary, with no generated file.

Instructions:

Create a binary crate.
In build.rs, compute the current time as seconds since the Unix epoch.
Expose it to the crate via cargo::rustc-env=BUILD_UNIX_TIME=....
In main, print it using the env! macro.

Solution

1
use std::time::{SystemTime, UNIX_EPOCH};
2

3
fn main() {
4
    let secs = SystemTime::now()
5
        .duration_since(UNIX_EPOCH)
6
        .unwrap()
7
        .as_secs();
8
    println!("cargo::rustc-env=BUILD_UNIX_TIME={secs}");
9
    println!("cargo::rerun-if-changed=build.rs");
10
}

1
fn main() {
2
    println!("built at unix time {}", env!("BUILD_UNIX_TIME"));
3
}

Real output: built at unix time 1780203193.

Exercise 2: Configurable API base URL with re-run control

Difficulty: Medium

Objective: Read an environment variable in build.rs, fall back to a default, and make Cargo re-run the script when that variable changes.

Instructions:

In build.rs, read API_BASE_URL from the environment, defaulting to https://api.example.com.
Expose it via cargo::rustc-env.
Print cargo::rerun-if-env-changed=API_BASE_URL so changing it triggers a rebuild.
Verify that cargo run uses the default and API_BASE_URL=... cargo run uses the override.

Solution

1
use std::env;
2

3
fn main() {
4
    let api_base = env::var("API_BASE_URL")
5
        .unwrap_or_else(|_| "https://api.example.com".to_string());
6
    println!("cargo::rustc-env=API_BASE_URL={api_base}");
7
    println!("cargo::rerun-if-env-changed=API_BASE_URL");
8
    println!("cargo::rerun-if-changed=build.rs");
9
}

1
fn main() {
2
    println!("API base: {}", env!("API_BASE_URL"));
3
}

Real output:

1
--- default ---
2
API base: https://api.example.com
3
--- overridden ---
4
API base: https://staging.internal

Exercise 3: Generate a lookup table from a JSON data file

Difficulty: Hard

Objective: Use a [build-dependencies] crate (serde_json) to parse a JSON file and generate a match-based lookup function written into OUT_DIR.

Instructions:

Add serde_json to [build-dependencies] with cargo add --build serde_json.
Create status_codes.json mapping HTTP codes (as string keys) to reason phrases.
In build.rs, parse it into a BTreeMap<u16, String>, generate fn reason_phrase(code: u16) -> Option<&'static str>, and write it to OUT_DIR/status.rs.
include! the generated file and look up a few codes (including one not in the file).
Add cargo::rerun-if-changed for both the JSON and build.rs.

Solution

1
[build-dependencies]
2
serde_json = "1"

1
use std::collections::BTreeMap;
2
use std::env;
3
use std::fmt::Write as _;
4
use std::fs;
5
use std::path::Path;
6

7
fn main() {
8
    let out_dir = env::var("OUT_DIR").unwrap();
9
    let dest = Path::new(&out_dir).join("status.rs");
10

11
    let raw = fs::read_to_string("status_codes.json").expect("status_codes.json");
12
    let map: BTreeMap<u16, String> =
13
        serde_json::from_str(&raw).expect("valid JSON object of code->reason");
14

15
    let mut code = String::from(
16
        "pub fn reason_phrase(code: u16) -> Option<&'static str> {\n    match code {\n",
17
    );
18
    for (status, reason) in &map {
19
        writeln!(code, "        {status} => Some({reason:?}),").unwrap();
20
    }
21
    code.push_str("        _ => None,\n    }\n}\n");
22
    fs::write(&dest, code).unwrap();
23

24
    println!("cargo::rerun-if-changed=status_codes.json");
25
    println!("cargo::rerun-if-changed=build.rs");
26
}

1
{ "200": "OK", "404": "Not Found", "500": "Internal Server Error" }

1
include!(concat!(env!("OUT_DIR"), "/status.rs"));
2

3
fn main() {
4
    for code in [200u16, 404, 418] {
5
        println!("{code} => {:?}", reason_phrase(code));
6
    }
7
}

Real output:

1
200 => Some("OK")
2
404 => Some("Not Found")
3
418 => None

Build Scripts: Code Generation and Native Linking with build.rs

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Compiling and Linking Native Libraries

The cargo::rerun-if-* Directives

Key Differences

Common Pitfalls

Pitfall 1: Writing generated files into src/

Pitfall 2: Forgetting that one rerun-if-changed disables the blanket re-run

Pitfall 3: Mistyping a directive key

Pitfall 4: Forgetting unsafe on extern blocks in edition 2024

Pitfall 5: Expecting build.rs to run at program runtime

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Embed a build timestamp

Exercise 2: Configurable API base URL with re-run control

Exercise 3: Generate a lookup table from a JSON data file

Build Scripts: Code Generation and Native Linking with `build.rs`

The `cargo::rerun-if-*` Directives

Pitfall 1: Writing generated files into `src/`

Pitfall 2: Forgetting that one `rerun-if-changed` disables the blanket re-run

Pitfall 4: Forgetting `unsafe` on `extern` blocks in edition 2024

Pitfall 5: Expecting `build.rs` to run at program runtime