gcc/diagnostic.h

   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 {
 104   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
 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
 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
 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
 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 */