| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| <head> |
| <title>Writing Clang Tools</title> |
| <link type="text/css" rel="stylesheet" href="../menu.css"> |
| <link type="text/css" rel="stylesheet" href="../content.css"> |
| </head> |
| <body> |
| <div id="content"> |
| |
| <h1>Writing Clang Tools</h1> |
| <p>Clang provides infrastructure to write tools that need syntactic and semantic |
| information about a program. This document will give a short introduction of the |
| different ways to write clang tools, and their pros and cons.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="libclang"><a href="http://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a></h2> |
| <!-- ======================================================================= --> |
| |
| <p>LibClang is a stable high level C interface to clang. When in doubt LibClang |
| is probably the interface you want to use. Consider the other interfaces only |
| when you have a good reason not to use LibClang.</p> |
| <p>Canonical examples of when to use LibClang:</p> |
| <ul> |
| <li>XCode</li> |
| <li>Clang Python Bindings</li> |
| </ul> |
| <p>Use LibClang when you...</p> |
| <ul> |
| <li>want to interface with clang from other languages than C++</li> |
| <li>need a stable interface that takes care to be backwards compatible</li> |
| <li>want powerful high-level abstractions, like iterating throught an AST |
| with a cursor, and don't want to learn all the nitty gritty details of Clang's |
| AST.</li> |
| </ul> |
| <p>Do not use LibClang when you...</p> |
| <ul> |
| <li>want full control over the Clang AST</li> |
| </ul> |
| |
| <!-- ======================================================================= --> |
| <h2 id="clang-plugins"><a href="http://clang.llvm.org/doxygen/classclang_1_1PluginASTAction.html">Clang Plugins</a></h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang Plugins allow you to run additional actions on the AST as part of |
| a compilation. Plugins are dynamic libraries that are loaded at runtime by |
| the compiler, and they're easy to integrate into your build environment.</p> |
| <p>Canonical examples of when to use Clang Plugins:</p> |
| <ul> |
| <li>special lint-style warnings or errors for your project</li> |
| <li>creating additional build artifacts from a single compile step</li> |
| </ul> |
| <p>Use Clang Plugins when you...</p> |
| <ul> |
| <li>need your tool to rerun if any of the dependencies change</li> |
| <li>want your tool to make or break a build</li> |
| <li>need full control over the Clang AST</li> |
| </ul> |
| <p>Do not use Clang Plugins when you...</p> |
| <ul> |
| <li>want to run tools outside of your build environment</li> |
| <li>want full control on how Clang is set up, including mapping of in-memory |
| virtual files</li> |
| <li>need to run over a specific subset of files in your project which is not |
| necessarily related to any changes which would trigger rebuilds</li> |
| </ul> |
| |
| <!-- ======================================================================= --> |
| <h2 id="libtooling"><a href="http://clang.llvm.org/doxygen/namespaceclang_1_1tooling.html">LibTooling</a></h2> |
| <!-- ======================================================================= --> |
| |
| <p>LibTooling is a C++ interface aimed at writing standalone tools, as well as |
| integrating into services that run clang tools.</p> |
| <p>Canonical examples of when to use LibTooling:</p> |
| <ul> |
| <li>a simple syntax checker</li> |
| <li>refactoring tools</li> |
| </ul> |
| <p>Use LibTooling when you...</p> |
| <ul> |
| <li>want to run tools over a single file, or a specific subset of files, |
| independently of the build system</li> |
| <li>want full control over the Clang AST</li> |
| <li>want to share code with Clang Plugins</li> |
| </ul> |
| <p>Do not use LibTooling when you...</p> |
| <ul> |
| <li>want to run as part of the build triggered by dependency changes</li> |
| <li>want a stable interface so you don't need to change your code when the |
| AST API changes</li> |
| <li>want high level abstractions like cursors and code completion out of the |
| box</li> |
| <li>do not want to write your tools in C++</li> |
| </ul> |
| |
| </div> |
| </body> |
| </html> |
| |
