1 ============= 2 Clang Plugins 3 ============= 4 5 Clang Plugins make it possible to run extra user defined actions during a 6 compilation. This document will provide a basic walkthrough of how to write and 7 run a Clang Plugin. 8 9 Introduction 10 ============ 11 12 Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction 13 tutorial <RAVFrontendAction>` on how to write a ``FrontendAction`` using the 14 ``RecursiveASTVisitor``. In this tutorial, we'll demonstrate how to write a 15 simple clang plugin. 16 17 Writing a ``PluginASTAction`` 18 ============================= 19 20 The main difference from writing normal ``FrontendActions`` is that you can 21 handle plugin command line options. The ``PluginASTAction`` base class declares 22 a ``ParseArgs`` method which you have to implement in your plugin. 23 24 .. code-block:: c++ 25 26 bool ParseArgs(const CompilerInstance &CI, 27 const std::vector<std::string>& args) { 28 for (unsigned i = 0, e = args.size(); i != e; ++i) { 29 if (args[i] == "-some-arg") { 30 // Handle the command line argument. 31 } 32 } 33 return true; 34 } 35 36 Registering a plugin 37 ==================== 38 39 A plugin is loaded from a dynamic library at runtime by the compiler. To 40 register a plugin in a library, use ``FrontendPluginRegistry::Add<>``: 41 42 .. code-block:: c++ 43 44 static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description"); 45 46 Putting it all together 47 ======================= 48 49 Let's look at an example plugin that prints top-level function names. This 50 example is also checked into the clang repository; please also take a look at 51 the latest `checked in version of PrintFunctionNames.cpp 52 <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_. 53 54 .. code-block:: c++ 55 56 #include "clang/Frontend/FrontendPluginRegistry.h" 57 #include "clang/AST/ASTConsumer.h" 58 #include "clang/AST/AST.h" 59 #include "clang/Frontend/CompilerInstance.h" 60 #include "llvm/Support/raw_ostream.h" 61 using namespace clang; 62 63 namespace { 64 65 class PrintFunctionsConsumer : public ASTConsumer { 66 public: 67 virtual bool HandleTopLevelDecl(DeclGroupRef DG) { 68 for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) { 69 const Decl *D = *i; 70 if (const NamedDecl *ND = dyn_cast<NamedDecl>(D)) 71 llvm::errs() << "top-level-decl: \"" << ND->getNameAsString() << "\"\n"; 72 } 73 74 return true; 75 } 76 }; 77 78 class PrintFunctionNamesAction : public PluginASTAction { 79 protected: 80 ASTConsumer *CreateASTConsumer(CompilerInstance &CI, llvm::StringRef) { 81 return new PrintFunctionsConsumer(); 82 } 83 84 bool ParseArgs(const CompilerInstance &CI, 85 const std::vector<std::string>& args) { 86 for (unsigned i = 0, e = args.size(); i != e; ++i) { 87 llvm::errs() << "PrintFunctionNames arg = " << args[i] << "\n"; 88 89 // Example error handling. 90 if (args[i] == "-an-error") { 91 DiagnosticsEngine &D = CI.getDiagnostics(); 92 unsigned DiagID = D.getCustomDiagID( 93 DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'"); 94 D.Report(DiagID); 95 return false; 96 } 97 } 98 if (args.size() && args[0] == "help") 99 PrintHelp(llvm::errs()); 100 101 return true; 102 } 103 void PrintHelp(llvm::raw_ostream& ros) { 104 ros << "Help for PrintFunctionNames plugin goes here\n"; 105 } 106 107 }; 108 109 } 110 111 static FrontendPluginRegistry::Add<PrintFunctionNamesAction> 112 X("print-fns", "print function names"); 113 114 Running the plugin 115 ================== 116 117 To run a plugin, the dynamic library containing the plugin registry must be 118 loaded via the :option:`-load` command line option. This will load all plugins 119 that are registered, and you can select the plugins to run by specifying the 120 :option:`-plugin` option. Additional parameters for the plugins can be passed with 121 :option:`-plugin-arg-<plugin-name>`. 122 123 Note that those options must reach clang's cc1 process. There are two 124 ways to do so: 125 126 * Directly call the parsing process by using the :option:`-cc1` option; this 127 has the downside of not configuring the default header search paths, so 128 you'll need to specify the full system path configuration on the command 129 line. 130 * Use clang as usual, but prefix all arguments to the cc1 process with 131 :option:`-Xclang`. 132 133 For example, to run the ``print-function-names`` plugin over a source file in 134 clang, first build the plugin, and then call clang with the plugin from the 135 source tree: 136 137 .. code-block:: console 138 139 $ export BD=/path/to/build/directory 140 $ (cd $BD && make PrintFunctionNames ) 141 $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \ 142 -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \ 143 -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \ 144 tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \ 145 -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \ 146 -plugin -Xclang print-fns 147 148 Also see the print-function-name plugin example's 149 `README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_ 150 151
