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?
answer
- the helper prints lines too
- rerun-if-env-changed for CC and CFLAGS
- any rerun-if line ends the scan
- cc never names the C files
- list sources and headers yourself
basics
~20 scc 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[package]
name = "tinyz"
version = "0.1.0"
edition = "2024"
[build-dependencies]
cc = "1.10"go deeper
Recall that cc compiles C files from build.rs and prints the link directives, and that it is a build dependency.
Explain which lines cc prints, where libtinyz.a lands, and why the first rerun-if line turns off the default package scan.
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.
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.