Add some documentation for --filter-platform.

rust-lang · Oct 28, 2019 · ca02e03 · ca02e03
1 parent d6b5a6b
commit ca02e03
Show file tree

Hide file tree

Showing 5 changed files with 44 additions and 4 deletions.
diff --git a/src/bin/cargo/commands/metadata.rs b/src/bin/cargo/commands/metadata.rs
@@ -15,8 +15,7 @@ pub fn cli() -> App {
         .arg(
             opt(
                 "filter-platform",
-                "Only include resolve dependencies matching the given target-triple \
-                 (\"host\" for current host)",
+                "Only include resolve dependencies matching the given target-triple",
             )
             .value_name("TRIPLE"),
         )

diff --git a/src/cargo/ops/cargo_output_metadata.rs b/src/cargo/ops/cargo_output_metadata.rs
@@ -54,6 +54,9 @@ pub fn output_metadata(ws: &Workspace<'_>, opt: &OutputMetadataOptions) -> Cargo
     })
 }
 
+/// This is the structure that is serialized and displayed to the user.
+///
+/// See cargo-metadata.adoc for detailed documentation of the format.
 #[derive(Serialize)]
 pub struct ExportInfo {
     packages: Vec<Package>,
@@ -84,6 +87,7 @@ struct Dep {
     pkg: PackageId,
 }
 
+/// Builds the resolve graph as it will be displayed to the user.
 fn build_resolve_graph(
     ws: &Workspace<'_>,
     resolve_opts: ResolveOpts,

diff --git a/src/doc/man/cargo-metadata.adoc b/src/doc/man/cargo-metadata.adoc
@@ -202,6 +202,9 @@ The output has the following format:
     /* The resolved dependency graph, with the concrete versions and features
        selected. The set depends on the enabled features.
        This is null if --no-deps is specified.
+       By default, this includes all dependencies for all target platforms.
+       The `--filter-platform` flag may be used to narrow to a specific
+       target triple.
     */
     "resolve": {
         /* Array of nodes within the dependency graph.
@@ -265,6 +268,14 @@ The output has the following format:
     Specify the version of the output format to use. Currently `1` is the only
     possible value.
 
+*--filter-platform* _TRIPLE_::
+    This filters the `resolve` output to only include dependencies for the
+    given target triple. Without this flag, the resolve includes all targets.
++
+Note that the dependencies listed in the "packages" array still includes all
+dependencies. Each package definition is intended to be an unaltered
+reproduction of the information within `Cargo.toml`.
+
 include::options-features.adoc[]
 
 === Display Options

diff --git a/src/doc/man/generated/cargo-metadata.html b/src/doc/man/generated/cargo-metadata.html
@@ -209,6 +209,9 @@ <h2 id="cargo_metadata_output_format">OUTPUT FORMAT</h2>
     /* The resolved dependency graph, with the concrete versions and features
        selected. The set depends on the enabled features.
        This is null if --no-deps is specified.
+       By default, this includes all dependencies for all target platforms.
+       The `--filter-platform` flag may be used to narrow to a specific
+       target triple.
     */
     "resolve": {
         /* Array of nodes within the dependency graph.
@@ -279,6 +282,16 @@ <h3 id="cargo_metadata_output_options">Output Options</h3>
 <p>Specify the version of the output format to use. Currently <code>1</code> is the only
 possible value.</p>
 </dd>
+<dt class="hdlist1"><strong>--filter-platform</strong> <em>TRIPLE</em></dt>
+<dd>
+<p>This filters the <code>resolve</code> output to only include dependencies for the
+given target triple. Without this flag, the resolve includes all targets.</p>
+<div class="paragraph">
+<p>Note that the dependencies listed in the "packages" array still includes all
+dependencies. Each package definition is intended to be an unaltered
+reproduction of the information within <code>Cargo.toml</code>.</p>
+</div>
+</dd>
 </dl>
 </div>
 </div>

diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-metadata
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 2.0.10
-.\"      Date: 2019-09-17
+.\"      Date: 2019-10-28
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-METADATA" "1" "2019-09-17" "\ \&" "\ \&"
+.TH "CARGO\-METADATA" "1" "2019-10-28" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -223,6 +223,9 @@ The output has the following format:
     /* The resolved dependency graph, with the concrete versions and features
        selected. The set depends on the enabled features.
        This is null if \-\-no\-deps is specified.
+       By default, this includes all dependencies for all target platforms.
+       The `\-\-filter\-platform` flag may be used to narrow to a specific
+       target triple.
     */
     "resolve": {
         /* Array of nodes within the dependency graph.
@@ -288,6 +291,16 @@ dependencies.
 Specify the version of the output format to use. Currently \fB1\fP is the only
 possible value.
 .RE
+.sp
+\fB\-\-filter\-platform\fP \fITRIPLE\fP
+.RS 4
+This filters the \fBresolve\fP output to only include dependencies for the
+given target triple. Without this flag, the resolve includes all targets.
+.sp
+Note that the dependencies listed in the "packages" array still includes all
+dependencies. Each package definition is intended to be an unaltered
+reproduction of the information within \fBCargo.toml\fP.
+.RE
 .SS "Feature Selection"
 .sp
 When no feature options are given, the \fBdefault\fP feature is activated for