=================================================
|
Choosing the Right Interface for Your Application
|
=================================================
|
|
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
|
-------------
|
|
:doc:`Clang Plugins <ClangPlugins>` 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
|
----------
|
|
:doc:`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++
|
|
:doc:`Clang tools <ClangTools>` 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 (:program:`clang-format`)
|
* Migration tools for new features in new language standards
|
* Core refactoring tools
|
