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