Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 1 | ======== |
| 2 | Overview |
| 3 | ======== |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 4 | |
| 5 | Clang Tools are standalone command line (and potentially GUI) tools |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 6 | designed for use by C++ developers who are already using and enjoying |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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`` |
Sean Silva | e30561d | 2013-01-02 12:40:31 +0000 | [diff] [blame] | 22 | - ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra`` |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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 |
Sean Silva | 7298c0b | 2013-03-03 17:07:35 +0000 | [diff] [blame] | 70 | tools that very specifically complement, and allow use and testing of |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 71 | *Clang* specific functionality. |
| 72 | |
| 73 | ``clang-check`` |
Sean Silva | 9987ce2 | 2013-01-07 21:46:47 +0000 | [diff] [blame] | 74 | --------------- |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 75 | |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 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`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 83 | |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 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 |
Dmitri Gribenko | 73189fb | 2013-01-09 22:22:51 +0000 | [diff] [blame] | 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 |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 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. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 95 | |
Dmitri Gribenko | 68c4146 | 2013-01-22 19:22:22 +0000 | [diff] [blame] | 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 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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. |
Dmitri Gribenko | 2626a2a | 2013-01-06 20:19:09 +0000 | [diff] [blame] | 112 | |
| 113 | Ideas for new Tools |
Daniel Dunbar | e3fc097 | 2013-01-07 20:43:06 +0000 | [diff] [blame] | 114 | =================== |
Dmitri Gribenko | 2626a2a | 2013-01-06 20:19:09 +0000 | [diff] [blame] | 115 | |
Dmitri Gribenko | 2626a2a | 2013-01-06 20:19:09 +0000 | [diff] [blame] | 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``). |
Dmitri Gribenko | 824ed0c | 2013-02-24 19:04:36 +0000 | [diff] [blame] | 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. |
Dmitri Gribenko | d0d6f64 | 2013-03-03 17:54:36 +0000 | [diff] [blame^] | 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 | |
Dmitri Gribenko | 0a8dead | 2013-02-25 01:14:45 +0000 | [diff] [blame] | 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. |
Dmitri Gribenko | 2626a2a | 2013-01-06 20:19:09 +0000 | [diff] [blame] | 152 | |