From 147e102e9c43d6f2f0309c4bb92436d55a3f52d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kornel=20Lesi=C5=84ski?= Date: Sat, 15 Aug 2020 17:13:19 +0100 Subject: [PATCH] Improve docs for cross-compilation #109 --- README.md | 10 ++++++++-- src/lib.rs | 33 ++++++++++++++++++++++++--------- 2 files changed, 32 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index d7a825d..3d8d2b0 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ fn main() { # External configuration via target-scoped environment variables -In cross-compilation context, it is useful to manage separately PKG_CONFIG_PATH +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 @@ -53,7 +53,13 @@ Each of these variables can also be supplied with certain prefixes and suffixes, 3. `_` - for example, `HOST_PKG_CONFIG_PATH` or `TARGET_PKG_CONFIG_PATH` 4. `` - a plain `PKG_CONFIG_PATH` -Also note that `PKG_CONFIG_ALLOW_CROSS` must always be set in cross-compilation context. +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. + +Some Rust sys crates support building vendored libraries from source, which may be a work +around for lack of cross-compilation support in `pkg-config`. # License diff --git a/src/lib.rs b/src/lib.rs index 2be11b3..e68371d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,11 +9,16 @@ //! 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`. //! +//! * `PKG_CONFIG_ALLOW_CROSS` - The `pkg-config` command usually doesn't +//! support cross-compilation, and this crate prevents it from selecting +//! incompatible versions of libraries. +//! Setting `PKG_CONFIG_ALLOW_CROSS=1` disables this protection, which is +//! likely to cause linking errors, unless `pkg-config` has been configured +//! to use appropriate sysroot and search paths for the target platform. +//! //! 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 @@ -106,9 +111,11 @@ pub enum Error { /// Contains the name of the responsible environment variable. EnvNoPkgConfig(String), - /// Cross compilation detected. + /// Detected cross compilation without a custom sysroot. /// - /// Override with `PKG_CONFIG_ALLOW_CROSS=1`. + /// Ignore the error with `PKG_CONFIG_ALLOW_CROSS=1`, + /// which may let `pkg-config` select libraries + /// for the host's architecture instead of the target's. CrossCompilation, /// Failed to run `pkg-config`. @@ -132,10 +139,13 @@ impl fmt::Display for Error { fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> { match *self { Error::EnvNoPkgConfig(ref name) => write!(f, "Aborted because {} is set", name), - Error::CrossCompilation => write!( - f, - "Cross compilation detected. \ - Use PKG_CONFIG_ALLOW_CROSS=1 to override" + Error::CrossCompilation => f.write_str( + "pkg-config has not been configured to support cross-compilation. + + Install a sysroot for the target platform and configure it via + PKG_CONFIG_SYSROOT_DIR and PKG_CONFIG_PATH, or install a + cross-compiling wrapper for pkg-config and set it via + PKG_CONFIG environment variable." ), Error::Command { ref command, @@ -177,7 +187,12 @@ pub fn probe_library(name: &str) -> Result { } /// Run `pkg-config` to get the value of a variable from a package using -/// --variable. +/// `--variable`. +/// +/// The content of `PKG_CONFIG_SYSROOT_DIR` is not injected in paths that are +/// returned by `pkg-config --variable`, which makes them unsuitable to use +/// during cross-compilation unless specifically designed to be used +/// at that time. pub fn get_variable(package: &str, variable: &str) -> Result { let arg = format!("--variable={}", variable); let cfg = Config::new();