gcc/diagnostic.h

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