+//! 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.
+//!
+//! A number of environment variables are available to globally configure how
+//! this crate will invoke `pkg-config`:
+//!
+//! * `PKG_CONFIG_ALLOW_CROSS` - if this variable is not set, then `pkg-config`
+//!   will automatically be disabled for all cross compiles.
+//! * `FOO_NO_PKG_CONFIG` - if set, this will disable running `pkg-config` when
+//!   probing for the library named `foo`.
+//!
+//! 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
+//!
+//! After running `pkg-config` all appropriate Cargo metadata will be printed on
+//! stdout if the search was successful.
+//!
+//! # Example
+//!
+//! Find the system library named `foo`.
+//!
+//! ```no_run
+//! extern crate pkg_config;
+//!
+//! fn main() {
+//!     pkg_config::find_library("foo").unwrap();
+//! }
+//! ```
+//!
+//! Configure how library `foo` is linked to.
+//!
+//! ```no_run
+//! extern crate pkg_config;
+//!
+//! fn main() {
+//!     pkg_config::Config::new().statik(true).find("foo").unwrap();
+//! }
+//! ```
+
+#![doc(html_root_url = "http://alexcrichton.com/pkg-config-rs")]
+#![cfg_attr(test, deny(warnings))]
+
+use std::ascii::AsciiExt;
+use std::env;
+use std::ffi::{OsStr, OsString};
+use std::fs;
+use std::path::{PathBuf, Path};
+use std::process::Command;
+use std::str;
+
+pub fn target_supported() -> bool {
+    env::var("HOST") == env::var("TARGET") ||
+        env::var_os("PKG_CONFIG_ALLOW_CROSS").is_some()
+}
+
+#[derive(Clone)]
+pub struct Config {
+    statik: Option<bool>,
+    atleast_version: Option<String>,
+    extra_args: Vec<OsString>,
+}
+
+#[derive(Debug)]
+pub struct Library {
+    pub libs: Vec<String>,
+    pub link_paths: Vec<PathBuf>,
+    pub frameworks: Vec<String>,
+    pub framework_paths: Vec<PathBuf>,
+    pub include_paths: Vec<PathBuf>,
+    pub version: String,
+    _priv: (),
+}
+
+/// Simple shortcut for using all default options for finding a library.
+pub fn find_library(name: &str) -> Result<Library, String> {
+    Config::new().find(name)
+}
+
+impl Config {
+    /// Creates a new set of configuration options which are all initially set
+    /// to "blank".
+    pub fn new() -> Config {
+        Config {
+            statik: None,
+            atleast_version: None,
+            extra_args: vec![],
+        }
+    }
+
+    /// Indicate whether the `--static` flag should be passed.
+    ///
+    /// This will override the inference from environment variables described in
+    /// the crate documentation.
+    pub fn statik(&mut self, statik: bool) -> &mut Config {
+        self.statik = Some(statik);
+        self
+    }
+
+    /// Indicate that the library must be at least version `vers`.
+    pub fn atleast_version(&mut self, vers: &str) -> &mut Config {
+        self.atleast_version = Some(vers.to_string());
+        self
+    }
+
+    /// Add an argument to pass to pkg-config.
+    ///
+    /// It's placed after all of the arguments generated by this library.
+    pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Config {
+        self.extra_args.push(arg.as_ref().to_os_string());
+        self
+    }
+
+    /// Run `pkg-config` to find the library `name`.
+    ///
+    /// This will use all configuration previously set to specify how
+    /// `pkg-config` is run.
+    pub fn find(&self, name: &str) -> Result<Library, String> {
+        if env::var_os(&format!("{}_NO_PKG_CONFIG", envify(name))).is_some() {
+            return Err(format!("pkg-config requested to be aborted for {}", name))
+        } else if !target_supported() {
+            return Err("pkg-config doesn't handle cross compilation. Use \
+                        PKG_CONFIG_ALLOW_CROSS=1 to override".to_string());
+        }
+
+        let mut library = Library::new();
+
+        let output = try!(run(self.command(name, &["--libs", "--cflags"])));
+        library.parse_libs_cflags(name, &output, self);
+
+        let output = try!(run(self.command(name, &["--modversion"])));
+        library.parse_modversion(&output);
+
+        Ok(library)
+    }
+
+    /// Run `pkg-config` to get the value of a variable from a package using
+    /// --variable.
+    pub fn get_variable(package: &str, variable: &str) -> Result<String, String> {
+        let arg = format!("--variable={}", variable);
+        let cfg = Config::new();
+        Ok(try!(run(cfg.command(package, &[&arg]))).trim_right().to_owned())
+    }
+
+    fn is_static(&self, name: &str) -> bool {
+        self.statik.unwrap_or_else(|| infer_static(name))
+    }
+
+    fn command(&self, name: &str, args: &[&str]) -> Command {
+        let mut cmd = Command::new("pkg-config");
+        if self.is_static(name) {
+            cmd.arg("--static");
+        }
+        cmd.args(args)
+           .args(&self.extra_args)
+           .env("PKG_CONFIG_ALLOW_SYSTEM_LIBS", "1");
+        if let Some(ref version) = self.atleast_version {
+            cmd.arg(&format!("{} >= {}", name, version));
+        } else {
+            cmd.arg(name);
+        }
+        cmd
+    }
+}
+
+impl Library {
+    fn new() -> Library {
+        Library {
+            libs: Vec::new(),
+            link_paths: Vec::new(),
+            include_paths: Vec::new(),
+            frameworks: Vec::new(),
+            framework_paths: Vec::new(),
+            version: String::new(),
+            _priv: (),
+        }
+    }
+
+    fn parse_libs_cflags(&mut self, name: &str, output: &str, config: &Config) {
+        let parts = output.split(' ')
+                          .filter(|l| l.len() > 2)
+                          .map(|arg| (&arg[0..2], &arg[2..]))
+                          .collect::<Vec<_>>();
+
+        let mut dirs = Vec::new();
+        let statik = config.is_static(name);
+        for &(flag, val) in parts.iter() {
+            match flag {
+                "-L" => {
+                    println!("cargo:rustc-link-search=native={}", val);
+                    dirs.push(PathBuf::from(val));
+                    self.link_paths.push(PathBuf::from(val));
+                }
+                "-F" => {
+                    println!("cargo:rustc-link-search=framework={}", val);
+                    self.framework_paths.push(PathBuf::from(val));
+                }
+                "-I" => {
+                    self.include_paths.push(PathBuf::from(val));
+                }
+                "-l" => {
+                    self.libs.push(val.to_string());
+                    if statik && !is_system(val, &dirs) {
+                        println!("cargo:rustc-link-lib=static={}", val);
+                    } else {
+                        println!("cargo:rustc-link-lib={}", val);
+                    }
+                }
+                _ => {}
+            }
+        }
+
+        let mut iter = output.split(' ');
+        while let Some(part) = iter.next() {
+            if part != "-framework" { continue }
+            if let Some(lib) = iter.next() {
+                println!("cargo:rustc-link-lib=framework={}", lib);
+                self.frameworks.push(lib.to_string());
+            }
+        }
+    }
+
+    fn parse_modversion(&mut self, output: &str) {
+        self.version.push_str(output.trim());
+    }
+}
+
+fn infer_static(name: &str) -> bool {
+    let name = envify(name);
+    if env::var_os(&format!("{}_STATIC", name)).is_some() {
+        true
+    } else if env::var_os(&format!("{}_DYNAMIC", name)).is_some() {
+        false
+    } else if env::var_os("PKG_CONFIG_ALL_STATIC").is_some() {
+        true
+    } else if env::var_os("PKG_CONFIG_ALL_DYNAMIC").is_some() {
+        false
+    } else {
+        false
+    }
+}
+
+fn envify(name: &str) -> String {
+    name.chars().map(|c| c.to_ascii_uppercase()).map(|c| {
+        if c == '-' {'_'} else {c}
+    }).collect()
+}
+
+fn is_system(name: &str, dirs: &[PathBuf]) -> bool {
+    let libname = format!("lib{}.a", name);
+    let root = Path::new("/usr");
+    !dirs.iter().any(|d| {
+        !d.starts_with(root) && fs::metadata(&d.join(&libname)).is_ok()
+    })
+}
+
+fn run(mut cmd: Command) -> Result<String, String> {
+    let out = try!(cmd.output().map_err(|e| {
+        format!("failed to run `{:?}`: {}", cmd, e)
+    }));
+
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    if out.status.success() {
+        return Ok(stdout);
+    }
+
+    let stderr = str::from_utf8(&out.stderr).unwrap();
+    let mut msg = format!("`{:?}` did not exit successfully: {}", cmd, out.status);
+    if stdout.len() > 0 {
+        msg.push_str("\n--- stdout\n");
+        msg.push_str(&stdout);
+    }
+    if stderr.len() > 0 {
+        msg.push_str("\n--- stderr\n");
+        msg.push_str(stderr);
+    }
+
+    return Err(msg);
+}
+

+

Keyboard shortcuts

Search tricks