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