cargo-install(1)

概要

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

描述

这个命令管理 Cargo 安装到本地的所有二进制crate。只有具有可执行的 [[bin]] 或 [[example]] 的包才能被安装，保存位置为安装根目录(root)的 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 仓库安装时可以指定 branch、tag 或 revision (hash值)。如果一个 crate 有多个二进制程序(binary)，可以使用 --bin 来指定安装其中的一个。如果想安装 example，也可以使用 --example 参数。

当这个包已经被安装，但看起来并不是最新版本时，Cargo 会重新安装它。如果以下的任何一个值发生改变，Cargo 就会重新安装该包:

包的版本或者安装源
安装的二进制程序的名字集合
选择的特性(features)
编译配置 (--profile).
编译目标 (--target).

使用 --path 时总会重新进行构建和安装，除非与其他包的程序发生了冲突。 --force 标志可以强制命令 Cargo 重新安装一个包。

从 crates.io 或 git 仓库进行安装时，会默认在一个临时文件夹中构建该crate。如果要改变这种行为，可以设置 CARGO_TARGET_DIR 环境变量为一个相对路径 (译者注：经测试，这个相对路径是相对于执行 cargo install 命令的路径(cwd)，构建过程产生的文件会存在该目录中，而可执行文件还是会放到 bin 目录下)。这在持续集成中缓存(cache) 构建文件尤其有用。

默认情况下，包自带的 Cargo.lock 文件会被忽略，这意味着 Cargo 会重新计算使用依赖的版本，很有可能使用到比发布该包时更新的依赖版本。可以使用 --locked 标志来强制要求 Cargo 使用包自带的 Cargo.lock (如果可行的话)。这对于保证构建的可重复性很有用，因为使用的是这个包发布时的那些保证可用的依赖版本。另一个有用之处在于该包发布后可能有某些依赖更新版本导致该包无法构建，或者依赖更新后出了问题，使用 --locked 可以避免这些麻烦。缺点就是你无法使用到依赖的任何修复或功能更新了。注意，Cargo 直到 1.37 版本才开始允许发布 Cargo.lock ，这意味着这之前发布的包中没有 Cargo.lock。

选项

安装选项

--vers version
--version version: 指定安装的版本。可以是一个版本请求，比如 ~1.2，使Cargo选择满足请求的最新版本。如果版本中没有操作符 (比如 ^ 或 ~)，那么格式必须为 MAJOR.MINOR.PATCH, 从而安装精确的版本；这个行为和Cargo toml文件中的版本请求不相同。
--git url: 被安装的 crate 的 Git URL。
--branch branch: 从 git 安装时使用的 branch。
--tag tag: 从 git 安装时使用的 tag。
--rev sha: 指定从git安装使用的具体commit。
--path path: 本地文件系统中 crate 的路径。
--list: 列出所有已安装的包及其版本信息。
-f
--force: 强行覆盖现有的 crate 或二进制文件，这可以用于已安装的二进制程序与另一个包的二进制程序重名时。如果你改变了系统中的某些东西 (比如 rustc 的版本)，想要以此重新进行构建该二进制程序，这个功能也会很有用。
--no-track: 默认情况下，Cargo 会使用root目录下的一个元数据文件来跟踪已安装的包。`--no-track` 这个标志告诉 Cargo 不要使用或创建该文件。使用该标志后，Cargo 会拒绝覆盖任何已存在的文件，除非使用了 --force 标志。同时这也使得Cargo无法防止同时进行多个 Cargo install 的并发调用
--bin name...: 仅安装指定的二进制程序。
--bins: 安装所有的二进制程序。
--example name...: 仅安装指定的 example。
--examples: 安装所有的 example。
--root dir: 将包安装到此文件夹。
--registry registry: 使用的注册机构 (registry) 的名字。注册机构定义在 Cargo config 文件中. 如果没有指定就使用默认的注册机构，其定义在 registry.default 字段中，该值的默认值为 crates-io 。
--index index: 使用的注册机构的 index 地址。

选择 feature

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

查看 features 文档获取更多信息。

-F features
--features features: 用空格或逗号来分隔多个启用的 feature。工作空间成员的 feature 可以通过 package-name/feature-name 语法来启用。该标志可以设置多次，最终将启用指定的所有 feature 。
--all-features: 启用指定包的所有可用 feature。
--no-default-features: 不使用指定包的 default feature 。

编译选项

--target triple

为指定的架构安装，默认情况下是宿主架构。通常的架构三元组格式为 <arch><sub>-<vendor>-<sys>-<abi>。运行 rustc --print target-list 可以获取所有支持的架构的列表。

也可以通过 build.target 配置。

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

--target-dir directory

存放构建产物和中间文件的文件夹。也可以用 CARGO_TARGET_DIR 环境变量来设置，或者 build.target-dir 设置选项。默认会放在该平台的的临时文件夹下。

当使用 --path 标志时，默认会放在该本地crate的工作空间的 target 文件夹中，除非明确指定了 --target-dir 。

--debug

构建 dev profile 而不是 release profile。另见 --profile 选项，可以用名字来指定一个 profile。

--profile name

根据所给的 profile 进行安装。参考 the reference 查看关于 profile 的更多信息。

--timings=fmts

输出编译所花费时间的信息，同时跟踪并发信息。接收一个由逗号分隔的输出格式；若 --timings 没有参数，则默认使用 --timings=html。指定输出格式 (而不是使用默认格式) 是不稳定 (unstable) 的，需要设置 -Zunstable-options。可用的输出格式选项有:

html (不稳定，需要 -Zunstable-options): 写入一个人类可读的 cargo-timing.html 文件到 target/cargo-timings 文件夹，其中包含关于编译过程的报告。同时也会写入一个文件名带着时间戳 (timestamp) 的报告文件，可以让你读取之前的编译报告。HTML 输出文件只适合人类阅读，不提供机器所需的 timing 数据。
json (不稳定，需要 -Zunstable-options): 生成机器可读的 JSON timing 信息。

清单选项

--frozen

--locked

这两个 flag 都需要 Cargo.lock 文件处于无需更新的状态。如果 lock 文件缺失，或者需要被更新，Cargo 会报错退出。 --frozen flag 还会阻止 Cargo 访问网络来判断 Cargo.lock 是否过期。

这些 flag 可以用于某些场景下你想断言 Cargo.lock 无需更新 (比如在CI中构建) 或者避免网络访问。

--offline

阻止 Cargo 访问网络。如果没有这个 flag，当 Cargo 需要访问网络但是没有网络时，就会报错退出。加上这个 flag，Cargo 会尝试在不联网的情况下继续执行 (如果可以的话) 。

要小心这会导致与在线模式不同的解析结果。Cargo 会限制自己在本地已下载的 crate 中查找版本，即使在本地的 index 拷贝中表明还有更新的版本。 cargo-fetch(1) 命令可以在进入离线模式前下载依赖。

同样的功能也可以通过设置 net.offline 配置。

杂项

-j N
--jobs N: 并行执行的任务数。可以通过 build.jobs 配置。默认值为逻辑CPU数。如果设置为负值，则最大的并行任务数为*逻辑CPU数*加*这个负数*。该值不能为0。
--keep-going: 依赖图中的 crate 能构建多少就构建多少，而不是一个失败就停止。功能还不稳定，需要 -Zunstable-options。

显示选项

-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: 将 JSON 信息输出到 stdout。从 the reference 获取更多详细信息。与 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 一起使用。

通用选项

+toolchain: 如果 Cargo 由 rustup 安装，那么 cargo 后第一个以 + 开头的参数会被认为是 rustup toolchain 名字(例如 +stable 或 +nightly)。查看 rustup documentation 了解 toolchain overrides 如何工作。
--config KEY=VALUE or PATH: 覆盖一个 Cargo 配置的值。参数应该是一个 TOML 语法的 KEY=VALUE，或者提供一个路径来指向一个额外的配置文件 (configuration file)。这个标记可以指定多次。参考 command-line overrides 一节获取更多信息。
-h
--help: 打印帮助信息。
-Z flag: 不稳定 (nightly-only) 的标志。执行 cargo -Z help 获取详细信息。