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 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`` 22 - ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra`` 23 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 70tools that very specifically complement, and allow use and testing of 71*Clang* specific functionality. 72 73``clang-check`` 74--------------- 75 76: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`. 83 84``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 89according 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 serve both 92as a user tool (ideally with powerful IDE integrations) and as part of other 93refactoring tools, e.g. to do a reformatting of all the lines changed during a 94renaming. 95 96``clang-modernize`` 97~~~~~~~~~~~~~~~~~~~ 98``clang-modernize`` 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 105* replace the type specifier in variable declarations with the ``auto`` type specifier; 106 107* add the ``override`` specifier to applicable member functions. 108 109Extra Clang Tools 110================= 111 112As various categories of Clang Tools are added to the extra repository, 113they'll be tracked here. The focus of this documentation is on the scope 114and features of the tools for other tool developers; each tool should 115provide its own user-focused documentation. 116 117Ideas for new Tools 118=================== 119 120* C++ cast conversion tool. Will convert C-style casts (``(type) value``) to 121 appropriate C++ cast (``static_cast``, ``const_cast`` or 122 ``reinterpret_cast``). 123* Non-member ``begin()`` and ``end()`` conversion tool. Will convert 124 ``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where 125 ``foo`` is a standard container. We could also detect similar patterns for 126 arrays. 127* ``make_shared`` / ``make_unique`` conversion. Part of this transformation 128 can be incorporated into the ``auto`` transformation. Will convert 129 130 .. code-block:: c++ 131 132 std::shared_ptr<Foo> sp(new Foo); 133 std::unique_ptr<Foo> up(new Foo); 134 135 func(std::shared_ptr<Foo>(new Foo), bar()); 136 137 into: 138 139 .. code-block:: c++ 140 141 auto sp = std::make_shared<Foo>(); 142 auto up = std::make_unique<Foo>(); // In C++14 mode. 143 144 // This also affects correctness. For the cases where bar() throws, 145 // make_shared() is safe and the original code may leak. 146 func(std::make_shared<Foo>(), bar()); 147 148* ``tr1`` removal tool. Will migrate source code from using TR1 library 149 features to C++11 library. For example: 150 151 .. code-block:: c++ 152 153 #include <tr1/unordered_map> 154 int main() 155 { 156 std::tr1::unordered_map <int, int> ma; 157 std::cout << ma.size () << std::endl; 158 return 0; 159 } 160 161 should be rewritten to: 162 163 .. code-block:: c++ 164 165 #include <unordered_map> 166 int main() 167 { 168 std::unordered_map <int, int> ma; 169 std::cout << ma.size () << std::endl; 170 return 0; 171 } 172 173* A tool to remove ``auto``. Will convert ``auto`` to an explicit type or add 174 comments with deduced types. The motivation is that there are developers 175 that don't want to use ``auto`` because they are afraid that they might lose 176 control over their code. 177 178* C++14: less verbose operator function objects (`N3421 179 <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm>`_). 180 For example: 181 182 .. code-block:: c++ 183 184 sort(v.begin(), v.end(), greater<ValueType>()); 185 186 should be rewritten to: 187 188 .. code-block:: c++ 189 190 sort(v.begin(), v.end(), greater<>()); 191 192