docs/Tooling.rst

   1 =================================================
   2 Choosing the Right Interface for Your Application
   3 =================================================
   4
   5 Clang provides infrastructure to write tools that need syntactic and semantic
   6 information about a program.  This document will give a short introduction of
   7 the different ways to write clang tools, and their pros and cons.
   8
   9 LibClang
  10 --------
  11
  12 `LibClang <http://clang.llvm.org/doxygen/group__CINDEX.html>`_ is a stable high
  13 level C interface to clang.  When in doubt LibClang is probably the interface
  14 you want to use.  Consider the other interfaces only when you have a good
  15 reason not to use LibClang.
  16
  17 Canonical examples of when to use LibClang:
  18
  19 * Xcode
  20 * Clang Python Bindings
  21
  22 Use LibClang when you...:
  23
  24 * want to interface with clang from other languages than C++
  25 * need a stable interface that takes care to be backwards compatible
  26 * want powerful high-level abstractions, like iterating through an AST with a
  27   cursor, and don't want to learn all the nitty gritty details of Clang's AST.
  28
  29 Do not use LibClang when you...:
  30
  31 * want full control over the Clang AST
  32
  33 Clang Plugins
  34 -------------
  35
  36 :doc:`Clang Plugins <ClangPlugins>` allow you to run additional actions on the
  37 AST as part of a compilation.  Plugins are dynamic libraries that are loaded at
  38 runtime by the compiler, and they're easy to integrate into your build
  39 environment.
  40
  41 Canonical examples of when to use Clang Plugins:
  42
  43 * special lint-style warnings or errors for your project
  44 * creating additional build artifacts from a single compile step
  45
  46 Use Clang Plugins when you...:
  47
  48 * need your tool to rerun if any of the dependencies change
  49 * want your tool to make or break a build
  50 * need full control over the Clang AST
  51
  52 Do not use Clang Plugins when you...:
  53
  54 * want to run tools outside of your build environment
  55 * want full control on how Clang is set up, including mapping of in-memory
  56   virtual files
  57 * need to run over a specific subset of files in your project which is not
  58   necessarily related to any changes which would trigger rebuilds
  59
  60 LibTooling
  61 ----------
  62
  63 :doc:`LibTooling <LibTooling>` is a C++ interface aimed at writing standalone
  64 tools, as well as integrating into services that run clang tools.  Canonical
  65 examples of when to use LibTooling:
  66
  67 * a simple syntax checker
  68 * refactoring tools
  69
  70 Use LibTooling when you...:
  71
  72 * want to run tools over a single file, or a specific subset of files,
  73   independently of the build system
  74 * want full control over the Clang AST
  75 * want to share code with Clang Plugins
  76
  77 Do not use LibTooling when you...:
  78
  79 * want to run as part of the build triggered by dependency changes
  80 * want a stable interface so you don't need to change your code when the AST API
  81   changes
  82 * want high level abstractions like cursors and code completion out of the box
  83 * do not want to write your tools in C++
  84
  85 :doc:`Clang tools <ClangTools>` are a collection of specific developer tools
  86 built on top of the LibTooling infrastructure as part of the Clang project.
  87 They are targeted at automating and improving core development activities of
  88 C/C++ developers.
  89
  90 Examples of tools we are building or planning as part of the Clang project:
  91
  92 * Syntax checking (:program:`clang-check`)
  93 * Automatic fixing of compile errors (:program:`clang-fixit`)
  94 * Automatic code formatting (:program:`clang-format`)
  95 * Migration tools for new features in new language standards
  96 * Core refactoring tools
  97