gcc: Diagnostic Message Formatting Options
1
1 3.7 Options to Control Diagnostic Messages Formatting
1 =====================================================
1
1 Traditionally, diagnostic messages have been formatted irrespective of
1 the output device's aspect (e.g. its width, ...). You can use the
1 options described below to control the formatting algorithm for
1 diagnostic messages, e.g. how many characters per line, how often source
1 location information should be reported. Note that some language front
1 ends may not honor these options.
1
1 '-fmessage-length=N'
1 Try to format error messages so that they fit on lines of about N
1 characters. If N is zero, then no line-wrapping is done; each
1 error message appears on a single line. This is the default for
1 all front ends.
1
1 '-fdiagnostics-show-location=once'
1 Only meaningful in line-wrapping mode. Instructs the diagnostic
1 messages reporter to emit source location information _once_; that
1 is, in case the message is too long to fit on a single physical
1 line and has to be wrapped, the source location won't be emitted
1 (as prefix) again, over and over, in subsequent continuation lines.
1 This is the default behavior.
1
1 '-fdiagnostics-show-location=every-line'
1 Only meaningful in line-wrapping mode. Instructs the diagnostic
1 messages reporter to emit the same source location information (as
1 prefix) for physical lines that result from the process of breaking
1 a message which is too long to fit on a single line.
1
1 '-fdiagnostics-color[=WHEN]'
1 '-fno-diagnostics-color'
1 Use color in diagnostics. WHEN is 'never', 'always', or 'auto'.
1 The default depends on how the compiler has been configured, it can
1 be any of the above WHEN options or also 'never' if 'GCC_COLORS'
1 environment variable isn't present in the environment, and 'auto'
1 otherwise. 'auto' means to use color only when the standard error
1 is a terminal. The forms '-fdiagnostics-color' and
1 '-fno-diagnostics-color' are aliases for
1 '-fdiagnostics-color=always' and '-fdiagnostics-color=never',
1 respectively.
1
1 The colors are defined by the environment variable 'GCC_COLORS'.
1 Its value is a colon-separated list of capabilities and Select
1 Graphic Rendition (SGR) substrings. SGR commands are interpreted
1 by the terminal or terminal emulator. (See the section in the
1 documentation of your text terminal for permitted values and their
1 meanings as character attributes.) These substring values are
1 integers in decimal representation and can be concatenated with
1 semicolons. Common values to concatenate include '1' for bold, '4'
1 for underline, '5' for blink, '7' for inverse, '39' for default
1 foreground color, '30' to '37' for foreground colors, '90' to '97'
1 for 16-color mode foreground colors, '38;5;0' to '38;5;255' for
1 88-color and 256-color modes foreground colors, '49' for default
1 background color, '40' to '47' for background colors, '100' to
1 '107' for 16-color mode background colors, and '48;5;0' to
1 '48;5;255' for 88-color and 256-color modes background colors.
1
1 The default 'GCC_COLORS' is
1 error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:\
1 quote=01:fixit-insert=32:fixit-delete=31:\
1 diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\
1 type-diff=01;32
1 where '01;31' is bold red, '01;35' is bold magenta, '01;36' is bold
1 cyan, '32' is green, '34' is blue, '01' is bold, and '31' is red.
1 Setting 'GCC_COLORS' to the empty string disables colors.
1 Supported capabilities are as follows.
1
1 'error='
1 SGR substring for error: markers.
1
1 'warning='
1 SGR substring for warning: markers.
1
1 'note='
1 SGR substring for note: markers.
1
1 'range1='
1 SGR substring for first additional range.
1
1 'range2='
1 SGR substring for second additional range.
1
1 'locus='
1 SGR substring for location information, 'file:line' or
1 'file:line:column' etc.
1
1 'quote='
1 SGR substring for information printed within quotes.
1
1 'fixit-insert='
1 SGR substring for fix-it hints suggesting text to be inserted
1 or replaced.
1
1 'fixit-delete='
1 SGR substring for fix-it hints suggesting text to be deleted.
1
1 'diff-filename='
1 SGR substring for filename headers within generated patches.
1
1 'diff-hunk='
1 SGR substring for the starts of hunks within generated
1 patches.
1
1 'diff-delete='
1 SGR substring for deleted lines within generated patches.
1
1 'diff-insert='
1 SGR substring for inserted lines within generated patches.
1
1 'type-diff='
1 SGR substring for highlighting mismatching types within
1 template arguments in the C++ frontend.
1
1 '-fno-diagnostics-show-option'
1 By default, each diagnostic emitted includes text indicating the
1 command-line option that directly controls the diagnostic (if such
1 an option is known to the diagnostic machinery). Specifying the
1 '-fno-diagnostics-show-option' flag suppresses that behavior.
1
1 '-fno-diagnostics-show-caret'
1 By default, each diagnostic emitted includes the original source
1 line and a caret '^' indicating the column. This option suppresses
1 this information. The source line is truncated to N characters, if
1 the '-fmessage-length=n' option is given. When the output is done
1 to the terminal, the width is limited to the width given by the
1 'COLUMNS' environment variable or, if not set, to the terminal
1 width.
1
1 '-fdiagnostics-parseable-fixits'
1 Emit fix-it hints in a machine-parseable format, suitable for
1 consumption by IDEs. For each fix-it, a line will be printed after
1 the relevant diagnostic, starting with the string "fix-it:". For
1 example:
1
1 fix-it:"test.c":{45:3-45:21}:"gtk_widget_show_all"
1
1 The location is expressed as a half-open range, expressed as a
1 count of bytes, starting at byte 1 for the initial column. In the
1 above example, bytes 3 through 20 of line 45 of "test.c" are to be
1 replaced with the given string:
1
1 00000000011111111112222222222
1 12345678901234567890123456789
1 gtk_widget_showall (dlg);
1 ^^^^^^^^^^^^^^^^^^
1 gtk_widget_show_all
1
1 The filename and replacement string escape backslash as "\\", tab
1 as "\t", newline as "\n", double quotes as "\"", non-printable
1 characters as octal (e.g. vertical tab as "\013").
1
1 An empty replacement string indicates that the given range is to be
1 removed. An empty range (e.g. "45:3-45:3") indicates that the
1 string is to be inserted at the given position.
1
1 '-fdiagnostics-generate-patch'
1 Print fix-it hints to stderr in unified diff format, after any
1 diagnostics are printed. For example:
1
1 --- test.c
1 +++ test.c
1 @ -42,5 +42,5 @
1
1 void show_cb(GtkDialog *dlg)
1 {
1 - gtk_widget_showall(dlg);
1 + gtk_widget_show_all(dlg);
1 }
1
1
1 The diff may or may not be colorized, following the same rules as
1 for diagnostics (see '-fdiagnostics-color').
1
1 '-fdiagnostics-show-template-tree'
1
1 In the C++ frontend, when printing diagnostics showing mismatching
1 template types, such as:
1
1 could not convert 'std::map<int, std::vector<double> >()'
1 from 'map<[...],vector<double>>' to 'map<[...],vector<float>>
1
1 the '-fdiagnostics-show-template-tree' flag enables printing a
1 tree-like structure showing the common and differing parts of the
1 types, such as:
1
1 map<
1 [...],
1 vector<
1 [double != float]>>
1
1 The parts that differ are highlighted with color ("double" and
1 "float" in this case).
1
1 '-fno-elide-type'
1 By default when the C++ frontend prints diagnostics showing
1 mismatching template types, common parts of the types are printed
1 as "[...]" to simplify the error message. For example:
1
1 could not convert 'std::map<int, std::vector<double> >()'
1 from 'map<[...],vector<double>>' to 'map<[...],vector<float>>
1
1 Specifying the '-fno-elide-type' flag suppresses that behavior.
1 This flag also affects the output of the
1 '-fdiagnostics-show-template-tree' flag.
1
1 '-fno-show-column'
1 Do not print column numbers in diagnostics. This may be necessary
1 if diagnostics are being scanned by a program that does not
1 understand the column numbers, such as 'dejagnu'.
1