mirror of https://github.com/rust-lang/cargo
495 lines
16 KiB
Groff
495 lines
16 KiB
Groff
'\" t
|
|
.TH "CARGO\-TREE" "1"
|
|
.nh
|
|
.ad l
|
|
.ss \n[.ss] 0
|
|
.SH "NAME"
|
|
cargo\-tree \- Display a tree visualization of a dependency graph
|
|
.SH "SYNOPSIS"
|
|
\fBcargo tree\fR [\fIoptions\fR]
|
|
.SH "DESCRIPTION"
|
|
This command will display a tree of dependencies to the terminal. An example
|
|
of a simple project that depends on the "rand" package:
|
|
.sp
|
|
.RS 4
|
|
.nf
|
|
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
|
|
.fi
|
|
.RE
|
|
.sp
|
|
Packages marked with \fB(*)\fR have been "de\-duplicated". The dependencies for the
|
|
package have already been shown elsewhere in the graph, and so are not
|
|
repeated. Use the \fB\-\-no\-dedupe\fR option to repeat the duplicates.
|
|
.sp
|
|
The \fB\-e\fR 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, \fBcargo tree \-e features\fR:
|
|
.sp
|
|
.RS 4
|
|
.nf
|
|
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
|
|
.fi
|
|
.RE
|
|
.sp
|
|
In this tree, \fBmyproject\fR depends on \fBlog\fR with the \fBserde\fR feature. \fBlog\fR in
|
|
turn depends on \fBcfg\-if\fR with "default" features. When using \fB\-e features\fR it
|
|
can be helpful to use \fB\-i\fR flag to show how the features flow into a package.
|
|
See the examples below for more detail.
|
|
.SS "Feature Unification"
|
|
This command shows a graph much closer to a feature\-unified graph Cargo will
|
|
build, rather than what you list in \fBCargo.toml\fR\&. For instance, if you specify
|
|
the same dependency in both \fB[dependencies]\fR and \fB[dev\-dependencies]\fR but with
|
|
different features on. This command may merge all features and show a \fB(*)\fR on
|
|
one of the dependency to indicate the duplicate.
|
|
.sp
|
|
As a result, for a mostly equivalent overview of what \fBcargo build\fR does,
|
|
\fBcargo tree \-e normal,build\fR is pretty close; for a mostly equivalent overview
|
|
of what \fBcargo test\fR does, \fBcargo tree\fR 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.
|
|
.sp
|
|
To learn more about feature unification, check out this
|
|
\fIdedicated section\fR <https://doc.rust\-lang.org/cargo/reference/features.html#feature\-unification>\&.
|
|
.SH "OPTIONS"
|
|
.SS "Tree Options"
|
|
.sp
|
|
\fB\-i\fR \fIspec\fR,
|
|
\fB\-\-invert\fR \fIspec\fR
|
|
.RS 4
|
|
Show the reverse dependencies for the given package. This flag will invert
|
|
the tree and display the packages that depend on the given package.
|
|
.sp
|
|
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 \fB\-\-workspace\fR flag can be used to extend it so that it will
|
|
show the package's reverse dependencies across the entire workspace. The \fB\-p\fR
|
|
flag can be used to display the package's reverse dependencies only with the
|
|
subtree of the package given to \fB\-p\fR\&.
|
|
.RE
|
|
.sp
|
|
\fB\-\-prune\fR \fIspec\fR
|
|
.RS 4
|
|
Prune the given package from the display of the dependency tree.
|
|
.RE
|
|
.sp
|
|
\fB\-\-depth\fR \fIdepth\fR
|
|
.RS 4
|
|
Maximum display depth of the dependency tree. A depth of 1 displays the direct
|
|
dependencies, for example.
|
|
.RE
|
|
.sp
|
|
\fB\-\-no\-dedupe\fR
|
|
.RS 4
|
|
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 \fB(*)\fR to indicate it has already been shown.
|
|
This flag will cause those duplicates to be repeated.
|
|
.RE
|
|
.sp
|
|
\fB\-d\fR,
|
|
\fB\-\-duplicates\fR
|
|
.RS 4
|
|
Show only dependencies which come in multiple versions (implies \fB\-\-invert\fR).
|
|
When used with the \fB\-p\fR flag, only shows duplicates within the subtree of the
|
|
given package.
|
|
.sp
|
|
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.
|
|
.RE
|
|
.sp
|
|
\fB\-e\fR \fIkinds\fR,
|
|
\fB\-\-edges\fR \fIkinds\fR
|
|
.RS 4
|
|
The dependency kinds to display. Takes a comma separated list of values:
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBall\fR \[em] Show all edge kinds.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBnormal\fR \[em] Show normal dependencies.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBbuild\fR \[em] Show build dependencies.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBdev\fR \[em] Show development dependencies.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBfeatures\fR \[em] Show features enabled by each dependency. If this is the only
|
|
kind given, then it will automatically include the other dependency kinds.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBno\-normal\fR \[em] Do not include normal dependencies.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBno\-build\fR \[em] Do not include build dependencies.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBno\-dev\fR \[em] Do not include development dependencies.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBno\-proc\-macro\fR \[em] Do not include procedural macro dependencies.
|
|
.RE
|
|
.sp
|
|
The \fBnormal\fR, \fBbuild\fR, \fBdev\fR, and \fBall\fR dependency kinds cannot be mixed with
|
|
\fBno\-normal\fR, \fBno\-build\fR, or \fBno\-dev\fR dependency kinds.
|
|
.sp
|
|
The default is \fBnormal,build,dev\fR\&.
|
|
.RE
|
|
.sp
|
|
\fB\-\-target\fR \fItriple\fR
|
|
.RS 4
|
|
Filter dependencies matching the given \fItarget triple\fR <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&.
|
|
The default is the host platform. Use the value \fBall\fR to include \fIall\fR targets.
|
|
.RE
|
|
.SS "Tree Formatting Options"
|
|
.sp
|
|
\fB\-\-charset\fR \fIcharset\fR
|
|
.RS 4
|
|
Chooses the character set to use for the tree. Valid values are "utf8" or
|
|
"ascii". Default is "utf8".
|
|
.RE
|
|
.sp
|
|
\fB\-f\fR \fIformat\fR,
|
|
\fB\-\-format\fR \fIformat\fR
|
|
.RS 4
|
|
Set the format string for each package. The default is "{p}".
|
|
.sp
|
|
This is an arbitrary string which will be used to display each package. The following
|
|
strings will be replaced with the corresponding value:
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fB{p}\fR \[em] The package name.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fB{l}\fR \[em] The package license.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fB{r}\fR \[em] The package repository URL.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fB{f}\fR \[em] Comma\-separated list of package features that are enabled.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fB{lib}\fR \[em] The name, as used in a \fBuse\fR statement, of the package's library.
|
|
.RE
|
|
.RE
|
|
.sp
|
|
\fB\-\-prefix\fR \fIprefix\fR
|
|
.RS 4
|
|
Sets how each line is displayed. The \fIprefix\fR value can be one of:
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBindent\fR (default) \[em] Shows each line indented as a tree.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBdepth\fR \[em] Show as a list, with the numeric depth printed before each entry.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBnone\fR \[em] Show as a flat list.
|
|
.RE
|
|
.RE
|
|
.SS "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
|
|
\fB\-\-manifest\-path\fR 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.
|
|
.sp
|
|
The default members of a workspace can be set explicitly with the
|
|
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
|
|
virtual workspace will include all workspace members (equivalent to passing
|
|
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
|
|
.sp
|
|
\fB\-p\fR \fIspec\fR\&...,
|
|
\fB\-\-package\fR \fIspec\fR\&...
|
|
.RS 4
|
|
Display only the specified packages. See \fBcargo\-pkgid\fR(1) for the
|
|
SPEC format. This flag may be specified multiple times and supports common Unix
|
|
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
|
|
expanding glob patterns before Cargo handles them, you must use single quotes or
|
|
double quotes around each pattern.
|
|
.RE
|
|
.sp
|
|
\fB\-\-workspace\fR
|
|
.RS 4
|
|
Display all members in the workspace.
|
|
.RE
|
|
.sp
|
|
\fB\-\-exclude\fR \fISPEC\fR\&...
|
|
.RS 4
|
|
Exclude the specified packages. Must be used in conjunction with the
|
|
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
|
|
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
|
|
accidentally expanding glob patterns before Cargo handles them, you must use
|
|
single quotes or double quotes around each pattern.
|
|
.RE
|
|
.SS "Manifest Options"
|
|
.sp
|
|
\fB\-\-manifest\-path\fR \fIpath\fR
|
|
.RS 4
|
|
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
|
|
\fBCargo.toml\fR file in the current directory or any parent directory.
|
|
.RE
|
|
.sp
|
|
\fB\-\-frozen\fR,
|
|
\fB\-\-locked\fR
|
|
.RS 4
|
|
Either of these flags requires that the \fBCargo.lock\fR file is
|
|
up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will
|
|
exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from
|
|
attempting to access the network to determine if it is out\-of\-date.
|
|
.sp
|
|
These may be used in environments where you want to assert that the
|
|
\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network
|
|
access.
|
|
.RE
|
|
.sp
|
|
\fB\-\-offline\fR
|
|
.RS 4
|
|
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.
|
|
.sp
|
|
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 \fBcargo\-fetch\fR(1) command to download dependencies before going
|
|
offline.
|
|
.sp
|
|
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
|
|
.RE
|
|
.SS "Feature Selection"
|
|
The feature flags allow you to control which features are enabled. When no
|
|
feature options are given, the \fBdefault\fR feature is activated for every
|
|
selected package.
|
|
.sp
|
|
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
|
|
for more details.
|
|
.sp
|
|
\fB\-F\fR \fIfeatures\fR,
|
|
\fB\-\-features\fR \fIfeatures\fR
|
|
.RS 4
|
|
Space or comma separated list of features to activate. Features of workspace
|
|
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
|
|
be specified multiple times, which enables all specified features.
|
|
.RE
|
|
.sp
|
|
\fB\-\-all\-features\fR
|
|
.RS 4
|
|
Activate all available features of all selected packages.
|
|
.RE
|
|
.sp
|
|
\fB\-\-no\-default\-features\fR
|
|
.RS 4
|
|
Do not activate the \fBdefault\fR feature of the selected packages.
|
|
.RE
|
|
.SS "Display Options"
|
|
.sp
|
|
\fB\-v\fR,
|
|
\fB\-\-verbose\fR
|
|
.RS 4
|
|
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 \fBterm.verbose\fR
|
|
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
|
|
.RE
|
|
.sp
|
|
\fB\-q\fR,
|
|
\fB\-\-quiet\fR
|
|
.RS 4
|
|
Do not print cargo log messages.
|
|
May also be specified with the \fBterm.quiet\fR
|
|
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
|
|
.RE
|
|
.sp
|
|
\fB\-\-color\fR \fIwhen\fR
|
|
.RS 4
|
|
Control when colored output is used. Valid values:
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
|
|
terminal.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
|
|
.RE
|
|
.sp
|
|
May also be specified with the \fBterm.color\fR
|
|
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
|
|
.RE
|
|
.SS "Common Options"
|
|
.sp
|
|
\fB+\fR\fItoolchain\fR
|
|
.RS 4
|
|
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
|
|
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
|
|
as \fB+stable\fR or \fB+nightly\fR).
|
|
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
|
|
for more information about how toolchain overrides work.
|
|
.RE
|
|
.sp
|
|
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
|
|
.RS 4
|
|
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
|
|
or provided as a path to an extra configuration file. This flag may be specified multiple times.
|
|
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
|
|
.RE
|
|
.sp
|
|
\fB\-h\fR,
|
|
\fB\-\-help\fR
|
|
.RS 4
|
|
Prints help information.
|
|
.RE
|
|
.sp
|
|
\fB\-Z\fR \fIflag\fR
|
|
.RS 4
|
|
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
|
|
.RE
|
|
.SH "ENVIRONMENT"
|
|
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
|
|
details on environment variables that Cargo reads.
|
|
.SH "EXIT STATUS"
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
|
|
.RE
|
|
.SH "EXAMPLES"
|
|
.sp
|
|
.RS 4
|
|
\h'-04' 1.\h'+01'Display the tree for the package in the current directory:
|
|
.sp
|
|
.RS 4
|
|
.nf
|
|
cargo tree
|
|
.fi
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04' 2.\h'+01'Display all the packages that depend on the \fBsyn\fR package:
|
|
.sp
|
|
.RS 4
|
|
.nf
|
|
cargo tree \-i syn
|
|
.fi
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04' 3.\h'+01'Show the features enabled on each package:
|
|
.sp
|
|
.RS 4
|
|
.nf
|
|
cargo tree \-\-format "{p} {f}"
|
|
.fi
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04' 4.\h'+01'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).
|
|
.sp
|
|
.RS 4
|
|
.nf
|
|
cargo tree \-d
|
|
.fi
|
|
.RE
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
\h'-04' 5.\h'+01'Explain why features are enabled for the \fBsyn\fR package:
|
|
.sp
|
|
.RS 4
|
|
.nf
|
|
cargo tree \-e features \-i syn
|
|
.fi
|
|
.RE
|
|
.sp
|
|
The \fB\-e features\fR flag is used to show features. The \fB\-i\fR flag is used to
|
|
invert the graph so that it displays the packages that depend on \fBsyn\fR\&. An
|
|
example of what this would display:
|
|
.sp
|
|
.RS 4
|
|
.nf
|
|
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" (*)
|
|
.fi
|
|
.RE
|
|
.sp
|
|
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
|
|
\fBrustversion\fR crate which is included from \fBmyproject\fR (with the default
|
|
features), and \fBmyproject\fR is the package selected on the command\-line. All
|
|
of the other \fBsyn\fR features are added by the "default" feature ("quote" is
|
|
added by "printing" and "proc\-macro", both of which are default features).
|
|
.sp
|
|
If you're having difficulty cross\-referencing the de\-duplicated \fB(*)\fR
|
|
entries, try with the \fB\-\-no\-dedupe\fR flag to get the full output.
|
|
.RE
|
|
.SH "SEE ALSO"
|
|
\fBcargo\fR(1), \fBcargo\-metadata\fR(1)
|