Manuel Klimek | 9771a9e | 2012-04-25 13:57:00 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> |
| 4 | <head> |
| 5 | <title>Writing Clang Tools</title> |
| 6 | <link type="text/css" rel="stylesheet" href="../menu.css"> |
| 7 | <link type="text/css" rel="stylesheet" href="../content.css"> |
| 8 | </head> |
| 9 | <body> |
Manuel Klimek | 0fe1e1f | 2012-05-24 17:09:10 +0000 | [diff] [blame] | 10 | |
| 11 | <!--#include virtual="../menu.html.incl"--> |
| 12 | |
Manuel Klimek | 9771a9e | 2012-04-25 13:57:00 +0000 | [diff] [blame] | 13 | <div id="content"> |
| 14 | |
| 15 | <h1>Writing Clang Tools</h1> |
| 16 | <p>Clang provides infrastructure to write tools that need syntactic and semantic |
| 17 | information about a program. This document will give a short introduction of the |
| 18 | different ways to write clang tools, and their pros and cons.</p> |
| 19 | |
| 20 | <!-- ======================================================================= --> |
| 21 | <h2 id="libclang"><a href="http://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a></h2> |
| 22 | <!-- ======================================================================= --> |
| 23 | |
| 24 | <p>LibClang is a stable high level C interface to clang. When in doubt LibClang |
| 25 | is probably the interface you want to use. Consider the other interfaces only |
| 26 | when you have a good reason not to use LibClang.</p> |
| 27 | <p>Canonical examples of when to use LibClang:</p> |
| 28 | <ul> |
Jean-Daniel Dupas | 332f9aa | 2012-05-13 14:32:11 +0000 | [diff] [blame] | 29 | <li>Xcode</li> |
Manuel Klimek | 9771a9e | 2012-04-25 13:57:00 +0000 | [diff] [blame] | 30 | <li>Clang Python Bindings</li> |
| 31 | </ul> |
| 32 | <p>Use LibClang when you...</p> |
| 33 | <ul> |
| 34 | <li>want to interface with clang from other languages than C++</li> |
| 35 | <li>need a stable interface that takes care to be backwards compatible</li> |
Benjamin Kramer | 48d798c | 2012-06-02 10:20:41 +0000 | [diff] [blame] | 36 | <li>want powerful high-level abstractions, like iterating through an AST |
Manuel Klimek | 9771a9e | 2012-04-25 13:57:00 +0000 | [diff] [blame] | 37 | with a cursor, and don't want to learn all the nitty gritty details of Clang's |
| 38 | AST.</li> |
| 39 | </ul> |
| 40 | <p>Do not use LibClang when you...</p> |
| 41 | <ul> |
| 42 | <li>want full control over the Clang AST</li> |
| 43 | </ul> |
| 44 | |
| 45 | <!-- ======================================================================= --> |
Manuel Klimek | 0fe1e1f | 2012-05-24 17:09:10 +0000 | [diff] [blame] | 46 | <h2 id="clang-plugins"><a href="ClangPlugins.html">Clang Plugins</a></h2> |
Manuel Klimek | 9771a9e | 2012-04-25 13:57:00 +0000 | [diff] [blame] | 47 | <!-- ======================================================================= --> |
| 48 | |
| 49 | <p>Clang Plugins allow you to run additional actions on the AST as part of |
| 50 | a compilation. Plugins are dynamic libraries that are loaded at runtime by |
| 51 | the compiler, and they're easy to integrate into your build environment.</p> |
| 52 | <p>Canonical examples of when to use Clang Plugins:</p> |
| 53 | <ul> |
| 54 | <li>special lint-style warnings or errors for your project</li> |
| 55 | <li>creating additional build artifacts from a single compile step</li> |
| 56 | </ul> |
| 57 | <p>Use Clang Plugins when you...</p> |
| 58 | <ul> |
| 59 | <li>need your tool to rerun if any of the dependencies change</li> |
| 60 | <li>want your tool to make or break a build</li> |
| 61 | <li>need full control over the Clang AST</li> |
| 62 | </ul> |
| 63 | <p>Do not use Clang Plugins when you...</p> |
| 64 | <ul> |
| 65 | <li>want to run tools outside of your build environment</li> |
| 66 | <li>want full control on how Clang is set up, including mapping of in-memory |
| 67 | virtual files</li> |
| 68 | <li>need to run over a specific subset of files in your project which is not |
| 69 | necessarily related to any changes which would trigger rebuilds</li> |
| 70 | </ul> |
| 71 | |
| 72 | <!-- ======================================================================= --> |
Manuel Klimek | 0fe1e1f | 2012-05-24 17:09:10 +0000 | [diff] [blame] | 73 | <h2 id="libtooling"><a href="LibTooling.html">LibTooling</a></h2> |
Manuel Klimek | 9771a9e | 2012-04-25 13:57:00 +0000 | [diff] [blame] | 74 | <!-- ======================================================================= --> |
| 75 | |
| 76 | <p>LibTooling is a C++ interface aimed at writing standalone tools, as well as |
| 77 | integrating into services that run clang tools.</p> |
| 78 | <p>Canonical examples of when to use LibTooling:</p> |
| 79 | <ul> |
| 80 | <li>a simple syntax checker</li> |
| 81 | <li>refactoring tools</li> |
| 82 | </ul> |
| 83 | <p>Use LibTooling when you...</p> |
| 84 | <ul> |
| 85 | <li>want to run tools over a single file, or a specific subset of files, |
| 86 | independently of the build system</li> |
| 87 | <li>want full control over the Clang AST</li> |
| 88 | <li>want to share code with Clang Plugins</li> |
| 89 | </ul> |
| 90 | <p>Do not use LibTooling when you...</p> |
| 91 | <ul> |
| 92 | <li>want to run as part of the build triggered by dependency changes</li> |
| 93 | <li>want a stable interface so you don't need to change your code when the |
| 94 | AST API changes</li> |
| 95 | <li>want high level abstractions like cursors and code completion out of the |
| 96 | box</li> |
| 97 | <li>do not want to write your tools in C++</li> |
| 98 | </ul> |
| 99 | |
Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 100 | <!-- ======================================================================= --> |
| 101 | <h2 id="clang-tools"><a href="ClangTools.html">Clang Tools</a></h2> |
| 102 | <!-- ======================================================================= --> |
| 103 | |
| 104 | <p>These are a collection of specific developer tools built on top of the |
| 105 | LibTooling infrastructure as part of the Clang project. They are targeted at |
| 106 | automating and improving core development activities of C/C++ developers.</p> |
| 107 | <p>Examples of tools we are building or planning as part of the Clang |
| 108 | project:</p> |
| 109 | <ul> |
| 110 | <li>Syntax checking (clang-check)</li> |
| 111 | <li>Automatic fixing of compile errors (clangc-fixit)</li> |
| 112 | <li>Automatic code formatting</li> |
| 113 | <li>Migration tools for new features in new language standards</li> |
| 114 | <li>Core refactoring tools</li> |
| 115 | </ul> |
| 116 | |
Manuel Klimek | 9771a9e | 2012-04-25 13:57:00 +0000 | [diff] [blame] | 117 | </div> |
| 118 | </body> |
| 119 | </html> |
| 120 | |