diff options
author | Sean Silva <silvas@purdue.edu> | 2012-12-12 23:44:55 +0000 |
---|---|---|
committer | Sean Silva <silvas@purdue.edu> | 2012-12-12 23:44:55 +0000 |
commit | 3872b46ba9a5275ef0bf4fcefe2d7ef11ce75cc5 (patch) | |
tree | 3adbf587f42fe9f1b48769961a94c8c1de7962b5 /docs/Tooling.rst | |
parent | b34ae9be5297aac85a6241e18bfaa46fde23d924 (diff) | |
download | clang-3872b46ba9a5275ef0bf4fcefe2d7ef11ce75cc5.tar.gz clang-3872b46ba9a5275ef0bf4fcefe2d7ef11ce75cc5.tar.bz2 clang-3872b46ba9a5275ef0bf4fcefe2d7ef11ce75cc5.tar.xz |
docs: Convert some docs to reST.
Converts:
LanguageExtensions
LibASTMatchers
LibTooling
PCHInternals
ThreadSanitizer
Tooling
Patch by Mykhailo Pustovit!
(with minor edits by Dmitri Gribenko and Sean Silva)
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@170048 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/Tooling.rst')
-rw-r--r-- | docs/Tooling.rst | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/docs/Tooling.rst b/docs/Tooling.rst new file mode 100644 index 0000000000..78b92efa9f --- /dev/null +++ b/docs/Tooling.rst @@ -0,0 +1,100 @@ +=================== +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 + |