1=================================================
2Choosing the Right Interface for Your Application
3=================================================
4
5Clang provides infrastructure to write tools that need syntactic and semantic
6information about a program.  This document will give a short introduction of
7the different ways to write clang tools, and their pros and cons.
8
9LibClang
10--------
11
12`LibClang <http://clang.llvm.org/doxygen/group__CINDEX.html>`_ is a stable high
13level C interface to clang.  When in doubt LibClang is probably the interface
14you want to use.  Consider the other interfaces only when you have a good
15reason not to use LibClang.
16
17Canonical examples of when to use LibClang:
18
19* Xcode
20* Clang Python Bindings
21
22Use 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
29Do not use LibClang when you...:
30
31* want full control over the Clang AST
32
33Clang Plugins
34-------------
35
36:doc:`Clang Plugins <ClangPlugins>` allow you to run additional actions on the
37AST as part of a compilation.  Plugins are dynamic libraries that are loaded at
38runtime by the compiler, and they're easy to integrate into your build
39environment.
40
41Canonical 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
46Use 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
52Do 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
60LibTooling
61----------
62
63:doc:`LibTooling <LibTooling>` is a C++ interface aimed at writing standalone
64tools, as well as integrating into services that run clang tools.  Canonical
65examples of when to use LibTooling:
66
67* a simple syntax checker
68* refactoring tools
69
70Use 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
77Do 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
86built on top of the LibTooling infrastructure as part of the Clang project.
87They are targeted at automating and improving core development activities of
88C/C++ developers.
89
90Examples 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
98