Next: Warning Options, Previous: Objective-C and Objective-C++ Dialect Options, Up: Invoking GCC [Contents][Index]
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=nTry 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-show-location=onceOnly 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-lineOnly 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-colorUse 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
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.
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.
-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-optionBy 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-caretBy 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-labelsBy 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-cweDiagnostic 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-line-numbersBy 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=widthThis option controls the minimum width of the left margin printed by -fdiagnostics-show-line-numbers. It defaults to 6.
-fdiagnostics-parseable-fixitsEmit 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-patchPrint 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-treeIn 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-typeBy 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=KINDSpecify 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-depthsThis 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=separate-events.
This is intended for use by GCC developers and plugin developers when debugging diagnostics that report interprocedural control flow.
-fno-show-columnDo 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-format=FORMATSelect a different format for printing diagnostics. FORMAT is ‘text’ or ‘json’. The default is ‘text’.
The ‘json’ format consists of a top-level JSON array containing JSON objects representing the diagnostics.
The JSON is emitted as one line, without formatting; the examples below have been formatted for clarity.
Diagnostics can have child diagnostics. For example, this error and note:
misleading-indentation.c:15:3: warning: this 'if' clause does not
guard... [-Wmisleading-indentation]
15 | if (flag)
| ^~
misleading-indentation.c:17:5: note: ...this statement, but the latter
is misleadingly indented as if it were guarded by the 'if'
17 | y = 2;
| ^
might be printed in JSON form (after formatting) like this:
[
{
"kind": "warning",
"locations": [
{
"caret": {
"column": 3,
"file": "misleading-indentation.c",
"line": 15
},
"finish": {
"column": 4,
"file": "misleading-indentation.c",
"line": 15
}
}
],
"message": "this \u2018if\u2019 clause does not guard...",
"option": "-Wmisleading-indentation",
"option_url": "https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wmisleading-indentation",
"children": [
{
"kind": "note",
"locations": [
{
"caret": {
"column": 5,
"file": "misleading-indentation.c",
"line": 17
}
}
],
"message": "...this statement, but the latter is …"
}
]
},
…
]
where the note is a child of the warning.
A diagnostic has a kind. If this is warning, then there is
an option key describing the command-line option controlling the
warning.
A diagnostic can contain zero or more locations. Each location has up
to three positions within it: a caret position and optional
start and finish positions. A location can also have
an optional label string. For example, this error:
bad-binary-ops.c:64:23: error: invalid operands to binary + (have 'S' {aka
'struct s'} and 'T' {aka 'struct t'})
64 | return callee_4a () + callee_4b ();
| ~~~~~~~~~~~~ ^ ~~~~~~~~~~~~
| | |
| | T {aka struct t}
| S {aka struct s}
has three locations. Its primary location is at the “+” token at column 23. It has two secondary locations, describing the left and right-hand sides of the expression, which have labels. It might be printed in JSON form as:
{
"children": [],
"kind": "error",
"locations": [
{
"caret": {
"column": 23, "file": "bad-binary-ops.c", "line": 64
}
},
{
"caret": {
"column": 10, "file": "bad-binary-ops.c", "line": 64
},
"finish": {
"column": 21, "file": "bad-binary-ops.c", "line": 64
},
"label": "S {aka struct s}"
},
{
"caret": {
"column": 25, "file": "bad-binary-ops.c", "line": 64
},
"finish": {
"column": 36, "file": "bad-binary-ops.c", "line": 64
},
"label": "T {aka struct t}"
}
],
"message": "invalid operands to binary + …"
}
If a diagnostic contains fix-it hints, it has a fixits array,
consisting of half-open intervals, similar to the output of
-fdiagnostics-parseable-fixits. For example, this diagnostic
with a replacement fix-it hint:
demo.c:8:15: error: 'struct s' has no member named 'colour'; did you
mean 'color'?
8 | return ptr->colour;
| ^~~~~~
| color
might be printed in JSON form as:
{
"children": [],
"fixits": [
{
"next": {
"column": 21,
"file": "demo.c",
"line": 8
},
"start": {
"column": 15,
"file": "demo.c",
"line": 8
},
"string": "color"
}
],
"kind": "error",
"locations": [
{
"caret": {
"column": 15,
"file": "demo.c",
"line": 8
},
"finish": {
"column": 20,
"file": "demo.c",
"line": 8
}
}
],
"message": "\u2018struct s\u2019 has no member named …"
}
where the fix-it hint suggests replacing the text from start up
to but not including next with string’s value. Deletions
are expressed via an empty value for string, insertions by
having start equal next.
If the diagnostic has a path of control-flow events associated with it,
it has a path array of objects representing the events. Each
event object has a description string, a location object,
along with a function string and a depth number for
representing interprocedural paths. The function represents the
current function at that event, and the depth represents the
stack depth relative to some baseline: the higher, the more frames are
within the stack.
For example, the intraprocedural example shown for -fdiagnostics-path-format= might have this JSON for its path:
"path": [
{
"depth": 0,
"description": "when 'PyList_New' fails, returning NULL",
"function": "test",
"location": {
"column": 10,
"file": "test.c",
"line": 25
}
},
{
"depth": 0,
"description": "when 'i < count'",
"function": "test",
"location": {
"column": 3,
"file": "test.c",
"line": 27
}
},
{
"depth": 0,
"description": "when calling 'PyList_Append', passing NULL from (1) as argument 1",
"function": "test",
"location": {
"column": 5,
"file": "test.c",
"line": 29
}
}
]
Next: Warning Options, Previous: Objective-C and Objective-C++ Dialect Options, Up: Invoking GCC [Contents][Index]