02-cargo install

cargo-install(1) 安装二进制 crate

7 分钟阅读

译文 · 基于 The Cargo Book

cargo-install(1)

原文链接: https://doc.rust-lang.org/cargo/commands/cargo-install.html

名称

cargo-install — 构建并安装 Rust 二进制程序

大纲

cargo install [options] crate[@version]…
cargo install [options] --path path
cargo install [options] --git url [crate…]
cargo install [options] --list

描述

此命令管理 Cargo 本地已安装的二进制 crate 集合。仅含可执行 [[bin]] 或 [[example]] 目标的包可以安装，所有可执行文件都安装到安装根的 bin 文件夹中。默认只安装二进制文件，不安装示例。

安装根按以下优先级确定：

--root 选项
CARGO_INSTALL_ROOT 环境变量
install.root Cargo 配置值
CARGO_HOME 环境变量
$HOME/.cargo

crate 可从多个来源安装。默认来源是 crates.io，但 --git、--path 与 --registry 标志可更改来源。若来源包含多个包（如 crates.io 或含多个 crate 的 git 仓库），必须提供 crate 参数以指定要安装的 crate。

来自 crates.io 的 crate 可通过 --version 标志可选指定要安装的版本；同样，来自 git 仓库的包也可选指定分支、标签或 revision。若 crate 有多个二进制文件，可用 --bin 参数选择性只安装其中一个；若要安装示例，可使用 --example 参数。

若包已安装，当已安装版本似乎不是最新时 Cargo 会重新安装。若以下任一值发生变化，Cargo 将重新安装该包：

包版本与来源。
已安装的二进制名称集合。
所选特性。
配置文件（--profile）。
目标（--target）。

使用 --path 安装时总会构建并安装，除非与来自其他包的二进制文件冲突。可用 --force 标志强制 Cargo 始终重新安装该包。

若来源是 crates.io 或 --git，默认会在临时目标目录中构建 crate。为避免此行为，可将 CARGO_TARGET_DIR 环境变量设为路径以指定目标目录。这在持续集成系统上缓存构建产物时尤其有用。

处理锁文件

默认情况下，包附带的 Cargo.lock 文件会被忽略。这意味着 Cargo 会重新计算使用哪些依赖版本，可能使用自包发布以来更新的版本。可用 --locked 标志强制 Cargo 使用打包的 Cargo.lock 文件（若可用）。这对确保可重现构建、使用包发布时可用的完全相同依赖集合可能有用。若发布了不再能在你的系统上构建或有其他问题的新版依赖，也可能有用。使用 --locked 的缺点是，你不会收到任何依赖的修复或更新。请注意，Cargo 直到 1.37 版本才开始发布 Cargo.lock 文件，这意味着更早版本发布的包不会有可用的 Cargo.lock 文件。

配置发现

此命令在系统或用户级别运行，而非项目级别。这意味着本地配置发现会被忽略。配置发现从 $CARGO_HOME/config.toml 开始。若使用 --path $PATH 安装包，将使用本地配置，从 $PATH/.cargo/config.toml 开始发现。

选项

安装选项

--vers version
--version version: 指定要安装的版本。可以是版本要求，如 ~1.2，让 Cargo 从给定要求中选择最新版本。若版本没有要求运算符（如 ^ 或 ~），则必须是 MAJOR.MINOR.PATCH 形式，将精确安装该版本；不会像 Cargo 依赖那样被视为 caret 要求。
--git url: 从中安装指定 crate 的 Git URL。
--branch branch: 从 git 安装时使用的分支。
--tag tag: 从 git 安装时使用的标签。
--rev sha: 从 git 安装时使用的特定提交。
--path path: 要从中安装的本地 crate 的文件系统路径。
--list: 列出所有已安装的包及其版本。
-n
--dry-run: （不稳定）执行所有检查但不实际安装。
-f
--force: 强制覆盖现有 crate 或二进制文件。若某包安装的二进制与另一包同名，这很有用。若系统上发生了变化而你想重新构建（例如更新了 rustc 版本），这也很有用。
--no-track: 默认情况下，Cargo 通过存储在安装根目录的元数据文件跟踪已安装的包。此标志告诉 Cargo 不使用或创建该文件。使用此标志时，除非使用 --force 标志，否则 Cargo 将拒绝覆盖任何现有文件。这也会禁用 Cargo 防止多个并发 Cargo 安装同时进行的能力。
--bin name…: 仅安装指定的二进制文件。
--bins: 安装所有二进制文件。这是默认行为。
--example name…: 仅安装指定的示例。
--examples: 安装所有示例。
--root dir: 安装包的目标目录。
--registry registry: 要使用的注册表名称。注册表名称在 Cargo 配置文件中定义。若未指定，则使用默认注册表，由 registry.default 配置键定义，默认为 crates-io。
--index index: 要使用的注册表索引 URL。

特性选择

特性标志用于控制启用哪些特性。若未指定特性选项，每个所选包都会激活 default 特性。

参见特性文档了解更多详情。

-F features
--features features: 空格或逗号分隔的要激活的特性列表。工作空间成员的特性可用 package-name/feature-name 语法启用。此标志可指定多次，以启用所有指定的特性。
--all-features: 激活所有所选包的全部可用特性。
--no-default-features: 不激活所选包的 default 特性。

编译选项

--target triple

为指定目标架构安装。默认为宿主架构。三元组的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的值：

rustc --print target-list 中支持的任意目标。
"host-tuple"，内部将替换为宿主目标。若你在交叉编译某些 crate，且不想将宿主机器指定为目标（例如多人协作的共享项目中的 xtask），这会特别有用。
自定义目标规范的路径。更多信息见 Custom Target Lookup Path。

也可通过 build.target 配置值指定。

请注意，指定此标志会使 Cargo 以不同模式运行，目标产物将放在单独的目录中。更多细节见构建缓存文档。

--target-dir directory

所有生成产物与中间文件的目录。也可通过 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置值指定。默认为平台临时目录中的新临时文件夹。

使用 --path 时，默认使用本地 crate 工作空间中的 target 目录，除非指定了 --target-dir。

--debug

使用 dev 配置文件构建，而非 release 配置文件。也可参见 --profile 选项以按名称选择特定配置文件。

--profile name

使用给定配置文件安装。关于配置文件的更多细节，见参考文档。

--timings

输出每次编译耗时信息，并随时间跟踪并发信息。

构建结束时会将文件 cargo-timing.html 写入 target/cargo-timings 目录。若你想查看之前的运行，还会写入文件名带时间戳的额外报告。这些报告仅供人类阅读，不提供机器可读的计时数据。

清单选项

--ignore-rust-version

忽略包中的 rust-version 规范。

--locked

断言使用的依赖与版本与最初生成现有 Cargo.lock 文件时完全相同。出现以下任一情况时 Cargo 将以错误退出：

锁文件缺失。
Cargo 因不同的依赖解析而试图更改锁文件。

可用于需要确定性构建的环境，例如 CI 流水线。

--offline

阻止 Cargo 以任何理由访问网络。若未指定此标志，当 Cargo 需要访问网络而网络不可用时会以错误停止。指定此标志后，Cargo 会在可能时尝试在无网络情况下继续。

请注意，这可能导致与在线模式不同的依赖解析。Cargo 会将自身限制为本地已下载的 crate，即便本地索引副本表明可能有更新版本。可先使用 cargo-fetch(1) 命令下载依赖再离线。

也可通过 net.offline 配置值指定。

--frozen

等价于同时指定 --locked 与 --offline。

其他选项

-j N

--jobs N

并行作业数。也可通过 build.jobs 配置值指定。默认为逻辑 CPU 数量。若为负数，则最大并行作业数为逻辑 CPU 数加上该值。若提供字符串 default，则恢复为默认值。不应为 0。

--keep-going

尽可能构建依赖图中的更多 crate，而不是在第一个构建失败的 crate 处中止。

例如，若当前包依赖 fails 与 works，其中一个构建失败，cargo install -j1 可能会也可能不会构建成功的那一个（取决于 Cargo 先运行哪一个），而 cargo install -j1 --keep-going 则一定会运行两次构建，即便先运行的那个失败。

显示选项

-v

--verbose

使用详细输出。可指定两次以获得“非常详细”的输出，其中包含依赖警告与构建脚本输出等额外信息。也可通过 term.verbose 配置值指定。

-q

--quiet

不打印 cargo 日志消息。也可通过 term.quiet 配置值指定。

--color when

控制何时使用彩色输出。有效值：

auto（默认）：自动检测终端是否支持颜色。
always：始终显示颜色。
never：从不显示颜色。

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

--message-format fmt

诊断消息的输出格式。可指定多次，由逗号分隔的值组成。有效值：

human（默认）：以人类可读的文本格式显示。与 short 和 json 冲突。
short：输出更短的人类可读文本消息。与 human 和 json 冲突。
json：向 stdout 输出 JSON 消息。更多细节见参考文档。与 human 和 short 冲突。
json-diagnostic-short：确保 JSON 消息的 rendered 字段包含来自 rustc 的“short”渲染。不能与 human 或 short 一起使用。
json-diagnostic-rendered-ansi：确保 JSON 消息的 rendered 字段包含嵌入式 ANSI 颜色代码，以遵循 rustc 的默认配色方案。不能与 human 或 short 一起使用。
json-render-diagnostics：指示 Cargo 不在输出的 JSON 消息中包含 rustc 诊断，而是由 Cargo 自身渲染来自 rustc 的 JSON 诊断。Cargo 自身的 JSON 诊断以及来自 rustc 的其他诊断仍会输出。不能与 human 或 short 一起使用。