Auto merge of #13311 - weihanglo:pkgid-json-message, r=epage

bors · bors · commit df0efb267457 · 2024-01-17T15:41:33.000Z
fix(json-msg): use pkgid spec in in JSON messages
diff --git a/src/cargo/core/compiler/custom_build.rs b/src/cargo/core/compiler/custom_build.rs
@@ -229,7 +229,7 @@ fn emit_build_output(
         .collect::<Vec<_>>();
 
     let msg = machine_message::BuildScript {
-        package_id,
+        package_id: package_id.to_spec(),
         linked_libs: &output.library_links,
         linked_paths: &library_paths,
         cfgs: &output.cfgs,
diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs
@@ -578,7 +578,7 @@ fn link_targets(cx: &mut Context<'_, '_>, unit: &Unit, fresh: bool) -> CargoResu
             };
 
             let msg = machine_message::Artifact {
-                package_id,
+                package_id: package_id.to_spec(),
                 manifest_path,
                 target: &target,
                 profile: art_profile,
@@ -1766,7 +1766,7 @@ fn on_stderr_line_inner(
     }
 
     let msg = machine_message::FromCompiler {
-        package_id,
+        package_id: package_id.to_spec(),
         manifest_path,
         target,
         message: compiler_message,
diff --git a/src/cargo/core/compiler/timings.rs b/src/cargo/core/compiler/timings.rs
@@ -222,7 +222,7 @@ impl<'cfg> Timings<'cfg> {
             .extend(unlocked.iter().cloned().cloned());
         if self.report_json {
             let msg = machine_message::TimingInfo {
-                package_id: unit_time.unit.pkg.package_id(),
+                package_id: unit_time.unit.pkg.package_id().to_spec(),
                 target: &unit_time.unit.target,
                 mode: unit_time.unit.mode,
                 duration: unit_time.duration,
diff --git a/src/cargo/util/machine_message.rs b/src/cargo/util/machine_message.rs
@@ -1,10 +1,12 @@
 use std::path::{Path, PathBuf};
 
+use cargo_util_schemas::core::PackageIdSpec;
 use serde::ser;
 use serde::Serialize;
 use serde_json::{self, json, value::RawValue};
 
-use crate::core::{compiler::CompileMode, PackageId, Target};
+use crate::core::compiler::CompileMode;
+use crate::core::Target;
 
 pub trait Message: ser::Serialize {
     fn reason(&self) -> &str;
@@ -19,7 +21,7 @@ pub trait Message: ser::Serialize {
 
 #[derive(Serialize)]
 pub struct FromCompiler<'a> {
-    pub package_id: PackageId,
+    pub package_id: PackageIdSpec,
     pub manifest_path: &'a Path,
     pub target: &'a Target,
     pub message: Box<RawValue>,
@@ -33,7 +35,7 @@ impl<'a> Message for FromCompiler<'a> {
 
 #[derive(Serialize)]
 pub struct Artifact<'a> {
-    pub package_id: PackageId,
+    pub package_id: PackageIdSpec,
     pub manifest_path: PathBuf,
     pub target: &'a Target,
     pub profile: ArtifactProfile,
@@ -71,7 +73,7 @@ pub enum ArtifactDebuginfo {
 
 #[derive(Serialize)]
 pub struct BuildScript<'a> {
-    pub package_id: PackageId,
+    pub package_id: PackageIdSpec,
     pub linked_libs: &'a [String],
     pub linked_paths: &'a [String],
     pub cfgs: &'a [String],
@@ -87,7 +89,7 @@ impl<'a> Message for BuildScript<'a> {
 
 #[derive(Serialize)]
 pub struct TimingInfo<'a> {
-    pub package_id: PackageId,
+    pub package_id: PackageIdSpec,
     pub target: &'a Target,
     pub mode: CompileMode,
     pub duration: f64,
diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md
@@ -334,8 +334,6 @@ 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
@@ -393,6 +391,8 @@ reproduction of the information within `Cargo.toml`.
        cargo metadata --format-version=1
 
 ## SEE ALSO
-{{man "cargo" 1}}, {{man "cargo-pkgid" 1}}, [Package ID Specifications]
+
+{{man "cargo" 1}}, {{man "cargo-pkgid" 1}}, [Package ID Specifications], [JSON messages]
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
+[JSON messages]: ../reference/external-tools.html#json-messages
diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md
@@ -21,8 +21,10 @@ fetched.
 
 A package specifier consists of a name, version, and source URL. You are
 allowed to use partial specifiers to succinctly match a specific package as
-long as it matches only one package. The format of a _spec_ can be one of the
-following:
+long as it matches only one package. This specifier is also used by other parts
+in Cargo, such as {{man "cargo-metadata" 1}} and [JSON messages] emitted by Cargo.
+
+The format of a _spec_ can be one of the following:
 
 SPEC Structure             | Example SPEC
 ---------------------------|--------------
@@ -88,6 +90,9 @@ Get the package ID for the given package instead of the current package.
        cargo pkgid file:///path/to/local/package#foo
 
 ## SEE ALSO
-{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}, {{man "cargo-metadata" 1}}, [Package ID Specifications]
+
+{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}, {{man "cargo-metadata" 1}},
+[Package ID Specifications], [JSON messages]
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
+[JSON messages]: ../reference/external-tools.html#json-messages
diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt
@@ -483,5 +483,7 @@ EXAMPLES
 
 SEE ALSO
        cargo(1), cargo-pkgid(1), Package ID Specifications
-       <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>
+       <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>, JSON
+       messages
+       <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
 
diff --git a/src/doc/man/generated_txt/cargo-pkgid.txt b/src/doc/man/generated_txt/cargo-pkgid.txt
@@ -18,8 +18,12 @@ DESCRIPTION
 
        A package specifier consists of a name, version, and source URL. You are
        allowed to use partial specifiers to succinctly match a specific package
-       as long as it matches only one package. The format of a spec can be one
-       of the following:
+       as long as it matches only one package. This specifier is also used by
+       other parts in Cargo, such as cargo-metadata(1) and JSON messages
+       <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
+       emitted by Cargo.
+
+       The format of a spec can be one of the following:
 
        +-----------------+--------------------------------------------------+
        | SPEC Structure  | Example SPEC                                     |
@@ -172,5 +176,7 @@ EXAMPLES
 SEE ALSO
        cargo(1), cargo-generate-lockfile(1), cargo-metadata(1), Package ID
        Specifications
-       <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>
+       <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>, JSON
+       messages
+       <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
 
diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md
@@ -334,8 +334,6 @@ 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
@@ -512,6 +510,8 @@ details on environment variables that Cargo reads.
        cargo metadata --format-version=1
 
 ## SEE ALSO
-[cargo(1)](cargo.html), [cargo-pkgid(1)](cargo-pkgid.html), [Package ID Specifications]
+
+[cargo(1)](cargo.html), [cargo-pkgid(1)](cargo-pkgid.html), [Package ID Specifications], [JSON messages]
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
+[JSON messages]: ../reference/external-tools.html#json-messages
diff --git a/src/doc/src/commands/cargo-pkgid.md b/src/doc/src/commands/cargo-pkgid.md
@@ -21,8 +21,10 @@ fetched.
 
 A package specifier consists of a name, version, and source URL. You are
 allowed to use partial specifiers to succinctly match a specific package as
-long as it matches only one package. The format of a _spec_ can be one of the
-following:
+long as it matches only one package. This specifier is also used by other parts
+in Cargo, such as [cargo-metadata(1)](cargo-metadata.html) and [JSON messages] emitted by Cargo.
+
+The format of a _spec_ can be one of the following:
 
 SPEC Structure             | Example SPEC
 ---------------------------|--------------
@@ -183,6 +185,9 @@ details on environment variables that Cargo reads.
        cargo pkgid file:///path/to/local/package#foo
 
 ## SEE ALSO
-[cargo(1)](cargo.html), [cargo-generate-lockfile(1)](cargo-generate-lockfile.html), [cargo-metadata(1)](cargo-metadata.html), [Package ID Specifications]
+
+[cargo(1)](cargo.html), [cargo-generate-lockfile(1)](cargo-generate-lockfile.html), [cargo-metadata(1)](cargo-metadata.html),
+[Package ID Specifications], [JSON messages]
 
 [Package ID Specifications]: ../reference/pkgid-spec.html
+[JSON messages]: ../reference/external-tools.html#json-messages
diff --git a/src/doc/src/reference/external-tools.md b/src/doc/src/reference/external-tools.md
@@ -42,6 +42,9 @@ information during the build:
 
 The output goes to stdout in the JSON object per line format. The `reason` field
 distinguishes different kinds of messages.
+The `package_id` field is a unique identifier for referring to the package, and
+as the `--package` argument to many commands. The syntax grammar can be found in
+chapter [Package ID Specifications].
 
 The `--message-format` option can also take additional formatting values which
 alter the way the JSON messages are computed and rendered. See the description
@@ -53,6 +56,7 @@ messages.
 
 [build command documentation]: ../commands/cargo-build.md
 [cargo_metadata]: https://crates.io/crates/cargo_metadata
+[Package ID Specifications]: ./pkgid-spec.md
 
 ### Compiler messages
 
@@ -66,7 +70,7 @@ structure:
     /* The "reason" indicates the kind of message. */
     "reason": "compiler-message",
     /* The Package ID, a unique identifier for referring to the package. */
-    "package_id": "my-package 0.1.0 (path+file:///path/to/my-package)",
+    "package_id": "file:///path/to/my-package#0.1.0",
     /* Absolute path to the package manifest. */
     "manifest_path": "/path/to/my-package/Cargo.toml",
     /* The Cargo target (lib, bin, example, etc.) that generated the message. */
@@ -135,7 +139,7 @@ following structure:
     /* The "reason" indicates the kind of message. */
     "reason": "compiler-artifact",
     /* The Package ID, a unique identifier for referring to the package. */
-    "package_id": "my-package 0.1.0 (path+file:///path/to/my-package)",
+    "package_id": "file:///path/to/my-package#0.1.0",
     /* Absolute path to the package manifest. */
     "manifest_path": "/path/to/my-package/Cargo.toml",
     /* The Cargo target (lib, bin, example, etc.) that generated the artifacts.
@@ -204,7 +208,7 @@ may be found in [the chapter on build scripts](build-scripts.md).
     /* The "reason" indicates the kind of message. */
     "reason": "build-script-executed",
     /* The Package ID, a unique identifier for referring to the package. */
-    "package_id": "my-package 0.1.0 (path+file:///path/to/my-package)",
+    "package_id": "file:///path/to/my-package#0.1.0",
     /* Array of libraries to link, as indicated by the `cargo::rustc-link-lib`
        instruction. Note that this may include a "KIND=" prefix in the string
        where KIND is the library kind.
diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1
@@ -55,8 +55,8 @@ 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": "file:///path/to/my\-package#0.1.0",
             /* The license value from the manifest, or null. */
@@ -529,4 +529,4 @@ cargo metadata \-\-format\-version=1
 .RE
 .RE
 .SH "SEE ALSO"
-\fBcargo\fR(1), \fBcargo\-pkgid\fR(1), \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>
+\fBcargo\fR(1), \fBcargo\-pkgid\fR(1), \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>, \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
diff --git a/src/etc/man/cargo-pkgid.1 b/src/etc/man/cargo-pkgid.1
@@ -19,8 +19,10 @@ fetched.
 .sp
 A package specifier consists of a name, version, and source URL. You are
 allowed to use partial specifiers to succinctly match a specific package as
-long as it matches only one package. The format of a \fIspec\fR can be one of the
-following:
+long as it matches only one package. This specifier is also used by other parts
+in Cargo, such as \fBcargo\-metadata\fR(1) and \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> emitted by Cargo.
+.sp
+The format of a \fIspec\fR can be one of the following:
 
 .TS
 allbox tab(:);
@@ -242,4 +244,5 @@ cargo pkgid file:///path/to/local/package#foo
 .RE
 .RE
 .SH "SEE ALSO"
-\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1), \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>
+\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1),
+\fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>, \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
diff --git a/tests/testsuite/binary_name.rs b/tests/testsuite/binary_name.rs
@@ -280,7 +280,7 @@ fn check_msg_format_json() {
     let output = r#"
 {
     "reason": "compiler-artifact",
-    "package_id": "foo 0.0.1 [..]",
+    "package_id": "path+file:///[..]/foo#0.0.1",
     "manifest_path": "[CWD]/Cargo.toml",
     "target": "{...}",
     "profile": "{...}",
diff --git a/tests/testsuite/build.rs b/tests/testsuite/build.rs
@@ -4160,7 +4160,7 @@ fn compiler_json_error_format() {
         r#"
             {
                 "reason":"compiler-artifact",
-                "package_id":"foo 0.5.0 ([..])",
+                "package_id":"path+file:///[..]/foo#0.5.0",
                 "manifest_path": "[..]",
                 "target":{
                     "kind":["custom-build"],
@@ -4187,7 +4187,7 @@ fn compiler_json_error_format() {
 
             {
                 "reason":"compiler-message",
-                "package_id":"bar 0.5.0 ([..])",
+                "package_id":"path+file:///[..]/bar#0.5.0",
                 "manifest_path": "[..]",
                 "target":{
                     "kind":["lib"],
@@ -4213,7 +4213,7 @@ fn compiler_json_error_format() {
                 },
                 "executable": null,
                 "features": [],
-                "package_id":"bar 0.5.0 ([..])",
+                "package_id":"path+file:///[..]/bar#0.5.0",
                 "manifest_path": "[..]",
                 "target":{
                     "kind":["lib"],
@@ -4234,7 +4234,7 @@ fn compiler_json_error_format() {
 
             {
                 "reason":"build-script-executed",
-                "package_id":"foo 0.5.0 ([..])",
+                "package_id":"path+file:///[..]/foo#0.5.0",
                 "linked_libs":[],
                 "linked_paths":[],
                 "env":[],
@@ -4244,7 +4244,7 @@ fn compiler_json_error_format() {
 
             {
                 "reason":"compiler-message",
-                "package_id":"foo 0.5.0 ([..])",
+                "package_id":"path+file:///[..]/foo#0.5.0",
                 "manifest_path": "[..]",
                 "target":{
                     "kind":["bin"],
@@ -4261,7 +4261,7 @@ fn compiler_json_error_format() {
 
             {
                 "reason":"compiler-artifact",
-                "package_id":"foo 0.5.0 ([..])",
+                "package_id":"path+file:///[..]/foo#0.5.0",
                 "manifest_path": "[..]",
                 "target":{
                     "kind":["bin"],
@@ -4332,7 +4332,7 @@ fn message_format_json_forward_stderr() {
             r#"
                 {
                     "reason":"compiler-message",
-                    "package_id":"foo 0.5.0 ([..])",
+                    "package_id":"path+file:///[..]/foo#0.5.0",
                     "manifest_path": "[..]",
                     "target":{
                         "kind":["bin"],
@@ -4349,7 +4349,7 @@ fn message_format_json_forward_stderr() {
 
                 {
                     "reason":"compiler-artifact",
-                    "package_id":"foo 0.5.0 ([..])",
+                    "package_id":"path+file:///[..]/foo#0.5.0",
                     "manifest_path": "[..]",
                     "target":{
                         "kind":["bin"],
diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs
diff --git a/tests/testsuite/install.rs b/tests/testsuite/install.rs
diff --git a/tests/testsuite/metabuild.rs b/tests/testsuite/metabuild.rs
diff --git a/tests/testsuite/test.rs b/tests/testsuite/test.rs
