Build script links

2023-11-15

You have an “upstream” crate that wraps a C library and provides Rust bindings for it. You also have a “downstream” crate that wraps a different C library. The downstream C library depends on the upstream C library — for example, to compile the downstream C code, you need access to the header files of the upstream C code.

The problem: How do you tell the compiler where to find the upstream crate's header files when compiling the downstream library?

The answer: the ‘package.links’ field and “build script metadata”. The upstream library needs to set ‘package.links’ in its ‘Cargo.toml’. You can choose any value (which I'll call ‘LINK_NAME’), but convention is that it's the name of the library that the Rust crate is providing bindings for. In the upstream library's ‘build.rs’, you output additional cargo metadata:

cargo:VAR_NAME=VALUE

Then, in your downstream library, this custom metadata will be available in an environment variable that you can read: ‘DEP_${LINK_NAME}_${VAR_NAME}’.

For this compilation example, you output a carefully named ‘include’ metadata variable, whose value is the actual location of the upstream header files. In your downstream ‘build.rs’, you read the ‘DEP_${LINK_NAME}_INCLUDE’ env var, and add that to the compiler's include search path.

The ‘links’ manifest key [The Cargo book]