[cfe-commits] r160708 - /cfe/trunk/docs/IntroductionToTheClangAST.html
Manuel Klimek
klimek at google.com
Wed Jul 25 00:28:11 PDT 2012
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>
+
More information about the cfe-commits
mailing list