mirror of
https://github.com/rust-lang/cargo.git
synced 2025-09-28 11:20:36 +00:00
518 lines
12 KiB
Groff
518 lines
12 KiB
Groff
'\" t
|
||
.\" Title: cargo-tree
|
||
.\" Author: [see the "AUTHOR(S)" section]
|
||
.\" Generator: Asciidoctor 2.0.10
|
||
.\" Date: 2020-04-02
|
||
.\" Manual: \ \&
|
||
.\" Source: \ \&
|
||
.\" Language: English
|
||
.\"
|
||
.TH "CARGO\-TREE" "1" "2020-04-02" "\ \&" "\ \&"
|
||
.ie \n(.g .ds Aq \(aq
|
||
.el .ds Aq '
|
||
.ss \n[.ss] 0
|
||
.nh
|
||
.ad l
|
||
.de URL
|
||
\fI\\$2\fP <\\$1>\\$3
|
||
..
|
||
.als MTO URL
|
||
.if \n[.g] \{\
|
||
. mso www.tmac
|
||
. am URL
|
||
. ad l
|
||
. .
|
||
. am MTO
|
||
. ad l
|
||
. .
|
||
. LINKSTYLE blue R < >
|
||
.\}
|
||
.SH "NAME"
|
||
cargo\-tree \- Display a tree visualization of a dependency graph
|
||
.SH "SYNOPSIS"
|
||
.sp
|
||
\fBcargo tree [\fIOPTIONS\fP]\fP
|
||
.SH "DESCRIPTION"
|
||
.sp
|
||
This command will display a tree of dependencies to the terminal. An example of a simple project that depends on the "rand" package:
|
||
.sp
|
||
.if n .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
|
||
.if n .RE
|
||
.sp
|
||
Packages marked with \fB(*)\fP have been "de\-duplicated". The dependencies for the
|
||
package have already been shown elswhere in the graph, and so are not
|
||
repeated. Use the \fB\-\-no\-dedupe\fP option to repeat the duplicates.
|
||
.SH "OPTIONS"
|
||
.SS "Tree Options"
|
||
.sp
|
||
\fB\-i\fP, \fB\-\-invert\fP
|
||
.RS 4
|
||
Invert the tree. Typically this flag is used with the \fB\-p\fP flag to show
|
||
the dependencies for a specific package.
|
||
.RE
|
||
.sp
|
||
\fB\-\-no\-dedupe\fP
|
||
.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(*)\fP to indicate it has
|
||
already been shown. This flag will cause those duplicates to be repeated.
|
||
.RE
|
||
.sp
|
||
\fB\-d\fP, \fB\-\-duplicates\fP
|
||
.RS 4
|
||
Show only dependencies which come in multiple versions (implies
|
||
\fB\-\-invert\fP). When used with the \fB\-p\fP 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\-\-no\-dev\-dependencies\fP
|
||
.RS 4
|
||
Do not include dev\-dependencies.
|
||
.RE
|
||
.sp
|
||
\fB\-\-target\fP \fITRIPLE\fP
|
||
.RS 4
|
||
Filter dependencies matching the given target\-triple.
|
||
The default is the host platform.
|
||
.RE
|
||
.sp
|
||
\fB\-\-no\-filter\-targets\fP
|
||
.RS 4
|
||
Show dependencies for all target platforms. Cannot be specified with
|
||
\fB\-\-target\fP.
|
||
.RE
|
||
.sp
|
||
\fB\-\-graph\-features\fP
|
||
.RS 4
|
||
Runs in a special mode where features are included as individual nodes.
|
||
This is intended to be used to help explain why a feature is enabled on
|
||
any particular package. It is recommended to use with the \fB\-p\fP and \fB\-i\fP
|
||
flags to show how the features flow into the package. See the examples
|
||
below for more detail.
|
||
.RE
|
||
.SS "Tree Formatting Options"
|
||
.sp
|
||
\fB\-\-charset\fP \fICHARSET\fP
|
||
.RS 4
|
||
Chooses the character set to use for the tree. Valid values are "utf8" or
|
||
"ascii". Default is "utf8".
|
||
.RE
|
||
.sp
|
||
\fB\-f\fP \fIFORMAT\fP, \fB\-\-format\fP \fIFORMAT\fP
|
||
.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
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fB{p}\fP — The package name.
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fB{l}\fP — The package license.
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fB{r}\fP — The package repository URL.
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fB{f}\fP — Comma\-separated list of package features that are enabled.
|
||
.RE
|
||
.RE
|
||
.sp
|
||
\fB\-\-prefix\fP \fIPREFIX\fP
|
||
.RS 4
|
||
Sets how each line is displayed. The \fIPREFIX\fP value can be one of:
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fBindent\fP (default) — Shows each line indented as a tree.
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fBdepth\fP — Show as a list, with the numeric depth printed before each entry.
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fBnone\fP — Show as a flat list.
|
||
.RE
|
||
.RE
|
||
.SS "Package Selection"
|
||
.sp
|
||
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\fP 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\fP key in the root manifest. If this is not set, a
|
||
virtual workspace will include all workspace members (equivalent to passing
|
||
\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself.
|
||
.sp
|
||
\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP...
|
||
.RS 4
|
||
Display only the specified packages. See \fBcargo\-pkgid\fP(1) for the
|
||
SPEC format. This flag may be specified multiple times.
|
||
.RE
|
||
.sp
|
||
\fB\-\-workspace\fP
|
||
.RS 4
|
||
Display all members in the workspace.
|
||
.RE
|
||
.sp
|
||
\fB\-\-exclude\fP \fISPEC\fP...
|
||
.RS 4
|
||
Exclude the specified packages. Must be used in conjunction with the
|
||
\fB\-\-workspace\fP flag. This flag may be specified multiple times.
|
||
.RE
|
||
.SS "Manifest Options"
|
||
.sp
|
||
\fB\-\-manifest\-path\fP \fIPATH\fP
|
||
.RS 4
|
||
Path to the \fBCargo.toml\fP file. By default, Cargo searches for the
|
||
\fBCargo.toml\fP file in the current directory or any parent directory.
|
||
.RE
|
||
.SS "Feature Selection"
|
||
.sp
|
||
The feature flags allow you to control the enabled features for the "current"
|
||
package. The "current" package is the package in the current directory, or the
|
||
one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual
|
||
workspace, then the default features are selected for all workspace members,
|
||
or all features if \fB\-\-all\-features\fP is specified.
|
||
.sp
|
||
When no feature options are given, the \fBdefault\fP feature is activated for
|
||
every selected package.
|
||
.sp
|
||
\fB\-\-features\fP \fIFEATURES\fP
|
||
.RS 4
|
||
Space or comma separated list of features to activate. These features only
|
||
apply to the current directory\(cqs package. Features of direct dependencies
|
||
may be enabled with \fB<dep\-name>/<feature\-name>\fP syntax. This flag may be
|
||
specified multiple times, which enables all specified features.
|
||
.RE
|
||
.sp
|
||
\fB\-\-all\-features\fP
|
||
.RS 4
|
||
Activate all available features of all selected packages.
|
||
.RE
|
||
.sp
|
||
\fB\-\-no\-default\-features\fP
|
||
.RS 4
|
||
Do not activate the \fBdefault\fP feature of the current directory\(cqs
|
||
package.
|
||
.RE
|
||
.SS "Display Options"
|
||
.sp
|
||
\fB\-v\fP, \fB\-\-verbose\fP
|
||
.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\fP
|
||
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
|
||
.RE
|
||
.sp
|
||
\fB\-q\fP, \fB\-\-quiet\fP
|
||
.RS 4
|
||
No output printed to stdout.
|
||
.RE
|
||
.sp
|
||
\fB\-\-color\fP \fIWHEN\fP
|
||
.RS 4
|
||
Control when colored output is used. Valid values:
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fBauto\fP (default): Automatically detect if color support is available on the
|
||
terminal.
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fBalways\fP: Always display colors.
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04'\(bu\h'+03'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP \(bu 2.3
|
||
.\}
|
||
\fBnever\fP: Never display colors.
|
||
.RE
|
||
.sp
|
||
May also be specified with the \fBterm.color\fP
|
||
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
|
||
.RE
|
||
.SS "Common Options"
|
||
.sp
|
||
\fB\-h\fP, \fB\-\-help\fP
|
||
.RS 4
|
||
Prints help information.
|
||
.RE
|
||
.sp
|
||
\fB\-Z\fP \fIFLAG\fP...
|
||
.RS 4
|
||
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for
|
||
details.
|
||
.RE
|
||
.sp
|
||
\fB\-\-frozen\fP, \fB\-\-locked\fP
|
||
.RS 4
|
||
Either of these flags requires that the \fBCargo.lock\fP 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\fP 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\fP file is up\-to\-date (such as a CI build) or want to avoid network
|
||
access.
|
||
.RE
|
||
.sp
|
||
\fB\-\-offline\fP
|
||
.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\fP(1) command to download dependencies before going
|
||
offline.
|
||
.sp
|
||
May also be specified with the \fBnet.offline\fP \c
|
||
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
|
||
.RE
|
||
.SH "ENVIRONMENT"
|
||
.sp
|
||
See \c
|
||
.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " "
|
||
for
|
||
details on environment variables that Cargo reads.
|
||
.SH "EXIT STATUS"
|
||
.sp
|
||
0
|
||
.RS 4
|
||
Cargo succeeded.
|
||
.RE
|
||
.sp
|
||
101
|
||
.RS 4
|
||
Cargo failed to complete.
|
||
.RE
|
||
.SH "EXAMPLES"
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04' 1.\h'+01'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP " 1." 4.2
|
||
.\}
|
||
Display the tree for the package in the current directory:
|
||
.sp
|
||
.if n .RS 4
|
||
.nf
|
||
cargo tree
|
||
.fi
|
||
.if n .RE
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04' 2.\h'+01'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP " 2." 4.2
|
||
.\}
|
||
Display all the packages that depend on the specified package:
|
||
.sp
|
||
.if n .RS 4
|
||
.nf
|
||
cargo tree \-i \-p syn
|
||
.fi
|
||
.if n .RE
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04' 3.\h'+01'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP " 3." 4.2
|
||
.\}
|
||
Show the features enabled on each package:
|
||
.sp
|
||
.if n .RS 4
|
||
.nf
|
||
cargo tree \-\-format "{p} {f}"
|
||
.fi
|
||
.if n .RE
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04' 4.\h'+01'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP " 4." 4.2
|
||
.\}
|
||
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
|
||
.if n .RS 4
|
||
.nf
|
||
cargo tree \-d
|
||
.fi
|
||
.if n .RE
|
||
.RE
|
||
.sp
|
||
.RS 4
|
||
.ie n \{\
|
||
\h'-04' 5.\h'+01'\c
|
||
.\}
|
||
.el \{\
|
||
. sp -1
|
||
. IP " 5." 4.2
|
||
.\}
|
||
Explain why features are enabled for the given package:
|
||
.sp
|
||
.if n .RS 4
|
||
.nf
|
||
cargo tree \-\-graph\-features \-i \-p syn
|
||
.fi
|
||
.if n .RE
|
||
.sp
|
||
An example of what this would display:
|
||
.sp
|
||
.if n .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
|
||
.if n .RE
|
||
.sp
|
||
To read this graph, you can follow the chain for each feature from the root to
|
||
see why it was included. For example, the "full" feature was added by the
|
||
\fBrustversion\fP crate which was included from \fBmyproject\fP (with the default
|
||
features), and \fBmyproject\fP was the package selected on the command\-line. All
|
||
of the other \fBsyn\fP features are added by the "default" feature ("quote" is
|
||
added by "printing" and "proc\-macro", both of which are default features).
|
||
.sp
|
||
If you\(cqre having difficulty cross\-referencing the de\-duplicated \fB(*)\fP entries,
|
||
try with the \fB\-\-no\-dedupe\fP flag to get the full output.
|
||
.RE
|
||
.SH "SEE ALSO"
|
||
.sp
|
||
\fBcargo\fP(1), \fBcargo\-metadata\fP(1) |