1 /* Various declarations for language-independent diagnostics subroutines.
2 Copyright (C) 2000-2023 Free Software Foundation, Inc.
3 Contributed by Gabriel Dos Reis <gdr@codesourcery.com>
4
5 This file is part of GCC.
6
7 GCC is free software; you can redistribute it and/or modify it under
8 the terms of the GNU General Public License as published by the Free
9 Software Foundation; either version 3, or (at your option) any later
10 version.
11
12 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 for more details.
16
17 You should have received a copy of the GNU General Public License
18 along with GCC; see the file COPYING3. If not see
19 <http://www.gnu.org/licenses/>. */
20
21 #ifndef GCC_DIAGNOSTIC_H
22 #define GCC_DIAGNOSTIC_H
23
24 #include "pretty-print.h"
25 #include "diagnostic-core.h"
26
27 /* An enum for controlling what units to use for the column number
28 when diagnostics are output, used by the -fdiagnostics-column-unit option.
29 Tabs will be expanded or not according to the value of -ftabstop. The origin
30 (default 1) is controlled by -fdiagnostics-column-origin. */
31
32 enum diagnostics_column_unit
33 {
34 /* The default from GCC 11 onwards: display columns. */
35 DIAGNOSTICS_COLUMN_UNIT_DISPLAY,
36
37 /* The behavior in GCC 10 and earlier: simple bytes. */
38 DIAGNOSTICS_COLUMN_UNIT_BYTE
39 };
40
41 /* An enum for controlling how to print non-ASCII characters/bytes when
42 a diagnostic suggests escaping the source code on output. */
43
44 enum diagnostics_escape_format
45 {
46 /* Escape non-ASCII Unicode characters in the form <U+XXXX> and
47 non-UTF-8 bytes in the form <XX>. */
48 DIAGNOSTICS_ESCAPE_FORMAT_UNICODE,
49
50 /* Escape non-ASCII bytes in the form <XX> (thus showing the underlying
51 encoding of non-ASCII Unicode characters). */
52 DIAGNOSTICS_ESCAPE_FORMAT_BYTES
53 };
54
55 /* Enum for overriding the standard output format. */
56
57 enum diagnostics_output_format
58 {
59 /* The default: textual output. */
60 DIAGNOSTICS_OUTPUT_FORMAT_TEXT,
61
62 /* JSON-based output, to stderr. */
63 DIAGNOSTICS_OUTPUT_FORMAT_JSON_STDERR,
64
65 /* JSON-based output, to a file. */
66 DIAGNOSTICS_OUTPUT_FORMAT_JSON_FILE,
67
68 /* SARIF-based output, to stderr. */
69 DIAGNOSTICS_OUTPUT_FORMAT_SARIF_STDERR,
70
71 /* SARIF-based output, to a file. */
72 DIAGNOSTICS_OUTPUT_FORMAT_SARIF_FILE
73 };
74
75 /* An enum for controlling how diagnostic_paths should be printed. */
76 enum diagnostic_path_format
77 {
78 /* Don't print diagnostic_paths. */
79 DPF_NONE,
80
81 /* Print diagnostic_paths by emitting a separate "note" for every event
82 in the path. */
83 DPF_SEPARATE_EVENTS,
84
85 /* Print diagnostic_paths by consolidating events together where they
86 are close enough, and printing such runs of events with multiple
87 calls to diagnostic_show_locus, showing the individual events in
88 each run via labels in the source. */
89 DPF_INLINE_EVENTS
90 };
91
92 /* An enum for capturing values of GCC_EXTRA_DIAGNOSTIC_OUTPUT,
93 and for -fdiagnostics-parseable-fixits. */
94
95 enum diagnostics_extra_output_kind
96 {
97 /* No extra output, or an unrecognized value. */
98 EXTRA_DIAGNOSTIC_OUTPUT_none,
99
100 /* Emit fix-it hints using the "fixits-v1" format, equivalent to
101 -fdiagnostics-parseable-fixits. */
102 EXTRA_DIAGNOSTIC_OUTPUT_fixits_v1,
103
104 /* Emit fix-it hints using the "fixits-v2" format. */
105 EXTRA_DIAGNOSTIC_OUTPUT_fixits_v2
106 };
107
108 /* A diagnostic is described by the MESSAGE to send, the FILE and LINE of
109 its context and its KIND (ice, error, warning, note, ...) See complete
110 list in diagnostic.def. */
111 struct diagnostic_info
112 {
113 diagnostic_info ()
114 : message (), richloc (), metadata (), x_data (), kind (), option_index (),
115 m_iinfo ()
116 { }
117
118 /* Text to be formatted. */
119 text_info message;
120
121 /* The location at which the diagnostic is to be reported. */
122 rich_location *richloc;
123
124 /* An optional bundle of metadata associated with the diagnostic
125 (or NULL). */
126 const diagnostic_metadata *metadata;
127
128 /* Auxiliary data for client. */
129 void *x_data;
130 /* The kind of diagnostic it is about. */
131 diagnostic_t kind;
132 /* Which OPT_* directly controls this diagnostic. */
133 int option_index;
134
135 /* Inlining context containing locations for each call site along
136 the inlining stack. */
137 struct inlining_info
138 {
139 /* Locations along the inlining stack. */
140 auto_vec<location_t, 8> m_ilocs;
141 /* The abstract origin of the location. */
142 void *m_ao;
143 /* Set if every M_ILOCS element is in a system header. */
144 bool m_allsyslocs;
145 } m_iinfo;
146 };
147
148 /* Each time a diagnostic's classification is changed with a pragma,
149 we record the change and the location of the change in an array of
150 these structs. */
151 struct diagnostic_classification_change_t
152 {
153 location_t location;
154 int option;
155 diagnostic_t kind;
156 };
157
158 /* Forward declarations. */
159 typedef void (*diagnostic_starter_fn) (diagnostic_context *,
160 diagnostic_info *);
161
162 typedef void (*diagnostic_start_span_fn) (diagnostic_context *,
163 expanded_location);
164
165 typedef void (*diagnostic_finalizer_fn) (diagnostic_context *,
166 diagnostic_info *,
167 diagnostic_t);
168
169 class edit_context;
170 namespace json { class value; }
171 class diagnostic_client_data_hooks;
172 class logical_location;
173
174 /* This data structure bundles altogether any information relevant to
175 the context of a diagnostic message. */
176 struct diagnostic_context
177 {
178 /* Where most of the diagnostic formatting work is done. */
179 pretty_printer *printer;
180
181 /* Cache of source code. */
182 file_cache *m_file_cache;
183
184 /* The number of times we have issued diagnostics. */
185 int diagnostic_count[DK_LAST_DIAGNOSTIC_KIND];
186
187 /* True if it has been requested that warnings be treated as errors. */
188 bool warning_as_error_requested;
189
190 /* The number of option indexes that can be passed to warning() et
191 al. */
192 int n_opts;
193
194 /* For each option index that can be passed to warning() et al
195 (OPT_* from options.h when using this code with the core GCC
196 options), this array may contain a new kind that the diagnostic
197 should be changed to before reporting, or DK_UNSPECIFIED to leave
198 it as the reported kind, or DK_IGNORED to not report it at
199 all. */
200 diagnostic_t *classify_diagnostic;
201
202 /* History of all changes to the classifications above. This list
203 is stored in location-order, so we can search it, either
204 binary-wise or end-to-front, to find the most recent
205 classification for a given diagnostic, given the location of the
206 diagnostic. */
207 diagnostic_classification_change_t *classification_history;
208
209 /* The size of the above array. */
210 int n_classification_history;
211
212 /* For pragma push/pop. */
213 int *push_list;
214 int n_push;
215
216 /* True if we should print the source line with a caret indicating
217 the location. */
218 bool show_caret;
219
220 /* Maximum width of the source line printed. */
221 int caret_max_width;
222
223 /* Character used for caret diagnostics. */
224 char caret_chars[rich_location::STATICALLY_ALLOCATED_RANGES];
225
226 /* True if we should print any CWE identifiers associated with
227 diagnostics. */
228 bool show_cwe;
229
230 /* True if we should print any rules associated with diagnostics. */
231 bool show_rules;
232
233 /* How should diagnostic_path objects be printed. */
234 enum diagnostic_path_format path_format;
235
236 /* True if we should print stack depths when printing diagnostic paths. */
237 bool show_path_depths;
238
239 /* True if we should print the command line option which controls
240 each diagnostic, if known. */
241 bool show_option_requested;
242
243 /* True if we should raise a SIGABRT on errors. */
244 bool abort_on_error;
245
246 /* True if we should show the column number on diagnostics. */
247 bool show_column;
248
249 /* True if pedwarns are errors. */
250 bool pedantic_errors;
251
252 /* True if permerrors are warnings. */
253 bool permissive;
254
255 /* The index of the option to associate with turning permerrors into
256 warnings. */
257 int opt_permissive;
258
259 /* True if errors are fatal. */
260 bool fatal_errors;
261
262 /* True if all warnings should be disabled. */
263 bool dc_inhibit_warnings;
264
265 /* True if warnings should be given in system headers. */
266 bool dc_warn_system_headers;
267
268 /* Maximum number of errors to report. */
269 int max_errors;
270
271 /* This function is called before any message is printed out. It is
272 responsible for preparing message prefix and such. For example, it
273 might say:
274 In file included from "/usr/local/include/curses.h:5:
275 from "/home/gdr/src/nifty_printer.h:56:
276 ...
277 */
278 diagnostic_starter_fn begin_diagnostic;
279
280 /* This function is called by diagnostic_show_locus in between
281 disjoint spans of source code, so that the context can print
282 something to indicate that a new span of source code has begun. */
283 diagnostic_start_span_fn start_span;
284
285 /* This function is called after the diagnostic message is printed. */
286 diagnostic_finalizer_fn end_diagnostic;
287
288 /* Client hook to report an internal error. */
289 void (*internal_error) (diagnostic_context *, const char *, va_list *);
290
291 /* Client hook to say whether the option controlling a diagnostic is
292 enabled. Returns nonzero if enabled, zero if disabled. */
293 int (*option_enabled) (int, unsigned, void *);
294
295 /* Client information to pass as second argument to
296 option_enabled. */
297 void *option_state;
298
299 /* Client hook to return the name of an option that controls a
300 diagnostic. Returns malloced memory. The first diagnostic_t
301 argument is the kind of diagnostic before any reclassification
302 (of warnings as errors, etc.); the second is the kind after any
303 reclassification. May return NULL if no name is to be printed.
304 May be passed 0 as well as the index of a particular option. */
305 char *(*option_name) (diagnostic_context *, int, diagnostic_t, diagnostic_t);
306
307 /* Client hook to return a URL describing the option that controls
308 a diagnostic. Returns malloced memory. May return NULL if no URL
309 is available. May be passed 0 as well as the index of a
310 particular option. */
311 char *(*get_option_url) (diagnostic_context *, int);
312
313 void (*print_path) (diagnostic_context *, const diagnostic_path *);
314 json::value *(*make_json_for_path) (diagnostic_context *, const diagnostic_path *);
315
316 /* Auxiliary data for client. */
317 void *x_data;
318
319 /* Used to detect that the last caret was printed at the same location. */
320 location_t last_location;
321
322 /* Used to detect when the input file stack has changed since last
323 described. */
324 const line_map_ordinary *last_module;
325
326 int lock;
327
328 /* A copy of lang_hooks.option_lang_mask (). */
329 unsigned lang_mask;
330
331 bool inhibit_notes_p;
332
333 /* When printing source code, should the characters at carets and ranges
334 be colorized? (assuming colorization is on at all).
335 This should be true for frontends that generate range information
336 (so that the ranges of code are colorized),
337 and false for frontends that merely specify points within the
338 source code (to avoid e.g. colorizing just the first character in
339 a token, which would look strange). */
340 bool colorize_source_p;
341
342 /* When printing source code, should labelled ranges be printed? */
343 bool show_labels_p;
344
345 /* When printing source code, should there be a left-hand margin
346 showing line numbers? */
347 bool show_line_numbers_p;
348
349 /* If printing source code, what should the minimum width of the margin
350 be? Line numbers will be right-aligned, and padded to this width. */
351 int min_margin_width;
352
353 /* Usable by plugins; if true, print a debugging ruler above the
354 source output. */
355 bool show_ruler_p;
356
357 /* True if -freport-bug option is used. */
358 bool report_bug;
359
360 /* Used to specify additional diagnostic output to be emitted after the
361 rest of the diagnostic. This is for implementing
362 -fdiagnostics-parseable-fixits and GCC_EXTRA_DIAGNOSTIC_OUTPUT. */
363 enum diagnostics_extra_output_kind extra_output_kind;
364
365 /* What units to use when outputting the column number. */
366 enum diagnostics_column_unit column_unit;
367
368 /* The origin for the column number (1-based or 0-based typically). */
369 int column_origin;
370
371 /* The size of the tabstop for tab expansion. */
372 int tabstop;
373
374 /* How should non-ASCII/non-printable bytes be escaped when
375 a diagnostic suggests escaping the source code on output. */
376 enum diagnostics_escape_format escape_format;
377
378 /* If non-NULL, an edit_context to which fix-it hints should be
379 applied, for generating patches. */
380 edit_context *edit_context_ptr;
381
382 /* How many diagnostic_group instances are currently alive. */
383 int diagnostic_group_nesting_depth;
384
385 /* How many diagnostics have been emitted since the bottommost
386 diagnostic_group was pushed. */
387 int diagnostic_group_emission_count;
388
389 /* Optional callbacks for handling diagnostic groups. */
390
391 /* If non-NULL, this will be called immediately before the first
392 time a diagnostic is emitted within a stack of groups. */
393 void (*begin_group_cb) (diagnostic_context * context);
394
395 /* If non-NULL, this will be called when a stack of groups is
396 popped if any diagnostics were emitted within that group. */
397 void (*end_group_cb) (diagnostic_context * context);
398
399 /* Callback for final cleanup. */
400 void (*final_cb) (diagnostic_context *context);
401
402 /* Callback to set the locations of call sites along the inlining
403 stack corresponding to a diagnostic location. Needed to traverse
404 the BLOCK_SUPERCONTEXT() chain hanging off the LOCATION_BLOCK()
405 of a diagnostic's location. */
406 void (*set_locations_cb)(diagnostic_context *, diagnostic_info *);
407
408 /* Optional callback for attempting to handle ICEs gracefully. */
409 void (*ice_handler_cb) (diagnostic_context *context);
410
411 /* Include files that diagnostic_report_current_module has already listed the
412 include path for. */
413 hash_set<location_t, false, location_hash> *includes_seen;
414
415 /* A bundle of hooks for providing data to the context about its client
416 e.g. version information, plugins, etc.
417 Used by SARIF output to give metadata about the client that's
418 producing diagnostics. */
419 diagnostic_client_data_hooks *m_client_data_hooks;
420 };
421
422 inline void
423 diagnostic_inhibit_notes (diagnostic_context * context)
424 {
425 context->inhibit_notes_p = true;
426 }
427
428
429 /* Client supplied function to announce a diagnostic. */
430 #define diagnostic_starter(DC) (DC)->begin_diagnostic
431
432 /* Client supplied function called after a diagnostic message is
433 displayed. */
434 #define diagnostic_finalizer(DC) (DC)->end_diagnostic
435
436 /* Extension hooks for client. */
437 #define diagnostic_context_auxiliary_data(DC) (DC)->x_data
438 #define diagnostic_info_auxiliary_data(DI) (DI)->x_data
439
440 /* Same as pp_format_decoder. Works on 'diagnostic_context *'. */
441 #define diagnostic_format_decoder(DC) ((DC)->printer->format_decoder)
442
443 /* Same as output_prefixing_rule. Works on 'diagnostic_context *'. */
444 #define diagnostic_prefixing_rule(DC) ((DC)->printer->wrapping.rule)
445
446 /* Raise SIGABRT on any diagnostic of severity DK_ERROR or higher. */
447 #define diagnostic_abort_on_error(DC) \
448 (DC)->abort_on_error = true
449
450 /* This diagnostic_context is used by front-ends that directly output
451 diagnostic messages without going through `error', `warning',
452 and similar functions. */
453 extern diagnostic_context *global_dc;
454
455 /* Returns whether the diagnostic framework has been intialized already and is
456 ready for use. */
457 #define diagnostic_ready_p() (global_dc->printer != NULL)
458
459 /* The total count of a KIND of diagnostics emitted so far. */
460 #define diagnostic_kind_count(DC, DK) (DC)->diagnostic_count[(int) (DK)]
461
462 /* The number of errors that have been issued so far. Ideally, these
463 would take a diagnostic_context as an argument. */
464 #define errorcount diagnostic_kind_count (global_dc, DK_ERROR)
465 /* Similarly, but for warnings. */
466 #define warningcount diagnostic_kind_count (global_dc, DK_WARNING)
467 /* Similarly, but for warnings promoted to errors. */
468 #define werrorcount diagnostic_kind_count (global_dc, DK_WERROR)
469 /* Similarly, but for sorrys. */
470 #define sorrycount diagnostic_kind_count (global_dc, DK_SORRY)
471
472 /* Returns nonzero if warnings should be emitted. */
473 #define diagnostic_report_warnings_p(DC, LOC) \
474 (!(DC)->dc_inhibit_warnings \
475 && !(in_system_header_at (LOC) && !(DC)->dc_warn_system_headers))
476
477 /* Override the option index to be used for reporting a
478 diagnostic. */
479
480 inline void
481 diagnostic_override_option_index (diagnostic_info *info, int optidx)
482 {
483 info->option_index = optidx;
484 }
485
486 /* Diagnostic related functions. */
487 extern void diagnostic_initialize (diagnostic_context *, int);
488 extern void diagnostic_color_init (diagnostic_context *, int value = -1);
489 extern void diagnostic_urls_init (diagnostic_context *, int value = -1);
490 extern void diagnostic_finish (diagnostic_context *);
491 extern void diagnostic_report_current_module (diagnostic_context *, location_t);
492 extern void diagnostic_show_locus (diagnostic_context *,
493 rich_location *richloc,
494 diagnostic_t diagnostic_kind);
495 extern void diagnostic_show_any_path (diagnostic_context *, diagnostic_info *);
496
497 /* Because we read source files a second time after the frontend did it the
498 first time, we need to know how the frontend handled things like character
499 set conversion and UTF-8 BOM stripping, in order to make everything
500 consistent. This function needs to be called by each frontend that requires
501 non-default behavior, to inform the diagnostics infrastructure how input is
502 to be processed. The default behavior is to do no conversion and not to
503 strip a UTF-8 BOM.
504
505 The callback should return the input charset to be used to convert the given
506 file's contents to UTF-8, or it should return NULL if no conversion is needed
507 for this file. SHOULD_SKIP_BOM only applies in case no conversion was
508 performed, and if true, it will cause a UTF-8 BOM to be skipped at the
509 beginning of the file. (In case a conversion was performed, the BOM is
510 rather skipped as part of the conversion process.) */
511
512 void diagnostic_initialize_input_context (diagnostic_context *context,
513 diagnostic_input_charset_callback ccb,
514 bool should_skip_bom);
515
516 /* Force diagnostics controlled by OPTIDX to be kind KIND. */
517 extern diagnostic_t diagnostic_classify_diagnostic (diagnostic_context *,
518 int /* optidx */,
519 diagnostic_t /* kind */,
520 location_t);
521 extern void diagnostic_push_diagnostics (diagnostic_context *, location_t);
522 extern void diagnostic_pop_diagnostics (diagnostic_context *, location_t);
523 extern bool diagnostic_report_diagnostic (diagnostic_context *,
524 diagnostic_info *);
525 #ifdef ATTRIBUTE_GCC_DIAG
526 extern void diagnostic_set_info (diagnostic_info *, const char *, va_list *,
527 rich_location *, diagnostic_t) ATTRIBUTE_GCC_DIAG(2,0);
528 extern void diagnostic_set_info_translated (diagnostic_info *, const char *,
529 va_list *, rich_location *,
530 diagnostic_t)
531 ATTRIBUTE_GCC_DIAG(2,0);
532 extern void diagnostic_append_note (diagnostic_context *, location_t,
533 const char *, ...) ATTRIBUTE_GCC_DIAG(3,4);
534 #endif
535 extern char *diagnostic_build_prefix (diagnostic_context *, const diagnostic_info *);
536 void default_diagnostic_starter (diagnostic_context *, diagnostic_info *);
537 void default_diagnostic_start_span_fn (diagnostic_context *,
538 expanded_location);
539 void default_diagnostic_finalizer (diagnostic_context *, diagnostic_info *,
540 diagnostic_t);
541 void diagnostic_set_caret_max_width (diagnostic_context *context, int value);
542 void diagnostic_action_after_output (diagnostic_context *, diagnostic_t);
543 void diagnostic_check_max_errors (diagnostic_context *, bool flush = false);
544
545 void diagnostic_file_cache_fini (void);
546
547 int get_terminal_width (void);
548
549 /* Return the location associated to this diagnostic. Parameter WHICH
550 specifies which location. By default, expand the first one. */
551
552 inline location_t
553 diagnostic_location (const diagnostic_info * diagnostic, int which = 0)
554 {
555 return diagnostic->message.get_location (which);
556 }
557
558 /* Return the number of locations to be printed in DIAGNOSTIC. */
559
560 inline unsigned int
561 diagnostic_num_locations (const diagnostic_info * diagnostic)
562 {
563 return diagnostic->message.m_richloc->get_num_locations ();
564 }
565
566 /* Expand the location of this diagnostic. Use this function for
567 consistency. Parameter WHICH specifies which location. By default,
568 expand the first one. */
569
570 inline expanded_location
571 diagnostic_expand_location (const diagnostic_info * diagnostic, int which = 0)
572 {
573 return diagnostic->richloc->get_expanded_location (which);
574 }
575
576 /* This is somehow the right-side margin of a caret line, that is, we
577 print at least these many characters after the position pointed at
578 by the caret. */
579 const int CARET_LINE_MARGIN = 10;
580
581 /* Return true if the two locations can be represented within the same
582 caret line. This is used to build a prefix and also to determine
583 whether to print one or two caret lines. */
584
585 inline bool
586 diagnostic_same_line (const diagnostic_context *context,
587 expanded_location s1, expanded_location s2)
588 {
589 return s2.column && s1.line == s2.line
590 && context->caret_max_width - CARET_LINE_MARGIN > abs (s1.column - s2.column);
591 }
592
593 extern const char *diagnostic_get_color_for_kind (diagnostic_t kind);
594 extern int diagnostic_converted_column (diagnostic_context *context,
595 expanded_location s);
596
597 /* Pure text formatting support functions. */
598 extern char *file_name_as_prefix (diagnostic_context *, const char *);
599
600 extern char *build_message_string (const char *, ...) ATTRIBUTE_PRINTF_1;
601
602 extern void diagnostic_output_format_init (diagnostic_context *,
603 const char *base_file_name,
604 enum diagnostics_output_format);
605 extern void diagnostic_output_format_init_json_stderr (diagnostic_context *context);
606 extern void diagnostic_output_format_init_json_file (diagnostic_context *context,
607 const char *base_file_name);
608 extern void diagnostic_output_format_init_sarif_stderr (diagnostic_context *context);
609 extern void diagnostic_output_format_init_sarif_file (diagnostic_context *context,
610 const char *base_file_name);
611
612 /* Compute the number of digits in the decimal representation of an integer. */
613 extern int num_digits (int);
614
615 extern json::value *json_from_expanded_location (diagnostic_context *context,
616 location_t loc);
617
618 extern bool warning_enabled_at (location_t, int);
619
620 extern char *get_cwe_url (int cwe);
621
622 #endif /* ! GCC_DIAGNOSTIC_H */