Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs for cross compilation. #161

Merged
merged 1 commit into from Feb 7, 2024
Merged

Update docs for cross compilation. #161

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
38 changes: 30 additions & 8 deletions src/lib.rs
View file
Open in desktop
Expand Up @@ -6,18 +6,18 @@
//! `Config` structure serves as a method of configuring how `pkg-config` is
//! invoked in a builder style.
//!
//! After running `pkg-config` all appropriate Cargo metadata will be printed on
//! stdout if the search was successful.
//!
//! # Environment variables
//!
//! A number of environment variables are available to globally configure how
//! this crate will invoke `pkg-config`:
//!
//! * `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.
//! ### Linking
//!
//! There are also a number of environment variables which can configure how a
//! library is linked to (dynamically vs statically). These variables control
Expand All @@ -30,8 +30,30 @@
//! * `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.
//! ### Cross-compilation
//!
//! 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
//! `PKG_CONFIG_SYSROOT_DIR`.
//!
//! Each of these variables can also be supplied with certain prefixes and
//! suffixes, in the following prioritized order:
//!
//! 1. `<var>_<target>` - for example, `PKG_CONFIG_PATH_x86_64-unknown-linux-gnu`
//! 2. `<var>_<target_with_underscores>` - for example,
//! `PKG_CONFIG_PATH_x86_64_unknown_linux_gnu`
//! 3. `<build-kind>_<var>` - for example, `HOST_PKG_CONFIG_PATH` or
//! `TARGET_PKG_CONFIG_PATH`
//! 4. `<var>` - a plain `PKG_CONFIG_PATH`
//!
//! 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.
//!
//! # Example
//!
Expand Down