Mercurial > hg > CbC > CbC_llvm

comparison clang-tools-extra/docs/pp-trace.rst @ 150:1d019706d866

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