cargo build 参数详解

cargo build 是 Rust 的核心构建命令，支持多种参数以控制编译行为，涵盖目标选择、优化配置、依赖管理等方面。以下是其常用参数及分类说明：

一、基础编译模式

1. --release

   • 作用：启用发布模式，使用 [profile.release] 配置（优化级别 opt-level=3，关闭调试信息）。
   • 示例：

     cargo build --release  # 生成优化后的可执行文件（位于 `target/release/`）
     

2. --debug（默认行为）

   • 作用：使用开发模式（[profile.dev]，优化级别 opt-level=0，包含调试信息）。
   • 示例：

     cargo build  # 生成调试版可执行文件（位于 `target/debug/`）
     

二、目标选择

1. 指定构建目标类型

   • --lib：仅构建库目标（src/lib.rs）。
   • --bin <NAME>：构建指定名称的二进制目标（支持通配符 *）。
   • --bins：构建所有二进制目标。
   • --example <NAME>：构建指定示例。
   • --examples：构建所有示例。
   • --test <NAME>：构建指定集成测试。
   • --tests：构建所有测试目标。
   • --bench <NAME>：构建指定基准测试。
   • --benches：构建所有基准测试。
   • --all-targets：等价于 --lib --bins --tests --benches --examples。

   示例：

   cargo build --bin main  # 仅构建 `src/bin/main.rs`
   cargo build --examples  # 构建所有示例
   

2. 跨平台构建

   • --target <TRIPLE>：为指定架构构建（如 x86_64-unknown-linux-gnu）。
   • 示例：

     cargo build --target x86_64-pc-windows-gnu  # 为 Windows 构建
     

三、特性与依赖控制

1. 特性激活

   • --features <FEATURES>：激活指定特性列表（空格或逗号分隔）。
   • --all-features：激活所有可用特性。
   • --no-default-features：禁用默认特性。

   示例：

   cargo build --features "serde,json"  # 激活 `serde` 和 `json` 特性
   

2. 依赖管理

   • --manifest-path <PATH>：指定 Cargo.toml 路径（默认自动搜索）。
   • --frozen/--locked：要求依赖版本与 Cargo.lock 完全一致（用于 CI/CD）。

   示例：

   cargo build --manifest-path ../path/to/Cargo.toml
   

四、输出与缓存控制

1. 输出目录

   • --target-dir <DIR>：指定编译输出目录（默认 target/）。
   • --out-dir <DIR>：将最终可执行文件复制到指定目录。

   示例：

   cargo build --target-dir ./build_output
   

2. 构建计划

   • --build-plan：输出构建步骤的 JSON 描述（不实际执行编译）。

   示例：

   cargo build --build-plan  # 查看构建流程
   

五、工作区控制

1. 工作区构建

   • --workspace：构建工作区中的所有成员（等价于 --all，已废弃）。
   • --exclude <PATTERN>：排除匹配的成员（需与 --workspace 共用）。

   示例：

   cargo build --workspace --exclude "utils*"  # 构建工作区中除 `utils` 开头的成员
   

六、其他实用参数

1. 环境变量覆盖

   • 通过 CARGO_TARGET_DIR 或 build.target-dir 配置项修改输出目录。

2. 性能分析

   • 结合 RUSTFLAGS="-C time-passes" 可输出编译时间统计（需手动设置环境变量）。

参数速查表

使用建议

• 开发阶段：直接使用 cargo build（默认调试模式），快速迭代。
• 发布阶段：使用 cargo build --release 生成优化后的二进制文件。
• 跨平台构建：通过 --target 指定目标架构，配合 rustup target add 安装对应工具链。
• 特性管理：在 Cargo.toml 中定义特性，通过 --features 灵活控制功能模块。

通过合理组合这些参数，可以高效控制 Rust 项目的编译行为，适应不同场景的需求。