Diagnostic Message Formatting Options (Using the GNU Compiler Collection (GCC))

### 3.8 Options to Control Diagnostic Messages Formatting ¶

Traditionally, diagnostic messages have been formatted irrespective of the output device’s aspect (e.g. its width, …). You can use the options described below to control the formatting algorithm for diagnostic messages, e.g. how many characters per line, how often source location information should be reported. Note that some language front ends may not honor these options.

`-fmessage-length=n` ¶

  Try to format error messages so that they fit on lines of about n characters. If n is zero, then no line-wrapping is done; each error message appears on a single line. This is the default for all front ends.

  Note - this option also affects the display of the ‘`#error`’ and ‘`#warning`’ pre-processor directives, and the ‘`deprecated`’ function/type/variable attribute. It does not however affect the ‘`pragma GCC warning`’ and ‘`pragma GCC error`’ pragmas.

`-fdiagnostics-plain-output` ¶

  This option requests that diagnostic output look as plain as possible, which may be useful when running `dejagnu` or other utilities that need to parse diagnostics output and prefer that it remain more stable over time. `-fdiagnostics-plain-output` is currently equivalent to the following options:

      -fno-diagnostics-show-caret
      -fno-diagnostics-show-line-numbers
      -fdiagnostics-color=never
      -fdiagnostics-urls=never
      -fdiagnostics-path-format=separate-events
      -fdiagnostics-text-art-charset=none
      -fno-diagnostics-show-event-links
      -fno-diagnostics-show-nesting

  In the future, if GCC changes the default appearance of its diagnostics, the corresponding option to disable the new behavior will be added to this list.

`-fdiagnostics-show-location=once` ¶

  Only meaningful in line-wrapping mode. Instructs the diagnostic messages reporter to emit source location information once; that is, in case the message is too long to fit on a single physical line and has to be wrapped, the source location won’t be emitted (as prefix) again, over and over, in subsequent continuation lines. This is the default behavior.

`-fdiagnostics-show-location=every-line`

  Only meaningful in line-wrapping mode. Instructs the diagnostic messages reporter to emit the same source location information (as prefix) for physical lines that result from the process of breaking a message which is too long to fit on a single line.

`-fdiagnostics-color[=WHEN]` ¶
`-fno-diagnostics-color`

  Use color in diagnostics. WHEN is ‘`never`’, ‘`always`’, or ‘`auto`’. The default depends on how the compiler has been configured, it can be any of the above WHEN options or also ‘`never`’ if `GCC_COLORS` environment variable isn’t present in the environment, and ‘`auto`’ otherwise. ‘`auto`’ makes GCC use color only when the standard error is a terminal, and when not executing in an emacs shell. The forms `-fdiagnostics-color` and `-fno-diagnostics-color` are aliases for `-fdiagnostics-color=always` and `-fdiagnostics-color=never`, respectively.

  The colors are defined by the environment variable `GCC_COLORS`. Its value is a colon-separated list of capabilities and Select Graphic Rendition (SGR) substrings. SGR commands are interpreted by the terminal or terminal emulator. (See the section in the documentation of your text terminal for permitted values and their meanings as character attributes.) These substring values are integers in decimal representation and can be concatenated with semicolons. Common values to concatenate include ‘`1`’ for bold, ‘`4`’ for underline, ‘`5`’ for blink, ‘`7`’ for inverse, ‘`39`’ for default foreground color, ‘`30`’ to ‘`37`’ for foreground colors, ‘`90`’ to ‘`97`’ for 16-color mode foreground colors, ‘`38;5;0`’ to ‘`38;5;255`’ for 88-color and 256-color modes foreground colors, ‘`49`’ for default background color, ‘`40`’ to ‘`47`’ for background colors, ‘`100`’ to ‘`107`’ for 16-color mode background colors, and ‘`48;5;0`’ to ‘`48;5;255`’ for 88-color and 256-color modes background colors.

  The default `GCC_COLORS` is

      error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:\
      quote=01:path=01;36:fixit-insert=32:fixit-delete=31:\
      diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\
      type-diff=01;32:fnname=01;32:targs=35:valid=01;31:invalid=01;32\
      highlight-a=01;32:highlight-b=01;34

  where ‘`01;31`’ is bold red, ‘`01;35`’ is bold magenta, ‘`01;36`’ is bold cyan, ‘`32`’ is green, ‘`34`’ is blue, ‘`01`’ is bold, and ‘`31`’ is red. Setting `GCC_COLORS` to the empty string disables colors. Supported capabilities are as follows.

  `error=` ¶

    SGR substring for error: markers.

  `warning=` ¶

    SGR substring for warning: markers.

  `note=` ¶

    SGR substring for note: markers.

  `path=` ¶

    SGR substring for colorizing paths of control-flow events as printed via `-fdiagnostics-path-format=`, such as the identifiers of individual events and lines indicating interprocedural calls and returns.

  `range1=` ¶

    SGR substring for first additional range.

  `range2=` ¶

    SGR substring for second additional range.

  `locus=` ¶

    SGR substring for location information, ‘`file:line`’ or ‘`file:line:column`’ etc.

  `quote=` ¶

    SGR substring for information printed within quotes.

  `fnname=` ¶

    SGR substring for names of C++ functions.

  `targs=` ¶

    SGR substring for C++ function template parameter bindings.

  `fixit-insert=` ¶

    SGR substring for fix-it hints suggesting text to be inserted or replaced.

  `fixit-delete=` ¶

    SGR substring for fix-it hints suggesting text to be deleted.

  `diff-filename=` ¶

    SGR substring for filename headers within generated patches.

  `diff-hunk=` ¶

    SGR substring for the starts of hunks within generated patches.

  `diff-delete=` ¶

    SGR substring for deleted lines within generated patches.

  `diff-insert=` ¶

    SGR substring for inserted lines within generated patches.

  `type-diff=` ¶

    SGR substring for highlighting mismatching types within template arguments in the C++ frontend.

  `valid=` ¶

    SGR substring for highlighting valid elements within text art diagrams.

  `invalid=` ¶

    SGR substring for highlighting invalid elements within text art diagrams.

  `highlight-a=` ¶
  `highlight-b=`

    SGR substrings for contrasting two different things within diagnostics, such as a pair of mismatching types. See `-fdiagnostics-show-highlight-colors`.

`-fdiagnostics-urls[=WHEN]` ¶

  Use escape sequences to embed URLs in diagnostics. For example, when `-fdiagnostics-show-option` emits text showing the command-line option controlling a diagnostic, embed a URL for documentation of that option.

  WHEN is ‘`never`’, ‘`always`’, or ‘`auto`’. ‘`auto`’ makes GCC use URL escape sequences only when the standard error is a terminal, and when not executing in an emacs shell or any graphical terminal which is known to be incompatible with this feature, see below.

  The default depends on how the compiler has been configured. It can be any of the above WHEN options.

  GCC can also be configured (via the `--with-diagnostics-urls=auto-if-env` configure-time option) so that the default is affected by environment variables. Under such a configuration, GCC defaults to using ‘`auto`’ if either `GCC_URLS` or `TERM_URLS` environment variables are present and non-empty in the environment of the compiler, or ‘`never`’ if neither are.

  However, even with `-fdiagnostics-urls=always` the behavior is dependent on those environment variables: If `GCC_URLS` is set to empty or ‘`no`’, do not embed URLs in diagnostics. If set to ‘`st`’, URLs use ST escape sequences. If set to ‘`bel`’, the default, URLs use BEL escape sequences. Any other non-empty value enables the feature. If `GCC_URLS` is not set, use `TERM_URLS` as a fallback. Note: ST is an ANSI escape sequence, string terminator ‘`ESC \`’, BEL is an ASCII character, CTRL-G that usually sounds like a beep.

  At this time GCC tries to detect also a few terminals that are known to not implement the URL feature, and have bugs or at least had bugs in some versions that are still in use, where the URL escapes are likely to misbehave, i.e. print garbage on the screen. That list is currently xfce4-terminal, certain known to be buggy gnome-terminal versions, the linux console, and mingw. This check can be skipped with the `-fdiagnostics-urls=always`.

`-fno-diagnostics-show-option` ¶

  By default, each diagnostic emitted includes text indicating the command-line option that directly controls the diagnostic (if such an option is known to the diagnostic machinery). Specifying the `-fno-diagnostics-show-option` flag suppresses that behavior.

`-fno-diagnostics-show-caret` ¶

  By default, each diagnostic emitted includes the original source line and a caret ‘`^`’ indicating the column. This option suppresses this information. The source line is truncated to n characters, if the `-fmessage-length=n` option is given. When the output is done to the terminal, the width is limited to the width given by the `COLUMNS` environment variable or, if not set, to the terminal width.

`-fno-diagnostics-show-labels` ¶

  By default, when printing source code (via `-fdiagnostics-show-caret`), diagnostics can label ranges of source code with pertinent information, such as the types of expressions:

          printf ("foo %s bar", long_i + long_j);
                       ~^       ~~~~~~~~~~~~~~~
                        |              |
                        char *         long int

  This option suppresses the printing of these labels (in the example above, the vertical bars and the “char *” and “long int” text).

`-fno-diagnostics-show-event-links` ¶

  By default, when printing execution paths (via `-fdiagnostics-path-format=inline-events`), GCC will print lines connecting related events, such as the line connecting events 1 and 2 in:

          3 |   if (p)
            |       ^
            |       |
            |       (1) following `false' branch (when `p' is NULL)... ->-+
            |                                                             |
            |                                                             |
            |+------------------------------------------------------------+
          4 ||    return 0;
          5 ||  return *p;
            ||         ~
            ||         |
            |+-------->(2) ...to here
            |          (3) dereference of NULL `p'

  This option suppresses the printing of such connector lines.

`-fno-diagnostics-show-cwe` ¶

  Diagnostic messages can optionally have an associated CWE identifier. GCC itself only provides such metadata for some of the `-fanalyzer` diagnostics. GCC plugins may also provide diagnostics with such metadata. By default, if this information is present, it will be printed with the diagnostic. This option suppresses the printing of this metadata.

`-fno-diagnostics-show-rules` ¶

  Diagnostic messages can optionally have rules associated with them, such as from a coding standard, or a specification. GCC itself does not do this for any of its diagnostics, but plugins may do so. By default, if this information is present, it will be printed with the diagnostic. This option suppresses the printing of this metadata.

`-fno-diagnostics-show-highlight-colors` ¶

  GCC can use color for emphasis and contrast when printing diagnostic messages and quoting the user’s source.

  For example, in

      demo.c: In function `test_bad_format_string_args':
      ../../src/demo.c:25:18: warning: format `%i' expects argument of type `int', but argument 2 has type `const char *' [-Wformat=]
         25 |   printf("hello %i", msg);
            |                 ~^   ~~~
            |                  |   |
            |                  int const char *
            |                 %s

  - the `%i` and `int` in the message and the `int` in the quoted source are colored using `highlight-a` (bold green by default), and
  - the `const char *` in the message and in the quoted source are both colored using `highlight-b` (bold blue by default).

  The intent is to draw the reader’s eyes to the relationships between the various aspects of the diagnostic message and the source, using color to group related elements and distinguish between mismatching ones.

  This additional colorization is enabled by default if color printing is enabled (as per `-fdiagnostics-color=`), but it can be separately disabled via `-fno-diagnostics-show-highlight-colors`.

`-fno-diagnostics-show-line-numbers` ¶

  By default, when printing source code (via `-fdiagnostics-show-caret`), a left margin is printed, showing line numbers. This option suppresses this left margin.

`-fdiagnostics-minimum-margin-width=width` ¶

  This option controls the minimum width of the left margin printed by `-fdiagnostics-show-line-numbers`. It defaults to 6.

`-fdiagnostics-show-context[=depth]` ¶
`-fno-diagnostics-show-context`

  With this option, the compiler might print the interesting control flow chain that guards the basic block of the statement which has the warning. depth is the maximum depth of the control flow chain. Currently, The list of the impacted warning options includes: `-Warray-bounds`, `-Wstringop-overflow`, `-Wstringop-overread`, `-Wstringop-truncation`. and `-Wrestrict`. More warning options might be added to this list in future releases. The forms `-fdiagnostics-show-context` and `-fno-diagnostics-show-context` are aliases for `-fdiagnostics-show-context=1` and `-fdiagnostics-show-context=0`, respectively.

`-fdiagnostics-parseable-fixits` ¶

  Emit fix-it hints in a machine-parseable format, suitable for consumption by IDEs. For each fix-it, a line will be printed after the relevant diagnostic, starting with the string “fix-it:”. For example:

      fix-it:"test.c":{45:3-45:21}:"gtk_widget_show_all"

  The location is expressed as a half-open range, expressed as a count of bytes, starting at byte 1 for the initial column. In the above example, bytes 3 through 20 of line 45 of “test.c” are to be replaced with the given string:

      00000000011111111112222222222
      12345678901234567890123456789
        gtk_widget_showall (dlg);
        ^^^^^^^^^^^^^^^^^^
        gtk_widget_show_all

  The filename and replacement string escape backslash as “\\", tab as “\t”, newline as “\n”, double quotes as “\"”, non-printable characters as octal (e.g. vertical tab as “\013”).

  An empty replacement string indicates that the given range is to be removed. An empty range (e.g. “45:3-45:3”) indicates that the string is to be inserted at the given position.

`-fdiagnostics-generate-patch` ¶

  Print fix-it hints to stderr in unified diff format, after any diagnostics are printed. For example:

      --- test.c
      +++ test.c
      @ -42,5 +42,5 @

       void show_cb(GtkDialog *dlg)
       {
      -  gtk_widget_showall(dlg);
      +  gtk_widget_show_all(dlg);
       }

  The diff may or may not be colorized, following the same rules as for diagnostics (see `-fdiagnostics-color`).

`-fdiagnostics-show-template-tree` ¶

  In the C++ frontend, when printing diagnostics showing mismatching template types, such as:

        could not convert 'std::map<int, std::vector<double> >()'
          from 'map<[...],vector<double>>' to 'map<[...],vector<float>>

  the `-fdiagnostics-show-template-tree` flag enables printing a tree-like structure showing the common and differing parts of the types, such as:

        map<
          [...],
          vector<
            [double != float]>>

  The parts that differ are highlighted with color (“double” and “float” in this case).

`-fno-elide-type` ¶

  By default when the C++ frontend prints diagnostics showing mismatching template types, common parts of the types are printed as “[...]” to simplify the error message. For example:

        could not convert 'std::map<int, std::vector<double> >()'
          from 'map<[...],vector<double>>' to 'map<[...],vector<float>>

  Specifying the `-fno-elide-type` flag suppresses that behavior. This flag also affects the output of the `-fdiagnostics-show-template-tree` flag.

`-fdiagnostics-path-format=KIND` ¶

  Specify how to print paths of control-flow events for diagnostics that have such a path associated with them.

  KIND is ‘`none`’, ‘`separate-events`’, or ‘`inline-events`’, the default.

  ‘`none`’ means to not print diagnostic paths.

  ‘`separate-events`’ means to print a separate “note” diagnostic for each event within the diagnostic. For example:

      test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter
      test.c:25:10: note: (1) when 'PyList_New' fails, returning NULL
      test.c:27:3: note: (2) when 'i < count'
      test.c:29:5: note: (3) when calling 'PyList_Append', passing NULL from (1) as argument 1

  ‘`inline-events`’ means to print the events “inline” within the source code. This view attempts to consolidate the events into runs of sufficiently-close events, printing them as labelled ranges within the source.

  For example, the same events as above might be printed as:

        'test': events 1-3
         25 |   list = PyList_New(0);
            |          ^~~~~~~~~~~~~
            |          |
            |          (1) when 'PyList_New' fails, returning NULL
         26 |
         27 |   for (i = 0; i < count; i++) {
            |   ~~~
            |   |
            |   (2) when 'i < count'
         28 |     item = PyLong_FromLong(random());
         29 |     PyList_Append(list, item);
            |     ~~~~~~~~~~~~~~~~~~~~~~~~~
            |     |
            |     (3) when calling 'PyList_Append', passing NULL from (1) as argument 1

  Interprocedural control flow is shown by grouping the events by stack frame, and using indentation to show how stack frames are nested, pushed, and popped.

  For example:

        'test': events 1-2
          |
          |  133 | {
          |      | ^
          |      | |
          |      | (1) entering 'test'
          |  134 |   boxed_int *obj = make_boxed_int (i);
          |      |                    ~~~~~~~~~~~~~~~~~~
          |      |                    |
          |      |                    (2) calling 'make_boxed_int'
          |
          +--> 'make_boxed_int': events 3-4
                 |
                 |  120 | {
                 |      | ^
                 |      | |
                 |      | (3) entering 'make_boxed_int'
                 |  121 |   boxed_int *result = (boxed_int *)wrapped_malloc (sizeof (boxed_int));
                 |      |                                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                 |      |                                    |
                 |      |                                    (4) calling 'wrapped_malloc'
                 |
                 +--> 'wrapped_malloc': events 5-6
                        |
                        |    7 | {
                        |      | ^
                        |      | |
                        |      | (5) entering 'wrapped_malloc'
                        |    8 |   return malloc (size);
                        |      |          ~~~~~~~~~~~~~
                        |      |          |
                        |      |          (6) calling 'malloc'
                        |
          <-------------+
          |
       'test': event 7
          |
          |  138 |   free_boxed_int (obj);
          |      |   ^~~~~~~~~~~~~~~~~~~~
          |      |   |
          |      |   (7) calling 'free_boxed_int'
          |
      (etc)

`-fdiagnostics-show-path-depths` ¶

  This option provides additional information when printing control-flow paths associated with a diagnostic.

  If this is option is provided then the stack depth will be printed for each run of events within `-fdiagnostics-path-format=inline-events`. If provided with `-fdiagnostics-path-format=separate-events`, then the stack depth and function declaration will be appended when printing each event.

  This is intended for use by GCC developers and plugin developers when debugging diagnostics that report interprocedural control flow.

`-fno-show-column` ¶

  Do not print column numbers in diagnostics. This may be necessary if diagnostics are being scanned by a program that does not understand the column numbers, such as `dejagnu`.

`-fdiagnostics-column-unit=UNIT` ¶

  Select the units for the column number. This affects traditional diagnostics (in the absence of `-fno-show-column`).

  The default UNIT, ‘`display`’, considers the number of display columns occupied by each character. This may be larger than the number of bytes required to encode the character, in the case of tab characters, or it may be smaller, in the case of multibyte characters. For example, the character “GREEK SMALL LETTER PI (U+03C0)” occupies one display column, and its UTF-8 encoding requires two bytes; the character “SLIGHTLY SMILING FACE (U+1F642)” occupies two display columns, and its UTF-8 encoding requires four bytes.

  Setting UNIT to ‘`byte`’ changes the column number to the raw byte count in all cases, as was traditionally output by GCC prior to version 11.1.0.

`-fdiagnostics-column-origin=ORIGIN` ¶

  Select the origin for column numbers, i.e. the column number assigned to the first column. The default value of 1 corresponds to traditional GCC behavior and to the GNU style guide. Some utilities may perform better with an origin of 0; any non-negative value may be specified.

`-fdiagnostics-escape-format=FORMAT` ¶

  When GCC prints pertinent source lines for a diagnostic it normally attempts to print the source bytes directly. However, some diagnostics relate to encoding issues in the source file, such as malformed UTF-8, or issues with Unicode normalization. These diagnostics are flagged so that GCC will escape bytes that are not printable ASCII when printing their pertinent source lines.

  This option controls how such bytes should be escaped.

  The default FORMAT, ‘`unicode`’ displays Unicode characters that are not printable ASCII in the form ‘`<U+XXXX>`’, and bytes that do not correspond to a Unicode character validly-encoded in UTF-8-encoded will be displayed as hexadecimal in the form ‘`<XX>`’.

  For example, a source line containing the string ‘`before`’ followed by the Unicode character U+03C0 (“GREEK SMALL LETTER PI”, with UTF-8 encoding 0xCF 0x80) followed by the byte 0xBF (a stray UTF-8 trailing byte), followed by the string ‘`after`’ will be printed for such a diagnostic as:

       before<U+03C0><BF>after

  Setting FORMAT to ‘`bytes`’ will display all non-printable-ASCII bytes in the form ‘`<XX>`’, thus showing the underlying encoding of non-ASCII Unicode characters. For the example above, the following will be printed:

       before<CF><80><BF>after

`-fdiagnostics-text-art-charset=CHARSET` ¶

  Some diagnostics can contain “text art” diagrams: visualizations created from text, intended to be viewed in a monospaced font.

  This option selects which characters should be used for printing such diagrams, if any. CHARSET is ‘`none`’, ‘`ascii`’, ‘`unicode`’, or ‘`emoji`’.

  The ‘`none`’ value suppresses the printing of such diagrams. The ‘`ascii`’ value will ensure that such diagrams are pure ASCII (“ASCII art”). The ‘`unicode`’ value will allow for conservative use of unicode drawing characters (such as box-drawing characters). The ‘`emoji`’ value further adds the possibility of emoji in the output (such as emitting U+26A0 WARNING SIGN followed by U+FE0F VARIATION SELECTOR-16 to select the emoji variant of the character).

  The default is ‘`emoji`’, except when the environment variable `LANG` is set to ‘`C`’, in which case the default is ‘`ascii`’.

`-fno-diagnostics-show-nesting` ¶

  Some GCC diagnostics have an internal tree-like structure of nested sub-diagnostics, such as for problems when instantiating C++ templates.

  By default GCC uses indentation and bullet points in its text output to show the nesting structure of these diagnostics, moves location information to separate lines to make the structure clearer, and eliminates redundant repeated information.

  Selecting `-fno-diagnostics-show-nesting` suppresses this indentation, reformatting, and elision, restoring an older ‘look” for the diagnostics.

`-fno-diagnostics-show-nesting-locations` ¶

  When `fdiagnostics-show-nesting` is enabled, file names and line- and column- numbers are displayed on separate lines from the messages. This location information can be disabled altogether with `-fno-diagnostics-show-nesting-locations`. This option exists for use by GCC developers, for writing DejaGnu test cases.

`-fdiagnostics-show-nesting-levels` ¶

  When `fdiagnostics-show-nesting` is enabled, use `fdiagnostics-show-nesting-levels` to also display numbers showing the depth of the nesting. This option exists for use by GCC developers for debugging nested diagnostics, but may be of use to plugin authors.

`-fdiagnostics-format=FORMAT` ¶

  Select a different format for printing diagnostics. FORMAT is ‘`text`’, ‘`sarif-stderr`’ or ‘`sarif-file`’.

  Using this option replaces any additional “output sinks” added by `-fdiagnostics-add-output=`, or that set by `-fdiagnostics-set-output=`.

  The default is ‘`text`’.

  The ‘`sarif-stderr`’ and ‘`sarif-file`’ formats both emit diagnostics in SARIF Version 2.1.0 format, either to stderr, or to a file named `source.sarif`, respectively.

`-fdiagnostics-add-output=DIAGNOSTICS-OUTPUT-SPEC` ¶

  Add an additional “output sink” for emitting diagnostics.

  DIAGNOSTICS-OUTPUT-SPEC should specify a scheme, optionally followed by `:` and one or more KEY=VALUE pairs, in this form:

      SCHEME
      SCHEME:KEY=VALUE
      SCHEME:KEY=VALUE,KEY2=VALUE2

  etc.

  Schemes, keys, or values with a name prefixed “experimental” may change or be removed without notice. Keys can be per-scheme, or related to GCC as a whole.

  SCHEME can be

  `text` ¶

    Emit diagnostics to stderr using GCC’s classic text output format.

    Supported keys for the `text` scheme are:

    `color=[yes|no]`

      Override colorization settings from `-fdiagnostics-color` for this text output.

    `show-nesting=[yes|no]`

      Enable a mode that emphasizes hierarchical relationships within diagnostics messages, as per `-fdiagnostics-show-nesting`. Defaults to `yes`.

    `show-nesting-locations=[yes|no]`

      If `show-nesting=yes`, then by default locations are shown; set this key to `no` to disable printing such locations. This exists for use by GCC developers, for writing DejaGnu test cases.

    `show-nesting-levels=[yes|no]`

      This is a debugging option for use with `show-nesting=yes`. Set this key to `yes` to print explicit nesting levels in the output. This exists for use by GCC developers.

  `sarif` ¶

    Emit diagnostics to a file in SARIF format.

    Supported keys for the `sarif` scheme are:

    `file=FILENAME`

      Specify the filename to write the SARIF output to, potentially with a leading absolute or relative path. If not specified, it defaults to `source.sarif`.

    `serialization=[json]`

      Specify the serialization format to use when writing out the SARIF. Currently this can only be `json`, but is present as an extension point for experimenting with other serializations.

    `version=[2.1|2.2-prerelease]`

      Specify the version of SARIF to use for the output. If not specified, defaults to 2.1. `2.2-prerelease` uses an unofficial draft of the future SARIF 2.2 specification and should only be used for experimentation in this release.

    There is also this key intended for use by GCC developers, rather than end-users, and subject to change or removal without notice:

    `state-graphs=[yes|no]`

      This is a debugging feature and defaults to `no`. If `state-graphs=yes`, then attempt to capture detailed state information from `-fanalyzer` in the generated SARIF.

  `experimental-html` ¶

    Emit diagnostics to a file in HTML format. This scheme is experimental, and may go away in future GCC releases. The keys and details of the output are also subject to change.

    Supported keys for the `experimental-html` scheme are:

    `css=[yes|no]`

      Add an embedded <style> to the generated HTML. Defaults to yes.

    `file=FILENAME`

      Specify the filename to write the HTML output to, potentially with a leading absolute or relative path. If not specified, it defaults to `source.html`.

    `javascript=[yes|no]`

      Add an embedded <script> to the generated HTML providing a barebones UI for viewing results. Defaults to yes.

    There are also these keys intended for use by GCC developers, rather than end-users, and subject to change or removal without notice:

    `show-state-diagrams=[yes|no]`

      This is a debugging feature and defaults to `no`. If `show-state-diagrams=yes`, then attempt to use `dot` to generate SVG diagrams in the generated HTML, visualizing the state at each event in a diagnostic path. These are visible by pressing “j” and “k” to single-step forward and backward through events. Enabling this option will slow down HTML generation.

    `show-graph-dot-src=[yes|no]`

      This is a debugging feature and defaults to `no`. If `show-graph-dot-src=yes` then if `show-state-diagrams=yes`, the generated state diagrams will also show the .dot source input to GraphViz used for the diagram.

    `show-graph-sarif=[yes|no]`

      This is a debugging feature and defaults to `no`. If `show-graph-sarif=yes` then if `show-state-diagrams=yes`, the generated state diagrams will also show a SARIF representation of the state.

  As well as scheme-specific keys, the following GCC-related key is usable on sinks of any scheme:

  `cfgs=[yes|no]`

    If `cfgs=yes` for a sink, then GCC will attempt to send information to that sink about the control flow graphs for the functions it is compiling. Text sinks ignore the information. SARIF sinks will add the graphs within `theRun.graphs`. HTML sinks will generate SVG displaying the graphs. The precise form of the information is subject to change without notice.

  For example,

      -fdiagnostics-add-output=sarif:version=2.1,file=foo.2.1.sarif
      -fdiagnostics-add-output=sarif:version=2.2-prerelease,file=foo.2.2.sarif

  would add a pair of outputs, each writing to a different file, using versions 2.1 and 2.2 of the SARIF standard respectively.

  In EBNF:

      diagnostics-output-specifier = diagnostics-output-name
                                         | diagnostics-output-name, ":", key-value-pairs;

      diagnostics-output-name = "text" | "sarif" | "experimental-html";

      key-value-pairs = key-value-pair
                            | key-value-pair "," key-value-pairs;

      key-value-pair = key "=" value;

      key = ? string without a '=' ? ;
      value = ? string without a ',' ? ;

`-fdiagnostics-set-output=DIAGNOSTICS-OUTPUT-SPEC` ¶

  This works in a similar way to `-fdiagnostics-add-output=` except that instead of adding an additional “output sink” for diagnostics, it replaces all existing output sinks, such as from `-fdiagnostics-format=`, `-fdiagnostics-add-output=`, or a prior call to `-fdiagnostics-set-output=`.

`-fno-diagnostics-json-formatting` ¶

  By default, when JSON is emitted for diagnostics (via `-fdiagnostics-format=sarif-stderr` or `-fdiagnostics-format=sarif-file`), GCC will add newlines and indentation to visually emphasize the hierarchical structure of the JSON.

  Use `-fno-diagnostics-json-formatting` to suppress this whitespace. It must be passed before the option it is to affect.

  This is intended for compatibility with tools that do not expect the output to contain newlines, such as that emitted by older GCC releases.