src/doc/rustc/src/json.md

   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                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.
  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         {
 174             "message": "if this is intentional, prefix it with an underscore",
 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     */
 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"
 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
 232 [option-emit]: command-line-arguments.md#option-emit
 233 [option-error-format]: command-line-arguments.md#option-error-format
 234 [option-json]: command-line-arguments.md#option-json