From: Chris Lattner Date: Tue, 31 Jul 2007 05:42:17 +0000 (+0000) Subject: Add a start at a clang internals manual, documenting some X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=86920d33addb25dab21cd8755601383622f889c5;p=clang Add a start at a clang internals manual, documenting some of the more subtle and interesting classes. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@40615 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html new file mode 100644 index 0000000000..0b180ade47 --- /dev/null +++ b/docs/InternalsManual.html @@ -0,0 +1,395 @@ +"clang" CFE Internals Manual + +

"clang" CFE Internals Manual

+ + + + + +

Introduction

+ + +

This document describes some of the more important APIs and internal design +decisions made in the clang C front-end. The purpose of this document is to +both capture some of this high level information and also describe some of the +design decisions behind it. This is meant for people interested in hacking on +clang, not for end-users. The description below is categorized by +libraries, and does not describe any of the clients of the libraries.

+ + +

LLVM System and Support Libraries

+ + +

The LLVM libsystem library provides the basic clang system abstraction layer, +which is used for file system access. The LLVM libsupport library provides many +underlying libraries and data-structures, + including command line option +processing and various containers.

+ + +

The clang 'Basic' Library

+ + +

This library certainly needs a better name. The 'basic' library contains a +number of low-level utilities for tracking and manipulating source buffers, +locations within the source buffers, diagnostics, tokens, target abstraction, +and information about the subset of the language being compiled for.

+ +

Part of this infrastructure is specific to C (such as the TargetInfo class), +other parts could be reused for other non-C-based languages (SourceLocation, +SourceManager, Diagnostics, FileManager). When and if there is future demand +we can figure out if it makes sense to introduce a new library, move the general +classes somewhere else, or introduce some other solution.

+ +

We describe the roles of these classes in order of their dependencies.

+ + +

The SourceLocation and SourceManager classes

+ + +

Strangely enough, the SourceLocation class represents a location within the +source code of the program. Important design points include:

+ +
    +
  1. sizeof(SourceLocation) must be extremely small, as these are embedded into + many AST nodes and are passed around often. Currently it is 32 bits.
    2. +
  2. SourceLocation must be a simple value object that can be efficiently + copied.
    3. +
  3. We should be able to represent a source location for any byte of any input + file. This includes in the middle of tokens, in whitespace, in trigraphs, + etc.
    4. +
  4. A SourceLocation must encode the current #include stack that was active when + the location was processed. For example, if the location corresponds to a + token, it should contain the set of #includes active when the token was + lexed. This allows us to print the #include stack for a diagnostic.
    5. +
  5. SourceLocation must be able to describe macro expansions, capturing both + the ultimate instantiation point and the source of the original character + data.
    6. +
+ +

In practice, the SourceLocation works together with the SourceManager class +to encode two pieces of information about a location: it's physical location +and it's virtual location. For most tokens, these will be the same. However, +for a macro expansion (or tokens that came from a _Pragma directive) these will +describe the location of the characters corresponding to the token and the +location where the token was used (i.e. the macro instantiation point or the +location of the _Pragma itself).

+ +

For efficiency, we only track one level of macro instantions: if a token was +produced by multiple instantiations, we only track the source and ultimate +destination. Though we could track the intermediate instantiation points, this +would require extra bookkeeping and no known client would benefit substantially +from this.

+ +

The clang front-end inherently depends on the location of a token being +tracked correctly. If it is ever incorrect, the front-end may get confused and +die. The reason for this is that the notion of the 'spelling' of a Token in +clang depends on being able to find the original input characters for the token. +This concept maps directly to the "physical" location for the token.

+ + +

The Lexer and Preprocessor Library

+ + +

The Lexer library contains several tightly-connected classes that are involved +with the nasty process of lexing and preprocessing C source code. The main +interface to this library for outside clients is the large Preprocessor class. +It contains the various pieces of state that are required to coherently read +tokens out of a translation unit.

+ +

The core interface to the Preprocessor object (once it is set up) is the +Preprocessor::Lex method, which returns the next Token from +the preprocessor stream. There are two types of token providers that the +preprocessor is capable of reading from: a buffer lexer (provided by the Lexer class) and a buffered token stream (provided by the MacroExpander class). + + + +

The Token class

+ + +

The Token class is used to represent a single lexed token. Tokens are +intended to be used by the lexer/preprocess and parser libraries, but are not +intended to live beyond them (for example, they should not live in the ASTs).

+ +

Tokens most often live on the stack (or some other location that is efficient +to access) as the parser is running, but occasionally do get buffered up. For +example, macro definitions are stored as a series of tokens, and the C++ +front-end will eventually need to buffer tokens up for tentative parsing and +various pieces of look-ahead. As such, the size of a Token matter. On a 32-bit +system, sizeof(Token) is currently 16 bytes.

+ +

Tokens contain the following information:

+ + + +

One interesting (and somewhat unusual) aspect of tokens is that they don't +contain any semantic information about the lexed value. For example, if the +token was a pp-number token, we do not represent the value of the number that +was lexed (this is left for later pieces of code to decide). Additionally, the +lexer library has no notion of typedef names vs variable names: both are +returned as identifiers, and the parser is left to decide whether a specific +identifier is a typedef or a variable (tracking this requires scope information +among other things).

+ + +

The Lexer class

+ + +

The Lexer class provides the mechanics of lexing tokens out of a source +buffer and deciding what they mean. The Lexer is complicated by the fact that +it operates on raw buffers that have not had spelling eliminated (this is a +necessity to get decent performance), but this is countered with careful coding +as well as standard performance techniques (for example, the comment handling +code is vectorized on X86 and PowerPC hosts).

+ +

The lexer has a couple of interesting modal features:

+ + + +

In addition to these modes, the lexer keeps track of a couple of other + features that are local to a lexed buffer, which change as the buffer is + lexed:

+ + + + +

The MacroExpander class

+ + +

The MacroExpander class is a token provider that returns tokens from a list +of tokens that came from somewhere else. It typically used for two things: 1) +returning tokens from a macro definition as it is being expanded 2) returning +tokens from an arbitrary buffer of tokens. The later use is used by _Pragma and +will most likely be used to handle unbounded look-ahead for the C++ parser.

+ + +

The MultipleIncludeOpt class

+ + +

The MultipleIncludeOpt class implements a really simple little state machine +that is used to detect the standard "#ifndef XX / #define XX" +idiom that people typically use to prevent multiple inclusion of headers. If a +buffer uses this idiom and is subsequently #include'd, the preprocessor can +simply check to see whether the guarding condition is defined or not. If so, +the preprocessor can completely ignore the include of the header.

+ + + + +

The Parser Library

+ + + +

The AST Library

+ + + +

The Type class and its subclasses

+ + +

The Type class (and its subclasses) are an important part of the AST. Types +are accessed through the ASTContext class, which implicitly creates and uniques +them as they are needed. Types have a couple of non-obvious features: 1) they +do not capture type qualifiers like const or volatile (See +QualType), and 2) they implicitly capture typedef +information.

+ +

Typedefs in C make semantic analysis a bit more complex than it would +be without them. The issue is that we want to capture typedef information +and represent it in the AST perfectly, but the semantics of operations need to +"see through" typedefs. For example, consider this code:

+ + +void func() {
+ typedef int foo;
+ foo X, *Y;
+ *X; // error
+ **Y; // error
+}
+ + +

The code above is illegal, and thus we expect there to be diagnostics emitted +on the annotated lines. In this example, we expect to get:

+ +
+../t.c:4:1: error: indirection requires pointer operand ('foo' invalid)
+*X; // error
+^~
+../t.c:5:1: error: indirection requires pointer operand ('foo' invalid)
+**Y; // error
+^~~
+
+ +

While this example is somewhat silly, it illustrates the point: we want to +retain typedef information where possible, so that we can emit errors about +"std::string" instead of "std::basic_string<char, std:...". +Doing this requires properly keeping typedef information (for example, the type +of "X" is "foo", not "int"), and requires properly propagating it through the +various operators (for example, the type of *Y is "foo", not "int").

+ + + +

+/// Type - This is the base class of the type hierarchy. A central concept +/// with types is that each type always has a canonical type. A canonical type +/// is the type with any typedef names stripped out of it or the types it +/// references. For example, consider: +/// +/// typedef int foo; +/// typedef foo* bar; +/// 'int *' 'foo *' 'bar' +/// +/// There will be a Type object created for 'int'. Since int is canonical, its +/// canonicaltype pointer points to itself. There is also a Type for 'foo' (a +/// TypeNameType). Its CanonicalType pointer points to the 'int' Type. Next +/// there is a PointerType that represents 'int*', which, like 'int', is +/// canonical. Finally, there is a PointerType type for 'foo*' whose canonical +/// type is 'int*', and there is a TypeNameType for 'bar', whose canonical type +/// is also 'int*'. +/// +/// Non-canonical types are useful for emitting diagnostics, without losing +/// information about typedefs being used. Canonical types are useful for type +/// comparisons (they allow by-pointer equality tests) and useful for reasoning +/// about whether something has a particular form (e.g. is a function type), +/// because they implicitly, recursively, strip all typedefs out of a type. +/// +/// Types, once created, are immutable. +///

+ + + +

The QualType class

+ + +

The QualType class is designed as a trivial value class that is small, +passed by-value and is efficient to query. The idea of QualType is that it +stores the type qualifiers (const, volatile, restrict) separately from the types +themselves: QualType is conceptually a pair of "Type*" and bits for the type +qualifiers.

+ +

By storing the type qualifiers as bits in the conceptual pair, it is +extremely efficient to get the set of qualifiers on a QualType (just return the +field of the pair), add a type qualifier (which is a trivial constant-time +operation that sets a bit), and remove one or more type qualifiers (just return +a QualType with the bitfield set to empty).

+ +

Further, because the bits are stored outside of the type itself, we do not +need to create duplicates of types with different sets of qualifiers (i.e. there +is only a single heap allocated "int" type: "const int" and "volatile const int" +both point to the same heap allocated "int" type). This reduces the heap size +used to represent bits and also means we do not have to consider qualifiers when +uniquing types (Type does not even contain qualifiers).

+ +

In practice, on hosts where it is safe, the 3 type qualifiers are stored in +the low bit of the pointer to the Type object. This means that QualType is +exactly the same size as a pointer, and this works fine on any system where +malloc'd objects are at least 8 byte aligned.