[cfe-commits] r155549 - /cfe/trunk/docs/Tooling.html

Wed Apr 25 06:57:01 PDT 2012

Author: klimek
Date: Wed Apr 25 08:57:00 2012
New Revision: 155549

URL: http://llvm.org/viewvc/llvm-project?rev=155549&view=rev
Log:
Adds a document describing the various tooling approaches and their pros and
cons.


Added:
    cfe/trunk/docs/Tooling.html   (with props)

Added: cfe/trunk/docs/Tooling.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/Tooling.html?rev=155549&view=auto
==============================================================================

--- cfe/trunk/docs/Tooling.html (added)
+++ cfe/trunk/docs/Tooling.html Wed Apr 25 08:57:00 2012
@@ -0,0 +1,100 @@
+<!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>
+

Propchange: cfe/trunk/docs/Tooling.html
------------------------------------------------------------------------------
    svn:eol-style = LF

Propchange: cfe/trunk/docs/Tooling.html
------------------------------------------------------------------------------
    svn:mime-type = text/html



