Add some documentation for --filter-platform.

diff --git a/src/bin/cargo/commands/metadata.rs b/src/bin/cargo/commands/metadata.rs
index 542bc59316821cda2698de5f510f11479e218e23..68eb6cad48ac9cc27790d95ec6c132e0a5dc285c 100644 (file)
--- 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
index ca28733dc05b364e0f17d9e702ffc4f3e3861a52..a6b64a692604e6c97d7e1067a2150970f6bd8c6d 100644 (file)
--- 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
index 906cb999e8fd28962d2e4fe49df6af06df49b621..45bd3b73736d3482c65ed78e1ae3c464787eed63 100644 (file)
--- 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
index 892e652a845886d577f1af4214abf1c9e5183cf7..7530f323a9f0a6cb3b858fa94ca0f2dd417677fc 100644 (file)
--- a/src/doc/man/generated/cargo-metadata.html
+++ b/src/doc/man/generated/cargo-metadata.html
@@ -209,6 +209,9 @@ for a Rust API for reading the metadata.</p>
     /* 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 @@ dependencies.</p>
 <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
index 924c599b9dd1c2064e9ff79d471c7608e7174f0c..7ab6f89bca2fef1bef94bd96a936d757caced1d8 100644 (file)
--- 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