cargo-build(1)

定义

cargo-build - 编译当前package

概要

cargo build [options]

说明

编译本地package以及它们的依赖

选项

Package 的选择

默认情况下，如果没有提供选择包的选项，那么会按照选择的配置清单文件来选择包(当没有指定 --manifest-path 时，按照当前工目录来查找配置清单文件)。如果工作空间根目录的配置清单文件，则会选择该工作空间的默认成员，否则仅选取配置清单文件所在的那个包。

workspace默认的成员可以通过根清单文件中的 workspace.default-members 键指定，如果没有指定该键，则会生成一个虚拟的workspace包含所有的workspace成员 (等同于直接传入 --workspace 参数)，并且非虚拟的workspace将只包含根crate自身。

-p spec...
--package spec...: 只包含特定的package。要了解SPEC格式，请参阅cargo-pkgid(1) 该标识可被指定多次，并且支持通用Unix通配符(common Unix glob patterns),例如: *, ? 和 []。然而, 为了避免shell在Cargo处理他们之前将通配符意外的展开 , 必须使用单引号或者双引号将模式串包住。
--workspace: 在workspace中构建全部成员。
--all: 是 --workspace已经弃用的别名。
--exclude SPEC...: 排除指定的package，必须与 --workspace 标识连用。该标识可以被指定多次，并且支持Unix通配符(common Unix glob patterns)，例如*, ? 和 []。然而, 为了避免shell在Cargo处理他们之前将通配符意外的展开 , 必须使用单引号或者双引号将模式串包住。

构建目标的选择

当没有目标选择选项给出的时候，cargo build 将构建所有的选定的package中的binary和library目标。如果Binary的 required-features 有缺失，则Binary构建将被跳过

如果集成测试或者性能测试被指定构建，则Binary目标将被自动构建。这允许了集成测试执行binary用以测试它们的行为。在构建集成测试时设置 CARGO_BIN_EXE_<name> 环境变量以便于它可以使用env 宏来定位可执行文件。

传入目标选择参数将只构建指定的目标。

需要注意的是--bin, --example, --test 和 --bench 标志同样支持Unix通配符(common Unix glob patterns)，例如 *, ? 和 []。然而, 为了避免shell在Cargo处理他们之前将通配符意外的展开, 必须使用单引号或者双引号将模式串包住。

--lib: 构建package的library。
--bin name...: 构建指定的binary，该标识可以被指定多次，并且支持Unix通配符。
--bins: 构建所有的binary目标。
--example name...: 构建指定的示例，该标识可以被指定多次，并且支持Unix通配符。
--examples: 构建所有的示例。
--test name...: 构建指定的集成测试，该标识可以被指定多次，并且支持Unix通配符。
--tests: 在测试模式下构建所有清单文件中带有 test = true 标识的目标，默认情况下，这将包含作为单元测试和集成测试构建的library和binary 当心这也会构建所需要的依赖，因此，library目标有可能被构建两次(一次作为单元测试，一次作为binary或集成测试等目标的依赖。)。通过在目标的清单文件设置中设置 test 标志，可以启用或禁用目标。
--bench name...: 构建指定的性能测试，该标识可以被指定多次，并且支持Unix通配符。
--benches: 在性能测试模式下构建所有清单文件中带有 bench = true 标识的目标，默认情况下，这将包含作为性能测试或性能测试目标构建的library和binary 当心这也会构建所需要的依赖，因此，library目标有可能被构建两次(一次作为性能测试，一次作为binary或性能测试等目标的依赖。)。通过在目标的清单文件设置中设置 bench 标志，可以选择是否启用。
--all-targets: 构建所有的目标，等同于 --lib --bins --tests --benches --examples.

特性选择

特性标志允许你控制开启哪些特性。当没有提供特性选项时，会为每个选择的包启用 default 特性。

查阅 the features documentation 以获取更多细节

-F features
--features features: 要激活的特性列表，特性间用空格逗号隔开。workspace的成员的特性可以通过 package-name/feature-name 来启用。该标志可以被设置多次，将启用所有给出的特性。
--all-features: 激活选中package的所有特性
--no-default-features: 不激活选中的package的 default 特性

编译选项

--target triple

为指定的CPU架构构建. 默认情况下是当前主机的架构. 参数中的三元组的一般格式是 <arch><sub>-<vendor>-<sys>-<abi>. 运行 rustc --print target-list 来获取支持的架构列表

也可以通过 build.target 配置。

注意，指定这个标志会使Cargo在不同的模式下运行，目标制品放在单独目录。参见构建缓存文档了解详情。

-r

--release

通过清单文件中 release 配置项目(profile)，以构建出优化过的产物。参阅 --profile 选项了解如何按照指定的配置项目构建

--profile name

通过给定的profile构建参阅参考手册获取更多关于profile的细节。

--ignore-rust-version

即使cargo低于项目中 rust-version 字段要求的cargo最低版本，也继续构建

--timings=fmts

输出每个编译过程所花费的时间，以及随着时间变化的并行执行情况，可以接收通过逗号分隔的可选的参数，来定义输出的格式 --timings 如果后面不跟参数将，将默认看作 --timings=html。给出输出格式(除了默认)是不稳定的的功能，需要加上 -Zunstable-options。有效的格式有:

html (不稳定, 需要 -Zunstable-options): 生成一个适合人类阅读的的耗时报告文件 cargo-timing.html ，保存到 target/cargo-timings 目录下。同时也在同目录下生成一个相同内容的用时间戳命名的报告，方便再次编译将前者覆盖后查看。 HTML 输出只适合人类阅读，并且不会提供适合机器阅读的耗时数据
json (不稳定, 需要 -Zunstable-options): 生成适合机器阅读的JSON格式的耗时信息

输出选项

--target-dir directory

所有生成目标产物以及中间文件存放的目录，也可通过 CARGO_TARGET_DIR 环境变量指定, 又或者通过 build.target-dir 配置。默认将保存到workspace根目录下的target 目录下

--out-dir directory

复制最终产物到指定目录.

该选项是不稳定的，只在 nightly channel 以及 -Z unstable-options 标志被设置才能启用。查阅 https://github.com/rust-lang/cargo/issues/6790 获取更多信息。

显示选项

-v

--verbose

输出详细信息。指定两次该选项表示 "非常详细" 输出诸如依赖警告或编译脚本的输出等信息。也可通过 term.verbose 配置项指定可选值。

-q

--quiet

不输出cargo日志信息。也可通过term.quiet 配置项指定可选值.

--color when

控制何时输出彩色信息，可选值:

auto (默认): 自动检测终端是否支持彩色。
always: 总是输出彩色信息。
never: 从不输出彩色信息。

也可通过 term.color 配置项指定可选值。

--message-format fmt

指定输出诊断信息的格式。可以被指定多次，值由逗号隔开，有效的值有:

human (default): 显示适合人类阅读的文本信息. 与 short 和 json冲突。
short: 输出更短的, 适合人类阅读的信息。与 human 和 json冲突
json: 输出json信息到stdout。查阅参考手册以获取详细信息。与 human 和 short冲突。
json-diagnostic-short: 确保JSON的 rendered 字段包含 "short" 由rustc渲染。不可以与 human 或者 short同时使用。
json-diagnostic-rendered-ansi: 确保JSON的 rendered 字段包含ANSI颜色码，以符合rustc的默认颜色方案，不可以与 human 或者 short同时使用。
json-render-diagnostics: 指导Cargo输出的JSON消息不要包含rustc的诊断信息，而是让Cargo自己渲染rustc的诊断信息，但是Cargo自己的JSON诊断和来自rustc的其他诊断保留。不可以与human 或者 short同时使用。

--build-plan

输出一系列的JSON消息到指示要运行的命令的stdout

该选项尚且不稳定，只有在 nightly channel 且-Z unstable-options 被指定时才可以开启。查阅 https://github.com/rust-lang/cargo/issues/5579 以获取更多信息.

清单选项

--manifest-path path

Cargo.toml 的路径. 默认情况下Cargo将搜索当前目录或所有父目录下的 Cargo.toml 文件。

--frozen

--locked

这些标志都要求 Cargo.lock 文件是最新的。如果lock文件丢失, 或是需要更新, Cargo会返回错误并退出，--frozen 选项还会阻止cargo通过网络来判断其是否过期。

可以用于断言 Cargo.lock 文件是否最新状态(例如CI构建)或避免网络访问。

--offline

阻止Cargo访问网络。如果不指定该选项，Cargo会在需要使用网络但不可用时停止构建并返回错误。设置该标识，Cargo将尽可能不使用网络完成构建。

需注意，这样可能会导致与在线模式不同的依赖处理，Cargo将限制仅使用已下载到本地的crate，即使本地索引中有更新版本。查阅 cargo-fetch(1) 命令，在脱机前下载依赖。

也可以使用 net.offline 配置。

一般选项

+toolchain: 如果Cargo已经通过rustup安装，并且第一个传给 cargo 的参数以 + 开头，则当作rustup的工具链名称。(例如 +stable 或 +nightly). 查阅 rustup 文档了解关于工具链覆盖的信息。
--config KEY=VALUE or PATH: 覆盖Cargo配置项的值，该参数应当为TOML KEY=VALUE 语法，或者提供附加的配置文件的路径。该标识可以多次指定。查阅命令行覆盖部分获取更多信息
-h
--help: 输出帮助信息。
-Z flag: Cargo不稳定的(每日构建)标志。运行 cargo -Z help 了解详情。