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