From 93ca0217a2aa3047c10518e991ab8578e90829e7 Mon Sep 17 00:00:00 2001 From: Sean Silva Date: Thu, 13 Dec 2012 01:10:46 +0000 Subject: docs: More reST conversion. Sorry for the large commit, but it is much faster to convert in batches. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@170067 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/IntroductionToTheClangAST.rst | 135 +++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 docs/IntroductionToTheClangAST.rst (limited to 'docs/IntroductionToTheClangAST.rst') diff --git a/docs/IntroductionToTheClangAST.rst b/docs/IntroductionToTheClangAST.rst new file mode 100644 index 0000000000..a23fb42b71 --- /dev/null +++ b/docs/IntroductionToTheClangAST.rst @@ -0,0 +1,135 @@ +============================= +Introduction to the Clang AST +============================= + +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. + +Introduction +============ + +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. + +Documentation for all Clang AST nodes is available via the generated +`Doxygen `_. 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). + +Examining the AST +================= + +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. + +Let's look at a simple example AST: + +:: + + # 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 ... + + + + + + + + + + + + + (CompoundStmt 0x48a5a38 + (DeclStmt 0x48a59c0 + 0x48a58c0 "int result = + (ParenExpr 0x48a59a0 'int' + (BinaryOperator 0x48a5978 'int' '/' + (ImplicitCastExpr 0x48a5960 'int' + (DeclRefExpr 0x48a5918 'int' lvalue ParmVar 0x4871d80 'x' 'int')) + (IntegerLiteral 0x48a5940 'int' 42)))") + (ReturnStmt 0x48a5a18 + (ImplicitCastExpr 0x48a5a00 'int' + (DeclRefExpr 0x48a59d8 'int' lvalue Var 0x48a58c0 'result' 'int')))) + + + + + +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 `translation unit +declaration `_. +In this example, our first user written declaration is the `function +declaration `_ +of 'f'. The body of 'f' is a `compound +statement `_, +whose child nodes are a `declaration +statement `_ +that declares our result variable, and the `return +statement `_. + +AST Context +=========== + +All information about the AST for a translation unit is bundled up in +the class +`ASTContext `_. +It allows traversal of the whole translation unit starting from +`getTranslationUnitDecl `_, +or to access Clang's `table of +identifiers `_ +for the parsed translation unit. + +AST Nodes +========= + +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 +`Decl `_ and +`Stmt `_. Many +important AST nodes derive from +`Type `_, +`Decl `_, +`DeclContext `_ +or `Stmt `_, with +some classes deriving from both Decl and DeclContext. + +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 +`CXXBaseSpecifier `_. + +Thus, to traverse the full AST, one starts from the +`TranslationUnitDecl `_ +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 +`RecursiveASTVisitor `_. +See the `RecursiveASTVisitor +tutorial `_. + +The two most basic nodes in the Clang AST are statements +(`Stmt `_) and +declarations +(`Decl `_). Note +that expressions +(`Expr `_) are +also statements in Clang's AST. -- cgit v1.2.1