clang-tools-extra/docs/pp-trace.rst

   1 .. index:: pp-trace
   2
   3 ==================================
   4 pp-trace User's Manual
   5 ==================================
   6
   7 .. toctree::
   8    :hidden:
   9
  10 :program:`pp-trace` is a standalone tool that traces preprocessor
  11 activity. It's also used as a test of Clang's PPCallbacks interface.
  12 It runs a given source file through the Clang preprocessor, displaying
  13 selected information from callback functions overridden in a
  14 `PPCallbacks <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html>`_
  15 derivation. The output is in a high-level YAML format, described in
  16 :ref:`OutputFormat`.
  17
  18 .. _Usage:
  19
  20 pp-trace Usage
  21 ==============
  22
  23 Command Line Format
  24 -------------------
  25
  26 ``pp-trace [<pp-trace-options>] <source-file> [-- <front-end-options>]``
  27
  28 ``<pp-trace-options>`` is a place-holder for options
  29 specific to pp-trace, which are described below in
  30 :ref:`CommandLineOptions`.
  31
  32 ``<source-file>`` specifies the source file to run through the preprocessor.
  33
  34 ``<front-end-options>`` is a place-holder for regular
  35 `Clang Compiler Options <https://clang.llvm.org/docs/UsersManual.html#command-line-options>`_,
  36 which must follow the <source-file>.
  37
  38 .. _CommandLineOptions:
  39
  40 Command Line Options
  41 --------------------
  42
  43 .. option:: -callbacks <comma-separated-globs>
  44
  45   This option specifies a comma-separated list of globs describing the list of
  46   callbacks that should be traced. Globs are processed in order of appearance.
  47   Positive globs add matched callbacks to the set, negative globs (those with
  48   the '-' prefix) remove callacks from the set.
  49
  50   * FileChanged
  51   * FileSkipped
  52   * InclusionDirective
  53   * moduleImport
  54   * EndOfMainFile
  55   * Ident
  56   * PragmaDirective
  57   * PragmaComment
  58   * PragmaDetectMismatch
  59   * PragmaDebug
  60   * PragmaMessage
  61   * PragmaDiagnosticPush
  62   * PragmaDiagnosticPop
  63   * PragmaDiagnostic
  64   * PragmaOpenCLExtension
  65   * PragmaWarning
  66   * PragmaWarningPush
  67   * PragmaWarningPop
  68   * MacroExpands
  69   * MacroDefined
  70   * MacroUndefined
  71   * Defined
  72   * SourceRangeSkipped
  73   * If
  74   * Elif
  75   * Ifdef
  76   * Ifndef
  77   * Else
  78   * Endif
  79
  80 .. option:: -output <output-file>
  81
  82   By default, pp-trace outputs the trace information to stdout. Use this
  83   option to output the trace information to a file.
  84
  85 .. _OutputFormat:
  86
  87 pp-trace Output Format
  88 ======================
  89
  90 The pp-trace output is formatted as YAML. See https://yaml.org/ for general
  91 YAML information. It's arranged as a sequence of information about the
  92 callback call, including the callback name and argument information, for
  93 example:::
  94
  95   ---
  96   - Callback: Name
  97     Argument1: Value1
  98     Argument2: Value2
  99   (etc.)
 100   ...
 101
 102 With real data:::
 103
 104   ---
 105   - Callback: FileChanged
 106     Loc: "c:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"
 107     Reason: EnterFile
 108     FileType: C_User
 109     PrevFID: (invalid)
 110     (etc.)
 111   - Callback: FileChanged
 112     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:5:1"
 113     Reason: ExitFile
 114     FileType: C_User
 115     PrevFID: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/Input/Level1B.h"
 116   - Callback: EndOfMainFile
 117   ...
 118
 119 In all but one case (MacroDirective) the "Argument" scalars have the same
 120 name as the argument in the corresponding PPCallbacks callback function.
 121
 122 Callback Details
 123 ----------------
 124
 125 The following sections describe the purpose and output format for each callback.
 126
 127 Click on the callback name in the section heading to see the Doxygen
 128 documentation for the callback.
 129
 130 The argument descriptions table describes the callback argument information
 131 displayed.
 132
 133 The Argument Name field in most (but not all) cases is the same name as the
 134 callback function parameter.
 135
 136 The Argument Value Syntax field describes the values that will be displayed
 137 for the argument value. It uses an ad hoc representation that mixes literal
 138 and symbolic representations. Enumeration member symbols are shown as the
 139 actual enum member in a (member1|member2|...) form. A name in parentheses
 140 can either represent a place holder for the described value, or confusingly,
 141 it might be a literal, such as (null), for a null pointer.
 142 Locations are shown as quoted only to avoid confusing the documentation generator.
 143
 144 The Clang C++ Type field is the type from the callback function declaration.
 145
 146 The description describes the argument or what is displayed for it.
 147
 148 Note that in some cases, such as when a structure pointer is an argument
 149 value, only some key member or members are shown to represent the value,
 150 instead of trying to display all members of the structure.
 151
 152 `FileChanged <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a7cc8cfaf34114fc65e92af621cd6464e>`_ Callback
 153 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 154
 155 FileChanged is called when the preprocessor enters or exits a file, both the
 156 top level file being compiled, as well as any #include directives. It will
 157 also be called as a result of a system header pragma or in internal renaming
 158 of a file.
 159
 160 Argument descriptions:
 161
 162 ==============   ==================================================   ============================== ==============================
 163 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 164 ==============   ==================================================   ============================== ==============================
 165 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 166 Reason           (EnterFile|ExitFile|SystemHeaderPragma|RenameFile)   PPCallbacks::FileChangeReason  Reason for change.
 167 FileType         (C_User|C_System|C_ExternCSystem)                    SrcMgr::CharacteristicKind     Include type.
 168 PrevFID          ((file)|(invalid))                                   FileID                         Previous file, if any.
 169 ==============   ==================================================   ============================== ==============================
 170
 171 Example:::
 172
 173   - Callback: FileChanged
 174     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"
 175     Reason: EnterFile
 176     FileType: C_User
 177     PrevFID: (invalid)
 178
 179 `FileSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab5b338a0670188eb05fa7685bbfb5128>`_ Callback
 180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 181
 182 FileSkipped is called when a source file is skipped as the result of header
 183 guard optimization.
 184
 185 Argument descriptions:
 186
 187 ==============   ==================================================   ============================== ========================================================
 188 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 189 ==============   ==================================================   ============================== ========================================================
 190 ParentFile       ("(file)" or (null))                                 const FileEntry                The file that #included the skipped file.
 191 FilenameTok      (token)                                              const Token                    The token in ParentFile that indicates the skipped file.
 192 FileType         (C_User|C_System|C_ExternCSystem)                    SrcMgr::CharacteristicKind     The file type.
 193 ==============   ==================================================   ============================== ========================================================
 194
 195 Example:::
 196
 197   - Callback: FileSkipped
 198     ParentFile: "/path/filename.h"
 199     FilenameTok: "filename.h"
 200     FileType: C_User
 201
 202 `InclusionDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a557d9738c329793513a6f57d6b60de52>`_ Callback
 203 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 204
 205 InclusionDirective is called when an inclusion directive of any kind (#include</code>, #import</code>, etc.) has been processed, regardless of whether the inclusion will actually result in an inclusion.
 206
 207 Argument descriptions:
 208
 209 ==============   ==================================================   ============================== ============================================================================================================
 210 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 211 ==============   ==================================================   ============================== ============================================================================================================
 212 HashLoc          "(file):(line):(col)"                                SourceLocation                 The location of the '#' that starts the inclusion directive.
 213 IncludeTok       (token)                                              const Token                    The token that indicates the kind of inclusion directive, e.g., 'include' or 'import'.
 214 FileName         "(file)"                                             StringRef                      The name of the file being included, as written in the source code.
 215 IsAngled         (true|false)                                         bool                           Whether the file name was enclosed in angle brackets; otherwise, it was enclosed in quotes.
 216 FilenameRange    "(file)"                                             CharSourceRange                The character range of the quotes or angle brackets for the written file name.
 217 File             "(file)"                                             const FileEntry                The actual file that may be included by this inclusion directive.
 218 SearchPath       "(path)"                                             StringRef                      Contains the search path which was used to find the file in the file system.
 219 RelativePath     "(path)"                                             StringRef                      The path relative to SearchPath, at which the include file was found.
 220 Imported         ((module name)|(null))                               const Module                   The module, whenever an inclusion directive was automatically turned into a module import or null otherwise.
 221 ==============   ==================================================   ============================== ============================================================================================================
 222
 223 Example:::
 224
 225   - Callback: InclusionDirective
 226     HashLoc: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:4:1"
 227     IncludeTok: include
 228     FileName: "Input/Level1B.h"
 229     IsAngled: false
 230     FilenameRange: "Input/Level1B.h"
 231     File: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/Input/Level1B.h"
 232     SearchPath: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace"
 233     RelativePath: "Input/Level1B.h"
 234     Imported: (null)
 235
 236 `moduleImport <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#af32dcf1b8b7c179c7fcd3e24e89830fe>`_ Callback
 237 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 238
 239 moduleImport is called when there was an explicit module-import syntax.
 240
 241 Argument descriptions:
 242
 243 ==============   ==================================================   ============================== ===========================================================
 244 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 245 ==============   ==================================================   ============================== ===========================================================
 246 ImportLoc        "(file):(line):(col)"                                SourceLocation                 The location of import directive token.
 247 Path             "(path)"                                             ModuleIdPath                   The identifiers (and their locations) of the module "path".
 248 Imported         ((module name)|(null))                               const Module                   The imported module; can be null if importing failed.
 249 ==============   ==================================================   ============================== ===========================================================
 250
 251 Example:::
 252
 253   - Callback: moduleImport
 254     ImportLoc: "d:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:2"
 255     Path: [{Name: Level1B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:9"}, {Name: Level2B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:17"}]
 256     Imported: Level2B
 257
 258 `EndOfMainFile <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a63e170d069e99bc1c9c7ea0f3bed8bcc>`_ Callback
 259 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 260
 261 EndOfMainFile is called when the end of the main file is reached.
 262
 263 Argument descriptions:
 264
 265 ==============   ==================================================   ============================== ======================
 266 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 267 ==============   ==================================================   ============================== ======================
 268 (no arguments)
 269 ==============   ==================================================   ============================== ======================
 270
 271 Example:::
 272
 273   - Callback: EndOfMainFile
 274
 275 `Ident <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3683f1d1fa513e9b6193d446a5cc2b66>`_ Callback
 276 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 277
 278 Ident is called when a #ident or #sccs directive is read.
 279
 280 Argument descriptions:
 281
 282 ==============   ==================================================   ============================== ==============================
 283 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 284 ==============   ==================================================   ============================== ==============================
 285 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 286 str              (name)                                               const std::string              The text of the directive.
 287 ==============   ==================================================   ============================== ==============================
 288
 289 Example:::
 290
 291   - Callback: Ident
 292     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-ident.cpp:3:1"
 293     str: "$Id$"
 294
 295 `PragmaDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0a2d7a72c62184b3cbde31fb62c6f2f7>`_ Callback
 296 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 297
 298 PragmaDirective is called when start reading any pragma directive.
 299
 300 Argument descriptions:
 301
 302 ==============   ==================================================   ============================== =================================
 303 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 304 ==============   ==================================================   ============================== =================================
 305 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 306 Introducer       (PIK_HashPragma|PIK__Pragma|PIK___pragma)            PragmaIntroducerKind           The type of the pragma directive.
 307 ==============   ==================================================   ============================== =================================
 308
 309 Example:::
 310
 311   - Callback: PragmaDirective
 312     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 313     Introducer: PIK_HashPragma
 314
 315 `PragmaComment <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ace0d940fc2c12ab76441466aab58dc37>`_ Callback
 316 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 317
 318 PragmaComment is called when a #pragma comment directive is read.
 319
 320 Argument descriptions:
 321
 322 ==============   ==================================================   ============================== ==============================
 323 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 324 ==============   ==================================================   ============================== ==============================
 325 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 326 Kind             ((name)|(null))                                      const IdentifierInfo           The comment kind symbol.
 327 Str              (message directive)                                  const std::string              The comment message directive.
 328 ==============   ==================================================   ============================== ==============================
 329
 330 Example:::
 331
 332   - Callback: PragmaComment
 333     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 334     Kind: library
 335     Str: kernel32.lib
 336
 337 `PragmaDetectMismatch <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab11158c9149fb8ad8af1903f4a6cd65d>`_ Callback
 338 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 339
 340 PragmaDetectMismatch is called when a #pragma detect_mismatch directive is read.
 341
 342 Argument descriptions:
 343
 344 ==============   ==================================================   ============================== ==============================
 345 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 346 ==============   ==================================================   ============================== ==============================
 347 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 348 Name             "(name)"                                             const std::string              The name.
 349 Value            (string)                                             const std::string              The value.
 350 ==============   ==================================================   ============================== ==============================
 351
 352 Example:::
 353
 354   - Callback: PragmaDetectMismatch
 355     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 356     Name: name
 357     Value: value
 358
 359 `PragmaDebug <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a57cdccb6dcc07e926513ac3d5b121466>`_ Callback
 360 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 361
 362 PragmaDebug is called when a #pragma clang __debug directive is read.
 363
 364 Argument descriptions:
 365
 366 ==============   ==================================================   ============================== ================================
 367 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 368 ==============   ==================================================   ============================== ================================
 369 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 370 DebugType        (string)                                             StringRef                      Indicates type of debug message.
 371 ==============   ==================================================   ============================== ================================
 372
 373 Example:::
 374
 375   - Callback: PragmaDebug
 376     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 377     DebugType: warning
 378
 379 `PragmaMessage <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abb42935d9a9fd8e2c4f51cfdc4ea2ae1>`_ Callback
 380 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 381
 382 PragmaMessage is called when a #pragma message directive is read.
 383
 384 Argument descriptions:
 385
 386 ==============   ==================================================   ============================== =======================================
 387 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 388 ==============   ==================================================   ============================== =======================================
 389 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 390 Namespace        (name)                                               StringRef                      The namespace of the message directive.
 391 Kind             (PMK_Message|PMK_Warning|PMK_Error)                  PPCallbacks::PragmaMessageKind The type of the message directive.
 392 Str              (string)                                             StringRef                      The text of the message directive.
 393 ==============   ==================================================   ============================== =======================================
 394
 395 Example:::
 396
 397   - Callback: PragmaMessage
 398     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 399     Namespace: "GCC"
 400     Kind: PMK_Message
 401     Str: The message text.
 402
 403 `PragmaDiagnosticPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0f3ff19762baa38fe6c5c58022d32979>`_ Callback
 404 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 405
 406 PragmaDiagnosticPush is called when a #pragma gcc diagnostic push directive is read.
 407
 408 Argument descriptions:
 409
 410 ==============   ==================================================   ============================== ==============================
 411 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 412 ==============   ==================================================   ============================== ==============================
 413 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 414 Namespace        (name)                                               StringRef                      Namespace name.
 415 ==============   ==================================================   ============================== ==============================
 416
 417 Example:::
 418
 419   - Callback: PragmaDiagnosticPush
 420     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 421     Namespace: "GCC"
 422
 423 `PragmaDiagnosticPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac94d789873122221fba8d76f6c5ea45e>`_ Callback
 424 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 425
 426 PragmaDiagnosticPop is called when a #pragma gcc diagnostic pop directive is read.
 427
 428 Argument descriptions:
 429
 430 ==============   ==================================================   ============================== ==============================
 431 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 432 ==============   ==================================================   ============================== ==============================
 433 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 434 Namespace        (name)                                               StringRef                      Namespace name.
 435 ==============   ==================================================   ============================== ==============================
 436
 437 Example:::
 438
 439   - Callback: PragmaDiagnosticPop
 440     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 441     Namespace: "GCC"
 442
 443 `PragmaDiagnostic <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afe7938f38a83cb7b4b25a13edfdd7bdd>`_ Callback
 444 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 445
 446 PragmaDiagnostic is called when a #pragma gcc diagnostic directive is read.
 447
 448 Argument descriptions:
 449
 450 ==============   ==================================================   ============================== ==============================
 451 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 452 ==============   ==================================================   ============================== ==============================
 453 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 454 Namespace        (name)                                               StringRef                      Namespace name.
 455 mapping          (0|MAP_IGNORE|MAP_WARNING|MAP_ERROR|MAP_FATAL)       diag::Severity                 Mapping type.
 456 Str              (string)                                             StringRef                      Warning/error name.
 457 ==============   ==================================================   ============================== ==============================
 458
 459 Example:::
 460
 461   - Callback: PragmaDiagnostic
 462     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 463     Namespace: "GCC"
 464     mapping: MAP_WARNING
 465     Str: WarningName
 466
 467 `PragmaOpenCLExtension <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a92a20a21fadbab4e2c788f4e27fe07e7>`_ Callback
 468 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 469
 470 PragmaOpenCLExtension is called when OpenCL extension is either disabled or enabled with a pragma.
 471
 472 Argument descriptions:
 473
 474 ==============   ==================================================   ============================== ==========================
 475 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 476 ==============   ==================================================   ============================== ==========================
 477 NameLoc          "(file):(line):(col)"                                SourceLocation                 The location of the name.
 478 Name             (name)                                               const IdentifierInfo           Name symbol.
 479 StateLoc         "(file):(line):(col)"                                SourceLocation                 The location of the state.
 480 State            (1|0)                                                unsigned                       Enabled/disabled state.
 481 ==============   ==================================================   ============================== ==========================
 482
 483 Example:::
 484
 485   - Callback: PragmaOpenCLExtension
 486     NameLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:10"
 487     Name: Name
 488     StateLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:18"
 489     State: 1
 490
 491 `PragmaWarning <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#aa17169d25fa1cf0a6992fc944d1d8730>`_ Callback
 492 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 493
 494 PragmaWarning is called when a #pragma warning directive is read.
 495
 496 Argument descriptions:
 497
 498 ==============   ==================================================   ============================== ==============================
 499 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 500 ==============   ==================================================   ============================== ==============================
 501 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 502 WarningSpec      (string)                                             StringRef                      The warning specifier.
 503 Ids              [(number)[, ...]]                                    ArrayRef<int>                  The warning numbers.
 504 ==============   ==================================================   ============================== ==============================
 505
 506 Example:::
 507
 508   - Callback: PragmaWarning
 509     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 510     WarningSpec: disable
 511     Ids: 1,2,3
 512
 513 `PragmaWarningPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ae5626ef70502687a859f323a809ed0b6>`_ Callback
 514 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 515
 516 PragmaWarningPush is called when a #pragma warning(push) directive is read.
 517
 518 Argument descriptions:
 519
 520 ==============   ==================================================   ============================== ==============================
 521 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 522 ==============   ==================================================   ============================== ==============================
 523 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 524 Level            (number)                                             int                            Warning level.
 525 ==============   ==================================================   ============================== ==============================
 526
 527 Example:::
 528
 529   - Callback: PragmaWarningPush
 530     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 531     Level: 1
 532
 533 `PragmaWarningPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac98d502af8811b8a6e7342d7cd2b3b95>`_ Callback
 534 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 535
 536 PragmaWarningPop is called when a #pragma warning(pop) directive is read.
 537
 538 Argument descriptions:
 539
 540 ==============   ==================================================   ============================== ==============================
 541 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 542 ==============   ==================================================   ============================== ==============================
 543 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 544 ==============   ==================================================   ============================== ==============================
 545
 546 Example:::
 547
 548   - Callback: PragmaWarningPop
 549     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
 550
 551 `MacroExpands <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a9bc725209d3a071ea649144ab996d515>`_ Callback
 552 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 553
 554 MacroExpands is called when ::HandleMacroExpandedIdentifier when a macro invocation is found.
 555
 556 Argument descriptions:
 557
 558 ==============   ==================================================   ============================== ======================================================================================================
 559 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 560 ==============   ==================================================   ============================== ======================================================================================================
 561 MacroNameTok     (token)                                              const Token                    The macro name token.
 562 MacroDirective   (MD_Define|MD_Undefine|MD_Visibility)                const MacroDirective           The kind of macro directive from the MacroDirective structure.
 563 Range            ["(file):(line):(col)", "(file):(line):(col)"]       SourceRange                    The source range for the expansion.
 564 Args             [(name)|(number)|<(token name)>[, ...]]              const MacroArgs                The argument tokens. Names and numbers are literal, everything else is of the form '<' tokenName '>'.
 565 ==============   ==================================================   ============================== ======================================================================================================
 566
 567 Example:::
 568
 569   - Callback: MacroExpands
 570     MacroNameTok: X_IMPL
 571     MacroDirective: MD_Define
 572     Range: [(nonfile), (nonfile)]
 573     Args: [a <plus> y, b]
 574
 575 `MacroDefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a8448fc9f96f22ad1b93ff393cffc5a76>`_ Callback
 576 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 577
 578 MacroDefined is called when a macro definition is seen.
 579
 580 Argument descriptions:
 581
 582 ==============   ==================================================   ============================== ==============================================================
 583 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 584 ==============   ==================================================   ============================== ==============================================================
 585 MacroNameTok     (token)                                              const Token                    The macro name token.
 586 MacroDirective   (MD_Define|MD_Undefine|MD_Visibility)                const MacroDirective           The kind of macro directive from the MacroDirective structure.
 587 ==============   ==================================================   ============================== ==============================================================
 588
 589 Example:::
 590
 591   - Callback: MacroDefined
 592     MacroNameTok: X_IMPL
 593     MacroDirective: MD_Define
 594
 595 `MacroUndefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#acb80fc6171a839db8e290945bf2c9d7a>`_ Callback
 596 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 597
 598 MacroUndefined is called when a macro #undef is seen.
 599
 600 Argument descriptions:
 601
 602 ==============   ==================================================   ============================== ==============================================================
 603 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 604 ==============   ==================================================   ============================== ==============================================================
 605 MacroNameTok     (token)                                              const Token                    The macro name token.
 606 MacroDirective   (MD_Define|MD_Undefine|MD_Visibility)                const MacroDirective           The kind of macro directive from the MacroDirective structure.
 607 ==============   ==================================================   ============================== ==============================================================
 608
 609 Example:::
 610
 611   - Callback: MacroUndefined
 612     MacroNameTok: X_IMPL
 613     MacroDirective: MD_Define
 614
 615 `Defined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3cc2a644533d0e4088a13d2baf90db94>`_ Callback
 616 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 617
 618 Defined is called when the 'defined' operator is seen.
 619
 620 Argument descriptions:
 621
 622 ==============   ==================================================   ============================== ==============================================================
 623 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 624 ==============   ==================================================   ============================== ==============================================================
 625 MacroNameTok     (token)                                              const Token                    The macro name token.
 626 MacroDirective   (MD_Define|MD_Undefine|MD_Visibility)                const MacroDirective           The kind of macro directive from the MacroDirective structure.
 627 Range            ["(file):(line):(col)", "(file):(line):(col)"]       SourceRange                    The source range for the directive.
 628 ==============   ==================================================   ============================== ==============================================================
 629
 630 Example:::
 631
 632   - Callback: Defined
 633     MacroNameTok: MACRO
 634     MacroDirective: (null)
 635     Range: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:5", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:19"]
 636
 637 `SourceRangeSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abdb4ebe11610f079ac33515965794b46>`_ Callback
 638 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 639
 640 SourceRangeSkipped is called when a source range is skipped.
 641
 642 Argument descriptions:
 643
 644 ==============   ==================================================   ============================== =========================
 645 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 646 ==============   ==================================================   ============================== =========================
 647 Range            ["(file):(line):(col)", "(file):(line):(col)"]       SourceRange                    The source range skipped.
 648 ==============   ==================================================   ============================== =========================
 649
 650 Example:::
 651
 652   - Callback: SourceRangeSkipped
 653     Range: [":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2", ":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:2"]
 654
 655 `If <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a645edcb0d6becbc6f256f02fd1287778>`_ Callback
 656 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 657
 658 If is called when an #if is seen.
 659
 660 Argument descriptions:
 661
 662 ==============   ==================================================   ============================== ===================================
 663 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 664 ==============   ==================================================   ============================== ===================================
 665 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 666 ConditionRange   ["(file):(line):(col)", "(file):(line):(col)"]       SourceRange                    The source range for the condition.
 667 ConditionValue   (true|false)                                         bool                           The condition value.
 668 ==============   ==================================================   ============================== ===================================
 669
 670 Example:::
 671
 672   - Callback: If
 673     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
 674     ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:1"]
 675     ConditionValue: false
 676
 677 `Elif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a180c9e106a28d60a6112e16b1bb8302a>`_ Callback
 678 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 679
 680 Elif is called when an #elif is seen.
 681
 682 Argument descriptions:
 683
 684 ==============   ==================================================   ============================== ===================================
 685 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 686 ==============   ==================================================   ============================== ===================================
 687 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 688 ConditionRange   ["(file):(line):(col)", "(file):(line):(col)"]       SourceRange                    The source range for the condition.
 689 ConditionValue   (true|false)                                         bool                           The condition value.
 690 IfLoc            "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 691 ==============   ==================================================   ============================== ===================================
 692
 693 Example:::
 694
 695   - Callback: Elif
 696     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
 697     ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:11:1"]
 698     ConditionValue: false
 699     IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
 700
 701 `Ifdef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0ce79575dda307784fd51a6dd4eec33d>`_ Callback
 702 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 703
 704 Ifdef is called when an #ifdef is seen.
 705
 706 Argument descriptions:
 707
 708 ==============   ==================================================   ============================== ==============================================================
 709 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 710 ==============   ==================================================   ============================== ==============================================================
 711 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 712 MacroNameTok     (token)                                              const Token                    The macro name token.
 713 MacroDirective   (MD_Define|MD_Undefine|MD_Visibility)                const MacroDirective           The kind of macro directive from the MacroDirective structure.
 714 ==============   ==================================================   ============================== ==============================================================
 715
 716 Example:::
 717
 718   - Callback: Ifdef
 719     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"
 720     MacroNameTok: MACRO
 721     MacroDirective: MD_Define
 722
 723 `Ifndef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a767af69f1cdcc4cd880fa2ebf77ad3ad>`_ Callback
 724 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 725
 726 Ifndef is called when an #ifndef is seen.
 727
 728 Argument descriptions:
 729
 730 ==============   ==================================================   ============================== ==============================================================
 731 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 732 ==============   ==================================================   ============================== ==============================================================
 733 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the directive.
 734 MacroNameTok     (token)                                              const Token                    The macro name token.
 735 MacroDirective   (MD_Define|MD_Undefine|MD_Visibility)                const MacroDirective           The kind of macro directive from the MacroDirective structure.
 736 ==============   ==================================================   ============================== ==============================================================
 737
 738 Example:::
 739
 740   - Callback: Ifndef
 741     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"
 742     MacroNameTok: MACRO
 743     MacroDirective: MD_Define
 744
 745 `Else <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ad57f91b6d9c3cbcca326a2bfb49e0314>`_ Callback
 746 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 747
 748 Else is called when an #else is seen.
 749
 750 Argument descriptions:
 751
 752 ==============   ==================================================   ============================== ===================================
 753 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 754 ==============   ==================================================   ============================== ===================================
 755 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the else directive.
 756 IfLoc            "(file):(line):(col)"                                SourceLocation                 The location of the if directive.
 757 ==============   ==================================================   ============================== ===================================
 758
 759 Example:::
 760
 761   - Callback: Else
 762     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
 763     IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
 764
 765 `Endif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afc62ca1401125f516d58b1629a2093ce>`_ Callback
 766 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 767
 768 Endif is called when an #endif is seen.
 769
 770 Argument descriptions:
 771
 772 ==============   ==================================================   ============================== ====================================
 773 Argument Name    Argument Value Syntax                                Clang C++ Type                 Description
 774 ==============   ==================================================   ============================== ====================================
 775 Loc              "(file):(line):(col)"                                SourceLocation                 The location of the endif directive.
 776 IfLoc            "(file):(line):(col)"                                SourceLocation                 The location of the if directive.
 777 ==============   ==================================================   ============================== ====================================
 778
 779 Example:::
 780
 781   - Callback: Endif
 782     Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
 783     IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
 784
 785 Building pp-trace
 786 =================
 787
 788 To build from source:
 789
 790 1. Read `Getting Started with the LLVM System`_ and `Clang Tools
 791    Documentation`_ for information on getting sources for LLVM, Clang, and
 792    Clang Extra Tools.
 793
 794 2. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give
 795    directions for how to build. With sources all checked out into the
 796    right place the LLVM build will build Clang Extra Tools and their
 797    dependencies automatically.
 798
 799    * If using CMake, you can also use the ``pp-trace`` target to build
 800      just the pp-trace tool and its dependencies.
 801
 802 .. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html
 803 .. _Building LLVM with CMake: https://llvm.org/docs/CMake.html
 804 .. _Clang Tools Documentation: https://clang.llvm.org/docs/ClangTools.html