/usr/share/doc/clang-3.5-doc/html/ClangPlugins.html is in clang-3.5-doc 1:3.5~svn201651-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Clang Plugins — Clang 3.5 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.5',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="top" title="Clang 3.5 documentation" href="index.html" />
<link rel="next" title="How to write RecursiveASTVisitor based ASTFrontendActions." href="RAVFrontendAction.html" />
<link rel="prev" title="LibFormat" href="LibFormat.html" />
</head>
<body>
<div class="header"><h1 class="heading"><a href="index.html">
<span>Clang 3.5 documentation</span></a></h1>
<h2 class="heading"><span>Clang Plugins</span></h2>
</div>
<div class="topnav">
<p>
«  <a href="LibFormat.html">LibFormat</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="RAVFrontendAction.html">How to write RecursiveASTVisitor based ASTFrontendActions.</a>  »
</p>
</div>
<div class="content">
<div class="section" id="clang-plugins">
<h1>Clang Plugins<a class="headerlink" href="#clang-plugins" title="Permalink to this headline">¶</a></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>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>Clang Plugins run FrontendActions over code. See the <a class="reference internal" href="RAVFrontendAction.html"><em>FrontendAction
tutorial</em></a> on how to write a <tt class="docutils literal"><span class="pre">FrontendAction</span></tt> using the
<tt class="docutils literal"><span class="pre">RecursiveASTVisitor</span></tt>. In this tutorial, we’ll demonstrate how to write a
simple clang plugin.</p>
</div>
<div class="section" id="writing-a-pluginastaction">
<h2>Writing a <tt class="docutils literal"><span class="pre">PluginASTAction</span></tt><a class="headerlink" href="#writing-a-pluginastaction" title="Permalink to this headline">¶</a></h2>
<p>The main difference from writing normal <tt class="docutils literal"><span class="pre">FrontendActions</span></tt> is that you can
handle plugin command line options. The <tt class="docutils literal"><span class="pre">PluginASTAction</span></tt> base class declares
a <tt class="docutils literal"><span class="pre">ParseArgs</span></tt> method which you have to implement in your plugin.</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="nf">ParseArgs</span><span class="p">(</span><span class="k">const</span> <span class="n">CompilerInstance</span> <span class="o">&</span><span class="n">CI</span><span class="p">,</span>
<span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">>&</span> <span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">e</span> <span class="o">=</span> <span class="n">args</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">==</span> <span class="s">"-some-arg"</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// Handle the command line argument.</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="registering-a-plugin">
<h2>Registering a plugin<a class="headerlink" href="#registering-a-plugin" title="Permalink to this headline">¶</a></h2>
<p>A plugin is loaded from a dynamic library at runtime by the compiler. To
register a plugin in a library, use <tt class="docutils literal"><span class="pre">FrontendPluginRegistry::Add<></span></tt>:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">FrontendPluginRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyPlugin</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="s">"my-plugin-name"</span><span class="p">,</span> <span class="s">"my plugin description"</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="putting-it-all-together">
<h2>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Permalink to this headline">¶</a></h2>
<p>Let’s look at an example plugin that prints top-level function names. This
example is checked into the clang repository; please take a look at
the <a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup">latest version of PrintFunctionNames.cpp</a>.</p>
</div>
<div class="section" id="running-the-plugin">
<h2>Running the plugin<a class="headerlink" href="#running-the-plugin" title="Permalink to this headline">¶</a></h2>
<p>To run a plugin, the dynamic library containing the plugin registry must be
loaded via the <em class="xref std std-option">-load</em> command line option. This will load all plugins
that are registered, and you can select the plugins to run by specifying the
<em class="xref std std-option">-plugin</em> option. Additional parameters for the plugins can be passed with
<em class="xref std std-option">-plugin-arg-</em>.</p>
<p>Note that those options must reach clang’s cc1 process. There are two
ways to do so:</p>
<ul class="simple">
<li>Directly call the parsing process by using the <em class="xref std std-option">-cc1</em> 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
<em class="xref std std-option">-Xclang</em>.</li>
</ul>
<p>For example, to run the <tt class="docutils literal"><span class="pre">print-function-names</span></tt> plugin over a source file in
clang, first build the plugin, and then call clang with the plugin from the
source tree:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">export </span><span class="nv">BD</span><span class="o">=</span>/path/to/build/directory
<span class="gp">$</span> <span class="o">(</span><span class="nb">cd</span> <span class="nv">$BD</span> <span class="o">&&</span> make PrintFunctionNames <span class="o">)</span>
<span class="gp">$</span> clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS <span class="se">\</span>
<span class="go"> -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \</span>
<span class="go"> -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \</span>
<span class="go"> tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \</span>
<span class="go"> -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \</span>
<span class="go"> -plugin -Xclang print-fns</span>
</pre></div>
</div>
<p>Also see the print-function-name plugin example’s
<a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup">README</a></p>
</div>
</div>
</div>
<div class="bottomnav">
<p>
«  <a href="LibFormat.html">LibFormat</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="RAVFrontendAction.html">How to write RecursiveASTVisitor based ASTFrontendActions.</a>  »
</p>
</div>
<div class="footer">
© Copyright 2007-2014, The Clang Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
|