| lib.rs |
A build dependency for Cargo libraries to find system artifacts through the
`pkg-config` utility.
This library will shell out to `pkg-config` as part of build scripts and
probe the system to determine how to link to a specified library. The
`Config` structure serves as a method of configuring how `pkg-config` is
invoked in a builder style.
After running `pkg-config` all appropriate Cargo metadata will be printed on
stdout if the search was successful.
# Environment variables
A number of environment variables are available to globally configure how
this crate will invoke `pkg-config`:
* `FOO_NO_PKG_CONFIG` - if set, this will disable running `pkg-config` when
probing for the library named `foo`.
### Linking
There are also a number of environment variables which can configure how a
library is linked to (dynamically vs statically). These variables control
whether the `--static` flag is passed. Note that this behavior can be
overridden by configuring explicitly on `Config`. The variables are checked
in the following order:
* `FOO_STATIC` - pass `--static` for the library `foo`
* `FOO_DYNAMIC` - do not pass `--static` for the library `foo`
* `PKG_CONFIG_ALL_STATIC` - pass `--static` for all libraries
* `PKG_CONFIG_ALL_DYNAMIC` - do not pass `--static` for all libraries
### Cross-compilation
In cross-compilation context, it is useful to manage separately
`PKG_CONFIG_PATH` and a few other variables for the `host` and the `target`
platform.
The supported variables are: `PKG_CONFIG_PATH`, `PKG_CONFIG_LIBDIR`, and
`PKG_CONFIG_SYSROOT_DIR`.
Each of these variables can also be supplied with certain prefixes and
suffixes, in the following prioritized order:
1. `<var>_<target>` - for example, `PKG_CONFIG_PATH_x86_64-unknown-linux-gnu`
2. `<var>_<target_with_underscores>` - for example,
`PKG_CONFIG_PATH_x86_64_unknown_linux_gnu`
3. `<build-kind>_<var>` - for example, `HOST_PKG_CONFIG_PATH` or
`TARGET_PKG_CONFIG_PATH`
4. `<var>` - a plain `PKG_CONFIG_PATH`
This crate will allow `pkg-config` to be used in cross-compilation
if `PKG_CONFIG_SYSROOT_DIR` or `PKG_CONFIG` is set. You can set
`PKG_CONFIG_ALLOW_CROSS=1` to bypass the compatibility check, but please
note that enabling use of `pkg-config` in cross-compilation without
appropriate sysroot and search paths set is likely to break builds.
# Example
Find the system library named `foo`, with minimum version 1.2.3:
```no_run
fn main() {
pkg_config::Config::new().atleast_version("1.2.3").probe("foo").unwrap();
}
```
Find the system library named `foo`, with no version requirement (not
recommended):
```no_run
fn main() {
pkg_config::probe_library("foo").unwrap();
}
```
Configure how library `foo` is linked to.
```no_run
fn main() {
pkg_config::Config::new().atleast_version("1.2.3").statik(true).probe("foo").unwrap();
}
``` |
45904 |
- |