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.

Usage

In your Cargo.toml:

[build-dependencies]
system-deps = "1.3"

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

[package.metadata.system-deps]
testlib = "1.2"

Finally, in your build.rs, add:

fn main() {
    system_deps::Config::new().probe().unwrap();
}

Optional dependency

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

[package.metadata.system-deps]
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:

[package.metadata.system-deps]
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.

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

[package.metadata.system-deps]
gstreamer = { name = "gstreamer-1.0", version = "1.0", feature-versions = { v1_2 = "1.2", v1_4 = "1.4", v1_6 = "1.6" }}

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:

• SYSTEM_DEPS_$NAME_SEARCH_NATIVE to override the cargo:rustc-link-search=native flag;
• SYSTEM_DEPS_$NAME_SEARCH_FRAMEWORK to override the cargo:rustc-link-search=framework flag;
• SYSTEM_DEPS_$NAME_LIB to override the cargo:rustc-link-lib flag;
• SYSTEM_DEPS_$NAME_LIB_FRAMEWORK to override the cargo:rustc-link-lib=framework flag;
• SYSTEM_DEPS_$NAME_INCLUDE to override the cargo:include flag.

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 libray as part of their build process. Here is how to do this in your build.rs:

fn main() {
    system_deps::Config::new()
        .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)
         })
        .probe()
        .unwrap();
}

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.

Structs

Config	Structure used to configure metadata before starting to probe for dependencies
Library	A system dependency

Enums

BuildInternalClosureError	Error used in return value of Config::add_build_internal closures
Error	system-deps errors
Source	From where the library settings have been retrieved