[cfe-dev] [PATCH] LibTooling docs

Fri Apr 20 01:30:55 PDT 2012

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120420/ffc3d34e/attachment.html>