Adds a tutorial for how to write clang plugins.

llvm-svn: 157396
2012-05-24 17:07:18 +00:00 · 2012-05-24 17:07:18 +00:00 · 3115e3d171
parent b482260748
commit 3115e3d171
1 changed files with 167 additions and 0 deletions
--- a/clang/docs/ClangPlugins.html
+++ b/clang/docs/ClangPlugins.html
@ -0,0 +1,167 @@
+<!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>
+<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 &amp;CI,
+                 const std::vector&lt;std::string>&amp; 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&lt;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&lt;NamedDecl>(D))
+        llvm::errs() &lt;&lt; "top-level-decl: \"" &lt;&lt; ND->getNameAsString() &lt;&lt; "\"\n";
+    }
+
+    return true;
+  }
+};
+
+class PrintFunctionNamesAction : public PluginASTAction {
+protected:
+  ASTConsumer *CreateASTConsumer(CompilerInstance &amp;CI, llvm::StringRef) {
+    return new PrintFunctionsConsumer();
+  }
+
+  bool ParseArgs(const CompilerInstance &amp;CI,
+                 const std::vector&lt;std::string>&amp; args) {
+    for (unsigned i = 0, e = args.size(); i != e; ++i) {
+      llvm::errs() &lt;&lt; "PrintFunctionNames arg = " &lt;&lt; args[i] &lt;&lt; "\n";
+
+      // Example error handling.
+      if (args[i] == "-an-error") {
+        DiagnosticsEngine &amp;D = CI.getDiagnostics();
+        unsigned DiagID = D.getCustomDiagID(
+          DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'");
+        D.Report(DiagID);
+        return false;
+      }
+    }
+    if (args.size() &amp;&amp; args[0] == "help")
+      PrintHelp(llvm::errs());
+
+    return true;
+  }
+  void PrintHelp(llvm::raw_ostream&amp; ros) {
+    ros &lt;&lt; "Help for PrintFunctionNames plugin goes here\n";
+  }
+
+};
+
+}
+
+static FrontendPluginRegistry::Add&lt;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-&lt;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 &amp;&amp; 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>
+