|
| 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. |
| 62 | + For spans located within a macro expansion, this will be the |
| 63 | + name of the expanded macro in the format "<MACRONAME macros>". |
| 64 | + */ |
| 65 | + "file_name": "lib.rs", |
| 66 | + /* The byte offset where the span starts (0-based, inclusive). */ |
| 67 | + "byte_start": 21, |
| 68 | + /* The byte offset where the span ends (0-based, exclusive). */ |
| 69 | + "byte_end": 22, |
| 70 | + /* The first line number of the span (1-based, inclusive). */ |
| 71 | + "line_start": 2, |
| 72 | + /* The last line number of the span (1-based, inclusive). */ |
| 73 | + "line_end": 2, |
| 74 | + /* The first character offset of the line_start (1-based, inclusive). */ |
| 75 | + "column_start": 9, |
| 76 | + /* The last character offset of the line_end (1-based, exclusive). */ |
| 77 | + "column_end": 10, |
| 78 | + /* Whether or not this is the "primary" span. |
| 79 | +
|
| 80 | + This indicates that this span is the focal point of the |
| 81 | + diagnostic. |
| 82 | +
|
| 83 | + There are rare cases where multiple spans may be marked as |
| 84 | + primary. For example, "immutable borrow occurs here" and |
| 85 | + "mutable borrow ends here" can be two separate primary spans. |
| 86 | +
|
| 87 | + The top (parent) message should always have at least one |
| 88 | + primary span, unless it has zero spans. Child messages may have |
| 89 | + zero or more primary spans. |
| 90 | + */ |
| 91 | + "is_primary": true, |
| 92 | + /* An array of objects showing the original source code for this |
| 93 | + span. This shows the entire lines of text where the span is |
| 94 | + located. A span across multiple lines will have a separate |
| 95 | + value for each line. |
| 96 | + */ |
| 97 | + "text": [ |
| 98 | + { |
| 99 | + /* The entire line of the original source code. */ |
| 100 | + "text": " let x = 123;", |
| 101 | + /* The first character offset of the line of |
| 102 | + where the span covers this line (1-based, inclusive). */ |
| 103 | + "highlight_start": 9, |
| 104 | + /* The last character offset of the line of |
| 105 | + where the span covers this line (1-based, exclusive). */ |
| 106 | + "highlight_end": 10 |
| 107 | + } |
| 108 | + ], |
| 109 | + /* An optional message to display at this span location. |
| 110 | + This is typically null for primary spans. |
| 111 | + */ |
| 112 | + "label": null, |
| 113 | + /* An optional string of a suggested replacement for this span to |
| 114 | + solve the issue. Tools may try to replace the contents of the |
| 115 | + span with this text. |
| 116 | + */ |
| 117 | + "suggested_replacement": null, |
| 118 | + /* An optional string that indicates the confidence of the |
| 119 | + "suggested_replacement". Tools may use this value to determine |
| 120 | + whether or not suggestions should be automatically applied. |
| 121 | +
|
| 122 | + Possible values may be: |
| 123 | + - "MachineApplicable": The suggestion is definitely what the |
| 124 | + user intended. This suggestion should be automatically |
| 125 | + applied. |
| 126 | + - "MaybeIncorrect": The suggestion may be what the user |
| 127 | + intended, but it is uncertain. The suggestion should result |
| 128 | + in valid Rust code if it is applied. |
| 129 | + - "HasPlaceholders": The suggestion contains placeholders like |
| 130 | + `(...)`. The suggestion cannot be applied automatically |
| 131 | + because it will not result in valid Rust code. The user will |
| 132 | + need to fill in the placeholders. |
| 133 | + - "Unspecified": The applicability of the suggestion is unknown. |
| 134 | + */ |
| 135 | + "suggestion_applicability": null, |
| 136 | + /* An optional object indicating the expansion of a macro within |
| 137 | + this span. |
| 138 | +
|
| 139 | + If a message occurs within a macro invocation, this object will |
| 140 | + provide details of where within the macro expansion the message |
| 141 | + is located. |
| 142 | + */ |
| 143 | + "expansion": { |
| 144 | + /* The span of the macro invocation. |
| 145 | + Uses the same span definition as the "spans" array. |
| 146 | + */ |
| 147 | + "span": {/*...*/} |
| 148 | + /* Name of the macro, such as "foo!" or "#[derive(Eq)]". */ |
| 149 | + "macro_decl_name": "some_macro!", |
| 150 | + /* Optional span where the relevant part of the macro is |
| 151 | + defined. */ |
| 152 | + "def_site_span": {/*...*/}, |
| 153 | + } |
| 154 | + } |
| 155 | + ], |
| 156 | + /* Array of attached diagnostic messages. |
| 157 | + This is an array of objects using the same format as the parent |
| 158 | + message. Children are not nested (children do not themselves |
| 159 | + contain "children" definitions). |
| 160 | + */ |
| 161 | + "children": [ |
| 162 | + { |
| 163 | + "message": "`#[warn(unused_variables)]` on by default", |
| 164 | + "code": null, |
| 165 | + "level": "note", |
| 166 | + "spans": [], |
| 167 | + "children": [], |
| 168 | + "rendered": null |
| 169 | + }, |
| 170 | + { |
| 171 | + "message": "consider prefixing with an underscore", |
| 172 | + "code": null, |
| 173 | + "level": "help", |
| 174 | + "spans": [ |
| 175 | + { |
| 176 | + "file_name": "lib.rs", |
| 177 | + "byte_start": 21, |
| 178 | + "byte_end": 22, |
| 179 | + "line_start": 2, |
| 180 | + "line_end": 2, |
| 181 | + "column_start": 9, |
| 182 | + "column_end": 10, |
| 183 | + "is_primary": true, |
| 184 | + "text": [ |
| 185 | + { |
| 186 | + "text": " let x = 123;", |
| 187 | + "highlight_start": 9, |
| 188 | + "highlight_end": 10 |
| 189 | + } |
| 190 | + ], |
| 191 | + "label": null, |
| 192 | + "suggested_replacement": "_x", |
| 193 | + "suggestion_applicability": "MachineApplicable", |
| 194 | + "expansion": null |
| 195 | + } |
| 196 | + ], |
| 197 | + "children": [], |
| 198 | + "rendered": null |
| 199 | + } |
| 200 | + ], |
| 201 | + /* Optional string of the rendered version of the diagnostic as displayed |
| 202 | + by rustc. Note that this may be influenced by the `--json` flag. |
| 203 | + */ |
| 204 | + "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" |
| 205 | +} |
| 206 | +``` |
| 207 | + |
| 208 | +## Artifact notifications |
| 209 | + |
| 210 | +Artifact notifications are emitted when the [`--json=artifacts` |
| 211 | +flag][option-json] is used. They indicate that a file artifact has been saved |
| 212 | +to disk. More information about emit kinds may be found in the [`--emit` |
| 213 | +flag][option-emit] documentation. |
| 214 | + |
| 215 | +```javascript |
| 216 | +{ |
| 217 | + /* The filename that was generated. */ |
| 218 | + "artifact": "libfoo.rlib", |
| 219 | + /* The kind of artifact that was generated. Possible values: |
| 220 | + - "link": The generated crate as specified by the crate-type. |
| 221 | + - "dep-info": The `.d` file with dependency information in a Makefile-like syntax. |
| 222 | + - "metadata": The Rust `.rmeta` file containing metadata about the crate. |
| 223 | + - "save-analysis": A JSON file emitted by the `-Zsave-analysis` feature. |
| 224 | + */ |
| 225 | + "emit": "link" |
| 226 | +} |
| 227 | +``` |
| 228 | + |
| 229 | +[option-emit]: command-line-arguments.md#option-emit |
| 230 | +[option-error-format]: command-line-arguments.md#option-error-format |
| 231 | +[option-json]: command-line-arguments.md#option-json |
0 commit comments