cargo-tree(1)

名称

cargo-tree — 显示依赖关系图的树状可视化

概要

cargo tree [选项]

描述

此命令将在终端显示依赖关系的树状图。一个依赖于“rand”包的简单项目的示例

myproject v0.1.0 (/myproject)
└── rand v0.7.3
    ├── getrandom v0.1.14
    │   ├── cfg-if v0.1.10
    │   └── libc v0.2.68
    ├── libc v0.2.68 (*)
    ├── rand_chacha v0.2.2
    │   ├── ppv-lite86 v0.2.6
    │   └── rand_core v0.5.1
    │       └── getrandom v0.1.14 (*)
    └── rand_core v0.5.1 (*)
[build-dependencies]
└── cc v1.0.50

标记为 (*) 的包已被“去重”。该包的依赖项已在图中的其他位置显示，因此不再重复。使用 --no-dedupe 选项来重复显示重复项。

-e 标志可用于选择要显示的依赖关系类型。“features”类型将输出更改为显示每个依赖项启用的功能。例如，cargo tree -e features

myproject v0.1.0 (/myproject)
└── log feature "serde"
    └── log v0.4.8
        ├── serde v1.0.106
        └── cfg-if feature "default"
            └── cfg-if v0.1.10

在此树中，myproject 依赖于具有 serde 功能的 log。log 又依赖于具有“default”功能的 cfg-if。当使用 -e features 时，使用 -i 标志显示功能如何流入包会很有帮助。有关更多详细信息，请参见以下示例。

功能统一

此命令显示的图更接近 Cargo 将构建的功能统一图，而不是您在 Cargo.toml 中列出的图。例如，如果您在 [dependencies] 和 [dev-dependencies] 中指定相同的依赖项，但具有不同的功能。此命令可能会合并所有功能并在其中一个依赖项上显示 (*) 以指示重复项。

因此，对于 cargo build 所做的事情的大致等效概述，cargo tree -e normal,build 非常接近；对于 cargo test 所做的事情的大致等效概述，cargo tree 非常接近。但是，它不能保证与 Cargo 将要构建的确切等效性，因为编译很复杂并且取决于许多不同的因素。

要了解有关功能统一的更多信息，请查看此专用部分。

选项

树选项

-i spec

--invert spec

显示给定包的反向依赖关系。此标志将反转树并显示依赖于给定包的包。

请注意，在工作区中，默认情况下它只会显示当前目录中工作区成员树内的包的反向依赖关系。--workspace 标志可用于扩展它，以便它将显示整个工作区中包的反向依赖关系。-p 标志可用于仅显示给定给 -p 的包子树中包的反向依赖关系。

--prune spec

从依赖关系树的显示中修剪给定的包。

--depth depth

依赖关系树的最大显示深度。例如，深度为 1 时显示直接依赖关系。

--no-dedupe

不要去重复重复的依赖项。通常，当一个包已经显示了它的依赖项时，进一步的出现将不会重新显示它的依赖项，并且将包括一个 (*) 来指示它已经被显示。此标志将导致重复项被重复。

-d

--duplicates

仅显示以多个版本出现的依赖项（隐含 --invert）。当与 -p 标志一起使用时，仅显示给定包子树中的重复项。

避免多次构建同一个包对于构建时间和可执行文件大小是有益的。此标志可以帮助识别有问题的包。然后，您可以调查是否可以将依赖于旧版本的重复项的包更新到较新的版本，以便只构建一个实例。

-e kinds

--edges kinds

要显示的依赖关系类型。接受一个以逗号分隔的值列表

• all — 显示所有边缘类型。
• normal — 显示普通依赖项。
• build — 显示构建依赖项。
• dev — 显示开发依赖项。
• features — 显示每个依赖项启用的功能。如果这是唯一给定的类型，那么它将自动包含其他依赖项类型。
• no-normal — 不包括普通依赖项。
• no-build — 不包括构建依赖项。
• no-dev — 不包括开发依赖项。
• no-proc-macro — 不包括过程宏依赖项。

normal、build、dev 和 all 依赖项类型不能与 no-normal、no-build 或 no-dev 依赖项类型混合使用。

默认值为 normal,build,dev。

--target triple

筛选匹配给定目标三元组的依赖项。默认值是主机平台。使用值 all 来包含所有目标。

树格式选项

--charset charset

选择用于树的字符集。有效值为“utf8”或“ascii”。如果未指定，cargo 将自动选择一个值。

-f format

--format format

设置每个包的格式字符串。默认值为“{p}”。

这是一个任意字符串，它将用于显示每个包。以下字符串将被替换为相应的值

• {p} — 包名称。
• {l} — 包许可证。
• {r} — 包存储库 URL。
• {f} — 以逗号分隔的已启用包功能列表。
• {lib} — 包的库的名称，如在 use 语句中使用。

--prefix prefix

设置每行如何显示。prefix 值可以是以下之一

• indent（默认）— 将每行显示为缩进的树。
• depth — 显示为列表，并在每个条目之前打印数字深度。
• none — 显示为平面列表。

包选择

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

可以使用根清单中的 workspace.default-members 键显式设置工作区的默认成员。如果未设置此项，虚拟工作区将包括所有工作区成员（等效于传递 --workspace），非虚拟工作区将只包括根 crate 本身。

-p spec…

--package spec…

仅显示指定的包。有关 SPEC 格式，请参阅 cargo-pkgid(1)。此标志可以多次指定，并支持常见的 Unix glob 模式，如 *、? 和 []。但是，为了避免 shell 在 Cargo 处理 glob 模式之前意外地扩展它们，您必须在每个模式周围使用单引号或双引号。

--workspace

显示工作区中的所有成员。

--exclude SPEC…

排除指定的包。必须与 --workspace 标志一起使用。此标志可以多次指定，并支持常见的 Unix glob 模式，如 *、? 和 []。但是，为了避免 shell 在 Cargo 处理 glob 模式之前意外地扩展它们，您必须在每个模式周围使用单引号或双引号。

清单选项

--manifest-path path

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

--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 channel 上可用，并且需要使用 -Z unstable-options 标志启用（请参阅 #14421）。

功能选择

特性标记允许您控制启用哪些特性。当没有给出特性选项时，将为每个选定的包激活default特性。

有关更多详细信息，请参阅特性文档。

-F 特性

--features 特性

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

--all-features

激活所有选定包的所有可用特性。

--no-default-features

不激活选定包的 default 特性。

显示选项

-v

--verbose

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

-q

--quiet

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

--color when

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

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

也可以使用 term.color 配置值指定。

常用选项

+工具链

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

--config KEY=VALUE 或 PATH

覆盖 Cargo 配置值。参数应采用 KEY=VALUE 的 TOML 语法，或者作为指向额外配置文件的路径提供。此标志可以指定多次。有关更多信息，请参阅命令行覆盖部分。

-C PATH

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

此选项仅在 nightly channel 上可用，并且需要 -Z unstable-options 标志才能启用（请参阅#10098）。

-h

--help

打印帮助信息。

-Z flag

Cargo 的不稳定（仅限 nightly）标志。运行 cargo -Z help 以获取详细信息。

环境变量

有关 Cargo 读取的环境变量的详细信息，请参阅参考文档。

退出状态

• 0：Cargo 成功。
• 101：Cargo 未能完成。

示例

1. 显示当前目录中包的树状结构

   cargo tree
   

2. 显示所有依赖于 syn 包的包

   cargo tree -i syn
   

3. 显示每个包上启用的特性

   cargo tree --format "{p} {f}"
   

4. 显示所有多次构建的包。如果树中出现多个 semver 不兼容的版本（如 1.0.0 和 2.0.0），则会发生这种情况。

   cargo tree -d
   

5. 解释为什么为 syn 包启用特性

   cargo tree -e features -i syn
   

   -e features 标志用于显示特性。-i 标志用于反转图，以便它显示依赖于 syn 的包。以下是它将显示的内容示例

   syn v1.0.17
   ├── syn feature "clone-impls"
   │   └── syn feature "default"
   │       └── rustversion v1.0.2
   │           └── rustversion feature "default"
   │               └── myproject v0.1.0 (/myproject)
   │                   └── myproject feature "default" (command-line)
   ├── syn feature "default" (*)
   ├── syn feature "derive"
   │   └── syn feature "default" (*)
   ├── syn feature "full"
   │   └── rustversion v1.0.2 (*)
   ├── syn feature "parsing"
   │   └── syn feature "default" (*)
   ├── syn feature "printing"
   │   └── syn feature "default" (*)
   ├── syn feature "proc-macro"
   │   └── syn feature "default" (*)
   └── syn feature "quote"
       ├── syn feature "printing" (*)
       └── syn feature "proc-macro" (*)
   

   要读取此图，您可以按照每个特性的链从根目录查看它包含的原因。例如，“full”特性由 rustversion crate 添加，该 crate 从 myproject 包含（具有默认特性），而 myproject 是命令行上选择的包。所有其他 syn 特性都由“default”特性添加（“quote”由“printing”和“proc-macro”添加，两者都是默认特性）。

   如果您在交叉引用重复的 (*) 条目时遇到困难，请尝试使用 --no-dedupe 标志以获取完整输出。

另请参阅

cargo(1)，cargo-metadata(1)