-
Notifications
You must be signed in to change notification settings - Fork 2.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Auto merge of #12914 - epage:metadata, r=weihanglo
fix(metadata): Stabilize id format as PackageIDSpec ### What does this PR try to resolve? For tools integrating with cargo, `cargo metadata` is the primary interface. Limitations include: - There isn't an unambiguous way to map a package entry from `cargo metadata` to a parameter to pass to other `cargo` commands. An `id` field exists but it is documented as an opaque string, useful only for comparisons with other `id`s within the document. - There isn't an unambiguous way of taking user parameters (`--package`) and mapping them to `cargo metadata` entries. `cargo pkgid` could help but it returns a `PackageIdSpec` which doesn't exist within the `cargo metadata` output. This attempts to solve these problems by switching the `id` field from `PackageId` to `PackageIdSpec` which is a [publicly documented format](https://doc.rust-lang.org/cargo/reference/pkgid-spec.html), can be generated by `cargo pkgid`, and is accepted by most commands via the `--package` flag. As the `"id"` field is documented as opaque, this technically isn't a breaking change though people could be parsing it. For `cargo_metadata` they do [use a new type that documents it as opaque but publicly expose the inner `String`](https://docs.rs/cargo_metadata/latest/cargo_metadata/struct.PackageId.html). The `String` wasn't publicly exposed due to a request by users but instead their `PackageId` type replaced using `String`s in the API in oli-obk/cargo_metadata#59 with no indication given as to why the `String` was still exposed. However, you'll note that before that PR, they had `WorkspaceMember` that parsed `PackageId`. This was introduced in oli-obk/cargo_metadata#26 without a motivation given. **Note that `PackageIdSpec` has multiple representation that might uniquely identify a package and we can return any one of them.** Fixes #7267 ### How should we test and review this PR? ### Additional information cc `@oli-obk`
- Loading branch information
Showing
13 changed files
with
353 additions
and
319 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
|
@@ -53,10 +53,10 @@ The JSON output has the following format: | |
"name": "my-package", | ||
/* The version of the package. */ | ||
"version": "0.1.0", | ||
/* The Package ID, an opaque and unique identifier for referring to the | ||
package. See "Compatibility" above for the stability guarantee. | ||
/* The Package ID for referring to the | ||
package within the document and as the `--package` argument to many commands | ||
*/ | ||
"id": "my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"id": "file:///path/to/my-package#0.1.0", | ||
/* The license value from the manifest, or null. */ | ||
"license": "MIT/Apache-2.0", | ||
/* The license-file value from the manifest, or null. */ | ||
|
@@ -242,13 +242,13 @@ The JSON output has the following format: | |
Each entry is the Package ID for the package. | ||
*/ | ||
"workspace_members": [ | ||
"my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"file:///path/to/my-package#0.1.0", | ||
], | ||
/* Array of default members of the workspace. | ||
Each entry is the Package ID for the package. | ||
*/ | ||
"workspace_default_members": [ | ||
"my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"file:///path/to/my-package#0.1.0", | ||
], | ||
// The resolved dependency graph for the entire workspace. The enabled | ||
// features are based on the enabled features for the "current" package. | ||
|
@@ -266,10 +266,10 @@ The JSON output has the following format: | |
"nodes": [ | ||
{ | ||
/* The Package ID of this node. */ | ||
"id": "my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"id": "file:///path/to/my-package#0.1.0", | ||
/* The dependencies of this package, an array of Package IDs. */ | ||
"dependencies": [ | ||
"bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" | ||
"https://github.com/rust-lang/crates.io-index#[email protected]" | ||
], | ||
/* The dependencies of this package. This is an alternative to | ||
"dependencies" which contains additional information. In | ||
|
@@ -283,7 +283,7 @@ The JSON output has the following format: | |
*/ | ||
"name": "bitflags", | ||
/* The Package ID of the dependency. */ | ||
"pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", | ||
"pkg": "https://github.com/rust-lang/crates.io-index#[email protected]" | ||
/* Array of dependency kinds. Added in Cargo 1.40. */ | ||
"dep_kinds": [ | ||
{ | ||
|
@@ -309,7 +309,7 @@ The JSON output has the following format: | |
This is null if this is a virtual workspace. Otherwise it is | ||
the Package ID of the root package. | ||
*/ | ||
"root": "my-package 0.1.0 (path+file:///path/to/my-package)" | ||
"root": "file:///path/to/my-package#0.1.0", | ||
}, | ||
/* The absolute path to the build directory where Cargo places its output. */ | ||
"target_directory": "/path/to/my-package/target", | ||
|
@@ -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 | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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: | ||
|
@@ -49,10 +49,10 @@ OUTPUT FORMAT | |
"name": "my-package", | ||
/* The version of the package. */ | ||
"version": "0.1.0", | ||
/* The Package ID, an opaque and unique identifier for referring to the | ||
package. See "Compatibility" above for the stability guarantee. | ||
/* The Package ID for referring to the | ||
package within the document and as the `--package` argument to many commands | ||
*/ | ||
"id": "my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"id": "file:///path/to/my-package#0.1.0", | ||
/* The license value from the manifest, or null. */ | ||
"license": "MIT/Apache-2.0", | ||
/* The license-file value from the manifest, or null. */ | ||
|
@@ -238,13 +238,13 @@ OUTPUT FORMAT | |
Each entry is the Package ID for the package. | ||
*/ | ||
"workspace_members": [ | ||
"my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"file:///path/to/my-package#0.1.0", | ||
], | ||
/* Array of default members of the workspace. | ||
Each entry is the Package ID for the package. | ||
*/ | ||
"workspace_default_members": [ | ||
"my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"file:///path/to/my-package#0.1.0", | ||
], | ||
// The resolved dependency graph for the entire workspace. The enabled | ||
// features are based on the enabled features for the "current" package. | ||
|
@@ -262,10 +262,10 @@ OUTPUT FORMAT | |
"nodes": [ | ||
{ | ||
/* The Package ID of this node. */ | ||
"id": "my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"id": "file:///path/to/my-package#0.1.0", | ||
/* The dependencies of this package, an array of Package IDs. */ | ||
"dependencies": [ | ||
"bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" | ||
"https://github.com/rust-lang/crates.io-index#[email protected]" | ||
], | ||
/* The dependencies of this package. This is an alternative to | ||
"dependencies" which contains additional information. In | ||
|
@@ -279,7 +279,7 @@ OUTPUT FORMAT | |
*/ | ||
"name": "bitflags", | ||
/* The Package ID of the dependency. */ | ||
"pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", | ||
"pkg": "https://github.com/rust-lang/crates.io-index#[email protected]" | ||
/* Array of dependency kinds. Added in Cargo 1.40. */ | ||
"dep_kinds": [ | ||
{ | ||
|
@@ -305,7 +305,7 @@ OUTPUT FORMAT | |
This is null if this is a virtual workspace. Otherwise it is | ||
the Package ID of the root package. | ||
*/ | ||
"root": "my-package 0.1.0 (path+file:///path/to/my-package)" | ||
"root": "file:///path/to/my-package#0.1.0", | ||
}, | ||
/* The absolute path to the build directory where Cargo places its output. */ | ||
"target_directory": "/path/to/my-package/target", | ||
|
@@ -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 | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
|
@@ -53,10 +53,10 @@ The JSON output has the following format: | |
"name": "my-package", | ||
/* The version of the package. */ | ||
"version": "0.1.0", | ||
/* The Package ID, an opaque and unique identifier for referring to the | ||
package. See "Compatibility" above for the stability guarantee. | ||
/* The Package ID for referring to the | ||
package within the document and as the `--package` argument to many commands | ||
*/ | ||
"id": "my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"id": "file:///path/to/my-package#0.1.0", | ||
/* The license value from the manifest, or null. */ | ||
"license": "MIT/Apache-2.0", | ||
/* The license-file value from the manifest, or null. */ | ||
|
@@ -242,13 +242,13 @@ The JSON output has the following format: | |
Each entry is the Package ID for the package. | ||
*/ | ||
"workspace_members": [ | ||
"my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"file:///path/to/my-package#0.1.0", | ||
], | ||
/* Array of default members of the workspace. | ||
Each entry is the Package ID for the package. | ||
*/ | ||
"workspace_default_members": [ | ||
"my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"file:///path/to/my-package#0.1.0", | ||
], | ||
// The resolved dependency graph for the entire workspace. The enabled | ||
// features are based on the enabled features for the "current" package. | ||
|
@@ -266,10 +266,10 @@ The JSON output has the following format: | |
"nodes": [ | ||
{ | ||
/* The Package ID of this node. */ | ||
"id": "my-package 0.1.0 (path+file:///path/to/my-package)", | ||
"id": "file:///path/to/my-package#0.1.0", | ||
/* The dependencies of this package, an array of Package IDs. */ | ||
"dependencies": [ | ||
"bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" | ||
"https://github.com/rust-lang/crates.io-index#[email protected]" | ||
], | ||
/* The dependencies of this package. This is an alternative to | ||
"dependencies" which contains additional information. In | ||
|
@@ -283,7 +283,7 @@ The JSON output has the following format: | |
*/ | ||
"name": "bitflags", | ||
/* The Package ID of the dependency. */ | ||
"pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", | ||
"pkg": "https://github.com/rust-lang/crates.io-index#[email protected]" | ||
/* Array of dependency kinds. Added in Cargo 1.40. */ | ||
"dep_kinds": [ | ||
{ | ||
|
@@ -309,7 +309,7 @@ The JSON output has the following format: | |
This is null if this is a virtual workspace. Otherwise it is | ||
the Package ID of the root package. | ||
*/ | ||
"root": "my-package 0.1.0 (path+file:///path/to/my-package)" | ||
"root": "file:///path/to/my-package#0.1.0", | ||
}, | ||
/* The absolute path to the build directory where Cargo places its output. */ | ||
"target_directory": "/path/to/my-package/target", | ||
|
@@ -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 | ||
|
Oops, something went wrong.