191 lines
6.9 KiB
ReStructuredText
191 lines
6.9 KiB
ReStructuredText
========
|
|
Overview
|
|
========
|
|
|
|
Clang Tools are standalone command line (and potentially GUI) tools
|
|
designed for use by C++ developers who are already using and enjoying
|
|
Clang as their compiler. These tools provide developer-oriented
|
|
functionality such as fast syntax checking, automatic formatting,
|
|
refactoring, etc.
|
|
|
|
Only a couple of the most basic and fundamental tools are kept in the
|
|
primary Clang Subversion project. The rest of the tools are kept in a
|
|
side-project so that developers who don't want or need to build them
|
|
don't. If you want to get access to the extra Clang Tools repository,
|
|
simply check it out into the tools tree of your Clang checkout and
|
|
follow the usual process for building and working with a combined
|
|
LLVM/Clang checkout:
|
|
|
|
- With Subversion:
|
|
|
|
- ``cd llvm/tools/clang/tools``
|
|
- ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra``
|
|
|
|
- Or with Git:
|
|
|
|
- ``cd llvm/tools/clang/tools``
|
|
- ``git clone http://llvm.org/git/clang-tools-extra.git extra``
|
|
|
|
This document describes a high-level overview of the organization of
|
|
Clang Tools within the project as well as giving an introduction to some
|
|
of the more important tools. However, it should be noted that this
|
|
document is currently focused on Clang and Clang Tool developers, not on
|
|
end users of these tools.
|
|
|
|
Clang Tools Organization
|
|
========================
|
|
|
|
Clang Tools are CLI or GUI programs that are intended to be directly
|
|
used by C++ developers. That is they are *not* primarily for use by
|
|
Clang developers, although they are hopefully useful to C++ developers
|
|
who happen to work on Clang, and we try to actively dogfood their
|
|
functionality. They are developed in three components: the underlying
|
|
infrastructure for building a standalone tool based on Clang, core
|
|
shared logic used by many different tools in the form of refactoring and
|
|
rewriting libraries, and the tools themselves.
|
|
|
|
The underlying infrastructure for Clang Tools is the
|
|
:doc:`LibTooling <LibTooling>` platform. See its documentation for much
|
|
more detailed information about how this infrastructure works. The
|
|
common refactoring and rewriting toolkit-style library is also part of
|
|
LibTooling organizationally.
|
|
|
|
A few Clang Tools are developed along side the core Clang libraries as
|
|
examples and test cases of fundamental functionality. However, most of
|
|
the tools are developed in a side repository to provide easy separation
|
|
from the core libraries. We intentionally do not support public
|
|
libraries in the side repository, as we want to carefully review and
|
|
find good APIs for libraries as they are lifted out of a few tools and
|
|
into the core Clang library set.
|
|
|
|
Regardless of which repository Clang Tools' code resides in, the
|
|
development process and practices for all Clang Tools are exactly those
|
|
of Clang itself. They are entirely within the Clang *project*,
|
|
regardless of the version control scheme.
|
|
|
|
Core Clang Tools
|
|
================
|
|
|
|
The core set of Clang tools that are within the main repository are
|
|
tools that very specifically complement, and allow use and testing of
|
|
*Clang* specific functionality.
|
|
|
|
``clang-check``
|
|
---------------
|
|
|
|
:doc:`ClangCheck` combines the LibTooling framework for running a
|
|
Clang tool with the basic Clang diagnostics by syntax checking specific files
|
|
in a fast, command line interface. It can also accept flags to re-display the
|
|
diagnostics in different formats with different flags, suitable for use driving
|
|
an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
|
|
fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for
|
|
instructions on how to setup and used `clang-check`.
|
|
|
|
``clang-format``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool
|
|
<ClangFormat>` with the goal of automatically reformatting C++ sources files
|
|
according to configurable style guides. To do so, clang-format uses Clang's
|
|
``Lexer`` to transform an input file into a token stream and then changes all
|
|
the whitespace around those tokens. The goal is for clang-format to serve both
|
|
as a user tool (ideally with powerful IDE integrations) and as part of other
|
|
refactoring tools, e.g. to do a reformatting of all the lines changed during a
|
|
renaming.
|
|
|
|
``cpp11-migrate``
|
|
~~~~~~~~~~~~~~~~~
|
|
``cpp11-migrate`` migrates C++ code to use C++11 features where appropriate.
|
|
Currently it can:
|
|
|
|
* convert loops to range-based for loops;
|
|
|
|
* convert null pointer constants (like ``NULL`` or ``0``) to C++11 ``nullptr``;
|
|
|
|
* replace the type specifier in variable declarations with the ``auto`` type specifier;
|
|
|
|
* add the ``override`` specifier to applicable member functions.
|
|
|
|
Extra Clang Tools
|
|
=================
|
|
|
|
As various categories of Clang Tools are added to the extra repository,
|
|
they'll be tracked here. The focus of this documentation is on the scope
|
|
and features of the tools for other tool developers; each tool should
|
|
provide its own user-focused documentation.
|
|
|
|
Ideas for new Tools
|
|
===================
|
|
|
|
* C++ cast conversion tool. Will convert C-style casts (``(type) value``) to
|
|
appropriate C++ cast (``static_cast``, ``const_cast`` or
|
|
``reinterpret_cast``).
|
|
* Non-member ``begin()`` and ``end()`` conversion tool. Will convert
|
|
``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where
|
|
``foo`` is a standard container. We could also detect similar patterns for
|
|
arrays.
|
|
* ``make_shared`` / ``make_unique`` conversion. Part of this transformation
|
|
can be incorporated into the ``auto`` transformation. Will convert
|
|
|
|
.. code-block:: c++
|
|
|
|
std::shared_ptr<Foo> sp(new Foo);
|
|
std::unique_ptr<Foo> up(new Foo);
|
|
|
|
func(std::shared_ptr<Foo>(new Foo), bar());
|
|
|
|
into:
|
|
|
|
.. code-block:: c++
|
|
|
|
auto sp = std::make_shared<Foo>();
|
|
auto up = std::make_unique<Foo>(); // In C++14 mode.
|
|
|
|
// This also affects correctness. For the cases where bar() throws,
|
|
// make_shared() is safe and the original code may leak.
|
|
func(std::make_shared<Foo>(), bar());
|
|
|
|
* ``tr1`` removal tool. Will migrate source code from using TR1 library
|
|
features to C++11 library. For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
#include <tr1/unordered_map>
|
|
int main()
|
|
{
|
|
std::tr1::unordered_map <int, int> ma;
|
|
std::cout << ma.size () << std::endl;
|
|
return 0;
|
|
}
|
|
|
|
should be rewritten to:
|
|
|
|
.. code-block:: c++
|
|
|
|
#include <unordered_map>
|
|
int main()
|
|
{
|
|
std::unordered_map <int, int> ma;
|
|
std::cout << ma.size () << std::endl;
|
|
return 0;
|
|
}
|
|
|
|
* A tool to remove ``auto``. Will convert ``auto`` to an explicit type or add
|
|
comments with deduced types. The motivation is that there are developers
|
|
that don't want to use ``auto`` because they are afraid that they might lose
|
|
control over their code.
|
|
|
|
* C++14: less verbose operator function objects (`N3421
|
|
<http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm>`_).
|
|
For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
sort(v.begin(), v.end(), greater<ValueType>());
|
|
|
|
should be rewritten to:
|
|
|
|
.. code-block:: c++
|
|
|
|
sort(v.begin(), v.end(), greater<>());
|
|
|