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