805 lines · plain
1.. index:: pp-trace2 3==================================4pp-trace User's Manual5==================================6 7.. toctree::8 :hidden:9 10:program:`pp-trace` is a standalone tool that traces preprocessor11activity. It's also used as a test of Clang's PPCallbacks interface.12It runs a given source file through the Clang preprocessor, displaying13selected information from callback functions overridden in a14`PPCallbacks <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html>`_15derivation. The output is in a high-level YAML format, described in16:ref:`OutputFormat`.17 18.. _Usage:19 20pp-trace Usage21==============22 23Command Line Format24-------------------25 26``pp-trace [<pp-trace-options>] <source-file> [-- <front-end-options>]``27 28``<pp-trace-options>`` is a place-holder for options29specific to pp-trace, which are described below in30: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 regular35`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 Options41--------------------42 43.. option:: -callbacks <comma-separated-globs>44 45 This option specifies a comma-separated list of globs describing the list of46 callbacks that should be traced. Globs are processed in order of appearance.47 Positive globs add matched callbacks to the set, negative globs (those with48 the '-' prefix) remove callacks from the set.49 50 * FileChanged51 * FileSkipped52 * InclusionDirective53 * moduleImport54 * EndOfMainFile55 * Ident56 * PragmaDirective57 * PragmaComment58 * PragmaDetectMismatch59 * PragmaDebug60 * PragmaMessage61 * PragmaDiagnosticPush62 * PragmaDiagnosticPop63 * PragmaDiagnostic64 * PragmaOpenCLExtension65 * PragmaWarning66 * PragmaWarningPush67 * PragmaWarningPop68 * MacroExpands69 * MacroDefined70 * MacroUndefined71 * Defined72 * SourceRangeSkipped73 * If74 * Elif75 * Ifdef76 * Ifndef77 * Else78 * Endif79 80.. option:: -output <output-file>81 82 By default, pp-trace outputs the trace information to stdout. Use this83 option to output the trace information to a file.84 85.. _OutputFormat:86 87pp-trace Output Format88======================89 90The pp-trace output is formatted as YAML. See https://yaml.org/ for general91YAML information. It's arranged as a sequence of information about the92callback call, including the callback name and argument information, for93example:::94 95 ---96 - Callback: Name97 Argument1: Value198 Argument2: Value299 (etc.)100 ...101 102With real data:::103 104 ---105 - Callback: FileChanged106 Loc: "c:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"107 Reason: EnterFile108 FileType: C_User109 PrevFID: (invalid)110 (etc.)111 - Callback: FileChanged112 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:5:1"113 Reason: ExitFile114 FileType: C_User115 PrevFID: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/Input/Level1B.h"116 - Callback: EndOfMainFile117 ...118 119In all but one case (MacroDirective) the "Argument" scalars have the same120name as the argument in the corresponding PPCallbacks callback function.121 122Callback Details123----------------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 Doxygen128documentation for the callback.129 130The argument descriptions table describes the callback argument information131displayed.132 133The Argument Name field in most (but not all) cases is the same name as the134callback function parameter.135 136The Argument Value Syntax field describes the values that will be displayed137for the argument value. It uses an ad hoc representation that mixes literal138and symbolic representations. Enumeration member symbols are shown as the139actual enum member in a (member1|member2|...) form. A name in parentheses140can 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 argument149value, 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>`_ Callback153^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^154 155FileChanged is called when the preprocessor enters or exits a file, both the156top level file being compiled, as well as any #include directives. It will157also be called as a result of a system header pragma or in internal renaming158of a file.159 160Argument descriptions:161 162============== ================================================== ============================== ==============================163Argument Name Argument Value Syntax Clang C++ Type Description164============== ================================================== ============================== ==============================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: FileChanged174 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"175 Reason: EnterFile176 FileType: C_User177 PrevFID: (invalid)178 179`FileSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab5b338a0670188eb05fa7685bbfb5128>`_ Callback180^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^181 182FileSkipped is called when a source file is skipped as the result of header183guard optimization.184 185Argument descriptions:186 187============== ================================================== ============================== ========================================================188Argument Name Argument Value Syntax Clang C++ Type Description189============== ================================================== ============================== ========================================================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: FileSkipped198 ParentFile: "/path/filename.h"199 FilenameTok: "filename.h"200 FileType: C_User201 202`InclusionDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a557d9738c329793513a6f57d6b60de52>`_ Callback203^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description211============== ================================================== ============================== ============================================================================================================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: InclusionDirective226 HashLoc: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:4:1"227 IncludeTok: include228 FileName: "Input/Level1B.h"229 IsAngled: false230 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>`_ Callback237^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description245============== ================================================== ============================== ===========================================================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: moduleImport254 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: Level2B257 258`EndOfMainFile <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a63e170d069e99bc1c9c7ea0f3bed8bcc>`_ Callback259^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description267============== ================================================== ============================== ======================268(no arguments)269============== ================================================== ============================== ======================270 271Example:::272 273 - Callback: EndOfMainFile274 275`Ident <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3683f1d1fa513e9b6193d446a5cc2b66>`_ Callback276^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description284============== ================================================== ============================== ==============================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: Ident292 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>`_ Callback296^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^297 298PragmaDirective is called when start reading any pragma directive.299 300Argument descriptions:301 302============== ================================================== ============================== =================================303Argument Name Argument Value Syntax Clang C++ Type Description304============== ================================================== ============================== =================================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: PragmaDirective312 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"313 Introducer: PIK_HashPragma314 315`PragmaComment <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ace0d940fc2c12ab76441466aab58dc37>`_ Callback316^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^317 318PragmaComment is called when a #pragma comment directive is read.319 320Argument descriptions:321 322============== ================================================== ============================== ==============================323Argument Name Argument Value Syntax Clang C++ Type Description324============== ================================================== ============================== ==============================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: PragmaComment333 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"334 Kind: library335 Str: kernel32.lib336 337`PragmaDetectMismatch <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab11158c9149fb8ad8af1903f4a6cd65d>`_ Callback338^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description346============== ================================================== ============================== ==============================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: PragmaDetectMismatch355 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"356 Name: name357 Value: value358 359`PragmaDebug <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a57cdccb6dcc07e926513ac3d5b121466>`_ Callback360^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description368============== ================================================== ============================== ================================369Loc "(file):(line):(col)" SourceLocation The location of the directive.370DebugType (string) StringRef Indicates type of debug message.371============== ================================================== ============================== ================================372 373Example:::374 375 - Callback: PragmaDebug376 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"377 DebugType: warning378 379`PragmaMessage <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abb42935d9a9fd8e2c4f51cfdc4ea2ae1>`_ Callback380^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^381 382PragmaMessage is called when a #pragma message directive is read.383 384Argument descriptions:385 386============== ================================================== ============================== =======================================387Argument Name Argument Value Syntax Clang C++ Type Description388============== ================================================== ============================== =======================================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: PragmaMessage398 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"399 Namespace: "GCC"400 Kind: PMK_Message401 Str: The message text.402 403`PragmaDiagnosticPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0f3ff19762baa38fe6c5c58022d32979>`_ Callback404^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description412============== ================================================== ============================== ==============================413Loc "(file):(line):(col)" SourceLocation The location of the directive.414Namespace (name) StringRef Namespace name.415============== ================================================== ============================== ==============================416 417Example:::418 419 - Callback: PragmaDiagnosticPush420 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>`_ Callback424^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description432============== ================================================== ============================== ==============================433Loc "(file):(line):(col)" SourceLocation The location of the directive.434Namespace (name) StringRef Namespace name.435============== ================================================== ============================== ==============================436 437Example:::438 439 - Callback: PragmaDiagnosticPop440 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>`_ Callback444^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description452============== ================================================== ============================== ==============================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: PragmaDiagnostic462 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"463 Namespace: "GCC"464 mapping: MAP_WARNING465 Str: WarningName466 467`PragmaOpenCLExtension <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a92a20a21fadbab4e2c788f4e27fe07e7>`_ Callback468^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description476============== ================================================== ============================== ==========================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: PragmaOpenCLExtension486 NameLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:10"487 Name: Name488 StateLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:18"489 State: 1490 491`PragmaWarning <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#aa17169d25fa1cf0a6992fc944d1d8730>`_ Callback492^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^493 494PragmaWarning is called when a #pragma warning directive is read.495 496Argument descriptions:497 498============== ================================================== ============================== ==============================499Argument Name Argument Value Syntax Clang C++ Type Description500============== ================================================== ============================== ==============================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: PragmaWarning509 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"510 WarningSpec: disable511 Ids: 1,2,3512 513`PragmaWarningPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ae5626ef70502687a859f323a809ed0b6>`_ Callback514^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description522============== ================================================== ============================== ==============================523Loc "(file):(line):(col)" SourceLocation The location of the directive.524Level (number) int Warning level.525============== ================================================== ============================== ==============================526 527Example:::528 529 - Callback: PragmaWarningPush530 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"531 Level: 1532 533`PragmaWarningPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac98d502af8811b8a6e7342d7cd2b3b95>`_ Callback534^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description542============== ================================================== ============================== ==============================543Loc "(file):(line):(col)" SourceLocation The location of the directive.544============== ================================================== ============================== ==============================545 546Example:::547 548 - Callback: PragmaWarningPop549 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>`_ Callback552^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^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 Description560============== ================================================== ============================== ======================================================================================================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: MacroExpands570 MacroNameTok: X_IMPL571 MacroDirective: MD_Define572 Range: [(nonfile), (nonfile)]573 Args: [a <plus> y, b]574 575`MacroDefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a8448fc9f96f22ad1b93ff393cffc5a76>`_ Callback576^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^577 578MacroDefined is called when a macro definition is seen.579 580Argument descriptions:581 582============== ================================================== ============================== ==============================================================583Argument Name Argument Value Syntax Clang C++ Type Description584============== ================================================== ============================== ==============================================================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: MacroDefined592 MacroNameTok: X_IMPL593 MacroDirective: MD_Define594 595`MacroUndefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#acb80fc6171a839db8e290945bf2c9d7a>`_ Callback596^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^597 598MacroUndefined is called when a macro #undef is seen.599 600Argument descriptions:601 602============== ================================================== ============================== ==============================================================603Argument Name Argument Value Syntax Clang C++ Type Description604============== ================================================== ============================== ==============================================================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: MacroUndefined612 MacroNameTok: X_IMPL613 MacroDirective: MD_Define614 615`Defined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3cc2a644533d0e4088a13d2baf90db94>`_ Callback616^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^617 618Defined is called when the 'defined' operator is seen.619 620Argument descriptions:621 622============== ================================================== ============================== ==============================================================623Argument Name Argument Value Syntax Clang C++ Type Description624============== ================================================== ============================== ==============================================================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: Defined633 MacroNameTok: MACRO634 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>`_ Callback638^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^639 640SourceRangeSkipped is called when a source range is skipped.641 642Argument descriptions:643 644============== ================================================== ============================== =========================645Argument Name Argument Value Syntax Clang C++ Type Description646============== ================================================== ============================== =========================647Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range skipped.648============== ================================================== ============================== =========================649 650Example:::651 652 - Callback: SourceRangeSkipped653 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>`_ Callback656^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^657 658If is called when an #if is seen.659 660Argument descriptions:661 662============== ================================================== ============================== ===================================663Argument Name Argument Value Syntax Clang C++ Type Description664============== ================================================== ============================== ===================================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: If673 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: false676 677`Elif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a180c9e106a28d60a6112e16b1bb8302a>`_ Callback678^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^679 680Elif is called when an #elif is seen.681 682Argument descriptions:683 684============== ================================================== ============================== ===================================685Argument Name Argument Value Syntax Clang C++ Type Description686============== ================================================== ============================== ===================================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: Elif696 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: false699 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>`_ Callback702^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^703 704Ifdef is called when an #ifdef is seen.705 706Argument descriptions:707 708============== ================================================== ============================== ==============================================================709Argument Name Argument Value Syntax Clang C++ Type Description710============== ================================================== ============================== ==============================================================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: Ifdef719 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"720 MacroNameTok: MACRO721 MacroDirective: MD_Define722 723`Ifndef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a767af69f1cdcc4cd880fa2ebf77ad3ad>`_ Callback724^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^725 726Ifndef is called when an #ifndef is seen.727 728Argument descriptions:729 730============== ================================================== ============================== ==============================================================731Argument Name Argument Value Syntax Clang C++ Type Description732============== ================================================== ============================== ==============================================================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: Ifndef741 Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"742 MacroNameTok: MACRO743 MacroDirective: MD_Define744 745`Else <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ad57f91b6d9c3cbcca326a2bfb49e0314>`_ Callback746^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^747 748Else is called when an #else is seen.749 750Argument descriptions:751 752============== ================================================== ============================== ===================================753Argument Name Argument Value Syntax Clang C++ Type Description754============== ================================================== ============================== ===================================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: Else762 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>`_ Callback766^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^767 768Endif is called when an #endif is seen.769 770Argument descriptions:771 772============== ================================================== ============================== ====================================773Argument Name Argument Value Syntax Clang C++ Type Description774============== ================================================== ============================== ====================================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: Endif782 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-trace786=================787 788To build from source:789 7901. Read `Getting Started with the LLVM System`_ and `Clang Tools791 Documentation`_ for information on getting sources for LLVM, Clang, and792 Clang Extra Tools.793 7942. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give795 directions for how to build. With sources all checked out into the796 right place the LLVM build will build Clang Extra Tools and their797 dependencies automatically.798 799 * If using CMake, you can also use the ``pp-trace`` target to build800 just the pp-trace tool and its dependencies.801 802.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html803.. _Building LLVM with CMake: https://llvm.org/docs/CMake.html804.. _Clang Tools Documentation: https://clang.llvm.org/docs/ClangTools.html805