[rustc.git] / src / doc / rustc / src / json.md

# 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.
               Note that this path may not exist. For example, if the path
               points to the standard library, and the rust src is not
               available in the sysroot, then it may point to a non-existent
               file. Beware that this may also point to the source of an
               external crate.
            */
            "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": "if this is intentional, prefix it 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: if this is intentional, prefix it 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"
}
```

## Future-incompatible reports

If the [`--json=future-incompat`][option-json] flag is used, then a separate
JSON structure will be emitted if the crate may stop compiling in the future.
This contains diagnostic information about the particular warnings that may be
turned into a hard error in the future. This will include the diagnostic
information, even if the diagnostics have been suppressed (such as with an
`#[allow]` attribute or the `--cap-lints` option).

```javascript
{
    /* An array of objects describing a warning that will become a hard error
       in the future.
    */
    "future_incompat_report":
    [
        {
            /* A diagnostic structure as defined in
               https://doc.rust-lang.org/rustc/json.html#diagnostics
            */
            "diagnostic": {...},
        }
    ]
}
```

[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
Commit	Line	Data
e74abb32 XL	1	# JSON Output
	2
	3	This chapter documents the JSON structures emitted by `rustc`. JSON may be
	4	enabled with the [`--error-format=json` flag][option-error-format]. Additional
	5	options may be specified with the [`--json` flag][option-json] which can
	6	change which messages are generated, and the format of the messages.
	7
	8	JSON messages are emitted one per line to stderr.
	9
	10	If parsing the output with Rust, the
	11	[`cargo_metadata`](https://crates.io/crates/cargo_metadata) crate provides
	12	some support for parsing the messages.
	13
	14	When parsing, care should be taken to be forwards-compatible with future changes
	15	to the format. Optional values may be `null`. New fields may be added. Enumerated
	16	fields like "level" or "suggestion_applicability" may add new values.
	17
	18	## Diagnostics
	19
	20	Diagnostic messages provide errors or possible concerns generated during
	21	compilation. `rustc` provides detailed information about where the diagnostic
	22	originates, along with hints and suggestions.
	23
	24	Diagnostics are arranged in a parent/child relationship where the parent
	25	diagnostic value is the core of the diagnostic, and the attached children
	26	provide additional context, help, and information.
	27
	28	Diagnostics have the following format:
	29
	30	```javascript
	31	{
	32	/* The primary message. */
	33	"message": "unused variable: `x`",
	34	/* The diagnostic code.
	35	Some messages may set this value to null.
	36	*/
	37	"code": {
	38	/* A unique string identifying which diagnostic triggered. */
	39	"code": "unused_variables",
	40	/* An optional string explaining more detail about the diagnostic code. */
	41	"explanation": null
	42	},
	43	/* The severity of the diagnostic.
	44	Values may be:
	45	- "error": A fatal error that prevents compilation.
	46	- "warning": A possible error or concern.
	47	- "note": Additional information or context about the diagnostic.
	48	- "help": A suggestion on how to resolve the diagnostic.
	49	- "failure-note": A note attached to the message for further information.
	50	- "error: internal compiler error": Indicates a bug within the compiler.
	51	*/
	52	"level": "warning",
	53	/* An array of source code locations to point out specific details about
	54	where the diagnostic originates from. This may be empty, for example
	55	for some global messages, or child messages attached to a parent.
	56
	57	Character offsets are offsets of Unicode Scalar Values.
	58	*/
	59	"spans": [
	60	{
	61	/* The file where the span is located.
ba9703b0 XL	62	Note that this path may not exist. For example, if the path
	63	points to the standard library, and the rust src is not
	64	available in the sysroot, then it may point to a non-existent
	65	file. Beware that this may also point to the source of an
	66	external crate.
e74abb32 XL	67	*/
	68	"file_name": "lib.rs",
	69	/* The byte offset where the span starts (0-based, inclusive). */
	70	"byte_start": 21,
	71	/* The byte offset where the span ends (0-based, exclusive). */
	72	"byte_end": 22,
	73	/* The first line number of the span (1-based, inclusive). */
	74	"line_start": 2,
	75	/* The last line number of the span (1-based, inclusive). */
	76	"line_end": 2,
	77	/* The first character offset of the line_start (1-based, inclusive). */
	78	"column_start": 9,
	79	/* The last character offset of the line_end (1-based, exclusive). */
	80	"column_end": 10,
	81	/* Whether or not this is the "primary" span.
	82
	83	This indicates that this span is the focal point of the
	84	diagnostic.
	85
	86	There are rare cases where multiple spans may be marked as
	87	primary. For example, "immutable borrow occurs here" and
	88	"mutable borrow ends here" can be two separate primary spans.
	89
	90	The top (parent) message should always have at least one
	91	primary span, unless it has zero spans. Child messages may have
	92	zero or more primary spans.
	93	*/
	94	"is_primary": true,
	95	/* An array of objects showing the original source code for this
	96	span. This shows the entire lines of text where the span is
	97	located. A span across multiple lines will have a separate
	98	value for each line.
	99	*/
	100	"text": [
	101	{
	102	/* The entire line of the original source code. */
	103	"text": " let x = 123;",
	104	/* The first character offset of the line of
	105	where the span covers this line (1-based, inclusive). */
	106	"highlight_start": 9,
	107	/* The last character offset of the line of
	108	where the span covers this line (1-based, exclusive). */
	109	"highlight_end": 10
	110	}
	111	],
	112	/* An optional message to display at this span location.
	113	This is typically null for primary spans.
	114	*/
	115	"label": null,
	116	/* An optional string of a suggested replacement for this span to
	117	solve the issue. Tools may try to replace the contents of the
	118	span with this text.
	119	*/
	120	"suggested_replacement": null,
	121	/* An optional string that indicates the confidence of the
	122	"suggested_replacement". Tools may use this value to determine
	123	whether or not suggestions should be automatically applied.
	124
	125	Possible values may be:
	126	- "MachineApplicable": The suggestion is definitely what the
	127	user intended. This suggestion should be automatically
	128	applied.
	129	- "MaybeIncorrect": The suggestion may be what the user
	130	intended, but it is uncertain. The suggestion should result
131	in valid Rust code if it is applied.
132	- "HasPlaceholders": The suggestion contains placeholders like
133	`(...)`. The suggestion cannot be applied automatically
134	because it will not result in valid Rust code. The user will
135	need to fill in the placeholders.
136	- "Unspecified": The applicability of the suggestion is unknown.
137	*/
138	"suggestion_applicability": null,
139	/* An optional object indicating the expansion of a macro within
140	this span.
141
142	If a message occurs within a macro invocation, this object will
143	provide details of where within the macro expansion the message
144	is located.
145	*/
146	"expansion": {
147	/* The span of the macro invocation.
148	Uses the same span definition as the "spans" array.
149	*/
150	"span": {/.../}
151	/* Name of the macro, such as "foo!" or "#[derive(Eq)]". */
152	"macro_decl_name": "some_macro!",
153	/* Optional span where the relevant part of the macro is
154	defined. */
155	"def_site_span": {/.../},
156	}
157	}
158	],
159	/* Array of attached diagnostic messages.
160	This is an array of objects using the same format as the parent
161	message. Children are not nested (children do not themselves
162	contain "children" definitions).
163	*/
164	"children": [
165	{
166	"message": "`#[warn(unused_variables)]` on by default",
167	"code": null,
168	"level": "note",
169	"spans": [],
170	"children": [],
171	"rendered": null
172	},
173	{
ba9703b0	174	"message": "if this is intentional, prefix it with an underscore",
e74abb32 XL	175	"code": null,
	176	"level": "help",
	177	"spans": [
	178	{
	179	"file_name": "lib.rs",
	180	"byte_start": 21,
	181	"byte_end": 22,
	182	"line_start": 2,
	183	"line_end": 2,
	184	"column_start": 9,
	185	"column_end": 10,
	186	"is_primary": true,
	187	"text": [
	188	{
	189	"text": " let x = 123;",
	190	"highlight_start": 9,
	191	"highlight_end": 10
	192	}
	193	],
	194	"label": null,
	195	"suggested_replacement": "_x",
	196	"suggestion_applicability": "MachineApplicable",
	197	"expansion": null
	198	}
	199	],
	200	"children": [],
	201	"rendered": null
	202	}
	203	],
	204	/* Optional string of the rendered version of the diagnostic as displayed
	205	by rustc. Note that this may be influenced by the `--json` flag.
	206	*/
ba9703b0	207	"rendered": "warning: unused variable: `x`\n --> lib.rs:2:9\n \|\n2 \| let x = 123;\n \| ^ help: if this is intentional, prefix it with an underscore: `_x`\n \|\n = note: `#[warn(unused_variables)]` on by default\n\n"
e74abb32 XL	208	}
	209	```
	210
	211	## Artifact notifications
	212
	213	Artifact notifications are emitted when the [`--json=artifacts`
	214	flag][option-json] is used. They indicate that a file artifact has been saved
	215	to disk. More information about emit kinds may be found in the [`--emit`
	216	flag][option-emit] documentation.
	217
	218	```javascript
	219	{
	220	/* The filename that was generated. */
	221	"artifact": "libfoo.rlib",
	222	/* The kind of artifact that was generated. Possible values:
	223	- "link": The generated crate as specified by the crate-type.
	224	- "dep-info": The `.d` file with dependency information in a Makefile-like syntax.
	225	- "metadata": The Rust `.rmeta` file containing metadata about the crate.
	226	- "save-analysis": A JSON file emitted by the `-Zsave-analysis` feature.
	227	*/
	228	"emit": "link"
	229	}
	230	```
	231
04454e1e FG	232	## Future-incompatible reports
	233
	234	If the [`--json=future-incompat`][option-json] flag is used, then a separate
	235	JSON structure will be emitted if the crate may stop compiling in the future.
	236	This contains diagnostic information about the particular warnings that may be
	237	turned into a hard error in the future. This will include the diagnostic
	238	information, even if the diagnostics have been suppressed (such as with an
	239	`#[allow]` attribute or the `--cap-lints` option).
	240
	241	```javascript
	242	{
	243	/* An array of objects describing a warning that will become a hard error
	244	in the future.
	245	*/
	246	"future_incompat_report":
	247	[
	248	{
	249	/* A diagnostic structure as defined in
	250	https://doc.rust-lang.org/rustc/json.html#diagnostics
	251	*/
	252	"diagnostic": {...},
	253	}
	254	]
	255	}
	256	```
	257
e74abb32 XL	258	[option-emit]: command-line-arguments.md#option-emit
	259	[option-error-format]: command-line-arguments.md#option-error-format
	260	[option-json]: command-line-arguments.md#option-json