条件依赖 target
核心概念
条件依赖(target-specific dependencies)允许根据目标平台来选择性地引入依赖。不同操作系统和架构可能需要不同的库,比如 Windows 上用 winapi,Linux 上用 nix。Cargo 通过 [target.'cfg(...)'.dependencies] 语法来声明平台相关的依赖,只有在匹配的目标平台上才会编译和链接这些依赖。
# 根据操作系统选择依赖
[target.'cfg(windows)'.dependencies]
winapi = { version = "0.3", features = ["winuser", "processthreadsapi"] }
windows-sys = "0.52"
[target.'cfg(unix)'.dependencies]
nix = { version = "0.28", features = ["signal", "process"] }
libc = "0.2"
[target.'cfg(target_os = "macos")'.dependencies]
core-foundation = "0.9"
# 根据架构选择依赖
[target.'cfg(target_arch = "x86_64")'.dependencies]
simd-json = "0.13"cfg 表达式
# === 操作系统 ===
[target.'cfg(windows)'.dependencies] # Windows
[target.'cfg(unix)'.dependencies] # Unix 系统(Linux, macOS, BSD 等)
[target.'cfg(target_os = "linux")'.dependencies] # 仅 Linux
[target.'cfg(target_os = "macos")'.dependencies] # 仅 macOS
[target.'cfg(target_os = "android")'.dependencies] # Android
# === 架构 ===
[target.'cfg(target_arch = "x86_64")'.dependencies] # x86-64
[target.'cfg(target_arch = "aarch64")'.dependencies] # ARM64
[target.'cfg(target_arch = "wasm32")'.dependencies] # WebAssembly
# === 逻辑组合 ===
[target.'cfg(all(unix, not(target_os = "macos")))'.dependencies]
# Unix 但不是 macOS(主要是 Linux 和 BSD)
[target.'cfg(any(target_os = "linux", target_os = "macos"))'.dependencies]
# Linux 或 macOS
[target.'cfg(not(windows))'.dependencies]
# 非 Windows
# === 其他条件 ===
[target.'cfg(target_env = "musl")'.dependencies] # musl libc
[target.'cfg(target_pointer_width = "64")'.dependencies] # 64 位
[target.'cfg(target_endian = "little")'.dependencies] # 小端序| cfg 表达式 | 说明 |
|---|---|
windows | Windows 系统 |
unix | Unix 系统 |
target_os = "linux" | Linux |
target_os = "macos" | macOS |
target_arch = "x86_64" | x86-64 架构 |
target_arch = "aarch64" | ARM64 架构 |
target_env = "gnu" | GNU 工具链 |
target_env = "msvc" | MSVC 工具链 |
all(a, b) | a 且 b |
any(a, b) | a 或 b |
not(a) | 非 a |
条件 dev-dependencies 和 build-dependencies
# 平台特定的开发依赖
[target.'cfg(windows)'.dev-dependencies]
windows-test-utils = "0.1"
[target.'cfg(unix)'.dev-dependencies]
nix = { version = "0.28", features = ["signal"] }
# 平台特定的构建依赖
[target.'cfg(windows)'.build-dependencies]
winres = "0.1" # Windows 资源文件编译
[target.'cfg(unix)'.build-dependencies]
pkg-config = "0.3" # Unix 系统库查找基本示例
[package]
name = "cross-platform"
version = "0.1.0"
edition = "2024"
[dependencies]
# 所有平台都需要的依赖
log = "0.4"
[target.'cfg(windows)'.dependencies]
winapi = { version = "0.3", features = ["winuser"] }
[target.'cfg(unix)'.dependencies]
libc = "0.2"// 在代码中配合条件依赖使用条件编译
#[cfg(windows)]
fn get_username() -> String {
// Windows 上获取用户名
std::env::var("USERNAME").unwrap_or_else(|_| "unknown".to_string())
}
#[cfg(unix)]
fn get_username() -> String {
// Unix 上获取用户名
std::env::var("USER").unwrap_or_else(|_| "unknown".to_string())
}
#[cfg(windows)]
fn platform_info() -> &'static str {
"Windows"
}
#[cfg(target_os = "linux")]
fn platform_info() -> &'static str {
"Linux"
}
#[cfg(target_os = "macos")]
fn platform_info() -> &'static str {
"macOS"
}
fn main() {
println!("平台: {}", platform_info());
println!("用户: {}", get_username());
}常见问题
问题一:target 依赖在非目标平台上会被下载吗?
不会。Cargo 只会下载和编译当前目标平台匹配的条件依赖。交叉编译时,Cargo 根据 --target 参数判断。
问题二:cfg 条件写错了 Cargo 会报错吗?
cfg 表达式的语法错误会被 Cargo 检测到。但如果写了一个合法但永远不会匹配的条件(如 target_os = "typo"),Cargo 不会警告。
问题三:条件依赖和 features 可以组合吗?
可以。条件依赖也支持所有标准的依赖选项,包括 features、optional、default-features 等。
问题四:怎么查看当前平台支持哪些 cfg 值?
运行 rustc --print cfg 查看当前平台的所有 cfg 标志。交叉编译时用 rustc --target x86_64-unknown-linux-gnu --print cfg。
适用场景
- 跨平台项目:不同 OS 使用不同的系统 API 库
- 架构优化:x86-64 上使用 SIMD 库
- 嵌入式开发:针对特定目标的依赖
- WebAssembly:wasm32 专用的绑定库
注意事项
- cfg 表达式必须用单引号包裹在 TOML 中
- 条件依赖不会在非匹配平台上编译
- 代码中要用对应的
#[cfg(...)]配合使用 rustc --print cfg查看可用的 cfg 标志all()、any()、not()可以组合复杂条件- 条件依赖同样支持 features、optional 等选项
总结
条件依赖通过 [target.'cfg(...)'.dependencies] 语法声明平台相关的依赖,只在匹配的目标平台上编译和链接。cfg 表达式支持 windows、unix、target_os、target_arch 等条件,以及 all()、any()、not() 逻辑组合。条件依赖同样适用于 dev-dependencies 和 build-dependencies。代码中需要用 #[cfg(...)] 配合条件编译。rustc --print cfg 可以查看当前平台的所有 cfg 标志。