clang/docs/ClangTools.rst

   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 tree. The rest of the tools are kept in a separate
  13 directory tree, `clang-tools-extra
  14 <https://github.com/llvm/llvm-project/tree/main/clang-tools-extra>`_.
  15
  16 This document describes a high-level overview of the organization of
  17 Clang Tools within the project as well as giving an introduction to some
  18 of the more important tools. However, it should be noted that this
  19 document is currently focused on Clang and Clang Tool developers, not on
  20 end users of these tools.
  21
  22 Clang Tools Organization
  23 ========================
  24
  25 Clang Tools are CLI or GUI programs that are intended to be directly
  26 used by C++ developers. That is they are *not* primarily for use by
  27 Clang developers, although they are hopefully useful to C++ developers
  28 who happen to work on Clang, and we try to actively dogfood their
  29 functionality. They are developed in three components: the underlying
  30 infrastructure for building a standalone tool based on Clang, core
  31 shared logic used by many different tools in the form of refactoring and
  32 rewriting libraries, and the tools themselves.
  33
  34 The underlying infrastructure for Clang Tools is the
  35 :doc:`LibTooling <LibTooling>` platform. See its documentation for much
  36 more detailed information about how this infrastructure works. The
  37 common refactoring and rewriting toolkit-style library is also part of
  38 LibTooling organizationally.
  39
  40 A few Clang Tools are developed along side the core Clang libraries as
  41 examples and test cases of fundamental functionality. However, most of
  42 the tools are developed in a side repository to provide easy separation
  43 from the core libraries. We intentionally do not support public
  44 libraries in the side repository, as we want to carefully review and
  45 find good APIs for libraries as they are lifted out of a few tools and
  46 into the core Clang library set.
  47
  48 Regardless of which repository Clang Tools' code resides in, the
  49 development process and practices for all Clang Tools are exactly those
  50 of Clang itself. They are entirely within the Clang *project*,
  51 regardless of the version control scheme.
  52
  53 Core Clang Tools
  54 ================
  55
  56 The core set of Clang tools that are within the main repository are
  57 tools that very specifically complement, and allow use and testing of
  58 *Clang* specific functionality.
  59
  60 ``clang-check``
  61 ---------------
  62
  63 :doc:`ClangCheck` combines the LibTooling framework for running a
  64 Clang tool with the basic Clang diagnostics by syntax checking specific files
  65 in a fast, command line interface. It can also accept flags to re-display the
  66 diagnostics in different formats with different flags, suitable for use driving
  67 an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
  68 fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for
  69 instructions on how to setup and used `clang-check`.
  70
  71 ``clang-format``
  72 ----------------
  73
  74 Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool
  75 <ClangFormat>` with the goal of automatically reformatting C++ sources files
  76 according to configurable style guides.  To do so, clang-format uses Clang's
  77 ``Lexer`` to transform an input file into a token stream and then changes all
  78 the whitespace around those tokens.  The goal is for clang-format to serve both
  79 as a user tool (ideally with powerful IDE integrations) and as part of other
  80 refactoring tools, e.g. to do a reformatting of all the lines changed during a
  81 renaming.
  82
  83
  84 Extra Clang Tools
  85 =================
  86
  87 As various categories of Clang Tools are added to the extra repository,
  88 they'll be tracked here. The focus of this documentation is on the scope
  89 and features of the tools for other tool developers; each tool should
  90 provide its own user-focused documentation.
  91
  92 ``clang-tidy``
  93 --------------
  94
  95 `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`_ is a clang-based C++
  96 linter tool. It provides an extensible framework for building compiler-based
  97 static analyses detecting and fixing bug-prone patterns, performance,
  98 portability and maintainability issues.
  99
 100
 101 Ideas for new Tools
 102 ===================
 103
 104 * C++ cast conversion tool.  Will convert C-style casts (``(type) value``) to
 105   appropriate C++ cast (``static_cast``, ``const_cast`` or
 106   ``reinterpret_cast``).
 107 * Non-member ``begin()`` and ``end()`` conversion tool.  Will convert
 108   ``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where
 109   ``foo`` is a standard container.  We could also detect similar patterns for
 110   arrays.
 111 * ``tr1`` removal tool.  Will migrate source code from using TR1 library
 112   features to C++11 library.  For example:
 113
 114   .. code-block:: c++
 115
 116     #include <tr1/unordered_map>
 117     int main()
 118     {
 119         std::tr1::unordered_map <int, int> ma;
 120         std::cout << ma.size () << std::endl;
 121         return 0;
 122     }
 123
 124   should be rewritten to:
 125
 126   .. code-block:: c++
 127
 128     #include <unordered_map>
 129     int main()
 130     {
 131         std::unordered_map <int, int> ma;
 132         std::cout << ma.size () << std::endl;
 133         return 0;
 134     }
 135
 136 * A tool to remove ``auto``.  Will convert ``auto`` to an explicit type or add
 137   comments with deduced types.  The motivation is that there are developers
 138   that don't want to use ``auto`` because they are afraid that they might lose
 139   control over their code.
 140
 141 * C++14: less verbose operator function objects (`N3421
 142   <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm>`_).
 143   For example:
 144
 145   .. code-block:: c++
 146
 147     sort(v.begin(), v.end(), greater<ValueType>());
 148
 149   should be rewritten to:
 150
 151   .. code-block:: c++
 152
 153     sort(v.begin(), v.end(), greater<>());
 154