Skip to content

Commit

Permalink
docs(metadata): Stabilize id format as PackageIDSpec
Browse files Browse the repository at this point in the history
This makes it so you can take a package from `cargo metadata` and
then pass it with the `--package` option without worrying about
ambiguity.

Fixes rust-lang#7267
  • Loading branch information
epage committed Nov 2, 2023
1 parent 2bce033 commit dd80f44
Show file tree
Hide file tree
Showing 4 changed files with 31 additions and 9 deletions.
9 changes: 7 additions & 2 deletions src/doc/man/cargo-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ considersed as incompatible:
* **Adding new values for enum-like fields** — Same as adding new fields. It
keeps metadata evolving without stagnation.
* **Changing opaque representations** — The inner representations of some
fields are implementation details. For example, fields related to "Package ID"
or "Source ID" are treated as opaque identifiers to differentiate packages or
fields are implementation details. For example, fields related to
"Source ID" are treated as opaque identifiers to differentiate packages or
sources. Consumers shouldn't rely on those representations unless specified.

### JSON format
Expand Down Expand Up @@ -331,6 +331,11 @@ The JSON output has the following format:
}
````

Notes:
- For `"id"` field syntax, see [Package ID Specifications] in the reference.

[Package ID Specifications]: ../reference/pkgid-spec.html

## OPTIONS

### Output Options
Expand Down
12 changes: 9 additions & 3 deletions src/doc/man/generated_txt/cargo-metadata.txt
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ OUTPUT FORMAT

o Changing opaque representations — The inner representations of some
fields are implementation details. For example, fields related to
Package ID” or “Source ID” are treated as opaque identifiers
to differentiate packages or sources. Consumers shouldn’t rely on
those representations unless specified.
“Source ID” are treated as opaque identifiers to differentiate
packages or sources. Consumers shouldn’t rely on those
representations unless specified.

JSON format
The JSON output has the following format:
Expand Down Expand Up @@ -326,6 +326,12 @@ OUTPUT FORMAT
}
}

Notes:

o For "id" field syntax, see Package ID Specifications
<https://doc.rust-lang.org/cargo/reference/pkgid-spec.html> in the
reference.

OPTIONS
Output Options
--no-deps
Expand Down
9 changes: 7 additions & 2 deletions src/doc/src/commands/cargo-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ considersed as incompatible:
* **Adding new values for enum-like fields** — Same as adding new fields. It
keeps metadata evolving without stagnation.
* **Changing opaque representations** — The inner representations of some
fields are implementation details. For example, fields related to "Package ID"
or "Source ID" are treated as opaque identifiers to differentiate packages or
fields are implementation details. For example, fields related to
"Source ID" are treated as opaque identifiers to differentiate packages or
sources. Consumers shouldn't rely on those representations unless specified.

### JSON format
Expand Down Expand Up @@ -331,6 +331,11 @@ The JSON output has the following format:
}
````

Notes:
- For `"id"` field syntax, see [Package ID Specifications] in the reference.

[Package ID Specifications]: ../reference/pkgid-spec.html

## OPTIONS

### Output Options
Expand Down
10 changes: 8 additions & 2 deletions src/etc/man/cargo-metadata.1
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ keeps metadata evolving without stagnation.
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBChanging opaque representations\fR \[em] The inner representations of some
fields are implementation details. For example, fields related to \[lq]Package ID\[rq]
or \[lq]Source ID\[rq] are treated as opaque identifiers to differentiate packages or
fields are implementation details. For example, fields related to
\[lq]Source ID\[rq] are treated as opaque identifiers to differentiate packages or
sources. Consumers shouldn\[cq]t rely on those representations unless specified.
.RE
.SS "JSON format"
Expand Down Expand Up @@ -333,6 +333,12 @@ The JSON output has the following format:
}
.fi
.RE
.sp
Notes:
.sp
.RS 4
\h'-04'\(bu\h'+02'For \fB"id"\fR field syntax, see \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html> in the reference.
.RE
.SH "OPTIONS"
.SS "Output Options"
.sp
Expand Down

0 comments on commit dd80f44

Please sign in to comment.