2012-05-25 01:07:18 +08:00
< !DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
< html >
< head >
< title > Clang Plugins< / title >
< link type = "text/css" rel = "stylesheet" href = "../menu.css" >
< link type = "text/css" rel = "stylesheet" href = "../content.css" >
< / head >
< body >
2012-05-25 01:16:23 +08:00
<!-- #include virtual="../menu.html.incl" -->
2012-05-25 01:07:18 +08:00
< div id = "content" >
< h1 > Clang Plugins< / h1 >
< p > Clang Plugins make it possible to run extra user defined actions during
a compilation. This document will provide a basic walkthrough of how to write
and run a Clang Plugin.< / p >
<!-- ======================================================================= -->
< h2 id = "intro" > Introduction< / h2 >
<!-- ======================================================================= -->
< p > Clang Plugins run FrontendActions over code. See the
< a href = "RAVFrontendAction.html" > FrontendAction tutorial< / a > on how to write a
FrontendAction using the RecursiveASTVisitor. In this tutorial, we'll
demonstrate how to write a simple clang plugin.
< / p >
<!-- ======================================================================= -->
< h2 id = "pluginactions" > Writing a PluginASTAction< / h2 >
<!-- ======================================================================= -->
< p > The main difference from writing normal FrontendActions is that you can
handle plugin command line options. The
PluginASTAction base class declares a ParseArgs method which you have to
implement in your plugin.
< / p >
< pre >
bool ParseArgs(const CompilerInstance & CI,
const std::vector< std::string>& args) {
for (unsigned i = 0, e = args.size(); i != e; ++i) {
if (args[i] == "-some-arg") {
// Handle the command line argument.
}
}
return true;
}
< / pre >
<!-- ======================================================================= -->
< h2 id = "registerplugin" > Registering a plugin< / h2 >
<!-- ======================================================================= -->
< p > A plugin is loaded from a dynamic library at runtime by the compiler. To register
a plugin in a library, use FrontendPluginRegistry::Add:< / p >
< pre >
static FrontendPluginRegistry::Add< MyPlugin> X("my-plugin-name", "my plugin description");
< / pre >
<!-- ======================================================================= -->
< h2 id = "example" > Putting it all together< / h2 >
<!-- ======================================================================= -->
< p > Let's look at an example plugin that prints top-level function names.
This example is also checked into the clang repository; please also take a look
at the latest < a href = "http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup" > checked in version of PrintFunctionNames.cpp< / a > .< / p >
< pre >
#include "clang/Frontend/FrontendPluginRegistry.h"
#include "clang/AST/ASTConsumer.h"
#include "clang/AST/AST.h"
#include "clang/Frontend/CompilerInstance.h"
#include "llvm/Support/raw_ostream.h"
using namespace clang;
namespace {
class PrintFunctionsConsumer : public ASTConsumer {
public:
virtual bool HandleTopLevelDecl(DeclGroupRef DG) {
for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) {
const Decl *D = *i;
if (const NamedDecl *ND = dyn_cast< NamedDecl>(D))
llvm::errs() < < "top-level-decl: \"" < < ND->getNameAsString() < < "\"\n";
}
return true;
}
};
class PrintFunctionNamesAction : public PluginASTAction {
protected:
ASTConsumer *CreateASTConsumer(CompilerInstance & CI, llvm::StringRef) {
return new PrintFunctionsConsumer();
}
bool ParseArgs(const CompilerInstance & CI,
const std::vector< std::string>& args) {
for (unsigned i = 0, e = args.size(); i != e; ++i) {
llvm::errs() < < "PrintFunctionNames arg = " < < args[i] < < "\n";
// Example error handling.
if (args[i] == "-an-error") {
DiagnosticsEngine & D = CI.getDiagnostics();
unsigned DiagID = D.getCustomDiagID(
DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'");
D.Report(DiagID);
return false;
}
}
if (args.size() & & args[0] == "help")
PrintHelp(llvm::errs());
return true;
}
void PrintHelp(llvm::raw_ostream& ros) {
ros < < "Help for PrintFunctionNames plugin goes here\n";
}
};
}
static FrontendPluginRegistry::Add< PrintFunctionNamesAction>
X("print-fns", "print function names");
< / pre >
<!-- ======================================================================= -->
< h2 id = "running" > Running the plugin< / h2 >
<!-- ======================================================================= -->
< p > To run a plugin, the dynamic library containing the plugin registry must be
loaded via the -load command line option. This will load all plugins that are
registered, and you can select the plugins to run by specifying the -plugin
option. Additional parameters for the plugins can be passed with -plugin-arg-< plugin-name>.< / p >
< p > Note that those options must reach clang's cc1 process. There are two
ways to do so:< / p >
< ul >
< li >
Directly call the parsing process by using the -cc1 option; this has the
downside of not configuring the default header search paths, so you'll need to
specify the full system path configuration on the command line.
< / li >
< li >
Use clang as usual, but prefix all arguments to the cc1 process with -Xclang.
< / li >
< / ul >
< p > For example, to run the print-function-names plugin over a source file in clang,
first build the plugin, and then call clang with the plugin from the source tree:< / p >
< pre >
$ export BD=/path/to/build/directory
$ (cd $BD & & make PrintFunctionNames )
$ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
-D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
-I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
-Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
-plugin -Xclang print-fns
< / pre >
< p > Also see the print-function-name plugin example's
< a href = "http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup" > README< / a > < / p >
< / div >
< / body >
< / html >
