Sean Silva | 13b5e11 | 2013-01-02 12:40:15 +0000 | [diff] [blame] | 1 | ================================================= |
| 2 | Choosing the Right Interface for Your Application |
| 3 | ================================================= |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 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 <http://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 | |
Sean Silva | 159cc9e | 2013-01-02 13:07:47 +0000 | [diff] [blame] | 36 | :doc:`Clang Plugins <ClangPlugins>` allow you to run additional actions on the |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 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 | |
Sean Silva | 159cc9e | 2013-01-02 13:07:47 +0000 | [diff] [blame] | 63 | :doc:`LibTooling <LibTooling>` is a C++ interface aimed at writing standalone |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 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 |
Sean Silva | 6fad575 | 2013-01-02 20:22:14 +0000 | [diff] [blame] | 75 | * want to share code with Clang Plugins |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 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 | Clang Tools |
| 86 | ----------- |
| 87 | |
Sean Silva | 159cc9e | 2013-01-02 13:07:47 +0000 | [diff] [blame] | 88 | :doc:`Clang tools <ClangTools>` are a collection of specific developer tools |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 89 | built on top of the LibTooling infrastructure as part of the Clang project. |
| 90 | They are targeted at automating and improving core development activities of |
| 91 | C/C++ developers. |
| 92 | |
| 93 | Examples of tools we are building or planning as part of the Clang project: |
| 94 | |
| 95 | * Syntax checking (:program:`clang-check`) |
| 96 | * Automatic fixing of compile errors (:program:`clang-fixit`) |
Sean Silva | 9cc4c39 | 2013-01-02 12:49:25 +0000 | [diff] [blame] | 97 | * Automatic code formatting (:program:`clang-format`) |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 98 | * Migration tools for new features in new language standards |
| 99 | * Core refactoring tools |
| 100 | |