Author: klimek
Date: Wed Jul 25 02:28:11 2012
New Revision: 160708
URL: http://llvm.org/viewvc/llvm-project?rev=160708&view=rev
Log:
Adds a introductionary document to the Clang AST.
Next steps are adding information about types & source location handling.
Added:
cfe/trunk/docs/IntroductionToTheClangAST.html
Added: cfe/trunk/docs/IntroductionToTheClangAST.html
URL:
http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/IntroductionToTheClangAST.html?rev=160708&view=auto
==============================================================================
--- cfe/trunk/docs/IntroductionToTheClangAST.html (added)
+++ cfe/trunk/docs/IntroductionToTheClangAST.html Wed Jul 25 02:28:11 2012
@@ -0,0 +1,139 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd";>
+<html>
+<head>
+<title>Introduction to the Clang AST</title>
+<link type="text/css" rel="stylesheet" href="../menu.css" />
+<link type="text/css" rel="stylesheet" href="../content.css" />
+</head>
+<body>
+
+<!--#include virtual="../menu.html.incl"-->
+
+<div id="content">
+
+<h1>Introduction to the Clang AST</h1>
+<p>This document gives a gentle introduction to the mysteries of the Clang AST.
+It is targeted at developers who either want to contribute to Clang, or use
+tools that work based on Clang's AST, like the AST matchers.</p>
+<!-- FIXME: Add link once we have an AST matcher document -->
+
+<!-- =======================================================================
-->
+<h2 id="intro">Introduction</h2>
+<!-- =======================================================================
-->
+
+<p>Clang's AST is different from ASTs produced by some other compilers in that
it closely
+resembles both the written C++ code and the C++ standard. For example,
+parenthesis expressions and compile time constants are available in an
unreduced
+form in the AST. This makes Clang's AST a good fit for refactoring tools.</p>
+
+<p>Documentation for all Clang AST nodes is available via the generated
+<a href="http://clang.llvm.org/doxygen";>Doxygen</a>. The doxygen online
+documentation is also indexed by your favorite search engine, which will make
+a search for clang and the AST node's class name usually turn up the doxygen
+of the class you're looking for (for example, search for: clang ParenExpr).</p>
+
+<!-- =======================================================================
-->
+<h2 id="examine">Examining the AST</h2>
+<!-- =======================================================================
-->
+
+<p>A good way to familarize yourself with the Clang AST is to actually look
+at it on some simple example code. Clang has a builtin AST-dump modes, which
+can be enabled with the flags -ast-dump and -ast-dump-xml. Note that
-ast-dump-xml
+currently only works with debug-builds of clang.</p>
+
+<p>Let's look at a simple example AST:</p>
+<pre>
+# cat test.cc
+int f(int x) {
+ int result = (x / 42);
+ return result;
+}
+
+# Clang by default is a frontend for many tools; -cc1 tells it to directly
+# use the C++ compiler mode. -undef leaves out some internal declarations.
+$ clang -cc1 -undef -ast-dump-xml test.cc
+... cutting out internal declarations of clang ...
+<TranslationUnit ptr="0x4871160">
+ <Function ptr="0x48a5800" name="f" prototype="true">
+ <FunctionProtoType ptr="0x4871de0" canonical="0x4871de0">
+ <BuiltinType ptr="0x4871250" canonical="0x4871250"/>
+ <parameters>
+ <BuiltinType ptr="0x4871250" canonical="0x4871250"/>
+ </parameters>
+ </FunctionProtoType>
+ <ParmVar ptr="0x4871d80" name="x" initstyle="c">
+ <BuiltinType ptr="0x4871250" canonical="0x4871250"/>
+ </ParmVar>
+ <Stmt>
+(CompoundStmt 0x48a5a38 <t2.cc:1:14, line:4:1>
+ (DeclStmt 0x48a59c0 <line:2:3, col:24>
+ 0x48a58c0 "int result =
+ (ParenExpr 0x48a59a0 <col:16, col:23> 'int'
+ (BinaryOperator 0x48a5978 <col:17, col:21> 'int' '/'
+ (ImplicitCastExpr 0x48a5960 <col:17> 'int' <LValueToRValue>
+ (DeclRefExpr 0x48a5918 <col:17> 'int' lvalue ParmVar 0x4871d80
'x' 'int'))
+ (IntegerLiteral 0x48a5940 <col:21> 'int' 42)))")
+ (ReturnStmt 0x48a5a18 <line:3:3, col:10>
+ (ImplicitCastExpr 0x48a5a00 <col:10> 'int' <LValueToRValue>
+ (DeclRefExpr 0x48a59d8 <col:10> 'int' lvalue Var 0x48a58c0 'result'
'int'))))
+
+ </Stmt>
+ </Function>
+</TranslationUnit>
+</pre>
+<p>In general, -ast-dump-xml dumps declarations in an XML-style format and
+statements in an S-expression-style format.
+The toplevel declaration in a translation unit is always the
+<a
href="http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html";>translation
unit declaration</a>.
+In this example, our first user written declaration is the
+<a
href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html";>function
declaration</a>
+of 'f'. The body of 'f' is a <a
href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html";>compound
statement</a>,
+whose child nodes are a <a
href="http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html";>declaration
statement</a>
+that declares our result variable, and the
+<a href="http://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html";>return
statement</a>.</p>
+
+<!-- =======================================================================
-->
+<h2 id="context">AST Context</h2>
+<!-- =======================================================================
-->
+
+<p>All information about the AST for a translation unit is bundled up in the
class
+<a
href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html";>ASTContext</a>.
+It allows traversal of the whole translation unit starting from
+<a
href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#abd909fb01ef10cfd0244832a67b1dd64";>getTranslationUnitDecl</a>,
+or to access Clang's <a
href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#a4f95adb9958e22fbe55212ae6482feb4";>table
of identifiers</a>
+for the parsed translation unit.</p>
+
+<!-- =======================================================================
-->
+<h2 id="nodes">AST Nodes</h2>
+<!-- =======================================================================
-->
+
+<p>Clang's AST nodes are modeled on a class hierarchy that does not have a
common
+ancestor. Instead, there are multiple larger hierarchies for basic node types
like
+<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html";>Decl</a> and
+<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html";>Stmt</a>. Many
+important AST nodes derive from <a
href="http://clang.llvm.org/doxygen/classclang_1_1Type.html";>Type</a>,
+<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html";>Decl</a>,
+<a
href="http://clang.llvm.org/doxygen/classclang_1_1DeclContext.html";>DeclContext</a>
or
+<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html";>Stmt</a>,
+with some classes deriving from both Decl and DeclContext.</p>
+<p>There are also a multitude of nodes in the AST that are not part of a
+larger hierarchy, and are only reachable from specific other nodes,
+like <a
href="http://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html";>CXXBaseSpecifier</a>.
+</p>
+
+<p>Thus, to traverse the full AST, one starts from the <a
href="http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html";>TranslationUnitDecl</a>
+and then recursively traverses everything that can be reached from that node
+- this information has to be encoded for each specific node type. This
algorithm
+is encoded in the <a
href="http://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html";>RecursiveASTVisitor</a>.
+See the <a
href="http://clang.llvm.org/docs/RAVFrontendAction.html";>RecursiveASTVisitor
tutorial</a>.</p>
+
+<p>The two most basic nodes in the Clang AST are statements (<a
href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html";>Stmt</a>)
+and declarations (<a
href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html";>Decl</a>).
+Note that expressions (<a
href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html";>Expr</a>)
+are also statements in Clang's AST.</p>
+
+</div>
+</body>
+</html>
+
_______________________________________________
cfe-commits mailing list
[email protected]
http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
