LibTooling(库工具)
LibTooling是个支持基于Clang编写独立工具的库.
在此,为LLVM安装Clang工具
介绍
用LibTooling构建的工具(如Clang插件)通过代码运行FrontendActions.
这里演示运行Clang的快速检查一堆代码语法的SyntaxOnlyAction的不同方法.
解析内存中的代码片
如果想对,如对ClangAST的某些部分单元测试的代码运行FrontendAction,则runToolOnCode就是你找的.如:
#include "clang/Tooling/Tooling.h"
TEST(runToolOnCode, CanSyntaxCheckCode) {//`runToolOnCode`返回在给定代码上是否正确`操作`运行.EXPECT_TRUE(runToolOnCode(std::make_unique<clang::SyntaxOnlyAction>(), "class X {};"));
}
编写独立工具
一旦对FrontendAction运行了单元测试,使其不可中断,就可创建独立工具了.作为独立运行clang的工具,首先要确定要为指定文件使用哪些命令行参数.
为此,创建了一个编译数据库.有很多种创建编译数据库的方法,可根据命令行选项来支持所有这些方法.
CommonOptionsParser类,负责解析与编译数据库和输入相关的命令行参数,以便所有工具可共享实现.
解析常用工具选项
可从构建目录或命令行读取编译数据库.使用CommonOptionsParser可显式指定编译命令行,用-p命令行选项指定构建路径,及用源文件路径自动定位编译数据库.
#include "clang/Tooling/CommonOptionsParser.h"
#include "llvm/Support/CommandLine.h"
using namespace clang::tooling;
//对`所有命令行选项`,应用自定义分类,以便只显示他们.
static llvm::cl::OptionCategory MyToolCategory("my-tool options");
int main(int argc, const char **argv) {//`CommonOptionsParser`构造器解析参数,并创建`编译数据库`.如果出现错误,它终止程序.CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);//使用`OptionsParser.getCompilations()`和`OptionsParser.getSourcePathList()`提取`编译数据库`和输入文件路径列表.
}
创建并运行ClangTool
一旦有了编译数据库,就可创建一个ClangTool并在一些代码上运行FrontendAction.如,要对"a.cc"和"b.cc"文件运行SyntaxOnlyAction,可这样写:
//可在同一进程中运行多个源的`clang`工具.
std::vector<std::string> Sources;
Sources.push_back("a.cc");
Sources.push_back("b.cc");
//把创建的`编译数据库`和要运行的`源码`交给`工具构造器`.
ClangTool Tool(OptionsParser.getCompilations(), Sources);
//`ClangTool`要为运行的每个`翻译单元`提供一个新的`FrontendAction`.因此,它以`FrontendActionFactory`作为参数.
//要从给定的`FrontendAction`类型创建`FrontendActionFactory`,调用`newFrontendActionFactory<clang::SyntaxOnlyAction>()`.
int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
组合在一起,第一个工具
现在,合并前面两个步骤到第一个实际工具中.此例工具的更高级版本也签入到tools/clang-check/ClangCheck.cpp的clang树中.
//声明`clang::SyntaxOnlyAction`.
#include "clang/Frontend/FrontendActions.h"
#include "clang/Tooling/CommonOptionsParser.h"
#include "clang/Tooling/Tooling.h"
//声明`llvm::cl::extrahelp`.
#include "llvm/Support/CommandLine.h"using namespace clang::tooling;
using namespace llvm;
static cl::OptionCategory MyToolCategory("my-tool options");
static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
//之后可添加此指定工具的帮助消息.
static cl::extrahelp MoreHelp("\nMore help text...\n");
int main(int argc, const char **argv) {CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);ClangTool Tool(OptionsParser.getCompilations(), OptionsParser.getSourcePathList());return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
}
在某些代码上运行该工具
检出并构建clang时,已构建``clang-check,并在构建目录中的bin/clang-check中.
可通过在"--"分隔符后,指定``llvm仓库中的文件运行clang-check的所有必需参数:
$ cd /path/to/source/llvm
$ export BD=/path/to/build/llvm
$ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \-Itools/clang/include -I$BD/include -Iinclude \-Itools/clang/lib/Headers -c
或,还可按把编译命令数据库输出到其构建目录中,来配置cmake:
# 或从UI设置CMAKE_EXPORT_COMPILE_COMMANDS.
$ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
这在目录中创建叫compile_commands.json的文件.现在,你可通过按第一个参数指定构建路径,并按进一步的位置参数指定一些源文件,来对项目中的文件运行clang-check:
$ cd /path/to/source/llvm
$ export BD=/path/to/build/llvm
$ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
内置包含
Clang工具需要其内置头文件,并按Clang方式搜索它们.因此,默认在$(dirname/path/to/tool)/中查找内置头文件.
相对工具二进制文件的/lib/clang/3.3/include.对在构建clang-resource-headers后,从llvm的顶级二进制目录运行的工具,或如果该工具从clang二进制文件旁边的clang安装的二进制目录运行,则开箱即用.
提示:如果工具找不到stddef.h或类似头文件,请使用-v调用该工具并查看它所查找的搜索路径.
连接
有关要链接的库列表,请查看工具的CMake文件之一(如clang-check/CMakeList.txt)这里.
