+ +

Writing Clang Tools

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.

+ + +

LibClang

+ + +

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.

Canonical examples of when to use LibClang:

XCode
Clang Python Bindings

Use LibClang when you...

want to interface with clang from other languages than C++
need a stable interface that takes care to be backwards compatible
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.

Do not use LibClang when you...

want full control over the Clang AST

+ + +

Clang Plugins

+ + +

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.

Canonical examples of when to use Clang Plugins:

special lint-style warnings or errors for your project
creating additional build artifacts from a single compile step

Use Clang Plugins when you...

need your tool to rerun if any of the dependencies change
want your tool to make or break a build
need full control over the Clang AST

Do not use Clang Plugins when you...

want to run tools outside of your build environment
want full control on how Clang is set up, including mapping of in-memory + virtual files
need to run over a specific subset of files in your project which is not + necessarily related to any changes which would trigger rebuilds

+ + +

LibTooling

+ + +

LibTooling is a C++ interface aimed at writing standalone tools, as well as +integrating into services that run clang tools.

Canonical examples of when to use LibTooling:

a simple syntax checker
refactoring tools

Use LibTooling when you...

want to run tools over a single file, or a specific subset of files, + independently of the build system
want full control over the Clang AST
want to share code with Clang Plugins

Do not use LibTooling when you...

want to run as part of the build triggered by dependency changes
want a stable interface so you don't need to change your code when the + AST API changes
want high level abstractions like cursors and code completion out of the + box
do not want to write your tools in C++

+ +