[BuildLibcalls, Attrs] Support more variants of C++'s new, add attributes for C+...
[lldb.git] / clang-tools-extra / docs / pp-trace.rst
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 purpose 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