192 lines · plain
1========2Overview3========4 5Clang Tools are standalone command line (and potentially GUI) tools6designed for use by C++ developers who are already using and enjoying7Clang as their compiler. These tools provide developer-oriented8functionality such as fast syntax checking, automatic formatting,9refactoring, etc.10 11Only a couple of the most basic and fundamental tools are kept in the12primary Clang tree. The rest of the tools are kept in a separate13directory tree, `clang-tools-extra14<https://github.com/llvm/llvm-project/tree/main/clang-tools-extra>`_.15 16This document describes a high-level overview of the organization of17Clang Tools within the project as well as giving an introduction to some18of the more important tools. However, it should be noted that this19document is currently focused on Clang and Clang Tool developers, not on20end users of these tools.21 22Clang Tools Organization23========================24 25Clang Tools are CLI or GUI programs that are intended to be directly26used by C++ developers. That is they are *not* primarily for use by27Clang developers, although they are hopefully useful to C++ developers28who happen to work on Clang, and we try to actively dogfood their29functionality. They are developed in three components: the underlying30infrastructure for building a standalone tool based on Clang, core31shared logic used by many different tools in the form of refactoring and32rewriting libraries, and the tools themselves.33 34The underlying infrastructure for Clang Tools is the35:doc:`LibTooling <LibTooling>` platform. See its documentation for much36more detailed information about how this infrastructure works. The37common refactoring and rewriting toolkit-style library is also part of38LibTooling organizationally.39 40A few Clang Tools are developed along side the core Clang libraries as41examples and test cases of fundamental functionality. However, most of42the tools are developed in a side repository to provide easy separation43from the core libraries. We intentionally do not support public44libraries in the side repository, as we want to carefully review and45find good APIs for libraries as they are lifted out of a few tools and46into the core Clang library set.47 48Regardless of which repository Clang Tools' code resides in, the49development process and practices for all Clang Tools are exactly those50of Clang itself. They are entirely within the Clang *project*,51regardless of the version control scheme.52 53Core Clang Tools54================55 56The core set of Clang tools that are within the main repository are57tools that very specifically complement, and allow use and testing of58*Clang* specific functionality.59 60``clang-check``61---------------62 63:doc:`ClangCheck` combines the LibTooling framework for running a64Clang tool with the basic Clang diagnostics by syntax checking specific files65in a fast, command line interface. It can also accept flags to re-display the66diagnostics in different formats with different flags, suitable for use driving67an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply68fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for69instructions on how to setup and use `clang-check`.70 71``clang-format``72----------------73 74Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool75<ClangFormat>` with the goal of automatically reformatting C++ source files76according to configurable style guides. To do so, clang-format uses Clang's77``Lexer`` to transform an input file into a token stream and then changes all78the whitespace around those tokens. The goal is for clang-format to serve both79as a user tool (ideally with powerful IDE integrations) and as part of other80refactoring tools, e.g. to do a reformatting of all the lines changed during a81renaming.82 83 84Extra Clang Tools85=================86 87As various categories of Clang Tools are added to the extra repository,88they'll be tracked here. The focus of this documentation is on the scope89and features of the tools for other tool developers; each tool should90provide its own user-focused documentation.91 92``Clang-Doc``93-------------94 95`Clang-Doc <https://clang.llvm.org/extra/clang-doc.html>`_ is a tool for96generating C and C++ documentation from source code and comments.97 98``Clang-Include-Fixer``99-----------------------100 101`Clang-Include-Fixer <https://clang.llvm.org/extra/clang-include-fixer.html>`_102is a tool to automate the addition of missing ``#include`` directives in a C++103file. It adds missing namespace qualifiers to unidentified symbols when104necessary and also removes unused headers.105 106``Clang-Tidy``107--------------108 109`Clang-Tidy <https://clang.llvm.org/extra/clang-tidy/>`_ is a Clang-based C++110linter tool. It provides an extensible framework for building compiler-based111static analyses detecting and fixing bug-prone patterns, performance,112portability and maintainability issues. It also has checks for modernizing code113to newer language standards.114 115``Clangd``116----------117 118`Clangd <https://clangd.llvm.org/>`_ is a language server that can work with119many editors via a plugin. It understands your C++ code and adds smart120features to your editor: code completion, compile errors, go-to-definition and121more.122 123``Modularize``124--------------125 126`Modularize <https://clang.llvm.org/extra/modularize.html>`_ is a standalone127tool that checks whether a set of headers provides the consistent definitions128required to use modules.129 130``pp-trace``131------------132 133`pp-trace <https://clang.llvm.org/extra/pp-trace.html>`_ is a standalone tool134that traces preprocessor activity. It’s also used as a test of Clang’s135``PPCallbacks`` interface.136 137 138Ideas for new Tools139===================140 141* C++ cast conversion tool. Will convert C-style casts (``(type) value``) to142 appropriate C++ cast (``static_cast``, ``const_cast`` or143 ``reinterpret_cast``).144* Non-member ``begin()`` and ``end()`` conversion tool. Will convert145 ``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where146 ``foo`` is a standard container. We could also detect similar patterns for147 arrays.148* ``tr1`` removal tool. Will migrate source code from using TR1 library149 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 add174 comments with deduced types. The motivation is that there are developers175 that don't want to use ``auto`` because they are afraid that they might lose176 control over their code.177 178* C++14: less verbose operator function objects (`N3421179 <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