1========
2Overview
3========
4
5Clang Tools are standalone command line (and potentially GUI) tools
6designed for use by C++ developers who are already using and enjoying
7Clang 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 tree. The rest of the tools are kept in a separate
13directory tree, `clang-tools-extra
14<https://github.com/llvm/llvm-project/tree/master/clang-tools-extra>`_.
15
16This document describes a high-level overview of the organization of
17Clang Tools within the project as well as giving an introduction to some
18of the more important tools. However, it should be noted that this
19document is currently focused on Clang and Clang Tool developers, not on
20end users of these tools.
21
22Clang Tools Organization
23========================
24
25Clang Tools are CLI or GUI programs that are intended to be directly
26used by C++ developers. That is they are *not* primarily for use by
27Clang developers, although they are hopefully useful to C++ developers
28who happen to work on Clang, and we try to actively dogfood their
29functionality. They are developed in three components: the underlying
30infrastructure for building a standalone tool based on Clang, core
31shared logic used by many different tools in the form of refactoring and
32rewriting libraries, and the tools themselves.
33
34The underlying infrastructure for Clang Tools is the
35:doc:`LibTooling <LibTooling>` platform. See its documentation for much
36more detailed information about how this infrastructure works. The
37common refactoring and rewriting toolkit-style library is also part of
38LibTooling organizationally.
39
40A few Clang Tools are developed along side the core Clang libraries as
41examples and test cases of fundamental functionality. However, most of
42the tools are developed in a side repository to provide easy separation
43from the core libraries. We intentionally do not support public
44libraries in the side repository, as we want to carefully review and
45find good APIs for libraries as they are lifted out of a few tools and
46into the core Clang library set.
47
48Regardless of which repository Clang Tools' code resides in, the
49development process and practices for all Clang Tools are exactly those
50of Clang itself. They are entirely within the Clang *project*,
51regardless of the version control scheme.
52
53Core Clang Tools
54================
55
56The core set of Clang tools that are within the main repository are
57tools that very specifically complement, and allow use and testing of
58*Clang* specific functionality.
59
60``clang-check``
61---------------
62
63:doc:`ClangCheck` combines the LibTooling framework for running a
64Clang tool with the basic Clang diagnostics by syntax checking specific files
65in a fast, command line interface. It can also accept flags to re-display the
66diagnostics in different formats with different flags, suitable for use driving
67an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
68fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for
69instructions on how to setup and used `clang-check`.
70
71``clang-format``
72----------------
73
74Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool
75<ClangFormat>` with the goal of automatically reformatting C++ sources files
76according to configurable style guides.  To do so, clang-format uses Clang's
77``Lexer`` to transform an input file into a token stream and then changes all
78the whitespace around those tokens.  The goal is for clang-format to serve both
79as a user tool (ideally with powerful IDE integrations) and as part of other
80refactoring tools, e.g. to do a reformatting of all the lines changed during a
81renaming.
82
83
84Extra Clang Tools
85=================
86
87As various categories of Clang Tools are added to the extra repository,
88they'll be tracked here. The focus of this documentation is on the scope
89and features of the tools for other tool developers; each tool should
90provide its own user-focused documentation.
91
92``clang-tidy``
93--------------
94
95`clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`_ is a clang-based C++
96linter tool. It provides an extensible framework for building compiler-based
97static analyses detecting and fixing bug-prone patterns, performance,
98portability and maintainability issues.
99
100
101Ideas for new Tools
102===================
103
104* C++ cast conversion tool.  Will convert C-style casts (``(type) value``) to
105  appropriate C++ cast (``static_cast``, ``const_cast`` or
106  ``reinterpret_cast``).
107* Non-member ``begin()`` and ``end()`` conversion tool.  Will convert
108  ``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where
109  ``foo`` is a standard container.  We could also detect similar patterns for
110  arrays.
111* ``tr1`` removal tool.  Will migrate source code from using TR1 library
112  features to C++11 library.  For example:
113
114  .. code-block:: c++
115
116    #include <tr1/unordered_map>
117    int main()
118    {
119        std::tr1::unordered_map <int, int> ma;
120        std::cout << ma.size () << std::endl;
121        return 0;
122    }
123
124  should be rewritten to:
125
126  .. code-block:: c++
127
128    #include <unordered_map>
129    int main()
130    {
131        std::unordered_map <int, int> ma;
132        std::cout << ma.size () << std::endl;
133        return 0;
134    }
135
136* A tool to remove ``auto``.  Will convert ``auto`` to an explicit type or add
137  comments with deduced types.  The motivation is that there are developers
138  that don't want to use ``auto`` because they are afraid that they might lose
139  control over their code.
140
141* C++14: less verbose operator function objects (`N3421
142  <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm>`_).
143  For example:
144
145  .. code-block:: c++
146
147    sort(v.begin(), v.end(), greater<ValueType>());
148
149  should be rewritten to:
150
151  .. code-block:: c++
152
153    sort(v.begin(), v.end(), greater<>());
154
155