3.7 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.

-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’ means to use color only when the standard error is a terminal. 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:fixit-insert=32:fixit-delete=31:\
diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\
type-diff=01;32

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.

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.

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.

-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.

-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.

-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.