Skip to content

Commit 070b4e9

Browse files
authored
Merge pull request #113 from kornelski/crossdocs
Improve docs for cross-compilation
2 parents a5931e3 + 147e102 commit 070b4e9

File tree

2 files changed

+32
-11
lines changed

2 files changed

+32
-11
lines changed

README.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ fn main() {
4040

4141
# External configuration via target-scoped environment variables
4242

43-
In cross-compilation context, it is useful to manage separately PKG_CONFIG_PATH
43+
In cross-compilation context, it is useful to manage separately `PKG_CONFIG_PATH`
4444
and a few other variables for the `host` and the `target` platform.
4545

4646
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,
5353
3. `<build-kind>_<var>` - for example, `HOST_PKG_CONFIG_PATH` or `TARGET_PKG_CONFIG_PATH`
5454
4. `<var>` - a plain `PKG_CONFIG_PATH`
5555

56-
Also note that `PKG_CONFIG_ALLOW_CROSS` must always be set in cross-compilation context.
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`.
5763

5864
# License
5965

src/lib.rs

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,16 @@
99
//! A number of environment variables are available to globally configure how
1010
//! this crate will invoke `pkg-config`:
1111
//!
12-
//! * `PKG_CONFIG_ALLOW_CROSS` - if this variable is not set, then `pkg-config`
13-
//! will automatically be disabled for all cross compiles.
1412
//! * `FOO_NO_PKG_CONFIG` - if set, this will disable running `pkg-config` when
1513
//! probing for the library named `foo`.
1614
//!
15+
//! * `PKG_CONFIG_ALLOW_CROSS` - The `pkg-config` command usually doesn't
16+
//! support cross-compilation, and this crate prevents it from selecting
17+
//! incompatible versions of libraries.
18+
//! Setting `PKG_CONFIG_ALLOW_CROSS=1` disables this protection, which is
19+
//! likely to cause linking errors, unless `pkg-config` has been configured
20+
//! to use appropriate sysroot and search paths for the target platform.
21+
//!
1722
//! There are also a number of environment variables which can configure how a
1823
//! library is linked to (dynamically vs statically). These variables control
1924
//! whether the `--static` flag is passed. Note that this behavior can be
@@ -106,9 +111,11 @@ pub enum Error {
106111
/// Contains the name of the responsible environment variable.
107112
EnvNoPkgConfig(String),
108113

109-
/// Cross compilation detected.
114+
/// Detected cross compilation without a custom sysroot.
110115
///
111-
/// Override with `PKG_CONFIG_ALLOW_CROSS=1`.
116+
/// Ignore the error with `PKG_CONFIG_ALLOW_CROSS=1`,
117+
/// which may let `pkg-config` select libraries
118+
/// for the host's architecture instead of the target's.
112119
CrossCompilation,
113120

114121
/// Failed to run `pkg-config`.
@@ -132,10 +139,13 @@ impl fmt::Display for Error {
132139
fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
133140
match *self {
134141
Error::EnvNoPkgConfig(ref name) => write!(f, "Aborted because {} is set", name),
135-
Error::CrossCompilation => write!(
136-
f,
137-
"Cross compilation detected. \
138-
Use PKG_CONFIG_ALLOW_CROSS=1 to override"
142+
Error::CrossCompilation => f.write_str(
143+
"pkg-config has not been configured to support cross-compilation.
144+
145+
Install a sysroot for the target platform and configure it via
146+
PKG_CONFIG_SYSROOT_DIR and PKG_CONFIG_PATH, or install a
147+
cross-compiling wrapper for pkg-config and set it via
148+
PKG_CONFIG environment variable."
139149
),
140150
Error::Command {
141151
ref command,
@@ -177,7 +187,12 @@ pub fn probe_library(name: &str) -> Result<Library, Error> {
177187
}
178188

179189
/// Run `pkg-config` to get the value of a variable from a package using
180-
/// --variable.
190+
/// `--variable`.
191+
///
192+
/// The content of `PKG_CONFIG_SYSROOT_DIR` is not injected in paths that are
193+
/// returned by `pkg-config --variable`, which makes them unsuitable to use
194+
/// during cross-compilation unless specifically designed to be used
195+
/// at that time.
181196
pub fn get_variable(package: &str, variable: &str) -> Result<String, Error> {
182197
let arg = format!("--variable={}", variable);
183198
let cfg = Config::new();

0 commit comments

Comments
 (0)