Once the arguments are parsed, the tree of subprocess jobs needed for the desired compilation sequence are - constructed. This involves determing the input files and + constructed. This involves determining the input files and their types, what work is to be done on them (preprocess, compile, assemble, link, etc.), and constructing a list of Action instances for each task. The result is a list of @@ -312,7 +312,7 @@ to run. Conceptually, the driver performs a top down matching to assign Action(s) to Tools. The ToolChain is responsible for selecting the tool to perform a particular - action; once seleected the driver interacts with the tool + action; once selected the driver interacts with the tool to see if it can match additional actions (for example, by having an integrated preprocessor). @@ -397,7 +397,7 @@

The driver constructs a Compilation object for each set of command line arguments. The Driver itself is intended to be - invariant during construct of a Compilation; an IDE should be + invariant during construction of a Compilation; an IDE should be able to construct a single long lived driver instance to use for an entire build, for example.

Unified Parsing & Pipelining

Parsing and pipelining both occur without reference to a Compilation instance. This is by design; the driver expects that both of these phases are platform neutral, with a few very well defined exceptions such as whether the platform uses a driver @@ -425,11 +425,11 @@ stop seeing some arguments the user provided, and see new ones instead).

For example, on Darwin -gfull gets translated into - two separate arguments, -g - and -fno-eliminate-unused-debug-symbols. Trying to - write Tool logic to do something with -gfull will not - work, because at Tools run after the arguments have been +

For example, on Darwin -gfull gets translated into two + separate arguments, -g + and -fno-eliminate-unused-debug-symbols. Trying to write Tool + logic to do something with -gfull will not work, because Tool + argument translation is done after the arguments have been translated.

A long term goal is to remove this tool chain specific diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index a4d5a057ebaa6..f39224f47dc56 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -67,6 +67,7 @@ td {

For efficiency, we only track one level of macro instantiations: 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 diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html index c855a5057a62d..9ac35e1dc2dc2 100644 --- a/docs/LanguageExtensions.html +++ b/docs/LanguageExtensions.html @@ -27,6 +27,7 @@ td {

Clang provides a number of ways to control which code constructs cause it to emit errors and warning messages, and how they are displayed to the console.

Controlling How Clang Displays Diagnostics

When Clang emits a diagnostic, it includes rich information in the output, and gives you fine-grain control over which information is printed. Clang has @@ -394,18 +400,64 @@ it:

Controlling Which Diagnostics Clang Generates

Diagnostic Mappings

-The two major classes are control from the command line and control via pragmas -in your code.

Controlling Diagnostics via Command Line Flags

Controlling Diagnostics via Pragmas

Clang can also control what diagnostics are enabled through the use of +pragmas in the source code. This is useful for turning off specific warnings +in a section of source code. Clang supports GCC's pragma for compatibility +with existing source code, as well as several extensions.

The pragma may control any warning that can be used from the command line. +Warnings may be set to ignored, warning, error, or fatal. The following +example code will tell Clang or GCC to ignore the -Wall warnings:

In addition to all of the functionality of provided by GCC's pragma, Clang +also allows you to push and pop the current warning state. This is particularly +useful when writing a header file that will be compiled by other people, because +you don't know what warning flags they build with.

In the below example +-Wmultichar is ignored for only a single line of code, after which the +diagnostics return to whatever state had previously existed.

The push and pop pragmas will save and restore the full diagnostic state of +the compiler, regardless of how it was set. That means that it is possible to +use push and pop around GCC compatible diagnostics and Clang will push and pop +them appropriately, while GCC will ignore the pushes and pops as unknown +pragmas. It should be noted that while Clang supports the GCC pragma, Clang and +GCC do not support the exact same set of warnings, so even when using GCC +compatible #pragmas there is no guarantee that they will have identical behaviour +on both compilers.

Precompiled Headers

Relocatable PCH Files

It is sometimes necessary to build a precompiled header from headers that +are not yet in their final, installed locations. For example, one might build a +precompiled header within the build tree that is then meant to be installed +alongside the headers. Clang permits the creation of "relocatable" precompiled +headers, which are built with a given path (into the build directory) and can +later be used from an installed location.

To build a relocatable precompiled header, place your headers into a +subdirectory whose structure mimics the installed location. For example, if you +want to build a precompiled header for the header mylib.h that +will be installed into /usr/include, create a subdirectory +build/usr/include and place the header mylib.h into +that subdirectory. If mylib.h depends on other headers, then +they can be stored within build/usr/include in a way that mimics +the installed location.

Building a relocatable precompiled header requires two additional arguments. +First, pass the --relocatable-pch flag to indicate that the +resulting PCH file should be relocatable. Second, pass +-isysroot /path/to/build, which makes all includes for your +library relative to the build directory. For example:

When loading the relocatable PCH file, the various headers used in the PCH +file are found from the system header root. For example, mylib.h +can be found in /usr/include/mylib.h. If the headers are installed +in some other system root, the -isysroot option can be used provide +a different system root from which the headers will be based. For example, +-isysroot /Developer/SDKs/MacOSX10.4u.sdk will look for +mylib.h in +/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h.

Relocatable precompiled headers are intended to be used in a limited number +of cases where the compilation environment is tightly controlled and the +precompiled header cannot be generated after headers have been installed. +Relocatable precompiled headers also have some performance impact, because +the difference in location between the header locations at PCH build time vs. +at the time of PCH use requires one of the PCH optimizations, +stat() caching, to be disabled. However, this change is only +likely to affect PCH files that reference a large number of headers.

C Language Features

+ +

The Index Library

+ +

Table of Contents

Design Philosophy
Classes +
- Entity
- ASTLocation
- DeclReferenceMap
+
Functions +
- ResolveLocationInAST
+
AST Files
index-test tool +
- Usage
- Examples
+

+ +

Design Philosophy

+ +

The Index library is meant to provide the basic infrastructure for + cross-translation-unit analysis and is primarily focused on indexing + related functionality. It provides an API for clients that need to + accurately map the AST nodes of the ASTContext to the locations in the source files. +It also allows them to analyze information across multiple translation units.

+ +

As a "general rule", ASTContexts are considered the primary source of +information that a client wants about a translation unit. There will be no such class as an + "indexing database" that stores, for example, source locations of identifiers separately from ASTContext. +All the information that a client needs from a translation unit will be extracted from the ASTContext.

+ +

Classes

+ +

Entity

+ +

To be able to reason about semantically the same Decls that are contained in multiple ASTContexts, the 'Entity' class was introduced. +An Entity is an ASTContext-independent "token" that can be created from a Decl (and a typename in the future) with +the purpose to "resolve" it into a Decl belonging to another ASTContext. Some examples to make the concept of Entities more clear:

+ +

+t1.c: +

+void foo(void);
+void bar(void);
+

+ +

+t2.c: +

+void foo(void) {
+}
+

+ +

+Translation unit t1.c contains 2 Entities foo and bar, while t2.c contains 1 Entity foo. +Entities are uniqued in such a way that the Entity* pointer for t1.c/foo is the same as the Entity* pointer for t2.c/foo. +An Entity doesn't convey any information about the declaration, it is more like an opaque pointer used only to get the +associated Decl out of an ASTContext so that the actual information for the declaration can be accessed. +Another important aspect of Entities is that they can only be created/associated for declarations that are visible outside the +translation unit. This means that for: +

+t3.c: +

+static void foo(void);
+

+there can be no Entity (if you ask for the Entity* of the static function foo you'll get a null pointer). +This is for 2 reasons: +

To preserve the invariant that the same Entity* pointers refer to the same semantic Decls. + In the above example t1.c/foo and t2.c/foo are the same, while t3.c/foo is different.
The purpose of Entity is to get the same semantic Decl from multiple ASTContexts. For a Decl that is not visible + outside of its own translation unit, you don't need an Entity since it won't appear in another ASTContext.

+ +

ASTLocation

+ +Encapsulates a "point" in the AST tree of the ASTContext. +It represents either a Decl*, or a Stmt* along with its immediate Decl* parent. +An example for its usage is that libIndex will provide the references of foo in the form of ASTLocations, +"pointing" at the expressions that reference foo. + +

DeclReferenceMap

+ +Accepts an ASTContext and creates a mapping from NamedDecls to the ASTLocations that reference them (in the same ASTContext). + +

Functions

+ +

ResolveLocationInAST

+ +A function that accepts an ASTContext and a SourceLocation which it resolves into an ASTLocation. + +

AST Files

+ +The precompiled headers implementation of clang (PCH) is ideal for storing an ASTContext in a compact form that +will be loaded later for AST analysis. An "AST file" refers to a translation unit that was "compiled" into a precompiled header file. + +

index-test tool

+ +

Usage

+ +A command-line tool that exercises the libIndex API, useful for testing its features. +As input it accepts multiple AST files (representing multiple translation units) and a few options: + +

+   -point-at  [file:line:column]
+

+Resolves a [file:line:column] triplet into a ASTLocation from the first AST file. If no other option is specified, it prints the ASTLocation. +It also prints a declaration's associated doxygen comment, if one is available. +

+ +

+   -print-refs
+

+Prints the ASTLocations that reference the declaration that was resolved out of the [file:line:column] triplet +

+ +

+   -print-defs
+

+Prints the ASTLocations that define the resolved declaration +

+ +

+   -print-decls
+

+Prints the ASTLocations that declare the resolved declaration +

+ +

Examples

+ +

+Here's an example of using index-test: +

+ +

+We have 3 files, +

+ +

+foo.h: +

+extern int global_var;
+
+void foo_func(int param1);
+void bar_func(void);
+

+ +t1.c: +

+#include "foo.h"
+
+void foo_func(int param1) {
+  int local_var = global_var;
+  for (int for_var = 100; for_var < 500; ++for_var) {
+    local_var = param1 + for_var;
+  }
+  bar_func();
+}
+

+ +t2.c: +

+#include "foo.h"
+
+int global_var = 10;
+
+void bar_func(void) {
+  global_var += 100;
+  foo_func(global_var);
+}
+

+ +

+You first get AST files out of t1.c and t2.c: + +

+$ clang-cc -emit-pch t1.c -o t1.ast
+$ clang-cc -emit-pch t2.c -o t2.ast
+

+ +

+Find the ASTLocation under this position of t1.c: +

+[...]
+void foo_func(int param1) {
+  int local_var = global_var;
+                      ^
+[...]
+

+ +

+$ index-test t1.ast -point-at t1.c:4:23
+> [Decl: Var local_var | Stmt: DeclRefExpr global_var] <t1.c:4:19, t1.c:4:19>
+

+ +

+Find the declaration: + +

+$ index-test t1.ast -point-at t1.c:4:23 -print-decls
+> [Decl: Var global_var] <foo.h:1:12, foo.h:1:12>
+

+ +

+Find the references: + +

+$ index-test t1.ast t2.ast -point-at t1.c:4:23 -print-refs
+> [Decl: Var local_var | Stmt: DeclRefExpr global_var] <t1.c:4:19, t1.c:4:19>
+> [Decl: Function bar_func | Stmt: DeclRefExpr global_var] <t2.c:6:3, t2.c:6:3>
+> [Decl: Function bar_func | Stmt: DeclRefExpr global_var] <t2.c:7:12, t2.c:7:12>
+

+ +

+Find definitions: + +

+$ index-test t1.ast t2.ast -point-at t1.c:4:23 -print-defs
+> [Decl: Var global_var] <t2.c:3:5, t2.c:3:18>
+

+ +

Unified Parsing & Pipelining

__builtin_shufflevector

__builtin_unreachable

Target-Specific Extensions

Controlling How Clang Displays Diagnostics

Controlling How Clang Displays Diagnostics

Controlling Which Diagnostics Clang Generates

Diagnostic Mappings

Controlling Diagnostics via Command Line Flags

Controlling Diagnostics via Pragmas

Precompiled Headers

Relocatable PCH Files

C Language Features

The Index Library

Design Philosophy

Classes

Entity

ASTLocation

DeclReferenceMap

Functions

ResolveLocationInAST

AST Files

index-test tool

Usage

Examples