pp-trace 用户手册¶

pp-trace 是一个独立的工具，用于跟踪预处理器活动。它也用作 Clang 的 PPCallbacks 接口的测试。它通过 Clang 预处理器运行给定的源文件，显示从 PPCallbacks 派生中重写的回调函数中选定的信息。输出采用高级 YAML 格式，在 pp-trace 输出格式中描述。

pp-trace 使用方法¶

命令行格式¶

pp-trace [<pp-trace-options>] <source-file> [-- <front-end-options>]

<pp-trace-options> 是 pp-trace 特定选项的占位符，这些选项在下面的命令行选项中描述。

<source-file> 指定要通过预处理器运行的源文件。

<front-end-options> 是常规 Clang 编译器选项的占位符，它必须位于 <source-file> 之后。

命令行选项¶

-callbacks <comma-separated-globs>¶

此选项指定一个用逗号分隔的列表，该列表描述了应跟踪的回调列表。通配符按出现顺序进行处理。正通配符将匹配的回调添加到集合中，负通配符（带有 ‘-’ 前缀的那些）将回调从集合中移除。

FileChanged
FileSkipped
InclusionDirective
moduleImport
EndOfMainFile
Ident
PragmaDirective
PragmaComment
PragmaDetectMismatch
PragmaDebug
PragmaMessage
PragmaDiagnosticPush
PragmaDiagnosticPop
PragmaDiagnostic
PragmaOpenCLExtension
PragmaWarning
PragmaWarningPush
PragmaWarningPop
MacroExpands
MacroDefined
MacroUndefined
Defined
SourceRangeSkipped
If
Elif
Ifdef
Ifndef
Else
Endif

-output <output-file>¶: 默认情况下，pp-trace 将跟踪信息输出到标准输出。使用此选项将跟踪信息输出到文件。

pp-trace 输出格式¶

pp-trace 输出格式化为 YAML。有关一般 YAML 信息，请参见 https://yaml.org/。它被组织成一系列关于回调调用的信息，包括回调名称和参数信息，例如：

---
- Callback: Name
  Argument1: Value1
  Argument2: Value2
(etc.)
...

使用真实数据：

---
- Callback: FileChanged
  Loc: "c:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"
  Reason: EnterFile
  FileType: C_User
  PrevFID: (invalid)
  (etc.)
- Callback: FileChanged
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:5:1"
  Reason: ExitFile
  FileType: C_User
  PrevFID: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/Input/Level1B.h"
- Callback: EndOfMainFile
...

除一种情况（MacroDirective）外，所有“Argument” 标量都与相应 PPCallbacks 回调函数中的参数同名。

回调详细信息¶

以下部分描述了每个回调的目的和输出格式。

单击节标题中的回调名称以查看该回调的 Doxygen 文档。

参数描述表描述了显示的回调参数信息。

在大多数（但并非全部）情况下，参数名称与回调函数参数的名称相同。

参数值语法字段描述了将为参数值显示的值。它使用了一种混合了字面量和符号表示的临时表示。枚举成员符号将显示为实际枚举成员，形式为 (member1|member2|…)。括号中的名称可以表示所描述值的占位符，或者令人困惑的是，它也可能是字面量，例如 (null)，表示空指针。位置仅用引号表示，以避免与文档生成器混淆。

Clang C++ 类型字段是回调函数声明中的类型。

描述描述了参数或为其显示的内容。

请注意，在某些情况下，例如当结构指针是参数值时，只会显示一些关键成员或成员来表示该值，而不是尝试显示结构的所有成员。

FileChanged 回调¶

当预处理器进入或退出文件时，FileChanged 会被调用，包括正在编译的顶级文件以及任何 #include 指令。它还会在系统头 pragma 或文件内部重命名时被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Reason	(EnterFile\|ExitFile\|SystemHeaderPragma\|RenameFile)	PPCallbacks::FileChangeReason	更改原因。
FileType	(C_User\|C_System\|C_ExternCSystem)	SrcMgr::CharacteristicKind	包含类型。
PrevFID	((file)\|(invalid))	FileID	上一个文件（如果有）。

示例：

- Callback: FileChanged
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1"
  Reason: EnterFile
  FileType: C_User
  PrevFID: (invalid)

FileSkipped 回调¶

当源文件因头文件保护优化而被跳过时，FileSkipped 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
ParentFile	(“(file)” 或 (null))	const FileEntry	#包含跳过文件的那个文件。
FilenameTok	(token)	const Token	ParentFile 中指示跳过文件的那个标记。
FileType	(C_User\|C_System\|C_ExternCSystem)	SrcMgr::CharacteristicKind	文件类型。

示例：

- Callback: FileSkipped
  ParentFile: "/path/filename.h"
  FilenameTok: "filename.h"
  FileType: C_User

InclusionDirective 回调¶

当任何类型的包含指令（#include</code>，#import</code> 等）被处理时，InclusionDirective 会被调用，无论包含是否真正会导致包含。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
HashLoc	“(file):(line):(col)”	SourceLocation	开始包含指令的 ‘#’ 的位置。
IncludeTok	(token)	const Token	指示包含指令类型的标记，例如 ‘include’ 或 ‘import’。
FileName	“(file)”	StringRef	要包含的文件的名称，如源代码中所写。
IsAngled	(true\|false)	bool	文件名是否用尖括号括起来；否则，它用引号括起来。
FilenameRange	“(file)”	CharSourceRange	书面文件名的引号或尖括号的字符范围。
File	“(file)”	const FileEntry	可能被此包含指令包含的实际文件。
SearchPath	“(path)”	StringRef	包含用于在文件系统中查找文件的搜索路径。
RelativePath	“(path)”	StringRef	相对于 SearchPath 的路径，在该路径下找到包含文件。
Imported	((module name)\|(null))	const Module	模块，当包含指令自动转换为模块导入时，否则为 null。

示例：

- Callback: InclusionDirective
  HashLoc: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:4:1"
  IncludeTok: include
  FileName: "Input/Level1B.h"
  IsAngled: false
  FilenameRange: "Input/Level1B.h"
  File: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/Input/Level1B.h"
  SearchPath: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace"
  RelativePath: "Input/Level1B.h"
  Imported: (null)

moduleImport 回调¶

当存在显式模块导入语法时，moduleImport 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
ImportLoc	“(file):(line):(col)”	SourceLocation	导入指令标记的位置。
Path	“(path)”	ModuleIdPath	模块“路径”的标识符（及其位置）。
Imported	((module name)\|(null))	const Module	导入的模块；如果导入失败，则可能为空。

示例：

- Callback: moduleImport
  ImportLoc: "d:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:2"
  Path: [{Name: Level1B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:9"}, {Name: Level2B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:17"}]
  Imported: Level2B

EndOfMainFile 回调¶

当到达主文件末尾时，EndOfMainFile 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
(无参数)

示例：

- Callback: EndOfMainFile

Ident 回调¶

当读取 #ident 或 #sccs 指令时，Ident 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
str	(name)	const std::string	指令的文本。

示例：

- Callback: Ident
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-ident.cpp:3:1"
  str: "$Id$"

PragmaDirective 回调¶

当开始读取任何 pragma 指令时，PragmaDirective 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Introducer	(PIK_HashPragma\|PIK__Pragma\|PIK___pragma)	PragmaIntroducerKind	pragma 指令的类型。

示例：

- Callback: PragmaDirective
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  Introducer: PIK_HashPragma

PragmaComment 回调¶

当读取 #pragma comment 指令时，PragmaComment 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Kind	((name)\|(null))	const IdentifierInfo	注释类型符号。
Str	(message directive)	const std::string	注释消息指令。

示例：

- Callback: PragmaComment
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  Kind: library
  Str: kernel32.lib

PragmaDetectMismatch 回调¶

当读取 #pragma detect_mismatch 指令时，PragmaDetectMismatch 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Name	“(name)”	const std::string	名称。
Value	(string)	const std::string	值。

示例：

- Callback: PragmaDetectMismatch
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  Name: name
  Value: value

PragmaDebug 回调¶

当读取 #pragma clang __debug 指令时，PragmaDebug 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
DebugType	(string)	StringRef	指示调试消息的类型。

示例：

- Callback: PragmaDebug
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  DebugType: warning

PragmaMessage 回调¶

当读取 #pragma message 指令时，PragmaMessage 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Namespace	(name)	StringRef	消息指令的命名空间。
Kind	(PMK_Message\|PMK_Warning\|PMK_Error)	PPCallbacks::PragmaMessageKind	消息指令的类型。
Str	(string)	StringRef	消息指令的文本。

示例：

- Callback: PragmaMessage
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  Namespace: "GCC"
  Kind: PMK_Message
  Str: The message text.

PragmaDiagnosticPush 回调¶

当读取 #pragma gcc diagnostic push 指令时，PragmaDiagnosticPush 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Namespace	(name)	StringRef	命名空间名称。

示例：

- Callback: PragmaDiagnosticPush
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  Namespace: "GCC"

PragmaDiagnosticPop 回调¶

当读取 #pragma gcc diagnostic pop 指令时，PragmaDiagnosticPop 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Namespace	(name)	StringRef	命名空间名称。

示例：

- Callback: PragmaDiagnosticPop
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  Namespace: "GCC"

PragmaDiagnostic 回调¶

当读取 #pragma gcc diagnostic 指令时，PragmaDiagnostic 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Namespace	(name)	StringRef	命名空间名称。
mapping	(0\|MAP_IGNORE\|MAP_WARNING\|MAP_ERROR\|MAP_FATAL)	diag::Severity	映射类型。
Str	(string)	StringRef	警告/错误名称。

示例：

- Callback: PragmaDiagnostic
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  Namespace: "GCC"
  mapping: MAP_WARNING
  Str: WarningName

PragmaOpenCLExtension 回调¶

当 OpenCL 扩展被禁用或使用 pragma 启用时，PragmaOpenCLExtension 会被调用。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
NameLoc	“(file):(line):(col)”	SourceLocation	名称的位置。
Name	(name)	const IdentifierInfo	名称符号。
StateLoc	“(file):(line):(col)”	SourceLocation	状态的位置。
State	(1\|0)	unsigned	启用/禁用状态。

示例：

- Callback: PragmaOpenCLExtension
  NameLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:10"
  Name: Name
  StateLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:18"
  State: 1

PragmaWarning 回调¶

当读取 #pragma warning 指令时，将调用 PragmaWarning。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
WarningSpec	(string)	StringRef	警告说明符。
Ids	[(number)[, …]]	ArrayRef<int>	警告编号。

示例：

- Callback: PragmaWarning
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  WarningSpec: disable
  Ids: 1,2,3

PragmaWarningPush 回调¶

当读取 #pragma warning(push) 指令时，将调用 PragmaWarningPush。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
Level	(number)	int	警告级别。

示例：

- Callback: PragmaWarningPush
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"
  Level: 1

PragmaWarningPop 回调¶

当读取 #pragma warning(pop) 指令时，将调用 PragmaWarningPop。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。

示例：

- Callback: PragmaWarningPop
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1"

MacroExpands 回调¶

当在找到宏调用时调用 ::HandleMacroExpandedIdentifier 时，将调用 MacroExpands。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
MacroNameTok	(token)	const Token	宏名称标记。
MacroDirective	(MD_Define\|MD_Undefine\|MD_Visibility)	const MacroDirective	来自 MacroDirective 结构的宏指令类型。
Range	[“(file):(line):(col)”, “(file):(line):(col)”]	SourceRange	扩展的源范围。
Args	[(name)\|(number)\|<(token name)>[, …]]	const MacroArgs	参数标记。名称和数字是文字，其他所有内容均采用 '‘ tokenName ’>’ 格式。

示例：

- Callback: MacroExpands
  MacroNameTok: X_IMPL
  MacroDirective: MD_Define
  Range: [(nonfile), (nonfile)]
  Args: [a <plus> y, b]

MacroDefined 回调¶

当看到宏定义时，将调用 MacroDefined。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
MacroNameTok	(token)	const Token	宏名称标记。
MacroDirective	(MD_Define\|MD_Undefine\|MD_Visibility)	const MacroDirective	来自 MacroDirective 结构的宏指令类型。

示例：

- Callback: MacroDefined
  MacroNameTok: X_IMPL
  MacroDirective: MD_Define

MacroUndefined 回调¶

当看到宏 #undef 时，将调用 MacroUndefined。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
MacroNameTok	(token)	const Token	宏名称标记。
MacroDirective	(MD_Define\|MD_Undefine\|MD_Visibility)	const MacroDirective	来自 MacroDirective 结构的宏指令类型。

示例：

- Callback: MacroUndefined
  MacroNameTok: X_IMPL
  MacroDirective: MD_Define

Defined 回调¶

当看到 'defined' 运算符时，将调用 Defined。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
MacroNameTok	(token)	const Token	宏名称标记。
MacroDirective	(MD_Define\|MD_Undefine\|MD_Visibility)	const MacroDirective	来自 MacroDirective 结构的宏指令类型。
Range	[“(file):(line):(col)”, “(file):(line):(col)”]	SourceRange	指令的源范围。

示例：

- Callback: Defined
  MacroNameTok: MACRO
  MacroDirective: (null)
  Range: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:5", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:19"]

SourceRangeSkipped 回调¶

当跳过源范围时，将调用 SourceRangeSkipped。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Range	[“(file):(line):(col)”, “(file):(line):(col)”]	SourceRange	跳过的源范围。

示例：

- Callback: SourceRangeSkipped
  Range: [":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2", ":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:2"]

If 回调¶

当看到 #if 时，将调用 If。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
ConditionRange	[“(file):(line):(col)”, “(file):(line):(col)”]	SourceRange	条件的源范围。
ConditionValue	(true\|false)	bool	条件值。

示例：

- Callback: If
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"
  ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:1"]
  ConditionValue: false

Elif 回调¶

当看到 #elif 时，将调用 Elif。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
ConditionRange	[“(file):(line):(col)”, “(file):(line):(col)”]	SourceRange	条件的源范围。
ConditionValue	(true\|false)	bool	条件值。
IfLoc	“(file):(line):(col)”	SourceLocation	指令的位置。

示例：

- Callback: Elif
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
  ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:11:1"]
  ConditionValue: false
  IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"

Ifdef 回调¶

当看到 #ifdef 时，将调用 Ifdef。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
MacroNameTok	(token)	const Token	宏名称标记。
MacroDirective	(MD_Define\|MD_Undefine\|MD_Visibility)	const MacroDirective	来自 MacroDirective 结构的宏指令类型。

示例：

- Callback: Ifdef
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"
  MacroNameTok: MACRO
  MacroDirective: MD_Define

Ifndef 回调¶

当看到 #ifndef 时，将调用 Ifndef。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	指令的位置。
MacroNameTok	(token)	const Token	宏名称标记。
MacroDirective	(MD_Define\|MD_Undefine\|MD_Visibility)	const MacroDirective	来自 MacroDirective 结构的宏指令类型。

示例：

- Callback: Ifndef
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1"
  MacroNameTok: MACRO
  MacroDirective: MD_Define

Else 回调¶

当看到 #else 时，将调用 Else。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	else 指令的位置。
IfLoc	“(file):(line):(col)”	SourceLocation	if 指令的位置。

示例：

- Callback: Else
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
  IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"

Endif 回调¶

当看到 #endif 时，将调用 Endif。

参数描述

参数名称	参数值语法	Clang C++ 类型	描述
Loc	“(file):(line):(col)”	SourceLocation	endif 指令的位置。
IfLoc	“(file):(line):(col)”	SourceLocation	if 指令的位置。

示例：

- Callback: Endif
  Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2"
  IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2"

构建 pp-trace¶

要从源代码构建

阅读 LLVM 系统入门和 Clang 工具文档以获取有关获取 LLVM、Clang 和 Clang 额外工具的源代码的信息。
LLVM 系统入门和使用 CMake 构建 LLVM 提供了构建说明。如果所有源代码都已签出到正确的位置，则 LLVM 构建将自动构建 Clang 额外工具及其依赖项。
- 如果使用 CMake，您还可以使用 pp-trace 目标仅构建 pp-trace 工具及其依赖项。