/usr/share/doc/clang-3.9-doc/html/ClangPlugins.html is in clang-3.9-doc 1:3.9.1-19ubuntu1.
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 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 | <!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.9 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.9',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.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" role="banner"><h1 class="heading"><a href="index.html">
<span>Clang 3.9 documentation</span></a></h1>
<h2 class="heading"><span>Clang Plugins</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<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"><span class="doc">FrontendAction
tutorial</span></a> on how to write a <code class="docutils literal"><span class="pre">FrontendAction</span></code> using the
<code class="docutils literal"><span class="pre">RecursiveASTVisitor</span></code>. 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 <code class="docutils literal"><span class="pre">PluginASTAction</span></code><a class="headerlink" href="#writing-a-pluginastaction" title="Permalink to this headline">¶</a></h2>
<p>The main difference from writing normal <code class="docutils literal"><span class="pre">FrontendActions</span></code> is that you can
handle plugin command line options. The <code class="docutils literal"><span class="pre">PluginASTAction</span></code> base class declares
a <code class="docutils literal"><span class="pre">ParseArgs</span></code> method which you have to implement in your plugin.</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><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 <code class="docutils literal"><span class="pre">FrontendPluginRegistry::Add<></span></code>:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><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="defining-pragmas">
<h2>Defining pragmas<a class="headerlink" href="#defining-pragmas" title="Permalink to this headline">¶</a></h2>
<p>Plugins can also define pragmas by declaring a <code class="docutils literal"><span class="pre">PragmaHandler</span></code> and
registering it using <code class="docutils literal"><span class="pre">PragmaHandlerRegistry::Add<></span></code>:</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="c1">// Define a pragma handler for #pragma example_pragma</span>
<span class="k">class</span> <span class="nc">ExamplePragmaHandler</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PragmaHandler</span> <span class="p">{</span>
<span class="k">public</span><span class="o">:</span>
<span class="n">ExamplePragmaHandler</span><span class="p">()</span> <span class="o">:</span> <span class="n">PragmaHandler</span><span class="p">(</span><span class="s">"example_pragma"</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
<span class="kt">void</span> <span class="n">HandlePragma</span><span class="p">(</span><span class="n">Preprocessor</span> <span class="o">&</span><span class="n">PP</span><span class="p">,</span> <span class="n">PragmaIntroducerKind</span> <span class="n">Introducer</span><span class="p">,</span>
<span class="n">Token</span> <span class="o">&</span><span class="n">PragmaTok</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// Handle the pragma</span>
<span class="p">}</span>
<span class="p">};</span>
<span class="k">static</span> <span class="n">PragmaHandlerRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">ExamplePragmaHandler</span><span class="o">></span> <span class="n">Y</span><span class="p">(</span><span class="s">"example_pragma"</span><span class="p">,</span><span class="s">"example pragma 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>
<div class="section" id="using-the-cc1-command-line">
<h3>Using the cc1 command line<a class="headerlink" href="#using-the-cc1-command-line" title="Permalink to this headline">¶</a></h3>
<p>To run a plugin, the dynamic library containing the plugin registry must be
loaded via the <cite>-load</cite> command line option. This will load all plugins
that are registered, and you can select the plugins to run by specifying the
<cite>-plugin</cite> option. Additional parameters for the plugins can be passed with
<cite>-plugin-arg-<plugin-name></cite>.</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 <cite>-cc1</cite> 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
<cite>-Xclang</cite>.</li>
</ul>
<p>For example, to run the <code class="docutils literal"><span class="pre">print-function-names</span></code> 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></span><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>
-D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE <span class="se">\</span>
-I<span class="nv">$BD</span>/tools/clang/include -Itools/clang/include -I<span class="nv">$BD</span>/include -Iinclude <span class="se">\</span>
tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only <span class="se">\</span>
-Xclang -load -Xclang <span class="nv">$BD</span>/lib/PrintFunctionNames.so -Xclang <span class="se">\</span>
-plugin -Xclang print-fns
</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 class="section" id="using-the-clang-command-line">
<h3>Using the clang command line<a class="headerlink" href="#using-the-clang-command-line" title="Permalink to this headline">¶</a></h3>
<p>Using <cite>-fplugin=plugin</cite> on the clang command line passes the plugin
through as an argument to <cite>-load</cite> on the cc1 command line. If the plugin
class implements the <code class="docutils literal"><span class="pre">getActionType</span></code> method then the plugin is run
automatically. For example, to run the plugin automatically after the main AST
action (i.e. the same as using <cite>-add-plugin</cite>):</p>
<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="c1">// Automatically run the plugin after the main AST action</span>
<span class="n">PluginASTAction</span><span class="o">::</span><span class="n">ActionType</span> <span class="n">getActionType</span><span class="p">()</span> <span class="k">override</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">AddAfterMainAction</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<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" role="contentinfo">
© Copyright 2007-2017, The Clang Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.5.
</div>
</body>
</html>
|