itsscb/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo.git synced 2025-09-28 11:20:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Auto merge of #12313 - weihanglo:opaque-id, r=ehuss

Browse Source 
doc: state `PackageId`/`SourceId` string is opaque
This commit is contained in:
bors 2023-07-08 20:48:07 +00:00
commit ea9c1a5bd7
4 changed files with 158 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
src/doc/man/cargo-metadata.md
View File

@ -13,15 +13,34 @@ cargo-metadata --- Machine-readable metadata about the current package
Output JSON to stdout containing information about the workspace members and
resolved dependencies of the current package.
It is recommended to include the `--format-version` flag to future-proof
your code to ensure the output is in the format you are expecting.
The format of the output is subject to change in futures versions of Cargo. It
is recommended to include the `--format-version` flag to future-proof your code
to ensure the output is in the format you are expecting. For more on the
expectations, see ["Compatibility"](#compatibility).
See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata)
for a Rust API for reading the metadata.
## OUTPUT FORMAT
The output has the following format:
### Compatibility
Within the same output format version, the compatibility is maintained, except
some scenarios. The following is a non-exhaustive list of changes that are not
considersed as incompatibile:
* **Adding new fields** — New fields will be added when needed. Reserving this
helps Cargo evolve without bumping the format version too often.
* **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
sources. Consumers shouldn't rely on those representations unless specified.
### JSON format
The JSON output has the following format:
```javascript
{
@ -34,7 +53,9 @@ The output has the following format:
"name": "my-package",
/* The version of the package. */
"version": "0.1.0",
/* The Package ID, a unique identifier for referring to the package. */
/* The Package ID, an opaque and unique identifier for referring to the
package. See "Compatibility" above for the stability guarantee.
*/
"id": "my-package 0.1.0 (path+file:///path/to/my-package)",
/* The license value from the manifest, or null. */
"license": "MIT/Apache-2.0",
@ -42,14 +63,25 @@ The output has the following format:
"license_file": "LICENSE",
/* The description value from the manifest, or null. */
"description": "Package description.",
/* The source ID of the package. This represents where
a package is retrieved from.
/* The source ID of the package, an "opaque" identifier representing
where a package is retrieved from. See "Compatibility" above for
the stability guarantee.
This is null for path dependencies and workspace members.
For other dependencies, it is a string with the format:
- "registry+URL" for registry-based dependencies.
Example: "registry+https://github.com/rust-lang/crates.io-index"
- "git+URL" for git-based dependencies.
Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
- "sparse+URL" for dependencies from a sparse registry
Example: "sparse+https://my-sparse-registry.org"
The value after the `+` is not explicitly defined, and may change
between versions of Cargo and may not directly correlate to other
things, such as registry definitions in a config file. New source
kinds may be added in the future which will have different `+`
prefixed identifiers.
*/
"source": null,
/* Array of dependencies declared in the package's manifest. */

45
src/doc/man/generated_txt/cargo-metadata.txt
View File

@ -10,14 +10,34 @@ DESCRIPTION
Output JSON to stdout containing information about the workspace members
and resolved dependencies of the current package.
It is recommended to include the --format-version flag to future-proof
your code to ensure the output is in the format you are expecting.
The format of the output is subject to change in futures versions of
Cargo. It is recommended to include the --format-version flag to
future-proof your code to ensure the output is in the format you are
expecting. For more on the expectations, see “Compatibility”.
See the cargo_metadata crate <https://crates.io/crates/cargo_metadata>
for a Rust API for reading the metadata.
OUTPUT FORMAT
The output has the following format:
Compatibility
Within the same output format version, the compatibility is maintained,
except some scenarios. The following is a non-exhaustive list of changes
that are not considersed as incompatibile:
o Adding new fields — New fields will be added when needed. Reserving
this helps Cargo evolve without bumping the format version too often.
o Adding new values for enum-like fields — Same as adding new fields.
It keeps metadata evolving without stagnation.
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.
JSON format
The JSON output has the following format:
{
/* Array of all packages in the workspace.
@ -29,7 +49,9 @@ OUTPUT FORMAT
"name": "my-package",
/* The version of the package. */
"version": "0.1.0",
/* The Package ID, a unique identifier for referring to the package. */
/* The Package ID, an opaque and unique identifier for referring to the
package. See "Compatibility" above for the stability guarantee.
*/
"id": "my-package 0.1.0 (path+file:///path/to/my-package)",
/* The license value from the manifest, or null. */
"license": "MIT/Apache-2.0",
@ -37,14 +59,25 @@ OUTPUT FORMAT
"license_file": "LICENSE",
/* The description value from the manifest, or null. */
"description": "Package description.",
/* The source ID of the package. This represents where
a package is retrieved from.
/* The source ID of the package, an "opaque" identifier representing
where a package is retrieved from. See "Compatibility" above for
the stability guarantee.
This is null for path dependencies and workspace members.
For other dependencies, it is a string with the format:
- "registry+URL" for registry-based dependencies.
Example: "registry+https://github.com/rust-lang/crates.io-index"
- "git+URL" for git-based dependencies.
Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
- "sparse+URL" for dependencies from a sparse registry
Example: "sparse+https://my-sparse-registry.org"
The value after the `+` is not explicitly defined, and may change
between versions of Cargo and may not directly correlate to other
things, such as registry definitions in a config file. New source
kinds may be added in the future which will have different `+`
prefixed identifiers.
*/
"source": null,
/* Array of dependencies declared in the package's manifest. */

44
src/doc/src/commands/cargo-metadata.md
View File

@ -13,15 +13,34 @@ cargo-metadata --- Machine-readable metadata about the current package
Output JSON to stdout containing information about the workspace members and
resolved dependencies of the current package.
It is recommended to include the `--format-version` flag to future-proof
your code to ensure the output is in the format you are expecting.
The format of the output is subject to change in futures versions of Cargo. It
is recommended to include the `--format-version` flag to future-proof your code
to ensure the output is in the format you are expecting. For more on the
expectations, see ["Compatibility"](#compatibility).
See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata)
for a Rust API for reading the metadata.
## OUTPUT FORMAT
The output has the following format:
### Compatibility
Within the same output format version, the compatibility is maintained, except
some scenarios. The following is a non-exhaustive list of changes that are not
considersed as incompatibile:
* **Adding new fields** — New fields will be added when needed. Reserving this
helps Cargo evolve without bumping the format version too often.
* **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
sources. Consumers shouldn't rely on those representations unless specified.
### JSON format
The JSON output has the following format:
```javascript
{
@ -34,7 +53,9 @@ The output has the following format:
"name": "my-package",
/* The version of the package. */
"version": "0.1.0",
/* The Package ID, a unique identifier for referring to the package. */
/* The Package ID, an opaque and unique identifier for referring to the
package. See "Compatibility" above for the stability guarantee.
*/
"id": "my-package 0.1.0 (path+file:///path/to/my-package)",
/* The license value from the manifest, or null. */
"license": "MIT/Apache-2.0",
@ -42,14 +63,25 @@ The output has the following format:
"license_file": "LICENSE",
/* The description value from the manifest, or null. */
"description": "Package description.",
/* The source ID of the package. This represents where
a package is retrieved from.
/* The source ID of the package, an "opaque" identifier representing
where a package is retrieved from. See "Compatibility" above for
the stability guarantee.
This is null for path dependencies and workspace members.
For other dependencies, it is a string with the format:
- "registry+URL" for registry-based dependencies.
Example: "registry+https://github.com/rust-lang/crates.io-index"
- "git+URL" for git-based dependencies.
Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
- "sparse+URL" for dependencies from a sparse registry
Example: "sparse+https://my-sparse-registry.org"
The value after the `+` is not explicitly defined, and may change
between versions of Cargo and may not directly correlate to other
things, such as registry definitions in a config file. New source
kinds may be added in the future which will have different `+`
prefixed identifiers.
*/
"source": null,
/* Array of dependencies declared in the package's manifest. */

49
src/etc/man/cargo-metadata.1
View File

@ -11,13 +11,37 @@ cargo\-metadata \[em] Machine\-readable metadata about the current package
Output JSON to stdout containing information about the workspace members and
resolved dependencies of the current package.
.sp
It is recommended to include the \fB\-\-format\-version\fR flag to future\-proof
your code to ensure the output is in the format you are expecting.
The format of the output is subject to change in futures versions of Cargo. It
is recommended to include the \fB\-\-format\-version\fR flag to future\-proof your code
to ensure the output is in the format you are expecting. For more on the
expectations, see \[lq]Compatibility\[rq]\&.
.sp
See the \fIcargo_metadata crate\fR <https://crates.io/crates/cargo_metadata>
for a Rust API for reading the metadata.
.SH "OUTPUT FORMAT"
The output has the following format:
.SS "Compatibility"
Within the same output format version, the compatibility is maintained, except
some scenarios. The following is a non\-exhaustive list of changes that are not
considersed as incompatibile:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBAdding new fields\fR \[em] New fields will be added when needed. Reserving this
helps Cargo evolve without bumping the format version too often.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBAdding new values for enum\-like fields\fR \[em] Same as adding new fields. It
keeps metadata evolving without stagnation.
.RE
.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
sources. Consumers shouldn\[cq]t rely on those representations unless specified.
.RE
.SS "JSON format"
The JSON output has the following format:
.sp
.RS 4
.nf
@ -31,7 +55,9 @@ The output has the following format:
"name": "my\-package",
/* The version of the package. */
"version": "0.1.0",
/* The Package ID, a unique identifier for referring to the package. */
/* The Package ID, an opaque and unique identifier for referring to the
package. See "Compatibility" above for the stability guarantee.
*/
"id": "my\-package 0.1.0 (path+file:///path/to/my\-package)",
/* The license value from the manifest, or null. */
"license": "MIT/Apache\-2.0",
@ -39,14 +65,25 @@ The output has the following format:
"license_file": "LICENSE",
/* The description value from the manifest, or null. */
"description": "Package description.",
/* The source ID of the package. This represents where
a package is retrieved from.
/* The source ID of the package, an "opaque" identifier representing
where a package is retrieved from. See "Compatibility" above for
the stability guarantee.
This is null for path dependencies and workspace members.
For other dependencies, it is a string with the format:
\- "registry+URL" for registry\-based dependencies.
Example: "registry+https://github.com/rust\-lang/crates.io\-index"
\- "git+URL" for git\-based dependencies.
Example: "git+https://github.com/rust\-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
\- "sparse+URL" for dependencies from a sparse registry
Example: "sparse+https://my\-sparse\-registry.org"
The value after the `+` is not explicitly defined, and may change
between versions of Cargo and may not directly correlate to other
things, such as registry definitions in a config file. New source
kinds may be added in the future which will have different `+`
prefixed identifiers.
*/
"source": null,
/* Array of dependencies declared in the package's manifest. */