docs/Tooling.rst

===================
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 <http://clang.llvm.org/doxygen/group__CINDEX.html>`_ 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 through 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 <ClangPlugins.html>`_ 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 <LibTooling.html>`_ 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 Plgins

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++

Clang Tools
-----------

`Clang tools <ClangTools.html>`_ are a collection of specific developer tools
built on top of the LibTooling infrastructure as part of the Clang project.
They are targeted at automating and improving core development activities of
C/C++ developers.

Examples of tools we are building or planning as part of the Clang project:

* Syntax checking (:program:`clang-check`)
* Automatic fixing of compile errors (:program:`clang-fixit`)
* Automatic code formatting
* Migration tools for new features in new language standards
* Core refactoring tools