docs/ClangTools.rst

========
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 both serve
both as a user tool (ideally with powerful IDE integrations) and 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<>());