98 lines · plain
1=================================================2Choosing the Right Interface for Your Application3=================================================4 5Clang provides infrastructure to write tools that need syntactic and semantic6information about a program. This document will give a short introduction of7the different ways to write clang tools, and their pros and cons.8 9LibClang10--------11 12`LibClang <https://clang.llvm.org/doxygen/group__CINDEX.html>`_ is a stable high13level C interface to clang. When in doubt LibClang is probably the interface14you want to use. Consider the other interfaces only when you have a good15reason not to use LibClang.16 17Canonical examples of when to use LibClang:18 19* Xcode20* Clang Python Bindings21 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 compatible26* want powerful high-level abstractions, like iterating through an AST with a27 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 AST32 33Clang Plugins34-------------35 36:doc:`Clang Plugins <ClangPlugins>` allow you to run additional actions on the37AST as part of a compilation. Plugins are dynamic libraries that are loaded at38runtime by the compiler, and they're easy to integrate into your build39environment.40 41Canonical examples of when to use Clang Plugins:42 43* special lint-style warnings or errors for your project44* creating additional build artifacts from a single compile step45 46Use Clang Plugins when you...:47 48* need your tool to rerun if any of the dependencies change49* want your tool to make or break a build50* need full control over the Clang AST51 52Do not use Clang Plugins when you...:53 54* want to run tools outside of your build environment55* want full control on how Clang is set up, including mapping of in-memory56 virtual files57* need to run over a specific subset of files in your project which is not58 necessarily related to any changes which would trigger rebuilds59 60LibTooling61----------62 63:doc:`LibTooling <LibTooling>` is a C++ interface aimed at writing standalone64tools, as well as integrating into services that run clang tools. Canonical65examples of when to use LibTooling:66 67* a simple syntax checker68* refactoring tools69 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 system74* want full control over the Clang AST75* want to share code with Clang Plugins76 77Do not use LibTooling when you...:78 79* want to run as part of the build triggered by dependency changes80* want a stable interface so you don't need to change your code when the AST API81 changes82* want high level abstractions like cursors and code completion out of the box83* do not want to write your tools in C++84 85:doc:`Clang tools <ClangTools>` are a collection of specific developer tools86built on top of the LibTooling infrastructure as part of the Clang project.87They are targeted at automating and improving core development activities of88C/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 standards96* Core refactoring tools97 98