[cfe-dev] [PATCH] LibTooling docs

Erik Verbruggen erikjv at me.com
Fri Apr 20 09:41:18 PDT 2012 

Sometimes you have this "err... Oops moment when your son manages to hit the send-button on your touch device when you are checking the to/cc of a list... :-/

-- Erik


On 20 apr. 2012, at 18:37, Erik Verbruggen <erikjv at me.com> wrote:

> I re-read Chris' tutorials, and they are all active. So ignore that. :-) All your changes look fine! 
> 
> Off the record: I am also a non-native English speaker (as I assume you are, correct me if I am wrong), but I learned that apparently "basically" is abused so much that some people will question if you really know what you are talking about :-/ And unfortunately, in my experience, I am afraid they are right. I do not doubt you knowledge, but it is something I had to learn "the hard way".
> 
> -- Erik
> 
> 
> On 20 apr. 2012, at 10:30, Manuel Klimek <klimek at google.com> wrote:
> 
>> On Thu, Apr 19, 2012 at 5:42 PM, Erik Verbruggen <erikjv at me.com> wrote:
>>> 
>>> On Apr 19, 2012, at 16:36, Manuel Klimek wrote:
>>> 
>>>> Please find a first version attached.
>>>> 
>>>> The next step is a short intro on how to write a FrontendAction, which
>>>> is common to clang plugins and libtooling, and thus I thought I'd put
>>>> it into a separate doc.
>>> 
>>> 
>>> Comments inline
>>> 
>>> Cheers,
>>> Erik.
>>> 
>>> 
>>>> 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
>>> 
>>> Don't use "we". "This tutorial demonstrates ..." is better. Same for constructs like "we'll": in colloquial communication that is okay, but otherwise you should use "we will". The only kind-of-exception is "don't" or any use of "n't" for "not".
>> 
>> I disagree with the idea that we need to be overly formal in those
>> tutorials. Now, if you think that some of my bad grammar makes the
>> sentences hard to understand / read, I'm happy to change, but I don't
>> think that a style that's more dry makes it easier to read...
>> 
>>>> running clang's SyntaxOnlyAction, which basically runs a quick syntax check, over a bunch of code.
>>> 
>>> Try not to use "basically", as it might sound like you just don't know what really happens. Now in all honesty, I have no better way of phrasing this sentence...
>> 
>> Done (just removed the "basically" :)
>> 
>>>> Parsing a code snippet in memory...
>>> 
>>> Ellipsis? Why not a dot/full-stop like in other headers?
>> 
>> Done.
>> 
>>>> 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
>>> 
>>> "it is"
>>> 
>>>> standalone tool to run clang, it first needs to figure out what command line arguments it needs for a specified file. To that end we want to create a CompilationDatabase.
>>> 
>>> ".. we want to ..." could be read as one-of-the-ways-to-do-it. Is it? Otherwise just state: "To that end a CompilationDatabase is needed."
>> 
>> I try to avoid passive voice wherever possible. Changed to "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. To allow both explicit specification of a compile command line, as well as retrieving the compile command lines from a database, we can write:
>>> 
>>> "To allow....can write:" -> "The following code allows for both explicit specification of a compile command line, as well as retrieving the compile commands lines from a database."
>> 
>> Done.
>> 
>>>> 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.
>>>> 
>>>> One we have a CompilationDatabase, we can create a ClangTool and run our FrontendAction over some code. For example, to run the
>>> 
>>> OnCe (note the C :-) ). But better: "Once the CompilationDatabase is created, ...."
>> 
>> Again, my strong preference for active voice trumps the idea of more formality.
>> 
>>>> SyntaxOnlyAction over the files "a.cc" and "b.cc" one would write:
>>> 
>>> "... one would write:" -> "the following code-snippet can be used:"
>>> 
>>>>  // 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.
>>> 
>>> "To combine the two..."
>> 
>> Not sure where this would go?
>> 
>>>>  #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 try 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
>> 
>> Thanks for the review!
>> 
>> /Manuel
>> <LibTooling.html>

More information about the cfe-dev mailing list