+ +

LibTooling

LibTooling is a library to support writing standalone tools based on +Clang. This document will provide a basic walkthrough of how to write +a tool using LibTooling.

+ + +

Introduction

+ + +

Tools built with LibTooling, like Clang Plugins, run FrontendActions over +code. +In this tutorial, we'll demonstrate the different ways of running clang's +SyntaxOnlyAction, which runs a quick syntax check, over a bunch of +code.

+ + +

Parsing a code snippet in memory.

+ + +

If you ever wanted to run a FrontendAction over some sample code, for example +to unit test parts of the Clang AST, runToolOnCode is what you looked for. Let +me give you an example: +

+  #include "clang/Tooling/Tooling.h"
+
+  TEST(runToolOnCode, CanSyntaxCheckCode) {
+    // runToolOnCode returns whether the action was correctly run over the
+    // given code.
+    EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
+  }
+

+ + +

Writing a standalone tool.

+ + +

Once you unit tested your FrontendAction to the point where it cannot +possibly break, it's time to create a standalone tool. For a standalone tool +to run clang, it first needs to figure out what command line arguments to use +for a specified file. To that end we create a CompilationDatabase.

+ +

Creating a compilation database.

CompilationDatabase provides static factory functions to help with parsing +compile commands from a build directory or the command line. The following code +allows for both explicit specification of a compile command line, as well as +retrieving the compile commands lines from a database. +

+int main(int argc, const char **argv) {
+  // First, try to create a fixed compile command database from the command line
+  // arguments.
+  llvm::OwningPtr<CompilationDatabase> Compilations(
+    FixedCompilationDatabase::loadFromCommandLine(argc, argv));
+
+  // Next, use normal llvm command line parsing to get the tool specific
+  // parameters.
+  cl::ParseCommandLineOptions(argc, argv);
+
+  if (!Compilations) {
+    // In case the user did not specify the compile command line via positional
+    // command line arguments after "--", try to load the compile commands from
+    // a database in the specified build directory.
+    std::string ErrorMessage;
+    Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath,
+                                                              ErrorMessage));
+
+    // If there is still no valid compile command database, we don't know how
+    // to run the tool.
+    if (!Compilations)
+      llvm::report_fatal_error(ErrorMessage);
+  }
+...
+}
+

+ +

Creating and running a ClangTool.

Once we have a CompilationDatabase, we can create a ClangTool and run our +FrontendAction over some code. For example, to run the SyntaxOnlyAction over +the files "a.cc" and "b.cc" one would write: +

+  // A clang tool can run over a number of sources in the same process...
+  std::vector<std::string> Sources;
+  Sources.push_back("a.cc");
+  Sources.push_back("b.cc");
+
+  // We hand the CompilationDatabase we created and the sources to run over into
+  // the tool constructor.
+  ClangTool Tool(*Compilations, Sources);
+
+  // The ClangTool needs a new FrontendAction for each translation unit we run
+  // on. Thus, it takes a FrontendActionFactory as parameter. To create a
+  // FrontendActionFactory from a given FrontendAction type, we call
+  // newFrontendActionFactory<clang::SyntaxOnlyAction>().
+  int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
+

+ +

Putting it together - the first tool.

Now we combine the two previous steps into our first real tool. This example +tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp. +

+  #include "llvm/Support/CommandLine.h"
+  #include "clang/Frontend/FrontendActions.h"
+  #include "clang/Tooling/CompilationDatabase.h"
+  #include "clang/Tooling/Tooling.h"
+
+  using namespace clang::tooling;
+  using namespace llvm;
+
+  cl::opt<std::string> BuildPath(
+    cl::Positional,
+    cl::desc("<build-path>"));
+
+  cl::list<std::string> SourcePaths(
+    cl::Positional,
+    cl::desc("<source0> [... <sourceN>]"),
+    cl::OneOrMore);
+
+  int main(int argc, const char **argv) {
+    llvm::OwningPtr<CompilationDatabase> Compilations(
+      FixedCompilationDatabase::loadFromCommandLine(argc, argv));
+    cl::ParseCommandLineOptions(argc, argv);
+    if (!Compilations) {
+      std::string ErrorMessage;
+      Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath,
+                                                                ErrorMessage));
+      if (!Compilations)
+        llvm::report_fatal_error(ErrorMessage);
+    }
+    ClangTool Tool(*Compilations, SourcePaths);
+    return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
+  }
+

+ +

Running the tool on some code.

When you check out and build clang, clang-check is already built and +available to you in bin/clang-check inside your build directory.

You can run clang-check on a file in the llvm repository by specifying +all the needed parameters after a "--" separator: +

+  $ 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
+

+ +

As an alternative, you can also configure cmake to output a compile command +database into its build directory: +

+  # Alternatively to calling cmake, use ccmake, toggle to advanced mode and
+  # set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
+  $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
+

+This creates a file called compile_commands.json in the build directory. Now +you can run clang-check over files in the project by specifying the build path +as first argument and some source files as further positional arguments: +

+  $ cd /path/to/source/llvm
+  $ export BD=/path/to/build/llvm
+  $ $BD/bin/clang-check $BD tools/clang/tools/clang-check/ClangCheck.cpp
+

+ +