1 ======== 2 Overview 3 ======== 4 5 Clang Tools are standalone command line (and potentially GUI) tools 6 designed for use by C++ developers who are already using and enjoying 7 Clang as their compiler. These tools provide developer-oriented 8 functionality such as fast syntax checking, automatic formatting, 9 refactoring, etc. 10 11 Only a couple of the most basic and fundamental tools are kept in the 12 primary Clang Subversion project. The rest of the tools are kept in a 13 side-project so that developers who don't want or need to build them 14 don't. If you want to get access to the extra Clang Tools repository, 15 simply check it out into the tools tree of your Clang checkout and 16 follow the usual process for building and working with a combined 17 LLVM/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 29 This document describes a high-level overview of the organization of 30 Clang Tools within the project as well as giving an introduction to some 31 of the more important tools. However, it should be noted that this 32 document is currently focused on Clang and Clang Tool developers, not on 33 end users of these tools. 34 35 Clang Tools Organization 36 ======================== 37 38 Clang Tools are CLI or GUI programs that are intended to be directly 39 used by C++ developers. That is they are *not* primarily for use by 40 Clang developers, although they are hopefully useful to C++ developers 41 who happen to work on Clang, and we try to actively dogfood their 42 functionality. They are developed in three components: the underlying 43 infrastructure for building a standalone tool based on Clang, core 44 shared logic used by many different tools in the form of refactoring and 45 rewriting libraries, and the tools themselves. 46 47 The underlying infrastructure for Clang Tools is the 48 :doc:`LibTooling <LibTooling>` platform. See its documentation for much 49 more detailed information about how this infrastructure works. The 50 common refactoring and rewriting toolkit-style library is also part of 51 LibTooling organizationally. 52 53 A few Clang Tools are developed along side the core Clang libraries as 54 examples and test cases of fundamental functionality. However, most of 55 the tools are developed in a side repository to provide easy separation 56 from the core libraries. We intentionally do not support public 57 libraries in the side repository, as we want to carefully review and 58 find good APIs for libraries as they are lifted out of a few tools and 59 into the core Clang library set. 60 61 Regardless of which repository Clang Tools' code resides in, the 62 development process and practices for all Clang Tools are exactly those 63 of Clang itself. They are entirely within the Clang *project*, 64 regardless of the version control scheme. 65 66 Core Clang Tools 67 ================ 68 69 The core set of Clang tools that are within the main repository are 70 tools 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 77 Clang tool with the basic Clang diagnostics by syntax checking specific files 78 in a fast, command line interface. It can also accept flags to re-display the 79 diagnostics in different formats with different flags, suitable for use driving 80 an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply 81 fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for 82 instructions on how to setup and used `clang-check`. 83 84 ``clang-format`` 85 ~~~~~~~~~~~~~~~~ 86 87 Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool 88 <ClangFormat>` with the goal of automatically reformatting C++ sources files 89 according 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 91 the whitespace around those tokens. The goal is for clang-format to both serve 92 both as a user tool (ideally with powerful IDE integrations) and part of other 93 refactoring tools, e.g. to do a reformatting of all the lines changed during a 94 renaming. 95 96 ``cpp11-migrate`` 97 ~~~~~~~~~~~~~~~~~ 98 ``cpp11-migrate`` migrates C++ code to use C++11 features where appropriate. 99 Currently 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 Extra Clang Tools 106 ================= 107 108 As various categories of Clang Tools are added to the extra repository, 109 they'll be tracked here. The focus of this documentation is on the scope 110 and features of the tools for other tool developers; each tool should 111 provide its own user-focused documentation. 112 113 Ideas for new Tools 114 =================== 115 116 * C++ cast conversion tool. Will convert C-style casts (``(type) value``) to 117 appropriate C++ cast (``static_cast``, ``const_cast`` or 118 ``reinterpret_cast``). 119 * 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. 123 * ``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 148 * 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. 152 153
