skip to content

A Cargo crate builds its bundled C compression code with the cc crate; why does editing csrc/tinyz.c not rebuild it, and how do you fix that?

level: seniorimportance: should knowfreq 22%

answer

  1. the helper prints lines too
  2. rerun-if-env-changed for CC and CFLAGS
  3. any rerun-if line ends the scan
  4. cc never names the C files
  5. list sources and headers yourself

basics

~20 s

cc prints cargo:rerun-if-env-changed lines for CC, CFLAGS and similar variables, and any rerun-if line switches off Cargo's whole-package scan. cc does not list the C sources, so the build script must print cargo::rerun-if-changed for each C file and header.

solid answer

~40 s

`cc::Build::new().file("csrc/tinyz.c").compile("tinyz")` does a lot for the build script: it picks a C compiler and flags for `TARGET`, follows the profile's `OPT_LEVEL` and `DEBUG`, archives `libtinyz.a` in `OUT_DIR`, and prints `cargo:rustc-link-lib=static=tinyz` and `cargo:rustc-link-search=native=<OUT_DIR>`. It also prints `cargo:rerun-if-env-changed=` lines for every variable it consults (`CC`, `CFLAGS`, `AR` and others). Those are rerun-if instructions, and the first one replaces Cargo's default of rerunning the script whenever a package file changes. Nothing lists `csrc/tinyz.c`, so `cargo build -v` reports the package `Fresh` and the old object code stays linked. The fix is to print `cargo::rerun-if-changed=csrc/tinyz.c` and `cargo::rerun-if-changed=csrc/tinyz.h` (or the whole `csrc` directory); then `cargo build -v` shows ``Dirty ... the file `csrc/tinyz.c` has changed`` and the C code is recompiled.

code

toml · 7 lines
toml
[package]
name = "tinyz"
version = "0.1.0"
edition = "2024"

[build-dependencies]
cc = "1.10"

go deeper

for a junior

Recall that cc compiles C files from build.rs and prints the link directives, and that it is a build dependency.

for a middle

Explain which lines cc prints, where libtinyz.a lands, and why the first rerun-if line turns off the default package scan.

for a senior

Diagnose stale C code from a Fresh package in cargo build -v, fix it by listing sources and headers, and check the saved output to see what Cargo watches.

for a principal

Make listing every native input part of review for crates that bundle C, since the failure hides on clean CI builds and bites developers incrementally.

## What the cc crate does for a build script `cc` is the common **build dependency** for compiling C, C++ or assembly inside a Cargo package. A crate that bundles a small C compression library, here `tinyz` with `csrc/tinyz.c` and `csrc/tinyz.h`, declares it under `[build-dependencies]` and calls it from `build.rs`. One call chain replaces a hand-written compiler invocation: - it chooses the right compiler for the **target** (`cc` on Unix-like hosts, MSVC's tools on Windows MSVC targets) and passes the target's flags, so cross-compiling works; - it reads the profile's `OPT_LEVEL` and `DEBUG` so the C code is optimised like the Rust code; - it compiles each file into `OUT_DIR` and archives the objects into `libtinyz.a` there; - it prints the **link directives** Cargo needs, so the script does not have to. How the Rust side declares and calls `tz_adler32` belongs to the material on FFI; Cargo's part is getting the archive built and onto the link line. ## The lines cc prints After `compile("tinyz")`, the script's saved output in `target/debug/build/tinyz-<hash>/output` contains, among others: 1. `cargo:rerun-if-env-changed=` lines for each variable cc consults, such as `CC`, `CFLAGS`, `AR`, `CC_aarch64-apple-darwin` and, on macOS hosts, `SDKROOT` and `MACOSX_DEPLOYMENT_TARGET`; 2. `cargo:rustc-link-lib=static=tinyz`; 3. `cargo:rustc-link-search=native=` followed by the `OUT_DIR` path. cc 1.10 still uses the older single-colon prefix, which every Cargo release accepts. The lines without a `cargo:` prefix in that file, such as `CFLAGS = None`, are cc's own diagnostics, which Cargo ignores. ## Why the C edit is ignored The trap is a chain of three facts: 1. With no `rerun-if` instruction, Cargo reruns a build script whenever any file in the package changes, `csrc/tinyz.c` included. 2. Printing **any** `rerun-if` instruction replaces that default: Cargo then watches only the listed paths and variables. 3. cc prints `rerun-if-env-changed` lines but **no `rerun-if-changed` line for the files it compiles**. So the moment the script calls cc, Cargo watches environment variables and nothing else. Edit `csrc/tinyz.c`, run `cargo build -v`, and Cargo reports `Fresh tinyz v0.1.0`: the script does not run, the C file is not recompiled, and the old `libtinyz.a` is linked. A clean build hides the bug, because with no saved output Cargo always runs the script, which is why it tends to surface as "my C change has no effect until I run `cargo clean`". A CI job that builds from scratch never shows it, while developers building incrementally link stale object code. ## The fix List the C inputs explicitly, before or after the cc call: - one `cargo::rerun-if-changed=` line per source file **and** per header, since a header edit changes the object code too; - or one line for the directory, `cargo::rerun-if-changed=csrc`, which Cargo scans recursively, at the cost of rerunning for unrelated files placed there. With the lines in place, editing the header makes `cargo build -v` print ``Dirty tinyz v0.1.0 (...): the file `csrc/tinyz.h` has changed``, run the script, and recompile. Changing `CFLAGS` reruns it as well, through cc's own lines. ## Related cc and Cargo behaviour | Situation | What happens | |---|---| | package has a library and binaries | the `-l static=tinyz` goes to the library target only; binaries reach the C code through the library's public API | | `cc::Build::cargo_metadata(false)` | cc prints no link or rerun lines, so the script must print `rustc-link-lib` and `rustc-link-search` itself | | `emit_rerun_if_env_changed(false)` | cc still printed `cargo:rerun-if-env-changed=CC_ENABLE_DEBUG_OUTPUT` in a run with cc 1.10, so the package scan stayed off | | the C code needs a system zlib or OpenSSL | a `*-sys` crate or a probing crate finds it; cc compiles only the code you hand it | Two more habits keep such crates healthy: - Build scripts get one jobserver slot from Cargo, and cc's optional `parallel` feature uses the jobserver protocol to compile several C files at once without oversubscribing the machine. - For a library with many C files, keep one list of paths, hand it to `cc::Build::files`, and print a `cargo::rerun-if-changed` line for each entry in the same loop, so the compiled set and the watched set cannot drift apart. - Run `cargo build -vv` once after adding cc to read every line it printed; it is the quickest way to see which inputs Cargo is actually watching.

  • Why does the C code still get compiled on a clean build, if Cargo is not watching csrc/tinyz.c?
    Rerun rules apply only when a previous run's output exists. On a clean build, or after `cargo clean`, there is nothing to reuse, so Cargo always runs the script and cc compiles every file. The bug appears only on incremental builds.
  • A package has src/lib.rs and src/main.rs, and the binary calls tz_adler32 through its own extern block without using the library. Why does linking fail?
    Cargo passes the `-l static=tinyz` from `rustc-link-lib` only to the library target when one exists, so the archive's symbols are linked into the library. The binary should call the library's safe Rust wrapper instead of declaring the C function itself.
  • Can you rely on cc to rerun the build when the compiler is upgraded?
    No. cc watches variables such as `CC` and `CFLAGS`, but its own documentation says it has no reliable way to detect a changed compiler and leaves that to the build script author, for example by listing a toolchain file or variable they control.

  • cc tells Cargo to watch every C file it compiles.
  • Adding cc only adds rerun triggers; the default package scan stays on.
  • Old C code after an edit means the cc crate is caching objects wrongly.
  • You must still print rustc-link-lib yourself after calling compile.
  • cc belongs in [dependencies] because the crate links its output.