docs/ClangPlugins.html - platform/external/clang - Git at Google

 <!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 &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>
	<!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>