granicus.if.org Git - clang/blob - docs/ClangTools.rst

   1 ===========
   2 Clang Tools
   3 ===========
   4
   5 Clang Tools are standalone command line (and potentially GUI) tools
   6 design 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 compliment, and allow use and testing of
  71 *Clang* specific functionality.
  72
  73 ``clang-check``
  74 ~~~~~~~~~~~~~~~
  75
  76 This tool combines the LibTooling framework for running a Clang tool
  77 with the basic Clang diagnostics by syntax checking specific files in a
  78 fast, command line interface. It can also accept flags to re-display the
  79 diagnostics in different formats with different flags, suitable for use
  80 driving an IDE or editor. Furthermore, it can be used in fixit-mode to
  81 directly apply fixit-hints offered by clang.
  82
  83 FIXME: Link to user-oriented clang-check documentation.
  84
  85 Extra Clang Tools
  86 =================
  87
  88 As various categories of Clang Tools are added to the extra repository,
  89 they'll be tracked here. The focus of this documentation is on the scope
  90 and features of the tools for other tool developers; each tool should
  91 provide its own user-focused documentation.