|
150
|
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 <https://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
|
