diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md index 0027a20b1f47..ddc957833c03 100644 --- a/src/doc/man/cargo-metadata.md +++ b/src/doc/man/cargo-metadata.md @@ -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 `PackageId` + or `SourceId` 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, a "opaque" 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. - This is null for path dependencies and workspace members. + /* 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. */ diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt index d9d48fd9a741..0f59eeb0c666 100644 --- a/src/doc/man/generated_txt/cargo-metadata.txt +++ b/src/doc/man/generated_txt/cargo-metadata.txt @@ -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 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 + PackageId or SourceId 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, a "opaque" 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. - This is null for path dependencies and workspace members. + /* 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. */ diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md index e9aeac7dfa7e..0ecd6c4087d0 100644 --- a/src/doc/src/commands/cargo-metadata.md +++ b/src/doc/src/commands/cargo-metadata.md @@ -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 `PackageId` + or `SourceId` 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, a "opaque" 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. - This is null for path dependencies and workspace members. + /* 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. */ diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1 index f2ebb63c7eb1..f6c8c9264ff1 100644 --- a/src/etc/man/cargo-metadata.1 +++ b/src/etc/man/cargo-metadata.1 @@ -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 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 \fBPackageId\fR +or \fBSourceId\fR 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, a "opaque" 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. - This is null for path dependencies and workspace members. + /* 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. */