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("
More help text...
");
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)这里.