The Diagnostics Subsystem¶

The Clang Diagnostics subsystem is an important part of how the compiler communicates with the human. Diagnostics are the warnings and errors produced when the code is incorrect or dubious. In Clang, each diagnostic produced has (at the minimum) a unique ID, an English translation associated with it, a SourceLocation to “put the caret”, and a severity (e.g., WARNING or ERROR). They can also optionally include a number of arguments to the diagnostic (which fill in “%0“‘s in the string) as well as a number of source ranges that related to the diagnostic.

In this section, we’ll be giving examples produced by the Clang command line driver, but diagnostics can be rendered in many different ways depending on how the DiagnosticClient interface is implemented. A representative example of a diagnostic is:

t.c:38:15: error: invalid operands to binary expression ('int *' and '_Complex float')
P = (P-42) + Gamma*4;
    ~~~~~~ ^ ~~~~~~~

In this example, you can see the English translation, the severity (error), you can see the source location (the caret (“^”) and file/line/column info), the source ranges “~~~~”, arguments to the diagnostic (“int*” and “_Complex float”). You’ll have to believe me that there is a unique ID backing the diagnostic :).

Getting all of this to happen has several steps and involves many moving pieces, this section describes them and talks about best practices when adding a new diagnostic.

"binary integer literals are an extension"
"format string contains '\\0' within the string body"
"more '%%' conversions than data arguments"
"invalid operands to binary expression (%0 and %1)"
"overloaded '%0' must be a %select{unary|binary|unary or binary}2 operator"
     " (has %1 parameter%s1)"

if (various things that are bad)
  Diag(Loc, diag::err_typecheck_invalid_operands)
    << lex->getType() << rex->getType()
    << lex->getSourceRange() << rex->getSourceRange();

test.cpp:3:7: warning: use of right-shift operator ('>>') in template argument
                       will require parentheses in C++11
A<100 >> 2> *a;
      ^
  (       )

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. SourceLocation must be a simple value object that can be efficiently copied.
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. 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. SourceLocation must be able to describe macro expansions, capturing both the ultimate instantiation point and the source of the original character data.

In practice, the SourceLocation works together with the SourceManager class to encode two pieces of information about a location: its spelling location and its expansion 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 expansion point or the location of the _Pragma itself).

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 “spelling location” for the token.

SourceRange and CharSourceRange¶

Clang represents most source ranges by [first, last], where “first” and “last” each point to the beginning of their respective tokens. For example consider the SourceRange of the following statement:

x = foo + bar;
^first    ^last

To map from this representation to a character-based representation, the “last” location needs to be adjusted to point to (or past) the end of that token with either Lexer::MeasureTokenLength() or Lexer::getLocForEndOfToken(). For the rare cases where character-level source ranges information is needed we use the CharSourceRange 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 periodically needs to buffer tokens up for tentative parsing and various pieces of look-ahead. As such, the size of a Token matters. On a 32-bit system, sizeof(Token) is currently 16 bytes.

Tokens occur in two forms: annotation tokens and normal tokens. Normal tokens are those returned by the lexer, annotation tokens represent semantic information and are produced by the parser, replacing normal tokens in the token stream. Normal tokens contain the following information:

• A SourceLocation — This indicates the location of the start of the token.
• A length — This stores the length of the token as stored in the SourceBuffer. For tokens that include them, this length includes trigraphs and escaped newlines which are ignored by later phases of the compiler. By pointing into the original source buffer, it is always possible to get the original spelling of a token completely accurately.
• IdentifierInfo — If a token takes the form of an identifier, and if identifier lookup was enabled when the token was lexed (e.g., the lexer was not reading in “raw” mode) this contains a pointer to the unique hash value for the identifier. Because the lookup happens before keyword identification, this field is set even for language keywords like “for”.
• TokenKind — This indicates the kind of token as classified by the lexer. This includes things like tok::starequal (for the “*=” operator), tok::ampamp for the “&&” token, and keyword values (e.g., tok::kw_for) for identifiers that correspond to keywords. Note that some tokens can be spelled multiple ways. For example, C++ supports “operator keywords”, where things like “and” are treated exactly like the “&&” operator. In these cases, the kind value is set to tok::ampamp, which is good for the parser, which doesn’t have to consider both forms. For something that cares about which form is used (e.g., the preprocessor “stringize” operator) the spelling indicates the original form.
• Flags — There are currently four flags tracked by the lexer/preprocessor system on a per-token basis:
  1. StartOfLine — This was the first token that occurred on its input source line.
  2. LeadingSpace — There was a space character either immediately before the token or transitively before the token as it was expanded through a macro. The definition of this flag is very closely defined by the stringizing requirements of the preprocessor.
  3. DisableExpand — This flag is used internally to the preprocessor to represent identifier tokens which have macro expansion disabled. This prevents them from being considered as candidates for macro expansion ever in the future.
  4. NeedsCleaning — This flag is set if the original spelling for the token includes a trigraph or escaped newline. Since this is uncommon, many pieces of code can fast-path on tokens that did not need cleaning.

One interesting (and somewhat unusual) aspect of normal 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 parser can do this translation by replacing tokens returned by the preprocessor with “Annotation Tokens”.

Annotation Tokens¶

Annotation tokens are tokens that are synthesized by the parser and injected into the preprocessor’s token stream (replacing existing tokens) to record semantic information found by the parser. For example, if “foo” is found to be a typedef, the “foo” tok::identifier token is replaced with an tok::annot_typename. This is useful for a couple of reasons: 1) this makes it easy to handle qualified type names (e.g., “foo::bar::baz<42>::t”) in C++ as a single “token” in the parser. 2) if the parser backtracks, the reparse does not need to redo semantic analysis to determine whether a token sequence is a variable, type, template, etc.

Annotation tokens are created by the parser and reinjected into the parser’s token stream (when backtracking is enabled). Because they can only exist in tokens that the preprocessor-proper is done with, it doesn’t need to keep around flags like “start of line” that the preprocessor uses to do its job. Additionally, an annotation token may “cover” a sequence of preprocessor tokens (e.g., “a::b::c” is five preprocessor tokens). As such, the valid fields of an annotation token are different than the fields for a normal token (but they are multiplexed into the normal Token fields):

• SourceLocation “Location” — The SourceLocation for the annotation token indicates the first token replaced by the annotation token. In the example above, it would be the location of the “a” identifier.
• SourceLocation “AnnotationEndLoc” — This holds the location of the last token replaced with the annotation token. In the example above, it would be the location of the “c” identifier.
• void* “AnnotationValue” — This contains an opaque object that the parser gets from Sema. The parser merely preserves the information for Sema to later interpret based on the annotation token kind.
• TokenKind “Kind” — This indicates the kind of Annotation token this is. See below for the different valid kinds.

Annotation tokens currently come in three kinds:

1. tok::annot_typename: This annotation token represents a resolved typename token that is potentially qualified. The AnnotationValue field contains the QualType returned by Sema::getTypeName(), possibly with source location information attached.
2. tok::annot_cxxscope: This annotation token represents a C++ scope specifier, such as “A::B::”. This corresponds to the grammar productions “::” and “:: [opt] nested-name-specifier”. The AnnotationValue pointer is a NestedNameSpecifier * returned by the Sema::ActOnCXXGlobalScopeSpecifier and Sema::ActOnCXXNestedNameSpecifier callbacks.
3. tok::annot_template_id: This annotation token represents a C++ template-id such as “foo<int, 4>”, where “foo” is the name of a template. The AnnotationValue pointer is a pointer to a malloc‘d TemplateIdAnnotation object. Depending on the context, a parsed template-id that names a type might become a typename annotation token (if all we care about is the named type, e.g., because it occurs in a type specifier) or might remain a template-id token (if we want to retain more source location information or produce a new type, e.g., in a declaration of a class template specialization). template-id annotation tokens that refer to a type can be “upgraded” to typename annotation tokens by the parser.

As mentioned above, annotation tokens are not returned by the preprocessor, they are formed on demand by the parser. This means that the parser has to be aware of cases where an annotation could occur and form it where appropriate. This is somewhat similar to how the parser handles Translation Phase 6 of C99: String Concatenation (see C99 5.1.1.2). In the case of string concatenation, the preprocessor just returns distinct tok::string_literal and tok::wide_string_literal tokens and the parser eats a sequence of them wherever the grammar indicates that a string literal can occur.

In order to do this, whenever the parser expects a tok::identifier or tok::coloncolon, it should call the TryAnnotateTypeOrScopeToken or TryAnnotateCXXScopeToken methods to form the annotation token. These methods will maximally form the specified annotation tokens and replace the current token with them, if applicable. If the current tokens is not valid for an annotation token, it will remain an identifier or “::” token.

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:

• The lexer can operate in “raw” mode. This mode has several features that make it possible to quickly lex the file (e.g., it stops identifier lookup, doesn’t specially handle preprocessor tokens, handles EOF differently, etc). This mode is used for lexing within an “#if 0” block, for example.
• The lexer can capture and return comments as tokens. This is required to support the -C preprocessor mode, which passes comments through, and is used by the diagnostic checker to identifier expect-error annotations.
• The lexer can be in ParsingFilename mode, which happens when preprocessing after reading a #include directive. This mode changes the parsing of “<” to return an “angled string” instead of a bunch of tokens for each thing within the filename.
• When parsing a preprocessor directive (after “#”) the ParsingPreprocessorDirective mode is entered. This changes the parser to return EOD at a newline.
• The Lexer uses a LangOptions object to know whether trigraphs are enabled, whether C++ or ObjC keywords are recognized, etc.

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 Lexer uses BufferPtr to keep track of the current character being lexed.
• The Lexer uses IsAtStartOfLine to keep track of whether the next lexed token will start with its “start of line” bit set.
• The Lexer keeps track of the current “#if” directives that are active (which can be nested).
• The Lexer keeps track of an MultipleIncludeOpt object, which is used to detect whether the buffer uses the standard “#ifndef XX / #define XX” idiom to prevent multiple inclusion. If a buffer does, subsequent includes can be ignored if the “XX” macro is defined.

The TokenLexer class¶

The TokenLexer 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 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. Once created, types are immutable (unlike decls).

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;
  typedef foo *bar;
  bar Z;
  *X; // error
  **Y; // error
  **Z; // 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:

test.c:6:1: error: indirection requires pointer operand ('foo' invalid)
  *X; // error
  ^~
test.c:7:1: error: indirection requires pointer operand ('foo' invalid)
  **Y; // error
  ^~~
test.c:8:1: error: indirection requires pointer operand ('foo' invalid)
  **Z; // 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”). In order to retain this information, the type of these expressions is an instance of the TypedefType class, which indicates that the type of these expressions is a typedef for “foo”.

Representing types like this is great for diagnostics, because the user-specified type is always immediately available. There are two problems with this: first, various semantic checks need to make judgements about the actual structure of a type, ignoring typedefs. Second, we need an efficient way to query whether two types are structurally identical to each other, ignoring typedefs. The solution to both of these problems is the idea of canonical types.

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, plus some extended qualifiers required by language extensions) separately from the types themselves. QualType is conceptually a pair of “Type*” and the bits for these 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, the two most common type qualifiers (const and restrict) are stored in the low bits of the pointer to the Type object, together with a flag indicating whether extended qualifiers are present (which must be heap-allocated). This means that QualType is exactly the same size as a pointer.

Declaration names¶

The DeclarationName class represents the name of a declaration in Clang. Declarations in the C family of languages can take several different forms. Most declarations are named by simple identifiers, e.g., “f” and “x” in the function declaration f(int x). In C++, declaration names can also name class constructors (“Class” in struct Class { Class(); }), class destructors (“~Class”), overloaded operator names (“operator+”), and conversion functions (“operator void const *”). In Objective-C, declaration names can refer to the names of Objective-C methods, which involve the method name and the parameters, collectively called a selector, e.g., “setWidth:height:”. Since all of these kinds of entities — variables, functions, Objective-C methods, C++ constructors, destructors, and operators — are represented as subclasses of Clang’s common NamedDecl class, DeclarationName is designed to efficiently represent any kind of name.

Given a DeclarationName N, N.getNameKind() will produce a value that describes what kind of name N stores. There are 10 options (all of the names are inside the DeclarationName class).

Identifier

The name is a simple identifier. Use N.getAsIdentifierInfo() to retrieve the corresponding IdentifierInfo* pointing to the actual identifier.

ObjCZeroArgSelector, ObjCOneArgSelector, ObjCMultiArgSelector

The name is an Objective-C selector, which can be retrieved as a Selector instance via N.getObjCSelector(). The three possible name kinds for Objective-C reflect an optimization within the DeclarationName class: both zero- and one-argument selectors are stored as a masked IdentifierInfo pointer, and therefore require very little space, since zero- and one-argument selectors are far more common than multi-argument selectors (which use a different structure).

CXXConstructorName

The name is a C++ constructor name. Use N.getCXXNameType() to retrieve the type that this constructor is meant to construct. The type is always the canonical type, since all constructors for a given type have the same name.

CXXDestructorName

The name is a C++ destructor name. Use N.getCXXNameType() to retrieve the type whose destructor is being named. This type is always a canonical type.

CXXConversionFunctionName

The name is a C++ conversion function. Conversion functions are named according to the type they convert to, e.g., “operator void const *”. Use N.getCXXNameType() to retrieve the type that this conversion function converts to. This type is always a canonical type.

CXXOperatorName

The name is a C++ overloaded operator name. Overloaded operators are named according to their spelling, e.g., “operator+” or “operator new []”. Use N.getCXXOverloadedOperator() to retrieve the overloaded operator (a value of type OverloadedOperatorKind).

CXXLiteralOperatorName

The name is a C++11 user defined literal operator. User defined Literal operators are named according to the suffix they define, e.g., “_foo” for “operator "" _foo”. Use N.getCXXLiteralIdentifier() to retrieve the corresponding IdentifierInfo* pointing to the identifier.

CXXUsingDirective

The name is a C++ using directive. Using directives are not really NamedDecls, in that they all have the same name, but they are implemented as such in order to store them in DeclContext effectively.

DeclarationNames are cheap to create, copy, and compare. They require only a single pointer’s worth of storage in the common cases (identifiers, zero- and one-argument Objective-C selectors) and use dense, uniqued storage for the other kinds of names. Two DeclarationNames can be compared for equality (==, !=) using a simple bitwise comparison, can be ordered with <, >, <=, and >= (which provide a lexicographical ordering for normal identifiers but an unspecified ordering for other kinds of names), and can be placed into LLVM DenseMaps and DenseSets.

DeclarationName instances can be created in different ways depending on what kind of name the instance will store. Normal identifiers (IdentifierInfo pointers) and Objective-C selectors (Selector) can be implicitly converted to DeclarationNames. Names for C++ constructors, destructors, conversion functions, and overloaded operators can be retrieved from the DeclarationNameTable, an instance of which is available as ASTContext::DeclarationNames. The member functions getCXXConstructorName, getCXXDestructorName, getCXXConversionFunctionName, and getCXXOperatorName, respectively, return DeclarationName instances for the four kinds of C++ special function names.

Declaration contexts¶

Every declaration in a program exists within some declaration context, such as a translation unit, namespace, class, or function. Declaration contexts in Clang are represented by the DeclContext class, from which the various declaration-context AST nodes (TranslationUnitDecl, NamespaceDecl, RecordDecl, FunctionDecl, etc.) will derive. The DeclContext class provides several facilities common to each declaration context:

Source-centric vs. Semantics-centric View of Declarations

DeclContext provides two views of the declarations stored within a declaration context. The source-centric view accurately represents the program source code as written, including multiple declarations of entities where present (see the section Redeclarations and Overloads), while the semantics-centric view represents the program semantics. The two views are kept synchronized by semantic analysis while the ASTs are being constructed.

Storage of declarations within that context

Every declaration context can contain some number of declarations. For example, a C++ class (represented by RecordDecl) contains various member functions, fields, nested types, and so on. All of these declarations will be stored within the DeclContext, and one can iterate over the declarations via [DeclContext::decls_begin(), DeclContext::decls_end()). This mechanism provides the source-centric view of declarations in the context.

Lookup of declarations within that context

The DeclContext structure provides efficient name lookup for names within that declaration context. For example, if N is a namespace we can look for the name N::f using DeclContext::lookup. The lookup itself is based on a lazily-constructed array (for declaration contexts with a small number of declarations) or hash table (for declaration contexts with more declarations). The lookup operation provides the semantics-centric view of the declarations in the context.

Ownership of declarations

The DeclContext owns all of the declarations that were declared within its declaration context, and is responsible for the management of their memory as well as their (de-)serialization.

All declarations are stored within a declaration context, and one can query information about the context in which each declaration lives. One can retrieve the DeclContext that contains a particular Decl using Decl::getDeclContext. However, see the section Lexical and Semantic Contexts for more information about how to interpret this context information.

void f(int x, int y, int z = 1);

inline void f(int x, int y, int z) { /* ...  */ }

void g();
void g(int);

class X {
public:
  void f(int x);
};

void X::f(int x = 17) { /* ...  */ }

enum Color {
  Red,
  Green,
  Blue
};

Color c = Red;

extern "C" {
  void f(int);
  void g(int);
}
// f and g are visible here

// Snippet #1:
namespace N {
  void f();
}
namespace N {
  void f(int);
}

// Snippet #2:
namespace N {
  void f();
  void f(int);
}

The CFG class¶

The CFG class is designed to represent a source-level control-flow graph for a single statement (Stmt*). Typically instances of CFG are constructed for function bodies (usually an instance of CompoundStmt), but can also be instantiated to represent the control-flow of any class that subclasses Stmt, which includes simple expressions. Control-flow graphs are especially useful for performing flow- or path-sensitive program analyses on a given function.

int foo(int x) {
  x = x + 1;
  if (x > 2)
    x++;
  else {
    x += 2;
    x *= 2;
  }

  return x;
}

Stmt *FooBody = ...
std::unique_ptr<CFG> FooCFG = CFG::buildCFG(FooBody);

[ B5 (ENTRY) ]
   Predecessors (0):
   Successors (1): B4

[ B4 ]
   1: x = x + 1
   2: (x > 2)
   T: if [B4.2]
   Predecessors (1): B5
   Successors (2): B3 B2

[ B3 ]
   1: x++
   Predecessors (1): B4
   Successors (1): B1

[ B2 ]
   1: x += 2
   2: x *= 2
   Predecessors (1): B4
   Successors (1): B1

[ B1 ]
   1: return x;
   Predecessors (2): B2 B3
   Successors (1): B0

[ B0 (EXIT) ]
   Predecessors (1): B1
   Successors (0):

Constant Folding in the Clang AST¶

There are several places where constants and constant folding matter a lot to the Clang front-end. First, in general, we prefer the AST to retain the source code as close to how the user wrote it as possible. This means that if they wrote “5+4”, we want to keep the addition and two constants in the AST, we don’t want to fold to “9”. This means that constant folding in various ways turns into a tree walk that needs to handle the various cases.

However, there are places in both C and C++ that require constants to be folded. For example, the C standard defines what an “integer constant expression” (i-c-e) is with very precise and specific requirements. The language then requires i-c-e’s in a lot of places (for example, the size of a bitfield, the value for a case statement, etc). For these, we have to be able to constant fold the constants, to do semantic checks (e.g., verify bitfield size is non-negative and that case statements aren’t duplicated). We aim for Clang to be very pedantic about this, diagnosing cases when the code does not use an i-c-e where one is required, but accepting the code unless running with -pedantic-errors.

Things get a little bit more tricky when it comes to compatibility with real-world source code. Specifically, GCC has historically accepted a huge superset of expressions as i-c-e’s, and a lot of real world code depends on this unfortunate accident of history (including, e.g., the glibc system headers). GCC accepts anything its “fold” optimizer is capable of reducing to an integer constant, which means that the definition of what it accepts changes as its optimizer does. One example is that GCC accepts things like “case X-X:” even when X is a variable, because it can fold this to 0.

Another issue are how constants interact with the extensions we support, such as __builtin_constant_p, __builtin_inf, __extension__ and many others. C99 obviously does not specify the semantics of any of these extensions, and the definition of i-c-e does not include them. However, these extensions are often used in real code, and we have to have a way to reason about them.

Finally, this is not just a problem for semantic analysis. The code generator and other clients have to be able to fold constants (e.g., to initialize global variables) and has to handle a superset of what C99 allows. Further, these clients can benefit from extended information. For example, we know that “foo() || 1” always evaluates to true, but we can’t replace the expression with true because it has side effects.

How to add an attribute¶

Attributes are a form of metadata that can be attached to a program construct, allowing the programmer to pass semantic information along to the compiler for various uses. For example, attributes may be used to alter the code generation for a program construct, or to provide extra semantic information for static analysis. This document explains how to add a custom attribute to Clang. Documentation on existing attributes can be found here.

clang-tblgen -gen-attr-docs -I /path/to/clang/include /path/to/clang/include/clang/Basic/Attr.td -o /path/to/clang/docs/AttributeReference.rst

How to add an expression or statement¶

Expressions and statements are one of the most fundamental constructs within a compiler, because they interact with many different parts of the AST, semantic analysis, and IR generation. Therefore, adding a new expression or statement kind into Clang requires some care. The following list details the various places in Clang where an expression or statement needs to be introduced, along with patterns to follow to ensure that the new expression or statement works well across all of the C languages. We focus on expressions, but statements are similar.

1. Introduce parsing actions into the parser. Recursive-descent parsing is mostly self-explanatory, but there are a few things that are worth keeping in mind:
   • Keep as much source location information as possible! You’ll want it later to produce great diagnostics and support Clang’s various features that map between source code and the AST.
   • Write tests for all of the “bad” parsing cases, to make sure your recovery is good. If you have matched delimiters (e.g., parentheses, square brackets, etc.), use Parser::BalancedDelimiterTracker to give nice diagnostics when things go wrong.
2. Introduce semantic analysis actions into Sema. Semantic analysis should always involve two functions: an ActOnXXX function that will be called directly from the parser, and a BuildXXX function that performs the actual semantic analysis and will (eventually!) build the AST node. It’s fairly common for the ActOnCXX function to do very little (often just some minor translation from the parser’s representation to Sema‘s representation of the same thing), but the separation is still important: C++ template instantiation, for example, should always call the BuildXXX variant. Several notes on semantic analysis before we get into construction of the AST:
   • Your expression probably involves some types and some subexpressions. Make sure to fully check that those types, and the types of those subexpressions, meet your expectations. Add implicit conversions where necessary to make sure that all of the types line up exactly the way you want them. Write extensive tests to check that you’re getting good diagnostics for mistakes and that you can use various forms of subexpressions with your expression.
   • When type-checking a type or subexpression, make sure to first check whether the type is “dependent” (Type::isDependentType()) or whether a subexpression is type-dependent (Expr::isTypeDependent()). If any of these return true, then you’re inside a template and you can’t do much type-checking now. That’s normal, and your AST node (when you get there) will have to deal with this case. At this point, you can write tests that use your expression within templates, but don’t try to instantiate the templates.
   • For each subexpression, be sure to call Sema::CheckPlaceholderExpr() to deal with “weird” expressions that don’t behave well as subexpressions. Then, determine whether you need to perform lvalue-to-rvalue conversions (Sema::DefaultLvalueConversions) or the usual unary conversions (Sema::UsualUnaryConversions), for places where the subexpression is producing a value you intend to use.
   • Your BuildXXX function will probably just return ExprError() at this point, since you don’t have an AST. That’s perfectly fine, and shouldn’t impact your testing.
3. Introduce an AST node for your new expression. This starts with declaring the node in include/Basic/StmtNodes.td and creating a new class for your expression in the appropriate include/AST/Expr*.h header. It’s best to look at the class for a similar expression to get ideas, and there are some specific things to watch for:
   • If you need to allocate memory, use the ASTContext allocator to allocate memory. Never use raw malloc or new, and never hold any resources in an AST node, because the destructor of an AST node is never called.
   • Make sure that getSourceRange() covers the exact source range of your expression. This is needed for diagnostics and for IDE support.
   • Make sure that children() visits all of the subexpressions. This is important for a number of features (e.g., IDE support, C++ variadic templates). If you have sub-types, you’ll also need to visit those sub-types in RecursiveASTVisitor.
   • Add printing support (StmtPrinter.cpp) for your expression.
   • Add profiling support (StmtProfile.cpp) for your AST node, noting the distinguishing (non-source location) characteristics of an instance of your expression. Omitting this step will lead to hard-to-diagnose failures regarding matching of template declarations.
   • Add serialization support (ASTReaderStmt.cpp, ASTWriterStmt.cpp) for your AST node.
4. Teach semantic analysis to build your AST node. At this point, you can wire up your Sema::BuildXXX function to actually create your AST. A few things to check at this point:
   • If your expression can construct a new C++ class or return a new Objective-C object, be sure to update and then call Sema::MaybeBindToTemporary for your just-created AST node to be sure that the object gets properly destructed. An easy way to test this is to return a C++ class with a private destructor: semantic analysis should flag an error here with the attempt to call the destructor.
   • Inspect the generated AST by printing it using clang -cc1 -ast-print, to make sure you’re capturing all of the important information about how the AST was written.
   • Inspect the generated AST under clang -cc1 -ast-dump to verify that all of the types in the generated AST line up the way you want them. Remember that clients of the AST should never have to “think” to understand what’s going on. For example, all implicit conversions should show up explicitly in the AST.
   • Write tests that use your expression as a subexpression of other, well-known expressions. Can you call a function using your expression as an argument? Can you use the ternary operator?
5. Teach code generation to create IR to your AST node. This step is the first (and only) that requires knowledge of LLVM IR. There are several things to keep in mind:
   • Code generation is separated into scalar/aggregate/complex and lvalue/rvalue paths, depending on what kind of result your expression produces. On occasion, this requires some careful factoring of code to avoid duplication.
   • CodeGenFunction contains functions ConvertType and ConvertTypeForMem that convert Clang’s types (clang::Type* or clang::QualType) to LLVM types. Use the former for values, and the latter for memory locations: test with the C++ “bool” type to check this. If you find that you are having to use LLVM bitcasts to make the subexpressions of your expression have the type that your expression expects, STOP! Go fix semantic analysis and the AST so that you don’t need these bitcasts.
   • The CodeGenFunction class has a number of helper functions to make certain operations easy, such as generating code to produce an lvalue or an rvalue, or to initialize a memory location with a given value. Prefer to use these functions rather than directly writing loads and stores, because these functions take care of some of the tricky details for you (e.g., for exceptions).
   • If your expression requires some special behavior in the event of an exception, look at the push*Cleanup functions in CodeGenFunction to introduce a cleanup. You shouldn’t have to deal with exception-handling directly.
   • Testing is extremely important in IR generation. Use clang -cc1 -emit-llvm and FileCheck to verify that you’re generating the right IR.
6. Teach template instantiation how to cope with your AST node, which requires some fairly simple code:
   • Make sure that your expression’s constructor properly computes the flags for type dependence (i.e., the type your expression produces can change from one instantiation to the next), value dependence (i.e., the constant value your expression produces can change from one instantiation to the next), instantiation dependence (i.e., a template parameter occurs anywhere in your expression), and whether your expression contains a parameter pack (for variadic templates). Often, computing these flags just means combining the results from the various types and subexpressions.
   • Add TransformXXX and RebuildXXX functions to the TreeTransform class template in Sema. TransformXXX should (recursively) transform all of the subexpressions and types within your expression, using getDerived().TransformYYY. If all of the subexpressions and types transform without error, it will then call the RebuildXXX function, which will in turn call getSema().BuildXXX to perform semantic analysis and build your expression.
   • To test template instantiation, take those tests you wrote to make sure that you were type checking with type-dependent expressions and dependent types (from step #2) and instantiate those templates with various types, some of which type-check and some that don’t, and test the error messages in each case.
7. There are some “extras” that make other features work better. It’s worth handling these extras to give your expression complete integration into Clang:
   • Add code completion support for your expression in SemaCodeComplete.cpp.
   • If your expression has types in it, or has any “interesting” features other than subexpressions, extend libclang’s CursorVisitor to provide proper visitation for your expression, enabling various IDE features such as syntax highlighting, cross-referencing, and so on. The c-index-test helper program can be used to test these features.