diff options
Diffstat (limited to 'docs/ClangPlugins.html')
| -rw-r--r-- | docs/ClangPlugins.html | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/docs/ClangPlugins.html b/docs/ClangPlugins.html new file mode 100644 index 0000000..ed560fe --- /dev/null +++ b/docs/ClangPlugins.html @@ -0,0 +1,170 @@ +<!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> + +<!--#include virtual="../menu.html.incl"--> + +<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> + |
