Auto merge of #64925 - ehuss:document-json, r=Mark-Simulacrum
Document JSON message output. This documents the JSON messages in the rustc book.
This commit is contained in:
commit
518deda77f
|
@ -10,6 +10,7 @@
|
|||
- [Warn-by-default lints](lints/listing/warn-by-default.md)
|
||||
- [Deny-by-default lints](lints/listing/deny-by-default.md)
|
||||
- [Codegen options](codegen-options/index.md)
|
||||
- [JSON Output](json.md)
|
||||
- [Targets](targets/index.md)
|
||||
- [Built-in Targets](targets/built-in.md)
|
||||
- [Custom Targets](targets/custom.md)
|
||||
|
|
|
@ -92,6 +92,7 @@ information about editions may be found in the [edition guide].
|
|||
[edition guide]: ../edition-guide/introduction.html
|
||||
|
||||
## `--emit`: specifies the types of output files to generate
|
||||
<a id="option-emit"></a>
|
||||
|
||||
This flag controls the types of output files generated by the compiler. It
|
||||
accepts a comma-separated list of values, and may be specified multiple times.
|
||||
|
@ -241,12 +242,13 @@ The "sysroot" is where `rustc` looks for the crates that come with the Rust
|
|||
distribution; this flag allows that to be overridden.
|
||||
|
||||
## `--error-format`: control how errors are produced
|
||||
<a id="option-error-format"></a>
|
||||
|
||||
This flag lets you control the format of messages. Messages are printed to
|
||||
stderr. The valid options are:
|
||||
|
||||
- `human` — Human-readable output. This is the default.
|
||||
- `json` — Structured JSON output.
|
||||
- `json` — Structured JSON output. See [the JSON chapter] for more detail.
|
||||
- `short` — Short, one-line messages.
|
||||
|
||||
## `--color`: configure coloring of output
|
||||
|
@ -273,6 +275,7 @@ pathname syntax. For example `--remap-path-prefix foo=bar` will match
|
|||
`foo/lib.rs` but not `./foo/lib.rs`.
|
||||
|
||||
## `--json`: configure json messages printed by the compiler
|
||||
<a id="option-json"></a>
|
||||
|
||||
When the `--error-format=json` option is passed to rustc then all of the
|
||||
compiler's diagnostic output will be emitted in the form of JSON blobs. The
|
||||
|
@ -305,9 +308,13 @@ to customize the output:
|
|||
Note that it is invalid to combine the `--json` argument with the `--color`
|
||||
argument, and it is required to combine `--json` with `--error-format=json`.
|
||||
|
||||
See [the JSON chapter] for more detail.
|
||||
|
||||
## `@path`: load command-line flags from a path
|
||||
|
||||
If you specify `@path` on the command-line, then it will open `path` and read
|
||||
command line options from it. These options are one per line; a blank line indicates
|
||||
an empty option. The file can use Unix or Windows style line endings, and must be
|
||||
encoded as UTF-8.
|
||||
|
||||
[the JSON chapter]: json.md
|
||||
|
|
|
@ -0,0 +1,231 @@
|
|||
# JSON Output
|
||||
|
||||
This chapter documents the JSON structures emitted by `rustc`. JSON may be
|
||||
enabled with the [`--error-format=json` flag][option-error-format]. Additional
|
||||
options may be specified with the [`--json` flag][option-json] which can
|
||||
change which messages are generated, and the format of the messages.
|
||||
|
||||
JSON messages are emitted one per line to stderr.
|
||||
|
||||
If parsing the output with Rust, the
|
||||
[`cargo_metadata`](https://crates.io/crates/cargo_metadata) crate provides
|
||||
some support for parsing the messages.
|
||||
|
||||
When parsing, care should be taken to be forwards-compatible with future changes
|
||||
to the format. Optional values may be `null`. New fields may be added. Enumerated
|
||||
fields like "level" or "suggestion_applicability" may add new values.
|
||||
|
||||
## Diagnostics
|
||||
|
||||
Diagnostic messages provide errors or possible concerns generated during
|
||||
compilation. `rustc` provides detailed information about where the diagnostic
|
||||
originates, along with hints and suggestions.
|
||||
|
||||
Diagnostics are arranged in a parent/child relationship where the parent
|
||||
diagnostic value is the core of the diagnostic, and the attached children
|
||||
provide additional context, help, and information.
|
||||
|
||||
Diagnostics have the following format:
|
||||
|
||||
```javascript
|
||||
{
|
||||
/* The primary message. */
|
||||
"message": "unused variable: `x`",
|
||||
/* The diagnostic code.
|
||||
Some messages may set this value to null.
|
||||
*/
|
||||
"code": {
|
||||
/* A unique string identifying which diagnostic triggered. */
|
||||
"code": "unused_variables",
|
||||
/* An optional string explaining more detail about the diagnostic code. */
|
||||
"explanation": null
|
||||
},
|
||||
/* The severity of the diagnostic.
|
||||
Values may be:
|
||||
- "error": A fatal error that prevents compilation.
|
||||
- "warning": A possible error or concern.
|
||||
- "note": Additional information or context about the diagnostic.
|
||||
- "help": A suggestion on how to resolve the diagnostic.
|
||||
- "failure-note": A note attached to the message for further information.
|
||||
- "error: internal compiler error": Indicates a bug within the compiler.
|
||||
*/
|
||||
"level": "warning",
|
||||
/* An array of source code locations to point out specific details about
|
||||
where the diagnostic originates from. This may be empty, for example
|
||||
for some global messages, or child messages attached to a parent.
|
||||
|
||||
Character offsets are offsets of Unicode Scalar Values.
|
||||
*/
|
||||
"spans": [
|
||||
{
|
||||
/* The file where the span is located.
|
||||
For spans located within a macro expansion, this will be the
|
||||
name of the expanded macro in the format "<MACRONAME macros>".
|
||||
*/
|
||||
"file_name": "lib.rs",
|
||||
/* The byte offset where the span starts (0-based, inclusive). */
|
||||
"byte_start": 21,
|
||||
/* The byte offset where the span ends (0-based, exclusive). */
|
||||
"byte_end": 22,
|
||||
/* The first line number of the span (1-based, inclusive). */
|
||||
"line_start": 2,
|
||||
/* The last line number of the span (1-based, inclusive). */
|
||||
"line_end": 2,
|
||||
/* The first character offset of the line_start (1-based, inclusive). */
|
||||
"column_start": 9,
|
||||
/* The last character offset of the line_end (1-based, exclusive). */
|
||||
"column_end": 10,
|
||||
/* Whether or not this is the "primary" span.
|
||||
|
||||
This indicates that this span is the focal point of the
|
||||
diagnostic.
|
||||
|
||||
There are rare cases where multiple spans may be marked as
|
||||
primary. For example, "immutable borrow occurs here" and
|
||||
"mutable borrow ends here" can be two separate primary spans.
|
||||
|
||||
The top (parent) message should always have at least one
|
||||
primary span, unless it has zero spans. Child messages may have
|
||||
zero or more primary spans.
|
||||
*/
|
||||
"is_primary": true,
|
||||
/* An array of objects showing the original source code for this
|
||||
span. This shows the entire lines of text where the span is
|
||||
located. A span across multiple lines will have a separate
|
||||
value for each line.
|
||||
*/
|
||||
"text": [
|
||||
{
|
||||
/* The entire line of the original source code. */
|
||||
"text": " let x = 123;",
|
||||
/* The first character offset of the line of
|
||||
where the span covers this line (1-based, inclusive). */
|
||||
"highlight_start": 9,
|
||||
/* The last character offset of the line of
|
||||
where the span covers this line (1-based, exclusive). */
|
||||
"highlight_end": 10
|
||||
}
|
||||
],
|
||||
/* An optional message to display at this span location.
|
||||
This is typically null for primary spans.
|
||||
*/
|
||||
"label": null,
|
||||
/* An optional string of a suggested replacement for this span to
|
||||
solve the issue. Tools may try to replace the contents of the
|
||||
span with this text.
|
||||
*/
|
||||
"suggested_replacement": null,
|
||||
/* An optional string that indicates the confidence of the
|
||||
"suggested_replacement". Tools may use this value to determine
|
||||
whether or not suggestions should be automatically applied.
|
||||
|
||||
Possible values may be:
|
||||
- "MachineApplicable": The suggestion is definitely what the
|
||||
user intended. This suggestion should be automatically
|
||||
applied.
|
||||
- "MaybeIncorrect": The suggestion may be what the user
|
||||
intended, but it is uncertain. The suggestion should result
|
||||
in valid Rust code if it is applied.
|
||||
- "HasPlaceholders": The suggestion contains placeholders like
|
||||
`(...)`. The suggestion cannot be applied automatically
|
||||
because it will not result in valid Rust code. The user will
|
||||
need to fill in the placeholders.
|
||||
- "Unspecified": The applicability of the suggestion is unknown.
|
||||
*/
|
||||
"suggestion_applicability": null,
|
||||
/* An optional object indicating the expansion of a macro within
|
||||
this span.
|
||||
|
||||
If a message occurs within a macro invocation, this object will
|
||||
provide details of where within the macro expansion the message
|
||||
is located.
|
||||
*/
|
||||
"expansion": {
|
||||
/* The span of the macro invocation.
|
||||
Uses the same span definition as the "spans" array.
|
||||
*/
|
||||
"span": {/*...*/}
|
||||
/* Name of the macro, such as "foo!" or "#[derive(Eq)]". */
|
||||
"macro_decl_name": "some_macro!",
|
||||
/* Optional span where the relevant part of the macro is
|
||||
defined. */
|
||||
"def_site_span": {/*...*/},
|
||||
}
|
||||
}
|
||||
],
|
||||
/* Array of attached diagnostic messages.
|
||||
This is an array of objects using the same format as the parent
|
||||
message. Children are not nested (children do not themselves
|
||||
contain "children" definitions).
|
||||
*/
|
||||
"children": [
|
||||
{
|
||||
"message": "`#[warn(unused_variables)]` on by default",
|
||||
"code": null,
|
||||
"level": "note",
|
||||
"spans": [],
|
||||
"children": [],
|
||||
"rendered": null
|
||||
},
|
||||
{
|
||||
"message": "consider prefixing with an underscore",
|
||||
"code": null,
|
||||
"level": "help",
|
||||
"spans": [
|
||||
{
|
||||
"file_name": "lib.rs",
|
||||
"byte_start": 21,
|
||||
"byte_end": 22,
|
||||
"line_start": 2,
|
||||
"line_end": 2,
|
||||
"column_start": 9,
|
||||
"column_end": 10,
|
||||
"is_primary": true,
|
||||
"text": [
|
||||
{
|
||||
"text": " let x = 123;",
|
||||
"highlight_start": 9,
|
||||
"highlight_end": 10
|
||||
}
|
||||
],
|
||||
"label": null,
|
||||
"suggested_replacement": "_x",
|
||||
"suggestion_applicability": "MachineApplicable",
|
||||
"expansion": null
|
||||
}
|
||||
],
|
||||
"children": [],
|
||||
"rendered": null
|
||||
}
|
||||
],
|
||||
/* Optional string of the rendered version of the diagnostic as displayed
|
||||
by rustc. Note that this may be influenced by the `--json` flag.
|
||||
*/
|
||||
"rendered": "warning: unused variable: `x`\n --> lib.rs:2:9\n |\n2 | let x = 123;\n | ^ help: consider prefixing with an underscore: `_x`\n |\n = note: `#[warn(unused_variables)]` on by default\n\n"
|
||||
}
|
||||
```
|
||||
|
||||
## Artifact notifications
|
||||
|
||||
Artifact notifications are emitted when the [`--json=artifacts`
|
||||
flag][option-json] is used. They indicate that a file artifact has been saved
|
||||
to disk. More information about emit kinds may be found in the [`--emit`
|
||||
flag][option-emit] documentation.
|
||||
|
||||
```javascript
|
||||
{
|
||||
/* The filename that was generated. */
|
||||
"artifact": "libfoo.rlib",
|
||||
/* The kind of artifact that was generated. Possible values:
|
||||
- "link": The generated crate as specified by the crate-type.
|
||||
- "dep-info": The `.d` file with dependency information in a Makefile-like syntax.
|
||||
- "metadata": The Rust `.rmeta` file containing metadata about the crate.
|
||||
- "save-analysis": A JSON file emitted by the `-Zsave-analysis` feature.
|
||||
*/
|
||||
"emit": "link"
|
||||
}
|
||||
```
|
||||
|
||||
[option-emit]: command-line-arguments.md#option-emit
|
||||
[option-error-format]: command-line-arguments.md#option-error-format
|
||||
[option-json]: command-line-arguments.md#option-json
|
Loading…
Reference in New Issue