cargo-doc(1)

描述

构建本地包及其所有依赖项的文档。输出文件会按照 rustdoc 的常规格式放置在 target/doc 目录中。

选项

文档选项

--open: 构建完成后，在浏览器中打开文档。除非您在 BROWSER 环境变量中定义了其他浏览器或使用了 doc.browser 配置项，否则将使用您的默认浏览器。
--no-deps: 不构建依赖项的文档。
--document-private-items: 在文档中包含非公共项。如果正在为二进制目标构建文档，此选项默认启用。

包选择

默认情况下，未提供包选择选项时，所选包取决于选定的清单文件（如果未给出 --manifest-path，则基于当前工作目录）。如果清单是工作空间的根目录，则选择工作空间的默认成员；否则，只选择清单定义的包。

工作空间的默认成员可以在根清单中通过 workspace.default-members 键显式设置。如果未设置此项，虚拟工作空间将包含所有工作空间成员（相当于传递 --workspace），非虚拟工作空间将只包含根 crate 本身。

-p spec…
--package spec…: 仅为指定的包构建文档。SPEC 格式请参见 cargo-pkgid(1)。此标志可以多次指定，并支持常见的 Unix glob 模式，如 *、? 和 []。但是，为了避免 shell 在 Cargo 处理之前意外展开 glob 模式，您必须在每个模式周围使用单引号或双引号。
--workspace: 为工作空间中的所有成员构建文档。
--all: --workspace 的已弃用别名。
--exclude SPEC…: 排除指定的包。必须与 --workspace 标志一起使用。此标志可以多次指定，并支持常见的 Unix glob 模式，如 *、? 和 []。但是，为了避免 shell 在 Cargo 处理之前意外展开 glob 模式，您必须在每个模式周围使用单引号或双引号。

目标选择

未提供目标选择选项时，cargo doc 将为所选包的所有二进制和库目标构建文档。如果二进制文件的名称与 lib 目标相同，则会跳过该二进制文件。如果二进制文件缺少 required-features，则会跳过构建。

可以通过在清单设置中为目标设置 doc = false 来更改默认行为。使用目标选择选项将忽略 doc 标志，并始终为给定的目标构建文档。

--lib: 为包的库构建文档。
--bin name…: 为指定的二进制文件构建文档。此标志可以多次指定，并支持常见的 Unix glob 模式。
--bins: 为所有二进制目标构建文档。
--example name…: 为指定的示例构建文档。此标志可以多次指定，并支持常见的 Unix glob 模式。
--examples: 为所有示例目标构建文档。

特性选择

特性标志允许您控制启用哪些特性。未提供特性选项时，将为每个选定的包激活 default 特性。

更多详情请参见特性文档。

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

编译选项

--target triple

为给定的架构构建文档。默认是主机架构。triple 的通用格式是 <arch><sub>-<vendor>-<sys>-<abi>。运行 rustc --print target-list 可以查看支持的目标列表。此标志可以多次指定。

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

请注意，指定此标志会使 Cargo 在不同的模式下运行，目标工件会放在单独的目录中。更多详情请参见构建缓存文档。

-r

--release

使用 release 配置构建优化工件的文档。有关按名称选择特定配置文件的信息，另请参见 --profile 选项。

--profile name

使用给定的配置文件构建文档。有关配置文件的更多详情请参见参考手册。

--timings=fmts

输出每个编译耗时以及跟踪并发信息。接受一个可选的逗号分隔的输出格式列表；不带参数的 --timings 将默认为 --timings=html。指定（非默认的）输出格式是不稳定的，需要 -Zunstable-options。有效输出格式：

html（不稳定，需要 -Zunstable-options）：将人类可读的编译报告文件 cargo-timing.html 写入 target/cargo-timings 目录。如果想查看旧的运行结果，也会在同一目录下写入一个带时间戳文件名的报告。HTML 输出仅适用于人工阅读，不提供机器可读的计时数据。
json（不稳定，需要 -Zunstable-options）：输出机器可读的 JSON 格式计时信息。

输出选项

--target-dir 目录: 所有生成的工件和中间文件的目录。也可以通过 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置值指定。默认为工作空间根目录下的 target。

显示选项

-v

--verbose

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

-q

--quiet

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

--color 何时

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

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

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

--message-format 格式

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

human（默认）：以人类可读的文本格式显示。与 short 和 json 冲突。
short：输出更短、人类可读的文本消息。与 human 和 json 冲突。
json：向标准输出发送 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 一起使用。

清单选项

--manifest-path 路径

Cargo.toml 文件的路径。默认情况下，Cargo 会在当前目录或任何父目录中搜索 Cargo.toml 文件。

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

--lockfile-path PATH

将锁文件的路径从默认路径 (<workspace_root>/Cargo.lock) 更改为 PATH。PATH 必须以 Cargo.lock 结尾（例如 --lockfile-path /tmp/temporary-lockfile/Cargo.lock）。请注意，提供 --lockfile-path 将忽略默认路径下现有的锁文件，而是使用 PATH 中的锁文件，或者如果 PATH 不存在则写入新的锁文件。此标志可用于在只读目录中运行大多数命令，并将锁文件写入提供的 PATH。

此选项仅在 nightly 版本中可用，并且需要启用 -Z unstable-options 标志（参见 #14421）。

通用选项

+工具链

如果 Cargo 是通过 rustup 安装的，并且 cargo 的第一个参数以 + 开头，则会被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。有关工具链覆盖工作方式的更多信息，请参见 rustup 文档。

--config 键=值 或路径

覆盖 Cargo 配置值。参数应为 TOML 语法 键=值，或提供额外配置文件的路径。此标志可以多次指定。更多详情请参见命令行覆盖部分。

-C 路径

在执行任何指定操作之前更改当前工作目录。这会影响 Cargo 默认查找项目清单 (Cargo.toml) 的位置，以及搜索发现 .cargo/config.toml 的目录等。此选项必须出现在命令名称之前，例如 cargo -C path/to/my-project build。

此选项仅在 nightly 版本中可用，并且需要启用 -Z unstable-options 标志（参见 #10098）。

-h

--help

打印帮助信息。

-Z 标志

Cargo 的不稳定标志（仅 nightly 版本）。运行 cargo -Z help 查看详情。

杂项选项

-j N

--jobs N

并行运行的作业数量。也可以通过 build.jobs 配置值指定。默认为逻辑 CPU 数量。如果为负数，则将最大并行作业数设置为逻辑 CPU 数量加上提供的值。如果提供了字符串 default，则将值重置为默认值。不能为 0。

--keep-going

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

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