Skip to content

Commit

Permalink
Auto merge of #7595 - ehuss:doc-json, r=Eh2406
Browse files Browse the repository at this point in the history
Document Cargo's JSON output.

This adds some documentation explaining Cargo's `--message-format=json` output.
  • Loading branch information
bors committed Nov 16, 2019
2 parents 4aa17ed + a280f8a commit e55600b
Show file tree
Hide file tree
Showing 20 changed files with 246 additions and 72 deletions.
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-bench.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-build.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-check.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-doc.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-fix.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-run.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-rustc.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-rustdoc.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/generated/cargo-test.html
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/doc/man/options-message-format.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
225 changes: 176 additions & 49 deletions src/doc/src/reference/external-tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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:
Expand All @@ -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

Expand Down
9 changes: 6 additions & 3 deletions src/etc/man/cargo-bench.1
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit e55600b

Please sign in to comment.