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