Auto merge of #7595 - ehuss:doc-json, r=Eh2406

Document Cargo's JSON output.

This adds some documentation explaining Cargo's `--message-format=json` output.

src/doc/man/generated/cargo-bench.html

@@ -321,7 +321,9 @@ <h3 id="cargo_bench_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/generated/cargo-build.html

@@ -255,7 +255,9 @@ <h3 id="cargo_build_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/generated/cargo-check.html

@@ -257,7 +257,9 @@ <h3 id="cargo_check_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/generated/cargo-doc.html

@@ -227,7 +227,9 @@ <h3 id="cargo_doc_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/generated/cargo-fix.html

@@ -328,7 +328,9 @@ <h3 id="cargo_fix_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/generated/cargo-run.html

@@ -179,7 +179,9 @@ <h3 id="cargo_run_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/generated/cargo-rustc.html

@@ -240,7 +240,9 @@ <h3 id="cargo_rustc_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/generated/cargo-rustdoc.html

@@ -255,7 +255,9 @@ <h3 id="cargo_rustdoc_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/generated/cargo-test.html

@@ -346,7 +346,9 @@ <h3 id="cargo_test_display_options">Display Options</h3>
 <p><code>short</code>: Emit shorter, human-readable text messages.</p>
 </li>
 <li>
-<p><code>json</code>: Emit JSON messages to stdout.</p>
+<p><code>json</code>: Emit JSON messages to stdout. See
+<a href="../reference/external-tools.html#json-messages">the reference</a>
+for more details.</p>
 </li>
 <li>
 <p><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains

src/doc/man/options-message-format.adoc

@@ -4,7 +4,9 @@
 +
 - `human` (default): Display in a human-readable text format.
 - `short`: Emit shorter, human-readable text messages.
-- `json`: Emit JSON messages to stdout.
+- `json`: Emit JSON messages to stdout. See
+  linkcargo:reference/external-tools.html#json-messages[the reference]
+  for more details.
 - `json-diagnostic-short`: Ensure the `rendered` field of JSON messages contains
   the "short" rendering from rustc.
 - `json-diagnostic-rendered-ansi`: Ensure the `rendered` field of JSON messages

src/doc/src/reference/external-tools.md

@@ -4,7 +4,7 @@ One of the goals of Cargo is simple integration with third-party tools, like
 IDEs and other build systems. To make integration easier, Cargo has several
 facilities:
 
-* a `cargo metadata` command, which outputs package structure and dependencies
+* a [`cargo metadata`] command, which outputs package structure and dependencies
   information in JSON,
 
 * a `--message-format` flag, which outputs information about a particular build,
@@ -15,60 +15,21 @@ facilities:
 
 ### Information about package structure
 
-You can use `cargo metadata` command to get information about package structure
-and dependencies. The output of the command looks like this:
-
-```text
-{
-  // Integer version number of the format.
-  "version": integer,
-
-  // List of packages for this workspace, including dependencies.
-  "packages": [
-    {
-      // Opaque package identifier.
-      "id": PackageId,
-
-      "name": string,
-
-      "version": string,
-
-      "source": SourceId,
-
-      // A list of declared dependencies, see `resolve` field for actual dependencies.
-      "dependencies": [ Dependency ],
-
-      "targets: [ Target ],
-
-      // Path to Cargo.toml
-      "manifest_path": string,
-    }
-  ],
-
-  "workspace_members": [ PackageId ],
-
-  // Dependencies graph.
-  "resolve": {
-     "nodes": [
-       {
-         "id": PackageId,
-         "dependencies": [ PackageId ]
-       }
-     ]
-  }
-}
-```
+You can use [`cargo metadata`] command to get information about package
+structure and dependencies. See the [`cargo metadata`] documentation
+for details on the format of the output.
 
 The format is stable and versioned. When calling `cargo metadata`, you should
 pass `--format-version` flag explicitly to avoid forward incompatibility
 hazard.
 
-If you are using Rust, there is [cargo_metadata] crate.
+If you are using Rust, the [cargo_metadata] crate can be used to parse the
+output.
 
 [cargo_metadata]: https://crates.io/crates/cargo_metadata
+[`cargo metadata`]: ../commands/cargo-metadata.md
 
-
-### Information about build
+### JSON messages
 
 When passing `--message-format=json`, Cargo will output the following
 information during the build:
@@ -82,9 +43,175 @@ information during the build:
 The output goes to stdout in the JSON object per line format. The `reason` field
 distinguishes different kinds of messages.
 
-Information about dependencies in the Makefile-compatible format is stored in
-the `.d` files alongside the artifacts.
+The `--message-format` option can also take additional formatting values which
+alter the way the JSON messages are computed and rendered. See the description
+of the `--message-format` option in the [build command documentation] for more
+details.
 
+[build command documentation]: ../commands/cargo-build.md
+
+#### Compiler messages
+
+The "compiler-message" message includes output from the compiler, such as
+warnings and errors. See the [rustc JSON chapter](../../rustc/json.md) for
+details on `rustc`'s message format, which is embedded in the following
+structure:
+
+```javascript
+{
+    /* 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)",
+    /* The Cargo target (lib, bin, example, etc.) that generated the message. */
+    "target": {
+        /* Array of target kinds.
+           - lib targets list the `crate-type` values from the
+             manifest such as "lib", "rlib", "dylib",
+             "proc-macro", etc. (default ["lib"])
+           - binary is ["bin"]
+           - example is ["example"]
+           - integration test is ["test"]
+           - benchmark is ["bench"]
+           - build script is ["custom-build"]
+        */
+        "kind": [
+            "lib"
+        ],
+        /* Array of crate types.
+           - lib and example libraries list the `crate-type` values
+             from the manifest such as "lib", "rlib", "dylib",
+             "proc-macro", etc. (default ["lib"])
+           - all other target kinds are ["bin"]
+        */
+        "crate_types": [
+            "lib"
+        ],
+        /* The name of the target. */
+        "name": "my-package",
+        /* Absolute path to the root source file of the target. */
+        "src_path": "/path/to/my-package/src/lib.rs",
+        /* The Rust edition of the target.
+           Defaults to the package edition.
+        */
+        "edition": "2018",
+        /* Array of required features.
+           This property is not included if no required features are set.
+        */
+        "required-features": ["feat1"],
+        /* Whether or not this target has doc tests enabled, and
+           the target is compatible with doc testing.
+        */
+        "doctest": true
+    },
+    /* The message emitted by the compiler.
+
+    See https://doc.rust-lang.org/rustc/json.html for details.
+    */
+    "message": {
+        /* ... */
+    }
+}
+```
+
+#### Artifact messages
+
+For every compilation step, a "compiler-artifact" message is emitted with the
+following structure:
+
+```javascript
+{
+    /* 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)",
+    /* The Cargo target (lib, bin, example, etc.) that generated the artifacts.
+       See the definition above for `compiler-message` for details.
+    */
+    "target": {
+        "kind": [
+            "lib"
+        ],
+        "crate_types": [
+            "lib"
+        ],
+        "name": "my-package",
+        "src_path": "/path/to/my-package/src/lib.rs",
+        "edition": "2018",
+        "doctest": true
+    },
+    /* The profile indicates which compiler settings were used. */
+    "profile": {
+        /* The optimization level. */
+        "opt_level": "0",
+        /* The debug level, an integer of 0, 1, or 2. If `null`, it implies
+           rustc's default of 0.
+        */
+        "debuginfo": 2,
+        /* Whether or not debug assertions are enabled. */
+        "debug_assertions": true,
+        /* Whether or not overflow checks are enabled. */
+        "overflow_checks": true,
+        /* Whether or not the `--test` flag is used. */
+        "test": false
+    },
+    /* Array of features enabled. */
+    "features": ["feat1", "feat2"],
+    /* Array of files generated by this step. */
+    "filenames": [
+        "/path/to/my-package/target/debug/libmy_package.rlib",
+        "/path/to/my-package/target/debug/deps/libmy_package-be9f3faac0a26ef0.rmeta"
+    ],
+    /* A string of the path to the executable that was created, or null if
+       this step did not generate an executable.
+    */
+    "executable": null,
+    /* Whether or not this step was actually executed.
+       When `true`, this means that the pre-existing artifacts were
+       up-to-date, and `rustc` was not executed. When `false`, this means that
+       `rustc` was run to generate the artifacts.
+    */
+    "fresh": true
+}
+
+```
+
+#### Build script output
+
+The "build-script-executed" message includes the parsed output of a build
+script. Note that this is emitted even if the build script is not run; it will
+display the previously cached value. More details about build script output
+may be found in [the chapter on build scripts](build-scripts.md).
+
+```javascript
+{
+    /* 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)",
+    /* 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.
+    */
+    "linked_libs": ["foo", "static=bar"],
+    /* Array of paths to include in the library search path, as indicated by
+       the `cargo:rustc-link-search` instruction. Note that this may include a
+       "KIND=" prefix in the string where KIND is the library kind.
+    */
+    "linked_paths": ["/some/path", "native=/another/path"],
+    /* Array of cfg values to enable, as indicated by the `cargo:rustc-cfg`
+       instruction.
+    */
+    "cfgs": ["cfg1", "cfg2=\"string\""],
+    /* Array of [KEY, VALUE] arrays of environment variables to set, as
+       indicated by the `cargo:rustc-env` instruction.
+    */
+    "env": [
+        ["SOME_KEY", "some value"],
+        ["ANOTHER_KEY", "another value"]
+    ]
+}
+```
 
 ### Custom subcommands
 

src/etc/man/cargo-bench.1

@@ -2,12 +2,12 @@
 .\"     Title: cargo-bench
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 2.0.10
-.\"      Date: 2019-09-05
+.\"      Date: 2019-11-15
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-BENCH" "1" "2019-09-05" "\ \&" "\ \&"
+.TH "CARGO\-BENCH" "1" "2019-11-15" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -389,7 +389,10 @@ and consists of comma\-separated values. Valid values:
 .  sp -1
 .  IP \(bu 2.3
 .\}
-\fBjson\fP: Emit JSON messages to stdout.
+\fBjson\fP: Emit JSON messages to stdout. See
+\c
+.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference"
+for more details.
 .RE
 .sp
 .RS 4