Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame^] | 1 | =========== |
| 2 | Clang Tools |
| 3 | =========== |
| 4 | |
| 5 | Clang Tools are standalone command line (and potentially GUI) tools |
| 6 | design 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 compliment, and allow use and testing of |
| 71 | *Clang* specific functionality. |
| 72 | |
| 73 | ``clang-check`` |
| 74 | ~~~~~~~~~~~~~~~ |
| 75 | |
| 76 | This tool combines the LibTooling framework for running a Clang tool |
| 77 | with the basic Clang diagnostics by syntax checking specific files in a |
| 78 | fast, command line interface. It can also accept flags to re-display the |
| 79 | diagnostics in different formats with different flags, suitable for use |
| 80 | driving an IDE or editor. Furthermore, it can be used in fixit-mode to |
| 81 | directly apply fixit-hints offered by clang. |
| 82 | |
| 83 | FIXME: Link to user-oriented clang-check documentation. |
| 84 | |
| 85 | Extra Clang Tools |
| 86 | ================= |
| 87 | |
| 88 | As various categories of Clang Tools are added to the extra repository, |
| 89 | they'll be tracked here. The focus of this documentation is on the scope |
| 90 | and features of the tools for other tool developers; each tool should |
| 91 | provide its own user-focused documentation. |