2401llvm,合并clang语法树
ASTImporter:合并ClangAST
ASTImporter类是Clang的核心库AST库的一部分.它导入一个ASTContext的节点到另一个ASTContext中.
这里,假设你对ClangAST有基本了解.如果你想了解有关AST结构的更多信息,见ClangAST简介.匹配ClangAST在此.
介绍
ASTContext包含长期有的,可在文件的整个分析语义过程中引用的AST节点(如类型和声明).有时,最好使用多个ASTContext.
如,想在同一个Clang工具中,解析多个不同的文件.如果可像解析每个文件产生一个AST一样的,查看生成的AST集,就会很方便.
ASTImporter提供了可从一个ASTContext复制声明或类型到另一个ASTContext的方法.从中导入的环境叫"从"环境或源环境;
而"到"环境或目标环境为导入进的环境.
ASTImporter库的现有用户,是交叉翻译单元(CTU)静态分析和LLDB式解析器.如果在另一个,(TU)翻译单元中找到函数定义,则CTU静态分析导入函数定义.
这样,分析就可突破单个TU限制.LLDB的式命令解析用户定义的式,为其创建一个ASTContext,然后从从调试信息(DWARF等)的AST导入中获得缺失定义.
导入算法
导入一个AST节点,会复制该节点到目标ASTContext中.为什么必须复制节点,而不能插入该节点指针到目标环境中呢?一个原因是"from"环境可能比"to"环境更长久.
此外,如果节点有相同地址,ClangAST会认为节点(或节点的某些属性)是等效的!
导入算法必须确保不同翻译单元中,结构等效的节点,不会在合并的AST中重复.如,如果在两个翻译单元中,包含向量模板(#include)的定义,则合并的AST应该只有一个代表模板的节点.
此外,必须发现(ODR)一个定义规则的违规行为.如,如果两个翻译单元中,有相同名字的类定义,但其中一个定义包含不同数量的字段.
因此,要查找现有定义,然后检查这些节点上的结构等价性.以下伪代码演示了导入机制的底层:
//导入的伪代码(!):
ErrorOrDecl Import(Decl *FromD) {
Decl *ToDecl = nullptr;
Found声明List = 用FromD相同名,在`to`环境中查找所有声明
for (auto FoundDecl : Found声明List) {
if (StructurallyEquivalent声明(FoundDecl, FromD)) {
ToDecl = FoundDecl;
Mark FromD as imported;
break;
} else {
Report ODR violation;
return error;
}
}
if (Found声明List is empty) {
导入依赖声明及to声明的类型
ToDecl = 在`to`环境创建新AST;
Mark FromD as imported;
}
return ToDecl;
}
如果两个AST节点在结构上是等效的,则它们是等效的.
1,内置类型和引用相同类型,如int和int在结构上是等价的,
2,函数类型及其所有参数在结构上有等效类型,
3,记录类型及其所有字段(按其定义顺序)有相同的标识名和结构上等效的类型,
4,变量或函数声明,且有相同标识名,且它们的类型在结构上是等效的.
可把定义结构等价类似地扩展到模板.
应用接口
创建一个使用ASTImporter类的工具!首先,从虚文件构建两个AST;虚文件的内容是从串字面合成的:
std::unique_ptr<ASTUnit> ToUnit = buildASTFromCode("", "to.cc"); //空文件
std::unique_ptr<ASTUnit> FromUnit = buildASTFromCode(
R"(
class MyClass {
int m1;
int m2;
};
)",
"from.cc");
第一个AST对应("to")为空的目标环境,第二个AST对应源("from")环境.接着,定义一个匹配"from"环境中的MyClass的匹配器:
auto Matcher = cxxRecordDecl(hasName("MyClass"));
auto *From = getFirstDecl<CXXRecordDecl>(Matcher, FromUnit);
现在创建导入器并导入:
ASTImporter Importer(ToUnit->getASTContext(), ToUnit->getFileManager(), FromUnit->getASTContext(), FromUnit->getFileManager(), /*`MinimalImport=`*/true);
llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
Import调用返回llvm::Expected,因此,必须检查是否有错误.细节,见错误处理文档.
if (!ImportedOrErr) {
llvm::Error Err = ImportedOrErr.takeError();
llvm::errs() << "ERROR: " << Err << "\n";
consumeError(std::move(Err));
return 1;
}
如果正确,则可得到底层值.此例中,打印"to"环境的AST.
Decl *Imported = *ImportedOrErr;
Imported->getTranslationUnitDecl()->dump();
因为在导入器的构造器中,设置了最小导入,因此(一旦运行测试工具)AST不包含成员声明.
要想得到成员,所以,用ImportDefinition复制MyClass的整个定义到"to"环境中.然后再次转储AST.
if (llvm::Error Err = Importer.ImportDefinition(From)) {
llvm::errs() << "ERROR: " << Err << "\n";
consumeError(std::move(Err));
return 1;
}
llvm::errs() << "Imported definition.\n";
Imported->getTranslationUnitDecl()->dump();
这一次,AST也包含成员了.
如果把导入器设置为执行"正常"(非最小)导入,则可省去调用ImportDefinition.
ASTImporter Importer( .... /*`MinimalImport=`*/false);
用正常导入时,会正常导入所有依赖声明.但是,在最小导入下,会不带定义的导入依赖声明,如果稍后需要,必须为每个声明导入它们的定义.
放在一起:
#include "clang/AST/ASTImporter.h"
#include "clang/ASTMatchers/ASTMatchFinder.h"
#include "clang/ASTMatchers/ASTMatchers.h"
#include "clang/Tooling/Tooling.h"
using namespace clang;
using namespace tooling;
using namespace ast_matchers;
template <typename Node, typename Matcher>
Node *getFirstDecl(Matcher M, const std::unique_ptr<ASTUnit> &Unit) {
auto MB = M.bind("bindStr"); //把`待匹配节点`绑定到`串键`.
auto MatchRes = match(MB, Unit->getASTContext());
//至少应该有一个匹配.
assert(MatchRes.size() >= 1);
//取第一个`匹配`及绑定节点.
Node *Result =
const_cast<Node *>(MatchRes[0].template getNodeAs<Node>("bindStr"));
assert(Result);
return Result;
}
int main() {
std::unique_ptr<ASTUnit> ToUnit = buildASTFromCode("", "to.cc");
std::unique_ptr<ASTUnit> FromUnit = buildASTFromCode(
R"(
class MyClass {
int m1;
int m2;
};
)",
"from.cc");
auto Matcher = cxxRecordDecl(hasName("MyClass"));
auto *From = getFirstDecl<CXXRecordDecl>(Matcher, FromUnit);
ASTImporter Importer(ToUnit->getASTContext(), ToUnit->getFileManager(), FromUnit->getASTContext(), FromUnit->getFileManager(), /*`MinimalImport=`*/true);
llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
if (!ImportedOrErr) {
llvm::Error Err = ImportedOrErr.takeError();
llvm::errs() << "ERROR: " << Err << "\n";
consumeError(std::move(Err));
return 1;
}
Decl *Imported = *ImportedOrErr;
Imported->getTranslationUnitDecl()->dump();
if (llvm::Error Err = Importer.ImportDefinition(From)) {
llvm::errs() << "ERROR: " << Err << "\n";
consumeError(std::move(Err));
return 1;
}
llvm::errs() << "Imported definition.\n";
Imported->getTranslationUnitDecl()->dump();
return 0;
};
假定clang/tools有构建和链接说明,在此扩展CMakeLists.txt:
add_clang_executable(astimporter-demo ASTImporterDemo.cpp)
clang_target_link_libraries(astimporter-demo
PRIVATE
LLVMSupport
clangAST
clangASTMatchers
clangBasic
clangFrontend
clangSerialization
clangTooling
)
然后,可构建并执行新工具.
$ ninja astimporter-demo && ./bin/astimporter-demo
导入过程中的错误
一般,源或目标环境都包含声明的定义.但是,有时,两个环境都定义了给定符号.如果这些定义不同,则就有名字冲突,在C++中,叫做ODR(一个定义规则)违规.
修改之前编写的工具,并用冲突定义试导入ClassTemplateSpecializationDecl:
int main() {
std::unique_ptr<ASTUnit> ToUnit = buildASTFromCode(
R"(
//主模板
template
struct X {};
//显式特化
template<>
struct X { int i; };
)" ,
"to.cc");
ToUnit->enableSourceFileDiagnostics();
std::unique_ptr<ASTUnit> FromUnit = buildASTFromCode(
R"(
//主模板
template
struct X {};
//显式特化
template<>
struct X { int i2; };
//字段不匹配:^^
)" ,
"from.cc");
FromUnit->enableSourceFileDiagnostics();
auto Matcher = classTemplateSpecializationDecl(hasName("X"));
auto *From = getFirstDecl<ClassTemplateSpecializationDecl>(Matcher, FromUnit);
auto *To = getFirstDecl<ClassTemplateSpecializationDecl>(Matcher, ToUnit);
ASTImporter Importer(ToUnit->getASTContext(), ToUnit->getFileManager(), FromUnit->getASTContext(), FromUnit->getFileManager(), /*`MinimalImport=`*/false);
llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
if (!ImportedOrErr) {
llvm::Error Err = ImportedOrErr.takeError();
llvm::errs() << "ERROR: " << Err << "\n";
consumeError(std::move(Err));
To->getTranslationUnitDecl()->dump();
return 1;
}
return 0;
};
运行该工具时,会收到以下警告:
`to.cc:7:14:`警告:`"X" `类型在不同的翻译单元中有不兼容的定义`[-Wodr]`
`构X<int>{inti;`
^
`to.cc:7:27:`注意:此处的`字段名`叫`"i"`
`构X<int>{inti;`
^
`from.cc:7:27:`注意:此处的`字段名`叫`"i2"`
`structX<int>{inti2;`
^
注意,因为这些诊断,必须在ASTUnit对象上调用enableSourceFileDiagnostics.
因为无法导入指定的(From)声明,因此返回值中出现错误.AST不包含冲突定义,因此只剩下原始AST.
错误传播
如果在导入给定节点前,有必须先导入的依赖节点,则把与依赖关系关联的导入错误传播到依赖节点.修改前例并导入FieldDecl而不是ClassTemplateSpecializationDecl.
auto Matcher = fieldDecl(hasName("i2"));
auto *From = getFirstDecl<FieldDecl>(Matcher, FromUnit);
本例中,可见(getImportDeclErrorIfAny)错误不仅是字段,也与特化相关联:
llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
if (!ImportedOrErr) {
llvm::Error Err = ImportedOrErr.takeError();
consumeError(std::move(Err));
//检查是否也按错误标记`ClassTemplateSpecializationDecl`.
auto *FromSpec = getFirstDecl<ClassTemplateSpecializationDecl>(
classTemplateSpecializationDecl(hasName("X")), FromUnit);
assert(Importer.getImportDeclErrorIfAny(FromSpec));
//顺便,也为`FieldDecl`设置错误.
assert(Importer.getImportDeclErrorIfAny(From));
return 1;
}
污染的AST
可能会在导入依赖节点时,发现错误.但是,那时,已创建了依赖项.这时,不会从"to"环境中删除现有的错误节点,而是关联一个错误到该节点.
用另一个Y类来扩展前例.此类在"to"环境中有前向定义,但在"from"环境中定义它.要想导入定义,但它包含一个类型与"to"环境中的类型冲突的成员:
std::unique_ptr<ASTUnit> ToUnit = buildASTFromCode(
R"(
//主模板
template
struct X {};
//显式特化
template<>
struct X { int i; };
class Y;
)" ,
"to.cc");
ToUnit->enableSourceFileDiagnostics();
std::unique_ptr<ASTUnit> FromUnit = buildASTFromCode(
R"(
//主模板
template
struct X {};
//显式特化
template<>
struct X { int i2; };
//字段不匹配:^^
class Y { void f() { X xi; } };
)" ,
"from.cc");
FromUnit->enableSourceFileDiagnostics();
auto Matcher = cxxRecordDecl(hasName("Y"));
auto *From = getFirstDecl<CXXRecordDecl>(Matcher, FromUnit);
auto *To = getFirstDecl<CXXRecordDecl>(Matcher, ToUnit);
这一次,为ASTImporterSharedState创建一个拥有"to"环境关联错误的shared_ptr.注意,可能会有几个不同的ASTImporter对象,从不同的"from"环境导入,但导入到相同的"to"环境中;
它们应共享相同的ASTImporterSharedState.注意,必须包含相应的ASTImporterSharedState.h头文件.
auto ImporterState = std::make_shared<ASTImporterSharedState>();
ASTImporter Importer(ToUnit->getASTContext(), ToUnit->getFileManager(), FromUnit->getASTContext(), FromUnit->getFileManager(), /*`MinimalImport=`*/false, ImporterState);
llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
if (!ImportedOrErr) {
llvm::Error Err = ImportedOrErr.takeError();
consumeError(std::move(Err));
//...但是已创建`节点`.
auto *ToYDef = getFirstDecl<CXXRecordDecl>(
cxxRecordDecl(hasName("Y"), isDefinition()), ToUnit);
ToYDef->dump();
//在共享状态下,已为`"ToYDef"`设置了错误.
Optional<ASTImportError> OptErr =
ImporterState->getImportDeclErrorIfAny(ToYDef);
assert(OptErr);
return 1;
}
如果看一下AST,则可见创建了带定义的Decl,但缺少字段.
不会删除错误节点,因为当错误识别时,再删除节点为时已晚,可能会有对AST中已有节点的其他引用.
这与ClangAST的整体设计原则一致:ClangAST节点(类型,声明,语句,式等)一般按创建后不变设计.
因此,ASTImporter库的用户,应总是在目标环境中,检查待检查节点是否有相关错误.建议跳过有关联错误节点的处理.
使用-ast-merge的Clang前端操作
-ast-merge命令行开关,可用来从给定的表示源环境的序化AST文件合并.有此开关时,会把源环境的每个顶级AST节点都合并到目标环境中.
如果合并成功,则为声明调用ASTConsumer::HandleTopLevelDecl.这导致可在扩展的AST上执行原始前端操作.
C示例
考虑以下三个文件:
//bar.h
#ifndef BAR_H
#define BAR_H
int bar();
#endif /*`BAR_H`*/
//`bar.c`
#include "bar.h"
int bar() {
return 41;
}
//`main.c`
#include "bar.h"
int main() {
return bar();
}
为两个源文件生成AST文件:
$ clang -cc1 -emit-pch -o bar.ast bar.c
$ clang -cc1 -emit-pch -o main.ast main.c
然后,如果只考虑bar()函数,检查一下合并AST会怎样:
$ clang -cc1 -ast-merge bar.ast -ast-merge main.ast /dev/null -ast-dump
可检查函数的原型和它的定义是否合并到同一个再声明链中.更重要的是,还合并了第三个原型声明到链中.
函数的合并方式是,如果原型引用相同类型,则添加原型到再声明链中,但只能有一个定义.
前两个声明是bar.ast,第三个声明是main.ast.
现在,从合并的AST创建一个目标文件:
$ clang -cc1 -ast-merge bar.ast -ast-merge main.ast /dev/null -emit-obj -o main.o
Next, we may call the linker and execute the created binary file.
$ clang -o a.out main.o
$ ./a.out
$ echo $
41
$
C++示例
在C++时,生成AST文件及调用前端方式有点不同.假设有这三个文件:
//`foo.h`
#ifndef FOO_H
#define FOO_H
struct foo {
virtual int fun();
};
#endif /*`FOO_H`*/
//`foo.cpp`
#include "foo.h"
int foo::fun() {
return 42;
}
//`main.cpp`
#include "foo.h"
int main() {
return foo().fun();
}
生成AST文件,合并它们,创建可执行文件,然后运行它:
$ clang++ -x c++-header -o foo.ast foo.cpp
$ clang++ -x c++-header -o main.ast main.cpp
$ clang++ -cc1 -x c++ -ast-merge foo.ast -ast-merge main.ast /dev/null -ast-dump
$ clang++ -cc1 -x c++ -ast-merge foo.ast -ast-merge main.ast /dev/null -emit-obj -o main.o
$ clang++ -o a.out main.o
$ ./a.out
$ echo $
42
$