In Cargo, what does links = "tinyz" in the tinyz-sys package enforce, and how does a dependent's build script receive DEP_TINYZ_INCLUDE from it?
answer
- one owner per native library
- a build script is mandatory
- metadata keyed by the links name
- direct dependents only
- the -sys naming convention
basics
~20 slinks = "tinyz" declares that the package links the native library tinyz: it must have a build script, and only one package in the graph may claim that name. Its script's cargo::metadata=include=... reaches direct dependents' build scripts as DEP_TINYZ_INCLUDE.
solid answer
~50 sThe `links` key in `[package]` tells Cargo which native library a package links. Cargo enforces two things: the package must have a build script (otherwise the manifest fails to parse with ``package specifies that it links to `tinyz` but does not have a custom build script``), and at most one package in the dependency graph may use that `links` value, so the library is linked once. If one crate needs `tinyz-sys` 0.1 and another needs 0.2, resolution fails with ``links to the native library `tinyz`, but it conflicts with a previous package``. In return, the script may print `cargo::metadata=KEY=VALUE`; Cargo passes it to the build scripts of packages that depend on `tinyz-sys` **directly**, as `DEP_<LINKS>_<KEY>` with both parts uppercased: `cargo::metadata=include=/path` becomes `DEP_TINYZ_INCLUDE=/path`. A crate further down does not see it, and on stable Cargo a package without `links` cannot pass metadata at all.
code
rust · 9 lines// tinyz-sys/build.rs (its Cargo.toml has links = "tinyz")
use std::env;
fn main() {
let dir = env::var("CARGO_MANIFEST_DIR").unwrap();
// Becomes DEP_TINYZ_INCLUDE in the build scripts of direct dependents.
println!("cargo::metadata=include={dir}/include");
println!("cargo::rerun-if-changed=build.rs");
}go deeper
Recall that links names the native library a package links and that such a package needs a build script.
Explain the one-package-per-links rule, the DEP_<LINKS>_<KEY> naming, and why the -sys convention exists.
Untangle a links conflict between two incompatible -sys versions by unifying the graph, and wire metadata such as include paths between build scripts.
Plan semver-incompatible releases of a widely used -sys crate carefully, since links forces every dependent onto the new version together.
## What links declares Native libraries such as zlib, OpenSSL or a bundled C compressor live outside Cargo's world of crates, yet two crates that each link their own copy can end in duplicate symbols or two incompatible versions in one binary. The `links` key gives Cargo enough knowledge to prevent that: ```toml [package] name = "tinyz-sys" version = "0.2.0" edition = "2024" links = "tinyz" ``` This says the package links the native library `tinyz` (`libtinyz`). Cargo attaches two rules and one capability to it: - the package **must have a build script**, which is expected to print the `cargo::rustc-link-lib` line that actually links the library; - **at most one package per `links` value** may appear in the dependency graph; - the build script may publish **metadata** to its dependents. `CARGO_MANIFEST_LINKS` gives the script its own `links` value. ## One package per links value Cargo's resolver treats `links` as a constraint. Two semver-compatible requirements on `tinyz-sys` unify to one version as usual, but two incompatible ones, such as `0.1` through an old codec crate and `0.2` directly, would normally produce two copies of the crate. With `links` that is forbidden, and Cargo 1.99 stops with: ```plaintext package `tinyz-sys` links to the native library `tinyz`, but it conflicts with a previous package which links to `tinyz` as well: ``` followed by the note that only one package in the graph may specify the same links value. The fix is in the dependency graph: move both users to one `tinyz-sys` line. This is also why the Cargo reference urges care before a semver-incompatible release of a widely used crate with `links`: every user must move at once. How duplicate majors of ordinary crates coexist is the subject of Cargo's resolver material. ## Passing metadata to dependents The metadata channel lets a `-sys` crate tell other build scripts what it found or built. The steps: 1. `tinyz-sys`'s build script prints `cargo::metadata=include=/path/to/tinyz/include`. 2. Cargo records the pair under the package's `links` value. 3. When Cargo runs the build script of a package that depends **directly** on `tinyz-sys`, it sets `DEP_TINYZ_INCLUDE=/path/to/tinyz/include` in that script's environment. 4. That script reads it with `std::env::var` and, for instance, passes it to `cc::Build::include` so its own C code finds `tinyz.h`. The naming rule takes the **`links` value**, not the package name, and uppercases both it and the key. The rule has edges worth stating precisely: | Situation | Does the dependent's build script see `DEP_TINYZ_INCLUDE`? | |---|---| | depends on `tinyz-sys` directly | yes | | depends on a crate that depends on `tinyz-sys` | no; metadata reaches immediate dependents only | | `tinyz-sys` has no `links` key | no; stable Cargo passes metadata only from packages with `links` | | the dependent's crate code, via `env!` | no; the variables are set for build scripts | The `cargo::metadata=` form needs Cargo 1.77; older scripts print `cargo:include=...`, where any key Cargo does not recognise is taken as metadata. ## The -sys convention Crates that link a native library are conventionally named with a `-sys` suffix and kept thin: - the `-sys` crate links `libtinyz`, probing the system first or building bundled sources, and declares the raw functions and types; - a companion crate without the suffix offers the safe, idiomatic API on top; - every crate that needs the library depends on the one `-sys` crate, which satisfies the one-package-per-`links` rule and centralises discovery logic; - other `-sys` crates whose C code needs the library read its `DEP_` metadata, such as the include directory, instead of searching for the headers again; - the `-sys` crate is the single place to override, through configuration or an environment switch that selects the system copy over the bundled one. The convention is a naming habit, not something Cargo checks; `links` is what Cargo enforces. ## Overriding a links build script Because Cargo knows which package owns `tinyz`, a configuration file can replace that build script altogether. A `[target.<triple>.tinyz]` table in a Cargo config file supplies `rustc-link-lib`, `rustc-link-search` and metadata keys directly; Cargo then neither compiles nor runs the script and uses those values instead. That is a way to point builds at a prebuilt copy of the library instead of building or probing for it. How config files are found and merged is part of the material on Cargo configuration.
- Why is the variable called DEP_TINYZ_INCLUDE and not DEP_TINYZ_SYS_INCLUDE?Cargo builds the name from the `links` value, not the package name: `DEP_` plus the uppercased `links` value, an underscore, and the uppercased key. `links = "tinyz"` with `cargo::metadata=include=...` therefore gives `DEP_TINYZ_INCLUDE`, whatever the package is called.
- How can a team skip a -sys crate's build script and use a prebuilt library?Because the package declares `links = "tinyz"`, a Cargo config file can carry a `[target.<triple>.tinyz]` table with `rustc-link-lib`, `rustc-link-search` and metadata keys. Cargo then does not compile or run that build script and uses those values, including the metadata dependents read.
- links = "tinyz" by itself makes Cargo link libtinyz into the crate.
- Two semver-incompatible versions of a links crate coexist like any duplicates.
- DEP_ metadata is visible to every package further down the graph.
- The variable name comes from the package name, so DEP_TINYZ_SYS_INCLUDE.
- Cargo requires a package with links to be named with a -sys suffix.
Assumes Cargo 1.99; the cargo::metadata= form needs Cargo 1.77, and older scripts write cargo:KEY=VALUE.