short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/generated/cargo-build.html b/src/doc/man/generated/cargo-build.html
index 6fe378bc804..ab6f0a752f1 100644
--- a/src/doc/man/generated/cargo-build.html
+++ b/src/doc/man/generated/cargo-build.html
@@ -255,7 +255,9 @@
short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/generated/cargo-check.html b/src/doc/man/generated/cargo-check.html
index 3af41f8fc53..32bc64ceb08 100644
--- a/src/doc/man/generated/cargo-check.html
+++ b/src/doc/man/generated/cargo-check.html
@@ -257,7 +257,9 @@
short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/generated/cargo-doc.html b/src/doc/man/generated/cargo-doc.html
index 515cc0e2911..ef3d4eadda3 100644
--- a/src/doc/man/generated/cargo-doc.html
+++ b/src/doc/man/generated/cargo-doc.html
@@ -227,7 +227,9 @@
short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/generated/cargo-fix.html b/src/doc/man/generated/cargo-fix.html
index 0a897a451be..46ef49e0864 100644
--- a/src/doc/man/generated/cargo-fix.html
+++ b/src/doc/man/generated/cargo-fix.html
@@ -328,7 +328,9 @@
short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/generated/cargo-run.html b/src/doc/man/generated/cargo-run.html
index ef73037a135..2eff28c0aaa 100644
--- a/src/doc/man/generated/cargo-run.html
+++ b/src/doc/man/generated/cargo-run.html
@@ -179,7 +179,9 @@
short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/generated/cargo-rustc.html b/src/doc/man/generated/cargo-rustc.html
index 9a17d8b736b..e46e13e6a2c 100644
--- a/src/doc/man/generated/cargo-rustc.html
+++ b/src/doc/man/generated/cargo-rustc.html
@@ -240,7 +240,9 @@
short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/generated/cargo-rustdoc.html b/src/doc/man/generated/cargo-rustdoc.html
index 4c02f893eb4..c4daa0e977b 100644
--- a/src/doc/man/generated/cargo-rustdoc.html
+++ b/src/doc/man/generated/cargo-rustdoc.html
@@ -255,7 +255,9 @@
short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/generated/cargo-test.html b/src/doc/man/generated/cargo-test.html
index 29ce85d416c..8c3ac2fe5d7 100644
--- a/src/doc/man/generated/cargo-test.html
+++ b/src/doc/man/generated/cargo-test.html
@@ -346,7 +346,9 @@
short: Emit shorter, human-readable text messages.
json: Emit JSON messages to stdout.
json: Emit JSON messages to stdout. See
+the reference
+for more details.
json-diagnostic-short: Ensure the rendered field of JSON messages contains
diff --git a/src/doc/man/options-message-format.adoc b/src/doc/man/options-message-format.adoc
index fa5922a5d9a..818d78f8127 100644
--- a/src/doc/man/options-message-format.adoc
+++ b/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
diff --git a/src/doc/src/reference/external-tools.md b/src/doc/src/reference/external-tools.md
index ea055fcc905..e2440e83760 100644
--- a/src/doc/src/reference/external-tools.md
+++ b/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
diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1
index c3f5d9d0d27..33eca8c000d 100644
--- a/src/etc/man/cargo-bench.1
+++ b/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
diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1
index 79cd83a43af..d078ceaf7cf 100644
--- a/src/etc/man/cargo-build.1
+++ b/src/etc/man/cargo-build.1
@@ -298,7 +298,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
diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1
index bf24fd4d2cc..20f9b0b0b65 100644
--- a/src/etc/man/cargo-check.1
+++ b/src/etc/man/cargo-check.1
@@ -298,7 +298,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
diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1
index a0ced6de6bd..39b9f077ab3 100644
--- a/src/etc/man/cargo-doc.1
+++ b/src/etc/man/cargo-doc.1
@@ -257,7 +257,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
diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1
index b8ec22b305b..c1f290042bc 100644
--- a/src/etc/man/cargo-fix.1
+++ b/src/etc/man/cargo-fix.1
@@ -368,7 +368,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
diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1
index c0005fe5d1a..eb3a5376030 100644
--- a/src/etc/man/cargo-run.1
+++ b/src/etc/man/cargo-run.1
@@ -2,12 +2,12 @@
.\" Title: cargo-run
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-09-05
+.\" Date: 2019-11-11
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-RUN" "1" "2019-09-05" "\ \&" "\ \&"
+.TH "CARGO\-RUN" "1" "2019-11-11" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -209,7 +209,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
diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1
index f8a2d7cbe3f..e179c2d117a 100644
--- a/src/etc/man/cargo-rustc.1
+++ b/src/etc/man/cargo-rustc.1
@@ -278,7 +278,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
diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1
index f606aea6c9d..98f31b656f2 100644
--- a/src/etc/man/cargo-rustdoc.1
+++ b/src/etc/man/cargo-rustdoc.1
@@ -288,7 +288,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
diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1
index 9ad135d6e2a..bade8a1c982 100644
--- a/src/etc/man/cargo-test.1
+++ b/src/etc/man/cargo-test.1
@@ -431,7 +431,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