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, 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 87pp-trace Output Format 88====================== 89 90The pp-trace output is formatted as YAML. See https://yaml.org/ for general 91YAML information. It's arranged as a sequence of information about the 92callback call, including the callback name and argument information, for 93example::: 94 95 --- 96 - Callback: Name 97 Argument1: Value1 98 Argument2: Value2 99 (etc.) 100 ... 101 102With 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 119In all but one case (MacroDirective) the "Argument" scalars have the same 120name as the argument in the corresponding PPCallbacks callback function. 121 122Callback Details 123---------------- 124 125The following sections describe the purpose and output format for each callback. 126 127Click on the callback name in the section heading to see the Doxygen 128documentation for the callback. 129 130The argument descriptions table describes the callback argument information 131displayed. 132 133The Argument Name field in most (but not all) cases is the same name as the 134callback function parameter. 135 136The Argument Value Syntax field describes the values that will be displayed 137for the argument value. It uses an ad hoc representation that mixes literal 138and symbolic representations. Enumeration member symbols are shown as the 139actual enum member in a (member1|member2|...) form. A name in parentheses 140can either represent a place holder for the described value, or confusingly, 141it might be a literal, such as (null), for a null pointer. 142Locations are shown as quoted only to avoid confusing the documentation generator. 143 144The Clang C++ Type field is the type from the callback function declaration. 145 146The description describes the argument or what is displayed for it. 147 148Note that in some cases, such as when a structure pointer is an argument 149value, only some key member or members are shown to represent the value, 150instead 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 155FileChanged is called when the preprocessor enters or exits a file, both the 156top level file being compiled, as well as any #include directives. It will 157also be called as a result of a system header pragma or in internal renaming 158of a file. 159 160Argument descriptions: 161 162============== ================================================== ============================== ============================== 163Argument Name Argument Value Syntax Clang C++ Type Description 164============== ================================================== ============================== ============================== 165Loc "(file):(line):(col)" SourceLocation The location of the directive. 166Reason (EnterFile|ExitFile|SystemHeaderPragma|RenameFile) PPCallbacks::FileChangeReason Reason for change. 167FileType (C_User|C_System|C_ExternCSystem) SrcMgr::CharacteristicKind Include type. 168PrevFID ((file)|(invalid)) FileID Previous file, if any. 169============== ================================================== ============================== ============================== 170 171Example::: 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 182FileSkipped is called when a source file is skipped as the result of header 183guard optimization. 184 185Argument descriptions: 186 187============== ================================================== ============================== ======================================================== 188Argument Name Argument Value Syntax Clang C++ Type Description 189============== ================================================== ============================== ======================================================== 190ParentFile ("(file)" or (null)) const FileEntry The file that #included the skipped file. 191FilenameTok (token) const Token The token in ParentFile that indicates the skipped file. 192FileType (C_User|C_System|C_ExternCSystem) SrcMgr::CharacteristicKind The file type. 193============== ================================================== ============================== ======================================================== 194 195Example::: 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 205InclusionDirective 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 207Argument descriptions: 208 209============== ================================================== ============================== ============================================================================================================ 210Argument Name Argument Value Syntax Clang C++ Type Description 211============== ================================================== ============================== ============================================================================================================ 212HashLoc "(file):(line):(col)" SourceLocation The location of the '#' that starts the inclusion directive. 213IncludeTok (token) const Token The token that indicates the kind of inclusion directive, e.g., 'include' or 'import'. 214FileName "(file)" StringRef The name of the file being included, as written in the source code. 215IsAngled (true|false) bool Whether the file name was enclosed in angle brackets; otherwise, it was enclosed in quotes. 216FilenameRange "(file)" CharSourceRange The character range of the quotes or angle brackets for the written file name. 217File "(file)" const FileEntry The actual file that may be included by this inclusion directive. 218SearchPath "(path)" StringRef Contains the search path which was used to find the file in the file system. 219RelativePath "(path)" StringRef The path relative to SearchPath, at which the include file was found. 220Imported ((module name)|(null)) const Module The module, whenever an inclusion directive was automatically turned into a module import or null otherwise. 221============== ================================================== ============================== ============================================================================================================ 222 223Example::: 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 239moduleImport is called when there was an explicit module-import syntax. 240 241Argument descriptions: 242 243============== ================================================== ============================== =========================================================== 244Argument Name Argument Value Syntax Clang C++ Type Description 245============== ================================================== ============================== =========================================================== 246ImportLoc "(file):(line):(col)" SourceLocation The location of import directive token. 247Path "(path)" ModuleIdPath The identifiers (and their locations) of the module "path". 248Imported ((module name)|(null)) const Module The imported module; can be null if importing failed. 249============== ================================================== ============================== =========================================================== 250 251Example::: 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 261EndOfMainFile is called when the end of the main file is reached. 262 263Argument descriptions: 264 265============== ================================================== ============================== ====================== 266Argument Name Argument Value Syntax Clang C++ Type Description 267============== ================================================== ============================== ====================== 268(no arguments) 269============== ================================================== ============================== ====================== 270 271Example::: 272 273 - Callback: EndOfMainFile 274 275`Ident <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3683f1d1fa513e9b6193d446a5cc2b66>`_ Callback 276^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 277 278Ident is called when a #ident or #sccs directive is read. 279 280Argument descriptions: 281 282============== ================================================== ============================== ============================== 283Argument Name Argument Value Syntax Clang C++ Type Description 284============== ================================================== ============================== ============================== 285Loc "(file):(line):(col)" SourceLocation The location of the directive. 286str (name) const std::string The text of the directive. 287============== ================================================== ============================== ============================== 288 289Example::: 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 298PragmaDirective is called when start reading any pragma directive. 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. 306Introducer (PIK_HashPragma|PIK__Pragma|PIK___pragma) PragmaIntroducerKind The type of the pragma directive. 307============== ================================================== ============================== ================================= 308 309Example::: 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 318PragmaComment is called when a #pragma comment directive is read. 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. 326Kind ((name)|(null)) const IdentifierInfo The comment kind symbol. 327Str (message directive) const std::string The comment message directive. 328============== ================================================== ============================== ============================== 329 330Example::: 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 340PragmaDetectMismatch is called when a #pragma detect_mismatch directive is read. 341 342Argument descriptions: 343 344============== ================================================== ============================== ============================== 345Argument Name Argument Value Syntax Clang C++ Type Description 346============== ================================================== ============================== ============================== 347Loc "(file):(line):(col)" SourceLocation The location of the directive. 348Name "(name)" const std::string The name. 349Value (string) const std::string The value. 350============== ================================================== ============================== ============================== 351 352Example::: 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 362PragmaDebug is called when a #pragma clang __debug directive is read. 363 364Argument descriptions: 365 366============== ================================================== ============================== ================================ 367Argument Name Argument Value Syntax Clang C++ Type Description 368============== ================================================== ============================== ================================ 369Loc "(file):(line):(col)" SourceLocation The location of the directive. 370DebugType (string) StringRef Indicates type of debug message. 371============== ================================================== ============================== ================================ 372 373Example::: 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 382PragmaMessage is called when a #pragma message 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. 390Namespace (name) StringRef The namespace of the message directive. 391Kind (PMK_Message|PMK_Warning|PMK_Error) PPCallbacks::PragmaMessageKind The type of the message directive. 392Str (string) StringRef The text of the message directive. 393============== ================================================== ============================== ======================================= 394 395Example::: 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 406PragmaDiagnosticPush is called when a #pragma gcc diagnostic push directive is read. 407 408Argument descriptions: 409 410============== ================================================== ============================== ============================== 411Argument Name Argument Value Syntax Clang C++ Type Description 412============== ================================================== ============================== ============================== 413Loc "(file):(line):(col)" SourceLocation The location of the directive. 414Namespace (name) StringRef Namespace name. 415============== ================================================== ============================== ============================== 416 417Example::: 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 426PragmaDiagnosticPop is called when a #pragma gcc diagnostic pop 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: 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 446PragmaDiagnostic is called when a #pragma gcc diagnostic 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. 455mapping (0|MAP_IGNORE|MAP_WARNING|MAP_ERROR|MAP_FATAL) diag::Severity Mapping type. 456Str (string) StringRef Warning/error name. 457============== ================================================== ============================== ============================== 458 459Example::: 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 470PragmaOpenCLExtension is called when OpenCL extension is either disabled or enabled with a pragma. 471 472Argument descriptions: 473 474============== ================================================== ============================== ========================== 475Argument Name Argument Value Syntax Clang C++ Type Description 476============== ================================================== ============================== ========================== 477NameLoc "(file):(line):(col)" SourceLocation The location of the name. 478Name (name) const IdentifierInfo Name symbol. 479StateLoc "(file):(line):(col)" SourceLocation The location of the state. 480State (1|0) unsigned Enabled/disabled state. 481============== ================================================== ============================== ========================== 482 483Example::: 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 494PragmaWarning is called when a #pragma warning directive is read. 495 496Argument descriptions: 497 498============== ================================================== ============================== ============================== 499Argument Name Argument Value Syntax Clang C++ Type Description 500============== ================================================== ============================== ============================== 501Loc "(file):(line):(col)" SourceLocation The location of the directive. 502WarningSpec (string) StringRef The warning specifier. 503Ids [(number)[, ...]] ArrayRef<int> The warning numbers. 504============== ================================================== ============================== ============================== 505 506Example::: 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 516PragmaWarningPush is called when a #pragma warning(push) directive is read. 517 518Argument descriptions: 519 520============== ================================================== ============================== ============================== 521Argument Name Argument Value Syntax Clang C++ Type Description 522============== ================================================== ============================== ============================== 523Loc "(file):(line):(col)" SourceLocation The location of the directive. 524Level (number) int Warning level. 525============== ================================================== ============================== ============================== 526 527Example::: 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 536PragmaWarningPop is called when a #pragma warning(pop) 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. 544============== ================================================== ============================== ============================== 545 546Example::: 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 554MacroExpands is called when ::HandleMacroExpandedIdentifier when a macro invocation is found. 555 556Argument descriptions: 557 558============== ================================================== ============================== ====================================================================================================== 559Argument Name Argument Value Syntax Clang C++ Type Description 560============== ================================================== ============================== ====================================================================================================== 561MacroNameTok (token) const Token The macro name token. 562MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. 563Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the expansion. 564Args [(name)|(number)|<(token name)>[, ...]] const MacroArgs The argument tokens. Names and numbers are literal, everything else is of the form '<' tokenName '>'. 565============== ================================================== ============================== ====================================================================================================== 566 567Example::: 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 578MacroDefined is called when a macro definition is seen. 579 580Argument descriptions: 581 582============== ================================================== ============================== ============================================================== 583Argument Name Argument Value Syntax Clang C++ Type Description 584============== ================================================== ============================== ============================================================== 585MacroNameTok (token) const Token The macro name token. 586MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. 587============== ================================================== ============================== ============================================================== 588 589Example::: 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 598MacroUndefined is called when a macro #undef 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: 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 618Defined is called when the 'defined' operator 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. 627Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the directive. 628============== ================================================== ============================== ============================================================== 629 630Example::: 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 640SourceRangeSkipped is called when a source range is skipped. 641 642Argument descriptions: 643 644============== ================================================== ============================== ========================= 645Argument Name Argument Value Syntax Clang C++ Type Description 646============== ================================================== ============================== ========================= 647Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range skipped. 648============== ================================================== ============================== ========================= 649 650Example::: 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 658If is called when an #if is seen. 659 660Argument descriptions: 661 662============== ================================================== ============================== =================================== 663Argument Name Argument Value Syntax Clang C++ Type Description 664============== ================================================== ============================== =================================== 665Loc "(file):(line):(col)" SourceLocation The location of the directive. 666ConditionRange ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the condition. 667ConditionValue (true|false) bool The condition value. 668============== ================================================== ============================== =================================== 669 670Example::: 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 680Elif is called when an #elif is seen. 681 682Argument descriptions: 683 684============== ================================================== ============================== =================================== 685Argument Name Argument Value Syntax Clang C++ Type Description 686============== ================================================== ============================== =================================== 687Loc "(file):(line):(col)" SourceLocation The location of the directive. 688ConditionRange ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the condition. 689ConditionValue (true|false) bool The condition value. 690IfLoc "(file):(line):(col)" SourceLocation The location of the directive. 691============== ================================================== ============================== =================================== 692 693Example::: 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 704Ifdef is called when an #ifdef is seen. 705 706Argument descriptions: 707 708============== ================================================== ============================== ============================================================== 709Argument Name Argument Value Syntax Clang C++ Type Description 710============== ================================================== ============================== ============================================================== 711Loc "(file):(line):(col)" SourceLocation The location of the directive. 712MacroNameTok (token) const Token The macro name token. 713MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. 714============== ================================================== ============================== ============================================================== 715 716Example::: 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 726Ifndef is called when an #ifndef is seen. 727 728Argument descriptions: 729 730============== ================================================== ============================== ============================================================== 731Argument Name Argument Value Syntax Clang C++ Type Description 732============== ================================================== ============================== ============================================================== 733Loc "(file):(line):(col)" SourceLocation The location of the directive. 734MacroNameTok (token) const Token The macro name token. 735MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. 736============== ================================================== ============================== ============================================================== 737 738Example::: 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 748Else is called when an #else is seen. 749 750Argument descriptions: 751 752============== ================================================== ============================== =================================== 753Argument Name Argument Value Syntax Clang C++ Type Description 754============== ================================================== ============================== =================================== 755Loc "(file):(line):(col)" SourceLocation The location of the else directive. 756IfLoc "(file):(line):(col)" SourceLocation The location of the if directive. 757============== ================================================== ============================== =================================== 758 759Example::: 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 768Endif is called when an #endif 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 endif directive. 776IfLoc "(file):(line):(col)" SourceLocation The location of the if directive. 777============== ================================================== ============================== ==================================== 778 779Example::: 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 785Building pp-trace 786================= 787 788To build from source: 789 7901. 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 7942. `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 805