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