pkgconfig-dependencies

[domenkozar]

This PR explores a new unstable feature that allows developers to
declaratively specify system library dependencies in Cargo.toml, eliminating
the need for custom build scripts to probe pkg-config.

With pkgconfig-dependencies, you can declare system libraries just like
regular Rust dependencies, with support for version constraints, alternative
names, fallback specifications, feature gating, and link type control.

The Problem

Currently, using system libraries in Rust requires manual build.rs scripts:

fn main() {
    pkg_config::probe_library("openssl")
        .or_else(|_| { /* fallback */ })
        .unwrap();
}

This is repetitive boilerplate that every project needs to write and maintain.

pkgconfig-dependencies

Simply declare your system dependencies in Cargo.toml:

  [pkgconfig-dependencies]
  openssl = "1.1"
  sqlite3 = "3.0"

Enable the feature and build:

  $ cargo build -Z pkgconfig-dependencies

Cargo automatically probes pkg-config, generates metadata, and makes it
available to your code.

Usage

Simple Dependencies

Just specify version constraints:

  [pkgconfig-dependencies]
  openssl = "1.1"
  libcurl = "7.0"
  zlib = "1.2"

Advanced Configuration

For more control, use the detailed form:

[pkgconfig-dependencies.sqlite3]
version = "3.0"
names = ["sqlite3", "sqlite"]      # Try alternative pkg-config names
optional = true                     # Don't fail if not found
link = "static"                     # How to link (static/dynamic)
feature = "with-sqlite"             # Only required if feature enabled

[pkgconfig-dependencies.sqlite3.fallback]
libs = ["sqlite3"]
lib-paths = ["/usr/local/lib"]
include-paths = ["/usr/local/include"]

Feature-Gated Dependencies

Build with or without system libraries:

  [features]
  system-deps = []

  [pkgconfig-dependencies.openssl]
  version = "1.1"
  feature = "system-deps"

  $ cargo build                          # Uses bundled dependencies
  $ cargo build --features system-deps   # Uses system OpenSSL

Accessing Library Information

Cargo generates a Rust module with compile-time constants:

  include!(concat!(env!("OUT_DIR"), "/pkgconfig_meta.rs"));

  fn main() {
      if pkgconfig::openssl::FOUND {
          println!("OpenSSL {} found", pkgconfig::openssl::VERSION);
          for lib in pkgconfig::openssl::LIBS {
              println!("cargo:rustc-link-lib={}", lib);
          }
      }
  }

Example: Portable OpenSSL

  [package]
  name = "cryptolib"

  [features]
  default = ["vendored"]
  vendored = []
  system = []

  [pkgconfig-dependencies.openssl]
  version = "1.1"
  names = ["openssl", "libssl"]
  feature = "system"
  optional = true
  link = "dynamic"
  fallback = { lib-paths = ["/opt/openssl/lib"], include-paths =
  ["/opt/openssl/include"] }

Works everywhere:

• Default: Uses vendored OpenSSL
• Linux with pkg-config: cargo build --features system
• Custom install: Fallback paths handle non-standard locations
• macOS/Windows: Alternative names handle platform naming differences

Unstable Feature Flag

This feature is behind -Z pkgconfig-dependencies and requires nightly:

  cargo +nightly build -Z pkgconfig-dependencies

[rustbot]

r? @ehuss

rustbot has assigned @ehuss.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[bonzini]

Cargo generates a Rust module with compile-time constants:

If you still need to do work in build.rs, you might as well use system-deps. I just don't see the point.

I'm not sure this is great advertisement for Claude Code...

[ssokolow]

Cargo generates a Rust module with compile-time constants:

If you still need to do work in build.rs, you might as well use system-deps. I just don't see the point.

I think the idea is that, given how much functional overlap there would be between the code for the case which does need that and the code for the case without, it makes sense to not encourage staying in the direction of "this codebase contains both lazy-static and once-cell" as soon as one of the transitive dependencies needs a build.rs.

Better to have a single source of truth for interfacing with pkg-config but, at the same time, not force everyone to "subsidize" the subset of packages which will need build.rs either way by forcing the common-case uses with no intrinsic build.rs dependency to depend on system-deps.

EDIT: In essence, it's extending Cargo's existing "Most crates don't need build.rs" to interfacing with pkg-config. Right now, interfacing with system libraries is akin to using Makefile to orchestrate your build when 99% of projects don't need that power and flexibility, but all have to pay for it.

[bonzini]

EDIT: In essence, it's extending Cargo's existing "Most crates don't need build.rs" to interfacing with pkg-config. Right now, interfacing with system libraries is akin to using Makefile to orchestrate your build when 99% of projects don't need that power and flexibility, but all have to pay for it.

The way to go for that would be to stabilize metabuild and have system-deps support it. There's no need to have Cargo do it.

[ssokolow]

I I'm reading that correctly, having a metabuild() function wouldn't address the other issue of making the dependencies declarative in a way that's beneficial to higher-level build orchestration.

(eg. distro build tooling extracting dependencies without running third-party code to extend the cargo fetch/cargo build --offline split to the system dependencies.)