| 1 |
@c Copyright (C) 2018-2025 Free Software Foundation, Inc. |
| 2 |
@c Free Software Foundation, Inc. |
| 3 |
@c This is part of the GCC manual. |
| 4 |
@c For copying conditions, see the file gcc.texi. |
| 5 |
|
| 6 |
@node User Experience Guidelines |
| 7 |
@chapter User Experience Guidelines |
| 8 |
@cindex user experience guidelines |
| 9 |
@cindex guidelines, user experience |
| 10 |
|
| 11 |
To borrow a slogan from |
| 12 |
@uref{https://elm-lang.org/news/compilers-as-assistants, Elm}, |
| 13 |
|
| 14 |
@quotation |
| 15 |
@strong{Compilers should be assistants, not adversaries.} A compiler should |
| 16 |
not just detect bugs, it should then help you understand why there is a bug. |
| 17 |
It should not berate you in a robot voice, it should give you specific hints |
| 18 |
that help you write better code. Ultimately, a compiler should make |
| 19 |
programming faster and more fun! |
| 20 |
@author Evan Czaplicki |
| 21 |
@end quotation |
| 22 |
|
| 23 |
This chapter provides guidelines on how to implement diagnostics and |
| 24 |
command-line options in ways that we hope achieve the above ideal. |
| 25 |
|
| 26 |
@menu |
| 27 |
* Guidelines for Diagnostics:: How to implement diagnostics. |
| 28 |
* Guidelines for Options:: Guidelines for command-line options. |
| 29 |
@end menu |
| 30 |
|
| 31 |
|
| 32 |
@node Guidelines for Diagnostics |
| 33 |
@section Guidelines for Diagnostics |
| 34 |
@cindex guidelines for diagnostics |
| 35 |
@cindex diagnostics, guidelines for |
| 36 |
|
| 37 |
@subsection Talk in terms of the user's code |
| 38 |
|
| 39 |
Diagnostics should be worded in terms of the user's source code, and the |
| 40 |
source language, rather than GCC's own implementation details. |
| 41 |
|
| 42 |
@subsection Diagnostics are actionable |
| 43 |
@cindex diagnostics, actionable |
| 44 |
|
| 45 |
A good diagnostic is @dfn{actionable}: it should assist the user in |
| 46 |
taking action. |
| 47 |
|
| 48 |
Consider what an end user will want to do when encountering a diagnostic. |
| 49 |
|
| 50 |
Given an error, an end user will think: ``How do I fix this?'' |
| 51 |
|
| 52 |
Given a warning, an end user will think: |
| 53 |
|
| 54 |
@itemize @bullet |
| 55 |
@item |
| 56 |
``Is this a real problem?'' |
| 57 |
@item |
| 58 |
``Do I care?'' |
| 59 |
@item |
| 60 |
if they decide it's genuine: ``How do I fix this?'' |
| 61 |
@end itemize |
| 62 |
|
| 63 |
A good diagnostic provides pertinent information to allow the user to |
| 64 |
easily answer the above questions. |
| 65 |
|
| 66 |
@subsection The user's attention is important |
| 67 |
|
| 68 |
A perfect compiler would issue a warning on every aspect of the user's |
| 69 |
source code that ought to be fixed, and issue no other warnings. |
| 70 |
Naturally, this ideal is impossible to achieve. |
| 71 |
|
| 72 |
@cindex signal-to-noise ratio (metaphorical usage for diagnostics) |
| 73 |
@cindex diagnostics, false positive |
| 74 |
@cindex diagnostics, true positive |
| 75 |
@cindex false positive |
| 76 |
@cindex true positive |
| 77 |
|
| 78 |
Warnings should have a good @dfn{signal-to-noise ratio}: we should have few |
| 79 |
@dfn{false positives} (falsely issuing a warning when no warning is |
| 80 |
warranted) and few @dfn{false negatives} (failing to issue a warning when |
| 81 |
one @emph{is} justified). |
| 82 |
|
| 83 |
Note that a false positive can mean, in practice, a warning that the |
| 84 |
user doesn't agree with. Ideally a diagnostic should contain enough |
| 85 |
information to allow the user to make an informed choice about whether |
| 86 |
they should care (and how to fix it), but a balance must be drawn against |
| 87 |
overloading the user with irrelevant data. |
| 88 |
|
| 89 |
@subsection Sometimes the user didn't write the code |
| 90 |
|
| 91 |
GCC is typically used in two different ways: |
| 92 |
|
| 93 |
@itemize @bullet |
| 94 |
@item |
| 95 |
Semi-interactive usage: GCC is used as a development tool when the user |
| 96 |
is writing code, as the ``compile'' part of the ``edit-compile-debug'' |
| 97 |
cycle. The user is actively hacking on the code themself (perhaps a |
| 98 |
project they wrote, or someone else's), where they just made a change |
| 99 |
to the code and want to see what happens, and to be warned about |
| 100 |
mistakes. |
| 101 |
|
| 102 |
@item |
| 103 |
Batch rebuilds: where the user is recompiling one or more existing |
| 104 |
packages, and GCC is a detail that's being invoked by various build |
| 105 |
scripts. Examples include a user trying to bring up an operating system |
| 106 |
consisting of hundreds of packages on a new CPU architecture, where the |
| 107 |
packages were written by many different people, or simply rebuilding |
| 108 |
packages after a dependency changed, where the user is hoping |
| 109 |
``nothing breaks'', since they are unfamiliar with the code. |
| 110 |
@end itemize |
| 111 |
|
| 112 |
Keep both of these styles of usage in mind when implementing diagnostics. |
| 113 |
|
| 114 |
@subsection Precision of Wording |
| 115 |
|
| 116 |
Provide the user with details that allow them to identify what the |
| 117 |
problem is. For example, the vaguely-worded message: |
| 118 |
|
| 119 |
@smallexample |
| 120 |
demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes] |
| 121 |
1 | int foo __attribute__((noinline)); |
| 122 |
| ^~~ |
| 123 |
@end smallexample |
| 124 |
|
| 125 |
@noindent |
| 126 |
doesn't tell the user why the attribute was ignored, or what kind of |
| 127 |
entity the compiler thought the attribute was being applied to (the |
| 128 |
source location for the diagnostic is also poor; |
| 129 |
@pxref{input_location_example,,discussion of @code{input_location}}). |
| 130 |
A better message would be: |
| 131 |
|
| 132 |
@smallexample |
| 133 |
demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was |
| 134 |
ignored [-Wattributes] |
| 135 |
1 | int foo __attribute__((noinline)); |
| 136 |
| ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~ |
| 137 |
demo.c:1:24: note: attribute 'noinline' is only applicable to functions |
| 138 |
@end smallexample |
| 139 |
|
| 140 |
@noindent |
| 141 |
which spells out the missing information (and fixes the location |
| 142 |
information, as discussed below). |
| 143 |
|
| 144 |
The above example uses a note to avoid a combinatorial explosion of possible |
| 145 |
messages. |
| 146 |
|
| 147 |
@subsection Try the diagnostic on real-world code |
| 148 |
|
| 149 |
It's worth testing a new warning on many instances of real-world code, |
| 150 |
written by different people, and seeing what it complains about, and |
| 151 |
what it doesn't complain about. |
| 152 |
|
| 153 |
This may suggest heuristics that silence common false positives. |
| 154 |
|
| 155 |
It may also suggest ways to improve the precision of the message. |
| 156 |
|
| 157 |
@subsection Make mismatches clear |
| 158 |
|
| 159 |
Many diagnostics relate to a mismatch between two different places in the |
| 160 |
user's source code. Examples include: |
| 161 |
@itemize @bullet |
| 162 |
@item |
| 163 |
a type mismatch, where the type at a usage site does not match the type |
| 164 |
at a declaration |
| 165 |
|
| 166 |
@item |
| 167 |
the argument count at a call site does not match the parameter count |
| 168 |
at the declaration |
| 169 |
|
| 170 |
@item |
| 171 |
something is erroneously duplicated (e.g.@: an error, due to breaking a |
| 172 |
uniqueness requirement, or a warning, if it's suggestive of a bug) |
| 173 |
|
| 174 |
@item |
| 175 |
an ``opened'' syntactic construct (such as an open-parenthesis) is not |
| 176 |
closed |
| 177 |
|
| 178 |
@c TODO: more examples? |
| 179 |
@end itemize |
| 180 |
|
| 181 |
In each case, the diagnostic should indicate @strong{both} pertinent |
| 182 |
locations (so that the user can easily see the problem and how to fix it). |
| 183 |
|
| 184 |
The standard way to do this is with a note (via @code{inform}). For |
| 185 |
example: |
| 186 |
|
| 187 |
@smallexample |
| 188 |
auto_diagnostic_group d; |
| 189 |
if (warning_at (loc, OPT_Wduplicated_cond, |
| 190 |
"duplicated %<if%> condition")) |
| 191 |
inform (EXPR_LOCATION (t), "previously used here"); |
| 192 |
@end smallexample |
| 193 |
|
| 194 |
@noindent |
| 195 |
which leads to: |
| 196 |
|
| 197 |
@smallexample |
| 198 |
demo.c: In function 'test': |
| 199 |
demo.c:5:17: warning: duplicated 'if' condition [-Wduplicated-cond] |
| 200 |
5 | else if (flag > 3) |
| 201 |
| ~~~~~^~~ |
| 202 |
demo.c:3:12: note: previously used here |
| 203 |
3 | if (flag > 3) |
| 204 |
| ~~~~~^~~ |
| 205 |
@end smallexample |
| 206 |
|
| 207 |
@noindent |
| 208 |
The @code{inform} call should be guarded by the return value from the |
| 209 |
@code{warning_at} call so that the note isn't emitted when the warning |
| 210 |
is suppressed. |
| 211 |
|
| 212 |
For cases involving punctuation where the locations might be near |
| 213 |
each other, they can be conditionally consolidated via |
| 214 |
@code{gcc_rich_location::add_location_if_nearby}: |
| 215 |
|
| 216 |
@smallexample |
| 217 |
auto_diagnostic_group d; |
| 218 |
gcc_rich_location richloc (primary_loc); |
| 219 |
bool added secondary = richloc.add_location_if_nearby (secondary_loc); |
| 220 |
error_at (&richloc, "main message"); |
| 221 |
if (!added secondary) |
| 222 |
inform (secondary_loc, "message for secondary"); |
| 223 |
@end smallexample |
| 224 |
|
| 225 |
@noindent |
| 226 |
This will emit either one diagnostic with two locations: |
| 227 |
@smallexample |
| 228 |
demo.c:42:10: error: main message |
| 229 |
(foo) |
| 230 |
~ ^ |
| 231 |
@end smallexample |
| 232 |
|
| 233 |
@noindent |
| 234 |
or two diagnostics: |
| 235 |
|
| 236 |
@smallexample |
| 237 |
demo.c:42:4: error: main message |
| 238 |
foo) |
| 239 |
^ |
| 240 |
demo.c:40:2: note: message for secondary |
| 241 |
( |
| 242 |
^ |
| 243 |
@end smallexample |
| 244 |
|
| 245 |
@subsection Location Information |
| 246 |
@cindex diagnostics, locations |
| 247 |
@cindex location information |
| 248 |
@cindex source code, location information |
| 249 |
@cindex caret |
| 250 |
|
| 251 |
GCC's @code{location_t} type can support both ordinary locations, |
| 252 |
and locations relating to a macro expansion. |
| 253 |
|
| 254 |
As of GCC 6, ordinary locations changed from supporting just a |
| 255 |
point in the user's source code to supporting three points: the |
| 256 |
@dfn{caret} location, plus a start and a finish: |
| 257 |
|
| 258 |
@smallexample |
| 259 |
a = foo && bar; |
| 260 |
~~~~^~~~~~ |
| 261 |
| | | |
| 262 |
| | finish |
| 263 |
| caret |
| 264 |
start |
| 265 |
@end smallexample |
| 266 |
|
| 267 |
Tokens coming out of libcpp have locations of the form @code{caret == start}, |
| 268 |
such as for @code{foo} here: |
| 269 |
|
| 270 |
@smallexample |
| 271 |
a = foo && bar; |
| 272 |
^~~ |
| 273 |
| | |
| 274 |
| finish |
| 275 |
caret == start |
| 276 |
@end smallexample |
| 277 |
|
| 278 |
Compound expressions should be reported using the location of the |
| 279 |
expression as a whole, rather than just of one token within it. |
| 280 |
|
| 281 |
For example, in @code{-Wformat}, rather than underlining just the first |
| 282 |
token of a bad argument: |
| 283 |
|
| 284 |
@smallexample |
| 285 |
printf("hello %i %s", (long)0, "world"); |
| 286 |
~^ ~ |
| 287 |
%li |
| 288 |
@end smallexample |
| 289 |
|
| 290 |
@noindent |
| 291 |
the whole of the expression should be underlined, so that the user can |
| 292 |
easily identify what is being referred to: |
| 293 |
|
| 294 |
@smallexample |
| 295 |
printf("hello %i %s", (long)0, "world"); |
| 296 |
~^ ~~~~~~~ |
| 297 |
%li |
| 298 |
@end smallexample |
| 299 |
|
| 300 |
@c this was r251239 |
| 301 |
|
| 302 |
Avoid using the @code{input_location} global, and the diagnostic functions |
| 303 |
that implicitly use it---use @code{error_at} and @code{warning_at} rather |
| 304 |
than @code{error} and @code{warning}, and provide the most appropriate |
| 305 |
@code{location_t} value available at that phase of the compilation. It's |
| 306 |
possible to supply secondary @code{location_t} values via |
| 307 |
@code{rich_location}. |
| 308 |
|
| 309 |
@noindent |
| 310 |
@anchor{input_location_example} |
| 311 |
For example, in the example of imprecise wording above, generating the |
| 312 |
diagnostic using @code{warning}: |
| 313 |
|
| 314 |
@smallexample |
| 315 |
// BAD: implicitly uses @code{input_location} |
| 316 |
warning (OPT_Wattributes, "%qE attribute ignored", name); |
| 317 |
@end smallexample |
| 318 |
|
| 319 |
@noindent |
| 320 |
leads to: |
| 321 |
|
| 322 |
@smallexample |
| 323 |
// BAD: uses @code{input_location} |
| 324 |
demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes] |
| 325 |
1 | int foo __attribute__((noinline)); |
| 326 |
| ^~~ |
| 327 |
@end smallexample |
| 328 |
|
| 329 |
@noindent |
| 330 |
which thus happened to use the location of the @code{int} token, rather |
| 331 |
than that of the attribute. Using @code{warning_at} with the location of |
| 332 |
the attribute, providing the location of the declaration in question |
| 333 |
as a secondary location, and adding a note: |
| 334 |
|
| 335 |
@smallexample |
| 336 |
auto_diagnostic_group d; |
| 337 |
gcc_rich_location richloc (attrib_loc); |
| 338 |
richloc.add_range (decl_loc); |
| 339 |
if (warning_at (OPT_Wattributes, &richloc, |
| 340 |
"attribute %qE on variable %qE was ignored", name)) |
| 341 |
inform (attrib_loc, "attribute %qE is only applicable to functions"); |
| 342 |
@end smallexample |
| 343 |
|
| 344 |
@noindent |
| 345 |
would lead to: |
| 346 |
|
| 347 |
@smallexample |
| 348 |
// OK: use location of attribute, with a secondary location |
| 349 |
demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was |
| 350 |
ignored [-Wattributes] |
| 351 |
1 | int foo __attribute__((noinline)); |
| 352 |
| ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~ |
| 353 |
demo.c:1:24: note: attribute 'noinline' is only applicable to functions |
| 354 |
@end smallexample |
| 355 |
|
| 356 |
@c TODO labelling of ranges |
| 357 |
|
| 358 |
@subsection Coding Conventions |
| 359 |
|
| 360 |
See the @uref{https://gcc.gnu.org/codingconventions.html#Diagnostics, |
| 361 |
diagnostics section} of the GCC coding conventions. |
| 362 |
|
| 363 |
In the C++ front end, when comparing two types in a message, use @samp{%H} |
| 364 |
and @samp{%I} rather than @samp{%T}, as this allows the diagnostics |
| 365 |
subsystem to highlight differences between template-based types. |
| 366 |
For example, rather than using @samp{%qT}: |
| 367 |
|
| 368 |
@smallexample |
| 369 |
// BAD: a pair of %qT used in C++ front end for type comparison |
| 370 |
error_at (loc, "could not convert %qE from %qT to %qT", expr, |
| 371 |
TREE_TYPE (expr), type); |
| 372 |
@end smallexample |
| 373 |
|
| 374 |
@noindent |
| 375 |
which could lead to: |
| 376 |
|
| 377 |
@smallexample |
| 378 |
error: could not convert 'map<int, double>()' from 'map<int,double>' |
| 379 |
to 'map<int,int>' |
| 380 |
@end smallexample |
| 381 |
|
| 382 |
@noindent |
| 383 |
using @samp{%H} and @samp{%I} (via @samp{%qH} and @samp{%qI}): |
| 384 |
|
| 385 |
@smallexample |
| 386 |
// OK: compare types in C++ front end via %qH and %qI |
| 387 |
error_at (loc, "could not convert %qE from %qH to %qI", expr, |
| 388 |
TREE_TYPE (expr), type); |
| 389 |
@end smallexample |
| 390 |
|
| 391 |
@noindent |
| 392 |
allows the above output to be simplified to: |
| 393 |
|
| 394 |
@smallexample |
| 395 |
error: could not convert 'map<int, double>()' from 'map<[...],double>' |
| 396 |
to 'map<[...],int>' |
| 397 |
@end smallexample |
| 398 |
|
| 399 |
@noindent |
| 400 |
where the @code{double} and @code{int} are colorized to highlight them. |
| 401 |
|
| 402 |
@c %H and %I were added in r248698. |
| 403 |
|
| 404 |
@subsection Group logically-related diagnostics |
| 405 |
|
| 406 |
Use @code{auto_diagnostic_group} when issuing multiple related |
| 407 |
diagnostics (seen in various examples on this page). This informs the |
| 408 |
diagnostic subsystem that all diagnostics issued within the lifetime |
| 409 |
of the @code{auto_diagnostic_group} are related. For example, |
| 410 |
@option{-fdiagnostics-format=json} will treat the first diagnostic |
| 411 |
emitted within the group as a top-level diagnostic, and all subsequent |
| 412 |
diagnostics within the group as its children. |
| 413 |
|
| 414 |
@subsection Quoting |
| 415 |
Text should be quoted by either using the @samp{q} modifier in a directive |
| 416 |
such as @samp{%qE}, or by enclosing the quoted text in a pair of @samp{%<} |
| 417 |
and @samp{%>} directives, and never by using explicit quote characters. |
| 418 |
The directives handle the appropriate quote characters for each language |
| 419 |
and apply the correct color or highlighting. |
| 420 |
|
| 421 |
The following elements should be quoted in GCC diagnostics: |
| 422 |
|
| 423 |
@itemize @bullet |
| 424 |
@item |
| 425 |
Language keywords. |
| 426 |
@item |
| 427 |
Tokens. |
| 428 |
@item |
| 429 |
Boolean, numerical, character, and string constants that appear in the |
| 430 |
source code. |
| 431 |
@item |
| 432 |
Identifiers, including function, macro, type, and variable names. |
| 433 |
@end itemize |
| 434 |
|
| 435 |
Other elements such as numbers that do not refer to numeric constants that |
| 436 |
appear in the source code should not be quoted. For example, in the message: |
| 437 |
|
| 438 |
@smallexample |
| 439 |
argument %d of %qE must be a pointer type |
| 440 |
@end smallexample |
| 441 |
|
| 442 |
@noindent |
| 443 |
since the argument number does not refer to a numerical constant in the |
| 444 |
source code it should not be quoted. |
| 445 |
|
| 446 |
@subsection Use color consistently when highlighting mismatches |
| 447 |
|
| 448 |
As of GCC 15, the diagnostics subsystem has a concept of ``highlight |
| 449 |
colors''. These should be used to consistently colorize both the text |
| 450 |
within diagnostic messages and underlined ranges of quoted source when |
| 451 |
highlighting mismatches, for all messages with a logically-related group |
| 452 |
of diagnostics. |
| 453 |
|
| 454 |
See @file{diagnostic-highlight-colors.h} for symbolic names for color |
| 455 |
codes, covering e.g. |
| 456 |
|
| 457 |
@itemize @bullet |
| 458 |
|
| 459 |
@item |
| 460 |
@code{highlight_colors::expected} versus @code{highlight_colors::actual} |
| 461 |
|
| 462 |
@item |
| 463 |
@code{highlight_colors::lhs} versus @code{highlight_colors::rhs} |
| 464 |
|
| 465 |
@end itemize |
| 466 |
|
| 467 |
For example, given: |
| 468 |
|
| 469 |
@smallexample |
| 470 |
error: invalid operands to binary + (have 'S' @{aka 'struct s'@} and 'T' @{aka 'struct t'@}) |
| 471 |
return callee_4a () + callee_4b (); |
| 472 |
~~~~~~~~~~~~ ^ ~~~~~~~~~~~~ |
| 473 |
| | |
| 474 |
| T @{aka struct t@} |
| 475 |
S @{aka struct s@} |
| 476 |
@end smallexample |
| 477 |
|
| 478 |
@itemize @bullet |
| 479 |
|
| 480 |
@item |
| 481 |
the text ``S @{aka struct s@}'' in the message and the left-hand label |
| 482 |
in the quoted source should be colorized as @code{highlight_colors::lhs} |
| 483 |
(which equates to the color name @code{highlight-a}) |
| 484 |
|
| 485 |
@item |
| 486 |
the text ``T @{aka struct t@}'' in the message and the right-hand label |
| 487 |
in the quoted source should be colorized as @code{highlight_colors::rhs} |
| 488 |
(which equates to the color name @code{highlight-b}) |
| 489 |
|
| 490 |
@end itemize |
| 491 |
|
| 492 |
Doing so ought to make it easier for the user to understand what the |
| 493 |
diagnostic is telling them. |
| 494 |
|
| 495 |
When issuing followup @code{note} diagnostics, all diagnostics within the |
| 496 |
group should use a consistent scheme to highlight the mismatching elements, |
| 497 |
so that color contrasts the differences. For example, given: |
| 498 |
|
| 499 |
@smallexample |
| 500 |
warning: format ‘%i’ expects argument of type ‘int’, but argument 2 has type ‘const char *’ [-Wformat=] |
| 501 |
279 | printf("hello " INT_FMT " world", msg); |
| 502 |
| ^~~~~~~~ ~~~ |
| 503 |
| | |
| 504 |
| const char * |
| 505 |
note: format string is defined here |
| 506 |
278 | #define INT_FMT "%i" |
| 507 |
| ~^ |
| 508 |
| | |
| 509 |
| int |
| 510 |
| %s |
| 511 |
@end smallexample |
| 512 |
|
| 513 |
@itemize @bullet |
| 514 |
|
| 515 |
@item |
| 516 |
the text @code{%i} and @code{int} referring to the format string and the |
| 517 |
expected type due to it should be colorized as @code{highlight-a} both |
| 518 |
in the diagnostics message and in the range quoted in the @code{range}. |
| 519 |
|
| 520 |
@item |
| 521 |
the text @code{const char *} in the diagnostic message and in the quoted |
| 522 |
range should be colorized as @code{highlight-b}. |
| 523 |
|
| 524 |
@end itemize |
| 525 |
|
| 526 |
This can be implemented by using e.g. |
| 527 |
@code{highlight_colors::actual} and |
| 528 |
@code{highlight_colors::expected} when adding ranges to |
| 529 |
@code{rich_location} instances, and e.g. by using the @code{%e} format |
| 530 |
code for @code{pretty_printer} to use a @code{pp_element *}, and using |
| 531 |
appropriate member functions of pp_element to add colorization. |
| 532 |
|
| 533 |
@subsection Spelling and Terminology |
| 534 |
|
| 535 |
See the @uref{https://gcc.gnu.org/codingconventions.html#Spelling |
| 536 |
Spelling, terminology and markup} section of the GCC coding conventions. |
| 537 |
|
| 538 |
@subsection Fix-it hints |
| 539 |
@cindex fix-it hints |
| 540 |
@cindex diagnostics guidelines, fix-it hints |
| 541 |
|
| 542 |
GCC's diagnostic subsystem can emit @dfn{fix-it hints}: small suggested |
| 543 |
edits to the user's source code. |
| 544 |
|
| 545 |
They are printed by default underneath the code in question. They |
| 546 |
can also be viewed via @option{-fdiagnostics-generate-patch} and |
| 547 |
@option{-fdiagnostics-parseable-fixits}. With the latter, an IDE |
| 548 |
ought to be able to offer to automatically apply the suggested fix. |
| 549 |
|
| 550 |
Fix-it hints contain code fragments, and thus they should not be marked |
| 551 |
for translation. |
| 552 |
|
| 553 |
Fix-it hints can be added to a diagnostic by using a @code{rich_location} |
| 554 |
rather than a @code{location_t} - the fix-it hints are added to the |
| 555 |
@code{rich_location} using one of the various @code{add_fixit} member |
| 556 |
functions of @code{rich_location}. They are documented with |
| 557 |
@code{rich_location} in @file{libcpp/line-map.h}. |
| 558 |
It's easiest to use the @code{gcc_rich_location} subclass of |
| 559 |
@code{rich_location} found in @file{gcc-rich-location.h}, as this |
| 560 |
implicitly supplies the @code{line_table} variable. |
| 561 |
|
| 562 |
For example: |
| 563 |
|
| 564 |
@smallexample |
| 565 |
if (const char *suggestion = hint.suggestion ()) |
| 566 |
@{ |
| 567 |
gcc_rich_location richloc (location); |
| 568 |
richloc.add_fixit_replace (suggestion); |
| 569 |
error_at (&richloc, |
| 570 |
"%qE does not name a type; did you mean %qs?", |
| 571 |
id, suggestion); |
| 572 |
@} |
| 573 |
@end smallexample |
| 574 |
|
| 575 |
@noindent |
| 576 |
which can lead to: |
| 577 |
|
| 578 |
@smallexample |
| 579 |
spellcheck-typenames.C:73:1: error: 'singed' does not name a type; did |
| 580 |
you mean 'signed'? |
| 581 |
73 | singed char ch; |
| 582 |
| ^~~~~~ |
| 583 |
| signed |
| 584 |
@end smallexample |
| 585 |
|
| 586 |
Non-trivial edits can be built up by adding multiple fix-it hints to one |
| 587 |
@code{rich_location}. It's best to express the edits in terms of the |
| 588 |
locations of individual tokens. Various handy functions for adding |
| 589 |
fix-it hints for idiomatic C and C++ can be seen in |
| 590 |
@file{gcc-rich-location.h}. |
| 591 |
|
| 592 |
@subsubsection Fix-it hints should work |
| 593 |
|
| 594 |
When implementing a fix-it hint, please verify that the suggested edit |
| 595 |
leads to fixed, compilable code. (Unfortunately, this currently must be |
| 596 |
done by hand using @option{-fdiagnostics-generate-patch}. It would be |
| 597 |
good to have an automated way of verifying that fix-it hints actually fix |
| 598 |
the code). |
| 599 |
|
| 600 |
For example, a ``gotcha'' here is to forget to add a space when adding a |
| 601 |
missing reserved word. Consider a C++ fix-it hint that adds |
| 602 |
@code{typename} in front of a template declaration. A naive way to |
| 603 |
implement this might be: |
| 604 |
|
| 605 |
@smallexample |
| 606 |
gcc_rich_location richloc (loc); |
| 607 |
// BAD: insertion is missing a trailing space |
| 608 |
richloc.add_fixit_insert_before ("typename"); |
| 609 |
error_at (&richloc, "need %<typename%> before %<%T::%E%> because " |
| 610 |
"%qT is a dependent scope", |
| 611 |
parser->scope, id, parser->scope); |
| 612 |
@end smallexample |
| 613 |
|
| 614 |
@noindent |
| 615 |
When applied to the code, this might lead to: |
| 616 |
|
| 617 |
@smallexample |
| 618 |
T::type x; |
| 619 |
@end smallexample |
| 620 |
|
| 621 |
@noindent |
| 622 |
being ``corrected'' to: |
| 623 |
|
| 624 |
@smallexample |
| 625 |
typenameT::type x; |
| 626 |
@end smallexample |
| 627 |
|
| 628 |
@noindent |
| 629 |
In this case, the correct thing to do is to add a trailing space after |
| 630 |
@code{typename}: |
| 631 |
|
| 632 |
@smallexample |
| 633 |
gcc_rich_location richloc (loc); |
| 634 |
// OK: note that here we have a trailing space |
| 635 |
richloc.add_fixit_insert_before ("typename "); |
| 636 |
error_at (&richloc, "need %<typename%> before %<%T::%E%> because " |
| 637 |
"%qT is a dependent scope", |
| 638 |
parser->scope, id, parser->scope); |
| 639 |
@end smallexample |
| 640 |
|
| 641 |
@noindent |
| 642 |
leading to this corrected code: |
| 643 |
|
| 644 |
@smallexample |
| 645 |
typename T::type x; |
| 646 |
@end smallexample |
| 647 |
|
| 648 |
@subsubsection Express deletion in terms of deletion, not replacement |
| 649 |
|
| 650 |
It's best to express deletion suggestions in terms of deletion fix-it |
| 651 |
hints, rather than replacement fix-it hints. For example, consider this: |
| 652 |
|
| 653 |
@smallexample |
| 654 |
auto_diagnostic_group d; |
| 655 |
gcc_rich_location richloc (location_of (retval)); |
| 656 |
tree name = DECL_NAME (arg); |
| 657 |
richloc.add_fixit_replace (IDENTIFIER_POINTER (name)); |
| 658 |
warning_at (&richloc, OPT_Wredundant_move, |
| 659 |
"redundant move in return statement"); |
| 660 |
@end smallexample |
| 661 |
|
| 662 |
@noindent |
| 663 |
which is intended to e.g.@: replace a @code{std::move} with the underlying |
| 664 |
value: |
| 665 |
|
| 666 |
@smallexample |
| 667 |
return std::move (retval); |
| 668 |
~~~~~~~~~~^~~~~~~~ |
| 669 |
retval |
| 670 |
@end smallexample |
| 671 |
|
| 672 |
@noindent |
| 673 |
where the change has been expressed as replacement, replacing |
| 674 |
with the name of the declaration. |
| 675 |
This works for simple cases, but consider this case: |
| 676 |
|
| 677 |
@smallexample |
| 678 |
#ifdef SOME_CONFIG_FLAG |
| 679 |
# define CONFIGURY_GLOBAL global_a |
| 680 |
#else |
| 681 |
# define CONFIGURY_GLOBAL global_b |
| 682 |
#endif |
| 683 |
|
| 684 |
int fn () |
| 685 |
@{ |
| 686 |
return std::move (CONFIGURY_GLOBAL /* some comment */); |
| 687 |
@} |
| 688 |
@end smallexample |
| 689 |
|
| 690 |
@noindent |
| 691 |
The above implementation erroneously strips out the macro and the |
| 692 |
comment in the fix-it hint: |
| 693 |
|
| 694 |
@smallexample |
| 695 |
return std::move (CONFIGURY_GLOBAL /* some comment */); |
| 696 |
~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 697 |
global_a |
| 698 |
@end smallexample |
| 699 |
|
| 700 |
@noindent |
| 701 |
and thus this resulting code: |
| 702 |
|
| 703 |
@smallexample |
| 704 |
return global_a; |
| 705 |
@end smallexample |
| 706 |
|
| 707 |
@noindent |
| 708 |
It's better to do deletions in terms of deletions; deleting the |
| 709 |
@code{std::move (} and the trailing close-paren, leading to |
| 710 |
this: |
| 711 |
|
| 712 |
@smallexample |
| 713 |
return std::move (CONFIGURY_GLOBAL /* some comment */); |
| 714 |
~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 715 |
CONFIGURY_GLOBAL /* some comment */ |
| 716 |
@end smallexample |
| 717 |
|
| 718 |
@noindent |
| 719 |
and thus this result: |
| 720 |
|
| 721 |
@smallexample |
| 722 |
return CONFIGURY_GLOBAL /* some comment */; |
| 723 |
@end smallexample |
| 724 |
|
| 725 |
@noindent |
| 726 |
Unfortunately, the pertinent @code{location_t} values are not always |
| 727 |
available. |
| 728 |
|
| 729 |
@c the above was https://gcc.gnu.org/ml/gcc-patches/2018-08/msg01474.html |
| 730 |
|
| 731 |
@subsubsection Multiple suggestions |
| 732 |
|
| 733 |
In the rare cases where you need to suggest more than one mutually |
| 734 |
exclusive solution to a problem, this can be done by emitting |
| 735 |
multiple notes and calling |
| 736 |
@code{rich_location::fixits_cannot_be_auto_applied} on each note's |
| 737 |
@code{rich_location}. If this is called, then the fix-it hints in |
| 738 |
the @code{rich_location} will be printed, but will not be added to |
| 739 |
generated patches. |
| 740 |
|
| 741 |
|
| 742 |
@node Guidelines for Options |
| 743 |
@section Guidelines for Options |
| 744 |
@cindex command-line options, guidelines for |
| 745 |
@cindex options, guidelines for |
| 746 |
@cindex guidelines for options |
| 747 |
|
| 748 |
@c TODO |