/usr/share/doc/clang-3.6-doc/html/ClangTools.html is in clang-3.6-doc 1:3.6.2-3ubuntu2.
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 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 | <!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>Overview — Clang 3.6 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.6',
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="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="top" title="Clang 3.6 documentation" href="index.html" />
<link rel="next" title="ClangCheck" href="ClangCheck.html" />
<link rel="prev" title="JSON Compilation Database Format Specification" href="JSONCompilationDatabase.html" />
</head>
<body role="document">
<div class="header" role="banner"><h1 class="heading"><a href="index.html">
<span>Clang 3.6 documentation</span></a></h1>
<h2 class="heading"><span>Overview</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="ClangCheck.html">ClangCheck</a>  »
</p>
</div>
<div class="content">
<div class="section" id="overview">
<h1>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h1>
<p>Clang Tools are standalone command line (and potentially GUI) tools
designed for use by C++ developers who are already using and enjoying
Clang as their compiler. These tools provide developer-oriented
functionality such as fast syntax checking, automatic formatting,
refactoring, etc.</p>
<p>Only a couple of the most basic and fundamental tools are kept in the
primary Clang Subversion project. The rest of the tools are kept in a
side-project so that developers who don’t want or need to build them
don’t. If you want to get access to the extra Clang Tools repository,
simply check it out into the tools tree of your Clang checkout and
follow the usual process for building and working with a combined
LLVM/Clang checkout:</p>
<ul class="simple">
<li>With Subversion:<ul>
<li><code class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools/clang/tools</span></code></li>
<li><code class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/clang-tools-extra/trunk</span> <span class="pre">extra</span></code></li>
</ul>
</li>
<li>Or with Git:<ul>
<li><code class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools/clang/tools</span></code></li>
<li><code class="docutils literal"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">http://llvm.org/git/clang-tools-extra.git</span> <span class="pre">extra</span></code></li>
</ul>
</li>
</ul>
<p>This document describes a high-level overview of the organization of
Clang Tools within the project as well as giving an introduction to some
of the more important tools. However, it should be noted that this
document is currently focused on Clang and Clang Tool developers, not on
end users of these tools.</p>
<div class="section" id="clang-tools-organization">
<h2>Clang Tools Organization<a class="headerlink" href="#clang-tools-organization" title="Permalink to this headline">¶</a></h2>
<p>Clang Tools are CLI or GUI programs that are intended to be directly
used by C++ developers. That is they are <em>not</em> primarily for use by
Clang developers, although they are hopefully useful to C++ developers
who happen to work on Clang, and we try to actively dogfood their
functionality. They are developed in three components: the underlying
infrastructure for building a standalone tool based on Clang, core
shared logic used by many different tools in the form of refactoring and
rewriting libraries, and the tools themselves.</p>
<p>The underlying infrastructure for Clang Tools is the
<a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> platform. See its documentation for much
more detailed information about how this infrastructure works. The
common refactoring and rewriting toolkit-style library is also part of
LibTooling organizationally.</p>
<p>A few Clang Tools are developed along side the core Clang libraries as
examples and test cases of fundamental functionality. However, most of
the tools are developed in a side repository to provide easy separation
from the core libraries. We intentionally do not support public
libraries in the side repository, as we want to carefully review and
find good APIs for libraries as they are lifted out of a few tools and
into the core Clang library set.</p>
<p>Regardless of which repository Clang Tools’ code resides in, the
development process and practices for all Clang Tools are exactly those
of Clang itself. They are entirely within the Clang <em>project</em>,
regardless of the version control scheme.</p>
</div>
<div class="section" id="core-clang-tools">
<h2>Core Clang Tools<a class="headerlink" href="#core-clang-tools" title="Permalink to this headline">¶</a></h2>
<p>The core set of Clang tools that are within the main repository are
tools that very specifically complement, and allow use and testing of
<em>Clang</em> specific functionality.</p>
<div class="section" id="clang-check">
<h3><code class="docutils literal"><span class="pre">clang-check</span></code><a class="headerlink" href="#clang-check" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="ClangCheck.html"><em>ClangCheck</em></a> combines the LibTooling framework for running a
Clang tool with the basic Clang diagnostics by syntax checking specific files
in a fast, command line interface. It can also accept flags to re-display the
diagnostics in different formats with different flags, suitable for use driving
an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
fixit-hints offered by clang. See <a class="reference internal" href="HowToSetupToolingForLLVM.html"><em>How To Setup Clang Tooling For LLVM</em></a> for
instructions on how to setup and used <cite>clang-check</cite>.</p>
<div class="section" id="clang-format">
<h4><code class="docutils literal"><span class="pre">clang-format</span></code><a class="headerlink" href="#clang-format" title="Permalink to this headline">¶</a></h4>
<p>Clang-format is both a <a class="reference internal" href="LibFormat.html"><em>library</em></a> and a <a class="reference internal" href="ClangFormat.html"><em>stand-alone tool</em></a> with the goal of automatically reformatting C++ sources files
according to configurable style guides. To do so, clang-format uses Clang’s
<code class="docutils literal"><span class="pre">Lexer</span></code> to transform an input file into a token stream and then changes all
the whitespace around those tokens. The goal is for clang-format to serve both
as a user tool (ideally with powerful IDE integrations) and as part of other
refactoring tools, e.g. to do a reformatting of all the lines changed during a
renaming.</p>
</div>
<div class="section" id="clang-modernize">
<h4><code class="docutils literal"><span class="pre">clang-modernize</span></code><a class="headerlink" href="#clang-modernize" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal"><span class="pre">clang-modernize</span></code> migrates C++ code to use C++11 features where appropriate.
Currently it can:</p>
<ul class="simple">
<li>convert loops to range-based for loops;</li>
<li>convert null pointer constants (like <code class="docutils literal"><span class="pre">NULL</span></code> or <code class="docutils literal"><span class="pre">0</span></code>) to C++11 <code class="docutils literal"><span class="pre">nullptr</span></code>;</li>
<li>replace the type specifier in variable declarations with the <code class="docutils literal"><span class="pre">auto</span></code> type specifier;</li>
<li>add the <code class="docutils literal"><span class="pre">override</span></code> specifier to applicable member functions.</li>
</ul>
</div>
</div>
</div>
<div class="section" id="extra-clang-tools">
<h2>Extra Clang Tools<a class="headerlink" href="#extra-clang-tools" title="Permalink to this headline">¶</a></h2>
<p>As various categories of Clang Tools are added to the extra repository,
they’ll be tracked here. The focus of this documentation is on the scope
and features of the tools for other tool developers; each tool should
provide its own user-focused documentation.</p>
</div>
<div class="section" id="ideas-for-new-tools">
<h2>Ideas for new Tools<a class="headerlink" href="#ideas-for-new-tools" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first">C++ cast conversion tool. Will convert C-style casts (<code class="docutils literal"><span class="pre">(type)</span> <span class="pre">value</span></code>) to
appropriate C++ cast (<code class="docutils literal"><span class="pre">static_cast</span></code>, <code class="docutils literal"><span class="pre">const_cast</span></code> or
<code class="docutils literal"><span class="pre">reinterpret_cast</span></code>).</p>
</li>
<li><p class="first">Non-member <code class="docutils literal"><span class="pre">begin()</span></code> and <code class="docutils literal"><span class="pre">end()</span></code> conversion tool. Will convert
<code class="docutils literal"><span class="pre">foo.begin()</span></code> into <code class="docutils literal"><span class="pre">begin(foo)</span></code> and similarly for <code class="docutils literal"><span class="pre">end()</span></code>, where
<code class="docutils literal"><span class="pre">foo</span></code> is a standard container. We could also detect similar patterns for
arrays.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">make_shared</span></code> / <code class="docutils literal"><span class="pre">make_unique</span></code> conversion. Part of this transformation
can be incorporated into the <code class="docutils literal"><span class="pre">auto</span></code> transformation. Will convert</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="n">sp</span><span class="p">(</span><span class="k">new</span> <span class="n">Foo</span><span class="p">);</span>
<span class="n">std</span><span class="o">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="n">up</span><span class="p">(</span><span class="k">new</span> <span class="n">Foo</span><span class="p">);</span>
<span class="n">func</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span><span class="p">(</span><span class="k">new</span> <span class="n">Foo</span><span class="p">),</span> <span class="n">bar</span><span class="p">());</span>
</pre></div>
</div>
<p>into:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="k">auto</span> <span class="n">sp</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">make_shared</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span><span class="p">();</span>
<span class="k">auto</span> <span class="n">up</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">make_unique</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span><span class="p">();</span> <span class="c1">// In C++14 mode.</span>
<span class="c1">// This also affects correctness. For the cases where bar() throws,</span>
<span class="c1">// make_shared() is safe and the original code may leak.</span>
<span class="n">func</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_shared</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span><span class="p">(),</span> <span class="n">bar</span><span class="p">());</span>
</pre></div>
</div>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">tr1</span></code> removal tool. Will migrate source code from using TR1 library
features to C++11 library. For example:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include</span> <span class="cpf"><tr1/unordered_map></span><span class="cp"></span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span>
<span class="p">{</span>
<span class="n">std</span><span class="o">::</span><span class="n">tr1</span><span class="o">::</span><span class="n">unordered_map</span> <span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">></span> <span class="n">ma</span><span class="p">;</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">ma</span><span class="p">.</span><span class="n">size</span> <span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>should be rewritten to:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include</span> <span class="cpf"><unordered_map></span><span class="cp"></span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span>
<span class="p">{</span>
<span class="n">std</span><span class="o">::</span><span class="n">unordered_map</span> <span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">></span> <span class="n">ma</span><span class="p">;</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">ma</span><span class="p">.</span><span class="n">size</span> <span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><p class="first">A tool to remove <code class="docutils literal"><span class="pre">auto</span></code>. Will convert <code class="docutils literal"><span class="pre">auto</span></code> to an explicit type or add
comments with deduced types. The motivation is that there are developers
that don’t want to use <code class="docutils literal"><span class="pre">auto</span></code> because they are afraid that they might lose
control over their code.</p>
</li>
<li><p class="first">C++14: less verbose operator function objects (<a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm">N3421</a>).
For example:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">sort</span><span class="p">(</span><span class="n">v</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">v</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">greater</span><span class="o"><</span><span class="n">ValueType</span><span class="o">></span><span class="p">());</span>
</pre></div>
</div>
<p>should be rewritten to:</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="n">sort</span><span class="p">(</span><span class="n">v</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">v</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">greater</span><span class="o"><></span><span class="p">());</span>
</pre></div>
</div>
</li>
</ul>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="ClangCheck.html">ClangCheck</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2007-2014, The Clang Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.6.
</div>
</body>
</html>
|