[][src]Crate system_deps

system-deps lets you write system dependencies in Cargo.toml metadata, rather than programmatically in build.rs. This makes those dependencies declarative, so other tools can read them as well.


In your Cargo.toml:

system-deps = "2.0"

Then, to declare a dependency on testlib >= 1.2 add the following section:

testlib = "1.2"

Finally, in your build.rs, add:

fn main() {

Optional dependency

You can easily declare an optional system dependency by associating it with a feature:

testdata = { version = "4.5", feature = "use-testdata" }

Overriding library name

toml keys cannot contain dot characters so if your library name does you can define it using the name field:

glib = { name = "glib-2.0", version = "2.64" }

Feature versions

-sys crates willing to support various versions of their underlying system libraries can use features to control the version of the dependency required. system-deps will pick the highest version among enabled features. Such version features must use the pattern v1_0, v1_2, etc.

v1_2 = []
v1_4 = ["v1_2"]
v1_6 = ["v1_4"]

name = "gstreamer-1.0"
version = "1.0"
v1_2 = { version = "1.2" }
v1_4 = { version = "1.4" }
v1_6 = { version = "1.6" }

The same mechanism can be used to require a different library name depending on the version:

name = "gstreamer-gl-1.0"
version = "1.14"
v1_18 = { version = "1.18", name = "gstreamer-gl-egl-1.0" }

Overriding build flags

By default system-deps automatically defines the required build flags for each dependency using the information fetched from pkg-config. These flags can be overriden using environment variables if needed:

With $NAME being the upper case name of the key defining the dependency in Cargo.toml. For example SYSTEM_DEPS_TESTLIB_SEARCH_NATIVE=/opt/lib could be used to override a dependency named testlib.

One can also define the environment variable SYSTEM_DEPS_$NAME_NO_PKG_CONFIG to fully disable pkg-config lookup for the given dependency. In this case at least SYSTEM_DEPS_$NAME_LIB or SYSTEM_DEPS_$NAME_LIB_FRAMEWORK should be defined as well.

Statically build system library

-sys crates can provide support for building and statically link their underlying system library as part of their build process. Here is how to do this in your build.rs:

fn main() {
        .add_build_internal("testlib", |lib, version| {
            // Actually build the library here
            system_deps::Library::from_internal_pkg_config("build/path-to-pc-file", lib, version)

This feature can be controlled using the SYSTEM_DEPS_$NAME_BUILD_INTERNAL environment variable which can have the following values:

  • auto: build the dependency only if the required version has not been found by pkg-config;
  • always: always build the dependency, ignoring any version which may be installed on the system;
  • never: (default) never build the dependency, system-deps will fail if the required version is not found on the system.

You can also use the SYSTEM_DEPS_BUILD_INTERNAL environment variable with the same values defining the behavior for all the dependencies which don't have SYSTEM_DEPS_$NAME_BUILD_INTERNAL defined.



Structure used to configure metadata before starting to probe for dependencies


A system dependency



Error used in return value of Config::add_build_internal closures


system-deps errors


From where the library settings have been retrieved