[−][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.

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:

ⓘThis example panics
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. Such version features should use the pattern v1_0, v1_2, etc.

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

[package.metadata.system-deps.gstreamer_1_0]
name = "gstreamer-1.0"
version = "1.0"

[package.metadata.system-deps.gstreamer_1_0.v1_2]
version = "1.2"
[package.metadata.system-deps.gstreamer_1_0.v1_4]
version = "1.4"
[package.metadata.system-deps.gstreamer_1_0.v1_6]
version = "1.6"

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

[package.metadata.system-deps.gst_gl]
name = "gstreamer-gl-1.0"
version = "1.14"

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

ⓘThis example panics
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