| .. index:: pp-trace |
| |
| ================================== |
| pp-trace User's Manual |
| ================================== |
| |
| .. toctree:: |
| :hidden: |
| |
| :program:`pp-trace` is a standalone tool that traces preprocessor |
| activity. It's also used as a test of Clang's PPCallbacks interface. |
| It runs a given source file through the Clang preprocessor, displaying |
| selected information from callback functions overridden in a |
| `PPCallbacks <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html>`_ |
| derivation. The output is in a high-level YAML format, described in |
| :ref:`OutputFormat`. |
| |
| .. _Usage: |
| |
| pp-trace Usage |
| ============== |
| |
| Command Line Format |
| ------------------- |
| |
| ``pp-trace [<pp-trace-options>] <source-file> [-- <front-end-options>]`` |
| |
| ``<pp-trace-options>`` is a place-holder for options |
| specific to pp-trace, which are described below in |
| :ref:`CommandLineOptions`. |
| |
| ``<source-file>`` specifies the source file to run through the preprocessor. |
| |
| ``<front-end-options>`` is a place-holder for regular |
| `Clang Compiler Options <https://clang.llvm.org/docs/UsersManual.html#command-line-options>`_, |
| which must follow the <source-file>. |
| |
| .. _CommandLineOptions: |
| |
| Command Line Options |
| -------------------- |
| |
| .. option:: -callbacks <comma-separated-globs> |
| |
| This option specifies a comma-separated list of globs describing the list of |
| callbacks that should be traced. Globs are processed in order of appearance. |
| Positive globs add matched callbacks to the set, negative globs (those with |
| the '-' prefix) remove callacks from the set. |
| |
| * FileChanged |
| * FileSkipped |
| * InclusionDirective |
| * moduleImport |
| * EndOfMainFile |
| * Ident |
| * PragmaDirective |
| * PragmaComment |
| * PragmaDetectMismatch |
| * PragmaDebug |
| * PragmaMessage |
| * PragmaDiagnosticPush |
| * PragmaDiagnosticPop |
| * PragmaDiagnostic |
| * PragmaOpenCLExtension |
| * PragmaWarning |
| * PragmaWarningPush |
| * PragmaWarningPop |
| * MacroExpands |
| * MacroDefined |
| * MacroUndefined |
| * Defined |
| * SourceRangeSkipped |
| * If |
| * Elif |
| * Ifdef |
| * Ifndef |
| * Else |
| * Endif |
| |
| .. option:: -output <output-file> |
| |
| By default, pp-trace outputs the trace information to stdout. Use this |
| option to output the trace information to a file. |
| |
| .. _OutputFormat: |
| |
| pp-trace Output Format |
| ====================== |
| |
| The pp-trace output is formatted as YAML. See https://yaml.org/ for general |
| YAML information. It's arranged as a sequence of information about the |
| callback call, including the callback name and argument information, for |
| example::: |
| |
| --- |
| - Callback: Name |
| Argument1: Value1 |
| Argument2: Value2 |
| (etc.) |
| ... |
| |
| With real data::: |
| |
| --- |
| - Callback: FileChanged |
| Loc: "c:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1" |
| Reason: EnterFile |
| FileType: C_User |
| PrevFID: (invalid) |
| (etc.) |
| - Callback: FileChanged |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:5:1" |
| Reason: ExitFile |
| FileType: C_User |
| PrevFID: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/Input/Level1B.h" |
| - Callback: EndOfMainFile |
| ... |
| |
| In all but one case (MacroDirective) the "Argument" scalars have the same |
| name as the argument in the corresponding PPCallbacks callback function. |
| |
| Callback Details |
| ---------------- |
| |
| The following sections describe the purpose and output format for each callback. |
| |
| Click on the callback name in the section heading to see the Doxygen |
| documentation for the callback. |
| |
| The argument descriptions table describes the callback argument information |
| displayed. |
| |
| The Argument Name field in most (but not all) cases is the same name as the |
| callback function parameter. |
| |
| The Argument Value Syntax field describes the values that will be displayed |
| for the argument value. It uses an ad hoc representation that mixes literal |
| and symbolic representations. Enumeration member symbols are shown as the |
| actual enum member in a (member1|member2|...) form. A name in parentheses |
| can either represent a place holder for the described value, or confusingly, |
| it might be a literal, such as (null), for a null pointer. |
| Locations are shown as quoted only to avoid confusing the documentation generator. |
| |
| The Clang C++ Type field is the type from the callback function declaration. |
| |
| The description describes the argument or what is displayed for it. |
| |
| Note that in some cases, such as when a structure pointer is an argument |
| value, only some key member or members are shown to represent the value, |
| instead of trying to display all members of the structure. |
| |
| `FileChanged <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a7cc8cfaf34114fc65e92af621cd6464e>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| FileChanged is called when the preprocessor enters or exits a file, both the |
| top level file being compiled, as well as any #include directives. It will |
| also be called as a result of a system header pragma or in internal renaming |
| of a file. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Reason (EnterFile|ExitFile|SystemHeaderPragma|RenameFile) PPCallbacks::FileChangeReason Reason for change. |
| FileType (C_User|C_System|C_ExternCSystem) SrcMgr::CharacteristicKind Include type. |
| PrevFID ((file)|(invalid)) FileID Previous file, if any. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: FileChanged |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1" |
| Reason: EnterFile |
| FileType: C_User |
| PrevFID: (invalid) |
| |
| `FileSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab5b338a0670188eb05fa7685bbfb5128>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| FileSkipped is called when a source file is skipped as the result of header |
| guard optimization. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ======================================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ======================================================== |
| ParentFile ("(file)" or (null)) const FileEntry The file that #included the skipped file. |
| FilenameTok (token) const Token The token in ParentFile that indicates the skipped file. |
| FileType (C_User|C_System|C_ExternCSystem) SrcMgr::CharacteristicKind The file type. |
| ============== ================================================== ============================== ======================================================== |
| |
| Example::: |
| |
| - Callback: FileSkipped |
| ParentFile: "/path/filename.h" |
| FilenameTok: "filename.h" |
| FileType: C_User |
| |
| `InclusionDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a557d9738c329793513a6f57d6b60de52>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| InclusionDirective is called when an inclusion directive of any kind (#include</code>, #import</code>, etc.) has been processed, regardless of whether the inclusion will actually result in an inclusion. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================================================================================================ |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================================================================================================ |
| HashLoc "(file):(line):(col)" SourceLocation The location of the '#' that starts the inclusion directive. |
| IncludeTok (token) const Token The token that indicates the kind of inclusion directive, e.g., 'include' or 'import'. |
| FileName "(file)" StringRef The name of the file being included, as written in the source code. |
| IsAngled (true|false) bool Whether the file name was enclosed in angle brackets; otherwise, it was enclosed in quotes. |
| FilenameRange "(file)" CharSourceRange The character range of the quotes or angle brackets for the written file name. |
| File "(file)" const FileEntry The actual file that may be included by this inclusion directive. |
| SearchPath "(path)" StringRef Contains the search path which was used to find the file in the file system. |
| RelativePath "(path)" StringRef The path relative to SearchPath, at which the include file was found. |
| Imported ((module name)|(null)) const Module The module, whenever an inclusion directive was automatically turned into a module import or null otherwise. |
| ============== ================================================== ============================== ============================================================================================================ |
| |
| Example::: |
| |
| - Callback: InclusionDirective |
| HashLoc: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:4:1" |
| IncludeTok: include |
| FileName: "Input/Level1B.h" |
| IsAngled: false |
| FilenameRange: "Input/Level1B.h" |
| File: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/Input/Level1B.h" |
| SearchPath: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace" |
| RelativePath: "Input/Level1B.h" |
| Imported: (null) |
| |
| `moduleImport <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#af32dcf1b8b7c179c7fcd3e24e89830fe>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| moduleImport is called when there was an explicit module-import syntax. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== =========================================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== =========================================================== |
| ImportLoc "(file):(line):(col)" SourceLocation The location of import directive token. |
| Path "(path)" ModuleIdPath The identifiers (and their locations) of the module "path". |
| Imported ((module name)|(null)) const Module The imported module; can be null if importing failed. |
| ============== ================================================== ============================== =========================================================== |
| |
| Example::: |
| |
| - Callback: moduleImport |
| ImportLoc: "d:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:2" |
| 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"}] |
| Imported: Level2B |
| |
| `EndOfMainFile <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a63e170d069e99bc1c9c7ea0f3bed8bcc>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| EndOfMainFile is called when the end of the main file is reached. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ====================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ====================== |
| (no arguments) |
| ============== ================================================== ============================== ====================== |
| |
| Example::: |
| |
| - Callback: EndOfMainFile |
| |
| `Ident <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3683f1d1fa513e9b6193d446a5cc2b66>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Ident is called when a #ident or #sccs directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| str (name) const std::string The text of the directive. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: Ident |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-ident.cpp:3:1" |
| str: "$Id$" |
| |
| `PragmaDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0a2d7a72c62184b3cbde31fb62c6f2f7>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaDirective is called when start reading any pragma directive. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ================================= |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ================================= |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Introducer (PIK_HashPragma|PIK__Pragma|PIK___pragma) PragmaIntroducerKind The type of the pragma directive. |
| ============== ================================================== ============================== ================================= |
| |
| Example::: |
| |
| - Callback: PragmaDirective |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| Introducer: PIK_HashPragma |
| |
| `PragmaComment <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ace0d940fc2c12ab76441466aab58dc37>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaComment is called when a #pragma comment directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Kind ((name)|(null)) const IdentifierInfo The comment kind symbol. |
| Str (message directive) const std::string The comment message directive. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: PragmaComment |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| Kind: library |
| Str: kernel32.lib |
| |
| `PragmaDetectMismatch <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab11158c9149fb8ad8af1903f4a6cd65d>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaDetectMismatch is called when a #pragma detect_mismatch directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Name "(name)" const std::string The name. |
| Value (string) const std::string The value. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: PragmaDetectMismatch |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| Name: name |
| Value: value |
| |
| `PragmaDebug <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a57cdccb6dcc07e926513ac3d5b121466>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaDebug is called when a #pragma clang __debug directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ================================ |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ================================ |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| DebugType (string) StringRef Indicates type of debug message. |
| ============== ================================================== ============================== ================================ |
| |
| Example::: |
| |
| - Callback: PragmaDebug |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| DebugType: warning |
| |
| `PragmaMessage <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abb42935d9a9fd8e2c4f51cfdc4ea2ae1>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaMessage is called when a #pragma message directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ======================================= |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ======================================= |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Namespace (name) StringRef The namespace of the message directive. |
| Kind (PMK_Message|PMK_Warning|PMK_Error) PPCallbacks::PragmaMessageKind The type of the message directive. |
| Str (string) StringRef The text of the message directive. |
| ============== ================================================== ============================== ======================================= |
| |
| Example::: |
| |
| - Callback: PragmaMessage |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| Namespace: "GCC" |
| Kind: PMK_Message |
| Str: The message text. |
| |
| `PragmaDiagnosticPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0f3ff19762baa38fe6c5c58022d32979>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaDiagnosticPush is called when a #pragma gcc diagnostic push directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Namespace (name) StringRef Namespace name. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: PragmaDiagnosticPush |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| Namespace: "GCC" |
| |
| `PragmaDiagnosticPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac94d789873122221fba8d76f6c5ea45e>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaDiagnosticPop is called when a #pragma gcc diagnostic pop directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Namespace (name) StringRef Namespace name. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: PragmaDiagnosticPop |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| Namespace: "GCC" |
| |
| `PragmaDiagnostic <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afe7938f38a83cb7b4b25a13edfdd7bdd>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaDiagnostic is called when a #pragma gcc diagnostic directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Namespace (name) StringRef Namespace name. |
| mapping (0|MAP_IGNORE|MAP_WARNING|MAP_ERROR|MAP_FATAL) diag::Severity Mapping type. |
| Str (string) StringRef Warning/error name. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: PragmaDiagnostic |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| Namespace: "GCC" |
| mapping: MAP_WARNING |
| Str: WarningName |
| |
| `PragmaOpenCLExtension <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a92a20a21fadbab4e2c788f4e27fe07e7>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaOpenCLExtension is called when OpenCL extension is either disabled or enabled with a pragma. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ========================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ========================== |
| NameLoc "(file):(line):(col)" SourceLocation The location of the name. |
| Name (name) const IdentifierInfo Name symbol. |
| StateLoc "(file):(line):(col)" SourceLocation The location of the state. |
| State (1|0) unsigned Enabled/disabled state. |
| ============== ================================================== ============================== ========================== |
| |
| Example::: |
| |
| - Callback: PragmaOpenCLExtension |
| NameLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:10" |
| Name: Name |
| StateLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:18" |
| State: 1 |
| |
| `PragmaWarning <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#aa17169d25fa1cf0a6992fc944d1d8730>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaWarning is called when a #pragma warning directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| WarningSpec (string) StringRef The warning specifier. |
| Ids [(number)[, ...]] ArrayRef<int> The warning numbers. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: PragmaWarning |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| WarningSpec: disable |
| Ids: 1,2,3 |
| |
| `PragmaWarningPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ae5626ef70502687a859f323a809ed0b6>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaWarningPush is called when a #pragma warning(push) directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| Level (number) int Warning level. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: PragmaWarningPush |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| Level: 1 |
| |
| `PragmaWarningPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac98d502af8811b8a6e7342d7cd2b3b95>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| PragmaWarningPop is called when a #pragma warning(pop) directive is read. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| ============== ================================================== ============================== ============================== |
| |
| Example::: |
| |
| - Callback: PragmaWarningPop |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" |
| |
| `MacroExpands <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a9bc725209d3a071ea649144ab996d515>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| MacroExpands is called when ::HandleMacroExpandedIdentifier when a macro invocation is found. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ====================================================================================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ====================================================================================================== |
| MacroNameTok (token) const Token The macro name token. |
| MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. |
| Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the expansion. |
| Args [(name)|(number)|<(token name)>[, ...]] const MacroArgs The argument tokens. Names and numbers are literal, everything else is of the form '<' tokenName '>'. |
| ============== ================================================== ============================== ====================================================================================================== |
| |
| Example::: |
| |
| - Callback: MacroExpands |
| MacroNameTok: X_IMPL |
| MacroDirective: MD_Define |
| Range: [(nonfile), (nonfile)] |
| Args: [a <plus> y, b] |
| |
| `MacroDefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a8448fc9f96f22ad1b93ff393cffc5a76>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| MacroDefined is called when a macro definition is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================================================== |
| MacroNameTok (token) const Token The macro name token. |
| MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. |
| ============== ================================================== ============================== ============================================================== |
| |
| Example::: |
| |
| - Callback: MacroDefined |
| MacroNameTok: X_IMPL |
| MacroDirective: MD_Define |
| |
| `MacroUndefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#acb80fc6171a839db8e290945bf2c9d7a>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| MacroUndefined is called when a macro #undef is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================================================== |
| MacroNameTok (token) const Token The macro name token. |
| MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. |
| ============== ================================================== ============================== ============================================================== |
| |
| Example::: |
| |
| - Callback: MacroUndefined |
| MacroNameTok: X_IMPL |
| MacroDirective: MD_Define |
| |
| `Defined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3cc2a644533d0e4088a13d2baf90db94>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Defined is called when the 'defined' operator is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================================================== |
| MacroNameTok (token) const Token The macro name token. |
| MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. |
| Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the directive. |
| ============== ================================================== ============================== ============================================================== |
| |
| Example::: |
| |
| - Callback: Defined |
| MacroNameTok: MACRO |
| MacroDirective: (null) |
| 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"] |
| |
| `SourceRangeSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abdb4ebe11610f079ac33515965794b46>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| SourceRangeSkipped is called when a source range is skipped. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ========================= |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ========================= |
| Range ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range skipped. |
| ============== ================================================== ============================== ========================= |
| |
| Example::: |
| |
| - Callback: SourceRangeSkipped |
| 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"] |
| |
| `If <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a645edcb0d6becbc6f256f02fd1287778>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| If is called when an #if is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== =================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== =================================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| ConditionRange ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the condition. |
| ConditionValue (true|false) bool The condition value. |
| ============== ================================================== ============================== =================================== |
| |
| Example::: |
| |
| - Callback: If |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2" |
| 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"] |
| ConditionValue: false |
| |
| `Elif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a180c9e106a28d60a6112e16b1bb8302a>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Elif is called when an #elif is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== =================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== =================================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| ConditionRange ["(file):(line):(col)", "(file):(line):(col)"] SourceRange The source range for the condition. |
| ConditionValue (true|false) bool The condition value. |
| IfLoc "(file):(line):(col)" SourceLocation The location of the directive. |
| ============== ================================================== ============================== =================================== |
| |
| Example::: |
| |
| - Callback: Elif |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2" |
| 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"] |
| ConditionValue: false |
| IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2" |
| |
| `Ifdef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0ce79575dda307784fd51a6dd4eec33d>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Ifdef is called when an #ifdef is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================================================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| MacroNameTok (token) const Token The macro name token. |
| MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. |
| ============== ================================================== ============================== ============================================================== |
| |
| Example::: |
| |
| - Callback: Ifdef |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1" |
| MacroNameTok: MACRO |
| MacroDirective: MD_Define |
| |
| `Ifndef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a767af69f1cdcc4cd880fa2ebf77ad3ad>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Ifndef is called when an #ifndef is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ============================================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ============================================================== |
| Loc "(file):(line):(col)" SourceLocation The location of the directive. |
| MacroNameTok (token) const Token The macro name token. |
| MacroDirective (MD_Define|MD_Undefine|MD_Visibility) const MacroDirective The kind of macro directive from the MacroDirective structure. |
| ============== ================================================== ============================== ============================================================== |
| |
| Example::: |
| |
| - Callback: Ifndef |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1" |
| MacroNameTok: MACRO |
| MacroDirective: MD_Define |
| |
| `Else <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ad57f91b6d9c3cbcca326a2bfb49e0314>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Else is called when an #else is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== =================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== =================================== |
| Loc "(file):(line):(col)" SourceLocation The location of the else directive. |
| IfLoc "(file):(line):(col)" SourceLocation The location of the if directive. |
| ============== ================================================== ============================== =================================== |
| |
| Example::: |
| |
| - Callback: Else |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2" |
| IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2" |
| |
| `Endif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afc62ca1401125f516d58b1629a2093ce>`_ Callback |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Endif is called when an #endif is seen. |
| |
| Argument descriptions: |
| |
| ============== ================================================== ============================== ==================================== |
| Argument Name Argument Value Syntax Clang C++ Type Description |
| ============== ================================================== ============================== ==================================== |
| Loc "(file):(line):(col)" SourceLocation The location of the endif directive. |
| IfLoc "(file):(line):(col)" SourceLocation The location of the if directive. |
| ============== ================================================== ============================== ==================================== |
| |
| Example::: |
| |
| - Callback: Endif |
| Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2" |
| IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2" |
| |
| Building pp-trace |
| ================= |
| |
| To build from source: |
| |
| 1. Read `Getting Started with the LLVM System`_ and `Clang Tools |
| Documentation`_ for information on getting sources for LLVM, Clang, and |
| Clang Extra Tools. |
| |
| 2. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give |
| directions for how to build. With sources all checked out into the |
| right place the LLVM build will build Clang Extra Tools and their |
| dependencies automatically. |
| |
| * If using CMake, you can also use the ``pp-trace`` target to build |
| just the pp-trace tool and its dependencies. |
| |
| .. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html |
| .. _Building LLVM with CMake: https://llvm.org/docs/CMake.html |
| .. _Clang Tools Documentation: https://clang.llvm.org/docs/ClangTools.html |
