diff options
Diffstat (limited to '')
| -rw-r--r-- | src/etc/man/cargo-tree.1 | 506 |
1 files changed, 506 insertions, 0 deletions
diff --git a/src/etc/man/cargo-tree.1 b/src/etc/man/cargo-tree.1 new file mode 100644 index 0000000..86077f5 --- /dev/null +++ b/src/etc/man/cargo-tree.1 @@ -0,0 +1,506 @@ +'\" t +.TH "CARGO\-TREE" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-tree \[em] 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 \[lq]rand\[rq] 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 \[lq]de\-duplicated\[rq]\&. 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 +\[lq]features\[rq] 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 \[lq]default\[rq] 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\[cq]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\[cq]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\[cq]s reverse dependencies across the entire workspace. The \fB\-p\fR +flag can be used to display the package\[cq]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 \[lq]utf8\[rq] or +\[lq]ascii\[rq]\&. Default is \[lq]utf8\[rq]\&. +.RE +.sp +\fB\-f\fR \fIformat\fR, +\fB\-\-format\fR \fIformat\fR +.RS 4 +Set the format string for each package. The default is \[lq]{p}\[rq]\&. +.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\[cq]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\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.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\[u2026] +.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 \[lq]very verbose\[rq] 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\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.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 \[lq]full\[rq] 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 \[lq]default\[rq] feature (\[lq]quote\[rq] is +added by \[lq]printing\[rq] and \[lq]proc\-macro\[rq], both of which are default features). +.sp +If you\[cq]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) |