gcc/diagnostic.h

   1 /* Various declarations for language-independent diagnostics subroutines.
   2    Copyright (C) 2000-2021 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   /* Used to specify additional diagnostic output to be emitted after the
 344      rest of the diagnostic.  This is for implementing
 345      -fdiagnostics-parseable-fixits and GCC_EXTRA_DIAGNOSTIC_OUTPUT.  */
 346   enum diagnostics_extra_output_kind extra_output_kind;
 347
 348   /* What units to use when outputting the column number.  */
 349   enum diagnostics_column_unit column_unit;
 350
 351   /* The origin for the column number (1-based or 0-based typically).  */
 352   int column_origin;
 353
 354   /* The size of the tabstop for tab expansion.  */
 355   int tabstop;
 356
 357   /* How should non-ASCII/non-printable bytes be escaped when
 358      a diagnostic suggests escaping the source code on output.  */
 359   enum diagnostics_escape_format escape_format;
 360
 361   /* If non-NULL, an edit_context to which fix-it hints should be
 362      applied, for generating patches.  */
 363   edit_context *edit_context_ptr;
 364
 365   /* How many diagnostic_group instances are currently alive.  */
 366   int diagnostic_group_nesting_depth;
 367
 368   /* How many diagnostics have been emitted since the bottommost
 369      diagnostic_group was pushed.  */
 370   int diagnostic_group_emission_count;
 371
 372   /* Optional callbacks for handling diagnostic groups.  */
 373
 374   /* If non-NULL, this will be called immediately before the first
 375      time a diagnostic is emitted within a stack of groups.  */
 376   void (*begin_group_cb) (diagnostic_context * context);
 377
 378   /* If non-NULL, this will be called when a stack of groups is
 379      popped if any diagnostics were emitted within that group.  */
 380   void (*end_group_cb) (diagnostic_context * context);
 381
 382   /* Callback for final cleanup.  */
 383   void (*final_cb) (diagnostic_context *context);
 384
 385   /* Callback to set the locations of call sites along the inlining
 386      stack corresponding to a diagnostic location.  Needed to traverse
 387      the BLOCK_SUPERCONTEXT() chain hanging off the LOCATION_BLOCK()
 388      of a diagnostic's location.  */
 389   void (*set_locations_cb)(diagnostic_context *, diagnostic_info *);
 390 };
 391
 392 static inline void
 393 diagnostic_inhibit_notes (diagnostic_context * context)
 394 {
 395   context->inhibit_notes_p = true;
 396 }
 397
 398
 399 /* Client supplied function to announce a diagnostic.  */
 400 #define diagnostic_starter(DC) (DC)->begin_diagnostic
 401
 402 /* Client supplied function called after a diagnostic message is
 403    displayed.  */
 404 #define diagnostic_finalizer(DC) (DC)->end_diagnostic
 405
 406 /* Extension hooks for client.  */
 407 #define diagnostic_context_auxiliary_data(DC) (DC)->x_data
 408 #define diagnostic_info_auxiliary_data(DI) (DI)->x_data
 409
 410 /* Same as pp_format_decoder.  Works on 'diagnostic_context *'.  */
 411 #define diagnostic_format_decoder(DC) ((DC)->printer->format_decoder)
 412
 413 /* Same as output_prefixing_rule.  Works on 'diagnostic_context *'.  */
 414 #define diagnostic_prefixing_rule(DC) ((DC)->printer->wrapping.rule)
 415
 416 /* Raise SIGABRT on any diagnostic of severity DK_ERROR or higher.  */
 417 #define diagnostic_abort_on_error(DC) \
 418   (DC)->abort_on_error = true
 419
 420 /* This diagnostic_context is used by front-ends that directly output
 421    diagnostic messages without going through `error', `warning',
 422    and similar functions.  */
 423 extern diagnostic_context *global_dc;
 424
 425 /* Returns whether the diagnostic framework has been intialized already and is
 426    ready for use.  */
 427 #define diagnostic_ready_p() (global_dc->printer != NULL)
 428
 429 /* The total count of a KIND of diagnostics emitted so far.  */
 430 #define diagnostic_kind_count(DC, DK) (DC)->diagnostic_count[(int) (DK)]
 431
 432 /* The number of errors that have been issued so far.  Ideally, these
 433    would take a diagnostic_context as an argument.  */
 434 #define errorcount diagnostic_kind_count (global_dc, DK_ERROR)
 435 /* Similarly, but for warnings.  */
 436 #define warningcount diagnostic_kind_count (global_dc, DK_WARNING)
 437 /* Similarly, but for warnings promoted to errors.  */
 438 #define werrorcount diagnostic_kind_count (global_dc, DK_WERROR)
 439 /* Similarly, but for sorrys.  */
 440 #define sorrycount diagnostic_kind_count (global_dc, DK_SORRY)
 441
 442 /* Returns nonzero if warnings should be emitted.  */
 443 #define diagnostic_report_warnings_p(DC, LOC)                           \
 444   (!(DC)->dc_inhibit_warnings                                           \
 445    && !(in_system_header_at (LOC) && !(DC)->dc_warn_system_headers))
 446
 447 /* Override the option index to be used for reporting a
 448    diagnostic.  */
 449
 450 static inline void
 451 diagnostic_override_option_index (diagnostic_info *info, int optidx)
 452 {
 453   info->option_index = optidx;
 454 }
 455
 456 /* Diagnostic related functions.  */
 457 extern void diagnostic_initialize (diagnostic_context *, int);
 458 extern void diagnostic_color_init (diagnostic_context *, int value = -1);
 459 extern void diagnostic_urls_init (diagnostic_context *, int value = -1);
 460 extern void diagnostic_finish (diagnostic_context *);
 461 extern void diagnostic_report_current_module (diagnostic_context *, location_t);
 462 extern void diagnostic_show_locus (diagnostic_context *,
 463                                    rich_location *richloc,
 464                                    diagnostic_t diagnostic_kind);
 465 extern void diagnostic_show_any_path (diagnostic_context *, diagnostic_info *);
 466
 467 /* Because we read source files a second time after the frontend did it the
 468    first time, we need to know how the frontend handled things like character
 469    set conversion and UTF-8 BOM stripping, in order to make everything
 470    consistent.  This function needs to be called by each frontend that requires
 471    non-default behavior, to inform the diagnostics infrastructure how input is
 472    to be processed.  The default behavior is to do no conversion and not to
 473    strip a UTF-8 BOM.
 474
 475    The callback should return the input charset to be used to convert the given
 476    file's contents to UTF-8, or it should return NULL if no conversion is needed
 477    for this file.  SHOULD_SKIP_BOM only applies in case no conversion was
 478    performed, and if true, it will cause a UTF-8 BOM to be skipped at the
 479    beginning of the file.  (In case a conversion was performed, the BOM is
 480    rather skipped as part of the conversion process.)  */
 481
 482 void diagnostic_initialize_input_context (diagnostic_context *context,
 483                                           diagnostic_input_charset_callback ccb,
 484                                           bool should_skip_bom);
 485
 486 /* Force diagnostics controlled by OPTIDX to be kind KIND.  */
 487 extern diagnostic_t diagnostic_classify_diagnostic (diagnostic_context *,
 488                                                     int /* optidx */,
 489                                                     diagnostic_t /* kind */,
 490                                                     location_t);
 491 extern void diagnostic_push_diagnostics (diagnostic_context *, location_t);
 492 extern void diagnostic_pop_diagnostics (diagnostic_context *, location_t);
 493 extern bool diagnostic_report_diagnostic (diagnostic_context *,
 494                                           diagnostic_info *);
 495 #ifdef ATTRIBUTE_GCC_DIAG
 496 extern void diagnostic_set_info (diagnostic_info *, const char *, va_list *,
 497                                  rich_location *, diagnostic_t) ATTRIBUTE_GCC_DIAG(2,0);
 498 extern void diagnostic_set_info_translated (diagnostic_info *, const char *,
 499                                             va_list *, rich_location *,
 500                                             diagnostic_t)
 501      ATTRIBUTE_GCC_DIAG(2,0);
 502 extern void diagnostic_append_note (diagnostic_context *, location_t,
 503                                     const char *, ...) ATTRIBUTE_GCC_DIAG(3,4);
 504 #endif
 505 extern char *diagnostic_build_prefix (diagnostic_context *, const diagnostic_info *);
 506 void default_diagnostic_starter (diagnostic_context *, diagnostic_info *);
 507 void default_diagnostic_start_span_fn (diagnostic_context *,
 508                                        expanded_location);
 509 void default_diagnostic_finalizer (diagnostic_context *, diagnostic_info *,
 510                                    diagnostic_t);
 511 void diagnostic_set_caret_max_width (diagnostic_context *context, int value);
 512 void diagnostic_action_after_output (diagnostic_context *, diagnostic_t);
 513 void diagnostic_check_max_errors (diagnostic_context *, bool flush = false);
 514
 515 void diagnostic_file_cache_fini (void);
 516
 517 int get_terminal_width (void);
 518
 519 /* Return the location associated to this diagnostic. Parameter WHICH
 520    specifies which location. By default, expand the first one.  */
 521
 522 static inline location_t
 523 diagnostic_location (const diagnostic_info * diagnostic, int which = 0)
 524 {
 525   return diagnostic->message.get_location (which);
 526 }
 527
 528 /* Return the number of locations to be printed in DIAGNOSTIC.  */
 529
 530 static inline unsigned int
 531 diagnostic_num_locations (const diagnostic_info * diagnostic)
 532 {
 533   return diagnostic->message.m_richloc->get_num_locations ();
 534 }
 535
 536 /* Expand the location of this diagnostic. Use this function for
 537    consistency.  Parameter WHICH specifies which location. By default,
 538    expand the first one.  */
 539
 540 static inline expanded_location
 541 diagnostic_expand_location (const diagnostic_info * diagnostic, int which = 0)
 542 {
 543   return diagnostic->richloc->get_expanded_location (which);
 544 }
 545
 546 /* This is somehow the right-side margin of a caret line, that is, we
 547    print at least these many characters after the position pointed at
 548    by the caret.  */
 549 const int CARET_LINE_MARGIN = 10;
 550
 551 /* Return true if the two locations can be represented within the same
 552    caret line.  This is used to build a prefix and also to determine
 553    whether to print one or two caret lines.  */
 554
 555 static inline bool
 556 diagnostic_same_line (const diagnostic_context *context,
 557                        expanded_location s1, expanded_location s2)
 558 {
 559   return s2.column && s1.line == s2.line
 560     && context->caret_max_width - CARET_LINE_MARGIN > abs (s1.column - s2.column);
 561 }
 562
 563 extern const char *diagnostic_get_color_for_kind (diagnostic_t kind);
 564 extern int diagnostic_converted_column (diagnostic_context *context,
 565                                         expanded_location s);
 566
 567 /* Pure text formatting support functions.  */
 568 extern char *file_name_as_prefix (diagnostic_context *, const char *);
 569
 570 extern char *build_message_string (const char *, ...) ATTRIBUTE_PRINTF_1;
 571
 572 extern void diagnostic_output_format_init (diagnostic_context *,
 573                                            enum diagnostics_output_format);
 574
 575 /* Compute the number of digits in the decimal representation of an integer.  */
 576 extern int num_digits (int);
 577
 578 extern json::value *json_from_expanded_location (diagnostic_context *context,
 579                                                  location_t loc);
 580
 581 extern bool warning_enabled_at (location_t, int);
 582
 583 #endif /* ! GCC_DIAGNOSTIC_H */