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