Home | History | Annotate | Download | only in docs
      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 serve both
     92 as a user tool (ideally with powerful IDE integrations) and as part of other
     93 refactoring tools, e.g. to do a reformatting of all the lines changed during a
     94 renaming.
     95 
     96 ``clang-modernize``
     97 ~~~~~~~~~~~~~~~~~~~
     98 ``clang-modernize`` 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 * replace the type specifier in variable declarations with the ``auto`` type specifier;
    106 
    107 * add the ``override`` specifier to applicable member functions.
    108 
    109 Extra Clang Tools
    110 =================
    111 
    112 As various categories of Clang Tools are added to the extra repository,
    113 they'll be tracked here. The focus of this documentation is on the scope
    114 and features of the tools for other tool developers; each tool should
    115 provide its own user-focused documentation.
    116 
    117 Ideas 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