Debian Codegraph @

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

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