9
9
//! A number of environment variables are available to globally configure how
10
10
//! this crate will invoke `pkg-config`:
11
11
//!
12
- //! * `PKG_CONFIG_ALLOW_CROSS` - if this variable is not set, then `pkg-config`
13
- //! will automatically be disabled for all cross compiles.
14
12
//! * `FOO_NO_PKG_CONFIG` - if set, this will disable running `pkg-config` when
15
13
//! probing for the library named `foo`.
16
14
//!
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
+ //!
17
22
//! There are also a number of environment variables which can configure how a
18
23
//! library is linked to (dynamically vs statically). These variables control
19
24
//! whether the `--static` flag is passed. Note that this behavior can be
@@ -106,9 +111,11 @@ pub enum Error {
106
111
/// Contains the name of the responsible environment variable.
107
112
EnvNoPkgConfig ( String ) ,
108
113
109
- /// Cross compilation detected .
114
+ /// Detected cross compilation without a custom sysroot .
110
115
///
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.
112
119
CrossCompilation ,
113
120
114
121
/// Failed to run `pkg-config`.
@@ -132,10 +139,13 @@ impl fmt::Display for Error {
132
139
fn fmt ( & self , f : & mut fmt:: Formatter ) -> Result < ( ) , fmt:: Error > {
133
140
match * self {
134
141
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."
139
149
) ,
140
150
Error :: Command {
141
151
ref command,
@@ -177,7 +187,12 @@ pub fn probe_library(name: &str) -> Result<Library, Error> {
177
187
}
178
188
179
189
/// 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.
181
196
pub fn get_variable ( package : & str , variable : & str ) -> Result < String , Error > {
182
197
let arg = format ! ( "--variable={}" , variable) ;
183
198
let cfg = Config :: new ( ) ;
0 commit comments