mirror of https://github.com/rust-lang/cargo
402 lines
17 KiB
Plaintext
402 lines
17 KiB
Plaintext
CARGO-TREE(1)
|
||
|
||
NAME
|
||
cargo-tree — Display a tree visualization of a dependency graph
|
||
|
||
SYNOPSIS
|
||
cargo tree [options]
|
||
|
||
DESCRIPTION
|
||
This command will display a tree of dependencies to the terminal. An
|
||
example of a simple project that depends on the “rand” package:
|
||
|
||
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
|
||
|
||
Packages marked with (*) have been “de-duplicated”. The dependencies
|
||
for the package have already been shown elsewhere in the graph, and so
|
||
are not repeated. Use the --no-dedupe option to repeat the duplicates.
|
||
|
||
The -e flag can be used to select the dependency kinds to display. The
|
||
“features” kind changes the output to display the features enabled
|
||
by each dependency. For example, 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
|
||
|
||
In this tree, myproject depends on log with the serde feature. log in
|
||
turn depends on cfg-if with “default” features. When using -e
|
||
features it can be helpful to use -i flag to show how the features flow
|
||
into a package. See the examples below for more detail.
|
||
|
||
Feature Unification
|
||
This command shows a graph much closer to a feature-unified graph Cargo
|
||
will build, rather than what you list in Cargo.toml. For instance, if
|
||
you specify the same dependency in both [dependencies] and
|
||
[dev-dependencies] but with different features on. This command may
|
||
merge all features and show a (*) on one of the dependency to indicate
|
||
the duplicate.
|
||
|
||
As a result, for a mostly equivalent overview of what cargo build does,
|
||
cargo tree -e normal,build is pretty close; for a mostly equivalent
|
||
overview of what cargo test does, cargo tree is pretty close. However,
|
||
it doesn’t guarantee the exact equivalence to what Cargo is going to
|
||
build, since a compilation is complex and depends on lots of different
|
||
factors.
|
||
|
||
To learn more about feature unification, check out this dedicated
|
||
section
|
||
<https://doc.rust-lang.org/cargo/reference/features.html#feature-unification>.
|
||
|
||
OPTIONS
|
||
Tree Options
|
||
-i spec, --invert spec
|
||
Show the reverse dependencies for the given package. This flag will
|
||
invert the tree and display the packages that depend on the given
|
||
package.
|
||
|
||
Note that in a workspace, by default it will only display the
|
||
package’s reverse dependencies inside the tree of the workspace
|
||
member in the current directory. The --workspace flag can be used to
|
||
extend it so that it will show the package’s reverse dependencies
|
||
across the entire workspace. The -p flag can be used to display the
|
||
package’s reverse dependencies only with the subtree of the
|
||
package given to -p.
|
||
|
||
--prune spec
|
||
Prune the given package from the display of the dependency tree.
|
||
|
||
--depth depth
|
||
Maximum display depth of the dependency tree. A depth of 1 displays
|
||
the direct dependencies, for example.
|
||
|
||
--no-dedupe
|
||
Do not de-duplicate repeated dependencies. Usually, when a package
|
||
has already displayed its dependencies, further occurrences will not
|
||
re-display its dependencies, and will include a (*) to indicate it
|
||
has already been shown. This flag will cause those duplicates to be
|
||
repeated.
|
||
|
||
-d, --duplicates
|
||
Show only dependencies which come in multiple versions (implies
|
||
--invert). When used with the -p flag, only shows duplicates within
|
||
the subtree of the given package.
|
||
|
||
It can be beneficial for build times and executable sizes to avoid
|
||
building that same package multiple times. This flag can help
|
||
identify the offending packages. You can then investigate if the
|
||
package that depends on the duplicate with the older version can be
|
||
updated to the newer version so that only one instance is built.
|
||
|
||
-e kinds, --edges kinds
|
||
The dependency kinds to display. Takes a comma separated list of
|
||
values:
|
||
|
||
o all — Show all edge kinds.
|
||
|
||
o normal — Show normal dependencies.
|
||
|
||
o build — Show build dependencies.
|
||
|
||
o dev — Show development dependencies.
|
||
|
||
o features — Show features enabled by each dependency. If this is
|
||
the only kind given, then it will automatically include the other
|
||
dependency kinds.
|
||
|
||
o no-normal — Do not include normal dependencies.
|
||
|
||
o no-build — Do not include build dependencies.
|
||
|
||
o no-dev — Do not include development dependencies.
|
||
|
||
o no-proc-macro — Do not include procedural macro dependencies.
|
||
|
||
The normal, build, dev, and all dependency kinds cannot be mixed
|
||
with no-normal, no-build, or no-dev dependency kinds.
|
||
|
||
The default is normal,build,dev.
|
||
|
||
--target triple
|
||
Filter dependencies matching the given target triple
|
||
<https://doc.rust-lang.org/cargo/appendix/glossary.html#target>. The
|
||
default is the host platform. Use the value all to include all
|
||
targets.
|
||
|
||
Tree Formatting Options
|
||
--charset charset
|
||
Chooses the character set to use for the tree. Valid values are
|
||
“utf8” or “ascii”. When unspecified, cargo will auto-select
|
||
a value.
|
||
|
||
-f format, --format format
|
||
Set the format string for each package. The default is “{p}”.
|
||
|
||
This is an arbitrary string which will be used to display each
|
||
package. The following strings will be replaced with the
|
||
corresponding value:
|
||
|
||
o {p} — The package name.
|
||
|
||
o {l} — The package license.
|
||
|
||
o {r} — The package repository URL.
|
||
|
||
o {f} — Comma-separated list of package features that are
|
||
enabled.
|
||
|
||
o {lib} — The name, as used in a use statement, of the
|
||
package’s library.
|
||
|
||
--prefix prefix
|
||
Sets how each line is displayed. The prefix value can be one of:
|
||
|
||
o indent (default) — Shows each line indented as a tree.
|
||
|
||
o depth — Show as a list, with the numeric depth printed before
|
||
each entry.
|
||
|
||
o none — Show as a flat list.
|
||
|
||
Package Selection
|
||
By default, when no package selection options are given, the packages
|
||
selected depend on the selected manifest file (based on the current
|
||
working directory if --manifest-path is not given). If the manifest is
|
||
the root of a workspace then the workspaces default members are
|
||
selected, otherwise only the package defined by the manifest will be
|
||
selected.
|
||
|
||
The default members of a workspace can be set explicitly with the
|
||
workspace.default-members key in the root manifest. If this is not set,
|
||
a virtual workspace will include all workspace members (equivalent to
|
||
passing --workspace), and a non-virtual workspace will include only the
|
||
root crate itself.
|
||
|
||
-p spec…, --package spec…
|
||
Display only the specified packages. See cargo-pkgid(1) for the SPEC
|
||
format. This flag may be specified multiple times and supports
|
||
common Unix glob patterns like *, ? and []. However, to avoid your
|
||
shell accidentally expanding glob patterns before Cargo handles
|
||
them, you must use single quotes or double quotes around each
|
||
pattern.
|
||
|
||
--workspace
|
||
Display all members in the workspace.
|
||
|
||
--exclude SPEC…
|
||
Exclude the specified packages. Must be used in conjunction with the
|
||
--workspace flag. This flag may be specified multiple times and
|
||
supports common Unix glob patterns like *, ? and []. However, to
|
||
avoid your shell accidentally expanding glob patterns before Cargo
|
||
handles them, you must use single quotes or double quotes around
|
||
each pattern.
|
||
|
||
Manifest Options
|
||
--manifest-path path
|
||
Path to the Cargo.toml file. By default, Cargo searches for the
|
||
Cargo.toml file in the current directory or any parent directory.
|
||
|
||
--locked
|
||
Ensures that Cargo uses the exact version of every dependency
|
||
captured in the existing Cargo.lock file. Cargo will exit with an
|
||
error when either of the following scenarios arises:
|
||
|
||
o The lock file is missing.
|
||
|
||
o The dependency resolution has changed, often caused by modifying
|
||
dependencies in the Cargo.toml file.
|
||
|
||
It may be used in environments where you want to assert that the
|
||
Cargo.lock file is up-to-date for reproducibility reasons, such as
|
||
in a CI build.
|
||
|
||
--offline
|
||
Prevents Cargo from accessing the network for any reason. Without
|
||
this flag, Cargo will stop with an error if it needs to access the
|
||
network and the network is not available. With this flag, Cargo will
|
||
attempt to proceed without the network if possible.
|
||
|
||
Beware that this may result in different dependency resolution than
|
||
online mode. Cargo will restrict itself to crates that are
|
||
downloaded locally, even if there might be a newer version as
|
||
indicated in the local copy of the index. See the cargo-fetch(1)
|
||
command to download dependencies before going offline.
|
||
|
||
May also be specified with the net.offline config value
|
||
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
||
|
||
--frozen
|
||
Equivalent to specifying both --locked and --offline.
|
||
|
||
Feature Selection
|
||
The feature flags allow you to control which features are enabled. When
|
||
no feature options are given, the default feature is activated for every
|
||
selected package.
|
||
|
||
See the features documentation
|
||
<https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
|
||
for more details.
|
||
|
||
-F features, --features features
|
||
Space or comma separated list of features to activate. Features of
|
||
workspace members may be enabled with package-name/feature-name
|
||
syntax. This flag may be specified multiple times, which enables all
|
||
specified features.
|
||
|
||
--all-features
|
||
Activate all available features of all selected packages.
|
||
|
||
--no-default-features
|
||
Do not activate the default feature of the selected packages.
|
||
|
||
Display Options
|
||
-v, --verbose
|
||
Use verbose output. May be specified twice for “very verbose”
|
||
output which includes extra output such as dependency warnings and
|
||
build script output. May also be specified with the term.verbose
|
||
config value
|
||
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
||
|
||
-q, --quiet
|
||
Do not print cargo log messages. May also be specified with the
|
||
term.quiet config value
|
||
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
||
|
||
--color when
|
||
Control when colored output is used. Valid values:
|
||
|
||
o auto (default): Automatically detect if color support is
|
||
available on the terminal.
|
||
|
||
o always: Always display colors.
|
||
|
||
o never: Never display colors.
|
||
|
||
May also be specified with the term.color config value
|
||
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
||
|
||
Common Options
|
||
+toolchain
|
||
If Cargo has been installed with rustup, and the first argument to
|
||
cargo begins with +, it will be interpreted as a rustup toolchain
|
||
name (such as +stable or +nightly). See the rustup documentation
|
||
<https://rust-lang.github.io/rustup/overrides.html> for more
|
||
information about how toolchain overrides work.
|
||
|
||
--config KEY=VALUE or PATH
|
||
Overrides a Cargo configuration value. The argument should be in
|
||
TOML syntax of KEY=VALUE, or provided as a path to an extra
|
||
configuration file. This flag may be specified multiple times. See
|
||
the command-line overrides section
|
||
<https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
|
||
for more information.
|
||
|
||
-C PATH
|
||
Changes the current working directory before executing any specified
|
||
operations. This affects things like where cargo looks by default
|
||
for the project manifest (Cargo.toml), as well as the directories
|
||
searched for discovering .cargo/config.toml, for example. This
|
||
option must appear before the command name, for example cargo -C
|
||
path/to/my-project build.
|
||
|
||
This option is only available on the nightly channel
|
||
<https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
|
||
requires the -Z unstable-options flag to enable (see #10098
|
||
<https://github.com/rust-lang/cargo/issues/10098>).
|
||
|
||
-h, --help
|
||
Prints help information.
|
||
|
||
-Z flag
|
||
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
|
||
details.
|
||
|
||
ENVIRONMENT
|
||
See the reference
|
||
<https://doc.rust-lang.org/cargo/reference/environment-variables.html>
|
||
for details on environment variables that Cargo reads.
|
||
|
||
EXIT STATUS
|
||
o 0: Cargo succeeded.
|
||
|
||
o 101: Cargo failed to complete.
|
||
|
||
EXAMPLES
|
||
1. Display the tree for the package in the current directory:
|
||
|
||
cargo tree
|
||
|
||
2. Display all the packages that depend on the syn package:
|
||
|
||
cargo tree -i syn
|
||
|
||
3. Show the features enabled on each package:
|
||
|
||
cargo tree --format "{p} {f}"
|
||
|
||
4. Show all packages that are built multiple times. This can happen if
|
||
multiple semver-incompatible versions appear in the tree (like 1.0.0
|
||
and 2.0.0).
|
||
|
||
cargo tree -d
|
||
|
||
5. Explain why features are enabled for the syn package:
|
||
|
||
cargo tree -e features -i syn
|
||
|
||
The -e features flag is used to show features. The -i flag is used to
|
||
invert the graph so that it displays the packages that depend on syn.
|
||
An example of what this would display:
|
||
|
||
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" (*)
|
||
|
||
To read this graph, you can follow the chain for each feature from
|
||
the root to see why it is included. For example, the “full”
|
||
feature is added by the rustversion crate which is included from
|
||
myproject (with the default features), and myproject is the package
|
||
selected on the command-line. All of the other syn features are added
|
||
by the “default” feature (“quote” is added by “printing”
|
||
and “proc-macro”, both of which are default features).
|
||
|
||
If you’re having difficulty cross-referencing the de-duplicated (*)
|
||
entries, try with the --no-dedupe flag to get the full output.
|
||
|
||
SEE ALSO
|
||
cargo(1), cargo-metadata(1)
|
||
|