vendor/pkg-config/README.md

   1 # pkg-config-rs
   2
   3 [![Build Status](https://travis-ci.com/rust-lang/pkg-config-rs.svg?branch=master)](https://travis-ci.com/rust-lang/pkg-config-rs)
   4 [![Rust](https://img.shields.io/badge/rust-1.30%2B-blue.svg?maxAge=3600)](https://github.com/rust-lang/pkg-config-rs/)
   5
   6 [Documentation](https://docs.rs/pkg-config)
   7
   8 A simple library meant to be used as a build dependency with Cargo packages in
   9 order to use the system `pkg-config` tool (if available) to determine where a
  10 library is located.
  11
  12 You can use this crate directly to probe for specific libraries, or use
  13 [metadeps](https://github.com/joshtriplett/metadeps) to declare all your
  14 `pkg-config` dependencies in `Cargo.toml`.
  15
  16 This library requires Rust 1.30+.
  17
  18 # Example
  19
  20 Find the system library named `foo`, with minimum version 1.2.3:
  21
  22 ```rust
  23 extern crate pkg_config;
  24
  25 fn main() {
  26     pkg_config::Config::new().atleast_version("1.2.3").probe("foo").unwrap();
  27 }
  28 ```
  29
  30 Find the system library named `foo`, with no version requirement (not
  31 recommended):
  32
  33 ```rust
  34 extern crate pkg_config;
  35
  36 fn main() {
  37     pkg_config::probe_library("foo").unwrap();
  38 }
  39 ```
  40
  41 # External configuration via target-scoped environment variables
  42
  43 In cross-compilation context, it is useful to manage separately `PKG_CONFIG_PATH`
  44 and a few other variables for the `host` and the `target` platform.
  45
  46 The supported variables are: `PKG_CONFIG_PATH`, `PKG_CONFIG_LIBDIR`, and
  47 `PKG_CONFIG_SYSROOT_DIR`.
  48
  49 Each of these variables can also be supplied with certain prefixes and suffixes, in the following prioritized order:
  50
  51 1. `<var>_<target>` - for example, `PKG_CONFIG_PATH_x86_64-unknown-linux-gnu`
  52 2. `<var>_<target_with_underscores>` - for example, `PKG_CONFIG_PATH_x86_64_unknown_linux_gnu`
  53 3. `<build-kind>_<var>` - for example, `HOST_PKG_CONFIG_PATH` or `TARGET_PKG_CONFIG_PATH`
  54 4. `<var>` - a plain `PKG_CONFIG_PATH`
  55
  56 This crate will allow `pkg-config` to be used in cross-compilation
  57 if `PKG_CONFIG_SYSROOT_DIR` or `PKG_CONFIG` is set. You can set `PKG_CONFIG_ALLOW_CROSS=1`
  58 to bypass the compatibility check, but please note that enabling use of `pkg-config` in
  59 cross-compilation without appropriate sysroot and search paths set is likely to break builds.
  60
  61 Some Rust sys crates support building vendored libraries from source, which may be a work
  62 around for lack of cross-compilation support in `pkg-config`.
  63
  64 # License
  65
  66 This project is licensed under either of
  67
  68  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
  69    http://www.apache.org/licenses/LICENSE-2.0)
  70  * MIT license ([LICENSE-MIT](LICENSE-MIT) or
  71    http://opensource.org/licenses/MIT)
  72
  73 at your option.
  74
  75 ### Contribution
  76
  77 Unless you explicitly state otherwise, any contribution intentionally submitted
  78 for inclusion in pkg-config-rs by you, as defined in the Apache-2.0 license, shall be
  79 dual licensed as above, without any additional terms or conditions.