# 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

### Linking.

Please note that this presents the linking requirements at the time of this writing. For the most up-to-date information, look at one of the tools' Makefiles (for example clang-check/Makefile).

To link a binary using the tooling infrastructure, link in the following libraries:

- Tooling
- Frontend
- Driver
- Serialization
- Parse
- Sema
- Analysis
- Edit
- AST
- Lex
- Basic