From 3115e3d1717af641d826fe2b596486b75181b1ae Mon Sep 17 00:00:00 2001 From: Manuel Klimek Date: Thu, 24 May 2012 17:07:18 +0000 Subject: [PATCH] Adds a tutorial for how to write clang plugins. llvm-svn: 157396 --- clang/docs/ClangPlugins.html | 167 +++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 clang/docs/ClangPlugins.html diff --git a/clang/docs/ClangPlugins.html b/clang/docs/ClangPlugins.html new file mode 100644 index 000000000000..d553a62fcfd3 --- /dev/null +++ b/clang/docs/ClangPlugins.html @@ -0,0 +1,167 @@ + + + +Clang Plugins + + + + +
+ +

Clang Plugins

+

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.

+ + +

Introduction

+ + +

Clang Plugins run FrontendActions over code. See the +FrontendAction tutorial on how to write a +FrontendAction using the RecursiveASTVisitor. In this tutorial, we'll +demonstrate how to write a simple clang plugin. +

+ + +

Writing a PluginASTAction

+ + +

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. +

+
+  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;
+  }
+
+ + +

Registering a plugin

+ + +

A plugin is loaded from a dynamic library at runtime by the compiler. To register +a plugin in a library, use FrontendPluginRegistry::Add:

+
+  static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description");
+
+ + +

Putting it all together

+ + +

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 checked in version of PrintFunctionNames.cpp.

+
+#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");
+
+ + +

Running the plugin

+ + +

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>.

+ +

Note that those options must reach clang's cc1 process. There are two +ways to do so:

+ +

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:

+
+  $ 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
+
+ +

Also see the print-function-name plugin example's +README

+ + + +
+ + +