blob: b7f7c7b0462fad41e1e4387e2c843dbbf9bee824 [file] [log] [blame]
Daniel Jasper6d5b57a2013-01-09 21:49:28 +00001========
2Overview
3========
Sean Silva93ca0212012-12-13 01:10:46 +00004
5Clang Tools are standalone command line (and potentially GUI) tools
Daniel Jasper6d5b57a2013-01-09 21:49:28 +00006designed for use by C++ developers who are already using and enjoying
Sean Silva93ca0212012-12-13 01:10:46 +00007Clang as their compiler. These tools provide developer-oriented
8functionality such as fast syntax checking, automatic formatting,
9refactoring, etc.
10
11Only a couple of the most basic and fundamental tools are kept in the
12primary Clang Subversion project. The rest of the tools are kept in a
13side-project so that developers who don't want or need to build them
14don't. If you want to get access to the extra Clang Tools repository,
15simply check it out into the tools tree of your Clang checkout and
16follow the usual process for building and working with a combined
17LLVM/Clang checkout:
18
19- With Subversion:
20
21 - ``cd llvm/tools/clang/tools``
Sean Silvae30561d2013-01-02 12:40:31 +000022 - ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra``
Sean Silva93ca0212012-12-13 01:10:46 +000023
24- Or with Git:
25
26 - ``cd llvm/tools/clang/tools``
27 - ``git clone http://llvm.org/git/clang-tools-extra.git extra``
28
29This document describes a high-level overview of the organization of
30Clang Tools within the project as well as giving an introduction to some
31of the more important tools. However, it should be noted that this
32document is currently focused on Clang and Clang Tool developers, not on
33end users of these tools.
34
35Clang Tools Organization
36========================
37
38Clang Tools are CLI or GUI programs that are intended to be directly
39used by C++ developers. That is they are *not* primarily for use by
40Clang developers, although they are hopefully useful to C++ developers
41who happen to work on Clang, and we try to actively dogfood their
42functionality. They are developed in three components: the underlying
43infrastructure for building a standalone tool based on Clang, core
44shared logic used by many different tools in the form of refactoring and
45rewriting libraries, and the tools themselves.
46
47The underlying infrastructure for Clang Tools is the
48:doc:`LibTooling <LibTooling>` platform. See its documentation for much
49more detailed information about how this infrastructure works. The
50common refactoring and rewriting toolkit-style library is also part of
51LibTooling organizationally.
52
53A few Clang Tools are developed along side the core Clang libraries as
54examples and test cases of fundamental functionality. However, most of
55the tools are developed in a side repository to provide easy separation
56from the core libraries. We intentionally do not support public
57libraries in the side repository, as we want to carefully review and
58find good APIs for libraries as they are lifted out of a few tools and
59into the core Clang library set.
60
61Regardless of which repository Clang Tools' code resides in, the
62development process and practices for all Clang Tools are exactly those
63of Clang itself. They are entirely within the Clang *project*,
64regardless of the version control scheme.
65
66Core Clang Tools
67================
68
69The core set of Clang tools that are within the main repository are
Sean Silva7298c0b2013-03-03 17:07:35 +000070tools that very specifically complement, and allow use and testing of
Sean Silva93ca0212012-12-13 01:10:46 +000071*Clang* specific functionality.
72
73``clang-check``
Sean Silva9987ce22013-01-07 21:46:47 +000074---------------
Sean Silva93ca0212012-12-13 01:10:46 +000075
Daniel Jasper6d5b57a2013-01-09 21:49:28 +000076:doc:`ClangCheck` combines the LibTooling framework for running a
77Clang tool with the basic Clang diagnostics by syntax checking specific files
78in a fast, command line interface. It can also accept flags to re-display the
79diagnostics in different formats with different flags, suitable for use driving
80an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
81fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for
82instructions on how to setup and used `clang-check`.
Sean Silva93ca0212012-12-13 01:10:46 +000083
Daniel Jasper6d5b57a2013-01-09 21:49:28 +000084``clang-format``
85~~~~~~~~~~~~~~~~
86
87Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool
88<ClangFormat>` with the goal of automatically reformatting C++ sources files
Dmitri Gribenko73189fb2013-01-09 22:22:51 +000089according to configurable style guides. To do so, clang-format uses Clang's
90``Lexer`` to transform an input file into a token stream and then changes all
91the whitespace around those tokens. The goal is for clang-format to both serve
Daniel Jasper6d5b57a2013-01-09 21:49:28 +000092both as a user tool (ideally with powerful IDE integrations) and part of other
93refactoring tools, e.g. to do a reformatting of all the lines changed during a
94renaming.
Sean Silva93ca0212012-12-13 01:10:46 +000095
Dmitri Gribenko68c41462013-01-22 19:22:22 +000096``cpp11-migrate``
97~~~~~~~~~~~~~~~~~
98``cpp11-migrate`` migrates C++ code to use C++11 features where appropriate.
99Currently it can:
100
101* convert loops to range-based for loops;
102
103* convert null pointer constants (like ``NULL`` or ``0``) to C++11 ``nullptr``.
104
Sean Silva93ca0212012-12-13 01:10:46 +0000105Extra Clang Tools
106=================
107
108As various categories of Clang Tools are added to the extra repository,
109they'll be tracked here. The focus of this documentation is on the scope
110and features of the tools for other tool developers; each tool should
111provide its own user-focused documentation.
Dmitri Gribenko2626a2a2013-01-06 20:19:09 +0000112
113Ideas for new Tools
Daniel Dunbare3fc0972013-01-07 20:43:06 +0000114===================
Dmitri Gribenko2626a2a2013-01-06 20:19:09 +0000115
Dmitri Gribenko2626a2a2013-01-06 20:19:09 +0000116* C++ cast conversion tool. Will convert C-style casts (``(type) value``) to
117 appropriate C++ cast (``static_cast``, ``const_cast`` or
118 ``reinterpret_cast``).
Dmitri Gribenko824ed0c2013-02-24 19:04:36 +0000119* Non-member ``begin()`` and ``end()`` conversion tool. Will convert
120 ``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where
121 ``foo`` is a standard container. We could also detect similar patterns for
122 arrays.
Dmitri Gribenkod0d6f642013-03-03 17:54:36 +0000123* ``tr1`` removal tool. Will migrate source code from using TR1 library
124 features to C++11 library. For example:
125
126 .. code-block:: c++
127
128 #include <tr1/unordered_map>
129 int main()
130 {
131 std::tr1::unordered_map <int, int> ma;
132 std::cout << ma.size () << std::endl;
133 return 0;
134 }
135
136 should be rewritten to:
137
138 .. code-block:: c++
139
140 #include <unordered_map>
141 int main()
142 {
143 std::unordered_map <int, int> ma;
144 std::cout << ma.size () << std::endl;
145 return 0;
146 }
147
Dmitri Gribenko0a8dead2013-02-25 01:14:45 +0000148* A tool to remove ``auto``. Will convert ``auto`` to an explicit type or add
149 comments with deduced types. The motivation is that there are developers
150 that don't want to use ``auto`` because they are afraid that they might lose
151 control over their code.
Dmitri Gribenko2626a2a2013-01-06 20:19:09 +0000152