cargo-doc(1)

名称

cargo-doc - 为包构建文档

概要

cargo doc [options]

描述

构建本地的包及其依赖的文档。输出以 rustdoc 的通常格式存放在 target/doc 路径下。

选项

文档选项

--open

构建完成后在浏览器中打开文档。这会使用到你的默认浏览器，除非你在 BROWSER 环境变量中指定其他的。 或者可以使用 doc.browser 设置选项来设置。

--no-deps

不为依赖构建文档。

--document-private-items

文档中包含非 Public 的语法元素(Rust item)。这会在二进制目标中默认启用。

包的选择

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

可以通过 workspace.default-members 来显式设置工作空间的默认成员。如果没有设置，在虚拟工作空间下会选择所有的成员，在非虚拟工作空间下仅会选择根 package 。

-p spec...

--package spec...

仅为指定的 package 构建文档。 见 cargo-pkgid(1) 中关于 SPEC 格式的描述。此标志可以指定多次，而且支持 common Unix glob patterns ，如 *， ? 和 []。但是，为避免你的 shell 误在 Cargo 之前扩展这些 glob pattern，必须用单引号或双引号将每个 pattern 括起来。

--workspace

为工作空间中的所有成员构建文档。

--all

--workspace 的同义词，已弃用。

--exclude SPEC...

排除指定的包。必须与 --workspace 标志一起使用。 此标志可以指定多次，而且支持 common Unix glob patterns ，如 *， ? 和 []。但是，为避免你的 shell 误在 Cargo 之前扩展这些 glob pattern，必须用单引号或双引号将每个 pattern 括起来。

目标选择

当没有提供目标选择选项， cargo doc 会为所选包的所有二进制和库目标构建文档。如果二进制目标的名字和库目标相同，则二进制目标会被跳过。如果二进制有丢失的 required-features ，则也会被跳过。

可以通过在清单文件中为 target 设置 doc = false 来改变默认行为。使用目标选择选项时会忽略 doc 标志，并且总会为所提供的目标构建文档。

--lib

为该包的库构建文档。

--bin name...

为特定的二进制构建文档。这个标志可以指定多次，而且支持 common Unix glob patterns。

--bins

为所有的二进制目标构建文档。

--example name...

为特定的 example 构建文档。这个标志可以指定多次，而且支持 common Unix glob patterns。

--examples

为所有的 example 目标构建文档。

feature 选择

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

查看 the features documentation 获取更多信息。

-F features

--features features

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

--all-features

启用指定包的所有可用 feature。

--no-default-features

不使用指定包的 default feature 。

编译选项

--target triple

为指定的架构而构建文档，默认为宿主架构。triple 的格式为 <arch><sub>-<vendor>-<sys>-<abi>。 执行 rustc --print target-list 可以展示支持的 target 的列表。该标志可以指定多次。

也可以通过 build.target 配置。

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

-r

--release

为使用 release profile 优化的产物构建文档。 另见 --profile 选项来按名称选择特定的 profile。

--profile name

用给定的 profile 构建文档。 见 the reference 查看关于 profile 的详细内容。

--ignore-rust-version

即使选择的 Rust 编译器版本落后于项目 rust-version 字段中指定的版本，也为其构建文档。

--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 信息。

输出选项

--target-dir directory

存放构建产物和中间文件的文件夹。也可以用 CARGO_TARGET_DIR 环境变量来设置，或者 build.target-dir 设置选项。默认会放在工作空间根目录的 target 子目录下。

显示选项

-v

--verbose

进行 verbose 输出。可以指定两遍来开启 "very verbose" 模式，输出更多的额外信息，像是依赖项的警告和构建脚本的输出信息。 也可以通过 term.verbose 配置 。

-q

--quiet

不打印 cargo log 信息。 也可以通过 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 一起使用。

清单选项

--manifest-path path

Cargo.toml 文件的路径。 默认情况下，Cargo 在当前目录或任意的父目录中查找 Cargo.toml 。

--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 配置选项来实现。

通用选项

+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 获取详细信息。

杂项

-j N

--jobs N

并行执行的任务数。可以通过 build.jobs 配置。默认值为逻辑CPU数。如果设置为负值，则最大的并行任务数为*逻辑CPU数*加*这个负数*。该值不能为0。

--keep-going

依赖图中的 crate 能构建多少就构建多少，而不是一个失败就停止。功能还不稳定，需要 -Zunstable-options。

环境

查看 the reference 获取 Cargo 读取的环境变量的更多信息。

退出状态

• 0: Cargo 执行成功。
• 101: Cargo 没有执行完成。

使用案例

1. 为本地包及其依赖构建文档，输出放在 target/doc 。

   cargo doc
   

其他参考

cargo(1), cargo-rustdoc(1), rustdoc(1)